Skip to content

Commit 18e4f0b

Browse files
fix(server): cursorless t3_thread_read returns the newest items for thread agents
An agent in a T3 thread that reads without a cursor now gets the newest items again, so it no longer pages through a long thread to reach the latest reply. Client callers (the CLI, linked environments, outside MCP clients) keep the oldest-first default they page forward from, and `latest` overrides either default. The context-handoff hint asks for `latest=false` because it walks history from the start. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent dcd11e0 commit 18e4f0b

7 files changed

Lines changed: 17 additions & 14 deletions

File tree

‎apps/server/src/mcp/OrchestratorMcpService.activity.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -470,9 +470,9 @@ it("readThread returns the newest items that fit the response budget", async ()
470470
limit: 100,
471471
maxCharsPerItem: 1_500,
472472
};
473-
const result = yield* service.readThread(makeScope(), { ...read, latest: true });
474-
// Older linked environments read without a cursor and follow only hasMore.
475-
const first = yield* service.readThread(makeScope(), read);
473+
const result = yield* service.readThread(makeScope(), read);
474+
// Linked environments and the CLI read as clients without a cursor and follow only hasMore.
475+
const first = yield* service.readThread({ ...makeScope(), thread: undefined }, read);
476476

477477
expect(pageOptions).toEqual([
478478
{ beforePosition: Number.POSITIVE_INFINITY, limit: 100, view: "activity" },

‎apps/server/src/mcp/OrchestratorMcpService.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3067,10 +3067,10 @@ const make = Effect.gen(function* () {
30673067
const view = input.view ?? "messages";
30683068
const limit = input.limit ?? DEFAULT_THREAD_READ_LIMIT;
30693069
const maxChars = input.maxCharsPerItem ?? DEFAULT_THREAD_ITEM_MAX_CHARS;
3070-
// Cursorless reads stay oldest-first: older linked environments page forward from them.
3070+
// Client callers (the CLI, older linked environments) page forward from a cursorless read.
30713071
const newestFirst =
30723072
input.beforePosition !== undefined ||
3073-
(input.latest === true && input.afterPosition === undefined);
3073+
(input.afterPosition === undefined && (input.latest ?? scope.thread !== undefined));
30743074
const timeline = yield* threadManagement
30753075
.getTimelinePage(input.threadId, {
30763076
...(input.afterPosition === undefined ? {} : { afterPosition: input.afterPosition }),

‎apps/server/src/mcp/toolkits/orchestrator/tools.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ const ThreadListTool = Tool.make("t3_thread_list", {
245245

246246
const ThreadReadTool = Tool.make("t3_thread_read", {
247247
description:
248-
"Read any thread by id. `messages` (default): user and assistant messages and plans. `activity`: all timeline items. Results are cut to fit about 30k chars. Page with `afterPosition=nextPosition` while `hasMore`. Newest items: `latest=true`, then older with `beforePosition=earlierPosition`. Cut-off text: `itemId` with `textOffset=nextTextOffset`. Reading a child's final result marks it delivered. In your reply, name it as its `link` verbatim.",
248+
"Read any thread by id. `messages` (default): user and assistant messages and plans. `activity`: all timeline items. Results are cut to fit about 30k chars. Returns the newest items; older with `beforePosition=earlierPosition`. From the start: `latest=false`, then `afterPosition=nextPosition` while `hasMore`. Cut-off text: `itemId` with `textOffset=nextTextOffset`. Reading a child's final result marks it delivered. In your reply, name it as its `link` verbatim.",
249249
parameters: OrchestratorMcpThreadReadInput,
250250
success: OrchestratorMcpThreadReadResult,
251251
failure: OrchestratorMcpFailure,

‎apps/server/src/orchestration-v2/ContextHandoffDelivery.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ export const deliverContextHandoffs = Effect.fn("orchestrationV2.deliverContextH
4444
(handoff) =>
4545
`Context handoff (${handoff.strategy === "fork_delta_summary" ? "merge_back / fork_delta_summary" : handoff.strategy}):\n${
4646
handoff.history?.coverage ??
47-
`From thread ${handoff.threadId}, runs ${handoff.coveredRunOrdinals.from}-${handoff.coveredRunOrdinals.to}. Recover history with t3_thread_read, view=activity; paginate with afterPosition, and use itemId/textOffset for long items.`
47+
`From thread ${handoff.threadId}, runs ${handoff.coveredRunOrdinals.from}-${handoff.coveredRunOrdinals.to}. Recover history with t3_thread_read, view=activity, latest=false; paginate with afterPosition=nextPosition, and use itemId/textOffset for long items.`
4848
}`,
4949
)
5050
.join("\n");
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"claudeSystemAppendBytes": 5597,
33
"codexAdditionalContextBytes": 7327,
4-
"mcpToolListJsonBytes": 48404
4+
"mcpToolListJsonBytes": 48442
55
}

‎docs/orchestration-v2/orchestrator-mcp-server.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -400,11 +400,13 @@ the environment by thread ID. A deleted thread returns `thread_not_found`. The
400400
default `messages` view returns user messages, assistant
401401
messages, and proposed plans. The `activity` view also returns summarized tool,
402402
reasoning, checkpoint, handoff, and runtime-request items. Large item text is
403-
bounded and reports whether it was truncated. A read without a cursor starts
404-
at the oldest item, and `afterPosition=nextPosition` reads newer ones. `latest`
405-
starts at the newest item instead, and `beforePosition=earlierPosition` reads
406-
older ones. The cursorless default stays oldest-first because linked
407-
environments on older versions read that way and follow only `hasMore`. The
403+
bounded and reports whether it was truncated. An agent in a T3 thread that
404+
reads without a cursor gets the newest items, and `beforePosition=earlierPosition`
405+
reads older ones. Client callers (the CLI, linked environments, outside MCP
406+
clients) start at the oldest item instead, because the CLI and linked
407+
environments on older versions read that way and follow only `hasMore`.
408+
`latest` overrides either default, and `afterPosition=nextPosition` reads newer
409+
items. The
408410
server stops adding items once the result reaches about 30,000 characters and
409411
reports the rest through `earlierPosition` or `hasMore`. Claude Code saves MCP
410412
results over its token limit to a file instead of showing them, so a read has

‎packages/contracts/src/orchestratorMcp.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -441,7 +441,8 @@ export const OrchestratorMcpThreadReadInput = Schema.Struct({
441441
description: "Read backward from here.",
442442
}),
443443
latest: Schema.optional(Schema.Boolean).annotate({
444-
description: "Without a cursor, read the newest items instead of the oldest.",
444+
description:
445+
"Without a cursor, read the newest items first. Defaults to true from a T3 thread.",
445446
}),
446447
limit: Schema.optional(clampedPositiveInt(100)).annotate({
447448
description: "Max items, 1 to 100.",

0 commit comments

Comments
 (0)