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

main
ts 1,022 lines 34.3 KB
Raw
1 import {
2 MessageId,
3 NodeId,
4 RunId,
5 RuntimeRequestId,
6 ThreadId,
7 TurnItemId,
8 type OrchestrationV2ProjectedTurnItem,
9 type OrchestrationV2TurnItem,
10 } from "@t3tools/contracts";
11 import { describe, expect, it } from "@effect/vitest";
12 import * as DateTime from "effect/DateTime";
13
14 import {
15 buildBoundedThreadProjection,
16 deferWorkHistoryRows,
17 boundedTimelineEncodedBytes,
18 computeLatestLocalTurnOrdinal,
19 decodeThreadHistoryCursor,
20 encodeThreadHistoryCursor,
21 projectedRowBoundedSnapshotEncodedBytes,
22 projectedRowEncodedBytes,
23 selectHistoryPageFromCursor,
24 selectDeferredWorkPage,
25 selectRecentTimelineWindow,
26 THREAD_HISTORY_PAGE_POLICY,
27 } from "./threadHistoryPaging.ts";
28 import { projectThreadProjectionForWire } from "./WireProjection.ts";
29
30 const NOW = DateTime.makeUnsafe("2026-06-20T00:00:00.000Z");
31 const THREAD = ThreadId.make("thread-1");
32 const RUN = RunId.make("run-interrupt-1");
33 const NODE = NodeId.make("node-interrupt-1");
34
35 function makeRow(
36 index: number,
37 options?: { readonly outputBytes?: number },
38 ): OrchestrationV2ProjectedTurnItem {
39 const id = TurnItemId.make(`item-${index}`);
40 const output =
41 options?.outputBytes !== undefined ? "x".repeat(options.outputBytes) : `output-${index}`;
42 return {
43 position: index,
44 visibility: "local",
45 sourceThreadId: THREAD,
46 sourceItemId: id,
47 item: {
48 id,
49 type: "command_execution",
50 threadId: THREAD,
51 runId: null,
52 nodeId: null,
53 providerThreadId: null,
54 providerTurnId: null,
55 nativeItemRef: null,
56 parentItemId: null,
57 ordinal: index + 1,
58 status: "completed",
59 title: `Command ${index}`,
60 input: `cmd-${index}`,
61 output,
62 exitCode: 0,
63 startedAt: NOW,
64 completedAt: NOW,
65 updatedAt: NOW,
66 },
67 };
68 }
69
70 function makeTurnStart(
71 index: number,
72 createdBy: "user" | "agent",
73 ): OrchestrationV2ProjectedTurnItem {
74 const row = makeRow(index);
75 return {
76 ...row,
77 item: {
78 ...row.item,
79 type: "user_message",
80 createdBy,
81 creationSource: "provider",
82 inputIntent: "turn_start",
83 messageId: MessageId.make(`prompt-${index}`),
84 text: `Prompt ${index}`,
85 attachments: [],
86 },
87 } as OrchestrationV2ProjectedTurnItem;
88 }
89
90 function interruptItem(
91 id: string,
92 type: "run_interrupt_request" | "run_interrupt_result",
93 ordinal: number,
94 ): OrchestrationV2TurnItem {
95 return {
96 id: TurnItemId.make(id),
97 type,
98 threadId: THREAD,
99 runId: RUN,
100 nodeId: NODE,
101 providerThreadId: null,
102 providerTurnId: null,
103 nativeItemRef: null,
104 parentItemId: null,
105 ordinal,
106 status: "completed",
107 title: type,
108 message: type === "run_interrupt_request" ? "Stopping" : "Stopped",
109 startedAt: NOW,
110 completedAt: NOW,
111 updatedAt: NOW,
112 } as OrchestrationV2TurnItem;
113 }
114
115 function interruptRow(
116 index: number,
117 type: "run_interrupt_request" | "run_interrupt_result",
118 ): OrchestrationV2ProjectedTurnItem {
119 const item = interruptItem(
120 type === "run_interrupt_request" ? "interrupt-req" : "interrupt-res",
121 type,
122 index + 1,
123 );
124 return {
125 position: index,
126 visibility: "local",
127 sourceThreadId: THREAD,
128 sourceItemId: item.id,
129 item,
130 };
131 }
132
133 function makeProjection(visibleTurnItems: OrchestrationV2ProjectedTurnItem[]) {
134 return {
135 thread: {
136 id: THREAD,
137 projectId: "project-1",
138 title: "Thread",
139 providerInstanceId: "codex",
140 modelSelection: { instanceId: "codex", model: "gpt-5" },
141 runtimeMode: "full-access",
142 interactionMode: "default",
143 branch: null,
144 worktreePath: null,
145 activeProviderThreadId: null,
146 lineage: {
147 parentThreadId: null,
148 relationshipToParent: null,
149 rootThreadId: THREAD,
150 },
151 forkedFrom: null,
152 createdBy: "user",
153 creationSource: "web",
154 createdAt: NOW,
155 updatedAt: NOW,
156 archivedAt: null,
157 deletedAt: null,
158 settledOverride: null,
159 settledAt: null,
160 },
161 runs: [{ id: "run-1" }],
162 attempts: [{ id: "attempt-1" }],
163 nodes: [],
164 subagents: [],
165 providerSessions: [],
166 providerThreads: [],
167 providerTurns: [],
168 runtimeRequests: [{ id: "req-1" }],
169 messages: [],
170 plans: [],
171 turnItems: visibleTurnItems.map((row) => row.item),
172 checkpointScopes: [],
173 checkpoints: [],
174 contextHandoffs: [],
175 contextTransfers: [],
176 visibleTurnItems,
177 updatedAt: NOW,
178 } as unknown as Parameters<typeof buildBoundedThreadProjection>[0]["projection"];
179 }
180
181 describe("threadHistoryPaging", () => {
182 it("defers completed work above 150 items and keeps conversation and persistent rows", () => {
183 const work = Array.from({ length: 151 }, (_, index) => {
184 const row = makeRow(index);
185 return { ...row, item: { ...row.item, runId: RUN, runStatus: "completed" } };
186 });
187 expect(deferWorkHistoryRows(work.slice(0, 150))).toHaveLength(150);
188 const deferredWork = deferWorkHistoryRows(work)[0]!.item.deferredWork!;
189 expect(deferredWork.itemCount).toBe(151);
190 expect(decodeThreadHistoryCursor(deferredWork.cursor).p).toBe(151);
191 const superseded = work.map((row) => ({
192 ...row,
193 item: { ...row.item, runStatus: "running", attemptId: "old", attemptStatus: "superseded" },
194 }));
195 const active = work.map((row, index) => ({
196 ...row,
197 sourceItemId: TurnItemId.make(`active-${index}`),
198 position: row.position + work.length,
199 item: { ...row.item, runStatus: "running", attemptId: "active", attemptStatus: "running" },
200 }));
201 const attempts = deferWorkHistoryRows([...superseded, ...active]);
202 expect(attempts[0]?.item.deferredWork?.itemCount).toBe(151);
203 expect(attempts.slice(1)).toEqual(active);
204 const compaction = {
205 ...work[0]!,
206 sourceItemId: TurnItemId.make("compaction"),
207 item: {
208 ...work[0]!.item,
209 type: "compaction" as const,
210 },
211 };
212 const persistent = {
213 ...work[0]!,
214 sourceItemId: TurnItemId.make("render"),
215 item: {
216 ...work[0]!.item,
217 type: "dynamic_tool" as const,
218 persistentOutput: true,
219 },
220 };
221 const deferred = deferWorkHistoryRows([
222 ...work.slice(0, 30),
223 compaction,
224 persistent,
225 ...work.slice(30),
226 ]);
227 expect(deferred.map((row) => row.sourceItemId)).toEqual(["item-0", "compaction", "render"]);
228 expect(deferred[0]?.item.deferredWork?.itemCount).toBe(151);
229 for (const runStatus of ["running", "failed", "interrupted", "cancelled"]) {
230 expect(
231 deferWorkHistoryRows(work.map((row) => ({ ...row, item: { ...row.item, runStatus } }))),
232 ).toHaveLength(151);
233 }
234 const interrupted = {
235 ...compaction,
236 item: { ...compaction.item, type: "run_interrupt_result" as const },
237 };
238 expect(deferWorkHistoryRows([...work, interrupted])).toHaveLength(152);
239 const failed = {
240 ...compaction,
241 item: {
242 ...compaction.item,
243 type: "error" as const,
244 status: "failed" as const,
245 nodeId: "root-node",
246 parentItemId: null,
247 },
248 };
249 expect(deferWorkHistoryRows([...work, failed])).toHaveLength(152);
250 });
251
252 it("keeps a human turn whole up to the turn row budget and pages a longer one from inside", () => {
253 const humanTurn = (length: number) => {
254 const items = Array.from({ length }, (_, index) => makeRow(index));
255 items[0] = {
256 ...items[0]!,
257 item: {
258 ...items[0]!.item,
259 type: "user_message",
260 createdBy: "user",
261 creationSource: "web",
262 inputIntent: "turn_start",
263 messageId: MessageId.make("long-human-turn"),
264 text: "Continue",
265 attachments: [],
266 },
267 } as OrchestrationV2ProjectedTurnItem;
268 return items;
269 };
270
271 const whole = selectRecentTimelineWindow({ items: humanTurn(180), snapshotSequence: 1 });
272 expect(whole.items).toHaveLength(180);
273 expect(whole.hasMoreHistory).toBe(false);
274
275 const items = humanTurn(THREAD_HISTORY_PAGE_POLICY.maxTurnItems + 100);
276 const recent = selectRecentTimelineWindow({ items, snapshotSequence: 1 });
277 expect(recent.items).toHaveLength(THREAD_HISTORY_PAGE_POLICY.maxItems);
278 const loaded = [...recent.items];
279 let cursor = recent.nextCursor;
280 for (let pages = 0; cursor !== null; pages += 1) {
281 expect(pages).toBeLessThan(items.length);
282 const page = selectHistoryPageFromCursor({ items, cursor, snapshotSequence: 1 });
283 expect(page.items.length).toBeGreaterThan(0);
284 expect(page.items.length).toBeLessThanOrEqual(
285 page.items[0]?.item.type === "user_message"
286 ? THREAD_HISTORY_PAGE_POLICY.maxTurnItems
287 : THREAD_HISTORY_PAGE_POLICY.maxItems,
288 );
289 loaded.unshift(...page.items);
290 cursor = page.nextCursor;
291 }
292 expect(loaded.map((row) => row.sourceItemId)).toEqual(items.map((row) => row.sourceItemId));
293
294 const large = items
295 .slice(0, 12)
296 .map((row) =>
297 row.item.type === "command_execution"
298 ? { ...row, item: { ...row.item, output: "x".repeat(200_000) } }
299 : row,
300 );
301 const bounded = buildBoundedThreadProjection({
302 projection: makeProjection(large),
303 snapshotSequence: 1,
304 });
305 expect(bounded.projection.visibleTurnItems.length).toBeLessThan(large.length);
306 expect(boundedTimelineEncodedBytes(bounded.projection)).toBeLessThanOrEqual(
307 THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes,
308 );
309 });
310
311 it("keeps background turns with user turns, with main's 150-turn fan-out ceiling", () => {
312 const items = Array.from({ length: 161 }, (_, turn) => {
313 const row = makeRow(turn * 2);
314 if (row.item.type !== "command_execution") throw new Error("Expected command fixture");
315 const prompt: OrchestrationV2ProjectedTurnItem = {
316 ...row,
317 item: {
318 ...row.item,
319 type: "user_message",
320 createdBy: turn === 0 ? "user" : "agent",
321 creationSource: "provider",
322 inputIntent: "turn_start",
323 messageId: MessageId.make(`prompt-${turn}`),
324 text: `Prompt ${turn}`,
325 attachments: [],
326 },
327 };
328 return [prompt, makeRow(turn * 2 + 1)];
329 }).flat();
330 const policy = { ...THREAD_HISTORY_PAGE_POLICY, maxItems: 1_000, maxEncodedBytes: 10_000_000 };
331 const first = selectRecentTimelineWindow({ items, snapshotSequence: 1, policy });
332 expect(first.items).toHaveLength(300);
333 expect(first.items[0]?.sourceItemId).toBe("item-22");
334 const older = selectHistoryPageFromCursor({
335 items,
336 cursor: first.nextCursor!,
337 snapshotSequence: 1,
338 policy,
339 });
340 expect(older.items).toHaveLength(22);
341 expect(older.hasMoreHistory).toBe(false);
342 expect([...older.items, ...first.items].map((row) => row.sourceItemId)).toEqual(
343 items.map((row) => row.sourceItemId),
344 );
345 });
346
347 it("counts runs that a notification started toward the 150-turn ceiling", () => {
348 const inRun = (index: number, run: number, item: object = {}) => {
349 const row = makeRow(index);
350 return {
351 ...row,
352 item: { ...row.item, runId: RunId.make(`run-${run}`), ...item },
353 } as OrchestrationV2ProjectedTurnItem;
354 };
355 const notification = (summary: string) => ({
356 type: "notification",
357 source: { kind: "monitor" },
358 outcome: "completed",
359 summary,
360 });
361 const items = Array.from({ length: 161 }, (_, run) => [
362 inRun(run * 4, run),
363 inRun(
364 run * 4 + 1,
365 run,
366 run === 0
367 ? {
368 type: "user_message",
369 createdBy: "user",
370 creationSource: "web",
371 inputIntent: "turn_start",
372 messageId: MessageId.make("prompt-0"),
373 text: "Prompt 0",
374 attachments: [],
375 }
376 : notification(`Wake ${run}`),
377 ),
378 inRun(run * 4 + 2, run, notification(`Steer ${run}`)),
379 inRun(run * 4 + 3, run),
380 ]).flat();
381 const policy = {
382 ...THREAD_HISTORY_PAGE_POLICY,
383 maxItems: 1_000,
384 maxTurnItems: 1_000,
385 maxEncodedBytes: 10_000_000,
386 };
387 const first = selectRecentTimelineWindow({ items, snapshotSequence: 1, policy });
388 expect(first.items).toHaveLength(150 * 4 - 1);
389 expect(first.items[0]?.sourceItemId).toBe(`item-${11 * 4 + 1}`);
390 const older = selectHistoryPageFromCursor({
391 items,
392 cursor: first.nextCursor!,
393 snapshotSequence: 1,
394 policy,
395 });
396 expect([...older.items, ...first.items].map((row) => row.sourceItemId)).toEqual(
397 items.map((row) => row.sourceItemId),
398 );
399
400 // A caller that holds only the newest rows gets the same page when it says what it left
401 // out: a user turn, and run 3, whose late notification is then not a new turn.
402 const late = items.with(402, inRun(402, 3, notification("Late")));
403 const cursor = encodeThreadHistoryCursor({
404 snapshotSequence: 1,
405 sourceThreadId: THREAD,
406 sourceItemId: late.at(-1)!.sourceItemId,
407 position: late.length - 1,
408 });
409 const prefix = { hasUserTurn: true, startedRuns: new Set(["run-3"]) };
410 const whole = selectHistoryPageFromCursor({ items: late, cursor, snapshotSequence: 1, policy });
411 expect(whole.items[0]?.sourceItemId).toBe(`item-${11 * 4 + 1}`);
412 expect(
413 selectHistoryPageFromCursor({
414 items: late.slice(22),
415 cursor,
416 snapshotSequence: 1,
417 policy,
418 prefix,
419 }),
420 ).toEqual({ ...whole, oldestScanned: late[45] });
421 // A part that ends above the page reports its first row, so the caller reads further back.
422 expect(
423 selectHistoryPageFromCursor({
424 items: late.slice(60),
425 cursor,
426 snapshotSequence: 1,
427 policy,
428 prefix,
429 }).oldestScanned,
430 ).toBe(late[60]);
431 });
432
433 it("pages agent-only child transcripts instead of dropping their earlier activity", () => {
434 const commandRows = Array.from({ length: 90 }, (_, index) => makeRow(index + 1));
435 const first = makeRow(0);
436 const prompt = {
437 ...first,
438 item: {
439 ...first.item,
440 type: "user_message" as const,
441 createdBy: "agent" as const,
442 creationSource: "provider" as const,
443 inputIntent: "turn_start" as const,
444 messageId: MessageId.make("child-prompt"),
445 text: "Inspect this project",
446 attachments: [],
447 },
448 } as OrchestrationV2ProjectedTurnItem;
449 const items = [prompt, ...commandRows];
450 const recent = selectRecentTimelineWindow({ items, snapshotSequence: 1 });
451
452 expect(recent.items).toHaveLength(THREAD_HISTORY_PAGE_POLICY.maxItems);
453 expect(recent.hasMoreHistory).toBe(true);
454 const older = selectHistoryPageFromCursor({
455 items,
456 cursor: recent.nextCursor!,
457 snapshotSequence: 1,
458 });
459 expect(older.items[0]?.item.type).toBe("user_message");
460 expect([...older.items, ...recent.items]).toHaveLength(items.length);
461 });
462
463 it("always includes at least one pathological oversized item", () => {
464 for (const humanTurn of [false, true]) {
465 const oversized = makeRow(0, { outputBytes: 2_000_000 });
466 const items = [
467 humanTurn
468 ? ({
469 ...oversized,
470 item: {
471 ...oversized.item,
472 type: "user_message",
473 createdBy: "user",
474 creationSource: "web",
475 inputIntent: "turn_start",
476 messageId: MessageId.make("oversized-human-turn"),
477 text: "x".repeat(2_000_000),
478 attachments: [],
479 },
480 } as OrchestrationV2ProjectedTurnItem)
481 : oversized,
482 makeRow(1, { outputBytes: 10 }),
483 ];
484 const policy = { ...THREAD_HISTORY_PAGE_POLICY, maxItems: 50, maxEncodedBytes: 1_024 };
485 const page = selectRecentTimelineWindow({ items, snapshotSequence: 1, policy });
486 expect(page.items).toHaveLength(1);
487 expect(page.items[0]?.sourceItemId).toBe("item-1");
488 expect(page.hasMoreHistory).toBe(true);
489
490 const older = selectHistoryPageFromCursor({
491 items,
492 cursor: page.nextCursor!,
493 snapshotSequence: 1,
494 policy,
495 });
496 expect(older.items).toHaveLength(1);
497 expect(older.items[0]?.sourceItemId).toBe("item-0");
498 expect(older.hasMoreHistory).toBe(false);
499 expect(older.nextCursor).toBeNull();
500 expect([...older.items, ...page.items].map((row) => row.sourceItemId)).toEqual(
501 items.map((row) => row.sourceItemId),
502 );
503 }
504 });
505
506 it.each([
507 {
508 name: "item ceiling",
509 items: Array.from({ length: 5 }, (_, index) => makeRow(index)),
510 policy: { maxItems: 3, maxEncodedBytes: 1_000 },
511 admitted: 3,
512 measured: 3,
513 },
514 {
515 name: "user turn ceiling",
516 items: [makeRow(0), makeTurnStart(1, "user"), makeRow(2)],
517 policy: { maxUserTurns: 1, maxItems: 100, maxEncodedBytes: 1_000 },
518 admitted: 2,
519 measured: 2,
520 },
521 {
522 name: "raw turn ceiling",
523 items: [
524 makeTurnStart(0, "user"),
525 ...Array.from({ length: 151 }, (_, index) => makeTurnStart(index + 1, "agent")),
526 ],
527 policy: { maxUserTurns: 10, maxItems: 1_000, maxEncodedBytes: 1_000_000 },
528 admitted: 150,
529 measured: 150,
530 },
531 {
532 name: "byte budget, which still admits an exact fit",
533 items: Array.from({ length: 5 }, (_, index) => makeRow(index)),
534 policy: { maxItems: 100, maxEncodedBytes: 20 },
535 admitted: 2,
536 measured: 3,
537 },
538 {
539 name: "byte budget, which still admits an oversized first row",
540 items: Array.from({ length: 5 }, (_, index) => makeRow(index)),
541 policy: { maxItems: 100, maxEncodedBytes: 5 },
542 admitted: 1,
543 measured: 2,
544 },
545 ])("measures only the rows needed to stop at the $name", (testCase) => {
546 const measured: OrchestrationV2ProjectedTurnItem[] = [];
547 const page = selectRecentTimelineWindow({
548 items: testCase.items,
549 snapshotSequence: 1,
550 policy: testCase.policy,
551 rowEncodedBytes: (row) => {
552 measured.push(row);
553 return 10;
554 },
555 });
556
557 expect(page.items.map((row) => row.sourceItemId)).toEqual(
558 testCase.items.slice(-testCase.admitted).map((row) => row.sourceItemId),
559 );
560 expect(measured).toHaveLength(testCase.measured);
561 expect(page.hasMoreHistory).toBe(true);
562 expect(decodeThreadHistoryCursor(page.nextCursor!).si).toBe(page.items[0]?.sourceItemId);
563 });
564
565 it("recovers identity-miss cursors when position is past a shrunken timeline", () => {
566 const items = Array.from({ length: 5 }, (_, index) => makeRow(index));
567 const cursor = encodeThreadHistoryCursor({
568 snapshotSequence: 3,
569 sourceThreadId: THREAD,
570 sourceItemId: TurnItemId.make("item-deleted-long-ago"),
571 position: 40,
572 });
573 const page = selectHistoryPageFromCursor({
574 items,
575 cursor,
576 snapshotSequence: 3,
577 policy: { maxItems: 2, maxEncodedBytes: 10_000_000 },
578 });
579 expect(page.items.map((row) => row.sourceItemId)).toEqual(["item-3", "item-4"]);
580 expect(page.hasMoreHistory).toBe(true);
581 expect(page.nextCursor).not.toBeNull();
582 const sparse = [makeRow(0), makeRow(10), makeRow(20)];
583 const middle = selectHistoryPageFromCursor({
584 items: sparse,
585 cursor: encodeThreadHistoryCursor({
586 snapshotSequence: 3,
587 sourceThreadId: THREAD,
588 sourceItemId: "item-hidden",
589 position: 15,
590 }),
591 snapshotSequence: 3,
592 });
593 expect(middle.items.map((row) => row.sourceItemId)).toEqual(["item-0", "item-10"]);
594 const work = Array.from({ length: 80 }, (_, index) => {
595 const row = makeRow(index);
596 return { ...row, item: { ...row.item, runId: RUN, ordinal: index + 100 } };
597 });
598 const tail = work[75]!;
599 const deferred = selectDeferredWorkPage({
600 items: work.filter((row) => row !== tail).map((row, position) => ({ ...row, position })),
601 cursor: encodeThreadHistoryCursor({
602 snapshotSequence: 3,
603 sourceThreadId: THREAD,
604 sourceItemId: tail.sourceItemId,
605 position: tail.item.ordinal,
606 inclusive: true,
607 }),
608 throughEntryId: work[0]!.sourceItemId,
609 snapshotSequence: 3,
610 });
611 expect(deferred.items.map((row) => row.sourceItemId)).toEqual(
612 work.slice(0, 75).map((row) => row.sourceItemId),
613 );
614 expect(deferred.nextCursor).toBeNull();
615 });
616
617 it("keeps cursor resolution stable when newer items append", () => {
618 const initial = Array.from({ length: 20 }, (_, index) => makeRow(index));
619 const recent = selectRecentTimelineWindow({
620 items: initial,
621 snapshotSequence: 2,
622 policy: { maxItems: 5, maxEncodedBytes: 10_000_000 },
623 });
624 const cursor = recent.nextCursor!;
625 const grown = [...initial, makeRow(20), makeRow(21)];
626 const older = selectHistoryPageFromCursor({
627 items: grown,
628 cursor,
629 snapshotSequence: 5,
630 policy: { maxItems: 5, maxEncodedBytes: 10_000_000 },
631 });
632 expect(older.items.map((row) => row.sourceItemId)).toEqual([
633 "item-10",
634 "item-11",
635 "item-12",
636 "item-13",
637 "item-14",
638 ]);
639 expect(older.hasMoreHistory).toBe(true);
640 });
641
642 it("builds a bounded projection that preserves non-timeline control state", () => {
643 const full = makeProjection(Array.from({ length: 40 }, (_, index) => makeRow(index)));
644 const bounded = buildBoundedThreadProjection({
645 projection: full,
646 snapshotSequence: 7,
647 policy: { maxItems: 5, maxEncodedBytes: 10_000_000 },
648 });
649 expect(bounded.projection.runs).toEqual(full.runs);
650 expect(bounded.projection.runtimeRequests).toEqual(full.runtimeRequests);
651 expect(bounded.projection.attempts).toEqual(full.attempts);
652 expect(bounded.projection.visibleTurnItems).toHaveLength(5);
653 expect(bounded.projection.turnItems).toHaveLength(5);
654 expect(bounded.hasMoreHistory).toBe(true);
655 expect(bounded.historyCursor).not.toBeNull();
656 expect(bounded.projection.visibleTurnItems.map((row) => row.position)).toEqual([0, 1, 2, 3, 4]);
657 expect(bounded.latestLocalTurnOrdinal).toBe(40);
658 expect(computeLatestLocalTurnOrdinal(full.turnItems)).toBe(40);
659 });
660
661 it("carries a full-projection watermark when the bounded window is inherited-only", () => {
662 const localOlder = makeRow(0);
663 const localMid = makeRow(1);
664 const inherited = {
665 ...makeRow(2),
666 visibility: "inherited" as const,
667 sourceThreadId: ThreadId.make("parent-thread"),
668 item: {
669 ...makeRow(2).item,
670 threadId: ThreadId.make("parent-thread"),
671 },
672 };
673 const full = makeProjection([localOlder, localMid, inherited]);
674 const inheritedOnly = {
675 ...full,
676 visibleTurnItems: [inherited],
677 turnItems: [localOlder.item, localMid.item],
678 };
679 const bounded = buildBoundedThreadProjection({
680 projection: inheritedOnly,
681 snapshotSequence: 2,
682 policy: { maxItems: 1, maxEncodedBytes: 10_000_000 },
683 });
684 expect(bounded.projection.visibleTurnItems.map((row) => String(row.sourceItemId))).toEqual([
685 String(inherited.sourceItemId),
686 ]);
687 expect(bounded.latestLocalTurnOrdinal).toBe(2);
688 expect(computeLatestLocalTurnOrdinal([])).toBeNull();
689 });
690
691 it("retains an out-of-window run_interrupt_request needed by a visible result", () => {
692 const request = interruptRow(0, "run_interrupt_request");
693 const filler = makeRow(1);
694 const result = interruptRow(2, "run_interrupt_result");
695 const full = makeProjection([request, filler, result]);
696 const bounded = buildBoundedThreadProjection({
697 projection: full,
698 snapshotSequence: 3,
699 policy: { maxItems: 1, maxEncodedBytes: 10_000_000 },
700 });
701
702 expect(bounded.projection.visibleTurnItems.map((row) => String(row.sourceItemId))).toEqual([
703 "interrupt-res",
704 ]);
705 expect(bounded.projection.turnItems.map((item) => String(item.id)).sort()).toEqual([
706 "interrupt-req",
707 "interrupt-res",
708 ]);
709 expect(bounded.hasMoreHistory).toBe(true);
710 });
711
712 it("charges local row.item duplication when measuring bounded timeline bytes", () => {
713 const rows = Array.from({ length: 8 }, (_, index) => makeRow(index, { outputBytes: 2_000 }));
714 const full = makeProjection(rows);
715 const maxEncodedBytes = 12_000;
716 const bounded = buildBoundedThreadProjection({
717 projection: full,
718 snapshotSequence: 1,
719 policy: { maxItems: 50, maxEncodedBytes },
720 });
721
722 const contribution = boundedTimelineEncodedBytes({
723 visibleTurnItems: bounded.projection.visibleTurnItems,
724 turnItems: bounded.projection.turnItems,
725 });
726 expect(contribution).toBeLessThanOrEqual(maxEncodedBytes);
727 expect(bounded.projection.visibleTurnItems.length).toBeGreaterThan(0);
728 expect(bounded.projection.visibleTurnItems.length).toBeLessThan(rows.length);
729
730 const historyPage = selectRecentTimelineWindow({
731 items: rows,
732 snapshotSequence: 1,
733 policy: { maxItems: 50, maxEncodedBytes },
734 });
735 const historyBytes = historyPage.items.reduce(
736 (sum, row) => sum + projectedRowEncodedBytes(row),
737 0,
738 );
739 expect(historyBytes).toBeLessThanOrEqual(maxEncodedBytes);
740 expect(historyPage.items.length).toBeGreaterThan(bounded.projection.visibleTurnItems.length);
741
742 const sample = rows[0]!;
743 expect(projectedRowBoundedSnapshotEncodedBytes(sample, THREAD)).toBeGreaterThan(
744 projectedRowEncodedBytes(sample),
745 );
746 });
747
748 it("does not carry the full duplicated message table into a bounded snapshot", () => {
749 const projection = makeProjection(Array.from({ length: 120 }, (_, index) => makeRow(index)));
750 const full = {
751 ...projection,
752 messages: Array.from({ length: 2_000 }, (_, index) => ({
753 id: MessageId.make(`message-${index}`),
754 threadId: THREAD,
755 runId: RunId.make(`old-run-${index}`),
756 nodeId: null,
757 role: "assistant" as const,
758 text: "x".repeat(1_000),
759 attachments: [],
760 streaming: false,
761 createdBy: "agent" as const,
762 creationSource: "provider" as const,
763 createdAt: NOW,
764 updatedAt: NOW,
765 })),
766 } as typeof projection;
767
768 const bounded = buildBoundedThreadProjection({
769 projection: full,
770 snapshotSequence: 9,
771 });
772
773 expect(bounded.projection.messages).toEqual([]);
774 expect(Buffer.byteLength(JSON.stringify(bounded.projection), "utf8")).toBeLessThan(
775 THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes + 100_000,
776 );
777 });
778
779 it("keeps a workflow coordinator's script outside the bounded window", () => {
780 const projection = makeProjection(Array.from({ length: 120 }, (_, index) => makeRow(index)));
781 const message = (index: number, workflowScript?: boolean) => ({
782 id: MessageId.make(`message-${index}`),
783 threadId: THREAD,
784 runId: RunId.make(`old-run-${index}`),
785 nodeId: null,
786 role: "user" as const,
787 text: `message ${index}`,
788 attachments: [],
789 streaming: false,
790 createdBy: "agent" as const,
791 creationSource: "provider" as const,
792 createdAt: NOW,
793 updatedAt: NOW,
794 ...(workflowScript === undefined ? {} : { workflowScript }),
795 });
796 const full = {
797 ...projection,
798 messages: [message(0, true), message(1, false), message(2)],
799 } as typeof projection;
800
801 const bounded = buildBoundedThreadProjection({ projection: full, snapshotSequence: 9 });
802
803 expect(bounded.projection.messages.map((retained) => retained.id)).toEqual([
804 MessageId.make("message-0"),
805 ]);
806 });
807
808 it("omits historical control details that remain available from history items", () => {
809 const projection = makeProjection(Array.from({ length: 200 }, (_, index) => makeRow(index)));
810 const populated = {
811 ...projection,
812 plans: Array.from({ length: 120 }, (_, index) => ({
813 id: `plan-${index}`,
814 threadId: THREAD,
815 runId: null,
816 nodeId: `node-${index}`,
817 status: "completed",
818 kind: "proposed_plan",
819 markdown: "p".repeat(2_097_152),
820 })),
821 contextHandoffs: Array.from({ length: 120 }, (_, index) => ({
822 id: `handoff-${index}`,
823 threadId: THREAD,
824 targetRunId: "run-1",
825 fromProviderThreadIds: [],
826 toProviderThreadId: "provider-thread-1",
827 coveredRunOrdinals: { from: 1, to: 1 },
828 strategy: "manual_context",
829 status: "superseded",
830 summaryMessageId: null,
831 summaryText: "h".repeat(2_097_152),
832 createdByProviderInstanceId: null,
833 createdAt: NOW,
834 updatedAt: NOW,
835 })),
836 } as unknown as typeof projection;
837
838 const bounded = buildBoundedThreadProjection({
839 projection: projectThreadProjectionForWire(populated),
840 snapshotSequence: 9,
841 });
842 const serializedBytes = Buffer.byteLength(JSON.stringify(bounded.projection), "utf8");
843
844 expect(serializedBytes).toBeLessThanOrEqual(THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes);
845 expect(bounded.projection.plans).toEqual([]);
846 expect(bounded.projection.contextHandoffs).toEqual([]);
847 expect(populated.plans).toHaveLength(120);
848 expect(
849 populated.plans[0]?.kind === "proposed_plan" ? populated.plans[0].markdown.length : 0,
850 ).toBe(2_097_152);
851 });
852
853 it.each([40_000, 80_000])(
854 "reserves pending question cards before visible history: %s bytes",
855 (questionBytes) => {
856 const rows = Array.from({ length: 20 }, (_, index) =>
857 makeRow(index + 1, { outputBytes: 1_500 }),
858 );
859 const requestId = RuntimeRequestId.make("pending-question");
860 const card: OrchestrationV2TurnItem = {
861 id: TurnItemId.make("pending-question-card"),
862 type: "user_input_request",
863 threadId: THREAD,
864 runId: null,
865 nodeId: NODE,
866 providerThreadId: null,
867 providerTurnId: null,
868 nativeItemRef: null,
869 parentItemId: null,
870 ordinal: 1,
871 status: "completed",
872 title: null,
873 requestId,
874 responseMode: "message",
875 questions: [
876 { id: "scope", header: "Scope", question: "q".repeat(questionBytes), options: [] },
877 ],
878 startedAt: NOW,
879 completedAt: NOW,
880 updatedAt: NOW,
881 };
882 const projection = {
883 ...makeProjection(rows),
884 turnItems: [card, ...rows.map((row) => row.item)],
885 runtimeRequests: [
886 {
887 id: requestId,
888 nodeId: NODE,
889 providerTurnId: null,
890 nativeRequestRef: null,
891 kind: "user_input" as const,
892 status: "pending" as const,
893 responseCapability: { type: "message" as const },
894 createdAt: NOW,
895 resolvedAt: null,
896 },
897 ],
898 };
899 const policy = { ...THREAD_HISTORY_PAGE_POLICY, maxEncodedBytes: 64_000 };
900
901 const bounded = buildBoundedThreadProjection({ projection, snapshotSequence: 9, policy });
902
903 expect(bounded.projection.turnItems).toContain(card);
904 expect(bounded.projection.visibleTurnItems.length).toBeGreaterThan(0);
905 expect(bounded.hasMoreHistory).toBe(true);
906 if (questionBytes < policy.maxEncodedBytes) {
907 expect(Buffer.byteLength(JSON.stringify(bounded.projection), "utf8")).toBeLessThanOrEqual(
908 policy.maxEncodedBytes,
909 );
910 } else {
911 expect(bounded.projection.visibleTurnItems).toHaveLength(1);
912 }
913 },
914 );
915
916 it("preserves oversized actionable state", () => {
917 const projection = makeProjection([makeRow(0)]);
918 const actionable = {
919 ...projection,
920 plans: [
921 {
922 id: "plan-actionable",
923 threadId: THREAD,
924 runId: null,
925 nodeId: "node-actionable",
926 status: "active",
927 kind: "proposed_plan",
928 markdown: "a".repeat(2_097_152),
929 },
930 ],
931 } as unknown as typeof projection;
932
933 const bounded = buildBoundedThreadProjection({ projection: actionable, snapshotSequence: 9 });
934
935 expect(bounded.projection.plans[0]).toEqual(actionable.plans[0]);
936 expect(bounded.projection.visibleTurnItems).toEqual(actionable.visibleTurnItems);
937 });
938
939 it.each([false, true])(
940 "keeps agent-only turns visible when checkpoint file lists fill the byte budget (stored interrupt request: %s)",
941 (withInterruptRequest) => {
942 const items = Array.from({ length: 3 }, (_, turn) => {
943 const first = makeRow(turn * 5);
944 const prompt = {
945 ...first,
946 item: {
947 ...first.item,
948 type: "user_message" as const,
949 createdBy: "agent" as const,
950 creationSource: "provider" as const,
951 inputIntent: "turn_start" as const,
952 messageId: MessageId.make(`agent-prompt-${turn}`),
953 text: `Step ${turn}`,
954 attachments: [],
955 },
956 } as OrchestrationV2ProjectedTurnItem;
957 return [prompt, ...Array.from({ length: 4 }, (_, index) => makeRow(turn * 5 + index + 1))];
958 }).flat();
959 const files = Array.from(
960 { length: 15_000 },
961 (_, index) =>
962 `work/ws-${index % 40}/.jj/repo/store/extra/${index.toString(16).padStart(40, "0")}`,
963 );
964 const base = makeProjection(items);
965 const projection = {
966 ...base,
967 turnItems: withInterruptRequest
968 ? [interruptItem("old-interrupt-req", "run_interrupt_request", 0), ...base.turnItems]
969 : base.turnItems,
970 checkpoints: [{ id: "checkpoint-1", files }],
971 } as unknown as ReturnType<typeof makeProjection>;
972
973 const bounded = buildBoundedThreadProjection({ projection, snapshotSequence: 1 });
974
975 expect(bounded.projection.visibleTurnItems).toHaveLength(items.length);
976 expect(bounded.hasMoreHistory).toBe(false);
977 },
978 );
979
980 it("keeps paged historical plan detail in the turn item and only status in its artifact", () => {
981 const detail = "Implement the historical plan exactly.\n".repeat(1_000);
982 const item = {
983 ...makeRow(0).item,
984 type: "proposed_plan",
985 planId: "plan-historical-visible",
986 markdown: detail,
987 streaming: false,
988 } as OrchestrationV2TurnItem;
989 const row = {
990 ...makeRow(0),
991 sourceItemId: item.id,
992 item,
993 } as OrchestrationV2ProjectedTurnItem;
994 const base = makeProjection([row]);
995 const projection = {
996 ...base,
997 plans: [
998 {
999 id: "plan-historical-visible",
1000 threadId: THREAD,
1001 runId: null,
1002 nodeId: "node-historical-visible",
1003 status: "completed",
1004 kind: "proposed_plan",
1005 markdown: detail,
1006 },
1007 ],
1008 } as unknown as typeof base;
1009
1010 const bounded = buildBoundedThreadProjection({ projection, snapshotSequence: 9 });
1011
1012 expect(bounded.projection.visibleTurnItems[0]?.item).toMatchObject({
1013 type: "proposed_plan",
1014 markdown: detail,
1015 });
1016 expect(bounded.projection.plans[0]).toMatchObject({
1017 status: "completed",
1018 markdown: "",
1019 detailInTurnItem: true,
1020 });
1021 });
1022 });