@armadra/agent 0.3.0 → 0.5.0

package/dist/modes/interactive/agent-ui.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 交互界面的第五波接线（计划审批、子 Agent、外部 Agent、剪贴板图片、harness 提示），从 interactive-mode.ts
+ * 拆出来，保持装配文件在 600 行以内。[W5-U]
+ *
+ * - 事件：`subagent_start / update / end` → 折叠视图（subagent-view.ts）并刷新对应的 task 工具行，后台任务
+ *   结束给一行提示；`limit_reached`、`model_fallback`、`background_job` → 一行友好提示。
+ * - 会话：`attach(session)` 接管计划审批（plan-flow.ts）、把外部 Agent 的 notice 转到消息区。
+ * - 命令：`/plan`（无参数：面板，有待审批的计划时打开审批框）、`/tasks`（无参数：选择任务，查看输出或停止）、
+ *   `/agents`、`/paste`；其余参数形式交给 commands-core（与 line 模式同一语义）。
+ * - `Ctrl+V` / `/paste`：剪贴板图片写进数据目录，输入框光标处插入 `@<路径>`。
+ *
+ * 外部 Agent 的 notice（W5-E runner 的 `{type:"notice"}`）由任务注册表写进会话日志（`[task tN] …`），没有
+ * 事件；这里在会话的 `options.log` 外面套一层，只把这类行转到消息区，其余照原样写日志。
+ */
+import type { AgentSession, SessionEvent } from "../../agent/types.js";
+import type { SwitchRequest } from "../../cli/compose-session.js";
+import type { ClipboardDeps } from "../../tools/clipboard-image.js";
+import type { Component, Editor, TUI, Theme } from "../../tui.js";
+import { FirstRunMerge } from "./approval-merge.js";
+import type { NoticeLevel } from "./message-view.js";
+import type { PickerSpec } from "./pickers.js";
+import { PlanFlow } from "./plan-flow.js";
+import type { PlanDialogHost } from "./plan-dialog.js";
+import { SubagentTracker } from "./subagent-view.js";
+import type { ToolTracker } from "./tool-view.js";
+export interface AgentUiDeps {
+    theme: Theme;
+    tui: TUI;
+    editor: Editor;
+    tools(): ToolTracker;
+    subagents: SubagentTracker;
+    session(): AgentSession;
+    dataDir: string;
+    env: Readonly<Record<string, string | undefined>>;
+    now(): number;
+    notice(level: NoticeLevel, text: string): void;
+    panel(component: Component): void;
+    pick(spec: PickerSpec): Promise<{
+        value: string;
+    } | undefined>;
+    hint(text: string): void;
+    render(): void;
+    switchSession(request: SwitchRequest): Promise<AgentSession>;
+    prompt(text: string): void;
+    dialog: Omit<PlanDialogHost, "editExternal" | "render">;
+    /** 路径显示（缩写家目录）。 */
+    displayPath(path: string): string;
+    /** 剪贴板读取的注入（测试）。 */
+    clipboard?: ClipboardDeps;
+}
+export declare class AgentUi {
+    private readonly deps;
+    readonly plan: PlanFlow;
+    readonly merge: FirstRunMerge;
+    private restoreLog;
+    /** 后台子 Agent 运行中：每秒重画跟随行的耗时（主会话空闲时 Loader 不转）。 */
+    private ticker;
+    constructor(deps: AgentUiDeps);
+    /** 新会话（启动、/new /resume /fork）：接管计划审批，转发外部 Agent notice。 */
+    attach(session: AgentSession): void;
+    detach(): void;
+    private followBackground;
+    private stopTicker;
+    private routeNotices;
+    /** 返回 true：事件已处理（调用方只需重画）。 */
+    onEvent(event: SessionEvent): boolean;
+    /** 交互界面自己处理的第五波命令；不是返回 false。 */
+    command(name: string, args: string): Promise<boolean>;
+    private showPlan;
+    private tasks;
+    /** `Ctrl+V` / `/paste`：光标处插入 `@<路径>`。 */
+    paste(): Promise<void>;
+}

package/dist/modes/interactive/agent-ui.js

