@armadra/agent 0.4.0 → 0.5.0

package/dist/drivers/jsonrpc.js

@@ -0,0 +1,180 @@
+/**
+ * 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` 失败。
+ */
+import { createLineReader, writeChunked } from "../modes/rpc/jsonl.js";
+import { RPC_ERRORS } from "./acp/types.js";
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = "RpcError";
+    }
+}
+export class JsonRpcPeer {
+    options;
+    pending = new Map();
+    reader;
+    lifetime = new AbortController();
+    nextId = 1;
+    writing = Promise.resolve();
+    isClosed = false;
+    resolveClosed;
+    /** 输入流结束或 `close()` 后 resolve。 */
+    closed = new Promise((resolve) => (this.resolveClosed = resolve));
+    constructor(options) {
+        this.options = options;
+        // 对端先退出时写入会 EPIPE / write after end：交给 closed 处理，不变成未捕获异常
+        options.output.on("error", () => undefined);
+        this.reader = createLineReader(options.input, (line) => this.onLine(line), () => this.shutdown());
+    }
+    get isOpen() {
+        return !this.isClosed;
+    }
+    /** 发请求；`signal` abort 时本端不再等（不通知对端，协议级取消由调用方另发）。 */
+    request(method, params, signal) {
+        if (this.isClosed)
+            return Promise.reject(closedError(method));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.pending.delete(id);
+                reject(new RpcError(RPC_ERRORS.internalError, `${method}: aborted`));
+            };
+            if (signal?.aborted === true)
+                return onAbort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.pending.set(id, {
+                method,
+                resolve: (value) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    signal?.removeEventListener("abort", onAbort);
+                    reject(error);
+                },
+            });
+            void this.send({ id, method, ...(params !== undefined ? { params } : {}) });
+        });
+    }
+    /** 输入流结束后仍可写（对端可能只关了自己的写端，还在读）；写失败静默。 */
+    notify(method, params) {
+        return this.send({ method, ...(params !== undefined ? { params } : {}) });
+    }
+    /** 停止读取并让挂起请求失败；不关闭底层流（由调用方决定）。 */
+    close() {
+        this.reader.close();
+        this.shutdown();
+    }
+    /** 等所有已排队的写入完成。 */
+    flush() {
+        return this.writing;
+    }
+    shutdown() {
+        if (this.isClosed)
+            return;
+        this.isClosed = true;
+        this.lifetime.abort();
+        for (const [id, pending] of [...this.pending]) {
+            this.pending.delete(id);
+            pending.reject(closedError(pending.method));
+        }
+        this.options.onClose?.();
+        this.resolveClosed();
+    }
+    send(message) {
+        const body = this.options.jsonrpcField === false ? message : { jsonrpc: "2.0", ...message };
+        const line = `${JSON.stringify(body)}\n`;
+        const output = this.options.output;
+        this.writing = this.writing
+            .then(() => output.writableEnded === true || output.destroyed === true
+            ? undefined
+            : writeChunked(output, line))
+            .catch(() => undefined);
+        return this.writing;
+    }
+    onLine(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            this.options.onProtocolError?.(line, "invalid JSON");
+            return;
+        }
+        if (typeof message !== "object" || message === null) {
+            this.options.onProtocolError?.(line, "not an object");
+            return;
+        }
+        if (typeof message.method === "string") {
+            if (message.id !== undefined && message.id !== null) {
+                void this.handleRequest(message.id, message.method, message.params);
+            }
+            else {
+                try {
+                    this.options.onNotification?.(message.method, message.params);
+                }
+                catch (error) {
+                    this.options.onProtocolError?.(line, `notification handler: ${String(error)}`);
+                }
+            }
+            return;
+        }
+        if (message.id === undefined || message.id === null) {
+            this.options.onProtocolError?.(line, "response without id");
+            return;
+        }
+        const pending = this.pending.get(message.id);
+        if (pending === undefined)
+            return;
+        this.pending.delete(message.id);
+        if (message.error !== undefined) {
+            const err = message.error;
+            pending.reject(new RpcError(typeof err.code === "number" ? err.code : RPC_ERRORS.internalError, typeof err.message === "string" ? err.message : "error", err.data));
+        }
+        else {
+            pending.resolve(message.result ?? null);
+        }
+    }
+    async handleRequest(id, method, params) {
+        const handler = this.options.onRequest;
+        if (handler === undefined) {
+            await this.send({
+                id,
+                error: { code: RPC_ERRORS.methodNotFound, message: `method not found: ${method}` },
+            });
+            return;
+        }
+        try {
+            const result = await handler(method, params, { id, signal: this.lifetime.signal });
+            await this.send({ id, result: result ?? null });
+        }
+        catch (error) {
+            const rpc = error instanceof RpcError
+                ? error
+                : new RpcError(RPC_ERRORS.internalError, error instanceof Error ? error.message : String(error));
+            await this.send({
+                id,
+                error: {
+                    code: rpc.code,
+                    message: rpc.message,
+                    ...(rpc.data !== undefined ? { data: rpc.data } : {}),
+                },
+            });
+        }
+    }
+}
+function closedError(method) {
+    return new RpcError(RPC_ERRORS.internalError, `${method}: connection closed`, {
+        reason: "connection_closed",
+    });
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Claude Code stream-json → DriverEvent 的映射表（docs/wave5-plan.md §5.1 normalize，R2 §3.2）。[W5-E]
+ *
+ * 线上形状按 Claude Code 2.1.x 的 `--output-format stream-json`（Agent SDK 所用的同一协议；
+ * 官方称其不是公开的 CLI 接口，R3），只读用到的字段，其余忽略。
+ */
+import type { PermissionMode } from "../../permissions/types.js";
+import type { AcpToolKind } from "../types.js";
+export declare function claudeToolKind(name: string): AcpToolKind;
+export declare function claudeToolTitle(name: string, input: unknown): string;
+export declare function claudeToolLocations(input: unknown): string[] | undefined;
+/** TodoWrite 的 todos → plan 条目。 */
+export declare function claudeTodos(input: unknown): {
+    content: string;
+    status: string;
+}[] | undefined;
+/**
+ * ama 模式 → Claude `--permission-mode`。full-auto 不映射成 bypassPermissions：协调者永远不替
+ * 外部 Agent 打开「跳过全部检查」，最宽给到 auto（Claude 自己的分类器 + 需要时问人）。
+ * `manual` 是 2.1.x 新名字，旧版本叫 `default`（探测 `--help` 决定）。
+ */
+export declare function claudePermissionMode(mode: PermissionMode, manualName: "manual" | "default"): string;
+/** 只能由人回答的提问类工具（ama 不代答）。 */
+export declare const CLAUDE_QUESTION_TOOLS: ReadonlySet<string>;
+export interface ClaudeResult {
+    subtype?: string;
+    is_error?: boolean;
+    result?: string;
+    session_id?: string;
+    total_cost_usd?: number;
+    num_turns?: number;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+    };
+    permission_denials?: {
+        tool_name?: string;
+    }[];
+    errors?: string[];
+}
+/** result.subtype → 回合结束原因；`undefined` 表示执行出错（调用方按错误处理）。 */
+export declare function claudeStopReason(result: ClaudeResult, interrupted: boolean): "end_turn" | "max_turn_requests" | "cancelled" | undefined;
+/** 只保留会话范围的权限建议（`localSettings` 等会改用户 / 项目配置文件，不能替人写）。 */
+export declare function sessionScopedSuggestions(suggestions: unknown): unknown[];

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

