Skip to content

feat(protocol): add bounded list pagination - #201

Merged
SarthakWade merged 3 commits into
feat/196-session-metadatafrom
feat/195-response-pagination
Sep 19, 2026
Merged

SarthakWade merged 3 commits into
feat/196-session-metadatafrom
feat/195-response-pagination

Conversation

@SarthakWade

Copy link
Copy Markdown
Collaborator

Summary

  • add reusable opaque cursor pagination to artifact, console, and network lists
  • preserve deterministic ordering while rejecting expired, malformed, stale, cross-command, cross-filter, and cross-session cursors
  • bound limits, cursor state, and encoded page values below the protocol frame ceiling
  • publish typed CLI, protocol schema, TypeScript, Python, MCP, documentation, and both-engine E2E coverage

Security and compatibility

  • cursor tokens are random server-side identifiers and contain no offsets, paths, filters, session names, page text, or secrets
  • cursor records expire after five minutes, are capped at 512 entries per owning store, and disappear on restart
  • collection mutations fail closed with typed recovery guidance instead of returning a misleading continuation
  • callers that omit pagination options retain the prior first-page behavior and existing result fields

Validation

  • pnpm test
  • pnpm test:runtime
  • pnpm test:npm
  • Python pytest, mypy, ruff, and generated-contract checks
  • web lint and production build
  • production macOS app build
  • focused WebKit and Chromium pagination flows, including stale, malformed, and wrong-filter failures
  • shell syntax and generated-contract drift checks

Closes #195

@SarthakWade
SarthakWade added this pull request to stack #202 September 19, 2026 09:58

@yashranaway yashranaway left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pagination for artifact.list, console.list, and network.list is fail-closed.

Cursors are random UUIDs stored in the owning process, not offsets in the token. They bind command/filter context, collection fingerprint, and direction, expire in five minutes, cap at 512 records, and vanish on restart. Unknown, expired, wrong-scope, and stale tokens are distinct errors. Limits are 1–250. Encoded page values stay under 768 KiB so the 1 MiB frame still has room for metadata. Default first-page behavior is preserved.

CI is green. Stacks on #199; merge 197 → 198 → 199 → 201.

@SarthakWade
SarthakWade merged commit 49f1b91 into main Sep 19, 2026
39 of 42 checks passed
@SarthakWade
SarthakWade deleted the feat/195-response-pagination branch September 19, 2026 11:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

G3: Add bounded cursor pagination for list commands

2 participants