qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/infra/acp-detector.test.d.ts

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

package/dist/runtime/infra/acp-detector.test.js

@@ -0,0 +1,164 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { platform, tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ACP_BACKENDS, AcpDetector, buildBackendEnv, normalizeWindowsAcpCommand, resolveWindowsCopilotLoader, } from "./acp-detector.js";
+const isWindows = platform() === "win32";
+// The real npm global .bin shim for codex-acp on this machine. B2 must resolve it
+// to a direct `node <entry>.js` invocation (no powershell -File wrapper that swallows
+// piped stdin). Skip cleanly if codex-acp is not installed in this environment.
+const CODEX_SHIM_BASE = "C:/Users/sunsion/AppData/Roaming/npm/codex-acp";
+const codexShimAvailable = isWindows && (existsSync(`${CODEX_SHIM_BASE}.cmd`) || existsSync(`${CODEX_SHIM_BASE}.ps1`));
+describe("resolveWindowsCopilotLoader verifies cache loader (B1)", () => {
+    let tmp;
+    const savedCache = process.env.COPILOT_CACHE_HOME;
+    const savedLocal = process.env.LOCALAPPDATA;
+    const savedHome = process.env.COPILOT_HOME;
+    beforeEach(() => {
+        tmp = mkdtempSync(join(tmpdir(), "copilot-cache-"));
+        // Point every cache root at empty/controlled dirs so only our broken loader exists.
+        process.env.COPILOT_CACHE_HOME = tmp;
+        process.env.LOCALAPPDATA = join(tmp, "noLocal");
+        process.env.COPILOT_HOME = join(tmp, "noHome");
+    });
+    afterEach(() => {
+        if (savedCache === undefined)
+            delete process.env.COPILOT_CACHE_HOME;
+        else
+            process.env.COPILOT_CACHE_HOME = savedCache;
+        if (savedLocal === undefined)
+            delete process.env.LOCALAPPDATA;
+        else
+            process.env.LOCALAPPDATA = savedLocal;
+        if (savedHome === undefined)
+            delete process.env.COPILOT_HOME;
+        else
+            process.env.COPILOT_HOME = savedHome;
+        rmSync(tmp, { recursive: true, force: true });
+    });
+    it.runIf(isWindows)("does NOT return a loader that fails probeVersion", () => {
+        // A broken loader (missing its node_modules deps) that throws when run -> probeVersion null.
+        const verDir = join(tmp, "pkg", "win32-x64", "1.0.0");
+        mkdirSync(verDir, { recursive: true });
+        const brokenLoader = join(verDir, "npm-loader.js");
+        writeFileSync(brokenLoader, "require('definitely-not-installed-pkg-xyz');\n");
+        const resolved = resolveWindowsCopilotLoader();
+        // The broken loader must never be returned; either null (fall back to global whichSync)
+        // or some OTHER genuinely-working loader on this machine, but not the broken temp one.
+        expect(resolved).not.toBe(brokenLoader);
+    });
+});
+describe("normalizeWindowsAcpCommand npm-shim direct node entry (B2)", () => {
+    it.runIf(codexShimAvailable)("resolves a .bin shim to a direct node entry (no powershell)", () => {
+        const r = normalizeWindowsAcpCommand(CODEX_SHIM_BASE, ["--foo"]);
+        expect(r.cliPath).toBe(process.execPath);
+        expect(r.acpArgs[0].endsWith(".js")).toBe(true);
+        expect(existsSync(r.acpArgs[0])).toBe(true);
+        expect(r.acpArgs).toContain("--foo");
+        expect(r.cliPath).not.toMatch(/powershell/i);
+        // The resolved entry is the codex-acp bin js the shim launches.
+        expect(r.acpArgs[0].replace(/\\/g, "/")).toContain("node_modules/@zed-industries/codex-acp/bin/codex-acp.js");
+    });
+    it.runIf(codexShimAvailable)("resolves the .cmd-suffixed shim path too", () => {
+        const r = normalizeWindowsAcpCommand(`${CODEX_SHIM_BASE}.cmd`, []);
+        expect(r.cliPath).toBe(process.execPath);
+        expect(r.acpArgs[0].endsWith(".js")).toBe(true);
+        expect(r.cliPath).not.toMatch(/powershell/i);
+    });
+});
+// ── B3: env injection — agent-config apiKey/baseUrl → backend-declared env vars ──────────────
+// This is the core gap fix: backends declared apiKeyEnvVar/baseUrlEnvVar but nothing populated
+// them, so a user who configured only { apiKey, baseUrl } never actually drove the CLI with a
+// third-party OpenAI/Anthropic gateway. buildBackendEnv maps the portable config onto the
+// declared env-var names so codex/claude run off a third-party key with no official login.
+describe("buildBackendEnv maps agent-config apiKey/baseUrl onto backend env vars (B3)", () => {
+    it("codex: apiKey/baseUrl → OPENAI_API_KEY/OPENAI_BASE_URL", () => {
+        const env = buildBackendEnv(ACP_BACKENDS.codex, {
+            apiKey: "sk-third-party-xyz",
+            baseUrl: "https://api.deepseek.com",
+        });
+        expect(env).toBeDefined();
+        expect(env?.OPENAI_API_KEY).toBe("sk-third-party-xyz");
+        expect(env?.OPENAI_BASE_URL).toBe("https://api.deepseek.com");
+        // Must NOT leak into the wrong (Anthropic) vars.
+        expect(env?.ANTHROPIC_API_KEY).toBeUndefined();
+    });
+    it("claude: apiKey/baseUrl → ANTHROPIC_API_KEY/ANTHROPIC_BASE_URL", () => {
+        const env = buildBackendEnv(ACP_BACKENDS.claude, {
+            apiKey: "sk-anthropic-compat",
+            baseUrl: "https://api.deepseek.com/anthropic",
+        });
+        expect(env).toBeDefined();
+        expect(env?.ANTHROPIC_API_KEY).toBe("sk-anthropic-compat");
+        expect(env?.ANTHROPIC_BASE_URL).toBe("https://api.deepseek.com/anthropic");
+        expect(env?.OPENAI_API_KEY).toBeUndefined();
+    });
+    it("only injects the vars the backend actually declares", () => {
+        // qwen declares apiKeyEnvVar (DASHSCOPE_API_KEY) but NO baseUrlEnvVar.
+        const env = buildBackendEnv(ACP_BACKENDS.qwen, {
+            apiKey: "qwen-key",
+            baseUrl: "https://example.invalid",
+        });
+        expect(env?.DASHSCOPE_API_KEY).toBe("qwen-key");
+        // No baseUrlEnvVar declared → baseUrl must not be injected under any var.
+        expect(Object.values(env ?? {})).not.toContain("https://example.invalid");
+    });
+    it("returns undefined when nothing is configured (preserves prior behavior)", () => {
+        expect(buildBackendEnv(ACP_BACKENDS.codex, undefined)).toBeUndefined();
+        expect(buildBackendEnv(ACP_BACKENDS.codex, {})).toBeUndefined();
+    });
+    it("explicit customConfig.env wins over the mapped apiKey/baseUrl (highest precedence)", () => {
+        const env = buildBackendEnv(ACP_BACKENDS.codex, {
+            apiKey: "from-apiKey-field",
+            baseUrl: "https://from-baseUrl-field",
+            env: { OPENAI_API_KEY: "hand-entered-wins", EXTRA: "1" },
+        });
+        expect(env?.OPENAI_API_KEY).toBe("hand-entered-wins"); // raw env overrides mapping
+        expect(env?.OPENAI_BASE_URL).toBe("https://from-baseUrl-field"); // mapping still applies where not overridden
+        expect(env?.EXTRA).toBe("1");
+    });
+    it("merges backend.env defaults beneath the mapped config (lowest precedence)", () => {
+        const backend = { ...ACP_BACKENDS.codex, env: { OPENAI_BASE_URL: "default-base", BACKEND_ONLY: "y" } };
+        const env = buildBackendEnv(backend, { apiKey: "k", baseUrl: "https://override-base" });
+        expect(env?.OPENAI_BASE_URL).toBe("https://override-base"); // mapped config overrides backend default
+        expect(env?.OPENAI_API_KEY).toBe("k");
+        expect(env?.BACKEND_ONLY).toBe("y"); // backend-only default survives
+    });
+});
+// Integration: the env actually reaches the ExternalAgentDescriptor that AgentProcessManager
+// spawns. Uses a real available agent (codex) if installed on this machine.
+describe("buildExternalDescriptor injects configured creds into descriptor.env (B3-integration)", () => {
+    // 20s timeout: scan(true) runs real where/probeVersion IO (spawns the codex CLI to read
+    // its version), which can exceed vitest's 5s default on a cold cache.
+    it.runIf(codexShimAvailable)("codex descriptor.env carries OPENAI_* from agent-config", () => {
+        const detector = new AcpDetector();
+        const store = {
+            agents: {
+                codex: { apiKey: "sk-integ-key", baseUrl: "https://api.deepseek.com" },
+            },
+        };
+        detector.setConfigStore(store);
+        detector.scan(true); // real scan; codex must resolve as available on this machine
+        const desc = detector.buildExternalDescriptor("codex");
+        expect(desc).not.toBeNull();
+        expect(desc?.env?.OPENAI_API_KEY).toBe("sk-integ-key");
+        expect(desc?.env?.OPENAI_BASE_URL).toBe("https://api.deepseek.com");
+    }, 20_000);
+    it.runIf(codexShimAvailable)("codex llmrouter descriptor carries provider args for login-free use", () => {
+        const detector = new AcpDetector();
+        detector.setConfigStore({ agents: {} });
+        detector.setKeySources({
+            llmrouterKey: "sk-qllm-auto",
+            llmrouterModel: "deepseek-v4-flash",
+            getLlmrouterBaseUrl: () => "https://www.qlogicagent.com/v1",
+        });
+        detector.scan(true);
+        const desc = detector.buildExternalDescriptor("codex");
+        expect(desc?.env?.OPENAI_API_KEY).toBe("sk-qllm-auto");
+        expect(desc?.env?.OPENAI_BASE_URL).toBe("https://www.qlogicagent.com/v1");
+        expect(desc?.env?.OPENAI_MODEL).toBe("deepseek-v4-flash");
+        expect(desc?.acpArgs.join(" ")).toContain("model_providers.llmrouter.wire_api=responses");
+        expect(desc?.acpArgs.join(" ")).toContain("model_provider=llmrouter");
+        expect(desc?.acpArgs.join(" ")).toContain("model=deepseek-v4-flash");
+    }, 20_000);
+});

