@devries-cameron20 / t3code Mirror · read-only / commits / 94827737ea
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 22, 22:00 UTC

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,