berry-agent 0.1.0-alpha.1

package/dist/channels/engine/process-io.js

@@ -0,0 +1,38 @@
+/** process stdin/stdout 直连适配器（组合根缺省注入位） */
+export class ProcessTerminalIO {
+    write(data) {
+        process.stdout.write(data);
+    }
+    size() {
+        // 兜底用 || 而非 ??：pty 未设 winsize 时（expect/CI 伪终端）node 返回
+        // rows/columns = 0 而非 undefined——`??` 只兜 null/undefined 兜不住 0；
+        // 0 行 0 列的终端物理不存在，零值与缺席同属「无有效几何」，一律回落
+        // 80×24（2026-09-13 真模型五轮实测定罪：0 值直透曾致 CellGrid 零宽
+        // 只擦不写 + 负行号 CUP——固定区渲染全空）。
+        return { columns: process.stdout.columns || 80, rows: process.stdout.rows || 24 };
+    }
+    setRawMode(enable) {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode(enable);
+    }
+    isRaw() {
+        return process.stdin.isRaw ?? false;
+    }
+    pause() {
+        process.stdin.pause();
+    }
+    resume() {
+        process.stdin.resume();
+    }
+    onInput(listener) {
+        const stdin = process.stdin;
+        stdin.setEncoding('utf8');
+        stdin.on('data', listener);
+        return () => stdin.removeListener('data', listener);
+    }
+    onResize(listener) {
+        const stdout = process.stdout;
+        stdout.on('resize', listener);
+        return () => stdout.removeListener('resize', listener);
+    }
+}

package/dist/channels/engine/types.js

@@ -0,0 +1,17 @@
+/**
+ * 自研 TUI 引擎契约件（07 篇 §4.1 自研引擎节件 1——批 10b 引擎核心）。
+ *
+ * 引擎与真 TTY 全解耦的接缝根基：TerminalIO 是注入面（按引擎生命周期需要
+ * 设计接口面，非照抄进程 API）、MemoryTerminalIO 内存实现是引擎公开测试面
+ * （结构性义务非可选件——「mock 只停在模型层」纪律的接缝根基）。
+ *
+ * 本文件只立契约（类型 + 协议），零实现、零外部依赖；实现可替换性由接口
+ * 面承载（CellBuffer 协议下实装在 cell 件、TerminalIO 下真终端适配在批 10c）。
+ */
+/** 16 色色号构造（brand 收口：色号只能经此进入引擎面） */
+export function ansiColor(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 15) {
+        throw new Error(`ansiColor: 色号须为 0-15 整数，收到 ${n}`);
+    }
+    return n;
+}

package/dist/channels/engine/width.js

