@autopilot-agent/cli 0.0.0-stage → 0.2.0

package/dist/tui/todo-list.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Text } from "ink";
+import stringWidth from "string-width";
+import { selectTimeline } from "@autopilot-agent/presentation";
+import { TUI_ACCENT_COLOR } from "../design-tokens.js";
+import { splitTuiInputGraphemes } from "./input/graphemes.js";
+/** 展开态按终端高度最多显示的任务行数；超出部分以隐藏计数提示。 */
+const TUI_TODO_EXPANDED_ROW_LIMIT = 10;
+/** 展开清单里每行文字可用的最大列数下限，避免极窄终端下行宽为负。 */
+const TUI_TODO_MIN_ROW_WIDTH = 12;
+/** 取得 Todo 状态的中文文字标签，供 screen reader 与 NO_COLOR 场景朗读。 */
+export function getTuiTodoStatusLabel(status) {
+    if (status === "in_progress")
+        return "进行中";
+    if (status === "completed")
+        return "已完成";
+    return "待处理";
+}
+/** 从共享 Presentation 读取当前 Turn 任务链的 in_progress activeForm，作为活动状态的稳定文案。 */
+export function getTuiTodoActiveForm(presentation, turnId) {
+    if (!presentation)
+        return undefined;
+    const todoItem = selectTimeline(presentation).find(function findTodoItem(item) {
+        return item.kind === "todo" && "turnId" in item && item.turnId === turnId;
+    });
+    if (todoItem?.kind !== "todo")
+        return undefined;
+    return todoItem.todos.find(function findActiveTodo(todo) { return todo.status === "in_progress"; })?.activeForm;
+}
+/** 取得 Todo 状态的纯文本 glyph，颜色不是唯一状态载体。 */
+export function getTuiTodoStatusGlyph(status) {
+    if (status === "in_progress")
+        return "■";
+    if (status === "completed")
+        return "✓";
+    return "□";
+}
+/** 按显示宽度做 grapheme 安全截断，中英文与组合 emoji 不会截出半字。 */
+export function truncateTuiTodoText(text, maximumWidth) {
+    if (stringWidth(text) <= maximumWidth)
+        return text;
+    const graphemes = splitTuiInputGraphemes(text);
+    let width = 0;
+    let output = "";
+    for (const grapheme of graphemes) {
+        const nextWidth = width + stringWidth(grapheme);
+        if (nextWidth > maximumWidth - 1)
+            break;
+        width = nextWidth;
+        output += grapheme;
+    }
+    return `${output}…`;
+}
+/** 按优先级（in_progress → 最近完成 → pending）在行数上限内挑选可见任务，保持原清单顺序展示。 */
+export function orderTuiTodoItems(todos, limit = TUI_TODO_EXPANDED_ROW_LIMIT) {
+    if (todos.length <= limit)
+        return { shown: [...todos], hidden: 0 };
+    // 超限时为 hidden 摘要预留一行，保证展开态总行数不会超过 limit。
+    const taskLimit = Math.max(1, limit - 1);
+    const inProgress = todos.filter(function isInProgress(todo) { return todo.status === "in_progress"; });
+    const recentCompletedFirst = [...todos].reverse().filter(function isCompleted(todo) { return todo.status === "completed"; });
+    const pending = todos.filter(function isPending(todo) { return todo.status === "pending"; });
+    const keep = new Set();
+    for (const candidate of [...inProgress, ...recentCompletedFirst, ...pending]) {
+        if (keep.size >= taskLimit)
+            break;
+        keep.add(candidate);
+    }
+    const shown = todos.filter(function isKept(todo) { return keep.has(todo); });
+    return { shown, hidden: todos.length - shown.length };
+}
+/** 生成 Todo 视图的共享展示数据；紧凑态一行，展开态为 header + 任务行 + 隐藏计数。 */
+export function getTuiTodoDisplay(item, options) {
+    if (item.todos.length === 0)
+        return undefined;
+    const total = item.todos.length;
+    const completed = item.counts.completed;
+    const activeTodo = item.todos.find(function findActiveTodo(todo) { return todo.status === "in_progress"; });
+    if (!options.expanded) {
+        const headerWidth = Math.max(TUI_TODO_MIN_ROW_WIDTH, options.columns - 2);
+        if (!activeTodo)
+            return { header: `Todo ${completed}/${total}`, rows: [], hidden: 0 };
+        // activeForm 的可用列数需扣除 'Todo x/y · ' 前缀，保证紧凑行整体不超出终端宽度。
+        const prefix = `Todo ${completed}/${total} · `;
+        const activeFormWidth = headerWidth - stringWidth(prefix);
+        return {
+            header: `${prefix}${activeFormWidth > 0 ? truncateTuiTodoText(activeTodo.activeForm, activeFormWidth) : ""}`,
+            activeForm: activeTodo.activeForm,
+            rows: [],
+            hidden: 0,
+        };
+    }
+    const { shown, hidden } = orderTuiTodoItems(item.todos, options.rowLimit ?? TUI_TODO_EXPANDED_ROW_LIMIT);
+    const rowWidth = Math.max(TUI_TODO_MIN_ROW_WIDTH, options.columns - 4);
+    const rows = shown.map(function createDisplayRow(todo) {
+        return { status: todo.status, text: truncateTuiTodoText(todo.content, rowWidth) };
+    });
+    return {
+        header: `Todo ${completed}/${total}`,
+        activeForm: activeTodo?.activeForm,
+        rows: hidden > 0 ? [...rows, { status: "pending", text: `${hidden} hidden`, hidden: true }] : rows,
+        hidden,
+    };
+}
+/** 渲染 Todo 任务链的 Ink 视图；screen reader 时每行前缀中文状态文字。 */
+export function TuiTodoList(props) {
+    const display = getTuiTodoDisplay(props.item, { expanded: props.expanded, screenReader: props.screenReader, columns: props.columns, rowLimit: props.rowLimit });
+    if (!display)
+        return null;
+    return (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, children: display.header }), display.rows.map(function renderTodoRow(row, index) {
+                if (row.hidden)
+                    return _jsxs(Text, { dimColor: props.useColor, children: ["+", row.text] }, `todo-row-${index}`);
+                const label = props.screenReader || !props.useColor ? `[${getTuiTodoStatusLabel(row.status)}] ` : `${getTuiTodoStatusGlyph(row.status)} `;
+                if (row.status === "completed")
+                    return _jsxs(Text, { dimColor: props.useColor, strikethrough: true, children: [label, row.text] }, `todo-row-${index}`);
+                if (row.status === "in_progress")
+                    return _jsxs(Text, { bold: true, color: props.useColor ? TUI_ACCENT_COLOR : undefined, children: [label, row.text] }, `todo-row-${index}`);
+                return _jsxs(Text, { children: [label, row.text] }, `todo-row-${index}`);
+            }), props.showToggleHint ? _jsxs(Text, { dimColor: props.useColor, children: ["Ctrl+O ", props.expanded ? "收起" : "展开"] }) : null] }));
+}

