@agentrq/acp-gateway 0.2.4 → 0.2.6

package/dist/__tests__/acpClient.test.js

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
 import { AgentRQACPClient } from "../acpClient.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -8,15 +9,25 @@ vi.mock("node:path");
 describe("AgentRQACPClient", () => {
     let mcpBridge;
     let client;
+    /**
+     * Answers the tool call that is waiting, the way agentrq does: by echoing
+     * back the request id the gateway actually sent.
+     */
+    function answerWith(behavior) {
+        setTimeout(() => {
+            const sent = mcpBridge.sendNotification.mock.calls.at(-1)?.[1];
+            mcpBridge.emit("verdict", { requestId: sent?.request_id, behavior });
+        }, 10);
+    }
     beforeEach(() => {
         vi.clearAllMocks();
-        mcpBridge = {
+        // A real emitter: the client registers one shared verdict listener when it
+        // is constructed, so a mocked `on` would never see a verdict at all.
+        mcpBridge = Object.assign(new EventEmitter(), {
             getSessionId: vi.fn().mockReturnValue("test-session"),
             sendNotification: vi.fn().mockResolvedValue(undefined),
             callTool: vi.fn(),
-            on: vi.fn(),
-            off: vi.fn(),
-        };
+        });
         client = new AgentRQACPClient(mcpBridge);
     });
     describe("requestPermission", () => {
@@ -32,11 +43,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "deny", name: "Deny" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-1");
         });
@@ -58,8 +65,8 @@ describe("AgentRQACPClient", () => {
             // here would surface as an unhandled rejection and crash the gateway.
             const response = await client.requestPermission(params);
             expect(response.outcome.outcome).toBe("cancelled");
-            // It must not register a verdict listener it can never clean up.
-            expect(mcpBridge.on).not.toHaveBeenCalled();
+            // Nothing may be left waiting on a verdict that will never come.
+            expect(client.pendingPermissionCount).toBe(0);
             consoleSpy.mockRestore();
         });
         it("should include task_id in the payload when available", async () => {
@@ -77,11 +84,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "deny", name: "Deny" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await clientWithTaskId.requestPermission(params);
             expect(getTaskId).toHaveBeenCalledWith("sess-1");
             expect(mcpBridge.sendNotification).toHaveBeenCalledWith("notifications/claude/channel/permission_request", expect.objectContaining({
@@ -112,11 +115,7 @@ describe("AgentRQACPClient", () => {
                 toolCall: { toolCallId: "req-123" },
                 options: [{ optionId: "opt-1", kind: "allow", name: "Allow" }],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             // Permission matching still works based on behavior, independent of title presence
             expect(response.outcome.optionId).toBe("opt-1");
@@ -130,11 +129,7 @@ describe("AgentRQACPClient", () => {
                 toolCall: { toolCallId: "req-123", title: "Test Tool" },
                 options: [{ optionId: "opt-1", kind: "allow", name: "Allow" }],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-1");
             expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Bridge Session ID: unknown"));
@@ -188,11 +183,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "reject_once", name: "Reject" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "call_abc", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await client.requestPermission(params);
             // A non-agentrq tool still goes to the human, but now with a meaningful
             // name and input rather than "Unknown Tool" / "{}".
@@ -224,11 +215,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "reject_once", name: "Reject" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "call_cmd", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await client.requestPermission(params);
             expect(mcpBridge.sendNotification).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
                 tool_name: "Run command",
@@ -244,11 +231,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "reject_once", name: "Reject" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "call_unseen", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await client.requestPermission(params);
             expect(mcpBridge.sendNotification).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ tool_name: "Unknown Tool", input_preview: "{}" }));
         });
@@ -270,11 +253,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "reject_once", name: "Reject" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "call_done", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await client.requestPermission(params);
             // Entry was dropped on completion, so it is no longer auto-allowed by
             // the remembered title — it goes to the human as an unknown tool.
@@ -303,11 +282,7 @@ describe("AgentRQACPClient", () => {
             expect(first.outcome.optionId).toBe("opt-1");
             expect(mcpBridge.sendNotification).not.toHaveBeenCalled();
             // A replay of the same id no longer resolves, so it reaches the human.
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "call_once", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await client.requestPermission(params);
             expect(mcpBridge.sendNotification).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ tool_name: "Unknown Tool" }));
         });
@@ -360,11 +335,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "reject_once", name: "Reject" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "call_bare", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             await client.requestPermission(params);
             expect(mcpBridge.sendNotification).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ tool_name: "Unknown Tool", input_preview: "{}" }));
         });
