@autopilot-agent/cli 0.0.0-stage → 0.1.0

package/dist/tui/brand/intro.d.ts

@@ -0,0 +1,12 @@
+/** 品牌开场动画：logo 帧、运动位置、像素字母逐列显现与着色渲染。 */
+import { type ReactNode } from "react";
+/** Autopilot 启动画面的侧脸、转头和眨眼帧。 */
+export declare function getAutopilotLogoRows(elapsedMs: number): string[];
+/** 计算 logo 的运动位置；终点固定在像素字母末尾之后，避免覆盖最后几个字母。 */
+export declare function getAutopilotLogoX(elapsedMs: number): number;
+/** 生成启动动画的像素字母：字母逐列出现，最后用亮色字符扫过。 */
+export declare function createAutopilotBrandRows(elapsedMs: number): string[];
+/** 渲染静态 logo；眼睛保持绿色，其余轮廓使用紫色品牌 token。 */
+export declare function renderAutopilotLogo(rows: string[], useColor: boolean): ReactNode;
+/** 渲染开场动画；像素字母为蓝色，运动中的 logo 为紫色，眼睛为绿色。 */
+export declare function renderAutopilotIntroRows(elapsedMs: number, useColor: boolean): ReactNode;

package/dist/tui/brand/intro.js

@@ -0,0 +1,88 @@
+/** 品牌开场动画：logo 帧、运动位置、像素字母逐列显现与着色渲染。 */
+import { CLI_TUI_COLORS } from "../../design-tokens.js";
+import { clampTuiProgress } from "../format.js";
+import { AUTOPILOT_BRAND_WORD, AUTOPILOT_INTRO_WIDTH, AUTOPILOT_LOGO_FINAL_X, AUTOPILOT_LOGO_HEIGHT, AUTOPILOT_WORD_START, AUTOPILOT_WORD_WIDTH, } from "../constants.js";
+import { AUTOPILOT_PIXEL_FONT, renderAutopilotColoredRows } from "./pixel.js";
+/** Autopilot 启动画面的侧脸、转头和眨眼帧。 */
+export function getAutopilotLogoRows(elapsedMs) {
+    if (elapsedMs < 2_100)
+        return ["   ▄▄▄  ", "  █   █ ", " █  · █ ", " █▄▄▄██ ", "  ███   ", "  ▀▀    ", "        "];
+    if (elapsedMs < 2_550)
+        return ["   ▄▄▄  ", "  █   █ ", " █  · █ ", " █▄▄▄██ ", "  ███   ", "  ▀▀    ", "        "];
+    if (elapsedMs < 2_800)
+        return ["  ▄▄▄▄▄ ", " █     █", "█  · ·  █", "█   ▀   █", "█  ───  █", " █▄▄▄▄▄█ ", "   ▀▀▀   "];
+    if (elapsedMs < 3_050)
+        return ["  ▄▄▄▄▄ ", " █     █", "█  ─ ─  █", "█   ▀   █", "█  ───  █", " █▄▄▄▄▄█ ", "   ▀▀▀   "];
+    return ["  ▄▄▄▄▄ ", " █     █", "█  ● ●  █", "█   ▀   █", "█  ───  █", " █▄▄▄▄▄█ ", "   ▀▀▀   "];
+}
+/** 计算 logo 的运动位置；终点固定在像素字母末尾之后，避免覆盖最后几个字母。 */
+export function getAutopilotLogoX(elapsedMs) {
+    return Math.round(AUTOPILOT_LOGO_FINAL_X * clampTuiProgress(elapsedMs / 1_350));
+}
+/** 生成启动动画的像素字母：字母逐列出现，最后用亮色字符扫过。 */
+export function createAutopilotBrandRows(elapsedMs) {
+    const wordWidth = AUTOPILOT_WORD_WIDTH;
+    const totalWidth = AUTOPILOT_INTRO_WIDTH;
+    const revealColumns = Math.round(wordWidth * clampTuiProgress((elapsedMs - 180) / 1_050));
+    const scanProgress = clampTuiProgress((elapsedMs - 1_650) / 850);
+    const scanColumn = elapsedMs < 1_650 ? -1 : Math.round((wordWidth - 1) * scanProgress);
+    const logoX = getAutopilotLogoX(elapsedMs);
+    const logoRows = getAutopilotLogoRows(elapsedMs);
+    const rows = Array.from({ length: AUTOPILOT_LOGO_HEIGHT }, function createBlankRow() {
+        return Array.from({ length: totalWidth }, function createBlankCell() { return " "; });
+    });
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+        const row = rows[rowIndex];
+        const logoRow = logoRows[rowIndex] ?? "";
+        const letters = AUTOPILOT_BRAND_WORD.split("");
+        for (let letterIndex = 0; letterIndex < letters.length; letterIndex += 1) {
+            const glyph = AUTOPILOT_PIXEL_FONT[letters[letterIndex] ?? ""];
+            const glyphRow = glyph?.[rowIndex] ?? "00000";
+            for (let pixelIndex = 0; pixelIndex < glyphRow.length; pixelIndex += 1) {
+                const wordColumn = letterIndex * 6 + pixelIndex;
+                if (wordColumn >= revealColumns || glyphRow[pixelIndex] !== "1")
+                    continue;
+                const outputColumn = AUTOPILOT_WORD_START + wordColumn;
+                row[outputColumn] = Math.abs(wordColumn - scanColumn) <= 1 ? "▐" : "▌";
+            }
+        }
+        for (let logoIndex = 0; logoIndex < logoRow.length; logoIndex += 1) {
+            const logoCell = logoRow[logoIndex];
+            if (logoCell && logoCell !== " ")
+                row[logoX + logoIndex] = logoCell;
+        }
+    }
+    // 每一帧都返回相同宽度；trimEnd 会让右侧内容随像素字母显现而横向移动。
+    return rows.map(function padBrandRow(row) { return row.join("").padEnd(totalWidth, " "); });
+}
+/** 渲染静态 logo；眼睛保持绿色，其余轮廓使用紫色品牌 token。 */
+export function renderAutopilotLogo(rows, useColor) {
+    return renderAutopilotColoredRows(rows, function colorAutopilotLogoCell(char) {
+        if (!useColor || char === " ")
+            return undefined;
+        if (char === "·" || char === "●")
+            return CLI_TUI_COLORS.copilotGreen;
+        if (char === "─" || char === "▀" || char === "▄")
+            return CLI_TUI_COLORS.copilotBlue;
+        return CLI_TUI_COLORS.copilotPurple;
+    });
+}
+/** 渲染开场动画；像素字母为蓝色，运动中的 logo 为紫色，眼睛为绿色。 */
+export function renderAutopilotIntroRows(elapsedMs, useColor) {
+    const rows = createAutopilotBrandRows(elapsedMs);
+    const logoRows = getAutopilotLogoRows(elapsedMs);
+    const logoX = getAutopilotLogoX(elapsedMs);
+    return renderAutopilotColoredRows(rows, function colorAutopilotIntroCell(char, column, rowIndex) {
+        if (!useColor || char === " ")
+            return undefined;
+        const logoCell = logoRows[rowIndex]?.[column - logoX];
+        if (logoCell && logoCell !== " ") {
+            if (logoCell === "·" || logoCell === "●")
+                return CLI_TUI_COLORS.copilotGreen;
+            if (logoCell === "─" || logoCell === "▀" || logoCell === "▄")
+                return CLI_TUI_COLORS.copilotBlue;
+            return CLI_TUI_COLORS.copilotPurple;
+        }
+        return char === "▐" ? CLI_TUI_COLORS.copilotBlueBright : CLI_TUI_COLORS.copilotBlue;
+    });
+}

