berry-agent-sdk 0.1.0-alpha.2

package/dist/src/channels/registry.js

@@ -0,0 +1,57 @@
+/**
+ * 多会话注册表与焦点编排（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);
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../../src/channels/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,OAAO,eAAe;IAKP;IACA;IALF,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,YAAY,GAAkB,IAAI,CAAC;IAE3C,YACmB,eAAqF,EACrF,OAAwE;QADxE,oBAAe,GAAf,eAAe,CAAsE;QACrF,YAAO,GAAP,OAAO,CAAiE;IACxF,CAAC;IAEJ,oCAAoC;IACpC,eAAe,CAAC,SAAiB;QAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAED,sCAAsC;IACtC,iBAAiB,CAAC,SAAiB;QACjC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;IAChE,CAAC;IAED,kCAAkC;IAClC,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,SAAS,CAAC,SAAiB;QACzB,OAAO,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC;IACzC,CAAC;IAED,4CAA4C;IAC5C,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,SAAiB;QAC3B,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC;QAC9B,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;QACnE,uCAAuC;QACvC,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;CACF"}

package/dist/src/channels/sdk/admit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 幂等 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 存储表）。
+ */
+/** admit 判定三档（conflict 档携错误码——调用方直接落结构化错误帧） */
+export type AdmitVerdict = {
+    status: 'fresh';
+} | {
+    status: 'duplicate';
+} | {
+    status: 'conflict';
+    code: 'SDK_MESSAGE_CONFLICT';
+};
+/**
+ * 判定一条 prompt 的受理档。
+ *
+ * @param known 既存 dedupeKey → 内容 映射（受理侧维护；跨重启语义由 durable
+ *   落账兑现——本函数纯逻辑不触存储）
+ * @param messageId 调用方自选幂等键（受理时即落账为 data.dedupeKey——两词一字段两面）
+ * @param content 消息内容（同键异内容的比对基准——字符串全等，无归一化）
+ */
+export declare function admitMessage(known: ReadonlyMap<string, string>, messageId: string, content: string): AdmitVerdict;

package/dist/src/channels/sdk/admit.js

@@ -0,0 +1,30 @@
+/**
+ * 幂等 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' };
+}
+//# sourceMappingURL=admit.js.map

package/dist/src/channels/sdk/admit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit.js","sourceRoot":"","sources":["../../../../../../src/channels/sdk/admit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAkC,EAAE,SAAiB,EAAE,OAAe;IACjG,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACvD,qCAAqC;IACrC,OAAO,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC;AAC/G,CAAC"}

package/dist/src/channels/sdk/backend.d.ts

@@ -0,0 +1,19 @@
+import type { UiBackend } from '../types.js';
+import { SdkWireCore, type SdkWireDeps, type SdkWireOptions } from './wire-core.js';
+/** createSdkBackend 产物（后端 + 线核 + 收口三位——装配面 13c/13e 消费） */
+export interface SdkBackendHandle {
+    /** 通道核注册面（UiBackend 契约件） */
+    readonly backend: UiBackend<never>;
+    /** 线协议核（宿主行解码 → handleRequest / 定时 heartbeatTick+drain） */
+    readonly core: SdkWireCore;
+    /** 连接收口：在飞 ask 全部 unavailable 收场（通道消失语义）+ core.close()（后续全静默） */
+    dispose(): void;
+}
+/**
+ * 造 SDK 通道后端（每连接一枚——core 即该连接的单连接状态机）。
+ *
+ * @param deps 装配桥注入面（decideApproval/onSubscribed 两面由本件自持——
+ *   幂等账与重推编舞是后端语义不是桥语义）
+ * @param options 线核构造选项（时钟/节拍/背压参——透传）
+ */
+export declare function createSdkBackend(deps: Omit<SdkWireDeps, 'decideApproval' | 'onSubscribed'>, options?: SdkWireOptions): SdkBackendHandle;

package/dist/src/channels/sdk/backend.js

@@ -0,0 +1,103 @@
+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();
+        },
+    };
+}
+//# sourceMappingURL=backend.js.map

package/dist/src/channels/sdk/backend.js.map

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

package/dist/src/channels/sdk/cursor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 边界如实。
+ */
+/** 游标对账判定（ok=false 携错误码与报因——调用方落 SDK_CURSOR_INVALID 错误帧） */
+export type CursorCheck = {
+    ok: true;
+} | {
+    ok: false;
+    code: 'SDK_CURSOR_INVALID';
+    reason: 'beyond-high-water' | 'tail-truncated';
+};
+/**
+ * 校验订阅/重放游标 after 的合法性（hello.after 与 getEntries.since 同语义）。
+ *
+ * 合法 ⇔ after < highWaterSeq（重放窗口 = (after, highWaterSeq]；after 恰为
+ * 既存末条 seq = 完全追平档——窗口空、直接进直播，亦合法）。
+ */
+export declare function validateAfterCursor(after: number, highWaterSeq: number): CursorCheck;
+/**
+ * 崩溃重连尾截断侦测（05 §3.5 崩溃重连对账条——hello/ack 携高水位的消费侧）。
+ *
+ * @param lastReceivedSeq 调用方已收末条 seq（无对账面〔首连〕传 undefined——恒 ok）
+ * @param highWaterSeq 服务端 hello/ack 携带的会话当前高水位
+ * @returns 已收末 seq ≥ 高水位 ⇒ 尾被截（含 ==：声称知道下一将分配 seq 同为
+ *   幻影——撕裂截断后 seq 复用使等值也歧义，保守同码）
+ */
+export declare function detectTailTruncation(lastReceivedSeq: number | undefined, highWaterSeq: number): CursorCheck;
+/**
+ * 重放-直播衔接序定位（05 §3.5 衔接序第 ③ 步——**落码回归锁位**函数化）：
+ * 直播起播 = 内存日志中 seq > 重放尾（lastReplayedSeq）的首条（含未落库在飞
+ * 事件）。重放尾与直播首无缝衔接 = 衔接完整性验收位，测试在册。
+ *
+ * @param log 会话内存日志（seq 单调连续升序——05 §1.1 写入序不变式）
+ * @param lastReplayedSeq 重放段末条 seq（空重放 = after 原值或 −1）
+ * @returns 直播起播下标（log.length = 重放已覆盖全部内存日志——直播等新事件）
+ */
+export declare function resolveLiveStart<T extends {
+    seq: number;
+}>(log: readonly T[], lastReplayedSeq: number): number;