@@ -382,11 +353,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "other", name: "No" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-1");
         });
@@ -398,11 +365,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "other", name: "Deny this" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "deny" }), 10);
-                }
-            });
+            answerWith("deny");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-2");
         });
@@ -414,11 +377,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "other", name: "Other 2" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "deny" }), 10);
-                }
-            });
+            answerWith("deny");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-1");
         });
@@ -430,11 +389,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "reject_once", name: "Reject Once" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "deny" }), 10);
-                }
-            });
+            answerWith("deny");
             const response = await client.requestPermission(params);
             // A spec-compliant "reject_once" kind must never be missed and fall
             // through to the first (allow) option — that would silently approve a
@@ -449,11 +404,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-2", kind: "other", name: "Skip" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "deny" }), 10);
-                }
-            });
+            answerWith("deny");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-2");
         });
@@ -462,11 +413,7 @@ describe("AgentRQACPClient", () => {
                 toolCall: { toolCallId: "req-123" },
                 options: [{ optionId: "opt-1", kind: "allow_once", name: "Proceed" }],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "deny" }), 10);
-                }
-            });
+            answerWith("deny");
             const response = await client.requestPermission(params);
             expect(response.outcome.outcome).toBe("cancelled");
         });
@@ -478,11 +425,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-once", kind: "allow_once", name: "Allow Once" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             // Selecting "allow_always" would make the spawned agent remember this
             // decision and stop asking for matching future tool calls, bypassing
@@ -497,11 +440,7 @@ describe("AgentRQACPClient", () => {
                     { optionId: "opt-once", kind: "reject_once", name: "Reject Once" },
                 ],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "deny" }), 10);
-                }
-            });
+            answerWith("deny");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-once");
         });
@@ -510,11 +449,7 @@ describe("AgentRQACPClient", () => {
                 toolCall: { toolCallId: "req-123" },
                 options: [{ optionId: "opt-always", kind: "allow_always", name: "Always Allow" }],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             expect(response.outcome.outcome).toBe("cancelled");
         });
@@ -523,11 +458,7 @@ describe("AgentRQACPClient", () => {
                 toolCall: { toolCallId: "req-123" },
                 options: [{ optionId: "opt-default", kind: "other", name: "Maybe" }],
             };
-            mcpBridge.on.mockImplementation((event, handler) => {
-                if (event === "verdict") {
-                    setTimeout(() => handler({ requestId: "req-123", behavior: "allow" }), 10);
-                }
-            });
+            answerWith("allow");
             const response = await client.requestPermission(params);
             expect(response.outcome.optionId).toBe("opt-default");
         });
@@ -865,6 +796,264 @@ describe("AgentRQACPClient", () => {
             expect(mcpBridge.callTool).toHaveBeenCalledWith("reply", { chatId: "task-123", text: "Hello world" });
         });
     });
