@armadra/agent 0.4.0 → 0.5.0

package/dist/modes/interactive/approval-merge.js

@@ -0,0 +1,89 @@
+/**
+ * default 模式下 `task(agent="claude")` 会问两次：task 工具调用一次，外部 Agent 本会话首次运行再一次
+ * （agents/external.ts 的 `firstRun`）。界面层把它们合并成一次确认。[W5-U]
+ *
+ * 规则（不放宽权限语义）：
+ * - 用户在对话框里**允许**了一次 `task` 工具调用，且它的 `agent` 是外部 Agent（类型的 runner 不是
+ *   ama）——对话框已把「以你在该 CLI 的登录运行」写在正文里——记下 `{agent, 时刻}`；
+ * - **紧接着**的下一个审批请求若是同一 Agent 的首次运行确认（`toolName: "task"`、输入带 `note`），其
+ *   `context.taskId` 对应的任务是该 Agent、且在允许之后才建立（同一次调用产生的任务），并在 60 s 内
+ *   到达，就以「允许」自动答复，不再弹框；
+ * - 记录只用一次；中间夹了任何别的审批请求、拒绝、超时，都作废——首次运行确认照常弹出。
+ */
+import { taskRegistryView } from "../../agent/subagent-registry.js";
+import { isFirstRunRequest } from "./approval-dialog.js";
+import { listAgents } from "./tasks-report.js";
+export const MERGE_WINDOW_MS = 60_000;
+function input(request) {
+    const value = request.input;
+    return typeof value === "object" && value !== null ? value : {};
+}
+export class FirstRunMerge {
+    deps;
+    pending;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    /** `task` 调用的 agent 是外部 Agent 时返回它的 runner。 */
+    externalRunner(agent) {
+        const runner = this.deps.runnerOf?.(agent) ??
+            listAgents(this.deps.sessionId()).find((a) => a.name === agent)?.runner;
+        return runner === undefined || runner === "ama" ? undefined : runner;
+    }
+    taskOf(taskId) {
+        if (this.deps.taskOf !== undefined)
+            return this.deps.taskOf(taskId);
+        return taskRegistryView(this.deps.sessionId())?.get(taskId);
+    }
+    /** 请求到来：命中合并返回 `allow`（不弹框）；否则返回 undefined，并作废记录。 */
+    intercept(request) {
+        const pending = this.pending;
+        this.pending = undefined;
+        if (pending === undefined || !isFirstRunRequest(request))
+            return undefined;
+        if (this.now() - pending.at > (this.deps.windowMs ?? MERGE_WINDOW_MS))
+            return undefined;
+        const taskId = request.context?.taskId;
+        if (taskId === undefined || request.context?.origin !== undefined)
+            return undefined;
+        const task = this.taskOf(taskId);
+        if (task === undefined || task.agent !== pending.agent || task.startedAt < pending.at)
+            return undefined;
+        const runner = this.externalRunner(pending.agent);
+        if (runner === undefined || input(request)["agent"] !== runner)
+            return undefined;
+        return "allow";
+    }
+    /** 用户答复之后：允许了外部 Agent 的 task 调用就记下。 */
+    record(request, decision) {
+        this.pending = undefined;
+        if (decision !== "allow" && decision !== "allow_session")
+            return;
+        if (request.toolName !== "task" || isFirstRunRequest(request))
+            return;
+        if ((request.context?.depth ?? 0) > 0 || request.context?.origin !== undefined)
+            return;
+        const agent = input(request)["agent"];
+        if (typeof agent !== "string" || this.externalRunner(agent) === undefined)
+            return;
+        this.pending = { agent, at: this.now() };
+    }
+}
+/** 把合并规则套在界面 broker 外面；自动答复时调 `onMerged`（消息区一行说明）。 */
+export function mergingBroker(inner, merge, onMerged) {
+    return {
+        async ask(request, signal) {
+            const merged = merge.intercept(request);
+            if (merged !== undefined) {
+                onMerged?.(request);
+                return merged;
+            }
+            const decision = await inner.ask(request, signal);
+            merge.record(request, decision);
+            return decision;
+        },
+    };
+}

