@armadra/agent 0.4.0 → 0.5.0

package/dist/modes/acp/acp-events.js

@@ -0,0 +1,233 @@
+/**
+ * `ama --mode acp`：ama 的会话事件 → ACP `session/update`（docs/wave5-plan.md §5.6）。[W5-E]
+ *
+ * | ama                                  | ACP                                                        |
+ * | ------------------------------------ | ---------------------------------------------------------- |
+ * | message_update text_delta            | agent_message_chunk                                        |
+ * | message_update thinking_delta        | agent_thought_chunk                                        |
+ * | message_update toolcall_end          | tool_call（pending，带 rawInput 与 locations）             |
+ * | tool_execution_start / end           | tool_call_update（in_progress → completed / failed）       |
+ * | todo_updated                         | plan                                                       |
+ * | turn_end                             | usage_update（上下文用量、窗口、会话累计美元）             |
+ * | permission_mode_changed              | current_mode_update                                        |
+ *
+ * 工具结果只回前 4 KB 文本（完整结果在 ama 会话里），codemode 内层调用（带 parentToolCallId）
+ * 不单列。`session/load` 回放同一套映射（用户消息 → user_message_chunk）。
+ */
+import { isAbsolute, resolve } from "node:path";
+import { PERMISSION_MODES_STRICT_FIRST } from "../../permissions/types.js";
+import { oneLine } from "../../drivers/turn.js";
+export const TOOL_OUTPUT_LIMIT = 4 * 1024;
+const KINDS = {
+    read: "read",
+    write: "edit",
+    edit: "edit",
+    bash: "execute",
+    grep: "search",
+    glob: "search",
+    ls: "search",
+    find: "search",
+    web_fetch: "fetch",
+    web_search: "fetch",
+    todo: "think",
+};
+export function toolKind(name) {
+    return KINDS[name] ?? "other";
+}
+function argOf(args, ...keys) {
+    if (args === null || typeof args !== "object")
+        return undefined;
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === "string" && value !== "")
+            return value;
+    }
+    return undefined;
+}
+export function toolTitle(name, args) {
+    const detail = argOf(args, "command") ??
+        argOf(args, "path", "file_path", "filePath") ??
+        argOf(args, "pattern", "query", "url", "prompt");
+    return detail === undefined ? name : `${name}: ${oneLine(detail, 100)}`;
+}
+export function toolLocations(args, cwd) {
+    const path = argOf(args, "path", "file_path", "filePath");
+    if (path === undefined)
+        return undefined;
+    return [{ path: isAbsolute(path) ? path : resolve(cwd, path) }];
+}
+function resultText(result) {
+    const text = typeof result.content === "string"
+        ? result.content
+        : result.content.map((b) => (b.type === "text" ? b.text : `[${b.type}]`)).join("");
+    return text.length > TOOL_OUTPUT_LIMIT
+        ? `${text.slice(0, TOOL_OUTPUT_LIMIT)}\n…（已截断，共 ${text.length} 字符）`
+        : text;
+}
+export function permissionModes(currentModeId) {
+    return {
+        currentModeId,
+        availableModes: PERMISSION_MODES_STRICT_FIRST.map((id) => ({ id, name: id })),
+    };
+}
+/** 一个会话的事件映射器（记住模型发出的工具调用，供权限请求关联 toolCallId）。 */
+export class AcpEventMapper {
+    cwd;
+    emit;
+    session;
+    /** 模型已发出、尚未执行完的工具调用。 */
+    pendingCalls = [];
+    constructor(cwd, emit, session) {
+        this.cwd = cwd;
+        this.emit = emit;
+        this.session = session;
+    }
+    /** 权限请求对应的工具调用 id（按工具名与参数匹配最近一个）。 */
+    toolCallIdFor(toolName, input) {
+        const args = JSON.stringify(input ?? null);
+        for (let i = this.pendingCalls.length - 1; i >= 0; i--) {
+            const call = this.pendingCalls[i];
+            if (call.name === toolName && call.args === args)
+                return call.id;
+        }
+        return undefined;
+    }
+    onEvent(event) {
+        switch (event.type) {
+            case "message_update": {
+                const e = event.assistantMessageEvent;
+                if (e.type === "text_delta")
+                    this.emit({
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: e.delta },
+                    });
+                else if (e.type === "thinking_delta")
+                    this.emit({
+                        sessionUpdate: "agent_thought_chunk",
+                        content: { type: "text", text: e.delta },
+                    });
+                else if (e.type === "toolcall_end") {
+                    const call = e.toolCall;
+                    this.pendingCalls.push({
+                        id: call.id,
+                        name: call.name,
+                        args: JSON.stringify(call.arguments),
+                    });
+                    this.emitToolCall(call.id, call.name, call.arguments, "pending");
+                }
+                return;
+            }
+            case "tool_execution_start":
+                if (event.parentToolCallId !== undefined)
+                    return;
+                this.emit({
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: event.toolCallId,
+                    status: "in_progress",
+                });
+                return;
+            case "tool_execution_end": {
+                if (event.parentToolCallId !== undefined)
+                    return;
+                const at = this.pendingCalls.findIndex((c) => c.id === event.toolCallId);
+                if (at >= 0)
+                    this.pendingCalls.splice(at, 1);
+                this.emit({
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: event.toolCallId,
+                    status: event.isError ? "failed" : "completed",
+                    content: [{ type: "content", content: { type: "text", text: resultText(event.result) } }],
+                });
+                return;
+            }
+            case "todo_updated":
+                this.emit({
+                    sessionUpdate: "plan",
+                    entries: event.items.map((item) => ({
+                        content: item.text,
+                        priority: "medium",
+                        status: item.status === "done" ? "completed" : item.status,
+                    })),
+                });
+                return;
+            case "turn_end":
+                this.emitUsage();
+                return;
+            case "permission_mode_changed":
+                this.emit({ sessionUpdate: "current_mode_update", currentModeId: event.mode });
+                return;
+            default:
+                return;
+        }
+    }
+    emitUsage() {
+        const stats = this.session().getStats();
+        if (stats.contextWindow === undefined)
+            return;
+        this.emit({
+            sessionUpdate: "usage_update",
+            used: stats.contextTokens ?? 0,
+            size: stats.contextWindow,
+            ...(stats.cost !== undefined ? { cost: { amount: stats.cost, currency: "USD" } } : {}),
+        });
+    }
+    /** `session/load`：按消息回放历史。 */
+    replay(messages) {
+        for (const message of messages) {
+            if (!("role" in message))
+                continue;
+            if (message.role === "user") {
+                for (const block of contentOf(message.content))
+                    this.emit({ sessionUpdate: "user_message_chunk", content: block });
+            }
+            else if (message.role === "assistant") {
+                for (const block of message.content) {
+                    if (block.type === "text")
+                        this.emit({
+                            sessionUpdate: "agent_message_chunk",
+                            content: { type: "text", text: block.text },
+                        });
+                    else if (block.type === "thinking" && block.redacted !== true)
+                        this.emit({
+                            sessionUpdate: "agent_thought_chunk",
+                            content: { type: "text", text: block.thinking },
+                        });
+                    else if (block.type === "toolCall")
+                        this.emitToolCall(block.id, block.name, block.arguments, "pending");
+                }
+            }
+            else if (message.role === "toolResult") {
+                this.emit({
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: message.toolCallId,
+                    status: message.isError ? "failed" : "completed",
+                });
+            }
+        }
+    }
+    emitToolCall(id, name, args, status) {
+        const locations = toolLocations(args, this.cwd);
+        this.emit({
+            sessionUpdate: "tool_call",
+            toolCallId: id,
+            title: toolTitle(name, args),
+            kind: toolKind(name),
+            status,
+            rawInput: args,
+            ...(locations !== undefined ? { locations } : {}),
+        });
+    }
+}
+function contentOf(content) {
+    if (typeof content === "string")
+        return content === "" ? [] : [{ type: "text", text: content }];
+    const out = [];
+    for (const block of content) {
+        if (block.type === "text")
+            out.push({ type: "text", text: block.text });
+        else if (block.type === "image") {
+            out.push({ type: "image", data: block.data, mimeType: block.mimeType });
+        }
+    }
+    return out;
+}