+    describe("waiting for a verdict", () => {
+        const params = (overrides = {}) => ({
+            sessionId: "sess-1",
+            toolCall: { toolCallId: "call-1", title: "Bash", rawInput: { command: "ls" } },
+            options: [
+                { optionId: "opt-1", kind: "allow_once", name: "Allow" },
+                { optionId: "opt-2", kind: "reject_once", name: "Deny" },
+            ],
+            ...overrides,
+        });
+        it("should scope the request id to the session it came from", async () => {
+            answerWith("allow");
+            await client.requestPermission(params());
+            // agentrq keys its bookkeeping on the request id alone, workspace-wide,
+            // while tool call ids are only unique within one session.
+            expect(mcpBridge.sendNotification.mock.calls[0][1].request_id).toBe("sess-1:call-1");
+        });
+        it("should fall back to the bare tool call id when there is no session", async () => {
+            answerWith("allow");
+            await client.requestPermission(params({ sessionId: undefined }));
+            expect(mcpBridge.sendNotification.mock.calls[0][1].request_id).toBe("call-1");
+        });
+        it("should keep one verdict listener however many calls are waiting", async () => {
+            const waiting = [
+                client.requestPermission(params()),
+                client.requestPermission(params({ toolCall: { toolCallId: "call-2", title: "Bash" } })),
+                client.requestPermission(params({ toolCall: { toolCallId: "call-3", title: "Bash" } })),
+            ];
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(3));
+            // A listener per request was only ever removed on a matching verdict, so
+            // every unanswered request leaked one for the life of the process.
+            expect(mcpBridge.listenerCount("verdict")).toBe(1);
+            client.cancelPendingPermissions("test");
+            await Promise.all(waiting);
+            expect(client.pendingPermissionCount).toBe(0);
+        });
+        it("should ignore a verdict for a call that is not waiting", async () => {
+            answerWith("allow");
+            await client.requestPermission(params());
+            expect(() => mcpBridge.emit("verdict", { requestId: "gone", behavior: "allow" })).not.toThrow();
+        });
+        it("should give up on a call nobody answers, and stop the turn", async () => {
+            vi.useFakeTimers();
+            const cancel = vi.fn();
+            const bounded = new AgentRQACPClient(mcpBridge, () => "task-1", {
+                permissionTimeoutMs: 60_000,
+            });
+            bounded.setSessionCanceller(cancel);
+            const waiting = bounded.requestPermission(params());
+            await vi.waitFor(() => expect(bounded.pendingPermissionCount).toBe(1));
+            await vi.advanceTimersByTimeAsync(60_000);
+            // Cancelling as well as answering: the spec treats "cancelled" as the
+            // answer a client gives because it cancelled the turn. Answering alone
+            // would leave the agent free to carry on and ask again.
+            expect((await waiting).outcome.outcome).toBe("cancelled");
+            expect(cancel).toHaveBeenCalledWith("sess-1");
+            expect(bounded.pendingPermissionCount).toBe(0);
+            vi.useRealTimers();
+        });
+        it("should survive a turn that cannot be cancelled", async () => {
+            vi.useFakeTimers();
+            const bounded = new AgentRQACPClient(mcpBridge, () => "task-1", {
+                permissionTimeoutMs: 60_000,
+            });
+            bounded.setSessionCanceller(() => {
+                throw new Error("connection gone");
+            });
+            const waiting = bounded.requestPermission(params());
+            await vi.waitFor(() => expect(bounded.pendingPermissionCount).toBe(1));
+            await vi.advanceTimersByTimeAsync(60_000);
+            expect((await waiting).outcome.outcome).toBe("cancelled");
+            vi.useRealTimers();
+        });
+        it("should wait indefinitely when the timeout is switched off", async () => {
+            vi.useFakeTimers();
+            const unbounded = new AgentRQACPClient(mcpBridge, () => "task-1", {
+                permissionTimeoutMs: 0,
+            });
+            const waiting = unbounded.requestPermission(params());
+            await vi.waitFor(() => expect(unbounded.pendingPermissionCount).toBe(1));
+            await vi.advanceTimersByTimeAsync(24 * 60 * 60_000);
+            expect(unbounded.pendingPermissionCount).toBe(1);
+            unbounded.cancelPendingPermissions("test over");
+            expect((await waiting).outcome.outcome).toBe("cancelled");
+            vi.useRealTimers();
+        });
+        it("should answer everything still waiting when the agent is gone", async () => {
+            const waiting = client.requestPermission(params());
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(1));
+            client.cancelPendingPermissions("agent process exited");
+            expect((await waiting).outcome.outcome).toBe("cancelled");
+            expect(client.pendingPermissionCount).toBe(0);
+        });
+        it("should re-send waiting calls when the workspace reconnects", async () => {
+            const waiting = client.requestPermission(params());
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(1));
+            const sentFirst = mcpBridge.sendNotification.mock.calls.length;
+            mcpBridge.emit("reconnected");
+            await vi.waitFor(() => expect(mcpBridge.sendNotification.mock.calls.length).toBe(sentFirst + 1));
+            // Same request id: the workspace has to recognise this as the decision it
+            // is already showing, not a new one to ask about again.
+            const [first, resent] = mcpBridge.sendNotification.mock.calls.map((c) => c[1]);
+            expect(resent).toEqual(first);
+            expect(client.pendingPermissionCount).toBe(1);
+            answerWith("allow");
+            expect((await waiting).outcome.outcome).toBe("selected");
+        });
+        it("should not talk to the workspace on reconnect when nothing is waiting", () => {
+            mcpBridge.emit("reconnected");
+            expect(mcpBridge.sendNotification).not.toHaveBeenCalled();
+        });
+        it("should keep waiting when the re-send itself fails", async () => {
+            const waiting = client.requestPermission(params());
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(1));
+            mcpBridge.sendNotification.mockRejectedValueOnce(new Error("still down"));
+            mcpBridge.emit("reconnected");
+            await vi.waitFor(() => expect(mcpBridge.sendNotification.mock.calls.length).toBeGreaterThan(1));
+            // The next reconnect gets another go; giving up here would lose the turn.
+            expect(client.pendingPermissionCount).toBe(1);
+            client.cancelPendingPermissions("test over");
+            await waiting;
+        });
+        it("should cancel only the pending permissions for the specified session", async () => {
+            const waitSess1 = client.requestPermission(params({ sessionId: "sess-1", toolCall: { toolCallId: "call-1", title: "Bash" } }));
+            const waitSess2 = client.requestPermission(params({ sessionId: "sess-2", toolCall: { toolCallId: "call-2", title: "Bash" } }));
+            const waitNoSess = client.requestPermission(params({ sessionId: undefined, toolCall: { toolCallId: "call-3", title: "Bash" } }));
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(3));
+            client.cancelPendingPermissions("task cancelled", "sess-1");
+            expect((await waitSess1).outcome.outcome).toBe("cancelled");
+            expect(client.pendingPermissionCount).toBe(2);
+            // Requests with undefined sessionId should NOT be cancelled by a session-scoped cancel
+            mcpBridge.emit("verdict", { requestId: "sess-2:call-2", behavior: "allow" });
+            expect((await waitSess2).outcome.outcome).toBe("selected");
+            mcpBridge.emit("verdict", { requestId: "call-3", behavior: "allow" });
+            expect((await waitNoSess).outcome.outcome).toBe("selected");
+            expect(client.pendingPermissionCount).toBe(0);
+        });
+        it("should do nothing if sessionId does not match any waiting permissions", async () => {
+            const waiting = client.requestPermission(params({ sessionId: "sess-1" }));
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(1));
+            client.cancelPendingPermissions("task cancelled", "sess-999");
+            expect(client.pendingPermissionCount).toBe(1);
+            answerWith("allow");
+            expect((await waiting).outcome.outcome).toBe("selected");
+        });
+        it("should send session/cancel RPC before settling pending permissions", async () => {
+            const callOrder = [];
+            const cancelSession = vi.fn().mockImplementation(async () => {
+                callOrder.push("cancelRPC");
+            });
+            client.setSessionCanceller(cancelSession);
+            const waiting = client.requestPermission(params({ sessionId: "sess-1" })).then((res) => {
+                callOrder.push("settledPermission");
+                return res;
+            });
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(1));
+            await client.cancelTurn("sess-1");
+            const res = await waiting;
+            expect(callOrder).toEqual(["cancelRPC", "settledPermission"]);
+            expect(res.outcome.outcome).toBe("cancelled");
+            expect(cancelSession).toHaveBeenCalledWith("sess-1");
+            expect(client.pendingPermissionCount).toBe(0);
+        });
+        it("should settle waiting permissions even if session/cancel never returns", async () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            // An agent wedged on its stdin: the write goes out, nothing comes back.
+            // The permissions must still settle or their queue slots are held forever.
+            client.setSessionCanceller(() => new Promise(() => { }));
+            const waiting = client.requestPermission(params({ sessionId: "sess-1" }));
+            await vi.waitFor(() => expect(client.pendingPermissionCount).toBe(1));
+            vi.useFakeTimers();
+            try {
+                const cancelling = client.cancelTurn("sess-1");
+                await vi.advanceTimersByTimeAsync(5000);
+                await cancelling;
+            }
+            finally {
+                vi.useRealTimers();
+            }
+            expect((await waiting).outcome.outcome).toBe("cancelled");
+            expect(client.pendingPermissionCount).toBe(0);
+            errorSpy.mockRestore();
+        });
+        it("should handle cancelTurn with undefined sessionId or no canceller gracefully", async () => {
+            await expect(client.cancelTurn(undefined)).resolves.toBeUndefined();
+            const freshClient = new AgentRQACPClient(mcpBridge, () => "task-1");
+            await expect(freshClient.cancelTurn("sess-1")).resolves.toBeUndefined();
+        });
+        it("should log error if cancelSession rejects during cancelTurn", async () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            client.setSessionCanceller(() => {
+                throw new Error("cancel RPC failed");
+            });
+            await client.cancelTurn("sess-1");
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to cancel turn for session sess-1:"), expect.any(Error));
+            errorSpy.mockRestore();
+        });
+        it("should say nothing when there is nothing waiting to cancel", () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            client.cancelPendingPermissions("nothing doing");
+            expect(errorSpy).not.toHaveBeenCalled();
+            errorSpy.mockRestore();
+        });
+    });
+    describe("session mode changes", () => {
+        it("should hand a mode change to whoever is watching for it", async () => {
+            const onMode = vi.fn();
+            client.setModeChangeHandler(onMode);
+            await client.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "current_mode_update", currentModeId: "auto" },
+            });
+            expect(onMode).toHaveBeenCalledWith("sess-1", "auto");
+        });
+        it("should not mind a mode change nobody is watching for", async () => {
+            await expect(client.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "current_mode_update", currentModeId: "auto" },
+            })).resolves.toBeUndefined();
+        });
+    });
+    describe("reportStopReason", () => {
+        function clientForTask(taskId) {
+            return new AgentRQACPClient(mcpBridge, () => taskId);
+        }
+        it("should say nothing when the agent simply finished", async () => {
+            await clientForTask("task-1").reportStopReason("sess-1", "end_turn");
+            expect(mcpBridge.callTool).not.toHaveBeenCalled();
+        });
+        it("should tell the workspace when a turn was refused or cut short", async () => {
+            const client = clientForTask("task-1");
+            await client.reportStopReason("sess-1", "refusal");
+            await client.reportStopReason("sess-1", "max_tokens");
+            await client.reportStopReason("sess-1", "max_turn_requests");
+            await client.reportStopReason("sess-1", "cancelled");
+            const texts = mcpBridge.callTool.mock.calls.map((c) => c[1].text);
+            expect(mcpBridge.callTool.mock.calls.every((c) => c[0] === "reply")).toBe(true);
+            expect(texts[0]).toContain("refused");
+            expect(texts[1]).toContain("ran out of output tokens");
+            expect(texts[2]).toContain("model requests");
+            expect(texts[3]).toContain("cancelled");
+        });
+        it("should still report a stop reason it does not recognise", async () => {
+            await clientForTask("task-1").reportStopReason("sess-1", "something_new");
+            expect(mcpBridge.callTool).toHaveBeenCalledWith("reply", {
+                chatId: "task-1",
+                text: expect.stringContaining("something_new"),
+            });
+        });
+        it("should skip a session with no task behind it", async () => {
+            await clientForTask(undefined).reportStopReason("sess-1", "refusal");
+            expect(mcpBridge.callTool).not.toHaveBeenCalled();
+        });
+        it("should survive a workspace that cannot be reached", async () => {
+            mcpBridge.callTool.mockRejectedValue(new Error("offline"));
+            await expect(clientForTask("task-1").reportStopReason("sess-1", "refusal")).resolves.toBeUndefined();
+        });
+    });
     describe("file operations", () => {
         it("should read text files", async () => {
             vi.mocked(path.resolve).mockReturnValue("/mock/path/file.txt");
@@ -900,5 +1089,345 @@ describe("AgentRQACPClient", () => {
             })).rejects.toThrow("write failed");
         });
     });
