Skip to content

Commit 7055bea

Browse files
t3dotggclaude
andcommitted
test(server): wire budget sends the shell resume cursor and project identities
The merge of main brought #35225, which types the budget test's opt-in records `Required` against the contracts. This branch adds `resumeFrom` to the shell query and `knownProjectIdentities` to the shell subscribe input, so the server typecheck failed on both records. Both fields differ per request, like the cursors the records already leave out, so each scenario sends its own: - The fleet shell subscribe names the snapshot's project identities. The fixture project is now in a repository; without the digest the subscribe resends it (851 B in 2 messages, over the 200 B and 1 message ceiling). - New row "fleet shell resume check": the HTTP route's answer to a client that holds rows, 18 B. - New row "stale shell reload": the same request from a cursor too old to replay, which gets the snapshot. Co-Authored-By: Claude Fable 5.2 <[email protected]>
1 parent 50deffe commit 7055bea

4 files changed

Lines changed: 105 additions & 20 deletions

File tree

‎apps/server/integration/TransferBudgetReport.integration.ts‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,11 @@ export interface TransferBudgetRun {
7474
readonly fleetShellLegacy: TimelineHttpMeasurement;
7575
/** The shell subscription a cold connect opens from that snapshot's cursor. */
7676
readonly fleetShellSubscribe: SocketOpenMeasurement;
77-
/** A shell resumed from a cursor too old to replay, by a client that reloads over HTTP. */
77+
/** A client that holds that snapshot's rows asks the HTTP route whether they still resume. */
78+
readonly fleetShellResume: TimelineHttpMeasurement;
79+
/** The same question from a cursor too old to replay: the route answers with the snapshot. */
80+
readonly staleShellReload: TimelineHttpMeasurement;
81+
/** A shell resumed over the socket from that old cursor, by a client that reloads over HTTP. */
7882
readonly staleShellResume: SocketOpenMeasurement;
7983
/**
8084
* The compact bounded snapshot of the long thread whose finished runs left todo lists open,
@@ -141,6 +145,7 @@ const SOCKET_BUDGETS = {
141145
longTurnColdOpen: { decodedBytes: LONG_TURN_FINISHED_BUDGET.decodedBytes, messages: 2 },
142146
// These three send no rows. A snapshot in their place is 393 KB for the thread, 42 KB for the shell.
143147
idleThreadResume: { decodedBytes: 200, messages: 1 },
148+
// A subscribe that does not name the snapshot's project identities gets the project again: 851 B.
144149
fleetShellSubscribe: { decodedBytes: 200, messages: 1 },
145150
staleShellResume: { decodedBytes: 400, messages: 2 },
146151
};
@@ -151,6 +156,12 @@ const FLEET_SHELL_BUDGET = {
151156
rows: 27,
152157
};
153158

159+
// The answer is `{"resumable":true}`. A snapshot in its place is 42 KB.
160+
const FLEET_SHELL_RESUME_BUDGET = {
161+
decodedBytes: 100,
162+
rows: 0,
163+
};
164+
154165
// About 14% above the observed 75 KB. The window holds the working run only: 2 nodes, 2 subagents,
155166
// 1 plan, 1 provider turn and the last finished turn's checkpoint. When finished runs ride along
156167
// it holds 82 nodes, 82 subagents, 41 plans, 41 provider turns, 40 checkpoints and 740 KB.
@@ -367,6 +378,8 @@ function scenarioRows(run: TransferBudgetRun): ScenarioRow[] {
367378
run.fleetShellSubscribe,
368379
SOCKET_BUDGETS.fleetShellSubscribe,
369380
),
381+
...httpRows("fleet shell resume check", run.fleetShellResume, FLEET_SHELL_RESUME_BUDGET),
382+
...httpRows("stale shell reload", run.staleShellReload, FLEET_SHELL_BUDGET),
370383
...socketRows("stale shell resume", run.staleShellResume, SOCKET_BUDGETS.staleShellResume),
371384
...httpRows("stale todo list cold open", run.staleTodoColdOpen, STALE_TODO_BUDGET),
372385
...STALE_TODO_RECORD_KINDS.map((kind): ScenarioRow => ({
@@ -439,8 +452,8 @@ export function formatTransferBudgetReport(runs: ReadonlyArray<TransferBudgetRun
439452
"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.",
440453
`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.`,
441454
`The long turn rows read a second thread whose last user turn holds ${LONG_TURN_WORK_ROWS} rows of reasoning, commands, file changes, MCP calls, progress messages, checkpoints, and subagents. While that turn runs, web and mobile load the compact bounded snapshot and then one older page. Once it finishes, its work is deferred: the cold open is read over HTTP as web does and over the socket alone as mobile does, then the first page of the deferred work is loaded as an expanded work group does.`,
442-
"The resume rows open a new socket from a cursor the client already holds: the first thread after one more ordinary turn, the long-turn thread with nothing new, and the shell from a cursor too old to replay.",
443-
`The fleet shell rows read the cold-connect shell after ${SHELL_SETTLED_THREADS} settled threads and ${SHELL_IDLE_SUBAGENTS} idle subagent children are added, then subscribe from that snapshot's cursor. Budgeted reads send the opt-ins current clients send; "older client" rows show the same read without the opt-ins added since row budgets.`,
455+
"The resume rows open a new socket from a cursor the client already holds: the first thread after one more ordinary turn, the long-turn thread with nothing new, and the shell from a cursor too old to replay. A client that holds shell rows first names their cursor to the HTTP shell route: the resume check row is the answer that keeps the rows, and the stale shell reload row is the snapshot that replaces them.",
456+
`The fleet shell rows read the cold-connect shell after ${SHELL_SETTLED_THREADS} settled threads and ${SHELL_IDLE_SUBAGENTS} idle subagent children are added, then subscribe from that snapshot's cursor and name its project identities, so the project's repository identity is not sent again. Budgeted reads send the opt-ins current clients send; "older client" rows show the same read without the opt-ins added since row budgets.`,
444457
`The stale todo list rows open a third thread the same way: ${STALE_TODO_SETTLED_RUNS} finished runs, then one run still at work with ${STALE_TODO_LIVE_ROWS} rows. Every run left its todo list open and has ${STALE_TODO_SUBAGENTS_PER_RUN} finished subagents, a provider turn and, once finished, a checkpoint. The record counts must not grow with the number of finished runs.`,
445458
"",
446459
"| Provider | Total thread wire | Budget | Result |",

‎apps/server/integration/TransferBudgetV2Fixture.integration.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,10 @@ import {
1414
RunId,
1515
ThreadId,
1616
TurnItemId,
17+
type ApplicationProjectEvent,
1718
type ProviderDriverKind,
1819
type OrchestrationV2DomainEvent,
20+
type RepositoryIdentity,
1921
type OrchestrationV2TurnItem,
2022
} from "@t3tools/contracts";
2123
import * as DateTime from "effect/DateTime";
@@ -837,6 +839,44 @@ export function staleTodoListThreadBatches(
837839
];
838840
}
839841

842+
const FLEET_PROJECT_ID = ProjectId.make("transfer-project");
843+
export const FLEET_PROJECT_IDENTITY: RepositoryIdentity = {
844+
canonicalKey: "github.com/t3/transfer-budget",
845+
locator: {
846+
source: "git-remote",
847+
remoteName: "origin",
848+
remoteUrl: "[email protected]:t3/transfer-budget.git",
849+
},
850+
owner: "t3",
851+
name: "transfer-budget",
852+
};
853+
854+
/**
855+
* The project every fixture thread belongs to. The test resolves it to FLEET_PROJECT_IDENTITY,
856+
* which a shell resume sends again unless the client names the identities it already holds.
857+
*/
858+
export const fleetProjectCreated: ApplicationProjectEvent = {
859+
sequence: 0,
860+
eventId: EventId.make("project-created:transfer-project"),
861+
aggregateKind: "project",
862+
aggregateId: FLEET_PROJECT_ID,
863+
occurredAt: "2026-06-01T00:00:00.000Z",
864+
commandId: null,
865+
causationEventId: null,
866+
correlationId: null,
867+
metadata: {},
868+
type: "project.created",
869+
payload: {
870+
projectId: FLEET_PROJECT_ID,
871+
title: "Transfer budget",
872+
workspaceRoot: "/tmp/transfer-budget",
873+
defaultModelSelection: null,
874+
scripts: [],
875+
createdAt: "2026-06-01T00:00:00.000Z",
876+
updatedAt: "2026-06-01T00:00:00.000Z",
877+
},
878+
};
879+
840880
export const SHELL_SETTLED_THREADS = 100;
841881
export const SHELL_IDLE_SUBAGENTS = 40;
842882

‎apps/server/integration/transferBudgetV2.integration.test.ts‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ import {
1919
OrchestrationV2ThreadBoundedSnapshot,
2020
OrchestrationV2ThreadDetailSnapshot,
2121
OrchestrationV2ThreadHistoryPage,
22-
OrchestrationV2ShellSnapshot,
22+
OrchestrationV2ShellHttpSnapshot,
23+
OrchestrationV2ShellResumable,
2324
OrchestrationV2GetThreadProjectionError,
2425
OrchestrationV2GetShellSnapshotError,
2526
ProviderDriverKind,
@@ -75,6 +76,8 @@ import {
7576
} from "./TransferBudgetReport.integration.ts";
7677
import { TRANSFER_HISTORY_TURN_COUNT } from "./fixtures/transferBudget.ts";
7778
import {
79+
FLEET_PROJECT_IDENTITY,
80+
fleetProjectCreated,
7881
LONG_TURN_THREAD_ID,
7982
longTurnThreadBatches,
8083
SHELL_IDLE_SUBAGENTS,
@@ -92,7 +95,8 @@ import {
9295

9396
// The opt-ins current web and mobile clients send, as client-runtime's boundedThreadSnapshotHttp.ts,
9497
// threadHistoryHttp.ts, shellSnapshotHttp.ts, threads.ts and shell.ts send them. Each is `Required`,
95-
// so an opt-in added to a contract fails typecheck here until this test sends it.
98+
// so an opt-in added to a contract fails typecheck here until this test sends it. An omitted field
99+
// differs per request (a cursor, or what the client holds), so each scenario sends its own.
96100
const CLIENT_BOUNDED_OPT_INS = {
97101
compactTurnItems: "1",
98102
dedupeBodies: "1",
@@ -105,7 +109,7 @@ const CLIENT_HISTORY_OPT_INS = { compactIds: "1", deferWork: "1" } satisfies Req
105109
const CLIENT_SHELL_OPT_INS = {
106110
omitIdleSubagents: "1",
107111
omitOlderSettled: "1",
108-
} satisfies Required<typeof EnvironmentOrchestrationShellSnapshotQuery.Type>;
112+
} satisfies Required<Omit<typeof EnvironmentOrchestrationShellSnapshotQuery.Type, "resumeFrom">>;
109113
const CLIENT_THREAD_SUBSCRIPTION = {
110114
requestCompletionMarker: true,
111115
acceptBoundedSnapshot: true,
@@ -114,17 +118,22 @@ const CLIENT_THREAD_SUBSCRIPTION = {
114118
acceptCompactIds: true,
115119
acceptDedupedBodies: true,
116120
} satisfies Required<Omit<OrchestrationV2SubscribeThreadInput, "threadId" | "afterSequence">>;
121+
type ShellResumeField = "afterSequence" | "httpSnapshotFallback" | "knownProjectIdentities";
117122
const CLIENT_SHELL_SUBSCRIPTION = {
118123
requestCompletionMarker: true,
119124
omitIdleSubagents: true,
120125
omitOlderSettled: true,
121-
} satisfies Required<
122-
Omit<OrchestrationV2SubscribeShellInput, "afterSequence" | "httpSnapshotFallback">
123-
>;
126+
} satisfies Required<Omit<OrchestrationV2SubscribeShellInput, ShellResumeField>>;
124127
const query = (optIns: Readonly<Record<string, string>>) => new URLSearchParams(optIns).toString();
125128
const CLIENT_BOUNDED_QUERY = query(CLIENT_BOUNDED_OPT_INS);
126129
const CLIENT_HISTORY_QUERY = query(CLIENT_HISTORY_OPT_INS);
127130
const CLIENT_SHELL_QUERY = query(CLIENT_SHELL_OPT_INS);
131+
// A client that holds shell rows names their cursor in the same request.
132+
const clientShellResumeQuery = (resumeFrom: number) =>
133+
query({
134+
...CLIENT_SHELL_OPT_INS,
135+
resumeFrom: String(resumeFrom),
136+
} satisfies Required<typeof EnvironmentOrchestrationShellSnapshotQuery.Type>);
128137

129138
const decodeThreadSnapshot = Schema.decodeUnknownEffect(
130139
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ThreadDetailSnapshot)),
@@ -136,7 +145,10 @@ const decodeHistoryPage = Schema.decodeUnknownEffect(
136145
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ThreadHistoryPage)),
137146
);
138147
const decodeShellSnapshot = Schema.decodeUnknownEffect(
139-
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ShellSnapshot)),
148+
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ShellHttpSnapshot)),
149+
);
150+
const decodeShellResumable = Schema.decodeUnknownEffect(
151+
Schema.fromJsonString(Schema.toCodecJson(OrchestrationV2ShellResumable)),
140152
);
141153