package/dist/modes/interactive/clipboard-paste.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `Ctrl+V` 与 `/paste`：剪贴板图片写进 `<dataDir>/clipboard/`，输入框插入 `@<路径>`（发送时按 `@图片`
+ * 附件读取）。[W5-U] 读取本身在 tools/clipboard-image.ts（W5-I）。
+ */
+import { type ClipboardDeps } from "../../tools/clipboard-image.js";
+export type PasteOutcome = {
+    ok: true;
+    ref: string;
+    path: string;
+} | {
+    ok: false;
+    message: string;
+};
+export declare const NO_CLIPBOARD_TOOL = "\u8BFB\u4E0D\u4E86\u526A\u8D34\u677F\u56FE\u7247\uFF1A\u6CA1\u6709\u53EF\u7528\u7684\u7CFB\u7EDF\u547D\u4EE4\uFF08macOS osascript / pngpaste\uFF0CLinux wl-paste / xclip\uFF0CWindows PowerShell\uFF09";
+export declare const NO_CLIPBOARD_IMAGE = "\u526A\u8D34\u677F\u91CC\u6CA1\u6709\u56FE\u7247";
+/** `@路径`；路径带空白时加引号。 */
+export declare function imageRef(path: string): string;
+export declare function pasteImage(dataDir: string, deps?: ClipboardDeps): Promise<PasteOutcome>;

package/dist/modes/interactive/clipboard-paste.js

