@armadra/agent 0.4.0 → 0.5.0

package/dist/drivers/native/claude-stream.js

@@ -0,0 +1,456 @@
+/**
+ * Claude Code 原生驱动：stream-json 长驻进程（docs/wave5-plan.md §5.1，R2 §1.2）。[W5-E]
+ *
+ * `claude -p --input-format stream-json --output-format stream-json --verbose
+ *  --include-partial-messages --permission-prompt-tool stdio --permission-mode <m> --session-id <uuid>`
+ * （续聊 `--resume <id>`；预算 `--max-budget-usd`；无人值守改 `--permission-prompts none`）。
+ *
+ * - 多轮复用同一进程：每回合写一行 `{"type":"user",…}`，以 `result` 结束；运行中再写即 steer。
+ * - 权限：`control_request{can_use_tool}` → hooks.onPermission（只交给人）→ `control_response`
+ *   allow（必须带 `updatedInput`，原样回传）/ deny；`control_cancel_request` 让挂起的请求回
+ *   cancelled。「本会话允许」只在 Claude 给了 `destination: "session"` 的建议时提供，并只回传这些
+ *   （会写配置文件的建议不替人接受）。`AskUserQuestion` 不代答：拒绝并提示写进最终回复。
+ * - 中断：`control_request{interrupt}`；15 s 无 `result` → 关 stdin → 杀进程树（#98713 / #94741）。
+ * - `--bare` 永不使用（它只认 API key，会把订阅切到 API 计费）。
+ * - 成本：`result.total_cost_usd` 是 Claude 自己的估算（同一进程内累计，按差值记本回合）。
+ */
+import { randomUUID } from "node:crypto";
+import { AmaError } from "../../errors.js";
+import { createLineReader } from "../../modes/rpc/jsonl.js";
+import { armCancelWatchdog, probeCandidate, spawnOf } from "../base.js";
+import { stderrHint } from "../process.js";
+import { TurnCollector, oneLine } from "../turn.js";
+import { CLAUDE_QUESTION_TOOLS, claudePermissionMode, claudeStopReason, claudeTodos, claudeToolKind, claudeToolLocations, claudeToolTitle, sessionScopedSuggestions, } from "./claude-normalize.js";
+export function claudeArgs(options, sessionId, manualName = "manual") {
+    const args = [
+        "-p",
+        "--input-format",
+        "stream-json",
+        "--output-format",
+        "stream-json",
+        "--verbose",
+        "--include-partial-messages",
+        "--permission-mode",
+        claudePermissionMode(options.mode, manualName),
+    ];
+    if (options.unattended === true)
+        args.push("--permission-prompts", "none");
+    else
+        args.push("--permission-prompt-tool", "stdio");
+    if (options.resume !== undefined)
+        args.push("--resume", options.resume);
+    else
+        args.push("--session-id", sessionId);
+    if (options.model !== undefined)
+        args.push("--model", options.model);
+    if (options.budgetUsd !== undefined)
+        args.push("--max-budget-usd", String(options.budgetUsd));
+    return args;
+}
+function userLine(content) {
+    const blocks = content.map((b) => b.type === "text"
+        ? { type: "text", text: b.text }
+        : { type: "image", source: { type: "base64", media_type: b.mimeType, data: b.data } });
+    return `${JSON.stringify({
+        type: "user",
+        message: { role: "user", content: blocks },
+        parent_tool_use_id: null,
+    })}\n`;
+}
+export class ClaudeStreamDriver {
+    agentId;
+    candidate;
+    deps;
+    kind = "claude-stream";
+    constructor(agentId, candidate, deps = {}) {
+        this.agentId = agentId;
+        this.candidate = candidate;
+        this.deps = deps;
+    }
+    probe() {
+        return probeCandidate(this.candidate, this.deps);
+    }
+    async open(options) {
+        let manual = "manual";
+        const probed = await probeCandidate(this.candidate, this.deps);
+        if (probed.path !== undefined && this.deps.probe !== undefined) {
+            const help = await this.deps.probe.capture(probed.path, ["--help"]);
+            if (help !== undefined && !help.includes('"manual"'))
+                manual = "default";
+        }
+        const sessionId = options.resume ?? randomUUID();
+        const transport = spawnOf(this.deps)({
+            program: probed.path ?? this.candidate.program,
+            args: [...this.candidate.args, ...claudeArgs(options, sessionId, manual)],
+            cwd: options.cwd,
+            env: options.env,
+        });
+        const session = new ClaudeStreamSession(this.agentId, sessionId, transport, this.deps);
+        if (probed.warning !== undefined)
+            session.notices.push(probed.warning);
+        try {
+            await session.initialize(options.signal);
+        }
+        catch (error) {
+            await session.close();
+            throw new AmaError("agent_start_failed", `${this.agentId}：启动失败（${error.message}）${stderrHint(transport) !== "" ? `：${stderrHint(transport)}` : ""}`, { cause: error });
+        }
+        return session;
+    }
+}
+class ClaudeStreamSession {
+    agentId;
+    id;
+    transport;
+    deps;
+    notices = [];
+    nextRequest = 1;
+    controls = new Map();
+    permissions = new Map();
+    turn;
+    hooks;
+    finishTurn;
+    failTurn;
+    running;
+    interrupted = false;
+    sawPartialText = false;
+    lastTotalCost = 0;
+    closed = false;
+    exited = false;
+    constructor(agentId, id, transport, deps) {
+        this.agentId = agentId;
+        this.id = id;
+        this.transport = transport;
+        this.deps = deps;
+        createLineReader(transport.stdout, (line) => this.onLine(line), () => this.onExit());
+        transport.stdin.on?.("error", () => undefined);
+    }
+    get sessionId() {
+        return this.id;
+    }
+    /** SDK 握手；旧版本不认 initialize 时忽略错误继续。 */
+    async initialize(signal) {
+        const response = this.control({ subtype: "initialize", hooks: null });
+        const aborted = new Promise((_, reject) => {
+            if (signal.aborted)
+                reject(new Error("aborted"));
+            signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true });
+        });
+        const timeout = new Promise((resolve) => setTimeout(resolve, 10_000).unref());
+        try {
+            await Promise.race([response, aborted, timeout]);
+        }
+        catch (error) {
+            if (this.exited || signal.aborted)
+                throw error;
+            this.deps.log?.("debug", `${this.agentId}: initialize 未被接受（${error.message}）`);
+        }
+    }
+    async prompt(content, hooks) {
+        if (this.closed || this.exited)
+            throw new AmaError("agent_closed", `${this.agentId} 会话已关闭`);
+        if (this.running !== undefined)
+            throw new AmaError("busy", `${this.agentId} 正在运行`);
+        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.sawPartialText = false;
+        const done = new Promise((resolve, reject) => {
+            this.finishTurn = resolve;
+            this.failTurn = reject;
+        });
+        this.running = done.then((result) => this.complete(result, turn));
+        this.write(userLine(content));
+        try {
+            return await this.running;
+        }
+        finally {
+            this.running = undefined;
+            this.turn = undefined;
+            this.hooks = undefined;
+            this.finishTurn = undefined;
+            this.failTurn = undefined;
+        }
+    }
+    async steer(content) {
+        if (this.closed || this.exited)
+            throw new AmaError("agent_closed", `${this.agentId} 会话已关闭`);
+        this.write(userLine(content));
+    }
+    async cancel() {
+        const running = this.running;
+        if (running === undefined || this.closed)
+            return;
+        this.interrupted = true;
+        for (const controller of this.permissions.values())
+            controller.abort();
+        void this.control({ subtype: "interrupt" }).catch(() => undefined);
+        armCancelWatchdog(this.transport, running.catch(() => undefined), this.deps);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const controller of this.permissions.values())
+            controller.abort();
+        if (this.running !== undefined) {
+            this.interrupted = true;
+            void this.control({ subtype: "interrupt" }).catch(() => undefined);
+        }
+        await this.transport.terminate();
+    }
+    complete(result, turn) {
+        if (typeof result.session_id === "string" && result.session_id !== "")
+            this.id = result.session_id;
+        const u = result.usage ?? {};
+        const total = typeof result.total_cost_usd === "number" ? result.total_cost_usd : undefined;
+        const cost = total === undefined ? undefined : Math.max(0, total - this.lastTotalCost);
+        if (total !== undefined)
+            this.lastTotalCost = total;
+        turn.push({
+            type: "usage",
+            ...(u.input_tokens !== undefined ? { input: u.input_tokens } : {}),
+            ...(u.output_tokens !== undefined ? { output: u.output_tokens } : {}),
+            ...(u.cache_read_input_tokens !== undefined ? { cacheRead: u.cache_read_input_tokens } : {}),
+            ...(cost !== undefined ? { costUsd: cost } : {}),
+        });
+        if (typeof result.result === "string" && result.result !== "")
+            turn.setFinalText(result.result);
+        const denials = result.permission_denials?.length ?? 0;
+        if (denials > 0)
+            turn.push({
+                type: "notice",
+                level: "info",
+                text: `${this.agentId} 有 ${denials} 次操作因无人审批被拒绝`,
+            });
+        if (result.subtype === "error_max_budget_usd")
+            turn.push({
+                type: "notice",
+                level: "warn",
+                text: `${this.agentId} 达到美元预算上限，已停止`,
+            });
+        const stop = claudeStopReason(result, this.interrupted);
+        if (stop === undefined) {
+            const detail = result.errors?.join("; ") ?? result.result ?? result.subtype ?? "unknown";
+            throw new AmaError("agent_failed", `${this.agentId} 回合失败：${oneLine(detail, 300)}`);
+        }
+        return turn.result(stop);
+    }
+    write(line) {
+        if (this.exited)
+            return;
+        this.transport.stdin.write(line);
+    }
+    control(request) {
+        const requestId = `ama-${this.nextRequest++}`;
+        return new Promise((resolve, reject) => {
+            this.controls.set(requestId, { resolve, reject });
+            this.write(`${JSON.stringify({ type: "control_request", request_id: requestId, request })}\n`);
+        });
+    }
+    respond(requestId, response) {
+        this.write(`${JSON.stringify({ type: "control_response", response: { subtype: "success", request_id: requestId, response } })}\n`);
+    }
+    respondError(requestId, error) {
+        this.write(`${JSON.stringify({ type: "control_response", response: { subtype: "error", request_id: requestId, error } })}\n`);
+    }
+    onExit() {
+        this.exited = true;
+        for (const controller of this.permissions.values())
+            controller.abort();
+        const error = new AmaError("agent_exited", `${this.agentId} 进程已退出${stderrHint(this.transport) !== "" ? `：${stderrHint(this.transport)}` : ""}`);
+        for (const pending of this.controls.values())
+            pending.reject(error);
+        this.controls.clear();
+        this.failTurn?.(error);
+    }
+    onLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            this.deps.log?.("debug", `${this.agentId}: 非 JSON 输出`);
+            return;
+        }
+        switch (msg["type"]) {
+            case "control_response":
+                return this.onControlResponse(msg["response"]);
+            case "control_request":
+                void this.onControlRequest(String(msg["request_id"]), (msg["request"] ?? {}));
+                return;
+            case "control_cancel_request":
+                this.permissions.get(String(msg["request_id"]))?.abort();
+                return;
+            case "system":
+                if (msg["subtype"] === "init" && typeof msg["session_id"] === "string")
+                    this.id = msg["session_id"];
+                return;
+            case "stream_event":
+                // 子 Agent（Task）内部的流式文本不进最终文本
+                if (typeof msg["parent_tool_use_id"] === "string")
+                    return;
+                return this.onStreamEvent((msg["event"] ?? {}));
+            case "assistant":
+                return this.onAssistant((msg["message"] ?? {}), msg["parent_tool_use_id"]);
+            case "user":
+                return this.onToolResults((msg["message"] ?? {}));
+            case "result":
+                this.finishTurn?.(msg);
+                return;
+            default:
+                return;
+        }
+    }
+    onControlResponse(response) {
+        if (response === undefined)
+            return;
+        const id = String(response["request_id"]);
+        const pending = this.controls.get(id);
+        if (pending === undefined)
+            return;
+        this.controls.delete(id);
+        if (response["subtype"] === "error")
+            pending.reject(new Error(String(response["error"] ?? "error")));
+        else
+            pending.resolve((response["response"] ?? {}));
+    }
+    onStreamEvent(event) {
+        if (event["type"] !== "content_block_delta" || this.turn === undefined)
+            return;
+        const delta = (event["delta"] ?? {});
+        if (delta["type"] === "text_delta" && typeof delta["text"] === "string") {
+            this.sawPartialText = true;
+            this.turn.push({ type: "message_delta", text: delta["text"] });
+        }
+        else if (delta["type"] === "thinking_delta" && typeof delta["thinking"] === "string") {
+            this.turn.push({ type: "thought_delta", text: delta["thinking"] });
+        }
+    }
+    onAssistant(message, parent) {
+        const turn = this.turn;
+        if (turn === undefined || !Array.isArray(message["content"]))
+            return;
+        // 子 Agent（Task）内部的消息不进最终文本
+        const nested = typeof parent === "string" && parent !== "";
+        for (const block of message["content"]) {
+            if (block["type"] === "text" &&
+                !nested &&
+                !this.sawPartialText &&
+                typeof block["text"] === "string")
+                turn.push({ type: "message_delta", text: block["text"] });
+            else if (block["type"] === "tool_use") {
+                const name = String(block["name"] ?? "tool");
+                const input = block["input"];
+                const locations = claudeToolLocations(input);
+                turn.push({
+                    type: "tool_call",
+                    id: String(block["id"]),
+                    title: claudeToolTitle(name, input),
+                    kind: claudeToolKind(name),
+                    status: "pending",
+                    ...(locations !== undefined ? { locations } : {}),
+                });
+                const todos = name === "TodoWrite" ? claudeTodos(input) : undefined;
+                if (todos !== undefined)
+                    turn.push({ type: "plan", entries: todos });
+            }
+        }
+        // 下一条助手消息的流式文本重新计
+        if (!nested)
+            this.sawPartialText = false;
+    }
+    onToolResults(message) {
+        const turn = this.turn;
+        if (turn === undefined || !Array.isArray(message["content"]))
+            return;
+        for (const block of message["content"]) {
+            if (block["type"] !== "tool_result")
+                continue;
+            const id = String(block["tool_use_id"]);
+            const known = turn.tool(id);
+            if (known === undefined)
+                continue;
+            turn.push({
+                type: "tool_call",
+                id,
+                title: known.title,
+                kind: known.kind,
+                status: block["is_error"] === true ? "failed" : "completed",
+                ...(known.locations.length > 0 ? { locations: [...known.locations] } : {}),
+            });
+        }
+    }
+    async onControlRequest(requestId, request) {
+        if (request["subtype"] !== "can_use_tool") {
+            this.respondError(requestId, `ama does not handle ${String(request["subtype"])}`);
+            return;
+        }
+        const name = String(request["tool_name"] ?? "tool");
+        const input = request["input"] ?? {};
+        const hooks = this.hooks;
+        if (CLAUDE_QUESTION_TOOLS.has(name)) {
+            this.turn?.push({
+                type: "notice",
+                level: "warn",
+                text: `${this.agentId} 想向你提问（${name}）；ama 不代答，已请它把问题写进最终回复`,
+            });
+            this.respond(requestId, {
+                behavior: "deny",
+                message: "The coordinator cannot relay interactive questions. Put your questions in your final reply and stop.",
+            });
+            return;
+        }
+        if (hooks === undefined || this.interrupted) {
+            this.respond(requestId, { behavior: "deny", message: "Cancelled", interrupt: true });
+            return;
+        }
+        const suggestions = sessionScopedSuggestions(request["permission_suggestions"]);
+        const controller = new AbortController();
+        this.permissions.set(requestId, controller);
+        const locations = claudeToolLocations(input);
+        try {
+            const outcome = await hooks.onPermission({
+                toolCall: {
+                    title: claudeToolTitle(name, input),
+                    kind: claudeToolKind(name),
+                    ...(locations !== undefined ? { locations } : {}),
+                    inputSummary: oneLine(JSON.stringify(input), 300),
+                },
+                options: [
+                    { optionId: "allow", kind: "allow_once" },
+                    ...(suggestions.length > 0
+                        ? [{ optionId: "allow_session", kind: "allow_always" }]
+                        : []),
+                    { optionId: "deny", kind: "reject_once" },
+                ],
+            }, controller.signal);
+            // Claude 自己取消了这个请求：不再回应
+            if (controller.signal.aborted && !this.interrupted && !this.closed)
+                return;
+            if (outcome.outcome === "cancelled" || controller.signal.aborted) {
+                this.respond(requestId, {
+                    behavior: "deny",
+                    message: "Cancelled by the user",
+                    interrupt: true,
+                });
+            }
+            else if (outcome.optionId === "allow" || outcome.optionId === "allow_session") {
+                this.respond(requestId, {
+                    behavior: "allow",
+                    updatedInput: input,
+                    ...(outcome.optionId === "allow_session" ? { updatedPermissions: suggestions } : {}),
+                });
+            }
+            else {
+                this.respond(requestId, { behavior: "deny", message: "The user denied this action" });
+            }
+        }
+        finally {
+            this.permissions.delete(requestId);
+        }
+    }
+}

