@armadra/agent 0.0.0-stage → 0.2.1

package/dist/modes/interactive/tool-view.js

@@ -0,0 +1,344 @@
+/**
+ * 工具调用显示（设计 §12.5）。[B7]
+ *
+ * - 一行标题 `● bash  git status`：圆点运行中为强调色，成功绿、失败红；摘要取最能代表这次调用的参数
+ *   （bash 命令、文件路径、搜索模式、task 描述……），路径相对会话 cwd。
+ * - 折叠（缺省）：结果前 3 行 + 剩余行数；`edit` 显示 `details.diff`（+/− 着色，前 12 行）；
+ *   `bash` 运行中流式显示尾部 8 行；错误红色。`Ctrl+O` 展开全部（上限 400 行）。
+ * - 嵌套：带 `parentToolCallId` 的调用（codemode 脚本里的 `tools.*`，B10）挂在外层调用下；折叠时只列
+ *   内层调用的标题（最近 5 个），展开时完整显示。
+ * - 工具输出先去掉 ANSI 与控制字符、Tab 换成空格，避免打乱布局。
+ * - 自定义渲染（W3-B9a-2，`ToolDefinition.renderCall / renderResult`）：`getTool` 能取到定义时，标题摘要
+ *   优先取 `renderCall(input, width)` 的第一行（codemode 显示脚本首行）；成功的结果优先用
+ *   `renderResult(result, width, expanded)`（去控制字符、按宽截断、上限 400 行）；自定义渲染抛错或返回
+ *   空时回到缺省显示；错误结果始终用缺省的红色显示。
+ */
+import { isAbsolute, relative } from "node:path";
+import { stripAnsi, truncateToWidth, wrapTextWithAnsi, } from "../../tui.js";
+import { contentText } from "./message-view.js";
+export const COLLAPSED_RESULT_LINES = 3;
+export const COLLAPSED_DIFF_LINES = 12;
+export const BASH_TAIL_LINES = 8;
+export const EXPANDED_MAX_LINES = 400;
+export const COLLAPSED_CHILDREN = 5;
+/** 工具输出 → 可安全显示的行。 */
+export function cleanLines(text) {
+    const clean = stripAnsi(text)
+        .replace(/\r\n?/g, "\n")
+        .replace(/\t/g, "    ")
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
+    const lines = clean.split("\n");
+    while (lines.length > 0 && lines[lines.length - 1].trim() === "")
+        lines.pop();
+    return lines;
+}
+function flat(text, max = 120) {
+    const one = text.replace(/\s*\n\s*/g, " ⏎ ").trim();
+    return one.length > max ? `${one.slice(0, max - 1)}…` : one;
+}
+function displayPath(path, cwd) {
+    if (cwd === undefined || !isAbsolute(path))
+        return path;
+    const rel = relative(cwd, path);
+    return rel === "" ? "." : rel.startsWith("..") || isAbsolute(rel) ? path : rel;
+}
+/** 标题行里的参数摘要。 */
+export function toolSummary(name, args, cwd) {
+    if (typeof args !== "object" || args === null)
+        return "";
+    const a = args;
+    const str = (key) => typeof a[key] === "string" && a[key] !== "" ? a[key] : undefined;
+    const path = str("path") ?? str("file_path");
+    switch (name) {
+        case "bash":
+            return flat(str("command") ?? "");
+        case "read": {
+            if (path === undefined)
+                return "";
+            const offset = typeof a["offset"] === "number" ? a["offset"] : undefined;
+            const limit = typeof a["limit"] === "number" ? a["limit"] : undefined;
+            const range = offset !== undefined || limit !== undefined
+                ? `:${offset ?? 1}${limit !== undefined ? `+${limit}` : ""}`
+                : "";
+            return displayPath(path, cwd) + range;
+        }
+        case "grep":
+        case "glob": {
+            const pattern = str("pattern") ?? "";
+            return path !== undefined ? `${flat(pattern)}  in ${displayPath(path, cwd)}` : flat(pattern);
+        }
+        case "task":
+            return flat(str("description") ?? str("prompt") ?? "");
+        default:
+            if (path !== undefined)
+                return displayPath(path, cwd);
+            for (const key of [
+                "command",
+                "pattern",
+                "description",
+                "query",
+                "url",
+                "name",
+                "code",
+                "script",
+            ]) {
+                const value = str(key);
+                if (value !== undefined)
+                    return flat(value);
+            }
+            return "";
+    }
+}
+function diffOf(result) {
+    const details = result?.details;
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const diff = details.diff;
+    return typeof diff === "string" && diff !== "" ? diff : undefined;
+}
+export class ToolView {
+    toolCallId;
+    toolName;
+    args;
+    options;
+    state = "running";
+    partial = "";
+    result;
+    expanded = false;
+    nested = [];
+    cache = null;
+    version = 0;
+    /** 外层调用（嵌套时）：子视图变化要让外层缓存失效。 */
+    parent;
+    constructor(toolCallId, toolName, args, options) {
+        this.toolCallId = toolCallId;
+        this.toolName = toolName;
+        this.args = args;
+        this.options = options;
+    }
+    get isRunning() {
+        return this.state === "running";
+    }
+    get isExpanded() {
+        return this.expanded;
+    }
+    get children() {
+        return this.nested;
+    }
+    setExpanded(expanded) {
+        if (this.expanded === expanded)
+            return;
+        this.expanded = expanded;
+        for (const child of this.nested)
+            child.setExpanded(expanded);
+        this.touch();
+    }
+    /** 运行中的输出（滚动尾部，整体替换）。 */
+    update(partial) {
+        this.partial = partial;
+        this.touch();
+    }
+    finish(result, isError) {
+        this.result = result;
+        this.state = isError || result.isError === true ? "error" : "done";
+        this.touch();
+    }
+    addNested(child) {
+        child.setExpanded(this.expanded);
+        child.parent = this;
+        this.nested.push(child);
+        this.touch();
+    }
+    touch() {
+        this.version++;
+        this.parent?.touch();
+    }
+    invalidate() {
+        this.cache = null;
+        for (const child of this.nested)
+            child.invalidate();
+    }
+    render(width) {
+        if (this.cache && this.cache.width === width && this.cache.version === this.version) {
+            return this.cache.lines;
+        }
+        const lines = [this.header(width), ...this.body(width)];
+        this.cache = { width, version: this.version, lines };
+        return lines;
+    }
+    header(width) {
+        const { theme } = this.options;
+        const dot = this.state === "running"
+            ? theme.fg("accent", "●")
+            : this.state === "error"
+                ? theme.fg("error", "●")
+                : theme.fg("success", "●");
+        const summary = this.customCall(width) ?? toolSummary(this.toolName, this.args, this.options.cwd);
+        const title = `${dot} ${theme.bold(theme.fg("tool", this.toolName))}`;
+        return truncateToWidth(summary === "" ? title : `${title}  ${summary}`, width);
+    }
+    custom(render) {
+        const tool = this.options.getTool?.(this.toolName);
+        if (tool === undefined)
+            return undefined;
+        try {
+            return render(tool);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** `renderCall` 的第一行（去控制字符、折叠空白）；没有或为空时 undefined。 */
+    customCall(width) {
+        const first = this.custom((tool) => tool.renderCall?.(this.args, width)?.[0]);
+        if (typeof first !== "string")
+            return undefined;
+        const line = flat(cleanLines(first).join(" "));
+        return line === "" ? undefined : line;
+    }
+    /** 成功结果的 `renderResult` 行；没有或为空时 undefined。 */
+    customResult(width) {
+        const result = this.result;
+        if (result === undefined || this.state !== "done")
+            return undefined;
+        const inner = Math.max(1, width - 2);
+        const rendered = this.custom((tool) => tool.renderResult?.(result, inner, this.expanded));
+        if (!Array.isArray(rendered) || rendered.length === 0)
+            return undefined;
+        return rendered
+            .slice(0, EXPANDED_MAX_LINES)
+            .map((line) => "  " + truncateToWidth(cleanLines(String(line)).join(" "), inner));
+    }
+    indent(lines, width, color) {
+        const { theme } = this.options;
+        const inner = Math.max(1, width - 2);
+        const out = [];
+        for (const line of lines) {
+            const pieces = this.expanded ? wrapTextWithAnsi(line, inner) : [truncateToWidth(line, inner)];
+            for (const piece of pieces)
+                out.push("  " + (color ? theme.fg(color, piece) : piece));
+        }
+        return out;
+    }
+    more(hidden) {
+        return "  " + this.options.theme.fg("dim", `… 另 ${hidden} 行（Ctrl+O 展开）`);
+    }
+    body(width) {
+        const { theme } = this.options;
+        const out = [];
+        // 嵌套调用
+        if (this.nested.length > 0) {
+            if (this.expanded) {
+                for (const child of this.nested) {
+                    for (const line of child.render(Math.max(1, width - 2)))
+                        out.push("  " + line);
+                }
+            }
+            else {
+                const shown = this.nested.slice(-COLLAPSED_CHILDREN);
+                if (this.nested.length > shown.length) {
+                    out.push("  " + theme.fg("dim", `… 前 ${this.nested.length - shown.length} 个调用`));
+                }
+                for (const child of shown)
+                    out.push("  " + child.header(Math.max(1, width - 2)));
+            }
+        }
+        if (this.state === "running") {
+            if (this.partial !== "") {
+                const all = cleanLines(this.partial);
+                const tail = this.expanded ? all.slice(-EXPANDED_MAX_LINES) : all.slice(-BASH_TAIL_LINES);
+                out.push(...this.indent(tail, width, "dim"));
+            }
+            return out;
+        }
+        const custom = this.customResult(width);
+        if (custom !== undefined) {
+            out.push(...custom);
+            return out;
+        }
+        const diff = this.state === "done" ? diffOf(this.result) : undefined;
+        if (diff !== undefined) {
+            const all = cleanLines(diff).filter((l) => !l.startsWith("---") && !l.startsWith("+++"));
+            const limit = this.expanded ? EXPANDED_MAX_LINES : COLLAPSED_DIFF_LINES;
+            const shown = all.slice(0, limit);
+            const inner = Math.max(1, width - 2);
+            for (const line of shown) {
+                const text = truncateToWidth(line, inner);
+                const colored = line.startsWith("+")
+                    ? theme.fg("success", text)
+                    : line.startsWith("-")
+                        ? theme.fg("error", text)
+                        : line.startsWith("@@")
+                            ? theme.fg("accent", text)
+                            : theme.fg("dim", text);
+                out.push("  " + colored);
+            }
+            if (all.length > shown.length)
+                out.push(this.more(all.length - shown.length));
+            return out;
+        }
+        const text = this.result === undefined ? "" : contentText(this.result.content);
+        const all = cleanLines(text);
+        if (all.length === 0)
+            return out;
+        const limit = this.expanded ? EXPANDED_MAX_LINES : COLLAPSED_RESULT_LINES;
+        const shown = all.slice(0, limit);
+        out.push(...this.indent(shown, width, this.state === "error" ? "error" : "dim"));
+        if (all.length > shown.length)
+            out.push(this.more(all.length - shown.length));
+        return out;
+    }
+}
+/** 按 toolCallId 管理视图与嵌套；`Ctrl+O` 的全局展开状态也在这里。 */
+export class ToolTracker {
+    options;
+    views = new Map();
+    expanded = false;
+    constructor(options) {
+        this.options = options;
+    }
+    get isExpanded() {
+        return this.expanded;
+    }
+    get(toolCallId) {
+        return this.views.get(toolCallId);
+    }
+    /** 新调用；返回视图与它是否是顶层（顶层由调用方加进消息区）。 */
+    start(event) {
+        const existing = this.views.get(event.toolCallId);
+        if (existing !== undefined)
+            return { view: existing, topLevel: false };
+        const view = new ToolView(event.toolCallId, event.toolName, event.args, this.options);
+        view.setExpanded(this.expanded);
+        this.views.set(event.toolCallId, view);
+        const parent = event.parentToolCallId !== undefined ? this.views.get(event.parentToolCallId) : undefined;
+        if (parent !== undefined) {
+            parent.addNested(view);
+            return { view, topLevel: false };
+        }
+        return { view, topLevel: true };
+    }
+    update(toolCallId, partial) {
+        this.views.get(toolCallId)?.update(partial);
+    }
+    end(toolCallId, result, isError) {
+        this.views.get(toolCallId)?.finish(result, isError);
+    }
+    /** 已完成的调用（重放历史）。 */
+    completed(toolCallId, toolName, args, result, isError) {
+        const { view } = this.start({ toolCallId, toolName, args });
+        if (result !== undefined)
+            view.finish(result, isError);
+        return view;
+    }
+    /** Ctrl+O：切换全部调用的展开状态。 */
+    toggleExpanded() {
+        this.expanded = !this.expanded;
+        for (const view of this.views.values())
+            view.setExpanded(this.expanded);
+        return this.expanded;
+    }
+    clear() {
+        this.views.clear();
+    }
+}

package/dist/modes/print/json-event.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 线上事件形状（设计 §13.2、src/rpc.ts）：RPC 与 `--output-format stream-json` 共用。[B6]
+ *
+ * - `message_update` 变成纯增量：去掉累计消息与 `partial`，附最新 `usage`；`done / error`
+ *   保留最终 `message`。其余 `SessionEvent` 原样。
+ * - `toJsonLine()`：一行 JSON；Error 序列化为 `{ name, message }`，bigint 转字符串，
+ *   U+2028 / U+2029 转义（部分 JSONL 客户端会把它们当换行）；图片 base64 不截断。
+ */
+import type { SessionEvent } from "../../agent/types.js";
+import type { AssistantEvent } from "../../ai/types.js";
+import type { RpcEvent, WireAssistantEvent } from "../../rpc.js";
+export declare function toWireAssistantEvent(event: AssistantEvent): WireAssistantEvent;
+export declare function toWireEvent(event: SessionEvent): RpcEvent;
+/** 一行 JSON（不含换行符）。 */
+export declare function toJsonLine(value: unknown): string;

package/dist/modes/print/json-event.js

@@ -0,0 +1,39 @@
+/**
+ * 线上事件形状（设计 §13.2、src/rpc.ts）：RPC 与 `--output-format stream-json` 共用。[B6]
+ *
+ * - `message_update` 变成纯增量：去掉累计消息与 `partial`，附最新 `usage`；`done / error`
+ *   保留最终 `message`。其余 `SessionEvent` 原样。
+ * - `toJsonLine()`：一行 JSON；Error 序列化为 `{ name, message }`，bigint 转字符串，
+ *   U+2028 / U+2029 转义（部分 JSONL 客户端会把它们当换行）；图片 base64 不截断。
+ */
+export function toWireAssistantEvent(event) {
+    if (!("partial" in event))
+        return event;
+    const { partial: _partial, ...rest } = event;
+    return rest;
+}
+export function toWireEvent(event) {
+    if (event.type !== "message_update")
+        return event;
+    const wire = {
+        type: "message_update",
+        assistantMessageEvent: toWireAssistantEvent(event.assistantMessageEvent),
+    };
+    const usage = event.message.usage;
+    if (usage !== undefined)
+        wire.usage = usage;
+    return wire;
+}
+function replacer(_key, value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Error)
+        return { name: value.name, message: value.message };
+    return value;
+}
+/** 一行 JSON（不含换行符）。 */
+export function toJsonLine(value) {
+    return JSON.stringify(value, replacer)
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}

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

@@ -0,0 +1,15 @@
+/**
+ * print 模式（`ama -p`，设计 §11.1 第 15–16 步）。[B6]
+ *
+ * - 提示 = 位置参数 + stdin 管道（stdin 非 TTY 时读到 EOF），两者都有时空一行拼接；都没有 → 用法错误 2。
+ * - `--output-format text`（缺省）：运行结束后输出最后一条助手文本；`json`：一个结果对象（文本、
+ *   停止原因、用量、缓存命中率、[W3-C2] `cache` 统计（同 `get_session_stats.cache`）、全部条目）；
+ *   `stream-json`：每个会话事件一行（线上形状同 RPC，含 `cache_miss` / `cache_warm` /
+ *   `context_pressure`）。
+ * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；SIGINT 130、SIGTERM 143（先 abort）。
+ */
+import type { ModeContext } from "../../cli/deps.js";
+import type { Runtime } from "../../cli/runtime.js";
+export declare function joinPrompt(argument: string | undefined, piped: string): string;
+export declare function runPrintMode(runtime: Runtime, context: ModeContext): Promise<number>;

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

@@ -0,0 +1,96 @@
+/**
+ * print 模式（`ama -p`，设计 §11.1 第 15–16 步）。[B6]
+ *
+ * - 提示 = 位置参数 + stdin 管道（stdin 非 TTY 时读到 EOF），两者都有时空一行拼接；都没有 → 用法错误 2。
+ * - `--output-format text`（缺省）：运行结束后输出最后一条助手文本；`json`：一个结果对象（文本、
+ *   停止原因、用量、缓存命中率、[W3-C2] `cache` 统计（同 `get_session_stats.cache`）、全部条目）；
+ *   `stream-json`：每个会话事件一行（线上形状同 RPC，含 `cache_miss` / `cache_warm` /
+ *   `context_pressure`）。
+ * - 无人值守：ask → deny（bootstrap 已按 print 设 unattended）。
+ * - 退出码：最终助手消息 `error / aborted` 或提示被拒 → 1；SIGINT 130、SIGTERM 143（先 abort）。
+ */
+import { currentSession } from "../../cli/compose-session.js";
+import { ExitCode } from "../../cli/exit-codes.js";
+import { errorText, lastAssistant, onStdoutClosed, onTerminationSignals } from "../shared.js";
+import { toJsonLine, toWireEvent } from "./json-event.js";
+export function joinPrompt(argument, piped) {
+    const parts = [argument ?? "", piped.replace(/\s+$/, "")].filter((p) => p.trim() !== "");
+    return parts.join("\n\n");
+}
+export async function runPrintMode(runtime, context) {
+    const { io } = context;
+    const format = context.args.outputFormat ?? "text";
+    const piped = io.stdinIsTTY ? "" : await io.readStdin();
+    const prompt = joinPrompt(context.prompt, piped);
+    if (prompt === "") {
+        io.stderr("ama: -p 需要提示（位置参数或 stdin 管道）\n");
+        return ExitCode.Usage;
+    }
+    const session = currentSession(runtime);
+    const unsubscribe = format === "stream-json"
+        ? session.subscribe((event) => io.stdout(`${toJsonLine(toWireEvent(event))}\n`))
+        : () => undefined;
+    let signalled;
+    const offSignals = onTerminationSignals((code) => {
+        signalled ??= code;
+        void session.abort();
+    });
+    let stdoutClosed = false;
+    const offEpipe = onStdoutClosed(() => {
+        stdoutClosed = true;
+        void session.abort();
+    });
+    let failure;
+    try {
+        await session.prompt(prompt);
+    }
+    catch (error) {
+        failure = errorText(error);
+    }
+    finally {
+        offSignals();
+        offEpipe();
+        unsubscribe();
+    }
+    const last = lastAssistant(session);
+    const text = session.getLastAssistantText() ?? "";
+    const stopReason = failure !== undefined ? "error" : (last?.stopReason ?? "stop");
+    if (format === "text") {
+        // 部分模型在正文前多发空行：只去前导空行，保留首行缩进；json / stream-json 原样。
+        const shown = text.replace(/^\s*\n/, "");
+        if (shown !== "" && last?.stopReason !== "error")
+            io.stdout(shown.endsWith("\n") ? shown : `${shown}\n`);
+    }
+    else if (format === "json") {
+        const stats = session.getStats();
+        io.stdout(`${toJsonLine({
+            type: "result",
+            sessionId: session.state.sessionId,
+            sessionFile: session.state.sessionFile,
+            model: session.state.model,
+            stopReason,
+            text,
+            ...(failure !== undefined || last?.errorMessage !== undefined
+                ? { error: failure ?? last?.errorMessage }
+                : {}),
+            usage: stats.tokens,
+            cost: stats.cost,
+            cacheHitRate: stats.cacheHitRate,
+            ...(stats.cache !== undefined ? { cache: stats.cache } : {}),
+            entries: session.entries,
+        })}\n`);
+    }
+    if (signalled !== undefined)
+        return signalled;
+    if (stdoutClosed)
+        return ExitCode.Ok; // 下游（如 `| head`）已拿够输出
+    if (failure !== undefined) {
+        io.stderr(`ama: ${failure}\n`);
+        return ExitCode.RuntimeError;
+    }
+    if (last?.stopReason === "error" || last?.stopReason === "aborted") {
+        io.stderr(`ama: ${last.errorMessage ?? "模型调用失败"}\n`);
+        return ExitCode.RuntimeError;
+    }
+    return ExitCode.Ok;
+}

package/dist/modes/rpc/commands.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RPC 命令分派表（设计 §13.2、src/rpc.ts 的 33 条命令）。[B6]
+ *
+ * - 提示类（prompt / steer / follow_up）不等运行结束：会话开始运行（`before_agent_start` /
+ *   `agent_start`）、入队或被处理后立刻应答 `{ disposition }`；运行中的进展走事件。
+ * - 会话类（new_session / switch_session / fork）经组装根 `switchSession`，`ctx.onSessionChanged`
+ *   让模式重新订阅事件。
+ * - 审批：`RpcApprovals` 是 UI broker（`set_client_capabilities` 声明 approvals 后挂上），
+ *   `permission_response` 按 requestId 作答；先到的回答暂存，等 broker 被问到时取用。
+ * - 密钥不离开进程：`get_available_models` 只回 `hasKey` 与 `keySource`。
+ */
+import type { AgentSession } from "../../agent/types.js";
+import type { Runtime } from "../../cli/runtime.js";
+import type { ApprovalBroker, ApprovalDecision, ApprovalRequest } from "../../permissions/types.js";
+import type { RpcCapability, RpcCommandMap, RpcCommandType } from "../../rpc.js";
+/** 审批 broker：等客户端 `permission_response`。 */
+export declare class RpcApprovals implements ApprovalBroker {
+    private readonly pending;
+    private readonly early;
+    ask(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision | undefined>;
+    /** 返回 false = 当前没有在等这个 requestId（已暂存，稍后被问到时生效）。 */
+    respond(requestId: string, decision: ApprovalDecision): boolean;
+    /** 关 stdin / 撤下时：全部弃权（会话按无人作答 deny）。 */
+    cancelAll(): void;
+}
+export interface RpcContext {
+    readonly runtime: Runtime;
+    session(): AgentSession;
+    capabilities: Set<RpcCapability>;
+    readonly approvals: RpcApprovals;
+    /** 会话被换掉后调用（模式据此重新订阅）。 */
+    onSessionChanged(next: AgentSession): void;
+    /** 运行开始后提示命令自身的失败（应答已发出）。 */
+    onBackgroundError(error: unknown): void;
+}
+export type RpcHandlers = {
+    [K in RpcCommandType]: (params: RpcCommandMap[K], ctx: RpcContext) => Promise<unknown>;
+};
+export declare const handlers: RpcHandlers;
+export declare const RPC_COMMAND_TYPES: RpcCommandType[];