@@ -0,0 +1,28 @@
+/**
+ * `Ctrl+V` 与 `/paste`：剪贴板图片写进 `<dataDir>/clipboard/`，输入框插入 `@<路径>`（发送时按 `@图片`
+ * 附件读取）。[W5-U] 读取本身在 tools/clipboard-image.ts（W5-I）。
+ */
+import { readClipboardImage } from "../../tools/clipboard-image.js";
+export const NO_CLIPBOARD_TOOL = "读不了剪贴板图片：没有可用的系统命令（macOS osascript / pngpaste，Linux wl-paste / xclip，Windows PowerShell）";
+export const NO_CLIPBOARD_IMAGE = "剪贴板里没有图片";
+/** `@路径`；路径带空白时加引号。 */
+export function imageRef(path) {
+    return /\s/.test(path) ? `@"${path}"` : `@${path}`;
+}
+export async function pasteImage(dataDir, deps) {
+    try {
+        const result = await readClipboardImage(dataDir, deps);
+        if (result.ok)
+            return { ok: true, ref: imageRef(result.path), path: result.path };
+        return {
+            ok: false,
+            message: result.reason === "no_tool" ? NO_CLIPBOARD_TOOL : NO_CLIPBOARD_IMAGE,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `读取剪贴板失败：${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}

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

@@ -7,9 +7,11 @@
  * - 交互模式自有命令：`/tree`（同一文件内换叶子到选中消息之前，文本回填编辑器，可改后重发形成新分支）、
  *   `/permissions`（当前模式、判定顺序与已加载规则）；`/help` 追加这两条与按键说明。
  * - `/session`、`/cache`（无参数）与 `/permissions` 在消息区画左竖条面板（panels.ts），不再拍成文本。
+ * - `/rewind`（无参数）打开回滚列表与确认面板（rewind-flow.ts）；带参数走 commands-core，对话变了时
+ *   重画消息区并回填原消息。
  * - 不是命令（含模板与 `/skill:`）返回 false，调用方把整行当提示发出。
  */
-import type { AgentSession } from "../../agent/types.js";
+import type { AgentSession, RewindDraftText } from "../../agent/types.js";
 import type { SwitchRequest } from "../../cli/compose-session.js";
 import type { Runtime } from "../../cli/runtime.js";
 import type { Component, SelectItem, Theme } from "../../tui.js";
@@ -34,6 +36,10 @@ export interface CommandUi {
     prompt(text: string): void;
     /** /tree 换叶子后重画消息区。 */
     reload(): void;
+    /** 回滚列表与确认面板（`/rewind` 无参数）；没有时回落为文字列表。 */
+    rewind?(): Promise<void>;
+    /** 回填原消息（文本 + 图片）；缺省只回填文本。 */
+    setDraft?(draft: RewindDraftText): void;
     exit(code: number): void;
     now(): number;
     /** 面板用的主题（与 panel 一起提供）。 */
@@ -42,6 +48,8 @@ export interface CommandUi {
     home?: string;
     /** 进程环境：给出时 /model 选择器按 fake-visibility 规则藏起测试供应商 fake。 */
     env?: Readonly<Record<string, string | undefined>>;
+    /** [W5-U] 界面自己处理的第五波命令（agent-ui.ts）；处理了返回 true。 */
+    extra?(name: string, args: string): Promise<boolean>;
 }
 /** 当前分支上的条目 id（树选择器标 ●）。 */
 export declare function activeBranchIds(session: AgentSession): Set<string>;

package/dist/modes/interactive/commands.js

@@ -7,6 +7,8 @@
  * - 交互模式自有命令：`/tree`（同一文件内换叶子到选中消息之前，文本回填编辑器，可改后重发形成新分支）、
  *   `/permissions`（当前模式、判定顺序与已加载规则）；`/help` 追加这两条与按键说明。
  * - `/session`、`/cache`（无参数）与 `/permissions` 在消息区画左竖条面板（panels.ts），不再拍成文本。
+ * - `/rewind`（无参数）打开回滚列表与确认面板（rewind-flow.ts）；带参数走 commands-core，对话变了时
+ *   重画消息区并回填原消息。
  * - 不是命令（含模板与 `/skill:`）返回 false，调用方把整行当提示发出。
  */
 import { formatModelRef } from "../../ai/providers/channels.js";
@@ -27,8 +29,11 @@ export const ALL_COMMANDS = [...BUILTIN_COMMANDS, ...INTERACTIVE_COMMANDS];
 export const KEY_HINTS = [
     "Enter 发送（运行中 = 插话）  Alt+Enter 排到本轮之后  Shift+Enter / Ctrl+J 换行",
     "Esc 中断（排队消息回填编辑器）  Alt+↑ 取回最后一条排队消息",
+    "空闲时 Esc Esc：输入框为空 = 回滚（/rewind），有字 = 清空（↑ 取回）",
     "Shift+Tab 切换权限模式  Ctrl+L 模型  Ctrl+T 思考级别  Ctrl+O 展开工具输出与思考",
     "审批：1–3 或 ↑↓ Enter 选择，y 允许  a 本会话允许同类  n / Esc 拒绝  v 完整输入",
+    "计划审批：1 批准  2 新上下文执行  3 继续修改  4 放弃并退出 Plan  e 编辑计划  Esc 留在 Plan",
+    "Ctrl+V 粘贴剪贴板图片（插入 @路径）  Ctrl+G 底部信息行两行 / 一行",
     "Ctrl+C 清空输入（再按退出）  Ctrl+D 空输入时退出  Tab 补全  @ 引用文件",
 ].join("\n");
 function homeOf(ui) {
@@ -184,10 +189,16 @@ export async function runInteractiveCommand(line, ui) {
     if (parsed === undefined)
         return false;
     try {
+        if (ui.extra !== undefined && (await ui.extra(parsed.name, parsed.args)))
+            return true;
         if (parsed.name === "tree") {
             await treeCommand(ui);
             return true;
         }
+        if (parsed.name === "rewind" && parsed.args === "" && ui.rewind !== undefined) {
+            await ui.rewind();
+            return true;
+        }
         const theme = ui.theme?.();
         if (parsed.name === "permissions") {
             if (ui.panel !== undefined && theme !== undefined) {
@@ -225,12 +236,20 @@ export async function runInteractiveCommand(line, ui) {
                 await handlePick(result.what, ui);
                 break;
             case "handled":
+                if (result.reload === true)
+                    ui.reload();
                 if (parsed.name === "help") {
                     const extra = INTERACTIVE_COMMANDS.map((c) => `/${c.name}  ${c.description}`);
                     ui.notice("info", [result.message ?? "", ...extra, "", KEY_HINTS].join("\n"));
                 }
                 else if (result.message !== undefined)
                     ui.notice("info", result.message);
+                if (result.draft !== undefined) {
+                    if (ui.setDraft !== undefined)
+                        ui.setDraft(result.draft);
+                    else
+                        ui.setEditorText(result.draft.text);
+                }
                 break;
         }
     }

package/dist/modes/interactive/double-esc.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 空闲时的双击 Esc（rewind-plan §4）：纯状态机，键位分派里用。[RW-C]
+ *
+ * - 输入框为空：第一次 `arm-rewind`（提示「再按 Esc 回滚」），间隔内第二次 `rewind`（打开回滚列表）。
+ * - 输入框有字：第一次 `arm-clear`（提示「再按 Esc 清空」），间隔内第二次 `clear`（清空并存进输入历史）。
+ * - 两次之间输入框状态变了（空 ↔ 有字）、超过间隔、或中间按了别的键（`reset()`）都重新计。
+ */
+/** 两次 Esc 的最大间隔。 */
+export declare const DOUBLE_ESC_MS = 800;
+/** 第一次 Esc 的提示停留时间。 */
+export declare const DOUBLE_ESC_HINT_MS = 1000;
+export type EscAction = "arm-rewind" | "rewind" | "arm-clear" | "clear";
+export declare class DoubleEscape {
+    private readonly windowMs;
+    private armed;
+    constructor(windowMs?: number);
+    press(now: number, editorEmpty: boolean): EscAction;
+    reset(): void;
+    get isArmed(): boolean;
+}

package/dist/modes/interactive/double-esc.js

@@ -0,0 +1,34 @@
+/**
+ * 空闲时的双击 Esc（rewind-plan §4）：纯状态机，键位分派里用。[RW-C]
+ *
+ * - 输入框为空：第一次 `arm-rewind`（提示「再按 Esc 回滚」），间隔内第二次 `rewind`（打开回滚列表）。
+ * - 输入框有字：第一次 `arm-clear`（提示「再按 Esc 清空」），间隔内第二次 `clear`（清空并存进输入历史）。
+ * - 两次之间输入框状态变了（空 ↔ 有字）、超过间隔、或中间按了别的键（`reset()`）都重新计。
+ */
+/** 两次 Esc 的最大间隔。 */
+export const DOUBLE_ESC_MS = 800;
+/** 第一次 Esc 的提示停留时间。 */
+export const DOUBLE_ESC_HINT_MS = 1000;
+export class DoubleEscape {
+    windowMs;
+    armed;
+    constructor(windowMs = DOUBLE_ESC_MS) {
+        this.windowMs = windowMs;
+    }
+    press(now, editorEmpty) {
+        const kind = editorEmpty ? "rewind" : "clear";
+        const armed = this.armed;
+        if (armed !== undefined && armed.kind === kind && now - armed.at <= this.windowMs) {
+            this.armed = undefined;
+            return kind;
+        }
+        this.armed = { kind, at: now };
+        return kind === "rewind" ? "arm-rewind" : "arm-clear";
+    }
+    reset() {
+        this.armed = undefined;
+    }
+    get isArmed() {
+        return this.armed !== undefined;
+    }
+}

package/dist/modes/interactive/event-notices.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 交互界面对几类会话事件的友好提示（第五波其它批次转来的显示项）。[W5-A]
+ *
+ * - W5-I：`entry_appended` 里 `reason: "image_budget"` 的 `context_edit`（一次降级会连写多条，每条一个消息）
+ *   合并成一条「已省略 N 张早期图片以符合请求上限」，N 按占位文本数；
+ * - W5-H1：`compaction_end.error` 的「compaction did not shrink」换成中文说明（其余错误原样）。
+ */
+import type { SessionEvent } from "../../agent/types.js";
+/** `compaction_end.error` 的显示文本。 */
+export declare function compactionErrorText(error: string): string;
+/** 同一轮同步写下的 image_budget 降级合并成一条提示。 */
+export declare class ImageBudgetNotices {
+    private readonly notify;
+    private pending;
+    private scheduled;
+    constructor(notify: (text: string) => void);
+    onEvent(event: SessionEvent): void;
+}
+/** `agent_settled.warning` 为它时不再单独显示（`limit_reached` 事件已给出友好提示）。 */
+export declare const LIMIT_WARNING = "limit_reached";
+/** `limit_reached`：回合 / 费用到限（每次运行每类一次）。 */
+export declare function limitReachedText(event: Extract<SessionEvent, {
+    type: "limit_reached";
+}>): string;
+/** `model_fallback`：主模型失败后改用回退模型重试一次。 */
+export declare function modelFallbackText(event: Extract<SessionEvent, {
+    type: "model_fallback";
+}>): string;
+/** `background_job`：后台命令启动 / 退出 / 停止。 */
+export declare function backgroundJobText(event: Extract<SessionEvent, {
+    type: "background_job";
+}>): string;

package/dist/modes/interactive/event-notices.js

@@ -0,0 +1,79 @@
+/**
+ * 交互界面对几类会话事件的友好提示（第五波其它批次转来的显示项）。[W5-A]
+ *
+ * - W5-I：`entry_appended` 里 `reason: "image_budget"` 的 `context_edit`（一次降级会连写多条，每条一个消息）
+ *   合并成一条「已省略 N 张早期图片以符合请求上限」，N 按占位文本数；
+ * - W5-H1：`compaction_end.error` 的「compaction did not shrink」换成中文说明（其余错误原样）。
+ */
+import { IMAGE_OMITTED_FOR_BUDGET, IMAGE_OMITTED_TOO_LARGE, } from "../../compaction/image-budget.js";
+/** `compaction_end.error` 的显示文本。 */
+export function compactionErrorText(error) {
+    if (/compaction did not shrink/i.test(error)) {
+        return "压缩后上下文没有变小，已保留原对话（不写摘要）";
+    }
+    return error;
+}
+function count(text, needle) {
+    let n = 0;
+    for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length))
+        n++;
+    return n;
+}
+/** 同一轮同步写下的 image_budget 降级合并成一条提示。 */
+export class ImageBudgetNotices {
+    notify;
+    pending = 0;
+    scheduled = false;
+    constructor(notify) {
+        this.notify = notify;
+    }
+    onEvent(event) {
+        if (event.type !== "entry_appended")
+            return;
+        const entry = event.entry;
+        if (entry.type !== "context_edit" || entry.reason !== "image_budget")
+            return;
+        const text = entry.replacement ?? "";
+        const images = count(text, IMAGE_OMITTED_FOR_BUDGET) + count(text, IMAGE_OMITTED_TOO_LARGE);
+        this.pending += Math.max(1, images);
+        if (this.scheduled)
+            return;
+        this.scheduled = true;
+        queueMicrotask(() => {
+            const n = this.pending;
+            this.pending = 0;
+            this.scheduled = false;
+            this.notify(`已省略 ${n} 张早期图片以符合请求上限`);
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// [W5-U] 第五波 harness 事件（W5-H2）的提示文本：交互界面与 line 模式共用
+// ---------------------------------------------------------------------------
+/** `agent_settled.warning` 为它时不再单独显示（`limit_reached` 事件已给出友好提示）。 */
+export const LIMIT_WARNING = "limit_reached";
+/** `limit_reached`：回合 / 费用到限（每次运行每类一次）。 */
+export function limitReachedText(event) {
+    if (event.kind === "turns")
+        return `已到回合上限（${event.limit} 回合），本次运行停止；发新消息继续（--max-turns / limits.maxTurns）`;
+    const spent = `$${event.value.toFixed(2)}`;
+    return `已到费用上限 $${event.limit.toFixed(2)}（本次运行已用 ${spent}），本次运行停止；发新消息继续（--max-cost / limits.maxCostUsd）`;
+}
+/** `model_fallback`：主模型失败后改用回退模型重试一次。 */
+export function modelFallbackText(event) {
+    const ref = (m) => `${m.provider}/${m.id}`;
+    return `${ref(event.from)} 不可用（${event.reason}），本次请求改用 ${ref(event.to)}，回复后切回`;
+}
+/** `background_job`：后台命令启动 / 退出 / 停止。 */
+export function backgroundJobText(event) {
+    const command = event.command.replace(/\s+/g, " ").trim();
+    const short = command.length > 60 ? `${command.slice(0, 59)}…` : command;
+    switch (event.phase) {
+        case "started":
+            return `后台命令 ${event.jobId} 已启动：${short}`;
+        case "exited":
+            return `后台命令 ${event.jobId} 已退出（码 ${event.exitCode ?? "?"}）：${short}`;
+        case "stopped":
+            return `后台命令 ${event.jobId} 已停止：${short}`;
+    }
+}

package/dist/modes/interactive/external-editor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 外部编辑器（计划审批框的「编辑计划」与「继续修改」）：`$VISUAL` → `$EDITOR` → `vi`（Windows `notepad`）。
+ * [W5-U] 编辑期间 TUI 挂起（交还终端），回来后整屏重画。临时文件在系统临时目录，读完即删。
+ */
+export interface ExternalEditorDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    /** 挂起 / 恢复界面。 */
+    suspend(): void;
+    resume(): void;
+    platform?: NodeJS.Platform;
+    /** 测试注入：代替真实启动编辑器（参数：命令行、文件路径），返回退出码。 */
+    run?(command: string, file: string): number | null;
+}
+export declare function editorCommand(env: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform): string;
+/** 在外部编辑器里改 `text`；编辑器非零退出或读不回来返回 undefined。 */
+export declare function editExternally(text: string, name: string, deps: ExternalEditorDeps): Promise<string | undefined>;

package/dist/modes/interactive/external-editor.js

@@ -0,0 +1,39 @@
+/**
+ * 外部编辑器（计划审批框的「编辑计划」与「继续修改」）：`$VISUAL` → `$EDITOR` → `vi`（Windows `notepad`）。
+ * [W5-U] 编辑期间 TUI 挂起（交还终端），回来后整屏重画。临时文件在系统临时目录，读完即删。
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export function editorCommand(env, platform = process.platform) {
+    const configured = env["VISUAL"]?.trim() || env["EDITOR"]?.trim();
+    if (configured !== undefined && configured !== "")
+        return configured;
+    return platform === "win32" ? "notepad" : "vi";
+}
+function runEditor(command, file) {
+    // 编辑器变量常带参数（`code --wait`），交给 shell 拆；路径加引号
+    const result = spawnSync(`${command} "${file}"`, { stdio: "inherit", shell: true });
+    return result.status;
+}
+/** 在外部编辑器里改 `text`；编辑器非零退出或读不回来返回 undefined。 */
+export async function editExternally(text, name, deps) {
+    const dir = mkdtempSync(join(tmpdir(), "ama-edit-"));
+    const file = join(dir, name);
+    writeFileSync(file, text);
+    deps.suspend();
+    try {
+        const code = (deps.run ?? runEditor)(editorCommand(deps.env, deps.platform), file);
+        if (code !== 0)
+            return undefined;
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        deps.resume();
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

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

@@ -11,15 +11,23 @@
  * - 晚绑定：`runtime.approvals.setUiBroker`（审批对话框）与 `runtime.notifier.set`（宿主通知进消息区），
  *   退出时撤下。
  * - 键位：Enter 发送（运行中 = steer），其余应用级键位见 `key-dispatch.ts`。
+ * - 回滚（RW-C）：`/rewind` 与空闲双击 Esc 走 rewind-flow.ts；回填的原消息图片暂存，随下一条消息发送。
+ * - 底部（W5-A，status-area.ts）：`ui.statusLine` full 时状态栏上方多一行速率行；Ctrl+G / `/statusline`
+ *   切换（只影响本会话）。
+ * - 第五波（W5-U，agent-ui.ts）：计划审批框、子 Agent 折叠视图、`/tasks` `/agents` `/paste` 与 Ctrl+V、审批来源
+ *   标注与外部 Agent 首次运行的合并确认（approval-merge.ts）、harness 提示。
  * - 启动头按 `ui.quietStartup`（startup-header.ts）：normal 框 + 模型 / 目录 / 模式 / 资源清单（窄屏或
  *   `ui.compact` 去框），header 一行，silent 不输出。
  */
 import type { AgentSession } from "../../agent/types.js";
 import type { ModeContext } from "../../cli/deps.js";
 import type { Runtime } from "../../cli/runtime.js";
+import type { StatusLineMode } from "../../config/types.js";
+import type { ClipboardDeps } from "../../tools/clipboard-image.js";
 import { Editor, Keybindings, TUI, type Terminal, type Theme } from "../../tui.js";
 import { MessageView } from "./message-view.js";
-import { StatusBar } from "./status-bar.js";
+import { StatusArea } from "./status-area.js";
+import type { StatusBar } from "./status-bar.js";
 import { ToolTracker } from "./tool-view.js";
 export interface InteractiveModeOptions {
     /** 缺省 `ProcessTerminal`（测试注入 MemoryTerminal）。 */
@@ -32,8 +40,12 @@ export interface InteractiveModeOptions {
     spinnerIntervalMs?: number;
     /** 输入历史文件；false 不读写（缺省 `<dataDir>/history`）。 */
     historyFile?: string | false;
+    /** 底部布局（缺省按 `ui.statusLine`；测试固定）。 */
+    statusLine?: StatusLineMode;
     /** 界面就绪后回调（测试驱动用）。 */
     onReady?(handle: InteractiveHandle): void;
+    /** 剪贴板读取的注入（测试；缺省调系统命令）。 */
+    clipboard?: ClipboardDeps;
 }
 export interface InteractiveHandle {
     readonly tui: TUI;
@@ -41,6 +53,7 @@ export interface InteractiveHandle {
     readonly view: MessageView;
     readonly tools: ToolTracker;
     readonly status: StatusBar;
+    readonly area: StatusArea;
     session(): AgentSession;
     exit(code: number): void;
 }