@armadra/agent 0.7.6 → 0.8.1

package/dist/drivers/native/pi-rpc.js

@@ -0,0 +1,483 @@
+/**
+ * pi 原生驱动：`pi --mode rpc` 长驻进程（stdin 命令 / stdout 响应与事件，严格按 LF 分帧）。[#198]
+ *
+ * `pi --mode rpc --session-id <uuid> [--model <m>] -e <审批闸> [--tools read,grep,find,ls]`
+ * （新会话与续聊都用 `--session-id`：pi 找到同 id 的项目会话就续上，否则新建）。
+ *
+ * - 回合：`prompt` → 响应 `disposition`（`handled` 时没有运行，直接结束）→ 事件流 → `agent_settled`
+ *   结束（`aborted` 为真即中断）；运行中追加用 `steer`；中断 `abort`（15 s 看门狗）。
+ * - 审批：pi 自己不问人，ama 以 `-e` 加载审批闸（{@link PI_GATE_SOURCE}），只读内置工具以外的调用
+ *   经 `extension_ui_request{confirm, title: "ama-approval"}` 到这里：plan / allowlist 直接拒绝（并以
+ *   `--tools` 只开只读工具），auto-edit / auto / full-auto 放行 `edit` / `write`，其余交给人（只交给人，
+ *   不代答）。其它扩展的对话框（select / input / editor / 别的 confirm）一律取消并提示。
+ * - 用量：assistant `message_end` 的 usage 累加（input 不含缓存命中，cost.total 是 pi 按价目表的估算）；
+ *   回合结束后 `get_session_stats` 的 `contextUsage` 记上下文占用与窗口。
+ */
+import { randomUUID } from "node:crypto";
+import { resolve as resolvePath } from "node:path";
+import { AmaError } from "../../errors.js";
+import { createLineReader } from "../../modes/rpc/jsonl.js";
+import { armCancelWatchdog, isReadOnlyMode, probeCandidate, spawnOf, } from "../base.js";
+import { stderrHint } from "../process.js";
+import { TurnCollector, oneLine } from "../turn.js";
+import { PI_GATE_TITLE, PI_READ_ONLY_TOOLS, writePiGate } from "./pi-gate.js";
+import { msg } from "../../i18n/index.js";
+const DIALOG_METHODS = new Set(["select", "confirm", "input", "editor"]);
+/** auto-edit 及更宽的模式下不问人的文件编辑工具。 */
+const EDIT_TOOLS = new Set(["edit", "write"]);
+export function piArgs(options, sessionId, gatePath) {
+    const args = ["--session-id", sessionId];
+    if (options.model !== undefined)
+        args.push("--model", options.model);
+    args.push("-e", gatePath);
+    if (isReadOnlyMode(options.mode))
+        args.push("--tools", PI_READ_ONLY_TOOLS.join(","));
+    return args;
+}
+export function piToolKind(tool) {
+    switch (tool) {
+        case "bash":
+        case "powershell":
+            return "execute";
+        case "edit":
+        case "write":
+            return "edit";
+        case "read":
+            return "read";
+        case "grep":
+        case "find":
+        case "ls":
+            return "search";
+        default:
+            return "other";
+    }
+}
+function piToolTitle(tool, input) {
+    if (typeof input["command"] === "string")
+        return `$ ${oneLine(input["command"], 100)}`;
+    if (typeof input["path"] === "string")
+        return `${tool} ${input["path"]}`;
+    if (typeof input["pattern"] === "string")
+        return `${tool} ${oneLine(input["pattern"], 80)}`;
+    return tool;
+}
+function textOf(message) {
+    const content = message["content"];
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((b) => (b["type"] === "text" && typeof b["text"] === "string" ? b["text"] : ""))
+        .join("");
+}
+export class PiRpcDriver {
+    agentId;
+    candidate;
+    deps;
+    kind = "pi-rpc";
+    constructor(agentId, candidate, deps = {}) {
+        this.agentId = agentId;
+        this.candidate = candidate;
+        this.deps = deps;
+    }
+    probe() {
+        return probeCandidate(this.candidate, this.deps);
+    }
+    async open(options) {
+        const probed = await probeCandidate(this.candidate, this.deps);
+        const sessionId = options.resume ?? randomUUID();
+        const gate = writePiGate();
+        const transport = spawnOf(this.deps)({
+            program: probed.path ?? this.candidate.program,
+            args: [...this.candidate.args, ...piArgs(options, sessionId, gate.path)],
+            cwd: options.cwd,
+            env: options.env,
+        });
+        const session = new PiSession(this.agentId, sessionId, transport, options, this.deps, () => gate.dispose());
+        if (probed.warning !== undefined)
+            session.notices.push(probed.warning);
+        try {
+            await session.start(options.signal);
+        }
+        catch (error) {
+            await session.close();
+            throw new AmaError("agent_start_failed", `${this.agentId}: failed to start (${error.message})${stderrHint(transport) !== "" ? `: ${stderrHint(transport)}` : ""}`, { cause: error });
+        }
+        return session;
+    }
+}
+class PiSession {
+    agentId;
+    id;
+    transport;
+    options;
+    deps;
+    dispose;
+    notices = [];
+    nextId = 1;
+    pending = new Map();
+    permissions = new Set();
+    turn;
+    hooks;
+    settle;
+    running;
+    usage = { input: 0, output: 0, cacheRead: 0, costUsd: 0, seen: false };
+    lastAssistant;
+    interrupted = false;
+    closed = false;
+    exited = false;
+    exitWaiters = new Set();
+    constructor(agentId, id, transport, options, deps, dispose) {
+        this.agentId = agentId;
+        this.id = id;
+        this.transport = transport;
+        this.options = options;
+        this.deps = deps;
+        this.dispose = dispose;
+        createLineReader(transport.stdout, (line) => this.onLine(line), () => this.onExit());
+        transport.stdin.on?.("error", () => undefined);
+    }
+    get sessionId() {
+        return this.id;
+    }
+    /** 握手：`get_state` 确认进程起来了，并取 pi 实际使用的会话 id。 */
+    async start(signal) {
+        const aborted = new Promise((_, reject) => {
+            if (signal.aborted)
+                reject(new Error("aborted"));
+            signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+        });
+        void aborted.catch(() => undefined);
+        const state = await Promise.race([this.request({ type: "get_state" }), aborted]);
+        const data = (state["data"] ?? {});
+        if (typeof data["sessionId"] === "string" && data["sessionId"] !== "")
+            this.id = data["sessionId"];
+    }
+    async prompt(content, hooks) {
+        if (this.closed || this.exited)
+            throw new AmaError("agent_closed", `${this.agentId} session is closed`);
+        if (this.running !== undefined)
+            throw new AmaError("busy", `${this.agentId} is already running`);
+        const turn = new TurnCollector((e) => hooks.onEvent(e));
+        for (const text of this.notices.splice(0))
+            turn.push({ type: "notice", level: "warn", text });
+        this.turn = turn;
+        this.hooks = hooks;
+        this.interrupted = false;
+        this.usage = { input: 0, output: 0, cacheRead: 0, costUsd: 0, seen: false };
+        this.lastAssistant = undefined;
+        this.running = this.run(content, turn);
+        try {
+            return await this.running;
+        }
+        finally {
+            this.running = undefined;
+            this.turn = undefined;
+            this.hooks = undefined;
+            this.settle = undefined;
+            this.exitWaiters.clear();
+        }
+    }
+    async run(content, turn) {
+        // 先让出一拍：`this.running` 赋值之后再写命令（同步回显的对端里事件可能立刻到达并触发 cancel）
+        await Promise.resolve();
+        const settled = new Promise((resolve) => (this.settle = resolve));
+        const response = await this.request({ type: "prompt", ...this.message(content) });
+        if (response["success"] !== true)
+            throw new AmaError("agent_failed", `${this.agentId} rejected the prompt: ${oneLine(String(response["error"] ?? "unknown"), 300)}`);
+        const disposition = (response["data"] ?? {})["disposition"];
+        if (disposition === "handled")
+            return turn.result("end_turn");
+        const aborted = await Promise.race([settled, this.exitPromise()]);
+        await this.reportContext(turn);
+        return this.complete(turn, aborted);
+    }
+    async steer(content) {
+        if (this.closed || this.exited)
+            throw new AmaError("agent_closed", `${this.agentId} session is closed`);
+        await this.request({ type: "steer", ...this.message(content) });
+    }
+    async cancel() {
+        const running = this.running;
+        if (running === undefined || this.closed)
+            return;
+        this.interrupted = true;
+        for (const c of this.permissions)
+            c.abort();
+        void this.request({ type: "abort" }).catch(() => undefined);
+        armCancelWatchdog(this.transport, running.catch(() => undefined), this.deps);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const c of this.permissions)
+            c.abort();
+        if (this.running !== undefined) {
+            this.interrupted = true;
+            this.write({ type: "abort" });
+        }
+        try {
+            await this.transport.terminate();
+        }
+        finally {
+            this.dispose();
+        }
+    }
+    message(content) {
+        const text = content.map((b) => (b.type === "text" ? b.text : "")).join("\n");
+        const images = content.flatMap((b) => b.type === "image" ? [{ type: "image", data: b.data, mimeType: b.mimeType }] : []);
+        return { message: text, ...(images.length > 0 ? { images } : {}) };
+    }
+    complete(turn, aborted) {
+        const u = this.usage;
+        if (u.seen)
+            turn.push({
+                type: "usage",
+                input: u.input,
+                output: u.output,
+                cacheRead: u.cacheRead,
+                costUsd: u.costUsd,
+            });
+        const last = this.lastAssistant;
+        if (last !== undefined) {
+            const text = textOf(last);
+            if (text !== "")
+                turn.setFinalText(text);
+        }
+        if (aborted || this.interrupted)
+            return turn.result("cancelled");
+        switch (last?.["stopReason"]) {
+            case "error":
+                throw new AmaError("agent_failed", `${this.agentId} failed: ${oneLine(String(last["errorMessage"] ?? "unknown error"), 300)}`);
+            case "aborted":
+                return turn.result("cancelled");
+            case "length":
+                return turn.result("max_tokens");
+            default:
+                return turn.result("end_turn");
+        }
+    }
+    /** `get_session_stats.contextUsage` → 上下文占用与窗口（拿不到就算了）。 */
+    async reportContext(turn) {
+        if (this.exited)
+            return;
+        try {
+            const stats = await Promise.race([
+                this.request({ type: "get_session_stats" }),
+                new Promise((resolve) => setTimeout(() => resolve({}), 5_000).unref()),
+            ]);
+            const usage = ((stats["data"] ?? {})["contextUsage"] ?? {});
+            const tokens = usage["tokens"];
+            const window = usage["contextWindow"];
+            if (typeof tokens === "number" || typeof window === "number")
+                turn.push({
+                    type: "usage",
+                    ...(typeof tokens === "number" ? { contextTokens: tokens } : {}),
+                    ...(typeof window === "number" ? { contextWindow: window } : {}),
+                });
+        }
+        catch {
+            // 统计拿不到不影响回合
+        }
+    }
+    exitPromise() {
+        return new Promise((_, reject) => {
+            if (this.exited)
+                reject(this.exitError());
+            else
+                this.exitWaiters.add(reject);
+        });
+    }
+    exitError() {
+        const hint = stderrHint(this.transport);
+        return new AmaError("agent_exited", `${this.agentId} process exited${hint !== "" ? `: ${hint}` : ""}`);
+    }
+    request(command) {
+        if (this.exited)
+            return Promise.reject(this.exitError());
+        const id = `ama-${this.nextId++}`;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.write({ id, ...command });
+        });
+    }
+    write(record) {
+        if (this.exited)
+            return;
+        this.transport.stdin.write(`${JSON.stringify(record)}\n`);
+    }
+    onExit() {
+        this.exited = true;
+        const error = this.exitError();
+        for (const p of this.pending.values())
+            p.reject(error);
+        this.pending.clear();
+        for (const reject of this.exitWaiters)
+            reject(error);
+        this.exitWaiters.clear();
+        for (const c of this.permissions)
+            c.abort();
+    }
+    onLine(line) {
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            this.deps.log?.("debug", msg().drivers.agent.nonJson(this.agentId));
+            return;
+        }
+        switch (record["type"]) {
+            case "response": {
+                const id = record["id"];
+                const pending = typeof id === "string" ? this.pending.get(id) : undefined;
+                if (pending === undefined || typeof id !== "string")
+                    return;
+                this.pending.delete(id);
+                pending.resolve(record);
+                return;
+            }
+            case "agent_settled":
+                this.settle?.(record["aborted"] === true);
+                return;
+            case "extension_ui_request":
+                void this.onDialog(record);
+                return;
+            default:
+                this.onEvent(record);
+        }
+    }
+    onEvent(record) {
+        const turn = this.turn;
+        if (turn === undefined)
+            return;
+        switch (record["type"]) {
+            case "message_update": {
+                const event = (record["assistantMessageEvent"] ?? {});
+                const delta = event["delta"];
+                if (typeof delta !== "string")
+                    return;
+                if (event["type"] === "text_delta")
+                    turn.push({ type: "message_delta", text: delta });
+                else if (event["type"] === "thinking_delta")
+                    turn.push({ type: "thought_delta", text: delta });
+                return;
+            }
+            case "message_end": {
+                const message = (record["message"] ?? {});
+                if (message["role"] !== "assistant")
+                    return;
+                this.lastAssistant = message;
+                const usage = (message["usage"] ?? {});
+                const num = (key) => typeof usage[key] === "number" ? usage[key] : 0;
+                const cost = (usage["cost"] ?? {})["total"];
+                this.usage = {
+                    input: this.usage.input + num("input"),
+                    output: this.usage.output + num("output"),
+                    cacheRead: this.usage.cacheRead + num("cacheRead"),
+                    costUsd: this.usage.costUsd + (typeof cost === "number" ? cost : 0),
+                    seen: true,
+                };
+                return;
+            }
+            case "tool_execution_start":
+            case "tool_execution_end": {
+                const tool = String(record["toolName"] ?? "tool");
+                const known = turn.tool(String(record["toolCallId"] ?? ""));
+                const input = (record["args"] ?? {});
+                const path = typeof input["path"] === "string" ? input["path"] : undefined;
+                const locations = path !== undefined ? [resolvePath(this.options.cwd, path)] : known?.locations;
+                turn.push({
+                    type: "tool_call",
+                    id: String(record["toolCallId"] ?? ""),
+                    title: known?.title ?? piToolTitle(tool, input),
+                    kind: piToolKind(tool),
+                    status: record["type"] === "tool_execution_start"
+                        ? "in_progress"
+                        : record["isError"] === true
+                            ? "failed"
+                            : "completed",
+                    ...(locations !== undefined && locations.length > 0 ? { locations } : {}),
+                });
+                return;
+            }
+            case "auto_retry_start":
+                turn.push({
+                    type: "notice",
+                    level: "warn",
+                    text: msg().drivers.agent.error(this.agentId, oneLine(String(record["errorMessage"] ?? "error"), 200), true),
+                });
+                return;
+            default:
+                return;
+        }
+    }
+    /** 扩展对话框：ama 的审批闸按模式决定或交给人；其它扩展的对话框取消（不代答）。 */
+    async onDialog(record) {
+        const id = String(record["id"] ?? "");
+        const method = String(record["method"] ?? "");
+        if (!DIALOG_METHODS.has(method)) {
+            if (record["method"] === "notify" && record["notifyType"] !== "info")
+                this.turn?.push({
+                    type: "notice",
+                    level: "warn",
+                    text: `${this.agentId}: ${oneLine(String(record["message"] ?? ""), 200)}`,
+                });
+            return;
+        }
+        if (method !== "confirm" || record["title"] !== PI_GATE_TITLE) {
+            this.turn?.push({
+                type: "notice",
+                level: "warn",
+                text: msg().drivers.agent.extensionDialog(this.agentId, oneLine(String(record["title"] ?? method), 80)),
+            });
+            this.write({ type: "extension_ui_response", id, cancelled: true });
+            return;
+        }
+        const confirmed = await this.decide(record);
+        this.write({ type: "extension_ui_response", id, confirmed });
+    }
+    async decide(record) {
+        let call;
+        try {
+            call = JSON.parse(String(record["message"] ?? "{}"));
+        }
+        catch {
+            return false;
+        }
+        const tool = String(call["tool"] ?? "tool");
+        const input = (call["input"] ?? {});
+        const mode = this.options.mode;
+        if (isReadOnlyMode(mode))
+            return false;
+        if (mode !== "default" && EDIT_TOOLS.has(tool))
+            return true;
+        const hooks = this.hooks;
+        if (hooks === undefined || this.interrupted || this.closed)
+            return false;
+        const known = this.turn?.tool(String(call["id"] ?? ""));
+        const path = typeof input["path"] === "string" ? input["path"] : undefined;
+        const controller = new AbortController();
+        this.permissions.add(controller);
+        try {
+            const outcome = await hooks.onPermission({
+                toolCall: {
+                    title: known?.title ?? piToolTitle(tool, input),
+                    kind: piToolKind(tool),
+                    ...(path !== undefined ? { locations: [resolvePath(this.options.cwd, path)] } : {}),
+                    inputSummary: oneLine(JSON.stringify(input), 300),
+                },
+                options: [
+                    { optionId: "allow", kind: "allow_once" },
+                    { optionId: "reject", kind: "reject_once" },
+                ],
+            }, controller.signal);
+            return (!controller.signal.aborted && outcome.outcome === "selected" && outcome.optionId === "allow");
+        }
+        finally {
+            this.permissions.delete(controller);
+        }
+    }
+}

