berry-agent-sdk 0.1.0-alpha.2

package/dist/src/channels/tui/overlay/alt-screen.js

@@ -0,0 +1,106 @@
+/**
+ * 副屏编舞件（07 §4.1 引擎节件 6（组件与呈现装配件） + §4.3 屏幕模型双形态）：AltScreenHost——
+ * 备屏 1049 整屏切换的进出编排。
+ *
+ * 「overlay」专指主屏浮层（OverlayStack）；本件是副屏路——件 8 /history
+ * 回看器与 06 /memory 的呈现形态（整屏内容值得 1049 备屏切换）。
+ *
+ * 编舞序（进出对称）：
+ * - 进：主屏 suspendMain（出屏串 + 卸监听 + pause 流 + raw 复先验）→ 副屏
+ *   Engine（共享同一 io 实例、screen:'alt-screen'）start（1049 备屏进 + raw +
+ *   放流——start 的显式放流正是为共享 io 场景补的结构性接缝）；
+ * - 出：退订转发 → 副屏 dispose（备屏出 + raw 复原 + pause）→ 主屏 resumeMain
+ *   （进屏串 + raw + 放流 + 全帧重画不走 repaint：停屏期瞬时行靠全帧 + 缓冲
+ *   补吐，07 屏模型 / 件 8 条款）→ onReturn 装配钩（树重建等附加动作）。
+ *
+ * 输入路由切换：共享 io 同一时刻只有一个在听（主屏 suspendMain 已卸监听、
+ * 副屏 start 重装）——副屏 input 事件转发 content.handleEvent（回看器键盘滚动）。
+ *
+ * 鼠标降级接线（2026-09-11 鼠标解码批）：open 组合 onMouseLegacy——X10 形首
+ * 达（开了 1006 的会话里到达 ⟺ 终端无 SGR 能力，判据可靠）即写 DECRST
+ * 1006/1002 关鼠标签听把选区还给终端原生（写序与出屏关序同取先 1006 后
+ * 1002）。降级闩 = per-entry：每次 open 新 Engine 新 decoder——重开重新武装、
+ * 再吃一次首达（非 SGR 终端上重开 /history 的首个鼠标事件死一次为已知代价）。
+ *
+ * 构造双注 (primary, io)：Engine.io 私有无 getter——装配根同根传两参（io 须与
+ * primary 共享同一实例，否则编舞失联）。
+ *
+ * 批 10f-4 主屏绑收窄：primary 原系 Engine 型——10e 前旧设想残留（主屏
+ * TuiBackend 自持输入管线不经 Engine，07 篇屏模型双形态实装对账注）。收窄为
+ * AltScreenPrimary 最小宿主介面（本件实际消费面：挂起 / 复起 + 生命周期判定
+ * 位）；Engine 语义保留给副屏自身的帧管线（生命周期四态仅副屏 Engine 消费）。
+ */
+import { Engine } from '../../engine/index.js';
+/**
+ * 副屏宿主：单副屏在场（再 open 拒绝返 null——1049 无嵌套备屏）。
+ */
+export class AltScreenHost {
+    primary;
+    io;
+    engineOptions;
+    onReturn;
+    alt = null;
+    unsubAltInput = null;
+    constructor(primary, io, options = {}) {
+        this.primary = primary;
+        this.io = io;
+        this.engineOptions = options.engineOptions;
+        this.onReturn = options.onReturn;
+    }
+    /** 副屏在场态 */
+    get isOpen() {
+        return this.alt !== null;
+    }
+    /**
+     * 进副屏：挂起主屏 → 副屏 Engine 进屏 → 输入转发接线。
+     * 拒绝位：已在副屏 / 主屏不在 running 态（无挂起对象）返 null。
+     */
+    open(content) {
+        if (this.alt !== null)
+            return null; // 已在副屏——无嵌套备屏
+        if (this.primary.lifecycle !== 'running')
+            return null; // 主屏不在场无挂起对象
+        this.primary.suspendMain(); // 出主屏（编舞对称的进半场）
+        const base = this.engineOptions;
+        const alt = new Engine({
+            ...base,
+            io: this.io,
+            screen: 'alt-screen',
+            // X10 首达降级组合柄：关鼠标签听回终端原生选区 + 链原注入柄（透传面）
+            onMouseLegacy: () => {
+                this.io.write('\x1b[?1006l\x1b[?1002l'); // DECRST（与出屏关序同取——对称律同序）
+                base?.onMouseLegacy?.();
+            },
+        });
+        alt.start(content); // 1049 备屏进 + 首帧（start 显式放流——共享 io 接缝）
+        this.unsubAltInput = alt.on('input', (event) => {
+            content.handleEvent(event); // 副屏内容终局消费（回看器键盘滚动）
+        });
+        this.alt = alt;
+        let closed = false;
+        return {
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                this.close();
+            },
+            get closed() {
+                return closed;
+            },
+        };
+    }
+    /** 出副屏（幂等）：退订 → 副屏 dispose → 主屏 resume（全帧重画）→ onReturn 钩 */
+    close() {
+        const alt = this.alt;
+        if (alt === null)
+            return;
+        this.unsubAltInput?.(); // 先退订转发（防 dispose 过程竞发）
+        this.unsubAltInput = null;
+        this.alt = null;
+        alt.dispose(); // 备屏出 + raw 复原 + pause 流
+        this.primary.resumeMain(); // 主屏复起 + 全帧重画不走 repaint（07 条款）+ 瞬时行补吐
+        this.onReturn?.();
+    }
+}
+//# sourceMappingURL=alt-screen.js.map