142154
const layerPersistence = EventSink.layer.pipe(
@@ -176,7 +188,7 @@ const layerEnrichment = Layer.unwrap(
176188
return Layer.mock(ProjectEnrichmentService.ProjectEnrichmentService)({
177189
getAvailable: () =>
178190
Effect.succeed({
179-
repositoryIdentity: null,
191+
repositoryIdentity: FLEET_PROJECT_IDENTITY,
180192
faviconPath: null,
181193
repositoryIdentityResolved: true,
182194
}),
@@ -263,10 +275,7 @@ const collectUntil = Effect.fn("transfer.collectUntil")(function* <T extends Str
263275
});
264276
type Subscription =
265277
| ({ readonly thread: ThreadId } & Pick<OrchestrationV2SubscribeThreadInput, "afterSequence">)
266-
| ({ readonly shell: true } & Pick<
267-
OrchestrationV2SubscribeShellInput,
268-
"afterSequence" | "httpSnapshotFallback"
269-
>);
278+
| ({ readonly shell: true } & Pick<OrchestrationV2SubscribeShellInput, ShellResumeField>);
270279
function subscriptionStream(
271280
client: MeasuredWsClient,
272281
subscription: Subscription,
@@ -457,8 +466,10 @@ it.live("reports V2 thread HTTP and WebSocket transfer budgets", () =>
457466
const readShell = (query: string) =>
458467
Effect.gen(function* () {
459468
const http = yield* get(`/api/orchestration/shell?${query}`);
460-
const { threads, snapshotSequence } = yield* decodeShellSnapshot(decoded(http));
461-
return { http, rows: threads.length, snapshotSequence };
469+
const { threads, snapshotSequence, projectIdentities } = yield* decodeShellSnapshot(
470+
decoded(http),
471+
);
472+
return { http, rows: threads.length, snapshotSequence, projectIdentities };
462473
});
463474
// A new socket, read until the subscription caught up or the server ended it.
464475
const open = (subscription: Subscription) =>
@@ -529,20 +540,36 @@ it.live("reports V2 thread HTTP and WebSocket transfer budgets", () =>
529540

530541
// The transfer thread plus the long-turn thread.
531542
const earlierThreads = decodedShell.threads.length + 1;
543+
// The fleet's project is in a repository. Earlier phases have no project, as on `main`.
544+
yield* (yield* ProjectStore.ProjectStoreV2).apply(fleetProjectCreated);
532545
yield* sink.write({ events: shellFleetEvents(provider) });
533546
const fleetShellLegacy = yield* readShell("");
534547
const fleetShell = yield* readShell(CLIENT_SHELL_QUERY);
535548
assert.equal(
536549
fleetShellLegacy.rows,
537550
earlierThreads + SHELL_SETTLED_THREADS + SHELL_IDLE_SUBAGENTS,
538551
);
539-
// A cold connect subscribes from the snapshot it just loaded.
552+
const { projectIdentities } = fleetShell;
553+
if (projectIdentities === undefined)
554+
return yield* Effect.die("Expected the shell snapshot to name its project identities");
555+
// A cold connect subscribes from the snapshot it just loaded and names its identities.
556+
// Without them the resume sends the project again, in a marked snapshot.
540557
const fleetShellSubscribe = yield* open({
541558
shell: true,
542559
afterSequence: fleetShell.snapshotSequence,
560+
knownProjectIdentities: projectIdentities,
543561
});
544562
assert.notInclude(fleetShellSubscribe.kinds, "snapshot");
545-
// A cursor too old to replay is told to reload over HTTP, not sent a socket snapshot.
563+
// A client that holds those rows asks the route whether they still resume, and keeps them.
564+
const fleetShellResumeHttp = yield* get(
565+
`/api/orchestration/shell?${clientShellResumeQuery(fleetShell.snapshotSequence)}`,
566+
);
567+
yield* decodeShellResumable(decoded(fleetShellResumeHttp));
568+
const fleetShellResume = { http: fleetShellResumeHttp, rows: 0 };
569+
// A cursor too old to replay gets the snapshot in the same answer.
570+
const staleShellReload = yield* readShell(clientShellResumeQuery(sequence));
571+
assert.equal(staleShellReload.rows, fleetShell.rows);
572+
// When that request fails, the socket tells the client to reload, with no snapshot.
546573
const staleShellResume = yield* open({
547574
shell: true,
548575
afterSequence: sequence,
@@ -601,6 +628,8 @@ it.live("reports V2 thread HTTP and WebSocket transfer budgets", () =>
601628
fleetShellLegacy,
602629
fleetShell,
603630
fleetShellSubscribe,
631+
fleetShellResume,
632+
staleShellReload,
604633
staleShellResume,
605634
staleTodoColdOpen,
606635
} satisfies TransferBudgetRun;

‎docs/internals/performance-regressions.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,10 @@ bounded snapshot and one older page) and after it finishes (the deferred cold op
7979
over the socket alone, and the first page of its deferred work). It caps the socket bytes of three
8080
resumes that must not send a snapshot: a thread after one ordinary turn, an idle thread, and a
8181
shell cursor too old to replay. It caps the cold-connect shell for a sidebar of settled threads and
82-
idle subagents, and the subscription a client opens from that snapshot. It also caps the bytes and
82+
idle subagents, and the subscription a client opens from that snapshot with its project identities.
83+
It caps both answers of the HTTP shell route to a client that holds rows and names their cursor: the
84+
few bytes that keep them, and the snapshot that replaces rows too old to replay. It also caps the
85+
bytes and
8386
the node, subagent, plan, provider turn and checkpoint counts of the bounded snapshot for a thread
8487
of 40 finished runs behind one working run, so finished runs cannot ride along with a window. The
8588
working run has a ready context handoff, so its history cannot ride along either.

0 commit comments

Comments
 (0)