@armadra/agent 0.4.0 → 0.5.1

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,11 +7,14 @@
  * - 交互模式自有命令：`/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 { PermissionMode } from "../../permissions/types.js";
 import type { Component, SelectItem, Theme } from "../../tui.js";
 import { type CommandInfo } from "../commands-core.js";
 import { type NoticeLevel } from "./message-view.js";
@@ -34,6 +37,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 +49,10 @@ export interface CommandUi {
     home?: string;
     /** 进程环境：给出时 /model 选择器按 fake-visibility 规则藏起测试供应商 fake。 */
     env?: Readonly<Record<string, string | undefined>>;
+    /** 切换权限模式前的确认（进入 Bypass 前弹确认框）；返回 false 保持原模式。 */
+    confirmMode?(mode: PermissionMode): boolean | Promise<boolean>;
+    /** [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,10 +7,13 @@
  * - 交互模式自有命令：`/tree`（同一文件内换叶子到选中消息之前，文本回填编辑器，可改后重发形成新分支）、
  *   `/permissions`（当前模式、判定顺序与已加载规则）；`/help` 追加这两条与按键说明。
  * - `/session`、`/cache`（无参数）与 `/permissions` 在消息区画左竖条面板（panels.ts），不再拍成文本。
+ * - `/rewind`（无参数）打开回滚列表与确认面板（rewind-flow.ts）；带参数走 commands-core，对话变了时
+ *   重画消息区并回填原消息。
  * - 不是命令（含模板与 `/skill:`）返回 false，调用方把整行当提示发出。
  */
 import { formatModelRef } from "../../ai/providers/channels.js";
 import { AgentSessionImpl } from "../../agent/session.js";
+import { THINKING_LEVELS } from "../../ai/thinking.js";
 import { listSessions } from "../../cli/compose-store.js";
 import { hideFakeProvider } from "../../cli/fake-visibility.js";
 import { AUTO_LAYER_TEXT, permissionModeLabel } from "../../permissions/modes.js";
@@ -27,8 +30,11 @@ export const ALL_COMMANDS = [...BUILTIN_COMMANDS, ...INTERACTIVE_COMMANDS];
 export const KEY_HINTS = [
     "Enter 发送（运行中 = 插话）  Alt+Enter 排到本轮之后  Shift+Enter / Ctrl+J 换行",
     "Esc 中断（排队消息回填编辑器）  Alt+↑ 取回最后一条排队消息",
-    "Shift+Tab 切换权限模式  Ctrl+L 模型  Ctrl+T 思考级别  Ctrl+O 展开工具输出与思考",
+    "空闲时 Esc Esc：输入框为空 = 回滚（/rewind），有字 = 清空（↑ 取回）",
+    "Shift+Tab / Tab（输入为空时）切换权限模式（进入 Bypass 前确认）  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) {
@@ -159,6 +165,11 @@ async function handlePick(what, ui) {
             if (picked === undefined)
                 return;
             const mode = picked.value;
+            const current = session.state.permissionMode;
+            if (mode !== current && ui.confirmMode !== undefined && !(await ui.confirmMode(mode))) {
+                ui.notice("info", `已取消，权限模式仍为 ${permissionModeLabel(current)}`);
+                return;
+            }
             session.setPermissionMode(mode);
             ui.notice("info", `权限模式：${permissionModeLabel(mode)}`);
             return;
@@ -171,6 +182,10 @@ async function handlePick(what, ui) {
                 title: "思考级别",
                 items: thinkingItems(reasoning),
                 selected: session.state.thinkingLevel,
+                currentValue: session.state.thinkingLevel,
+                filterable: false,
+                numberKeys: true,
+                footer: `↑↓ 选择 · 1-${THINKING_LEVELS.length} 直接选 · Enter 确认 · Esc 取消`,
             });
             if (picked !== undefined)
                 session.setThinkingLevel(picked.value);
@@ -184,10 +199,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) {
@@ -211,6 +232,7 @@ export async function runInteractiveCommand(line, ui) {
             runtime: ui.runtime,
             session: () => ui.session(),
             switchSession: (request) => ui.switchSession(request),
+            ...(ui.confirmMode !== undefined ? { confirmPermissionMode: ui.confirmMode } : {}),
         });
         if (result === undefined)
             return false;
@@ -225,12 +247,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/confirm-dialog.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 通用确认框：底部覆盖层 + `Box`，选项样式与审批对话框一致（终端界面视觉设计 v1 §3.11）。
+ *
+ * - 编号选项 `› 1. 进入 Bypass   y`，选中行 `›` + `selection` 底色，右侧按键提示 `dim`；
+ * - 按键：↑↓ 移动（循环）、Enter 确认、数字直选、选项按键提示里的单个字母直选（如 `y` / `n`）；
+ *   Esc / Ctrl+C / `tui.select.cancel` 取消（返回 undefined）；
+ * - 宽 < 56 列紧凑：去掉空行、按键提示只留第一个、底部提示缩短。字形取 `theme.glyphs`（ASCII 回退）。
+ *
+ * 用途：进入 Bypass permissions 前的确认（`confirmBypass`，permissions/bypass.ts）。
+ */
+import { type Component, type Focusable, type Keybindings, type OverlayHandle, type OverlayOptions, type SemanticColor, type Theme } from "../../tui.js";
+export interface ChoiceOption {
+    label: string;
+    /** 右侧按键提示（空格分隔）；其中的单个字母同时是直选键。 */
+    keys: string;
+}
+export interface ChoiceSpec {
+    title: string;
+    /** 正文（已着色），选项之上。 */
+    body: readonly string[];
+    options: readonly ChoiceOption[];
+    /** 缺省选中的下标。 */
+    selected?: number;
+    borderColor?: SemanticColor;
+}
+export interface ChoiceHost {
+    theme: Theme;
+    keybindings?: Keybindings;
+    showOverlay(component: Component, options: OverlayOptions): OverlayHandle;
+}
+export declare class ChoiceDialog implements Component, Focusable {
+    private readonly spec;
+    private readonly host;
+    private readonly done;
+    focused: boolean;
+    private selected;
+    constructor(spec: ChoiceSpec, host: Omit<ChoiceHost, "showOverlay">, done: (index: number | undefined) => void);
+    get selectedIndex(): number;
+    handleInput(data: string): void;
+    render(width: number): string[];
+    private optionLines;
+    invalidate(): void;
+}
+/** 打开确认框（底部覆盖层）：返回选中的下标，取消返回 undefined。 */
+export declare function openChoice(host: ChoiceHost, spec: ChoiceSpec): Promise<number | undefined>;
+/** Bypass 确认框的内容（缺省选中「取消」，边框 warning）。 */
+export declare function bypassChoiceSpec(theme: Theme): ChoiceSpec;
+/** 进入 Bypass 前问一次：选「进入 Bypass」返回 true，取消 / 选「取消」返回 false。 */
+export declare function confirmBypass(host: ChoiceHost): Promise<boolean>;

package/dist/modes/interactive/confirm-dialog.js

@@ -0,0 +1,121 @@
+/**
+ * 通用确认框：底部覆盖层 + `Box`，选项样式与审批对话框一致（终端界面视觉设计 v1 §3.11）。
+ *
+ * - 编号选项 `› 1. 进入 Bypass   y`，选中行 `›` + `selection` 底色，右侧按键提示 `dim`；
+ * - 按键：↑↓ 移动（循环）、Enter 确认、数字直选、选项按键提示里的单个字母直选（如 `y` / `n`）；
+ *   Esc / Ctrl+C / `tui.select.cancel` 取消（返回 undefined）；
+ * - 宽 < 56 列紧凑：去掉空行、按键提示只留第一个、底部提示缩短。字形取 `theme.glyphs`（ASCII 回退）。
+ *
+ * 用途：进入 Bypass permissions 前的确认（`confirmBypass`，permissions/bypass.ts）。
+ */
+import { BYPASS_CHOICES, BYPASS_CONFIRM_TITLE, BYPASS_DEFAULT_CHOICE, BYPASS_RISK_LINES, } from "../../permissions/bypass.js";
+import { Box, defaultKeybindings, matchesKey, padToWidth, truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "../../tui.js";
+/** 宽度低于它（Box 外宽）时用紧凑布局。 */
+const COMPACT_WIDTH = 56;
+export class ChoiceDialog {
+    spec;
+    host;
+    done;
+    focused = false;
+    selected;
+    constructor(spec, host, done) {
+        this.spec = spec;
+        this.host = host;
+        this.done = done;
+        this.selected = Math.max(0, Math.min(spec.options.length - 1, spec.selected ?? 0));
+    }
+    get selectedIndex() {
+        return this.selected;
+    }
+    handleInput(data) {
+        const keys = this.host.keybindings ?? defaultKeybindings;
+        const n = this.spec.options.length;
+        const letter = data.length === 1 ? data.toLowerCase() : "";
+        const byLetter = letter === "" || !/^[a-z]$/.test(letter)
+            ? -1
+            : this.spec.options.findIndex((o) => o.keys.split(/\s+/).includes(letter));
+        if (byLetter !== -1)
+            this.done(byLetter);
+        else if (matchesKey(data, "escape") ||
+            keys.matches(data, "app.clear") ||
+            keys.matches(data, "tui.select.cancel")) {
+            this.done(undefined);
+        }
+        else if (/^[1-9]$/.test(data) && Number(data) <= n)
+            this.done(Number(data) - 1);
+        else if (keys.matches(data, "tui.select.up"))
+            this.selected = (this.selected + n - 1) % n;
+        else if (keys.matches(data, "tui.select.down"))
+            this.selected = (this.selected + 1) % n;
+        else if (matchesKey(data, "enter"))
+            this.done(this.selected);
+    }
+    render(width) {
+        const { theme } = this.host;
+        const compact = width + 4 < COMPACT_WIDTH;
+        const lines = [];
+        for (const line of this.spec.body)
+            lines.push(...wrapTextWithAnsi(line, width));
+        if (!compact)
+            lines.push("");
+        lines.push(...this.optionLines(width, compact));
+        if (!compact)
+            lines.push("");
+        const g = theme.glyphs;
+        const arrows = g.arrowUp + g.arrowDown;
+        const n = this.spec.options.length;
+        lines.push(theme.fg("dim", compact
+            ? `${arrows} Enter · 1-${n} · Esc`
+            : `${arrows} 选择 · Enter 确认 · 1-${n} 直接选 · Esc 取消`));
+        return lines.map((l) => truncateToWidth(l, width));
+    }
+    optionLines(width, compact) {
+        const { theme } = this.host;
+        const g = theme.glyphs;
+        const shown = this.spec.options.map((o) => (compact ? o.keys.split(/\s+/)[0] : o.keys));
+        const keyWidth = Math.max(...shown.map((k) => visibleWidth(k)));
+        return this.spec.options.map((option, i) => {
+            const selected = i === this.selected;
+            const left = `${selected ? g.prompt : " "} ${i + 1}. ${option.label}`;
+            const right = padToWidth(shown[i], keyWidth);
+            const room = Math.max(1, width - keyWidth - 1);
+            const label = selected ? theme.fg("accent", theme.bold(left)) : left;
+            const line = padToWidth(truncateToWidth(label, room), room) + " " + theme.fg("dim", right);
+            return selected ? theme.bg("selection", line) : line;
+        });
+    }
+    invalidate() { }
+}
+/** 打开确认框（底部覆盖层）：返回选中的下标，取消返回 undefined。 */
+export function openChoice(host, spec) {
+    return new Promise((resolve) => {
+        let handle;
+        let settled = false;
+        const dialog = new ChoiceDialog(spec, host, (index) => {
+            if (settled)
+                return;
+            settled = true;
+            handle?.hide();
+            resolve(index);
+        });
+        handle = host.showOverlay(new Box(dialog, {
+            title: spec.title,
+            theme: host.theme,
+            ...(spec.borderColor !== undefined ? { borderColor: spec.borderColor } : {}),
+        }), { anchor: "bottom" });
+    });
+}
+/** Bypass 确认框的内容（缺省选中「取消」，边框 warning）。 */
+export function bypassChoiceSpec(theme) {
+    return {
+        title: BYPASS_CONFIRM_TITLE,
+        body: BYPASS_RISK_LINES.map((line, i) => (i === 0 ? theme.fg("warning", line) : line)),
+        options: BYPASS_CHOICES,
+        selected: BYPASS_DEFAULT_CHOICE,
+        borderColor: "warning",
+    };
+}
+/** 进入 Bypass 前问一次：选「进入 Bypass」返回 true，取消 / 选「取消」返回 false。 */
+export async function confirmBypass(host) {
+    return (await openChoice(host, bypassChoiceSpec(host.theme))) === 0;
+}

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>;