Expose one shared cursor-based pagination primitive for plugin authors

[V3RON]

Summary

Agent tool pagination is implemented four different ways across the codebase, the shared primitive that should prevent that is duplicated in two private copies and exported to nobody, and the most common of the four conventions — offset/limit over a live collection — silently skips rows.

Proposal: settle on one pagination model (cursor/keyset), move the existing primitive into @rozenite/agent-shared, export it for plugin authors, and add the one adapter that makes the simple cases a one-liner.

Current state

Four conventions

where	shape
mmkv, storage, file-system, redux-devtools plugins	offset / limit, hand-rolled
network-activity plugin	cursor / limit, hand-rolled
tanstack-query plugin	cursor + page{hasMore,nextCursor}
built-in console domain	paginateSource with a validated opaque cursor

An agent that learns how console.getMessages pages learns nothing transferable about mmkv.list-entries.

The primitive is duplicated and private

paginateSource, PaginatedSource, encodeCursor, hashFilters exist in two copies:

• packages/cli/src/commands/agent/runtime/pagination/
• packages/middleware/src/agent/runtime/pagination/

diff shows the divergence is currently formatting only (different prettier settings), so consolidation is mechanical today. It will not stay that way.

Neither copy is exported from agent-shared, agent-sdk, or agent-bridge, so a plugin author has no way to reach it. That is why six plugins hand-rolled their own.

Motivation: offset pagination over a live app is incorrect

packages/mmkv-plugin/src/react-native/useMMKVAgentTools.ts:87-90:

const allKeys = view.getAllKeys();
const safeOffset = Math.max(0, Math.floor(offset));
const keys = allKeys.slice(safeOffset, safeOffset + safeLimit);

Same pattern in useStorageAgentTools.ts:108-110 and useFileSystemAgentTools.ts:98-107. No sort anywhere. Two independent defects:

1. Order is undefined. getAllKeys() ordering is an implementation detail of the underlying store. Nothing guarantees two calls agree, so "page 2" is not a well-defined concept.

2. Live mutation shifts indices. The app keeps running while the agent pages. Agent reads offset 0..99; the app deletes any key before index 100; agent reads offset 100..199 — the entry formerly at index 100 is now at 99 and is silently skipped. No error, no gap marker. Insertions cause silent duplicates the same way.

Keyset pagination fixes both by construction: sort by a stable unique key, checkpoint on the last key returned, resume at "first key strictly greater than checkpoint". A deletion behind the cursor is harmless; an insertion lands in its correct position.

Every source in question has a natural stable key — MMKV/storage keys by name, files by path, redux actions by seq, network requests by id, console messages by seq — so there is no case here that needs offsets.

Proposal

One model

Cursor/keyset only. Drop offset from the agent tool surface.

The existing PaginatedSource<TCheckpoint, TItem, TFilters> interface is already the right shape and needs no redesign:

listFrom(input: { checkpoint?, order, limit, filters }): ListFromResult<TCheckpoint, TItem>
getBounds(filters): SourceBounds<TCheckpoint>

Move it to agent-shared and export it

agent-shared is already the common dependency of agent-bridge (plugin-side), agent-sdk, cli, and middleware, and it already hosts defineAgentToolContract. A paginated tool needs both, so they belong in one import. This also collapses the two duplicate copies before they diverge semantically.

Add an adapter for the trivial case

The reason six plugins hand-rolled .slice() is that implementing listFrom by hand looks harder than not. It should be one call:

const source = createSortedArraySource({
  items: () => view.getAllKeys(),
  keyOf: (key) => key,
});

The adapter owns sorting, checkpoint resolution, hasMore, and bounds. The author writes no pagination logic and gets correct behaviour under concurrent mutation for free.

Surface total

getBounds can already supply it; the envelope just never exposes it. Without a magnitude, hasMore: true forces the agent to choose blind between walking pages and stopping early — and those are very different decisions depending on whether the answer is 62 or 4,000. With total, one call is often enough to decide to narrow the filter instead of walking 80 pages.

Note this is orthogonal to the pagination model — an exact count is as cheap for keyset as for offset, which is why dropping offset costs nothing here.

Sub-point: make the cursor token readable

Not a separate model change — the same keyset semantics with a cheaper encoding.

Today encodeCursor emits base64url(JSON) of {v, t, d, p, f, o}. Measured on a realistic getMessages cursor with filters: 180 chars, of which the full sha1 filtersHash is 40 (30% of the decoded payload) and deviceId is 36.

