@armadra/agent 0.4.0 → 0.5.0

package/dist/drivers/agents.js

@@ -0,0 +1,142 @@
+/**
+ * 外部 Agent 的入口（W5-G 的 `task(agent=…)` 经它拿 runner，docs/wave5-plan.md §5.5、§7.6、D13、D17）。[W5-E]
+ *
+ * - `resolve("claude" | "codex" | "acp:<program>" | 表里的 id)` → {@link ProcessRunner}（按驱动表候选链，
+ *   每次 `start` 时按模式与安装情况选驱动）；同一 spec 复用同一个 runner。
+ * - 宿主（`HostApi.runners.provide`）注入的 runner 优先：同名替换内置外部 runner。
+ * - **有宿主（profile.host）时不自 spawn**：内置外部 runner 一律不可用，只认宿主注入的（D17；绕过画布
+ *   spawn 会让节点、连线授权与审批全部失效）。
+ * - 共用一个并发池、一个探测缓存（`<dataDir>/drivers.json`）与 pid 登记（`<dataDir>/drivers/pids.json`；
+ *   首次创建时清理上次崩溃留下的孤儿进程）。
+ */
+import { join } from "node:path";
+import { AmaError } from "../errors.js";
+import { AcpDriver } from "./acp/driver.js";
+import { DRIVER_CATALOG, candidatesFor } from "./catalog.js";
+import { HostRunnerRegistry } from "./host-runners.js";
+import { ClaudeStreamDriver } from "./native/claude-stream.js";
+import { CodexAppServerDriver } from "./native/codex-app-server.js";
+import { OneshotDriver } from "./native/oneshot.js";
+import { PidRegistry, pidsFile } from "./pids.js";
+import { poolFromConfig } from "./pool.js";
+import { ProgramProbe } from "./probe.js";
+import { spawnTransport } from "./process.js";
+import { ProcessRunner } from "./runner.js";
+/** 按候选种类建驱动。 */
+export function createDriver(agentId, candidate, deps) {
+    switch (candidate.kind) {
+        case "acp":
+        case "acp-adapter":
+            return new AcpDriver(agentId, candidate, deps);
+        case "claude-stream":
+            return new ClaudeStreamDriver(agentId, candidate, deps);
+        case "codex-app-server":
+            return new CodexAppServerDriver(agentId, candidate, deps);
+        case "oneshot":
+            return new OneshotDriver(agentId, candidate, deps);
+    }
+}
+export { HostRunnerRegistry };
+let reaped = false;
+export class ExternalAgents {
+    options;
+    hostRunners;
+    pool;
+    runners = new Map();
+    driverDeps;
+    constructor(options) {
+        this.options = options;
+        this.hostRunners = options.hostRunners ?? new HostRunnerRegistry();
+        this.pool = poolFromConfig(options.config);
+        const registry = options.dataDir !== undefined ? new PidRegistry(pidsFile(options.dataDir)) : undefined;
+        if (registry !== undefined && !reaped && options.driverDeps?.spawn === undefined) {
+            reaped = true;
+            void registry
+                .reapOrphans()
+                .then((killed) => {
+                if (killed.length > 0)
+                    options.log?.("info", `清理了上次遗留的外部 Agent 进程：${killed.join(", ")}`);
+            })
+                .catch(() => undefined);
+        }
+        const log = options.log;
+        this.driverDeps = {
+            probe: new ProgramProbe({
+                env: options.env,
+                cwd: options.cwd,
+                ...(options.dataDir !== undefined
+                    ? { cacheFile: join(options.dataDir, "drivers.json") }
+                    : {}),
+            }),
+            spawn: (spec) => spawnTransport(spec, {
+                onSpawn: (pid) => registry?.add(pid, spec.program),
+                onExit: (pid) => registry?.remove(pid),
+            }),
+            ...(log !== undefined ? { log } : {}),
+            ...options.driverDeps,
+        };
+    }
+    /** `task(agent=<spec>)` 的 runner；不可用时抛 AmaError（`agent_host_only` / `agent_unknown`）。 */
+    resolve(spec) {
+        const hosted = this.hostRunners.get(spec);
+        if (hosted !== undefined)
+            return hosted;
+        if (this.options.hosted)
+            throw new AmaError("agent_host_only", `嵌入宿主时外部 Agent 由宿主提供：「${spec}」没有被宿主注入（ama 不自行启动外部 CLI）`);
+        const cached = this.runners.get(spec);
+        if (cached !== undefined)
+            return cached;
+        const found = candidatesFor(spec);
+        if (found === undefined)
+            throw new AmaError("agent_unknown", `未知的外部 Agent：${spec}`);
+        const drivers = found.candidates.map((c) => createDriver(found.agentId, c, this.driverDeps));
+        const o = this.options;
+        const runner = new ProcessRunner(drivers, {
+            approve: o.approve,
+            pool: this.pool,
+            env: o.env,
+            trusted: o.trusted,
+            ...(o.store !== undefined ? { store: o.store } : {}),
+            ...(o.config !== undefined ? { config: o.config } : {}),
+            ...(o.parentMode !== undefined ? { parentMode: o.parentMode } : {}),
+            ...(o.unattended !== undefined ? { unattended: o.unattended } : {}),
+            ...(o.log !== undefined ? { log: o.log } : {}),
+        });
+        this.runners.set(spec, runner);
+        return runner;
+    }
+    /** `/agents` 与 RPC `get_agents` 的外部 Agent 部分（探测 PATH 与版本，不联网）。 */
+    async list() {
+        const out = this.hostRunners.list().map((r) => ({
+            name: r.id,
+            description: r.description,
+            runner: r.id,
+            source: "host",
+        }));
+        if (this.options.hosted)
+            return out;
+        for (const entry of DRIVER_CATALOG) {
+            if (out.some((a) => a.name === entry.agentId))
+                continue;
+            let installed = false;
+            let version;
+            for (const c of entry.candidates) {
+                const probe = await createDriver(entry.agentId, c, this.driverDeps).probe();
+                if (probe.installed) {
+                    installed = true;
+                    version = probe.version;
+                    break;
+                }
+            }
+            out.push({
+                name: entry.agentId,
+                description: entry.label,
+                runner: entry.agentId,
+                source: "builtin",
+                installed,
+                ...(version !== undefined ? { version } : {}),
+            });
+        }
+        return out;
+    }
+}