package/dist/runtime/infra/acp-host-handler.d.ts

@@ -0,0 +1,31 @@
+import type { AcpHostRequestHandler } from "./acp-protocol-adapter.js";
+interface HostHandlerOpts {
+    cwd: string;
+    /**
+     * Optional interactive permission resolver. When provided, session/request_permission is routed
+     * here (forwarded to the user) instead of auto-allowing. Returning a chosen optionId responds to
+     * the external agent. If omitted, permissions auto-allow (host-trust baseline for sub-agents).
+     */
+    requestPermission?: (params: Record<string, unknown>) => Promise<{
+        optionId: string;
+    }>;
+}
+/**
+ * Host-side reverse-RPC handler for an EXTERNAL ACP agent (codex/copilot/…).
+ *
+ * Auto-allows permissions (the external agent runs under the qlogicagent host's
+ * trust, matching the internal sub-agent baseline), serves fs read/write confined
+ * to the agent cwd, and runs terminals as real child processes. Terminals are
+ * tracked in a Map so the agent process lifecycle (detach/kill) can reap them via
+ * disposeAll().
+ *
+ * Terminal response shapes align with the official ACP schema
+ * (@agentclientprotocol/sdk):
+ *   - createTerminal       -> { terminalId }
+ *   - terminalOutput       -> { output, truncated, exitStatus: {exitCode, signal} | null }
+ *   - waitForTerminalExit  -> { exitCode, signal }
+ */
+export declare function createAcpHostHandler(opts: HostHandlerOpts): AcpHostRequestHandler & {
+    disposeAll(): void;
+};
+export {};

