fix(agent-sdk): stop maxItems from dropping rows and reporting a stale cursor

[V3RON]

Description

callToolWithOptionalPagination trimmed collected items down to maxItems but passed the producer's page envelope through unchanged, so the returned page.nextCursor pointed past the rows it had just discarded. Those rows became unreachable with no error and no gap marker.

Two independent loss paths, both fixed:

• Initial page — with limit: 20, maxItems: 5, the tool returned 20 rows, the caller received 5, and the cursor still pointed past row 19. Rows 5–19 vanished, and the result looked complete.
• Mid-loop — with limit: 5, maxItems: 7, rows 7–9 were fetched, discarded, and skipped by the propagated cursor.

The fix is to stop over-fetching: every request, including the first, now asks for min(callerLimit, maxItems - collectedSoFar), so a well-behaved producer's own cursor lands exactly on the truncation boundary. No cursors are synthesized.

For producers that clamp or ignore limit (console.getMessages documents "Default 50, max 200"), truncation can still happen. In that case the cursor is untrustworthy, so it is dropped and a new truncated: true field is set on PageEnvelope alongside hasMore: true, meaning "rows were dropped; resume position is unknown — restart or narrow the query."

Related Issue

Closes #329

Context

The SDK cannot fix this by computing a cursor. Cursor encoding is producer-owned and opaque — built-in domains use base64url of {v,scope,index}, third-party plugins may use anything — so there is no way to express "row 5 of this page". Hence the two-part approach: make truncation not happen in the common case, and signal it honestly when a producer forces it.

hasMore is deliberately true whenever truncated is set: we positively know unconsumed rows exist, since we just discarded them, even though the resume position is lost.

Reviewer notes:

• One existing test (caps an oversized first page...) encoded the bug as expected behavior, asserting that a limit-ignoring producer's stale cursor was propagated past a discarded row. Its expectations were updated. Worth a look, since the bug had a test blessing it.
• merged.page.limit still reports the producer's real page size, not the SDK's internally reduced request limit.
• page.reset handling is untouched and its existing tests pass unmodified.
• validateAutoPagination still requires pagesLimit alongside maxItems. That constraint is arguably now unnecessary, since maxItems alone is well-defined once requests are budgeted, but relaxing it is a public API change and is left out of a bugfix.
• Deliberately excludes CLI output changes. feat(cli): emit reusable columnar JSON for paginated output #322 renders page.nextCursor into a runnable next command, which is what makes this bug user-visible; consuming the new truncated signal there is a follow-up on that branch, since the code it needs does not exist on main.

Testing

• Added regression tests to packages/agent-sdk/src/__tests__/pagination.test.ts for both loss paths, using a fake producer that mirrors the real cursor encoding in local-domains.ts. Each asserts on concrete row identities: the union of rows received plus rows reachable via the returned cursor. Both were confirmed failing before the fix (expected [5,6,...,19] to deeply equal [] and expected [7,8,9] to deeply equal []).
• npx turbo run typecheck lint test --force across the whole repo: 99 successful, 99 total.
• Version plan added: .changeset/agent-sdk-max-items-row-loss.md (@rozenite/agent-sdk patch, @rozenite/agent-shared minor for the new PageEnvelope field).