package/dist/src/channels/tui/overlay/alt-screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alt-screen.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/overlay/alt-screen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,MAAM,EAAsB,MAAM,uBAAuB,CAAC;AA6BnE;;GAEG;AACH,MAAM,OAAO,aAAa;IACP,OAAO,CAAmB;IAC1B,EAAE,CAAa;IACf,aAAa,CAAmD;IAChE,QAAQ,CAA2B;IAC5C,GAAG,GAAkB,IAAI,CAAC;IAC1B,aAAa,GAAwB,IAAI,CAAC;IAElD,YAAY,OAAyB,EAAE,EAAc,EAAE,UAA4B,EAAE;QACnF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,YAAY;IACZ,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,OAAuB;QAC1B,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,CAAC,cAAc;QAClD,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,CAAC,aAAa;QACpE,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,gBAAgB;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC;YACrB,GAAG,IAAI;YACP,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,MAAM,EAAE,YAAY;YACpB,wCAAwC;YACxC,aAAa,EAAE,GAAG,EAAE;gBAClB,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC,yBAAyB;gBAClE,IAAI,EAAE,aAAa,EAAE,EAAE,CAAC;YAC1B,CAAC;SACF,CAAC,CAAC;QACH,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,sCAAsC;QAC1D,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAiB,EAAE,EAAE;YACzD,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,oBAAoB;QAClD,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,OAAO;YACL,KAAK,EAAE,GAAG,EAAE;gBACV,IAAI,MAAM;oBAAE,OAAO;gBACnB,MAAM,GAAG,IAAI,CAAC;gBACd,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,CAAC;YACD,IAAI,MAAM;gBACR,OAAO,MAAM,CAAC;YAChB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,4DAA4D;IACpD,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACrB,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO;QACzB,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,wBAAwB;QAChD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;QAChB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,yBAAyB;QACxC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,sCAAsC;QACjE,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/src/channels/tui/overlay/overlay.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 主屏浮层基建（07 §4.1 引擎节件 6（组件与呈现装配件））：OverlayStack——cell 网格局部区浮层。
+ *
+ * 「overlay」专指主屏浮层（不进 1049 备屏——副屏另名 AltScreenHost）：
+ * - 栈形多枚并存，栈底先画、栈顶最后画（覆盖序即栈序）；
+ * - 锚定是函数（拿帧几何自由定位——select / confirm 挂输入框上方等），
+ *   返回 region 须在屏内（越界写由缓冲吸收——缓冲兜底，锚定函数自律）；
+ * - 事件路由模态独占：栈非空时 routeEvent 恒返 true——占焦期间未消费键
+ *   不穿透至 UiBackend 三序（07 §4.3 输入路由拦截链条款）；
+ * - 进出栈经 onChange 通知装配层请求重绘（overlay 是主屏帧的组成段）。
+ */
+import type { CellBuffer, InputEvent, Region, Renderable } from '../../engine/index.js';
+/** 浮层内容协议：可渲染 + 可吃键（占焦模态件的两面） */
+export interface OverlayContent extends Renderable {
+    /** 键 / 文本 / IME / 粘贴事件分发（返回是否消费——未消费也不穿透） */
+    handleEvent(event: InputEvent): boolean;
+}
+/** 锚定函数（帧几何 → 浮层区域；返回 region 须在屏内——缓冲吸收越界兜底） */
+export type OverlayAnchor = (frame: {
+    width: number;
+    height: number;
+}) => Region;
+/** 浮层句柄（两形态共用——主屏浮层与副屏同形接口） */
+export interface OverlayHandle {
+    /** 关层（幂等；非栈顶亦可关——按句柄定位移除） */
+    close(): void;
+    /** 已关态 */
+    readonly closed: boolean;
+}
+/**
+ * 浮层栈：主屏帧的「后画段」与输入路由的「先吃段」。
+ *
+ * 装配序（每帧）：主树 render → renderAll（浮层覆盖其上）；
+ * 路由序（每键）：routeEvent（栈非空短路三序）→ UiBackend 命令 / 队列 / 输入框。
+ */
+export declare class OverlayStack {
+    private entries;
+    /** 栈变更通知（开 / 关——装配层接重绘请求） */
+    onChange?: () => void;
+    /** 在场浮层数 */
+    get size(): number;
+    /** 在场浮层只读快照（栈底→栈顶——装配层量高遍历/测试观测面） */
+    get contents(): readonly OverlayContent[];
+    /** 开层：压栈 + 返回句柄（幂等关闭归句柄） */
+    open(content: OverlayContent, anchor: OverlayAnchor): OverlayHandle;
+    /** 浮层渲染（主树渲染后调用——栈底先画、栈顶覆盖） */
+    renderAll(buffer: CellBuffer): void;
+    /**
+     * 事件路由（模态独占）：栈顶先吃；**栈非空恒返 true**——未消费键不穿透
+     * 至三序（07 §4.3 overlay 占焦条款）。栈空返 false（无浮层归常态路由）。
+     */
+    routeEvent(event: InputEvent): boolean;
+}