package/dist/tui/transcript.d.ts

@@ -0,0 +1,24 @@
+/** transcript 节点渲染：用户 prompt、通知、完整历史 Turn 与动态等待输入。 */
+import { type ReactNode } from "react";
+import type { CliTuiPendingInput, CliTuiTranscriptItem } from "./types.js";
+/** 渲染一个用户 prompt；当前 Turn 会暂留在动态区，避免历史区固化时机丢失。@文件 片段用强调色加粗。 */
+export declare function TuiPromptLine(props: {
+    content: string;
+    useColor: boolean;
+    columns: number;
+    keyValue?: string;
+}): ReactNode;
+/** 渲染已经完成的 prompt、notice 或完整 Turn。 */
+export declare function TuiTranscriptItem(props: {
+    item: CliTuiTranscriptItem;
+    useColor: boolean;
+    columns: number;
+    screenReader?: boolean;
+}): ReactNode;
+/** 历史节点保持引用稳定；回答流动时只重新计算当前 Turn。 */
+export declare const MemoizedTuiTranscriptItem: import("react").MemoExoticComponent<typeof TuiTranscriptItem>;
+/** queue 在等待区显示原文；steer 正文已按提交位置留在所属轮。 */
+export declare function TuiPendingInputItem(props: {
+    item: CliTuiPendingInput;
+    useColor: boolean;
+}): ReactNode;

