Au moment où un chat s'ouvre, les plugins devraient déjà savoir : Hermes ajoute le hook on_session_open

Neuf heures du matin. Vous ouvrez Hermes Desktop et vous reprenez le travail de la veille, dans le même dépôt. Votre plugin de mémoire tient déjà la conclusion à laquelle vous étiez parvenu — quel endpoint était mal configuré depuis le départ, quel fichier de test s’est révélé une perte de temps. Mais il ignore que vous êtes de retour. Il n’apprend l’existence d’une conversation qu’au moment où vous tapez le premier message et où celui-ci traverse le modèle.
L’autre cas est pire. Vous ouvrez la fenêtre, vous faites défiler deux écrans du chat de la veille, vous la refermez. Le plugin n’entend rien du tout, parce que le nouveau message qu’il attendait ne vient jamais.
Les auteurs de plugins réagissent en général de la même façon : ils font du polling. Réveil toutes les quelques secondes, listing du répertoire des sessions, lecture des dates de modification. Ça marche, mais c’est laid — le polling ne peut pas dire si vous êtes vraiment revenu, et il ne distingue pas une session neuve d’une session rouverte.
on_session_open existe pour combler ce trou.
Un tour complet plus tôt que on_session_start
Hermes avait déjà un hook au nom très proche : on_session_start. Presque le même nom, un point de déclenchement très différent — celui-là se déclenche à l’intérieur du premier tour de l’agent, c’est-à-dire au moment où un vrai message utilisateur va être traité.
Du coup, quand vous rouvrez un chat sauvegardé, on_session_start ne se déclenche jamais. Même si vous continuez à parler, ce qui se déclenche c’est « ce tour a commencé », pas « cette session a été ouverte ».
on_session_open couvre la seconde chose : l’instant où une session est créée ou ouverte, avant que le modèle ne voie quoi que ce soit. La doc est explicite sur l’intention — il sert à se préparer à une conversation, par exemple un plugin de mémoire qui précharge les vingt dernières notes, ou une barre de statut qui marque immédiatement la session comme ouverte.
Ce que le point de déclenchement signifie vraiment
Les détails comptent, parce qu’ils décident si votre callback tourne deux fois pour un seul clic.
C’est l’autorité de session du gateway qui l’émet : quand une connexion client s’attache à une session locale à laquelle elle n’était pas déjà attachée, il se déclenche une fois. Vous obtenez donc des frontières nettes :
- Une ouverture, un déclenchement. Un client qui relit un snapshot d’une session qu’il détient déjà ne le déclenche pas. Une reconnexion après une coupure de socket ne le déclenche pas. Inutile de maintenir un ensemble de déduplication.
- Deux clients qui ouvrent la même session déclenchent deux fois. Ce sont deux ouvertures réelles, et les plugins doivent savoir que deux personnes sont arrivées.
- Création et reprise comptent toutes les deux, distinguées par
reason:createtant que la session n’a aucun message,resumedès qu’elle contient une conversation. - Il s’exécute dans le profil propriétaire de la session. Sur un gateway qui sert plusieurs profils, les plugins de chaque profil ne voient que leurs propres sessions — pas de fuite entre profils.
- Les chats de messagerie ne le déclenchent pas. Telegram, Discord et compagnie n’ont pas d’action « ouvrir » ; leurs sessions commencent avec le premier message, et
on_session_startreste le bon hook dans ce cas.
Le payload est petit : session_id, platform (cli, tui, desktop, acp, etc.) et reason (create ou resume). Aucun contenu de message, aucune saisie utilisateur — volontairement, pour que la question de la vie privée ne se pose jamais ici.
Écrire un callback : réchauffer le cache d’abord
Dans un plugin, l’enregistrement ressemble à celui de n’importe quel autre hook :
# ~/.hermes/plugins/session-warm/__init__.py
_cache = {}
def warm(session_id, platform, reason, **kwargs):
# Cheap preparation only: read files, query a local index, write state
_cache[session_id] = load_recent_notes(limit=20)
def register(ctx):
ctx.register_hook("on_session_open", warm)
Ne supprimez pas **kwargs. Des champs s’ajoutent au fil du temps, et une signature figée en dur finit tôt ou tard par rencontrer un nouveau champ et se transformer en TypeError.
Le seul point à retenir dans cet extrait : le callback tourne dans le gateway, pas dans le client. Quand le CLI classique, le TUI ou Desktop ouvre une session, c’est le processus gateway qui charge et exécute le code du plugin ; le processus client ne touche jamais aux plugins. C’est une frontière de sécurité, et c’est aussi pourquoi les lignes de log affichent le pid du gateway.
Vous n’êtes pas obligé d’écrire du Python. Les hooks shell gèrent aussi cet événement :
# ~/.hermes/config.yaml
hooks:
on_session_open:
- command: "~/.hermes/agent-hooks/session-open.sh"
timeout: 10
Le script reçoit sur stdin un payload JSON contenant ces trois champs. Pour ajouter une ligne d’audit ou pinguer un service local, une douzaine de lignes de bash suffisent.
Ensuite, testez. hermes hooks test couvre cet événement : il déclenche chaque hook correspondant sur un payload synthétique et affiche la réponse analysée.
hermes hooks test on_session_open
Un budget de cinq secondes, et la règle qui en découle
Il y a un compromis de conception à connaître : l’ouverture de la session n’attend jamais les plugins, mais le tour suivant de la session, si.
Concrètement, le callback est distribué sur son propre thread, donc le moment où vous cliquez sur ouvrir reste immédiat. Mais avant que le tour ne démarre vraiment, il attend le callback — jusqu’à 5 secondes, ou plus si plugins.hook_callback_timeout (30 secondes par défaut) est réglé plus haut. Au-delà, le tour continue et le callback poursuit son exécution en arrière-plan.
Mettre plugins.hook_callback_timeout à 0 signifie que les callbacks ne sont jamais abandonnés. Même dans ce cas, le tour n’attend que 5 secondes : ce réglage veut dire « ne tue pas les callbacks lents », pas « laisse-les prendre la conversation en otage ».
D’où la règle : gardez le callback rapide. Lire des fichiers locaux, lancer une requête SQLite, remplir un cache en mémoire — tout cela tient dans le budget. Appeler un LLM, taper une API distante, scanner un dépôt — vous ajoutez maintenant de la latence à la première phrase de l’utilisateur.
Deux détails de plus :
- Si le callback d’une session tourne encore et que la même session est rouverte, la nouvelle ouverture le rejoint et ne se déclenche qu’une fois à la fin du premier, avec les détails de l’ouverture la plus récente. Un callback bloqué ne peut pas empiler dix threads.
- Si les plugins chargés du profil ne contiennent aucun abonné, il ne se passe rien — pas même un thread.
Les échecs sont fail-open : l’exception est journalisée puis ignorée, les callbacks suivants continuent, et la session s’ouvre quoi qu’il arrive.
Ce qui a sa place ici, et ce qui n’en a pas
Les bons cas d’usage sont ceux du type « la conversation n’a pas commencé, mais je veux être prêt » :
- Préchauffage mémoire ou base de connaissances : aller chercher les notes et les conclusions liées à ce dépôt pour que le premier message en profite déjà.
- État et signaux : barres de statut, dashboards externes, journaux d’audit. « Qui a ouvert quelle session, et quand » est une ligne que les opérateurs veulent vraiment.
- Identifiants ou répertoires de travail par session : les plugins qui doivent savoir à quel projet appartient une session avant de choisir une configuration.
- Nettoyage des restes du tour précédent : sur une ouverture
create, jeter les brouillons périmés est plus fiable que deviner.
Les mauvais cas sont tout aussi nets :
- « La session a démarré » sur les plateformes de messagerie — utilisez
on_session_start. - Tout ce qui a besoin d’une saisie utilisateur ; à ce stade, il n’y en a aucune.
- Tout aller-retour réseau mesuré en centaines de millisecondes.
Une note de périmètre : les sessions lancées avec --safe-mode ou --ignore-user-config ne le déclenchent jamais, parce que les plugins ne sont pas chargés dans ces modes.
Puis-je l’utiliser dès aujourd’hui ?
Le hook a été fusionné sur main le 8 novembre 2026 (PR #151120). J’ai vérifié ce que contenait la v0.23.0 : cette release est sortie le 6 novembre, donc ce hook n’est pas dans la v0.23.0. C’est du code main uniquement, et il arrivera dans une release stable avec la prochaine version.
Mise à jour (10/11/2026) : ces changements sont sortis dans la v0.23.1 (9 novembre) : un
hermes updatesuffit. Le « pas dans la v0.23.0 » ci-dessus reste exact ; la v0.23.1 comble l’écart.
Si vous tournez sur main, vous pouvez l’utiliser tout de suite. Si vous êtes sur une release stable, écrivez le plugin et validez la logique avec hermes hooks test, pour qu’il fonctionne le jour de la montée de version.
En attendant, les hooks plus anciens couvrent une partie du terrain : on_session_start pour le premier tour, plus les hooks de frontière de session que nous avons détaillés dans les notifications de plugin pour les sessions compactées et supprimées. La même machinerie de distribution peut d’ailleurs bloquer tout un tour avant l’appel au modèle — voir le hook de politique pre_llm_call — et la référence des commandes liste chaque nom d’événement et chaque champ de configuration pris en charge.
La version courte
on_session_open comble un trou précis : « la session est ouverte, mais aucun message n’est encore arrivé ». Les plugins étaient aveugles exactement à ce moment-là. Ils reçoivent désormais session_id, platform et reason, plus cinq secondes pour se préparer. La seule règle à retenir est celle qu’implique le budget : faites des choses peu coûteuses pendant ces cinq secondes, et laissez les coûteuses au premier tour.