Skip to content

[FEATURE]: Add random seek metadata to V2 message pagination #44660

Closed as not planned

Description

@pascalandr

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 seek query containing a zero-based message rank, mutually exclusive with cursor
  • optional cursor.range response metadata containing start, end, and total
  • a seek response still returns normal opaque previous and next cursors, 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 compaction message 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

  1. github-actions commented on Aug 24, 2026

    @github-actions
    Contributor

    This issue might be a duplicate of existing issues. Please check:

  2. pascalandr commented on Aug 24, 2026

    @pascalandr
    Author

    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.

  3. changed the title [-]question(v2): random access in paginated session messages[/-] [+][FEATURE]: Add random seek metadata to V2 message pagination[/+] on Aug 25, 2026
  4. pascalandr commented on Aug 25, 2026

    @pascalandr
    Author

    I prepared the focused implementation on pascalandr:message-seek while waiting for design approval before opening a PR.

    It keeps existing cursor tokens unchanged, adds optional seek plus optional end-exclusive cursor.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.

  5. pascalandr commented on Aug 28, 2026

    @pascalandr
    Author

    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.

  6. github-actions commented on Oct 27, 2026

    @github-actions
    Contributor

    To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions