@agentrq/acp-gateway 0.2.5 → 0.2.6

package/README.md

@@ -42,7 +42,7 @@ npm install -g @agentrq/acp-gateway
 
 ## Current Version
 
-`0.2.5`
+`0.2.6`
 
 ## Usage
 
@@ -252,6 +252,7 @@ acp-gateway/
 │   ├── index.ts           # Entry point & orchestrator
 │   ├── mcpClient.ts       # MCP Bridge with auto-reconnect
 │   ├── registry.ts        # ACP registry index client
+│   ├── telemetry.ts       # Thought / plan / usage rendering
 │   └── __tests__/         # Unit tests
 ├── package.json
 └── tsconfig.json
@@ -262,6 +263,7 @@ 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.
+- **Streaming telemetry**: Reasoning, execution plans and token/cost counters are forwarded on `notifications/claude/channel/telemetry`. Reasoning is batched into one block per boundary (the agent starts answering, calls a tool, or revises its plan) rather than one message per token; plans go out as they change; only the last usage snapshot of a turn is reported. Sends are queued off the ACP stream, so a workspace that is slow or unreachable never stalls the agent.
 - **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()`.

package/dist/__tests__/acpClient.test.js

@@ -918,6 +918,81 @@ describe("AgentRQACPClient", () => {
             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");
@@ -1014,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