package/dist/tui/transcript.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** transcript 节点渲染：用户 prompt、通知、完整历史 Turn 与动态等待输入。 */
+import { memo } from "react";
+import { Box, Text } from "ink";
+import { TUI_ACCENT_COLOR, TUI_PROMPT_BACKGROUND_COLOR, TUI_WAITING_BACKGROUND_COLOR } from "../design-tokens.js";
+import { splitTuiFileMentionSegments } from "./input/file-mention.js";
+import { renderTimeline } from "./timeline/static-timeline.js";
+/** 渲染一个用户 prompt；当前 Turn 会暂留在动态区，避免历史区固化时机丢失。@文件 片段用强调色加粗。 */
+export function TuiPromptLine(props) {
+    const segments = splitTuiFileMentionSegments(props.content);
+    return (_jsx(Box, { width: props.columns, paddingX: 1, backgroundColor: props.useColor ? TUI_PROMPT_BACKGROUND_COLOR : undefined, children: _jsx(Text, { color: props.useColor ? TUI_ACCENT_COLOR : undefined, children: segments.map(function renderPromptSegment(segment, index) {
+                if (!segment.isMention)
+                    return _jsx(Text, { children: segment.text }, index);
+                return _jsx(Text, { bold: props.useColor, children: segment.text }, index);
+            }) }) }, props.keyValue));
+}
+/** 渲染已经完成的 prompt、notice 或完整 Turn。 */
+export function TuiTranscriptItem(props) {
+    const item = props.item;
+    if (item.kind === "prompt") {
+        return _jsx(TuiPromptLine, { content: item.content, useColor: props.useColor, columns: props.columns, keyValue: item.key }, item.key);
+    }
+    if (item.kind === "notice") {
+        return _jsxs(Text, { dimColor: props.useColor, children: ["info: ", item.message] }, item.key);
+    }
+    return (_jsx(Box, { flexDirection: "column", children: renderTimeline(item.events, props.useColor, item, Math.max(1, props.columns - 2), props.screenReader ?? false) }, item.key));
+}
+/** 历史节点保持引用稳定；回答流动时只重新计算当前 Turn。 */
+export const MemoizedTuiTranscriptItem = memo(TuiTranscriptItem);
+/** queue 在等待区显示原文；steer 正文已按提交位置留在所属轮。 */
+export function TuiPendingInputItem(props) {
+    const label = props.item.delivery === "queue" ? "[排队]" : "[引导]";
+    return (_jsxs(Box, { flexDirection: "column", backgroundColor: props.useColor ? TUI_WAITING_BACKGROUND_COLOR : undefined, children: [props.item.delivery === "queue" ? _jsx(Text, { children: props.item.content }) : null, _jsxs(Text, { dimColor: props.useColor, children: ["\u21B3 ", label, " \u7B49\u5F85\u5F53\u524D\u6B65\u9AA4\u7ED3\u675F"] })] }, props.item.key));
+}

package/dist/tui/trust-dialog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CLI 首次 Trust 确认对话框。
+ *
+ * 只在信任建立前渲染 canonical 工作区与 Yes/No 选择；不读取任何工作区配置、
+ * 不初始化 Provider，也不创建 Runtime/Project/Session。授权只通过用户显式确认。
+ */
+import { type ReactNode } from "react";
+import { type Key } from "ink";
+/** Trust 对话框固定选项；Yes 是唯一授权动作。 */
+export declare const TRUST_DIALOG_OPTIONS: readonly [{
+    readonly value: "grant";
+    readonly label: "是，我信任此工作区";
+}, {
+    readonly value: "decline";
+    readonly label: "否，退出";
+}];
+/** 将按键归一为 Trust 对话框的焦点移动或确认/取消动作。 */
+export declare function resolveTrustDialogNavigation(input: string, key: Key, current: number): {
+    next: number;
+    action?: "confirm" | "cancel";
+};
+/** 渲染首次 Trust 确认卡；直角单线、warning 语义，路径只在交互 TTY 显示。 */
+export declare function TuiTrustDialog(props: {
+    workspaceRoot: string;
+    selectedIndex: number;
+    useColor: boolean;
+    screenReader: boolean;
+}): ReactNode;
+/** Trust 对话框的信号来源；与 main.ts 的 CliSignalSource 结构兼容。 */
+export interface CliTrustDialogSignalSource {
+    on(signal: "SIGINT" | "SIGTERM", listener: () => void): void;
+    removeListener(signal: "SIGINT" | "SIGTERM", listener: () => void): void;
+}
+/** 首次 Trust 对话框的运行选项。 */
+export interface CliTrustDialogOptions {
+    workspaceRoot: string;
+    streams: {
+        stdout: {
+            write(chunk: string): void;
+            isTTY?: boolean;
+            columns?: number;
+        };
+        stdin: NodeJS.ReadStream;
+    };
+    env?: NodeJS.ProcessEnv;
+    signalSource?: CliTrustDialogSignalSource;
+}
+/** 首次 Trust 决策；granted 表示用户显式授权。 */
+export type CliTrustDecision = "granted" | "declined";
+/** 在交互 TTY 渲染首次 Trust 对话框并等待用户决定。 */
+export declare function runCliTrustDialog(options: CliTrustDialogOptions): Promise<CliTrustDecision>;

