berry-agent-sdk 0.1.0-alpha.2

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../../../../../src/channels/tui/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,SAAS,EAAkB,MAAM,oBAAoB,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAc,SAAS,CAAC,CAAC,CAAC,CAAC;AAEpD;;;GAGG;AACH,SAAS,KAAK,CAAC,IAAY;IACzB,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,cAAsB;IACjD,OAAO,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CAAC;AACjD,CAAC"}

package/dist/src/channels/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * channels 件类型契约（L4 宿主固定件——02 篇席 10；机制真源 07 篇 §4.1/§4.3、
+ * 03 篇 §2.2 命令面、04 篇 §4 队列、04 篇 §9 审批归属）。
+ *
+ * 批 10a 落通道核（多会话信封分流 + 投影拉取注入 + 命令面 + ui 原语分发 +
+ * 提问队列——通道无关逻辑，零渲染依赖〔2026-09-06 改裁弃 pi-tui 后天然
+ * 满足——TUI 实装已落件内自研栈，批 10e〕）。
+ * 单向 DAG：channels → contracts, context, agent（02 §4.1——投影类型经装配侧
+ * 泛型钉入，不 import session）。
+ */
+export type { SessionEnvelope, NotifyLevel, UiAskOptions, UiSelectChoice, UiInputOptions, UiCapabilities, UiBackend, } from '../contracts/index.js';
+export type { ApprovalAskAnswer, ApprovalAskRequest } from '../contracts/index.js';
+/**
+ * todo 条目（07 §4.1 呈现面件 4——todoFor 注入载荷）：items 全量快照真源 =
+ * 05 §1.1 todo/write 事件载荷，本形是呈现投影（装配从 todo 状态映射注入；
+ * webui SPA 同源折叠产物）。
+ */
+export interface TodoItem {
+    /** 四态（呈现记号：☐ 待办 / ◐ 进行中 / ☑ 已完成·暗淡 / ⊙ 缓办·暗淡） */
+    readonly status: 'pending' | 'in-progress' | 'completed' | 'deferred';
+    /** 条目内容 */
+    readonly content: string;
+    /** 进行文案（进行中态优先于 content 呈现——CC 式 activeForm 语义） */
+    readonly activeForm?: string;
+}
+/** 命令参数（03 §2.2 签名定形：raw 原文引号原样 / argv 引号感知词切分） */
+export interface CommandArgs {
+    /** 命令名后的输入原文（引号形态原样保留） */
+    readonly raw: string;
+    /** 引号感知切分的词数组（单引号保字面、双引号保内部空格、裸词按空白切） */
+    readonly argv: readonly string[];
+    /**
+     * 发起会话 id（07 §4.3 消费腿条款档位 2 配套——交互动词族批 ix-2 新建）：
+     * 命令由会话输入框发起时通道核透传发起会话；CLI 面命令（无会话语境）
+     * 缺席——缺席即无锚语境，ctx.ui 阻塞三件须显式 opts.sessionId。
+     */
+    readonly sessionId?: string;
+}
+/** TUI 命令 handler 形（03 §2.2：void/Promise 双形） */
+export type CommandHandler = (args: CommandArgs) => void | Promise<void>;
+/** 命令注册条目（/help 与补全面消费——description 可选） */
+export interface CommandSpec {
+    readonly name: string;
+    readonly handler: CommandHandler;
+    readonly description?: string;
+}
+/** 提问队列项 kind（07 §4.3 提问队列：阻塞原语与审批 ask 统一入队） */
+export type AskKind = 'confirm' | 'select' | 'input' | 'approval';
+/**
+ * 通道核装配选项。投影拉取经注入回调（host 装配侧钉 session 面——channels
+ * 不依赖 session 是 02 §4.1 边表的刻意设计，投影类型 TProjection 由装配钉入）。
+ */
+export interface ChannelsOptions<TProjection> {
+    /**
+     * 投影拉取注入（焦点切换清屏重画的数据源——07 §4.1 通道契约）。
+     * 缺席时 focus 仍可切（焦点态生效）、repaint 以空投影收场——装配错误
+     * 呈现缺真源是核可观察态，不静默假装有历史。
+     */
+    readonly fetchProjection?: (sessionId: string) => Promise<readonly TProjection[]>;
+    /**
+     * 审批 always 的策略表回写注入（07 §4.3 提问队列条款 / 04 §9 ③ 既有
+     * 条款的通道侧接法）：用户答 `always` 且载荷带 suggestedEntry 草案 → 本
+     * 回调落跨会话策略表 allow 条目（用户显式按键后机器只执行写入——装配接
+     * safety 侧写入面）。无草案 always 不触发（零草案零副作用）。
+     */
+    readonly onApprovalAlways?: (entry: string) => void;
+    /**
+     * 历史正文拉取注入（07 §4.1 件 8 /history——批 10f-4 接线位）：与
+     * fetchProjection 同层同形（通道核只消费注入回调不依赖 session——边表
+     * 执法的刻意设计；真源接线归批 12 host 装配）。在场 = 通道核注册
+     * /history 命令（真源 = 聚焦会话 → 拉全量 durable 正文投影 → 扇出后端
+     * openHistory）；缺席 = 不注册不虚报（件 8 条款注册面律）。
+     */
+    readonly history?: (sessionId: string) => Promise<readonly TProjection[]>;
+    /**
+     * 记忆管理面注册位（06 §7 `/memory`——mm 批）：与 history 同层同律的
+     * 注入在场判（在场 = 通道核注册 /memory 命令；缺席 = 不注册不虚报）。
+     * true 形非回调——管理面数据不经通道核流转（后端装配自持材料，openMemory
+     * 零参形），通道核只做命令受理与扇出；扇出 falsy（后端不支持或缺材料）
+     * 时 notify 降级提示。装配真值 = 座位在位（persistence 在场 ⇒ memory 件
+     * 将装载；件缺席由降级提示诚实兜底）。
+     */
+    readonly memory?: true;
+}