package/dist/drivers/permissions.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的权限：交人、不代答（docs/wave5-plan.md §5.3，D15）。[W5-E]
+ * 外部 Agent 的权限：交人、不代答（docs/history/wave5-plan.md §5.3，D15）。[W5-E]
  *
  * 1. 子 Agent 自己的策略先判，它决定要问人的才到 ama；到了以后只走审批通道（宿主 → UI →
  *    无人值守拒绝），auto 分类器与模型都不参与——`approve` 由调用方接到会话的

package/dist/drivers/permissions.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的权限：交人、不代答（docs/wave5-plan.md §5.3，D15）。[W5-E]
+ * 外部 Agent 的权限：交人、不代答（docs/history/wave5-plan.md §5.3，D15）。[W5-E]
  *
  * 1. 子 Agent 自己的策略先判，它决定要问人的才到 ama；到了以后只走审批通道（宿主 → UI →
  *    无人值守拒绝），auto 分类器与模型都不参与——`approve` 由调用方接到会话的

package/dist/drivers/pids.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 进程登记与孤儿清理（docs/wave5-plan.md §5.4 孤儿进程）。[W5-E]
+ * 外部 Agent 进程登记与孤儿清理（docs/history/wave5-plan.md §5.4 孤儿进程）。[W5-E]
  *
  * `<dataDir>/drivers/pids.json` 记 `{ pid, program, owner }`（owner = 起它的 ama 进程）。
  * 正常退出时 `process-tree.ts` 已同步杀掉仍存活的组；这里处理 ama 被 SIGKILL / 崩溃留下的孤儿：

