@agentrq/acp-gateway 0.2.3 → 0.2.5

package/README.md

@@ -42,7 +42,7 @@ npm install -g @agentrq/acp-gateway
 
 ## Current Version
 
-`0.2.3`
+`0.2.5`
 
 ## Usage
 
@@ -66,12 +66,99 @@ acp-gateway -- your-acp-agent --flag1 --flag2
 You can specify gateway options before the `--` separator:
 
 - `--max-concurrency` / `--maxConcurrency` `<number>`: Sets the maximum number of concurrent tasks allowed to prompt the ACP agent at once. Defaults to `2`.
+- `--agent <registry-id>`: Runs an agent from the ACP registry instead of a command you supply yourself.
+- `--list-agents`: Prints every agent in the registry and how each one can run on this machine, then exits.
+- `--allow-unverified-agent`: Installs a registry binary that publishes no checksum. Off by default.
+- `--registry-url <url>`: Reads a different registry index (for pinning, or for testing).
+- `--auth-method <id>`: The authentication method to use when the agent asks for a login. Defaults to picking one automatically.
+- `--help` / `-h`: Explains every option, with examples. Also shown when `acp-gateway` is run with nothing to do.
+- `--list-auth-methods`: Prints the login methods the agent advertises, then exits.
+- `--login [method-id]`: Logs in to the agent, then exits.
+- `--logout`: Ends the agent's authenticated state, then exits (only for agents that support logout).
 
 Example:
 ```bash
 acp-gateway --max-concurrency 4 -- gemini --acp
 ```
 
+### Running an Agent from the Registry
+
+The [ACP registry](https://github.com/agentclientprotocol/registry) lists agents that implement the
+protocol, and `acp-gateway` can run one by name — no installing or wiring up by hand:
+
+```bash
+acp-gateway --list-agents          # see what's published
+acp-gateway --agent gemini         # run one
+```
+
+Registry entries are distributed in three ways, and the gateway prefers them in this order:
+
+| Distribution | How it runs | Downloads anything? |
+|---|---|---|
+| `npx` | `npx -y <package> <args>` | No — npm fetches and verifies the package |
+| `uvx` | `uvx <package> <args>` | No — uv fetches and verifies the package |
+| `binary` | Archive is downloaded, checked, unpacked and cached | Yes |
+
+Package distributions come first because npm and PyPI verify what they serve. A binary is only used
+when it is the agent's only distribution.
+
+**Binaries are verified before they run.** The registry's `sha256` for the archive is optional, and
+roughly half of the published binary targets omit it. Where there is no checksum the gateway refuses
+to install rather than run something it cannot vouch for:
+
+```
+The ACP registry publishes no sha256 for "antigravity-acp" on this platform, so the download
+cannot be verified. Re-run with --allow-unverified-agent to install it anyway, or install the
+agent yourself and pass it after --.
+```
+
+Downloads are cached per agent, version and platform, so each build is fetched once:
+
+| Platform | Cache location |
+|---|---|
+| macOS / Linux | `$XDG_CACHE_HOME/acp-gateway/agents`, else `~/.cache/acp-gateway/agents` |
+| Windows | `%LOCALAPPDATA%\acp-gateway\agents` |
+
+All six platforms the registry publishes for are supported — macOS, Linux and Windows on both x86_64
+and arm64. Archives are unpacked with the system's own `tar` (and `unzip` for zips on Linux, whose
+`tar` cannot read them), so no archive libraries are added as dependencies.
+
+### Authentication
+
+Agents that require a login advertise their login methods during the ACP handshake, and refuse to open a
+session until one has been used. `acp-gateway` handles that the same way an editor such as Zed does.
+
+List what an agent offers:
+
+```bash
+acp-gateway --list-auth-methods -- gemini --acp
+```
+
+Log in ahead of time — with no method id, you are asked to pick one:
+
+```bash
+acp-gateway --login -- gemini --acp
+acp-gateway --login oauth-personal -- gemini --acp   # or name the method directly
+```
+
+Log out again:
+
+```bash
+acp-gateway --logout -- gemini --acp
+```
+
+Nothing has to be done up front, though: if an agent refuses the first session because it needs a login,
+`acp-gateway` logs in and retries by itself.
+
+There are two kinds of method:
+
+- **Agent** methods — the agent runs the login itself (a browser flow, an API key it already holds). These
+  need nobody present, so they are chosen first and work in an unattended gateway.
+- **Terminal** methods — the agent's own binary is re-run interactively so you can log in at a TUI.
+  `acp-gateway` only offers to run these when it has a real terminal to hand over.
+
+Credentials are never stored by the gateway; the agent keeps its own, exactly as it does under an editor.
+
 ### Configuration
 
 `acp-gateway` searches for `.mcp.json` starting in the current working directory and up to 3 parent directories.
@@ -134,6 +221,9 @@ Example `.mcp.json`:
 | `src/acpClient.ts` | Implements the ACP `Client` interface — routes permission requests, handles session updates, and provides file operations. |
 | `src/mcpClient.ts` | `EventEmitter`-based MCP client with auto-reconnection, notification handling, and tool call dispatch. |
 | `src/config.ts` | Parses `.mcp.json` from the current directory tree up to 3 levels deep. |
+| `src/auth.ts` | ACP authentication — lists the agent's login methods, detects `auth_required`, and runs agent or terminal logins. |
+| `src/registry.ts` | Reads the ACP registry index — agent lookup, host platform matching, and package launch commands. |
+| `src/agentInstall.ts` | Downloads, verifies, unpacks and caches a registry agent's binary distribution. |
 
 ## Development
 
@@ -156,9 +246,12 @@ npm test
 acp-gateway/
 ├── src/
 │   ├── acpClient.ts      # ACP Client implementation
+│   ├── agentInstall.ts    # Registry binary download / verify / cache
+│   ├── auth.ts            # ACP authentication (login / logout)
 │   ├── config.ts          # .mcp.json loader
 │   ├── index.ts           # Entry point & orchestrator
 │   ├── mcpClient.ts       # MCP Bridge with auto-reconnect
+│   ├── registry.ts        # ACP registry index client
 │   └── __tests__/         # Unit tests
 ├── package.json
 └── tsconfig.json
@@ -169,6 +262,8 @@ acp-gateway/
 - **Auto-reconnection**: The MCP transport auto-reconnects on disconnection with exponential backoff (1s → 30s max).
 - **Notification-driven tasks**: The MCP server pushes task content via `notifications/claude/channel`; `acp-gateway` reacts immediately.
 - **Permission flow**: ACP agent requests permission → `acp-gateway` forwards to MCP server → waits for verdict → resolves the ACP permission.
+- **Registry agents**: `--agent <id>` resolves through the registry index; package distributions are preferred over binaries, and a binary without a published `sha256` is refused unless explicitly allowed.
+- **Authentication**: Login methods come from the `initialize` handshake; an `auth_required` refusal triggers a login and one retry of `newSession`.
 - **File I/O**: `readTextFile` / `writeTextFile` are proxied directly to the filesystem; paths are resolved relative to `process.cwd()`.
 
 ## Contributing

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");