package/dist/tui/brand/pixel.d.ts

@@ -0,0 +1,8 @@
+/** 品牌像素字体与渲染纯函数：静态品牌行生成 + 按字符着色渲染，供 header/intro/viewport 共用。 */
+import { type ReactNode } from "react";
+/** Autopilot 品牌像素字体；每个字母 5×7，由 0/1 表示亮灭。 */
+export declare const AUTOPILOT_PIXEL_FONT: Record<string, readonly string[]>;
+/** 根据字符来源把品牌动画拆成 Copilot-inspired 的蓝、紫、绿三组 token。 */
+export declare function renderAutopilotColoredRows(rows: string[], colorForCell: (char: string, column: number, rowIndex: number) => string | undefined, maximumWidth?: number): ReactNode;
+/** 生成静态品牌的纯文本行，供内联品牌和备用屏时间线共用。 */
+export declare function createAutopilotStaticWordRows(): string[];

package/dist/tui/brand/pixel.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { AUTOPILOT_BRAND_WORD, AUTOPILOT_LOGO_HEIGHT, AUTOPILOT_WORD_WIDTH } from "../constants.js";
+/** Autopilot 品牌像素字体；每个字母 5×7，由 0/1 表示亮灭。 */
+export const AUTOPILOT_PIXEL_FONT = {
+    A: ["01110", "10001", "10001", "11111", "10001", "10001", "10001"],
+    I: ["11111", "00100", "00100", "00100", "00100", "00100", "11111"],
+    L: ["10000", "10000", "10000", "10000", "10000", "10000", "11111"],
+    O: ["01110", "10001", "10001", "10001", "10001", "10001", "01110"],
+    P: ["11110", "10001", "10001", "11110", "10000", "10000", "10000"],
+    T: ["11111", "00100", "00100", "00100", "00100", "00100", "00100"],
+    U: ["10001", "10001", "10001", "10001", "10001", "10001", "01110"],
+};
+/** 根据字符来源把品牌动画拆成 Copilot-inspired 的蓝、紫、绿三组 token。 */
+export function renderAutopilotColoredRows(rows, colorForCell, maximumWidth) {
+    const width = maximumWidth === undefined ? undefined : Math.max(1, Math.floor(maximumWidth));
+    return (_jsx(Box, { flexDirection: "column", width: width, overflow: width === undefined ? undefined : "hidden", children: rows.map(function renderAutopilotRow(row, rowIndex) {
+            const visibleRow = width === undefined ? row : row.slice(0, width);
+            const segments = [];
+            for (let column = 0; column < visibleRow.length; column += 1) {
+                const char = visibleRow[column] ?? " ";
+                const color = colorForCell(char, column, rowIndex);
+                const previous = segments[segments.length - 1];
+                if (previous && previous.color === color)
+                    previous.text += char;
+                else
+                    segments.push({ text: char, color });
+            }
+            return (_jsx(Text, { wrap: width === undefined ? undefined : "truncate-end", children: segments.map(function renderAutopilotSegment(segment, segmentIndex) {
+                    return _jsx(Text, { color: segment.color, children: segment.text }, String(rowIndex) + ":" + String(segmentIndex));
+                }) }, String(rowIndex)));
+        }) }));
+}
+/** 生成静态品牌的纯文本行，供内联品牌和备用屏时间线共用。 */
+export function createAutopilotStaticWordRows() {
+    const rows = Array.from({ length: AUTOPILOT_LOGO_HEIGHT }, function createWordRow() {
+        return Array.from({ length: AUTOPILOT_WORD_WIDTH }, function createWordCell() { return " "; });
+    });
+    for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+        for (let letterIndex = 0; letterIndex < AUTOPILOT_BRAND_WORD.length; letterIndex += 1) {
+            const glyph = AUTOPILOT_PIXEL_FONT[AUTOPILOT_BRAND_WORD[letterIndex] ?? ""];
+            const glyphRow = glyph?.[rowIndex] ?? "00000";
+            for (let pixelIndex = 0; pixelIndex < glyphRow.length; pixelIndex += 1) {
+                if (glyphRow[pixelIndex] === "1")
+                    rows[rowIndex][letterIndex * 6 + pixelIndex] = "█";
+            }
+        }
+    }
+    return rows.map(function joinWordRow(row) { return row.join(""); });
+}

