fix(server): t3_thread_read returns the newest items and fits in agent context#33428

Explanation

The title names the main change: t3_thread_read now returns the newest items and fits within the agent context limit. The changeset implements newest-first reads with backward paging, a response budget, and a lower maxCharsPerItem ceiling, so the title matches the primary intent. It follows the conventional commit format and is specific enough for a teammate scanning history.

Explanation

Scope: directly linked issue #33417 only. It is open and has no parent context. Its requirements are coding requirements.

[#33417] Default or documented reads must fit the agent output limit. Implemented. In apps/server/src/mcp/OrchestratorMcpService.ts, readThread adds a THREAD_READ_BUDGET_CHARS = 30_000 budget. It measures the encoded thread, recentRuns and each item, and stops adding items when the next item would exceed the budget. It always keeps at least one item. The diff shows this. The summary reports that the maxCharsPerItem ceiling drops from 50,000 to 20,000 in packages/contracts. The added test in OrchestratorMcpService.activity.test.ts asserts fewer than 100 items and under 31,000 serialized characters for 100 activity items of 1,500 chars each. The PR also reports measured reads of 27,841 to 29,880 chars on real threads.

[#33417] An agent gets the latest messages in one call. Implemented. With no afterPosition, readThread passes beforePosition = Infinity to getTimelinePage. ProjectionStore.ts then returns matching.slice(-limit), which is the newest page in chronological order. The response sets hasMore false for that page and sets earlierPosition for older items. The CLI readLatestMessages walks back with earlierPosition. Its loop normally finishes in one call, but it is not guaranteed to be a single call. The issue's expected behavior is met for MCP agents.

[#33417] Paging must work in both directions and be documented. Implemented. beforePosition reads older items. afterPosition reads newer items. afterPosition = -1 starts at the first item. ProjectionStore.test.ts has newest-page and earlier-page assertions. The tool description in apps/server/src/mcp/toolkits/orchestrator/tools.ts and docs/orchestration-v2/orchestrator-mcp-server.md were updated. I did not read the test or doc files directly. This relies on the summary.

[#33417] Proposed lower defaults (limit 20, maxCharsPerItem 4000, runLimit 3). Not adopted. The diff leaves DEFAULT_THREAD_READ_LIMIT = 50, DEFAULT_THREAD_RUN_LIMIT = 10 and DEFAULT_THREAD_ITEM_MAX_CHARS = 20_000 unchanged. The issue presents these as part of a proposed fix. Its stated expected behavior is met by the response budget, so this deviation does not fail the assessment. The PR objectives and description state that the author made this choice.

Process note, not a coding requirement: the issue asked for a yes or no from a maintainer on the newest-first default before implementation. The PR states that no maintainer has replied. This assessment does not treat that as a coding failure.

Uncertainty: I did not run the test suite. Test results rely on the PR description.

Explanation

Every change group maps to #33417 or to a direct consequence of the requested changes.

• apps/server/src/orchestration-v2/ProjectionStore.ts: adds beforePosition and hasEarlier. This implements backward paging and the newest-page default. The default store behavior stays oldest-first when beforePosition is absent. Verified in the diff.
• apps/server/src/mcp/OrchestratorMcpService.ts: adds the response budget, newest-first selection, and earlierPosition. These implement the issue's core requirements. Verified in the diff.
• apps/server/src/cli/thread.ts (readLatestMessages, readTimeline): the issue asks that the CLI readLatestMessages stop widening windows. The change uses backward paging. readTimeline passes afterPosition: -1 so it keeps its oldest-first behavior. This is connected to the default change.
• apps/server/src/peer/RemoteDelegation.ts: lastReply relied on oldest-first forward paging. Once the default changes, it must read backward from the newest page when the peer sends earlierPosition. It keeps forward reads for older peers. This is a direct consequence of the default change. I did not read this file. The link relies on the PR description and summary.
• packages/contracts/src/orchestratorMcp.ts: adds beforePosition, allows afterPosition = -1, adds optional earlierPosition, and lowers the maxCharsPerItem ceiling to 20,000. The ceiling change keeps one item from consuming the whole budget. This supports the response budget requirement.
• Tests (cli/thread.test.ts, McpHttpServer.test.ts, OrchestratorMcpService.activity.test.ts, ProjectionStore.test.ts, RemoteDelegation.test.ts, tools.test.ts, core.test.ts): updated fixtures and new assertions for the changed behavior.
• Docs and tool description: required by #33417.

No change was found that is unrelated to #33417. Minor side effect: item-scoped reads (itemId) now return the newest matching rows when no cursor is given, because the same default applies. This follows from the new default and is not unrelated work.

Explanation

The description follows the template closely and is substantively complete. It states the problem with measured data (137 of 308 calls overflowed Claude Code's MCP output limit) and a root-cause analysis (oldest-first paging and no total-size bound). The Change section gives a diff-style summary and explains the read-direction semantics, the 30,000-character response budget, the lowered maxCharsPerItem ceiling, and the caller updates (CLI readLatestMessages, readTimeline, RemoteDelegation.lastReply, tool description, docs). Scope and approval is addressed: it links issue 33417, says the author filed it and has no maintainer reply yet, and openly flags that the newest-first default change needs maintainer sign-off. Verification is detailed: a before/after table on a real database copy, the specific failing-on-main tests, the vitest file list with pass counts, typecheck and lint results, and explicit 'not checked' items. The model and harness are named at the end. Minor gaps: the Scope section does not include a maintainer approval comment for the default change, which the template asks for, and the author acknowledges this. The Verification section does not include screenshots, but this is not a UI change, so that requirement does not apply.

• Create a new PR