The best way to control Claude Code, Codex and more from any computer or phone
fix(server): coalesce tool output before it fills the live buffer (#16317)
Co-authored-by: maria-rcks <maria@kuuro.net>
Alyx Buckmann committed
Nov 6, 2026 at 05:21 UTC
693ac5f5df23a8fd8432ce73c356d05edc40bd0a
3 files changed
+151
-19
apps/server/src/orchestration-v2/LiveStreamBudget.test.ts
+57
@@ -87,6 +87,63 @@ describe("bufferLatestLiveStream", () => {
87
});
88
89
describe("replayAndBufferProjectedLiveEvents", () => {
90
+ it.effect.each(["items", "bytes"] as const)(
91
+ "replays the undelivered tail after a %s overflow without losing or duplicating events",
92
+ (limit) =>
93
+ Effect.scoped(
94
+ Effect.gen(function* () {
95
+ const pubsub = yield* PubSub.unbounded<Event>();
96
+ const subscribed = yield* Deferred.make<PubSub.Subscription<Event>>();
97
+ const events = [
98
+ { sequence: 1, text: "one" },
99
+ { sequence: 2, text: "two" },
100
+ { sequence: 3, text: "three" },
101
+ ];
102
+ const limits = limit === "items" ? { maxItems: 1 } : { maxSerializedBytes: 40 };
103
+ const pull = yield* Stream.toPull(
104
+ replayAndBufferProjectedLiveEvents(
105
+ {
106
+ project: (event: Event) => event,
107
+ subscribe: PubSub.subscribe(pubsub).pipe(
108
+ Effect.tap((subscription) => Deferred.succeed(subscribed, subscription)),
109
+ ),
110
+ latestSequence: Effect.succeed(1),
111
+ replay: () => Stream.succeed(events[0]!),
112
+ },
113
+ limits,
114
+ ),
115
+ );
116
+ const received = [...(yield* pull)];
117
+ // Hold the ACK while more durable events arrive.
118
+ yield* PubSub.publishAll(pubsub, events.slice(1));
119
+ yield* (yield* Deferred.await(subscribed)).shutdownHook.await;
120
+ const overflow = yield* pull.pipe(Effect.result);
121
+ expect(overflow._tag).toBe("Failure");
122
+ if (overflow._tag === "Failure")
123
+ expect(overflow.failure._tag).toBe("LiveStreamBufferError");
124
+
125
+ const afterSequence = received.at(-1)!.sequence;
126
+ const resumed = yield* replayAndBufferProjectedLiveEvents(
127
+ {
128
+ project: (event: Event) => event,
129
+ subscribe: PubSub.subscribe(pubsub),
130
+ afterSequence,
131
+ latestSequence: Effect.succeed(3),
132
+ replay: (throughSequence) =>
133
+ Stream.fromIterable(
134
+ events.filter(
135
+ (event) => event.sequence > afterSequence && event.sequence <= throughSequence,
136
+ ),
137
+ ),
138
+ },
139
+ limits,
140
+ ).pipe(Stream.take(2), Stream.runCollect);
141
+ expect([...received, ...resumed]).toEqual(events);
142
+ expect(yield* PubSub.size(pubsub)).toBe(0);
143
+ }),
144
+ ),
145
+ );
146
+
147
it.effect.each(["high-water", "replay"] as const)(
148
"unsubscribes and cancels a blocked %s read on live overflow",
149
(phase) =>
apps/server/src/orchestration-v2/ThreadLiveEventCoalescer.test.ts
+60
-3
@@ -36,6 +36,7 @@ function makeToolActivity(
36
readonly kind?: "tool.updated" | "tool.completed";
37
readonly toolCallId?: string;
38
readonly turnId?: RunId;
39
+ readonly output?: string;
40
} = {},
41
): ThreadEvent {
42
const itemRunId = options.turnId ?? runId;
@@ -66,7 +67,7 @@ function makeToolActivity(
67
completedAt: status === "completed" ? now : null,
68
updatedAt: now,
69
input: "echo app.ts",
69
- output: `output-${sequence}`,
70
+ output: options.output ?? `output-${sequence}`,
71
},
72
},
73
};
@@ -155,6 +156,62 @@ function makeTextItem(
156
}
157
158
describe("ThreadLiveEventCoalescer", () => {
159
+ it.effect.each(["items", "bytes"] as const)(
160
+ "replaces superseded tool output before charging the %s budget",
161
+ (limit) =>
162
+ Effect.scoped(
163
+ Effect.gen(function* () {
164
+ const updates = Array.from({ length: 1_100 }, (_, index) => makeToolActivity(index + 1));
165
+ const latest = updates.at(-1)!;
166
+ const coalescer = yield* makeThreadLiveEventCoalescer(
167
+ limit === "items"
168
+ ? { maxItems: 1 }
169
+ : { maxSerializedBytes: Buffer.byteLength(encodeEvent(latest)) },
170
+ );
171
+ yield* coalescer.offerAll(updates);
172
+ expect(yield* coalescer.usage).toEqual({
173
+ retainedItems: 1,
174
+ retainedSerializedBytes: Buffer.byteLength(encodeEvent(latest)),
175
+ });
176
+ yield* coalescer.end;
177
+ expect(yield* coalescer.stream.pipe(Stream.runCollect)).toEqual([latest]);
178
+ expect(yield* coalescer.usage).toEqual({ retainedItems: 0, retainedSerializedBytes: 0 });
179
+ }),
180
+ ),
181
+ );
182
+
183
+ it.effect("handles a tool output burst larger than the default 8 MiB buffer", () =>
184
+ Effect.scoped(
185
+ Effect.gen(function* () {
186
+ const coalescer = yield* makeThreadLiveEventCoalescer();
187
+ const updates = Array.from({ length: 150 }, (_, index) =>
188
+ makeToolActivity(index + 1, { output: "x".repeat(64 * 1024) }),
189
+ );
190
+ yield* coalescer.offerAll(updates);
191
+ yield* coalescer.end;
192
+ expect(yield* coalescer.stream.pipe(Stream.runCollect)).toEqual([updates.at(-1)]);
193
+ }),
194
+ ),
195
+ );
196
+
197
+ it.effect("still fails when a single replacement exceeds the byte budget", () =>
198
+ Effect.scoped(
199
+ Effect.gen(function* () {
200
+ const first = makeToolActivity(1);
201
+ const coalescer = yield* makeThreadLiveEventCoalescer({
202
+ maxSerializedBytes: Buffer.byteLength(encodeEvent(first)),
203
+ });
204
+ yield* coalescer.offer(first);
205
+ const overflow = yield* coalescer
206
+ .offer(makeToolActivity(2, { output: "x".repeat(2_000) }))
207
+ .pipe(Effect.result);
208
+ expect(overflow._tag).toBe("Failure");
209
+ yield* coalescer.closed;
210
+ expect(yield* coalescer.usage).toEqual({ retainedItems: 0, retainedSerializedBytes: 0 });
211
+ }),
212
+ ),
213
+ );
214
+
215
it("preserves tool-call identity switches as insertion-order boundaries", () => {
216
const events = [
217
makeToolActivity(1, { toolCallId: "call-a" }),
@@ -399,8 +456,8 @@ describe("ThreadLiveEventCoalescer", () => {
456
yield* TestClock.adjust("40 millis");
457
yield* coalescer.offerAll(latest);
458
expect(yield* coalescer.usage).toEqual({
402
- retainedItems: 4,
403
- retainedSerializedBytes: serializedBytes([...first, ...latest]),
459
+ retainedItems: 2,
460
+ retainedSerializedBytes: serializedBytes(latest),
461
});
462
yield* TestClock.adjust("10 millis");
463
const expectedUsage = {
apps/server/src/orchestration-v2/ThreadLiveEventCoalescer.ts
+34
-16
@@ -90,7 +90,9 @@ export const makeThreadLiveEventCoalescer = Effect.fn(
90
E | LiveStreamBufferError | Cause.Done
91
>();
92
const mutex = yield* Semaphore.make(1);
93
- let pendingUpdates: Array<RetainedLiveItem<ThreadLiveEvent>> = [];
93
+ const pendingUpdates = new Set<RetainedLiveItem<ThreadLiveEvent>>();
94
+ const latestUpdates = new Map<string, RetainedLiveItem<ThreadLiveEvent>>();
95
+ const pendingKeys = new Map<ThreadLiveEvent["event"]["type"], string>();
96
let windowGeneration = 0;
97
let windowFiber: Fiber.Fiber<void, never> | null = null;
98
let closed = false;
@@ -106,14 +108,13 @@ export const makeThreadLiveEventCoalescer = Effect.fn(
108
});
109
110
const flushPending = Effect.fnUntraced(function* () {
109
- if (pendingUpdates.length === 0) {
111
+ if (pendingUpdates.size === 0) {
112
return;
113
}
112
- const items = yield* budget.replace(
113
- pendingUpdates,
114
- coalesceLiveUpdatedEvents(pendingUpdates.map((item) => item.value)),
115
- );
116
- pendingUpdates = [];
114
+ const items = Array.from(pendingUpdates);
115
+ pendingUpdates.clear();
116
+ latestUpdates.clear();
117
+ pendingKeys.clear();
118
yield* Queue.offerAll(output, items);
119
}, Effect.uninterruptible);
120
@@ -131,7 +132,6 @@ export const makeThreadLiveEventCoalescer = Effect.fn(
132
}
133
}),
134
),
134
- Effect.catchTags({ LiveStreamBufferError: () => Effect.void }),
135
);
136
137
// Keep each source batch together so a synchronization marker cannot pass
@@ -143,18 +143,28 @@ export const makeThreadLiveEventCoalescer = Effect.fn(
143
(input) =>
144
Effect.gen(function* () {
145
yield* budget.check;
146
- if (input.kind === "event") {
147
- yield* budget.retain(input).pipe(
148
- Effect.tap((item) => Effect.sync(() => pendingUpdates.push(item))),
146
+ const startsWindow = pendingUpdates.size === 0;
147
+ const key = input.kind === "event" ? coalescibleUpdateKey(input) : null;
148
+ if (input.kind === "event" && key !== null) {
149
+ const pendingKey = pendingKeys.get(input.event.type);
150
+ if (pendingKey !== undefined && pendingKey !== key) latestUpdates.clear();
151
+ pendingKeys.set(input.event.type, key);
152
+ const previous = latestUpdates.get(key);
153
+ yield* budget.replace(previous ? [previous] : [], [input]).pipe(
154
+ Effect.tap(([item]) =>
155
+ Effect.sync(() => {
156
+ if (previous) pendingUpdates.delete(previous);
157
+ pendingUpdates.add(item!);
158
+ latestUpdates.set(key, item!);
159
+ }),
160
+ ),
161
Effect.uninterruptible,
162
);
151
- }
152
- if (input.kind === "event" && coalescibleUpdateKey(input) !== null) {
153
- if (pendingUpdates.length === 1) {
163
+ if (startsWindow) {
164
const generation = ++windowGeneration;
165
windowFiber = yield* Effect.forkIn(flushWindow(generation), coalescerScope);
166
}
157
- if (pendingUpdates.length >= MAX_PENDING_UPDATES) {
167
+ if (pendingUpdates.size >= MAX_PENDING_UPDATES) {
168
yield* cancelWindow();
169
windowGeneration += 1;
170
yield* flushPending();
@@ -162,6 +172,12 @@ export const makeThreadLiveEventCoalescer = Effect.fn(
172
return;
173
}
174
175
+ if (input.kind === "event") {
176
+ yield* budget.retain(input).pipe(
177
+ Effect.tap((item) => Effect.sync(() => pendingUpdates.add(item))),
178
+ Effect.uninterruptible,
179
+ );
180
+ }
181
yield* cancelWindow();
182
windowGeneration += 1;
183
yield* flushPending();
@@ -187,7 +203,9 @@ export const makeThreadLiveEventCoalescer = Effect.fn(
203
windowGeneration += 1;
204
yield* cancelWindow();
205
budget.release(pendingUpdates);
190
- pendingUpdates = [];
206
+ pendingUpdates.clear();
207
+ latestUpdates.clear();
208
+ pendingKeys.clear();
209
budget.release(yield* Queue.clear(output).pipe(Effect.orElseSucceed(() => [])));
210
if (cause) {
211
yield* Queue.failCause(output, cause);