package/dist/runtime/infra/acp-host-handler.js

@@ -0,0 +1,123 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, normalize, relative, resolve, sep } from "node:path";
+/**
+ * Host-side reverse-RPC handler for an EXTERNAL ACP agent (codex/copilot/…).
+ *
+ * Auto-allows permissions (the external agent runs under the qlogicagent host's
+ * trust, matching the internal sub-agent baseline), serves fs read/write confined
+ * to the agent cwd, and runs terminals as real child processes. Terminals are
+ * tracked in a Map so the agent process lifecycle (detach/kill) can reap them via
+ * disposeAll().
+ *
+ * Terminal response shapes align with the official ACP schema
+ * (@agentclientprotocol/sdk):
+ *   - createTerminal       -> { terminalId }
+ *   - terminalOutput       -> { output, truncated, exitStatus: {exitCode, signal} | null }
+ *   - waitForTerminalExit  -> { exitCode, signal }
+ */
+export function createAcpHostHandler(opts) {
+    const terminals = new Map();
+    let seq = 0;
+    /** Resolve a path and confine it to the agent cwd (reject traversal escapes). */
+    const safe = (p) => {
+        const abs = isAbsolute(p) ? normalize(p) : resolve(opts.cwd, p);
+        const rel = relative(opts.cwd, abs);
+        if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+            throw new Error(`path escapes cwd: ${p}`);
+        }
+        return abs;
+    };
+    const getTerminalId = (params) => String(params.terminalId ?? "");
+    return {
+        async requestPermission(params) {
+            if (opts.requestPermission) {
+                return opts.requestPermission(params);
+            }
+            return { optionId: "allow" };
+        },
+        async readTextFile(params) {
+            const content = await readFile(safe(params.path), "utf8");
+            return { content };
+        },
+        async writeTextFile(params) {
+            await writeFile(safe(params.path), params.content, "utf8");
+            return {};
+        },
+        async createTerminal(params) {
+            const command = String(params.command ?? "");
+            const rawArgs = params.args;
+            const args = Array.isArray(rawArgs) ? rawArgs.map(String) : [];
+            const rawCwd = params.cwd;
+            const cwd = rawCwd ? safe(String(rawCwd)) : opts.cwd;
+            const extraEnv = params.env;
+            const env = { ...process.env, ...(extraEnv && typeof extraEnv === "object" ? extraEnv : {}) };
+            const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+            const id = `term-${++seq}`;
+            const term = {
+                child,
+                output: "",
+                exitStatus: null,
+                exit: new Promise((res) => {
+                    child.on("exit", (code, signal) => {
+                        const status = { exitCode: code, signal };
+                        term.exitStatus = status;
+                        res(status);
+                    });
+                    child.on("error", () => {
+                        const status = { exitCode: null, signal: null };
+                        term.exitStatus = status;
+                        res(status);
+                    });
+                }),
+            };
+            child.stdout?.on("data", (d) => { term.output += d.toString(); });
+            child.stderr?.on("data", (d) => { term.output += d.toString(); });
+            terminals.set(id, term);
+            return { terminalId: id };
+        },
+        async terminalOutput(params) {
+            const t = terminals.get(getTerminalId(params));
+            if (!t)
+                return { output: "", truncated: false, exitStatus: null };
+            return { output: t.output, truncated: false, exitStatus: t.exitStatus };
+        },
+        async waitForTerminalExit(params) {
+            const t = terminals.get(getTerminalId(params));
+            if (!t)
+                return { exitCode: null, signal: null };
+            return t.exit;
+        },
+        async releaseTerminal(params) {
+            const id = getTerminalId(params);
+            const t = terminals.get(id);
+            if (t && t.child.exitCode === null && t.child.signalCode === null) {
+                try {
+                    t.child.kill();
+                }
+                catch { /* already gone */ }
+            }
+            terminals.delete(id);
+            return {};
+        },
+        async killTerminal(params) {
+            const t = terminals.get(getTerminalId(params));
+            if (t) {
+                try {
+                    t.child.kill("SIGKILL");
+                }
+                catch { /* already gone */ }
+            }
+            return {};
+        },
+        disposeAll() {
+            for (const t of terminals.values()) {
+                try {
+                    t.child.kill("SIGKILL");
+                }
+                catch { /* already gone */ }
+            }
+            terminals.clear();
+        },
+    };
+}