package/dist/tui/constants.d.ts

@@ -0,0 +1,56 @@
+/**
+ * TUI 的非颜色常量：Autopilot 品牌像素几何、终端控制序列、输入相关常量与
+ * 代理展示名。颜色语义 token 集中在 design-tokens.ts，这里不重复定义。
+ */
+/** Autopilot 品牌版本号。 */
+export declare const AUTOPILOT_VERSION = "0.1.0";
+/** 品牌像素字母的完整单词。 */
+export declare const AUTOPILOT_BRAND_WORD = "AUTOPILOT";
+/** 开场动画总时长（毫秒）。 */
+export declare const AUTOPILOT_INTRO_DURATION_MS = 4500;
+/** 品牌 logo 的像素宽度。 */
+export declare const AUTOPILOT_LOGO_WIDTH = 9;
+/** 品牌 logo 的像素高度。 */
+export declare const AUTOPILOT_LOGO_HEIGHT = 7;
+/** 品牌单词相对行首的起始列。 */
+export declare const AUTOPILOT_WORD_START = 2;
+/** 品牌单词与 logo 之间的像素间距。 */
+export declare const AUTOPILOT_BRAND_GAP = 3;
+/** 品牌像素单词的总显示宽度（每字母 6 列，减最后 1 列）。 */
+export declare const AUTOPILOT_WORD_WIDTH: number;
+/** logo 最终落点：单词结束后再留品牌间距。 */
+export declare const AUTOPILOT_LOGO_FINAL_X: number;
+/** 开场动画的总宽度。 */
+export declare const AUTOPILOT_INTRO_WIDTH: number;
+/** 代理在 TUI 中的展示名。 */
+export declare const TUI_AGENT_LABEL = "Autopilot";
+/** Node 20+ 的 Unicode grapheme 分词器，保证一个组合 emoji 只占一个输入光标位置。 */
+export declare const TUI_INPUT_SEGMENTER: Intl.Segmenter;
+/** prompt 前缀字符。 */
+export declare const TUI_PROMPT_PREFIX = "\u203A ";
+/** 输入光标的可视字符。 */
+export declare const TUI_CURSOR_CHARACTER = "\u258F";
+/** 输入光标的终端显示宽度。 */
+export declare const TUI_CURSOR_WIDTH: number;
+/** 启用 bracketed paste 的控制序列。 */
+export declare const TUI_BRACKETED_PASTE_ENABLE = "\u001B[?2004h";
+/** 关闭 bracketed paste 的控制序列。 */
+export declare const TUI_BRACKETED_PASTE_DISABLE = "\u001B[?2004l";
+/** 启用终端 focus 报告的控制序列。 */
+export declare const TUI_TERMINAL_FOCUS_ENABLE = "\u001B[?1004h";
+/** 关闭终端 focus 报告的控制序列。 */
+export declare const TUI_TERMINAL_FOCUS_DISABLE = "\u001B[?1004l";
+/** 进入备用屏并清屏的控制序列。 */
+export declare const TUI_ALTERNATE_SCREEN_ENABLE = "\u001B[?1049h\u001B[2J\u001B[H";
+/** 退出备用屏的控制序列。 */
+export declare const TUI_ALTERNATE_SCREEN_DISABLE = "\u001B[?1049l";
+/** inline TUI 缩窄时清除当前视口和已保存的 scrollback，避免旧帧可被向上滚动看到。 */
+export declare const TUI_INLINE_RESIZE_CLEAR = "\u001B[2J\u001B[3J\u001B[H";
+/** 启用鼠标追踪（含 SGR 扩展模式）的控制序列。 */
+export declare const TUI_MOUSE_TRACKING_ENABLE = "\u001B[?1000h\u001B[?1002h\u001B[?1003h\u001B[?1006h";
+/** 关闭鼠标追踪的控制序列。 */
+export declare const TUI_MOUSE_TRACKING_DISABLE = "\u001B[?1006l\u001B[?1003l\u001B[?1002l\u001B[?1000l";
+/** Store 批量发布 answer delta 的间隔（毫秒）。 */
+export declare const TUI_EVENT_PUBLISH_INTERVAL_MS = 32;
+/** OSC 52 剪贴板的最大字节数。 */
+export declare const TUI_OSC52_MAX_BYTES = 100000;

