@armadra/agent 0.3.0 → 0.5.0

package/dist/modes/interactive/run-indicator.js

@@ -0,0 +1,189 @@
+/**
+ * 运行指示与排队消息（终端界面视觉设计 v1 §3.7、§3.8）：输入框上方的 Loader 动词状态机与排队列表。
+ *
+ * 动词按「当前最深状态」取，避免事件乱序时闪回：
+ *   审批打开 → `等待确认`（无 Esc 提示，Esc 由对话框消费）
+ *   有运行中的工具 → `运行 bash` / `运行 3 个工具`
+ *   自动重试等待中 → `重试 2/3 · 2s 后`（不显示已用时）
+ *   压缩中 → `压缩上下文`
+ *   助手在流式输出 → 末块是思考 `思考中`，否则 `回复中 · ↓≈1.2k`（本条输出的估算 token，4 字符 ≈ 1）
+ *   其余（等首个 token）→ `思考中`
+ * 运行或压缩时 Loader 才挂进槽位；附加项 `Esc 中断`。
+ *
+ * 排队消息：缩进 2 列（挂在当前回合下），`↳ 插话 / 之后  文本` 整体 muted、标签 dim；超过 3 条首行
+ * `… 另 N 条`；末行 `Alt+↑ 取回 · Esc 回填并中断`。
+ */
+import { Container, Text } from "../../tui.js";
+import { ORIGIN_LABELS } from "./message-view.js";
+import { formatTokens } from "./status-bar.js";
+export const QUEUE_PREVIEW = 3;
+function oneLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** 助手消息里已流出的文字（思考 + 正文）的估算 token 与末块类型。 */
+function streamState(message) {
+    let chars = 0;
+    let last;
+    for (const block of message.content) {
+        if (block.type === "text") {
+            chars += block.text.length;
+            if (block.text !== "")
+                last = "text";
+        }
+        else if (block.type === "thinking") {
+            chars += block.thinking.length;
+            if (block.thinking !== "")
+                last = "thinking";
+        }
+        else if (block.type === "toolCall")
+            last = "toolCall";
+    }
+    return { tokens: Math.ceil(chars / 4), thinking: last === "thinking" };
+}
+export class RunIndicator {
+    deps;
+    running = false;
+    compacting = false;
+    approval = false;
+    retry;
+    stream;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get busy() {
+        return this.running || this.compacting;
+    }
+    setApproval(open) {
+        this.approval = open;
+        this.sync();
+    }
+    /** 会话切换后清零。 */
+    reset() {
+        this.running = false;
+        this.compacting = false;
+        this.approval = false;
+        this.retry = undefined;
+        this.stream = undefined;
+        this.sync();
+    }
+    /** 会话事件 → 状态；返回后已同步 Loader。 */
+    onEvent(event) {
+        switch (event.type) {
+            case "agent_start":
+                this.running = true;
+                break;
+            case "agent_settled":
+                this.running = false;
+                this.retry = undefined;
+                this.stream = undefined;
+                break;
+            case "message_start":
+                if (event.message.role === "assistant") {
+                    this.retry = undefined;
+                    this.stream = streamState(event.message);
+                }
+                break;
+            case "message_update":
+                if (event.message.role === "assistant")
+                    this.stream = streamState(event.message);
+                break;
+            case "message_end":
+                if (event.message.role === "assistant")
+                    this.stream = undefined;
+                break;
+            case "compaction_start":
+                this.compacting = true;
+                break;
+            case "compaction_end":
+                this.compacting = false;
+                break;
+            case "auto_retry_start":
+                this.retry = { attempt: event.attempt, max: event.maxAttempts, delayMs: event.delayMs };
+                break;
+            case "auto_retry_end":
+                this.retry = undefined;
+                break;
+            case "tool_execution_start":
+            case "tool_execution_end":
+                break;
+            default:
+                return;
+        }
+        this.sync();
+    }
+    /** 按当前状态换动词，并挂上 / 撤下 Loader。 */
+    sync() {
+        const { loader, slot, render } = this.deps;
+        const active = this.busy;
+        if (active)
+            this.applyVerb();
+        if (active && slot.children.length === 0) {
+            slot.addChild(loader);
+            loader.start();
+        }
+        else if (!active && slot.children.length > 0) {
+            loader.stop();
+            slot.clear();
+        }
+        render();
+    }
+    applyVerb() {
+        const { loader, tools } = this.deps;
+        const esc = ["Esc 中断"];
+        if (this.approval) {
+            loader.setVerb("等待确认");
+            return;
+        }
+        const running = tools.running();
+        const top = running.filter((view) => !running.some((p) => p.children.includes(view)));
+        if (top.length === 1) {
+            loader.setVerb(`运行 ${top[0].toolName}`, esc);
+            return;
+        }
+        if (top.length > 1) {
+            loader.setVerb(`运行 ${top.length} 个工具`, esc);
+            return;
+        }
+        if (this.retry !== undefined) {
+            const seconds = Math.max(1, Math.round(this.retry.delayMs / 1000));
+            loader.setVerb(`重试 ${this.retry.attempt}/${this.retry.max}`, [`${seconds}s 后`], {
+                elapsed: false,
+            });
+            return;
+        }
+        if (this.compacting) {
+            loader.setVerb("压缩上下文", esc);
+            return;
+        }
+        const stream = this.stream;
+        if (stream !== undefined && !stream.thinking && stream.tokens > 0) {
+            loader.setVerb("回复中", [`↓≈${formatTokens(stream.tokens)}`, ...esc]);
+            return;
+        }
+        loader.setVerb("思考中", esc);
+    }
+}
+/** 排队消息（插话 / 之后），挂在 Loader 之上。 */
+export class QueueView extends Text {
+    theme;
+    constructor(theme) {
+        super("");
+        this.theme = theme;
+    }
+    setQueue(steering, followUp) {
+        const t = this.theme;
+        const row = (origin, text) => `  ${t.fg("dim", `${t.glyphs.queued} ${ORIGIN_LABELS[origin]}`)}  ${t.fg("muted", oneLine(text))}`;
+        const rows = [
+            ...steering.map((text) => row("steer", text)),
+            ...followUp.map((text) => row("followUp", text)),
+        ];
+        const shown = rows.slice(-QUEUE_PREVIEW);
+        if (rows.length > shown.length) {
+            shown.unshift("  " + t.fg("dim", `${t.glyphs.ellipsis} 另 ${rows.length - shown.length} 条`));
+        }
+        if (rows.length > 0) {
+            shown.push("    " + t.fg("dim", `Alt+${t.glyphs.arrowUp} 取回 · Esc 回填并中断`));
+        }
+        this.setText(shown.join("\n"));
+    }
+}

