@epoch-agent/tui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1364 @@
+import * as React from 'react';
+import React__default from 'react';
+import { ModelRef, PermissionLevel, SelectionContext, SetSelectionResult, ModelSelection, ExpandedCommand, EpochFilePart, BackgroundTaskInfo, ApprovalRequest, ApprovalOutcome, ContextBreakdown, CustomCommandSource, EpochUserContent, AgentEvent, CustomCommandDef, KeybindingTable, ToolArtifact, TokenUsage, KeyChord, KeyContext, KeyAction } from '@epoch-agent/protocol';
+import { HistoryItemWithoutId } from '@epoch-agent/view';
+export { DIFF_CONTEXT_LINES, DIFF_MAX_LINES, DiffLine, DiffResult, HistoryItem, HistoryItemWithoutId, StreamReduceResult, applyStreamEvent, collapseContext, diffLines } from '@epoch-agent/view';
+import { Instance, Key } from 'ink';
+
+interface SelectOption<T> {
+    /** 选项正文 */
+    label: string;
+    value: T;
+    /** 右侧灰色补充说明 */
+    description?: string;
+    /** 危险选项（标红），比如「永久允许」「拒绝」 */
+    danger?: boolean;
+}
+
+/**
+ * 检查点与回退在 TUI 这一侧的形状（方案 27 PR-3）。
+ *
+ * 下面这几个是 core 那几个类型的**结构性镜像**，不是它们本身 —— 同
+ * `listTools` / `listSkills` 的既有做法：`CheckpointSummary` / `RewindPreview`
+ * 住在 core，而 tui 只依赖 protocol，够不着。逐字抄一份的代价是可能漂移，
+ * 换来的是 tui 不必为了画一个面板去依赖引擎；接线那一层
+ * （`cli/src/tui-host.ts`）有两条会红的用例守着这几个字段真的对得上。
+ *
+ * 单独成文件而不是塞进 `commands/types.ts`：那个文件是 `HostActions` 契约的家，
+ * 加完这一批就破 500 行的硬线了。语义全在 docs/CHECKPOINTS.md，这里只写形状。
+ */
+/** 检查点列表里的一条 */
+interface CheckpointEntry {
+    /** 会话内的轮次序号。它同时是 `preview` / `rewind` 的入参 */
+    turnIndex: number;
+    createdAt: number;
+    /** 用户那一轮说了什么（已截断），列表里靠它认人 */
+    preview: string;
+    /** 这一轮碰过几个文件 */
+    fileCount: number;
+    /**
+     * 快照本身就有文件没存进来（读失败 / 超单文件上限）。
+     *
+     * **必须显示出来**：回退这样一条检查点只能恢复一部分，而「部分回退」的工作区
+     * 比不回退更难收拾 —— 用户有权在按下去之前知道这件事。
+     */
+    incomplete: boolean;
+}
+/** 回退一个文件要做的动作。语义见 docs/CHECKPOINTS.md */
+type RewindFileAction = 'restore' | 'delete' | 'recreate' | 'skip';
+/** 现状相对「agent 留下它时」漂了没有 */
+type RewindFileDrift = 'as-agent-left-it' | 'changed-since' | 'unknown';
+interface RewindFileEntry {
+    path: string;
+    action: RewindFileAction;
+    drift: RewindFileDrift;
+}
+/** 按下去之前先给用户看的那一份 */
+interface RewindPlan {
+    turnIndex: number;
+    preview: string;
+    /**
+     * 对话那半能不能退。旧检查点、或者跑在没有持久化的内存模式里时为 false ——
+     * 那时只能退文件，面板要把那个选项**说明白**而不是让它静默失败
+     */
+    canRewindConversation: boolean;
+    incomplete: boolean;
+    /** 会被动的文件 */
+    files: RewindFileEntry[];
+    /**
+     * **不会**被动的：agent 改完之后又有人动过（你自己改的、terminal 里的命令改的）。
+     *
+     * 默认一个都不覆盖。要覆盖得由用户逐个点过头，把路径塞进 `rewind` 的
+     * `overwrite` —— 刻意没有「全部覆盖」那个按钮，它毁掉的是用户自己刚写的东西。
+     */
+    conflicts: RewindFileEntry[];
+}
+/** 回退的范围（方案 27 §2.4 的三选一） */
+type RewindScope = 'files' | 'conversation' | 'both';
+/** 回退完了到底动了什么。形状和 runtime 的 `RewindResult` 逐字对齐 */
+interface RewindReport {
+    /** 文件那半；`scope: 'conversation'` 时为 null（压根没做） */
+    files: {
+        restored: string[];
+        deleted: string[];
+        recreated: string[];
+        /** 因为漂过而没动的 */
+        skippedConflicts: string[];
+        /** 整体失败的原因；成功时缺席。**失败即什么都没改** */
+        failed?: string;
+    } | null;
+    /** 对话删掉了几条；没做 / 不支持 / 失败时 null */
+    messagesRemoved: number | null;
+}
+/**
+ * 检查点与回退能力（`HostActions.checkpoints`）。
+ *
+ * 三个方法一起给或一起不给：只给 `list` 的话，用户能选中一条然后什么都不会发生。
+ * 缺这一整项时 `/rewind` **压根不注册**（`SlashCommand.available`）、Esc Esc 也
+ * 不武装 —— 承诺一个不存在的安全网比没有安全网更糟。
+ */
+interface CheckpointActions {
+    /** 这个会话有哪些检查点，新的在前 */
+    list: () => Promise<readonly CheckpointEntry[]>;
+    /** 按下去之前先看：会动哪些文件、哪些因为漂过而不敢动。检查点不存在时回 null */
+    preview: (turnIndex: number) => Promise<RewindPlan | null>;
+    /**
+     * 真的退。`overwrite` 是用户**逐个点过头**的冲突文件路径，
+     * 不在里面的冲突一律跳过。
+     */
+    rewind: (turnIndex: number, opts: {
+        scope: RewindScope;
+        overwrite?: readonly string[];
+    }) => Promise<RewindReport>;
+}
+/** 回退完了要说的那一句：`ok: false` 表示工作区一个字节都没改 */
+interface RewindSummary {
+    text: string;
+    ok: boolean;
+}
+
+/**
+ * 宿主交给 TUI 的**只读展示形状**。
+ *
+ * 这几个的共同点是「引擎那边已经算完了，这里只负责画」：判定住在 core / runtime，
+ * 而 tui 不许 import core，所以过来的一律是字符串、布尔和数组。
+ * 单独一个文件是因为 [commands/types.ts](../commands/types.ts) 要放的是**契约**
+ * （`HostActions` / `SlashCommand`），而这几样是契约里传的**数据** ——
+ * 混在一起那个文件只会一直长。
+ */
+/**
+ * 企业托管策略在面板上的样子（方案 22 §2.6）。
+ */
+interface ManagedInfo {
+    /** 这台机器上到底有没有托管文件。没有 ≠ 三个开关全 false，措辞不一样 */
+    present: boolean;
+    /** 读的是哪个文件。管理员要知道该往哪儿放，所以不存在时也带着 */
+    path: string;
+    /** 打开了的元开关，逐条一句人话；全关时空数组 */
+    switches: readonly string[];
+}
+/**
+ * 一个已装插件在 `/plugin` 里的样子（方案 32）。
+ *
+ * `enabled` 和 `loaded` 是**两件事**，所以是两个字段而不是一个状态枚举：
+ * 前者是用户的意愿（记录里那个开关），后者是这次启动的事实。
+ * 「启用着但没加载」正是最需要被看见的那一格 —— 它意味着出了事，`reason` 说明是什么。
+ */
+interface PluginInfo {
+    name: string;
+    version: string;
+    /** 用户当初敲的那个来源字符串（`./my-plugin` / `github:owner/repo` / …） */
+    source: string;
+    enabled: boolean;
+    loaded: boolean;
+    /** 没加载时的原因；加载了就没有 */
+    reason?: string;
+    /**
+     * 这个插件带来的扩展物，每类一句人话（「3 条命令」「1 个 hook ⚠」）。
+     *
+     * 已经在宿主那侧算好：数它们要扫插件目录、要解析 `hooks.json`，
+     * 那份逻辑住在 core 的 `plugin/inventory.ts`，而 tui 不许 import core。
+     */
+    contributes: readonly string[];
+}
+/** 宿主读到的一张剪贴板图片。字段与 `EpochImagePart` 对齐，另带展示用的尺寸信息 */
+interface ClipboardImagePart {
+    /** 裸 base64，不带 `data:` 前缀 */
+    base64: string;
+    mediaType: string;
+    /** 原始字节数（不是 base64 长度） */
+    bytes: number;
+    width?: number;
+    height?: number;
+}
+
+/**
+ * 消息类型 — 基于 Google Gemini CLI types.ts
+ * @license Apache-2.0 (adapted from google-gemini/gemini-cli)
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * Modifications Copyright 2024-2026 bowen
+ *
+ * ---
+ *
+ * `HistoryItem*` 那一族已经搬去 `@epoch-agent/view` —— 浏览器端要用同一套
+ * （方案 20 §7）。留在这里的是**只有终端才有的**那几样。
+ */
+
+/**
+ * 一张计划卡片是哪种场合画的（方案 35 PR-2）。
+ *
+ * 前两档是**用户刚点的那个出口**；第三档是 `/plan show` 的回看形态 ——
+ * 它必须和前两档分开，因为那时只有计划正文，不知道当年按的是哪个出口
+ * （落盘的只有正文，见 `SessionMeta.plan`）。硬套一个 `execute` 就是在猜，
+ * 而猜错的那半句恰好是「你的文件现在能不能被改」。
+ */
+type PlanCardMode = 'execute' | 'readonly' | 'current';
+/**
+ * 一份**已批准**的计划，作为时间线上的一条常驻展示项（方案 35 PR-2）。
+ *
+ * 在这之前，一份计划在屏幕上只出现两次：`exit_plan_mode` 那张工具卡，和审批框。
+ * 两者都是一次性的 —— 用户点完「批准并执行」，那份纲就滚走了，而它接下来十分钟
+ * 都是这一轮的依据。
+ *
+ * ## 为什么它**不在** `@epoch-agent/view` 里
+ *
+ * view 是 tui 和 web 共用的展示项定义，加一种就等于要求两个宿主都画它
+ * （`web` 那个 switch 刻意没有 default，加一支两边一起红）。而 web 的持久形态
+ * **不是时间线上的一条** —— 设计稿（`design/web-ui/README.md` 第七节）把它定成
+ * 检视面板的第四个 tab，并且明确否掉了「在时间线里保留一份长正文」那个方案
+ * （理由：一轮结束后还要翻上去找，等于没有持久化）。
+ *
+ * 也就是说这两个宿主对同一件事的**形状本来就不同**，硬塞进共用联合类型只会逼
+ * web 画一个设计上已经否掉的东西。等 web 的检视面板落地，那边走的是面板状态，
+ * 不是这条展示项 —— 到那时这里也不需要搬家。
+ */
+type HistoryItemPlan = {
+    type: 'plan';
+    /** 计划正文，markdown */
+    markdown: string;
+    /**
+     * 用户是按哪个出口批的。两者对「接下来会发生什么」的含义完全不同，
+     * 而卡片上必须看得出来 —— 不然用户记不住自己刚才是不是放了写权限出去。
+     *
+     * `current` 是 `/plan show` 的**回看**形态：那时只知道计划正文，不知道当年
+     * 按的是哪个出口（落盘的只有正文），所以它两句都不说。
+     */
+    mode: PlanCardMode;
+    /** 「批准并执行」时恢复到的权限级别；另两档没有 */
+    level?: string;
+};
+/**
+ * TUI 的展示项联合 = view 那一套 + 终端独有的几种。
+ *
+ * 存在的理由见 {@link HistoryItemPlan}。**只在 TUI 内部用** —— 往 view / web
+ * 那边传的仍然是 `HistoryItemWithoutId`，这个别名不会漏出包外。
+ */
+type TuiHistoryItemWithoutId = HistoryItemWithoutId | HistoryItemPlan;
+/** 带 id 的完整展示项，对应 view 的 `HistoryItem` */
+type TuiHistoryItem = TuiHistoryItemWithoutId & {
+    id: number;
+};
+
+/**
+ * 斜杠命令的契约。
+ *
+ * 命令拿到的是一组回调（`SlashCommandContext`），自己不碰 React 状态，
+ * 也不 import 任何 core 的东西 —— tui 只依赖 protocol，凡是需要引擎能力的
+ * （切权限级别、列工具、读启动诊断）都由宿主在 `renderApp({ host })` 时注入。
+ *
+ * 这样命令实现是纯函数式的，可以直接对着一个假的 context 单测，
+ * 不用把整个 Ink 树跑起来。
+ */
+
+/**
+ * `/goal` 一次子命令的结果（方案 52 PR-1）。
+ *
+ * `message` 是**宿主已经渲染好的一句话**，TUI 原样印出来 —— 判据见
+ * {@link HostActions.goals} 上那段 ⚠️。`ok` 只决定印成 info 还是 warning：
+ * 拒绝的理由本身在 `message` 里，因为「下一步该敲什么」逐条不同
+ * （`busy` 要先 `/goal clear`，`no-goal` 要先建一个）。
+ */
+interface GoalActionResult {
+    ok: boolean;
+    message: string;
+}
+/** 宿主（tui-entry）注入的引擎能力。全部可选：缺哪个对应命令就报「不可用」而不是崩 */
+interface HostActions {
+    /**
+     * 切换权限级别。
+     *
+     * 回 `{ok:false}` 时 `reason` 必须说明**为什么** —— 最常见的那一种是企业托管
+     * 禁掉了 bypass（`disableBypassPermissionsMode`），而光说一句「切换失败」
+     * 会让用户以为撞上了 bug，然后去反复重试一件永远不会成功的事。
+     */
+    setPermissionLevel?: (level: PermissionLevel) => {
+        ok: boolean;
+        reason?: string;
+    };
+    /** 读当前权限级别（切换后状态栏要跟着变） */
+    getPermissionLevel?: () => PermissionLevel;
+    /** 已注册（且对模型可见）的工具清单 */
+    listTools?: () => Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** buildRuntime() 的启动诊断，每个模块一行 */
+    getDiagnostics?: () => string[];
+    /**
+     * provider 类型 / API key 提示，用于 /model。
+     *
+     * 回 `null` = provider 没起来。**每次调都要重新问宿主**，别缓存：
+     * 方案 26 之后 `/model` 能换 provider，缓存下来就会显示启动时那家。
+     */
+    getProviderInfo?: () => {
+        provider: string;
+        apiKeyHint: string;
+    } | null;
+    /**
+     * 换模型（方案 26）。`'reset'` = 回到配置里那个。
+     *
+     * 返回的是 core 的判定结果原样透传，**不在这里翻译成 boolean**：
+     * 三种拒绝（没凭据 / 不认图片 / 窗口装不下）各有各的下一步动作，
+     * 收成一个 false 之后 UI 只能编一句笼统的话。
+     * 判据全在 core，这里只负责把结果显示出来 —— 少一处会和引擎漂移的地方。
+     *
+     * `ctx` 是**两边各知道一半**的会话事实，所以两边都填、在宿主那侧合并：
+     *   - `usedTokens` —— TUI 有（`SessionStats.lastInputTokens`），引擎侧没有
+     *     一个「上一次请求送进去多少」的现成读点
+     *   - `hasImages` —— 宿主有（会话历史里的 image part），TUI 只看得见
+     *     还没发出去的那几张
+     */
+    setModel?: (ref: ModelRef | 'reset', ctx?: SelectionContext) => SetSelectionResult;
+    /**
+     * 当前模型选择 + 它的上下文窗口。
+     *
+     * 和 `getPermissionLevel` 同一个理由：切换之后 `/model` 再看要是**当前值**，
+     * 而不是 TUI 启动时那一份快照。
+     */
+    getModelSelection?: () => {
+        selection: ModelSelection;
+        contextLength: number;
+    };
+    /**
+     * 取走引擎在这一轮里攒下的模型提示，取完即清（方案 26 验收 #8）。
+     *
+     * 目前只有一句：某个模型连续失败到了阈值，本会话不再自动降级重试它。
+     * 这件事必须**说出来**，否则用户看到的只是「回答忽然换了个味道」，
+     * 而账单和能力都已经不是他选的那个模型了。
+     *
+     * 拉而不是推：产出它的 `ProviderRouter` 在 `loop.ts` 底下，发不出 `AgentEvent`。
+     */
+    drainModelNotices?: () => string[];
+    /**
+     * 用系统查看器打开一个 artifact。打不开就 reject，消息直接 toast 给用户。
+     *
+     * 由宿主实现而不是 TUI 自己 spawn：能不能打开是一条**安全判定**
+     * （路径必须在 artifact 目录里、扩展名必须在白名单里），那份判定住在
+     * `core/src/context/artifact-open.ts`，而 tui 不许 import core。
+     */
+    openArtifact?: (path: string) => Promise<void>;
+    /**
+     * 读系统剪贴板里的图片，没有图片返回 null。
+     *
+     * 同样是宿主能力：要 spawn `osascript` / `xclip` / PowerShell，
+     * 换成 Electron 宿主时是 `clipboard.readImage()`，接口一样、实现不同。
+     */
+    readClipboardImage?: () => Promise<ClipboardImagePart | null>;
+    /**
+     * 当前模型认不认图片。
+     *
+     * 用来在**粘贴那一刻**就拦住，而不是等一个来回之后由引擎报错 ——
+     * 引擎侧那道闸门（loop.ts）仍然是权威判定，这里只是省掉一次白等。
+     */
+    supportsImages?: () => boolean;
+    /**
+     * 把一条自定义斜杠命令展开成一次 turn 的输入（方案 23）。
+     *
+     * 插值（`$ARGUMENTS` / `$1`）要用方案 21 的 tokenizer，而那住在 infra ——
+     * tui 只依赖 protocol，够不着。所以展开在宿主侧做，TUI 拿到的是结果。
+     *
+     * 认不出这个命令名时回 `undefined`（正常情况下不会：命令表本来就是宿主给的，
+     * 除非表在这中间被换掉了）。
+     */
+    expandCommand?: (name: string, args: string) => ExpandedCommand | undefined;
+    /**
+     * 工作区文件清单，`@` 补全的候选（方案 25）。
+     *
+     * 由宿主提供：它要跑 `git ls-files` / 走目录，而 tui 只依赖 protocol。
+     * 异步是因为第一次可能要几十毫秒 —— 不该阻塞首帧。
+     */
+    listWorkspaceFiles?: () => Promise<readonly string[]>;
+    /**
+     * 把 `@路径` 解析成带内容的附件部件（方案 25 §2.2 的选项 B）。
+     *
+     * **必须由宿主做**，不只是因为 tui 读不了文件：这条路要过工作区边界判定和
+     * 权限判定，而两者都在引擎那一侧。TUI 自己 `readFileSync` 等于给 `@`
+     * 开了一条绕过 `file_read` 的读取通道。
+     */
+    resolveMentions?: (paths: readonly string[]) => {
+        parts: EpochFilePart[];
+        /** 要念给用户听的话（截断了 / 被拦了 / 超上限了） */
+        notices: string[];
+    };
+    /**
+     * 当前的后台任务表（方案 36 PR-2）。
+     *
+     * 同步返回：它只是读一张内存里的表，而状态栏每两秒要问一次 —— 异步的话
+     * 每次都要过一遍微任务队列，还得处理「上一次还没回来」的竞态。
+     */
+    listBackgroundTasks?: () => readonly BackgroundTaskInfo[];
+    /**
+     * 用户自配的状态栏那一段（方案 29 §2.6）。没配时**宿主不注入这一项**，
+     * 状态栏据此决定画不画 —— 而不是画一段空的、留个洞。
+     *
+     * 同步返回、且**不保证是最新的**：宿主给的是上一次跑完的值，顺便判断要不要
+     * 在后台再跑一次。这是刻意的，两个理由都写在
+     * [cli/src/statusline.ts](../../../cli/src/statusline.ts) 的文件头：
+     * 状态栏是装饰，不能因为一条命令卡住就让整个 UI 等；也不该由 TUI 来管
+     * 「谁去关那个定时器」。
+     */
+    readStatusLine?: () => string | null;
+    /**
+     * 跑一条**用户手打**的命令（`!ls -la`，方案 25 §2.3）。
+     *
+     * `approve` 由 TUI 提供：宿主判定要确认时回调它，TUI 弹出和模型那条路
+     * **完全相同**的确认框。判定本身在引擎侧 —— `!` 不是免检通道。
+     */
+    runShellCommand?: (command: string, approve: (request: ApprovalRequest) => Promise<ApprovalOutcome>) => Promise<{
+        output: string;
+        ok: boolean;
+        blocked?: boolean;
+    }>;
+    /** 写一条记忆（`#记一下`，方案 25 §2.4）。`target` 决定用户级还是项目级 */
+    writeMemory?: (content: string, target: 'user' | 'memory', approve: (request: ApprovalRequest) => Promise<ApprovalOutcome>) => Promise<{
+        output: string;
+        ok: boolean;
+        blocked?: boolean;
+    }>;
+    /**
+     * 把 `!` 跑出来的输出记进**模型的**上下文（方案 25 §2.3）。
+     *
+     * TUI 自己的历史不是模型的上下文 —— 不接这一条的话，用户看得见输出而模型
+     * 看不见，而「你看一下这个命令的输出」正是 `!` 存在的意义。
+     */
+    noteToSession?: (text: string) => void;
+    /**
+     * 当前上下文预算的构成（方案 25 §2.5）。
+     *
+     * **每次调都要重新问**：历史每轮都在长。缓存下来 `/context` 会一直显示
+     * 第一次看的那个数。
+     */
+    getContextBreakdown?: () => ContextBreakdown | null;
+    /**
+     * 已加载的技能（方案 23 §2.5）。
+     *
+     * `scope` 要露出来：用户看见一条不认识的技能，第一个问题是「这哪来的」——
+     * 同 `/help` 把内置命令和自定义命令分两段列的理由。
+     */
+    listSkills?: () => ReadonlyArray<{
+        name: string;
+        description: string;
+        category: string;
+        /**
+         * `plugin` 是方案 32 加的第三种来源，它带的技能名一律是 `<插件名>:<名字>`；
+         * `host` 是方案 44 加的第四种（嵌入宿主 ship 的目录），同样一律带前缀。
+         *
+         * ⚠️ 这个联合是**抄**的（tui 不许 import core），所以它靠 `cli/src/tui-host.ts`
+         * 那一行装配去撞真源 —— 真源加一格而这里不加，那一行当场编译不过。
+         * 方案 44 就是这么被逮到的。
+         */
+        scope: 'user' | 'project' | 'plugin' | 'host';
+    }>;
+    /**
+     * 可派给子 agent 的角色表（方案 18）。
+     *
+     * `tools` 是**声明值**，实际生效的还要和当时的工具表取交集 ——
+     * 显示时要说明这一点，否则用户会以为角色能用一个已经被卸载的工具。
+     */
+    listAgentRoles?: () => ReadonlyArray<{
+        name: string;
+        description: string;
+        source?: string;
+        tools?: readonly string[];
+    }>;
+    /**
+     * MCP server 的连接状态。
+     *
+     * **getter 语义，每次调都要重新问**：MCP 会热重连，缓存下来 `/mcp` 会一直
+     * 显示启动那一刻的状态 —— 而这条命令存在的唯一理由就是「现在到底连上没有」。
+     */
+    listMcpServers?: () => ReadonlyArray<{
+        name: string;
+        status: string;
+        toolCount: number;
+        error?: string;
+    }>;
+    /**
+     * 已装插件一览（方案 32）。
+     *
+     * **停用的和加载失败的都要在里面** —— 这条命令一半的价值就在那儿：
+     * 一个因为 `epochVersion` 不满足而没加载的插件，在别处的唯一痕迹是启动时
+     * 一行 warn，而用户查「我装的东西怎么没生效」时看的就是这一屏。
+     */
+    listPlugins?: () => {
+        /** `~/.epoch/plugins.json`，显示出来是为了回答「我该去改哪个文件」 */
+        statePath: string;
+        plugins: readonly PluginInfo[];
+    };
+    /**
+     * 停用 / 启用一个插件（`/plugin disable <名字>`）。
+     *
+     * **装和卸不在这里**：那两件事要联网、要解包、要在预览之后问一句，
+     * 而那一问是插件这条路上真正的闸门。理由写在 `commands/plugins.ts` 的文件头。
+     *
+     * 异步是因为写状态文件要先抢一把跨进程的锁 —— 同一台机器上可能还开着另一个
+     * `epoch plugin install`。
+     */
+    setPluginEnabled?: (name: string, enabled: boolean) => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** 已记住的记忆条目。`target` 区分用户级和项目级 */
+    listMemories?: () => ReadonlyArray<{
+        content: string;
+        target: string;
+    }>;
+    /**
+     * 删一条记忆。
+     *
+     * 写入不在这里 —— `/memory add` 复用已有的 `writeMemory`（带审批回调）。
+     * 不为一条 UI 命令新开一条绕过权限的写路径。
+     */
+    removeMemory?: (content: string) => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /**
+     * 往系统剪贴板写一段文本。
+     *
+     * 和 `readClipboardImage` 同一个理由归宿主：要 spawn `pbcopy` / `clip.exe` /
+     * `xclip`，换成 Electron 宿主时是 `clipboard.writeText()`。
+     */
+    copyToClipboard?: (text: string) => Promise<void>;
+    /** 工作区当前的 `git diff`。不是 git 仓库、或者 git 不在 PATH 时回 `ok: false` */
+    gitDiff?: () => Promise<{
+        text: string;
+        ok: boolean;
+        message?: string;
+    }>;
+    /**
+     * 工作区**有没有**未提交的改动（方案 27 §2.5 那句 `git stash` 提示）。
+     *
+     * 和 `gitDiff` 分开而不是拿它的 `text` 判空：回退面板要的只是一个布尔和一个
+     * 计数，而 `git diff HEAD` 在大仓库上会把几 MB 的补丁读进内存 —— 为了一行提示
+     * 付这个代价不划算。口径也不同：这里走 `git status --porcelain`，**未跟踪的
+     * 新文件也算**，而 `git diff HEAD` 看不见它们。
+     *
+     * 不是 git 仓库、git 不在 PATH 时回 `ok: false` —— 那时**什么都不提示**，
+     * 而不是提示「工作区是干净的」：我们只是不知道。
+     */
+    gitDirty?: () => Promise<{
+        ok: boolean;
+        dirty: boolean;
+        count: number;
+    }>;
+    /**
+     * 检查点与回退（方案 27）。`/rewind` 和 Esc Esc 共用这一份能力。
+     *
+     * 缺它时那条命令不注册、那个键位不武装 —— 判据见 {@link CheckpointActions}。
+     */
+    checkpoints?: CheckpointActions;
+    /**
+     * 把当前会话导出成 Markdown，返回真正写到的路径。
+     *
+     * 由宿主做而不是拿 TUI 自己的历史拼：TUI 的历史是**给人看的投影**
+     * （工具调用被折叠成一行卡片），而导出要的是完整记录 ——
+     * 那份在 `sessionStore.loadMessages()` 里。
+     */
+    exportSession?: (file?: string) => Promise<{
+        path: string;
+        messages: number;
+    }>;
+    /**
+     * 手动压一次上下文（`/compact`，方案 25 §2.6）。
+     *
+     * `instruction` 是「这次帮我留住什么」。**压缩是一次真实的 LLM 请求**，
+     * 所以这条命令会花钱 —— 结果里带上压缩前后的条数，让用户看得见换来了什么。
+     */
+    compactContext?: (instruction?: string) => Promise<{
+        ran: boolean;
+        before: number;
+        after: number;
+        reason?: string;
+    }>;
+    /** 最近的会话列表（`/resume` 的候选） */
+    listSessions?: () => ReadonlyArray<{
+        id: string;
+        title: string;
+        startedAt: number;
+        messageCount: number;
+    }>;
+    /**
+     * 换到另一段会话，**模型真的接上那段上下文**。
+     *
+     * 返回恢复出来的历史，供 TUI 回放进屏幕。只回放不换上下文的话，
+     * 用户会照着屏幕上那段去问「你刚才说的那个方案」，然后收到一句对不上的回答。
+     */
+    resumeSession?: (sessionId: string) => ReadonlyArray<{
+        role: string;
+        content: string;
+    }>;
+    /** 会话全文检索（Ctrl+R，走 SQLite FTS5） */
+    searchSessions?: (query: string) => ReadonlyArray<{
+        sessionId: string;
+        title: string;
+        snippet: string;
+    }>;
+    /**
+     * 当前生效的权限规则 + 遮蔽情况（`/permissions`，方案 22 §2.7）。
+     *
+     * `layer` 是**来源层**，这条命令存在的一半意义就在它身上 —— 用户查权限问题时
+     * 的第一个问题永远是「这条 deny 是谁加的、我该去改哪个文件」。
+     */
+    listPermissions?: () => {
+        level: string;
+        rules: ReadonlyArray<{
+            bucket: string;
+            rule: string;
+            layer: string;
+        }>;
+        shadows: ReadonlyArray<{
+            kind: string;
+            message: string;
+        }>;
+        /** 企业托管策略（方案 22 §2.6）。这台机器上没有托管文件时 `present: false` */
+        managed: ManagedInfo;
+    };
+    /**
+     * Plan 模式（方案 35）—— 用户主动那一半。
+     *
+     * **出口处那次审批不在这里**：它走的是既有的 `approval-request` 链
+     * （`exit_plan_mode` 工具发起），TUI 接的还是 `run.requestApproval` 那一个队列。
+     * 这里只有「进 / 出 / 现在在不在」，外加「已经批过的那份是什么」。
+     */
+    planMode?: {
+        active: () => boolean;
+        /** 进入前的权限级别；不在模式里时为 null */
+        from: () => string | null;
+        enter: () => {
+            ok: boolean;
+            from?: string;
+            reason?: string;
+        };
+        /** 主动退出，返回恢复到的级别；本来就不在模式里时回 null */
+        leave: () => string | null;
+        /**
+         * 当前生效的那份**已批准**计划；没有就是 null（方案 35 PR-2）。
+         *
+         * `/plan` 拿它回答「我刚才批的那份计划是什么」。这条在 `--resume` 之后
+         * 尤其要紧：屏幕上是空的（那张卡片是上一个进程画的），而模型手上那份还在
+         * —— 没有这个出口，用户无从知道自己接回来的会话正照着哪份纲跑。
+         *
+         * 可选：老宿主没实现时 `/plan` 少说一段，不该因此报「不可用」。
+         */
+        approvedPlan?: () => string | null;
+    };
+    /**
+     * 长任务的目标（方案 52）—— `/goal` 命令族的全部数据源。
+     *
+     * ## ⚠️ 为什么这一组回的是**渲染好的字符串**，而别的能力回结构
+     *
+     * `checkpoints` 那一组回的是数据（TUI 自己画面板），这一组不是 —— 每个方法
+     * 回一句已经拼好的话。判据是 **i18n**：
+     *
+     * `tui` 只依赖 protocol（见 `packages/tui/README.md` 的依赖表），够不着
+     * `@epoch-agent/infra` 的 `t()`，所以 TUI 里写的每一句中文都是硬编码的、
+     * 也就永远只有中文。这一片是**新增**的用户可见文案，把它硬编码进来等于给
+     * i18n 那条棘轮（`scripts/i18n-scan.mjs`，只许降不许升）再添一笔债。
+     *
+     * 所以措辞归宿主：cli 那侧用 `t()` 从 `locales/{zh,en}.yaml` 的 `goal.*` 取，
+     * TUI 只负责**解析子命令**和**把结果印出来**。这不是新发明的形状 ——
+     * `listPlugins` / `ManagedInfo` 早就是「宿主算好的展示形状」（见本文件
+     * import 那几行上的注释）。
+     *
+     * 整组可选：宿主没接（会话库起不来）时 `/goal` 压根不注册。
+     */
+    goals?: {
+        /**
+         * 当前目标的多行展示。没有目标时是那句「还没有目标 + 怎么建一个」的提示 ——
+         * **不是空串**：`/goal` 不带参数时用户要的答案在两种情况下都存在。
+         */
+        describe: () => string;
+        /**
+         * 用法那一行。今天只有一个调用点：`/goal budget 三轮` 这种数字没看懂的情况。
+         *
+         * 单独一格而不是复用 `describe()`：那时候用户要的不是「当前目标怎么样」，
+         * 是「我刚才那句该怎么敲」。印错一个的代价是他把状态又读一遍，然后再错一次。
+         */
+        usage: () => string;
+        /** 建一个（人专用）。已经有一个没结束的目标时 `ok: false` */
+        create: (objective: string) => GoalActionResult;
+        /** 改正文。不重置轮次，也不改状态 */
+        edit: (objective: string) => GoalActionResult;
+        /** 改预算（轮数）。调到比已用还小时当场变成「预算用完了」 */
+        budget: (rounds: number) => GoalActionResult;
+        pause: () => GoalActionResult;
+        resume: () => GoalActionResult;
+        /** 人替模型报完成。依据必填 —— 那段话是回头核对的唯一凭据 */
+        done: (evidence: string) => GoalActionResult;
+        clear: () => GoalActionResult;
+        /**
+         * 卡住时那一行开机提示；没卡住（或没有目标）时 null。
+         *
+         * 宿主（`tui-entry`）把它接在 `startupNotices` 后面 —— 这是验收 8：
+         * 一个无人值守跑到一半卡住的任务，人回来打开 TUI 时**第一屏就该看见**
+         * 卡在哪，而不是要先想起来敲一条命令。
+         */
+        blockedNotice: () => string | null;
+    };
+    /**
+     * 把一次「永久允许」渲染成可提交进 git 的规则字符串（方案 22 §2.7）。
+     *
+     * 审批缓存是**本机的**、不进 git、换台机器就没了；规则是能提交的。
+     * 两者今天完全没有桥，用户想让规则生效只能自己去读文档猜语法。
+     * 反推不出有意义的规则时回 `null`（宿主据此不显示提示，而不是显示一条死规则）。
+     */
+    suggestRule?: (request: ApprovalRequest) => {
+        rule: string;
+        hint: string;
+    } | null;
+}
+/** 选择框的共同部分 —— 单选和多选只差 `onPick` 的入参 */
+interface PickerBase {
+    title: string;
+    /**
+     * 副标题。结构化提问（方案 34）拿它放「第 2/4 问 · 缓存后端」——
+     * 四个问题逐个走完时，用户必须看得出「还有几个」，否则第二个弹窗出现的那一刻
+     * 他会以为自己刚才点错了。
+     */
+    subtitle?: string;
+    options: Array<SelectOption<string>>;
+    initialIndex?: number;
+    /**
+     * 在列表末尾自动追加一个「其他…」，选中后就地敲字（方案 34 验收 3）。
+     *
+     * **由宿主提供而不是让调用方自己加一个选项**：那样每个调用方都得记得加，
+     * 忘了的表现是用户答不上来只能按 Esc —— 而 Esc 的语义是「跳过」，
+     * 对模型来说和「用户写了别的」完全不同。
+     */
+    allowFreeInput?: boolean;
+    /** Esc。不给时 App 只收掉弹窗，不通知发起方 */
+    onCancel?: () => void;
+}
+/** 命令要弹选择框时提交的请求（单选，默认形态） */
+interface SinglePickerRequest extends PickerBase {
+    multiSelect?: false;
+    /** 选中的 label；用户走自由输入时是他打的原文 */
+    onPick: (value: string) => void;
+}
+/** 多选（方案 34 验收 2）。答案是数组，一项都没勾时是空数组 —— 那也是个合法答案 */
+interface MultiPickerRequest extends PickerBase {
+    multiSelect: true;
+    onPick: (values: string[]) => void;
+}
+/**
+ * 选择框请求。
+ *
+ * 做成判别联合而不是「`onPick: (v: string | string[]) => void` 一把抓」：
+ * 后者会让每个既有调用方（`/permission`、`/plugin`、`/resume`）都得在回调里
+ * 先 `Array.isArray` 一次，而它们压根不可能收到数组。判别符让「这个框是几选」
+ * 这件事在**声明处**就定死，回调的入参类型跟着自动收窄。
+ */
+type PickerRequest = SinglePickerRequest | MultiPickerRequest;
+/** 提交一条消息时的额外约束（方案 23：自定义命令可以收窄这一轮的工具表） */
+interface SubmitOptions {
+    /**
+     * 这一轮对模型可见的工具白名单。不给 = 不收窄。
+     *
+     * 真正的收窄发生在引擎侧（`runtime.commands.scope()`），这里只是把意图
+     * 一路带过去 —— TUI 自己没有工具表，也不该有。
+     */
+    allowedTools?: readonly string[];
+    /**
+     * 只在这一轮生效的模型（命令 frontmatter 的 `model:`，方案 26 验收 #9）。
+     *
+     * 和 `allowedTools` 同一个形状、同一条理由：解析（含 `utility` 关键字）在
+     * 引擎侧做完了，TUI 只负责把它原样带到 `onRun`，还原也在那一侧无条件发生。
+     */
+    model?: ModelRef;
+}
+/** 命令能改的 UI 开关 */
+interface UiToggles {
+    /** 是否把本轮 reasoning 原文落进历史 */
+    showThoughts: boolean;
+    setShowThoughts: (v: boolean) => void;
+}
+interface SlashCommandContext {
+    /** 命令名之后的原始参数串（已 trim，可能为空） */
+    args: string;
+    /** 往历史里追加消息 */
+    push: (item: TuiHistoryItemWithoutId) => void;
+    /** 清空历史 */
+    clear: () => void;
+    /** 退出 TUI */
+    exit: () => void;
+    /** 弹选择框 */
+    pick: (req: PickerRequest) => void;
+    /**
+     * 打开回退面板（方案 27 PR-3）。
+     *
+     * **没有走 `pick`**：那个是「从一组固定选项里选一个」，而回退是一台状态机 ——
+     * 选检查点 → 逐个勾要覆盖的冲突文件 → 选范围 → 对话那半再确认一次不可撤销。
+     * 用一串嵌套的 `pick` 拼出来，等于把「默认一个冲突都不覆盖」这条安全判定
+     * 摊在四层回调里。
+     *
+     * 和 `clear` / `exit` 同一个形状：面板的开关状态住在 `App`，命令只按门铃。
+     * Esc Esc 按的是同一个门铃 —— **一个面板，两个入口**。
+     */
+    openRewind: () => void;
+    /**
+     * 请求一次审批，弹出的确认框和模型那条路**完全相同**。
+     *
+     * 有这一条，命令才不会成为绕过权限的后门：`/memory add` 往磁盘写东西，
+     * 和 `#` 速记、和模型自己调 `memory` 工具，在危险性上没有区别。
+     * 实现就是 `useAgentRun` 的 `requestApproval` —— 一个来源，一种弹窗。
+     */
+    approve: (request: ApprovalRequest) => Promise<ApprovalOutcome>;
+    /**
+     * 把一段文本当成用户消息发出去（方案 23 的自定义命令走这条）。
+     *
+     * 内置命令一个都不用它 —— 它们是「在 TUI 里做一件事」，而自定义命令是
+     * 「替用户敲一段话」。两者共用同一个注册表但走不同的出口，这是刻意的：
+     * 命令**不是**新的 agent 类型，就是一次预置的 turn。
+     */
+    submitPrompt: (text: string, opts?: SubmitOptions) => void;
+    /** 宿主能力 */
+    host: HostActions;
+    /** 会话与配置的只读快照 */
+    info: {
+        sessionId: string;
+        model: string;
+        cwd: string;
+        contextLimit: number;
+        permissionLevel: string;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        costUsd?: number;
+    };
+    /** UI 开关 */
+    toggles: UiToggles;
+    /** 全部命令，供 /help 自我描述 */
+    commands: readonly SlashCommand[];
+    /**
+     * 当前显示历史（已落定的 + 还挂在 pending 区的）。
+     *
+     * `/copy` 要从里面往回找最后一条模型回答。含 pending 是刻意的：
+     * 刚说完的那句还没落进 `<Static>` 就敲 `/copy`，用户要的显然是它 ——
+     * `Ctrl+O` 找 artifact 时用的也是同一个合并口径。
+     */
+    history: readonly TuiHistoryItemWithoutId[];
+}
+interface SlashCommand {
+    /** 不带斜杠的命令名 */
+    name: string;
+    /** 别名，同样不带斜杠 */
+    aliases?: string[];
+    /** 一行说明，出现在补全面板和 /help 里 */
+    description: string;
+    /** 参数占位符，例如 `[level]`；只用于展示 */
+    argHint?: string;
+    /**
+     * 来源。内置命令不写这个字段；自定义命令写 `'user'` / `'project'`。
+     *
+     * `/help` 靠它把两类分开列 —— 用户看见一条不认识的命令时，第一个问题
+     * 永远是「这是哪来的」。
+     */
+    source?: CustomCommandSource;
+    /**
+     * 这条命令要不要注册。不给 = 永远注册。
+     *
+     * 判据只看**宿主注入了哪些能力**，因为那是唯一「这台机器上到底有没有这个东西」
+     * 的真源。缺能力时报一句「不可用」和压根不出现，是两件不同的事：
+     * 前者适合「本该有、这次没起来」（`/tools` 在 provider 挂掉时仍该在），
+     * 后者适合「这个版本就没有这个功能」（方案 22 PR-4 之前的 `/permissions`）。
+     * 后者要是注册了，它会出现在 `/help` 和补全面板里 —— 那是在承诺一个不存在的功能。
+     */
+    available?: (host: HostActions) => boolean;
+    /**
+     * 执行。可以是异步的 —— `/copy` `/diff` `/export` 都要等 IO。
+     *
+     * 返回 promise 时调用方会接住 rejection 并 push 成一条 error 历史项，
+     * 和同步抛出走同一个出口。**别在实现里自己 catch 完就吞掉**，
+     * 那样错误既不进历史也不进日志。
+     */
+    run: (ctx: SlashCommandContext) => void | Promise<void>;
+}
+
+/**
+ * 共享状态类型 — 对标 Gemini CLI StreamingState + types。
+ * @license Apache-2.0 (adapted)
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * Modifications Copyright 2024-2026 bowen
+ */
+
+/** 流式状态三态 [Gemini CLI StreamingState] */
+declare enum StreamingState {
+    Idle = "idle",
+    Responding = "responding",
+    WaitingForConfirmation = "waiting_for_confirmation"
+}
+/**
+ * 一次等待用户答复的审批。
+ *
+ * 携带完整的 `ApprovalRequest` 而不是 `{ toolName, args: unknown }`：
+ * 弹窗要分字段渲染「谁 / 干什么 / 目标 / 原因」，拿一个 unknown 只能
+ * `JSON.stringify` 出来给人看序列化对象。
+ *
+ * `respond` 收 `ApprovalOutcome` 而不是 boolean：协议有四种答复，砍成两种
+ * 等于把 core 的审批缓存（allow-session / allow-always）废掉。
+ *
+ * 第二个参数 `note` 只有计划审批的 `plan-revise` 会带（用户的修改意见）。
+ * `request.plan` 存在时弹的是计划审批框，那时四个选项讲的是**接下来怎么走**，
+ * 不是授权范围 —— 见 `PlanConfirmation`。
+ */
+interface ConfirmationRequest {
+    request: ApprovalRequest;
+    respond: (outcome: ApprovalOutcome, note?: string) => void;
+}
+
+/**
+ * 跑一轮的入口。
+ *
+ * 入参是 `EpochUserContent`（`string | 部件数组`）而不是 `string`：Ctrl+V 粘进来的
+ * 图片必须跟着这一次提交走到引擎。**不放宽成联合类型**是不行的 —— 历史项、
+ * 队列、debug 日志全都只要文本，它们统一走 `contentToText()` 取投影。
+ */
+type RunFn = (message: EpochUserContent, opts: {
+    signal: AbortSignal;
+} & SubmitOptions) => AsyncGenerator<AgentEvent>;
+
+interface AppProps {
+    welcomeMessage?: string;
+    /** 启动诊断，作为首屏的 info 项显示（配置写错了必须看得见） */
+    startupNotices?: string[];
+    onRun?: RunFn;
+    onExit?: () => void;
+    /** 宿主注入的引擎能力，供斜杠命令使用 */
+    host?: HostActions;
+    /** 宿主加载好的自定义斜杠命令（方案 23）。不给就只有内置那几条 */
+    customCommands?: readonly CustomCommandDef[];
+    /**
+     * 生效的键位表（方案 31）。**必须是已经校验过的那一份** ——
+     * 读盘 / zod / 保留键 / 冲突检测都在宿主那一侧（`core/src/config/keybindings.ts`，
+     * 由 `cli/src/tui-entry.ts` 调），tui 只消费。
+     *
+     * 不给就是默认表，也就是「用户没配过」和「宿主不支持配」走同一条路 ——
+     * 行为与今天逐键一致。
+     */
+    keybindings?: KeybindingTable;
+}
+declare function App({ welcomeMessage, startupNotices, onRun, onExit, host, customCommands, keybindings, }: AppProps): React__default.ReactElement;
+
+/**
+ * 工具调用的一行摘要 —— 纯函数，可单测。
+ *
+ * 旧版历史项只画一个工具名（`✓ read_file`），看不出读的哪个文件、跑的哪条命令，
+ * 也就没法回头核对 agent 到底干了什么。
+ *
+ * 参数名不受我们完全控制（MCP 工具的 schema 是别人定的），所以是**候选名
+ * 依次尝试 + 兜底**，而不是每个工具写一条规则：加一个 MCP server 不该需要改这里。
+ */
+/**
+ * 取出最能代表这次调用的那个参数。
+ *
+ * 候选名都没命中时退回「第一个能折成字符串的参数」——总比什么都不显示好，
+ * 但**不**退回整个 JSON：那就变回了旧版弹窗里那种没人读的序列化对象。
+ */
+declare function primaryArg(input: unknown): string | undefined;
+/** `read_file(src/a.ts)`；取不到主参数时退回单纯的工具名 */
+declare function formatToolCall(toolName: string, input: unknown): string;
+
+/** 人类可读的字节数。core 里那份是给模型看的，这份是给终端看的，各在各的包里 */
+declare function formatArtifactBytes(bytes: number): string;
+/**
+ * `🖼 1920×1080 PNG 340.0 KB · shot-a1b2.png`
+ *
+ * 被闸门拦下（没有 `data`）时补一句「未进入上下文」：这是用户最需要知道的一件事 ——
+ * 模型**没看见**这张图，它后面的回答不是基于图片内容的。
+ */
+declare function formatArtifact(artifact: ToolArtifact): string;
+/** 值得被「打开」的产物：落了盘的图片。真正能不能打开由 core 说了算 */
+declare function isOpenableArtifact(artifact: ToolArtifact): boolean;
+/**
+ * 从历史里找**最近**一个能打开的产物。
+ *
+ * 从后往前扫历史而不是单独存一份状态：历史本来就是唯一的真源，
+ * 另开一个 `artifacts` 数组就得同步清屏、中断、重挂三条路径。
+ */
+declare function lastOpenableArtifact(items: readonly TuiHistoryItemWithoutId[]): ToolArtifact | undefined;
+
+interface AppState {
+    version: string;
+    cwd: string;
+}
+declare const AppContext: React.Context<AppState | null>;
+declare const useAppContext: () => AppState;
+
+interface ConfigState {
+    model: string;
+    workDir: string;
+    permissionLevel: string;
+    contextLimit: number;
+    /** 是否使用背景色渲染消息气泡（stub: 始终返回 false） */
+    getUseBackgroundColor: () => boolean;
+}
+declare const ConfigContext: React.Context<ConfigState | undefined>;
+declare const useConfig: () => ConfigState;
+
+/**
+ * SessionContext — 会话统计。
+ *
+ * `usage` 事件里的 `cumulative` 来自 `BudgetGuard`，它有**两种口径**：接上
+ * `BudgetStore` 时跨轮累加（常态），store 起不来时每轮从零开始。宿主必须按对应
+ * 口径记账 —— 拿「每轮最终值相加」去算 session 口径会重复计，拿「最新值当总量」
+ * 去算 run 口径会少计。
+ *
+ * **口径不能从事件流里猜**：第二轮的第一个累计值比第一轮的末值大，既可能是接着
+ * 涨，也可能是重新开始后恰好超过。所以由 runtime 显式告知（`EpochRuntime.usageScope`
+ * → `ConfigState.usageScope` → 这里）。曾经试过用「变小就当重置」的启发式，
+ * 在 run 口径下（1000 → 1200）直接算错。
+ *
+ * `lastInputTokens`（状态栏 ctx% 用的那个）在两种口径下都是相邻两次 `usage` 的
+ * **提示词规模**差值 —— 也就是最后那次请求实际送进去多少 token。直接拿累计值算
+ * ctx% 会随轮数一路涨到 100% 再也不下来。
+ *
+ * ⚠️ 这里说的是 `promptTokens(usage)` 而**不是** `usage.inputTokens`：后者按
+ * 方案 42 PR-0 的口径只装**非缓存**那一份。开了 prompt caching 的 provider 上，
+ * 一段 6k 的上下文可能只有 110 个非缓存 token，拿它算 ctx% 会显示 0% ——
+ * 而缓存命中的那 6k 照样占着窗口。
+ *
+ * @license Apache-2.0 (adapted from google-gemini/gemini-cli SessionStatsProvider)
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * Modifications Copyright 2024-2026 bowen
+ */
+
+/** `usage.cumulative` 的口径，来自 `EpochRuntime.usageScope` */
+type UsageScope = 'session' | 'run';
+/** 预算剩余额度；对应上限没配时字段缺席 */
+interface BudgetRemaining {
+    costUsd?: number;
+    tokens?: number;
+}
+interface SessionStatsState {
+    sessionId: string;
+    /** 会话累计（增量累加得来） */
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    /**
+     * 最近一次 LLM 请求的 input tokens —— 这个才代表当前上下文占用。
+     * 状态栏的 ctx% 必须用它。
+     */
+    lastInputTokens: number;
+    /** 会话累计成本。**从来没拿到过定价数据时为 undefined，不是 0** */
+    totalCostUsd?: number;
+    /** 本轮（自 startRun 起）产出的 output tokens，状态行显示实时进度用 */
+    runOutputTokens: number;
+    /** 本轮最近一次 usage 事件的原始累计值。**是引擎口径的累计，不是本轮用量** */
+    runUsage?: TokenUsage;
+    /** 预算余额，来自 usage 事件；没配预算时为 undefined */
+    budgetRemaining?: BudgetRemaining;
+    promptCount: number;
+}
+interface SessionContextValue {
+    stats: SessionStatsState;
+    /** 新一轮开始：清掉上一轮的实时用量 */
+    startRun: () => void;
+    /** usage / finish 事件：按增量入账 */
+    applyUsage: (cumulative: TokenUsage, budgetRemaining?: BudgetRemaining) => void;
+    /** 本轮收尾。`finish.usage` 通常与最后一个 usage 事件相同，此时增量为 0，不会重复计 */
+    endRun: (usage: TokenUsage) => void;
+}
+/**
+ * 相邻两次累计值之间的增量 = 最近一次 LLM 请求的真实用量。
+ *
+ * 一律 clamp 到 ≥0：口径是由 `usageScope` 决定的，真出现倒退（引擎重置了计数器）
+ * 时把它当 0 处理，宁可少算一次也不要把总量算成负数。
+ */
+declare function deltaOf(prev: TokenUsage, next: TokenUsage): TokenUsage;
+declare const SessionStatsProvider: React__default.FC<{
+    children: React__default.ReactNode;
+    sessionId: string;
+    /** `usage.cumulative` 的口径；不给时按常态（接了 store）算 */
+    usageScope?: UsageScope;
+}>;
+declare const useSessionStats: () => SessionContextValue;
+
+/**
+ * renderApp — 挂载 TUI。
+ *
+ * provider 树和 render options 收在这里，因为它们是 UI 自己的事：
+ * `exitOnCtrlC: false` 是「Ctrl+C 按两次才退出」的前提（ink 默认会自己吞掉
+ * \x03 直接结束进程，App 里的 useInput 根本收不到），只能在 render() 处传。
+ */
+
+interface RenderAppOptions extends AppProps {
+    sessionId: string;
+    app: AppState;
+    config: ConfigState;
+    /**
+     * `usage` 事件里 `cumulative` 的口径，来自 `EpochRuntime.usageScope`。
+     * 不给按 `'session'`（接了 BudgetStore 的常态）算 —— 见 session-context 的文件头。
+     */
+    usageScope?: UsageScope;
+}
+declare function renderApp({ sessionId, app, config, usageScope, ...appProps }: RenderAppOptions): Instance;
+
+interface BannerProps {
+    /** 终端宽度；分隔线要扣掉容器的左右 padding，否则宽度 = columns + 2 会折行多出一行 */
+    width?: number;
+}
+declare function Banner({ width }: BannerProps): React__default.ReactElement;
+
+/**
+ * 注册表。顺序即 /help 和补全面板的展示顺序。
+ *
+ * 按用途分了段：会话 → 引擎内省 → 仓库 → 回退 → 开关。后面几个分组住在各自的
+ * 文件里（方案 25 PR-4 起），因为这个文件加完九条命令就会破 500 行的硬线。
+ *
+ * ⚠️ 这份表是**全集**，不是「这台机器上能用的」。按宿主能力过滤发生在
+ * `useSlashCommands` 合并那一步 —— 见 `availableCommands()`。
+ * 保留名检查（方案 23）要的正是全集：一条命令这次没注册，
+ * 不代表自定义命令就可以占用它的名字，否则升个版就撞名了。
+ */
+declare const BUILTIN_COMMANDS: readonly SlashCommand[];
+
+/**
+ * 斜杠命令的解析与匹配 —— 纯函数，不碰 React，可直接单测。
+ *
+ * 判定「这行输入是不是命令」必须严格：`/` 开头**且**第一行不含空格之前的部分
+ * 能匹配上某个已注册命令。否则用户想问「/etc/hosts 是什么」会被当成未知命令。
+ * 这也是 Claude Code 的行为 —— 认不出来的斜杠输入按普通消息发出去。
+ */
+
+interface ParsedSlashInput {
+    /** 命令名（小写，不带斜杠） */
+    name: string;
+    /** 命令名之后的原始参数串（已 trim） */
+    args: string;
+}
+/**
+ * 把一行输入拆成命令名 + 参数。不是斜杠开头时返回 null。
+ *
+ * 只看**第一行**：多行输入里第一行是 `/clear` 而后面还有正文，说明用户是想
+ * 发一段以斜杠开头的文本，不是执行命令。
+ */
+declare function parseSlashInput(text: string): ParsedSlashInput | null;
+/** 按名字或别名精确找命令 */
+declare function findCommand(commands: readonly SlashCommand[], name: string): SlashCommand | undefined;
+/**
+ * 补全用的前缀匹配。
+ *
+ * `/` 单独一个字符时列出全部命令（用户刚敲下斜杠，正等着看有什么可用）。
+ * 已经带了参数（有空格）时不再补全 —— 那时候用户在填参数，不该再弹列表。
+ */
+declare function matchCommands(commands: readonly SlashCommand[], text: string): readonly SlashCommand[];
+
+/**
+ * 默认绑定表 —— **就是这一轮之前硬编码在 app.tsx / input-box.tsx 里的那些键**。
+ *
+ * 这一点是本 PR 唯一能证明「抽了一层但没改行为」的东西（方案 §4.1 #1：无配置文件
+ * 时逐键一致）。所以改这张表 = 改产品行为，不是改实现细节 —— 动之前先问一句这是
+ * 不是本来就想改的那件事。守卫用例在
+ * [keybindings.test.ts](../../__tests__/keybindings.test.ts)：它逐条对着改造前的
+ * 判断列了一遍；而 `app.test.tsx` / `dialogs.test.tsx` 那些从 stdin 打真键的用例
+ * 是另一道 —— 那些用例一个字都没改就绿了，才是「行为没动」的真凭据。
+ *
+ * ## 这张表是**真源**，加载期靠参数拿到它
+ *
+ * `core/src/config/keybindings.ts` 要拿它当底表（用户配置逐动作覆盖上去），但
+ * core 不许依赖 tui。所以不是 core 去 import，而是 **cli 把它当参数递进去**
+ * （`cli/src/tui-entry.ts`）—— 避免了「同一张表在两个包里各存一份然后漂移」，
+ * 那正是 `RESERVED_COMMAND_NAMES` 今天要靠两条双向用例兜着的形态。
+ */
+
+/**
+ * 默认表。每个动作后面的注释是它在改造前的出处。
+ *
+ * 几处刻意的对齐，别当成笔误：
+ *
+ * - **`line-start` / `line-end` 各有两个键**：改造前就是
+ *   `key.home || (key.ctrl && input === 'a')`，一个动作两个键是本方案的原生形态
+ *   （§2.2「一个动作可以绑多个键」），不是妥协
+ * - **`newline` 有三个键**：`shift+enter` / `alt+enter` 是改造前
+ *   `key.return && (key.meta || key.shift)` 那一支拆出来的两半，`ctrl+j` 是
+ *   `input === '\n'` 那一支（见 parser.ts 文件头第 1 条）
+ * - **`rewind` 是空的**。第二下 Esc 开回退面板，靠的是 `app.tsx` 里 500ms 的双击
+ *   窗口（`useRewind`），而**序列语法归 PR-2**。留着这个动作而不是删掉它，是为了
+ *   用户今天就能把回退面板绑到一个单键上（`{"rewind": ["ctrl+shift+r"]}` 就能用，
+ *   app.tsx 接了这条）；PR-2 再给它 `["escape escape"]` 的默认值
+ * - **`ctrl+c` / `ctrl+d` 在表里**，而且同时是保留键（`RESERVED_CHORDS`）。两件事
+ *   不矛盾：默认表得写出来它们干什么，保留只是不许**改**它们
+ */
+declare const DEFAULT_KEYBINDINGS: KeybindingTable;
+
+/**
+ * ink 的 `(input, key)` → 一个 {@link KeyChord}。
+ *
+ * 这是 chord 语法**属于 tui 的那一半**：另一半（`"ctrl+l"` 字符串 ↔ chord）在
+ * protocol，因为 core 那侧读配置文件时要用同一份规则。这里之所以不能也放过去 ——
+ * `Key` 是 ink 的类型，而 protocol 是零依赖包。
+ *
+ * ## 归一化的三处硬账
+ *
+ * 1. **`\n` 就是 Ctrl+J**。ink 7 只在收到 `\r` 时置 `key.return`；`\n`（Ctrl+J
+ *    在 ASCII 里就是 0x0A）走 `name='enter'` 但**不置** `key.return`，也不置
+ *    `key.ctrl`，于是它到这里只是一个普通的 `input === '\n'`。改造前
+ *    input-box.tsx 里那句 `if (input === '\n') buf.newline()` 就是在接它。这里把
+ *    它归成 `ctrl+j`，用户于是可以在配置里写 `"newline": ["ctrl+j"]` —— 名副其实。
+ * 2. **macOS 的 Option+Enter 是 `\x1b\r`**，ink 归成 `return` + `meta`。所以
+ *    `alt+enter` 和 `shift+enter` 都落在 `enter` 上，只是修饰位不同。
+ * 3. **字母一律小写**，大小写由 `key.shift` 表达。终端里 Ctrl 组合给的本来就是
+ *    小写字母，而直接敲 `K` 给的是大写 + shift —— 不统一的话 `ctrl+k` 和
+ *    `shift+k` 会撞进同一个 id。
+ */
+
+/**
+ * 这一下按键是哪个 chord。判不出主键时返回 undefined —— 调用方据此放行
+ * （比如输入框继续走「把这个字符插进去」那条路）。
+ *
+ * 判不出的两类都是真实存在的：**纯修饰键**（只按住 Ctrl 不按别的，ink 那边
+ * `input` 是空串）和**多字符输入**（粘贴一整段文本，ink 一次给完）。两者都不该
+ * 被当成某个键的绑定 —— 后者尤其要小心：一段以 `l` 开头的粘贴内容不能触发清屏。
+ */
+declare function chordOf(input: string, key: Key): KeyChord | undefined;
+
+/** 这一下按键在给定上下文里是哪个动作；没绑（或判不出主键）返回 undefined */
+type ActionResolver = (input: string, key: Parameters<typeof chordOf>[1], context: KeyContext) => KeyAction | undefined;
+/**
+ * @param override 显式的表。**只有 `App` 传它** —— 它是表的持有者（从 prop 收），
+ *                 而一个组件读不到自己 `Provider` 里的值。其余组件一律不传，
+ *                 从 context 拿，于是「表只有一份」这件事在树上是显然的。
+ */
+declare function useKeybinding(override?: KeybindingTable): ActionResolver;
+
+/**
+ * StreamingContext — 流式状态（直接抄 Gemini CLI StreamingContext）。
+ * @license Apache-2.0 (adapted from google-gemini/gemini-cli)
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * Modifications Copyright 2024-2026 bowen
+ */
+
+declare const StreamingContext: React__default.Context<StreamingState | undefined>;
+declare const useStreamingContext: () => StreamingState;
+
+/**
+ * UIStateContext — 核心 UI 状态。
+ *
+ * 只放**跨组件**的状态。原来这里还挂着 `isInputActive` / `showErrorDetails` /
+ * `renderMarkdown` / `elapsedTime` / 三个 `is*DialogOpen`，八个字段没有任何
+ * 读者也没有对应组件 —— 它们不是「预留扩展点」，是照抄 Gemini CLI 的
+ * UIStateContext 时连字段一起抄过来的空壳，读代码的人会以为对话框已经实现了。
+ *
+ * @license Apache-2.0 (adapted from google-gemini/gemini-cli UIStateContext)
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ * Modifications Copyright 2024-2026 bowen
+ */
+
+interface UIState {
+    /** 已完成的历史消息 */
+    history: TuiHistoryItem[];
+    /** 流式渲染中的待定消息 */
+    pendingHistoryItems: TuiHistoryItemWithoutId[];
+    /** 当前流式状态 */
+    streamingState: StreamingState;
+    /** 本轮累加的 reasoning 原文。默认不显示，`/thinking` 打开后收尾时落进历史 */
+    thought: string;
+    /** 队首的工具审批请求 */
+    confirmationRequest: ConfirmationRequest | null;
+    /** 斜杠命令弹出的选择框 */
+    picker: PickerRequest | null;
+    /** 分辨率 */
+    terminalWidth: number;
+    terminalHeight: number;
+    /**
+     * 当前权限级别。
+     *
+     * 不能只读 ConfigContext：`/permission` 能在运行期改它，而 ConfigContext
+     * 是 tui-entry 传进来的一个不变对象，改了状态栏不会跟着变。
+     */
+    permissionLevel: PermissionLevel;
+    /**
+     * 当前模型和它的上下文窗口（方案 26）。
+     *
+     * 和 `permissionLevel` 同一个理由、同一个坑：`/model` 能在运行期换它。
+     * 两者要**一起**变 —— 换模型窗口也变了，状态栏的 ctx% 是拿窗口当分母算的，
+     * 只改模型名的话进度条会按旧模型的窗口继续画，越换越不准。
+     */
+    model: string;
+    contextLimit: number;
+}
+interface UIStateContextValue {
+    state: UIState;
+    setHistory: React__default.Dispatch<React__default.SetStateAction<TuiHistoryItem[]>>;
+    setPendingItems: React__default.Dispatch<React__default.SetStateAction<TuiHistoryItemWithoutId[]>>;
+    setStreamingState: (s: StreamingState) => void;
+    setThought: (t: string) => void;
+    setConfirmation: (r: ConfirmationRequest | null) => void;
+    setPicker: (p: PickerRequest | null) => void;
+    setTerminalSize: (w: number, h: number) => void;
+    setPermissionLevel: (level: PermissionLevel) => void;
+    /** 模型和窗口一起换，不给单独改模型名的入口——见 UIState.model 的注释 */
+    setModel: (model: string, contextLimit: number) => void;
+}
+declare const UIStateProvider: React__default.FC<{
+    children: React__default.ReactNode;
+    /** 初始权限级别，来自配置 */
+    initialPermissionLevel?: PermissionLevel;
+    /** 初始模型与窗口，来自配置 */
+    initialModel?: string;
+    initialContextLimit?: number;
+}>;
+declare const useUIState: () => UIStateContextValue;
+
+interface TextBufferState {
+    /** 逻辑行（不含换行符） */
+    lines: string[];
+    /** 光标所在行 */
+    row: number;
+    /** 光标在行内的 code-point 偏移 */
+    col: number;
+}
+
+interface TextBufferAPI {
+    /** 当前完整文本 */
+    text: string;
+    lines: string[];
+    row: number;
+    col: number;
+    isMultiline: boolean;
+    isEmpty: boolean;
+    /** 光标是否在第一行 / 最后一行（决定 ↑↓ 是行间移动还是翻历史） */
+    atFirstRow: boolean;
+    atLastRow: boolean;
+    insert: (chunk: string) => void;
+    newline: () => void;
+    backspace: () => void;
+    deleteChar: () => void;
+    moveLeft: () => void;
+    moveRight: () => void;
+    moveUp: () => void;
+    moveDown: () => void;
+    moveLineStart: () => void;
+    moveLineEnd: () => void;
+    deleteWordLeft: () => void;
+    killToLineStart: () => void;
+    killToLineEnd: () => void;
+    /** 取出文本并清空（同步返回真实文本） */
+    take: () => string;
+    setText: (text: string) => void;
+    clear: () => void;
+}
+declare function useTextBuffer(): TextBufferAPI;
+
+interface ClampResult {
+    /** 裁剪后的文本 */
+    text: string;
+    /** 被隐藏的视觉行数（0 表示没裁剪） */
+    hiddenLines: number;
+}
+/**
+ * 把文本裁剪到最多 `maxLines` 个视觉行，保留**尾部**。
+ *
+ * 流式渲染期间必须限制动态帧的高度：Ink 的 log-update 只能擦除它上一帧写过的
+ * 行数，一旦帧比终端还高、内容滚出屏幕，擦除范围就对不上，屏幕上会残留重复行。
+ * 保留尾部是因为流式过程中用户关心的是最新产出的内容。
+ * 对应 Gemini CLI `MaxSizedBox` 的 `overflowDirection='top'`。
+ */
+declare function clampTailLines(text: string, width: number, maxLines: number): ClampResult;
+
+export { type ActionResolver, App, AppContext, type AppProps, type AppState, BUILTIN_COMMANDS, Banner, type BudgetRemaining, type CheckpointActions, type CheckpointEntry, type ClampResult, type ClipboardImagePart, ConfigContext, type ConfigState, type ConfirmationRequest, DEFAULT_KEYBINDINGS, type GoalActionResult, type HistoryItemPlan, type HostActions, type ManagedInfo, type PickerRequest, type PluginInfo, type RenderAppOptions, type RewindFileAction, type RewindFileDrift, type RewindFileEntry, type RewindPlan, type RewindReport, type RewindScope, type RewindSummary, SessionStatsProvider, type SessionStatsState, type SlashCommand, type SlashCommandContext, StreamingContext, StreamingState, type TextBufferAPI, type TextBufferState, type TuiHistoryItem, type TuiHistoryItemWithoutId, type UIState, UIStateProvider, type UsageScope, clampTailLines, deltaOf, findCommand, formatArtifact, formatArtifactBytes, formatToolCall, isOpenableArtifact, lastOpenableArtifact, matchCommands, parseSlashInput, primaryArg, renderApp, useAppContext, useConfig, useKeybinding, useSessionStats, useStreamingContext, useTextBuffer, useUIState };