@armadra/agent 0.5.1 → 0.6.1

package/dist/modes/interactive/terminal-setup.js

@@ -0,0 +1,23 @@
+/**
+ * 交互模式装配用到的两个小工具（从 interactive-mode.ts 拆出，控制单文件行数）：真实终端与 keybindings.json。
+ */
+import { join } from "node:path";
+import { KEYBINDINGS_FILE } from "../../config/paths.js";
+import { AmaError } from "../../errors.js";
+import { msg } from "../../i18n/index.js";
+import { Keybindings, ProcessTerminal, loadKeybindingsFile } from "../../tui.js";
+/** stdin / stdout 都是 TTY 才用真实终端；否则抛 `terminal_init_failed`（调用方降级到行式界面）。 */
+export function processTerminal() {
+    const stdin = process.stdin;
+    if (stdin.isTTY !== true || typeof stdin.setRawMode !== "function" || !process.stdout.isTTY) {
+        throw new AmaError("terminal_init_failed", msg().interactive.app.notTty);
+    }
+    return new ProcessTerminal();
+}
+/** 读 `<configDir>/keybindings.json`；问题逐条交给 `warn`。 */
+export function loadKeys(runtime, warn) {
+    const parsed = loadKeybindingsFile(join(runtime.paths.configDir, KEYBINDINGS_FILE));
+    for (const w of parsed.warnings)
+        warn(msg().interactive.app.keybindingsWarning(w));
+    return new Keybindings(parsed.overrides);
+}

package/dist/modes/interactive/tool-summary.js

@@ -8,6 +8,7 @@
  * - grep `N 处匹配 · M 个文件`；glob `N 个文件`；codemode `N 个内层调用 · 脚本输出 M 行`；
  * - task `完成 · 耗时 · ↑in ↓out`；其它 `N 行输出`；失败（非 bash）取错误首行。
  */
+import { msg } from "../../i18n/index.js";
 import { isAbsolute, relative } from "node:path";
 import { stripAnsi } from "../../tui.js";
 import { formatTokens } from "./status-bar.js";