package/dist/src/channels/tui/overlay/overlay.js

@@ -0,0 +1,58 @@
+/**
+ * 浮层栈：主屏帧的「后画段」与输入路由的「先吃段」。
+ *
+ * 装配序（每帧）：主树 render → renderAll（浮层覆盖其上）；
+ * 路由序（每键）：routeEvent（栈非空短路三序）→ UiBackend 命令 / 队列 / 输入框。
+ */
+export class OverlayStack {
+    entries = [];
+    /** 栈变更通知（开 / 关——装配层接重绘请求） */
+    onChange;
+    /** 在场浮层数 */
+    get size() {
+        return this.entries.length;
+    }
+    /** 在场浮层只读快照（栈底→栈顶——装配层量高遍历/测试观测面） */
+    get contents() {
+        return this.entries.map((entry) => entry.content);
+    }
+    /** 开层：压栈 + 返回句柄（幂等关闭归句柄） */
+    open(content, anchor) {
+        const entry = { content, anchor, closed: false };
+        this.entries.push(entry);
+        this.onChange?.();
+        return {
+            close: () => {
+                if (entry.closed)
+                    return;
+                entry.closed = true;
+                const idx = this.entries.indexOf(entry);
+                if (idx >= 0)
+                    this.entries.splice(idx, 1);
+                this.onChange?.();
+            },
+            get closed() {
+                return entry.closed;
+            },
+        };
+    }
+    /** 浮层渲染（主树渲染后调用——栈底先画、栈顶覆盖） */
+    renderAll(buffer) {
+        for (const entry of this.entries) {
+            const region = entry.anchor({ width: buffer.columns, height: buffer.rows });
+            entry.content.render(buffer, region);
+        }
+    }
+    /**
+     * 事件路由（模态独占）：栈顶先吃；**栈非空恒返 true**——未消费键不穿透
+     * 至三序（07 §4.3 overlay 占焦条款）。栈空返 false（无浮层归常态路由）。
+     */
+    routeEvent(event) {
+        const top = this.entries[this.entries.length - 1];
+        if (top === undefined)
+            return false;
+        top.content.handleEvent(event); // 消费与否都在层内终局（不穿透）
+        return true;
+    }
+}
+//# sourceMappingURL=overlay.js.map

