@armadra/agent 0.3.0 → 0.5.0

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

@@ -1,20 +1,30 @@
 /**
  * 审批对话框（设计 §12.6）：模式层的 UI `ApprovalBroker`，底部覆盖层。[B7]
  *
- * - 标题行：`[task]`（`request.context.depth > 0`，子 Agent 发起）+ 工具名 + 原因标签；
+ * - 标题行：来源标注 + 工具名 + 原因标签。来源（W5-U）：外部 Agent 的请求（`context.origin`）标
+ *   `[claude · 会话 abc12345]`，正文取 `origin.toolCall` 的标题 / 种类 / 路径；task 子 Agent（`depth > 0`）标
+ *   `[task:<agent>]`（类型名经 `ApprovalHost.taskAgent` 查注册表，查不到为 `[task]`）；外部 Agent 首次运行确认
+ *   （`toolName: "task"` 且输入带 `note`）标题为「首次运行外部 Agent」，正文是说明与模式；选项始终是
+ *   允许 / 本会话允许 / 拒绝三项（外部 Agent 的 `reject_always` 不由这里选）；
  * - 输入：bash 显示命令全文，write 显示路径与行数，edit 显示路径与每处修改的 −/+ 摘要，其它显示
  *   一行摘要；`v` 展开 / 收起完整输入（JSON）；
  * - 执行前预览（W3-B9a-2，`request.preview`）：输入摘要之后列出会碰到的路径与规模，danger 红、
  *   warn 黄、info 暗色；`other` 类预览与输入摘要重复，不显示；
  * - 原因：mode（当前权限模式需要确认）/ dangerous / hook + Hook 给的文本；
- * - 按键：`y` 允许、`n` / Esc / Ctrl+C 拒绝、`a` 本会话允许同类；
+ * - 选项（终端界面视觉设计 v1 §3.11）：编号列表 `1. 允许  y` / `2. 本会话允许同类  a` / `3. 拒绝  n Esc`，
+ *   选中行 `›` + selection 底色；缺省选中：危险命令 → 拒绝，其余 → 允许。按键 `y / a / n / Esc / Ctrl+C /
+ *   1 2 3 / ↑↓ Enter / v` 都有效；
+ * - 标题按原因：需要确认 / 危险命令 / Hook 要求确认（子 Agent 发起前缀 `[task] `）；边框颜色随预览严重度
+ *   （danger error、warn warning）；宽 < 56 时紧凑：工具名单独一行、去掉空行、按键提示缩短；
  * - 超时与中断：broker 链在超时（缺省 10 分钟）或运行被中断时 abort `signal`，对话框关闭并返回
  *   undefined（链按 deny 处理），消息区留一行说明。
  *
  * broker 链本身串行化审批，所以同一时刻最多一个对话框。
  */
+import { AUTO_LAYER_TEXT, isPermissionMode, permissionModeLabel } from "../../permissions/modes.js";
 import { previewDisplayLines } from "../../permissions/preview.js";