package/dist/modes/acp/acp-mode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `ama --mode acp` 的进程入口（docs/wave5-plan.md §5.6）。[W5-E]
+ *
+ * - stdin / stdout 是 ACP（JSON-RPC 2.0 over NDJSON），不发 hello（ACP 由客户端 `initialize` 起头）；
+ *   诊断与宿主通知写 stderr。
+ * - 审批：挂 {@link AcpServer.broker} 为 UI broker，ama 的审批请求以 `session/request_permission`
+ *   交给客户端。
+ * - 退出语义同 rpc：stdin 关闭 → 撤下审批、等在途请求与已开始的运行结束 → 退出 0；
+ *   SIGINT / SIGTERM → abort 后退出 130 / 143。
+ */
+import type { ModeContext } from "../../cli/deps.js";
+import type { Runtime } from "../../cli/runtime.js";
+export interface AcpModeOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+}
+export declare function runAcpMode(runtime: Runtime, context: ModeContext, options?: AcpModeOptions): Promise<number>;

package/dist/modes/acp/acp-mode.js

@@ -0,0 +1,47 @@
+/**
+ * `ama --mode acp` 的进程入口（docs/wave5-plan.md §5.6）。[W5-E]
+ *
+ * - stdin / stdout 是 ACP（JSON-RPC 2.0 over NDJSON），不发 hello（ACP 由客户端 `initialize` 起头）；
+ *   诊断与宿主通知写 stderr。
+ * - 审批：挂 {@link AcpServer.broker} 为 UI broker，ama 的审批请求以 `session/request_permission`
+ *   交给客户端。
+ * - 退出语义同 rpc：stdin 关闭 → 撤下审批、等在途请求与已开始的运行结束 → 退出 0；
+ *   SIGINT / SIGTERM → abort 后退出 130 / 143。
+ */
+import { ExitCode } from "../../cli/exit-codes.js";
+import { onTerminationSignals } from "../shared.js";
+import { AcpServer } from "./acp-server.js";
+export async function runAcpMode(runtime, context, options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const server = new AcpServer(runtime, { input: stdin, output: stdout }, (message) => context.io.stderr(`ama: ${message}\n`));
+    runtime.approvals.setUiBroker(server.broker);
+    runtime.notifier.set((message, level) => context.io.stderr(`ama: [${level}] ${message}\n`));
+    return new Promise((resolve) => {
+        let finished = false;
+        const finish = async (code, abort) => {
+            if (finished)
+                return;
+            finished = true;
+            offSignals();
+            stdin.pause?.();
+            runtime.approvals.setUiBroker(undefined);
+            const session = server.session();
+            if (abort)
+                await session.abort().catch(() => undefined);
+            await session.waitForIdle().catch(() => undefined);
+            await server.peer.flush();
+            server.peer.close();
+            server.dispose();
+            runtime.notifier.set(undefined);
+            resolve(code);
+        };
+        void server.peer.closed.then(() => finish(ExitCode.Ok, false));
+        const offSignals = onTerminationSignals((code) => {
+            if (finished)
+                void server.session().abort();
+            else
+                void finish(code, true);
+        });
+    });
+}

