@devries-cameron20 / t3code-1 / commits / 6237824a2c
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(server): t3_thread_read results fit MCP clients' output limit (#33455)

Julius Marminge committed Nov 12, 2026 at 22:41 UTC 6237824a2c4c78a59188bda9845c5bd09ff5d52d
3 files changed +225 -45
apps/server/src/mcp/OrchestratorMcpService.activity.test.ts
+128
@@ -1,6 +1,7 @@
1 import {
2 EnvironmentId,
3 NodeId,
4 + type OrchestratorMcpThreadReadResult,
5 type OrchestrationV2ThreadProjection,
6 type OrchestrationV2ThreadShell,
7 ProjectId,
@@ -493,6 +494,133 @@ it("readThread returns the newest items that fit the response budget", async ()
494 }).pipe(Effect.provide(layer), Effect.runPromise);
495 });
496
497 +it("readThread keeps an activity page within an MCP client's output limit and pages the rest", async () => {
498 + const projection = {
499 + thread: baseThread({
500 + threadId: parentThreadId,
501 + title: "Parent",
502 + instanceId: parentInstanceId,
503 + model: "gpt-5.4",
504 + }),
505 + runs: [makeRun({ id: activeRunId, ordinal: 1, status: "running" })],
506 + visibleTurnItems: [],
507 + providerTurns: [],
508 + runtimeRequests: [],
509 + messages: [],
510 + contextTransfers: [],
511 + subagents: [],
512 + updatedAt: now,
513 + } as unknown as OrchestrationV2ThreadProjection;
514 + const rows = Array.from({ length: 60 }, (_, position) => ({
515 + position,
516 + visibility: "visible",
517 + sourceThreadId: parentThreadId,
518 + sourceItemId: TurnItemId.make(`turn-item-mcp-reasoning-${position}`),
519 + item: {
520 + type: "reasoning",
521 + runId: activeRunId,
522 + status: "completed",
523 + // Command titles can carry a whole command.
524 + title: position === 1 ? "標".repeat(60_000) : null,
525 + text: position === 0 ? "😀a".repeat(30_000) : `${position} `.padEnd(3_000, "x"),
526 + updatedAt: now,
527 + },
528 + }));
529 +
530 + const layer = layerOrchestratorService.pipe(
531 + Layer.provide(
532 + Layer.mergeAll(
533 + Layer.mock(ThreadManagementService.ThreadManagementService)({
534 + getTimelinePage: (_threadId, options) => {
535 + const after =
536 + options.itemId === undefined
537 + ? rows.filter((row) => row.position > (options.afterPosition ?? -1))
538 + : rows.filter((row) => row.sourceItemId === options.itemId);
539 + return Effect.succeed({
540 + items: after.slice(
541 + 0,
542 + options.limit,
543 + ) as unknown as OrchestrationV2ThreadProjection["visibleTurnItems"],
544 + totalItems: rows.length,
545 + hasMore: after.length > options.limit,
546 + hasEarlier: false,
547 + });
548 + },
549 + getThreadRecords: () => Effect.succeed(projection),
550 + getProjectThreadRecords: () => Effect.succeed(projection),
551 + getThreadShell: () =>
552 + Effect.succeed(projection.thread as unknown as OrchestrationV2ThreadShell),
553 + } satisfies Partial<ThreadManagementService.ThreadManagementService["Service"]>),
554 + ServerSettings.layerTest(),
555 + Layer.mock(ProviderRegistry.ProviderRegistry)({
556 + getProviders: Effect.succeed([]),
557 + } satisfies Partial<ProviderRegistry.ProviderRegistry["Service"]>),
558 + Layer.mock(ProjectService.ProjectService)({}),
559 + Layer.mock(SecretRequests.SecretRequests)({}),
560 + Layer.mock(RemoteDelegation.RemoteDelegation)({}),
561 + Layer.mock(ScheduledTaskService.ScheduledTaskService)({
562 + list: () => Effect.succeed({ tasks: [] }),
563 + } satisfies Partial<ScheduledTaskService.ScheduledTaskService["Service"]>),
564 + Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
565 + list: () => Effect.succeed([]),
566 + } satisfies Partial<ProviderAdapterRegistry.ProviderAdapterRegistryV2["Service"]>),
567 + NodeCrypto.layer,
568 + ),
569 + ),
570 + );
571 +
572 + await Effect.gen(function* () {
573 + const service = yield* OrchestratorMcpService.OrchestratorMcpService;
574 + const positions: Array<number> = [];
575 + let afterPosition: number | undefined;
576 + for (let page = 0; page < rows.length; page++) {
577 + const result = yield* service.readThread(makeScope(), {
578 + threadId: parentThreadId,
579 + view: "activity",
580 + limit: 100,
581 + maxCharsPerItem: 1_500,
582 + afterPosition: afterPosition ?? -1,
583 + });
584 + // Claude Code rejects MCP results over 25k tokens; CJK text is about a token per char.
585 + expect(Buffer.byteLength(JSON.stringify(result))).toBeLessThanOrEqual(50_000);
586 + if (page === 0) expect(result.hasMore).toBe(true);
587 + positions.push(...result.items.map((item) => item.position));
588 + if (!result.hasMore) break;
589 + afterPosition = result.nextPosition ?? undefined;
590 + }
591 + expect(positions).toEqual(rows.map((row) => row.position));
592 +
593 + const longText = rows[0]!.item.text;
594 + const pages: Array<string> = [];
595 + let textOffset: number | null = 0;
596 + while (textOffset !== null) {
597 + const result: OrchestratorMcpThreadReadResult = yield* service.readThread(makeScope(), {
598 + threadId: parentThreadId,
599 + view: "activity",
600 + itemId: rows[0]!.sourceItemId,
601 + textOffset,
602 + maxCharsPerItem: 50_000,
603 + });
604 + expect(Buffer.byteLength(JSON.stringify(result))).toBeLessThanOrEqual(50_000);
605 + const [item] = result.items;
606 + expect(item?.text?.isWellFormed()).toBe(true);
607 + pages.push(item!.text!);
608 + textOffset = item!.nextTextOffset ?? null;
609 + }
610 + expect(pages.length).toBeGreaterThan(1);
611 + expect(pages.join("")).toBe(longText);
612 +
613 + (projection.thread as { title: string }).title = "標".repeat(30_000);
614 + const underHugeTitle = yield* service.readThread(makeScope(), {
615 + threadId: parentThreadId,
616 + view: "activity",
617 + itemId: rows[0]!.sourceItemId,
618 + maxCharsPerItem: 50_000,
619 + });
620 + expect(underHugeTitle.items[0]?.text?.length).toBeGreaterThan(1_000);
621 + }).pipe(Effect.provide(layer), Effect.runPromise);
622 +});
623 +
624 it("taskStatus returns task.providerInstanceId rather than the driver kind", async () => {
625 const parentProjection = {
626 thread: baseThread({
apps/server/src/mcp/OrchestratorMcpService.ts
+93 -39
@@ -146,10 +146,9 @@ const DEFAULT_THREAD_LIST_LIMIT = 10;
146 const DEFAULT_THREAD_READ_LIMIT = 10;
147 const DEFAULT_THREAD_RUN_LIMIT = 10;
148 const DEFAULT_THREAD_ITEM_MAX_CHARS = 500;
149 -// Claude Code saves MCP results over ~25k tokens to a file instead of showing them. Thread JSON
150 -// runs about 2 chars per token, so a read stops adding items here and reports the rest as more.
151 -const THREAD_READ_BUDGET_CHARS = 30_000;
152 -const encodeJsonText = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
149 +// Claude Code saves MCP results over ~25k tokens to a file instead of showing them. Bytes, not
150 +// chars: CJK text runs near one token per char, which a char budget lets through at 30k tokens.
151 +const THREAD_READ_RESULT_MAX_BYTES = 30_000;
152
153 interface ResolvedTarget {
154 readonly modelSelection: ModelSelection;
@@ -635,14 +634,12 @@ function taskResultTransfer(
634
635 function pageIncludesTerminalTaskResult(input: {
636 readonly parentThreadId: ThreadId;
638 - readonly page: ReadonlyArray<OrchestrationV2ThreadProjection["visibleTurnItems"][number]>;
637 + readonly items: ReadonlyArray<OrchestratorMcpThreadTimelineItem>;
638 readonly task: OrchestrationV2Subagent;
639 readonly target: Pick<
640 OrchestrationV2ThreadProjection,
641 "thread" | "runs" | "contextTransfers" | "messages" | "turnItems" | "providerTurns"
642 >;
644 - readonly maxChars: number;
645 - readonly textOffset: number;
643 }): boolean {
644 const transfer = taskResultTransfer(input.parentThreadId, input.target, input.task);
645 if (transfer === undefined) return false;
@@ -655,21 +652,14 @@ function pageIncludesTerminalTaskResult(input: {
652 const result = subagentResultForRun(input.target, run);
653 if (result.messageId === null && result.turnItemId === null) return false;
654
658 - return input.page.some((row) => {
659 - if (row.sourceThreadId !== input.target.thread.id) return false;
655 + return input.items.some((item) => {
656 + if (item.sourceThreadId !== input.target.thread.id) return false;
657 const matchesResult =
661 - (result.turnItemId !== null && row.sourceItemId === result.turnItemId) ||
658 + (result.turnItemId !== null && item.itemId === result.turnItemId) ||
659 (result.messageId !== null &&
663 - row.item.type === "assistant_message" &&
664 - row.item.messageId === result.messageId);
665 - if (!matchesResult) return false;
666 -
667 - const text = turnItemText(row.item);
668 - return (
669 - text !== null &&
670 - (input.textOffset === 0 || input.textOffset < text.length) &&
671 - text.length <= textPageEnd(text, input.textOffset, input.maxChars)
672 - );
660 + item.type === "assistant_message" &&
661 + item.messageId === result.messageId);
662 + return matchesResult && item.text !== null && !item.textTruncated;
663 });
664 }
665
@@ -1102,6 +1092,78 @@ function timelineItem(input: {
1092 };
1093 }
1094
1095 +const jsonBytes = (value: unknown) => Buffer.byteLength(JSON.stringify(value), "utf8");
1096 +
1097 +/** The longest prefix length in [low, high] that `fits`, or `low - 1`. */
1098 +function longestFitting(low: number, high: number, fits: (length: number) => boolean): number {
1099 + let best = low - 1;
1100 + while (low <= high) {
1101 + const mid = Math.floor((low + high) / 2);
1102 + if (fits(mid)) {
1103 + best = mid;
1104 + low = mid + 1;
1105 + } else {
1106 + high = mid - 1;
1107 + }
1108 + }
1109 + return best;
1110 +}
1111 +
1112 +/** The item with its text cut, and an oversized title too, until its JSON fits `maxBytes`. */
1113 +function timelineItemWithin(
1114 + input: Parameters<typeof timelineItem>[0],
1115 + maxBytes: number,
1116 +): OrchestratorMcpThreadTimelineItem {
1117 + const longestText = (title: string | null) => {
1118 + const withText = (maxChars: number) => ({ ...timelineItem({ ...input, maxChars }), title });
1119 + const chars = longestFitting(2, input.maxChars - 1, (n) => jsonBytes(withText(n)) <= maxBytes);
1120 + return withText(Math.max(chars, 1));
1121 + };
1122 + const item = longestText(input.row.item.title);
1123 + const title = item.title;
1124 + if (title === null || jsonBytes(item) <= maxBytes) return item;
1125 + // Half the budget for the title keeps `textOffset` pages of the text useful.
1126 + const cutTitle = (chars: number) =>
1127 + title.slice(0, chars === 0 ? 0 : textPageEnd(title, 0, chars));
1128 + const titleChars = longestFitting(
1129 + 1,
1130 + title.length - 1,
1131 + (n) => jsonBytes({ ...item, title: cutTitle(n) }) <= maxBytes / 2,
1132 + );
1133 + return longestText(cutTitle(Math.max(titleChars, 0)));
1134 +}
1135 +
1136 +/**
1137 + * The items, read from the end the caller pages toward, whose result fits
1138 + * THREAD_READ_RESULT_MAX_BYTES; `start` is the first kept index. Never empty for a non-empty page.
1139 + */
1140 +function timelineItemsWithinBudget(
1141 + envelope: Omit<OrchestratorMcpThreadReadResult, "items">,
1142 + inputs: ReadonlyArray<Parameters<typeof timelineItem>[0]>,
1143 + newestFirst: boolean,
1144 +): { readonly items: Array<OrchestratorMcpThreadTimelineItem>; readonly start: number } {
1145 + // An oversized envelope (say, a huge thread title) must not starve items to one char per read.
1146 + const budget = Math.max(
1147 + THREAD_READ_RESULT_MAX_BYTES - jsonBytes({ ...envelope, items: [] }),
1148 + THREAD_READ_RESULT_MAX_BYTES / 2,
1149 + );
1150 + const items: Array<OrchestratorMcpThreadTimelineItem> = [];
1151 + let bytes = 0;
1152 + for (const input of newestFirst ? inputs.toReversed() : inputs) {
1153 + const item = timelineItem(input);
1154 + bytes += jsonBytes(item) + (items.length === 0 ? 0 : 1);
1155 + if (bytes <= budget) {
1156 + items.push(item);
1157 + continue;
1158 + }
1159 + if (items.length === 0) items.push(timelineItemWithin(input, budget));
1160 + break;
1161 + }
1162 + return newestFirst
1163 + ? { items: items.toReversed(), start: inputs.length - items.length }
1164 + : { items, start: 0 };
1165 +}
1166 +
1167 const make = Effect.gen(function* () {
1168 const random = yield* SecureRandom.SecureRandom;
1169 const threadManagement = yield* ThreadManagementService.ThreadManagementService;
@@ -3113,25 +3175,17 @@ const make = Effect.gen(function* () {
3175 .toSorted((left, right) => right.ordinal - left.ordinal)
3176 .slice(0, input.runLimit ?? DEFAULT_THREAD_RUN_LIMIT)
3177 .map((run) => threadRun(target, run));
3116 - const allItems = timeline.items.map((row) =>
3117 - timelineItem({
3178 + const { items, start } = timelineItemsWithinBudget(
3179 + { thread, recentRuns, nextPosition: null, hasMore: false, earlierPosition: null },
3180 + timeline.items.map((row) => ({
3181 row,
3182 maxChars,
3183 messagesByThreadId,
3184 ...(input.itemId === undefined ? {} : { textOffset: input.textOffset ?? 0 }),
3122 - }),
3185 + })),
3186 + newestFirst,
3187 );
3124 - // Keep the end of the page the caller is reading toward, and at least one item.
3125 - let size = encodeJsonText({ thread, recentRuns }).length;
3126 - let kept = 0;
3127 - for (const item of newestFirst ? allItems.toReversed() : allItems) {
3128 - size += encodeJsonText(item).length + 1;
3129 - if (kept > 0 && size > THREAD_READ_BUDGET_CHARS) break;
3130 - kept++;
3131 - }
3132 - const start = newestFirst ? allItems.length - kept : 0;
3133 - const items = allItems.slice(start, start + kept);
3134 - const page = timeline.items.slice(start, start + kept);
3188 + const page = timeline.items.slice(start, start + items.length);
3189 const returnedRunIds = new Set(
3190 page.filter((row) => row.sourceThreadId === target.thread.id).map((row) => row.item.runId),
3191 );
@@ -3149,7 +3203,9 @@ const make = Effect.gen(function* () {
3203 target,
3204 returnedRunIds,
3205 );
3152 - if (parent !== undefined && scope.thread !== undefined && tasks.length > 0) {
3206 + // A read past the end of an item's text shows the agent nothing to acknowledge.
3207 + const readPastEnd = (input.textOffset ?? 0) > 0 && items.every((item) => !item.text);
3208 + if (parent !== undefined && scope.thread !== undefined && tasks.length > 0 && !readPastEnd) {
3209 for (const task of tasks) {
3210 const transfer = taskResultTransfer(parent.thread.id, target, task);
3211 const resultRunId = transfer?.sourcePoint.runId ?? delegatedTaskRun(target, task)?.id;
@@ -3165,11 +3221,9 @@ const make = Effect.gen(function* () {
3221 if (
3222 pageIncludesTerminalTaskResult({
3223 parentThreadId: parent.thread.id,
3168 - page,
3224 + items,
3225 task,
3226 target: { ...target, ...resultRecords },
3171 - maxChars,
3172 - textOffset: input.itemId === undefined ? 0 : (input.textOffset ?? 0),
3227 })
3228 ) {
3229 yield* readTask(
@@ -3187,7 +3241,7 @@ const make = Effect.gen(function* () {
3241 recentRuns,
3242 items,
3243 nextPosition: items.at(-1)?.position ?? null,
3190 - hasMore: timeline.hasMore || (!newestFirst && kept < allItems.length),
3244 + hasMore: timeline.hasMore || (!newestFirst && items.length < timeline.items.length),
3245 earlierPosition: timeline.hasEarlier || start > 0 ? (items[0]?.position ?? null) : null,
3246 } satisfies OrchestratorMcpThreadReadResult;
3247 }),
apps/server/src/mcp/OrchestratorMcpToolkit.integration.test.ts
+4 -6
@@ -81,6 +81,7 @@ const cancellationPrompt = "Remain active until the parent cancels this delegate
81 const queuedFollowupPrompt = "Complete the queued follow-up and return the final result.";
82 const queuedFollowupResult = "Queued delegated follow-up completed.";
83 const decodeThreadRead = Schema.decodeUnknownEffect(OrchestratorMcpThreadReadResult);
84 +const longFollowupResult = "Long delegated follow-up line. ".repeat(1_500);
85
86 const decodeDelegateTaskResult = Schema.decodeUnknownEffect(OrchestratorMcpDelegateTaskResult);
87 const decodeThreadInterruptResult = Schema.decodeUnknownEffect(
@@ -201,11 +202,7 @@ describe("orchestrator MCP toolkit", () => {
202 { label: "distinct", result: queuedFollowupResult, latestSummary: queuedFollowupResult },
203 { label: "identical", result: delegatedResult, latestSummary: null },
204 { label: "emoji", result: "😀", latestSummary: "😀" },
204 - {
205 - label: "paginated",
206 - result: "git safety ".repeat(120),
207 - latestSummary: "git safety ".repeat(120),
208 - },
205 + { label: "long", result: longFollowupResult, latestSummary: longFollowupResult },
206 ])("reports $label child results", ({ result, latestSummary }) =>
207 Effect.gen(function* () {
208 const cwd = yield* checkpointWorkspace("delegated-task-status");
@@ -708,7 +705,7 @@ describe("orchestrator MCP toolkit", () => {
705 {
706 threadId: delegated.childThreadId,
707 limit: 100,
711 - maxCharsPerItem: result === "😀" ? 1 : 20_000,
708 + maxCharsPerItem: result === "😀" ? 1 : 50_000,
709 },
710 { ...invocation, thread: undefined },
711 ).pipe(Effect.withTracer(tracer));
@@ -751,6 +748,7 @@ describe("orchestrator MCP toolkit", () => {
748 threadId: delegated.childThreadId,
749 itemId: finalItem!.itemId,
750 textOffset: nextTextOffset,
751 + maxCharsPerItem: 50_000,
752 }).pipe(Effect.withTracer(tracer));
753 const nextPage = yield* decodeThreadRead(continuation.structuredContent);
754 text += nextPage.items[0]?.text ?? "";