package/dist/drivers/pids.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 进程登记与孤儿清理（docs/wave5-plan.md §5.4 孤儿进程）。[W5-E]
+ * 外部 Agent 进程登记与孤儿清理（docs/history/wave5-plan.md §5.4 孤儿进程）。[W5-E]
  *
  * `<dataDir>/drivers/pids.json` 记 `{ pid, program, owner }`（owner = 起它的 ama 进程）。
  * 正常退出时 `process-tree.ts` 已同步杀掉仍存活的组；这里处理 ama 被 SIGKILL / 崩溃留下的孤儿：

package/dist/drivers/pool.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 并发池（docs/wave5-plan.md §5.4 并发）。[W5-E]
+ * 外部 Agent 并发池（docs/history/wave5-plan.md §5.4 并发）。[W5-E]
  *
  * 总并发 `agents.maxConcurrent`（缺省 3）+ 每个 Agent 的上限 `agents.<id>.maxConcurrent`
  * （claude 缺省 2：订阅有速率限制）；超出排队（先来先得），排队可被 abort。与 ama 自己的

package/dist/drivers/pool.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 并发池（docs/wave5-plan.md §5.4 并发）。[W5-E]
+ * 外部 Agent 并发池（docs/history/wave5-plan.md §5.4 并发）。[W5-E]
  *
  * 总并发 `agents.maxConcurrent`（缺省 3）+ 每个 Agent 的上限 `agents.<id>.maxConcurrent`
  * （claude 缺省 2：订阅有速率限制）；超出排队（先来先得），排队可被 abort。与 ama 自己的

