The best way to control Claude Code, Codex and more from any computer or phone
fix(acp): bound unread raw notification retention (#19585)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: maria-rcks <maria@kuuro.net>
Wout Stiens committed
Nov 7, 2026 at 11:50 UTC
beaeeff40ef108e2cdb37112bfd0dd31b4660eae
4 files changed
+275
-38
packages/effect-acp/src/agent.ts
+5
@@ -35,6 +35,11 @@ export class AcpAgent extends Context.Service<
35
AcpAgent,
36
{
37
readonly raw: {
38
+ /**
39
+ * Stream of inbound ACP notifications observed on the connection. Unread
40
+ * ones are kept best-effort: the newest 32 whose JSON lines fit in 16Mi
41
+ * characters, always including the latest. Ends when the connection does.
42
+ */
43
readonly notifications: Stream.Stream<AcpProtocol.AcpIncomingNotification>;
44
readonly request: (
45
method: string,
packages/effect-acp/src/client.ts
+5
@@ -60,6 +60,11 @@ export interface AcpClientOptions {
60
}
61
62
type AcpClientRaw = {
63
+ /**
64
+ * Inbound notifications. Unread ones are kept best-effort: the newest 32 whose
65
+ * JSON lines fit in 16Mi characters, always including the latest. Ends with the
66
+ * connection.
67
+ */
68
readonly notifications: Stream.Stream<AcpProtocol.AcpIncomingNotification>;
69
readonly request: (method: string, payload: unknown) => Effect.Effect<unknown, AcpError.AcpError>;
70
readonly notify: (method: string, payload: unknown) => Effect.Effect<void, AcpError.AcpError>;
packages/effect-acp/src/protocol.test.ts
+177
@@ -62,6 +62,16 @@ const JsonRpcErrorResponse = Schema.Struct({
62
});
63
const encodeUnknownJsonString = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
64
const encoder = new TextEncoder();
65
+const MIB = 1024 * 1024;
66
+const decodeIndex = Schema.decodeUnknownSync(Schema.Struct({ index: Schema.Number }));
67
+const largeNotification = (index: number, textLength: number) =>
68
+ encoder.encode(
69
+ `${encodeUnknownJsonString({
70
+ jsonrpc: "2.0",
71
+ method: "x/large",
72
+ params: { index, text: "x".repeat(textLength) },
73
+ })}\n`,
74
+ );
75
const mockPeerPath = Effect.map(Effect.service(Path.Path), (path) =>
76
path.join(import.meta.dirname, "../test/fixtures/acp-mock-peer.ts"),
77
);
@@ -148,6 +158,173 @@ it.layer(NodeServices.layer)("effect-acp protocol", (it) => {
158
}),
159
);
160
161
+ it.effect("keeps only recent raw notifications after their callbacks run", () =>
162
+ Effect.gen(function* () {
163
+ const { stdio, input } = yield* makeInMemoryStdio();
164
+ const handled = yield* Deferred.make<void>();
165
+ let handledCount = 0;
166
+ const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
167
+ stdio,
168
+ serverRequestMethods: new Set(),
169
+ onNotification: () =>
170
+ Effect.sync(() => ++handledCount).pipe(
171
+ Effect.flatMap((count) =>
172
+ count === 64 ? Deferred.succeed(handled, undefined).pipe(Effect.asVoid) : Effect.void,
173
+ ),
174
+ ),
175
+ });
176
+
177
+ const messages = Array.from({ length: 64 }, (_, index) =>
178
+ encodeUnknownJsonString({
179
+ jsonrpc: "2.0",
180
+ method: "x/performance",
181
+ params: { index },
182
+ }),
183
+ );
184
+ yield* Queue.offer(input, encoder.encode(`${messages.join("\n")}\n`));
185
+ yield* Deferred.await(handled);
186
+
187
+ const retained = yield* transport.incoming.pipe(Stream.take(32), Stream.runCollect);
188
+
189
+ assert.equal(handledCount, 64);
190
+ assert.equal(retained.length, 32);
191
+ assert.deepEqual(retained[0]?.params, { index: 32 });
192
+ assert.deepEqual(retained[31]?.params, { index: 63 });
193
+ }),
194
+ );
195
+
196
+ it.effect("keeps the newest unread raw notifications whose JSON fits in 16Mi characters", () =>
197
+ Effect.gen(function* () {
198
+ const { stdio, input } = yield* makeInMemoryStdio();
199
+ const handled = yield* Queue.unbounded<number>();
200
+ const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
201
+ stdio,
202
+ serverRequestMethods: new Set(),
203
+ onNotification: (notification) =>
204
+ Queue.offer(handled, decodeIndex(notification.params).index).pipe(Effect.asVoid),
205
+ });
206
+
207
+ // Ten 3 MiB notifications: only the newest five fit in the budget.
208
+ for (let index = 0; index < 10; index++) {
209
+ yield* Queue.offer(input, largeNotification(index, 3 * MIB));
210
+ assert.equal(yield* Queue.take(handled), index);
211
+ }
212
+
213
+ const retained = yield* transport.incoming.pipe(Stream.take(5), Stream.runCollect);
214
+ assert.deepEqual(
215
+ retained.map((notification) => decodeIndex(notification.params).index),
216
+ [5, 6, 7, 8, 9],
217
+ );
218
+ }),
219
+ );
220
+
221
+ it.effect("keeps a single unread raw notification that alone exceeds the budget", () =>
222
+ Effect.gen(function* () {
223
+ const { stdio, input } = yield* makeInMemoryStdio();
224
+ const handled = yield* Queue.unbounded<number>();
225
+ const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
226
+ stdio,
227
+ serverRequestMethods: new Set(),
228
+ onNotification: (notification) =>
229
+ Queue.offer(handled, decodeIndex(notification.params).index).pipe(Effect.asVoid),
230
+ });
231
+
232
+ yield* Queue.offer(input, largeNotification(0, 1));
233
+ yield* Queue.take(handled);
234
+ yield* Queue.offer(input, largeNotification(1, 17 * MIB));
235
+ yield* Queue.take(handled);
236
+
237
+ const [retained] = yield* transport.incoming.pipe(Stream.take(1), Stream.runCollect);
238
+ assert.equal(decodeIndex(retained?.params).index, 1);
239
+ }),
240
+ );
241
+
242
+ it.effect("delivers every raw notification to a reader that keeps up, then ends", () =>
243
+ Effect.gen(function* () {
244
+ const { stdio, input } = yield* makeInMemoryStdio();
245
+ const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
246
+ stdio,
247
+ serverRequestMethods: new Set(),
248
+ });
249
+ const received = yield* Queue.unbounded<number>();
250
+ const reader = yield* transport.incoming.pipe(
251
+ Stream.map((notification) => decodeIndex(notification.params).index),
252
+ Stream.tap((index) => Queue.offer(received, index)),
253
+ Stream.runCollect,
254
+ Effect.forkScoped,
255
+ );
256
+
257
+ // 30 MiB in total, well past the unread budget.
258
+ for (let index = 0; index < 10; index++) {
259
+ yield* Queue.offer(input, largeNotification(index, 3 * MIB));
260
+ assert.equal(yield* Queue.take(received), index);
261
+ }
262
+ yield* Queue.end(input);
263
+
264
+ assert.deepEqual(yield* Fiber.join(reader), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
265
+ }),
266
+ );
267
+
268
+ it.effect("ends the raw notification stream when the connection scope closes", () =>
269
+ Effect.gen(function* () {
270
+ const { stdio } = yield* makeInMemoryStdio();
271
+ const connection = yield* Scope.make();
272
+ const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
273
+ stdio,
274
+ serverRequestMethods: new Set(),
275
+ }).pipe(Scope.provide(connection));
276
+ const reader = yield* transport.incoming.pipe(Stream.runCollect, Effect.forkScoped);
277
+
278
+ yield* Scope.close(connection, Exit.void);
279
+
280
+ assert.deepEqual(yield* Fiber.join(reader), []);
281
+ }),
282
+ );
283
+
284
+ it.effect("keeps the ended raw backlog intact when notifications arrive after termination", () =>
285
+ Effect.gen(function* () {
286
+ const { stdio, input } = yield* makeInMemoryStdio();
287
+ const handled = yield* Queue.unbounded<number>();
288
+ const terminated = yield* Deferred.make<void>();
289
+ const transport = yield* AcpProtocol.makeAcpPatchedProtocol({
290
+ stdio: Stdio.make({
291
+ args: stdio.args,
292
+ stdin: stdio.stdin,
293
+ stdout: () => Sink.forEach(() => Effect.die("stdout failed")),
294
+ stderr: () => Sink.drain,
295
+ }),
296
+ serverRequestMethods: new Set(),
297
+ onNotification: (notification) =>
298
+ Queue.offer(handled, decodeIndex(notification.params).index).pipe(Effect.asVoid),
299
+ onTermination: () => Deferred.succeed(terminated, undefined).pipe(Effect.asVoid),
300
+ });
301
+ const deliver = (index: number) =>
302
+ Queue.offer(
303
+ input,
304
+ encoder.encode(
305
+ `${encodeUnknownJsonString({ jsonrpc: "2.0", method: "x/late", params: { index } })}\n`,
306
+ ),
307
+ ).pipe(Effect.andThen(Queue.take(handled)));
308
+
309
+ for (let index = 0; index < 32; index++) {
310
+ assert.equal(yield* deliver(index), index);
311
+ }
312
+ // A failed write terminates the connection while the reader keeps running.
313
+ yield* transport.notify("x/fail", {}).pipe(Effect.exit);
314
+ yield* Deferred.await(terminated);
315
+ assert.equal(yield* deliver(32), 32);
316
+
317
+ const retained = yield* transport.incoming.pipe(
318
+ Stream.map((notification) => decodeIndex(notification.params).index),
319
+ Stream.runCollect,
320
+ );
321
+ assert.deepEqual(
322
+ retained,
323
+ Array.from({ length: 32 }, (_, index) => index),
324
+ );
325
+ }),
326
+ );
327
+
328
// clanka once sent a usage_update without `used` and `size`. One bad update
329
// must not end a session whose later updates are fine.
330
it.effect("drops a session/update that fails to decode and keeps reading", () =>
packages/effect-acp/src/protocol.ts
+88
-38
@@ -128,6 +128,17 @@ interface AcpPendingRequest {
128
readonly method: string;
129
}
130
131
+/** A decoded wire message and the length of the JSON line it arrived on. */
132
+interface AcpDecodedWireMessage {
133
+ readonly message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded;
134
+ readonly lineLength: number;
135
+}
136
+
137
+interface AcpBufferedRawNotification {
138
+ readonly notification: AcpIncomingNotification;
139
+ readonly lineLength: number;
140
+}
141
+
142
interface AcpOutgoingWrite {
143
readonly acknowledgement?: Deferred.Deferred<void, AcpError.AcpError>;
144
readonly payload: string | Uint8Array;
@@ -168,7 +179,8 @@ const makeStrictNdJsonRpcParser = () => {
179
const decoder = new TextDecoder();
180
let buffer = "";
181
return {
171
- decode: (bytes: Uint8Array | string): ReadonlyArray<unknown> => {
182
+ // Every message in a batch line is charged the whole line.
183
+ decode: (bytes: Uint8Array | string): ReadonlyArray<AcpDecodedWireMessage> => {
184
const chunk = typeof bytes === "string" ? bytes : decoder.decode(bytes, { stream: true });
185
const lastNewline = chunk.lastIndexOf("\n");
186
// Splitting the whole buffer per chunk is quadratic for multi-megabyte lines.
@@ -178,7 +190,14 @@ const makeStrictNdJsonRpcParser = () => {
190
}
191
const lines = (buffer + chunk.slice(0, lastNewline)).split("\n");
192
buffer = chunk.slice(lastNewline + 1);
181
- return lines.flatMap((line) => codec.decode(line));
193
+ return lines.flatMap((line) =>
194
+ codec.decode(line).map((message) => ({
195
+ message: normalizeAcpJsonRpcError(
196
+ message as RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
197
+ ),
198
+ lineLength: line.length,
199
+ })),
200
+ );
201
},
202
// A truncated final line is left to the exit status, which explains a crash better.
203
end: (): ReadonlyArray<unknown> => {
@@ -196,7 +215,11 @@ const makeStrictNdJsonRpcParser = () => {
215
},
216
};
217
};
218
+// Unread raw notifications are best-effort. The newest is always kept; older
219
+// ones are dropped once the backlog passes either limit. The length limit counts
220
+// JSON line characters (UTF-16 code units), not bytes or heap size.
221
const MAX_BUFFERED_RAW_NOTIFICATIONS = 32;
222
+const MAX_BUFFERED_RAW_NOTIFICATION_JSON_LENGTH = 16 * 1024 * 1024;
223
224
const decodeFailureDiagnostics = (error: AcpError.AcpProtocolParseError) => ({
225
operation: error.operation,
@@ -258,9 +281,14 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
281
const parser = makeStrictNdJsonRpcParser();
282
const serverQueue = yield* Queue.unbounded<RpcMessage.FromClientEncoded>();
283
const clientQueue = yield* Queue.unbounded<RpcMessage.FromServerEncoded>();
261
- const notificationQueue = yield* Queue.sliding<AcpIncomingNotification>(
262
- MAX_BUFFERED_RAW_NOTIFICATIONS,
263
- );
284
+ const rawNotifications = yield* Queue.unbounded<AcpBufferedRawNotification, Cause.Done<void>>();
285
+ // JSON length of the notifications offered since the queue was last empty.
286
+ // `incoming` takes the whole backlog on every pull, so an empty queue holds
287
+ // nothing, and a read can only make this an overestimate.
288
+ let rawNotificationsJsonLength = 0;
289
+ // Raw readers finish with the connection: termination ends the queue, and so
290
+ // does closing the scope, which interrupts the reader before it terminates.
291
+ yield* Effect.addFinalizer(() => Queue.end(rawNotifications));
292
const disconnects = yield* Queue.unbounded<number>();
293
const outgoing = yield* Queue.unbounded<AcpOutgoingWrite, AcpError.AcpError | Cause.Done<void>>();
294
const outgoingWriterState = yield* Ref.make<AcpOutgoingWriterState>({
@@ -430,8 +458,27 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
458
),
459
);
460
433
- const dispatchNotification = (notification: AcpIncomingNotification) =>
434
- Queue.offer(notificationQueue, notification).pipe(
461
+ // Offer first so an ended queue rejects the notification without evicting the
462
+ // backlog readers are still draining. Offer and eviction share one sync block,
463
+ // so readers never see more than the limits allow.
464
+ const bufferRawNotification = (notification: AcpIncomingNotification, lineLength: number) =>
465
+ Effect.sync(() => {
466
+ if (Queue.sizeUnsafe(rawNotifications) === 0) rawNotificationsJsonLength = 0;
467
+ if (!Queue.offerUnsafe(rawNotifications, { notification, lineLength })) return;
468
+ rawNotificationsJsonLength += lineLength;
469
+ while (
470
+ Queue.sizeUnsafe(rawNotifications) > MAX_BUFFERED_RAW_NOTIFICATIONS ||
471
+ (Queue.sizeUnsafe(rawNotifications) > 1 &&
472
+ rawNotificationsJsonLength > MAX_BUFFERED_RAW_NOTIFICATION_JSON_LENGTH)
473
+ ) {
474
+ const dropped = Queue.takeUnsafe(rawNotifications);
475
+ if (dropped === undefined || Exit.isFailure(dropped)) break;
476
+ rawNotificationsJsonLength -= dropped.value.lineLength;
477
+ }
478
+ });
479
+
480
+ const dispatchNotification = (notification: AcpIncomingNotification, lineLength: number) =>
481
+ bufferRawNotification(notification, lineLength).pipe(
482
Effect.andThen(
483
// A failing or dying handler must not stop the reader, or every later
484
// message on the connection goes unanswered.
@@ -461,6 +508,7 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
508
return [
509
Effect.gen(function* () {
510
yield* Queue.offer(disconnects, 0);
511
+ yield* Queue.end(rawNotifications);
512
const error = yield* classify();
513
yield* Deferred.fail(terminationFailure, error);
514
yield* failAllExtPending(error);
@@ -569,18 +617,21 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
617
);
618
};
619
572
- const handleRequestEncoded = (message: RpcMessage.RequestEncoded) => {
620
+ const handleRequestEncoded = (message: RpcMessage.RequestEncoded, lineLength: number) => {
621
if (message.id === "") {
622
if (message.tag === CLIENT_METHODS.session_update) {
623
return decodeSessionUpdate(message.payload).pipe(
624
Effect.matchEffect({
625
onFailure: dropUndecodableNotification(CLIENT_METHODS.session_update),
626
onSuccess: (params) =>
579
- dispatchNotification({
580
- _tag: "SessionUpdate",
581
- method: CLIENT_METHODS.session_update,
582
- params: options.transformSessionUpdate?.(params) ?? params,
583
- }),
627
+ dispatchNotification(
628
+ {
629
+ _tag: "SessionUpdate",
630
+ method: CLIENT_METHODS.session_update,
631
+ params: options.transformSessionUpdate?.(params) ?? params,
632
+ },
633
+ lineLength,
634
+ ),
635
}),
636
);
637
}
@@ -593,15 +644,14 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
644
Effect.matchEffect({
645
onFailure: dropUndecodableNotification(method),
646
onSuccess: (params) =>
596
- dispatchNotification({ _tag: "ElicitationComplete", method, params }),
647
+ dispatchNotification({ _tag: "ElicitationComplete", method, params }, lineLength),
648
}),
649
);
650
}
600
- return dispatchNotification({
601
- _tag: "ExtNotification",
602
- method: message.tag,
603
- params: message.payload,
604
- });
651
+ return dispatchNotification(
652
+ { _tag: "ExtNotification", method: message.tag, params: message.payload },
653
+ lineLength,
654
+ );
655
}
656
657
const observeIncoming =
@@ -677,12 +727,13 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
727
}),
728
);
729
680
- const routeDecodedMessage = (
681
- message: RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded,
682
- ): Effect.Effect<void, AcpError.AcpError> => {
730
+ const routeDecodedMessage = ({
731
+ message,
732
+ lineLength,
733
+ }: AcpDecodedWireMessage): Effect.Effect<void, AcpError.AcpError> => {
734
switch (message._tag) {
735
case "Request":
685
- return handleRequestEncoded(message);
736
+ return handleRequestEncoded(message, lineLength);
737
case "Exit":
738
return handleExitEncoded(message);
739
case "Chunk":
@@ -724,12 +775,7 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
775
).pipe(
776
Effect.flatMap(() =>
777
Effect.try({
727
- try: () =>
728
- (
729
- parser.decode(data) as ReadonlyArray<
730
- RpcMessage.FromClientEncoded | RpcMessage.FromServerEncoded
731
- >
732
- ).map(normalizeAcpJsonRpcError),
778
+ try: () => parser.decode(data),
779
catch: (cause) =>
780
new AcpError.AcpProtocolParseError({
781
operation: "decode-wire-message",
@@ -737,12 +783,14 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
783
}),
784
}),
785
),
740
- Effect.tap((messages) =>
741
- logProtocol({
742
- direction: "incoming",
743
- stage: "decoded",
744
- payload: messages,
745
- }),
786
+ Effect.tap((decoded) =>
787
+ options.logIncoming
788
+ ? logProtocol({
789
+ direction: "incoming",
790
+ stage: "decoded",
791
+ payload: decoded.map(({ message }) => message),
792
+ })
793
+ : Effect.void,
794
),
795
Effect.tapErrorTag("AcpProtocolParseError", (error) =>
796
logProtocol({
@@ -751,8 +799,8 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
799
payload: decodeFailureDiagnostics(error),
800
}),
801
),
754
- Effect.flatMap((messages) =>
755
- Effect.forEach(messages, routeDecodedMessage, {
802
+ Effect.flatMap((decoded) =>
803
+ Effect.forEach(decoded, routeDecodedMessage, {
804
discard: true,
805
}),
806
),
@@ -1032,7 +1080,9 @@ export const makeAcpPatchedProtocol = Effect.fn("makeAcpPatchedProtocol")(functi
1080
clientProtocol,
1081
serverProtocol,
1082
get incoming() {
1035
- return Stream.fromQueue(notificationQueue);
1083
+ return Stream.fromQueue(rawNotifications).pipe(
1084
+ Stream.map(({ notification }) => notification),
1085
+ );
1086
},
1087
request: sendRequest,
1088
notify: sendNotification,