package/dist/src/channels/types.js

@@ -0,0 +1,12 @@
+/**
+ * channels 件类型契约（L4 宿主固定件——02 篇席 10；机制真源 07 篇 §4.1/§4.3、
+ * 03 篇 §2.2 命令面、04 篇 §4 队列、04 篇 §9 审批归属）。
+ *
+ * 批 10a 落通道核（多会话信封分流 + 投影拉取注入 + 命令面 + ui 原语分发 +
+ * 提问队列——通道无关逻辑，零渲染依赖〔2026-09-06 改裁弃 pi-tui 后天然
+ * 满足——TUI 实装已落件内自研栈，批 10e〕）。
+ * 单向 DAG：channels → contracts, context, agent（02 §4.1——投影类型经装配侧
+ * 泛型钉入，不 import session）。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/channels/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/channels/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/src/channels/ui-core.d.ts

@@ -0,0 +1,80 @@
+/**
+ * ui 原语分发核（07 §4.3 签名定稿的通道无关编排面——2026-09-06 channels 纵切批）。
+ *
+ * 职责三块：①降级判定——通道不支持的原语按「notify 化」降级
+ * （select→input→notify、confirm→input→notify——插件不感知通道能力差异）；
+ * ②阻塞原语编排——入提问队列（与审批 ask 同队列）+ 多后端并发竞速
+ * （04 §9 跨入口先答先得，败腿经 signal 撤销）；③widget 会话级单槽
+ * （后写胜前写、置 null 清空——07 §4.3 setWidget 多写者语义）。
+ *
+ * 撤销面（07 §4.3）：外部 signal abort 或队列收口 → 保守值收场
+ * （confirm→false / select·input→''）——曾在屏者的撤销说明行归后端
+ * signal 消费实现，核只负责 abort 传播与结算。
+ *
+ * 核级 API 一律显式 sessionId（多会话归属的机器位）；ctx.ui 薄包装绑
+ * 「当前会话」归 host 装配批。后端移除（removeBackend）时在飞问询的收口
+ * 是后端自身义务（移除前 settle 或经 signal abort）——装配级事件，核不代管。
+ */
+import type { ApprovalAskAnswer, ApprovalAskRequest, AskKind, NotifyLevel, UiAskOptions, UiBackend, UiInputOptions, UiSelectChoice } from './types.js';
+import { AskQueue } from './ask-queue.js';
+export declare class UiCore {
+    private readonly backendsGetter;
+    private readonly askQueue;
+    /** 审批 always 的策略表回写注入（07 §4.3 提问队列条款——装配接线） */
+    private readonly onApprovalAlways;
+    /** widget 会话级单槽（07 §4.3——per-session 恰一槽，后写胜前写） */
+    private readonly widgets;
+    constructor(backendsGetter: () => readonly UiBackend<never>[], askQueue: AskQueue, onApprovalAlways?: (entry: string) => void);
+    private backends;
+    /** 能力过滤：声明且实现俱在才 capable（防后端声明能力而缺实现——防御位） */
+    private capable;
+    /** 一次性通知：扇出全部后端（level 档识别与 info 归一归后端呈现侧） */
+    notify(message: string, opts?: {
+        level?: NotifyLevel;
+    }): void;
+    /** 状态行更新：扇出 capable 后端（last-writer-wins 天然）；零 capable no-op */
+    setStatus(sessionId: string, status: string): void;
+    /** widget 单槽：后写胜前写、置 null 清空；扇出 capable 后端 */
+    setWidget(sessionId: string, node: unknown | null): void;
+    /** 当前槽值（repaint 载荷消费——焦点切换重画带上该会话槽） */
+    widgetOf(sessionId: string): {
+        node: unknown;
+    } | null;
+    /** 观众探针：任一后端自报有观众（TUI 恒真 / webui 在线连接数 > 0 / 零后端即假） */
+    hasAudience(): boolean;
+    /** 是/否确认（降级链：confirm 后端 → input 后端〔(y/n) 形〕→ notify 化 + 保守值 false） */
+    confirm(sessionId: string, message: string, opts?: UiAskOptions): Promise<boolean>;
+    /** 单选（降级链：select 后端 → input 后端〔编号列表形〕→ notify 化 + 保守值 ''） */
+    select(sessionId: string, message: string, choices: readonly UiSelectChoice[], opts?: UiAskOptions): Promise<string>;
+    /** 自由文本输入（降级链：input 后端 → notify 化 + 保守值 ''） */
+    input(sessionId: string, message: string, opts?: UiInputOptions): Promise<string>;
+    /**
+     * 审批 ask（07 §4.3 提问队列条款——与阻塞三件同队同收口律）：
+     * 多后端竞速先答先得（跨入口单漏斗——decide durable 单漏斗在
+     * ApprovalService 不变）；收口两语义分立（对齐 04 §9 run 信号透传
+     * ask 链）——会话关闭 / run 打断 → `'cancel'`（用户主动终止）；降级
+     * 到底（全部后端无 approval capability）→ `'unavailable'`（呈现面
+     * 结构性无人可答——ApprovalService 侧落 timeout 源；2026-09-13 真模型
+     * 实测批修，修前误答 'cancel' 错标用户主动取消）；`always` + 草案 →
+     * onApprovalAlways 回写；无草案 always 防御收口视同 approve（零草案
+     * 零副作用）。
+     */
+    askApproval(sessionId: string, request: ApprovalAskRequest, opts?: UiAskOptions): Promise<ApprovalAskAnswer>;
+    /** always 收口路：带草案回写策略表注入面；无草案防御视同 approve */
+    private settleApprovalAlways;
+    /**
+     * 会话收口（通道侧——unregisterSession 联动）：清提问队列（余项保守值）+
+     * 清 widget 槽。后端各自的会话呈现清理由其后端自身负责（onEnvelope 流断）。
+     */
+    closeSession(sessionId: string): void;
+    /** 提问队列观察面（透传——诊断面/测试消费） */
+    pending(sessionId: string): readonly AskKind[];
+    /**
+     * ask 统一编排：入队 → 队首呈现（多后端竞速先答先得）→ 落定出队。
+     * 入口先收副屏（07 §4.1 件 8 条款：注意力优先级 ask > 回看——ask 到来时
+     * 在场副屏先收起再入提问队列；能力缺席〔无副屏后端〕零义务跳过）。
+     * 三条收口路（全部 once）：首答（含降级解析值）/ 呈现异常（保守值——
+     * fail-closed）/ 外部 signal abort 或队列取消（保守值）。
+     */
+    private ask;
+}