package/dist/src/channels/tui/overlay/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/overlay/overlay.ts"],"names":[],"mappings":"AAqCA;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IACf,OAAO,GAAmB,EAAE,CAAC;IACrC,6BAA6B;IAC7B,QAAQ,CAAc;IAEtB,YAAY;IACZ,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,qCAAqC;IACrC,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpD,CAAC;IAED,4BAA4B;IAC5B,IAAI,CAAC,OAAuB,EAAE,MAAqB;QACjD,MAAM,KAAK,GAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC/D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;QAClB,OAAO;YACL,KAAK,EAAE,GAAG,EAAE;gBACV,IAAI,KAAK,CAAC,MAAM;oBAAE,OAAO;gBACzB,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;gBACpB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACxC,IAAI,GAAG,IAAI,CAAC;oBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC1C,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YACpB,CAAC;YACD,IAAI,MAAM;gBACR,OAAO,KAAK,CAAC,MAAM,CAAC;YACtB,CAAC;SACF,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,SAAS,CAAC,MAAkB;QAC1B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YAC5E,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,KAAiB;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAClD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACpC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,kBAAkB;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/src/channels/tui/overlay/select-confirm.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 一次性问答面板两枚（07 §4.3）：select / confirm 的主屏浮层实装。
+ *
+ * - select：↑/↓ 移动高亮、Enter 选定、Esc 取消收 ''（与撤销面保守值同语义）；
+ * - confirm：Enter/y 确认 true、Esc/n 取消 false（保守值 = 不动原状态）；
+ * - 一次性问答不值得整屏切换——主屏浮层形态（挂 OverlayStack，不进 1049）；
+ * - 面板底先铺空格再写内容（写格覆盖下层浮出内容——不写格的位置会透出
+ *   主树文字）；
+ * - onFinish 单次语义（触发即完成态，后续事件静默——防连按双 resolve）；
+ *   关层归装配（onFinish 回调里 close 句柄——裸件不持栈引用）。
+ */
+import type { CellBuffer, InputEvent, Region, Renderable } from '../../engine/index.js';
+/** 保守取消值（select——空串与撤销面同语义） */
+export declare const SELECT_CANCELLED = "";
+/** 选项（value 是应答值、label 是呈现、hint 右侧说明段） */
+export interface SelectOption {
+    readonly value: string;
+    readonly label: string;
+    readonly hint?: string;
+}
+/** select 面板选项集 */
+export interface SelectPanelOptions {
+    readonly title?: string;
+    readonly options: readonly SelectOption[];
+}
+/**
+ * 选择面板：单选浮层。onFinish 后赋（装配在 open 句柄后接线——闭包里关层）。
+ */
+export declare class SelectPanel implements Renderable {
+    /** 完成回调（Enter 选定 value / Esc 取消收 ''）——装配接线 */
+    onFinish?: (value: string) => void;
+    private activeIndex;
+    private done;
+    private readonly title;
+    private readonly options;
+    constructor(options: SelectPanelOptions);
+    /** 量高：标题（有则 1）+ 选项行数（单行制——不折行，超宽截断归渲染） */
+    measure(width: number): number;
+    /** 落位：铺底空格 → 标题 → 选项行（高亮反色 + 说明右对齐） */
+    render(buffer: CellBuffer, region: Region): void;
+    /** 事件分发：完成态静默；↑/↓ 循环移动、Enter 选定、Esc 取消 */
+    handleEvent(event: InputEvent): boolean;
+    /** 单次完成路（触发后锁完成态） */
+    private finish;
+}
+/** confirm 面板配置 */
+export interface ConfirmPanelOptions {
+    readonly message: string;
+    /** 确认键提示文案（缺省 'enter 确认'） */
+    readonly confirmHint?: string;
+    /** 取消键提示文案（缺省 'esc 取消'） */
+    readonly cancelHint?: string;
+}
+/**
+ * 确认面板：两键问答浮层（Enter/y → true、Esc/n → false——保守值 = 不动原状态）。
+ */
+export declare class ConfirmPanel implements Renderable {
+    /** 完成回调——装配接线（同 SelectPanel 形） */
+    onFinish?: (confirmed: boolean) => void;
+    private done;
+    private readonly message;
+    private readonly confirmHint;
+    private readonly cancelHint;
+    constructor(options: ConfirmPanelOptions);
+    /** 量高：消息 1 + 键提示 1 */
+    measure(width: number): number;
+    /** 落位：铺底空格 → 消息 → 键提示（dim） */
+    render(buffer: CellBuffer, region: Region): void;
+    /** 事件分发：Enter/y 确认、Esc/n 取消（保守值） */
+    handleEvent(event: InputEvent): boolean;
+    /** 单次完成路 */
+    private finish;
+}

package/dist/src/channels/tui/overlay/select-confirm.js