@@ -0,0 +1,106 @@
+/**
+ * Claude Code stream-json → DriverEvent 的映射表（docs/wave5-plan.md §5.1 normalize，R2 §3.2）。[W5-E]
+ *
+ * 线上形状按 Claude Code 2.1.x 的 `--output-format stream-json`（Agent SDK 所用的同一协议；
+ * 官方称其不是公开的 CLI 接口，R3），只读用到的字段，其余忽略。
+ */
+import { oneLine } from "../turn.js";
+const KINDS = {
+    Read: "read",
+    Write: "edit",
+    Edit: "edit",
+    MultiEdit: "edit",
+    NotebookEdit: "edit",
+    Bash: "execute",
+    BashOutput: "execute",
+    KillShell: "execute",
+    Grep: "search",
+    Glob: "search",
+    LS: "search",
+    WebFetch: "fetch",
+    WebSearch: "fetch",
+    TodoWrite: "think",
+    ExitPlanMode: "switch_mode",
+};
+export function claudeToolKind(name) {
+    return KINDS[name] ?? "other";
+}
+function field(input, ...keys) {
+    if (input === null || typeof input !== "object")
+        return undefined;
+    for (const key of keys) {
+        const v = input[key];
+        if (typeof v === "string" && v !== "")
+            return v;
+    }
+    return undefined;
+}
+export function claudeToolTitle(name, input) {
+    const detail = field(input, "command") ??
+        field(input, "file_path", "notebook_path", "path") ??
+        field(input, "pattern", "url", "query", "description");
+    return detail === undefined ? name : `${name}: ${oneLine(detail, 100)}`;
+}
+export function claudeToolLocations(input) {
+    const path = field(input, "file_path", "notebook_path", "path");
+    return path === undefined ? undefined : [path];
+}
+/** TodoWrite 的 todos → plan 条目。 */
+export function claudeTodos(input) {
+    const todos = input?.todos;
+    if (!Array.isArray(todos))
+        return undefined;
+    return todos.flatMap((t) => t !== null && typeof t === "object" && typeof t.content === "string"
+        ? [
+            {
+                content: t.content,
+                status: String(t.status ?? "pending"),
+            },
+        ]
+        : []);
+}
+/**
+ * ama 模式 → Claude `--permission-mode`。full-auto 不映射成 bypassPermissions：协调者永远不替
+ * 外部 Agent 打开「跳过全部检查」，最宽给到 auto（Claude 自己的分类器 + 需要时问人）。
+ * `manual` 是 2.1.x 新名字，旧版本叫 `default`（探测 `--help` 决定）。
+ */
+export function claudePermissionMode(mode, manualName) {
+    switch (mode) {
+        // allowlist 也按 plan：Claude 的 dontAsk 会放行它自己配置里的 allow 规则（可能含写操作）
+        case "plan":
+        case "allowlist":
+            return "plan";
+        case "default":
+            return manualName;
+        case "auto-edit":
+            return "acceptEdits";
+        case "auto":
+        case "full-auto":
+            return "auto";
+    }
+}
+/** 只能由人回答的提问类工具（ama 不代答）。 */
+export const CLAUDE_QUESTION_TOOLS = new Set(["AskUserQuestion"]);
+/** result.subtype → 回合结束原因；`undefined` 表示执行出错（调用方按错误处理）。 */
+export function claudeStopReason(result, interrupted) {
+    if (interrupted)
+        return "cancelled";
+    switch (result.subtype) {
+        case "success":
+            return result.is_error === true ? undefined : "end_turn";
+        case "error_max_turns":
+            return "max_turn_requests";
+        case "error_max_budget_usd":
+            return "cancelled";
+        default:
+            return undefined;
+    }
+}
+/** 只保留会话范围的权限建议（`localSettings` 等会改用户 / 项目配置文件，不能替人写）。 */
+export function sessionScopedSuggestions(suggestions) {
+    if (!Array.isArray(suggestions))
+        return [];
+    return suggestions.filter((s) => s !== null &&
+        typeof s === "object" &&
+        s.destination === "session");
+}

package/dist/drivers/native/claude-stream.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { type DriverDeps } from "../base.js";
+import type { CatalogCandidate } from "../catalog.js";
+import type { AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
+export declare function claudeArgs(options: Pick<DriverOpenOptions, "mode" | "model" | "resume" | "budgetUsd" | "unattended">, sessionId: string, manualName?: "manual" | "default"): string[];
+export declare class ClaudeStreamDriver implements AgentDriver {
+    readonly agentId: string;
+    private readonly candidate;
+    private readonly deps;
+    readonly kind: "claude-stream";
+    constructor(agentId: string, candidate: CatalogCandidate, deps?: DriverDeps);
+    probe(): Promise<DriverProbe>;
+    open(options: DriverOpenOptions): Promise<DriverSession>;
+}