package/dist/drivers/native/codex-app-server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Codex 原生驱动：`codex app-server`（stdio JSON-RPC，docs/wave5-plan.md §5.1，R2 §1.3）。[W5-E]
+ *
+ * - `initialize{clientInfo}` → `initialized` 通知 → `thread/start`（或 `thread/resume`，带
+ *   `excludeTurns` 不回放）→ 每回合 `turn/start`，以对应 turn 的 `turn/completed` 结束；
+ *   运行中追加用 `turn/steer{expectedTurnId}`；中断 `turn/interrupt`（15 s 看门狗）。
+ * - 审批（服务端请求，只交给人）：`item/commandExecution/requestApproval`、
+ *   `item/fileChange/requestApproval` → accept / acceptForSession / decline（回合取消 → cancel；
+ *   execpolicy 与网络策略修订会改持久配置，不提供）；`item/permissions/requestApproval` →
+ *   按人的选择授予本回合 / 本会话或不授予；`item/tool/requestUserInput` 与
+ *   `mcpServer/elicitation/request` 不代答（错误 / cancel，并发提示）。
+ * - 用量：`thread/tokenUsage/updated` 的 `total` 差值记本回合（订阅 token，不换算美元）。
+ * - 每个会话一个子进程，不连共享 daemon（隔离清楚）。
+ */
+import { type DriverDeps } from "../base.js";
+import type { CatalogCandidate } from "../catalog.js";
+import type { AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
+export declare class CodexAppServerDriver implements AgentDriver {
+    readonly agentId: string;
+    private readonly candidate;
+    private readonly deps;
+    readonly kind: "codex-app-server";
+    constructor(agentId: string, candidate: CatalogCandidate, deps?: DriverDeps);
+    probe(): Promise<DriverProbe>;
+    open(options: DriverOpenOptions): Promise<DriverSession>;
+}