package/dist/drivers/probe.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的探测（docs/wave5-plan.md §5.1 probe.ts）。[W5-E]
+ * 外部 Agent 的探测（docs/history/wave5-plan.md §5.1 probe.ts）。[W5-E]
  *
  * - PATH 查找不起 shell：逐个目录拼程序名（Windows 加 PATHEXT 后缀）；绝对 / 相对路径直接认。
  * - 版本：`<program> --version` 取第一个 `x.y.z`，5 s 超时，不联网、不计费。

package/dist/drivers/probe.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的探测（docs/wave5-plan.md §5.1 probe.ts）。[W5-E]
+ * 外部 Agent 的探测（docs/history/wave5-plan.md §5.1 probe.ts）。[W5-E]
  *
  * - PATH 查找不起 shell：逐个目录拼程序名（Windows 加 PATHEXT 后缀）；绝对 / 相对路径直接认。
  * - 版本：`<program> --version` 取第一个 `x.y.z`，5 s 超时，不联网、不计费。

package/dist/drivers/process.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 子进程（docs/wave5-plan.md §5.4 看门狗 / 孤儿进程）。[W5-E]
+ * 外部 Agent 子进程（docs/history/wave5-plan.md §5.4 看门狗 / 孤儿进程）。[W5-E]
  *
  * - POSIX 以 `detached` 自成进程组，结束时 `killProcessTree`（SIGTERM → 宽限 → SIGKILL）；
  *   登记到 `tools/process-tree.ts`，ama 退出时同步清掉仍存活的组。

