qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/infra/acp-protocol-adapter.js

@@ -0,0 +1,382 @@
+/**
+ * ACP Protocol Adapter — a thin wrapper over the official @agentclientprotocol/sdk
+ * `ClientSideConnection`. qlogicagent is the ACP *client* (host); spawned external
+ * agents (codex-acp, claude-agent-acp, openclaw, …) are the ACP *agents*.
+ *
+ * The SDK owns the wire protocol entirely: JSON-RPC 2.0 / NDJSON framing, request↔response
+ * correlation, and the reverse-RPC dispatch. This module owns only the three concerns the SDK
+ * leaves to the host:
+ *   1. bridging a Node ChildProcess's stdio to the SDK's web-stream transport (ndJsonStream)
+ *   2. mapping our loose `AcpHostRequestHandler` onto the typed SDK `Client` interface
+ *   3. translating SDK `session/update` notifications into qlogicagent's internal `turn.*` methods
+ *
+ * Extension capabilities (clientCapabilities.qlogicagent) are forwarded verbatim — the SDK does
+ * not strip outgoing params (validation runs only on the receiving side), so openclaw interop is
+ * preserved.
+ */
+import { Readable, Writable } from "node:stream";
+import { ClientSideConnection, ndJsonStream, } from "@agentclientprotocol/sdk";
+// ── ACP Protocol Constants ──────────────────────────────────
+/** Official ACP protocol version (number, not string). */
+const ACP_PROTOCOL_VERSION = 1;
+// External ACP agents only (the builtin agent uses a separate RPC path). Heavy CLIs like kimi-cli
+// (Python + large deps) can cold-start past 10s, so allow generous margin before declaring the
+// handshake dead — paired with the process-tree reap that prevents the machine from bogging down.
+const HANDSHAKE_TIMEOUT = 20_000;
+const SESSION_SETUP_TIMEOUT = 30_000;
+const DEFAULT_PROMPT_TIMEOUT = 300_000;
+/** Standard session/update types (from @agentclientprotocol/sdk). */
+const SESSION_UPDATE_TYPES = {
+    USER_MESSAGE_CHUNK: "user_message_chunk",
+    AGENT_MESSAGE_CHUNK: "agent_message_chunk",
+    AGENT_THOUGHT_CHUNK: "agent_thought_chunk",
+    TOOL_CALL: "tool_call",
+    TOOL_CALL_UPDATE: "tool_call_update",
+    PLAN: "plan",
+    AVAILABLE_COMMANDS_UPDATE: "available_commands_update",
+    CURRENT_MODE_UPDATE: "current_mode_update",
+    CONFIG_OPTION_UPDATE: "config_option_update",
+    SESSION_INFO_UPDATE: "session_info_update",
+    USAGE_UPDATE: "usage_update",
+};
+/**
+ * Thrown when an agent rejects session setup because the user must authenticate first — e.g. kimi
+ * returns -32000 "Authentication required" with a `kimi login` authMethod. Carries the agent's
+ * advertised authMethods and `retryable = false`, so the spawn layer surfaces it immediately (a
+ * missing login never heals by retrying) with an actionable message instead of a generic failure.
+ */
+export class AcpAuthRequiredError extends Error {
+    retryable = false;
+    authMethods;
+    constructor(message, authMethods) {
+        super(message);
+        this.name = "AcpAuthRequiredError";
+        this.authMethods = authMethods;
+    }
+}
+/**
+ * Recognise the ACP "authentication required" failure (by code -32000, an authMethods payload, or
+ * message text) and convert it to an {@link AcpAuthRequiredError} whose message tells the user how
+ * to log in (from the agent's own authMethod description). Returns null for any other error.
+ */
+export function asAuthRequiredError(err, fallbackAuthMethods) {
+    if (err instanceof AcpAuthRequiredError)
+        return err;
+    const e = err;
+    const authMethods = Array.isArray(e?.data?.authMethods) ? e.data.authMethods : [];
+    const isAuth = e?.code === -32000 || authMethods.length > 0 || /auth(?:entication|orization)?\s+required/i.test(e?.message ?? "");
+    if (isAuth) {
+        const m = authMethods[0];
+        const hint = m?.description || (m?.name ? `Use "${m.name}".` : "");
+        return new AcpAuthRequiredError(`Authentication required.${hint ? ` ${hint}` : ""}`, authMethods);
+    }
+    // Fallback: the agent advertised authMethods at *initialize* and then failed session setup with a
+    // generic error (hermes returns authMethod "hermes-setup", then session/new fails -32603 "Internal
+    // error" / data.details "No LLM provider configured"). It needs auth/config and won't heal by
+    // retrying — surface the agent's actionable detail (or authMethod description) + those authMethods.
+    if (fallbackAuthMethods && fallbackAuthMethods.length > 0) {
+        const m = fallbackAuthMethods[0];
+        const message = e?.data?.details || m?.description || (m?.name ? `Authentication required. Use "${m.name}".` : (e?.message || "Authentication required."));
+        return new AcpAuthRequiredError(message, fallbackAuthMethods);
+    }
+    return null;
+}
+// ── ACP Protocol Adapter ────────────────────────────────────
+export class AcpProtocolAdapter {
+    conn = null;
+    child = null;
+    onNotification = null;
+    hostHandler = null;
+    /**
+     * Attach to a child process's stdio for ACP communication.
+     * Constructs the official ClientSideConnection over the child's stdin/stdout. The connection's
+     * read loop starts immediately, so incoming notifications + reverse-RPC are live after this call.
+     *
+     * @param child The spawned ACP agent process
+     * @param onNotification Callback for agent notifications (raw method + params; caller translates)
+     * @param hostHandler Optional handler for agent→host requests (fs, terminal, permission)
+     */
+    attach(child, onNotification, hostHandler) {
+        this.child = child;
+        this.onNotification = onNotification ?? null;
+        this.hostHandler = hostHandler ?? null;
+        if (!child.stdin || !child.stdout) {
+            throw new Error("ACP adapter: child process has no stdio");
+        }
+        const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        this.conn = new ClientSideConnection(() => this.buildClient(), stream);
+    }
+    /**
+     * Build the SDK Client implementation (agent→host reverse-RPC) from our loose host handler.
+     * Re-reads this.hostHandler / this.onNotification on each call so detach() takes effect.
+     */
+    buildClient() {
+        const handler = () => this.hostHandler;
+        const notify = (method, params) => this.onNotification?.(method, params);
+        return {
+            // Notifications: forward the SDK SessionNotification verbatim under the standard method
+            // name so the caller's translateNotification() sees the same shape as the legacy wire.
+            async sessionUpdate(params) {
+                notify("session/update", params);
+            },
+            // Permission: the host handler returns a flat { optionId }; the ACP spec wants a nested
+            // outcome. Convert here so the agent receives a spec-compliant RequestPermissionResponse.
+            async requestPermission(params) {
+                const h = handler();
+                const decision = h?.requestPermission
+                    ? await h.requestPermission(params)
+                    : { optionId: "allow" };
+                const optionId = decision?.optionId;
+                return optionId
+                    ? { outcome: { outcome: "selected", optionId } }
+                    : { outcome: { outcome: "cancelled" } };
+            },
+            async readTextFile(params) {
+                const r = await handler()?.readTextFile?.(params);
+                return { content: r?.content ?? "" };
+            },
+            async writeTextFile(params) {
+                await handler()?.writeTextFile?.(params);
+                return {};
+            },
+            async createTerminal(params) {
+                const r = await handler()?.createTerminal?.(params);
+                return (r ?? { terminalId: "" });
+            },
+            async terminalOutput(params) {
+                const r = await handler()?.terminalOutput?.(params);
+                return (r ?? { output: "", truncated: false });
+            },
+            async releaseTerminal(params) {
+                await handler()?.releaseTerminal?.(params);
+                return {};
+            },
+            async waitForTerminalExit(params) {
+                const r = await handler()?.waitForTerminalExit?.(params);
+                return (r ?? {});
+            },
+            async killTerminal(params) {
+                await handler()?.killTerminal?.(params);
+                return {};
+            },
+            // Arbitrary agent→host extension methods/notifications.
+            async extMethod(method, params) {
+                const r = await handler()?.extMethod?.(method, params);
+                return (r ?? {});
+            },
+            async extNotification(method, params) {
+                notify(method, params);
+            },
+        };
+    }
+    /** Detach from the child process. The SDK read loop ends when the child's stdout closes. */
+    detach() {
+        this.conn = null;
+        this.hostHandler = null;
+        this.onNotification = null;
+        this.child = null;
+    }
+    requireConn() {
+        if (!this.conn)
+            throw new Error("ACP adapter not attached");
+        return this.conn;
+    }
+    /** Race a connection call against a timeout; optionally run a side effect (e.g. cancel) on timeout. */
+    async withTimeout(p, ms, label, onTimeout) {
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                try {
+                    onTimeout?.();
+                }
+                catch { /* best-effort */ }
+                reject(new Error(`ACP ${label} timeout (${ms}ms)`));
+            }, ms);
+        });
+        try {
+            return await Promise.race([p, timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    // ── ACP Lifecycle Methods ─────────────────────────────────
+    /**
+     * Perform the ACP initialize handshake. Sends standard clientInfo + clientCapabilities plus the
+     * qlogicagent extension capability (forwarded verbatim by the SDK).
+     */
+    async initialize(_child) {
+        const params = {
+            protocolVersion: ACP_PROTOCOL_VERSION,
+            clientCapabilities: {
+                fs: { readTextFile: true, writeTextFile: true },
+                terminal: true,
+                qlogicagent: { version: 1, events: true, methods: true, orchestration: true },
+            },
+            clientInfo: { name: "qlogicagent", version: "1.0.0" },
+        };
+        const result = await this.withTimeout(this.requireConn().initialize(params), HANDSHAKE_TIMEOUT, "initialize").catch((err) => { throw asAuthRequiredError(err) ?? err; });
+        const agentCaps = (result?.agentCapabilities ?? {});
+        return {
+            protocolVersion: typeof result?.protocolVersion === "number" ? result.protocolVersion : 0,
+            agentCapabilities: {
+                loadSession: agentCaps.loadSession === true,
+                mcpCapabilities: agentCaps.mcpCapabilities,
+                promptCapabilities: agentCaps.promptCapabilities,
+                sessionCapabilities: agentCaps.sessionCapabilities,
+                qlogicagent: agentCaps.qlogicagent,
+            },
+            agentInfo: result?.agentInfo,
+            authMethods: result?.authMethods,
+        };
+    }
+    /**
+     * Create an ACP session (session/new). A non-standard systemPrompt is forwarded under `_meta`
+     * (the ACP extension mechanism) so it survives validation on the agent side.
+     */
+    async createSession(_child, options) {
+        const params = {
+            cwd: options.cwd,
+            mcpServers: options.mcpServers ?? [],
+        };
+        if (options.additionalDirectories?.length) {
+            params.additionalDirectories = options.additionalDirectories;
+        }
+        if (options.systemPrompt) {
+            params._meta = { qlogicagent: { systemPrompt: options.systemPrompt } };
+        }
+        const result = await this.withTimeout(this.requireConn().newSession(params), SESSION_SETUP_TIMEOUT, "session/new").catch((err) => { throw asAuthRequiredError(err) ?? err; });
+        if (typeof result?.sessionId !== "string") {
+            throw new Error("ACP session/new: agent did not return sessionId");
+        }
+        return { sessionId: result.sessionId };
+    }
+    /**
+     * Send a prompt to a running ACP session (session/prompt). Content streams back via session/update
+     * notifications during execution; the response carries only { stopReason, usage? }. On timeout the
+     * turn is cancelled (session/cancel) so the agent stops cleanly.
+     */
+    async sendPrompt(_child, sessionId, content, timeoutMs = DEFAULT_PROMPT_TIMEOUT) {
+        const conn = this.requireConn();
+        const result = await this.withTimeout(conn.prompt({ sessionId, prompt: [{ type: "text", text: content }] }), timeoutMs, "session/prompt", () => { void conn.cancel({ sessionId }).catch(() => { }); });
+        return {
+            stopReason: result?.stopReason ?? "end_turn",
+            usage: result?.usage,
+            userMessageId: undefined,
+        };
+    }
+    /**
+     * Resume an existing ACP session (session/load — replays history via notifications).
+     * Only valid when the agent advertised the loadSession capability.
+     */
+    async resumeSession(_child, sessionId, options) {
+        const params = {
+            sessionId,
+            cwd: options?.cwd ?? process.cwd(),
+            mcpServers: options?.mcpServers ?? [],
+        };
+        const result = await this.withTimeout(this.requireConn().loadSession(params), SESSION_SETUP_TIMEOUT, "session/load");
+        // session/load returns an empty object in the SDK; the sessionId is the one we passed.
+        const resolved = typeof result?.sessionId === "string" ? result.sessionId : sessionId;
+        return { sessionId: resolved };
+    }
+    // ── Notification Translation ──────────────────────────────
+    /**
+     * Translate an ACP notification into qlogicagent's internal format.
+     * Returns null if the notification is not translatable (handled separately).
+     *
+     * Standard ACP: agent sends "session/update" with params { sessionId, update: { sessionUpdate, … } }.
+     * Used by both the external-agent path (this adapter) and the internal/builtin agent path, so it
+     * stays a pure static function decoupled from the connection.
+     */
+    static translateNotification(method, params) {
+        const p = params;
+        if (method === "session/update") {
+            if (!p)
+                return null;
+            const update = p.update;
+            if (!update)
+                return null;
+            const updateType = update.sessionUpdate;
+            const sessionId = p.sessionId;
+            switch (updateType) {
+                case SESSION_UPDATE_TYPES.AGENT_MESSAGE_CHUNK: {
+                    const content = update.content;
+                    const text = content?.text ?? content?.content ?? "";
+                    return {
+                        method: "turn.delta",
+                        params: { text, sessionId, messageId: update.messageId },
+                    };
+                }
+                case SESSION_UPDATE_TYPES.AGENT_THOUGHT_CHUNK: {
+                    const content = update.content;
+                    const text = content?.text ?? "";
+                    return {
+                        method: "turn.thought_delta",
+                        params: { text, sessionId },
+                    };
+                }
+                case SESSION_UPDATE_TYPES.TOOL_CALL: {
+                    return {
+                        method: "turn.tool_call",
+                        params: {
+                            callId: update.toolCallId,
+                            toolName: update.title,
+                            status: update.status ?? "running",
+                            content: update.content,
+                            kind: update.kind,
+                            rawInput: update.rawInput,
+                            sessionId,
+                        },
+                    };
+                }
+                case SESSION_UPDATE_TYPES.TOOL_CALL_UPDATE: {
+                    return {
+                        method: "turn.tool_result",
+                        params: {
+                            callId: update.toolCallId,
+                            toolName: update.title,
+                            status: update.status ?? "completed",
+                            content: update.content,
+                            rawOutput: update.rawOutput,
+                            sessionId,
+                        },
+                    };
+                }
+                case SESSION_UPDATE_TYPES.USAGE_UPDATE: {
+                    return {
+                        method: "turn.usage_update",
+                        params: (update ?? {}),
+                    };
+                }
+                case SESSION_UPDATE_TYPES.PLAN: {
+                    return {
+                        method: "turn.plan",
+                        params: { steps: update.steps, sessionId },
+                    };
+                }
+                case SESSION_UPDATE_TYPES.AVAILABLE_COMMANDS_UPDATE:
+                case SESSION_UPDATE_TYPES.CURRENT_MODE_UPDATE:
+                case SESSION_UPDATE_TYPES.CONFIG_OPTION_UPDATE:
+                case SESSION_UPDATE_TYPES.SESSION_INFO_UPDATE: {
+                    return {
+                        method: "turn.session_info",
+                        params: { type: updateType, ...update, sessionId },
+                    };
+                }
+                case SESSION_UPDATE_TYPES.USER_MESSAGE_CHUNK: {
+                    return null;
+                }
+                default: {
+                    return {
+                        method: `turn.${updateType ?? "unknown"}`,
+                        params: { ...update, sessionId },
+                    };
+                }
+            }
+        }
+        // Non-standard notification method — not translatable here.
+        return null;
+    }
+}

package/dist/runtime/infra/acp-protocol-adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/infra/acp-protocol-adapter.test.js

@@ -0,0 +1,180 @@
+import { PassThrough, Readable, Writable } from "node:stream";
+import { AgentSideConnection, ndJsonStream, RequestError } from "@agentclientprotocol/sdk";
+import { afterEach, describe, expect, it } from "vitest";
+import { AcpProtocolAdapter, AcpAuthRequiredError, asAuthRequiredError } from "./acp-protocol-adapter.js";
+// ── In-memory ACP agent harness ──────────────────────────────
+// Wires our (client-side) adapter to a fake (agent-side) SDK connection over two PassThrough pipes,
+// exercising the REAL official-SDK wire path: handshake, session, prompt, session/update
+// notifications, and the session/request_permission reverse-RPC — no child process needed.
+/** Fill the Agent methods a test doesn't care about so each case overrides only what it needs. */
+function fakeAgent(overrides) {
+    return {
+        async initialize() {
+            return { protocolVersion: 1, agentCapabilities: {} };
+        },
+        async newSession() {
+            return { sessionId: "s" };
+        },
+        async prompt() {
+            return { stopReason: "end_turn" };
+        },
+        async authenticate() {
+            return {};
+        },
+        async cancel() {
+            /* no-op */
+        },
+        ...overrides,
+    };
+}
+function makeHarness(buildAgent) {
+    const aToB = new PassThrough(); // adapter → agent (adapter's stdin)
+    const bToA = new PassThrough(); // agent → adapter (adapter's stdout)
+    const child = { stdin: aToB, stdout: bToA };
+    const agentStream = ndJsonStream(Writable.toWeb(bToA), Readable.toWeb(aToB));
+    // eslint-disable-next-line no-new -- the connection drives itself off the stream
+    new AgentSideConnection(buildAgent, agentStream);
+    return { child };
+}
+let adapter = null;
+afterEach(() => {
+    adapter?.detach();
+    adapter = null;
+});
+describe("AcpProtocolAdapter (official @agentclientprotocol/sdk ClientSideConnection)", () => {
+    it("performs the initialize handshake and surfaces agent capabilities", async () => {
+        const { child } = makeHarness(() => fakeAgent({
+            async initialize() {
+                return { protocolVersion: 1, agentCapabilities: { loadSession: true } };
+            },
+        }));
+        adapter = new AcpProtocolAdapter();
+        adapter.attach(child);
+        const init = await adapter.initialize(child);
+        expect(init.protocolVersion).toBe(1);
+        expect(init.agentCapabilities.loadSession).toBe(true);
+    });
+    it("creates a session and returns the agent's sessionId", async () => {
+        const { child } = makeHarness(() => fakeAgent({
+            async newSession(params) {
+                expect(params.cwd).toBe("/work");
+                return { sessionId: "s-42" };
+            },
+        }));
+        adapter = new AcpProtocolAdapter();
+        adapter.attach(child);
+        await adapter.initialize(child);
+        const session = await adapter.createSession(child, { cwd: "/work" });
+        expect(session.sessionId).toBe("s-42");
+    });
+    it("streams session/update notifications, translated to internal turn.* methods", async () => {
+        const { child } = makeHarness((conn) => fakeAgent({
+            async newSession() {
+                return { sessionId: "s-stream" };
+            },
+            async prompt(params) {
+                await conn.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "hello " } },
+                });
+                await conn.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "world" } },
+                });
+                return { stopReason: "end_turn" };
+            },
+        }));
+        const seen = [];
+        adapter = new AcpProtocolAdapter();
+        adapter.attach(child, (method, params) => {
+            const t = AcpProtocolAdapter.translateNotification(method, params);
+            if (t)
+                seen.push({ method: t.method, text: t.params.text });
+        });
+        await adapter.initialize(child);
+        await adapter.createSession(child, { cwd: "/work" });
+        const res = await adapter.sendPrompt(child, "s-stream", "hi");
+        expect(res.stopReason).toBe("end_turn");
+        const deltas = seen.filter((s) => s.method === "turn.delta").map((s) => s.text);
+        expect(deltas).toEqual(["hello ", "world"]);
+    });
+    it("answers session/request_permission via the host handler, converting flat optionId → nested outcome", async () => {
+        let agentReceivedOutcome = null;
+        const { child } = makeHarness((conn) => fakeAgent({
+            async newSession() {
+                return { sessionId: "s-perm" };
+            },
+            async prompt(params) {
+                const resp = await conn.requestPermission({
+                    sessionId: params.sessionId,
+                    toolCall: { toolCallId: "tool-1", title: "rm -rf /tmp/x" },
+                    options: [
+                        { optionId: "allow", name: "Allow", kind: "allow_once" },
+                        { optionId: "reject", name: "Reject", kind: "reject_once" },
+                    ],
+                });
+                agentReceivedOutcome = resp.outcome;
+                return { stopReason: "end_turn" };
+            },
+        }));
+        // Host handler picks "allow" (flat shape — the adapter must nest it for the SDK).
+        const hostHandler = {
+            async requestPermission(params) {
+                expect(params.toolCall?.toolCallId).toBe("tool-1");
+                return { optionId: "allow" };
+            },
+        };
+        adapter = new AcpProtocolAdapter();
+        adapter.attach(child, undefined, hostHandler);
+        await adapter.initialize(child);
+        await adapter.createSession(child, { cwd: "/work" });
+        await adapter.sendPrompt(child, "s-perm", "delete it");
+        // The agent must receive the spec-compliant nested outcome, not the host handler's flat shape.
+        expect(agentReceivedOutcome).toEqual({ outcome: "selected", optionId: "allow" });
+    });
+    it("converts an agent's auth-required session/new rejection into an actionable AcpAuthRequiredError", async () => {
+        const { child } = makeHarness(() => fakeAgent({
+            async newSession() {
+                // What kimi returns: -32000 + a `kimi login` authMethod.
+                throw new RequestError(-32000, "Authentication required", {
+                    authMethods: [{ id: "login", name: "Login with Kimi account", description: "Run `kimi login` in the terminal." }],
+                });
+            },
+        }));
+        adapter = new AcpProtocolAdapter();
+        adapter.attach(child);
+        await adapter.initialize(child);
+        const err = await adapter.createSession(child, { cwd: "/work" }).catch((e) => e);
+        expect(err, "createSession should reject").toBeInstanceOf(AcpAuthRequiredError);
+        expect(err.retryable).toBe(false); // spawn layer must not retry
+        expect(err.message).toContain("kimi login"); // actionable hint surfaced to the user
+        expect(err.authMethods[0]?.id).toBe("login");
+    });
+});
+describe("asAuthRequiredError (recognises both auth-gating patterns)", () => {
+    it("converts a direct auth rejection (-32000 + authMethods) into an actionable error", () => {
+        const err = new RequestError(-32000, "Authentication required", {
+            authMethods: [{ id: "login", name: "Login", description: "Run `kimi login`." }],
+        });
+        const out = asAuthRequiredError(err);
+        expect(out).toBeInstanceOf(AcpAuthRequiredError);
+        expect(out.retryable).toBe(false);
+        expect(out.message).toContain("kimi login");
+        expect(out.authMethods[0]?.id).toBe("login");
+    });
+    it("promotes a generic session/new failure to auth-required when initialize advertised authMethods (hermes pattern)", () => {
+        // hermes returns authMethods at initialize, then fails session/new with -32603 + a provider detail.
+        const err = new RequestError(-32603, "Internal error", { details: "No LLM provider configured. Run `hermes model`." });
+        const initAuthMethods = [{ id: "hermes-setup", name: "Configure Hermes provider", description: "Run hermes acp --setup." }];
+        const out = asAuthRequiredError(err, initAuthMethods);
+        expect(out).toBeInstanceOf(AcpAuthRequiredError);
+        expect(out.retryable).toBe(false); // spawn layer must not burn retries on a config gate
+        expect(out.message).toContain("No LLM provider configured"); // the agent's actionable detail surfaces
+        expect(out.authMethods[0]?.id).toBe("hermes-setup"); // initialize authMethods drive the login card
+    });
+    it("returns null for a generic failure with no auth signal and no fallback (stays retryable)", () => {
+        expect(asAuthRequiredError(new RequestError(-32603, "Internal error", {}))).toBeNull();
+        // A generic failure with an EMPTY fallback list is not auth — must not false-positive.
+        expect(asAuthRequiredError(new Error("boom"), [])).toBeNull();
+    });
+});