@@ -0,0 +1,122 @@
+/**
+ * 文本度量件（07 篇 §4.1 自研引擎节件 2——批 10b 引擎核心）。
+ *
+ * 字素边界与列宽两件必须同时在场（立法缘由：berry 注释点名 OpenCode 反课
+ * 「只用字素切分不管列宽 → CJK 断行错位至今未修」）——
+ * - 字素边界：运行时内建 Intl.Segmenter（零新依赖，模块级单例）；
+ * - 列宽：EAW 分类**数据面**外包 get-east-asian-width（§2.1 精确锁 1.6.0），
+ *   `ambiguous = 1` 的中西混排语境取舍**决策面自持**在本件（见 eawWidth 注释）。
+ */
+import { eastAsianWidthType } from 'get-east-asian-width';
+/** 字素切分器（模块级单例——Segmenter 构造贵、无状态可复用） */
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+/** 变体选择子 16（emoji 呈现形——字素含之即宽 2） */
+const VS16 = 0xfe0f;
+/** Regional Indicator 起止（旗帜 = 恰一对 RI 合成一字素） */
+const RI_FIRST = 0x1f1e6;
+const RI_LAST = 0x1f1ff;
+/**
+ * EAW 单码点分类宽（决策面自持位）。
+ *
+ * ambiguous（A 类：〇 ⊡ ⛭ …）在 CJK 语境常按 2 列渲染、西文语境按 1 列——
+ * 本仓取舍 **= 1**（中西混排对话正文按窄计），依据 = berry 实证同款取舍；
+ * 部分按 2 渲染的 CJK 终端上对齐误差可容忍，可配置性挂真实需求再裁
+ * （07 §4.1 终端支持矩阵降级三款注记在案）。
+ * 注：外包库的 eastAsianWidth() 缺省 ambiguousAsWide = true——与本取舍相反，
+ * 故只取其分类函数、宽度判定自持，不走其合成宽函数。
+ */
+function eawWidth(codePoint) {
+    const type = eastAsianWidthType(codePoint);
+    return type === 'wide' || type === 'fullwidth' ? 2 : 1;
+}
+/**
+ * 字素级宽度四规则（07 引擎节件 2）：
+ * ① 字素内任一码点 EAW wide/fullwidth → 2；
+ * ② 含 VS16 → 2（emoji 呈现形——窄基字符 + VS16 也占双列）；
+ * ③ 恰一对 Regional Indicator → 2（旗帜——单码点 EAW 覆盖不到，孤立 RI 按 1）；
+ * ④ 其余 → 1。
+ */
+export function graphemeWidth(grapheme) {
+    const codePoints = [...grapheme].map((ch) => ch.codePointAt(0));
+    // 规则③：恰一对 RI（两面旗恰好两个 RI 码点合成）判 2；单 RI / 三连 RI 落规则④
+    const riCount = codePoints.filter((cp) => cp >= RI_FIRST && cp <= RI_LAST).length;
+    if (codePoints.length === 2 && riCount === 2)
+        return 2;
+    // 规则②：VS16 在场即宽（emoji 呈现形语义优先于基字符分类）
+    if (codePoints.includes(VS16))
+        return 2;
+    // 规则①：任一码点 wide/fullwidth → 2
+    for (const cp of codePoints) {
+        if (eawWidth(cp) === 2)
+            return 2;
+    }
+    // 规则④：其余 → 1（含控制字符的占位语义不在此件发明——网格写入层拒收）
+    return 1;
+}
+/** 切分字素序列（Intl.Segmenter——ZWJ 家族 / 旗帜 / 变体选择子整素不撕裂） */
+export function splitGraphemes(text) {
+    if (text === '')
+        return [];
+    const out = [];
+    for (const seg of segmenter.segment(text))
+        out.push(seg.segment);
+    return out;
+}
+/** 整字三原语之一·测宽：全串字素宽度和 */
+export function stringWidth(text) {
+    let width = 0;
+    for (const g of splitGraphemes(text))
+        width += graphemeWidth(g);
+    return width;
+}
+/**
+ * 整字三原语之二·按宽截断：截到不超过 cols 的最长字素前缀——
+ * 宽字素跨界整字丢弃**不产半字**（末位恰剩一列放不下双宽字素时整字放弃）。
+ */
+export function truncateToWidth(text, cols) {
+    if (cols <= 0)
+        return '';
+    let used = 0;
+    let out = '';
+    for (const g of splitGraphemes(text)) {
+        const w = graphemeWidth(g);
+        if (used + w > cols)
+            break; // 剩余列宽不足整字——整字丢弃（不产半字）
+        used += w;
+        out += g;
+    }
+    return out;
+}
+/**
+ * 整字三原语之三·整字换行：按 cols 折行——
+ * 行末剩一列遇双宽字素整字下移**第二列不悬挂**；ZWJ 家族**跨行不撕裂**
+ * （字素切分在前、折行只动字素边界）；显式 \n 强制换行（段语义保留）。
+ */
+export function wrapText(text, cols) {
+    if (cols <= 0)
+        return [text]; // 非法宽防御：不折行整段返回（坏参不丢字）
+    const lines = [];
+    // 先按显式换行分段（空段保留——空行语义），段内再按宽折行
+    for (const paragraph of text.split('\n')) {
+        if (paragraph === '') {
+            lines.push('');
+            continue;
+        }
+        let current = '';
+        let used = 0;
+        for (const g of splitGraphemes(paragraph)) {
+            const w = graphemeWidth(g);
+            if (used + w > cols) {
+                lines.push(current); // 当前行满——整字下移开新行（双宽字不悬挂第二列）
+                current = g;
+                used = w;
+            }
+            else {
+                current += g;
+                used += w;
+            }
+        }
+        lines.push(current); // 段尾行（含整段未折情形）
+    }
+    return lines;
+}