package/dist/drivers/base.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 各驱动共用的依赖与看门狗（docs/wave5-plan.md §5.4）。[W5-E]
+ */
+import type { PermissionMode } from "../permissions/types.js";
+import type { CatalogCandidate } from "./catalog.js";
+import type { ProgramProbe } from "./probe.js";
+import { type AgentTransport, type SpawnTransport } from "./process.js";
+import type { DriverProbe } from "./types.js";
+/** 中断后等回合结束的宽限；过了关 stdin，再 SIGTERM 进程树（§5.2 cancel）。 */
+export declare const CANCEL_GRACE_MS = 15000;
+export interface DriverDeps {
+    /** 缺省起真实子进程。 */
+    spawn?: SpawnTransport;
+    /** 缺省：认为已安装（测试 / 宿主注入的 transport 用）。 */
+    probe?: ProgramProbe;
+    log?(level: "debug" | "info" | "warn", message: string): void;
+    /** 缺省 {@link CANCEL_GRACE_MS}。 */
+    cancelGraceMs?: number;
+    /** 计时器（测试注入假时钟）。 */
+    setTimer?(fn: () => void, ms: number): () => void;
+}
+export declare function defaultSetTimer(fn: () => void, ms: number): () => void;
+export declare function spawnOf(deps: DriverDeps): SpawnTransport;
+/** 探测一个候选：已安装、版本、静态能力；版本越过已验证区间时附 warn。 */
+export declare function probeCandidate(candidate: CatalogCandidate, deps: DriverDeps): Promise<DriverProbe & {
+    path?: string;
+    warning?: string;
+}>;
+/**
+ * 中断的看门狗：发出协议级中断后，`graceMs` 内回合没结束就关 stdin 并杀进程树。
+ * 返回取消函数（回合正常结束时调用）。
+ */
+export declare function armCancelWatchdog(transport: AgentTransport, turnDone: Promise<unknown>, deps: DriverDeps): () => void;
+/** 模式是否只读类（plan / allowlist）：没有对应映射时不能让外部 Agent 以缺省模式跑。 */
+export declare function isReadOnlyMode(mode: PermissionMode): boolean;

package/dist/drivers/base.js

