@armadra/agent 0.4.0 → 0.5.1

package/dist/drivers/acp/testing/fake-agent.js

@@ -0,0 +1,211 @@
+/**
+ * 黄金记录用的假 ACP Agent（docs/wave5-plan.md §5.1、§5.7）。[W5-E]
+ *
+ * 零依赖、不联网、不碰文件系统；行为由提示文本里的标记决定，供 ama 自己的测试与 Armadra 复用
+ * （`@armadra/agent/acp` 导出 {@link runFakeAcpAgent} 与可执行入口路径）：
+ *
+ * | 提示里含         | 行为                                                                              |
+ * | ---------------- | --------------------------------------------------------------------------------- |
+ * | （无标记）       | `agent_message_chunk` 回 `echo: <文本>`，`usage_update`，`end_turn`               |
+ * | `[permission]`   | `tool_call`(edit, pending) → `session/request_permission`（四个选项）→ 按结果     |
+ * |                  | `tool_call_update` completed / failed；客户端回 cancelled 时本回合 `cancelled`    |
+ * | `[slow]`         | 一直等，直到 `session/cancel` → `cancelled`                                       |
+ * | `[plan]`         | 先发 `plan`（两条）再回文本                                                      |
+ * | `[think]`        | 先发 `agent_thought_chunk`                                                        |
+ * | `[refuse]`       | `refusal`                                                                         |
+ *
+ * 会话：`session/new` 发 `fake-<n>`；`session/resume` / `session/load` 接受任何 `fake-` 开头的 id
+ * （load 先回放一条用户消息与一条回复）；`session/list` 列本进程建过的会话。
+ */
+import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS } from "../types.js";
+import { JsonRpcPeer, RpcError } from "../../jsonrpc.js";
+const MODES = [
+    { id: "default", name: "Default" },
+    { id: "plan", name: "Plan" },
+];
+function textOf(blocks) {
+    return blocks.map((b) => (b.type === "text" ? b.text : `[${b.type}]`)).join("");
+}
+function waitAbort(signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        signal.addEventListener("abort", () => resolve(), { once: true });
+    });
+}
+/** 在给定流上跑假 Agent；输入流结束时 resolve。 */
+export function runFakeAcpAgent(input, output, options = {}) {
+    const sessions = new Map();
+    let counter = 0;
+    const update = (sessionId, value) => peer.notify(ACP_METHODS.sessionUpdate, { sessionId, update: value });
+    const session = (id) => {
+        const found = typeof id === "string" ? sessions.get(id) : undefined;
+        if (found === undefined)
+            throw new RpcError(RPC_ERRORS.resourceNotFound, `unknown session: ${String(id)}`);
+        return found;
+    };
+    const open = (id, cwd) => {
+        const created = { id, cwd, mode: "default", turns: 0 };
+        sessions.set(id, created);
+        return created;
+    };
+    const prompt = async (params) => {
+        const s = session(params.sessionId);
+        const turn = new AbortController();
+        s.turn = turn;
+        s.turns += 1;
+        const text = textOf(params.prompt);
+        const usage = { inputTokens: 10 * s.turns, outputTokens: 5, totalTokens: 10 * s.turns + 5 };
+        const done = (stopReason) => {
+            s.turn = undefined;
+            return { stopReason, usage };
+        };
+        if (text.includes("[think]"))
+            await update(s.id, {
+                sessionUpdate: "agent_thought_chunk",
+                content: { type: "text", text: "thinking…" },
+            });
+        if (text.includes("[plan]"))
+            await update(s.id, {
+                sessionUpdate: "plan",
+                entries: [
+                    { content: "read", priority: "high", status: "completed" },
+                    { content: "write", priority: "medium", status: "pending" },
+                ],
+            });
+        if (text.includes("[refuse]"))
+            return done("refusal");
+        if (text.includes("[slow]")) {
+            await waitAbort(turn.signal);
+            return done("cancelled");
+        }
+        if (text.includes("[permission]")) {
+            const toolCallId = `call-${s.turns}`;
+            await update(s.id, {
+                sessionUpdate: "tool_call",
+                toolCallId,
+                title: "Write note.txt",
+                kind: "edit",
+                status: "pending",
+                locations: [{ path: `${s.cwd}/note.txt` }],
+                rawInput: { path: "note.txt", content: "hi" },
+            });
+            let answer;
+            try {
+                answer = await peer.request(ACP_METHODS.requestPermission, {
+                    sessionId: s.id,
+                    toolCall: { toolCallId, title: "Write note.txt", kind: "edit", status: "pending" },
+                    options: [
+                        { optionId: "allow", name: "Allow", kind: "allow_once" },
+                        { optionId: "always", name: "Always allow", kind: "allow_always" },
+                        { optionId: "reject", name: "Reject", kind: "reject_once" },
+                        { optionId: "never", name: "Never", kind: "reject_always" },
+                    ],
+                });
+            }
+            catch {
+                return done("cancelled");
+            }
+            if (answer.outcome.outcome === "cancelled" || turn.signal.aborted) {
+                await update(s.id, { sessionUpdate: "tool_call_update", toolCallId, status: "failed" });
+                return done("cancelled");
+            }
+            const allowed = answer.outcome.optionId === "allow" || answer.outcome.optionId === "always";
+            await update(s.id, {
+                sessionUpdate: "tool_call_update",
+                toolCallId,
+                status: allowed ? "completed" : "failed",
+            });
+            await update(s.id, {
+                sessionUpdate: "agent_message_chunk",
+                content: { type: "text", text: allowed ? "wrote note.txt" : "write rejected" },
+            });
+            await update(s.id, { sessionUpdate: "usage_update", used: usage.totalTokens, size: 1000 });
+            return done("end_turn");
+        }
+        await update(s.id, {
+            sessionUpdate: "agent_message_chunk",
+            content: { type: "text", text: `echo: ${text}` },
+        });
+        await update(s.id, {
+            sessionUpdate: "usage_update",
+            used: usage.totalTokens,
+            size: 1000,
+            cost: { amount: 0.001 * s.turns, currency: "USD" },
+        });
+        return done("end_turn");
+    };
+    const peer = new JsonRpcPeer({
+        input,
+        output,
+        async onRequest(method, raw) {
+            const params = (raw ?? {});
+            switch (method) {
+                case ACP_METHODS.initialize:
+                    return {
+                        protocolVersion: ACP_PROTOCOL_VERSION,
+                        agentCapabilities: options.minimal
+                            ? { promptCapabilities: { image: false } }
+                            : {
+                                loadSession: true,
+                                promptCapabilities: { image: false, embeddedContext: false },
+                                sessionCapabilities: { list: {}, resume: {}, close: {} },
+                            },
+                        authMethods: [],
+                        agentInfo: { name: options.name ?? "fake-acp-agent", version: "1.0.0" },
+                    };
+                case ACP_METHODS.sessionNew: {
+                    counter += 1;
+                    const s = open(`fake-${counter}`, String(params["cwd"] ?? ""));
+                    if (options.minimal)
+                        return { sessionId: s.id };
+                    return { sessionId: s.id, modes: { currentModeId: s.mode, availableModes: MODES } };
+                }
+                case ACP_METHODS.sessionResume:
+                case ACP_METHODS.sessionLoad: {
+                    const id = String(params["sessionId"] ?? "");
+                    if (options.minimal || !id.startsWith("fake-"))
+                        throw new RpcError(RPC_ERRORS.resourceNotFound, `unknown session: ${id}`);
+                    const s = sessions.get(id) ?? open(id, String(params["cwd"] ?? ""));
+                    if (method === ACP_METHODS.sessionLoad) {
+                        await update(id, {
+                            sessionUpdate: "user_message_chunk",
+                            content: { type: "text", text: "earlier" },
+                        });
+                        await update(id, {
+                            sessionUpdate: "agent_message_chunk",
+                            content: { type: "text", text: "echo: earlier" },
+                        });
+                    }
+                    return { modes: { currentModeId: s.mode, availableModes: MODES } };
+                }
+                case ACP_METHODS.sessionList:
+                    return {
+                        sessions: [...sessions.values()].map((s) => ({ sessionId: s.id, cwd: s.cwd })),
+                    };
+                case ACP_METHODS.sessionClose:
+                    session(params["sessionId"]).turn?.abort();
+                    sessions.delete(String(params["sessionId"]));
+                    return {};
+                case ACP_METHODS.sessionSetMode: {
+                    const s = session(params["sessionId"]);
+                    s.mode = String(params["modeId"]);
+                    await update(s.id, { sessionUpdate: "current_mode_update", currentModeId: s.mode });
+                    return {};
+                }
+                case ACP_METHODS.sessionPrompt:
+                    return prompt(raw);
+                default:
+                    throw new RpcError(RPC_ERRORS.methodNotFound, `method not found: ${method}`);
+            }
+        },
+        onNotification(method, raw) {
+            if (method !== ACP_METHODS.sessionCancel)
+                return;
+            const id = raw?.sessionId;
+            if (typeof id === "string")
+                sessions.get(id)?.turn?.abort();
+        },
+    });
+    return peer.closed;
+}