package/dist/tui/constants.js

@@ -0,0 +1,57 @@
+/**
+ * TUI 的非颜色常量：Autopilot 品牌像素几何、终端控制序列、输入相关常量与
+ * 代理展示名。颜色语义 token 集中在 design-tokens.ts，这里不重复定义。
+ */
+import stringWidth from "string-width";
+/** Autopilot 品牌版本号。 */
+export const AUTOPILOT_VERSION = "0.1.0";
+/** 品牌像素字母的完整单词。 */
+export const AUTOPILOT_BRAND_WORD = "AUTOPILOT";
+/** 开场动画总时长（毫秒）。 */
+export const AUTOPILOT_INTRO_DURATION_MS = 4_500;
+/** 品牌 logo 的像素宽度。 */
+export const AUTOPILOT_LOGO_WIDTH = 9;
+/** 品牌 logo 的像素高度。 */
+export const AUTOPILOT_LOGO_HEIGHT = 7;
+/** 品牌单词相对行首的起始列。 */
+export const AUTOPILOT_WORD_START = 2;
+/** 品牌单词与 logo 之间的像素间距。 */
+export const AUTOPILOT_BRAND_GAP = 3;
+/** 品牌像素单词的总显示宽度（每字母 6 列，减最后 1 列）。 */
+export const AUTOPILOT_WORD_WIDTH = AUTOPILOT_BRAND_WORD.length * 6 - 1;
+/** logo 最终落点：单词结束后再留品牌间距。 */
+export const AUTOPILOT_LOGO_FINAL_X = AUTOPILOT_WORD_START + AUTOPILOT_WORD_WIDTH + AUTOPILOT_BRAND_GAP;
+/** 开场动画的总宽度。 */
+export const AUTOPILOT_INTRO_WIDTH = AUTOPILOT_LOGO_FINAL_X + AUTOPILOT_LOGO_WIDTH;
+/** 代理在 TUI 中的展示名。 */
+export const TUI_AGENT_LABEL = "Autopilot";
+/** Node 20+ 的 Unicode grapheme 分词器，保证一个组合 emoji 只占一个输入光标位置。 */
+export const TUI_INPUT_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+/** prompt 前缀字符。 */
+export const TUI_PROMPT_PREFIX = "› ";
+/** 输入光标的可视字符。 */
+export const TUI_CURSOR_CHARACTER = "▏";
+/** 输入光标的终端显示宽度。 */
+export const TUI_CURSOR_WIDTH = stringWidth(TUI_CURSOR_CHARACTER);
+/** 启用 bracketed paste 的控制序列。 */
+export const TUI_BRACKETED_PASTE_ENABLE = "\u001b[?2004h";
+/** 关闭 bracketed paste 的控制序列。 */
+export const TUI_BRACKETED_PASTE_DISABLE = "\u001b[?2004l";
+/** 启用终端 focus 报告的控制序列。 */
+export const TUI_TERMINAL_FOCUS_ENABLE = "\u001b[?1004h";
+/** 关闭终端 focus 报告的控制序列。 */
+export const TUI_TERMINAL_FOCUS_DISABLE = "\u001b[?1004l";
+/** 进入备用屏并清屏的控制序列。 */
+export const TUI_ALTERNATE_SCREEN_ENABLE = "\u001b[?1049h\u001b[2J\u001b[H";
+/** 退出备用屏的控制序列。 */
+export const TUI_ALTERNATE_SCREEN_DISABLE = "\u001b[?1049l";
+/** inline TUI 缩窄时清除当前视口和已保存的 scrollback，避免旧帧可被向上滚动看到。 */
+export const TUI_INLINE_RESIZE_CLEAR = "\u001b[2J\u001b[3J\u001b[H";
+/** 启用鼠标追踪（含 SGR 扩展模式）的控制序列。 */
+export const TUI_MOUSE_TRACKING_ENABLE = "\u001b[?1000h\u001b[?1002h\u001b[?1003h\u001b[?1006h";
+/** 关闭鼠标追踪的控制序列。 */
+export const TUI_MOUSE_TRACKING_DISABLE = "\u001b[?1006l\u001b[?1003l\u001b[?1002l\u001b[?1000l";
+/** Store 批量发布 answer delta 的间隔（毫秒）。 */
+export const TUI_EVENT_PUBLISH_INTERVAL_MS = 32;
+/** OSC 52 剪贴板的最大字节数。 */
+export const TUI_OSC52_MAX_BYTES = 100_000;