package/dist/modes/interactive/session-events.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 交互界面的会话事件分派：`SessionEvent` → 消息区、工具视图、状态栏、运行指示。[B7]
+ * 从 interactive-mode.ts 拆出（W5-U：第五波事件先交给 agent-ui.ts，预算到限的 agent_settled warning 不重复显示）。
+ */
+import type { AgentSession, SessionEvent } from "../../agent/types.js";
+import type { AgentUi } from "./agent-ui.js";
+import type { MessageView, NoticeLevel } from "./message-view.js";
+import type { RunIndicator } from "./run-indicator.js";
+import type { StatusArea } from "./status-area.js";
+import type { StatusBar } from "./status-bar.js";
+import type { ToolTracker } from "./tool-view.js";
+export interface SessionEventDeps {
+    view: MessageView;
+    tools: ToolTracker;
+    status: StatusBar;
+    area: StatusArea;
+    agentUi(): AgentUi;
+    indicator: RunIndicator;
+    session(): AgentSession;
+    setQueue(steering: readonly string[], followUp: readonly string[]): void;
+    notice(level: NoticeLevel, text: string): void;
+    render(): void;
+}
+export declare function createSessionEventHandler(deps: SessionEventDeps): (event: SessionEvent) => void;

package/dist/modes/interactive/session-events.js

