Cuando se abre un chat, los plugins ya deberían saberlo: Hermes añade el hook on_session_open

Nueve de la mañana. Abres Hermes Desktop y retomas el trabajo de ayer en el mismo repo. Tu plugin de memoria ya tiene la conclusión a la que llegaste: qué endpoint estaba mal configurado desde el principio, qué archivo de tests resultó ser una pérdida de tiempo. Pero no tiene ni idea de que has vuelto. Solo se entera de que existe una conversación cuando escribes el primer mensaje y este pasa por el modelo.
El otro caso es peor. Abres la ventana, recorres dos pantallas del chat de ayer y la cierras. El plugin no oye nada, porque el mensaje nuevo que esperaba no llega nunca.
Quien escribe plugins suele reaccionar igual: hacer polling. Despertarse cada pocos segundos, listar el directorio de sesiones, mirar las fechas de modificación. Funciona, pero es feo: el polling no distingue si de verdad has vuelto, ni si la session es nueva o reabierta.
on_session_open existe para cerrar esa brecha.
Un turno entero antes que on_session_start
Hermes ya tenía un hook de nombre parecido: on_session_start. Casi el mismo nombre, un punto de disparo muy distinto: aquel salta dentro del primer turno del agente, es decir, cuando está a punto de procesarse un mensaje real del usuario.
Así que, cuando reabres un chat guardado, on_session_start no se dispara. Aunque sigas hablando, lo que salta es «este turno ha empezado», no «esta session se ha abierto».
on_session_open es lo segundo: el instante en que una session se crea o se abre, antes de que el modelo vea nada. La documentación es explícita sobre la intención: sirve para prepararse para una conversación, por ejemplo un plugin de memoria que precarga las últimas veinte notas, o una barra de estado que marca la session como abierta de inmediato.
Qué significa realmente el punto de disparo
Los detalles importan, porque son los que deciden si tu callback se ejecuta dos veces por un solo clic.
Lo dispara la autoridad de sesiones del gateway: cuando una conexión de cliente se engancha a una session local a la que no estaba enganchada, salta una vez. Eso te da bordes limpios:
- Una apertura, un disparo. Un cliente que relee una instantánea de una session que ya tiene no lo dispara. Reconectar después de perder el socket tampoco. No necesitas mantener un conjunto de deduplicación.
- Dos clientes que abren la misma session lo disparan dos veces. Son dos aperturas reales, y los plugins deberían saber que han llegado dos personas.
- Crear y reanudar cuentan las dos, y se distinguen por
reason:createmientras la session todavía no tiene mensajes,resumecuando ya hay conversación. - Se ejecuta en el profile dueño de la session. En un gateway que sirve varios profiles, los plugins de cada profile solo ven sus propias sesiones: nada de contaminación cruzada.
- Los chats de mensajería no lo disparan. Telegram, Discord y compañía no tienen una acción de «abrir»; sus sesiones empiezan con el primer mensaje, y ahí
on_session_startsigue siendo el hook correcto.
El payload es pequeño: session_id, platform (cli, tui, desktop, acp, etcétera) y reason (create o resume). Ni contenido de mensajes ni entrada del usuario: a propósito, para que aquí nunca tengas que pensar en privacidad.
Escribir un callback: calienta la caché primero
Dentro de un plugin, el registro es igual que el de cualquier otro hook:
# ~/.hermes/plugins/session-warm/__init__.py
_cache = {}
def warm(session_id, platform, reason, **kwargs):
# Solo preparación barata: leer archivos, consultar un índice local, escribir estado
_cache[session_id] = load_recent_notes(limit=20)
def register(ctx):
ctx.register_hook("on_session_open", warm)
No quites **kwargs. Con el tiempo se van añadiendo campos, y una firma hardcodeada acaba topándose con uno nuevo y convirtiéndose en un TypeError.
Lo único que merece la pena destacar de ese fragmento: el callback se ejecuta en el gateway, no en el cliente. Cuando el CLI clásico, la TUI o Desktop abren una session, el proceso del gateway carga y ejecuta el código del plugin; el proceso cliente nunca toca plugins. Es una frontera de seguridad, y también la razón por la que las líneas de log muestran el pid del gateway.
Tampoco hace falta escribir Python. Los shell hooks también soportan este evento:
# ~/.hermes/config.yaml
hooks:
on_session_open:
- command: "~/.hermes/agent-hooks/session-open.sh"
timeout: 10
El script recibe un payload JSON por stdin con esos tres campos. Para añadir una línea de auditoría o hacer ping a un servicio local, una docena de líneas de bash sobran.
Después, pruébalo. hermes hooks test cubre este evento: dispara todos los hooks que coinciden contra un payload sintético e imprime la respuesta ya parseada.
hermes hooks test on_session_open
Un presupuesto de cinco segundos, y la regla que se deriva
Hay un compromiso de diseño que conviene conocer: abrir la session nunca espera a los plugins, pero el siguiente turno de esa session sí.
En concreto, el callback se despacha en su propio hilo, así que el instante en que haces clic en abrir es instantáneo. Pero antes de que el turno arranque de verdad, se espera al callback: hasta 5 segundos, o más si plugins.hook_callback_timeout (30 segundos por defecto) está configurado más alto. Pasado ese punto, el turno sigue adelante y el callback continúa en segundo plano.
Poner plugins.hook_callback_timeout a 0 significa que los callbacks no se abandonan nunca. Aun así, el turno solo espera 5 segundos: ese ajuste quiere decir «no mates los callbacks lentos», no «déjales retener la conversación como rehenes».
De ahí sale la regla: mantén el callback rápido. Leer archivos locales, una consulta a SQLite, rellenar una caché en memoria: todo dentro de presupuesto. Llamar a un LLM, pegarle a una API remota, escanear un repositorio: eso ya es añadir latencia a la primera frase del usuario.
Dos detalles más:
- Si el callback de una session sigue en marcha y esa misma session se vuelve a abrir, la nueva apertura se le une y se dispara una sola vez al terminar el primero, con los datos de la apertura más reciente. Un callback atascado no puede apilar diez hilos.
- Si los plugins cargados del profile no tienen ningún suscriptor, no pasa nada: ni siquiera se crea un hilo.
Los fallos son fail-open: una excepción se registra y se salta, los callbacks posteriores continúan, y la session se abre igual.
Qué encaja aquí y qué no
Los buenos encajes son los casos de «la conversación no ha empezado, pero quiero estar listo»:
- Calentar memoria o base de conocimiento: traer las notas y conclusiones ligadas a este repo para que el primer mensaje ya se beneficie.
- Estado y señales: barras de estado, dashboards externos, logs de auditoría. «Quién abrió qué session y cuándo» es una línea que los operadores quieren de verdad.
- Credenciales o directorios de trabajo por session: plugins que necesitan saber a qué proyecto pertenece una session antes de elegir una configuración.
- Limpiar los restos de la ronda anterior: en una apertura
create, tirar los borradores viejos es más fiable que adivinar.
Los malos encajes están igual de claros:
- «La session ha empezado» en plataformas de mensajería: usa
on_session_start. - Cualquier cosa que necesite entrada del usuario; en este punto no hay ninguna.
- Cualquier ida y vuelta de red medida en cientos de milisegundos.
Una nota de alcance: las sesiones iniciadas con --safe-mode o --ignore-user-config nunca lo disparan, porque en esos modos no se cargan plugins.
¿Puedo usarlo hoy?
El hook entró en main el 8 de noviembre de 2026 (PR #151120). He comprobado qué trajo la v0.23.0: esa release salió el 6 de noviembre, así que este hook no está en la v0.23.0. Es código solo de main y llegará a una release estable con la próxima versión.
Actualización (10/11/2026): estos cambios ya salieron en la v0.23.1 (9 de noviembre): basta con
hermes update. Lo de «no está en v0.23.0» sigue siendo cierto; la v0.23.1 cierra la brecha.
Si corres main, puedes usarlo ya. Si estás en una release estable, escribe el plugin y valida la lógica con hermes hooks test, para que funcione el día que actualices.
Hasta entonces, los hooks anteriores siguen cubriendo parte del terreno: on_session_start para el primer turno, más los hooks de frontera de session que vimos en las notificaciones de plugin para sesiones compactadas y eliminadas. La misma maquinaria de despacho también puede bloquear un turno entero antes de la llamada al modelo: mira el hook de política pre_llm_call, y la referencia de comandos lista todos los nombres de evento y campos de configuración soportados.
La versión corta
on_session_open rellena un hueco muy concreto: «la session está abierta, pero todavía no ha llegado ningún mensaje». Los plugins antes eran ciegos justo en ese momento. Ahora reciben session_id, platform y reason, más cinco segundos para prepararse. La única regla que hay que recordar es la que implica el presupuesto: haz cosas baratas en esos cinco segundos y deja las caras para el primer turno.