package/dist/modes/acp/acp-server.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `ama --mode acp`：把 ama 的会话暴露为 ACP Agent（docs/wave5-plan.md §5.6，D14）。[W5-E]
+ *
+ * 与 `--mode rpc` 同一引擎（Runtime + 组装根的会话切换），一次只有一个活动会话：
+ * - `session/new` 新开（启动时那个空会话第一次直接认领）；`session/load` 切到该会话并回放历史；
+ *   `session/resume` 切换不回放；`session/list` 列本 cwd 的会话；`session/close` 中断并释放；
+ *   对非活动会话发 `session/prompt` 时（空闲）先切过去。
+ * - `session/prompt` → `prompt`（文本 + 图片；资源链接以 `@uri` 文本给出，嵌入资源取文本）；
+ *   回合结束按会话状态给 stopReason：中断 → cancelled，输出截断 → max_tokens，出错 → JSON-RPC 错误。
+ * - `session/cancel` → `abort`；`session/set_mode` → `setPermissionMode`（模式 id = ama 权限模式）。
+ * - 审批：ama 的审批请求经 `session/request_permission` 交给客户端（允许 / 本会话允许 / 拒绝）；
+ *   客户端回 cancelled、连接断开或回合被中断 → 交给链上下一个回答者（无人 → 拒绝）。
+ * - 不声明 / 不使用客户端的 `fs`、`terminal` 能力（Armadra Q5）；ama 自己读写、自己跑命令。
+ * - cwd 固定为启动目录（信任与项目配置都按它判定）；客户端给别的 cwd → invalid params。
+ */
+import type { ImageBlock } from "../../ai/types.js";
+import type { AgentSession } from "../../agent/types.js";
+import type { Runtime } from "../../cli/runtime.js";
+import { JsonRpcPeer } from "../../drivers/jsonrpc.js";
+import type { ApprovalBroker } from "../../permissions/types.js";
+export declare const ACP_AGENT_CAPABILITIES: {
+    loadSession: boolean;
+    promptCapabilities: {
+        image: boolean;
+        audio: boolean;
+        embeddedContext: boolean;
+    };
+    mcpCapabilities: {
+        http: boolean;
+        sse: boolean;
+    };
+    sessionCapabilities: {
+        list: {};
+        resume: {};
+        close: {};
+    };
+};
+/** ACP 提示 → ama 的文本与图片。 */
+export declare function promptOf(blocks: unknown): {
+    text: string;
+    images: ImageBlock[];
+};
+export declare class AcpServer {
+    private readonly runtime;
+    private readonly log;
+    readonly peer: JsonRpcPeer;
+    private activeId;
+    /** 启动时的空会话还没被 session/new 认领。 */
+    private freshUnclaimed;
+    private mapper;
+    private unsubscribe;
+    private cancelRequested;
+    private readonly cwd;
+    constructor(runtime: Runtime, streams: {
+        input: NodeJS.ReadableStream;
+        output: NodeJS.WritableStream;
+    }, log?: (message: string) => void);
+    session(): AgentSession;
+    /** 审批交给客户端：ama 的 UI broker。 */
+    readonly broker: ApprovalBroker;
+    private makeMapper;
+    private emit;
+    private subscribe;
+    dispose(): void;
+    private handle;
+    private initialize;
+    private checkCwd;
+    private modes;
+    private switchTo;
+    private newSession;
+    private openSession;
+    private list;
+    private close;
+    private ensureIdle;
+    private prompt;
+    private cancel;
+    private setMode;
+    private askClient;
+}