@@ -0,0 +1,96 @@
+/**
+ * 交互界面的会话事件分派：`SessionEvent` → 消息区、工具视图、状态栏、运行指示。[B7]
+ * 从 interactive-mode.ts 拆出（W5-U：第五波事件先交给 agent-ui.ts，预算到限的 agent_settled warning 不重复显示）。
+ */
+import { cacheEventNotice, cacheNoticesEnabled } from "../session-report.js";
+import { compactionErrorText, ImageBudgetNotices, LIMIT_WARNING } from "./event-notices.js";
+export function createSessionEventHandler(deps) {
+    const { view, tools, status, area, agentUi, indicator, session, setQueue, notice, render } = deps;
+    const images = new ImageBudgetNotices((text) => notice("info", text));
+    return (event) => {
+        if (area.onEvent(event) || agentUi().onEvent(event))
+            return render();
+        images.onEvent(event);
+        switch (event.type) {
+            case "agent_settled":
+                // 预算到限已由 limit_reached 给出友好提示
+                if (event.warning !== undefined && event.warning !== LIMIT_WARNING)
+                    view.addNotice("warn", event.warning);
+                status.refresh();
+                break;
+            case "message_start": {
+                const message = event.message;
+                if (message.role === "user")
+                    view.addUser(message);
+                else if (message.role === "assistant")
+                    view.startAssistant(message);
+                else if (message.role === "custom" && message.display) {
+                    view.addNotice("info", typeof message.content === "string" ? message.content : "");
+                }
+                break;
+            }
+            case "message_update":
+                view.updateAssistant(event.message);
+                break;
+            case "message_end":
+                if (event.message.role === "assistant") {
+                    view.endAssistant(event.message);
+                    status.refresh();
+                }
+                break;
+            case "tool_execution_start": {
+                const started = tools.start(event);
+                if (started.topLevel)
+                    view.addTool(started.view);
+                break;
+            }
+            case "tool_execution_update":
+                tools.update(event.toolCallId, event.partial);
+                render();
+                return;
+            case "tool_execution_end":
+                tools.end(event.toolCallId, event.result, event.isError);
+                break;
+            case "queue_update":
+                setQueue(event.steering, event.followUp);
+                return;
+            case "compaction_end":
+                if (event.result !== undefined)
+                    view.addCompaction(event.result);
+                else if (event.error !== undefined)
+                    view.addNotice("error", `压缩失败：${compactionErrorText(event.error)}`);
+                else if (event.aborted)
+                    view.addNotice("info", "压缩已取消");
+                status.refresh();
+                break;
+            case "auto_retry_start":
+                view.addRetry(event.attempt, event.maxAttempts, event.delayMs, event.errorMessage);
+                break;
+            case "auto_retry_end":
+                if (!event.success)
+                    view.addRetryFailed(event.finalError);
+                break;
+            case "cache_miss":
+            case "context_pressure": {
+                const shown = cacheEventNotice(event, cacheNoticesEnabled(session()));
+                if (shown !== undefined)
+                    view.addNotice(shown.level, shown.text);
+                status.refresh();
+                render();
+                return;
+            }
+            case "cache_warm":
+            case "permission_mode_changed":
+            case "model_changed":
+            case "thinking_level_changed":
+            case "session_changed":
+                status.refresh();
+                render();
+                return;
+            default:
+                break;
+        }
+        indicator.onEvent(event);
+        render();
+    };
+}

