Repository navigation
Description
Feature hasn't been suggested before.
- I verified that existing pagination issues do not provide total-position metadata or random access.
Describe the enhancement you want to request
V2 message pagination exposes opaque previous and next cursors, but clients cannot size a bounded virtual transcript or jump to an unvisited position without walking every preceding cursor.
Proposed backward-compatible extension:
- optional
seekquery containing a zero-based message rank, mutually exclusive withcursor - optional
cursor.rangeresponse metadata containingstart,end, andtotal - a seek response still returns normal opaque
previousandnextcursors, so sequential navigation remains unchanged
This lets clients jump once and then continue with cursors. Existing requests and cursor tokens keep their current behavior. The implementation can use the existing (session_id, seq) index and does not require storing UI-specific height data.
Would this API shape be acceptable? I can prepare the focused protocol, server, generated-client, and pagination-test changes after design approval.
Transcript mutation consistency
This positional metadata also needs an authoritative transcript revision, as requested in #43766 (or an equivalent checkpoint contract).
The current cursor encodes only the anchor message ID, order, and direction. The server resolves that message to its current seq when the cursor is consumed. This is insufficient for a bounded client when the transcript changes between requests:
- compaction appends a new
compactionmessage at the end, then updates that projection while it streams, so a previously observed end and total become stale; - revert can delete the message referenced by a cursor, and the current message query returns an empty page when that anchor no longer exists, which is indistinguishable from reaching a real edge;
- a search result or saved rank can move relative to the latest end while its message ID remains valid.
The cursor.range values and returned data should therefore identify the transcript revision from which they were calculated. A client must be able to detect that a saved range, seek target, or cursor belongs to an older revision instead of silently treating stale metadata as authoritative.
This does not require combining the two APIs: #44660 remains responsible for total/rank/seek, while #43766 remains responsible for the monotonic transcript revision. They need to compose in the message-list response.
Additional acceptance criteria:
data,cursor.range, and the transcript revision describe one consistent read;- the revision changes for appended messages, in-place message content updates, and removals;
- clients can distinguish a stale/deleted cursor anchor from a genuine empty edge;
- an unchanged transcript keeps existing opaque cursors and sequential navigation behavior.
Activity
github-actions commentedon Aug 24, 2026
This issue might be a duplicate of existing issues. Please check:
/session/[id]/message— directly discusses cursor-based pagination API design for the same endpointpascalandr commentedon Aug 24, 2026
Thanks, I checked these issues.
#6548 and #35895 cover bounded sequential cursor pagination, which is already available in the V2 API. Neither exposes the total message count nor a way to seek directly to an arbitrary unvisited rank.
#43766 would help detect transcript mutations, but a revision token does not provide total-position or random-access navigation.
The question here is specifically whether V2 already has a supported total/rank/seek primitive that is not visible in the public message-list contract.
[-]question(v2): random access in paginated session messages[/-][+][FEATURE]: Add random seek metadata to V2 message pagination[/+]pascalandr commentedon Aug 25, 2026
I prepared the focused implementation on
pascalandr:message-seekwhile waiting for design approval before opening a PR.It keeps existing cursor tokens unchanged, adds optional
seekplus optional end-exclusivecursor.range, regenerates both clients, and covers direct/out-of-range seek and cursor continuation through the live HTTP API test. No schema migration is required.pascalandr commentedon Aug 28, 2026
Related API request: #45801 asks for each transcript-search result to expose a directly navigable target. That target should compose with the rank/seek contract proposed here so clients can open a match without walking every preceding cursor.
feat(opencode): migrate CodeNomad to native V2 (#647)
github-actions commentedon Oct 27, 2026
To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.