@@ -0,0 +1,157 @@
+import { ACCENT_INDEX } from '../theme.js';
+import { ansiColor } from '../../engine/index.js';
+import { prefixDisplayWidth } from '../editor/visual-lines.js';
+/** 保守取消值（select——空串与撤销面同语义） */
+export const SELECT_CANCELLED = '';
+/** 高亮行样式（整行反色——面板内最强存在感） */
+const ACTIVE_STYLE = Object.freeze({ inverse: true });
+/** 标题样式（accent 定值——theme 单源） */
+const TITLE_STYLE = Object.freeze({ fg: ansiColor(ACCENT_INDEX) });
+/** 说明段样式（dim） */
+const HINT_STYLE = Object.freeze({ dim: true });
+/** 无修饰单字符 / 命名键匹配 */
+function isPlainKey(e, key) {
+    return !e.ctrl && !e.alt && !e.shift && !e.meta && e.key === key;
+}
+/** 键事件窄化（其他事件形面板不消费） */
+function asKey(event) {
+    return event.kind === 'key' ? event : null;
+}
+/**
+ * 选择面板：单选浮层。onFinish 后赋（装配在 open 句柄后接线——闭包里关层）。
+ */
+export class SelectPanel {
+    /** 完成回调（Enter 选定 value / Esc 取消收 ''）——装配接线 */
+    onFinish;
+    activeIndex = 0;
+    done = false;
+    title;
+    options;
+    constructor(options) {
+        this.title = options.title;
+        this.options = options.options;
+    }
+    /** 量高：标题（有则 1）+ 选项行数（单行制——不折行，超宽截断归渲染） */
+    measure(width) {
+        void width; // 高与宽无关（截断不折行）
+        return (this.title !== undefined ? 1 : 0) + this.options.length;
+    }
+    /** 落位：铺底空格 → 标题 → 选项行（高亮反色 + 说明右对齐） */
+    render(buffer, region) {
+        // 铺底空格（写格覆盖——未写格会透出主树文字）
+        for (let r = 0; r < region.height; r++) {
+            for (let c = 0; c < region.width; c++) {
+                buffer.setCell(region.row + r, region.col + c, ' ');
+            }
+        }
+        let row = region.row;
+        if (this.title !== undefined) {
+            buffer.writeText(row, region.col, this.title, TITLE_STYLE);
+            row += 1;
+        }
+        for (let i = 0; i < this.options.length; i++, row++) {
+            const active = i === this.activeIndex;
+            const option = this.options[i];
+            // 前缀 + label 段（高亮行整段反色）
+            const prefix = active ? '❯ ' : '  ';
+            buffer.writeText(row, region.col, `${prefix}${option.label}`, active ? ACTIVE_STYLE : undefined);
+            // 说明段右对齐（dim 恒态——不随高亮变脸；按显示宽——CJK 段宽 ≠ 码位数）
+            if (option.hint !== undefined && option.hint.length > 0) {
+                const hintCols = prefixDisplayWidth(option.hint, option.hint.length);
+                buffer.writeText(row, region.col + region.width - hintCols, option.hint, HINT_STYLE);
+            }
+        }
+    }
+    /** 事件分发：完成态静默；↑/↓ 循环移动、Enter 选定、Esc 取消 */
+    handleEvent(event) {
+        const e = asKey(event);
+        if (e === null)
+            return true; // 面板占焦——非键事件（文本 / IME / 粘贴）层内终局
+        if (e.phase === 'release' || this.done)
+            return true;
+        if (e.ctrl || e.alt || e.shift || e.meta)
+            return true;
+        if (e.key === 'up') {
+            this.activeIndex = this.activeIndex === 0 ? this.options.length - 1 : this.activeIndex - 1;
+            return true;
+        }
+        if (e.key === 'down') {
+            this.activeIndex = this.activeIndex === this.options.length - 1 ? 0 : this.activeIndex + 1;
+            return true;
+        }
+        if (e.key === 'enter') {
+            this.finish(this.options[this.activeIndex]?.value ?? SELECT_CANCELLED);
+            return true;
+        }
+        if (e.key === 'escape') {
+            this.finish(SELECT_CANCELLED);
+            return true;
+        }
+        return true; // 其余键层内终局（模态独占——不穿透）
+    }
+    /** 单次完成路（触发后锁完成态） */
+    finish(value) {
+        if (this.done)
+            return;
+        this.done = true;
+        this.onFinish?.(value);
+    }
+}
+/**
+ * 确认面板：两键问答浮层（Enter/y → true、Esc/n → false——保守值 = 不动原状态）。
+ */
+export class ConfirmPanel {
+    /** 完成回调——装配接线（同 SelectPanel 形） */
+    onFinish;
+    done = false;
+    message;
+    confirmHint;
+    cancelHint;
+    constructor(options) {
+        this.message = options.message;
+        this.confirmHint = options.confirmHint ?? 'enter 确认';
+        this.cancelHint = options.cancelHint ?? 'esc 取消';
+    }
+    /** 量高：消息 1 + 键提示 1 */
+    measure(width) {
+        void width;
+        return 2;
+    }
+    /** 落位：铺底空格 → 消息 → 键提示（dim） */
+    render(buffer, region) {
+        for (let r = 0; r < region.height; r++) {
+            for (let c = 0; c < region.width; c++) {
+                buffer.setCell(region.row + r, region.col + c, ' ');
+            }
+        }
+        buffer.writeText(region.row, region.col, this.message);
+        buffer.writeText(region.row + 1, region.col, `${this.confirmHint} · ${this.cancelHint}`, HINT_STYLE);
+    }
+    /** 事件分发：Enter/y 确认、Esc/n 取消（保守值） */
+    handleEvent(event) {
+        const e = asKey(event);
+        if (e === null)
+            return true;
+        if (e.phase === 'release' || this.done)
+            return true;
+        if (e.ctrl || e.alt || e.shift || e.meta)
+            return true;
+        if (isPlainKey(e, 'enter') || isPlainKey(e, 'y')) {
+            this.finish(true);
+            return true;
+        }
+        if (isPlainKey(e, 'escape') || isPlainKey(e, 'n')) {
+            this.finish(false);
+            return true;
+        }
+        return true; // 其余键层内终局
+    }
+    /** 单次完成路 */
+    finish(confirmed) {
+        if (this.done)
+            return;
+        this.done = true;
+        this.onFinish?.(confirmed);
+    }
+}
+//# sourceMappingURL=select-confirm.js.map