@@ -0,0 +1,234 @@
+/**
+ * 交互界面的第五波接线（计划审批、子 Agent、外部 Agent、剪贴板图片、harness 提示），从 interactive-mode.ts
+ * 拆出来，保持装配文件在 600 行以内。[W5-U]
+ *
+ * - 事件：`subagent_start / update / end` → 折叠视图（subagent-view.ts）并刷新对应的 task 工具行，后台任务
+ *   结束给一行提示；`limit_reached`、`model_fallback`、`background_job` → 一行友好提示。
+ * - 会话：`attach(session)` 接管计划审批（plan-flow.ts）、把外部 Agent 的 notice 转到消息区。
+ * - 命令：`/plan`（无参数：面板，有待审批的计划时打开审批框）、`/tasks`（无参数：选择任务，查看输出或停止）、
+ *   `/agents`、`/paste`；其余参数形式交给 commands-core（与 line 模式同一语义）。
+ * - `Ctrl+V` / `/paste`：剪贴板图片写进数据目录，输入框光标处插入 `@<路径>`。
+ *
+ * 外部 Agent 的 notice（W5-E runner 的 `{type:"notice"}`）由任务注册表写进会话日志（`[task tN] …`），没有
+ * 事件；这里在会话的 `options.log` 外面套一层，只把这类行转到消息区，其余照原样写日志。
+ */
+import { taskRegistryView } from "../../agent/subagent-registry.js";
+import { planController } from "../../plan/controller.js";
+import { agentsPanel, planPanel, taskOutputPanel } from "./agent-panels.js";
+import { FirstRunMerge } from "./approval-merge.js";
+import { pasteImage } from "./clipboard-paste.js";
+import { backgroundJobText, limitReachedText, modelFallbackText } from "./event-notices.js";
+import { editExternally } from "./external-editor.js";
+import { PlanFlow } from "./plan-flow.js";
+import { backgroundEndText, SubagentTracker } from "./subagent-view.js";
+import { listTasks, stopTask, taskLine, taskOutput } from "./tasks-report.js";
+const TASK_NOTICE = /^\[task (t\d+)\] ([\s\S]*)$/;
+export class AgentUi {
+    deps;
+    plan;
+    merge;
+    restoreLog;
+    /** 后台子 Agent 运行中：每秒重画跟随行的耗时（主会话空闲时 Loader 不转）。 */
+    ticker;
+    constructor(deps) {
+        this.deps = deps;
+        this.merge = new FirstRunMerge({ sessionId: () => deps.session().state.sessionId });
+        this.plan = new PlanFlow({
+            dialog: {
+                ...deps.dialog,
+                displayPath: (path) => deps.displayPath(path),
+                render: () => deps.render(),
+                editExternal: (text, kind) => editExternally(text, kind === "plan" ? "plan.md" : "feedback.md", {
+                    env: deps.env,
+                    suspend: () => deps.tui.stop(),
+                    resume: () => {
+                        deps.tui.start();
+                        deps.tui.forceFullRedraw();
+                    },
+                }),
+            },
+            switchSession: (request) => deps.switchSession(request),
+            notice: (level, text) => deps.notice(level, text),
+            prompt: (text) => deps.prompt(text),
+        });
+    }
+    /** 新会话（启动、/new /resume /fork）：接管计划审批，转发外部 Agent notice。 */
+    attach(session) {
+        this.deps.subagents.clear();
+        this.stopTicker();
+        this.plan.attach(session);
+        this.routeNotices(session);
+    }
+    detach() {
+        this.restoreLog?.();
+        this.restoreLog = undefined;
+        this.stopTicker();
+    }
+    followBackground() {
+        const running = this.deps.subagents.running().filter((s) => s.background);
+        if (running.length === 0)
+            return this.stopTicker();
+        if (this.ticker !== undefined)
+            return;
+        this.ticker = setInterval(() => {
+            const live = this.deps.subagents.running().filter((s) => s.background);
+            if (live.length === 0)
+                return this.stopTicker();
+            for (const state of live)
+                this.deps.tools().get(state.parentToolCallId)?.refresh();
+            this.deps.render();
+        }, 1000);
+        this.ticker.unref?.();
+    }
+    stopTicker() {
+        if (this.ticker !== undefined)
+            clearInterval(this.ticker);
+        this.ticker = undefined;
+    }
+    routeNotices(session) {
+        this.detach();
+        const holder = session.options;
+        if (holder === undefined)
+            return;
+        const original = holder.log;
+        const routed = (level, message) => {
+            const match = TASK_NOTICE.exec(message);
+            if (match !== null && (level === "info" || level === "warn")) {
+                const taskId = match[1];
+                const agent = taskRegistryView(session.state.sessionId)?.get(taskId)?.agent ?? "task";
+                this.deps.notice(level === "warn" ? "warn" : "info", `[${agent} · ${taskId}] ${match[2]}`);
+                return;
+            }
+            original?.call(holder, level, message);
+        };
+        holder.log = routed;
+        this.restoreLog = () => {
+            if (holder.log !== routed)
+                return;
+            if (original === undefined)
+                delete holder.log;
+            else
+                holder.log = original;
+        };
+    }
+    /** 返回 true：事件已处理（调用方只需重画）。 */
+    onEvent(event) {
+        switch (event.type) {
+            case "subagent_start":
+            case "subagent_update":
+            case "subagent_end": {
+                const state = this.deps.subagents.onEvent(event);
+                if (state === undefined)
+                    return true;
+                this.deps.tools().get(state.parentToolCallId)?.refresh();
+                // 后台任务：完成时 <task-notification> 那一行就是提示；失败 / 停止另给一行
+                if (event.type === "subagent_end" && state.background && state.status !== "completed")
+                    this.deps.notice("warn", backgroundEndText(state));
+                this.followBackground();
+                return true;
+            }
+            case "limit_reached":
+                this.deps.notice("warn", limitReachedText(event));
+                return true;
+            case "model_fallback":
+                this.deps.notice("warn", modelFallbackText(event));
+                return false;
+            case "background_job":
+                this.deps.notice("info", backgroundJobText(event));
+                return true;
+            default:
+                return false;
+        }
+    }
+    /** 交互界面自己处理的第五波命令；不是返回 false。 */
+    async command(name, args) {
+        if (args !== "")
+            return false;
+        switch (name) {
+            case "plan":
+                await this.showPlan();
+                return true;
+            case "tasks":
+                await this.tasks();
+                return true;
+            case "agents":
+                this.deps.panel(agentsPanel(this.deps.session().state.sessionId, this.deps.theme));
+                return true;
+            case "paste":
+                await this.paste();
+                return true;
+            default:
+                return false;
+        }
+    }
+    async showPlan() {
+        const session = this.deps.session();
+        const controller = planController(session);
+        if (controller === undefined) {
+            this.deps.notice("info", "当前会话没有 Plan 能力");
+            return;
+        }
+        this.deps.panel(planPanel(controller, session, this.deps.theme, this.deps.displayPath));
+        const pending = controller.pending();
+        if (pending !== undefined && !session.state.isStreaming)
+            await this.plan.ask(session, pending);
+    }
+    async tasks() {
+        const sessionId = this.deps.session().state.sessionId;
+        const tasks = listTasks(sessionId);
+        if (tasks.length === 0) {
+            this.deps.notice("info", "还没有子 Agent 任务");
+            return;
+        }
+        const now = this.deps.now();
+        const picked = await this.deps.pick({
+            title: "子 Agent 任务",
+            items: [...tasks]
+                .reverse()
+                .map((task) => ({ value: task.taskId, label: taskLine(task, now) })),
+            footer: "↑↓ 选择 · Enter 查看 · Esc 取消",
+        });
+        if (picked === undefined)
+            return;
+        const task = taskRegistryView(sessionId)?.get(picked.value);
+        if (task === undefined)
+            return;
+        if (task.status === "running") {
+            const action = await this.deps.pick({
+                title: `任务 ${task.taskId}`,
+                items: [
+                    { value: "output", label: "查看已有输出" },
+                    { value: "stop", label: "停止任务" },
+                ],
+                numberKeys: true,
+            });
+            if (action === undefined)
+                return;
+            if (action.value === "stop") {
+                await stopTask(sessionId, task.taskId);
+                this.deps.notice("info", `已停止 ${task.taskId}`);
+                return;
+            }
+        }
+        const fresh = taskRegistryView(sessionId)?.get(task.taskId) ?? task;
+        const output = taskOutput(sessionId, task.taskId);
+        const { theme, displayPath } = this.deps;
+        this.deps.panel(taskOutputPanel(fresh, output, theme, this.deps.now(), displayPath));
+    }
+    /** `Ctrl+V` / `/paste`：光标处插入 `@<路径>`。 */
+    async paste() {
+        this.deps.hint("读取剪贴板…");
+        const pasted = await pasteImage(this.deps.dataDir, this.deps.clipboard);
+        if (!pasted.ok) {
+            this.deps.hint("");
+            this.deps.notice("info", pasted.message);
+            return;
+        }
+        const editor = this.deps.editor;
+        const before = editor.getText();
+        const lead = before === "" || /\s$/.test(before) ? "" : " ";
+        editor.insertText(`${lead}${pasted.ref} `);
+        this.deps.hint("已插入剪贴板图片");
+        this.deps.render();
+    }
+}

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

