The best way to control Claude Code, Codex and more from any computer or phone
fix(server): coalesce queued shell updates for slow clients (#14859)
Co-authored-by: maria-rcks <254055478+maria-rcks@users.noreply.github.com> Co-authored-by: Julius Marminge <julius0216@outlook.com>
maria committed
Oct 20, 2026 at 05:46 UTC
94827737ea018902dd2e932cddb51643365dc446
5 files changed
+362
-3
apps/server/src/orchestration-v2/LiveStreamBudget.test.ts
+34
@@ -9,6 +9,7 @@ import { describe, expect } from "vite-plus/test";
9
10
import {
11
bufferLiveStream,
12
+ bufferLatestLiveStream,
13
makeLiveStreamBudget,
14
replayAndBufferLiveEvents,
15
type RetainedLiveItem,
@@ -75,6 +76,39 @@ it.effect("stops draining a slow subscriber when its unacknowledged tail fills",
76
77
type Event = { readonly sequence: number; readonly text: string; readonly threadId?: string };
78
79
+describe("bufferLatestLiveStream", () => {
80
+ it.effect.each(["items", "bytes"] as const)(
81
+ "counts an unacknowledged state against the %s limit when its replacement arrives",
82
+ (limit) =>
83
+ Effect.scoped(
84
+ Effect.gen(function* () {
85
+ const releaseUpdate = yield* Deferred.make<void>();
86
+ const closed = yield* Deferred.make<void>();
87
+ const first = { sequence: 1, text: "é".repeat(20) };
88
+ const next = { ...first, sequence: 2 };
89
+ const pull = yield* Stream.toPull(
90
+ bufferLatestLiveStream(
91
+ Stream.concat(
92
+ Stream.succeed(first),
93
+ Stream.fromEffect(Deferred.await(releaseUpdate)).pipe(Stream.map(() => next)),
94
+ ).pipe(Stream.ensuring(Deferred.succeed(closed, undefined))),
95
+ () => "same-thread",
96
+ limit === "items"
97
+ ? { maxItems: 1 }
98
+ : { maxSerializedBytes: Buffer.byteLength(JSON.stringify(first)) },
99
+ ),
100
+ );
101
+ expect(yield* pull).toEqual([first]);
102
+ yield* Deferred.succeed(releaseUpdate, undefined);
103
+ yield* Deferred.await(closed);
104
+ const result = yield* pull.pipe(Effect.result);
105
+ expect(result._tag).toBe("Failure");
106
+ if (result._tag === "Failure") expect(result.failure._tag).toBe("LiveStreamBufferError");
107
+ }),
108
+ ),
109
+ );
110
+});
111
+
112
describe("replayAndBufferLiveEvents", () => {
113
it.effect.each(["high-water", "replay"] as const)(
114
"unsubscribes and cancels a blocked %s read on live overflow",
apps/server/src/orchestration-v2/LiveStreamBudget.ts
+78
@@ -7,6 +7,7 @@ import * as Exit from "effect/Exit";
7
import * as Queue from "effect/Queue";
8
import * as PubSub from "effect/PubSub";
9
import * as Scope from "effect/Scope";
10
+import * as Semaphore from "effect/Semaphore";
11
import * as Stream from "effect/Stream";
12
13
export class LiveStreamBufferError extends Schema.TaggedError<LiveStreamBufferError>()(
@@ -254,6 +255,83 @@ export const bufferLiveStream = <A extends object, E, R>(
255
}),
256
);
257
258
+/** Coalesce queued full states; delivered states stay charged until the next pull ACKs them. */
259
+export const bufferLatestLiveStream = <A extends { readonly sequence: number }, E, R>(
260
+ source: Stream.Stream<A, E, R>,
261
+ key: (value: A) => string,
262
+ limits?: LiveStreamLimits,
263
+) =>
264
+ Stream.unwrap(
265
+ Effect.gen(function* () {
266
+ const budget = yield* makeLiveStreamBudget(limits);
267
+ const ready = yield* Queue.bounded<void, E | LiveStreamBufferError | Cause.Done>(1);
268
+ const mutex = yield* Semaphore.make(1);
269
+ const pending = new Map<string, RetainedLiveItem<A>>();
270
+ let closed = false;
271
+ const close = (error?: LiveStreamBufferError) =>
272
+ mutex.withPermit(
273
+ Effect.gen(function* () {
274
+ if (closed) return;
275
+ closed = true;
276
+ budget.release(pending.values());
277
+ pending.clear();
278
+ if (error) yield* Queue.fail(ready, error);
279
+ yield* Queue.shutdown(ready);
280
+ }),
281
+ );
282
+ yield* Effect.addFinalizer(() => close());
283
+ yield* budget.failed.pipe(
284
+ Effect.catchTags({ LiveStreamBufferError: close }),
285
+ Effect.forkScoped,
286
+ );
287
+ yield* source.pipe(
288
+ Stream.runForEach((value) =>
289
+ mutex.withPermit(
290
+ Effect.gen(function* () {
291
+ yield* budget.check;
292
+ if (closed) return;
293
+ const identity = key(value);
294
+ const previous = pending.get(identity);
295
+ if (previous && previous.value.sequence >= value.sequence) return;
296
+ const wasEmpty = pending.size === 0;
297
+ const [item] = yield* budget.replace(previous ? [previous] : [], [value]);
298
+ pending.set(identity, item!);
299
+ // Only the empty-to-nonempty transition needs a wakeup; replacements
300
+ // must not leave another token after this batch has drained.
301
+ if (wasEmpty) yield* Queue.offer(ready, undefined);
302
+ }).pipe(Effect.uninterruptible),
303
+ ),
304
+ ),
305
+ Effect.raceFirst(budget.failed),
306
+ Effect.exit,
307
+ Effect.flatMap((exit) =>
308
+ Exit.isFailure(exit) ? Queue.failCause(ready, exit.cause) : Queue.end(ready),
309
+ ),
310
+ Effect.forkScoped({ startImmediately: true }),
311
+ );
312
+ return budget.deliver(
313
+ Stream.fromPull(
314
+ Effect.succeed(
315
+ Queue.take(ready).pipe(
316
+ Effect.andThen(
317
+ mutex.withPermit(
318
+ Effect.sync(() => {
319
+ const items = Array.from(pending.values()).sort(
320
+ (left, right) => left.value.sequence - right.value.sequence,
321
+ );
322
+ pending.clear();
323
+ // Moving to delivery preserves the budget charge until ACK.
324
+ return items as Arr.NonEmptyArray<RetainedLiveItem<A>>;
325
+ }),
326
+ ),
327
+ ),
328
+ ),
329
+ ),
330
+ ),
331
+ );
332
+ }),
333
+ );
334
+
335
/**
336
* Subscribe and start draining before reading the high-water mark. A blocked
337
* catch-up query or an unacknowledged replay batch must not strand an unbounded
apps/server/src/orchestration-v2/ShellStream.test.ts
+161
@@ -8,10 +8,14 @@ import type {
8
} from "@t3tools/contracts";
9
import { ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
10
import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
11
+import type * as Cause from "effect/Cause";
12
import * as DateTime from "effect/DateTime";
13
+import * as Deferred from "effect/Deferred";
14
import * as Duration from "effect/Duration";
15
import * as Effect from "effect/Effect";
16
import * as Option from "effect/Option";
17
+import * as PubSub from "effect/PubSub";
18
+import * as Queue from "effect/Queue";
19
import * as SqlClient from "effect/sql/SqlClient";
20
import * as Stream from "effect/Stream";
21
import * as TestClock from "effect/testing/TestClock";
@@ -19,6 +23,7 @@ import * as TestClock from "effect/testing/TestClock";
23
import {
24
archivedShellStreamItemFromThreadShell,
25
buildActiveShellSnapshot,
26
+ bufferShellLiveStream,
27
coalesceShellApplicationEvents,
28
coalesceStoredThreadEvents,
29
composeShellStreamWithEnrichment,
@@ -54,6 +59,64 @@ const emptyShellSnapshot = {
59
archivedThreads: [],
60
} as OrchestrationV2ShellSnapshot;
61
62
+it.effect("coalesces a slow shell subscriber by identity and location in sequence order", () =>
63
+ Effect.scoped(
64
+ Effect.gen(function* () {
65
+ const input = yield* Queue.unbounded<
66
+ Extract<OrchestrationV2ShellStreamItem, { readonly sequence: number }>,
67
+ Cause.Done
68
+ >();
69
+ const drained = yield* Deferred.make<void>();
70
+ const shell = shellFixture({ id: ThreadId.make("same"), title: "Before" });
71
+ const project = {
72
+ id: ProjectId.make("same"),
73
+ title: "Before",
74
+ workspaceRoot: "/workspace/same",
75
+ repositoryIdentity: null,
76
+ defaultModelSelection: null,
77
+ scripts: [],
78
+ createdAt: "2026-09-01T00:00:00Z",
79
+ updatedAt: "2026-09-01T00:00:00Z",
80
+ };
81
+ const initial = {
82
+ kind: "thread.updated" as const,
83
+ sequence: 1,
84
+ location: "active" as const,
85
+ thread: shell,
86
+ };
87
+ const updates = [
88
+ { kind: "project.updated", sequence: 2, project },
89
+ { ...initial, sequence: 3 },
90
+ { ...initial, sequence: 4, location: "archive" },
91
+ { ...initial, sequence: 5, thread: { ...shell, id: ThreadId.make("other") } },
92
+ {
93
+ kind: "project.updated",
94
+ sequence: 6,
95
+ project: { ...project, id: ProjectId.make("other") },
96
+ },
97
+ { kind: "project.removed", sequence: 7, projectId: project.id },
98
+ { kind: "thread.removed", sequence: 8, location: "active", threadId: shell.id },
99
+ { kind: "project.updated", sequence: 9, project: { ...project, title: "Recreated" } },
100
+ { ...initial, sequence: 10, thread: { ...shell, title: "Recreated" } },
101
+ { kind: "thread.removed", sequence: 11, location: "archive", threadId: shell.id },
102
+ ] satisfies Array<Extract<OrchestrationV2ShellStreamItem, { readonly sequence: number }>>;
103
+ const pull = yield* Stream.toPull(
104
+ bufferShellLiveStream(
105
+ Stream.fromQueue(input).pipe(Stream.ensuring(Deferred.succeed(drained, undefined))),
106
+ { maxItems: 6, maxSerializedBytes: 1_500 },
107
+ ),
108
+ );
109
+ yield* Queue.offer(input, initial);
110
+ expect(yield* pull).toEqual([initial]);
111
+ yield* Queue.offerAll(input, updates);
112
+ yield* Queue.end(input);
113
+ // Finish producing the burst while the first batch is still awaiting its ACK.
114
+ yield* Deferred.await(drained);
115
+ expect(yield* pull).toEqual([updates[3], updates[4], updates[7], updates[8], updates[9]]);
116
+ }),
117
+ ),
118
+);
119
+
120
describe("buildActiveShellSnapshot", () => {
121
it("never duplicates archived rows into the regular shell", () => {
122
const active = shellFixture({ archivedAt: null });
@@ -356,6 +419,104 @@ describe("shellStreamItemsFromResumeSnapshot", () => {
419
});
420
421
describe("composeShellStreamWithEnrichment", () => {
422
+ it.effect("preserves pending repository resolutions while an enrichment ACK is withheld", () =>
423
+ Effect.scoped(
424
+ Effect.gen(function* () {
425
+ // Match ProjectEnrichmentService's sliding notifications and the WS batching path.
426
+ const changes = yield* Effect.acquireRelease(
427
+ PubSub.sliding<{ readonly workspaceRoot: string }>(256),
428
+ PubSub.shutdown,
429
+ );
430
+ const subscription = yield* PubSub.subscribe(changes);
431
+ const pull = yield* Stream.toPull(
432
+ composeShellStreamWithEnrichment({
433
+ initial: Stream.empty,
434
+ tail: Stream.empty,
435
+ enrichment: Stream.fromSubscription(subscription).pipe(
436
+ Stream.groupedWithin(64, Duration.millis(25)),
437
+ Stream.map((changes) =>
438
+ shellStreamItemFromEnrichmentRefresh({
439
+ snapshot: emptyShellSnapshot,
440
+ changes,
441
+ }),
442
+ ),
443
+ ),
444
+ }),
445
+ );
446
+
447
+ const firstRoots = Array.from({ length: 64 }, (_, index) => `/workspace/first-${index}`);
448
+ yield* PubSub.publishAll(
449
+ changes,
450
+ firstRoots.map((workspaceRoot) => ({ workspaceRoot })),
451
+ );
452
+ expect(yield* pull).toMatchObject([{ resolvedRepositoryIdentityRoots: firstRoots }]);
453
+
454
+ // The next completion can be batched before the client acknowledges the first.
455
+ yield* PubSub.publish(changes, { workspaceRoot: "/workspace/pending" });
456
+ yield* Effect.yieldNow;
457
+ yield* TestClock.adjust(Duration.millis(25));
458
+ const laterRoots = Array.from({ length: 256 }, (_, index) => `/workspace/later-${index}`);
459
+ yield* PubSub.publishAll(
460
+ changes,
461
+ laterRoots.map((workspaceRoot) => ({ workspaceRoot })),
462
+ );
463
+
464
+ const resumed = yield* Stream.fromPull(Effect.succeed(pull)).pipe(
465
+ Stream.takeUntil(
466
+ (item) =>
467
+ item.resolvedRepositoryIdentityRoots?.includes("/workspace/later-255") ?? false,
468
+ ),
469
+ Stream.runCollect,
470
+ );
471
+ expect(resumed.flatMap((item) => item.resolvedRepositoryIdentityRoots ?? [])).toEqual([
472
+ "/workspace/pending",
473
+ ...laterRoots,
474
+ ]);
475
+ }),
476
+ ),
477
+ );
478
+
479
+ it.effect("keeps a merged shell batch charged while the client withholds its ACK", () =>
480
+ Effect.scoped(
481
+ Effect.gen(function* () {
482
+ const update = yield* Deferred.make<void>();
483
+ const closed = yield* Deferred.make<void>();
484
+ const initial = {
485
+ kind: "thread.removed" as const,
486
+ sequence: 1,
487
+ location: "active" as const,
488
+ threadId: ThreadId.make("thread-a"),
489
+ };
490
+ const pull = yield* Stream.toPull(
491
+ composeShellStreamWithEnrichment({
492
+ initial: Stream.empty,
493
+ tail: bufferShellLiveStream(
494
+ Stream.concat(
495
+ Stream.succeed(initial),
496
+ Stream.fromEffect(Deferred.await(update)).pipe(
497
+ Stream.map(() => ({ ...initial, sequence: 2 })),
498
+ ),
499
+ ).pipe(Stream.ensuring(Deferred.succeed(closed, undefined))),
500
+ { maxItems: 1 },
501
+ ),
502
+ enrichment: Stream.empty,
503
+ }),
504
+ );
505
+ expect(yield* pull).toEqual([initial]);
506
+ // Let the merge producer run while the client still withholds its ACK.
507
+ yield* Effect.yieldNow;
508
+ yield* Deferred.succeed(update, undefined);
509
+ yield* Deferred.await(closed);
510
+ const result = yield* Stream.fromPull(Effect.succeed(pull)).pipe(
511
+ Stream.runDrain,
512
+ Effect.result,
513
+ );
514
+ expect(result._tag).toBe("Failure");
515
+ if (result._tag === "Failure") expect(result.failure._tag).toBe("LiveStreamBufferError");
516
+ }),
517
+ ),
518
+ );
519
+
520
it.effect(
521
"emits every initial item before enrichment even when enrichment is already ready",
522
() =>
apps/server/src/orchestration-v2/ShellStream.ts
+87
-2
@@ -13,12 +13,43 @@ import {
13
OrchestrationV2ThreadShell as ThreadShellSchema,
14
} from "@t3tools/contracts";
15
import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
16
+import type * as Arr from "effect/Array";
17
+import type * as Cause from "effect/Cause";
18
import * as Clock from "effect/Clock";
19
+import * as Deferred from "effect/Deferred";
20
import * as Effect from "effect/Effect";
21
+import * as Exit from "effect/Exit";
22
+import * as Queue from "effect/Queue";
23
import * as Schema from "effect/Schema";
24
import type * as SqlClient from "effect/sql/SqlClient";
25
import * as Stream from "effect/Stream";
26
27
+import { bufferLatestLiveStream } from "./LiveStreamBudget.ts";
28
+
29
+type ShellDelta = Extract<OrchestrationV2ShellStreamItem, { readonly sequence: number }>;
30
+
31
+/** Snapshots, synchronization, and enrichment markers must bypass full-state coalescing. */
32
+export const bufferShellLiveStream = <E, R>(
33
+ source: Stream.Stream<ShellDelta, E, R>,
34
+ limits?: { readonly maxItems?: number; readonly maxSerializedBytes?: number },
35
+) =>
36
+ bufferLatestLiveStream(
37
+ source,
38
+ (item) => {
39
+ switch (item.kind) {
40
+ case "project.updated":
41
+ return `project:${item.project.id}`;
42
+ case "project.removed":
43
+ return `project:${item.projectId}`;
44
+ case "thread.updated":
45
+ return `thread:${item.location}:${item.thread.id}`;
46
+ case "thread.removed":
47
+ return `thread:${item.location}:${item.threadId}`;
48
+ }
49
+ },
50
+ limits,
51
+ );
52
+
53
export function buildActiveShellSnapshot(input: {
54
readonly projects: ReadonlyArray<OrchestrationProjectShell>;
55
readonly threads: OrchestrationV2ThreadShellSnapshot;
@@ -112,7 +143,58 @@ export function composeShellStreamWithEnrichment<A, E, R, A2, E2, R2, A3, E3, R3
143
readonly tail: Stream.Stream<A2, E2, R2>;
144
readonly enrichment: Stream.Stream<A3, E3, R3>;
145
}): Stream.Stream<A | A2 | A3, E | E2 | E3, R | R2 | R3> {
115
- return Stream.concat(input.initial, Stream.merge(input.tail, input.enrichment));
146
+ const merged = Stream.fromPull(
147
+ Effect.gen(function* () {
148
+ const output = yield* Queue.bounded<
149
+ {
150
+ readonly items: Arr.NonEmptyReadonlyArray<A2 | A3>;
151
+ readonly acknowledged?: Deferred.Deferred<void>;
152
+ },
153
+ E2 | E3 | Cause.Done
154
+ >(0);
155
+ yield* Effect.addFinalizer(() => Queue.shutdown(output));
156
+ let remaining = 2;
157
+ const drain = (effect: Effect.Effect<void, E2 | E3, R2 | R3>) =>
158
+ effect.pipe(
159
+ Effect.exit,
160
+ Effect.flatMap((exit) =>
161
+ Exit.isFailure(exit)
162
+ ? Queue.failCause(output, exit.cause)
163
+ : --remaining === 0
164
+ ? Queue.end(output)
165
+ : Effect.void,
166
+ ),
167
+ Effect.forkScoped,
168
+ );
169
+ yield* drain(
170
+ input.tail.pipe(
171
+ Stream.runForEachArray((items) =>
172
+ Effect.gen(function* () {
173
+ const acknowledged = yield* Deferred.make<void>();
174
+ yield* Queue.offer(output, { items, acknowledged });
175
+ yield* Deferred.await(acknowledged);
176
+ }),
177
+ ),
178
+ ),
179
+ );
180
+ // Keep draining the sliding enrichment subscription after each handoff,
181
+ // as Stream.merge does, while only the budgeted tail waits for an ACK.
182
+ yield* drain(
183
+ input.enrichment.pipe(Stream.runForEachArray((items) => Queue.offer(output, { items }))),
184
+ );
185
+ let previous: Deferred.Deferred<void> | undefined;
186
+ // Stream.merge pulls ahead after handing off each batch. Wait for the next
187
+ // downstream pull so shell delivery keeps that batch charged until its RPC ACK.
188
+ // @effect-diagnostics-next-line returnEffectInGen:off - Stream.fromPull needs the pull effect as its result.
189
+ return Effect.gen(function* () {
190
+ if (previous) yield* Deferred.succeed(previous, undefined);
191
+ const next = yield* Queue.take(output);
192
+ previous = next.acknowledged;
193
+ return next.items;
194
+ });
195
+ }),
196
+ ).pipe(Stream.scoped);
197
+ return Stream.concat(input.initial, merged);
198
}
199
200
const sameProjects = Schema.toEquivalence(Schema.Array(ProjectShellSchema));
@@ -275,7 +357,10 @@ export function coalesceStoredThreadEvents(
357
export function shellStreamItemFromThreadShell(input: {
358
readonly stored: Extract<ShellApplicationEvent, { readonly event: unknown }>;
359
readonly shell: OrchestrationV2ThreadShell | null;
278
-}): Exclude<OrchestrationV2ShellStreamItem, { readonly kind: "snapshot" }> {
360
+}): Extract<
361
+ OrchestrationV2ShellStreamItem,
362
+ { readonly kind: "thread.updated" | "thread.removed" }
363
+> {
364
if (input.shell !== null) {
365
if (input.shell.archivedAt !== null) {
366
return {
apps/server/src/ws.ts
+2
-1
@@ -121,6 +121,7 @@ import * as SecretRequests from "./secrets/SecretRequests.ts";
121
import {
122
archivedShellStreamItemFromThreadShell,
123
buildActiveShellSnapshot,
124
+ bufferShellLiveStream,
125
coalesceShellApplicationEvents,
126
coalesceStoredThreadEvents,
127
composeShellStreamWithEnrichment,
@@ -1019,7 +1020,7 @@ export const subscribeOrchestrationV2Shell = Effect.fn("ws.orchestrationV2.subsc
1020
);
1021
1022
const liveFrom = (afterSequence: number) =>
1022
- bufferLiveStream(
1023
+ bufferShellLiveStream(
1024
toShellStream(
1025
applicationEvents.streamProjectedApplicationEvents({
1026
afterSequence,