package/dist/src/channels/tui/overlay/select-confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-confirm.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/overlay/select-confirm.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAkB,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,+BAA+B;AAC/B,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAEnC,4BAA4B;AAC5B,MAAM,YAAY,GAAwB,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AAC3E,gCAAgC;AAChC,MAAM,WAAW,GAAwB,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;AACxF,iBAAiB;AACjB,MAAM,UAAU,GAAwB,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;AAErE,qBAAqB;AACrB,SAAS,UAAU,CAAC,CAA+B,EAAE,GAAW;IAC9D,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC;AACnE,CAAC;AAED,wBAAwB;AACxB,SAAS,KAAK,CAAC,KAAiB;IAC9B,OAAO,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAE,KAAsC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/E,CAAC;AAeD;;GAEG;AACH,MAAM,OAAO,WAAW;IACtB,8CAA8C;IAC9C,QAAQ,CAA2B;IAC3B,WAAW,GAAG,CAAC,CAAC;IAChB,IAAI,GAAG,KAAK,CAAC;IACJ,KAAK,CAAqB;IAC1B,OAAO,CAA0B;IAElD,YAAY,OAA2B;QACrC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,0CAA0C;IAC1C,OAAO,CAAC,KAAa;QACnB,KAAK,KAAK,CAAC,CAAC,eAAe;QAC3B,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAClE,CAAC;IAED,uCAAuC;IACvC,MAAM,CAAC,MAAkB,EAAE,MAAc;QACvC,yBAAyB;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;QACD,IAAI,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACrB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YAC3D,GAAG,IAAI,CAAC,CAAC;QACX,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC;YACpD,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,CAAC,WAAW,CAAC;YACtC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;YAChC,wBAAwB;YACxB,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YACpC,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACjG,4CAA4C;YAC5C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACrE,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,GAAG,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACvF,CAAC;QACH,CAAC;IACH,CAAC;IAED,0CAA0C;IAC1C,WAAW,CAAC,KAAiB;QAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,CAAC,gCAAgC;QAC7D,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACpD,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACtD,IAAI,CAAC,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;YAC3F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;YAC3F,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,KAAK,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,IAAI,gBAAgB,CAAC,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC9B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,CAAC,qBAAqB;IACpC,CAAC;IAED,qBAAqB;IACb,MAAM,CAAC,KAAa;QAC1B,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;CACF;AAWD;;GAEG;AACH,MAAM,OAAO,YAAY;IACvB,kCAAkC;IAClC,QAAQ,CAAgC;IAChC,IAAI,GAAG,KAAK,CAAC;IACJ,OAAO,CAAS;IAChB,WAAW,CAAS;IACpB,UAAU,CAAS;IAEpC,YAAY,OAA4B;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,UAAU,CAAC;QACrD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,QAAQ,CAAC;IACnD,CAAC;IAED,sBAAsB;IACtB,OAAO,CAAC,KAAa;QACnB,KAAK,KAAK,CAAC;QACX,OAAO,CAAC,CAAC;IACX,CAAC;IAED,8BAA8B;IAC9B,MAAM,CAAC,MAAkB,EAAE,MAAc;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;QACD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACvD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,MAAM,IAAI,CAAC,UAAU,EAAE,EAAE,UAAU,CAAC,CAAC;IACvG,CAAC;IAED,oCAAoC;IACpC,WAAW,CAAC,KAAiB;QAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC5B,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACpD,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,IAAI,CAAC;QACtD,IAAI,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,CAAC,UAAU;IACzB,CAAC;IAED,YAAY;IACJ,MAAM,CAAC,SAAkB;QAC/B,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/channels/tui/panels/todo-panel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * todo 面板（07 §4.1 呈现面件 4）——输入框上方紧凑面板。
+ *
+ * - 数据面纯呈现投影：items 全量快照经 `update()` 整体替换（真源 = 装配
+ *   注入的 todoFor——05 §1.1 todo/write 事件载荷的会话侧映射，webui SPA
+ *   同源折叠产物）；空表与 null/undefined 同为清板；
+ * - 条目四态记号：☐ 待办 / ◐ 进行中（activeForm 优先于 content——CC 式
+ *   文案）/ ☑ 已完成·暗淡 / ⊙ 缓办·暗淡；
+ * - 帽 6 条 + 溢出行「+ N 更多」（暗淡）；
+ * - 刷新时机归装配（TuiBackend 三时点 repaint / tool_execution_end /
+ *   agent_end——批 10e-2 已接线），件内零时钟零事件面。
+ */
+import { type CellBuffer, type Region, type Renderable } from '../../engine/index.js';
+import type { TodoItem } from '../../types.js';
+/** todo 面板：条目快照 → 固定区行段（清板即零行——布局自洽） */
+export declare class TodoPanel implements Renderable {
+    private items;
+    /** 快照整体替换（null / undefined / 空表同义——清板） */
+    update(items: readonly TodoItem[] | null | undefined): void;
+    /** 量高：清板 0；帽内条数 + 溢出行 */
+    measure(width: number): number;
+    /** 落位：每条一行（记号 + 空格 + 内容截断）；溢出行收尾 */
+    render(buffer: CellBuffer, region: Region): void;
+}

