berry-agent-sdk 0.1.0-alpha.2

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

@@ -0,0 +1,94 @@
+/**
+ * 工具实时进度面板（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 { truncateToWidth } from '../../engine/index.js';
+/** 帽内行数（溢出行另计——spec 定形） */
+const MAX_ROWS = 4;
+/**
+ * update 载荷宽容解码 → 末行输出文本（null = 文本缺席）。
+ * 网格行是单行物理面——string 形内部换行折叠空格（直显语义的物理收口）。
+ */
+export function decodeUpdateText(update) {
+    if (typeof update === 'string') {
+        const collapsed = update.replaceAll('\n', ' ');
+        return collapsed.trim() === '' ? null : collapsed;
+    }
+    // AgentToolResult 形：content 块数组——取文本块的行序列倒扫末条非空行
+    if (typeof update === 'object' && update !== null && Array.isArray(update.content)) {
+        const lines = [];
+        for (const block of update.content) {
+            if (typeof block === 'object' &&
+                block !== null &&
+                block.type === 'text' &&
+                typeof block.text === 'string') {
+                lines.push(...block.text.split('\n'));
+            }
+        }
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (line !== '')
+                return line;
+        }
+    }
+    return null; // 数字/布尔/无文本块对象——文本缺席
+}
+/** 工具进度面板：正在流 partial 的工具各占一行（清板即零行） */
+export class ToolProgressPanel {
+    /** 建档表（toolCallId→名——start 建档反查；end/clear 同摘） */
+    names = new Map();
+    rows = [];
+    /** 建档不建行（工具名供 update 反查——无档退 toolCallId 防御路径） */
+    begin(toolCallId, name) {
+        this.names.set(toolCallId, name);
+    }
+    /** update 消费：已有行原位换文本；无行建行（首 update 建行条款） */
+    applyUpdate(toolCallId, update) {
+        const text = decodeUpdateText(update);
+        const existing = this.rows.find((row) => row.toolCallId === toolCallId);
+        if (existing !== undefined) {
+            existing.text = text;
+            return;
+        }
+        this.rows.push({ toolCallId, name: this.names.get(toolCallId) ?? toolCallId, text });
+    }
+    /** end 即摘行（建档同摘——迟到 update 无档退 id 名） */
+    end(toolCallId) {
+        this.rows = this.rows.filter((row) => row.toolCallId !== toolCallId);
+        this.names.delete(toolCallId);
+    }
+    /** 清板（行与建档同清——agent_start·end·repaint 瞬时面律） */
+    clear() {
+        this.rows = [];
+        this.names.clear();
+    }
+    /** 量高：清板 0；帽内行数 + 溢出行 */
+    measure(width) {
+        void width; // 行单行制——宽度不敏感（截断吸收）
+        if (this.rows.length === 0)
+            return 0;
+        return Math.min(this.rows.length, MAX_ROWS) + (this.rows.length > MAX_ROWS ? 1 : 0);
+    }
+    /** 落位：每工具一行 ` ▸ 名 · 末行`（缺席 ` ▸ 名 …`）；溢出行收尾 */
+    render(buffer, region) {
+        const visible = this.rows.slice(0, MAX_ROWS);
+        visible.forEach((row, i) => {
+            const tail = row.text !== null ? ` · ${row.text}` : ' …';
+            buffer.writeText(region.row + i, region.col, truncateToWidth(` ▸ ${row.name}${tail}`, region.width));
+        });
+        const overflow = this.rows.length - MAX_ROWS;
+        if (overflow > 0) {
+            buffer.writeText(region.row + MAX_ROWS, region.col, `+ ${overflow} 更多`, { dim: true });
+        }
+    }
+}
+//# sourceMappingURL=tool-progress-panel.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-progress-panel.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/panels/tool-progress-panel.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/tui/scroll/scroll-view.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 滚动视口件（07 §4.1 引擎节件 6（组件与呈现装配件））：行集 + 视口窗口化 + 键盘滚动 + 滚动条按需显隐。
+ *
+ * - 内容溢出视口才显滚动条（承 pi-tui `scrollbar:'auto'` 语义）：先按全宽折
+ *   视觉行判溢出，溢出则让出一列重折 + 画 thumb（两遍折叠换「按需占列」的
+ *   布局自洽——折宽分槽缓存，帧间零重折）；
+ * - follow 尾随模式（初始 true——回看器开屏显尾）：内容更替贴尾；上滚破随；
+ *   再滚到底复随（判据：偏移到达 maxOffset）；
+ * - 键盘滚动 ↑/↓ 单行、PgUp/PgDn 翻页、Home/End 到首尾（press/repeat 动作、
+ *   release 归上层）；滚轮 ±3 视觉行（vim mousescroll ver 缺省档——2026-09-11
+ *   鼠标解码批 mu-2 接入，走显式滚动路：破随后即时夹取、复随判据同键盘）；
+ * - 滚动条渐隐计时随组件批定形（07 挂账）——v1 溢出期间常显。
+ */
+import type { CellBuffer, InputEvent, Region, Renderable } from '../../engine/index.js';
+import { type VisualSegment } from '../editor/visual-lines.js';
+/** 滚动视口选项 */
+export interface ScrollViewOptions {
+    /** 量高帽（嵌入 Flex 布局时限制分配；缺省全量——副屏 root 直收全屏 region） */
+    readonly maxHeight?: number;
+}
+/**
+ * 滚动视口：逻辑行集为数据源，字素硬折视觉行（复用 editor 基件折行算术），
+ * 自持视口偏移与尾随态。
+ */
+export declare class ScrollView implements Renderable {
+    private lines;
+    /** 折叠缓存（行集引用失效 + 折宽分槽——同一行集多折宽并存零抖动） */
+    private cacheLines;
+    private cacheMaps;
+    /** 视口首行（视觉行下标） */
+    private offset;
+    /** 尾随模式（true = 内容更替贴尾） */
+    private follow;
+    /** 折宽与视口高实测（render / measure 回写——显式滚动的即时夹取依据） */
+    private lastWidth;
+    private viewportHeight;
+    /** 量高帽（嵌入 Flex 布局时限制分配；缺省全量——副屏 root 直收全屏 region） */
+    private readonly maxHeight;
+    /** 滚动通知（装配层接重绘请求） */
+    onScroll?: () => void;
+    constructor(options?: ScrollViewOptions);
+    /** 行集整体替换（回看器快照档——新事件不追加、整档重设） */
+    setLines(lines: string[]): void;
+    /** 绝对滚动（视觉行下标——越界即时夹取） */
+    scrollTo(viewportRow: number): void;
+    /** 相对滚动（负向上 / 正向下；0 无动作） */
+    scrollBy(delta: number): void;
+    /** 滚到顶部（破随） */
+    scrollToTop(): void;
+    /** 滚到底部（复随） */
+    scrollToEnd(): void;
+    /**
+     * 滚到逻辑行定位处（件 8 回看器搜索跳转消费）：定位处所在视觉行对齐视口顶
+     * （col 缺省 = 行首）；两遍折叠同 render 判溢出（溢出档折宽与呈现一致——
+     * 跳转落点不因滚动条让列错行）。显式滚动路——破随（applyOffset 同律）。
+     */
+    scrollToLine(line: number, col?: number): void;
+    /** 视口首行（夹取后的观测值） */
+    get scrollOffset(): number;
+    /** 尾随态（回看器判断是否在追新） */
+    get isFollowing(): boolean;
+    /** 量高：视觉行数夹 maxHeight（缺省全量——副屏 root 场景不经本路） */
+    measure(width: number): number;
+    /** 落位渲染：折行判溢出 → 夹取自愈 → 正文 → 滚动条（溢出才显） */
+    render(buffer: CellBuffer, region: Region): void;
+    /**
+     * 视口切片写出（批 10f-4 件 8 回看器接缝）：基类裸文本直写；子类覆写按
+     * 带样式行渲染（样式段 + 匹配高亮）——折叠与偏移算术恒归本件，样式呈现
+     * 归子类（零第二滚动引擎）。
+     */
+    protected writeSlice(buffer: CellBuffer, region: Region, displayRow: number, seg: VisualSegment): void;
+    /** 输入消费：key = 无修饰滚动键位（press/repeat 相）；mouse = 滚轮（其余归上层） */
+    handleEvent(event: InputEvent): boolean;
+    /** 视口几何观测（子类屏幕坐标反查用——render/measure 实测回写值） */
+    protected get viewportGeometry(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * 视口内显示行 → 视觉段反查（mu-2 子类接缝：屏幕坐标 → 逻辑位的折叠映射
+     * 半场——与 render 两遍折叠同判溢出同分槽缓存，零第二映射；界外返 null）。
+     */
+    protected segmentAt(displayRow: number): VisualSegment | null;
+    /** 滚动条列命中判（溢出让列时末列——07 件 8「视口外命中零动作」的判据位） */
+    protected hitScrollbar(col: number): boolean;
+    /** 折叠缓存取（行集引用 + 折宽双键——分槽并存） */
+    private visualMap;
+    /** 以已知折宽即时夹取（显式滚动 / 尾随贴尾的收口路——渲染后缓存命中零成本） */
+    private clampNow;
+    /** 偏移夹取（内容短于视口归零）+ 复随判据（到底即复随；破随只在显式滚动） */
+    private clampOffset;
+    /** 显式滚动统一路（先破随后即时夹取——夹到底自然复随） */
+    private applyOffset;
+    /** 滚动条：右列 thumb 段（size 按比例、start 按偏移比例） */
+    private drawScrollbar;
+}

package/dist/src/channels/tui/scroll/scroll-view.js

@@ -0,0 +1,255 @@
+import { buildVisualLineMap, findVisualLineAt } from '../editor/visual-lines.js';
+/** 滚动条 thumb 样式（dim——存在感弱于正文） */
+const SCROLLBAR_STYLE = Object.freeze({ dim: true });
+/** 滚动条 thumb 字符 */
+const THUMB = '┃';
+/** 未渲染过时的防御缺省（render 后由实测回写） */
+const DEFAULT_WIDTH = 80;
+const DEFAULT_PAGE_SIZE = 10;
+/** 单步滚动键位表（无修饰——ctrl/meta/shift 组合归上层） */
+const SCROLL_ACTIONS = Object.freeze({
+    up: 'line-up',
+    down: 'line-down',
+    pageup: 'page-up',
+    pagedown: 'page-down',
+    home: 'to-top',
+    end: 'to-bottom',
+});
+/** 滚轮单步视觉行数（vim mousescroll ver 缺省档三行——tmux copy-mode 五行不取；07 引擎节件 6 条款码面缺省参数） */
+const WHEEL_LINES = 3;
+/**
+ * 滚动视口：逻辑行集为数据源，字素硬折视觉行（复用 editor 基件折行算术），
+ * 自持视口偏移与尾随态。
+ */
+export class ScrollView {
+    lines = [];
+    /** 折叠缓存（行集引用失效 + 折宽分槽——同一行集多折宽并存零抖动） */
+    cacheLines = null;
+    cacheMaps = new Map();
+    /** 视口首行（视觉行下标） */
+    offset = 0;
+    /** 尾随模式（true = 内容更替贴尾） */
+    follow = true;
+    /** 折宽与视口高实测（render / measure 回写——显式滚动的即时夹取依据） */
+    lastWidth = DEFAULT_WIDTH;
+    viewportHeight = DEFAULT_PAGE_SIZE;
+    /** 量高帽（嵌入 Flex 布局时限制分配；缺省全量——副屏 root 直收全屏 region） */
+    maxHeight;
+    /** 滚动通知（装配层接重绘请求） */
+    onScroll;
+    constructor(options = {}) {
+        this.maxHeight = options.maxHeight;
+    }
+    /* ---------------- 数据面 ---------------- */
+    /** 行集整体替换（回看器快照档——新事件不追加、整档重设） */
+    setLines(lines) {
+        this.lines = lines;
+        this.cacheLines = null; // 缓存失效（引用比对落空即整缓存弃）
+        if (this.follow) {
+            this.offset = Number.MAX_SAFE_INTEGER; // 尾随贴尾
+            this.clampNow(); // 即时夹到视觉底
+        }
+    }
+    /* ---------------- 滚动控制面 ---------------- */
+    /** 绝对滚动（视觉行下标——越界即时夹取） */
+    scrollTo(viewportRow) {
+        this.applyOffset(viewportRow);
+    }
+    /** 相对滚动（负向上 / 正向下；0 无动作） */
+    scrollBy(delta) {
+        if (delta !== 0)
+            this.applyOffset(this.offset + delta);
+    }
+    /** 滚到顶部（破随） */
+    scrollToTop() {
+        this.applyOffset(0);
+    }
+    /** 滚到底部（复随） */
+    scrollToEnd() {
+        this.applyOffset(Number.MAX_SAFE_INTEGER);
+    }
+    /**
+     * 滚到逻辑行定位处（件 8 回看器搜索跳转消费）：定位处所在视觉行对齐视口顶
+     * （col 缺省 = 行首）；两遍折叠同 render 判溢出（溢出档折宽与呈现一致——
+     * 跳转落点不因滚动条让列错行）。显式滚动路——破随（applyOffset 同律）。
+     */
+    scrollToLine(line, col = 0) {
+        let map = this.visualMap(this.lastWidth, false);
+        if (map.length > this.viewportHeight)
+            map = this.visualMap(this.lastWidth, true);
+        // 定位处所在视觉行（col 落段判定——与 findVisualLineAt 同规则的本体内联）
+        const vi = findVisualLineAt(map, line, col);
+        this.applyOffset(vi);
+    }
+    /** 视口首行（夹取后的观测值） */
+    get scrollOffset() {
+        return this.offset;
+    }
+    /** 尾随态（回看器判断是否在追新） */
+    get isFollowing() {
+        return this.follow;
+    }
+    /* ---------------- 渲染协商 ---------------- */
+    /** 量高：视觉行数夹 maxHeight（缺省全量——副屏 root 场景不经本路） */
+    measure(width) {
+        this.lastWidth = width;
+        const map = this.visualMap(width, false);
+        const cap = this.maxHeight ?? map.length;
+        if (map.length <= cap)
+            return map.length;
+        // 溢出预判：滚动条让列重折后行数只多不少——以折后行数夹帽（量高即承诺，不超卖）
+        return Math.min(this.visualMap(width, true).length, cap);
+    }
+    /** 落位渲染：折行判溢出 → 夹取自愈 → 正文 → 滚动条（溢出才显） */
+    render(buffer, region) {
+        if (region.width <= 1 || region.height <= 0)
+            return; // 一列给内容都不够——防御位
+        this.lastWidth = region.width;
+        this.viewportHeight = region.height;
+        // 两遍折叠：全宽判溢出 → 溢出让一列重折（分槽缓存免抖动）
+        let map = this.visualMap(region.width, false);
+        const reservesBar = map.length > region.height;
+        if (reservesBar)
+            map = this.visualMap(region.width, true);
+        // follow 物化：尾随态贴真尾后再夹取（防御 setLines 时几何缺省值的贴尾失真
+        // ——批 10f-4 回看器开屏场景：构造期 clampNow 用缺省页高，首帧真几何才对齐）
+        if (this.follow)
+            this.offset = Number.MAX_SAFE_INTEGER;
+        this.clampOffset(map, region.height);
+        // 正文（视口内视觉行——切片写出经 writeSlice 单点，子类覆写带样式）
+        const end = Math.min(map.length, this.offset + region.height);
+        for (let vi = this.offset; vi < end; vi++) {
+            const seg = map[vi];
+            this.writeSlice(buffer, region, vi - this.offset, seg);
+        }
+        // 滚动条（溢出才显——右列 thumb 段按比例）
+        if (reservesBar)
+            this.drawScrollbar(buffer, region, map.length);
+    }
+    /**
+     * 视口切片写出（批 10f-4 件 8 回看器接缝）：基类裸文本直写；子类覆写按
+     * 带样式行渲染（样式段 + 匹配高亮）——折叠与偏移算术恒归本件，样式呈现
+     * 归子类（零第二滚动引擎）。
+     */
+    writeSlice(buffer, region, displayRow, seg) {
+        const line = this.lines[seg.line] ?? '';
+        buffer.writeText(region.row + displayRow, region.col, line.slice(seg.startCol, seg.startCol + seg.length));
+    }
+    /* ---------------- 输入事件 ---------------- */
+    /** 输入消费：key = 无修饰滚动键位（press/repeat 相）；mouse = 滚轮（其余归上层） */
+    handleEvent(event) {
+        if (event.kind === 'mouse') {
+            // 滚轮消费路（mu-2）：wheel 无 release 相（终端不报——press 一相到达）；
+            // 修饰位照常滚动——shift/ctrl+轮在终端侧多已截留改道（水平滚/缩放），
+            // SGR 报文到达即按垂直滚消费。走 scrollBy 显式滚动路（复随判据同键盘）
+            if (event.phase !== 'press')
+                return false;
+            if (event.button === 'wheel-up') {
+                this.scrollBy(-WHEEL_LINES);
+                return true;
+            }
+            if (event.button === 'wheel-down') {
+                this.scrollBy(WHEEL_LINES);
+                return true;
+            }
+            return false; // 非滚轮鼠标相归上层（子类选区路）
+        }
+        if (event.kind !== 'key')
+            return false;
+        if (event.phase === 'release')
+            return false;
+        if (event.ctrl || event.alt || event.shift || event.meta)
+            return false;
+        const action = SCROLL_ACTIONS[event.key];
+        if (action === undefined)
+            return false;
+        switch (action) {
+            case 'line-up':
+                this.scrollBy(-1);
+                break;
+            case 'line-down':
+                this.scrollBy(1);
+                break;
+            case 'page-up':
+                this.scrollBy(-this.viewportHeight);
+                break;
+            case 'page-down':
+                this.scrollBy(this.viewportHeight);
+                break;
+            case 'to-top':
+                this.scrollToTop();
+                break;
+            case 'to-bottom':
+                this.scrollToEnd();
+                break;
+        }
+        return true;
+    }
+    /* ---------------- 内部算术 ---------------- */
+    /** 视口几何观测（子类屏幕坐标反查用——render/measure 实测回写值） */
+    get viewportGeometry() {
+        return { width: this.lastWidth, height: this.viewportHeight };
+    }
+    /**
+     * 视口内显示行 → 视觉段反查（mu-2 子类接缝：屏幕坐标 → 逻辑位的折叠映射
+     * 半场——与 render 两遍折叠同判溢出同分槽缓存，零第二映射；界外返 null）。
+     */
+    segmentAt(displayRow) {
+        let map = this.visualMap(this.lastWidth, false);
+        if (map.length > this.viewportHeight)
+            map = this.visualMap(this.lastWidth, true);
+        return map[this.offset + displayRow] ?? null;
+    }
+    /** 滚动条列命中判（溢出让列时末列——07 件 8「视口外命中零动作」的判据位） */
+    hitScrollbar(col) {
+        const map = this.visualMap(this.lastWidth, false);
+        return map.length > this.viewportHeight && col === this.lastWidth - 1;
+    }
+    /** 折叠缓存取（行集引用 + 折宽双键——分槽并存） */
+    visualMap(width, reserveBar) {
+        const foldWidth = Math.max(1, width - (reserveBar ? 1 : 0));
+        if (this.cacheLines !== this.lines) {
+            this.cacheLines = this.lines;
+            this.cacheMaps.clear();
+        }
+        let map = this.cacheMaps.get(foldWidth);
+        if (map === undefined) {
+            map = buildVisualLineMap(this.lines, foldWidth);
+            this.cacheMaps.set(foldWidth, map);
+        }
+        return map;
+    }
+    /** 以已知折宽即时夹取（显式滚动 / 尾随贴尾的收口路——渲染后缓存命中零成本） */
+    clampNow() {
+        const map = this.visualMap(this.lastWidth, false);
+        this.clampOffset(map, this.viewportHeight);
+    }
+    /** 偏移夹取（内容短于视口归零）+ 复随判据（到底即复随；破随只在显式滚动） */
+    clampOffset(map, viewportHeight) {
+        const maxOffset = Math.max(0, map.length - viewportHeight);
+        this.offset = Math.min(Math.max(0, this.offset), maxOffset);
+        if (this.offset >= maxOffset)
+            this.follow = true;
+    }
+    /** 显式滚动统一路（先破随后即时夹取——夹到底自然复随） */
+    applyOffset(next) {
+        this.follow = false;
+        this.offset = Math.max(0, next);
+        this.clampNow();
+        this.onScroll?.();
+    }
+    /** 滚动条：右列 thumb 段（size 按比例、start 按偏移比例） */
+    drawScrollbar(buffer, region, totalLines) {
+        const h = region.height;
+        const maxOffset = Math.max(0, totalLines - h);
+        if (maxOffset === 0)
+            return; // 防御位（溢出判据已排除——双保险）
+        const thumbSize = Math.max(1, Math.floor((h * h) / totalLines));
+        const thumbStart = Math.round((this.offset / maxOffset) * (h - thumbSize));
+        const col = region.col + region.width - 1;
+        for (let r = 0; r < thumbSize; r++) {
+            buffer.setCell(region.row + thumbStart + r, col, THUMB, SCROLLBAR_STYLE);
+        }
+    }
+}
+//# sourceMappingURL=scroll-view.js.map

package/dist/src/channels/tui/scroll/scroll-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-view.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/scroll/scroll-view.ts"],"names":[],"mappings":"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"}

package/dist/src/channels/tui/status/status-line.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 状态行动画件（07 §4.1 呈现面件 3——批 10d-4）。
+ *
+ * - 转轮帧动画：braille 十帧（accent 着色——引擎节件 3 着色纪律的两个
+ *   accent 载体之一：对话输入件焦点边框与本件转轮）；帧推进 = `tick()`
+ *   （装配层定时驱动——件内零自驱时钟，测试确定性前提）；
+ * - 工具名实时显示：`tool_execution_start` 消费点 → ` ⚙ <工具名> …`
+ *   （状态面消费——正文面零渲染不变）；
+ * - 启停驱动：agent_start → start()、agent_end → stop()；
+ * - 与 setStatus last-writer-wins 共存（件 6 usage 行与 ctx.ui.setStatus
+ *   同一载体的闲态文案）：忙态显转轮段、闲态显文案行；
+ * - onChange 通知：状态任何变更（启停/换工具/换文案/推帧）触发——装配层
+ *   接重绘请求。
+ */
+import type { CellBuffer, Region, Renderable } from '../../engine/index.js';
+/** 状态行动画件（量高恒 1 行——底部固定区状态行） */
+export declare class StatusLine implements Renderable {
+    /** 状态变更通知（装配层接重绘请求——start/stop/setTool/setStatus/tick） */
+    onChange?: () => void;
+    private busy;
+    /** 忙态文案（agent_start 附带的活动描述——工具名在场时让位） */
+    private busyText;
+    /** 闲态文案（setStatus last-writer-wins——忙时写入挂起、闲时呈现） */
+    private idleText;
+    /** 实时工具名（tool_execution_start 写入；null = 无工具在场） */
+    private toolName;
+    private frameIndex;
+    /** 量高：恒 1（状态行单行制） */
+    measure(width: number): number;
+    /** 落位：忙态 = 转轮（accent）+ 工具段/活动文案；闲态 = 文案行（空则空行） */
+    render(buffer: CellBuffer, region: Region): void;
+    /** 进入忙态（agent_start 驱动；text = 可选活动描述） */
+    start(text?: string): void;
+    /** 退出忙态（agent_end 驱动——工具名一并清） */
+    stop(): void;
+    /** 忙态观测（装配层布防抖逻辑用） */
+    get isBusy(): boolean;
+    /** 实时工具名（tool_execution_start → name；null 清——工具退场） */
+    setTool(name: string | null): void;
+    /** 闲态文案（last-writer-wins——usage 行与自定义状态同载体共存） */
+    setStatus(text: string): void;
+    /** 推帧（装配层定时驱动——仅忙态有意义；闲态推帧零变化零通知） */
+    tick(): void;
+    /** 当前转轮帧观测面（测试断言帧推进用） */
+    get frame(): string;
+}

package/dist/src/channels/tui/status/status-line.js

@@ -0,0 +1,77 @@
+import { ansiColor } from '../../engine/index.js';
+import { ACCENT_INDEX } from '../theme.js';
+/** 转轮帧序（braille 十帧——accent 呈现形态随组件批定形，本批定形） */
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/** 转轮样式（accent 定值——theme 单源） */
+const SPINNER_STYLE = Object.freeze({ fg: ansiColor(ACCENT_INDEX) });
+/** 状态行动画件（量高恒 1 行——底部固定区状态行） */
+export class StatusLine {
+    /** 状态变更通知（装配层接重绘请求——start/stop/setTool/setStatus/tick） */
+    onChange;
+    busy = false;
+    /** 忙态文案（agent_start 附带的活动描述——工具名在场时让位） */
+    busyText = '';
+    /** 闲态文案（setStatus last-writer-wins——忙时写入挂起、闲时呈现） */
+    idleText = '';
+    /** 实时工具名（tool_execution_start 写入；null = 无工具在场） */
+    toolName = null;
+    frameIndex = 0;
+    /** 量高：恒 1（状态行单行制） */
+    measure(width) {
+        void width;
+        return 1;
+    }
+    /** 落位：忙态 = 转轮（accent）+ 工具段/活动文案；闲态 = 文案行（空则空行） */
+    render(buffer, region) {
+        if (this.busy) {
+            const frame = SPINNER_FRAMES[this.frameIndex % SPINNER_FRAMES.length];
+            buffer.writeText(region.row, region.col, frame, SPINNER_STYLE);
+            // 转轮后文案段（rest 自带前导空格——起点 = 转轮格 +1；工具名优先——件 3 语义）
+            const rest = this.toolName !== null ? ` ⚙ ${this.toolName} …` : this.busyText !== '' ? ` ${this.busyText}` : '';
+            if (rest !== '')
+                buffer.writeText(region.row, region.col + 1, rest);
+        }
+        else if (this.idleText !== '') {
+            buffer.writeText(region.row, region.col, this.idleText);
+        }
+    }
+    /** 进入忙态（agent_start 驱动；text = 可选活动描述） */
+    start(text = '') {
+        this.busy = true;
+        this.busyText = text;
+        this.toolName = null;
+        this.onChange?.();
+    }
+    /** 退出忙态（agent_end 驱动——工具名一并清） */
+    stop() {
+        this.busy = false;
+        this.toolName = null;
+        this.onChange?.();
+    }
+    /** 忙态观测（装配层布防抖逻辑用） */
+    get isBusy() {
+        return this.busy;
+    }
+    /** 实时工具名（tool_execution_start → name；null 清——工具退场） */
+    setTool(name) {
+        this.toolName = name;
+        this.onChange?.();
+    }
+    /** 闲态文案（last-writer-wins——usage 行与自定义状态同载体共存） */
+    setStatus(text) {
+        this.idleText = text;
+        this.onChange?.();
+    }
+    /** 推帧（装配层定时驱动——仅忙态有意义；闲态推帧零变化零通知） */
+    tick() {
+        if (!this.busy)
+            return;
+        this.frameIndex++;
+        this.onChange?.();
+    }
+    /** 当前转轮帧观测面（测试断言帧推进用） */
+    get frame() {
+        return SPINNER_FRAMES[this.frameIndex % SPINNER_FRAMES.length];
+    }
+}
+//# sourceMappingURL=status-line.js.map

package/dist/src/channels/tui/status/status-line.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-line.js","sourceRoot":"","sources":["../../../../../../../src/channels/tui/status/status-line.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,27 @@
+/**
+ * TUI 呈现配色面（07 篇 §4.1 引擎节件 3「着色克制」条款的定值件）。
+ *
+ * 着色纪律单源（引擎节件 3）：accent 只用于焦点指示面（现载体 = 对话输入件
+ * 焦点边框、状态行转轮、overlay 占焦族〔select 面板标题 + 补全弹层空态〕
+ * ——2026-09-07 实装对账补列），正文不混用（唯一例外 = 非聚焦摘要行的会话区分色
+ * ——非 accent 家族的第二着色位，见 sessionColor）；accent 无用户配置面——
+ * v1 固定内置色板、缺省索引在本件定值（「随组件批定值」的兑现位）。
+ */
+import { type AnsiColor } from '../engine/index.js';
+/**
+ * accent 缺省色号（v1 定值 = cyan 6）。
+ *
+ * 选型依据：cyan 是 16 色板经典强调色，与常见终端配色（暗底浅字）对比稳定；
+ * 索引 6 属标准 8 色，8 色降级终端（07 §4.1 支持矩阵——bold 亮色映射兜底）
+ * 下仍可辨。真彩 / 256 色升级挂账引擎节件 3，届时本值随色板扩展再裁。
+ */
+export declare const ACCENT_INDEX: AnsiColor;
+/**
+ * 会话区分色：会话短 id 散列映射 16 色板索引（07 引擎节件 3——确定性纯
+ * 函数、零配置零存储；berry themeFor「各归各色」的等价承接，主题配置面
+ * 不预造）。消费面 = 非聚焦摘要行着色（呈现面件 9），与 accent 家族互斥。
+ *
+ * 映射域 = 16 色板全域（含索引 0——黑底终端上可读性弱是已知取舍，按规范
+ * 字面全域映射；真实痛感出现时随色板升级挂账一并再裁）。
+ */
+export declare function sessionColor(sessionShortId: string): AnsiColor;