@@ -135,6 +136,7 @@ export function bashOutput(result) {
 /** 完成后的一行结果摘要（已着色，不含 `⎿`）。 */
 export function resultSummary(input, theme) {
     const { name, result, isError, lines } = input;
+    const m = msg().interactive.view.tool;
     const details = record(result.details);
     const muted = (s) => theme.fg("muted", s);
     const sep = theme.fg("dim", " · ");
@@ -146,27 +148,27 @@ export function resultSummary(input, theme) {
         const code = num(details["exit_code"]) ?? (isError ? 1 : 0);
         const total = num(details["totalLines"]) ?? count;
         const head = details["aborted"] === true
-            ? "已中断"
+            ? m.interrupted
             : details["timedOut"] === true
-                ? "超时"
-                : `退出 ${code}`;
-        const parts = [head, duration, ...(total > 0 ? [`${total} 行`] : [])];
+                ? m.timedOut
+                : m.exit(code);
+        const parts = [head, duration, ...(total > 0 ? [m.lines(total)] : [])];
         const text = parts.join(" · ");
         return isError || code !== 0 ? theme.fg("error", text) : parts.map(muted).join(sep);
     }
     if (isError)
-        return theme.fg("error", `${theme.glyphs.fail} ${lines[0] ?? "失败"}`);
+        return theme.fg("error", `${theme.glyphs.fail} ${lines[0] ?? m.failed}`);
     switch (name) {
         case "read": {
             const mime = details["mimeType"];
             if (typeof mime === "string")
-                return muted(`图片 ${mime}`);
+                return muted(m.image(mime));
             const first = num(details["firstLine"]);
             const last = num(details["lastLine"]);
             if (num(details["totalLines"]) === 0)
-                return muted("空文件");
+                return muted(m.emptyFile);
             const n = first !== undefined && last !== undefined ? last - first + 1 : count;
-            return muted(`读取 ${n} 行`);
+            return muted(m.read(n));
         }
         case "edit": {
             const rows = parseDiff(diffOf(result) ?? "");
@@ -174,7 +176,7 @@ export function resultSummary(input, theme) {
             const del = rows.filter((r) => r.kind === "del").length;
             const edits = record(input.args)["edits"];
             const n = num(details["replacements"]) ?? (Array.isArray(edits) ? edits.length : 1);
-            return (muted(`${n} 处修改`) +
+            return (muted(m.edits(n)) +
                 sep +
                 theme.fg("success", `+${add}`) +
                 " " +
@@ -183,23 +185,23 @@ export function resultSummary(input, theme) {
         case "write": {
             const content = record(input.args)["content"];
             const n = typeof content === "string" ? cleanLines(content).length : 0;
-            return muted(`${details["created"] === true ? "新建" : "覆盖"} · ${n} 行`);
+            return muted(m.write(details["created"] === true, n));
         }
         case "grep": {
             const matches = num(details["matches"]);
             if (matches === 0)
-                return muted("无匹配");
+                return muted(m.noMatch);
             if (matches === undefined)
-                return muted(`${count} 行`);
-            return muted(`${matches} 处匹配 · ${num(details["files"]) ?? "?"} 个文件`);
+                return muted(m.lines(count));
+            return muted(m.matches(matches, num(details["files"])));
         }
         case "glob": {
             const n = num(details["count"]);
-            return muted(n === 0 ? "无匹配" : `${n ?? count} 个文件`);
+            return muted(n === 0 ? m.noMatch : m.files(n ?? count));
         }
         case "codemode": {
             const calls = num(details["toolCalls"]) ?? input.nestedCount ?? 0;
-            return muted(`${calls} 个内层调用 · 脚本输出 ${count} 行`);
+            return muted(m.codemode(calls, count));
         }
         case "task": {
             const usage = record(details["usage"]);
@@ -210,9 +212,9 @@ export function resultSummary(input, theme) {
                     `${theme.glyphs.arrowUp}${formatTokens(input_)} ${theme.glyphs.arrowDown}${formatTokens(output)}`,
                 ]
                 : [];
-            return muted(["完成", duration, ...tokens].join(" · "));
+            return muted([m.done, duration, ...tokens].join(" · "));
         }
         default:
-            return muted(count === 0 ? "完成" : `${count} 行输出`);
+            return muted(count === 0 ? m.done : m.outputLines(count));
     }
 }

package/dist/modes/interactive/tool-view.js

@@ -20,6 +20,7 @@
  * - 自定义渲染（`ToolDefinition.renderCall / renderResult`）：标题摘要优先取 `renderCall` 第一行；成功的结果
  *   正文优先用 `renderResult`；抛错或返回空时回到缺省显示；错误结果始终用缺省显示。
  */
+import { msg } from "../../i18n/index.js";
 import { formatElapsed, truncateToWidth, wrapTextWithAnsi, } from "../../tui.js";
 import { contentText } from "./message-view.js";
 import { subagentLine } from "./subagent-view.js";
@@ -159,7 +160,7 @@ export class ToolView {
         const g = theme.glyphs;
         const lead = "  " + theme.fg("border", g.result) + " ";
         if (this.state === "running" && this.awaiting) {
-            return truncateToWidth(lead + theme.fg("dim", `${g.spinnerStatic} 等待确认`), width);
+            return truncateToWidth(lead + theme.fg("dim", msg().interactive.view.tool.awaiting(g.spinnerStatic)), width);
         }
         const sub = this.subagentState();
         if (this.state === "running" && sub !== undefined) {
@@ -170,7 +171,8 @@ export class ToolView {
         if (this.state === "running") {
             const frame = this.options.spinner?.() ?? g.spinnerStatic;
             const elapsed = formatElapsed(this.now() - this.startedAt);
-            const what = this.toolName === "task" ? `子 Agent · 运行中 ${elapsed}` : `运行中 · ${elapsed}`;
+            const m = msg().interactive.view.tool;
+            const what = this.toolName === "task" ? m.subagentRunning(elapsed) : m.running(elapsed);
             return truncateToWidth(lead + theme.fg("accent", frame) + " " + theme.fg("muted", what), width);
         }
         const result = this.result;
@@ -251,7 +253,7 @@ export class ToolView {
     }
     more(hidden) {
         const { theme } = this.options;
-        return BODY + theme.fg("dim", `${theme.glyphs.ellipsis} 另 ${hidden} 行（Ctrl+O 展开）`);
+        return (BODY + theme.fg("dim", msg().interactive.view.tool.moreLines(theme.glyphs.ellipsis, hidden)));
     }
     nestedLines(width) {
         const { theme } = this.options;
@@ -269,7 +271,8 @@ export class ToolView {
         const shown = this.nested.slice(-COLLAPSED_CHILDREN);
         if (this.nested.length > shown.length) {
             const hidden = this.nested.length - shown.length;
-            out.push(BODY + theme.fg("dim", `${theme.glyphs.ellipsis} 前 ${hidden} 个调用`));
+            out.push(BODY +
+                theme.fg("dim", msg().interactive.view.tool.earlierCalls(theme.glyphs.ellipsis, hidden)));
         }
         for (const child of shown) {
             out.push(BODY + child.header(inner));

package/dist/modes/interactive/trace-view.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `/trace` 覆盖层（docs/wave6-plan.md §2.4）。[W6-T1]
+ *
+ * - `/trace`（当前会话）、`/trace t2`（以任务 t2 为根：ama 子会话的子轨迹，或外部 Agent 骨架）。
+ * - 主屏约束下的覆盖层：`anchor: "bottom"`、高度 `rows − 1`（同 rewind 面板）；退出撤掉覆盖层，消息区不变。
+ * - 布局：标题汇总一行 + 列表窗口 + 按键提示一行；只格式化可见窗口里的行（10k 节点也只算可见行）。
+ * - 键：↑↓ / PgUp PgDn / Home End 移动；→ 展开（子 Agent 展开即懒加载子轨迹）或进第一个子行；← 折叠或回父行；
+ *   Enter 详情卡片（再按或 Esc 返回）；「更早的 N 个回合」行上 Enter / ↑ 加载前一页；f 跟随开关（进行中自动开，
+ *   手动上移暂停，End 恢复）；Esc 先关详情再关视图。
+ * - 刷新：会话事件（`entry_appended` / `telemetry_tick` / 工具起止 / 请求起止）触发，节流 ≤ 2 Hz；每次整棵
+ *   重建（构建器是 O(条目) 的纯函数，10k 节点实测见 trace-view.test.ts），展开状态与光标按行 key 保留。
+ */
+import type { AgentSession } from "../../agent/types.js";
+import { type Component, type Focusable, type Keybindings, type OverlayHandle, type Theme } from "../../tui.js";
+import { type TraceRow } from "../../trace/flatten.js";
+import { LiveTracker, type ChildLoader } from "../../trace/session.js";
+import type { NoticeLevel } from "./message-view.js";
+/** 尾部优先：首屏与每次向前翻页的回合数。 */
+export declare const TRACE_PAGE_TURNS = 50;
+/** 刷新节流（≤ 2 Hz）。 */
+export declare const TRACE_REFRESH_MS = 500;
+export interface TraceViewHost {
+    theme: Theme;
+    keybindings?: Keybindings;
+    showOverlay(component: Component, options: {
+        anchor: "bottom";
+    }): OverlayHandle;
+    rows(): number;
+    session(): AgentSession;
+    now(): number;
+    notice(level: NoticeLevel, text: string): void;
+    /** 请求重画（异步刷新后）。 */
+    render?(): void;
+    /** 子会话读取（测试注入）；缺省只读读文件、按 mtime 缓存。 */
+    loadChild?: ChildLoader;
+    /** 刷新节流（测试用 0）。 */
+    refreshMs?: number;
+}
+export declare class TraceView implements Component, Focusable {
+    private readonly host;
+    private readonly taskId;
+    private readonly close;
+    focused: boolean;
+    private trace;
+    private root;
+    private rows;
+    private lookup;
+    private readonly expanded;
+    /** 已展开过的 ama 子 Agent（重建后重新挂子轨迹）。 */
+    private readonly loaded;
+    private fromTurn;
+    private cursor;
+    private top;
+    private follow;
+    private detail;
+    readonly live: LiveTracker;
+    private readonly loadChild;
+    constructor(host: TraceViewHost, taskId: string | undefined, close: () => void);
+    /** 任务存在（`/trace <id>`）或看主会话。 */
+    get found(): boolean;
+    private rowsKeyOfRoot;
+    /** 重建轨迹（会话条目 + live 叠加 + 已展开的子轨迹）。 */
+    rebuild(): void;
+    /** 重新摊平，光标按 key 保持；跟随时贴底。 */
+    private reflow;
+    /** 会话有变化：重建并重排。 */
+    refresh(): void;
+    /** 当前行数（测试用）。 */
+    get rowCount(): number;
+    get cursorIndex(): number;
+    get selected(): TraceRow | undefined;
+    get following(): boolean;
+    get detailOpen(): boolean;
+    private bodyHeight;
+    private move;
+    private loadEarlier;
+    private expand;
+    private collapse;
+    handleInput(data: string): void;
+    private detailInput;
+    private ctx;
+    private headerLine;
+    render(width: number): string[];
+    invalidate(): void;
+}
+/**
+ * 打开 `/trace` 覆盖层；关闭时 resolve。任务不存在时提示一行、不打开。
+ */
+export declare function openTraceView(host: TraceViewHost, taskId?: string): Promise<void>;

package/dist/modes/interactive/trace-view.js

@@ -0,0 +1,332 @@
+/**
+ * `/trace` 覆盖层（docs/wave6-plan.md §2.4）。[W6-T1]
+ *
+ * - `/trace`（当前会话）、`/trace t2`（以任务 t2 为根：ama 子会话的子轨迹，或外部 Agent 骨架）。
+ * - 主屏约束下的覆盖层：`anchor: "bottom"`、高度 `rows − 1`（同 rewind 面板）；退出撤掉覆盖层，消息区不变。
+ * - 布局：标题汇总一行 + 列表窗口 + 按键提示一行；只格式化可见窗口里的行（10k 节点也只算可见行）。
+ * - 键：↑↓ / PgUp PgDn / Home End 移动；→ 展开（子 Agent 展开即懒加载子轨迹）或进第一个子行；← 折叠或回父行；
+ *   Enter 详情卡片（再按或 Esc 返回）；「更早的 N 个回合」行上 Enter / ↑ 加载前一页；f 跟随开关（进行中自动开，
+ *   手动上移暂停，End 恢复）；Esc 先关详情再关视图。
+ * - 刷新：会话事件（`entry_appended` / `telemetry_tick` / 工具起止 / 请求起止）触发，节流 ≤ 2 Hz；每次整棵
+ *   重建（构建器是 O(条目) 的纯函数，10k 节点实测见 trace-view.test.ts），展开状态与光标按行 key 保留。
+ */
+import { msg } from "../../i18n/index.js";
+import { defaultKeybindings, matchesKey, padToWidth, truncateToWidth, visibleWidth, } from "../../tui.js";
+import { buildTrace, findSubagent, loadSubagentTrace } from "../../trace/build.js";
+import { describeNode, detailLines, entryLookup, } from "../../trace/detail.js";
+import { flattenNode, flattenTrace, needsChild, rowIndex, tailStart, } from "../../trace/flatten.js";
+import { formatRow, rowLabel, summaryText } from "../../trace/format.js";
+import { childLoader, LiveTracker, traceInputOf } from "../../trace/session.js";
+/** 尾部优先：首屏与每次向前翻页的回合数。 */
+export const TRACE_PAGE_TURNS = 50;
+/** 刷新节流（≤ 2 Hz）。 */
+export const TRACE_REFRESH_MS = 500;
+export class TraceView {
+    host;
+    taskId;
+    close;
+    focused = false;
+    trace;
+    root;
+    rows = [];
+    lookup;
+    expanded = new Map();
+    /** 已展开过的 ama 子 Agent（重建后重新挂子轨迹）。 */
+    loaded = new Set();
+    fromTurn = 0;
+    cursor = 0;
+    top = 0;
+    follow = false;
+    detail;
+    live;
+    loadChild;
+    constructor(host, taskId, close) {
+        this.host = host;
+        this.taskId = taskId;
+        this.close = close;
+        this.live = new LiveTracker(host.session, host.now);
+        this.loadChild = host.loadChild ?? childLoader();
+        this.rebuild();
+        this.follow = this.trace.partial;
+        if (taskId === undefined)
+            this.fromTurn = tailStart(this.trace, TRACE_PAGE_TURNS);
+        if (this.root !== undefined)
+            this.expanded.set(this.rowsKeyOfRoot(), true);
+        this.reflow();
+        this.cursor = Math.max(0, this.rows.length - 1);
+    }
+    /** 任务存在（`/trace <id>`）或看主会话。 */
+    get found() {
+        return this.taskId === undefined || this.root !== undefined;
+    }
+    rowsKeyOfRoot() {
+        return `a:${this.taskId}`;
+    }
+    /** 重建轨迹（会话条目 + live 叠加 + 已展开的子轨迹）。 */
+    rebuild() {
+        const session = this.host.session();
+        const input = traceInputOf(session);
+        this.trace = buildTrace(input, { live: this.live.overlay() });
+        for (const taskId of this.loaded) {
+            const node = findSubagent(this.trace, taskId);
+            if (node !== undefined)
+                loadSubagentTrace(node, this.loadChild);
+        }
+        if (this.taskId !== undefined) {
+            this.root = findSubagent(this.trace, this.taskId);
+            if (this.root !== undefined)
+                loadSubagentTrace(this.root, this.loadChild);
+        }
+        const children = this.loadChild.inputs().flatMap((i) => i.entries);
+        this.lookup = entryLookup([...input.entries, ...children], session.state.cwd);
+    }
+    /** 重新摊平，光标按 key 保持；跟随时贴底。 */
+    reflow() {
+        const key = this.rows[this.cursor]?.key;
+        const opts = { expanded: this.expanded, fromTurn: this.fromTurn };
+        this.rows =
+            this.root !== undefined ? flattenNode(this.root, opts) : flattenTrace(this.trace, opts);
+        const at = key === undefined ? -1 : rowIndex(this.rows, key);
+        this.cursor = this.follow
+            ? Math.max(0, this.rows.length - 1)
+            : at >= 0
+                ? at
+                : Math.min(this.cursor, Math.max(0, this.rows.length - 1));
+        if (this.detail !== undefined) {
+            const fresh = this.rows[rowIndex(this.rows, this.detail.row.key)];
+            if (fresh !== undefined)
+                this.detail.row = fresh;
+        }
+    }
+    /** 会话有变化：重建并重排。 */
+    refresh() {
+        this.rebuild();
+        this.reflow();
+    }
+    /** 当前行数（测试用）。 */
+    get rowCount() {
+        return this.rows.length;
+    }
+    get cursorIndex() {
+        return this.cursor;
+    }
+    get selected() {
+        return this.rows[this.cursor];
+    }
+    get following() {
+        return this.follow;
+    }
+    get detailOpen() {
+        return this.detail !== undefined;
+    }
+    bodyHeight() {
+        return Math.max(1, this.host.rows() - 1 - 2);
+    }
+    move(delta) {
+        if (this.rows.length === 0)
+            return;
+        if (delta < 0)
+            this.follow = false;
+        // 第一行是「更早的回合」时继续上移 = 加载前一页
+        if (delta < 0 && this.cursor === 0 && this.rows[0]?.node.kind === "more")
+            return this.loadEarlier();
+        this.cursor = Math.max(0, Math.min(this.rows.length - 1, this.cursor + delta));
+        if (delta > 0 && this.cursor === this.rows.length - 1 && this.trace.partial)
+            this.follow = true;
+    }
+    loadEarlier() {
+        const key = this.rows[1]?.key;
+        this.fromTurn = Math.max(0, this.fromTurn - TRACE_PAGE_TURNS);
+        this.reflow();
+        const at = key === undefined ? -1 : rowIndex(this.rows, key);
+        this.cursor = Math.max(0, at - 1);
+    }
+    expand() {
+        const row = this.selected;
+        if (row === undefined)
+            return;
+        if (!row.expandable)
+            return;
+        if (!row.expanded) {
+            if (needsChild(row.node)) {
+                this.loaded.add(row.node.taskId);
+                loadSubagentTrace(row.node, this.loadChild);
+                this.rebuild();
+            }
+            this.expanded.set(row.key, true);
+            this.reflow();
+            return;
+        }
+        if (this.rows[this.cursor + 1]?.depth === row.depth + 1)
+            this.cursor++;
+    }
+    collapse() {
+        const row = this.selected;
+        if (row === undefined)
+            return;
+        this.follow = false;
+        if (row.expanded) {
+            this.expanded.set(row.key, false);
+            this.reflow();
+            return;
+        }
+        const slash = row.key.lastIndexOf("/");
+        if (slash < 0)
+            return;
+        const parent = rowIndex(this.rows, row.key.slice(0, slash));
+        if (parent >= 0)
+            this.cursor = parent;
+    }
+    handleInput(data) {
+        const keys = this.host.keybindings ?? defaultKeybindings;
+        if (this.detail !== undefined)
+            return this.detailInput(data, keys);
+        const page = this.bodyHeight();
+        if (keys.matches(data, "tui.select.up"))
+            this.move(-1);
+        else if (keys.matches(data, "tui.select.down"))
+            this.move(1);
+        else if (keys.matches(data, "tui.select.pageUp"))
+            this.move(-page);
+        else if (keys.matches(data, "tui.select.pageDown"))
+            this.move(page);
+        else if (matchesKey(data, "home")) {
+            this.follow = false;
+            this.cursor = 0;
+        }
+        else if (matchesKey(data, "end")) {
+            this.cursor = Math.max(0, this.rows.length - 1);
+            this.follow = this.trace.partial;
+        }
+        else if (matchesKey(data, "right"))
+            this.expand();
+        else if (matchesKey(data, "left"))
+            this.collapse();
+        else if (matchesKey(data, "enter")) {
+            const row = this.selected;
+            if (row?.node.kind === "more")
+                this.loadEarlier();
+            else if (row !== undefined && row.node.kind !== "aux_group")
+                this.detail = { row, scroll: 0 };
+        }
+        else if (data === "f") {
+            this.follow = !this.follow;
+            if (this.follow)
+                this.cursor = Math.max(0, this.rows.length - 1);
+        }
+        else if (matchesKey(data, "escape") || keys.matches(data, "tui.select.cancel"))
+            this.close();
+    }
+    detailInput(data, keys) {
+        const detail = this.detail;
+        const page = this.bodyHeight();
+        if (keys.matches(data, "tui.select.up"))
+            detail.scroll = Math.max(0, detail.scroll - 1);
+        else if (keys.matches(data, "tui.select.down"))
+            detail.scroll++;
+        else if (keys.matches(data, "tui.select.pageUp"))
+            detail.scroll = Math.max(0, detail.scroll - page);
+        else if (keys.matches(data, "tui.select.pageDown"))
+            detail.scroll += page;
+        else if (matchesKey(data, "escape") || matchesKey(data, "enter") || matchesKey(data, "left"))
+            this.detail = undefined;
+    }
+    ctx() {
+        return {
+            theme: this.host.theme,
+            describe: (n) => describeNode(n, this.lookup),
+        };
+    }
+    headerLine(width) {
+        const theme = this.host.theme;
+        const m = msg().trace;
+        const root = this.root;
+        const title = root !== undefined ? m.taskTitle(root.taskId, root.agent) : m.title;
+        const source = root !== undefined ? root.child : this.trace;
+        const summary = source !== undefined ? ` · ${summaryText(source, theme)}` : "";
+        const state = this.trace.partial ? (this.follow ? m.follow.on : m.follow.off) : "";
+        const right = state === "" ? "" : ` ${theme.fg(this.follow ? "accent" : "muted", state)}`;
+        const left = truncateToWidth(`${theme.bold(title)}${theme.fg("muted", summary)}`, Math.max(1, width - visibleWidth(right)), theme.glyphs.ellipsis);
+        return padToWidth(`${left}${right}`, width);
+    }
+    render(width) {
+        const theme = this.host.theme;
+        const height = this.bodyHeight();
+        const lines = [this.headerLine(width)];
+        if (this.detail !== undefined) {
+            const { row } = this.detail;
+            const body = [
+                theme.bold(rowLabel(row, this.ctx())),
+                ...detailLines(row.node, this.lookup, Math.max(8, width - 2), theme, this.trace.startedAt),
+            ].map((l) => ` ${l}`);
+            const max = Math.max(0, body.length - height);
+            this.detail.scroll = Math.min(this.detail.scroll, max);
+            for (const line of body.slice(this.detail.scroll, this.detail.scroll + height))
+                lines.push(padToWidth(truncateToWidth(line, width, theme.glyphs.ellipsis), width));
+        }
+        else if (this.rows.length === 0)
+            lines.push(padToWidth(theme.dim(` ${msg().trace.empty}`), width));
+        else {
+            // 窗口：光标始终可见；跟随时贴底
+            if (this.cursor < this.top)
+                this.top = this.cursor;
+            if (this.cursor >= this.top + height)
+                this.top = this.cursor - height + 1;
+            this.top = Math.max(0, Math.min(this.top, Math.max(0, this.rows.length - height)));
+            const ctx = this.ctx();
+            for (let i = this.top; i < Math.min(this.rows.length, this.top + height); i++)
+                lines.push(formatRow(this.rows[i], width, ctx, i === this.cursor));
+        }
+        while (lines.length < height + 1)
+            lines.push(" ".repeat(width));
+        const hints = msg().trace.hints;
+        const hint = this.detail !== undefined ? hints.detail : width < 60 ? hints.listNarrow : hints.list;
+        lines.push(padToWidth(truncateToWidth(theme.dim(hint), width, theme.glyphs.ellipsis), width));
+        return lines;
+    }
+    invalidate() { }
+}
+/**
+ * 打开 `/trace` 覆盖层；关闭时 resolve。任务不存在时提示一行、不打开。
+ */
+export function openTraceView(host, taskId) {
+    return new Promise((resolve) => {
+        let handle;
+        let timer;
+        let unsubscribe;
+        let last = 0;
+        const finish = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            unsubscribe?.();
+            handle?.hide();
+            host.render?.();
+            resolve();
+        };
+        const view = new TraceView(host, taskId, finish);
+        if (!view.found) {
+            host.notice("warn", msg().trace.taskNotFound(taskId));
+            resolve();
+            return;
+        }
+        const throttle = host.refreshMs ?? TRACE_REFRESH_MS;
+        const flush = () => {
+            timer = undefined;
+            last = host.now();
+            view.refresh();
+            host.render?.();
+        };
+        unsubscribe = host.session().subscribe((event) => {
+            if (!view.live.onEvent(event) || timer !== undefined)
+                return;
+            const wait = Math.max(0, throttle - (host.now() - last));
+            if (wait === 0)
+                flush();
+            else {
+                timer = setTimeout(flush, wait);
+                timer.unref?.();
+            }
+        });
+        handle = host.showOverlay(view, { anchor: "bottom" });
+    });
+}