• filtersHash guards against "you changed filters mid-walk" (validateCursorContext). It is a mistake detector, not a security boundary — 8 chars is ample.
• deviceId is redundant: sessions are device-keyed, --session already pins it, and per Agent sessions should auto-heal after an app relaunch #317 the deviceId survives rebind.

A readable composite — 8891~a3f2 — is ~13 chars, and gives the agent three things base64 does not:

• it can see whether it is advancing or looping; two opaque blobs look identical, 8891 → 8941 does not
• the position survives context compaction as meaning ("read up to seq 8891") rather than noise
• "everything newer than what I already saw" needs no decode step

The usual objection to a readable cursor is that callers will do arithmetic on it (cursor + 50), which is wrong for keyset. The guard is exactly what prevents that: a hand-constructed token fails loudly because the caller cannot compute the guard. Readability and safety are not in tension here — the guard is what buys the readability.

Crucially, none of this reaches plugin authors: they return a typed TCheckpoint and the framework encodes it, so the wire format stays a framework-internal decision that can change again later without touching a single plugin.

Also expose position as a first-class envelope field so the common case needs no parsing at all.

Also worth unifying: the two limit regimes

• packages/cli/src/commands/agent/runtime/pagination/limits.ts — DEFAULT_PAGE_LIMIT = 50, MAX = 200
• packages/cli/src/commands/agent/output-shaping.ts — DEFAULT_PAGE_LIMIT = 20, MAX = 100

Same -n, --limit flag, different ceilings depending on whether you are listing domains or calling a tool. Pick one pair.

Suggested scope

• Move pagination/ into packages/agent-shared/src/ and export paginateSource, PaginatedSource, PageEnvelope, PageRequest
• Delete the duplicate copies in packages/cli/ and packages/middleware/, re-importing from agent-shared
• Add createSortedArraySource for stable keyed collections
• Add total to PageEnvelope, sourced from getBounds / an explicit count
• Shorten filtersHash to 8 chars and drop deviceId from the cursor payload
• Replace the base64 token with a readable <position>~<guard> composite, and add position to the envelope
• Migrate mmkv, storage, file-system, redux-devtools from offset to cursor
• Migrate network-activity and tanstack-query onto the shared primitive
• Unify the two DEFAULT_PAGE_LIMIT / MAX_PAGE_LIMIT pairs
• Document the primitive in website/src/docs/agent/making-your-plugin-agent-enabled.mdx
• Tests: concurrent mutation during a walk (the skip bug above), unsorted source input, stale checkpoint, guard mismatch, total accuracy

Breaking changes

Tool argument shapes change for four plugins (offset → cursor) and the cursor token format changes for everyone. Both are agent-facing rather than app-facing — no application code calls these — but the plugin packages need a coordinated release.

Migrating the four offset plugins is a bug fix, not just a consistency change, so it is worth doing even though it breaks their tool signatures.

Related

• Agent sessions should auto-heal after an app relaunch #317 — session auto-heal. The cursor can drop deviceId partly because deviceId is stable across rebind there.
• Emit columnar JSON for row-shaped agent output to cut token usage #318 — columnar output. Covers dropping the terminal page envelope and emitting next as a runnable command; this issue covers what goes in the envelope.
• Separate bug, not covered here: packages/agent-sdk/src/pagination.ts:139 does merged.page = { ...next.page } on every iteration, so a reset: true raised at page 2 of a 5-page auto-paginated walk is overwritten by page 3 and vanishes from the final envelope — the caller gets a result that silently discarded accumulated pages. Worth its own issue.

[V3RON]

Implementation boundary agreed with #318: this will be an independent PR against main and owns the shared pagination primitive, cursor/keyset semantics, and pagination envelope data. #318 separately owns CLI output shaping. Rebase coordination may be needed depending on merge order.

[V3RON]

Note from MCP server design

We're planning a rozenite mcp server that exposes a gateway tool surface (discover / describe / call / release) instead of flat-exposing all ~80 agent tools. Part of that design is having the server auto-paginate up to a budget and hand the model a single consolidated result, so it doesn't have to manage cursor walks by hand.

This issue is a prerequisite for that, for two reasons.

1. Auto-pagination over the offset plugins is currently unsafe

The silent-skip bug described here (useMMKVAgentTools.ts:87-90, same in useStorageAgentTools.ts and useFileSystemAgentTools.ts) is bad when an agent walks pages deliberately. It's worse when a server walks them automatically, because it turns a bug the agent might notice into one it cannot: the consolidated result looks complete and has no gap marker.