@@ -0,0 +1,59 @@
+/**
+ * 各驱动共用的依赖与看门狗（docs/wave5-plan.md §5.4）。[W5-E]
+ */
+import { candidateCapabilities } from "./catalog.js";
+import { versionSatisfies } from "./probe.js";
+import { spawnTransport } from "./process.js";
+/** 中断后等回合结束的宽限；过了关 stdin，再 SIGTERM 进程树（§5.2 cancel）。 */
+export const CANCEL_GRACE_MS = 15_000;
+export function defaultSetTimer(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+export function spawnOf(deps) {
+    return deps.spawn ?? ((spec) => spawnTransport(spec));
+}
+/** 探测一个候选：已安装、版本、静态能力；版本越过已验证区间时附 warn。 */
+export async function probeCandidate(candidate, deps) {
+    const capabilities = candidateCapabilities(candidate);
+    if (deps.probe === undefined)
+        return { installed: true, capabilities };
+    const located = await deps.probe.locate(candidate.program, candidate.versionArgs);
+    if (located === undefined)
+        return { installed: false, capabilities };
+    const out = {
+        installed: true,
+        capabilities,
+        path: located.path,
+    };
+    if (located.version !== undefined)
+        out.version = located.version;
+    if (candidate.verified !== undefined &&
+        located.version !== undefined &&
+        !versionSatisfies(located.version, candidate.verified))
+        out.warning = `${candidate.program} ${located.version} 不在已验证区间 ${candidate.verified}，协议可能有变化`;
+    return out;
+}
+/**
+ * 中断的看门狗：发出协议级中断后，`graceMs` 内回合没结束就关 stdin 并杀进程树。
+ * 返回取消函数（回合正常结束时调用）。
+ */
+export function armCancelWatchdog(transport, turnDone, deps) {
+    const setTimer = deps.setTimer ?? defaultSetTimer;
+    let fired = false;
+    const clear = setTimer(() => {
+        fired = true;
+        deps.log?.("warn", "外部 Agent 中断后未在宽限内结束回合，关闭进程");
+        void transport.terminate();
+    }, deps.cancelGraceMs ?? CANCEL_GRACE_MS);
+    void turnDone.finally(() => {
+        if (!fired)
+            clear();
+    });
+    return clear;
+}
+/** 模式是否只读类（plan / allowlist）：没有对应映射时不能让外部 Agent 以缺省模式跑。 */
+export function isReadOnlyMode(mode) {
+    return mode === "plan" || mode === "allowlist";
+}

package/dist/drivers/catalog.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 内置驱动表（数据，docs/wave5-plan.md §5.1 catalog.ts，D14）。[W5-E]
+ *
+ * agentId → 候选链；按 D14 的优先级排：原生 ACP > 已装 ACP 适配器 > 原生结构化协议 > 一次性打印。
+ * 探测时取第一个已安装的候选。`verified` 是实测过的版本区间：越界仍可用，但发一条 warn 提示
+ * （R3：Claude stream-json 不是公开接口、Codex app-server 标 experimental）。没有实测过的
+ * ACP Agent 不写 `verified`，`/agents` 标「未验证」。
+ *
+ * `runner: acp:<program>` 时先按程序名找本表里的 ACP 候选（拿到参数与模式映射），找不到就以
+ * 无参数的通用 ACP 启动。
+ */
+import type { PermissionMode } from "../permissions/types.js";
+import type { DriverCapabilities, DriverKind } from "./types.js";
+export type CandidateKind = Exclude<DriverKind, "host">;
+export interface CatalogCandidate {
+    kind: CandidateKind;
+    program: string;
+    args: readonly string[];
+    /** `--version` 以外的版本参数。 */
+    versionArgs?: readonly string[];
+    /** 实测过的版本区间（`>=x.y.z <x.y.z`）。 */
+    verified?: string;
+    /** ama 模式 → 该 Agent 的 ACP 模式 id（`session/set_mode`）；缺省按同名匹配。 */
+    modes?: Partial<Record<PermissionMode, string>>;
+    permissions?: DriverCapabilities["permissions"];
+    usage?: DriverCapabilities["usage"];
+    /** 一次性打印模式的方言。 */
+    oneshot?: "claude" | "codex" | "gemini";
+}
+export interface CatalogEntry {
+    agentId: string;
+    label: string;
+    candidates: readonly CatalogCandidate[];
+}
+export declare const DRIVER_CATALOG: readonly CatalogEntry[];
+export declare function catalogEntry(agentId: string): CatalogEntry | undefined;
+/**
+ * `runner` 规格 → 候选链：`claude` / `codex` 与表中 id 走表；`acp:<program>` 取表里同程序名的
+ * ACP 候选，否则通用 ACP（无参数）。
+ */
+export declare function candidatesFor(spec: string): {
+    agentId: string;
+    candidates: CatalogCandidate[];
+} | undefined;
+/** 候选的静态能力（ACP 的会话能力要到 initialize 才知道，这里取保守值）。 */
+export declare function candidateCapabilities(c: CatalogCandidate): DriverCapabilities;

package/dist/drivers/catalog.js

@@ -0,0 +1,167 @@
+/**
+ * 内置驱动表（数据，docs/wave5-plan.md §5.1 catalog.ts，D14）。[W5-E]
+ *
+ * agentId → 候选链；按 D14 的优先级排：原生 ACP > 已装 ACP 适配器 > 原生结构化协议 > 一次性打印。
+ * 探测时取第一个已安装的候选。`verified` 是实测过的版本区间：越界仍可用，但发一条 warn 提示
+ * （R3：Claude stream-json 不是公开接口、Codex app-server 标 experimental）。没有实测过的
+ * ACP Agent 不写 `verified`，`/agents` 标「未验证」。
+ *
+ * `runner: acp:<program>` 时先按程序名找本表里的 ACP 候选（拿到参数与模式映射），找不到就以
+ * 无参数的通用 ACP 启动。
+ */
+const ALL_MODES = [
+    "plan",
+    "allowlist",
+    "default",
+    "auto-edit",
+    "auto",
+    "full-auto",
+];
+export const DRIVER_CATALOG = [
+    {
+        agentId: "claude",
+        label: "Claude Code",
+        candidates: [
+            { kind: "acp-adapter", program: "claude-agent-acp", args: [], usage: "usd" },
+            {
+                kind: "claude-stream",
+                program: "claude",
+                args: [],
+                verified: ">=2.1.0 <3.0.0",
+                usage: "usd",
+            },
+            { kind: "oneshot", program: "claude", args: [], oneshot: "claude", usage: "usd" },
+        ],
+    },
+    {
+        agentId: "codex",
+        label: "Codex",
+        candidates: [
+            { kind: "acp-adapter", program: "codex-acp", args: [], usage: "tokens" },
+            {
+                kind: "codex-app-server",
+                program: "codex",
+                args: ["app-server"],
+                verified: ">=0.160.0 <0.200.0",
+                usage: "tokens",
+            },
+            { kind: "oneshot", program: "codex", args: [], oneshot: "codex", usage: "tokens" },
+        ],
+    },
+    {
+        agentId: "gemini",
+        label: "Gemini CLI",
+        candidates: [
+            { kind: "acp", program: "gemini", args: ["--acp"], usage: "tokens" },
+            { kind: "oneshot", program: "gemini", args: [], oneshot: "gemini", usage: "tokens" },
+        ],
+    },
+    {
+        agentId: "qwen",
+        label: "Qwen Code",
+        // #11887：0.23.x 受限模式下不发 request_permission 就执行 → 只在 plan 下用
+        candidates: [{ kind: "acp", program: "qwen", args: ["--acp"], permissions: "unreliable" }],
+    },
+    {
+        agentId: "kimi",
+        label: "Kimi Code",
+        candidates: [{ kind: "acp", program: "kimi", args: ["acp"] }],
+    },
+    {
+        agentId: "opencode",
+        label: "OpenCode",
+        candidates: [{ kind: "acp", program: "opencode", args: ["acp"] }],
+    },
+    {
+        agentId: "copilot",
+        label: "GitHub Copilot CLI",
+        candidates: [
+            { kind: "acp", program: "copilot", args: ["--acp", "--stdio"], usage: "requests" },
+        ],
+    },
+    {
+        agentId: "goose",
+        label: "Goose",
+        candidates: [{ kind: "acp", program: "goose", args: ["acp"] }],
+    },
+    {
+        agentId: "ama",
+        label: "ama",
+        candidates: [
+            {
+                kind: "acp",
+                program: "ama",
+                args: ["--mode", "acp"],
+                usage: "usd",
+                modes: Object.fromEntries(ALL_MODES.map((m) => [m, m])),
+            },
+        ],
+    },
+];
+export function catalogEntry(agentId) {
+    return DRIVER_CATALOG.find((entry) => entry.agentId === agentId);
+}
+/**
+ * `runner` 规格 → 候选链：`claude` / `codex` 与表中 id 走表；`acp:<program>` 取表里同程序名的
+ * ACP 候选，否则通用 ACP（无参数）。
+ */
+export function candidatesFor(spec) {
+    if (spec.startsWith("acp:")) {
+        const program = spec.slice(4).trim();
+        if (program === "")
+            return undefined;
+        for (const entry of DRIVER_CATALOG)
+            for (const c of entry.candidates)
+                if (c.kind === "acp" && c.program === program)
+                    return { agentId: spec, candidates: [c] };
+        return { agentId: spec, candidates: [{ kind: "acp", program, args: [] }] };
+    }
+    const entry = catalogEntry(spec);
+    return entry === undefined ? undefined : { agentId: spec, candidates: [...entry.candidates] };
+}
+/** 候选的静态能力（ACP 的会话能力要到 initialize 才知道，这里取保守值）。 */
+export function candidateCapabilities(c) {
+    switch (c.kind) {
+        case "claude-stream":
+            return {
+                resume: "resume",
+                list: false,
+                permissions: "interactive",
+                steer: true,
+                modes: ALL_MODES,
+                usage: "usd",
+                images: true,
+            };
+        case "codex-app-server":
+            return {
+                resume: "resume",
+                list: true,
+                permissions: "interactive",
+                steer: true,
+                modes: ALL_MODES,
+                usage: "tokens",
+                images: false,
+            };
+        case "oneshot":
+            return {
+                resume: c.oneshot === "gemini" ? "none" : "resume",
+                list: false,
+                permissions: "none",
+                steer: false,
+                // 不能审批：只在只读任务下用（§5.1 oneshot）
+                modes: ["plan"],
+                usage: c.usage ?? "none",
+                images: false,
+            };
+        default:
+            return {
+                resume: "resume",
+                list: true,
+                permissions: c.permissions ?? "interactive",
+                steer: false,
+                modes: c.permissions === "unreliable" ? ["plan"] : ALL_MODES,
+                usage: c.usage ?? "tokens",
+                images: false,
+            };
+    }
+}

package/dist/drivers/env.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 外部 Agent 子进程环境清理（docs/wave5-plan.md §5.4，D16）。[W5-E]
+ *
+ * ama 分不清「用户 shell 本来就有」与「为 ama 设的」变量，所以缺省全剥、显式放回：
+ * - 删：`BUILTIN_PROVIDERS[].envKeys`（各家 API key）、`*_BASE_URL`、`AMA_*`、`CODEX_API_KEY`、
+ *   `ANTHROPIC_AUTH_TOKEN`——它们漏进 Claude / Codex 会把订阅登录切成 API 计费（R2 K4）；
+ * - 删：`ARMADRA_*`（`ARMADRA_ASKPASS_*` 除外）——在 Armadra 画布终端里直接运行 ama 时，这些是该终端节点的
+ *   身份（节点 / 会话 / Hook 端点 / 画布控制）；子进程继承后，Armadra 装在 Claude / Codex 上的 Hook 会把
+ *   子 Agent 的事件记到这个节点名下（状态、审批等待、投递确认都会串）。askpass 留给 git 凭据提示；
+ * - 留：其余全部（PATH / HOME / LANG / TERM / SSH_* / 代理变量 / CLI 自己的 OAuth 令牌等）；
+ * - 放回：`agents.<id>.env.passthrough` 列出的变量（从原环境取值）。
+ *
+ * Windows 上变量名不分大小写，比较一律转大写。`--bare` 之类改用 API key 的旗标永不缺省（驱动侧）。
+ */
+import { type AgentsConfig } from "../config/types-w5.js";
+/** 除供应商表之外也要剥离的变量（会让 CLI 改用 API 计费）。 */
+export declare const EXTRA_STRIPPED_KEYS: readonly string[];
+/** 该变量是否缺省剥离。 */
+export declare function isStrippedEnvKey(name: string): boolean;
+export declare function buildChildEnv(env: NodeJS.ProcessEnv, agentId: string, config: AgentsConfig | undefined): NodeJS.ProcessEnv;

package/dist/drivers/env.js

@@ -0,0 +1,46 @@
+/**
+ * 外部 Agent 子进程环境清理（docs/wave5-plan.md §5.4，D16）。[W5-E]
+ *
+ * ama 分不清「用户 shell 本来就有」与「为 ama 设的」变量，所以缺省全剥、显式放回：
+ * - 删：`BUILTIN_PROVIDERS[].envKeys`（各家 API key）、`*_BASE_URL`、`AMA_*`、`CODEX_API_KEY`、
+ *   `ANTHROPIC_AUTH_TOKEN`——它们漏进 Claude / Codex 会把订阅登录切成 API 计费（R2 K4）；
+ * - 删：`ARMADRA_*`（`ARMADRA_ASKPASS_*` 除外）——在 Armadra 画布终端里直接运行 ama 时，这些是该终端节点的
+ *   身份（节点 / 会话 / Hook 端点 / 画布控制）；子进程继承后，Armadra 装在 Claude / Codex 上的 Hook 会把
+ *   子 Agent 的事件记到这个节点名下（状态、审批等待、投递确认都会串）。askpass 留给 git 凭据提示；
+ * - 留：其余全部（PATH / HOME / LANG / TERM / SSH_* / 代理变量 / CLI 自己的 OAuth 令牌等）；
+ * - 放回：`agents.<id>.env.passthrough` 列出的变量（从原环境取值）。
+ *
+ * Windows 上变量名不分大小写，比较一律转大写。`--bare` 之类改用 API key 的旗标永不缺省（驱动侧）。
+ */
+import { BUILTIN_PROVIDERS } from "../ai/providers/builtin.js";
+import { agentEntry } from "../config/types-w5.js";
+/** 除供应商表之外也要剥离的变量（会让 CLI 改用 API 计费）。 */
+export const EXTRA_STRIPPED_KEYS = ["CODEX_API_KEY", "ANTHROPIC_AUTH_TOKEN"];
+let providerKeys;
+function strippedKeys() {
+    providerKeys ??= new Set([...BUILTIN_PROVIDERS.flatMap((p) => p.envKeys ?? []), ...EXTRA_STRIPPED_KEYS].map((k) => k.toUpperCase()));
+    return providerKeys;
+}
+/** 该变量是否缺省剥离。 */
+export function isStrippedEnvKey(name) {
+    const upper = name.toUpperCase();
+    if (upper.startsWith("ARMADRA_"))
+        return !upper.startsWith("ARMADRA_ASKPASS_");
+    return upper.startsWith("AMA_") || upper.endsWith("_BASE_URL") || strippedKeys().has(upper);
+}
+export function buildChildEnv(env, agentId, config) {
+    const out = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined || isStrippedEnvKey(name))
+            continue;
+        out[name] = value;
+    }
+    const passthrough = agentEntry(config, agentId)?.env?.passthrough ?? [];
+    if (passthrough.length > 0) {
+        const wanted = new Set(passthrough.map((n) => n.toUpperCase()));
+        for (const [name, value] of Object.entries(env))
+            if (value !== undefined && wanted.has(name.toUpperCase()))
+                out[name] = value;
+    }
+    return out;
+}