package/dist/modes/interactive/startup-header.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 交互模式启动头（终端界面视觉设计 v1 §3.1）。
+ *
+ * - `normal`：宽度 ≥ 56 且非 `ui.compact` 时画框（宽 `min(width, 64)`，左对齐）——标题 `✻ ama x.y.z`、
+ *   键值行（模型 / 目录 / 模式 / 已加载 / 宿主 / 警告）、按键提示；否则去框去键列，每项一行。
+ * - `header`：一行 `✻ ama x.y.z · 模型 · 模式 · /help`，无框。`silent` 不输出（调用方不加本组件）。
+ * - 着色：`✻` accent、标题粗体；键列 dim；模型 accent；已信任 success / 未信任 warning；Bypass 模式 warning；
+ *   按键提示 dim。路径过长时从左截断（`…/armadra-agent`）。宽度变化时按新宽重算是否去框。
+ */
+import type { StartupInfo } from "../../cli/startup-screen.js";
+import { type Component, type Theme } from "../../tui.js";
+/** 画框的最小宽度；更窄时去框去键列。 */
+export declare const HEADER_BOX_MIN_WIDTH = 56;
+/** 设计稿写 60；常见的「供应商/模型@渠道 · 思考 级别」要 62 列左右才不截断，取 64。 */
+export declare const HEADER_BOX_MAX_WIDTH = 64;
+export interface StartupHeaderOptions {
+    theme: Theme;
+    level: "normal" | "header";
+    /** `ui.compact`：normal 也不画框。 */
+    compact?: boolean;
+}
+/** 从左截断到 `width` 列（保留末尾，前面加省略号）。 */
+export declare function truncateLeft(text: string, width: number, ellipsis?: string): string;
+export declare class StartupHeader implements Component {
+    private readonly info;
+    private readonly options;
+    private cache;
+    constructor(info: StartupInfo, options: StartupHeaderOptions);
+    private get theme();
+    private title;
+    private modeText;
+    private trustText;
+    private loadedText;
+    private codemodeText;
+    render(width: number): string[];
+    private headerLine;
+    private plainLines;
+    private boxLines;
+    invalidate(): void;
+}

package/dist/modes/interactive/startup-header.js