package/dist/tui/trust-dialog.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * CLI 首次 Trust 确认对话框。
+ *
+ * 只在信任建立前渲染 canonical 工作区与 Yes/No 选择；不读取任何工作区配置、
+ * 不初始化 Provider，也不创建 Runtime/Project/Session。授权只通过用户显式确认。
+ */
+import { useRef, useState } from "react";
+import { Box, Text, render, useInput } from "ink";
+import { TUI_ACCENT_COLOR } from "../design-tokens.js";
+import { parseTuiControlAction } from "./input/keys.js";
+import { createRoutedTuiStdin, createTuiTerminalLifecycle } from "./lifecycle.js";
+import { resolveNoColor, resolveScreenReader } from "./render-mode.js";
+/** Trust 对话框固定选项；Yes 是唯一授权动作。 */
+export const TRUST_DIALOG_OPTIONS = [
+    { value: "grant", label: "是，我信任此工作区" },
+    { value: "decline", label: "否，退出" },
+];
+/** 将按键归一为 Trust 对话框的焦点移动或确认/取消动作。 */
+export function resolveTrustDialogNavigation(input, key, current) {
+    const control = parseTuiControlAction(input, key);
+    if (control === "interrupt" || control === "cancel")
+        return { next: current, action: "cancel" };
+    if (key.upArrow)
+        return { next: Math.max(0, current - 1) };
+    if (key.downArrow)
+        return { next: Math.min(TRUST_DIALOG_OPTIONS.length - 1, current + 1) };
+    if (key.return)
+        return { next: current, action: "confirm" };
+    return { next: current };
+}
+/** 渲染首次 Trust 确认卡；直角单线、warning 语义，路径只在交互 TTY 显示。 */
+export function TuiTrustDialog(props) {
+    const selectedIndex = Math.max(0, Math.min(props.selectedIndex, TRUST_DIALOG_OPTIONS.length - 1));
+    return (_jsxs(Box, { borderStyle: "single", borderColor: props.useColor ? TUI_ACCENT_COLOR : undefined, paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, color: props.useColor ? TUI_ACCENT_COLOR : undefined, children: "\u8BBF\u95EE\u5DE5\u4F5C\u533A" }), _jsx(Text, { children: props.workspaceRoot }), _jsx(Text, { children: "\u4EC5\u5F53\u8FD9\u662F\u4F60\u521B\u5EFA\u6216\u4FE1\u4EFB\u7684\u9879\u76EE\u65F6\u7EE7\u7EED\u3002" }), _jsx(Text, { children: "Agent \u5C06\u80FD\u591F\u5728\u6B64\u5DE5\u4F5C\u533A\u5185\u8BFB\u53D6\u3001\u7F16\u8F91\u548C\u6267\u884C\u6587\u4EF6\u3002" }), TRUST_DIALOG_OPTIONS.map(function renderTrustOption(option, index) {
+                const selected = index === selectedIndex;
+                return _jsxs(Text, { inverse: selected && props.useColor, children: [selected ? "›" : " ", " ", option.label, selected && props.screenReader ? "（已选择）" : ""] }, option.value);
+            }), _jsx(Text, { dimColor: props.useColor, children: "\u2191/\u2193 \u9009\u62E9 \u00B7 Enter \u786E\u8BA4 \u00B7 Esc/Ctrl+C \u9000\u51FA" })] }));
+}
+/** 在交互 TTY 渲染首次 Trust 对话框并等待用户决定。 */
+export function runCliTrustDialog(options) {
+    return new Promise(function runTrustDialog(resolve) {
+        const env = options.env ?? process.env;
+        const noColor = resolveNoColor(env);
+        const screenReader = resolveScreenReader(env);
+        const routedStdin = createRoutedTuiStdin(options.streams.stdin);
+        const terminalLifecycle = createTuiTerminalLifecycle(options.streams.stdout, "inline");
+        let decision = "declined";
+        let settled = false;
+        let instance;
+        /** 把真实 TTY 的按键数据原样转发给 Ink 专用输入流；Trust 对话框不参与鼠标路由。 */
+        function forwardTrustInput(chunk) {
+            routedStdin.write(chunk);
+        }
+        /** stdin 到达 EOF 时结束 Ink 输入流。 */
+        function finishTrustInput() {
+            routedStdin.end();
+        }
+        /** 移除真实 stdin 转发监听并结束 Ink 输入流，所有退出路径只清理一次。 */
+        function detachTrustInput() {
+            options.streams.stdin.removeListener("data", forwardTrustInput);
+            options.streams.stdin.removeListener("end", finishTrustInput);
+            routedStdin.end();
+        }
+        options.streams.stdin.on("data", forwardTrustInput);
+        options.streams.stdin.once("end", finishTrustInput);
+        /** 记录最终决定并请求 Ink 卸载；终端恢复在 waitUntilExit 后统一执行。 */
+        function settle(next) {
+            if (settled)
+                return;
+            settled = true;
+            decision = next;
+            // Inline 模式下 unmount 会保留最后一帧；先清理，避免 Trust 卡片残留在后续 TUI 上方。
+            instance?.clear();
+            instance?.unmount();
+        }
+        function handleSigint() { settle("declined"); }
+        function handleSigterm() { settle("declined"); }
+        options.signalSource?.on("SIGINT", handleSigint);
+        options.signalSource?.on("SIGTERM", handleSigterm);
+        /** 对话框主体：焦点与决策只在本组件内完成，不接触 Runtime。 */
+        function TrustDialogApp() {
+            const [selectedIndex, setSelectedIndex] = useState(0);
+            const selectedIndexRef = useRef(0);
+            function updateSelectedIndex(next) {
+                selectedIndexRef.current = next;
+                setSelectedIndex(next);
+            }
+            useInput(function handleTrustInput(input, key) {
+                const navigation = resolveTrustDialogNavigation(input, key, selectedIndexRef.current);
+                if (navigation.action === "confirm")
+                    settle(selectedIndexRef.current === 0 ? "granted" : "declined");
+                else if (navigation.action === "cancel")
+                    settle("declined");
+                else if (navigation.next !== selectedIndexRef.current)
+                    updateSelectedIndex(navigation.next);
+            });
+            return _jsx(TuiTrustDialog, { workspaceRoot: options.workspaceRoot, selectedIndex: selectedIndex, useColor: !noColor && !screenReader, screenReader: screenReader });
+        }
+        try {
+            terminalLifecycle.enter();
+            instance = render(_jsx(TrustDialogApp, {}), {
+                stdout: options.streams.stdout,
+                stdin: routedStdin,
+                exitOnCtrlC: false,
+                patchConsole: true,
+                incrementalRendering: false,
+                isScreenReaderEnabled: screenReader,
+            });
+        }
+        catch {
+            terminalLifecycle.restore();
+            detachTrustInput();
+            options.signalSource?.removeListener("SIGINT", handleSigint);
+            options.signalSource?.removeListener("SIGTERM", handleSigterm);
+            resolve("declined");
+            return;
+        }
+        void instance.waitUntilExit().then(function finishTrustDialog() {
+            terminalLifecycle.restore();
+            detachTrustInput();
+            options.signalSource?.removeListener("SIGINT", handleSigint);
+            options.signalSource?.removeListener("SIGTERM", handleSigterm);
+            resolve(decision);
+        });
+    });
+}