package/dist/drivers/host-runners.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 宿主注入的 runner（`HostApi.runners.provide` 的底座，docs/wave5-plan.md §5.5，D17）。[W5-E → W5-EG]
+ *
+ * 一个宿主适配器一份（host/api-impl.ts 建，经 {@link ExternalAgents} 的 `hostRunners` 选项交给每个
+ * 主会话）：宿主可以在 `create()` 里或之后任何时候 `provide`，同名替换；返回的函数注销。
+ * `onChange` 供 `/agents` / RPC `get_agents` 的缓存刷新。
+ */
+import type { HostRunner } from "../host/types.js";
+export declare class HostRunnerRegistry {
+    private readonly runners;
+    private readonly listeners;
+    provide(runner: HostRunner): () => void;
+    get(id: string): HostRunner | undefined;
+    list(): HostRunner[];
+    /** 注入 / 注销时回调；返回取消订阅。 */
+    onChange(listener: () => void): () => void;
+    private changed;
+}

package/dist/drivers/host-runners.js

@@ -0,0 +1,45 @@
+/**
+ * 宿主注入的 runner（`HostApi.runners.provide` 的底座，docs/wave5-plan.md §5.5，D17）。[W5-E → W5-EG]
+ *
+ * 一个宿主适配器一份（host/api-impl.ts 建，经 {@link ExternalAgents} 的 `hostRunners` 选项交给每个
+ * 主会话）：宿主可以在 `create()` 里或之后任何时候 `provide`，同名替换；返回的函数注销。
+ * `onChange` 供 `/agents` / RPC `get_agents` 的缓存刷新。
+ */
+import { AmaError } from "../errors.js";
+export class HostRunnerRegistry {
+    runners = new Map();
+    listeners = new Set();
+    provide(runner) {
+        if (typeof runner?.id !== "string" || runner.id === "" || typeof runner.start !== "function")
+            throw new AmaError("invalid_arguments", "runners.provide：需要带 id 与 start 的 runner");
+        this.runners.set(runner.id, runner);
+        this.changed();
+        return () => {
+            if (this.runners.get(runner.id) !== runner)
+                return;
+            this.runners.delete(runner.id);
+            this.changed();
+        };
+    }
+    get(id) {
+        return this.runners.get(id);
+    }
+    list() {
+        return [...this.runners.values()];
+    }
+    /** 注入 / 注销时回调；返回取消订阅。 */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => void this.listeners.delete(listener);
+    }
+    changed() {
+        for (const listener of [...this.listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // 监听方出错不影响宿主
+            }
+        }
+    }
+}