@@ -0,0 +1,169 @@
+/**
+ * 交互模式启动头（终端界面视觉设计 v1 §3.1）。
+ *
+ * - `normal`：宽度 ≥ 56 且非 `ui.compact` 时画框（宽 `min(width, 64)`，左对齐）——标题 `✻ ama x.y.z`、
+ *   键值行（模型 / 目录 / 模式 / 已加载 / 宿主 / 警告）、按键提示；否则去框去键列，每项一行。
+ * - `header`：一行 `✻ ama x.y.z · 模型 · 模式 · /help`，无框。`silent` 不输出（调用方不加本组件）。
+ * - 着色：`✻` accent、标题粗体；键列 dim；模型 accent；已信任 success / 未信任 warning；Bypass 模式 warning；
+ *   按键提示 dim。路径过长时从左截断（`…/armadra-agent`）。宽度变化时按新宽重算是否去框。
+ */
+import { permissionModeLabel } from "../../permissions/modes.js";
+import { Box, KeyValue, padToWidth, truncateToWidth, visibleWidth, } from "../../tui.js";
+/** 画框的最小宽度；更窄时去框去键列。 */
+export const HEADER_BOX_MIN_WIDTH = 56;
+/** 设计稿写 60；常见的「供应商/模型@渠道 · 思考 级别」要 62 列左右才不截断，取 64。 */
+export const HEADER_BOX_MAX_WIDTH = 64;
+/** 从左截断到 `width` 列（保留末尾，前面加省略号）。 */
+export function truncateLeft(text, width, ellipsis = "…") {
+    if (visibleWidth(text) <= width)
+        return text;
+    const room = width - visibleWidth(ellipsis);
+    if (room <= 0)
+        return truncateToWidth(ellipsis, width);
+    const chars = [...text];
+    let out = "";
+    let used = 0;
+    for (let i = chars.length - 1; i >= 0; i--) {
+        const w = visibleWidth(chars[i]);
+        if (used + w > room)
+            break;
+        out = chars[i] + out;
+        used += w;
+    }
+    return ellipsis + out;
+}
+/** 去掉模型引用里的渠道（`@messages`）。 */
+function withoutChannel(model) {
+    const at = model.indexOf("@");
+    return at === -1 ? model : model.slice(0, at);
+}
+export class StartupHeader {
+    info;
+    options;
+    cache = null;
+    constructor(info, options) {
+        this.info = info;
+        this.options = options;
+    }
+    get theme() {
+        return this.options.theme;
+    }
+    title() {
+        const t = this.theme;
+        return `${t.fg("accent", t.glyphs.thinking)} ${t.bold(`ama ${this.info.version}`)}`;
+    }
+    modeText() {
+        const label = permissionModeLabel(this.info.permissionMode);
+        return this.info.permissionMode === "full-auto" ? this.theme.fg("warning", label) : label;
+    }
+    trustText(withSource) {
+        const { trusted, trustSource } = this.info;
+        const text = `${trusted ? "已信任" : "未信任"}${withSource ? `（${trustSource}）` : ""}`;
+        return this.theme.fg(trusted ? "success" : "warning", text);
+    }
+    loadedText() {
+        const { contextFiles, skills, prompts, hooks } = this.info;
+        const parts = [];
+        if (contextFiles.length > 0)
+            parts.push(contextFiles.join(", "));
+        if (skills > 0)
+            parts.push(`${skills} Skill`);
+        if (prompts > 0)
+            parts.push(`${prompts} 模板`);
+        if (hooks > 0)
+            parts.push(`${hooks} Hook`);
+        return parts.length === 0 ? undefined : parts.join(" · ");
+    }
+    codemodeText() {
+        return this.info.codemode === "off" ? undefined : `codemode ${this.info.codemode}`;
+    }
+    render(width) {
+        if (this.cache?.width === width)
+            return this.cache.lines;
+        const lines = this.options.level === "header"
+            ? [this.headerLine(width)]
+            : this.options.compact === true || width < HEADER_BOX_MIN_WIDTH
+                ? this.plainLines(width)
+                : this.boxLines(width);
+        this.cache = { width, lines };
+        return lines;
+    }
+    headerLine(width) {
+        const t = this.theme;
+        const sep = t.fg("dim", " · ");
+        const parts = [
+            this.title(),
+            t.fg("accent", withoutChannel(this.info.model)),
+            this.modeText(),
+            t.fg("dim", "/help"),
+        ];
+        return truncateToWidth(parts.join(sep), width);
+    }
+    plainLines(width) {
+        const t = this.theme;
+        const sep = t.fg("dim", " · ");
+        const ellipsis = t.glyphs.ellipsis;
+        const { info } = this;
+        const lines = [this.title()];
+        lines.push(t.fg("accent", withoutChannel(info.model)) + sep + info.thinking);
+        const trust = this.trustText(false);
+        const room = Math.max(4, width - visibleWidth(trust) - 3);
+        lines.push(truncateLeft(info.cwd, room, ellipsis) + sep + trust);
+        const mode = [this.modeText(), info.preset, this.codemodeText()].filter((p) => p !== undefined);
+        lines.push(mode.join(sep));
+        const loaded = this.loadedText();
+        if (loaded !== undefined)
+            lines.push(loaded);
+        if (info.host !== undefined)
+            lines.push(`宿主 ${info.host}`);
+        if (info.warnings > 0)
+            lines.push(t.fg("warning", `警告 ${info.warnings} 条（ama doctor）`));
+        lines.push(t.fg("dim", "/help · Shift+Tab 切模式"));
+        return lines.map((line) => truncateToWidth(line, width));
+    }
+    boxLines(width) {
+        const t = this.theme;
+        const sep = t.fg("dim", " · ");
+        const { info } = this;
+        const boxWidth = Math.min(width, HEADER_BOX_MAX_WIDTH);
+        /** 框内文本宽：边框 2 + 内边距 2；键列 6 + 间隔 1。 */
+        const valueWidth = boxWidth - 4 - 7;
+        const trust = this.trustText(true);
+        const cwdRoom = Math.max(4, valueWidth - visibleWidth(trust) - 3);
+        const rows = [
+            { key: "模型", value: t.fg("accent", info.model) + sep + `思考 ${info.thinking}` },
+            { key: "目录", value: truncateLeft(info.cwd, cwdRoom, t.glyphs.ellipsis) + sep + trust },
+            {
+                key: "模式",
+                value: [this.modeText(), `预设 ${info.preset}`, this.codemodeText()]
+                    .filter((p) => p !== undefined)
+                    .join(sep),
+            },
+        ];
+        const loaded = this.loadedText();
+        if (loaded !== undefined)
+            rows.push({ key: "已加载", value: loaded });
+        if (info.host !== undefined)
+            rows.push({ key: "宿主", value: info.host });
+        if (info.warnings > 0) {
+            rows.push({ key: "警告", value: t.fg("warning", `${info.warnings} 条（ama doctor 查看）`) });
+        }
+        // 键列固定 6 列（「已加载」的宽度），没有这一行时也对齐
+        const padded = rows.map((row) => ({ ...row, key: padToWidth(row.key, 6) }));
+        const kv = new KeyValue(padded, { theme: t, gap: 1, maxKeyRatio: 1 });
+        const body = {
+            render: (inner) => [
+                this.title(),
+                "",
+                ...kv.render(inner),
+                "",
+                t.fg("dim", "/help 命令 · Shift+Tab 切模式 · Ctrl+O 展开工具输出"),
+            ],
+            invalidate: () => kv.invalidate(),
+        };
+        return new Box(body, { theme: t }).render(boxWidth);
+    }
+    invalidate() {
+        this.cache = null;
+    }
+}