package/dist/channels/index.js

@@ -0,0 +1,15 @@
+export { CommandRegistry, tokenize } from './commands.js';
+export { AskQueue } from './ask-queue.js';
+export { UiCore } from './ui-core.js';
+export { SessionChannels } from './registry.js';
+export { createChannels } from './service.js';
+export { TuiBackend } from './tui/index.js';
+// 真终端适配器 + 补全源族（批 12e host 装配消费——engine/·tui/ 组件族非公开
+// 面纪律的件外出口位：「本面随真实件外消费扩」先例；余组件仍件内消费）
+export { ProcessTerminalIO } from './engine/index.js';
+export { FileMentionSource } from './tui/index.js';
+// SDK 线协议（批 13a 契约先行——03 §10.6 件身份条：协议核心代码位与 channels
+// 通道核同体，SDK 通道后端 = UiBackend 第三后端；本面出协议词汇/信封 + NDJSON
+// 编解码 + admit/游标纯逻辑四件。后端实装（事件外推/请求受理/出站队列）随批
+// 13b；stdio 传输归宿主 serve、HTTP+SSE/MCP 归 core:sdk 件〔src/sdk/ 13e〕）
+export * from './sdk/index.js';

package/dist/channels/registry.js

@@ -0,0 +1,56 @@
+/**
+ * 多会话注册表与焦点编排（07 §4.1 通道契约——2026-09-06 channels 纵切批）。
+ *
+ * 职责：会话在场集合 + 焦点位（聚焦者全渲染/非聚焦摘要行的判定源）+
+ * 焦点切换清屏重画（拉投影 → repaint 回调——投影拉取经装配注入，
+ * channels 不 import session 是 02 §4.1 边表的刻意设计）。
+ *
+ * 焦点切换不自动回退：聚焦会话注销后焦点空悬（focused=null——非聚焦态
+ * 全体），下一焦点由用户动作显式给（切焦编舞归 TUI 呈现批）。
+ */
+export class SessionChannels {
+    fetchProjection;
+    repaint;
+    sessions = new Set();
+    currentFocus = null;
+    constructor(fetchProjection, repaint) {
+        this.fetchProjection = fetchProjection;
+        this.repaint = repaint;
+    }
+    /** 会话入场（幂等；焦点不自动变更——显式 focus 才切） */
+    registerSession(sessionId) {
+        this.sessions.add(sessionId);
+    }
+    /** 会话退场：在场集移除；若正是聚焦者 → 焦点空悬（不自动接续） */
+    unregisterSession(sessionId) {
+        this.sessions.delete(sessionId);
+        if (this.currentFocus === sessionId)
+            this.currentFocus = null;
+    }
+    /** 当前聚焦会话（null = 焦点空悬——全体非聚焦态） */
+    get focusedId() {
+        return this.currentFocus;
+    }
+    isFocused(sessionId) {
+        return this.currentFocus === sessionId;
+    }
+    /** 在场判定（emit 路由前置——不在场会话的信封仍可分流，呈现裁剪归后端） */
+    has(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /**
+     * 焦点切换（07 §4.1：清屏重画）：置位 → 拉投影 → repaint。
+     * 投影拉取缺席 → 空投影重画（诚实缺席：装配缺真源是可观察态，不静默假装
+     * 有历史）；拉取异常向上抛（fail-loud——投影真源故障不降级为「无历史」谎言）。
+     * 未注册会话 focus 视同注册（焦点即活跃声明——幂等）。
+     */
+    async focus(sessionId) {
+        this.registerSession(sessionId);
+        this.currentFocus = sessionId;
+        const projection = await (this.fetchProjection?.(sessionId) ?? []);
+        // 焦点可能在拉投影期间被再切（快速切焦）——只为本焦点落画（迟到的旧画弃）
+        if (this.currentFocus === sessionId) {
+            this.repaint(sessionId, projection);
+        }
+    }
+}

package/dist/channels/sdk/admit.js

@@ -0,0 +1,29 @@
+/**
+ * 幂等 admit 判定纯函数（03 篇 §10.6 线协议七原则④ + 05 篇 §3.5 第二腿——
+ * durable 承载条）。
+ *
+ * **两词一字段两面**（05 §3.5）：线面 `messageId`（03 §10.6 请求面动词族条）
+ * 受理时即落账为 durable `data.dedupeKey`——单键直写、无映射表、无变换。
+ * 本函数以 messageId 为键直查既存表（键域同一），语义真源在规范、查重实现
+ * （日志扫描 / 投影侧索引）随受理实装（批 13b）定形。
+ *
+ * 语义三档：fresh（无同键——受理新跑）/ duplicate（同键同内容——幂等重收执，
+ * 回执即既存事件本身、经 after 重放可取、不重跑）/ conflict（同键异内容——
+ * `SDK_MESSAGE_CONFLICT`，误判超时重发零副作用的反面执法位）。跨重启幂等
+ * 天然成立（durable 即真相——无第二套 admit 存储表）。
+ */
+/**
+ * 判定一条 prompt 的受理档。
+ *
+ * @param known 既存 dedupeKey → 内容 映射（受理侧维护；跨重启语义由 durable
+ *   落账兑现——本函数纯逻辑不触存储）
+ * @param messageId 调用方自选幂等键（受理时即落账为 data.dedupeKey——两词一字段两面）
+ * @param content 消息内容（同键异内容的比对基准——字符串全等，无归一化）
+ */
+export function admitMessage(known, messageId, content) {
+    const existing = known.get(messageId);
+    if (existing === undefined)
+        return { status: 'fresh' };
+    // 同键：内容全等分档——异内容即冲突（fail-loud 不静默覆盖）
+    return existing === content ? { status: 'duplicate' } : { status: 'conflict', code: 'SDK_MESSAGE_CONFLICT' };
+}

package/dist/channels/sdk/backend.js

@@ -0,0 +1,102 @@
+import { SdkWireCore } from './wire-core.js';
+/**
+ * 造 SDK 通道后端（每连接一枚——core 即该连接的单连接状态机）。
+ *
+ * @param deps 装配桥注入面（decideApproval/onSubscribed 两面由本件自持——
+ *   幂等账与重推编舞是后端语义不是桥语义）
+ * @param options 线核构造选项（时钟/节拍/背压参——透传）
+ */
+export function createSdkBackend(deps, options) {
+    /** 未决 ask 账（approvalId → 账项——decide 幂等判据 + 重推面） */
+    const pending = new Map();
+    /** 后端内 ask 计数（调用方未指派 approvalId 时生成 `sdk-N`——连接内唯一） */
+    let askSeq = 0;
+    const core = new SdkWireCore({
+        ...deps,
+        // decide 应答：未决账项在册且未决 → 落定回执 applied；unknown/已决 →
+        // superseded（跨入口竞速败者——03 §10.6 第三腿幂等语义）
+        decideApproval: (approvalId, answer) => {
+            const entry = pending.get(approvalId);
+            if (entry === undefined || entry.settled)
+                return 'superseded';
+            entry.settled = true;
+            pending.delete(approvalId);
+            entry.resolve(answer);
+            return 'applied';
+        },
+        // 订阅受理钩：该会话未决 ask 全量重推（重连后凭 hello 重收 ask 面；
+        // 已决者早已出账——重推面天然只含未决）
+        onSubscribed: (sessionId) => {
+            for (const entry of pending.values()) {
+                if (entry.frame.sessionId === sessionId)
+                    core.pushFrame(entry.frame, sessionId);
+            }
+        },
+    }, options);
+    const backend = {
+        id: 'sdk',
+        // 唯 approval 一位（文件头能力面注）——其余 false 使核降级判定不路由本后端
+        capabilities: {
+            notify: false,
+            confirm: false,
+            select: false,
+            input: false,
+            approval: true,
+            setStatus: false,
+            setWidget: false,
+        },
+        // 观众探针：活跃订阅数（零订阅 = 无人接帧 = 无观众）
+        hasAudience: () => core.subscriptionCount > 0,
+        // 能力位 false——核不扇出本后端（方法在场纯为接口完备）
+        notify: () => { },
+        // 活体信封直推直播腿（focused 无 SDK 语义——订阅即全量，无聚焦降档）
+        onEnvelope: (env) => core.pushEvent(env.sessionId, env.event),
+        askApproval: (sessionId, request, opts) => new Promise((resolve) => {
+            // fail-closed：该会话无订阅者即结构性无人可答——立即 unavailable
+            //（帧不出站；04 §9 无应答者语义，非用户主动取消——与 abort 路分立）
+            if (!core.isSubscribed(sessionId)) {
+                resolve('unavailable');
+                return;
+            }
+            const approvalId = request.approvalId ?? `sdk-${++askSeq}`;
+            const frame = {
+                kind: 'ask',
+                sessionId,
+                approvalId,
+                summary: request.summary,
+                ...(request.reason !== undefined ? { reason: request.reason } : {}),
+                ...(request.toolName !== undefined ? { toolName: request.toolName } : {}),
+                ...(request.suggestedEntry !== undefined ? { suggestedEntry: request.suggestedEntry } : {}),
+            };
+            const entry = { frame, settled: false, resolve };
+            pending.set(approvalId, entry);
+            core.pushFrame(frame, sessionId);
+            // 败腿撤销（UiCore 竞速先答后 abort 传播位）：保守值 cancel（04 §9
+            // run 信号透传——用户主动打断语义，不落 unavailable）+ 出账（迟到
+            // decide 归 superseded）；已决后迟到 abort 是无害 no-op
+            opts?.signal?.addEventListener('abort', () => {
+                if (entry.settled)
+                    return;
+                entry.settled = true;
+                pending.delete(approvalId);
+                resolve('cancel');
+            }, { once: true });
+        }),
+    };
+    return {
+        backend,
+        core,
+        dispose: () => {
+            // 连接收口：在飞 ask 按通道消失语义收场（unavailable——连接断了无观众
+            // 可答，ApprovalService 落 timeout 源；用户主动打断走 abort 路 cancel）
+            for (const entry of pending.values()) {
+                if (entry.settled)
+                    continue;
+                entry.settled = true;
+                entry.resolve('unavailable');
+            }
+            pending.clear();
+            core.close();
+        },
+    };
+}

package/dist/channels/sdk/cursor.js

@@ -0,0 +1,56 @@
+/**
+ * after 游标对账纯函数（03 篇 §10.6 线协议七原则③ + 05 篇 §3.5 第一腿——
+ * durable seq + after 游标 / 崩溃重连对账 / 重放-直播衔接序）。
+ *
+ * 高水位约定（与 ./protocol.ts 文件头单源同律）：**highWaterSeq = 会话日志当前
+ * 长度**（= 下一将分配 seq；既存末条 seq = highWaterSeq − 1；空会话 = 0）。
+ *
+ * 两执法句在该约定下的形态：
+ * - 调用方已收末 seq ≥ 高水位 ⇒ 尾被截（撕裂尾截断后 seq 按 log.length 重编
+ *   **复用**——调用方已收的尾段 seq 在恢复后日志中不存在或被同号异容复用）；
+ * - `after=N` ≥ 高水位 ⇒ 游标非法（N 越过既存末条 = 声称已收不存在的事件；
+ *   含空会话 after=0 档——新会话订阅应缺席 after）。
+ * 两档同码 `SDK_CURSOR_INVALID`，调用方从头（或 getEntries）重对账——消费侧
+ * 幂等以 dedupeKey 兜底，at-least-once 边界如实。
+ */
+/**
+ * 校验订阅/重放游标 after 的合法性（hello.after 与 getEntries.since 同语义）。
+ *
+ * 合法 ⇔ after < highWaterSeq（重放窗口 = (after, highWaterSeq]；after 恰为
+ * 既存末条 seq = 完全追平档——窗口空、直接进直播，亦合法）。
+ */
+export function validateAfterCursor(after, highWaterSeq) {
+    if (after >= highWaterSeq) {
+        return { ok: false, code: 'SDK_CURSOR_INVALID', reason: 'beyond-high-water' };
+    }
+    return { ok: true };
+}
+/**
+ * 崩溃重连尾截断侦测（05 §3.5 崩溃重连对账条——hello/ack 携高水位的消费侧）。
+ *
+ * @param lastReceivedSeq 调用方已收末条 seq（无对账面〔首连〕传 undefined——恒 ok）
+ * @param highWaterSeq 服务端 hello/ack 携带的会话当前高水位
+ * @returns 已收末 seq ≥ 高水位 ⇒ 尾被截（含 ==：声称知道下一将分配 seq 同为
+ *   幻影——撕裂截断后 seq 复用使等值也歧义，保守同码）
+ */
+export function detectTailTruncation(lastReceivedSeq, highWaterSeq) {
+    if (lastReceivedSeq === undefined)
+        return { ok: true };
+    if (lastReceivedSeq >= highWaterSeq) {
+        return { ok: false, code: 'SDK_CURSOR_INVALID', reason: 'tail-truncated' };
+    }
+    return { ok: true };
+}
+/**
+ * 重放-直播衔接序定位（05 §3.5 衔接序第 ③ 步——**落码回归锁位**函数化）：
+ * 直播起播 = 内存日志中 seq > 重放尾（lastReplayedSeq）的首条（含未落库在飞
+ * 事件）。重放尾与直播首无缝衔接 = 衔接完整性验收位，测试在册。
+ *
+ * @param log 会话内存日志（seq 单调连续升序——05 §1.1 写入序不变式）
+ * @param lastReplayedSeq 重放段末条 seq（空重放 = after 原值或 −1）
+ * @returns 直播起播下标（log.length = 重放已覆盖全部内存日志——直播等新事件）
+ */
+export function resolveLiveStart(log, lastReplayedSeq) {
+    const index = log.findIndex((entry) => entry.seq > lastReplayedSeq);
+    return index === -1 ? log.length : index;
+}

package/dist/channels/sdk/index.js

@@ -0,0 +1,20 @@
+/**
+ * SDK 通道后端件内聚合面（channels 通道核第三后端——03 篇 §10.6 件身份条：
+ * 协议核心代码位与 channels 通道核同体，UiBackend 多后端接口位既有）。
+ *
+ * 批 13a 契约先行笔 = 协议词汇/信封 + NDJSON 编解码 + admit/游标纯逻辑；
+ * 批 13b = 线协议核心（wire-core 单连接状态机：六动词受理/活体外推/心跳
+ * 装配面/出站有界队列背压）+ 后端实装（13b-3）。stdio 传输归宿主 serve
+ * （07 §5）；HTTP+SSE 与 MCP 包装归 core:sdk 件（src/sdk/ 批 13e）。
+ *
+ * SDK_ 五码注册在 contracts 错误码注册表 CORE_ERROR_CODES（规范定名码直入
+ * contracts 的仓内先例——CHANNEL_/AGENT_ 同款；注册笔系并行会话〔批 12 泳道〕
+ * 先行落、本批收编，勿在本件重复注册）。
+ */
+export * from './protocol.js';
+export * from './jsonl.js';
+export * from './admit.js';
+export * from './cursor.js';
+export * from './schema.js';
+export * from './wire-core.js';
+export * from './backend.js';

package/dist/channels/sdk/jsonl.js

@@ -0,0 +1,208 @@
+import { SDK_FRAME_KINDS, SDK_REQUEST_VERBS } from './protocol.js';
+import { validateSdkRequest } from './schema.js';
+/** 行终止符两位（编码转义对象——显式转义写法防字面量在编辑/传输中丢失） */
+const LS = '\u2028';
+const PS = '\u2029';
+/** 判别字段的受控名（请求 `verb` / 线帧 `kind`） */
+const FRAME_KIND_SET = new Set(SDK_FRAME_KINDS);
+const REQUEST_VERB_SET = new Set(SDK_REQUEST_VERBS);
+/** decide.answer 四值闭集（contracts ApprovalAskAnswer 减 'unavailable'——结构性
+ * 自报值非通道答案，SDK 通道面不受理；2026-09-13 复盘发现 #28：修前注称「同集」
+ * 在 unavailable 入集后失真） */
+const APPROVAL_ANSWERS = new Set(['approve', 'reject', 'cancel', 'always']);
+/** decide-result.outcome 闭集（跨入口竞速回执两档） */
+const DECIDE_OUTCOMES = new Set(['applied', 'superseded']);
+/** 解码失败（fail-loud——坏行不产半帧；线面应答形〔错误帧映射〕归宿主 serve 装配批） */
+export class SdkDecodeError extends Error {
+    rawLine;
+    constructor(message, 
+    /** 原始行文本（审计面——截断到 200 字符防日志洪水） */
+    rawLine) {
+        super(`SDK 线解码失败：${message}`);
+        this.rawLine = rawLine;
+        this.name = 'SdkDecodeError';
+    }
+}
+/**
+ * 编码单帧为一行（含行尾 `\n`）。出站纪律：序列化 + U+2028/U+2029 转义——
+ * 返回值保证恰一个 `\n` 且在末尾（行安全锁，测试在册）。
+ */
+export function encodeWireLine(frame) {
+    const json = JSON.stringify(frame).replaceAll(LS, '\\u2028').replaceAll(PS, '\\u2029');
+    return `${json}\n`;
+}
+/** 值判别：请求（verb 判别字段在闭集内）——非抛型窄卫（消费面路由用） */
+export function isSdkRequest(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'verb' in value &&
+        typeof value.verb === 'string' &&
+        REQUEST_VERB_SET.has(value.verb));
+}
+/** 值判别：线帧（kind 判别字段在闭集内）——非抛型窄卫 */
+export function isSdkFrame(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'kind' in value &&
+        typeof value.kind === 'string' &&
+        FRAME_KIND_SET.has(value.kind));
+}
+/** 结构校验：非对象 / 判别字段缺席 / 判别值不在闭集 —— 各自独立报因 */
+function classify(value, rawLine) {
+    if (typeof value !== 'object' || value === null) {
+        throw new SdkDecodeError('非 JSON 对象', rawLine);
+    }
+    const v = value;
+    if (typeof v.verb === 'string' && REQUEST_VERB_SET.has(v.verb))
+        return 'request';
+    if (typeof v.kind === 'string' && FRAME_KIND_SET.has(v.kind))
+        return 'frame';
+    if (v.verb !== undefined || v.kind !== undefined) {
+        throw new SdkDecodeError(`判别值不识别（verb=${String(v.verb)} kind=${String(v.kind)}——闭集外）`, rawLine);
+    }
+    throw new SdkDecodeError('判别字段缺席（verb/kind 均无）', rawLine);
+}
+/** 标量必填断言（结构性校验——深校验挂账见文件头） */
+function requireString(shape, key, rawLine) {
+    const v = shape[key];
+    if (typeof v !== 'string')
+        throw new SdkDecodeError(`${key} 必填且须为 string`, rawLine);
+    return v;
+}
+function requireNumber(shape, key, rawLine) {
+    const v = shape[key];
+    if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new SdkDecodeError(`${key} 必填且须为有限数`, rawLine);
+    }
+    return v;
+}
+/** 逐请求动词的结构性必填校验（六动词族——03 §10.6 收窄律闭集） */
+function validateRequest(shape, verb, rawLine) {
+    switch (verb) {
+        case 'hello':
+            requireNumber(shape, 'protocolVersion', rawLine);
+            break;
+        case 'prompt':
+            requireString(shape, 'messageId', rawLine);
+            requireString(shape, 'content', rawLine);
+            break;
+        case 'interrupt':
+            requireString(shape, 'sessionId', rawLine);
+            break;
+        case 'getEntries':
+            requireString(shape, 'sessionId', rawLine);
+            requireNumber(shape, 'since', rawLine);
+            break;
+        case 'decide':
+            requireString(shape, 'approvalId', rawLine);
+            if (!APPROVAL_ANSWERS.has(shape.answer)) {
+                throw new SdkDecodeError('answer 必填且须为 approve/reject/cancel/always 四值闭集', rawLine);
+            }
+            break;
+        case 'sessions':
+            break;
+    }
+}
+/** 逐线帧 kind 的结构性必填校验 */
+function validateFrame(shape, kind, rawLine) {
+    switch (kind) {
+        case 'event':
+            requireNumber(shape, 'seq', rawLine);
+            requireString(shape, 'sessionId', rawLine);
+            if (typeof shape.event !== 'object' ||
+                shape.event === null ||
+                typeof shape.event.type !== 'string') {
+                throw new SdkDecodeError('event 必填且须携 string type（04 §2 十型判别）', rawLine);
+            }
+            break;
+        case 'hello':
+            requireString(shape, 'sessionId', rawLine);
+            requireNumber(shape, 'protocolVersion', rawLine);
+            requireNumber(shape, 'highWaterSeq', rawLine);
+            break;
+        case 'heartbeat':
+            requireString(shape, 'sessionId', rawLine);
+            if (shape.runState !== 'idle' && shape.runState !== 'running') {
+                throw new SdkDecodeError('runState 必填且须为 idle/running 两值闭集', rawLine);
+            }
+            requireNumber(shape, 'elapsedMs', rawLine);
+            break;
+        case 'ack':
+            requireString(shape, 'sessionId', rawLine);
+            requireString(shape, 'messageId', rawLine);
+            if (typeof shape.duplicate !== 'boolean') {
+                throw new SdkDecodeError('duplicate 必填且须为 boolean', rawLine);
+            }
+            requireNumber(shape, 'highWaterSeq', rawLine);
+            break;
+        case 'replay-end':
+            requireString(shape, 'sessionId', rawLine);
+            requireNumber(shape, 'lastReplayedSeq', rawLine);
+            break;
+        case 'entries':
+            requireString(shape, 'sessionId', rawLine);
+            break;
+        case 'decide-result':
+            requireString(shape, 'approvalId', rawLine);
+            if (!DECIDE_OUTCOMES.has(shape.outcome)) {
+                throw new SdkDecodeError('outcome 必填且须为 applied/superseded 两值闭集', rawLine);
+            }
+            break;
+        case 'ask':
+            // 审批外推帧恰三必填标量（reason/toolName/suggestedEntry 可选呈现位不校验）
+            requireString(shape, 'sessionId', rawLine);
+            requireString(shape, 'approvalId', rawLine);
+            requireString(shape, 'summary', rawLine);
+            break;
+        case 'sessions':
+            break;
+        case 'error':
+            requireString(shape, 'code', rawLine);
+            requireString(shape, 'message', rawLine);
+            break;
+    }
+}
+/**
+ * 解码单行为请求或线帧（fail-loud：非 JSON / 判别缺席 / 必填缺失各自报因，
+ * 坏行不产半帧）。行尾 `\r` 容忍（CRLF 传输面统一 LF——与 TUI 输入解码同律）。
+ */
+export function decodeWireLine(line) {
+    const rawLine = line;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        throw new SdkDecodeError('非合法 JSON', rawLine);
+    }
+    const which = classify(parsed, rawLine);
+    const shape = parsed;
+    if (which === 'request') {
+        validateRequest(shape, shape.verb, rawLine);
+        // 深校验（批 13e 接入——./schema.ts 单源）：结构层过后逐字段 typebox 校验
+        //（未知字段拒收/选填语义——HTTP 体校验位同源同件）
+        const deep = validateSdkRequest(parsed);
+        if (!deep.ok)
+            throw new SdkDecodeError(deep.reason, rawLine);
+        return deep.value;
+    }
+    validateFrame(shape, shape.kind, rawLine);
+    return parsed;
+}
+/**
+ * 流式分帧（stdio 管道跨 chunk 边界的安全分帧）：按 `\n` 切行、行尾 `\r` 剥离
+ * （CRLF 统一 LF）、空行跳过（心跳间隙的空拍不产帧）。入参 chunk 与上次
+ * remainder 拼接后切分；无完整行的 chunk 只进 remainder（零字节丢失、零半帧）。
+ */
+export function splitWireLines(chunk, remainder = '') {
+    const joined = remainder + chunk;
+    const lastNewline = joined.lastIndexOf('\n');
+    if (lastNewline === -1)
+        return { lines: [], remainder: joined };
+    const lines = joined
+        .slice(0, lastNewline)
+        .split('\n')
+        .map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line))
+        .filter((line) => line.length > 0);
+    return { lines, remainder: joined.slice(lastNewline + 1) };
+}