package/dist/tui/context.d.ts

@@ -0,0 +1,11 @@
+/** /context 的覆盖视图：渲染 Context Usage 安全报告，并提供底部灰色 Esc 退出提示。 */
+import type { ReactNode } from "react";
+import type { ContextUsageView } from "@autopilot-agent/core";
+/** 渲染当前 Context 报告覆盖视图；按键由 app.tsx 统一分发，避免创建第二套输入器。 */
+export declare function TuiContextReport(props: {
+    usage: ContextUsageView | null;
+    expanded: boolean;
+    columns: number;
+    useColor: boolean;
+    screenReader: boolean;
+}): ReactNode;

package/dist/tui/context.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { formatContextReportLines } from "../context-report.js";
+/** 渲染当前 Context 报告覆盖视图；按键由 app.tsx 统一分发，避免创建第二套输入器。 */
+export function TuiContextReport(props) {
+    // screen reader / NO_COLOR 跳过装饰网格但保留完整文本；与原 transcript 视图共用同一格式化函数。
+    const decorative = props.useColor && !(props.screenReader ?? false);
+    const lines = formatContextReportLines(props.usage, props.expanded, { grid: decorative, columns: props.columns });
+    return _jsxs(Box, { flexDirection: "column", width: props.columns, children: [lines.map(function renderReportLine(line, index) {
+                return _jsx(Text, { children: line }, String(index));
+            }), _jsxs(Text, { dimColor: props.useColor, children: ["Esc \u8FD4\u56DE\u804A\u5929", props.screenReader ? " · context report" : ""] })] });
+}

package/dist/tui/diff-stats.d.ts

@@ -0,0 +1,8 @@
+/** edit diff 统计渲染：新增和删除复用 unified diff 的既有语义色。 */
+import { type ReactNode } from "react";
+/** 渲染带有文本标记的新增/删除统计；NO_COLOR 下仍保留完整正负号。 */
+export declare function TuiDiffStats(props: {
+    added: number;
+    removed: number;
+    useColor: boolean;
+}): ReactNode;

package/dist/tui/diff-stats.js

@@ -0,0 +1,7 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from "ink";
+import { TUI_DIFF_ADDED_COLOR, TUI_DIFF_REMOVED_COLOR } from "../design-tokens.js";
+/** 渲染带有文本标记的新增/删除统计；NO_COLOR 下仍保留完整正负号。 */
+export function TuiDiffStats(props) {
+    return _jsxs(Text, { children: ["(", _jsxs(Text, { color: props.useColor ? TUI_DIFF_ADDED_COLOR : undefined, children: ["+", props.added] }), ", ", _jsxs(Text, { color: props.useColor ? TUI_DIFF_REMOVED_COLOR : undefined, children: ["-", props.removed] }), ")"] });
+}