package/dist/tui/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * 仅 TUI 层自有类型。Controller / 投影 / 事件等宿主协议类型统一从
+ * ../types.js 与 ../controller.js 复用，不在这里重复声明领域协议。
+ */
+import type { CliActivityState } from "../activity-animation.js";
+import type { AgentPresentationState } from "@autopilot-agent/presentation";
+import type { ContextUsageView } from "@autopilot-agent/core";
+import type { CliController, CliControllerResult } from "../controller.js";
+import type { TuiSgrMouseEvent } from "../tui-input-router.js";
+import type { CliAction, CliExitCode, CliProjection, CliPublicEvent, CliQueuedInputStarted, CliTurnStatus } from "../types.js";
+/** TUI 中可固化的 transcript 节点。 */
+export type CliTuiTranscriptItem = {
+    kind: "prompt";
+    key: string;
+    content: string;
+} | {
+    kind: "notice";
+    key: string;
+    message: string;
+} | {
+    kind: "turn";
+    key: string;
+    turnId: string;
+    events: CliTuiTimelineEvent[];
+    presentation?: AgentPresentationState;
+    status: CliTurnStatus;
+    thoughtDurationMs?: number;
+    totalDurationMs?: number;
+};
+/** TUI 本地补充的时间线节点；不回流 Controller、Runtime 或持久化事件流。 */
+export type CliTuiTimelineEvent = CliPublicEvent | {
+    type: "tui_input_consumed";
+    seq: number;
+    turnId: string;
+    inputId: string;
+    content: string;
+    delivery: "steer" | "queue";
+    consumed?: boolean;
+    cancelled?: boolean;
+    position?: CliTuiInputPosition;
+} | {
+    type: "tui_approval_submitted";
+    seq: number;
+    turnId: string;
+    approvalId: string;
+    decision: Extract<CliAction, {
+        type: "approve";
+    }>["decision"];
+};
+/** 动态区中尚未被 Core 消费的引导或排队输入。 */
+export interface CliTuiPendingInput {
+    key: string;
+    content: string;
+    inputId: string;
+    delivery: "steer" | "queue";
+}
+/** 提交瞬间的本地位置；只引用安全展示节点，不保存附件展开或私有消息。 */
+export interface CliTuiInputPosition {
+    turnId?: string;
+    eventCount: number;
+    order?: number;
+    items: Array<{
+        id: string;
+        answerLength?: number;
+    }>;
+}
+/** Turn 的本地展示计时；只用于 TUI 文案，不进入 Runtime 或持久化事件。 */
+export interface CliTuiTurnMetrics {
+    startedAt: number;
+    firstAnswerAt?: number;
+    completedAt?: number;
+}
+/** 当前 Turn 的用户输入；动态区保留它，避免历史区固化时机导致 prompt 消失。 */
+export interface CliTuiActivePrompt {
+    key: string;
+    content: string;
+    turnId?: string;
+}
+/** TUI 的不可变快照；快照不包含 Runtime 私有字段。 */
+export interface CliTuiSnapshot {
+    transcript: CliTuiTranscriptItem[];
+    activePrompt?: CliTuiActivePrompt;
+    pendingInputs: CliTuiPendingInput[];
+    liveTurnId?: string;
+    liveEvents: CliTuiTimelineEvent[];
+    /** 当前 Turn 的共享 Runtime Presentation 状态，供 inline 与备用屏使用同一 selector。 */
+    livePresentation?: AgentPresentationState;
+    liveMetrics?: CliTuiTurnMetrics;
+    hasLiveApprovalEvent: boolean;
+    activity: CliActivityState;
+    status: CliTurnStatus;
+    recoverable: boolean;
+    pendingApproval?: CliProjection["pendingApproval"];
+    activeSkills: Array<{
+        skillId: string;
+        contentHash: string;
+    }>;
+    /** 最近一次 context_usage 的安全 DTO；只驱动状态栏刷新，不进入时间线。 */
+    contextUsage?: ContextUsageView | null;
+    cancellationRequested: boolean;
+    requestedExitCode?: CliExitCode;
+}
+/** TUI Store 只负责把安全事件转成 React 可订阅快照。 */
+export interface CliTuiStore {
+    getSnapshot(): CliTuiSnapshot;
+    subscribe(listener: () => void): () => void;
+    recordPrompt(content: string, displayAsActive?: boolean): string | undefined;
+    captureInputPosition(): CliTuiInputPosition;
+    addPendingPrompt(content: string, input: {
+        inputId: string;
+        delivery: "steer" | "queue";
+    }, position?: CliTuiInputPosition): void;
+    markQueuedInputStarted(input: CliQueuedInputStarted): void;
+    recordApprovalSubmission(decision: Extract<CliAction, {
+        type: "approve";
+    }>["decision"]): void;
+    addNotice(message: string): void;
+    acceptEvent(event: CliPublicEvent, projection: CliProjection): void;
+    syncProjection(projection: CliProjection): void;
+    setCancellationRequested(requested: boolean): void;
+    requestExit(code: CliExitCode): void;
+}
+/** TUI 的启动操作；resume 不把完整 checkpoint 传入 UI。 */
+export type CliTuiInitialOperation = {
+    type: "start";
+    content: string;
+} | {
+    type: "resume";
+};
+/** Ink TUI 的运行参数。 */
+export interface RunCliTuiOptions {
+    controller: CliController;
+    /** 主机已知的只读会话标识；仅用于备用屏退出后的安全摘要。 */
+    sessionId?: string;
+    /** canonical 工作区根；仅用于 @ 文件候选索引预热。 */
+    workspaceRoot?: string;
+    streams: {
+        stdout: TuiOutputStream;
+        stderr: {
+            write(chunk: string): void;
+        };
+        stdin: NodeJS.ReadStream;
+    };
+    signalSource: {
+        on(signal: "SIGINT" | "SIGTERM", listener: () => void): void;
+        removeListener(signal: "SIGINT" | "SIGTERM", listener: () => void): void;
+    };
+    forceExit?(code: 130): void;
+    initial?: CliTuiInitialOperation;
+    closeWhenIdle: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/** TUI 读取终端尺寸所需的最小宿主流接口；resize 监听保持可选以兼容测试 double。 */
+export interface TuiTerminalSizeSource {
+    columns?: number;
+    rows?: number;
+    on?(event: "resize", listener: () => void): void;
+    off?(event: "resize", listener: () => void): void;
+}
+/** TUI 的最小输出流接口；Ink 渲染代理与真实 stdout 均实现此形状。 */
+export type TuiOutputStream = TuiTerminalSizeSource & {
+    write(chunk: string): void;
+    isTTY?: boolean;
+};
+/** TUI 运行结果；退出码仍由宿主 Main 统一解释。 */
+export interface RunCliTuiResult {
+    result: CliControllerResult;
+    exitCode: CliExitCode;
+}
+/** 退出备用屏后输出的最小安全会话摘要；不携带 Runtime 私有状态或存储位置。 */
+export interface CliTuiRecap {
+    sessionId: string;
+    completedTurnCount: number;
+    finalStatus: CliTurnStatus;
+    recoverable: boolean;
+}
+/** TUI 启动期一次性解析的终端渲染模式。 */
+export type TuiRenderMode = "inline" | "alternate-screen";
+/** 可幂等恢复终端控制序列的最小生命周期对象。 */
+export interface TuiTerminalLifecycle {
+    enter(): void;
+    reassert(): void;
+    restore(): void;
+}
+/** 备用屏向应用视口转交的鼠标事件入口；只保存一个当前处理器。 */
+export interface TuiMouseInputSink {
+    setHandler(handler: ((event: TuiSgrMouseEvent, wheelNotches: number) => void) | undefined): void;
+    dispatch(event: TuiSgrMouseEvent, wheelNotches?: number): void;
+}

package/dist/tui/types.js

@@ -0,0 +1,5 @@
+/**
+ * 仅 TUI 层自有类型。Controller / 投影 / 事件等宿主协议类型统一从
+ * ../types.js 与 ../controller.js 复用，不在这里重复声明领域协议。
+ */
+export {};

package/dist/tui/viewport/selection.d.ts

@@ -0,0 +1,27 @@
+/** 备用屏文字划选纯函数：来源坐标定位、跨行选区提取与平台剪贴板写入。 */
+import type { TimelineVisualLine } from "../../timeline-lines.js";
+/** 备用屏文字划选端点；始终关联纯文本时间线的来源坐标。 */
+export interface TuiTextSelectionPoint {
+    itemId: string;
+    sourceOffset: number;
+}
+/** 备用屏文字划选状态；锚点和焦点可跨多个视觉行。 */
+export interface TuiTextSelection {
+    anchor?: TuiTextSelectionPoint;
+    focus?: TuiTextSelectionPoint;
+}
+/** 将终端列坐标映射到视觉行的完整 grapheme 边界，避免截断中文和 emoji。 */
+export declare function resolveTuiVisualLineOffset(line: TimelineVisualLine, column: number): number;
+/** 在当前视觉行中定位选区端点，以便随 resize 后的换行重新找到来源坐标。 */
+export declare function findTuiSelectionLineIndex(lines: TimelineVisualLine[], point: TuiTextSelectionPoint): number;
+/** 从纯文本视觉行中提取跨行选区，供 Windows 剪贴板或 OSC 52 使用。 */
+export declare function getTuiSelectedText(lines: TimelineVisualLine[], selection: TuiTextSelection): string;
+/** 返回当前视觉行被选中的本地字符范围，用于仅反显实际拖拽到的文本。 */
+export declare function getTuiVisualLineSelectionRange(lines: TimelineVisualLine[], selection: TuiTextSelection, lineIndex: number): {
+    start: number;
+    end: number;
+} | undefined;
+/** 将当前选区交给平台剪贴板；Windows 不经 shell 调用 clip，其它平台使用有界 OSC 52。 */
+export declare function copyTuiSelectedText(text: string, stdout: {
+    write(chunk: string): void;
+}): void;

package/dist/tui/viewport/selection.js

@@ -0,0 +1,79 @@
+/** 备用屏文字划选纯函数：来源坐标定位、跨行选区提取与平台剪贴板写入。 */
+import { spawn } from "node:child_process";
+import stringWidth from "string-width";
+import { TUI_OSC52_MAX_BYTES } from "../constants.js";
+/** 将终端列坐标映射到视觉行的完整 grapheme 边界，避免截断中文和 emoji。 */
+export function resolveTuiVisualLineOffset(line, column) {
+    const targetColumn = Math.max(0, column);
+    let displayColumn = 0;
+    let offset = 0;
+    for (const segment of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(line.text)) {
+        const nextColumn = displayColumn + stringWidth(segment.segment);
+        if (targetColumn < nextColumn)
+            return line.sourceStart + offset;
+        displayColumn = nextColumn;
+        offset += segment.segment.length;
+    }
+    return line.sourceStart + line.text.length;
+}
+/** 在当前视觉行中定位选区端点，以便随 resize 后的换行重新找到来源坐标。 */
+export function findTuiSelectionLineIndex(lines, point) {
+    return lines.findIndex(function findSelectionLine(line) {
+        return line.itemId === point.itemId && point.sourceOffset >= line.sourceStart && point.sourceOffset <= line.sourceEnd;
+    });
+}
+/** 从纯文本视觉行中提取跨行选区，供 Windows 剪贴板或 OSC 52 使用。 */
+export function getTuiSelectedText(lines, selection) {
+    if (!selection.anchor || !selection.focus)
+        return "";
+    const anchorIndex = findTuiSelectionLineIndex(lines, selection.anchor);
+    const focusIndex = findTuiSelectionLineIndex(lines, selection.focus);
+    if (anchorIndex < 0 || focusIndex < 0)
+        return "";
+    const [startIndex, endIndex, startPoint, endPoint] = anchorIndex < focusIndex || anchorIndex === focusIndex && selection.anchor.sourceOffset <= selection.focus.sourceOffset
+        ? [anchorIndex, focusIndex, selection.anchor, selection.focus]
+        : [focusIndex, anchorIndex, selection.focus, selection.anchor];
+    const fragments = [];
+    for (let index = startIndex; index <= endIndex; index += 1) {
+        const line = lines[index];
+        if (!line)
+            continue;
+        const start = index === startIndex ? Math.max(0, startPoint.sourceOffset - line.sourceStart) : 0;
+        const end = index === endIndex ? Math.max(start, endPoint.sourceOffset - line.sourceStart) : line.text.length;
+        fragments.push(line.text.slice(start, end));
+    }
+    return fragments.join("\n");
+}
+/** 返回当前视觉行被选中的本地字符范围，用于仅反显实际拖拽到的文本。 */
+export function getTuiVisualLineSelectionRange(lines, selection, lineIndex) {
+    if (!selection.anchor || !selection.focus)
+        return undefined;
+    const anchorIndex = findTuiSelectionLineIndex(lines, selection.anchor);
+    const focusIndex = findTuiSelectionLineIndex(lines, selection.focus);
+    if (anchorIndex < 0 || focusIndex < 0)
+        return undefined;
+    const [startIndex, endIndex, startPoint, endPoint] = anchorIndex < focusIndex || anchorIndex === focusIndex && selection.anchor.sourceOffset <= selection.focus.sourceOffset
+        ? [anchorIndex, focusIndex, selection.anchor, selection.focus]
+        : [focusIndex, anchorIndex, selection.focus, selection.anchor];
+    if (lineIndex < startIndex || lineIndex > endIndex)
+        return undefined;
+    const line = lines[lineIndex];
+    if (!line)
+        return undefined;
+    const start = lineIndex === startIndex ? Math.max(0, startPoint.sourceOffset - line.sourceStart) : 0;
+    const end = lineIndex === endIndex ? Math.max(start, endPoint.sourceOffset - line.sourceStart) : line.text.length;
+    return start < end ? { start, end } : undefined;
+}
+/** 将当前选区交给平台剪贴板；Windows 不经 shell 调用 clip，其它平台使用有界 OSC 52。 */
+export function copyTuiSelectedText(text, stdout) {
+    if (!text)
+        return;
+    if (process.platform === "win32") {
+        const clipboard = spawn("clip", [], { stdio: "pipe", windowsHide: true });
+        clipboard.on("error", function ignoreClipboardFailure() { });
+        clipboard.stdin.end(text);
+        return;
+    }
+    const bytes = Buffer.from(text);
+    stdout.write(`\u001b]52;c;${bytes.subarray(0, TUI_OSC52_MAX_BYTES).toString("base64")}\u0007`);
+}