Skip to content

Commit 2f0c047

Browse files
fix(server): keep the t3_thread_read tool list within main's agent context budget
The newest-first read had grown the advertised tool list by 316 bytes. `afterPosition=-1` now starts a read at the oldest item, replacing the `latest` flag, and the t3_thread_read description and its limit descriptions are shorter, so the tool list is smaller than main's again. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 18e4f0b commit 2f0c047

7 files changed

Lines changed: 14 additions & 22 deletions

File tree

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -473,10 +473,12 @@ it("readThread returns the newest items that fit the response budget", async ()
473473
const result = yield* service.readThread(makeScope(), read);
474474
// Linked environments and the CLI read as clients without a cursor and follow only hasMore.
475475
const first = yield* service.readThread({ ...makeScope(), thread: undefined }, read);
476+
const fromStart = yield* service.readThread(makeScope(), { ...read, afterPosition: -1 });
476477

477478
expect(pageOptions).toEqual([
478479
{ beforePosition: Number.POSITIVE_INFINITY, limit: 100, view: "activity" },
479480
{ limit: 100, view: "activity" },
481+
{ afterPosition: -1, limit: 100, view: "activity" },
480482
]);
481483
// Claude Code saves results over ~50k chars of this JSON to a file instead of showing them.
482484
expect(JSON.stringify(result).length).toBeLessThan(31_000);
@@ -487,6 +489,7 @@ it("readThread returns the newest items that fit the response budget", async ()
487489
expect(first.items[0]?.position).toBe(0);
488490
expect(first.hasMore).toBe(true);
489491
expect(first.nextPosition).toBe(first.items.at(-1)?.position);
492+
expect(fromStart.items[0]?.position).toBe(0);
490493
}).pipe(Effect.provide(layer), Effect.runPromise);
491494
});
492495

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3070,7 +3070,7 @@ const make = Effect.gen(function* () {
30703070
// Client callers (the CLI, older linked environments) page forward from a cursorless read.
30713071
const newestFirst =
30723072
input.beforePosition !== undefined ||
3073-
(input.afterPosition === undefined && (input.latest ?? scope.thread !== undefined));
3073+
(input.afterPosition === undefined && 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. 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.",
248+
"Read any thread by id. View `messages` (default) or `activity` (all items). Newest first; older: `beforePosition=earlierPosition`; from the start: `afterPosition=-1`, then `nextPosition`. Cut-off text: `itemId`, `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, latest=false; paginate with afterPosition=nextPosition, 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, afterPosition=-1; 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": 48442
4+
"mcpToolListJsonBytes": 48099
55
}

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

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -405,9 +405,8 @@ reads without a cursor gets the newest items, and `beforePosition=earlierPositio
405405
reads older ones. Client callers (the CLI, linked environments, outside MCP
406406
clients) start at the oldest item instead, because the CLI and linked
407407
environments on older versions read that way and follow only `hasMore`.
408-
`latest` overrides either default, and `afterPosition=nextPosition` reads newer
409-
items. The
410-
server stops adding items once the result reaches about 30,000 characters and
408+
`afterPosition=-1` starts any read at the oldest item, and
409+
`afterPosition=nextPosition` reads newer items. The server stops adding items once the result reaches about 30,000 characters and
411410
reports the rest through `earlierPosition` or `hasMore`. Claude Code saves MCP
412411
results over its token limit to a file instead of showing them, so a read has
413412
to fit whatever `limit` an agent asks for.

‎packages/contracts/src/orchestratorMcp.ts‎

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -436,22 +436,12 @@ export const OrchestratorMcpThreadReadInput = Schema.Struct({
436436
itemId: Schema.optional(TurnItemId),
437437
textOffset: Schema.optional(NonNegativeInt),
438438
view: Schema.optional(Schema.Literals(["messages", "activity"])),
439-
afterPosition: Schema.optional(NonNegativeInt),
440-
beforePosition: Schema.optional(NonNegativeInt).annotate({
441-
description: "Read backward from here.",
442-
}),
443-
latest: Schema.optional(Schema.Boolean).annotate({
444-
description:
445-
"Without a cursor, read the newest items first. Defaults to true from a T3 thread.",
446-
}),
447-
limit: Schema.optional(clampedPositiveInt(100)).annotate({
448-
description: "Max items, 1 to 100.",
449-
}),
450-
runLimit: Schema.optional(clampedPositiveInt(50)).annotate({
451-
description: "Max recent runs, 1 to 50.",
452-
}),
439+
afterPosition: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(-1))),
440+
beforePosition: Schema.optional(NonNegativeInt),
441+
limit: Schema.optional(clampedPositiveInt(100)).annotate({ description: "Max 100." }),
442+
runLimit: Schema.optional(clampedPositiveInt(50)).annotate({ description: "Max 50." }),
453443
maxCharsPerItem: Schema.optional(clampedPositiveInt(20_000)).annotate({
454-
description: "Max chars per item, 1 to 20000.",
444+
description: "Max 20000.",
455445
}),
456446
});
457447
export type OrchestratorMcpThreadReadInput = typeof OrchestratorMcpThreadReadInput.Type;

0 commit comments

Comments
 (0)