Lire une session Hermes sans l'ouvrir : session.transcript

Vous construisez un petit panneau latéral pour votre éditeur : les dix dernières conversations à gauche, celle qui est sélectionnée à droite. Les données viennent d’une gateway Hermes. Simple, jusqu’au mur : la gateway n’a qu’une seule manière de relire une conversation, et elle s’appelle session.resume. Le nom est honnête — resume veut dire ouvrir. Appelez-la et la gateway construit un agent pour cette session, abonne l’appelant à ses événements et transforme une conversation stockée en conversation en cours d’exécution. Vous vouliez trois lignes d’aperçu et vous récupérez un processus vivant à surveiller.
Le lot fusionné le 6 novembre comble ce trou. La gateway dispose maintenant d’une vraie méthode en lecture seule, session.transcript, plus une option picker: true sur session.list. Les deux sont autorisées comme des lectures, ne construisent aucun agent, n’abonnent personne et ne coûtent rien une fois la réponse envoyée. Cet article couvre ce que vous pouvez lire désormais, le fonctionnement du cursor, et la seule branche qui ressemble à une erreur sans en être une.
L’ancien angle mort : afficher une ligne obligeait à tout ouvrir
Ce n’était pas tant une erreur qu’un héritage. session.resume signifie « continuer cette conversation », elle doit donc rendre la session vivante : la réclamer, reconstruire le runtime, attacher l’appelant au flux d’événements. Pour une liste en lecture seule, ce compromis est mauvais dans les deux sens — et il est franchement dangereux, parce qu’ouvrir votre panneau latéral pourrait prendre la session dans laquelle l’utilisateur est en train d’écrire.
Alors beaucoup de clients tiers ont fait la chose évidente : lire state.db directement. Ça marche jusqu’au jour où la forme du stock bouge, et à ce moment-là le client casse. L’intérêt de ce changement est justement de sortir les clients du fichier de base de données pour les mettre devant une interface versionnée.
Une méthode, trois métiers : lister, paginer, les enfants
| Ce que le client veut | Avant | Maintenant |
|---|---|---|
| Lister les conversations avec dossier, dernière activité et dernière réponse | session.list renvoyait id, titre, premier prompt, compteurs |
session.list avec picker: true ajoute preview, last_reply, cwd, git_branch, workspace, last_active_at, pinned |
| N’afficher que les conversations de ce dossier | aucun filtre | un paramètre workspace, filtré selon la règle de hermes -c |
| Paginer le transcript sans s’attacher | seulement session.resume, qui attache |
session.transcript |
| Interroger les nouveaux messages | impossible sans s’attacher | renvoyer le next_cursor de la page précédente |
| Savoir où Hermes a résumé la conversation | les lignes de handoff étaient retirées de ce que voyaient les clients | chaque handoff est une ligne row_kind: "compaction" à sa position |
| Lire la conversation d’un enfant délégué | impossible | le paramètre subagent_id |
| Savoir à quelle session appartient une ligne enfant | les lignes de subagent.list ne le disaient pas |
les lignes portent child_session_id |
La règle workspace mérite une phrase à elle seule : une conversation appartient au dossier où se trouvait sa première ligne — la racine git enregistrée s’il y en a une, sinon son cwd. C’est pourquoi une session ouverte dans packages/webapp/ à l’intérieur d’un monorepo se retrouve en filtrant sur la racine du dépôt, et non sur le package.
À quoi ça ressemble : une requête, un cursor
La requête est volontairement banale. L’ordre par défaut va du plus ancien au plus récent, cent lignes par page :
{"method": "session.transcript", "params": {"session_id": "ses_8f21", "limit": 50}}
{
"session_id": "ses_8f21",
"rows": [
{"row_kind": "message", "role": "user", "text": "the build fails on CI only"},
{"row_kind": "message", "role": "assistant", "text": "Which stage?"},
{"row_kind": "compaction", "role": "system", "text": "Summary of 34 earlier messages...", "compacted_messages": 34}
],
"next_cursor": "c2VzXzhmMjE6MToxMjM0",
"reset": false
}
Les rows sont des lignes d’affichage, pas des lignes brutes du stock : chaque message logique apparaît une fois, jusqu’à 64 résultats d’outils de l’appel en bord de page suivent, et les handoffs de compaction restent là où ils ont eu lieu. L’ordre que vous recevez est l’ordre que l’utilisateur a vu.
Le cursor est opaque. Ne l’analysez pas et ne le transportez pas d’une session à l’autre — il est lié à la session, à l’enfant et à l’ordre pour lequel il a été émis.
Le cursor est aussi le poll
C’est la plus belle partie du design et la plus facile à mal utiliser.
Avec order: "oldest" (le défaut), next_cursor n’est jamais null. Quand vous lisez jusqu’à ce qu’une page revienne vide, gardez le cursor et repassez-le : vous ne recevez que les lignes écrites depuis. Ce qui ressemblait à de la pagination est aussi un flux incrémental — pas de websocket, pas de callbacks, juste un poll.
order: "latest" est l’autre direction : du plus récent au plus ancien, pagination vers l’arrière, et next_cursor devient null à la fin. C’est la forme qu’il faut pour un lecteur qui s’ouvre déjà déroulé en bas.
reset: true n’est pas une erreur. Remplacez ce que vous détenez.
S’il y a une branche à ne pas rater, c’est celle-là.
Le cursor garantit plus qu’une position. Il enregistre l’état des lignes qu’il a couvertes. Tant que chaque changement intermédiaire est un ajout — un nouveau message, un nouveau résultat d’outil — la page suivante continue après le cursor et renvoie reset: false. Mais tout le reste ne prolonge pas la marche : une compaction sur place, une rotation vers un nouveau segment, un rewind, une réécriture ou une suppression d’une ligne couverte. Alors la réponse est reset: true et elle repart de la première page. Il n’y a qu’une réaction correcte : jeter votre copie en cache et utiliser cette page.
Pour un lecteur, c’est une fonctionnalité — vous ne vous retrouvez jamais avec la première moitié d’une conversation d’une version et la seconde d’une autre. Pour la personne qui écrit le client, c’est une branche normale du protocole, pas un chemin d’échec. Une réponse qui ne porte aucun cursor est aussi reset: true.
Lire un enfant délégué
Passez subagent_id et la méthode lit un enfant de cette session à la place. La réponse gagne quatre champs : subagent_id, available, running, child_session_id.
Les barrières sont volontaires :
- La session doit être vivante sur cette gateway, sinon vous obtenez
not_found. - Un enfant en cours doit figurer dans le roster vivant du parent, enfants imbriqués compris.
- Un enfant terminé se retrouve via le
_subagent_idestampillé sur sa ligne au moment du spawn, et seulement si sa chaîne de parents rejoint cette conversation par des sauts delegate-child ou compression-continuation. Une branche de la conversation ne vous prête pas ses enfants. - Un enfant étranger ou inconnu répond
available: false,rows: [],next_cursor: null,reset: true. Pas d’erreur, pas de fuite.
Les lignes de subagent.list portent désormais child_session_id, donc « à quelle session appartient cet enfant » n’est plus une devinette.
Les limites contre lesquelles concevoir
limitva de 1 à 500, défaut 100, lignes de compaction comprises.- Une page porte au maximum 2 MiB de JSON, coupée entre groupes d’outils, pour qu’un appel et son résultat ne soient jamais séparés entre deux pages.
- Une ligne plus grosse que ça ne garde que son rôle, son type, son heure, ses ids et le début de son texte, et renvoie
truncated: true. - Les images s’affichent comme
[image]sauf si vous demandezinline_images: true.
L’autorisation est la même vérification de lecture que celle de session.resume (profile, propriétaire ou opérateur), et la lecture passe par la voie de lecture concurrente de la gateway — un prompt que vous envoyez ne fera pas la queue derrière les requêtes de page de quelqu’un d’autre.
Peut-on l’utiliser aujourd’hui
Pas depuis une release stable. Ces commits sont arrivés sur main les 6 et 7 novembre (PR #150102, qui a intégré les lectures d’enfants de #140477) et ils ne sont pas dans le tag v0.23.0, coupé le 5 novembre. Vérifiez la capacité plutôt que la version : une gateway qui sert cette méthode annonce session-transcript-v1 dans runtime.describe.capabilities, et session-list-picker-v1 pour les options de liste. Sinon, repliez-vous.
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 avez seulement besoin d’une copie d’une conversation hors de la machine aujourd’hui, exporter une session est la bonne voie. Et si les lignes compaction vous intriguent, la raison pour laquelle une seule conversation compte plusieurs segments — et pourquoi le transcript doit les montrer à leur place — est dans les frontières de session. La sémantique côté attaché que cette méthode remplace est traitée dans le compte rendu sur la reprise Chat C.
L’essentiel
session.transcript sépare deux choses restées soudées longtemps : lire une conversation et l’ouvrir. Un client peut maintenant regarder sans entrer, paginer et interroger avec le même cursor, et se voir dire clairement quand la conversation sous-jacente a changé de forme. Si votre client ouvre encore state.db lui-même, voilà la raison d’arrêter.