package/dist/src/channels/tui/panels/todo-panel.js

@@ -0,0 +1,55 @@
+/**
+ * todo 面板（07 §4.1 呈现面件 4）——输入框上方紧凑面板。
+ *
+ * - 数据面纯呈现投影：items 全量快照经 `update()` 整体替换（真源 = 装配
+ *   注入的 todoFor——05 §1.1 todo/write 事件载荷的会话侧映射，webui SPA
+ *   同源折叠产物）；空表与 null/undefined 同为清板；
+ * - 条目四态记号：☐ 待办 / ◐ 进行中（activeForm 优先于 content——CC 式
+ *   文案）/ ☑ 已完成·暗淡 / ⊙ 缓办·暗淡；
+ * - 帽 6 条 + 溢出行「+ N 更多」（暗淡）；
+ * - 刷新时机归装配（TuiBackend 三时点 repaint / tool_execution_end /
+ *   agent_end——批 10e-2 已接线），件内零时钟零事件面。
+ */
+import { truncateToWidth } from '../../engine/index.js';
+/** 帽内条数（溢出行另计——spec 定形不预收数字者已实测定形 6） */
+const MAX_ITEMS = 6;
+/** 四态记号（呈现投影——07 §4.1 件 4 定形） */
+const STATUS_MARKS = Object.freeze({
+    pending: '☐',
+    'in-progress': '◐',
+    completed: '☑',
+    deferred: '⊙',
+});
+/** 暗淡两态（已完成 / 缓办——退场视觉语义） */
+const DIM_STATUSES = new Set(['completed', 'deferred']);
+/** todo 面板：条目快照 → 固定区行段（清板即零行——布局自洽） */
+export class TodoPanel {
+    items = [];
+    /** 快照整体替换（null / undefined / 空表同义——清板） */
+    update(items) {
+        this.items = items ?? [];
+    }
+    /** 量高：清板 0；帽内条数 + 溢出行 */
+    measure(width) {
+        void width; // 条目单行制——宽度不敏感（内容截断吸收）
+        if (this.items.length === 0)
+            return 0;
+        return Math.min(this.items.length, MAX_ITEMS) + (this.items.length > MAX_ITEMS ? 1 : 0);
+    }
+    /** 落位：每条一行（记号 + 空格 + 内容截断）；溢出行收尾 */
+    render(buffer, region) {
+        const visible = this.items.slice(0, MAX_ITEMS);
+        visible.forEach((item, i) => {
+            const dimmed = DIM_STATUSES.has(item.status);
+            // 进行中 activeForm 优先（缺席回落 content）
+            const content = item.status === 'in-progress' && item.activeForm !== undefined ? item.activeForm : item.content;
+            const row = `${STATUS_MARKS[item.status]} ${truncateToWidth(content, region.width - 2)}`;
+            buffer.writeText(region.row + i, region.col, row, dimmed ? { dim: true } : undefined);
+        });
+        const overflow = this.items.length - MAX_ITEMS;
+        if (overflow > 0) {
+            buffer.writeText(region.row + MAX_ITEMS, region.col, `+ ${overflow} 更多`, { dim: true });
+        }
+    }
+}
+//# sourceMappingURL=todo-panel.js.map