package/dist/drivers/acp/types.d.ts

@@ -0,0 +1,285 @@
+/**
+ * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ *
+ * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
+ * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（camelCase），
+ * 未知字段一律保留不报错；`_meta` 不解释。
+ *
+ * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
+ * 用它自己的权限策略；它要问人的才经 `session/request_permission` 回到 ama。
+ */
+import type { AcpToolKind } from "../types.js";
+export declare const ACP_PROTOCOL_VERSION: 1;
+/** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
+export declare const ACP_METHODS: {
+    readonly initialize: "initialize";
+    readonly sessionNew: "session/new";
+    readonly sessionLoad: "session/load";
+    readonly sessionResume: "session/resume";
+    readonly sessionList: "session/list";
+    readonly sessionClose: "session/close";
+    readonly sessionPrompt: "session/prompt";
+    readonly sessionCancel: "session/cancel";
+    readonly sessionSetMode: "session/set_mode";
+    readonly sessionUpdate: "session/update";
+    readonly requestPermission: "session/request_permission";
+};
+/** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
+export declare const RPC_ERRORS: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+    readonly authRequired: -32000;
+    readonly resourceNotFound: -32002;
+};
+export interface AcpTextContent {
+    type: "text";
+    text: string;
+}
+export interface AcpImageContent {
+    type: "image";
+    /** base64。 */
+    data: string;
+    mimeType: string;
+    uri?: string;
+}
+export interface AcpResourceLink {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    mimeType?: string;
+    title?: string;
+    description?: string;
+    size?: number;
+}
+export interface AcpEmbeddedResource {
+    type: "resource";
+    resource: {
+        uri: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    };
+}
+export type AcpContentBlock = AcpTextContent | AcpImageContent | AcpResourceLink | AcpEmbeddedResource;
+export interface AcpImplementationInfo {
+    name: string;
+    title?: string;
+    version: string;
+}
+export interface AcpClientCapabilities {
+    fs?: {
+        readTextFile?: boolean;
+        writeTextFile?: boolean;
+    };
+    terminal?: boolean;
+}
+export interface AcpInitializeParams {
+    protocolVersion: number;
+    clientCapabilities: AcpClientCapabilities;
+    clientInfo?: AcpImplementationInfo;
+}
+export interface AcpAgentCapabilities {
+    loadSession?: boolean;
+    promptCapabilities?: {
+        image?: boolean;
+        audio?: boolean;
+        embeddedContext?: boolean;
+    };
+    mcpCapabilities?: {
+        http?: boolean;
+        sse?: boolean;
+    };
+    /** 2026 年稳定进 v1 的会话能力（存在即支持）。 */
+    sessionCapabilities?: {
+        list?: Record<string, unknown> | null;
+        resume?: Record<string, unknown> | null;
+        close?: Record<string, unknown> | null;
+    };
+}
+export interface AcpAuthMethod {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+export interface AcpInitializeResult {
+    protocolVersion: number;
+    agentCapabilities?: AcpAgentCapabilities;
+    authMethods?: AcpAuthMethod[];
+    agentInfo?: AcpImplementationInfo;
+}
+/** ama 不向外部 Agent 传 MCP 服务器（Skills 不做 MCP），总是空数组。 */
+export type AcpMcpServer = Record<string, unknown>;
+export interface AcpSessionMode {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+export interface AcpSessionModeState {
+    currentModeId: string;
+    availableModes: AcpSessionMode[];
+}
+export interface AcpNewSessionParams {
+    cwd: string;
+    mcpServers: AcpMcpServer[];
+}
+export interface AcpNewSessionResult {
+    sessionId: string;
+    modes?: AcpSessionModeState | null;
+}
+export interface AcpLoadSessionParams {
+    sessionId: string;
+    cwd: string;
+    mcpServers: AcpMcpServer[];
+}
+export interface AcpLoadSessionResult {
+    modes?: AcpSessionModeState | null;
+}
+export type AcpResumeSessionParams = AcpLoadSessionParams;
+export type AcpResumeSessionResult = AcpLoadSessionResult;
+export interface AcpListSessionsParams {
+    cwd?: string;
+    cursor?: string;
+}
+export interface AcpSessionInfo {
+    sessionId: string;
+    cwd: string;
+    title?: string | null;
+    updatedAt?: string | null;
+}
+export interface AcpListSessionsResult {
+    sessions: AcpSessionInfo[];
+    nextCursor?: string | null;
+}
+export interface AcpCloseSessionParams {
+    sessionId: string;
+}
+export interface AcpSetModeParams {
+    sessionId: string;
+    modeId: string;
+}
+export type AcpStopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled";
+export interface AcpPromptParams {
+    sessionId: string;
+    prompt: AcpContentBlock[];
+}
+/** 本回合用量（可选字段，按 2026-06 稳定的 usage 提案）。 */
+export interface AcpPromptUsage {
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    thoughtTokens?: number;
+    cachedReadTokens?: number;
+    cachedWriteTokens?: number;
+}
+export interface AcpPromptResult {
+    stopReason: AcpStopReason;
+    usage?: AcpPromptUsage | null;
+}
+export interface AcpCancelParams {
+    sessionId: string;
+}
+export type { AcpToolKind };
+export type AcpToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+export interface AcpToolCallLocation {
+    path: string;
+    line?: number | null;
+}
+export type AcpToolCallContent = {
+    type: "content";
+    content: AcpContentBlock;
+} | {
+    type: "diff";
+    path: string;
+    oldText?: string | null;
+    newText: string;
+} | {
+    type: "terminal";
+    terminalId: string;
+};
+export interface AcpToolCall {
+    toolCallId: string;
+    title: string;
+    kind?: AcpToolKind;
+    status?: AcpToolCallStatus;
+    content?: AcpToolCallContent[];
+    locations?: AcpToolCallLocation[];
+    rawInput?: unknown;
+    rawOutput?: unknown;
+}
+/** `tool_call_update` 与权限请求里的 toolCall：除 id 外都可缺。 */
+export type AcpToolCallUpdate = Partial<AcpToolCall> & {
+    toolCallId: string;
+};
+export interface AcpPlanEntry {
+    content: string;
+    priority: "high" | "medium" | "low";
+    status: "pending" | "in_progress" | "completed";
+}
+export type AcpSessionUpdate = {
+    sessionUpdate: "user_message_chunk";
+    content: AcpContentBlock;
+} | {
+    sessionUpdate: "agent_message_chunk";
+    content: AcpContentBlock;
+} | {
+    sessionUpdate: "agent_thought_chunk";
+    content: AcpContentBlock;
+} | ({
+    sessionUpdate: "tool_call";
+} & AcpToolCall) | ({
+    sessionUpdate: "tool_call_update";
+} & AcpToolCallUpdate) | {
+    sessionUpdate: "plan";
+    entries: AcpPlanEntry[];
+} | {
+    sessionUpdate: "current_mode_update";
+    currentModeId: string;
+} | {
+    sessionUpdate: "usage_update";
+    /** 当前上下文已用 token。 */
+    used: number;
+    /** 上下文窗口。 */
+    size: number;
+    cost?: {
+        amount: number;
+        currency: string;
+    } | null;
+} | {
+    sessionUpdate: "available_commands_update";
+    availableCommands: {
+        name: string;
+        description: string;
+    }[];
+} | {
+    sessionUpdate: "session_info_update";
+    title?: string | null;
+    updatedAt?: string | null;
+};
+export interface AcpSessionNotification {
+    sessionId: string;
+    update: AcpSessionUpdate;
+}
+export type AcpPermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+export interface AcpPermissionOption {
+    optionId: string;
+    name: string;
+    kind: AcpPermissionOptionKind;
+}
+export interface AcpRequestPermissionParams {
+    sessionId: string;
+    toolCall: AcpToolCallUpdate;
+    options: AcpPermissionOption[];
+}
+export type AcpPermissionOutcome = {
+    outcome: "cancelled";
+} | {
+    outcome: "selected";
+    optionId: string;
+};
+export interface AcpRequestPermissionResult {
+    outcome: AcpPermissionOutcome;
+}

package/dist/drivers/acp/types.js

@@ -0,0 +1,36 @@
+/**
+ * ACP（Agent Client Protocol）v1 的子集类型（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ *
+ * 手写、零依赖；只收 ama 作为客户端（驱动外部 Agent）与服务端（`ama --mode acp`）两侧用到的部分：
+ * `initialize`、`session/new|load|resume|list|close`、`session/prompt|cancel|set_mode`、
+ * `session/update`（含 `usage_update`）、`session/request_permission`。字段名与规范一致（camelCase），
+ * 未知字段一律保留不报错；`_meta` 不解释。
+ *
+ * 不声明 `fs` / `terminal` 客户端能力（与 Armadra Q5 一致）：外部 Agent 自己读写、自己跑命令，
+ * 用它自己的权限策略；它要问人的才经 `session/request_permission` 回到 ama。
+ */
+export const ACP_PROTOCOL_VERSION = 1;
+/** 方法名（客户端 → Agent 的请求 / 通知，Agent → 客户端的请求 / 通知）。 */
+export const ACP_METHODS = {
+    initialize: "initialize",
+    sessionNew: "session/new",
+    sessionLoad: "session/load",
+    sessionResume: "session/resume",
+    sessionList: "session/list",
+    sessionClose: "session/close",
+    sessionPrompt: "session/prompt",
+    sessionCancel: "session/cancel",
+    sessionSetMode: "session/set_mode",
+    sessionUpdate: "session/update",
+    requestPermission: "session/request_permission",
+};
+/** JSON-RPC 错误码（规范沿用 JSON-RPC 2.0；`-32000` 为 ACP 的 auth_required）。 */
+export const RPC_ERRORS = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+    authRequired: -32000,
+    resourceNotFound: -32002,
+};

package/dist/drivers/agents.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 外部 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 type { AgentInfo } from "../agents/types.js";
+import type { AgentsConfig } from "../config/types-w5.js";
+import type { PermissionMode } from "../permissions/types.js";
+import type { SubagentRunner } from "../tools/types.js";
+import type { DriverDeps } from "./base.js";
+import { type CatalogCandidate } from "./catalog.js";
+import { HostRunnerRegistry } from "./host-runners.js";
+import type { ApproveFn } from "./permissions.js";
+import { type DriverPool } from "./pool.js";
+import type { AgentStore } from "./store.js";
+import type { AgentDriver } from "./types.js";
+/** 按候选种类建驱动。 */
+export declare function createDriver(agentId: string, candidate: CatalogCandidate, deps: DriverDeps): AgentDriver;
+export { HostRunnerRegistry };
+export interface ExternalAgentsOptions {
+    config?: AgentsConfig;
+    /** 原始环境（子进程环境由 runner 按 D16 清理）。 */
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    /** 探测缓存与 pid 登记的位置；不给则只做内存缓存、不登记。 */
+    dataDir?: string;
+    /** 有宿主（profile.host）：只认宿主注入的 runner。 */
+    hosted: boolean;
+    /** 宿主注入的 runner（宿主适配器一份，跨会话共享）；不给则本实例自建一份。 */
+    hostRunners?: HostRunnerRegistry;
+    /** 审批只交给人：接到会话的 requestApproval。 */
+    approve: ApproveFn;
+    store?: AgentStore;
+    parentMode?(): PermissionMode;
+    unattended?: boolean | (() => boolean);
+    trusted(cwd: string): boolean;
+    /** 测试 / 宿主注入（spawn、probe）。 */
+    driverDeps?: DriverDeps;
+    log?(level: "debug" | "info" | "warn", message: string): void;
+}
+export declare class ExternalAgents {
+    private readonly options;
+    readonly hostRunners: HostRunnerRegistry;
+    readonly pool: DriverPool;
+    private readonly runners;
+    private readonly driverDeps;
+    constructor(options: ExternalAgentsOptions);
+    /** `task(agent=<spec>)` 的 runner；不可用时抛 AmaError（`agent_host_only` / `agent_unknown`）。 */
+    resolve(spec: string): SubagentRunner;
+    /** `/agents` 与 RPC `get_agents` 的外部 Agent 部分（探测 PATH 与版本，不联网）。 */
+    list(): Promise<AgentInfo[]>;
+}