package/dist/drivers/process.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 子进程（docs/wave5-plan.md §5.4 看门狗 / 孤儿进程）。[W5-E]
+ * 外部 Agent 子进程（docs/history/wave5-plan.md §5.4 看门狗 / 孤儿进程）。[W5-E]
  *
  * - POSIX 以 `detached` 自成进程组，结束时 `killProcessTree`（SIGTERM → 宽限 → SIGKILL）；
  *   登记到 `tools/process-tree.ts`，ama 退出时同步清掉仍存活的组。

package/dist/drivers/runner.d.ts

@@ -1,5 +1,5 @@
 /**
- * ProcessRunner：把 AgentDriver 适配成 SubagentRunner（docs/wave5-plan.md §7.6、§5.3–§5.4）。[W5-E]
+ * ProcessRunner：把 AgentDriver 适配成 SubagentRunner（docs/history/wave5-plan.md §7.6、§5.3–§5.4）。[W5-E]
  *
  * 外部 CLI Agent 由此与 ama 子 Agent 共用 `task(agent=…)` 入口（D13）。`start()`：
  * 1. 只在已信任目录里起（§5.4 信任；`claude -p` 会跳过目录信任对话框并执行项目 hooks）；

package/dist/drivers/runner.js

@@ -1,5 +1,5 @@
 /**
- * ProcessRunner：把 AgentDriver 适配成 SubagentRunner（docs/wave5-plan.md §7.6、§5.3–§5.4）。[W5-E]
+ * ProcessRunner：把 AgentDriver 适配成 SubagentRunner（docs/history/wave5-plan.md §7.6、§5.3–§5.4）。[W5-E]
  *
  * 外部 CLI Agent 由此与 ama 子 Agent 共用 `task(agent=…)` 入口（D13）。`start()`：
  * 1. 只在已信任目录里起（§5.4 信任；`claude -p` 会跳过目录信任对话框并执行项目 hooks）；
@@ -144,6 +144,7 @@ const TURN_INTERRUPT = new Set([
     "acp-adapter",
     "claude-stream",
     "codex-app-server",
+    "pi-rpc",
 ]);
 class ProcessHandle {
     runner;

package/dist/drivers/store.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的会话引用与记账（docs/wave5-plan.md §5.4 记账 / 敏感数据，session-format 登记）。[W5-E]
+ * 外部 Agent 的会话引用与记账（docs/history/wave5-plan.md §5.4 记账 / 敏感数据，session-format 登记）。[W5-E]
  *
  * - `custom{ama.agent-session}`：`{ agent, runner, sessionId, cwd?, taskId? }`——外部 CLI 自己的
  *   会话 id，续聊（`taskId` / resume）用；不含原始事件与转录。

package/dist/drivers/store.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 的会话引用与记账（docs/wave5-plan.md §5.4 记账 / 敏感数据，session-format 登记）。[W5-E]
+ * 外部 Agent 的会话引用与记账（docs/history/wave5-plan.md §5.4 记账 / 敏感数据，session-format 登记）。[W5-E]
  *
  * - `custom{ama.agent-session}`：`{ agent, runner, sessionId, cwd?, taskId? }`——外部 CLI 自己的
  *   会话 id，续聊（`taskId` / resume）用；不含原始事件与转录。

package/dist/drivers/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 驱动契约（docs/wave5-plan.md §5.1–§5.3，D14）。[W5-C0] 契约文件，实现归 W5-E。
+ * 外部 Agent 驱动契约（docs/history/wave5-plan.md §5.1–§5.3，D14）。[W5-C0] 契约文件，实现归 W5-E。
  *
  * 内部词汇 = ACP v1 子集：各家原生协议（Claude stream-json、Codex app-server、一次性打印模式）
  * 都映射成 `DriverEvent`；权限请求以 `DriverPermissionRequest` 交给 ama 的 broker 链——**只交给人，
@@ -20,7 +20,7 @@ export interface DriverCapabilities {
     usage: "tokens" | "usd" | "requests" | "none";
     images: boolean;
 }
-export type DriverKind = "acp" | "acp-adapter" | "claude-stream" | "codex-app-server" | "oneshot" | "host";
+export type DriverKind = "acp" | "acp-adapter" | "claude-stream" | "codex-app-server" | "pi-rpc" | "oneshot" | "host";
 export interface DriverProbe {
     installed: boolean;
     version?: string;

package/dist/drivers/types.js

@@ -1,5 +1,5 @@
 /**
- * 外部 Agent 驱动契约（docs/wave5-plan.md §5.1–§5.3，D14）。[W5-C0] 契约文件，实现归 W5-E。
+ * 外部 Agent 驱动契约（docs/history/wave5-plan.md §5.1–§5.3，D14）。[W5-C0] 契约文件，实现归 W5-E。
  *
  * 内部词汇 = ACP v1 子集：各家原生协议（Claude stream-json、Codex app-server、一次性打印模式）
  * 都映射成 `DriverEvent`；权限请求以 `DriverPermissionRequest` 交给 ama 的 broker 链——**只交给人，

package/dist/git/info.d.ts

@@ -1,5 +1,5 @@
 /**
- * 状态行的 git 信息（docs/wave5-plan.md §1.3）。[W5-A]
+ * 状态行的 git 信息（docs/history/wave5-plan.md §1.3）。[W5-A]
  *
  * - 分支与短提交零依赖读 `.git/HEAD`（`checkpoints/git-head.ts`，worktree / 子模块的 gitdir 文件、
  *   packed-refs 都认）；detached 时没有分支只显示短提交；还没有提交的分支只显示分支名。

package/dist/git/info.js

@@ -1,5 +1,5 @@
 /**
- * 状态行的 git 信息（docs/wave5-plan.md §1.3）。[W5-A]
+ * 状态行的 git 信息（docs/history/wave5-plan.md §1.3）。[W5-A]
  *
  * - 分支与短提交零依赖读 `.git/HEAD`（`checkpoints/git-head.ts`，worktree / 子模块的 gitdir 文件、
  *   packed-refs 都认）；detached 时没有分支只显示短提交；还没有提交的分支只显示分支名。

package/dist/host/api-impl.d.ts

@@ -6,7 +6,7 @@
  * 事件总线 `AgentEventBus` 由 bootstrap 创建并交给 AgentSession 发事件；处理器只观察，
  * 抛错记日志；`emit` 等待全部处理器（`session_shutdown` 需要被 await）。
  *
- * [W5-EG] `runners.provide`（docs/wave5-plan.md §5.5，D17）：宿主注入的 runner 进本适配器的
+ * [W5-EG] `runners.provide`（docs/history/wave5-plan.md §5.5，D17）：宿主注入的 runner 进本适配器的
  * {@link HostRunnerRegistry}（跨会话共享），每个主会话的外部 Agent 入口（agents/external.ts）经
  * {@link hostRunnersOf} 取到它；有宿主时 ama 不自 spawn 外部 CLI，只认这里注入的。
  */

package/dist/host/api-impl.js

@@ -6,7 +6,7 @@
  * 事件总线 `AgentEventBus` 由 bootstrap 创建并交给 AgentSession 发事件；处理器只观察，
  * 抛错记日志；`emit` 等待全部处理器（`session_shutdown` 需要被 await）。
  *
- * [W5-EG] `runners.provide`（docs/wave5-plan.md §5.5，D17）：宿主注入的 runner 进本适配器的
+ * [W5-EG] `runners.provide`（docs/history/wave5-plan.md §5.5，D17）：宿主注入的 runner 进本适配器的
  * {@link HostRunnerRegistry}（跨会话共享），每个主会话的外部 Agent 入口（agents/external.ts）经
  * {@link hostRunnersOf} 取到它；有宿主时 ama 不自 spawn 外部 CLI，只认这里注入的。
  */