package/dist/tui/format.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TUI 纯函数格式化工具：状态/工具/审批/权限标签、耗时与进度、工具行文案、
+ * 已消费输入文案和终端尺寸读取。本文件不依赖任何 React 组件。
+ */
+import type { CliAction, CliPublicEvent, CliStatusView, CliTurnStatus } from "../types.js";
+import type { CliTuiTimelineEvent } from "./types.js";
+/** 判断一个状态是否已经离开可继续执行的活动阶段；waiting_user_input 是可恢复等待，不算终态。 */
+export declare function isTerminalStatus(status: CliTurnStatus): boolean;
+/** 判断 Turn 是否仍可由 Ctrl+C 或 Esc 请求 Runtime 取消。 */
+export declare function isActiveTuiStatus(status: CliTurnStatus): boolean;
+/** 将内部生命周期状态转换为用户视角的短状态。 */
+export declare function getTuiStatusLabel(status: CliTurnStatus): string;
+/** 从 CLI 安全事件中读取失败终态原因，不访问 Runtime 原始错误。 */
+export declare function getTuiTurnFailureReason(events: CliTuiTimelineEvent[]): string | undefined;
+/** 从 CLI 安全状态事件读取终态原因、恢复性与预算摘要；只解释最新生命周期状态，当前状态非终态时不复活旧 pause 的 termination。 */
+export declare function getTuiTerminationSummary(events: CliTuiTimelineEvent[], currentStatus?: CliTurnStatus): string | undefined;
+/** 将内部工具名映射为面向用户的动作名称。 */
+export declare function getTuiToolLabel(toolName: string): string;
+/** 清理工具摘要中的内部名称与重复前缀。 */
+export declare function cleanTuiToolSummary(toolName: string, summary: string): string;
+/** 将 0..1 的动画进度限制在可渲染范围。 */
+export declare function clampTuiProgress(value: number): number;
+/** 将耗时格式化为稳定的 h/m/s，避免长任务只显示一个不断增长的秒数。 */
+export declare function formatTuiDuration(durationMs: number): string;
+/** 工具结果行的分段：glyph 是状态文字标签，badge 是 [动作名] 徽标文本，rest 是徽标后的详情或失败原因。 */
+export interface TuiToolLineParts {
+    glyph?: string;
+    badge: string;
+    rest: string;
+}
+/** 将工具执行结果拆分为 glyph/徽标/详情三段；彩色 chip 渲染与纯文本出口共用同一份布局事实。 */
+export declare function getTuiToolLineParts(toolName: string, summary: string, status?: Extract<CliPublicEvent, {
+    type: "tool_result";
+}>["status"], errorCode?: string): TuiToolLineParts;
+/** 将工具执行结果映射为稳定、简短的用户视角结果行；徽标固定为 [动作名]，NO_COLOR 下即退化形态。 */
+export declare function formatTuiToolLine(toolName: string, summary: string, status?: Extract<CliPublicEvent, {
+    type: "tool_result";
+}>["status"], errorCode?: string): string;
+/** 读取 edit diff 的新增/删除行数，兼容旧事件只携带文本的情况。 */
+export declare function getTuiDiffStats(diff?: {
+    text?: string;
+    added?: number;
+    removed?: number;
+}): {
+    added: number;
+    removed: number;
+} | undefined;
+/** 将 edit diff 统计格式化为 NO_COLOR 与纯文本出口共用的稳定文本。 */
+export declare function formatTuiDiffStats(diff?: {
+    text?: string;
+    added?: number;
+    removed?: number;
+}): string | undefined;
+/** 将内部错误码收敛为用户能理解的结果，不把 Core/工具实现细节直接打印到终端。 */
+export declare function getTuiToolFailureMessage(status: Extract<CliPublicEvent, {
+    type: "tool_result";
+}>["status"], errorCode?: string, detail?: string): string;
+/** 将已由 Controller 成功投递的输入统一为可读的插入提示。 */
+export declare function formatTuiInputConsumed(event: Extract<CliTuiTimelineEvent, {
+    type: "tui_input_consumed";
+}>): string;
+/** 将 Core 权限模式转换为状态栏可读的中文标签。 */
+export declare function getTuiPermissionModeLabel(mode: CliStatusView["permissionMode"]): string;
+/** 将审批决定映射为稳定中文标签；历史时间线与动态时间线共用同一份映射。 */
+export declare function getTuiApprovalDecisionLabel(decision: Extract<CliAction, {
+    type: "approve";
+}>["decision"]): string;
+/** 将终端流尺寸收敛为 TUI 布局使用的列/行数；宽度保留最小 30、最大 120 的既有约束。 */
+export declare function readTuiTerminalSize(stdout: {
+    columns?: number;
+    rows?: number;
+}): {
+    columns: number;
+    rows: number;
+};

package/dist/tui/format.js

