Read a Hermes session without opening it: session.transcript


You are building a small side panel for your editor: the last ten conversations on the left, the picked one on the right. The data comes from a Hermes gateway. Simple, until you hit the wall — the gateway has exactly one way to read a conversation back, and it is called session.resume. The name is honest: resume means open. Call it and the gateway builds an agent for that session, subscribes the caller to its events, and turns a stored conversation into a running one. You wanted three lines of preview text and you got a live process to babysit.

The batch merged on November 6 closes that gap. The gateway now has a real read-only method, session.transcript, plus a picker: true option on session.list. Both are authorized as reads, build no agent, subscribe nobody, and cost nothing once the reply is sent. This post covers what you can now read, how the cursor works, and the one branch that looks like an error but is not.

The old corner: showing one line meant opening the whole thing

This was not a mistake so much as an inheritance. session.resume means “continue this conversation”, so it has to make the session live: claim it, rebuild the runtime, attach the caller to the event stream. For a read-only list that trade is wrong in both directions — and it is actively dangerous, because opening your side panel could take the session the user is currently typing into.

So plenty of third-party clients did the obvious thing and read state.db directly. That works right up until the store’s shape moves, at which point the client breaks. The point of this change is to move clients off the database file and in front of a versioned interface.

One method, three jobs: listing, paging, children

What the client wants Before Now
List conversations with folder, last activity and last reply session.list returned id, title, first prompt, counts session.list with picker: true adds preview, last_reply, cwd, git_branch, workspace, last_active_at, pinned
Show only this folder’s conversations no filter a workspace parameter, matched by hermes -c’s own rule
Page the transcript without attaching only session.resume, which attaches session.transcript
Poll for new messages impossible without attaching pass the previous page’s next_cursor back
Know where Hermes summarised the conversation handoff rows were dropped from what clients saw every handoff is a row_kind: "compaction" row at its position
Read a delegated child’s conversation not possible the subagent_id parameter
Know which session a child row belongs to subagent.list rows did not say rows carry child_session_id

The workspace rule is worth one sentence on its own: a conversation belongs to the folder its first row was in — the recorded git repo root if there is one, otherwise its cwd. That is why a session opened in packages/webapp/ inside a monorepo is found by filtering on the repo root, not on the package.

How it looks: one request, one cursor

The request is deliberately dull. Default order is oldest-first, one hundred rows a 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
}

rows are display rows, not raw store rows: each logical message appears once, up to 64 tool results of the call at the page edge ride along, and compaction handoffs sit where they happened. The order you receive is the order the user saw.

The cursor is opaque. Do not parse it and do not carry it across sessions — it is bound to the session, the child and the order it was issued for.

The cursor is also the poll

This is the nicest part of the design and the easiest to misuse.

With order: "oldest" (the default) next_cursor is never null. When you read until a page comes back empty, keep the cursor and pass it again: you get only the rows written since. A thing that looked like pagination is also an incremental feed — no websocket, no callbacks, just a poll.

order: "latest" is the other direction: newest first, paging backwards, and next_cursor becomes null at the end. That is the shape you want for a reader that opens scrolled to the bottom.

reset: true is not an error. Replace what you hold.

If there is one branch to get right, it is this one.

The cursor vouches for more than a position. It records the state of the rows it covered. While every change in between was an append — a new message, a new tool result — the next page continues after the cursor and says reset: false. But anything else does not extend the walk: an in-place compaction, a rotation into a new segment, a rewind, a rewrite or a deletion of a covered row. Then the reply is reset: true and it starts again from the first page. There is exactly one correct reaction: throw away your cached copy and use this page.

For a reader that is a feature — you never end up with the first half of a conversation from one version and the second half from another. For the person writing the client it is a normal branch of the protocol, not a failure path. A reply that carries no cursor at all is reset: true too.

Reading a delegated child

Pass subagent_id and the method reads a child of that session instead. The reply gains four fields: subagent_id, available, running, child_session_id.

The gates are deliberate:

  • The session must be live on this gateway, or you get not_found.
  • A running child must be in the parent’s live roster, nested children included.
  • A finished child is located through the _subagent_id stamped on its row at spawn, and only if its parent chain reaches this conversation through delegate-child or compression-continuation hops. A branch of the conversation does not lend you its children.
  • A foreign or unknown child answers available: false, rows: [], next_cursor: null, reset: true. No error, no leak.

subagent.list rows now carry child_session_id, so “which session does this child belong to” is no longer guesswork.

Limits you should design against

  • limit is 1–500, default 100, compaction rows included.
  • A page carries at most 2 MiB of JSON, cut between tool groups, so a call and its result are never split across pages.
  • A single row bigger than that keeps only its role, kind, time, ids and the head of its text, and says truncated: true.
  • Images render as [image] unless you ask for inline_images: true.

Authorization is the same read check session.resume uses (profile, owner or operator), and the read runs on the gateway’s concurrent read lane — a prompt you send will not queue behind someone else’s page fetches.

Can you use it today

Not from a stable release. These commits landed on main on November 6–7 (PR #150102, which folded in #140477’s subagent reads) and they are not in the v0.23.0 tag, which was cut on November 5. Check capability rather than version: a gateway that serves this advertises session-transcript-v1 in runtime.describe.capabilities, and session-list-picker-v1 for the list options. If it does not, fall back.

Update (2026-11-10): these changes shipped in v0.23.1 (November 9) — hermes update is enough. The “not in v0.23.0” statements above are still accurate; v0.23.1 closes the gap.

If you only need a copy of a conversation off the machine today, exporting a session is the path. And if the compaction rows puzzle you, the reason a single conversation is several segments — and why the transcript has to show them in place — is in session boundaries. The attached-side semantics this method replaces are covered in the Chat C resume write-up.

The short version

session.transcript separates two things that were welded together for a long time: reading a conversation and opening it. A client can now look without walking in, page and poll with the same cursor, and get told plainly when the conversation underneath changed shape. If your client still opens state.db itself, this is the reason to stop.