The best way to control Claude Code, Codex and more from any computer or phone
perf: huge checkpoints ship up to 75x smaller to clients (#27110)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Oct 29, 2026 at 13:17 UTC
7f39a860d9775e1c5e7cf9c0655d719d966f64f6
10 files changed
+167
-38
apps/mobile/src/features/review/reviewModel.ts
+5
-2
@@ -1,6 +1,9 @@
1
import { parsePatchFiles } from "@pierre/diffs/utils/parsePatchFiles";
2
import type { ChangeTypes, FileDiffMetadata } from "@pierre/diffs/types";
3
-import type { ThreadCheckpointSummary } from "@t3tools/client-runtime/state/thread-checkpoints";
3
+import {
4
+ checkpointFileTotals,
5
+ type ThreadCheckpointSummary,
6
+} from "@t3tools/client-runtime/state/thread-checkpoints";
7
import type { ReviewDiffPreviewSource } from "@t3tools/contracts";
8
import { quoteGitPatchPath } from "@t3tools/shared/gitPatchPath";
9
import * as Arr from "effect/Array";
@@ -107,7 +110,7 @@ function checkpointTitle(checkpoint: ThreadCheckpointSummary): string {
110
}
111
112
function checkpointSubtitle(checkpoint: ThreadCheckpointSummary): string {
110
- const fileCount = checkpoint.files.length;
113
+ const fileCount = checkpointFileTotals(checkpoint).count;
114
if (checkpoint.status !== "ready") {
115
return `Diff ${checkpoint.status}`;
116
}
apps/server/src/orchestration-v2/ThreadStream.ts
+6
-4
@@ -10,7 +10,10 @@ import {
10
buildBoundedThreadProjection,
11
type BoundedProjectionResult,
12
} from "./threadHistoryPaging.ts";
13
-import { projectThreadProjectionForWire } from "./WireProjection.ts";
13
+import {
14
+ capProjectionCheckpointFilesForWire,
15
+ projectThreadProjectionForWire,
16
+} from "./WireProjection.ts";
17
18
export const THREAD_RESUME_MAX_REPLAY_EVENTS = 128;
19
@@ -44,10 +47,9 @@ export function boundedSnapshotResponseFields(input: {
47
readonly compactIds: boolean;
48
}) {
49
const { bounded } = input;
50
+ const capped = capProjectionCheckpointFilesForWire(bounded.projection);
51
// Dedupe keeps shared items one object, which the compaction's identity check needs.
48
- const projection = input.dedupeBodies
49
- ? dedupeSnapshotBodies(bounded.projection)
50
- : bounded.projection;
52
+ const projection = input.dedupeBodies ? dedupeSnapshotBodies(capped) : capped;
53
const compactProjection = input.compactTurnItems ? omitLocalVisibleTurnItems(projection) : null;
54
return {
55
projection: compactProjection ?? projection,
apps/server/src/orchestration-v2/WireProjection.test.ts
+43
@@ -1,4 +1,7 @@
1
import {
2
+ CheckpointId,
3
+ CheckpointRef,
4
+ CheckpointScopeId,
5
MessageId,
6
ContextHandoffId,
7
ProviderThreadId,
@@ -381,6 +384,46 @@ describe("live body deduper", () => {
384
]);
385
});
386
387
+ it("caps a large checkpoint's files for the wire and still dedupes its item", () => {
388
+ const files = Array.from({ length: 250 }, (_, index) => ({
389
+ path: `vendor/file-${index}.ts`,
390
+ kind: "modified",
391
+ additions: 2,
392
+ deletions: 1,
393
+ }));
394
+ const checkpointId = CheckpointId.make("checkpoint-large");
395
+ const scopeId = CheckpointScopeId.make("scope-large");
396
+ const captured = event(1, {
397
+ type: "checkpoint.captured",
398
+ payload: {
399
+ id: checkpointId,
400
+ threadId: base.threadId,
401
+ scopeId,
402
+ runId: null,
403
+ nodeId: NodeId.make("node-large"),
404
+ parentCheckpointId: null,
405
+ ordinalWithinScope: 1,
406
+ appRunOrdinal: null,
407
+ ref: CheckpointRef.make("refs/t3/checkpoints/large"),
408
+ status: "ready",
409
+ files,
410
+ capturedAt: at,
411
+ },
412
+ });
413
+ const item = event(2, {
414
+ type: "turn-item.updated",
415
+ payload: { ...base, type: "checkpoint", checkpointId, scopeId, files },
416
+ });
417
+ const dedupe = makeLiveBodyDeduper();
418
+ const [record, card] = [captured, item].map((streamed) =>
419
+ dedupe({ ...streamed, event: projectDomainEventForWire(streamed.event) }),
420
+ );
421
+
422
+ const filesTotal = { count: 250, additions: 500, deletions: 250 };
423
+ expect(payloadOf(record!)).toMatchObject({ files: files.slice(0, 200), filesTotal });
424
+ expect(payloadOf(card!)).toMatchObject({ files: [], filesOmitted: true, filesTotal });
425
+ });
426
+
427
it("ships a reply whole when its message arrives after it", () => {
428
const first = reply(1, "a");
429
expect([first, message(2, "a")].map(makeLiveBodyDeduper())[0]).toBe(first);
apps/server/src/orchestration-v2/WireProjection.ts
+57
-1
@@ -21,6 +21,8 @@ import {
21
toolOutputIndicatesFailure,
22
} from "@t3tools/shared/toolOutput";
23
24
+// A checkpoint over vendored or generated trees can list 15k+ files; the card needs a prefix.
25
+const MAX_WIRE_CHECKPOINT_FILES = 200;
26
const MAX_DETAIL_STRING_BYTES = 32_768;
27
const MAX_DYNAMIC_VALUE_BYTES = 16_384;
28
const MAX_ON_DEMAND_BYTES = 256 * 1024;
@@ -96,8 +98,59 @@ function summarizeDynamicValue(value: unknown): unknown {
98
};
99
}
100
101
+type CheckpointFiles = Pick<OrchestrationV2Checkpoint, "files" | "filesTotal">;
102
+
103
+// Same input, same output object: snapshot compaction relies on shared item identity.
104
+const cappedCheckpointFiles = new WeakMap<object, object>();
105
+
106
+function capCheckpointFiles<T extends CheckpointFiles>(value: T): T {
107
+ if (value.files.length <= MAX_WIRE_CHECKPOINT_FILES || value.filesTotal !== undefined) {
108
+ return value;
109
+ }
110
+ const cached = cappedCheckpointFiles.get(value);
111
+ if (cached !== undefined) return cached as T;
112
+ let additions = 0;
113
+ let deletions = 0;
114
+ for (const file of value.files) {
115
+ additions += file.additions;
116
+ deletions += file.deletions;
117
+ }
118
+ const capped = {
119
+ ...value,
120
+ files: value.files.slice(0, MAX_WIRE_CHECKPOINT_FILES),
121
+ filesTotal: { count: value.files.length, additions, deletions },
122
+ };
123
+ cappedCheckpointFiles.set(value, capped);
124
+ return capped;
125
+}
126
+
127
+/** Idempotent; bounded snapshots that skip `projectThreadProjectionForWire` still need it. */
128
+export function capProjectionCheckpointFilesForWire(
129
+ projection: OrchestrationV2ThreadProjection,
130
+): OrchestrationV2ThreadProjection {
131
+ const checkpoints = projection.checkpoints.map(capCheckpointFiles);
132
+ const turnItems = projection.turnItems.map(capCheckpointItemFiles);
133
+ const visibleTurnItems = projection.visibleTurnItems.map((row) => {
134
+ const item = capCheckpointItemFiles(row.item);
135
+ return item === row.item ? row : { ...row, item };
136
+ });
137
+ const unchanged = (next: ReadonlyArray<unknown>, previous: ReadonlyArray<unknown>) =>
138
+ next.every((value, index) => value === previous[index]);
139
+ return unchanged(checkpoints, projection.checkpoints) &&
140
+ unchanged(turnItems, projection.turnItems) &&
141
+ unchanged(visibleTurnItems, projection.visibleTurnItems)
142
+ ? projection
143
+ : { ...projection, checkpoints, turnItems, visibleTurnItems };
144
+}
145
+
146
+function capCheckpointItemFiles(item: OrchestrationV2TurnItem): OrchestrationV2TurnItem {
147
+ return item.type === "checkpoint" ? capCheckpointFiles(item) : item;
148
+}
149
+
150
export function projectTurnItemForWire(item: OrchestrationV2TurnItem): OrchestrationV2TurnItem {
151
switch (item.type) {
152
+ case "checkpoint":
153
+ return capCheckpointFiles(item);
154
case "handoff": {
155
const { summary: _summary, ...projected } = item;
156
return projected;
@@ -241,6 +294,7 @@ export function projectThreadProjectionForWire(
294
};
295
return {
296
...projection,
297
+ checkpoints: projection.checkpoints.map(capCheckpointFiles),
298
contextHandoffs: projection.contextHandoffs.map(projectContextHandoffForWire),
299
turnItems: projection.turnItems.map(project),
300
visibleTurnItems: projection.visibleTurnItems.map((row) => ({
@@ -257,7 +311,9 @@ export function projectDomainEventForWire(
311
? { ...event, payload: projectTurnItemForWire(event.payload) }
312
: event.type === "context-handoff.updated"
313
? { ...event, payload: projectContextHandoffForWire(event.payload) }
260
- : event;
314
+ : event.type === "checkpoint.captured"
315
+ ? { ...event, payload: capCheckpointFiles(event.payload) }
316
+ : event;
317
}
318
319
const LIVE_DEDUPE_MEMORY = 32;
apps/web/src/components/ChatView.logic.ts
+4
-6
@@ -3,6 +3,7 @@ import {
3
deriveLatestThreadRun,
4
deriveThreadRuntime,
5
} from "@t3tools/client-runtime/state/thread-execution";
6
+import { checkpointFileTotals } from "@t3tools/client-runtime/state/thread-checkpoints";
7
import { derivePendingBackgroundWork } from "@t3tools/shared/orchestrationV2PendingBackgroundWork";
8
import {
9
latestUnheldRun,
@@ -218,7 +219,7 @@ export function shouldOpenProactiveTurnDiff(input: {
219
}
220
221
export function resolveProactiveTurnDiffAction(input: {
221
- checkpoint: Pick<TurnDiffSummary, "status" | "files"> | undefined;
222
+ checkpoint: Pick<TurnDiffSummary, "status" | "files" | "filesTotal"> | undefined;
223
isGitRepo: boolean | undefined;
224
}): "defer" | "ignore" | "open" {
225
if (input.checkpoint === undefined || input.checkpoint.status === "missing") return "defer";
@@ -230,11 +231,8 @@ export function resolveProactiveTurnDiffAction(input: {
231
) {
232
return "ignore";
233
}
233
- const changedLines = input.checkpoint.files.reduce(
234
- (total, file) => total + file.additions + file.deletions,
235
- 0,
236
- );
237
- return input.checkpoint.files.length >= 3 || changedLines >= 50 ? "open" : "ignore";
234
+ const totals = checkpointFileTotals(input.checkpoint);
235
+ return totals.count >= 3 || totals.additions + totals.deletions >= 50 ? "open" : "ignore";
236
}
237
238
/** Mark reactivated Diff tabs to preserve review scope. Already-active tabs must not leave a marker for
apps/web/src/components/chat/ChangedFilesTree.tsx
+23
-11
@@ -1,11 +1,7 @@
1
-import { type RunId } from "@t3tools/contracts";
1
+import { type OrchestrationV2CheckpointFileTotals, type RunId } from "@t3tools/contracts";
2
import { type MouseEvent, type ReactNode, memo, useLayoutEffect, useRef, useState } from "react";
3
import { type TurnDiffFileChange } from "../../types";
4
-import {
5
- buildTurnDiffTree,
6
- summarizeTurnDiffStats,
7
- type TurnDiffTreeNode,
8
-} from "../../lib/turnDiffTree";
4
+import { buildTurnDiffTree, type TurnDiffTreeNode } from "../../lib/turnDiffTree";
5
import { ChevronRightIcon, FileDiffIcon } from "lucide-react";
6
import { ChevronsDownUp, ChevronsUpDown, Folder, FolderClosed } from "lucide";
7
import { cn } from "~/lib/utils";
@@ -30,7 +26,9 @@ type ChangedFileContextMenuHandler = (filePath: string, event: MouseEvent) => vo
26
27
export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
28
runId: RunId;
29
+ /** May be a prefix of the changed files; `totals` covers all of them. */
30
files: ReadonlyArray<TurnDiffFileChange>;
31
+ totals: OrchestrationV2CheckpointFileTotals;
32
allDirectoriesExpanded: boolean;
33
resolvedTheme: "light" | "dark";
34
onToggleAllDirectories: () => void;
@@ -40,13 +38,14 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
38
const {
39
runId,
40
files,
41
+ totals,
42
allDirectoriesExpanded,
43
resolvedTheme,
44
onToggleAllDirectories,
45
onOpenTurnDiff,
46
onFileContextMenu,
47
} = props;
49
- const summaryStat = summarizeTurnDiffStats(files);
48
+ const hiddenFileCount = totals.count - files.length;
49
const hasDirectories = files.some((file) => /[/\\]/.test(file.path));
50
51
return (
@@ -60,12 +59,12 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
59
>
60
<div className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 text-xs font-medium text-foreground">
61
<span>
63
- {files.length} changed file{files.length === 1 ? "" : "s"}
62
+ {totals.count.toLocaleString()} changed file{totals.count === 1 ? "" : "s"}
63
</span>
65
- {hasNonZeroStat(summaryStat) && (
64
+ {hasNonZeroStat(totals) && (
65
<DiffStatLabel
67
- additions={summaryStat.additions}
68
- deletions={summaryStat.deletions}
66
+ additions={totals.additions}
67
+ deletions={totals.deletions}
68
layout="inline"
69
className="text-xs leading-4"
70
/>
@@ -126,6 +125,19 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
125
onOpenTurnDiff={onOpenTurnDiff}
126
onFileContextMenu={onFileContextMenu}
127
/>
128
+ {hiddenFileCount > 0 && (
129
+ <div className="px-3 pb-2">
130
+ <Button
131
+ type="button"
132
+ size="xs"
133
+ variant="ghost-muted"
134
+ onClick={() => onOpenTurnDiff(runId, files[0]?.path)}
135
+ >
136
+ {hiddenFileCount.toLocaleString()} more file{hiddenFileCount === 1 ? "" : "s"} in the
137
+ full diff
138
+ </Button>
139
+ </div>
140
+ )}
141
</div>
142
);
143
});
apps/web/src/components/chat/TimelineAssistantRows.tsx
+2
@@ -9,6 +9,7 @@ import { Button } from "../ui/button";
9
import { ProposedPlanCard } from "./ProposedPlanCard";
10
import { HtmlRenderFrame } from "./HtmlRenderFrame";
11
import { McpAppFrame } from "./McpAppFrame";
12
+import { checkpointFileTotals } from "@t3tools/client-runtime/state/thread-checkpoints";
13
import { ChangedFilesCard } from "./ChangedFilesTree";
14
import { useFileContextMenuHandler } from "../../fileContextMenu";
15
import { useProject, useThreadShell } from "../../state/entities";
@@ -347,6 +348,7 @@ function AssistantChangedFilesSectionInner({
348
<ChangedFilesCard
349
runId={turnSummary.runId}
350
files={checkpointFiles}
351
+ totals={checkpointFileTotals(turnSummary)}
352
allDirectoriesExpanded={allDirectoriesExpanded}
353
resolvedTheme={resolvedTheme}
354
onToggleAllDirectories={() =>
apps/web/src/lib/turnDiffTree.ts
-14
@@ -98,20 +98,6 @@ function toTreeNodes(directory: MutableDirectoryNode): TurnDiffTreeNode[] {
98
return [...subdirectories, ...files];
99
}
100
101
-export function summarizeTurnDiffStats(files: ReadonlyArray<TurnDiffFileChange>): TurnDiffStat {
102
- return files.reduce(
103
- (acc, file) => {
104
- const stat = readStat(file);
105
- if (!stat) return acc;
106
- return {
107
- additions: acc.additions + stat.additions,
108
- deletions: acc.deletions + stat.deletions,
109
- };
110
- },
111
- { additions: 0, deletions: 0 },
112
- );
113
-}
114
-
101
export function buildTurnDiffTree(files: ReadonlyArray<TurnDiffFileChange>): TurnDiffTreeNode[] {
102
const root: MutableDirectoryNode = {
103
name: "",
packages/client-runtime/src/state/threadCheckpoints.ts
+17
@@ -3,6 +3,7 @@ import type {
3
CheckpointRef,
4
CheckpointScopeId,
5
MessageId,
6
+ OrchestrationV2CheckpointFileTotals,
7
OrchestrationV2ThreadProjection,
8
RunId,
9
} from "@t3tools/contracts";
@@ -15,12 +16,14 @@ export interface ThreadCheckpointSummary {
16
readonly checkpointTurnCount: number;
17
readonly checkpointRef: CheckpointRef;
18
readonly status: "ready" | "missing" | "error" | "stale";
19
+ /** A prefix of the changed files when `filesTotal` is set; see `checkpointFileTotals`. */
20
readonly files: ReadonlyArray<{
21
readonly path: string;
22
readonly kind: string;
23
readonly additions: number;
24
readonly deletions: number;
25
}>;
26
+ readonly filesTotal?: OrchestrationV2CheckpointFileTotals;
27
readonly assistantMessageId: MessageId | null;
28
readonly completedAt: string;
29
}
@@ -43,9 +46,23 @@ export function deriveThreadCheckpointSummaries(
46
checkpointRef: checkpoint.ref,
47
status: checkpoint.status,
48
files: checkpoint.files,
49
+ ...(checkpoint.filesTotal === undefined ? {} : { filesTotal: checkpoint.filesTotal }),
50
assistantMessageId,
51
completedAt: DateTime.formatIso(checkpoint.capturedAt),
52
},
53
];
54
});
55
}
56
+
57
+export function checkpointFileTotals(
58
+ checkpoint: Pick<ThreadCheckpointSummary, "files" | "filesTotal">,
59
+): OrchestrationV2CheckpointFileTotals {
60
+ if (checkpoint.filesTotal !== undefined) return checkpoint.filesTotal;
61
+ let additions = 0;
62
+ let deletions = 0;
63
+ for (const file of checkpoint.files) {
64
+ additions += file.additions;
65
+ deletions += file.deletions;
66
+ }
67
+ return { count: checkpoint.files.length, additions, deletions };
68
+}
packages/contracts/src/orchestrationV2.ts
+10
@@ -1349,6 +1349,14 @@ export const OrchestrationV2CheckpointFileSummary = Schema.Struct({
1349
});
1350
export type OrchestrationV2CheckpointFileSummary = typeof OrchestrationV2CheckpointFileSummary.Type;
1351
1352
+/** Sent only when the wire carries a prefix of `files`; the totals cover the full list. */
1353
+export const OrchestrationV2CheckpointFileTotals = Schema.Struct({
1354
+ count: NonNegativeInt,
1355
+ additions: NonNegativeInt,
1356
+ deletions: NonNegativeInt,
1357
+});
1358
+export type OrchestrationV2CheckpointFileTotals = typeof OrchestrationV2CheckpointFileTotals.Type;
1359
+
1360
export const OrchestrationV2Checkpoint = Schema.Struct({
1361
id: CheckpointId,
1362
threadId: ThreadId,
@@ -1361,6 +1369,7 @@ export const OrchestrationV2Checkpoint = Schema.Struct({
1369
ref: CheckpointRef,
1370
status: Schema.Literals(["ready", "missing", "error", "stale"]),
1371
files: Schema.Array(OrchestrationV2CheckpointFileSummary),
1372
+ filesTotal: Schema.optionalKey(OrchestrationV2CheckpointFileTotals),
1373
capturedAt: Schema.DateTimeUtc,
1374
});
1375
export type OrchestrationV2Checkpoint = typeof OrchestrationV2Checkpoint.Type;
@@ -1659,6 +1668,7 @@ export const OrchestrationV2TurnItem = Schema.Union([
1668
checkpointId: CheckpointId,
1669
scopeId: CheckpointScopeId,
1670
files: Schema.Array(OrchestrationV2CheckpointFileSummary),
1671
+ filesTotal: Schema.optionalKey(OrchestrationV2CheckpointFileTotals),
1672
/** Same as the files of checkpoint `checkpointId`. */
1673
filesOmitted: DedupedBodyMarker,
1674
}),