-import { Box, Container, Text, defaultKeybindings, matchesKey, truncateToWidth, } from "../../tui.js";
+import { Box, defaultKeybindings, matchesKey, padToWidth, truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "../../tui.js";
+import { displayPath, flat } from "./tool-summary.js";
 import { toolSummary } from "./tool-view.js";
 const COMMAND_LINES = 8;
 const EDIT_LINES = 3;
@@ -28,19 +38,83 @@ function lines(text, max) {
 function record(input) {
     return typeof input === "object" && input !== null ? input : {};
 }
-/** 对话框正文（不含按键行）。 */
+/** 外部 Agent 首次运行确认（`requestApproval` 发来的 `task` 请求，输入带 `note`）。 */
+export function isFirstRunRequest(request) {
+    return request.toolName === "task" && typeof record(request.input)["note"] === "string";
+}
+/** 来源标注：`[claude · 会话 abc12345]` / `[task:explore]` / `[task]`；主会话发起为 undefined。 */
+export function sourceLabel(request, taskAgent) {
+    const context = request.context;
+    const origin = context?.origin;
+    if (origin !== undefined)
+        return `[${origin.agent} · 会话 ${origin.sessionId.slice(0, 8)}]`;
+    if ((context?.depth ?? 0) <= 0)
+        return undefined;
+    const taskId = context?.taskId;
+    const agent = taskId === undefined ? undefined : taskAgent?.(taskId);
+    return agent === undefined ? "[task]" : `[task:${agent}]`;
+}
+/** 原因 → 标题文字（带来源标注）。 */
+export function approvalTitle(request, taskAgent) {
+    const label = sourceLabel(request, taskAgent);
+    const reason = isFirstRunRequest(request)
+        ? "首次运行外部 Agent"
+        : request.reason === "dangerous"
+            ? "危险命令"
+            : request.reason === "hook"
+                ? "Hook 要求确认"
+                : "需要确认";
+    return label === undefined ? reason : `${label} ${reason}`;
+}
+/** 外部 Agent 请求的正文：标题 + 种类、涉及路径、输入摘要。 */
+function originLines(origin, theme, cwd) {
+    const out = [];
+    for (const path of (origin.toolCall.locations ?? []).slice(0, 3))
+        out.push(theme.fg("muted", displayPath(path, cwd)));
+    const hidden = (origin.toolCall.locations?.length ?? 0) - 3;
+    if (hidden > 0)
+        out.push(theme.fg("dim", `… 另 ${hidden} 个路径`));
+    const summary = origin.toolCall.inputSummary;
+    if (summary !== undefined && summary.trim() !== "") {
+        const { shown, hidden: more } = lines(summary, COMMAND_LINES);
+        out.push(...shown.map((l) => theme.fg("code", l)));
+        if (more > 0)
+            out.push(theme.fg("dim", `… 另 ${more} 行`));
+    }
+    return out;
+}
+/** 对话框正文（不含选项与按键行）。 */
 export function describeRequest(request, theme, options = {}) {
     const out = [];
-    const task = (request.context?.depth ?? 0) > 0 ? theme.fg("warning", "[task] ") : "";
+    const label = sourceLabel(request, options.taskAgent);
+    const task = label === undefined ? "" : theme.fg("warning", `${label} `);
+    const origin = request.context?.origin;
+    const firstRun = isFirstRunRequest(request);
     const tag = request.reason === "dangerous"
         ? theme.fg("error", "危险命令")
         : request.reason === "hook"
             ? theme.fg("warning", "Hook 要求确认")
-            : theme.fg("dim", "需要确认");
-    out.push(`${task}${theme.bold(theme.fg("tool", request.toolName))}  ${tag}`);
+            : origin !== undefined
+                ? theme.fg("dim", origin.toolCall.kind)
+                : theme.fg("dim", firstRun ? "首次运行" : "需要确认");
     const input = record(request.input);
+    const name = origin !== undefined
+        ? theme.bold(theme.fg("tool", flat(origin.toolCall.title)))
+        : firstRun
+            ? theme.bold(theme.fg("tool", `task ${String(input["agent"] ?? "")}`.trim()))
+            : theme.bold(theme.fg("tool", request.toolName));
+    out.push(options.compact === true ? `${task}${name}` : `${task}${name}  ${tag}`);
     const more = (n) => theme.fg("dim", `… 另 ${n} 行（v 查看）`);
-    if (options.expanded === true) {
+    if (origin !== undefined && options.expanded !== true) {
+        out.push(...originLines(origin, theme, options.cwd));
+    }
+    else if (firstRun && options.expanded !== true) {
+        out.push(String(input["note"]));
+        const mode = input["mode"];
+        if (typeof mode === "string")
+            out.push(theme.fg("dim", `模式 ${isPermissionMode(mode) ? permissionModeLabel(mode) : mode}`));
+    }
+    else if (options.expanded === true) {
         const json = JSON.stringify(request.input, null, 2) ?? String(request.input);
         const { shown, hidden } = lines(json, FULL_INPUT_LINES);
         out.push(...shown.map((l) => theme.fg("code", l)));
@@ -80,46 +154,60 @@ export function describeRequest(request, theme, options = {}) {
         const summary = toolSummary(request.toolName, input, options.cwd);
         if (summary !== "")
             out.push(summary);
+        const agent = input["agent"];
+        const runner = request.toolName === "task" && typeof agent === "string"
+            ? options.externalRunner?.(agent)
+            : undefined;
+        // 与首次运行确认合并（approval-merge.ts）：允许即同意本会话以你的登录运行该 CLI
+        if (runner !== undefined)
+            out.push(theme.fg("warning", `外部 Agent ${agent}：以你在 ${runner} CLI 的登录运行（含本会话首次运行确认）`));
     }
     const severity = request.preview?.severity;
     const color = severity === "danger" ? "error" : severity === "warn" ? "warning" : "dim";
     out.push(...previewDisplayLines(request.preview).map((l) => theme.fg(color, l)));
-    if (request.reason === "hook") {
+    const auto = request.autoDecision;
+    if (origin !== undefined || firstRun) {
+        // 外部 Agent 的请求由它自己的策略决定要问；首次运行确认的说明已在正文
+        if (origin !== undefined)
+            out.push(theme.fg("dim", `${origin.agent} 请求确认`));
+        else
+            out.push(theme.fg("dim", "本会话首次以你的登录运行该 CLI"));
+    }
+    else if (request.reason === "hook") {
         out.push(theme.fg("warning", `Hook：${request.hookReason ?? "（无说明）"}`));
     }
     else if (request.reason === "dangerous") {
         out.push(theme.fg("error", "这条命令可能有破坏性，请确认"));
     }
+    else if (auto !== undefined) {
+        out.push(theme.fg("warning", `Auto ${AUTO_LAYER_TEXT[auto.layer]}：${auto.reason}`));
+    }
     else if (options.permissionMode !== undefined) {
-        out.push(theme.fg("dim", `权限模式 ${options.permissionMode} 下需要确认`));
+        const mode = options.permissionMode;
+        const label = isPermissionMode(mode) ? permissionModeLabel(mode) : mode;
+        out.push(theme.fg("dim", `权限模式 ${label} 下需要确认`));
     }
     return out;
 }
-export const APPROVAL_KEYS_HINT = "[y] 允许  [n] 拒绝  [a] 本会话允许同类  [v] 完整输入";
+export const APPROVAL_OPTIONS = [
+    { decision: "allow", label: "允许", keys: "y" },
+    { decision: "allow_session", label: "本会话允许同类", keys: "a" },
+    { decision: "deny", label: "拒绝", keys: "n Esc" },
+];
+/** 宽度低于它（Box 外宽）时用紧凑布局。 */
+const COMPACT_WIDTH = 56;
 class ApprovalDialog {
     request;
     host;
     decide;
     focused = false;
     expanded = false;
-    body = new Container();
+    selected;
     constructor(request, host, decide) {
         this.request = request;
         this.host = host;
         this.decide = decide;
-        this.rebuild();
-    }
-    rebuild() {
-        const { theme } = this.host;
-        this.body.clear();
-        const options = {
-            permissionMode: this.host.permissionMode(),
-            expanded: this.expanded,
-        };
-        if (this.host.cwd !== undefined)
-            options.cwd = this.host.cwd;
-        this.body.addChild(new Text(describeRequest(this.request, theme, options).join("\n")));
-        this.body.addChild(new Text(theme.fg("accent", APPROVAL_KEYS_HINT)));
+        this.selected = request.reason === "dangerous" ? 2 : 0;
     }
     handleInput(data) {
         const keys = this.host.keybindings ?? defaultKeybindings;
@@ -134,17 +222,78 @@ class ApprovalDialog {
             keys.matches(data, "tui.select.cancel")) {
             this.decide("deny");
         }
-        else if (key === "v") {
-            this.expanded = !this.expanded;
-            this.rebuild();
+        else if (/^[1-3]$/.test(data))
+            this.decide(APPROVAL_OPTIONS[Number(data) - 1].decision);
+        else if (keys.matches(data, "tui.select.up")) {
+            this.selected = (this.selected + APPROVAL_OPTIONS.length - 1) % APPROVAL_OPTIONS.length;
         }
+        else if (keys.matches(data, "tui.select.down")) {
+            this.selected = (this.selected + 1) % APPROVAL_OPTIONS.length;
+        }
+        else if (matchesKey(data, "enter"))
+            this.decide(APPROVAL_OPTIONS[this.selected].decision);
+        else if (key === "v")
+            this.expanded = !this.expanded;
     }
+    /** `width` 是 Box 内宽；紧凑与否按外宽（+ 4）判断。 */
     render(width) {
-        return this.body.render(width).map((l) => truncateToWidth(l, width));
+        const { theme } = this.host;
+        const compact = width + 4 < COMPACT_WIDTH;
+        const options = {
+            permissionMode: this.host.permissionMode(),
+            expanded: this.expanded,
+            compact,
+        };
+        if (this.host.cwd !== undefined)
+            options.cwd = this.host.cwd;
+        if (this.host.taskAgent !== undefined)
+            options.taskAgent = this.host.taskAgent;
+        if (this.host.externalRunner !== undefined)
+            options.externalRunner = this.host.externalRunner;
+        const body = describeRequest(this.request, theme, options);
+        const lines = [];
+        // 输入摘要（标题 + 命令）与预览 / 原因之间空一行
+        const head = this.inputLines(body);
+        for (const line of body.slice(0, head))
+            lines.push(...wrapTextWithAnsi(line, width));
+        if (!compact && head < body.length)
+            lines.push("");
+        for (const line of body.slice(head))
+            lines.push(...wrapTextWithAnsi(line, width));
+        if (!compact)
+            lines.push("");
+        lines.push(...this.optionLines(width, compact));
+        if (!compact)
+            lines.push("");
+        const arrows = theme.glyphs.arrowUp + theme.glyphs.arrowDown;
+        const hint = compact
+            ? `${arrows} Enter · v 完整输入`
+            : `${arrows} 选择 · Enter 确认 · v 完整输入`;
+        lines.push(theme.fg("dim", hint));
+        return lines.map((l) => truncateToWidth(l, width));
+    }
+    /** 正文里属于「输入摘要」的行数（首行 + 命令 / 路径 / 修改摘要，止于预览或原因行）。 */
+    inputLines(body) {
+        const preview = previewDisplayLines(this.request.preview).length;
+        const reasonLines = body.length > 0 ? 1 : 0;
+        return Math.max(1, body.length - preview - reasonLines);
     }
-    invalidate() {
-        this.body.invalidate();
+    optionLines(width, compact) {
+        const { theme } = this.host;
+        const g = theme.glyphs;
+        const keyWidth = compact ? 1 : Math.max(...APPROVAL_OPTIONS.map((o) => o.keys.length));
+        return APPROVAL_OPTIONS.map((option, i) => {
+            const selected = i === this.selected;
+            const keys = compact ? option.keys.slice(0, 1) : option.keys;
+            const left = `${selected ? g.prompt : " "} ${i + 1}. ${option.label}`;
+            const right = keys.padEnd(keyWidth);
+            const room = Math.max(1, width - visibleWidth(right) - 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() { }
 }
 /** UI broker：每个请求开一个底部覆盖层，等用户按键或 signal abort。 */
 export class ApprovalDialogBroker {
@@ -177,18 +326,26 @@ export class ApprovalDialogBroker {
             const dialog = new ApprovalDialog(request, this.host, settle);
             this.open++;
             this.host.onOpen?.();
+            const severity = request.preview?.severity;
             handle = this.host.showOverlay(new Box(dialog, {
-                title: (request.context?.depth ?? 0) > 0 ? "子任务审批" : "审批",
+                title: approvalTitle(request, this.host.taskAgent),
                 theme: this.host.theme,
+                ...(severity === "danger"
+                    ? { borderColor: "error" }
+                    : severity === "warn"
+                        ? { borderColor: "warning" }
+                        : {}),
             }));
             signal.addEventListener("abort", onAbort, { once: true });
         });
     }
 }
 /** 结果的一行说明（消息区）。 */
-export function approvalOutcomeText(request, outcome) {
-    const task = (request.context?.depth ?? 0) > 0 ? "[task] " : "";
-    const what = `${task}${request.toolName}`;
+export function approvalOutcomeText(request, outcome, taskAgent) {
+    const label = sourceLabel(request, taskAgent);
+    const origin = request.context?.origin;
+    const tool = origin !== undefined ? flat(origin.toolCall.title, 60) : request.toolName;
+    const what = `${label === undefined ? "" : `${label} `}${tool}`;
     switch (outcome) {
         case "allow":
             return `已允许 ${what}`;

package/dist/modes/interactive/approval-merge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 type { ApprovalBroker, ApprovalDecision, ApprovalRequest } from "../../permissions/types.js";
+export declare const MERGE_WINDOW_MS = 60000;
+export interface FirstRunMergeDeps {
+    sessionId(): string;
+    now?(): number;
+    /** 类型名 → runner（`ama` / `claude` / …）；缺省查会话的类型表。 */
+    runnerOf?(agent: string): string | undefined;
+    /** 任务 id → 类型名与建立时刻；缺省查注册表。 */
+    taskOf?(taskId: string): {
+        agent: string;
+        startedAt: number;
+    } | undefined;
+    windowMs?: number;
+}
+export declare class FirstRunMerge {
+    private readonly deps;
+    private pending;
+    constructor(deps: FirstRunMergeDeps);
+    private now;
+    /** `task` 调用的 agent 是外部 Agent 时返回它的 runner。 */
+    externalRunner(agent: string): string | undefined;
+    private taskOf;
+    /** 请求到来：命中合并返回 `allow`（不弹框）；否则返回 undefined，并作废记录。 */
+    intercept(request: ApprovalRequest): ApprovalDecision | undefined;
+    /** 用户答复之后：允许了外部 Agent 的 task 调用就记下。 */
+    record(request: ApprovalRequest, decision: ApprovalDecision | undefined): void;
+}
+/** 把合并规则套在界面 broker 外面；自动答复时调 `onMerged`（消息区一行说明）。 */
+export declare function mergingBroker(inner: ApprovalBroker, merge: FirstRunMerge, onMerged?: (request: ApprovalRequest) => void): ApprovalBroker;

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

@@ -2,16 +2,19 @@
  * 交互模式的斜杠命令：把 commands-core 的 `CommandResult` 变成界面动作。[B7]
  *
  * - `handled` → 消息区显示文本；`prompt` → 发提示；`exit` → 退出；
- * - `pick` → 打开对应选择器：模型（setModel）、会话（resume）、树（/fork 无参数：从选中的用户消息
+ * - `pick` → 打开对应选择器：模型（setModel；不列测试供应商 fake，`AMA_SHOW_FAKE=1` 或 `AMA_FAKE_SCRIPT` 时照列）、会话（resume）、树（/fork 无参数：从选中的用户消息
  *   之前分叉，消息文本回填编辑器）、权限模式、思考级别；
  * - 交互模式自有命令：`/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 { SelectItem } from "../../tui.js";
+import type { Component, SelectItem, Theme } from "../../tui.js";
 import { type CommandInfo } from "../commands-core.js";
 import { type NoticeLevel } from "./message-view.js";
 import { type PickerSpec } from "./pickers.js";
@@ -26,13 +29,27 @@ export interface CommandUi {
     switchSession(request: SwitchRequest): Promise<AgentSession>;
     pick(spec: PickerSpec): Promise<SelectItem | undefined>;
     notice(level: NoticeLevel, text: string): void;
+    /** 消息区面板（/session、/cache、/permissions）；缺省回落为文本通知。 */
+    panel?(component: Component): void;
     setEditorText(text: string): void;
     /** 发一条提示（不等运行结束）。 */
     prompt(text: string): void;
     /** /tree 换叶子后重画消息区。 */
     reload(): void;
+    /** 回滚列表与确认面板（`/rewind` 无参数）；没有时回落为文字列表。 */
+    rewind?(): Promise<void>;
+    /** 回填原消息（文本 + 图片）；缺省只回填文本。 */
+    setDraft?(draft: RewindDraftText): void;
     exit(code: number): void;
     now(): number;
+    /** 面板用的主题（与 panel 一起提供）。 */
+    theme?(): Theme;
+    /** 家目录（面板里路径缩写为 ~）。 */
+    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>;