@devries-cameron20 / t3code-1 / commits / 7f39a860d9
Fork 0

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 }),