@@ -1,13 +1,21 @@
 /**
  * 审批对话框（设计 §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 处理），消息区留一行说明。
  *
@@ -17,6 +25,10 @@ import type { ApprovalBroker, ApprovalDecision, ApprovalRequest } from "../../pe
 import { type Component, type Keybindings, type OverlayHandle, type Theme } from "../../tui.js";
 export interface ApprovalHost {
     theme: Theme;
+    /** task 子 Agent 的类型名（`[task:<agent>]`）；查不到返回 undefined。 */
+    taskAgent?(taskId: string): string | undefined;
+    /** `task` 调用的 agent 是外部 Agent 时返回 runner（见 approval-merge.ts）。 */
+    externalRunner?(agent: string): string | undefined;
     keybindings?: Keybindings;
     /** 路径显示的基准。 */
     cwd?: string;
@@ -29,13 +41,33 @@ export interface ApprovalHost {
     /** 结果说明（消息区一行）。 */
     report?(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): void;
 }
-/** 对话框正文（不含按键行）。 */
-export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: {
+export interface DescribeOptions {
     cwd?: string;
     permissionMode?: string;
     expanded?: boolean;
-}): string[];
-export declare const APPROVAL_KEYS_HINT = "[y] \u5141\u8BB8  [n] \u62D2\u7EDD  [a] \u672C\u4F1A\u8BDD\u5141\u8BB8\u540C\u7C7B  [v] \u5B8C\u6574\u8F93\u5165";
+    /** 紧凑（窄屏）：首行只放工具名（原因已在标题上）。 */
+    compact?: boolean;
+    /** task 子 Agent 的类型名（来源标注）。 */
+    taskAgent?: TaskAgentLookup;
+    /** `task` 调用的 agent 是外部 Agent 时返回 runner（正文写明首次运行一并确认）。 */
+    externalRunner?(agent: string): string | undefined;
+}
+export type TaskAgentLookup = (taskId: string) => string | undefined;
+/** 外部 Agent 首次运行确认（`requestApproval` 发来的 `task` 请求，输入带 `note`）。 */
+export declare function isFirstRunRequest(request: ApprovalRequest): boolean;
+/** 来源标注：`[claude · 会话 abc12345]` / `[task:explore]` / `[task]`；主会话发起为 undefined。 */
+export declare function sourceLabel(request: ApprovalRequest, taskAgent?: TaskAgentLookup): string | undefined;
+/** 原因 → 标题文字（带来源标注）。 */
+export declare function approvalTitle(request: ApprovalRequest, taskAgent?: TaskAgentLookup): string;
+/** 对话框正文（不含选项与按键行）。 */
+export declare function describeRequest(request: ApprovalRequest, theme: Theme, options?: DescribeOptions): string[];
+interface ApprovalOption {
+    decision: ApprovalDecision;
+    label: string;
+    /** 右侧按键提示。 */
+    keys: string;
+}
+export declare const APPROVAL_OPTIONS: readonly ApprovalOption[];
 /** UI broker：每个请求开一个底部覆盖层，等用户按键或 signal abort。 */
 export declare class ApprovalDialogBroker implements ApprovalBroker {
     private readonly host;
@@ -45,4 +77,5 @@ export declare class ApprovalDialogBroker implements ApprovalBroker {
     ask(request: ApprovalRequest, signal: AbortSignal): Promise<ApprovalDecision | undefined>;
 }
 /** 结果的一行说明（消息区）。 */
-export declare function approvalOutcomeText(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled"): string;
+export declare function approvalOutcomeText(request: ApprovalRequest, outcome: ApprovalDecision | "cancelled", taskAgent?: TaskAgentLookup): string;
+export {};