package/dist/src/channels/tui/panels/todo-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-panel.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/panels/todo-panel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,eAAe,EAAiD,MAAM,uBAAuB,CAAC;AAGvG,wCAAwC;AACxC,MAAM,SAAS,GAAG,CAAC,CAAC;AAEpB,iCAAiC;AACjC,MAAM,YAAY,GAAiD,MAAM,CAAC,MAAM,CAAC;IAC/E,OAAO,EAAE,GAAG;IACZ,aAAa,EAAE,GAAG;IAClB,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;CACd,CAAC,CAAC;AAEH,6BAA6B;AAC7B,MAAM,YAAY,GAAoC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AAEzF,wCAAwC;AACxC,MAAM,OAAO,SAAS;IACZ,KAAK,GAAwB,EAAE,CAAC;IAExC,0CAA0C;IAC1C,MAAM,CAAC,KAA6C;QAClD,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,yBAAyB;IACzB,OAAO,CAAC,KAAa;QACnB,KAAK,KAAK,CAAC,CAAC,uBAAuB;QACnC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,MAAkB,EAAE,MAAc;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAC/C,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;YAC1B,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7C,kCAAkC;YAClC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,aAAa,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;YAChH,MAAM,GAAG,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACzF,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACxF,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC;QAC/C,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,GAAG,SAAS,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,QAAQ,KAAK,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;CACF"}

package/dist/src/channels/tui/panels/tool-progress-panel.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 工具实时进度面板（07 §4.1 呈现面件 5）——状态行上方的瞬时活动面板。
+ *
+ * - 行生命周期：`tool_execution_start` 建档（toolCallId→名——**不建行**，
+ *   首个 `tool_execution_update` 才建行）/ 后续 update 原位换行 /
+ *   `tool_execution_end` 即摘行 / `clear()` 清板（agent_start·end·repaint
+ *   三时点——瞬时面律：不入正文、不跨 repaint 保存）；
+ * - 宽容解码（update 载荷契约面 `unknown`——03 §2.3 自由载荷，呈现侧零
+ *   契约收紧）：string 直显 / AgentToolResult 形〔content 块数组〕取文本块
+ *   倒扫末条非空行 / 其余视为文本缺席退化为 ` ▸ 名 …`；
+ * - 帽 4 行 + 溢出行「+ N 更多」；
+ * - 与件 3 分职互补：状态行示「执行哪个工具」、本件行示「输出到哪了」。
+ */
+import { type CellBuffer, type Region, type Renderable } from '../../engine/index.js';
+/**
+ * update 载荷宽容解码 → 末行输出文本（null = 文本缺席）。
+ * 网格行是单行物理面——string 形内部换行折叠空格（直显语义的物理收口）。
+ */
+export declare function decodeUpdateText(update: unknown): string | null;
+/** 工具进度面板：正在流 partial 的工具各占一行（清板即零行） */
+export declare class ToolProgressPanel implements Renderable {
+    /** 建档表（toolCallId→名——start 建档反查；end/clear 同摘） */
+    private readonly names;
+    private rows;
+    /** 建档不建行（工具名供 update 反查——无档退 toolCallId 防御路径） */
+    begin(toolCallId: string, name: string): void;
+    /** update 消费：已有行原位换文本；无行建行（首 update 建行条款） */
+    applyUpdate(toolCallId: string, update: unknown): void;
+    /** end 即摘行（建档同摘——迟到 update 无档退 id 名） */
+    end(toolCallId: string): void;
+    /** 清板（行与建档同清——agent_start·end·repaint 瞬时面律） */
+    clear(): void;
+    /** 量高：清板 0；帽内行数 + 溢出行 */
+    measure(width: number): number;
+    /** 落位：每工具一行 ` ▸ 名 · 末行`（缺席 ` ▸ 名 …`）；溢出行收尾 */
+    render(buffer: CellBuffer, region: Region): void;
+}