+    describe("streaming telemetry", () => {
+        /** Every telemetry notification the bridge was asked to send, in order. */
+        function telemetrySent() {
+            return mcpBridge.sendNotification.mock.calls
+                .filter((c) => c[0] === "notifications/claude/channel/telemetry")
+                .map((c) => c[1]);
+        }
+        function newClient(taskId = "task-123") {
+            mcpBridge.callTool = vi
+                .fn()
+                .mockResolvedValue({ isError: false, content: [] });
+            vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+            return new AgentRQACPClient(mcpBridge, () => taskId);
+        }
+        function thought(text) {
+            return {
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "agent_thought_chunk",
+                    content: { type: "text", text },
+                },
+            };
+        }
+        it("batches thought chunks into one block per boundary", async () => {
+            const c = newClient();
+            await c.sessionUpdate(thought("Let me "));
+            await c.sessionUpdate(thought("check the config."));
+            // Nothing goes out mid-block: one notification per token is unusable.
+            expect(telemetrySent()).toHaveLength(0);
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "tool_call",
+                    title: "read_file",
+                    status: "pending",
+                    toolCallId: "tc-1",
+                },
+            });
+            await c.flushReply("sess-1");
+            const thoughts = telemetrySent().filter((p) => p.kind === "thought");
+            expect(thoughts).toHaveLength(1);
+            expect(thoughts[0]).toMatchObject({
+                task_id: "task-123",
+                session_id: "sess-1",
+                kind: "thought",
+                text: "Let me check the config.",
+            });
+        });
+        it("closes off a reasoning block when the agent starts answering", async () => {
+            const c = newClient();
+            await c.sessionUpdate(thought("Thinking first."));
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "agent_message_chunk",
+                    content: { type: "text", text: "The answer." },
+                },
+            });
+            await c.sessionUpdate(thought("Second thought."));
+            await c.flushReply("sess-1");
+            expect(telemetrySent()
+                .filter((p) => p.kind === "thought")
+                .map((p) => p.text)).toEqual(["Thinking first.", "Second thought."]);
+        });
+        it("keeps reasoning out of the reply the human sees", async () => {
+            const c = newClient();
+            await c.sessionUpdate(thought("Internal reasoning."));
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "agent_message_chunk",
+                    content: { type: "text", text: "Done." },
+                },
+            });
+            await c.flushReply("sess-1");
+            expect(mcpBridge.callTool).toHaveBeenCalledWith("reply", {
+                chatId: "task-123",
+                text: "Done.",
+            });
+        });
+        it("ignores non-text thought chunks", async () => {
+            const c = newClient();
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "agent_thought_chunk",
+                    content: { type: "image", data: "…" },
+                },
+            });
+            await c.flushReply("sess-1");
+            expect(telemetrySent()).toHaveLength(0);
+        });
+        it("does not report whitespace-only reasoning", async () => {
+            const c = newClient();
+            await c.sessionUpdate(thought("   \n  "));
+            await c.flushReply("sess-1");
+            expect(telemetrySent()).toHaveLength(0);
+        });
+        it("reports a legacy plan update as soon as it arrives", async () => {
+            const c = newClient();
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "plan",
+                    entries: [
+                        { content: "Read the config", priority: "high", status: "completed" },
+                        { content: "Add tests", priority: "low", status: "pending" },
+                    ],
+                },
+            });
+            // Plans are queued, not awaited on the stream's hot path.
+            await c.flushReply("sess-1");
+            expect(telemetrySent()).toEqual([
+                {
+                    task_id: "task-123",
+                    session_id: "sess-1",
+                    kind: "plan",
+                    text: "- ✅ Read the config\n- ⬜ Add tests",
+                    data: {
+                        planId: "default",
+                        planType: "items",
+                        entries: [
+                            {
+                                content: "Read the config",
+                                priority: "high",
+                                status: "completed",
+                            },
+                            { content: "Add tests", priority: "low", status: "pending" },
+                        ],
+                    },
+                },
+            ]);
+        });
+        it("reports an ID-keyed plan update", async () => {
+            const c = newClient();
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "plan_update",
+                    plan: {
+                        type: "markdown",
+                        planId: "plan-7",
+                        content: "## Steps\n1. Ship it",
+                    },
+                },
+            });
+            await c.flushReply("sess-1");
+            expect(telemetrySent()[0]).toMatchObject({
+                kind: "plan",
+                text: "## Steps\n1. Ship it",
+                data: {
+                    planId: "plan-7",
+                    planType: "markdown",
+                    content: "## Steps\n1. Ship it",
+                },
+            });
+        });
+        it("reports a withdrawn plan so the human sees it was dropped", async () => {
+            const c = newClient();
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "plan_removed", planId: "plan-7" },
+            });
+            await c.flushReply("sess-1");
+            expect(telemetrySent()[0]).toMatchObject({
+                kind: "plan",
+                text: "Plan withdrawn.",
+                data: { planId: "plan-7", removed: true },
+            });
+        });
+        it("puts reasoning in front of the plan it explains", async () => {
+            const c = newClient();
+            await c.sessionUpdate(thought("I should plan this out."));
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "plan", entries: [] },
+            });
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "plan_removed", planId: "default" },
+            });
+            await c.flushReply("sess-1");
+            expect(telemetrySent().map((p) => p.kind)).toEqual([
+                "thought",
+                "plan",
+                "plan",
+            ]);
+        });
+        it("reports only the last usage snapshot, once the turn is over", async () => {
+            const c = newClient();
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "usage_update", used: 100, size: 200_000 },
+            });
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "usage_update",
+                    used: 50_000,
+                    size: 200_000,
+                    cost: { amount: 0.42, currency: "USD" },
+                },
+            });
+            // Each snapshot supersedes the last, so none go out mid-turn.
+            expect(telemetrySent()).toHaveLength(0);
+            await c.flushReply("sess-1");
+            expect(telemetrySent()).toEqual([
+                {
+                    task_id: "task-123",
+                    session_id: "sess-1",
+                    kind: "usage",
+                    text: "Context 50,000 / 200,000 tokens (25%) · 0.42 USD",
+                    data: {
+                        used: 50_000,
+                        size: 200_000,
+                        percent: 25,
+                        cost: { amount: 0.42, currency: "USD" },
+                    },
+                },
+            ]);
+        });
+        it("does not report the same usage snapshot on a later turn", async () => {
+            const c = newClient();
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "usage_update", used: 100, size: 200_000 },
+            });
+            await c.flushReply("sess-1");
+            mcpBridge.sendNotification.mockClear();
+            await c.flushReply("sess-1");
+            expect(telemetrySent()).toHaveLength(0);
+        });
+        it("orders reasoning, the reply, then the usage footer", async () => {
+            const c = newClient();
+            const order = [];
+            mcpBridge.sendNotification = vi.fn(async (_m, p) => {
+                order.push(p.kind);
+            });
+            mcpBridge.callTool = vi.fn(async () => {
+                order.push("reply");
+                return { isError: false, content: [] };
+            });
+            await c.sessionUpdate(thought("Reasoning."));
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "agent_message_chunk",
+                    content: { type: "text", text: "Answer." },
+                },
+            });
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: { sessionUpdate: "usage_update", used: 1, size: 100 },
+            });
+            await c.flushReply("sess-1");
+            expect(order).toEqual(["thought", "reply", "usage"]);
+        });
+        it("drops telemetry when the session has no task to attach it to", async () => {
+            const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const c = new AgentRQACPClient(mcpBridge, () => undefined);
+            await c.sessionUpdate(thought("Nowhere to put this."));
+            await c.flushReply("sess-1");
+            expect(telemetrySent()).toHaveLength(0);
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("dropping thought telemetry"));
+            consoleSpy.mockRestore();
+        });
+        it("still delivers the reply when telemetry cannot be sent", async () => {
+            const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const c = newClient();
+            mcpBridge.sendNotification.mockRejectedValue(new Error("offline"));
+            await c.sessionUpdate(thought("Reasoning."));
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "agent_message_chunk",
+                    content: { type: "text", text: "Answer." },
+                },
+            });
+            await c.flushReply("sess-1");
+            expect(mcpBridge.callTool).toHaveBeenCalledWith("reply", {
+                chatId: "task-123",
+                text: "Answer.",
+            });
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Failed to send thought telemetry"), expect.anything());
+            consoleSpy.mockRestore();
+        });
+        it("keeps sending telemetry after one send has failed", async () => {
+            const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const c = newClient();
+            mcpBridge.sendNotification
+                .mockRejectedValueOnce(new Error("offline"))
+                .mockResolvedValue(undefined);
+            await c.sessionUpdate(thought("First block."));
+            await c.sessionUpdate({
+                sessionId: "sess-1",
+                update: {
+                    sessionUpdate: "tool_call",
+                    title: "read_file",
+                    status: "pending",
+                    toolCallId: "tc-1",
+                },
+            });
+            await c.sessionUpdate(thought("Second block."));
+            await c.flushReply("sess-1");
+            expect(telemetrySent().map((p) => p.text)).toEqual([
+                "First block.",
+                "Second block.",
+            ]);
+            consoleSpy.mockRestore();
+        });
+        it("survives a queued send that throws outright", async () => {
+            const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            // Looking up the task is the gateway's own callback, and it is the one
+            // step outside sendTelemetry's own error handling.
+            const c = new AgentRQACPClient(mcpBridge, () => {
+                throw new Error("task lookup blew up");
+            });
+            await c.sessionUpdate(thought("Reasoning."));
+            await expect(c.flushReply("sess-1")).resolves.toBeUndefined();
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining("Telemetry send failed"), expect.anything());
+            consoleSpy.mockRestore();
+        });
+        it("keeps each session's telemetry to itself", async () => {
+            const c = new AgentRQACPClient(mcpBridge, (sessionId) => `task-${sessionId}`);
+            await c.sessionUpdate(thought("Session one."));
+            await c.sessionUpdate({
+                sessionId: "sess-2",
+                update: {
+                    sessionUpdate: "agent_thought_chunk",
+                    content: { type: "text", text: "Session two." },
+                },
+            });
+            await c.flushReply("sess-2");
+            expect(telemetrySent()).toHaveLength(1);
+            expect(telemetrySent()[0]).toMatchObject({
+                task_id: "task-sess-2",
+                text: "Session two.",
+            });
+        });
+    });
 });
 //# sourceMappingURL=acpClient.test.js.map