package/dist/runtime/infra/acp-host-handler.test.d.ts

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

package/dist/runtime/infra/acp-host-handler.test.js

@@ -0,0 +1,64 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { createAcpHostHandler } from "./acp-host-handler.js";
+describe("AcpHostHandler", () => {
+    it("requestPermission auto-allows", async () => {
+        const h = createAcpHostHandler({ cwd: process.cwd() });
+        expect(await h.requestPermission({})).toEqual({ optionId: "allow" });
+    });
+    it("readTextFile reads within cwd, rejects escape", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "acphh-"));
+        writeFileSync(join(dir, "a.txt"), "hello");
+        const h = createAcpHostHandler({ cwd: dir });
+        expect((await h.readTextFile({ path: "a.txt" })).content).toBe("hello");
+        await expect(h.readTextFile({ path: "../../etc/hosts" })).rejects.toThrow();
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("writeTextFile writes within cwd, rejects escape", async () => {
+        const dir = mkdtempSync(join(tmpdir(), "acphh-"));
+        const h = createAcpHostHandler({ cwd: dir });
+        await h.writeTextFile({ path: "out.txt", content: "data 42" });
+        expect((await h.readTextFile({ path: "out.txt" })).content).toBe("data 42");
+        await expect(h.writeTextFile({ path: "../escape.txt", content: "x" })).rejects.toThrow();
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("terminal create/output/wait/release lifecycle", async () => {
+        const h = createAcpHostHandler({ cwd: process.cwd() });
+        const created = (await h.createTerminal({
+            command: process.execPath,
+            args: ["-e", "console.log('PONG')"],
+        }));
+        expect(typeof created.terminalId).toBe("string");
+        const exit = (await h.waitForTerminalExit({ terminalId: created.terminalId }));
+        expect(exit.exitCode).toBe(0);
+        const out = (await h.terminalOutput({ terminalId: created.terminalId }));
+        expect(String(out.output)).toContain("PONG");
+        expect(out.truncated).toBe(false);
+        // exitStatus aligns with the official terminalExitStatus schema (exitCode/signal).
+        expect(out.exitStatus.exitCode).toBe(0);
+        await h.releaseTerminal({ terminalId: created.terminalId });
+        // After release the terminal is forgotten -> empty output.
+        const afterRelease = (await h.terminalOutput({ terminalId: created.terminalId }));
+        expect(afterRelease.output).toBe("");
+    });
+    it("killTerminal terminates a long-running child; disposeAll reaps the rest", async () => {
+        const h = createAcpHostHandler({ cwd: process.cwd() });
+        const created = (await h.createTerminal({
+            command: process.execPath,
+            args: ["-e", "setInterval(() => {}, 1000)"],
+        }));
+        await h.killTerminal({ terminalId: created.terminalId });
+        const exit = (await h.waitForTerminalExit({ terminalId: created.terminalId }));
+        // Killed process exits via signal (or non-zero code on Windows).
+        expect(exit.exitCode === null || exit.exitCode !== 0 || exit.signal !== null).toBe(true);
+        const created2 = (await h.createTerminal({
+            command: process.execPath,
+            args: ["-e", "setInterval(() => {}, 1000)"],
+        }));
+        h.disposeAll();
+        const after = (await h.terminalOutput({ terminalId: created2.terminalId }));
+        expect(after.output).toBe("");
+    });
+});

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

@@ -0,0 +1,146 @@
+/**
+ * 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 type { ChildProcess } from "node:child_process";
+import type { AcpInitializeResult, AcpSessionResult, AcpPromptResponse, McpServerConfig } from "../../protocol/wire/acp-agent-management.js";
+/**
+ * Handler for agent→host requests (fs, terminal, permission, elicitation).
+ * Host implementations should implement the methods they support. This is intentionally loose
+ * (Record-typed) — {@link AcpProtocolAdapter} bridges it onto the SDK's strongly-typed Client.
+ */
+export interface AcpHostRequestHandler {
+    /** Read a text file from the host filesystem. */
+    readTextFile?(params: {
+        path: string;
+    }): Promise<{
+        content: string;
+    } | undefined>;
+    /** Write a text file on the host filesystem. */
+    writeTextFile?(params: {
+        path: string;
+        content: string;
+    }): Promise<Record<string, unknown> | undefined>;
+    /** Request permission for a tool call. Returns the chosen option id (host responsibility). */
+    requestPermission?(params: Record<string, unknown>): Promise<{
+        optionId: string;
+    }>;
+    /** Elicitation request (ask user for input). */
+    elicitation?(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Create a terminal session. */
+    createTerminal?(params: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+    /** Terminal output data. */
+    terminalOutput?(params: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+    /** Release a terminal. */
+    releaseTerminal?(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Wait for terminal exit. */
+    waitForTerminalExit?(params: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+    /** Kill a terminal. */
+    killTerminal?(params: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Extension method (unknown method from agent). */
+    extMethod?(method: string, params: unknown): Promise<unknown>;
+}
+/** Internal representation of an ACP notification translated to qlogicagent format. */
+export interface TranslatedNotification {
+    method: string;
+    params: Record<string, unknown>;
+}
+/** An auth method an agent advertises when it needs the user to log in (subset of ACP shape). */
+export interface AcpAuthMethod {
+    id?: string;
+    name?: string;
+    description?: string;
+}
+/**
+ * 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 declare class AcpAuthRequiredError extends Error {
+    readonly retryable: false;
+    readonly authMethods: AcpAuthMethod[];
+    constructor(message: string, authMethods: AcpAuthMethod[]);
+}
+/**
+ * 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 declare function asAuthRequiredError(err: unknown, fallbackAuthMethods?: AcpAuthMethod[]): AcpAuthRequiredError | null;
+export declare class AcpProtocolAdapter {
+    private conn;
+    private child;
+    private onNotification;
+    private hostHandler;
+    /**
+     * 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: ChildProcess, onNotification?: (method: string, params: unknown) => void, hostHandler?: AcpHostRequestHandler): void;
+    /**
+     * 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.
+     */
+    private buildClient;
+    /** Detach from the child process. The SDK read loop ends when the child's stdout closes. */
+    detach(): void;
+    private requireConn;
+    /** Race a connection call against a timeout; optionally run a side effect (e.g. cancel) on timeout. */
+    private withTimeout;
+    /**
+     * Perform the ACP initialize handshake. Sends standard clientInfo + clientCapabilities plus the
+     * qlogicagent extension capability (forwarded verbatim by the SDK).
+     */
+    initialize(_child?: ChildProcess): Promise<AcpInitializeResult>;
+    /**
+     * 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.
+     */
+    createSession(_child: ChildProcess, options: {
+        cwd: string;
+        mcpServers?: McpServerConfig[];
+        additionalDirectories?: string[];
+        systemPrompt?: string;
+    }): Promise<AcpSessionResult>;
+    /**
+     * 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.
+     */
+    sendPrompt(_child: ChildProcess, sessionId: string, content: string, timeoutMs?: number): Promise<AcpPromptResponse>;
+    /**
+     * Resume an existing ACP session (session/load — replays history via notifications).
+     * Only valid when the agent advertised the loadSession capability.
+     */
+    resumeSession(_child: ChildProcess, sessionId: string, options?: {
+        cwd?: string;
+        mcpServers?: McpServerConfig[];
+    }): Promise<AcpSessionResult>;
+    /**
+     * 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: string, params: unknown): TranslatedNotification | null;
+}