@armadra/agent 0.4.0 → 0.5.1

package/dist/drivers/acp/client.js

@@ -0,0 +1,160 @@
+/**
+ * ACP 客户端（docs/wave5-plan.md §5.1，D14）。[W5-E]
+ *
+ * JSON-RPC over NDJSON（{@link JsonRpcPeer}），手写零依赖；`@armadra/agent/acp` 导出供 Armadra 复用。
+ *
+ * - 不声明 `fs` / `terminal` 能力：Agent 发来的 `fs/*`、`terminal/*` 请求一律 method not found。
+ * - `session/request_permission` 交给 `onPermission`（驱动再交给 ama 的审批通道，只交给人）；
+ *   没有处理器时按无人值守回首个 `reject_once`（没有则 cancelled）。
+ * - `cancel(sessionId)` 发 `session/cancel` 通知，并让该会话所有挂起的权限请求回 `cancelled`
+ *   （规范要求：客户端取消回合后必须以 cancelled 回答挂起的请求）。
+ */
+import { JsonRpcPeer, RpcError } from "../jsonrpc.js";
+import { ACP_METHODS, ACP_PROTOCOL_VERSION, RPC_ERRORS, } from "./types.js";
+/** 无人值守的回答：首个 reject_once，没有就 cancelled。 */
+export function unattendedOutcome(params) {
+    const reject = params.options.find((o) => o.kind === "reject_once");
+    return {
+        outcome: reject !== undefined
+            ? { outcome: "selected", optionId: reject.optionId }
+            : { outcome: "cancelled" },
+    };
+}
+export class AcpClient {
+    options;
+    peer;
+    /** sessionId → 挂起权限请求的取消器。 */
+    pendingPermissions = new Map();
+    initResult;
+    constructor(options) {
+        this.options = options;
+        this.peer = new JsonRpcPeer({
+            input: options.input,
+            output: options.output,
+            onRequest: (method, params, ctx) => this.onRequest(method, params, ctx.signal),
+            onNotification: (method, params) => {
+                if (method === ACP_METHODS.sessionUpdate)
+                    options.onUpdate?.(params);
+            },
+            onClose: () => {
+                for (const set of this.pendingPermissions.values())
+                    for (const c of set)
+                        c.abort();
+                options.onClose?.();
+            },
+            ...(options.onProtocolError !== undefined
+                ? { onProtocolError: options.onProtocolError }
+                : {}),
+        });
+    }
+    get closed() {
+        return this.peer.closed;
+    }
+    get isOpen() {
+        return this.peer.isOpen;
+    }
+    get agentCapabilities() {
+        return this.initResult?.agentCapabilities ?? {};
+    }
+    get agentInfo() {
+        return this.initResult?.agentInfo;
+    }
+    async initialize(signal) {
+        const result = await this.peer.request(ACP_METHODS.initialize, {
+            protocolVersion: ACP_PROTOCOL_VERSION,
+            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+            ...(this.options.clientInfo !== undefined ? { clientInfo: this.options.clientInfo } : {}),
+        }, signal);
+        if (result.protocolVersion !== ACP_PROTOCOL_VERSION)
+            throw new RpcError(RPC_ERRORS.invalidRequest, `ACP 协议版本不兼容：Agent ${String(result.protocolVersion)}，客户端 ${ACP_PROTOCOL_VERSION}`);
+        this.initResult = result;
+        return result;
+    }
+    supportsResume() {
+        return this.agentCapabilities.sessionCapabilities?.resume != null;
+    }
+    supportsLoad() {
+        return this.agentCapabilities.loadSession === true;
+    }
+    supportsList() {
+        return this.agentCapabilities.sessionCapabilities?.list != null;
+    }
+    supportsClose() {
+        return this.agentCapabilities.sessionCapabilities?.close != null;
+    }
+    supportsImages() {
+        return this.agentCapabilities.promptCapabilities?.image === true;
+    }
+    newSession(cwd, signal) {
+        return this.peer.request(ACP_METHODS.sessionNew, { cwd, mcpServers: [] }, signal);
+    }
+    /** 不回放历史（优先，R13：v2 计划取消 load）。 */
+    resumeSession(sessionId, cwd, signal) {
+        return this.peer.request(ACP_METHODS.sessionResume, { sessionId, cwd, mcpServers: [] }, signal);
+    }
+    /** 回放历史（以 session/update 通知）。 */
+    loadSession(sessionId, cwd, signal) {
+        return this.peer.request(ACP_METHODS.sessionLoad, { sessionId, cwd, mcpServers: [] }, signal);
+    }
+    listSessions(cwd, cursor) {
+        return this.peer.request(ACP_METHODS.sessionList, {
+            ...(cwd !== undefined ? { cwd } : {}),
+            ...(cursor !== undefined ? { cursor } : {}),
+        });
+    }
+    closeSession(sessionId) {
+        return this.peer.request(ACP_METHODS.sessionClose, { sessionId });
+    }
+    prompt(sessionId, prompt, signal) {
+        return this.peer.request(ACP_METHODS.sessionPrompt, { sessionId, prompt }, signal);
+    }
+    setMode(sessionId, modeId) {
+        return this.peer.request(ACP_METHODS.sessionSetMode, { sessionId, modeId });
+    }
+    /** 协议级取消：发通知，并让挂起的权限请求回 cancelled。 */
+    async cancel(sessionId) {
+        for (const controller of this.pendingPermissions.get(sessionId) ?? [])
+            controller.abort();
+        await this.peer.notify(ACP_METHODS.sessionCancel, { sessionId });
+    }
+    close() {
+        this.peer.close();
+    }
+    async onRequest(method, params, connection) {
+        if (method !== ACP_METHODS.requestPermission)
+            throw new RpcError(RPC_ERRORS.methodNotFound, `client does not support ${method}`);
+        const request = params;
+        if (typeof request?.sessionId !== "string" || !Array.isArray(request.options))
+            throw new RpcError(RPC_ERRORS.invalidParams, "invalid session/request_permission params");
+        const handler = this.options.onPermission;
+        if (handler === undefined)
+            return unattendedOutcome(request);
+        const controller = new AbortController();
+        const set = this.pendingPermissions.get(request.sessionId) ?? new Set();
+        set.add(controller);
+        this.pendingPermissions.set(request.sessionId, set);
+        const signal = AbortSignal.any([controller.signal, connection]);
+        try {
+            const answer = await Promise.race([
+                handler(request, signal),
+                new Promise((resolve) => {
+                    const cancelled = () => resolve({ outcome: { outcome: "cancelled" } });
+                    if (signal.aborted)
+                        cancelled();
+                    else
+                        signal.addEventListener("abort", cancelled, { once: true });
+                }),
+            ]);
+            if (signal.aborted)
+                return { outcome: { outcome: "cancelled" } };
+            // 只认 Agent 自己给的选项
+            if (answer.outcome.outcome === "selected" &&
+                !request.options.some((o) => answer.outcome.outcome === "selected" && o.optionId === answer.outcome.optionId))
+                return { outcome: { outcome: "cancelled" } };
+            return answer;
+        }
+        finally {
+            set.delete(controller);
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * AcpDriver：经 ACP 驱动外部 Agent（docs/wave5-plan.md §5.1–§5.2，D14）。[W5-E]
+ *
+ * open：起进程 → `initialize` → 续聊优先 `session/resume`（不回放），其次 `session/load`
+ * （回放的历史通知在 open 期间丢弃），都不支持则新开并发 notice「已新开」→ 按 ama 模式
+ * `session/set_mode`（只读模式没有映射时拒绝启动，避免以 Agent 缺省模式跑写操作）。
+ * prompt：`session/update` → DriverEvent；`session/request_permission` → hooks.onPermission
+ * （只交给人）；回合以 `session/prompt` 的 stopReason 结束。
+ * cancel：`session/cancel`，挂起的权限请求回 cancelled，15 s 内无回合结束 → 关 stdin → 杀进程树。
+ */
+import type { ContentBlock } from "../../ai/types.js";
+import type { PermissionMode } from "../../permissions/types.js";
+import { type DriverDeps } from "../base.js";
+import type { CatalogCandidate } from "../catalog.js";
+import { TurnCollector } from "../turn.js";
+import type { AgentDriver, DriverOpenOptions, DriverProbe, DriverSession } from "../types.js";
+import type { AcpContentBlock, AcpSessionModeState, AcpSessionUpdate } from "./types.js";
+export declare function toAcpContent(blocks: readonly ContentBlock[], images: boolean): AcpContentBlock[];
+/** session/update → DriverEvent（用户消息回放、命令表等忽略）。 */
+export declare function pushAcpUpdate(update: AcpSessionUpdate, turn: TurnCollector): void;
+/** ama 模式 → 该 Agent 的模式 id（显式映射 > 同名）。 */
+export declare function pickModeId(mode: PermissionMode, candidate: CatalogCandidate, state: AcpSessionModeState | null | undefined): string | undefined;
+export declare class AcpDriver implements AgentDriver {
+    readonly agentId: string;
+    private readonly candidate;
+    private readonly deps;
+    readonly kind: "acp" | "acp-adapter";
+    constructor(agentId: string, candidate: CatalogCandidate, deps?: DriverDeps);
+    probe(): Promise<DriverProbe>;
+    open(options: DriverOpenOptions): Promise<DriverSession>;
+}

package/dist/drivers/acp/driver.js

@@ -0,0 +1,274 @@
+/**
+ * AcpDriver：经 ACP 驱动外部 Agent（docs/wave5-plan.md §5.1–§5.2，D14）。[W5-E]
+ *
+ * open：起进程 → `initialize` → 续聊优先 `session/resume`（不回放），其次 `session/load`
+ * （回放的历史通知在 open 期间丢弃），都不支持则新开并发 notice「已新开」→ 按 ama 模式
+ * `session/set_mode`（只读模式没有映射时拒绝启动，避免以 Agent 缺省模式跑写操作）。
+ * prompt：`session/update` → DriverEvent；`session/request_permission` → hooks.onPermission
+ * （只交给人）；回合以 `session/prompt` 的 stopReason 结束。
+ * cancel：`session/cancel`，挂起的权限请求回 cancelled，15 s 内无回合结束 → 关 stdin → 杀进程树。
+ */
+import { AmaError } from "../../errors.js";
+import { armCancelWatchdog, isReadOnlyMode, probeCandidate, spawnOf, } from "../base.js";
+import { stderrHint } from "../process.js";
+import { TurnCollector, oneLine } from "../turn.js";
+import { AcpClient } from "./client.js";
+import { AMA_VERSION } from "../../version.js";
+export function toAcpContent(blocks, images) {
+    const out = [];
+    for (const block of blocks) {
+        if (block.type === "text")
+            out.push({ type: "text", text: block.text });
+        else if (images)
+            out.push({ type: "image", data: block.data, mimeType: block.mimeType });
+    }
+    return out;
+}
+function locationsOf(locations) {
+    return locations === undefined ? undefined : locations.map((l) => l.path);
+}
+/** session/update → DriverEvent（用户消息回放、命令表等忽略）。 */
+export function pushAcpUpdate(update, turn) {
+    switch (update.sessionUpdate) {
+        case "agent_message_chunk":
+            if (update.content.type === "text")
+                turn.push({ type: "message_delta", text: update.content.text });
+            return;
+        case "agent_thought_chunk":
+            if (update.content.type === "text")
+                turn.push({ type: "thought_delta", text: update.content.text });
+            return;
+        case "tool_call":
+        case "tool_call_update": {
+            const known = turn.tool(update.toolCallId);
+            const locations = locationsOf(update.locations);
+            turn.push({
+                type: "tool_call",
+                id: update.toolCallId,
+                title: oneLine(update.title ?? known?.title ?? ""),
+                kind: update.kind ?? known?.kind ?? "other",
+                status: update.status ?? known?.status ?? "pending",
+                ...(locations !== undefined ? { locations } : {}),
+            });
+            return;
+        }
+        case "plan":
+            turn.push({
+                type: "plan",
+                entries: update.entries.map((e) => ({ content: e.content, status: e.status })),
+            });
+            return;
+        case "usage_update":
+            turn.push({
+                type: "usage",
+                contextTokens: update.used,
+                contextWindow: update.size,
+                ...(update.cost?.currency === "USD" ? { costUsd: update.cost.amount } : {}),
+            });
+            return;
+        default:
+            return;
+    }
+}
+/** ama 模式 → 该 Agent 的模式 id（显式映射 > 同名）。 */
+export function pickModeId(mode, candidate, state) {
+    const wanted = [candidate.modes?.[mode] ?? mode];
+    // allowlist 在外部 Agent 那边没有等价物：退到只读的 plan
+    if (mode === "allowlist")
+        wanted.push(candidate.modes?.plan ?? "plan");
+    return wanted.find((id) => state?.availableModes.some((m) => m.id === id) === true);
+}
+export class AcpDriver {
+    agentId;
+    candidate;
+    deps;
+    kind;
+    constructor(agentId, candidate, deps = {}) {
+        this.agentId = agentId;
+        this.candidate = candidate;
+        this.deps = deps;
+        this.kind = candidate.kind === "acp-adapter" ? "acp-adapter" : "acp";
+    }
+    probe() {
+        return probeCandidate(this.candidate, this.deps);
+    }
+    async open(options) {
+        // 与原生驱动一致：用探测到的完整路径启动。Windows 上 npm 装的 ACP Agent 是 `.cmd` 垫片，
+        // 裸程序名 spawn 会 ENOENT（commandLine 只认带扩展名的路径改走 cmd.exe）。[W5-Z]
+        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 AcpDriverSession(this.agentId, transport, this.deps);
+        try {
+            await session.start(options, this.candidate);
+        }
+        catch (error) {
+            await session.close();
+            if (error instanceof AmaError)
+                throw error;
+            const hint = stderrHint(transport);
+            throw new AmaError("agent_start_failed", `${this.agentId}：ACP 启动失败（${error.message}）${hint !== "" ? `：${hint}` : ""}`, { cause: error });
+        }
+        return session;
+    }
+}
+class AcpDriverSession {
+    agentId;
+    transport;
+    deps;
+    id = "";
+    client;
+    hooks;
+    turn;
+    replaying = false;
+    running;
+    closed = false;
+    notices = [];
+    constructor(agentId, transport, deps) {
+        this.agentId = agentId;
+        this.transport = transport;
+        this.deps = deps;
+    }
+    get sessionId() {
+        return this.id;
+    }
+    async start(options, candidate) {
+        this.client = new AcpClient({
+            input: this.transport.stdout,
+            output: this.transport.stdin,
+            clientInfo: { name: "ama", version: AMA_VERSION },
+            onUpdate: (n) => this.onUpdate(n),
+            onPermission: (p, signal) => this.onPermission(p, signal),
+            onProtocolError: (_line, reason) => this.deps.log?.("debug", `${this.agentId}: ${reason}`),
+        });
+        const signal = options.signal;
+        await this.client.initialize(signal);
+        let modes;
+        if (options.resume !== undefined) {
+            if (this.client.supportsResume()) {
+                modes = (await this.client.resumeSession(options.resume, options.cwd, signal)).modes;
+                this.id = options.resume;
+            }
+            else if (this.client.supportsLoad()) {
+                this.replaying = true;
+                try {
+                    modes = (await this.client.loadSession(options.resume, options.cwd, signal)).modes;
+                }
+                finally {
+                    this.replaying = false;
+                }
+                this.id = options.resume;
+            }
+            else {
+                this.notices.push(`${this.agentId} 不支持续接会话，已新开`);
+            }
+        }
+        if (this.id === "") {
+            const created = await this.client.newSession(options.cwd, signal);
+            this.id = created.sessionId;
+            modes = created.modes;
+        }
+        const modeId = pickModeId(options.mode, candidate, modes);
+        if (modeId !== undefined) {
+            if (modes?.currentModeId !== modeId)
+                await this.client.setMode(this.id, modeId);
+        }
+        else if (isReadOnlyMode(options.mode)) {
+            throw new AmaError("agent_mode_unsupported", `${this.agentId} 没有与 ama「${options.mode}」对应的只读模式，不能以它的缺省模式代替`);
+        }
+        else if (modes != null) {
+            this.notices.push(`${this.agentId} 没有「${options.mode}」模式，按它自己的缺省模式运行（需要授权的操作仍交给你）`);
+        }
+    }
+    async prompt(content, hooks) {
+        if (this.closed)
+            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 });
+        this.hooks = hooks;
+        this.turn = turn;
+        const images = this.client.supportsImages();
+        if (!images && content.some((b) => b.type === "image"))
+            turn.push({ type: "notice", level: "warn", text: `${this.agentId} 不接受图片，已省略` });
+        const request = this.client.prompt(this.id, toAcpContent(content, images));
+        this.running = request;
+        try {
+            const result = await request.catch((error) => {
+                if (this.client.isOpen)
+                    throw error;
+                const hint = stderrHint(this.transport);
+                throw new AmaError("agent_exited", `${this.agentId} 进程已退出${hint !== "" ? `：${hint}` : ""}`, {
+                    cause: error,
+                });
+            });
+            const usage = result.usage;
+            if (usage != null) {
+                turn.mergeUsage({
+                    ...(usage.inputTokens !== undefined ? { input: usage.inputTokens } : {}),
+                    ...(usage.outputTokens !== undefined ? { output: usage.outputTokens } : {}),
+                    ...(usage.cachedReadTokens !== undefined ? { cacheRead: usage.cachedReadTokens } : {}),
+                });
+            }
+            return turn.result(result.stopReason);
+        }
+        finally {
+            this.running = undefined;
+            this.hooks = undefined;
+            this.turn = undefined;
+        }
+    }
+    async cancel() {
+        const running = this.running;
+        if (running === undefined || this.closed)
+            return;
+        await this.client.cancel(this.id).catch(() => undefined);
+        armCancelWatchdog(this.transport, running.catch(() => undefined), this.deps);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.client !== undefined) {
+            if (this.running !== undefined)
+                await this.client.cancel(this.id).catch(() => undefined);
+            if (this.id !== "" && this.client.isOpen && this.client.supportsClose()) {
+                const timer = new Promise((resolve) => setTimeout(resolve, 2_000).unref());
+                await Promise.race([this.client.closeSession(this.id).catch(() => undefined), timer]);
+            }
+            this.client.close();
+        }
+        await this.transport.terminate();
+    }
+    onUpdate(notification) {
+        if (this.replaying || notification.sessionId !== this.id || this.turn === undefined)
+            return;
+        pushAcpUpdate(notification.update, this.turn);
+    }
+    async onPermission(params, signal) {
+        const hooks = this.hooks;
+        if (hooks === undefined || params.sessionId !== this.id)
+            return { outcome: { outcome: "cancelled" } };
+        const call = params.toolCall;
+        const known = this.turn?.tool(call.toolCallId);
+        const locations = locationsOf(call.locations) ?? known?.locations;
+        const outcome = await hooks.onPermission({
+            toolCall: {
+                title: oneLine(call.title ?? known?.title ?? call.toolCallId),
+                kind: call.kind ?? known?.kind ?? "other",
+                ...(locations !== undefined && locations.length > 0 ? { locations: [...locations] } : {}),
+                ...(call.rawInput !== undefined
+                    ? { inputSummary: oneLine(JSON.stringify(call.rawInput), 300) }
+                    : {}),
+            },
+            options: params.options.map((o) => ({ optionId: o.optionId, kind: o.kind })),
+        }, signal);
+        return { outcome };
+    }
+}

package/dist/drivers/acp/testing/fake-agent-main.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal]`。[W5-E]
+ * 行为见 fake-agent.ts；stdin 结束即退出。
+ */
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * 假 ACP Agent 的进程入口：`node dist/drivers/acp/testing/fake-agent-main.js [--minimal]`。[W5-E]
+ * 行为见 fake-agent.ts；stdin 结束即退出。
+ */
+import { runFakeAcpAgent } from "./fake-agent.js";
+const minimal = process.argv.includes("--minimal");
+void runFakeAcpAgent(process.stdin, process.stdout, { minimal }).then(() => process.exit(0));

package/dist/drivers/acp/testing/fake-agent.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 黄金记录用的假 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` 列本进程建过的会话。
+ */
+export interface FakeAcpAgentOptions {
+    /** `initialize` 回的 agentInfo.name，缺省 `fake-acp-agent`。 */
+    name?: string;
+    /** 不声明 resume / list / close / loadSession（测降级路径）。 */
+    minimal?: boolean;
+}
+/** 在给定流上跑假 Agent；输入流结束时 resolve。 */
+export declare function runFakeAcpAgent(input: NodeJS.ReadableStream, output: NodeJS.WritableStream, options?: FakeAcpAgentOptions): Promise<void>;