The best way to control Claude Code, Codex and more from any computer or phone
perf(client-runtime): merge shell deltas once per received batch (#18416)
Co-authored-by: SAPHID <saphid@users.noreply.github.com> Co-authored-by: GPT-6.1 Sol <noreply@openai.com>
Alex Southwell committed
Nov 1, 2026 at 20:52 UTC
1915569b195768bbb1890a2dad817045f8d08a22
4 files changed
+409
-35
packages/client-runtime/src/state/shell-sync.test.ts
+184
@@ -123,6 +123,190 @@ const makePersistenceHarness = Effect.fn("test.makeShellPersistenceHarness")(fun
123
});
124
125
describe("environment shell synchronization", () => {
126
+ it.effect.each([
127
+ { bufferSize: Infinity, expectedSequences: [51], existingRows: false },
128
+ { bufferSize: Infinity, expectedSequences: [51], existingRows: true },
129
+ // RpcClient defaults to a 16-event buffer, which splits larger server chunks.
130
+ { bufferSize: 16, expectedSequences: [17, 33, 49, 51], existingRows: false },
131
+ { bufferSize: 16, expectedSequences: [17, 33, 49, 51], existingRows: true },
132
+ ])("batches $bufferSize events (existing: $existingRows)", (input) =>
133
+ Effect.gen(function* () {
134
+ const { bufferSize, expectedSequences, existingRows } = input;
135
+ const events = yield* Queue.bounded<OrchestrationV2ShellStreamItem>(bufferSize);
136
+ let rowVisits = 0;
137
+ const rows = Array.from({ length: 50 }, (_, index) => ({
138
+ ...v2ThreadShell,
139
+ get id() {
140
+ rowVisits += 1;
141
+ return ThreadId.make(`thread-${index}`);
142
+ },
143
+ }));
144
+ const batchSnapshot = { ...LIVE_SHELL_SNAPSHOT, threads: existingRows ? rows : [] };
145
+ const client = {
146
+ [ORCHESTRATION_V2_WS_METHODS.subscribeShell]: () => Stream.fromQueue(events),
147
+ } as unknown as WsRpcProtocolClient;
148
+ const supervisorState = yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE);
149
+ const activeSession = yield* SubscriptionRef.make<Option.Option<RpcSession.RpcSession>>(
150
+ Option.some(session(client)),
151
+ );
152
+ const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
153
+ target: TARGET,
154
+ state: supervisorState,
155
+ session: activeSession,
156
+ prepared: yield* SubscriptionRef.make(Option.some(PREPARED)),
157
+ connect: Effect.void,
158
+ disconnect: Effect.void,
159
+ retryNow: Effect.void,
160
+ } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
161
+ const cache = Persistence.EnvironmentCacheStore.of({
162
+ loadShell: () => Effect.succeedNone,
163
+ saveShell: () => Effect.void,
164
+ loadThread: () => Effect.succeedNone,
165
+ saveThread: () => Effect.void,
166
+ removeThread: () => Effect.void,
167
+ loadServerConfig: () => Effect.succeedNone,
168
+ saveServerConfig: () => Effect.void,
169
+ loadVcsRefs: () => Effect.succeedNone,
170
+ saveVcsRefs: () => Effect.void,
171
+ removeVcsRefs: () => Effect.void,
172
+ clearVcsRefs: () => Effect.void,
173
+ clear: () => Effect.void,
174
+ });
175
+ const shellState = yield* makeEnvironmentShellState().pipe(
176
+ Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
177
+ Effect.provideService(Persistence.EnvironmentCacheStore, cache),
178
+ Effect.provideService(
179
+ ShellSnapshotLoader.ShellSnapshotLoader,
180
+ ShellSnapshotLoader.ShellSnapshotLoader.of({
181
+ load: () => Effect.succeedNone,
182
+ }),
183
+ ),
184
+ );
185
+ yield* SubscriptionRef.set(supervisorState, {
186
+ desired: true,
187
+ network: "online",
188
+ phase: "connected",
189
+ stage: null,
190
+ attempt: 1,
191
+ generation: 1,
192
+ lastFailure: null,
193
+ retryAt: null,
194
+ });
195
+ yield* Queue.offer(events, { kind: "snapshot", snapshot: batchSnapshot });
196
+ yield* Queue.offer(events, { kind: "synchronized" });
197
+ yield* SubscriptionRef.changes(shellState).pipe(
198
+ Stream.filter((state) => state.status === "live"),
199
+ Stream.runHead,
200
+ );
201
+
202
+ // Observe before publishing so no batch can arrive before the subscription.
203
+ const observed = yield* SubscriptionRef.changes(shellState).pipe(
204
+ Stream.drop(1),
205
+ Stream.takeUntil(
206
+ (state) => Option.isSome(state.snapshot) && state.snapshot.value.snapshotSequence === 51,
207
+ ),
208
+ Stream.runCollect,
209
+ Effect.forkScoped({ startImmediately: true }),
210
+ );
211
+ rowVisits = 0;
212
+ yield* Queue.offerAll(
213
+ events,
214
+ Array.from({ length: 50 }, (_, index) => ({
215
+ kind: "thread.updated" as const,
216
+ sequence: 2 + index,
217
+ location: "active" as const,
218
+ thread: {
219
+ ...v2ThreadShell,
220
+ get id() {
221
+ rowVisits += 1;
222
+ return ThreadId.make(`thread-${index}`);
223
+ },
224
+ title: "Updated",
225
+ },
226
+ })),
227
+ );
228
+ const states = yield* Fiber.join(observed);
229
+ if (existingRows) {
230
+ // Index each received batch once; distinct updates must not rescan every row.
231
+ expect(rowVisits).toBeLessThanOrEqual(50 * (expectedSequences.length + 10));
232
+ }
233
+ const snapshots = states.map((state) => Option.getOrThrow(state.snapshot));
234
+ expect(snapshots.map((snapshot) => snapshot.snapshotSequence)).toEqual(expectedSequences);
235
+ expect(snapshots.at(-1)!.threads.map((thread) => thread.id)).toEqual(
236
+ Array.from({ length: 50 }, (_, index) => `thread-${index}`),
237
+ );
238
+
239
+ const removedObserved = yield* SubscriptionRef.changes(shellState).pipe(
240
+ Stream.filter(
241
+ (state) => Option.isSome(state.snapshot) && state.snapshot.value.snapshotSequence === 52,
242
+ ),
243
+ Stream.runHead,
244
+ Effect.forkScoped({ startImmediately: true }),
245
+ );
246
+ yield* Queue.offerAll(events, [
247
+ { kind: "future.event", sequence: 99 } as never,
248
+ {
249
+ kind: "thread.removed",
250
+ sequence: 52,
251
+ location: "active",
252
+ threadId: ThreadId.make("thread-0"),
253
+ },
254
+ {
255
+ kind: "thread.removed",
256
+ sequence: 51,
257
+ location: "active",
258
+ threadId: ThreadId.make("thread-1"),
259
+ },
260
+ ]);
261
+ const removedState = Option.getOrThrow(yield* Fiber.join(removedObserved));
262
+ expect(removedState.generation).toBe(states.at(-1)!.generation);
263
+ expect([...removedState.removedAt]).toEqual([[ThreadId.make("thread-0"), 52]]);
264
+
265
+ // An authoritative snapshot resets even a higher live cursor in the same batch.
266
+ const resetRow = { ...v2ThreadShell, id: ThreadId.make("reset-row") };
267
+ const resetObserved = yield* SubscriptionRef.changes(shellState).pipe(
268
+ Stream.filter(
269
+ (state) => Option.isSome(state.snapshot) && state.snapshot.value.snapshotSequence === 4,
270
+ ),
271
+ Stream.runHead,
272
+ Effect.forkScoped({ startImmediately: true }),
273
+ );
274
+ yield* Queue.offerAll(events, [
275
+ {
276
+ kind: "thread.removed",
277
+ sequence: 52,
278
+ location: "active",
279
+ threadId: ThreadId.make("thread-0"),
280
+ },
281
+ {
282
+ kind: "snapshot",
283
+ snapshot: { ...LIVE_SHELL_SNAPSHOT, snapshotSequence: 2, threads: [resetRow] },
284
+ },
285
+ { kind: "thread.removed", sequence: 2, location: "active", threadId: resetRow.id },
286
+ {
287
+ kind: "thread.updated",
288
+ sequence: 3,
289
+ location: "active",
290
+ thread: { ...resetRow, title: "After reset" },
291
+ },
292
+ { kind: "synchronized" },
293
+ {
294
+ kind: "thread.updated",
295
+ sequence: 4,
296
+ location: "active",
297
+ thread: { ...resetRow, title: "After completion" },
298
+ },
299
+ ]);
300
+ const resetState = Option.getOrThrow(yield* Fiber.join(resetObserved));
301
+ expect(resetState.status).toBe("live");
302
+ expect(resetState.generation).toBeGreaterThan(removedState.generation);
303
+ expect(resetState.removedAt.size).toBe(0);
304
+ expect(Option.getOrThrow(resetState.snapshot).threads).toEqual([
305
+ { ...resetRow, title: "After completion" },
306
+ ]);
307
+ }).pipe(Effect.scoped),
308
+ );
309
+
310
it.effect("skips unchanged shell writes, persists resets and flushes changed rows", () =>
311
Effect.gen(function* () {
312
const saved = yield* SubscriptionRef.make<ReadonlyArray<OrchestrationV2ShellSnapshot>>([]);
packages/client-runtime/src/state/shell.ts
+50
-35
@@ -31,7 +31,8 @@ import type { RpcSession } from "../rpc/session.ts";
31
import * as ShellSnapshotLoader from "./shellSnapshotHttp.ts";
32
import type { DeferredShellSnapshot } from "./shellPullRequests.ts";
33
import {
34
- applyShellStreamEvent,
34
+ applyShellStreamEvents,
35
+ type ShellStreamEvent,
36
mergeShellSnapshotProjects,
37
reuseUnchangedThreadShells,
38
sameThreadPullRequests,
@@ -211,10 +212,46 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
212
) {
213
const initial = yield* SubscriptionRef.get(state);
214
let waiting = yield* Ref.get(awaitingCompletion);
214
- /* oxlint-disable oxc/no-accumulating-spread -- This copies a fixed-shape state record, not a growing collection. */
215
let next = initial;
216
let receivedSnapshot = false;
217
+ let deltas: Array<ShellStreamEvent> = [];
218
+ const flushDeltas = () => {
219
+ if (deltas.length > 0 && Option.isSome(next.snapshot)) {
220
+ let sequence = next.snapshot.value.snapshotSequence;
221
+ let removedAt: Map<ThreadId, number> | undefined;
222
+ for (const delta of deltas) {
223
+ if (delta.sequence <= sequence) continue;
224
+ switch (delta.kind) {
225
+ case "thread.removed":
226
+ removedAt ??= new Map(next.removedAt);
227
+ removedAt.set(delta.threadId, delta.sequence);
228
+ break;
229
+ case "thread.updated":
230
+ case "project.updated":
231
+ case "project.removed":
232
+ break;
233
+ default:
234
+ continue;
235
+ }
236
+ sequence = delta.sequence;
237
+ }
238
+ next = {
239
+ ...next,
240
+ removedAt: removedAt ?? next.removedAt,
241
+ snapshot: Option.some(applyShellStreamEvents(next.snapshot.value, deltas)),
242
+ status: waiting ? "synchronizing" : "live",
243
+ error: Option.none(),
244
+ };
245
+ }
246
+ deltas = [];
247
+ };
248
for (const item of items) {
249
+ if (item.kind !== "snapshot" && item.kind !== "synchronized") {
250
+ deltas.push(item);
251
+ continue;
252
+ }
253
+ // Snapshots can reset the cursor; completion markers change the sync status.
254
+ flushDeltas();
255
if (item.kind === "synchronized") {
256
waiting = false;
257
if (Option.isSome(next.snapshot)) {
@@ -222,46 +259,24 @@ export const makeEnvironmentShellState = Effect.fn("EnvironmentShellState.make")
259
}
260
continue;
261
}
225
- const authoritative =
226
- item.kind === "snapshot" && item.resolvedRepositoryIdentityRoots === undefined;
227
- const nextSnapshot =
228
- item.kind === "snapshot"
229
- ? mergeShellSnapshotProjects(
230
- Option.getOrNull(next.snapshot),
231
- item.snapshot,
232
- item.resolvedRepositoryIdentityRoots === undefined
233
- ? undefined
234
- : {
235
- resolvedRepositoryIdentityRoots: item.resolvedRepositoryIdentityRoots,
236
- },
237
- )
238
- : Option.match(next.snapshot, {
239
- onNone: () => null,
240
- onSome: (snapshot) =>
241
- item.sequence > snapshot.snapshotSequence
242
- ? applyShellStreamEvent(snapshot, item)
243
- : snapshot,
244
- });
245
- if (nextSnapshot === null) continue;
246
- receivedSnapshot ||= item.kind === "snapshot";
247
- const removal =
248
- item.kind === "thread.removed" &&
249
- Option.exists(next.snapshot, (snapshot) => item.sequence > snapshot.snapshotSequence)
250
- ? item
251
- : null;
262
+ const authoritative = item.resolvedRepositoryIdentityRoots === undefined;
263
+ const nextSnapshot = mergeShellSnapshotProjects(
264
+ Option.getOrNull(next.snapshot),
265
+ item.snapshot,
266
+ item.resolvedRepositoryIdentityRoots === undefined
267
+ ? undefined
268
+ : { resolvedRepositoryIdentityRoots: item.resolvedRepositoryIdentityRoots },
269
+ );
270
+ receivedSnapshot = true;
271
next = {
272
snapshot: Option.some(nextSnapshot),
273
status: waiting ? "synchronizing" : "live",
274
error: Option.none(),
275
generation: authoritative ? ++lastShellGeneration : next.generation,
257
- removedAt: authoritative
258
- ? EMPTY_REMOVALS
259
- : removal === null
260
- ? next.removedAt
261
- : new Map(next.removedAt).set(removal.threadId, removal.sequence),
276
+ removedAt: authoritative ? EMPTY_REMOVALS : next.removedAt,
277
};
278
}
264
- /* oxlint-enable oxc/no-accumulating-spread */
279
+ flushDeltas();
280
yield* Ref.set(awaitingCompletion, waiting);
281
if (next === initial) return;
282
if (pendingLinkIds !== undefined && Option.isSome(next.snapshot)) {
packages/client-runtime/src/state/shellReducer.test.ts
+94
@@ -4,6 +4,8 @@ import { describe, expect, it } from "vite-plus/test";
4
import { v2Project, v2ShellSnapshot, v2ThreadShell } from "./orchestrationV2TestFixtures.ts";
5
import {
6
applyShellStreamEvent,
7
+ applyShellStreamEvents,
8
+ type ShellStreamEvent,
9
mergeShellSnapshotProjects,
10
reuseUnchangedThreadShells,
11
} from "./shellReducer.ts";
@@ -327,3 +329,95 @@ describe("reuseUnchangedThreadShells", () => {
329
expect(next.threads[0]?.pullRequests).toEqual([]);
330
});
331
});
332
+
333
+describe("applyShellStreamEvents", () => {
334
+ const row = (id: string) => ({ ...v2ThreadShell, id: ThreadId.make(id) });
335
+ const a = row("a");
336
+ const b = row("b");
337
+ const unchanged = row("unchanged");
338
+ const archived = row("archived");
339
+ const oldArchive = row("old-archive");
340
+ const added = row("new");
341
+ const update = (
342
+ sequence: number,
343
+ thread: typeof v2ThreadShell,
344
+ location: "active" | "archive" = "active",
345
+ ): ShellStreamEvent => ({ kind: "thread.updated", sequence, location, thread });
346
+ const remove = (sequence: number, thread: typeof v2ThreadShell): ShellStreamEvent => ({
347
+ kind: "thread.removed",
348
+ sequence,
349
+ location: "active",
350
+ threadId: thread.id,
351
+ });
352
+
353
+ it("matches sequential mixed deltas, including remove/reinsert order and stale events", () => {
354
+ const otherProject = { ...v2Project, id: ProjectId.make("other-project") };
355
+ const seed = {
356
+ ...v2ShellSnapshot,
357
+ snapshotSequence: 4,
358
+ projects: [{ ...v2Project, repositoryIdentity }, otherProject],
359
+ threads: [a, b, unchanged],
360
+ archivedThreads: [archived, oldArchive],
361
+ };
362
+ const events: Array<ShellStreamEvent> = [
363
+ update(5, { ...b, title: "Renamed" }),
364
+ remove(5, a),
365
+ remove(6, a),
366
+ update(7, a),
367
+ update(8, b, "archive"),
368
+ update(9, archived),
369
+ update(10, oldArchive, "archive"),
370
+ update(11, added),
371
+ remove(12, { ...a, id: ThreadId.make("missing") }),
372
+ remove(11, added),
373
+ remove(13, added),
374
+ update(14, added),
375
+ update(15, { ...archived }),
376
+ { kind: "project.updated", sequence: 16, project: { ...v2Project, title: "Updated" } },
377
+ { kind: "project.updated", sequence: 17, project: { ...v2Project, workspaceRoot: "/moved" } },
378
+ { kind: "project.removed", sequence: 18, projectId: v2Project.id },
379
+ { kind: "project.updated", sequence: 19, project: v2Project },
380
+ ];
381
+ const sequential = events.reduce(applyShellStreamEvent, seed);
382
+ const next = applyShellStreamEvents(seed, events);
383
+ expect(next).toEqual(sequential);
384
+ expect(next.threads.map((row) => row.id)).toEqual([unchanged.id, a.id, archived.id, added.id]);
385
+ expect(next.threads[0]).toBe(unchanged);
386
+ expect(next.threads[2]).toBe(archived);
387
+ expect(next.projects[0]).toBe(otherProject);
388
+ expect(next.archivedThreads).toEqual([]);
389
+ expect(seed.threads).toEqual([a, b, unchanged]);
390
+ expect(seed.archivedThreads).toEqual([archived, oldArchive]);
391
+ // Identity retention must use the latest project in this batch.
392
+ expect(applyShellStreamEvents(seed, events.slice(0, 14)).projects[0]?.repositoryIdentity).toBe(
393
+ repositoryIdentity,
394
+ );
395
+ expect(
396
+ applyShellStreamEvents(seed, events.slice(0, 15)).projects[0]?.repositoryIdentity,
397
+ ).toBeNull();
398
+ });
399
+
400
+ it("keeps collection identities for equal rows and rejects stale deltas without indexing", () => {
401
+ const seed = { ...v2ShellSnapshot, threads: [a, b], snapshotSequence: 4 };
402
+ const next = applyShellStreamEvents(seed, [update(5, { ...a }), update(6, { ...b })]);
403
+ expect(next).toEqual(
404
+ [update(5, { ...a }), update(6, { ...b })].reduce(applyShellStreamEvent, seed),
405
+ );
406
+ expect(next.threads).toBe(seed.threads);
407
+ expect(next.projects).toBe(seed.projects);
408
+ expect(next.archivedThreads).toBe(seed.archivedThreads);
409
+ expect(next.snapshotSequence).toBe(6);
410
+ expect(applyShellStreamEvents(seed, [remove(3, a), update(4, b)])).toBe(seed);
411
+ expect(applyShellStreamEvents(seed, [])).toBe(seed);
412
+ });
413
+
414
+ it("does not advance the cursor for an unknown future event", () => {
415
+ const events = [
416
+ { kind: "future.event", sequence: 99 } as never,
417
+ update(1, { ...a, title: "Changed" }),
418
+ ];
419
+ expect(applyShellStreamEvents(v2ShellSnapshot, events)).toEqual(
420
+ events.reduce(applyShellStreamEvent, v2ShellSnapshot),
421
+ );
422
+ });
423
+});
packages/client-runtime/src/state/shellReducer.ts
+81
@@ -191,3 +191,84 @@ export function applyShellStreamEvent(
191
return snapshot;
192
}
193
}
194
+
195
+/** Index a collection lazily and materialize it only if a delta changes its rows. */
196
+function batchRows<T extends { readonly id: unknown }>(rows: ReadonlyArray<T>) {
197
+ let byId: Map<T["id"], T> | undefined;
198
+ let changed = false;
199
+ const index = () => {
200
+ if (byId === undefined) {
201
+ byId = new Map();
202
+ for (const row of rows) byId.set(row.id, row);
203
+ }
204
+ return byId;
205
+ };
206
+ return {
207
+ get: (id: T["id"]) => index().get(id),
208
+ set: (row: T) => {
209
+ index().set(row.id, row);
210
+ changed = true;
211
+ },
212
+ remove: (id: T["id"]) => {
213
+ if (index().delete(id)) changed = true;
214
+ },
215
+ finish: () => (changed ? Array.from(index().values()) : rows),
216
+ };
217
+}
218
+
219
+export type ShellStreamEvent = Exclude<
220
+ OrchestrationV2ShellStreamItem,
221
+ { readonly kind: "snapshot" } | { readonly kind: "synchronized" }
222
+>;
223
+
224
+/** Apply ordered deltas with one index and at most one new array per collection. */
225
+export function applyShellStreamEvents(
226
+ snapshot: OrchestrationV2ShellSnapshot,
227
+ events: ReadonlyArray<ShellStreamEvent>,
228
+): OrchestrationV2ShellSnapshot {
229
+ // Avoid indexing the whole shell for the common single-event delivery.
230
+ if (events.length === 1) return applyShellStreamEvent(snapshot, events[0]!);
231
+ const projects = batchRows(snapshot.projects);
232
+ const threads = batchRows(snapshot.threads);
233
+ const archivedThreads = batchRows(snapshot.archivedThreads);
234
+ let sequence = snapshot.snapshotSequence;
235
+ for (const event of events) {
236
+ if (event.sequence <= sequence) continue;
237
+ switch (event.kind) {
238
+ case "project.updated":
239
+ projects.set(retainRepositoryIdentity(projects.get(event.project.id), event.project));
240
+ break;
241
+ case "project.removed":
242
+ projects.remove(event.projectId);
243
+ break;
244
+ case "thread.updated": {
245
+ const id = event.thread.id;
246
+ if (event.location === "active") {
247
+ const previous = threads.get(id);
248
+ if (previous !== undefined && sameThreadShell(previous, event.thread)) break;
249
+ threads.set(event.thread);
250
+ } else {
251
+ threads.remove(id);
252
+ }
253
+ // Legacy archive deltas remove rows from the shell; the archive is queried separately.
254
+ archivedThreads.remove(id);
255
+ break;
256
+ }
257
+ case "thread.removed":
258
+ threads.remove(event.threadId);
259
+ archivedThreads.remove(event.threadId);
260
+ break;
261
+ default:
262
+ continue;
263
+ }
264
+ sequence = event.sequence;
265
+ }
266
+ if (sequence === snapshot.snapshotSequence) return snapshot;
267
+ return {
268
+ ...snapshot,
269
+ snapshotSequence: sequence,
270
+ projects: projects.finish(),
271
+ threads: threads.finish(),
272
+ archivedThreads: archivedThreads.finish(),
273
+ };
274
+}