package/dist/modes/interactive/status-area.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 交互界面的底部区域：提示行、速率行（status-line.ts）与状态栏（status-bar.ts）的装配。[W5-A]
+ *
+ * - 布局 `ui.statusLine`（独立终端缺省 full；有 profile 时 PROFILE_DEFAULTS 给 compact）；运行时 Ctrl+G
+ *   （`app.statusLine.toggle`）或 `/statusline [full|compact]` 切换，只影响本会话（本进程），不写配置。
+ * - 会话时长从本进程打开当前会话（含 /new /resume /fork 切换）起算，用界面的时钟。
+ * - git：`GitInfoWatcher` 在回合边界刷新——agent_settled、写类工具（write / edit / bash / task）结束、
+ *   session_rewound、/tree 之后；结果变化时重画。
+ * - [W5-U] `model_fallback` 之后状态栏模型项显示 `主模型 → 回退模型`，切回主模型（`model_changed`）后消失。
+ * - `telemetry_tick`（流式中 ≤ 2 Hz）只重取统计并重画（速率行），状态栏的内容这时不变。
+ */
+import type { AgentSession, SessionEvent } from "../../agent/types.js";
+import type { Runtime } from "../../cli/runtime.js";
+import type { StatusLineMode } from "../../config/types.js";
+import { type Component, type Theme } from "../../tui.js";
+import { StatusBar } from "./status-bar.js";
+import { StatusLine } from "./status-line.js";
+/** 一行提示；空时不占行。 */
+export declare class HintLine implements Component {
+    private text;
+    setText(text: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+}
+export interface StatusAreaDeps {
+    runtime: Runtime;
+    theme: Theme;
+    session(): AgentSession;
+    now(): number;
+    render(): void;
+    /**
+     * 布局切换后整屏重画（行数变了，差分渲染会在屏底留一空行，宿主按「最后一行 = 状态栏」锚定会错位）；
+     * 缺省 render。
+     */
+    redraw?(): void;
+    /** 初始布局（缺省按配置）。 */
+    layout?: StatusLineMode;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class StatusArea {
+    private readonly deps;
+    readonly hint: HintLine;
+    readonly bar: StatusBar;
+    readonly rate: StatusLine;
+    private mode;
+    private startedAt;
+    private git;
+    private gitCwd;
+    private offGit;
+    private sandboxStrict;
+    /** [W5-U] 模型回退中（`model_fallback` 到切回主模型）。 */
+    private fallback;
+    private bashSandbox;
+    constructor(deps: StatusAreaDeps);
+    layout(): StatusLineMode;
+    setLayout(mode: StatusLineMode): void;
+    toggle(): StatusLineMode;
+    refresh(): void;
+    /** 换了会话（/new /resume /fork）：时长重新起算，cwd 变了就换 git 监视。 */
+    rebind(): void;
+    refreshGit(): void;
+    /** 返回 true：事件已处理完（只需重画），调用方不再分派。 */
+    onEvent(event: SessionEvent): boolean;
+    dispose(): void;
+    private gitView;
+    private watchGit;
+}
+/**
+ * `/statusline [full|compact]`（无参数切换）：是这条命令就处理并返回 true，否则 false 交给其它命令。
+ * line 模式没有底部信息行，commands-core 只登记命令名、回一句说明。
+ */
+export declare function statusLineSlash(area: StatusArea, line: string, notice: (level: "info" | "error", text: string) => void): boolean;
+export declare function statusLineText(mode: StatusLineMode): string;