package/dist/src/channels/sdk/cursor.js

@@ -0,0 +1,57 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=cursor.js.map

package/dist/src/channels/sdk/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../../../../src/channels/sdk/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,YAAoB;IACrE,IAAI,KAAK,IAAI,YAAY,EAAE,CAAC;QAC1B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAChF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,eAAmC,EAAE,YAAoB;IAC5F,IAAI,eAAe,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,eAAe,IAAI,YAAY,EAAE,CAAC;QACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAA4B,GAAiB,EAAE,eAAuB;IACpG,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,CAAC;IACpE,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;AAC3C,CAAC"}

package/dist/src/channels/sdk/index.d.ts

@@ -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/src/channels/sdk/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/src/channels/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/channels/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}

package/dist/src/channels/sdk/jsonl.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SDK 线协议 NDJSON 编解码（03 篇 §10.6 线协议七原则⑦ 背压与写出纪律——NDJSON
+ * 行安全条款；stdio JSONL 传输的帧法真源，HTTP/SSE 腿复用同编解码语义）。
+ *
+ * 行安全：JSON 串内裸 U+2028（LINE SEPARATOR）/ U+2029（PARAGRAPH SEPARATOR）
+ * 在 JSON 合法但按 JS 行终止符语义会被下游 NDJSON 消费方的分行逻辑撕行（Claude
+ * gh-28405 实锤）——本编码器序列化后统一转义为 \u2028/\u2029 转义形（结构字符不
+ * 可能是这两位，全串替换零误伤）；解码侧 JSON.parse 原生还原，无需特判。
+ *
+ * 校验深度（契约面纪律）：本层做判别字段 + 必填标量的结构性校验（fail-loud
+ * 宁拒勿吞）；逐动词深校验（typebox schema 面——03 §10.6 请求面动词族条
+ * 「每动词 typebox schema 校验后消费——webui 微路由同纪律」）在 ./schema.ts
+ * 单源、decodeWireLine 尾段接入（批 13e 兑现 13a 挂账）——HTTP 体校验位
+ * （core:sdk 件）经 channels 公开面同源消费，零第二套。
+ */
+import type { SdkRequest, SdkWireFrame } from './protocol.js';
+/** 解码失败（fail-loud——坏行不产半帧；线面应答形〔错误帧映射〕归宿主 serve 装配批） */
+export declare class SdkDecodeError extends Error {
+    /** 原始行文本（审计面——截断到 200 字符防日志洪水） */
+    readonly rawLine: string;
+    constructor(message: string, 
+    /** 原始行文本（审计面——截断到 200 字符防日志洪水） */
+    rawLine: string);
+}
+/**
+ * 编码单帧为一行（含行尾 `\n`）。出站纪律：序列化 + U+2028/U+2029 转义——
+ * 返回值保证恰一个 `\n` 且在末尾（行安全锁，测试在册）。
+ */
+export declare function encodeWireLine(frame: SdkWireFrame | SdkRequest): string;
+/** 值判别：请求（verb 判别字段在闭集内）——非抛型窄卫（消费面路由用） */
+export declare function isSdkRequest(value: unknown): value is SdkRequest;
+/**
+ * 解码单行为请求或线帧（fail-loud：非 JSON / 判别缺席 / 必填缺失各自报因，
+ * 坏行不产半帧）。行尾 `\r` 容忍（CRLF 传输面统一 LF——与 TUI 输入解码同律）。
+ */
+export declare function decodeWireLine(line: string): SdkWireFrame | SdkRequest;
+/** 分帧结果：完整行列表 + 跨 chunk 残留（无 `\n` 尾的半行，续入下次调用） */
+export interface WireSplit {
+    lines: string[];
+    remainder: string;
+}
+/**
+ * 流式分帧（stdio 管道跨 chunk 边界的安全分帧）：按 `\n` 切行、行尾 `\r` 剥离
+ * （CRLF 统一 LF）、空行跳过（心跳间隙的空拍不产帧）。入参 chunk 与上次
+ * remainder 拼接后切分；无完整行的 chunk 只进 remainder（零字节丢失、零半帧）。
+ */
+export declare function splitWireLines(chunk: string, remainder?: string): WireSplit;