package/dist/src/channels/ui-core.js

@@ -0,0 +1,210 @@
+/**
+ * ui 原语分发核（07 §4.3 签名定稿的通道无关编排面——2026-09-06 channels 纵切批）。
+ *
+ * 职责三块：①降级判定——通道不支持的原语按「notify 化」降级
+ * （select→input→notify、confirm→input→notify——插件不感知通道能力差异）；
+ * ②阻塞原语编排——入提问队列（与审批 ask 同队列）+ 多后端并发竞速
+ * （04 §9 跨入口先答先得，败腿经 signal 撤销）；③widget 会话级单槽
+ * （后写胜前写、置 null 清空——07 §4.3 setWidget 多写者语义）。
+ *
+ * 撤销面（07 §4.3）：外部 signal abort 或队列收口 → 保守值收场
+ * （confirm→false / select·input→''）——曾在屏者的撤销说明行归后端
+ * signal 消费实现，核只负责 abort 传播与结算。
+ *
+ * 核级 API 一律显式 sessionId（多会话归属的机器位）；ctx.ui 薄包装绑
+ * 「当前会话」归 host 装配批。后端移除（removeBackend）时在飞问询的收口
+ * 是后端自身义务（移除前 settle 或经 signal abort）——装配级事件，核不代管。
+ */
+import { AskQueue } from './ask-queue.js';
+export class UiCore {
+    backendsGetter;
+    askQueue;
+    /** 审批 always 的策略表回写注入（07 §4.3 提问队列条款——装配接线） */
+    onApprovalAlways;
+    /** widget 会话级单槽（07 §4.3——per-session 恰一槽，后写胜前写） */
+    widgets = new Map();
+    constructor(backendsGetter, askQueue, onApprovalAlways) {
+        this.backendsGetter = backendsGetter;
+        this.askQueue = askQueue;
+        this.onApprovalAlways = onApprovalAlways;
+    }
+    backends() {
+        return this.backendsGetter();
+    }
+    /** 能力过滤：声明且实现俱在才 capable（防后端声明能力而缺实现——防御位） */
+    capable(cap) {
+        // 能力键与方法名同名惯例的唯一例外：approval 位的方法面叫 askApproval
+        //（与服务面同名——UiBackend 上 confirm/select/input 三件方法名即能力名）
+        const method = cap === 'approval' ? 'askApproval' : cap;
+        return this.backends().filter((b) => b.capabilities[cap] === true && typeof b[method] === 'function');
+    }
+    // ---- 非阻塞三件（纯活体层——07 §4.3 语义纪律：不落日志不入队） ----
+    /** 一次性通知：扇出全部后端（level 档识别与 info 归一归后端呈现侧） */
+    notify(message, opts) {
+        for (const b of this.backends()) {
+            if (b.capabilities.notify)
+                b.notify(message, opts);
+        }
+    }
+    /** 状态行更新：扇出 capable 后端（last-writer-wins 天然）；零 capable no-op */
+    setStatus(sessionId, status) {
+        for (const b of this.capable('setStatus'))
+            b.setStatus?.(sessionId, status);
+    }
+    /** widget 单槽：后写胜前写、置 null 清空；扇出 capable 后端 */
+    setWidget(sessionId, node) {
+        if (node === null) {
+            this.widgets.delete(sessionId);
+        }
+        else {
+            this.widgets.set(sessionId, { node });
+        }
+        for (const b of this.capable('setWidget'))
+            b.setWidget?.(sessionId, node);
+    }
+    /** 当前槽值（repaint 载荷消费——焦点切换重画带上该会话槽） */
+    widgetOf(sessionId) {
+        return this.widgets.get(sessionId) ?? null;
+    }
+    /** 观众探针：任一后端自报有观众（TUI 恒真 / webui 在线连接数 > 0 / 零后端即假） */
+    hasAudience() {
+        return this.backends().some((b) => b.hasAudience());
+    }
+    // ---- 阻塞三件（入提问队列——与审批 ask 同队列 per-session FIFO） ----
+    /** 是/否确认（降级链：confirm 后端 → input 后端〔(y/n) 形〕→ notify 化 + 保守值 false） */
+    confirm(sessionId, message, opts) {
+        return this.ask(sessionId, 'confirm', opts?.signal, () => false, (signal) => {
+            const direct = this.capable('confirm');
+            if (direct.length > 0) {
+                return Promise.race(direct.map((b) => b.confirm(message, { signal })));
+            }
+            const viaInput = this.capable('input');
+            if (viaInput.length > 0) {
+                // confirm→input 降级（07 §4.3 降级路径同链透传）：(y/n) 形、答 y/yes 为真
+                const prompt = `${message} (y/n)`;
+                return Promise.race(viaInput.map((b) => b.input(prompt, { signal }))).then((answer) => /^y(es)?$/i.test(answer.trim()));
+            }
+            // notify 化到底：呈现问句后保守值收场（无人可答——fail-closed）
+            this.notify(message);
+            return Promise.resolve(false);
+        });
+    }
+    /** 单选（降级链：select 后端 → input 后端〔编号列表形〕→ notify 化 + 保守值 ''） */
+    select(sessionId, message, choices, opts) {
+        return this.ask(sessionId, 'select', opts?.signal, () => '', (signal) => {
+            const direct = this.capable('select');
+            if (direct.length > 0) {
+                return Promise.race(direct.map((b) => b.select(message, choices, { signal }))).then((answer) => validateChoice(answer, choices));
+            }
+            const viaInput = this.capable('input');
+            if (viaInput.length > 0) {
+                // select→input 降级（Web 通道维持同款——07 §4.3）：编号列表提示、手输 value
+                const prompt = `${message}\n${choices.map((c, i) => `${i + 1}. ${c.label} → ${c.value}`).join('\n')}`;
+                return Promise.race(viaInput.map((b) => b.input(prompt, { signal }))).then((answer) => validateChoice(answer, choices));
+            }
+            this.notify(`${message}\n${choices.map((c) => `- ${c.label} → ${c.value}`).join('\n')}`);
+            return Promise.resolve('');
+        });
+    }
+    /** 自由文本输入（降级链：input 后端 → notify 化 + 保守值 ''） */
+    input(sessionId, message, opts) {
+        return this.ask(sessionId, 'input', opts?.signal, () => '', (signal) => {
+            const viaInput = this.capable('input');
+            if (viaInput.length > 0) {
+                return Promise.race(viaInput.map((b) => b.input(message, { placeholder: opts?.placeholder, signal })));
+            }
+            this.notify(message);
+            return Promise.resolve('');
+        });
+    }
+    /**
+     * 审批 ask（07 §4.3 提问队列条款——与阻塞三件同队同收口律）：
+     * 多后端竞速先答先得（跨入口单漏斗——decide durable 单漏斗在
+     * ApprovalService 不变）；收口两语义分立（对齐 04 §9 run 信号透传
+     * ask 链）——会话关闭 / run 打断 → `'cancel'`（用户主动终止）；降级
+     * 到底（全部后端无 approval capability）→ `'unavailable'`（呈现面
+     * 结构性无人可答——ApprovalService 侧落 timeout 源；2026-09-13 真模型
+     * 实测批修，修前误答 'cancel' 错标用户主动取消）；`always` + 草案 →
+     * onApprovalAlways 回写；无草案 always 防御收口视同 approve（零草案
+     * 零副作用）。
+     */
+    askApproval(sessionId, request, opts) {
+        return this.ask(sessionId, 'approval', opts?.signal, () => 'cancel', (signal) => {
+            const direct = this.capable('approval');
+            if (direct.length > 0) {
+                return Promise.race(direct.map((b) => b.askApproval(sessionId, request, { signal }))).then((answer) => this.settleApprovalAlways(answer, request));
+            }
+            // notify 化到底：呈现摘要后自报结构性无人（fail-closed——04 §9 无应答
+            // 者语义，ApprovalService 落 unavailable/timeout；与打断路保守值 'cancel'
+            // 分立——修前误答 'cancel' 致 decided 错标 cancel/user 双失真）
+            this.notify(request.summary);
+            return Promise.resolve('unavailable');
+        });
+    }
+    /** always 收口路：带草案回写策略表注入面；无草案防御视同 approve */
+    settleApprovalAlways(answer, request) {
+        if (answer !== 'always')
+            return answer;
+        if (request.suggestedEntry === undefined)
+            return 'approve'; // 零草案零副作用（04 §9 ③）
+        this.onApprovalAlways?.(request.suggestedEntry);
+        return 'always';
+    }
+    // ---- 收口 ----
+    /**
+     * 会话收口（通道侧——unregisterSession 联动）：清提问队列（余项保守值）+
+     * 清 widget 槽。后端各自的会话呈现清理由其后端自身负责（onEnvelope 流断）。
+     */
+    closeSession(sessionId) {
+        this.askQueue.clearSession(sessionId);
+        this.widgets.delete(sessionId);
+    }
+    /** 提问队列观察面（透传——诊断面/测试消费） */
+    pending(sessionId) {
+        return this.askQueue.pending(sessionId);
+    }
+    // ---- 编舞内核 ----
+    /**
+     * ask 统一编排：入队 → 队首呈现（多后端竞速先答先得）→ 落定出队。
+     * 入口先收副屏（07 §4.1 件 8 条款：注意力优先级 ask > 回看——ask 到来时
+     * 在场副屏先收起再入提问队列；能力缺席〔无副屏后端〕零义务跳过）。
+     * 三条收口路（全部 once）：首答（含降级解析值）/ 呈现异常（保守值——
+     * fail-closed）/ 外部 signal abort 或队列取消（保守值）。
+     */
+    ask(sessionId, kind, externalSignal, conservative, present) {
+        // ask 强制收起（件 8 条款——批 10f-4）：扇出可选钩，先于入队
+        for (const b of this.backends())
+            b.collapseAltScreen?.();
+        let resolve;
+        const promise = new Promise((r) => {
+            resolve = r;
+        });
+        let done = false;
+        // 内部 signal：败腿撤销 + 队列收口的统一传播位（后端只认这一个信号源——
+        // 外部 signal 经本核折入 finish，不直传后端）
+        const controller = new AbortController();
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            controller.abort(); // 败腿撤销传播（已落定后端再收 abort 是无害 no-op）
+            resolve(value);
+            this.askQueue.settled(sessionId);
+        };
+        const externalAbort = () => finish(conservative());
+        externalSignal?.addEventListener('abort', externalAbort, { once: true });
+        this.askQueue.enqueue(sessionId, kind, {
+            start: () => {
+                present(controller.signal).then(finish, () => finish(conservative()));
+            },
+            cancel: () => finish(conservative()),
+        });
+        return promise;
+    }
+}
+/** select 降级答案校验：手输不在 value 集即保守值 ''（fail-closed——不猜最近匹配） */
+function validateChoice(answer, choices) {
+    const trimmed = answer.trim();
+    return choices.some((c) => c.value === trimmed) ? trimmed : '';
+}
+//# sourceMappingURL=ui-core.js.map