package/dist/runtime/infra/acp-usage-tracker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ACP Usage Tracker — 3-tier token usage tracking for external ACP agents.
+ *
+ * Tier 1: Real-time `usage_update` notifications (preferred).
+ * Tier 2: Per-turn `PromptResponse.usage` fallback.
+ * Tier 3: Graceful degradation — no usage data, no budget enforcement.
+ *
+ * The tracker prevents double-counting when an agent sends both
+ * usage_update notifications AND prompt response usage.
+ */
+import type { AcpUsageUpdatePayload, AcpPromptResponseUsage } from "../../protocol/wire/acp-agent-management.js";
+export interface AccumulatedUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedReadTokens: number;
+    thoughtTokens: number;
+    /** Total cost (USD), if reported. */
+    cost: number;
+    /** Whether at least one usage_update was received (Tier 1 active). */
+    hasTier1: boolean;
+    /** Number of turns processed (Tier 2 fallback). */
+    turnCount: number;
+}
+export declare class AcpUsageTracker {
+    private usage;
+    /**
+     * Tier 1: Handle a `usage_update` notification from ACP agent.
+     * Sets the hasTier1 flag to prevent double-counting from Tier 2.
+     */
+    onUsageUpdate(payload: AcpUsageUpdatePayload): void;
+    /**
+     * Tier 2: Handle per-turn usage from PromptResponse.
+     * Only applied if Tier 1 is NOT active (prevents double-counting).
+     */
+    onPromptResponseUsage(usage: AcpPromptResponseUsage | undefined): void;
+    /** Get the current accumulated usage snapshot. */
+    getUsage(): Readonly<AccumulatedUsage>;
+    /** Reset all counters. */
+    reset(): void;
+    /**
+     * Check whether we have any usage data.
+     * Returns false in Tier 3 (graceful degradation).
+     */
+    hasData(): boolean;
+}