@devries-cameron20 / t3code-1 / commits / 1915569b19
Fork 0

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 +}