Skip to content

Commit bb8d84c

Browse files
fix(server): keep cursorless t3_thread_read oldest-first and make newest an opt-in
Older linked environments, older CLIs and the context-handoff hint all read without a cursor and page forward with hasMore. Changing that default broke them, so newest-first now needs latest=true. The response budget and beforePosition stay. The CLI and RemoteDelegation go back to main's forward paging, which works against old and new servers. AI-assisted; verified with the tests and tools listed above.
1 parent a58b40d commit bb8d84c

10 files changed

Lines changed: 111 additions & 98 deletions

File tree

‎apps/server/src/cli/thread.test.ts‎

Lines changed: 7 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -376,36 +376,23 @@ const timelineTools = (types: ReadonlyArray<string>) => {
376376
const items = types.map((type, position) => ({ position, itemId: `item-${position}`, type }));
377377
const served: Array<number> = [];
378378
const call = ((_tool: string, input: unknown) => {
379-
const args = input as {
380-
readonly afterPosition?: number;
381-
readonly beforePosition?: number;
382-
readonly limit: number;
383-
};
384-
const forward = args.afterPosition !== undefined;
385-
const isMatch = (item: (typeof items)[number]) =>
386-
["user_message", "assistant_message", "proposed_plan"].includes(item.type);
379+
const args = input as { readonly afterPosition?: number; readonly limit: number };
387380
// Scanning one match past the page keeps reads of huge fixtures linear.
388381
const matching: typeof items = [];
389-
if (forward) {
390-
for (let position = args.afterPosition! + 1; position < items.length; position++) {
391-
if (isMatch(items[position]!)) matching.push(items[position]!);
392-
if (matching.length > args.limit) break;
393-
}
394-
} else {
395-
for (let position = (args.beforePosition ?? items.length) - 1; position >= 0; position--) {
396-
if (isMatch(items[position]!)) matching.unshift(items[position]!);
382+
for (let position = (args.afterPosition ?? -1) + 1; position < items.length; position++) {
383+
const item = items[position]!;
384+
if (["user_message", "assistant_message", "proposed_plan"].includes(item.type)) {
385+
matching.push(item);
397386
if (matching.length > args.limit) break;
398387
}
399388
}
400-
const page = forward ? matching.slice(0, args.limit) : matching.slice(-args.limit);
401-
const more = matching.length > page.length;
389+
const page = matching.slice(0, args.limit);
402390
served.push(page.length);
403391
return Effect.succeed({
404392
thread: { itemCount: items.length },
405393
items: page,
406394
nextPosition: page.at(-1)?.position ?? null,
407-
hasMore: forward && more,
408-
earlierPosition: !forward && more ? (page[0]?.position ?? null) : null,
395+
hasMore: matching.length > page.length,
409396
});
410397
}) as ThreadTools["call"];
411398
const latest = (count: number) =>

‎apps/server/src/cli/thread.ts‎

Lines changed: 59 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -385,52 +385,81 @@ const readTimeline = Effect.fn("cli.thread.readTimeline")(function* (
385385
view: "messages" | "activity",
386386
) {
387387
const items: Array<OrchestratorMcpThreadTimelineItem> = [];
388-
let afterPosition = -1;
388+
let afterPosition: number | undefined;
389389
let page: OrchestratorMcpThreadReadResult;
390390
do {
391391
page = yield* tools.call(
392392
"t3_thread_read",
393-
{ threadId, view, limit: READ_PAGE_LIMIT, runLimit: 1, afterPosition },
393+
{
394+
threadId,
395+
view,
396+
limit: READ_PAGE_LIMIT,
397+
runLimit: 1,
398+
...(afterPosition === undefined ? {} : { afterPosition }),
399+
},
394400
OrchestratorMcpThreadReadResult,
395401
);
396402
items.push(...page.items);
397-
afterPosition = page.nextPosition ?? -1;
398-
} while (page.hasMore && page.nextPosition !== null);
403+
afterPosition = page.nextPosition ?? undefined;
404+
} while (page.hasMore && afterPosition !== undefined);
399405
return { thread: page.thread, items };
400406
});
401407

402-
/** The latest `count` user and assistant messages, oldest first, read backward from the end. */
408+
/**
409+
* The latest `count` user and assistant messages, oldest first. Positions
410+
* count every timeline item, so the read starts near the end and widens
411+
* backward only while tool and plan items leave too few messages.
412+
*/
403413
export const readLatestMessages = Effect.fn("cli.thread.readLatestMessages")(function* (
404414
tools: ThreadTools,
405415
threadId: ThreadId,
406416
count: number,
407417
) {
408-
const pages: Array<ReadonlyArray<OrchestratorMcpThreadTimelineItem>> = [];
409-
let found = 0;
410-
let beforePosition: number | null = null;
411-
let page: OrchestratorMcpThreadReadResult;
418+
let { thread } = yield* tools.call(
419+
"t3_thread_read",
420+
{ threadId, limit: 1, runLimit: 1 },
421+
OrchestratorMcpThreadReadResult,
422+
);
423+
let messages: Array<OrchestratorMcpThreadTimelineItem> = [];
424+
// The newest window has no upper bound, so items added since the first
425+
// read are still shown.
426+
let before: number | undefined;
427+
let start = thread.itemCount;
428+
let span = Math.max(count, READ_PAGE_LIMIT);
412429
do {
413-
page = yield* tools.call(
414-
"t3_thread_read",
415-
{
416-
threadId,
417-
view: "messages",
418-
limit: Math.min(count, READ_PAGE_LIMIT),
419-
runLimit: 1,
420-
...(beforePosition === null ? {} : { beforePosition }),
421-
},
422-
OrchestratorMcpThreadReadResult,
423-
);
424-
const messages = page.items.filter(
425-
(item) => item.type === "user_message" || item.type === "assistant_message",
426-
);
427-
pages.push(messages);
428-
found += messages.length;
429-
beforePosition = page.earlierPosition ?? null;
430-
} while (found < count && beforePosition !== null);
431-
// `flat` because the whole --messages count is too many to spread as arguments.
432-
const messages = pages.toReversed().flat();
433-
return { thread: page.thread, messages: messages.slice(Math.max(0, messages.length - count)) };
430+
const end = before;
431+
start = Math.max(0, start - span);
432+
const window: Array<OrchestratorMcpThreadTimelineItem> = [];
433+
let afterPosition = start - 1;
434+
let page: OrchestratorMcpThreadReadResult;
435+
do {
436+
page = yield* tools.call(
437+
"t3_thread_read",
438+
{
439+
threadId,
440+
view: "messages",
441+
limit: READ_PAGE_LIMIT,
442+
runLimit: 1,
443+
...(afterPosition < 0 ? {} : { afterPosition }),
444+
},
445+
OrchestratorMcpThreadReadResult,
446+
);
447+
window.push(
448+
...page.items.filter(
449+
(item) =>
450+
(item.type === "user_message" || item.type === "assistant_message") &&
451+
(end === undefined || item.position < end),
452+
),
453+
);
454+
afterPosition = page.nextPosition ?? Number.POSITIVE_INFINITY;
455+
} while (page.hasMore && afterPosition < (end ?? Number.POSITIVE_INFINITY) - 1);
456+
thread = page.thread;
457+
// A window can hold the whole --messages count, too many to spread as arguments.
458+
messages = window.concat(messages);
459+
before = start;
460+
span *= 2;
461+
} while (messages.length < count && start > 0);
462+
return { thread, messages: messages.slice(Math.max(0, messages.length - count)) };
434463
});
435464

436465
/** Item text past the read's per-item cap. */

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

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -419,22 +419,29 @@ it("readThread returns the newest items that fit the response budget", async ()
419419

420420
await Effect.gen(function* () {
421421
const service = yield* OrchestratorMcpService.OrchestratorMcpService;
422-
const result = yield* service.readThread(makeScope(), {
422+
const read = {
423423
threadId: parentThreadId,
424-
view: "activity",
424+
view: "activity" as const,
425425
limit: 100,
426426
maxCharsPerItem: 1_500,
427-
});
427+
};
428+
const result = yield* service.readThread(makeScope(), { ...read, latest: true });
429+
// Older linked environments read without a cursor and follow only hasMore.
430+
const first = yield* service.readThread(makeScope(), read);
428431

429432
expect(pageOptions).toEqual([
430433
{ beforePosition: Number.POSITIVE_INFINITY, limit: 100, view: "activity" },
434+
{ limit: 100, view: "activity" },
431435
]);
432436
// Claude Code saves results over ~50k chars of this JSON to a file instead of showing them.
433437
expect(JSON.stringify(result).length).toBeLessThan(31_000);
434438
expect(result.items.length).toBeLessThan(100);
435439
expect(result.items.at(-1)?.position).toBe(99);
436440
expect(result.earlierPosition).toBe(result.items[0]?.position);
437441
expect(result.hasMore).toBe(false);
442+
expect(first.items[0]?.position).toBe(0);
443+
expect(first.hasMore).toBe(true);
444+
expect(first.nextPosition).toBe(first.items.at(-1)?.position);
438445
}).pipe(Effect.provide(layer), Effect.runPromise);
439446
});
440447

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3042,8 +3042,10 @@ const make = Effect.gen(function* () {
30423042
const view = input.view ?? "messages";
30433043
const limit = input.limit ?? DEFAULT_THREAD_READ_LIMIT;
30443044
const maxChars = input.maxCharsPerItem ?? DEFAULT_THREAD_ITEM_MAX_CHARS;
3045-
// Without a cursor, a read returns the newest items, which is what callers usually want.
3046-
const newestFirst = input.afterPosition === undefined || input.beforePosition !== undefined;
3045+
// Cursorless reads stay oldest-first: older linked environments page forward from them.
3046+
const newestFirst =
3047+
input.beforePosition !== undefined ||
3048+
(input.latest === true && input.afterPosition === undefined);
30473049
const timeline = yield* threadManagement
30483050
.getTimelinePage(input.threadId, {
30493051
...(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. Returns the newest items, cut to fit about 30k chars. Older: `beforePosition=earlierPosition`. Newer than a read: `afterPosition=nextPosition` while `hasMore`. From the start: `afterPosition=-1`. 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. 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.",
249249
parameters: OrchestratorMcpThreadReadInput,
250250
success: OrchestratorMcpThreadReadResult,
251251
failure: OrchestratorMcpFailure,

‎apps/server/src/peer/RemoteDelegation.test.ts‎

Lines changed: 4 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -429,12 +429,9 @@ const boxToolkitLayer = (thread: BoxThread) => {
429429
(entry) => options.view === "activity" || entry.type === "assistant_message",
430430
)
431431
: replies.filter((entry) => entry.id === options.itemId);
432-
const before = options.beforePosition ?? Number.POSITIVE_INFINITY;
433-
const inRange = visible.filter(
434-
(entry) => entry.position > (options.afterPosition ?? -1) && entry.position < before,
435-
);
436-
const matching =
437-
options.beforePosition === undefined ? inRange.slice(0, 1) : inRange.slice(-1);
432+
const matching = visible
433+
.filter((entry) => entry.position > (options.afterPosition ?? -1))
434+
.slice(0, 1);
438435
return {
439436
items: matching.map(({ id, runId: itemRunId, text, position, type }) => ({
440437
position,
@@ -471,10 +468,7 @@ const boxToolkitLayer = (thread: BoxThread) => {
471468
options.itemId === undefined &&
472469
matching.length > 0 &&
473470
visible.some((entry) => entry.position > matching.at(-1)!.position),
474-
hasEarlier:
475-
options.itemId === undefined &&
476-
matching.length > 0 &&
477-
visible.some((entry) => entry.position < matching[0]!.position),
471+
hasEarlier: false,
478472
};
479473
}),
480474
interruptThread: (input) =>

‎apps/server/src/peer/RemoteDelegation.ts‎

Lines changed: 12 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -605,38 +605,29 @@ const make = Effect.gen(function* () {
605605
) {
606606
let reply: OrchestratorMcpThreadTimelineItem | undefined;
607607
let error: OrchestratorMcpThreadTimelineItem | undefined;
608-
let cursor: { readonly afterPosition?: number; readonly beforePosition?: number } = {};
608+
let afterPosition: number | undefined;
609609
let run: OrchestratorMcpThreadRun | undefined;
610610
while (true) {
611611
const read = yield* forwarding.readThread(scope, remote.environmentId, {
612612
threadId: remote.threadId,
613613
view: failed ? "activity" : "messages",
614614
limit: 100,
615615
runLimit: 50,
616-
...cursor,
616+
...(afterPosition === undefined ? {} : { afterPosition }),
617617
});
618618
run ??= read.recentRuns.find((candidate) => candidate.runId === runId);
619-
const pageReply = read.items.findLast(
620-
(item) => item.type === "assistant_message" && (runId === null || item.runId === runId),
621-
);
622-
const pageError = failed
623-
? read.items.findLast(
619+
reply =
620+
read.items.findLast(
621+
(item) => item.type === "assistant_message" && (runId === null || item.runId === runId),
622+
) ?? reply;
623+
if (failed) {
624+
error =
625+
read.items.findLast(
624626
(item) => item.type === "error" && (runId === null || item.runId === runId),
625-
)
626-
: undefined;
627-
// Older peers omit earlierPosition and page forward from the start; newer ones start at
628-
// the newest page, so the first match found reading backward is the latest.
629-
if (read.earlierPosition === undefined) {
630-
reply = pageReply ?? reply;
631-
error = pageError ?? error;
632-
if (!read.hasMore || read.nextPosition === null) break;
633-
cursor = { afterPosition: read.nextPosition };
634-
} else {
635-
reply ??= pageReply;
636-
error ??= pageError;
637-
if ((failed ? error : reply) !== undefined || read.earlierPosition === null) break;
638-
cursor = { beforePosition: read.earlierPosition };
627+
) ?? error;
639628
}
629+
if (!read.hasMore || read.nextPosition === null) break;
630+
afterPosition = read.nextPosition;
640631
}
641632
reply = error ?? reply;
642633
if (reply === undefined) return undefined;
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": 48384
4+
"mcpToolListJsonBytes": 48404
55
}

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

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -400,13 +400,15 @@ 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 returns
404-
the newest items. `beforePosition=earlierPosition` reads older items, and
405-
`afterPosition=nextPosition` reads newer ones; `afterPosition=-1` starts at the
406-
first item. The server stops adding items once the result reaches about 30,000
407-
characters and reports the rest through `earlierPosition` or `hasMore`.
408-
Claude Code saves MCP results over its token limit to a file instead of showing
409-
them, so a read has to fit whatever `limit` an agent asks for.
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
408+
server stops adding items once the result reaches about 30,000 characters and
409+
reports the rest through `earlierPosition` or `hasMore`. Claude Code saves MCP
410+
results over its token limit to a file instead of showing them, so a read has
411+
to fit whatever `limit` an agent asks for.
410412

411413
Thread and message results include required `createdBy` and `creationSource`
412414
provenance. MCP-created threads and user-role messages use `createdBy: "agent"`

‎packages/contracts/src/orchestratorMcp.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -421,12 +421,13 @@ export const OrchestratorMcpThreadReadInput = Schema.Struct({
421421
itemId: Schema.optional(TurnItemId),
422422
textOffset: Schema.optional(NonNegativeInt),
423423
view: Schema.optional(Schema.Literals(["messages", "activity"])),
424-
afterPosition: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(-1))).annotate({
425-
description: "Read forward from here. -1 reads from the start.",
426-
}),
424+
afterPosition: Schema.optional(NonNegativeInt),
427425
beforePosition: Schema.optional(NonNegativeInt).annotate({
428426
description: "Read backward from here.",
429427
}),
428+
latest: Schema.optional(Schema.Boolean).annotate({
429+
description: "Without a cursor, read the newest items instead of the oldest.",
430+
}),
430431
limit: Schema.optional(clampedPositiveInt(100)).annotate({
431432
description: "Max items, 1 to 100.",
432433
}),

0 commit comments

Comments
 (0)