@@ -0,0 +1,176 @@
+/**
+ * TUI 纯函数格式化工具：状态/工具/审批/权限标签、耗时与进度、工具行文案、
+ * 已消费输入文案和终端尺寸读取。本文件不依赖任何 React 组件。
+ */
+import { formatAgentTermination } from "../termination-format.js";
+/** 判断一个状态是否已经离开可继续执行的活动阶段；waiting_user_input 是可恢复等待，不算终态。 */
+export function isTerminalStatus(status) {
+    return status !== "idle" && status !== "running" && status !== "waiting_approval" && status !== "waiting_user_input";
+}
+/** 判断 Turn 是否仍可由 Ctrl+C 或 Esc 请求 Runtime 取消。 */
+export function isActiveTuiStatus(status) {
+    return status === "running" || status === "waiting_approval";
+}
+/** 将内部生命周期状态转换为用户视角的短状态。 */
+export function getTuiStatusLabel(status) {
+    switch (status) {
+        case "idle": return "Ready";
+        case "running": return "Working";
+        case "waiting_approval": return "Waiting for approval";
+        case "waiting_user_input": return "Waiting for Web answer";
+        case "interrupted": return "Stopped";
+        case "interrupted_recoverable": return "Paused — resume available";
+        case "completed": return "Completed";
+        case "failed": return "Failed";
+        case "limit_reached": return "Limit reached — resume available";
+    }
+}
+/** 从 CLI 安全事件中读取失败终态原因，不访问 Runtime 原始错误。 */
+export function getTuiTurnFailureReason(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type === "status" && event.status === "failed" && event.reason)
+            return event.reason;
+    }
+    return undefined;
+}
+/** 只有真实中断或失败终态才允许解释 termination；进行中与等待状态不得从旧事件复活终态。 */
+function isRealTurnEndStatus(status) {
+    return status === "interrupted" || status === "interrupted_recoverable" || status === "failed" || status === "limit_reached";
+}
+/** 从 CLI 安全状态事件读取终态原因、恢复性与预算摘要；只解释最新生命周期状态，当前状态非终态时不复活旧 pause 的 termination。 */
+export function getTuiTerminationSummary(events, currentStatus) {
+    if (currentStatus !== undefined && !isRealTurnEndStatus(currentStatus))
+        return undefined;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type === "status")
+            return event.termination && isRealTurnEndStatus(event.status) ? formatAgentTermination(event.termination) : undefined;
+    }
+    return undefined;
+}
+/** 将内部工具名映射为面向用户的动作名称。 */
+export function getTuiToolLabel(toolName) {
+    switch (toolName) {
+        case "glob_files": return "查找文件";
+        case "grep_files": return "搜索代码";
+        case "read_file": return "查看文件";
+        case "write_file": return "写入文件";
+        case "edit_file": return "修改文件";
+        case "run_command": return "运行命令";
+        default: return "处理任务";
+    }
+}
+/** 清理工具摘要中的内部名称与重复前缀。 */
+export function cleanTuiToolSummary(toolName, summary) {
+    // run_command 的 started summary 已由 Core 脱敏为 `$ command`，这是树状进度中唯一需要保留的命令细节。
+    if (toolName === "run_command")
+        return summary;
+    const withoutToolName = summary.replace(new RegExp(`^${toolName}:\\s*`, "i"), "");
+    if (toolName === "glob_files")
+        return withoutToolName.replace(/^Searching files:\s*/i, "");
+    if (toolName === "grep_files")
+        return withoutToolName.replace(/^Searching code:\s*/i, "");
+    if (toolName === "read_file")
+        return withoutToolName.replace(/^Reading\s+/i, "");
+    return withoutToolName;
+}
+/** 将 0..1 的动画进度限制在可渲染范围。 */
+export function clampTuiProgress(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/** 将耗时格式化为稳定的 h/m/s，避免长任务只显示一个不断增长的秒数。 */
+export function formatTuiDuration(durationMs) {
+    const totalSeconds = Math.round(Math.max(0, durationMs) / 1000);
+    if (totalSeconds === 0)
+        return "<1s";
+    const hours = Math.floor(totalSeconds / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = totalSeconds % 60;
+    if (hours > 0)
+        return `${hours}h ${String(minutes).padStart(2, "0")}m ${String(seconds).padStart(2, "0")}s`;
+    if (minutes > 0)
+        return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+    return `${seconds}s`;
+}
+/** 将工具执行结果拆分为 glyph/徽标/详情三段；彩色 chip 渲染与纯文本出口共用同一份布局事实。 */
+export function getTuiToolLineParts(toolName, summary, status, errorCode) {
+    const label = getTuiToolLabel(toolName);
+    const detail = cleanTuiToolSummary(toolName, summary).trim();
+    if (status === undefined)
+        return { badge: `[${label}]`, rest: detail ? ` · ${detail}` : "" };
+    if (status === "success")
+        return { glyph: "✓", badge: `[${label}]`, rest: toolName === "run_command" ? "" : detail ? ` · ${detail}` : "" };
+    return { glyph: "✗", badge: `[${label}]`, rest: ` · ${getTuiToolFailureMessage(status, errorCode, detail)}` };
+}
+/** 将工具执行结果映射为稳定、简短的用户视角结果行；徽标固定为 [动作名]，NO_COLOR 下即退化形态。 */
+export function formatTuiToolLine(toolName, summary, status, errorCode) {
+    const parts = getTuiToolLineParts(toolName, summary, status, errorCode);
+    return `${parts.glyph ? `${parts.glyph} ` : ""}${parts.badge}${parts.rest}`;
+}
+/** 读取 edit diff 的新增/删除行数，兼容旧事件只携带文本的情况。 */
+export function getTuiDiffStats(diff) {
+    if (!diff)
+        return undefined;
+    const lines = diff.text?.replace(/\r\n?/g, "\n").split("\n");
+    const added = diff.added ?? lines?.filter(function countAdded(line) { return line.startsWith("+") && !line.startsWith("+++"); }).length;
+    const removed = diff.removed ?? lines?.filter(function countRemoved(line) { return line.startsWith("-") && !line.startsWith("---"); }).length;
+    if (added === undefined && removed === undefined)
+        return undefined;
+    return { added: added ?? 0, removed: removed ?? 0 };
+}
+/** 将 edit diff 统计格式化为 NO_COLOR 与纯文本出口共用的稳定文本。 */
+export function formatTuiDiffStats(diff) {
+    const statistics = getTuiDiffStats(diff);
+    return statistics ? `(+${statistics.added}, -${statistics.removed})` : undefined;
+}
+/** 将内部错误码收敛为用户能理解的结果，不把 Core/工具实现细节直接打印到终端。 */
+export function getTuiToolFailureMessage(status, errorCode, detail) {
+    if (status === "approval_required")
+        return "需要确认";
+    if (status === "question_required")
+        return "请在支持结构化回答的 Web 中处理";
+    if (status === "denied")
+        return "已拒绝";
+    if (status === "cancelled")
+        return "已取消";
+    if (status === "timeout")
+        return "执行超时";
+    if (status === "error" && detail?.startsWith("Exit "))
+        return "命令执行失败";
+    switch (errorCode) {
+        case "FILE_NOT_READ": return "读取文件失败";
+        case "FILE_NOT_WRITTEN": return "写入文件失败";
+        case "FILE_EDIT_FAILED": return "修改文件失败";
+        case "PERMISSION_DENIED": return "权限不足";
+        case "TOOL_EXECUTION_FAILED":
+        case "COMMAND_FAILED":
+            return "工具执行失败";
+        default:
+            return detail && !/^[A-Z][A-Z0-9_]+$/.test(detail) ? detail : "工具执行失败";
+    }
+}
+/** 将已由 Controller 成功投递的输入统一为可读的插入提示。 */
+export function formatTuiInputConsumed(event) {
+    const label = event.delivery === "queue" ? "[排队]" : "[引导]";
+    return `${label} you: ${event.content} · 已插入当前 turn`;
+}
+/** 将 Core 权限模式转换为状态栏可读的中文标签。 */
+export function getTuiPermissionModeLabel(mode) {
+    if (mode === "auto_approve")
+        return "为我审批";
+    if (mode === "full_access")
+        return "完全访问";
+    return "询问";
+}
+/** 将审批决定映射为稳定中文标签；历史时间线与动态时间线共用同一份映射。 */
+export function getTuiApprovalDecisionLabel(decision) {
+    return decision === "allow_once" ? "本次" : decision === "allow_session" ? "本次会话" : decision === "allow_workspace" ? "此工作区" : "拒绝";
+}
+/** 将终端流尺寸收敛为 TUI 布局使用的列/行数；宽度保留最小 30、最大 120 的既有约束。 */
+export function readTuiTerminalSize(stdout) {
+    return {
+        columns: Math.max(30, Math.min(Number(stdout.columns ?? 80) - 2, 120)),
+        rows: Math.max(8, Number(stdout.rows ?? 24)),
+    };
+}

package/dist/tui/hooks/use-file-mention-index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * TUI @文件提及的索引预热：挂载后调用一次 Core `listWorkspaceFiles`，模块级缓存供整个会话复用。
+ * 空查询候选由「工作区一层目录（尾随 /）+ 全部文件」合并稳定排序构成；失败静默降级为空候选。
+ */
+/** useFileMentionIndex 的返回契约；ready 为 false 时 @ 菜单不激活。 */
+export interface FileMentionIndex {
+    /** 目录（尾随 /）与文件的稳定排序候选池。 */
+    entries: string[];
+    /** 索引是否已就绪（成功或失败终态）。 */
+    ready: boolean;
+}
+/** 清空模块级 @ 索引缓存；仅供测试在用例间隔离。 */
+export declare function resetFileMentionIndexCache(): void;
+/** 挂载后预热 @ 文件索引；workspaceRoot 缺失或 Core 枚举失败时静默降级为空候选，不影响普通输入。 */
+export declare function useFileMentionIndex(workspaceRoot: string | undefined): FileMentionIndex;