@agentrq/acp-gateway 0.2.4 → 0.2.5

package/README.md

@@ -42,7 +42,7 @@ npm install -g @agentrq/acp-gateway
 
 ## Current Version
 
-`0.2.4`
+`0.2.5`
 
 ## Usage
 

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,189 @@ 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 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");