@devries-cameron20 / t3code-1 / commits / beaeeff40e
Fork 0

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,