Repository navigation
[FEATURE]: Add a transcript revision token for incremental consumers #43766
Description
[FEATURE]: Add a transcript revision token for incremental consumers
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request
Incremental consumers of session transcripts (e.g. external integrations that sync or archive conversations) currently cannot detect when a transcript they already read has changed. I hit this while developing an OpenCode session-sync plugin (related work in nowledge-co/community#522).
What exists today: the legacy and v2 session message endpoints both expose pagination cursors. Those cursors identify a message position and ordering, but there is no value that identifies the revision of the whole transcript. A client can keep paging from a cursor, but it cannot detect that OpenCode later changed or removed an earlier message or part. Compaction may also prune old tool-result content after a client has already read it.
Ask: expose a monotonic transcript revision (e.g. an ETag, revision number, or checkpoint token) with message-list responses, or via a dedicated endpoint. Incremental consumers could compare the revision and rescan only when previously read content changes.
I checked the legacy and v2 session message endpoints and could not find an existing revision/ETag/checkpoint API. I also found #19567 (durable event export / replay surface), which is related but distinct: that request is about an append-only event stream, while this one is a lightweight revision signal on the existing message-list surface.
Activity
pascalandr commentedon Aug 28, 2026
CodeNomad's bounded V2 transcript integration has a concrete correctness case for this revision token.
On the current beta message surface:
packages/server/src/handlers/message.tsencodes a pagination cursor as{ id, order, direction };Session.messagesresolves that message ID to its currentsession_message.seqwhen the cursor is consumed;session.compaction.startedappends a newcompactionprojection at a new sequence, while compaction deltas/end update that same row;session.revert.committedcan delete the row referenced by an older cursor. A missing cursor anchor currently returns[], which is indistinguishable from a valid transcript edge.This means a bounded client can hold a structurally valid cursor while its previously observed end, total, or search rank is no longer authoritative. Compaction exposes this systematically because it advances the transcript end without a new user prompt.
We opened #44660 for optional
seekpluscursor.range.{start,end,total}. That positional metadata needs to compose with the revision requested here:dataand range metadata;This keeps responsibilities separate: #44660 supplies position/random access; #43766 supplies snapshot authority.
pascalandr commentedon Aug 28, 2026
Related API request: #45801 asks for server-side transcript search results to carry the revision defined here. Without that composition, a bounded client cannot tell whether paginated matches still belong to the transcript version it searched.
pascalandr commentedon Aug 28, 2026
Additional V1-to-V2 migration context from CodeNomad:
V1 did not expose a transcript revision either, but
session.messagesreturned the complete projected transcript in one response. CodeNomad therefore did not combine independently fetched message pages, and could reconcile that one response against events received during hydration with a local store counter.V2 introduces a different consistency problem because the transcript is now consumed through multiple opaque cursor requests. CodeNomad keeps a bounded 200-message resident window and may traverse further pages for search. If compaction, revert, append, or an in-place content update occurs between requests, the client cannot determine whether the collected pages describe one server snapshot. CodeNomad's local revision counter only records events that this client observed; it cannot establish the revision used by the server for each page or recover authority after reconnect.
This is therefore not a missing V1 field requested for parity. It is snapshot authority required by V2 pagination. A revision on each message-list/search response would let bounded clients discard mixed reads and restart from one known transcript state.
feat(opencode): migrate CodeNomad to native V2 (#647)