The best way to control Claude Code, Codex and more from any computer or phone
fix(server): long agent turns no longer load whole when a thread opens (#24589)
Co-authored-by: luke2x <97411838+luke2x@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 24, 2026 at 16:54 UTC
553203c57b780cef9fb30ad835d759befe0dcb7c
18 files changed
+864
-240
apps/server/integration/TransferBudgetReport.integration.ts
+51
@@ -11,11 +11,17 @@ import {
11
TRANSFER_MEASURED_MCP_RESULT_BYTES,
12
TRANSFER_MEASURED_TOOLS,
13
} from "./fixtures/transferBudget.ts";
14
+import { LONG_TURN_WORK_ROWS } from "./TransferBudgetV2Fixture.integration.ts";
15
16
export interface WebSocketCatchUpMeasurement extends WebSocketTransferTotals {
17
readonly mode: "replay" | "snapshot";
18
}
19
20
+export interface TimelineHttpMeasurement {
21
+ readonly http: HttpTransferMeasurement;
22
+ readonly rows: number;
23
+}
24
+
25
export interface TransferBudgetRun {
26
readonly provider: ProviderDriverKind;
27
readonly threadSnapshot: HttpTransferMeasurement;
@@ -27,6 +33,9 @@ export interface TransferBudgetRun {
33
readonly reconnectShell: WebSocketCatchUpMeasurement;
34
readonly measuredTurnSqlStatements: number;
35
readonly reconnectSqlStatements: number;
36
+ /** The compact bounded snapshot web and mobile load when the long-turn thread opens. */
37
+ readonly longTurnColdOpen: TimelineHttpMeasurement;
38
+ readonly longTurnHistoryPage: TimelineHttpMeasurement;
39
}
40
41
interface ProviderTransferBudget {
@@ -50,6 +59,15 @@ const TRANSFER_BUDGETS: Readonly<Record<string, ProviderTransferBudget>> = {
59
claudeAgent: TRANSFER_BUDGET,
60
};
61
62
+// Decoded bytes, not wire bytes: phones parse and keep the decoded JSON. About
63
+// 30% above the observed 92 KB; without row budgets inside user turns the cold
64
+// open carried all 920 rows (1.07 MB). Kept apart from TRANSFER_BUDGET because
65
+// the PR comment validates that object's keys.
66
+const LONG_TURN_BUDGET = {
67
+ decodedBytes: 120_000,
68
+ rows: 75,
69
+};
70
+
71
function totalWireBytes(run: TransferBudgetRun): number {
72
return run.threadSnapshot.wireBytes + run.measuredTurnWebSocket.wireBytes;
73
}
@@ -144,6 +162,24 @@ function webSocketRows(
162
];
163
}
164
165
+function longTurnRows(
166
+ provider: ProviderDriverKind,
167
+ phase: string,
168
+ measured: TimelineHttpMeasurement,
169
+): string[] {
170
+ return [
171
+ infoRow(provider, phase, "HTTP wire", measured.http.wireBytes),
172
+ row(
173
+ provider,
174
+ phase,
175
+ "HTTP decoded",
176
+ measured.http.decodedBodyBytes,
177
+ LONG_TURN_BUDGET.decodedBytes,
178
+ ),
179
+ row(provider, phase, "rows", measured.rows, LONG_TURN_BUDGET.rows, String),
180
+ ];
181
+}
182
+
183
export function transferBudgetViolations(runs: ReadonlyArray<TransferBudgetRun>): string[] {
184
const violations: string[] = [];
185
for (const run of runs) {
@@ -170,6 +206,18 @@ export function transferBudgetViolations(runs: ReadonlyArray<TransferBudgetRun>)
206
run.measuredTurnWebSocket.messages,
207
budget.measuredTurnWebSocketMessages,
208
],
209
+ [
210
+ "long-turn cold open decoded bytes",
211
+ run.longTurnColdOpen.http.decodedBodyBytes,
212
+ LONG_TURN_BUDGET.decodedBytes,
213
+ ],
214
+ ["long-turn cold open rows", run.longTurnColdOpen.rows, LONG_TURN_BUDGET.rows],
215
+ [
216
+ "long-turn history page decoded bytes",
217
+ run.longTurnHistoryPage.http.decodedBodyBytes,
218
+ LONG_TURN_BUDGET.decodedBytes,
219
+ ],
220
+ ["long-turn history page rows", run.longTurnHistoryPage.rows, LONG_TURN_BUDGET.rows],
221
] as const;
222
for (const [metric, observed, maximum] of checks) {
223
if (observed > maximum) {
@@ -187,6 +235,7 @@ export function formatTransferBudgetReport(runs: ReadonlyArray<TransferBudgetRun
235
"Wire values are thread data bytes read from local HTTP and WebSocket sockets. HTTP includes response headers; WebSocket measurement starts after the resumed thread subscription synchronizes. TCP/IP, TLS framing, and the WebSocket upgrade are excluded. WebSocket permessage-deflate is negotiated.",
236
"The measured turn is observed on three sockets at once: one with only the thread subscription (the capped rows), one with only the shell subscription, and a second client holding both. Server egress is the sum of the three. After the turn the second client disconnects and new sockets resubscribe from the cursor it held before the turn, which is the cursor a backgrounded phone would hold. SQL statements are the SQL client's per-statement spans, counted across V2 persistence and the HTTP/WebSocket handlers.",
237
`Scenario: ${TRANSFER_HISTORY_TURN_COUNT} historical turns with ${TRANSFER_HISTORY_TOOLS_PER_TURN} command tools and one retained ${formatBytes(TRANSFER_HISTORY_MCP_RESULT_BYTES)} MCP result each, followed by one measured turn with ${TRANSFER_MEASURED_TOOLS} command tools and a retained ${formatBytes(TRANSFER_MEASURED_MCP_RESULT_BYTES)} MCP result. Synthetic V2 domain events exercise persistence, wire projection, and production HTTP/subscription handlers; this does not measure provider adapter ingestion. Payloads contain no user data.`,
238
+ `The long-turn rows open a second thread through the compact bounded snapshot web and mobile use, then load one older page. Its last user turn holds ${LONG_TURN_WORK_ROWS} rows of reasoning, commands, file changes, MCP calls, progress messages, checkpoints, and subagents.`,
239
"",
240
"| Provider | Total thread wire | Budget | Result |",
241
"| --- | ---: | ---: | --- |",
@@ -264,6 +313,8 @@ export function formatTransferBudgetReport(runs: ReadonlyArray<TransferBudgetRun
313
run.reconnectShell,
314
),
315
infoRow(run.provider, "reconnect", "SQL statements", run.reconnectSqlStatements, String),
316
+ ...longTurnRows(run.provider, "long-turn cold open", run.longTurnColdOpen),
317
+ ...longTurnRows(run.provider, "long-turn history page", run.longTurnHistoryPage),
318
);
319
}
320
apps/server/integration/TransferBudgetV2Fixture.integration.ts
+232
-5
@@ -1,4 +1,6 @@
1
import {
2
+ CheckpointId,
3
+ CheckpointScopeId,
4
EventId,
5
MessageId,
6
NodeId,
@@ -9,6 +11,7 @@ import {
11
TurnItemId,
12
type ProviderDriverKind,
13
type OrchestrationV2DomainEvent,
14
+ type OrchestrationV2TurnItem,
15
} from "@t3tools/contracts";
16
import * as DateTime from "effect/DateTime";
17
import {
@@ -20,15 +23,18 @@ import {
23
} from "./fixtures/transferBudget.ts";
24
25
export const THREAD_ID = ThreadId.make("transfer-budget-thread");
23
-export function threadCreated(provider: ProviderDriverKind): OrchestrationV2DomainEvent {
26
+export function threadCreated(
27
+ provider: ProviderDriverKind,
28
+ threadId: ThreadId = THREAD_ID,
29
+): OrchestrationV2DomainEvent {
30
const now = DateTime.makeUnsafe("2026-06-01T00:00:00Z");
31
return {
26
- id: EventId.make("thread-created"),
32
+ id: EventId.make(`thread-created:${threadId}`),
33
type: "thread.created",
28
- threadId: THREAD_ID,
34
+ threadId,
35
occurredAt: now,
36
payload: {
31
- id: THREAD_ID,
37
+ id: threadId,
38
projectId: ProjectId.make("transfer-project"),
39
title: "Transfer budget",
40
providerInstanceId: ProviderInstanceId.make(provider),
@@ -41,7 +47,7 @@ export function threadCreated(provider: ProviderDriverKind): OrchestrationV2Doma
47
branch: null,
48
worktreePath: null,
49
activeProviderThreadId: null,
44
- lineage: { parentThreadId: null, relationshipToParent: null, rootThreadId: THREAD_ID },
50
+ lineage: { parentThreadId: null, relationshipToParent: null, rootThreadId: threadId },
51
forkedFrom: null,
52
createdBy: "user",
53
creationSource: "web",
@@ -179,3 +185,224 @@ export function turnEvents(
185
});
186
return events;
187
}
188
+
189
+export const LONG_TURN_THREAD_ID = ThreadId.make("transfer-budget-long-turn");
190
+export const LONG_TURN_WORK_ROWS = 900;
191
+
192
+/**
193
+ * Three short user turns, then one agent turn far longer than a cold-open
194
+ * window, with the item kinds a long agent run produces. One batch per turn.
195
+ */
196
+export function longTurnThreadBatches(
197
+ provider: ProviderDriverKind,
198
+): ReadonlyArray<ReadonlyArray<OrchestrationV2DomainEvent>> {
199
+ const threadId = LONG_TURN_THREAD_ID;
200
+ const providerInstanceId = ProviderInstanceId.make(provider);
201
+ const modelSelection = {
202
+ instanceId: providerInstanceId,
203
+ model: provider === "codex" ? "gpt-5.4" : "claude-sonnet-4-6",
204
+ };
205
+ let ordinal = 0;
206
+ const text = (turn: number, row: number, targetBytes: number) =>
207
+ diagnosticOutput({ provider, turnIndex: 100 + turn, toolIndex: row, targetBytes });
208
+
209
+ const turn = (index: number, workRows: number): OrchestrationV2DomainEvent[] => {
210
+ const now = DateTime.makeUnsafe(`2026-06-02T00:${String(index).padStart(2, "0")}:00Z`);
211
+ const runId = RunId.make(`long-turn-run-${index}`);
212
+ const nodeId = NodeId.make(`long-turn-node-${index}`);
213
+ const common = {
214
+ threadId,
215
+ runId,
216
+ nodeId,
217
+ driver: provider,
218
+ providerInstanceId,
219
+ occurredAt: now,
220
+ };
221
+ const run = {
222
+ id: runId,
223
+ threadId,
224
+ ordinal: index + 1,
225
+ providerInstanceId,
226
+ modelSelection,
227
+ providerThreadId: null,
228
+ userMessageId: MessageId.make(`long-turn-user-${index}`),
229
+ rootNodeId: nodeId,
230
+ activeAttemptId: null,
231
+ status: "running" as const,
232
+ requestedAt: now,
233
+ startedAt: now,
234
+ completedAt: null,
235
+ checkpointId: null,
236
+ contextHandoffId: null,
237
+ };
238
+ const base = (row: string, title: string | null) => {
239
+ ordinal += 1;
240
+ return {
241
+ id: TurnItemId.make(`long-turn-item-${index}-${row}`),
242
+ threadId,
243
+ runId,
244
+ nodeId,
245
+ providerThreadId: null,
246
+ providerTurnId: null,
247
+ nativeItemRef: null,
248
+ parentItemId: null,
249
+ ordinal,
250
+ status: "completed" as const,
251
+ title,
252
+ startedAt: now,
253
+ completedAt: now,
254
+ updatedAt: now,
255
+ };
256
+ };
257
+ const events: OrchestrationV2DomainEvent[] = [
258
+ { ...common, id: EventId.make(`long-turn-run-${index}`), type: "run.created", payload: run },
259
+ ];
260
+ const message = (role: "user" | "assistant", row: string, messageText: string) => {
261
+ const messageId = MessageId.make(`long-turn-${role}-${index}-${row}`);
262
+ const createdBy = role === "user" ? ("user" as const) : ("agent" as const);
263
+ events.push(
264
+ {
265
+ ...common,
266
+ id: EventId.make(`long-turn-message-${index}-${row}`),
267
+ type: "message.updated",
268
+ payload: {
269
+ id: messageId,
270
+ threadId,
271
+ runId,
272
+ nodeId,
273
+ role,
274
+ text: messageText,
275
+ attachments: [],
276
+ streaming: false,
277
+ createdAt: now,
278
+ updatedAt: now,
279
+ createdBy,
280
+ creationSource: "web",
281
+ },
282
+ },
283
+ {
284
+ ...common,
285
+ id: EventId.make(`long-turn-item-event-${index}-${row}`),
286
+ type: "turn-item.updated",
287
+ payload:
288
+ role === "user"
289
+ ? {
290
+ ...base(row, null),
291
+ type: "user_message",
292
+ createdBy,
293
+ creationSource: "web",
294
+ messageId,
295
+ inputIntent: "turn_start",
296
+ text: messageText,
297
+ attachments: [],
298
+ }
299
+ : {
300
+ ...base(row, null),
301
+ type: "assistant_message",
302
+ messageId,
303
+ text: messageText,
304
+ streaming: false,
305
+ },
306
+ },
307
+ );
308
+ };
309
+ const workItem = (row: number): OrchestrationV2TurnItem => {
310
+ if (row % 100 === 50) {
311
+ return {
312
+ ...base(String(row), "Checkpoint"),
313
+ type: "checkpoint",
314
+ checkpointId: CheckpointId.make(`long-turn-checkpoint-${index}-${row}`),
315
+ scopeId: CheckpointScopeId.make(`long-turn-scope-${index}`),
316
+ files: Array.from({ length: 40 }, (_, file) => ({
317
+ path: `src/feature/module-${row}-${file}.ts`,
318
+ kind: "modified",
319
+ additions: file + 1,
320
+ deletions: file,
321
+ })),
322
+ };
323
+ }
324
+ if (row % 100 === 99) {
325
+ return {
326
+ ...base(String(row), "Subagent"),
327
+ type: "subagent",
328
+ subagentId: NodeId.make(`long-turn-subagent-${index}-${row}`),
329
+ origin: "app_owned",
330
+ driver: provider,
331
+ providerInstanceId,
332
+ childThreadId: null,
333
+ prompt: text(index, row, 2_048),
334
+ result: text(index, row + 1, 3_072),
335
+ };
336
+ }
337
+ switch (row % 8) {
338
+ case 0:
339
+ case 7:
340
+ return {
341
+ ...base(String(row), "Reasoning"),
342
+ type: "reasoning",
343
+ text: text(index, row, 1_536),
344
+ streaming: false,
345
+ };
346
+ case 3:
347
+ return {
348
+ ...base(String(row), `Edit module ${row}`),
349
+ type: "file_change",
350
+ fileName: `src/feature/module-${row}.ts`,
351
+ additions: 12,
352
+ deletions: 4,
353
+ diffStr: text(index, row, 2_048),
354
+ };
355
+ case 4:
356
+ return {
357
+ ...base(String(row), "MCP search"),
358
+ type: "dynamic_tool",
359
+ toolName: "mcp__test__search",
360
+ input: { query: `module ${row}` },
361
+ output: { text: text(index, row, 6_144) },
362
+ };
363
+ case 5:
364
+ return {
365
+ ...base(String(row), null),
366
+ type: "assistant_message",
367
+ messageId: MessageId.make(`long-turn-progress-${index}-${row}`),
368
+ text: text(index, row, 600),
369
+ streaming: false,
370
+ };
371
+ default:
372
+ return {
373
+ ...base(String(row), `Run check ${row}`),
374
+ type: "command_execution",
375
+ input: `vp test run src/feature/module-${row}.test.ts`,
376
+ output: text(index, row, 4_096),
377
+ exitCode: 0,
378
+ };
379
+ }
380
+ };
381
+
382
+ message("user", "prompt", `Continue the feature work, step ${index}.`);
383
+ for (let row = 0; row < workRows; row++) {
384
+ events.push({
385
+ ...common,
386
+ id: EventId.make(`long-turn-work-${index}-${row}`),
387
+ type: "turn-item.updated",
388
+ payload: workItem(row),
389
+ });
390
+ }
391
+ message("assistant", "answer", text(index, workRows, 1_200));
392
+ events.push({
393
+ ...common,
394
+ id: EventId.make(`long-turn-complete-${index}`),
395
+ type: "run.updated",
396
+ payload: { ...run, status: "completed", completedAt: now },
397
+ });
398
+ return events;
399
+ };
400
+
401
+ return [
402
+ [threadCreated(provider, threadId)],
403
+ turn(0, 4),
404
+ turn(1, 4),
405
+ turn(2, 4),
406
+ turn(3, LONG_TURN_WORK_ROWS),
407
+ ];
408
+}
apps/server/integration/transferBudgetV2.integration.test.ts
+47
-2
@@ -16,7 +16,9 @@ import {
16
EnvironmentAuthenticatedPrincipal,
17
ORCHESTRATION_V2_WS_METHODS,
18
OrchestrationV2RpcSchemas,
19
+ OrchestrationV2ThreadBoundedSnapshot,
20
OrchestrationV2ThreadDetailSnapshot,
21
+ OrchestrationV2ThreadHistoryPage,
22
OrchestrationV2ShellSnapshot,
23
OrchestrationV2GetThreadProjectionError,
24
OrchestrationV2GetShellSnapshotError,
@@ -63,11 +65,23 @@ import {
65
type TransferBudgetRun,
66
} from "./TransferBudgetReport.integration.ts";
67
import { TRANSFER_HISTORY_TURN_COUNT } from "./fixtures/transferBudget.ts";
66
-import { THREAD_ID, threadCreated, turnEvents } from "./TransferBudgetV2Fixture.integration.ts";
68
+import {
69
+ LONG_TURN_THREAD_ID,
70
+ longTurnThreadBatches,
71
+ THREAD_ID,
72
+ threadCreated,
73
+ turnEvents,
74
+} from "./TransferBudgetV2Fixture.integration.ts";
75
76
const decodeThreadSnapshot = Schema.decodeUnknownEffect(
77
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ThreadDetailSnapshot)),
78
);
79
+const decodeBoundedSnapshot = Schema.decodeUnknownEffect(
80
+ Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ThreadBoundedSnapshot)),
81
+);
82
+const decodeHistoryPage = Schema.decodeUnknownEffect(
83
+ Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ThreadHistoryPage)),
84
+);
85
const decodeShellSnapshot = Schema.decodeUnknownEffect(
86
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ShellSnapshot)),
87
);
@@ -87,6 +101,10 @@ const layerManagement = Layer.unwrap(
101
getThreadSnapshot: (id) => projections.getThreadSnapshot(id).pipe(Effect.orDie),
102
getThreadSnapshotWindow: (id, options) =>
103
projections.getThreadSnapshotWindow(id, options).pipe(Effect.orDie),
104
+ getThreadHistoryPage: (id, cursor, throughEntryId, conversationOnly) =>
105
+ projections
106
+ .getThreadHistoryPage(id, cursor, throughEntryId, conversationOnly)
107
+ .pipe(Effect.orDie),
108
getThreadShell: (id) => projections.getThreadShell(id).pipe(Effect.orDie),
109
getShellSnapshot: (options) => projections.getShellSnapshot(options).pipe(Effect.orDie),
110
listActiveSubagentThreadIds: () =>
@@ -331,7 +349,29 @@ it.live("reports V2 thread HTTP and WebSocket transfer budgets", () =>
349
const shellMode = yield* synchronized(rsq);
350
const reconnectThread = { ...resumedThread.recorder.totals(), mode: threadMode };
351
const reconnectShell = { ...resumedShell.recorder.totals(), mode: shellMode };
352
+ const reconnectSqlStatements = counter.count() - reconnectSqlStart;
353
assert.equal(threadMode, "snapshot");
354
+
355
+ for (const events of longTurnThreadBatches(provider)) yield* sink.write({ events });
356
+ const longTurnColdOpen = yield* measureHttpGet({
357
+ url: `${base}/api/orchestration/threads/${LONG_TURN_THREAD_ID}/bounded?compactTurnItems=1`,
358
+ headers: { [ORCHESTRATION_PROTOCOL_HEADER]: String(ORCHESTRATION_PROTOCOL_VERSION) },
359
+ });
360
+ assert.equal(longTurnColdOpen.status, 200);
361
+ const coldOpen = yield* decodeBoundedSnapshot(
362
+ Buffer.from(longTurnColdOpen.decodedBody).toString(),
363
+ );
364
+ const cursor = coldOpen.historyCursor;
365
+ if (cursor === null) return yield* Effect.die("Expected older long-turn history");
366
+ const longTurnHistoryPage = yield* measureHttpGet({
367
+ url: `${base}/api/orchestration/threads/${LONG_TURN_THREAD_ID}/history?cursor=${encodeURIComponent(cursor)}`,
368
+ headers: { [ORCHESTRATION_PROTOCOL_HEADER]: String(ORCHESTRATION_PROTOCOL_VERSION) },
369
+ });
370
+ assert.equal(longTurnHistoryPage.status, 200);
371
+ const historyPage = yield* decodeHistoryPage(
372
+ Buffer.from(longTurnHistoryPage.decodedBody).toString(),
373
+ );
374
+ assert.isTrue(historyPage.hasMoreHistory);
375
return {
376
provider,
377
threadSnapshot,
@@ -342,7 +382,12 @@ it.live("reports V2 thread HTTP and WebSocket transfer budgets", () =>
382
measuredTurnSqlStatements,
383
reconnectThread,
384
reconnectShell,
345
- reconnectSqlStatements: counter.count() - reconnectSqlStart,
385
+ reconnectSqlStatements,
386
+ longTurnColdOpen: {
387
+ http: longTurnColdOpen,
388
+ rows: coldOpen.projection.visibleTurnItems.length,
389
+ },
390
+ longTurnHistoryPage: { http: longTurnHistoryPage, rows: historyPage.items.length },
391
} satisfies TransferBudgetRun;
392
}).pipe(
393
Effect.provide(Layer.fresh(layerServices).pipe(Layer.provideMerge(NodeServices.layer))),
apps/server/src/orchestration-v2/ProjectionStore.test.ts
+129
-3
@@ -40,8 +40,10 @@ import * as ProjectionStore from "./ProjectionStore.ts";
40
import {
41
buildBoundedThreadProjection,
42
decodeThreadHistoryCursor,
43
+ encodeThreadHistoryCursor,
44
selectHistoryPageFromCursor,
45
THREAD_HISTORY_PAGE_POLICY,
46
+ THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT,
47
} from "./threadHistoryPaging.ts";
48
49
const layerTest = Layer.mergeAll(
@@ -1529,6 +1531,126 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
1531
[baselineId],
1532
);
1533
}
1534
+ const humanWindow = () =>
1535
+ projectionStore.getThreadSnapshotWindow(threadId, {
1536
+ rowLimit: 77,
1537
+ userTurnLimit: THREAD_HISTORY_PAGE_POLICY.maxUserTurns,
1538
+ });
1539
+ assert.lengthOf(
1540
+ (yield* humanWindow()).projection.turnItems,
1541
+ THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT,
1542
+ );
1543
+ // With the newest user turn 1,000 rows back, the window pages from inside it.
1544
+ const setNewestTurnType = (type: "command_execution" | "user_message") => sql`
1545
+ UPDATE orchestration_v2_projection_turn_items
1546
+ SET type = ${type}, payload_json = json_set(payload_json, '$.type', ${type})
1547
+ WHERE thread_id = ${threadId} AND ordinal = 1000
1548
+ `;
1549
+ yield* setNewestTurnType("command_execution");
1550
+ assert.lengthOf((yield* humanWindow()).projection.turnItems, 77);
1551
+ yield* setNewestTurnType("user_message");
1552
+
1553
+ // Fewer than 75 rows still need a byte pass after materializing wire payloads.
1554
+ yield* sql`
1555
+ UPDATE orchestration_v2_projection_turn_items
1556
+ SET type = 'assistant_message', payload_json = json_set(payload_json,
1557
+ '$.type', 'assistant_message', '$.text', ${"x".repeat(40_000)},
1558
+ '$.messageId', turn_item_id, '$.streaming', json('false'))
1559
+ WHERE thread_id = ${threadId} AND ordinal BETWEEN 2 AND 70
1560
+ `;
1561
+ const byteCursor = encodeThreadHistoryCursor({
1562
+ snapshotSequence: 0,
1563
+ sourceThreadId: threadId,
1564
+ sourceItemId: TurnItemId.make("turn-item:bounded-sql-history:71"),
1565
+ position: 70,
1566
+ });
1567
+ const bytePage = yield* projectionStore.getThreadHistoryPage(threadId, byteCursor);
1568
+ assert.isAbove(bytePage.items.length, 0);
1569
+ assert.isBelow(bytePage.items.length, 70);
1570
+ assert.isAtMost(
1571
+ Buffer.byteLength(JSON.stringify(bytePage.items), "utf8"),
1572
+ THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes,
1573
+ );
1574
+ const byteIds = bytePage.items.map((row) => String(row.sourceItemId));
1575
+ let byteNext = bytePage.nextCursor;
1576
+ for (let pages = 0; byteNext !== null; pages += 1) {
1577
+ assert.isBelow(pages, 70);
1578
+ const page = yield* projectionStore.getThreadHistoryPage(threadId, byteNext);
1579
+ assert.isAbove(page.items.length, 0);
1580
+ byteIds.unshift(...page.items.map((row) => String(row.sourceItemId)));
1581
+ byteNext = page.nextCursor;
1582
+ }
1583
+ assert.deepEqual(
1584
+ byteIds,
1585
+ Array.from({ length: 70 }, (_, index) => `turn-item:bounded-sql-history:${index + 1}`),
1586
+ );
1587
+ yield* sql`
1588
+ UPDATE orchestration_v2_projection_turn_items
1589
+ SET type = 'command_execution', payload_json = json_set(payload_json, '$.type', 'command_execution')
1590
+ WHERE thread_id = ${threadId} AND ordinal BETWEEN 2 AND 70
1591
+ `;
1592
+
1593
+ // A targeted page that needs more than 20 human turns must still reach its target
1594
+ // after the byte pass re-bounds it.
1595
+ yield* sql`
1596
+ UPDATE orchestration_v2_projection_turn_items
1597
+ SET type = 'user_message', payload_json = json_set(payload_json,
1598
+ '$.type', 'user_message', '$.createdBy', 'user', '$.creationSource', 'web',
1599
+ '$.inputIntent', 'turn_start', '$.messageId', turn_item_id, '$.text', 'Turn',
1600
+ '$.attachments', json('[]'))
1601
+ WHERE thread_id = ${threadId} AND ordinal BETWEEN 600 AND 624
1602
+ `;
1603
+ const targetedPage = yield* projectionStore.getThreadHistoryPage(
1604
+ threadId,
1605
+ encodeThreadHistoryCursor({
1606
+ snapshotSequence: 0,
1607
+ sourceThreadId: threadId,
1608
+ sourceItemId: TurnItemId.make("turn-item:bounded-sql-history:625"),
1609
+ position: 624,
1610
+ }),
1611
+ "turn-item:bounded-sql-history:600",
1612
+ );
1613
+ assert.strictEqual(
1614
+ String(targetedPage.items[0]?.sourceItemId),
1615
+ "turn-item:bounded-sql-history:600",
1616
+ );
1617
+ yield* sql`
1618
+ UPDATE orchestration_v2_projection_turn_items
1619
+ SET type = 'command_execution', payload_json = json_set(payload_json, '$.type', 'command_execution')
1620
+ WHERE thread_id = ${threadId} AND ordinal BETWEEN 600 AND 624
1621
+ `;
1622
+
1623
+ // A turn split by the row budget keeps an interrupt result's request on the same page.
1624
+ yield* sql`
1625
+ UPDATE orchestration_v2_projection_turn_items
1626
+ SET run_id = 'run:bounded-sql-history:500',
1627
+ type = CASE ordinal WHEN 500 THEN 'run_interrupt_request' ELSE 'run_interrupt_result' END,
1628
+ payload_json = json_set(payload_json,
1629
+ '$.runId', 'run:bounded-sql-history:500', '$.message', 'Stop',
1630
+ '$.type', CASE ordinal WHEN 500 THEN 'run_interrupt_request' ELSE 'run_interrupt_result' END)
1631
+ WHERE thread_id = ${threadId} AND ordinal IN (500, 580)
1632
+ `;
1633
+ const interruptPage = yield* projectionStore.getThreadHistoryPage(
1634
+ threadId,
1635
+ encodeThreadHistoryCursor({
1636
+ snapshotSequence: 0,
1637
+ sourceThreadId: threadId,
1638
+ sourceItemId: TurnItemId.make("turn-item:bounded-sql-history:590"),
1639
+ position: 589,
1640
+ }),
1641
+ );
1642
+ const interruptIds = interruptPage.items.map((row) => String(row.sourceItemId));
1643
+ assert.include(interruptIds, "turn-item:bounded-sql-history:580");
1644
+ assert.include(interruptIds, "turn-item:bounded-sql-history:500");
1645
+ assert.notInclude(interruptIds, "turn-item:bounded-sql-history:501");
1646
+ yield* sql`
1647
+ UPDATE orchestration_v2_projection_turn_items
1648
+ SET run_id = 'run:bounded-sql-history:' || ordinal, type = 'command_execution',
1649
+ payload_json = json_set(payload_json,
1650
+ '$.runId', 'run:bounded-sql-history:' || ordinal, '$.type', 'command_execution')
1651
+ WHERE thread_id = ${threadId} AND ordinal IN (500, 580)
1652
+ `;
1653
+
1654
const retainedRequestPlan = yield* sql<{ readonly detail: string }>`
1655
EXPLAIN QUERY PLAN
1656
WITH selected AS (
@@ -1571,9 +1693,9 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
1693
const sqlPageLimit = THREAD_HISTORY_PAGE_POLICY.maxItems + 2;
1694
const initialSnapshot = yield* projectionStore.getThreadSnapshotWindow(threadId, {
1695
rowLimit: sqlPageLimit,
1696
+ userTurnLimit: THREAD_HISTORY_PAGE_POLICY.maxUserTurns,
1697
});
1698
const initialPage = buildBoundedThreadProjection({
1576
- policy: { ...THREAD_HISTORY_PAGE_POLICY, maxUserTurns: undefined },
1699
projection: initialSnapshot.projection,
1700
snapshotSequence: initialSnapshot.snapshotSequence,
1701
});
@@ -1586,10 +1708,14 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
1708
const anchorItemId = TurnItemId.make(decodeThreadHistoryCursor(cursor).si);
1709
const snapshot = yield* projectionStore.getThreadSnapshotWindow(threadId, {
1710
rowLimit: sqlPageLimit,
1711
+ userTurnLimit: 20,
1712
anchorItemId,
1713
});
1714
+ assert.isAtMost(
1715
+ snapshot.projection.visibleTurnItems.length,
1716
+ THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT,
1717
+ );
1718
const page = selectHistoryPageFromCursor({
1592
- policy: { ...THREAD_HISTORY_PAGE_POLICY, maxUserTurns: undefined },
1719
items: snapshot.projection.visibleTurnItems,
1720
cursor,
1721
snapshotSequence: snapshot.snapshotSequence,
@@ -1599,7 +1725,7 @@ it.layer(layerTest)("ProjectionStoreV2", (it) => {
1725
cursor = page.nextCursor;
1726
}
1727
1602
- assert.isAtLeast(pageCount, 4);
1728
+ assert.isAtLeast(pageCount, 3);
1729
assert.lengthOf(loadedIds, 1_000);
1730
assert.strictEqual(new Set(loadedIds).size, 1_000);
1731
assert.deepEqual(
apps/server/src/orchestration-v2/ProjectionStore.ts
+100
-70
@@ -96,10 +96,12 @@ import {
96
isConversationHistoryItem,
97
threadHistoryTurnStarts,
98
THREAD_HISTORY_MAX_RAW_TURNS,
99
+ missingInterruptRequests,
100
+ olderHistoryPagePolicy,
101
selectHistoryPageFromCursor,
102
selectRecentTimelineWindow,
103
THREAD_HISTORY_PAGE_POLICY,
102
- OLDER_THREAD_USER_TURN_LIMIT,
104
+ THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT,
105
} from "./threadHistoryPaging.ts";
106
107
export class ProjectionStoreApplyEventError extends Schema.TaggedError<ProjectionStoreApplyEventError>()(
@@ -2992,6 +2994,17 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
2994
ELSE 0
2995
END AS ordinal
2996
FROM user_anchors
2997
+ ), latest_user_turn AS (
2998
+ -- Mirrors selectOlderTimelinePage: whole turns while the
2999
+ -- newest user turn fits the turn row budget, otherwise the
3000
+ -- window pages from inside that turn with the row limit.
3001
+ SELECT COUNT(*) AS row_count
3002
+ FROM (
3003
+ SELECT 1
3004
+ FROM eligible
3005
+ WHERE ordinal >= (SELECT MAX(ordinal) FROM user_anchors)
3006
+ LIMIT ${THREAD_HISTORY_PAGE_POLICY.maxTurnItems + 1}
3007
+ )
3008
), selected AS (
3009
-- Choose and sort rows by ID, then fetch payloads in that
3010
-- order. A turn window can hold megabytes of tool output, and
@@ -3002,7 +3015,9 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
3015
ORDER BY ordinal DESC, turn_item_id DESC
3016
LIMIT CASE
3017
WHEN ${window.rowLimit} = 0 THEN 0
3005
- WHEN (SELECT COUNT(*) FROM user_anchors) > 0 THEN -1
3018
+ WHEN (SELECT row_count FROM latest_user_turn)
3019
+ BETWEEN 1 AND ${THREAD_HISTORY_PAGE_POLICY.maxTurnItems}
3020
+ THEN ${THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT}
3021
ELSE ${window.rowLimit}
3022
END
3023
), retained AS MATERIALIZED (
@@ -5478,84 +5493,85 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
5493
FROM orchestration_events WHERE application_event_version = 2
5494
AND aggregate_kind = 'thread' AND stream_id = ${threadId}`;
5495
const snapshotSequence = revisions[0]?.sequence ?? 0;
5481
- const page = yield* Effect.try({
5482
- try: () =>
5483
- selectHistoryPageFromCursor({
5484
- items: index.visible.map((row, position) => ({
5485
- ...row,
5486
- position,
5487
- canonicalPosition: position,
5488
- })),
5496
+ const indexed = index.visible.map((row, position) => ({
5497
+ ...row,
5498
+ position,
5499
+ canonicalPosition: position,
5500
+ }));
5501
+ const selection = yield* Effect.try({
5502
+ try: () => {
5503
+ const policy = olderHistoryPagePolicy({ items: indexed, cursor, throughEntryId });
5504
+ const page = selectHistoryPageFromCursor({
5505
+ items: indexed,
5506
cursor,
5507
snapshotSequence,
5508
rowEncodedBytes: () => 0,
5492
- throughEntryId,
5493
- }),
5509
+ policy,
5510
+ });
5511
+ return { policy, page };
5512
+ },
5513
catch: (cause) => new ProjectionStoreReadError({ threadId, cause }),
5514
});
5515
+ const { policy, page } = selection;
5516
const end = (page.items.at(-1)?.canonicalPosition ?? -1) + 1;
5517
const hasUserTurns = index.visible
5518
.slice(0, end)
5519
.some((row) => isThreadHistoryUserTurn(row.item));
5500
- const materialized =
5501
- conversationOnly && hasUserTurns
5502
- ? page.items.filter((row) => isConversationHistoryItem(row.item))
5503
- : page.items;
5504
- const sources = yield* encodeTimelineSources(
5505
- materialized
5506
- .filter((row) => !row.synthetic)
5507
- .map((row) => ({ threadId: row.sourceThreadId, id: row.sourceItemId })),
5508
- );
5509
- const payloads = yield* sql<{
5510
- thread_id: string;
5511
- turn_item_id: string;
5512
- payload_json: string;
5513
- }>`
5520
+ const materialize = Effect.fn("ProjectionStore.materializeHistoryRows")(function* (
5521
+ rows: ReadonlyArray<(typeof indexed)[number]>,
5522
+ ) {
5523
+ if (rows.length === 0) return [];
5524
+ const sources = yield* encodeTimelineSources(
5525
+ rows
5526
+ .filter((row) => !row.synthetic)
5527
+ .map((row) => ({ threadId: row.sourceThreadId, id: row.sourceItemId })),
5528
+ );
5529
+ const payloads = yield* sql<{
5530
+ thread_id: string;
5531
+ turn_item_id: string;
5532
+ payload_json: string;
5533
+ }>`
5534
SELECT item.thread_id, item.turn_item_id, item.payload_json
5535
FROM orchestration_v2_projection_turn_items item JOIN json_each(${sources}) wanted
5536
ON item.thread_id = json_extract(wanted.value, '$.threadId')
5537
AND item.turn_item_id = json_extract(wanted.value, '$.id')`;
5518
- const byIdentity = new Map(
5519
- payloads.map((row) => [`${row.thread_id}:${row.turn_item_id}`, row.payload_json]),
5520
- );
5521
- const items = yield* Effect.forEach(materialized, (row) =>
5522
- Effect.gen(function* () {
5523
- const payload = byIdentity.get(`${row.sourceThreadId}:${row.sourceItemId}`);
5524
- const item =
5525
- row.synthetic ??
5526
- (payload === undefined
5527
- ? yield* new ProjectionStoreReadError({ threadId })
5528
- : yield* decodeTurnItemPayload(payload));
5529
- return {
5530
- position: row.canonicalPosition,
5531
- visibility: row.visibility,
5532
- sourceThreadId: row.sourceThreadId,
5533
- sourceItemId: row.sourceItemId,
5534
- item: projectTurnItemForWire(item),
5535
- };
5536
- }),
5537
- );
5538
- if (hasUserTurns)
5539
- return {
5540
- ...page,
5541
- snapshotSequence,
5542
- items: items.map((row, position) => ({ ...row, position })),
5543
- };
5544
- const bounded = selectRecentTimelineWindow({
5545
- items,
5546
- snapshotSequence,
5547
- policy: {
5548
- ...THREAD_HISTORY_PAGE_POLICY,
5549
- maxUserTurns: OLDER_THREAD_USER_TURN_LIMIT,
5550
- maxItems:
5551
- THREAD_HISTORY_PAGE_POLICY.maxItems * (throughEntryId === undefined ? 1 : 2),
5552
- },
5538
+ const byIdentity = new Map(
5539
+ payloads.map((row) => [`${row.thread_id}:${row.turn_item_id}`, row.payload_json]),
5540
+ );
5541
+ return yield* Effect.forEach(rows, (row) =>
5542
+ Effect.gen(function* () {
5543
+ const payload = byIdentity.get(`${row.sourceThreadId}:${row.sourceItemId}`);
5544
+ const item =
5545
+ row.synthetic ??
5546
+ (payload === undefined
5547
+ ? yield* new ProjectionStoreReadError({ threadId })
5548
+ : yield* decodeTurnItemPayload(payload));
5549
+ return {
5550
+ position: row.canonicalPosition,
5551
+ visibility: row.visibility,
5552
+ sourceThreadId: row.sourceThreadId,
5553
+ sourceItemId: row.sourceItemId,
5554
+ item: projectTurnItemForWire(item),
5555
+ };
5556
+ }),
5557
+ );
5558
});
5559
+ const items = yield* materialize(
5560
+ conversationOnly && hasUserTurns
5561
+ ? page.items.filter((row) => isConversationHistoryItem(row.item))
5562
+ : page.items,
5563
+ );
5564
+ const bounded = selectRecentTimelineWindow({ items, snapshotSequence, policy });
5565
+ const requests = yield* materialize(missingInterruptRequests(indexed, bounded.items));
5566
+ const pageItems = [...requests, ...bounded.items].map((row, position) => ({
5567
+ ...row,
5568
+ position,
5569
+ }));
5570
return {
5571
snapshotSequence,
5572
items: conversationOnly
5557
- ? bounded.items.filter((row) => isConversationHistoryItem(row.item))
5558
- : bounded.items,
5573
+ ? pageItems.filter((row) => isConversationHistoryItem(row.item))
5574
+ : pageItems,
5575
nextCursor: bounded.hasMoreHistory ? bounded.nextCursor : page.nextCursor,
5576
hasMoreHistory: bounded.hasMoreHistory || page.hasMoreHistory,
5577
};
@@ -7383,21 +7399,26 @@ export const layerMemory: Layer.Layer<ProjectionStoreV2> = Layer.effect(
7399
return yield* new ProjectionStoreThreadNotFoundError({ threadId });
7400
return yield* Effect.try({
7401
try: () => {
7402
+ const visible = projection.visibleTurnItems.map((row) => ({
7403
+ ...row,
7404
+ item: projectTurnItemForWire(row.item),
7405
+ }));
7406
const page = selectHistoryPageFromCursor({
7387
- items: projection.visibleTurnItems.map((row) => ({
7388
- ...row,
7389
- item: projectTurnItemForWire(row.item),
7390
- })),
7407
+ items: visible,
7408
cursor,
7409
throughEntryId,
7410
snapshotSequence,
7411
});
7412
+ const items = [
7413
+ ...missingInterruptRequests(visible, page.items),
7414
+ ...page.items,
7415
+ ].map((row, position) => ({ ...row, position }));
7416
return {
7417
...page,
7418
snapshotSequence,
7419
items: conversationOnly
7399
- ? page.items.filter((row) => isConversationHistoryItem(row.item))
7400
- : page.items,
7420
+ ? items.filter((row) => isConversationHistoryItem(row.item))
7421
+ : items,
7422
};
7423
},
7424
catch: (cause) => new ProjectionStoreReadError({ threadId, cause }),
@@ -7448,7 +7469,16 @@ export const layerMemory: Layer.Layer<ProjectionStoreV2> = Layer.effect(
7469
? rawStart
7470
: anchors.at(-anchorLimit)!
7471
: Math.max(0, anchorIndex - options.rowLimit);
7451
- const visibleTurnItems = candidates.slice(start);
7472
+ const latestTurnRows = anchors.length > 0 ? anchorIndex - anchors.at(-1)! : 0;
7473
+ const rowLimit =
7474
+ options.rowLimit > 0 &&
7475
+ latestTurnRows > 0 &&
7476
+ latestTurnRows <= THREAD_HISTORY_PAGE_POLICY.maxTurnItems
7477
+ ? THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT
7478
+ : options.rowLimit;
7479
+ const visibleTurnItems = candidates.slice(
7480
+ Math.max(start, anchorIndex - Math.max(0, rowLimit)),
7481
+ );
7482
return {
7483
...snapshot,
7484
projection: { ...snapshot.projection, visibleTurnItems },
apps/server/src/orchestration-v2/ThreadFind.test.ts
+12
-3
@@ -24,7 +24,11 @@ import * as SqlitePersistence from "../persistence/Sqlite.ts";
24
import * as ProjectionStore from "./ProjectionStore.ts";
25
import * as ProjectStore from "./ProjectStore.ts";
26
import * as EventStore from "./EventStore.ts";
27
-import { encodeThreadHistoryCursor, selectHistoryPageFromCursor } from "./threadHistoryPaging.ts";
27
+import {
28
+ encodeThreadHistoryCursor,
29
+ selectHistoryPageFromCursor,
30
+ THREAD_HISTORY_PAGE_POLICY,
31
+} from "./threadHistoryPaging.ts";
32
import { projectTurnItemForWire } from "./WireProjection.ts";
33
34
const layerTest = Layer.mergeAll(EventStore.layer, ProjectionStore.layer, ProjectStore.layer).pipe(
@@ -722,7 +726,7 @@ describe("V2 history materialization", () => {
726
}).pipe(Effect.provide(layerTest)),
727
);
728
725
- it.effect("pages complete turns without duplicating or skipping messages", () =>
729
+ it.effect("pages long turns without duplicating or skipping messages", () =>
730
Effect.gen(function* () {
731
const projection = yield* setup;
732
const items = Array.from({ length: 45 }, (_, turn) => [
@@ -763,7 +767,12 @@ describe("V2 history materialization", () => {
767
snapshotSequence: snapshot.snapshotSequence,
768
}),
769
});
766
- assert.equal(page.items[0]?.item.type, "user_message");
770
+ // A turn larger than the byte budget is split, but only a lone oversized item may exceed it.
771
+ assert.isTrue(
772
+ page.items.length === 1 ||
773
+ Buffer.byteLength(JSON.stringify(page.items), "utf8") <=
774
+ THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes,
775
+ );
776
collected.unshift(...page.items.map((row) => String(row.sourceItemId)));
777
cursor = page.nextCursor;
778
}
apps/server/src/orchestration-v2/ThreadStream.test.ts
-1
@@ -161,7 +161,6 @@ describe("decideThreadResume", () => {
161
expect(snapshot.historyCursor).not.toBeNull();
162
expect(snapshot.hasMoreHistory).toBe(true);
163
expect(snapshot.latestLocalTurnOrdinal).toBe(80);
164
- expect(snapshot.payloadBudgetExceeded).toBe(false);
164
});
165
166
it("rejects a 10 MiB raw replay even when its projected form fits the wire budget", () => {
apps/server/src/orchestration-v2/ThreadStream.ts
-1
@@ -52,7 +52,6 @@ export function boundedSnapshotResponseFields(input: {
52
historyCursor: bounded.historyCursor,
53
hasMoreHistory: bounded.hasMoreHistory,
54
latestLocalTurnOrdinal: bounded.latestLocalTurnOrdinal,
55
- payloadBudgetExceeded: bounded.payloadBudgetExceeded,
55
...(compactProjection === null ? {} : { turnItemsOmitLocalVisible: true as const }),
56
};
57
}
apps/server/src/orchestration-v2/threadHistoryPaging.test.ts
+111
-67
@@ -106,27 +106,6 @@ function interruptRow(
106
};
107
}
108
109
-function assistantRow(
110
- text: string,
111
- visibility: "local" | "inherited" = "local",
112
-): OrchestrationV2ProjectedTurnItem {
113
- const row = makeRow(0);
114
- const sourceThreadId = visibility === "local" ? THREAD : ThreadId.make("parent-thread");
115
- return {
116
- ...row,
117
- visibility,
118
- sourceThreadId,
119
- item: {
120
- ...row.item,
121
- threadId: sourceThreadId,
122
- type: "assistant_message",
123
- messageId: MessageId.make("answer-0"),
124
- text,
125
- streaming: false,
126
- },
127
- } as OrchestrationV2ProjectedTurnItem;
128
-}
129
-
109
function makeProjection(visibleTurnItems: OrchestrationV2ProjectedTurnItem[]) {
110
return {
111
thread: {
@@ -176,6 +155,65 @@ function makeProjection(visibleTurnItems: OrchestrationV2ProjectedTurnItem[]) {
155
}
156
157
describe("threadHistoryPaging", () => {
158
+ it("keeps a human turn whole up to the turn row budget and pages a longer one from inside", () => {
159
+ const humanTurn = (length: number) => {
160
+ const items = Array.from({ length }, (_, index) => makeRow(index));
161
+ items[0] = {
162
+ ...items[0]!,
163
+ item: {
164
+ ...items[0]!.item,
165
+ type: "user_message",
166
+ createdBy: "user",
167
+ creationSource: "web",
168
+ inputIntent: "turn_start",
169
+ messageId: MessageId.make("long-human-turn"),
170
+ text: "Continue",
171
+ attachments: [],
172
+ },
173
+ } as OrchestrationV2ProjectedTurnItem;
174
+ return items;
175
+ };
176
+
177
+ const whole = selectRecentTimelineWindow({ items: humanTurn(180), snapshotSequence: 1 });
178
+ expect(whole.items).toHaveLength(180);
179
+ expect(whole.hasMoreHistory).toBe(false);
180
+
181
+ const items = humanTurn(THREAD_HISTORY_PAGE_POLICY.maxTurnItems + 100);
182
+ const recent = selectRecentTimelineWindow({ items, snapshotSequence: 1 });
183
+ expect(recent.items).toHaveLength(THREAD_HISTORY_PAGE_POLICY.maxItems);
184
+ const loaded = [...recent.items];
185
+ let cursor = recent.nextCursor;
186
+ for (let pages = 0; cursor !== null; pages += 1) {
187
+ expect(pages).toBeLessThan(items.length);
188
+ const page = selectHistoryPageFromCursor({ items, cursor, snapshotSequence: 1 });
189
+ expect(page.items.length).toBeGreaterThan(0);
190
+ expect(page.items.length).toBeLessThanOrEqual(
191
+ page.items[0]?.item.type === "user_message"
192
+ ? THREAD_HISTORY_PAGE_POLICY.maxTurnItems
193
+ : THREAD_HISTORY_PAGE_POLICY.maxItems,
194
+ );
195
+ loaded.unshift(...page.items);
196
+ cursor = page.nextCursor;
197
+ }
198
+ expect(loaded.map((row) => row.sourceItemId)).toEqual(items.map((row) => row.sourceItemId));
199
+
200
+ const large = items
201
+ .slice(0, 12)
202
+ .map((row) =>
203
+ row.item.type === "command_execution"
204
+ ? { ...row, item: { ...row.item, output: "x".repeat(200_000) } }
205
+ : row,
206
+ );
207
+ const bounded = buildBoundedThreadProjection({
208
+ projection: makeProjection(large),
209
+ snapshotSequence: 1,
210
+ });
211
+ expect(bounded.projection.visibleTurnItems.length).toBeLessThan(large.length);
212
+ expect(boundedTimelineEncodedBytes(bounded.projection)).toBeLessThanOrEqual(
213
+ THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes,
214
+ );
215
+ });
216
+
217
it("keeps background turns with user turns, with main's 150-turn fan-out ceiling", () => {
218
const items = Array.from({ length: 161 }, (_, turn) => {
219
const row = makeRow(turn * 2);
@@ -195,13 +233,15 @@ describe("threadHistoryPaging", () => {
233
};
234
return [prompt, makeRow(turn * 2 + 1)];
235
}).flat();
198
- const first = selectRecentTimelineWindow({ items, snapshotSequence: 1 });
236
+ const policy = { ...THREAD_HISTORY_PAGE_POLICY, maxItems: 1_000, maxEncodedBytes: 10_000_000 };
237
+ const first = selectRecentTimelineWindow({ items, snapshotSequence: 1, policy });
238
expect(first.items).toHaveLength(300);
239
expect(first.items[0]?.sourceItemId).toBe("item-22");
240
const older = selectHistoryPageFromCursor({
241
items,
242
cursor: first.nextCursor!,
243
snapshotSequence: 1,
244
+ policy,
245
});
246
expect(older.items).toHaveLength(22);
247
expect(older.hasMoreHistory).toBe(false);
@@ -244,13 +284,20 @@ describe("threadHistoryPaging", () => {
284
inRun(run * 4 + 2, run, notification(`Steer ${run}`)),
285
inRun(run * 4 + 3, run),
286
]).flat();
247
- const first = selectRecentTimelineWindow({ items, snapshotSequence: 1 });
287
+ const policy = {
288
+ ...THREAD_HISTORY_PAGE_POLICY,
289
+ maxItems: 1_000,
290
+ maxTurnItems: 1_000,
291
+ maxEncodedBytes: 10_000_000,
292
+ };
293
+ const first = selectRecentTimelineWindow({ items, snapshotSequence: 1, policy });
294
expect(first.items).toHaveLength(150 * 4 - 1);
295
expect(first.items[0]?.sourceItemId).toBe(`item-${11 * 4 + 1}`);
296
const older = selectHistoryPageFromCursor({
297
items,
298
cursor: first.nextCursor!,
299
snapshotSequence: 1,
300
+ policy,
301
});
302
expect([...older.items, ...first.items].map((row) => row.sourceItemId)).toEqual(
303
items.map((row) => row.sourceItemId),
@@ -288,26 +335,46 @@ describe("threadHistoryPaging", () => {
335
});
336
337
it("always includes at least one pathological oversized item", () => {
291
- const items = [makeRow(0, { outputBytes: 2_000_000 }), makeRow(1, { outputBytes: 10 })];
292
- const page = selectRecentTimelineWindow({
293
- items,
294
- snapshotSequence: 1,
295
- policy: { maxItems: 50, maxEncodedBytes: 1_024 },
296
- });
297
- expect(page.items).toHaveLength(1);
298
- expect(page.items[0]?.sourceItemId).toBe("item-1");
299
- expect(page.hasMoreHistory).toBe(true);
300
-
301
- const older = selectHistoryPageFromCursor({
302
- items,
303
- cursor: page.nextCursor!,
304
- snapshotSequence: 1,
305
- policy: { maxItems: 50, maxEncodedBytes: 1_024 },
306
- });
307
- expect(older.items).toHaveLength(1);
308
- expect(older.items[0]?.sourceItemId).toBe("item-0");
309
- expect(older.hasMoreHistory).toBe(false);
310
- expect(older.nextCursor).toBeNull();
338
+ for (const humanTurn of [false, true]) {
339
+ const oversized = makeRow(0, { outputBytes: 2_000_000 });
340
+ const items = [
341
+ humanTurn
342
+ ? ({
343
+ ...oversized,
344
+ item: {
345
+ ...oversized.item,
346
+ type: "user_message",
347
+ createdBy: "user",
348
+ creationSource: "web",
349
+ inputIntent: "turn_start",
350
+ messageId: MessageId.make("oversized-human-turn"),
351
+ text: "x".repeat(2_000_000),
352
+ attachments: [],
353
+ },
354
+ } as OrchestrationV2ProjectedTurnItem)
355
+ : oversized,
356
+ makeRow(1, { outputBytes: 10 }),
357
+ ];
358
+ const policy = { ...THREAD_HISTORY_PAGE_POLICY, maxItems: 50, maxEncodedBytes: 1_024 };
359
+ const page = selectRecentTimelineWindow({ items, snapshotSequence: 1, policy });
360
+ expect(page.items).toHaveLength(1);
361
+ expect(page.items[0]?.sourceItemId).toBe("item-1");
362
+ expect(page.hasMoreHistory).toBe(true);
363
+
364
+ const older = selectHistoryPageFromCursor({
365
+ items,
366
+ cursor: page.nextCursor!,
367
+ snapshotSequence: 1,
368
+ policy,
369
+ });
370
+ expect(older.items).toHaveLength(1);
371
+ expect(older.items[0]?.sourceItemId).toBe("item-0");
372
+ expect(older.hasMoreHistory).toBe(false);
373
+ expect(older.nextCursor).toBeNull();
374
+ expect([...older.items, ...page.items].map((row) => row.sourceItemId)).toEqual(
375
+ items.map((row) => row.sourceItemId),
376
+ );
377
+ }
378
});
379
380
it("recovers identity-miss cursors when position is past a shrunken timeline", () => {
@@ -557,7 +624,6 @@ describe("threadHistoryPaging", () => {
624
const serializedBytes = Buffer.byteLength(JSON.stringify(bounded.projection), "utf8");
625
626
expect(serializedBytes).toBeLessThanOrEqual(THREAD_HISTORY_PAGE_POLICY.maxEncodedBytes);
560
- expect(bounded.payloadBudgetExceeded).toBe(false);
627
expect(bounded.projection.plans).toEqual([]);
628
expect(bounded.projection.contextHandoffs).toEqual([]);
629
expect(populated.plans).toHaveLength(120);
@@ -566,7 +632,7 @@ describe("threadHistoryPaging", () => {
632
).toBe(2_097_152);
633
});
634
569
- it("preserves oversized actionable state and reports the budget exception", () => {
635
+ it("preserves oversized actionable state", () => {
636
const projection = makeProjection([makeRow(0)]);
637
const actionable = {
638
...projection,
@@ -585,30 +651,10 @@ describe("threadHistoryPaging", () => {
651
652
const bounded = buildBoundedThreadProjection({ projection: actionable, snapshotSequence: 9 });
653
588
- expect(bounded.payloadBudgetExceeded).toBe(true);
654
expect(bounded.projection.plans[0]).toEqual(actionable.plans[0]);
655
expect(bounded.projection.visibleTurnItems).toEqual(actionable.visibleTurnItems);
656
});
657
593
- it("flips overflow at the exact encoded size when timeline text fits the budget", () => {
594
- // Inherited rows are encoded once, local rows twice; neither may overflow early.
595
- for (const visibility of ["local", "inherited"] as const) {
596
- const projection = makeProjection([assistantRow("a".repeat(20_000), visibility)]);
597
- const build = (maxEncodedBytes: number) =>
598
- buildBoundedThreadProjection({
599
- projection,
600
- snapshotSequence: 1,
601
- policy: { maxItems: 75, maxEncodedBytes },
602
- });
603
- const bytes = Buffer.byteLength(
604
- JSON.stringify(build(Number.MAX_SAFE_INTEGER).projection),
605
- "utf8",
606
- );
607
- expect(build(bytes).payloadBudgetExceeded).toBe(false);
608
- expect(build(bytes - 1).payloadBudgetExceeded).toBe(true);
609
- }
610
- });
611
-
658
it("keeps agent-only turns visible when checkpoint file lists fill the byte budget", () => {
659
const items = Array.from({ length: 3 }, (_, turn) => {
660
const first = makeRow(turn * 5);
@@ -641,7 +687,6 @@ describe("threadHistoryPaging", () => {
687
688
expect(bounded.projection.visibleTurnItems).toHaveLength(items.length);
689
expect(bounded.hasMoreHistory).toBe(false);
644
- expect(bounded.payloadBudgetExceeded).toBe(true);
690
});
691
692
it("keeps paged historical plan detail in the turn item and only status in its artifact", () => {
@@ -685,6 +730,5 @@ describe("threadHistoryPaging", () => {
730
markdown: "",
731
detailInTurnItem: true,
732
});
688
- expect(bounded.payloadBudgetExceeded).toBe(false);
733
});
734
});
apps/server/src/orchestration-v2/threadHistoryPaging.ts
+89
-67
@@ -7,12 +7,15 @@ import type {
7
} from "@t3tools/contracts";
8
9
/**
10
- * Item/byte budgets only apply to histories without turn starts; tool activity
11
- * must not split an ordinary conversation turn.
10
+ * Every window stops at the byte budget. A window that holds a user turn also
11
+ * stops at `maxUserTurns` or `maxTurnItems` rows, which keeps ordinary turns
12
+ * whole (V1 kept 500 activities). Any other window, such as an agent-driven
13
+ * thread or the inside of one very long turn, stops at `maxItems` rows.
14
*/
15
export const THREAD_HISTORY_PAGE_POLICY = {
16
maxUserTurns: 10,
17
maxItems: 75,
18
+ maxTurnItems: 500,
19
maxEncodedBytes: 1_048_576,
20
} as const;
21
@@ -24,12 +27,16 @@ export function isConversationHistoryItem(item: Pick<OrchestrationV2TurnItem, "t
27
export const THREAD_HISTORY_MAX_RAW_TURNS = 150;
28
29
export const THREAD_HISTORY_SNAPSHOT_ROW_LIMIT = THREAD_HISTORY_PAGE_POLICY.maxItems + 2;
30
+/** The snapshot query's row limit once the history has a user turn. */
31
+export const THREAD_HISTORY_TURN_SNAPSHOT_ROW_LIMIT = THREAD_HISTORY_PAGE_POLICY.maxTurnItems + 2;
32
33
const THREAD_HISTORY_CURSOR_MAX_LENGTH = 4_096;
34
35
export type ThreadHistoryPagePolicy = {
36
readonly maxUserTurns?: number | undefined;
37
readonly maxItems: number;
38
+ /** Defaults to `maxItems`. */
39
+ readonly maxTurnItems?: number | undefined;
40
readonly maxEncodedBytes: number;
41
};
42
@@ -64,7 +71,6 @@ export type BoundedProjectionResult = {
71
readonly historyCursor: string | null;
72
readonly hasMoreHistory: boolean;
73
readonly latestLocalTurnOrdinal: number | null;
67
- readonly payloadBudgetExceeded: boolean;
74
};
75
76
export class InvalidThreadHistoryCursorError extends Error {
@@ -79,27 +85,6 @@ function bytesOfJson(value: unknown): number {
85
return Buffer.byteLength(JSON.stringify(value), "utf8");
86
}
87
82
-/**
83
- * Proves overflow without serializing: a string's UTF-16 length never exceeds
84
- * its UTF-8 JSON bytes, and local items are encoded once per array they sit in.
85
- */
86
-function timelineTextExceedsBudget(
87
- projection: OrchestrationV2ThreadProjection,
88
- budget: number,
89
-): boolean {
90
- let length = 0;
91
- const exceeds = (item: OrchestrationV2TurnItem): boolean => {
92
- if ("text" in item) {
93
- length += item.text.length;
94
- }
95
- return length > budget;
96
- };
97
- return (
98
- projection.visibleTurnItems.some((row) => exceeds(row.item)) ||
99
- projection.turnItems.some(exceeds)
100
- );
101
-}
102
-
88
export function projectedRowEncodedBytes(row: HistoryRow): number {
89
return bytesOfJson(row);
90
}
@@ -210,8 +195,7 @@ export function isThreadHistoryUserTurn(item: HistoryRow["item"]): boolean {
195
}
196
197
/**
213
- * Histories without turn starts use row budgets and always admit at least one
214
- * row so oversized items cannot deadlock paging.
198
+ * Always admit at least one row so oversized items cannot deadlock paging.
199
*/
200
function selectOlderTimelinePage<Row extends HistoryRow>(input: {
201
readonly items: ReadonlyArray<Row>;
@@ -236,14 +220,17 @@ function selectOlderTimelinePage<Row extends HistoryRow>(input: {
220
const turnLimit = candidates.some((row) => isThreadHistoryUserTurn(row.item))
221
? policy.maxUserTurns
222
: undefined;
223
+ const maxItems =
224
+ turnLimit === undefined ? policy.maxItems : (policy.maxTurnItems ?? policy.maxItems);
225
for (let index = end - 1; index >= 0; index -= 1) {
226
const row = input.items[index]!;
241
- const rowBytes = turnLimit === undefined ? rowCost(row) : 0;
227
+ const rowBytes = rowCost(row);
228
if (
229
selected.length > 0 &&
244
- (turnLimit === undefined
245
- ? selected.length >= policy.maxItems || encodedBytes + rowBytes > policy.maxEncodedBytes
246
- : userTurns >= turnLimit || rawTurns >= THREAD_HISTORY_MAX_RAW_TURNS)
230
+ (selected.length >= maxItems ||
231
+ encodedBytes + rowBytes > policy.maxEncodedBytes ||
232
+ (turnLimit !== undefined &&
233
+ (userTurns >= turnLimit || rawTurns >= THREAD_HISTORY_MAX_RAW_TURNS)))
234
) {
235
break;
236
}
@@ -252,6 +239,10 @@ function selectOlderTimelinePage<Row extends HistoryRow>(input: {
239
if (isThreadHistoryUserTurn(row.item)) userTurns += 1;
240
if (turnStarts[index]) rawTurns += 1;
241
}
242
+ // Inside a turn longer than the window, no selected row starts a user turn.
243
+ // Later pages and the snapshot query see only such rows and use `maxItems`,
244
+ // so this page uses it too.
245
+ if (userTurns === 0) selected.splice(policy.maxItems);
246
selected.reverse();
247
248
const oldest = selected[0];
@@ -307,6 +298,44 @@ function findCursorIndex(
298
return Math.min(cursor.p, items.length);
299
}
300
301
+/**
302
+ * Older pages allow twice the turns, and a targeted page widens further so it
303
+ * reaches `throughEntryId`. Callers that re-bound a page must reuse this policy
304
+ * or they drop the target again.
305
+ */
306
+export function olderHistoryPagePolicy<Row extends HistoryRow>(input: {
307
+ readonly items: ReadonlyArray<Row>;
308
+ readonly cursor: string;
309
+ readonly policy?: ThreadHistoryPagePolicy | undefined;
310
+ readonly throughEntryId?: string | undefined;
311
+}): ThreadHistoryPagePolicy {
312
+ const policy = input.policy ?? {
313
+ ...THREAD_HISTORY_PAGE_POLICY,
314
+ maxUserTurns: OLDER_THREAD_USER_TURN_LIMIT,
315
+ };
316
+ if (input.throughEntryId === undefined) return policy;
317
+ const anchorIndex = findCursorIndex(input.items, decodeThreadHistoryCursor(input.cursor));
318
+ const targetIndex = input.items.findIndex(
319
+ (row) => (row.item.messageId ?? row.item.id) === input.throughEntryId,
320
+ );
321
+ if (targetIndex < 0 || targetIndex >= anchorIndex) return policy;
322
+ const turns = input.items
323
+ .slice(targetIndex, anchorIndex)
324
+ .filter((row) => isThreadHistoryUserTurn(row.item)).length;
325
+ return {
326
+ ...policy,
327
+ maxUserTurns: Math.min(
328
+ OLDER_THREAD_USER_TURN_LIMIT * 2,
329
+ Math.max(
330
+ OLDER_THREAD_USER_TURN_LIMIT,
331
+ turns + (isThreadHistoryUserTurn(input.items[targetIndex]!.item) ? 0 : 1),
332
+ ),
333
+ ),
334
+ maxItems: policy.maxItems * 2,
335
+ maxTurnItems: (policy.maxTurnItems ?? policy.maxItems) * 2,
336
+ };
337
+}
338
+
339
export function selectHistoryPageFromCursor<Row extends HistoryRow>(input: {
340
readonly items: ReadonlyArray<Row>;
341
readonly cursor: string;
@@ -316,41 +345,42 @@ export function selectHistoryPageFromCursor<Row extends HistoryRow>(input: {
345
readonly throughEntryId?: string | undefined;
346
}): SelectTimelinePageResult<Row> {
347
const decoded = decodeThreadHistoryCursor(input.cursor);
319
- const anchorIndex = findCursorIndex(input.items, decoded);
320
- let policy = input.policy ?? {
321
- ...THREAD_HISTORY_PAGE_POLICY,
322
- maxUserTurns: OLDER_THREAD_USER_TURN_LIMIT,
323
- };
324
- if (input.throughEntryId !== undefined) {
325
- const targetIndex = input.items.findIndex(
326
- (row) => (row.item.messageId ?? row.item.id) === input.throughEntryId,
327
- );
328
- if (targetIndex >= 0 && targetIndex < anchorIndex) {
329
- const turns = input.items
330
- .slice(targetIndex, anchorIndex)
331
- .filter((row) => isThreadHistoryUserTurn(row.item)).length;
332
- policy = {
333
- ...policy,
334
- maxUserTurns: Math.min(
335
- OLDER_THREAD_USER_TURN_LIMIT * 2,
336
- Math.max(
337
- OLDER_THREAD_USER_TURN_LIMIT,
338
- turns + (isThreadHistoryUserTurn(input.items[targetIndex]!.item) ? 0 : 1),
339
- ),
340
- ),
341
- maxItems: policy.maxItems * 2,
342
- };
343
- }
344
- }
348
return selectOlderTimelinePage({
349
items: input.items,
347
- exclusiveEndIndex: anchorIndex,
350
+ exclusiveEndIndex: findCursorIndex(input.items, decoded),
351
snapshotSequence: input.snapshotSequence,
352
...(input.rowEncodedBytes === undefined ? {} : { rowEncodedBytes: input.rowEncodedBytes }),
350
- policy,
353
+ policy: olderHistoryPagePolicy(input),
354
});
355
}
356
357
+/**
358
+ * Row and byte budgets can split a turn between an interrupt result and its
359
+ * older request. Clients read a superseded result without a request as a
360
+ * legacy steer and hide it, so a page carries the requests its results need.
361
+ */
362
+export function missingInterruptRequests<Row extends HistoryRow>(
363
+ items: ReadonlyArray<Row>,
364
+ page: ReadonlyArray<Pick<HistoryRow, "item" | "sourceThreadId" | "sourceItemId">>,
365
+): Row[] {
366
+ const runs = new Set<string>();
367
+ for (const row of page) {
368
+ if (row.item.type === "run_interrupt_result" && row.item.runId != null)
369
+ runs.add(row.item.runId);
370
+ }
371
+ for (const row of page) {
372
+ if (row.item.type === "run_interrupt_request" && row.item.runId != null)
373
+ runs.delete(row.item.runId);
374
+ }
375
+ if (runs.size === 0) return [];
376
+ return items.filter(
377
+ (row) =>
378
+ row.item.type === "run_interrupt_request" &&
379
+ row.item.runId != null &&
380
+ runs.has(row.item.runId),
381
+ );
382
+}
383
+
384
function isLocalProjectedRow(
385
projection: OrchestrationV2ThreadProjection,
386
row: OrchestrationV2ProjectedTurnItem,
@@ -529,11 +559,7 @@ export function buildBoundedThreadProjection(input: {
559
policy.maxEncodedBytes / 2,
560
policy.maxEncodedBytes - dependencyReserve - controlBytes - 1_024,
561
);
532
- const windowPolicy: ThreadHistoryPagePolicy = {
533
- maxUserTurns: policy.maxUserTurns,
534
- maxItems: policy.maxItems,
535
- maxEncodedBytes: windowBudget,
536
- };
562
+ const windowPolicy: ThreadHistoryPagePolicy = { ...policy, maxEncodedBytes: windowBudget };
563
564
const window = selectRecentTimelineWindow({
565
items: controlProjection.visibleTurnItems,
@@ -604,9 +630,5 @@ export function buildBoundedThreadProjection(input: {
630
historyCursor: window.nextCursor,
631
hasMoreHistory: window.hasMoreHistory,
632
latestLocalTurnOrdinal,
607
- payloadBudgetExceeded:
608
- controlBytes > policy.maxEncodedBytes ||
609
- timelineTextExceedsBudget(projection, policy.maxEncodedBytes) ||
610
- bytesOfJson(projection) > policy.maxEncodedBytes,
633
};
634
}
apps/server/src/ws.ts
+3
-4
@@ -1968,13 +1968,12 @@ export const layerWsRpc = (
1968
rowLimit: THREAD_HISTORY_SNAPSHOT_ROW_LIMIT,
1969
})
1970
.pipe(
1971
- Effect.map((snapshot) =>
1972
- projectThreadProjectionForWire(
1971
+ Effect.map(
1972
+ (snapshot) =>
1973
buildBoundedThreadProjection({
1974
- projection: snapshot.projection,
1974
+ projection: projectThreadProjectionForWire(snapshot.projection),
1975
snapshotSequence: snapshot.snapshotSequence,
1976
}).projection,
1977
- ),
1977
),
1978
Effect.mapError(
1979
(cause) =>
docs/internals/performance-regressions.md
+13
-5
@@ -12,8 +12,11 @@ client can produce reassuring timings while missing the active transport path.
12
13
The v2 checks pin these invariants:
14
15
-- Client cold opens target 75 recent timeline rows and about 1 MiB of encoded data. Required
16
- control records and the at-least-one-row rule can exceed the byte target; it is not a hard cap.
15
+- Cold opens and history pages stop at about 1 MiB of encoded rows. A window that holds a user
16
+ turn also stops at 10 user turns (20 on older pages) or 500 rows, so ordinary turns stay whole.
17
+ Any other window, including the inside of one turn longer than 500 rows, stops at 75 rows. The
18
+ snapshot query applies the same rule before it decodes payloads. Required control records and
19
+ the at-least-one-row rule can exceed the byte target; it is not a hard cap.
20
- The bounded snapshot does not retain the full duplicate conversation-message table.
21
- Older activity is fetched in bounded HTTP pages and merged without disturbing the live scroll
22
window.
@@ -29,8 +32,10 @@ The v2 checks pin these invariants:
32
projects small can increase server allocations on repeated large tool updates.
33
- Raw command output, dynamic-tool result bodies, and inline file-change bodies are omitted at
34
the wire boundary, including small outputs. Explicit failure flags and bounded result IDs
32
- preserve status and grouped action counts without shipping those bodies. Persisted events
33
- remain complete; the existing diff endpoints still provide file content when requested.
35
+ preserve status and grouped action counts without shipping those bodies. Subagent prompts and
36
+ results, reasoning text, command lines, search results, and checkpoint file lists still ship.
37
+ Persisted events remain complete; the existing diff endpoints still provide file content when
38
+ requested.
39
Explicit cross-environment transcript exports preserve full tool bodies so the destination
40
agent can read the context. The export rejects timeline JSON above the file attachment limit
41
before sending it; the client still applies its attachment limit to the complete file.
@@ -57,7 +62,10 @@ transport performance fixtures validate contract encoding and compare pre-compre
62
for the same synthetic workload, preserving historical application-object counts separately.
63
These are neither compressed WebSocket captures nor measurements of server RSS, and command
64
fixtures exclude unrelated settings calls and subscription events. Payload budgets belong in
60
-these tests so regressions fail locally.
65
+these tests so regressions fail locally. The transfer budget integration test
66
+(`apps/server/integration/transferBudgetV2.integration.test.ts`) caps the decoded bytes and rows
67
+of the compact bounded snapshot that web and mobile load, and of one older page, for a 900-row
68
+agent turn.
69
70
## Event store and startup
71
packages/client-runtime/src/platform/orchestrationCache.test.ts
+10
-4
@@ -74,14 +74,20 @@ describe("orchestration cache envelopes", () => {
74
expect(decoded.visibleTurnItems.find((entry) => entry.item.id === item.id)?.item).toEqual(item);
75
});
76
77
- it("rejects thread snapshots saved before queued-run items were kept, but not shells", () => {
78
- const staleThread = encodeStoredThreadSnapshotJson({
77
+ it("rejects thread snapshots saved before human history was bounded, but not shells", () => {
78
+ const currentThread = encodeStoredThreadSnapshotJson({
79
schemaVersion: ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
80
environmentId,
81
threadId: v2ThreadId,
82
snapshot: { snapshotSequence: 4, projection: v2Projection },
83
- }).replace(`"schemaVersion":${ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION}`, `"schemaVersion":3`);
84
- expect(() => decodeStoredThreadSnapshotJson(staleThread)).toThrow();
83
+ });
84
+ for (const staleVersion of [3, 4]) {
85
+ const staleThread = currentThread.replace(
86
+ `"schemaVersion":${ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION}`,
87
+ `"schemaVersion":${staleVersion}`,
88
+ );
89
+ expect(() => decodeStoredThreadSnapshotJson(staleThread)).toThrow();
90
+ }
91
const shell = encodeStoredShellSnapshot({
92
schemaVersion: ORCHESTRATION_CACHE_SCHEMA_VERSION,
93
environmentId,
packages/client-runtime/src/platform/orchestrationCache.ts
+2
-1
@@ -10,7 +10,8 @@ import * as Option from "effect/Option";
10
import * as Schema from "effect/Schema";
11
12
export const ORCHESTRATION_CACHE_SCHEMA_VERSION = 3 as const;
13
-export const ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION = 4 as const;
13
+// Older caches may contain human turns that bypassed server history budgets.
14
+export const ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION = 5 as const;
15
16
export const StoredOrchestrationShellSnapshot = Schema.Struct({
17
schemaVersion: Schema.Literal(ORCHESTRATION_CACHE_SCHEMA_VERSION),
packages/client-runtime/src/state/boundedThreadSnapshotHttp.test.ts
-1
@@ -115,7 +115,6 @@ const boundedBody = (compact: boolean) => ({
115
historyCursor: "bounded-cursor",
116
hasMoreHistory: true,
117
latestLocalTurnOrdinal: 2,
118
- payloadBudgetExceeded: false,
118
...(compact ? { turnItemsOmitLocalVisible: true } : {}),
119
});
120
packages/client-runtime/src/state/threads-atoms.test.ts
-1
@@ -339,7 +339,6 @@ describe("createEnvironmentThreadStateAtoms", () => {
339
historyCursor: "socket-older-1",
340
hasMoreHistory: true,
341
latestLocalTurnOrdinal: 4,
342
- payloadBudgetExceeded: false,
342
});
343
yield* Queue.offer(subscription.events, { kind: "synchronized" });
344
yield* observeState(
packages/client-runtime/src/state/threads-sync.test.ts
+65
-3
@@ -20,6 +20,7 @@ import * as Option from "effect/Option";
20
import * as Queue from "effect/Queue";
21
import * as Ref from "effect/Ref";
22
import * as Scope from "effect/Scope";
23
+import * as Schema from "effect/Schema";
24
import * as Stream from "effect/Stream";
25
import * as SubscriptionRef from "effect/SubscriptionRef";
26
import * as TestClock from "effect/testing/TestClock";
@@ -36,6 +37,11 @@ import {
37
import * as ConnectionWakeups from "../connection/wakeups.ts";
38
import * as EnvironmentSupervisor from "../connection/supervisor.ts";
39
import * as Persistence from "../platform/persistence.ts";
40
+import {
41
+ ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
42
+ StoredOrchestrationThreadSnapshot,
43
+ decodeOrDiscardOrchestrationCache,
44
+} from "../platform/orchestrationCache.ts";
45
import * as RpcSession from "../rpc/session.ts";
46
import { v2Projection, v2ThreadId } from "./orchestrationV2TestFixtures.ts";
47
import { EMPTY_THREAD_HISTORY_META } from "./threadHistoryMerge.ts";
@@ -328,6 +334,65 @@ const deleted = (sequence = 3): OrchestrationV2ThreadStreamItem => {
334
};
335
336
describe("EnvironmentThreads", () => {
337
+ it.effect("discards an oversized version-4 cache and requests a fresh bounded snapshot", () =>
338
+ Effect.gen(function* () {
339
+ const item: OrchestrationV2TurnItem = {
340
+ id: TurnItemId.make("old-unbounded-cache-item"),
341
+ threadId: THREAD_ID,
342
+ runId: null,
343
+ nodeId: null,
344
+ providerThreadId: null,
345
+ providerTurnId: null,
346
+ nativeItemRef: null,
347
+ parentItemId: null,
348
+ ordinal: 1,
349
+ status: "completed",
350
+ title: null,
351
+ startedAt: BASE_PROJECTION.updatedAt,
352
+ completedAt: BASE_PROJECTION.updatedAt,
353
+ updatedAt: BASE_PROJECTION.updatedAt,
354
+ type: "system_notice",
355
+ message: "x".repeat(1_100_000),
356
+ };
357
+ const schema = Schema.fromJsonString(StoredOrchestrationThreadSnapshot);
358
+ const encoded = yield* Schema.encodeEffect(schema)({
359
+ schemaVersion: ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION,
360
+ environmentId: TARGET.environmentId,
361
+ threadId: THREAD_ID,
362
+ snapshot: {
363
+ snapshotSequence: CACHED_SNAPSHOT_SEQUENCE,
364
+ projection: { ...BASE_PROJECTION, turnItems: [item] },
365
+ },
366
+ });
367
+ const stale = encoded.replace(
368
+ `"schemaVersion":${ORCHESTRATION_THREAD_CACHE_SCHEMA_VERSION}`,
369
+ '"schemaVersion":4',
370
+ );
371
+ let discarded = false;
372
+ const h = yield* makeHarness({
373
+ loadCached: decodeOrDiscardOrchestrationCache(
374
+ Schema.decodeUnknownEffect(schema)(stale).pipe(
375
+ Effect.map((stored) => Option.some(stored.snapshot)),
376
+ ),
377
+ Effect.sync(() => {
378
+ discarded = true;
379
+ }),
380
+ ),
381
+ httpSnapshot: {
382
+ _tag: "present",
383
+ snapshot: { snapshotSequence: CACHED_SNAPSHOT_SEQUENCE, projection: BASE_PROJECTION },
384
+ history: { historyCursor: "fresh-bounded-cursor", hasMoreHistory: true },
385
+ },
386
+ });
387
+ const state = yield* awaitThreadState(h.observed, (value) => value.status === "live");
388
+ expect(discarded).toBe(true);
389
+ expect(yield* Ref.get(h.loaderCalls)).toBe(1);
390
+ expect(Option.getOrThrow(state.data)).toEqual(BASE_PROJECTION);
391
+ expect(state.history.historyCursor).toBe("fresh-bounded-cursor");
392
+ expect(state.history.hasMoreHistory).toBe(true);
393
+ }),
394
+ );
395
+
396
it.effect("loads the server thread when its local cache read fails", () =>
397
Effect.gen(function* () {
398
const h = yield* makeHarness({
@@ -1084,7 +1149,6 @@ describe("EnvironmentThreads", () => {
1149
historyCursor: "socket-history-cursor",
1150
hasMoreHistory: true,
1151
latestLocalTurnOrdinal: 47,
1087
- payloadBudgetExceeded: false,
1152
});
1153
1154
const state = yield* awaitThreadState(
@@ -1199,7 +1263,6 @@ describe("EnvironmentThreads", () => {
1263
historyCursor: "progressive-cursor",
1264
hasMoreHistory: true,
1265
latestLocalTurnOrdinal: 47,
1202
- payloadBudgetExceeded: false,
1266
});
1267
yield* awaitThreadState(
1268
harness.observed,
@@ -1308,7 +1371,6 @@ describe("EnvironmentThreads", () => {
1371
historyCursor: "compact-cursor",
1372
hasMoreHistory: true,
1373
latestLocalTurnOrdinal: 2,
1311
- payloadBudgetExceeded: false,
1374
turnItemsOmitLocalVisible: true,
1375
});
1376
packages/contracts/src/orchestrationV2.ts
-2
@@ -3324,7 +3324,6 @@ export const OrchestrationV2ThreadBoundedSnapshot = Schema.Struct({
3324
historyCursor: Schema.NullOr(TrimmedNonEmptyString),
3325
hasMoreHistory: Schema.Boolean,
3326
latestLocalTurnOrdinal: Schema.NullOr(NonNegativeInt),
3327
- payloadBudgetExceeded: Schema.optional(Schema.Boolean),
3327
/**
3328
* Set only for clients that opted in: `projection.turnItems` omits the items
3329
* of local visible rows, which lead the full list. Clients must restore them
@@ -3408,7 +3407,6 @@ export const OrchestrationV2ThreadStreamItem = Schema.Union([
3407
historyCursor: Schema.optionalKey(Schema.NullOr(TrimmedNonEmptyString)),
3408
hasMoreHistory: Schema.optionalKey(Schema.Boolean),
3409
latestLocalTurnOrdinal: Schema.optionalKey(Schema.NullOr(NonNegativeInt)),
3411
- payloadBudgetExceeded: Schema.optionalKey(Schema.Boolean),
3410
turnItemsOmitLocalVisible: Schema.optionalKey(Schema.Literal(true)),
3411
}),
3412
Schema.Struct({