@rozenite/agent-sdk already has callToolWithOptionalPagination, and MCP would use exactly that path — so migrating those four plugins from offset to cursor gates the feature.

2. packages/agent-sdk/src/pagination.ts:139 blocks it too

The bug noted at the end of this issue — merged.page = { ...next.page } on every iteration, so a reset: true raised at page 2 of a 5-page walk is overwritten and vanishes — is in the exact code path MCP would depend on. Happy to see it filed separately, but flagging that it's load-bearing for auto-pagination rather than an edge case.

total is the highest-value item here for MCP

Strong +1, and it's worth more in MCP than on the CLI. hasMore: true alone forces the model to choose blind between walking pages and stopping early, and it resolves that by walking. With total, one call decides whether to narrow the filter instead — total: 62 and total: 4000 lead to completely different next actions.

Readable cursors: less critical for MCP, still fine

In the gateway design the server manages cursors, so the model mostly sees an opaque page token it passes back. The "am I advancing or looping" benefit is real but mostly accrues to the CLI path. No objection — just noting MCP isn't the motivating case, so it shouldn't be weighted as if it were.

Two limit regimes: consider a token budget instead of picking a pair

Re: limits.ts (50/200) vs output-shaping.ts (20/100) — #318's measurements show per-row size varying by more than an order of magnitude between tree nodes and console messages, so any fixed row count is either wasteful or truncating depending on the tool. MCP will cap on serialized size rather than row count. Might be a better answer than choosing one of the two pairs.

Request: keep the extraction going one step further

Moving pagination/ into agent-shared and deleting the two private copies is exactly right. Related ask on #318: the columnar encoder and parseFields projection are about to be added to packages/cli/src/commands/agent/output-shaping.ts, i.e. CLI-private — the same shape of problem this issue is fixing. Since this issue is already touching the envelope, it's nearly free to land the whole shaping layer (pagination envelope + projection + columnar) in one shared place, so CLI and MCP are thin renderers over it.

No changes requested to the proposed pagination model — cursor/keyset only, with createSortedArraySource for the trivial case, is what makes server-side auto-pagination correct by construction.

[V3RON]

Note from #322: the token-based page cap belongs here, not there

Carve-out 2 on #318 suggested capping pages on serialized size rather than row count, and noted it "happens to sidestep the 'two limit regimes' question" raised here. We looked at implementing it in #322 and concluded it can't be done correctly without this issue's producer-side work. Recording why, so it isn't rediscovered.

A byte cap only helps if it can truncate mid-page, and a consumer cannot. Cursor encoding is producer-owned and opaque — built-in domains use base64url of {v,scope,index}, plugins may use anything — so nothing downstream can express "stop at row 7 of this page". A CLI-side cap therefore has only two options, both bad:

1. Truncate and reuse the producer's cursor → silently skips the discarded rows. This is exactly the data-loss bug filed as autoPaginate.maxItems silently drops rows and returns a cursor that skips them #329 / fixed in fix(agent-sdk): stop maxItems from dropping rows and reporting a stale cursor #332, reintroduced deliberately.
2. Re-request with a smaller limit → correct, but costs an extra round trip per overshoot, and the caller has to guess the row size in advance.

The correct shape is for the producer to accept a byte or token budget and return a cursor at whatever row it actually stopped at. That is a change to PaginatedSource/listFrom and the cursor payload, both owned by this issue.

It also interacts with two things already in scope here:

• The two limit regimes. Unifying 50/200 and 20/100 and adding a size budget are the same decision — whether the page bound is rows, bytes, or both. Settling one without the other means revisiting it.
• total. Once a size budget exists, hasMore: true is even less actionable than the argument above makes it, because the agent can no longer infer remaining work from a known page size. A size-bounded page makes surfacing total more valuable, not less.

One data point in favor. #318's measurements show a >10x spread in per-row size on real tools: tree-node rows are short integers (65% saving from columnar encoding), console rows carry one long text field (23%). Any fixed row limit is therefore either wasteful on narrow tables or truncating on console output, which is the strongest argument for the change — it just needs to land producer-side.

Suggested sequencing: land PaginatedSource in agent-shared with the cursor/keyset model first, then add the size budget to listFrom as part of settling the limit regimes, then let CLI and MCP pass their own budget. #322 leaves the row-based cap untouched so it has nothing to unwind.

For reference, #332 adds truncated?: boolean to PageEnvelope for the case where a consumer is forced to truncate and has no trustworthy resume position. If a producer-side size budget lands here, it should not need that field — it can always return an accurate cursor — so truncated is a fallback for misbehaving producers, not a model this should build on.