Skip to content

G3: Add bounded cursor pagination for list commands #195

Description

@SarthakWade

Problem

Large artifact and diagnostic collections are currently bounded by truncation. Agents can see that data was omitted but cannot retrieve later entries without clearing state or changing unrelated limits.

Split from #54 G3.

Contract

  • Add an architecture decision defining cursor opacity, scope, ordering, expiry, mutation behavior, bounds, and error codes.
  • Introduce one reusable pagination model for artifacts list, console list, and network list.
  • Support a bounded --limit and opaque --cursor; reject unknown, malformed, expired, cross-command, cross-session, and tampered cursors.
  • Keep ordering deterministic and prevent duplicates or skips for an unchanged collection.
  • Bind diagnostic cursors to the session and command filters. Bind artifact cursors to the artifact store.
  • Never encode filesystem paths, secrets, cookie or storage values, page-controlled text, or unbounded state into cursors.
  • Keep every page below the 1 MiB frame and report nextCursor, returned, total or available where it is truthful, and truncation or mutation state.
  • Preserve safe backward compatibility for callers that omit pagination options.

Acceptance criteria

  • All three list commands can traverse collections larger than one page.
  • Stable collections produce complete, ordered, duplicate-free traversal.
  • Collection mutation has an explicit tested contract and never silently returns misleading data.
  • Cursor misuse fails closed with typed recovery guidance.
  • Limits are validated consistently by CLI and protocol layers.
  • Cursors and responses remain bounded and redact sensitive data.
  • CLI, protocol schema, SDK generation, MCP, unit, and both-engine E2E coverage pass.
  • Documentation explains cursor lifetime and restart behavior.

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:cliCLI parser, help, capabilitiesarea:core-protocolHeadlessProtocol: wire protocol, validation, transportpriority:mediumScheduled, not blockingtype:featureNew capability or command

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions