@armadra/agent 0.4.0 → 0.5.1

package/dist/drivers/native/codex-app-server.js

@@ -0,0 +1,407 @@
+/**
+ * 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 { AmaError } from "../../errors.js";
+import { AMA_VERSION } from "../../version.js";
+import { armCancelWatchdog, probeCandidate, spawnOf } from "../base.js";
+import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
+import { stderrHint } from "../process.js";
+import { TurnCollector, oneLine } from "../turn.js";
+import { codexDecision, codexPlan, codexPolicy, codexToolEvent, grantedProfile, readTokens, } from "./codex-normalize.js";
+const DECISION_OPTIONS = [
+    { optionId: "accept", kind: "allow_once" },
+    { optionId: "acceptForSession", kind: "allow_always" },
+    { optionId: "decline", kind: "reject_once" },
+];
+function textInput(content) {
+    return content.flatMap((b) => b.type === "text" ? [{ type: "text", text: b.text, text_elements: [] }] : []);
+}
+export class CodexAppServerDriver {
+    agentId;
+    candidate;
+    deps;
+    kind = "codex-app-server";
+    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 transport = spawnOf(this.deps)({
+            program: probed.path ?? this.candidate.program,
+            args: this.candidate.args,
+            cwd: options.cwd,
+            env: options.env,
+        });
+        const session = new CodexSession(this.agentId, transport, this.deps);
+        if (probed.warning !== undefined)
+            session.notices.push(probed.warning);
+        try {
+            await session.start(options);
+        }
+        catch (error) {
+            await session.close();
+            if (error instanceof AmaError)
+                throw error;
+            throw new AmaError("agent_start_failed", `${this.agentId}：app-server 启动失败（${error.message}）${stderrHint(transport) !== "" ? `：${stderrHint(transport)}` : ""}`, { cause: error });
+        }
+        return session;
+    }
+}
+class CodexSession {
+    agentId;
+    transport;
+    deps;
+    notices = [];
+    peer;
+    threadId = "";
+    turnId;
+    turn;
+    hooks;
+    finishTurn;
+    running;
+    permissions = new Set();
+    /** fileChange 条目的路径（审批请求只带 itemId）。 */
+    itemPaths = new Map();
+    messages = new Map();
+    tokensTotal;
+    tokensAtStart;
+    contextWindow;
+    closed = false;
+    interruptRequested = false;
+    constructor(agentId, transport, deps) {
+        this.agentId = agentId;
+        this.transport = transport;
+        this.deps = deps;
+        this.peer = new JsonRpcPeer({
+            input: transport.stdout,
+            output: transport.stdin,
+            jsonrpcField: false,
+            onRequest: (method, params) => this.onServerRequest(method, (params ?? {})),
+            onNotification: (method, params) => this.onNotification(method, (params ?? {})),
+            onClose: () => {
+                for (const c of this.permissions)
+                    c.abort();
+            },
+        });
+    }
+    get sessionId() {
+        return this.threadId;
+    }
+    async start(options) {
+        const signal = options.signal;
+        await this.peer.request("initialize", {
+            clientInfo: { name: "ama", title: "ama", version: AMA_VERSION },
+            capabilities: { experimentalApi: false, requestAttestation: false },
+        }, signal);
+        await this.peer.notify("initialized");
+        const policy = codexPolicy(options.mode, options.unattended === true);
+        const common = {
+            cwd: options.cwd,
+            ...policy,
+            ...(options.model !== undefined ? { model: options.model } : {}),
+        };
+        if (options.resume !== undefined) {
+            try {
+                const resumed = await this.peer.request("thread/resume", { threadId: options.resume, excludeTurns: true, ...common }, signal);
+                this.threadId = resumed.thread?.id ?? options.resume;
+                return;
+            }
+            catch (error) {
+                if (signal.aborted || !(error instanceof RpcError))
+                    throw error;
+                this.notices.push(`${this.agentId} 找不到会话 ${options.resume}，已新开`);
+            }
+        }
+        const started = await this.peer.request("thread/start", common, signal);
+        const id = started.thread?.id;
+        if (typeof id !== "string" || id === "")
+            throw new Error("thread/start 没有返回 thread.id");
+        this.threadId = id;
+    }
+    async prompt(content, hooks) {
+        if (this.closed || !this.peer.isOpen)
+            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: "info", text });
+        if (content.some((b) => b.type === "image"))
+            turn.push({ type: "notice", level: "warn", text: `${this.agentId} 驱动暂不传图片，已省略` });
+        this.turn = turn;
+        this.hooks = hooks;
+        this.messages.clear();
+        this.tokensAtStart = this.tokensTotal;
+        this.interruptRequested = false;
+        const completed = new Promise((resolve) => (this.finishTurn = resolve));
+        const closed = this.peer.closed.then(() => {
+            throw new AmaError("agent_exited", `${this.agentId} 进程已退出${stderrHint(this.transport) !== "" ? `：${stderrHint(this.transport)}` : ""}`);
+        });
+        void closed.catch(() => undefined);
+        this.running = (async () => {
+            const response = await Promise.race([
+                this.peer.request("turn/start", {
+                    threadId: this.threadId,
+                    input: textInput(content),
+                }),
+                closed,
+            ]);
+            if (typeof response.turn?.id === "string")
+                this.setTurnId(response.turn.id);
+            const done = await Promise.race([completed, closed]);
+            return this.complete(done, turn);
+        })();
+        try {
+            return await this.running;
+        }
+        finally {
+            this.running = undefined;
+            this.turn = undefined;
+            this.hooks = undefined;
+            this.turnId = undefined;
+            this.finishTurn = undefined;
+        }
+    }
+    async steer(content) {
+        if (this.turnId === undefined)
+            throw new AmaError("not_running", `${this.agentId} 没有进行中的回合`);
+        await this.peer.request("turn/steer", {
+            threadId: this.threadId,
+            input: textInput(content),
+            expectedTurnId: this.turnId,
+        });
+    }
+    async cancel() {
+        const running = this.running;
+        if (running === undefined || this.closed)
+            return;
+        for (const c of this.permissions)
+            c.abort();
+        this.interruptRequested = true;
+        if (this.turnId !== undefined)
+            this.sendInterrupt(this.turnId);
+        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();
+        this.peer.close();
+        await this.transport.terminate();
+    }
+    /** turn id 可能先从通知 / 服务端请求里知道（早于 turn/start 的响应被处理）。 */
+    setTurnId(id) {
+        if (this.running === undefined || this.turnId !== undefined)
+            return;
+        this.turnId = id;
+        if (this.interruptRequested)
+            this.sendInterrupt(id);
+    }
+    sendInterrupt(turnId) {
+        void this.peer
+            .request("turn/interrupt", { threadId: this.threadId, turnId })
+            .catch(() => undefined);
+    }
+    complete(turnInfo, turn) {
+        const start = this.tokensAtStart;
+        const end = this.tokensTotal;
+        if (end !== undefined) {
+            turn.push({
+                type: "usage",
+                input: end.inputTokens - (start?.inputTokens ?? 0),
+                output: end.outputTokens - (start?.outputTokens ?? 0),
+                cacheRead: end.cachedInputTokens - (start?.cachedInputTokens ?? 0),
+                ...(this.contextWindow !== undefined ? { contextWindow: this.contextWindow } : {}),
+            });
+        }
+        const last = [...this.messages.values()].at(-1);
+        if (last !== undefined)
+            turn.setFinalText(last);
+        const status = turnInfo["status"];
+        if (status === "interrupted")
+            return turn.result("cancelled");
+        if (status === "failed") {
+            const error = (turnInfo["error"] ?? {});
+            throw new AmaError("agent_failed", `${this.agentId} 回合失败：${oneLine(String(error["message"] ?? "unknown"), 300)}`);
+        }
+        return turn.result("end_turn");
+    }
+    onNotification(method, params) {
+        const turn = this.turn;
+        switch (method) {
+            case "thread/tokenUsage/updated": {
+                const usage = (params["tokenUsage"] ?? {});
+                const total = readTokens(usage["total"]);
+                if (total !== undefined)
+                    this.tokensTotal = total;
+                if (typeof usage["modelContextWindow"] === "number")
+                    this.contextWindow = usage["modelContextWindow"];
+                return;
+            }
+            case "turn/started": {
+                const id = (params["turn"] ?? {})["id"];
+                if (typeof id === "string")
+                    this.setTurnId(id);
+                return;
+            }
+            case "turn/completed": {
+                const info = (params["turn"] ?? {});
+                if (this.turnId === undefined || info["id"] === this.turnId)
+                    this.finishTurn?.(info);
+                return;
+            }
+            default:
+                break;
+        }
+        if (turn === undefined)
+            return;
+        switch (method) {
+            case "item/agentMessage/delta": {
+                const delta = String(params["delta"] ?? "");
+                const id = String(params["itemId"] ?? "");
+                this.messages.set(id, (this.messages.get(id) ?? "") + delta);
+                turn.push({ type: "message_delta", text: delta });
+                return;
+            }
+            case "item/reasoning/summaryTextDelta":
+            case "item/reasoning/textDelta":
+                turn.push({ type: "thought_delta", text: String(params["delta"] ?? "") });
+                return;
+            case "item/started":
+            case "item/completed": {
+                const item = (params["item"] ?? {});
+                if (item["type"] === "agentMessage" && method === "item/completed") {
+                    this.messages.set(String(item["id"]), String(item["text"] ?? ""));
+                    return;
+                }
+                const event = codexToolEvent(item, method === "item/started" ? "started" : "completed");
+                if (event === undefined)
+                    return;
+                if (event.locations !== undefined)
+                    this.itemPaths.set(event.id, event.locations);
+                turn.push(event);
+                return;
+            }
+            case "turn/plan/updated": {
+                const plan = codexPlan(params);
+                if (plan !== undefined)
+                    turn.push(plan);
+                return;
+            }
+            case "error": {
+                const error = (params["error"] ?? {});
+                turn.push({
+                    type: "notice",
+                    level: "warn",
+                    text: `${this.agentId}：${oneLine(String(error["message"] ?? "error"), 200)}${params["willRetry"] === true ? "（重试中）" : ""}`,
+                });
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    async ask(request) {
+        const hooks = this.hooks;
+        if (hooks === undefined || this.closed)
+            return undefined;
+        const controller = new AbortController();
+        this.permissions.add(controller);
+        try {
+            const outcome = await hooks.onPermission(request, controller.signal);
+            return outcome.outcome === "selected" && !controller.signal.aborted
+                ? outcome.optionId
+                : undefined;
+        }
+        finally {
+            this.permissions.delete(controller);
+        }
+    }
+    async onServerRequest(method, params) {
+        if (typeof params["turnId"] === "string")
+            this.setTurnId(params["turnId"]);
+        switch (method) {
+            case "item/commandExecution/requestApproval": {
+                const command = String(params["command"] ?? "");
+                const reason = typeof params["reason"] === "string" ? ` — ${params["reason"]}` : "";
+                const cwd = typeof params["cwd"] === "string" ? [params["cwd"]] : undefined;
+                const answer = await this.ask({
+                    toolCall: {
+                        title: `$ ${oneLine(command, 100)}`,
+                        kind: "execute",
+                        ...(cwd !== undefined ? { locations: cwd } : {}),
+                        inputSummary: oneLine(`${command}${reason}`, 300),
+                    },
+                    options: DECISION_OPTIONS,
+                });
+                return { decision: codexDecision(answer) };
+            }
+            case "item/fileChange/requestApproval": {
+                const paths = this.itemPaths.get(String(params["itemId"] ?? "")) ?? [];
+                const reason = typeof params["reason"] === "string" ? params["reason"] : "";
+                const answer = await this.ask({
+                    toolCall: {
+                        title: paths.length > 0 ? `edit ${paths.join(", ")}` : "edit files",
+                        kind: "edit",
+                        ...(paths.length > 0 ? { locations: paths } : {}),
+                        ...(reason !== "" ? { inputSummary: oneLine(reason, 300) } : {}),
+                    },
+                    options: DECISION_OPTIONS,
+                });
+                return { decision: codexDecision(answer) };
+            }
+            case "item/permissions/requestApproval": {
+                const reason = typeof params["reason"] === "string" ? params["reason"] : "";
+                const answer = await this.ask({
+                    toolCall: {
+                        title: "request additional permissions",
+                        kind: "other",
+                        inputSummary: oneLine(`${JSON.stringify(params["permissions"] ?? {})} ${reason}`, 300),
+                    },
+                    options: [
+                        { optionId: "turn", kind: "allow_once" },
+                        { optionId: "session", kind: "allow_always" },
+                        { optionId: "deny", kind: "reject_once" },
+                    ],
+                });
+                if (answer === "turn" || answer === "session")
+                    return { permissions: grantedProfile(params["permissions"]), scope: answer };
+                return { permissions: {}, scope: "turn" };
+            }
+            case "item/tool/requestUserInput":
+                this.turn?.push({
+                    type: "notice",
+                    level: "warn",
+                    text: `${this.agentId} 想向你提问；ama 不代答，请让它把问题写进最终回复`,
+                });
+                throw new RpcError(-32601, "The coordinator cannot relay interactive questions");
+            case "mcpServer/elicitation/request":
+                this.turn?.push({
+                    type: "notice",
+                    level: "warn",
+                    text: `${this.agentId} 的 MCP 服务器请求输入；ama 不代答，已取消`,
+                });
+                return { action: "cancel", content: null, _meta: null };
+            default:
+                throw new RpcError(-32601, `ama does not handle ${method}`);
+        }
+    }
+}

package/dist/drivers/native/codex-normalize.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Codex app-server（0.160.x，`[experimental]`）↔ ama 的映射（docs/wave5-plan.md §5.1 normalize，
+ * R2 §1.3）。[W5-E]
+ *
+ * 只依赖 `test/fixtures/drivers/codex-schema/shapes.json` 锁住的方法与字段（12 个方法 + 5 类审批
+ * 请求）；线上不写 `"jsonrpc"` 字段。
+ */
+import type { PermissionMode } from "../../permissions/types.js";
+import type { DriverEvent } from "../types.js";
+export type CodexApprovalPolicy = "untrusted" | "on-request" | "never";
+export type CodexSandbox = "read-only" | "workspace-write" | "danger-full-access";
+/**
+ * ama 模式 → Codex `approvalPolicy` + `sandbox`。从不给 `danger-full-access`；
+ * 无人值守一律 `never`（不发审批请求，越权的操作由沙箱拒绝后交回模型）。
+ */
+export declare function codexPolicy(mode: PermissionMode, unattended: boolean): {
+    approvalPolicy: CodexApprovalPolicy;
+    sandbox: CodexSandbox;
+};
+type Json = Record<string, unknown>;
+/** ThreadItem → tool_call（非工具类条目返回 undefined）。 */
+export declare function codexToolEvent(item: Json, phase: "started" | "completed"): Extract<DriverEvent, {
+    type: "tool_call";
+}> | undefined;
+/** turn/plan/updated → plan。 */
+export declare function codexPlan(params: Json): DriverEvent | undefined;
+export interface CodexTokens {
+    totalTokens: number;
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+}
+export declare function readTokens(value: unknown): CodexTokens | undefined;
+/** 审批决定（ACP 词汇 → Codex）；execpolicy 修订是持久配置变更，不提供。 */
+export declare function codexDecision(optionId: string | undefined): "accept" | "acceptForSession" | "decline" | "cancel";
+/** 去掉 null 字段（`RequestPermissionProfile` → `GrantedPermissionProfile`）。 */
+export declare function grantedProfile(permissions: unknown): Json;
+export {};

package/dist/drivers/native/codex-normalize.js

@@ -0,0 +1,124 @@
+/**
+ * Codex app-server（0.160.x，`[experimental]`）↔ ama 的映射（docs/wave5-plan.md §5.1 normalize，
+ * R2 §1.3）。[W5-E]
+ *
+ * 只依赖 `test/fixtures/drivers/codex-schema/shapes.json` 锁住的方法与字段（12 个方法 + 5 类审批
+ * 请求）；线上不写 `"jsonrpc"` 字段。
+ */
+import { oneLine } from "../turn.js";
+/**
+ * ama 模式 → Codex `approvalPolicy` + `sandbox`。从不给 `danger-full-access`；
+ * 无人值守一律 `never`（不发审批请求，越权的操作由沙箱拒绝后交回模型）。
+ */
+export function codexPolicy(mode, unattended) {
+    const base = (() => {
+        switch (mode) {
+            case "plan":
+            case "allowlist":
+                return { approvalPolicy: "never", sandbox: "read-only" };
+            case "default":
+                // 写文件 / 越过只读沙箱都要先问人（≈ ama default 的「写与执行要问」）
+                return { approvalPolicy: "on-request", sandbox: "read-only" };
+            case "auto-edit":
+                return { approvalPolicy: "untrusted", sandbox: "workspace-write" };
+            case "auto":
+                return { approvalPolicy: "on-request", sandbox: "workspace-write" };
+            case "full-auto":
+                return { approvalPolicy: "never", sandbox: "workspace-write" };
+        }
+    })();
+    return unattended ? { ...base, approvalPolicy: "never" } : base;
+}
+/** ThreadItem → tool_call（非工具类条目返回 undefined）。 */
+export function codexToolEvent(item, phase) {
+    const id = String(item["id"] ?? "");
+    const type = item["type"];
+    let kind;
+    let title;
+    let locations;
+    switch (type) {
+        case "commandExecution":
+            kind = "execute";
+            title = `$ ${oneLine(String(item["command"] ?? ""), 100)}`;
+            break;
+        case "fileChange": {
+            kind = "edit";
+            const changes = Array.isArray(item["changes"]) ? item["changes"] : [];
+            locations = changes.map((c) => String(c["path"] ?? "")).filter((p) => p !== "");
+            title = locations.length > 0 ? `edit ${locations.join(", ")}` : "edit";
+            break;
+        }
+        case "mcpToolCall":
+            kind = "other";
+            title = `${String(item["server"] ?? "mcp")}.${String(item["tool"] ?? "tool")}`;
+            break;
+        case "dynamicToolCall":
+            kind = "other";
+            title = String(item["tool"] ?? "tool");
+            break;
+        case "webSearch":
+            kind = "fetch";
+            title = `search ${oneLine(String(item["query"] ?? ""), 80)}`;
+            break;
+        default:
+            return undefined;
+    }
+    const status = String(item["status"] ?? "");
+    const failed = status === "failed" || status === "declined";
+    return {
+        type: "tool_call",
+        id,
+        title,
+        kind,
+        status: phase === "started" ? "in_progress" : failed ? "failed" : "completed",
+        ...(locations !== undefined && locations.length > 0 ? { locations } : {}),
+    };
+}
+/** turn/plan/updated → plan。 */
+export function codexPlan(params) {
+    const plan = params["plan"];
+    if (!Array.isArray(plan))
+        return undefined;
+    return {
+        type: "plan",
+        entries: plan.map((s) => ({
+            content: String(s["step"] ?? ""),
+            status: String(s["status"] ?? "pending"),
+        })),
+    };
+}
+export function readTokens(value) {
+    if (value === null || typeof value !== "object")
+        return undefined;
+    const v = value;
+    const num = (k) => (typeof v[k] === "number" ? v[k] : 0);
+    return {
+        totalTokens: num("totalTokens"),
+        inputTokens: num("inputTokens"),
+        cachedInputTokens: num("cachedInputTokens"),
+        outputTokens: num("outputTokens"),
+    };
+}
+/** 审批决定（ACP 词汇 → Codex）；execpolicy 修订是持久配置变更，不提供。 */
+export function codexDecision(optionId) {
+    switch (optionId) {
+        case "accept":
+            return "accept";
+        case "acceptForSession":
+            return "acceptForSession";
+        case "decline":
+            return "decline";
+        default:
+            return "cancel";
+    }
+}
+/** 去掉 null 字段（`RequestPermissionProfile` → `GrantedPermissionProfile`）。 */
+export function grantedProfile(permissions) {
+    if (permissions === null || typeof permissions !== "object")
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(permissions))
+        if (v !== null && v !== undefined)
+            out[k] = v;
+    return out;
+}

package/dist/drivers/native/oneshot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 一次性打印模式兜底（docs/wave5-plan.md §5.1 oneshot.ts）。[W5-E]
+ *
+ * `claude -p --output-format json`、`codex exec --json`、`gemini -p --output-format stream-json`：
+ * **不能审批**（能力 `permissions: "none"`），所以只在只读任务下用——open 时模式不是
+ * plan / allowlist 直接拒绝；子进程一律以只读方式启动（Claude `--permission-mode plan
+ * --permission-prompts none`，Codex `sandbox_mode="read-only"` + `approval_policy="never"`，
+ * Gemini `--approval-mode default`，无头时需要批准的工具不可用；未实测）。每回合起一个进程，提示从 stdin 给（Gemini 走 `-p` 参数）；
+ * 续聊用各 CLI 自己的 resume。中断 = 结束进程树。
+ */
+import { type DriverDeps } from "../base.js";
+import type { CatalogCandidate } from "../catalog.js";
+import type { AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
+type Dialect = NonNullable<CatalogCandidate["oneshot"]>;
+export declare function oneshotArgs(dialect: Dialect, options: Pick<DriverOpenOptions, "model" | "budgetUsd">, session: {
+    id: string;
+    resume: boolean;
+}, prompt: string): string[];
+export declare class OneshotDriver implements AgentDriver {
+    readonly agentId: string;
+    private readonly candidate;
+    private readonly deps;
+    readonly kind: "oneshot";
+    constructor(agentId: string, candidate: CatalogCandidate, deps?: DriverDeps);
+    probe(): Promise<DriverProbe>;
+    open(options: DriverOpenOptions): Promise<DriverSession>;
+}
+export {};