package/dist/drivers/jsonrpc.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JSON-RPC 2.0 over NDJSON 的对等端（docs/wave5-plan.md §5.1）。[W5-E]
+ *
+ * ACP 客户端 / 服务端与 Codex app-server 驱动共用：
+ * - 分帧复用 `modes/rpc/jsonl.ts`（只按 `\n` 切行、64 KiB 分片写、背压等 drain），写入串行；
+ * - 双向：本端可发请求 / 通知，也处理对端的请求（`onRequest` 抛 {@link RpcError} 即回错误）与通知；
+ * - `jsonrpcField: false` 时不写 `"jsonrpc":"2.0"`（Codex app-server 的线上形状），读取两种都认；
+ * - 连接关闭（输入流结束）时所有挂起的请求以 `connection_closed` 失败。
+ */
+export type RpcId = string | number;
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+export interface IncomingRequestContext {
+    readonly id: RpcId;
+    /** 连接关闭时 abort。 */
+    readonly signal: AbortSignal;
+}
+export interface JsonRpcPeerOptions {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+    /** 缺省 true。 */
+    jsonrpcField?: boolean;
+    onRequest?(method: string, params: unknown, ctx: IncomingRequestContext): Promise<unknown>;
+    onNotification?(method: string, params: unknown): void;
+    /** 输入流结束（对端退出或关管道）。 */
+    onClose?(): void;
+    /** 无法解析的行（不影响连接）。 */
+    onProtocolError?(line: string, reason: string): void;
+}
+export declare class JsonRpcPeer {
+    private readonly options;
+    private readonly pending;
+    private readonly reader;
+    private readonly lifetime;
+    private nextId;
+    private writing;
+    private isClosed;
+    private resolveClosed;
+    /** 输入流结束或 `close()` 后 resolve。 */
+    readonly closed: Promise<void>;
+    constructor(options: JsonRpcPeerOptions);
+    get isOpen(): boolean;
+    /** 发请求；`signal` abort 时本端不再等（不通知对端，协议级取消由调用方另发）。 */
+    request<T = unknown>(method: string, params?: unknown, signal?: AbortSignal): Promise<T>;
+    /** 输入流结束后仍可写（对端可能只关了自己的写端，还在读）；写失败静默。 */
+    notify(method: string, params?: unknown): Promise<void>;
+    /** 停止读取并让挂起请求失败；不关闭底层流（由调用方决定）。 */
+    close(): void;
+    /** 等所有已排队的写入完成。 */
+    flush(): Promise<void>;
+    private shutdown;
+    private send;
+    private onLine;
+    private handleRequest;
+}