Eine Hermes-Session lesen, ohne sie zu öffnen: session.transcript

Du baust ein kleines Seitenpanel für deinen Editor: links die letzten zehn Unterhaltungen, rechts die ausgewählte. Die Daten kommen von einem Hermes-Gateway. Einfach — bis du gegen die Wand läufst: Das Gateway hat genau einen Weg, eine Unterhaltung wieder zu lesen, und der heißt session.resume. Der Name ist ehrlich: resume heißt öffnen. Rufst du es auf, baut das Gateway einen Agenten für diese Session, abonniert den Aufrufer auf ihre Events und macht aus einer gespeicherten Unterhaltung eine laufende. Du wolltest drei Zeilen Vorschautext und bekommst einen laufenden Prozess, um den du dich kümmern musst.
Der Batch, der am 6. November gemergt wurde, schließt diese Lücke. Das Gateway hat jetzt eine echte Read-only-Methode, session.transcript, plus eine Option picker: true auf session.list. Beide sind als Reads autorisiert, bauen keinen Agenten, abonnieren niemanden und kosten nichts, sobald die Antwort raus ist. Dieser Beitrag zeigt, was du jetzt lesen kannst, wie der Cursor funktioniert und den einen Branch, der wie ein Fehler aussieht, aber keiner ist.
Die alte Sackgasse: eine Zeile anzeigen hieß, alles öffnen zu müssen
Das war weniger ein Fehler als ein Erbe. session.resume heißt „diese Unterhaltung fortsetzen“, also muss es die Session live machen: sie beanspruchen, die Runtime neu aufbauen, den Aufrufer an den Event-Stream hängen. Für eine reine Lese-Liste ist dieser Tausch in beide Richtungen falsch — und er ist aktiv gefährlich, denn dein Seitenpanel zu öffnen könnte die Session übernehmen, in die der Nutzer gerade tippt.
Also taten viele Drittanbieter-Clients das Naheliegende und lasen state.db direkt. Das funktioniert genau so lange, bis sich die Form des Stores ändert — dann bricht der Client. Der Punkt dieser Änderung ist, Clients von der Datenbankdatei weg und vor eine versionierte Schnittstelle zu holen.
Eine Methode, drei Aufgaben: listen, blättern, Kinder
| Was der Client will | Vorher | Jetzt |
|---|---|---|
| Unterhaltungen mit Ordner, letzter Aktivität und letzter Antwort auflisten | session.list gab id, Titel, ersten Prompt, Zähler zurück |
session.list mit picker: true ergänzt preview, last_reply, cwd, git_branch, workspace, last_active_at, pinned |
| Nur die Unterhaltungen dieses Ordners zeigen | kein Filter | ein workspace-Parameter, gematcht nach derselben Regel wie hermes -c |
| Durch das Transkript blättern, ohne anzuhängen | nur session.resume, das anhängt |
session.transcript |
| Auf neue Nachrichten pollen | ohne Anhängen unmöglich | den next_cursor der vorigen Seite zurückgeben |
| Wissen, wo Hermes die Unterhaltung zusammengefasst hat | Handoff-Zeilen wurden Clients vorenthalten | jeder Handoff ist eine Zeile mit row_kind: "compaction" an seiner Position |
| Die Unterhaltung eines delegierten Kindes lesen | nicht möglich | der Parameter subagent_id |
| Wissen, zu welcher Session eine Kind-Zeile gehört | subagent.list-Zeilen sagten es nicht |
Zeilen tragen child_session_id |
Die workspace-Regel verdient einen eigenen Satz: Eine Unterhaltung gehört zu dem Ordner, in dem ihre erste Zeile lag — die aufgezeichnete git-Repo-Wurzel, falls es eine gibt, sonst ihr cwd. Deshalb findet man eine Session, die in einem Monorepo unter packages/webapp/ geöffnet wurde, über einen Filter auf die Repo-Wurzel, nicht auf das Package.
Wie es aussieht: eine Anfrage, ein Cursor
Die Anfrage ist bewusst langweilig. Standardreihenfolge ist älteste zuerst, hundert Zeilen pro Seite:
{"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
}
rows sind Display-Zeilen, keine rohen Store-Zeilen: Jede logische Nachricht erscheint einmal, bis zu 64 Tool-Results des Aufrufs am Seitenrand fahren mit, und Compaction-Handoffs sitzen dort, wo sie passiert sind. Die Reihenfolge, die du bekommst, ist die, die der Nutzer gesehen hat.
Der Cursor ist opak. Parse ihn nicht und trage ihn nicht über Sessions hinweg — er ist an die Session, das Kind und die Reihenfolge gebunden, für die er ausgegeben wurde.
Der Cursor ist auch der Poll
Das ist der schönste Teil des Designs und der am leichtesten falsch benutzte.
Mit order: "oldest" (dem Default) ist next_cursor nie null. Wenn du liest, bis eine Seite leer zurückkommt, behalte den Cursor und gib ihn erneut mit: Du bekommst nur die Zeilen, die seither geschrieben wurden. Ein Ding, das wie Pagination aussah, ist auch ein inkrementeller Feed — kein Websocket, keine Callbacks, nur ein Poll.
order: "latest" ist die andere Richtung: neueste zuerst, rückwärts blättern, und next_cursor wird am Ende null. Das ist die Form, die du für einen Reader willst, der nach unten gescrollt öffnet.
reset: true ist kein Fehler. Ersetze, was du hältst.
Wenn es einen Branch gibt, den du richtig hinbekommen musst, dann diesen.
Der Cursor bürgt für mehr als eine Position. Er hält den Zustand der Zeilen fest, die er abdeckte. Solange jede Änderung dazwischen ein Append war — eine neue Nachricht, ein neues Tool-Result —, setzt die nächste Seite hinter dem Cursor fort und sagt reset: false. Alles andere verlängert den Lauf nicht: eine In-place-Compaction, eine Rotation in ein neues Segment, ein Rewind, ein Rewrite oder das Löschen einer abgedeckten Zeile. Dann lautet die Antwort reset: true, und sie beginnt wieder auf der ersten Seite. Es gibt genau eine richtige Reaktion: Wirf deine gecachte Kopie weg und nimm diese Seite.
Für einen Reader ist das ein Feature — du endest nie mit der ersten Hälfte einer Unterhaltung aus der einen Version und der zweiten Hälfte aus einer anderen. Für den, der den Client schreibt, ist es ein normaler Branch des Protokolls, kein Fehlerpfad. Eine Antwort ganz ohne Cursor ist ebenfalls reset: true.
Ein delegiertes Kind lesen
Gib subagent_id mit, und die Methode liest stattdessen ein Kind dieser Session. Die Antwort bekommt vier Felder: subagent_id, available, running, child_session_id.
Die Gates sind Absicht:
- Die Session muss auf diesem Gateway live sein, sonst bekommst du
not_found. - Ein laufendes Kind muss im Live-Roster des Parents stehen, verschachtelte Kinder eingeschlossen.
- Ein abgeschlossenes Kind wird über die
_subagent_idgefunden, die ihm beim Spawn auf seine Zeile gestempelt wurde, und nur, wenn seine Parent-Kette diese Unterhaltung über delegate-child- oder compression-continuation-Hops erreicht. Ein Branch der Unterhaltung verleiht dir nicht seine Kinder. - Ein fremdes oder unbekanntes Kind antwortet mit
available: false,rows: [],next_cursor: null,reset: true. Kein Fehler, kein Leak.
subagent.list-Zeilen tragen jetzt child_session_id, damit ist „zu welcher Session gehört dieses Kind“ kein Raten mehr.
Grenzen, gegen die du entwerfen solltest
limitliegt bei 1–500, Default 100, Compaction-Zeilen mitgezählt.- Eine Seite trägt höchstens 2 MiB JSON, geschnitten zwischen Tool-Gruppen, sodass ein Aufruf und sein Ergebnis nie über Seiten verteilt werden.
- Eine einzelne Zeile, die größer ist, behält nur Rolle, Art, Zeit, IDs und den Kopf ihres Textes und sagt
truncated: true. - Bilder erscheinen als
[image], außer du fragstinline_images: truean.
Die Autorisierung ist derselbe Read-Check, den session.resume nutzt (Profile, Owner oder Operator), und der Read läuft auf der parallelen Read-Lane des Gateways — ein Prompt, den du sendest, stellt sich nicht hinter die Seiten-Fetches anderer.
Kannst du es heute nutzen
Nicht aus einem Stable-Release. Diese Commits landeten am 6.–7. November auf main (PR #150102, der die Subagent-Reads aus #140477 aufgenommen hat), und sie sind nicht im v0.23.0-Tag, das am 5. November geschnitten wurde. Prüfe die Capability statt die Version: Ein Gateway, das das hier ausliefert, wirbt in runtime.describe.capabilities mit session-transcript-v1 und mit session-list-picker-v1 für die Listen-Optionen. Wenn nicht, fall zurück.
Update (10.11.2026): Diese Änderungen sind mit v0.23.1 (9. November) erschienen – ein
hermes updategenügt. Die Aussage „nicht in v0.23.0“ oben stimmt weiterhin; v0.23.1 schließt die Lücke.
Wenn du heute nur eine Kopie einer Unterhaltung von der Maschine brauchst, ist eine Session exportieren der Weg. Und wenn dich die compaction-Zeilen irritieren: Warum eine einzelne Unterhaltung aus mehreren Segmenten besteht — und warum das Transkript sie an Ort und Stelle zeigen muss —, steht in den Session-Grenzen. Die Semantik der Anhänge-Seite, die diese Methode ersetzt, behandelt der Chat-C-Resume-Text.
Die Kurzfassung
session.transcript trennt zwei Dinge, die lange zusammengeschweißt waren: eine Unterhaltung lesen und sie öffnen. Ein Client kann jetzt hineinschauen, ohne einzutreten, mit demselben Cursor blättern und pollen, und erfährt klar, wenn die Unterhaltung darunter ihre Form geändert hat. Wenn dein Client state.db immer noch selbst öffnet, ist das der Grund, damit aufzuhören.