package/dist/src/channels/ui-core.js.map

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

package/dist/src/context/codes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/context/codes.js

@@ -0,0 +1,41 @@
+/**
+ * context 模块错误码注册（02 §5.3 #2：各模块落码批经 registerErrorCodes 显式注册，
+ * 禁字符串字面量散落）。
+ *
+ * 域码族注记：EVENT_* / SCOPE_* 系 04 §6 定名的域语义命名（事件面/作用域面），
+ * 视同 CONTEXT_ 域族成员（02 §5.3 前缀族注记，2026-09-05 落码批）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'EVENT_NOT_REGISTERED',
+        module: 'context',
+        description: 'ctx.emit/on 未注册词 fail-loud（词汇注册表单源——禁散播未声明事件名）',
+    },
+    {
+        code: 'EVENT_DUPLICATE',
+        module: 'context',
+        description: '事件词汇撞名拒静默覆盖（注册表单源执法）',
+    },
+    {
+        code: 'SCOPE_STALE',
+        module: 'context',
+        description: '作用域已回卷后的迟到操作（迟到的服务注册/disposer 登记拒绝——异步竞速收口）',
+    },
+    {
+        code: 'SCOPE_EFFECT_CAPACITY',
+        module: 'context',
+        description: 'effect 总注册帽：本作用域自有登记达 10^4 拒新登记（03 §3.4 可用性防线——失控登记不拖垮回卷序；拒在 register 回调执行前）',
+    },
+    {
+        code: 'CONTEXT_SERVICE_MISSING',
+        module: 'context',
+        description: 'get 缺席 fail-loud（拼错名立即炸，不静默 undefined 传播；可选消费走 tryGet）',
+    },
+    {
+        code: 'CONTEXT_SERVICE_DUPLICATE',
+        module: 'context',
+        description: '同作用域 provide 撞名拒（两方抢一名即装配 bug；fork 子遮蔽父合法）',
+    },
+]);
+//# sourceMappingURL=codes.js.map

package/dist/src/context/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../../../src/context/codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,kBAAkB,CAAC;IACjB;QACE,IAAI,EAAE,sBAAsB;QAC5B,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,gDAAgD;KAC9D;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,sBAAsB;KACpC;IACD;QACE,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,6CAA6C;KAC3D;IACD;QACE,IAAI,EAAE,uBAAuB;QAC7B,MAAM,EAAE,SAAS;QACjB,WAAW,EACT,8EAA8E;KACjF;IACD;QACE,IAAI,EAAE,yBAAyB;QAC/B,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,wDAAwD;KACtE;IACD;QACE,IAAI,EAAE,2BAA2B;QACjC,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,4CAA4C;KAC1D;CACF,CAAC,CAAC"}

package/dist/src/context/events.d.ts

@@ -0,0 +1,62 @@
+/**
+ * emit / serial / parallel 的监听器形态（通知型——返回值不被广播语义消费）。
+ * 返回面 unknown 而非 void：unknown 是 top type 吸收一切同步/异步返回
+ * （parallel 复用本面收口时恰需读返回值；void 的「调用方不读」语义反而失真）。
+ */
+export type NotifyListener<T> = (data: T) => unknown;
+/** waterfall 的监听器形态：必须调 next 委托（不调即短路） */
+export type WaterfallListener<T> = (value: T, next: (value: T) => Promise<T>) => Promise<T> | T;
+/** 监听器异常上报面（emit/serial 的隔离腿去向；host 装配时接 logger） */
+export type ListenerErrorReporter = (eventName: string, err: unknown) => void;
+/**
+ * 事件分派器：词汇注册表 + 四模式派发。一个 ctx 一枚（装载运行时的通信契约
+ * 单源——双实现 = 通信割裂）。
+ */
+export declare class EventDispatch {
+    /** 词汇注册表（name → 已注册标记；单源执法面） */
+    private readonly registered;
+    /** 监听器表（name → 注册序监听器列表；on 返回退订闭包；泛型在存储侧擦除为 unknown、取回侧 cast 还原） */
+    private readonly listeners;
+    /** serial 排队尾（per-name 链式 promise——排队串行） */
+    private readonly serialQueues;
+    /** 隔离腿异常上报（缺省 stderr 直写；装配根接 logger） */
+    private readonly onListenerError;
+    constructor(options?: {
+        onListenerError?: ListenerErrorReporter;
+    });
+    /** 注册事件词汇（装载期声明面）；撞名拒 EVENT_DUPLICATE（禁静默覆盖） */
+    registerEventNames(names: readonly string[]): void;
+    /** 判别词汇是否已注册（装配断言/诊断面） */
+    isRegistered(name: string): boolean;
+    /**
+     * 挂通知型监听器（emit/serial 共用监听面——同词两模式收同一监听器形态）。
+     * 词未注册拒 EVENT_NOT_REGISTERED（fail-loud 禁散播未声明事件名）。
+     * @returns 退订闭包（消费方经 scope.effect 组合生命周期）
+     */
+    on(name: string, listener: NotifyListener<unknown>): () => void;
+    /**
+     * 广播：全部监听器并发各跑各，异常互相隔离（单腿炸不波及他腿与调用方——
+     * 上报 onListenerError 后照常收口）。
+     */
+    emit(name: string, data?: unknown): Promise<void>;
+    /**
+     * 串行管线：监听器必须调 next(value) 委托——不调即短路（管线后段不再执行，
+     * 返回值为该监听器的产出）；异常沿链传播（管线失败语义——守门行依赖）。
+     */
+    waterfall<T>(name: string, value: T): Promise<T>;
+    /** 挂管线监听器（waterfall 专用面——与 on 分开：形态不同防误用） */
+    onWaterfall<T>(name: string, listener: WaterfallListener<T>): () => void;
+    /**
+     * 全体并发，Promise.all 收口（异常传播——与 emit 的区别即异常语义）。
+     * 监听器面与 on 共用（通知型返回值参与收口）。
+     */
+    parallel<T, R>(name: string, data: T): Promise<R[]>;
+    /**
+     * 排队串行：逐监听器顺序执行（后段等前段完成）；不短路——异常隔离上报后
+     * 继续下一段（与 waterfall 的区别 = 无委托链、异常不停段）。
+     * 同词多次派发按到达序排队（per-name 链式 promise）。
+     */
+    serial(name: string, data?: unknown): Promise<void>;
+    /** 未注册词执法（emit/on/waterfall/parallel/serial 共用） */
+    private assertRegistered;
+}