berry-agent 0.1.0-alpha.1

package/dist/channels/sdk/protocol.js

@@ -0,0 +1,24 @@
+/** 线协议版本（③/⑤ 版本握手第一天就有：连接即 hello 双方携 protocolVersion 比对） */
+export const SDK_PROTOCOL_VERSION = 1;
+/**
+ * 线帧 kind 闭集（十：活体事件帧 + 线控四件〔hello/heartbeat/ack/replay-end〕+
+ * 请求应答三件〔entries/sessions/decide-result〕+ 错误帧 + ask 审批外推帧——
+ * ask 独立于 event 位，审批挂起态非活体流，见 {@link SdkAskFrame} 文注）。
+ */
+export const SDK_FRAME_KINDS = [
+    'event',
+    'hello',
+    'heartbeat',
+    'ack',
+    'replay-end',
+    'error',
+    'entries',
+    'sessions',
+    'decide-result',
+    'ask',
+];
+/**
+ * 请求动词六件闭集（03 §10.6 请求面动词族条——v1 收窄律；steer/followUp/inject
+ * 三通道词**不在场**是执法位：驱动侧单源律的结构锁，测试断言在册）。
+ */
+export const SDK_REQUEST_VERBS = ['hello', 'prompt', 'interrupt', 'decide', 'getEntries', 'sessions'];

package/dist/channels/sdk/schema.js

@@ -0,0 +1,91 @@
+/**
+ * SDK 线协议请求面 typebox 深校验（03 §10.6 请求面动词族条「每动词 typebox
+ * schema 校验后消费——webui 微路由同纪律」；13a 挂账批 13e 兑现件）。
+ *
+ * 单源律：六动词 schema 全集即请求面唯一深校验真源——stdio 解码位
+ * （./jsonl.ts decodeWireLine 尾段）与 HTTP 体校验位（core:sdk 件经 channels
+ * 公开面消费）同源接入，零第二套。结构层（判别字段闭集/必填标量型）仍由
+ * jsonl.ts 先行快校——本层补齐逐字段型/选填语义/未知字段拒收。
+ *
+ * 非抛型结果面：{ok, value} | {ok:false, reason}——错误帧映射归宿主传输层
+ * （stdio = SdkDecodeError 包装；HTTP = 400 携结构化错误码），本层零错误词。
+ */
+import { Type } from 'typebox';
+import { Value } from 'typebox/value';
+// 顶部 typebox 注入形态说明：typebox 主包 + value 子路径均入 channels externals
+// 白名单（tools/conversation/web/exec/skills 同律——schema 层宿主件直用）。
+/** 公共字段词面：未知字段拒收（收窄律执法——请求面六动词载荷即全集） */
+const strict = { additionalProperties: false };
+/** hello 请求 schema（protocolVersion 必填；sessionId/after/noDelta 选填） */
+const HelloSchema = Type.Object({
+    verb: Type.Literal('hello'),
+    protocolVersion: Type.Integer(),
+    sessionId: Type.Optional(Type.String()),
+    after: Type.Optional(Type.Integer()),
+    noDelta: Type.Optional(Type.Boolean()),
+}, strict);
+/** prompt 请求 schema（messageId/content 必填；sessionId 选填——缺席即新建） */
+const PromptSchema = Type.Object({
+    verb: Type.Literal('prompt'),
+    messageId: Type.String(),
+    content: Type.String(),
+    sessionId: Type.Optional(Type.String()),
+}, strict);
+/** interrupt 请求 schema（sessionId 必填） */
+const InterruptSchema = Type.Object({
+    verb: Type.Literal('interrupt'),
+    sessionId: Type.String(),
+}, strict);
+/** decide 请求 schema（approvalId/answer 必填；note 选填——answer 四值闭集） */
+const DecideSchema = Type.Object({
+    verb: Type.Literal('decide'),
+    approvalId: Type.String(),
+    answer: Type.Union([
+        Type.Literal('approve'),
+        Type.Literal('reject'),
+        Type.Literal('cancel'),
+        Type.Literal('always'),
+    ]),
+    note: Type.Optional(Type.String()),
+}, strict);
+/** getEntries 请求 schema（sessionId/since 必填；cursor 选填——分页续读） */
+const GetEntriesSchema = Type.Object({
+    verb: Type.Literal('getEntries'),
+    sessionId: Type.String(),
+    since: Type.Integer(),
+    cursor: Type.Optional(Type.String()),
+}, strict);
+/** sessions 请求 schema（零载荷） */
+const SessionsSchema = Type.Object({ verb: Type.Literal('sessions') }, strict);
+/** 六动词 schema 分派表（verb 判别字段路由——与 SDK_REQUEST_VERBS 同序） */
+const SCHEMAS_BY_VERB = {
+    hello: HelloSchema,
+    prompt: PromptSchema,
+    interrupt: InterruptSchema,
+    decide: DecideSchema,
+    getEntries: GetEntriesSchema,
+    sessions: SessionsSchema,
+};
+/**
+ * 请求深校验（非抛型）。输入须已过 jsonl.ts 结构层（verb 在闭集内）——本层
+ * 补逐字段校验；独立调用时对判别字段缺席/闭集外同样诚实拒收（reason 单句）。
+ */
+export function validateSdkRequest(value) {
+    if (typeof value !== 'object' || value === null) {
+        return { ok: false, reason: '请求须为 JSON 对象' };
+    }
+    const verb = value.verb;
+    const schema = typeof verb === 'string' ? SCHEMAS_BY_VERB[verb] : undefined;
+    if (schema === undefined) {
+        return { ok: false, reason: `请求动词不识别（verb=${String(verb)}——闭集外或缺席）` };
+    }
+    if (!Value.Check(schema, value)) {
+        // 逐字段首错定位（fail-loud 可行动报因——webui 微路由同纪律）
+        const errors = [...Value.Errors(schema, value)];
+        const first = errors[0];
+        const at = first === undefined ? '' : `（${first.instancePath || '(root)'}：${first.message}）`;
+        return { ok: false, reason: `${verb} 请求载荷不合 schema${at}` };
+    }
+    // Value.Check 通过即结构吻合 SdkRequest 判别联合——窄化断言位
+    return { ok: true, value: value };
+}

package/dist/channels/sdk/wire-core.js

@@ -0,0 +1,446 @@
+import { admitMessage } from './admit.js';
+import { validateAfterCursor } from './cursor.js';
+import { SDK_PROTOCOL_VERSION, } from './protocol.js';
+/**
+ * 判帧是否纯活体可丢（⑦ 背压 shedding 面——03 §10.6「纯活体帧可丢」）：
+ * message_update delta 与 tool_execution_update 进度帧——丢帧无害，durable
+ * 定稿/锚定帧兜底（双轨律掉帧语义）。其余 event 帧与全部线控/回执帧不可丢。
+ */
+export function isDroppableFrame(frame) {
+    return (frame.kind === 'event' && (frame.event.type === 'message_update' || frame.event.type === 'tool_execution_update'));
+}
+/**
+ * 出站有界队列（⑦）：sink 可写即直写；背压期入队；溢出先丢队内最旧可丢帧
+ * （shedding——丢纯活体保线控），无可丢可让则过载（线控帧不可丢 ⇒ 断连档）。
+ */
+export class SdkOutboundQueue {
+    sink;
+    cap;
+    queue = [];
+    overloaded = false;
+    constructor(sink, cap) {
+        this.sink = sink;
+        this.cap = cap;
+    }
+    /** 累计丢弃纯活体帧数（观测面——宿主日志/指标可读） */
+    droppedCount = 0;
+    /** 容量观测面（过载错误帧文案与宿主指标用） */
+    get capacity() {
+        return this.cap;
+    }
+    enqueue(frame) {
+        if (this.overloaded)
+            return 'dropped'; // 断连档后全弃（宿主即将关传输）
+        if (this.queue.length === 0 && this.sink.write(frame))
+            return 'sent';
+        if (this.queue.length >= this.cap) {
+            // 溢出纪律：入站纯活体帧先自弃（最廉 shedding）；线控/锚定帧入站则让
+            // 位队内最旧纯活体帧，队内无可让 ⇒ 过载（线控帧不可丢——断连档）
+            if (isDroppableFrame(frame)) {
+                this.droppedCount++;
+                return 'dropped';
+            }
+            while (this.queue.length >= this.cap) {
+                const shedIndex = this.queue.findIndex(isDroppableFrame);
+                if (shedIndex === -1) {
+                    this.overloaded = true;
+                    return 'overload';
+                }
+                this.queue.splice(shedIndex, 1);
+                this.droppedCount++;
+            }
+        }
+        this.queue.push(frame);
+        return 'queued';
+    }
+    /**
+     * 宿主 writable 时冲刷（按序 FIFO；sink 再拒即停——余量留下轮）。
+     * @returns 本轮冲出帧数
+     */
+    drain() {
+        let drained = 0;
+        while (this.queue.length > 0 && this.sink.write(this.queue[0])) {
+            this.queue.shift();
+            drained++;
+        }
+        return drained;
+    }
+    get isOverloaded() {
+        return this.overloaded;
+    }
+}
+/**
+ * SDK 线协议核心（单连接状态机）。
+ *
+ * 生命周期间隙：宿主建核 → 行解码（./jsonl.ts）→ handleRequest 逐请求；
+ * 13b-3 后端把活体事件推入 {@link pushEvent}；宿主定时调
+ * {@link heartbeatTick}（心跳义务的装配驱动位）与 {@link drain}（writable）。
+ */
+export class SdkWireCore {
+    deps;
+    subs = new Map();
+    /** admit 已知键账（连接生命周期内快速档——跨重启档走 lookupDedupeKey） */
+    known = new Map();
+    /** 连接级 messageId → sessionId 反查账（sessionId 缺席重发的快速档定位面） */
+    messageIndex = new Map();
+    queue;
+    now;
+    heartbeatIntervalMs;
+    overloadRetryAfterMs;
+    /** 连接级缺省 noDelta（连接级 hello 落定；prompt 自动订阅继承） */
+    connectionNoDelta;
+    closed = false;
+    constructor(deps, options = {}) {
+        this.deps = deps;
+        this.now = options.now ?? Date.now;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 5_000;
+        this.overloadRetryAfterMs = options.overloadRetryAfterMs ?? 1_000;
+        this.connectionNoDelta = options.initialConnectionNoDelta ?? false;
+        this.queue = new SdkOutboundQueue(deps.sink, options.queueCap ?? 512);
+    }
+    // ---------------------------------------------------------------------------
+    // 请求面六动词受理
+    // ---------------------------------------------------------------------------
+    /** 请求受理总入口（行解码后逐请求路由——本方法即 NDJSON 请求面的全语义） */
+    handleRequest(req) {
+        if (this.closed) {
+            // 版本拒连/过载断连后的残行：同码直写重申（绕队列——连接将亡，宿主随即关传输）；
+            // 宿主主动 close()（无因）后的残行静默弃（装配纪律位：关传输后不应再喂行）
+            if (this.closedReason !== undefined) {
+                this.deps.sink.write({
+                    kind: 'error',
+                    code: this.closedReason,
+                    message: '连接已关闭（版本握手拒连或出站过载断连）——残行不受理',
+                });
+            }
+            return;
+        }
+        switch (req.verb) {
+            case 'hello':
+                this.handleHello(req.protocolVersion, req.sessionId, req.after, req.noDelta);
+                break;
+            case 'prompt':
+                this.handlePrompt(req.sessionId, req.messageId, req.content);
+                break;
+            case 'interrupt':
+                this.handleInterrupt(req.sessionId);
+                break;
+            case 'decide':
+                this.handleDecide(req.approvalId, req.answer, req.note);
+                break;
+            case 'getEntries':
+                this.handleGetEntries(req.sessionId, req.since, req.cursor);
+                break;
+            case 'sessions':
+                this.emit({ kind: 'sessions', sessions: this.deps.listSessions() });
+                break;
+        }
+    }
+    /** hello：版本握手（⑤）→ 会话订阅 + 游标重放（③）→ 衔接界标 */
+    handleHello(protocolVersion, sessionId, after, noDelta) {
+        // ⑤ 版本握手第一天就有：不符即拒连（先应答后置闭——emit 对 closed 自静默）
+        if (protocolVersion !== SDK_PROTOCOL_VERSION) {
+            this.emitError('SDK_PROTOCOL_MISMATCH', `线协议版本不符：服务端 ${SDK_PROTOCOL_VERSION} / 调用方 ${protocolVersion}`);
+            this.closed = true;
+            this.closedReason = 'SDK_PROTOCOL_MISMATCH';
+            return;
+        }
+        // 连接级握手（无会话订阅）：落定连接缺省 noDelta——显式携值胜出、缺席承
+        // 构造初值（07 §5 --no-delta 宿主立场缺省；选项缺席时初值 false 语义不变）
+        if (sessionId === undefined) {
+            this.connectionNoDelta = noDelta ?? this.connectionNoDelta;
+            this.emit({ kind: 'hello', protocolVersion: SDK_PROTOCOL_VERSION, sessionId: '', highWaterSeq: 0 });
+            return;
+        }
+        const state = this.deps.sessionStateOf(sessionId);
+        if (state === 'missing') {
+            this.emitError('SESSION_NOT_FOUND', `会话 ${sessionId} 不存在`, sessionId);
+            return;
+        }
+        // 订阅三步（同步读面下原子——文件头衔接序文注）：①快照高水位（先于挂监听，
+        // 快照后事件只走直播段——零跨段重复）②重放至快照 ③replay-end 后转直播
+        const highWater = this.deps.highWaterOf(sessionId) ?? 0;
+        this.emit({ kind: 'hello', protocolVersion: SDK_PROTOCOL_VERSION, sessionId, highWaterSeq: highWater });
+        let lastReplayed = -1;
+        if (after !== undefined) {
+            const check = validateAfterCursor(after, highWater);
+            if (!check.ok) {
+                this.emitError('SDK_CURSOR_INVALID', `订阅游标非法（${check.reason}）：after=${after} 高水位=${highWater}`, sessionId);
+                return; // 游标非法即拒订阅（不挂监听——调用方重对账后再来）
+            }
+            const page = this.deps.queryEntries(sessionId, after);
+            if (page.entries.length > 0) {
+                this.emit({ kind: 'entries', sessionId, entries: page.entries, nextCursor: page.nextCursor });
+                lastReplayed = page.entries[page.entries.length - 1].seq;
+            }
+            else {
+                lastReplayed = after; // 空窗（完全追平档）——after 原值即重放尾
+            }
+        }
+        this.emit({ kind: 'replay-end', sessionId, lastReplayedSeq: lastReplayed });
+        this.subs.set(sessionId, {
+            noDelta: noDelta ?? this.connectionNoDelta,
+            phase: 'live',
+            running: false,
+            runStartAt: 0,
+            lastElapsedMs: 0,
+            stage: null,
+            lastFrameAt: this.now(),
+        });
+        this.deps.onSubscribed?.(sessionId);
+    }
+    /** prompt：admit 三档（④）→ fresh 受理 / duplicate 幂等重收执 / conflict 拒收 */
+    handlePrompt(sessionId, messageId, content) {
+        // sessionId 缺席但连接内既见该 messageId：定位既落会话（重发走原会话快速档——
+        // 反查账是连接级索引，不参与 durable 语义）
+        if (sessionId === undefined) {
+            const indexed = this.messageIndex.get(messageId);
+            if (indexed !== undefined)
+                sessionId = indexed;
+        }
+        // 显式携带即续接：missing/closed 双拒（已闭对齐 webui 404 语义——读面走 getEntries）
+        if (sessionId !== undefined) {
+            const state = this.deps.sessionStateOf(sessionId);
+            if (state === 'missing') {
+                this.emitError('SESSION_NOT_FOUND', `会话 ${sessionId} 不存在`, sessionId);
+                return;
+            }
+            if (state === 'closed') {
+                this.emitError('SESSION_CLOSED', `会话 ${sessionId} 已关闭（新发拒收——回放走 getEntries）`, sessionId);
+                return;
+            }
+        }
+        // admit 判定：连接内快速档（known）→ durable 档（lookupDedupeKey 跨重启幂等）
+        let sessionKnown = sessionId === undefined ? undefined : this.known.get(sessionId);
+        let verdict = admitMessage(sessionKnown ?? new Map(), messageId, content);
+        if (verdict.status === 'fresh' && sessionId !== undefined) {
+            const durable = this.deps.lookupDedupeKey(sessionId, messageId);
+            if (durable !== undefined) {
+                // durable 命中——种子进连接内账后按同键判定（后续快速档直达）
+                sessionKnown ??= new Map();
+                sessionKnown.set(messageId, durable);
+                this.known.set(sessionId, sessionKnown);
+                verdict = admitMessage(sessionKnown, messageId, content);
+            }
+        }
+        if (verdict.status === 'conflict') {
+            this.emitError('SDK_MESSAGE_CONFLICT', `messageId=${messageId} 同键异内容（幂等 admit 冲突档）`, sessionId);
+            return;
+        }
+        if (verdict.status === 'duplicate') {
+            const sid = sessionId;
+            this.messageIndex.set(messageId, sid);
+            this.emit({
+                kind: 'ack',
+                sessionId: sid,
+                messageId,
+                duplicate: true,
+                highWaterSeq: this.deps.highWaterOf(sid) ?? 0,
+            });
+            return;
+        }
+        // fresh：唯一写路径过桥（sessionId 缺席即新建——桥落定回示句柄）
+        const outcome = this.deps.submitPrompt({ sessionId, content, messageId });
+        const record = this.known.get(outcome.sessionId) ?? new Map();
+        record.set(messageId, content);
+        this.known.set(outcome.sessionId, record);
+        this.messageIndex.set(messageId, outcome.sessionId);
+        // 自动订阅（13b 落码定形）：prompt 落定会话即挂直播（ack 携句柄 → 事件随后
+        // 即流；只直播不重放——重放走显式 hello.after）。既有订阅不覆写（hello 订阅
+        // 携 noDelta 等订阅参数胜出）；新会话无未决 ask，onSubscribed 只对新挂者发。
+        if (!this.subs.has(outcome.sessionId)) {
+            this.subs.set(outcome.sessionId, {
+                noDelta: this.connectionNoDelta,
+                phase: 'live',
+                running: false,
+                runStartAt: 0,
+                lastElapsedMs: 0,
+                stage: null,
+                lastFrameAt: this.now(),
+            });
+            this.deps.onSubscribed?.(outcome.sessionId);
+        }
+        this.emit({
+            kind: 'ack',
+            sessionId: outcome.sessionId,
+            messageId,
+            duplicate: false,
+            routedChannel: outcome.routedChannel,
+            highWaterSeq: this.deps.highWaterOf(outcome.sessionId) ?? 0,
+        });
+    }
+    /** interrupt：受理经事件流可观察（turn/end reason='interrupted'）——无应答帧 */
+    handleInterrupt(sessionId) {
+        if (this.deps.sessionStateOf(sessionId) === 'missing') {
+            this.emitError('SESSION_NOT_FOUND', `会话 ${sessionId} 不存在`, sessionId);
+            return;
+        }
+        this.deps.interruptSession(sessionId);
+    }
+    /** decide：跨入口审批竞速应答——applied/superseded 回执（03 §10.6 第三腿） */
+    handleDecide(approvalId, answer, note) {
+        const outcome = this.deps.decideApproval(approvalId, answer, note);
+        this.emit({ kind: 'decide-result', approvalId, outcome });
+    }
+    /** getEntries：对账读面（since 同 after 语义——05 §3.5 第一腿） */
+    handleGetEntries(sessionId, since, cursor) {
+        if (this.deps.sessionStateOf(sessionId) === 'missing') {
+            this.emitError('SESSION_NOT_FOUND', `会话 ${sessionId} 不存在`, sessionId);
+            return;
+        }
+        const highWater = this.deps.highWaterOf(sessionId) ?? 0;
+        const check = validateAfterCursor(since, highWater);
+        if (!check.ok) {
+            this.emitError('SDK_CURSOR_INVALID', `对账游标非法（${check.reason}）：since=${since} 高水位=${highWater}`, sessionId);
+            return;
+        }
+        const page = this.deps.queryEntries(sessionId, since, cursor);
+        this.emit({ kind: 'entries', sessionId, entries: page.entries, nextCursor: page.nextCursor });
+    }
+    // ---------------------------------------------------------------------------
+    // 活体外推腿（13b-3 后端 onEnvelope → 此处；订阅过滤 + 水位 seq + 心跳账）
+    // ---------------------------------------------------------------------------
+    /**
+     * 活体事件推入（双轨律直播段唯一入口）。未订阅会话丢弃；noDelta 订阅剥
+     * message_update；seq = 推入时刻高水位（durable 水位语义——弱单调，协议
+     * 文注定形）。同步推入顺带推导心跳账（run 态/阶段）。
+     */
+    pushEvent(sessionId, event) {
+        if (this.closed)
+            return;
+        const sub = this.subs.get(sessionId);
+        if (sub === undefined || sub.phase !== 'live')
+            return;
+        this.trackHeartbeat(sub, event);
+        if (sub.noDelta && event.type === 'message_update')
+            return; // ① delta 缺省开、--no-delta 退订
+        this.emit({ kind: 'event', seq: this.deps.highWaterOf(sessionId) ?? 0, sessionId, event }, sessionId);
+    }
+    /**
+     * 非事件帧外推（批 13b-3 后端消费位——ask 审批外推帧的入口）：独立帧族
+     * 不占 seq 不进 durable（03 §10.6 第三腿），直接过出站单点（背压/静默账
+     * 与事件帧同律）。订阅判据由调用方先决（后端 fail-closed 位）。
+     */
+    pushFrame(frame, sessionId) {
+        this.emit(frame, sessionId);
+    }
+    /** 订阅观测面（后端 fail-closed 判据——ask 帧去向位） */
+    isSubscribed(sessionId) {
+        return this.subs.get(sessionId)?.phase === 'live';
+    }
+    /**
+     * 退订（批 13e-2 HTTP 传输位：SSE 流全撤即退——ask fail-closed 判据与真
+     * 观众同步；未决 ask 不动〔重连 hello 即重推〕，admit 账不动〔连接级〕）。
+     * 退订后同会话再 hello/prompt 即重挂新订阅态。
+     */
+    unsubscribe(sessionId) {
+        this.subs.delete(sessionId);
+    }
+    /** 活跃订阅数（后端 hasAudience 探针——零订阅即无观众） */
+    get subscriptionCount() {
+        let count = 0;
+        for (const sub of this.subs.values())
+            if (sub.phase === 'live')
+                count++;
+        return count;
+    }
+    /** 心跳账推导（事件流 → runState/stage——非事件型 probe 走 tick 时查面） */
+    trackHeartbeat(sub, event) {
+        switch (event.type) {
+            case 'agent_start':
+                sub.running = true;
+                sub.runStartAt = this.now();
+                sub.stage = null;
+                break;
+            case 'agent_end':
+                sub.running = false;
+                sub.lastElapsedMs = Math.max(0, this.now() - sub.runStartAt);
+                sub.stage = null;
+                break;
+            case 'message_start':
+            case 'message_update':
+                sub.stage = { type: 'thinking' };
+                break;
+            case 'tool_execution_start':
+                sub.stage = { type: 'tool', name: event.name, sinceMs: this.now() };
+                break;
+            case 'tool_execution_end':
+                sub.stage = null; // 工具间隙（下一 message_start/tool_execution_start 再立）
+                break;
+            default:
+                break; // turn_* 不改阶段账
+        }
+    }
+    /**
+     * 心跳拍（② 协议义务的装配驱动位——宿主定间隔调）。静默填充式：会话级
+     * 最近一帧距今超阈才发（活跃流自证活性，心跳只填间隙）；阶段优先 retry
+     * probe（驱动退避等待期——事件流不可推导的非事件型源）。
+     */
+    heartbeatTick() {
+        if (this.closed)
+            return;
+        const now = this.now();
+        for (const [sessionId, sub] of this.subs) {
+            if (sub.phase !== 'live' || now - sub.lastFrameAt < this.heartbeatIntervalMs)
+                continue;
+            const probe = this.deps.retryProbeOf(sessionId);
+            const stage = probe !== null && probe.nextAt !== null
+                ? { type: 'retry', probe }
+                : sub.stage === null
+                    ? null
+                    : sub.stage.type === 'tool'
+                        ? { type: 'tool', name: sub.stage.name, stageElapsedMs: Math.max(0, now - sub.stage.sinceMs) }
+                        : { type: 'thinking' };
+            const elapsedMs = sub.running ? Math.max(0, now - sub.runStartAt) : sub.lastElapsedMs;
+            this.emit({ kind: 'heartbeat', sessionId, runState: sub.running ? 'running' : 'idle', stage, elapsedMs }, sessionId);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // 出站（emit + ⑦ 背压执法）与生命周期间隙
+    // ---------------------------------------------------------------------------
+    /** 出站单点：入有界队列；过载即断连档（SDK_OVERLOADED 尽力直写 + 宿主关传输） */
+    emit(frame, sessionId) {
+        if (this.closed)
+            return;
+        const status = this.queue.enqueue(frame);
+        if (sessionId !== undefined) {
+            const sub = this.subs.get(sessionId);
+            if (sub !== undefined)
+                sub.lastFrameAt = this.now(); // 任何携会话帧都刷新静默账
+        }
+        if (status !== 'overload')
+            return;
+        // ⑦ 线控帧不可丢 ⇒ 过载断连：错误帧绕队列尽力直写，钩宿主关传输
+        this.closed = true;
+        this.closedReason = 'SDK_OVERLOADED';
+        this.deps.sink.write({
+            kind: 'error',
+            code: 'SDK_OVERLOADED',
+            message: `出站队列溢出（容量 ${this.queue.capacity}）——线控帧不可丢，断连档`,
+            willRetry: true,
+            retryAfterMs: this.overloadRetryAfterMs,
+        });
+        this.deps.onOverload?.(this.overloadRetryAfterMs);
+    }
+    emitError(code, message, sessionId) {
+        this.emit({ kind: 'error', sessionId, code, message }, sessionId);
+    }
+    closedReason;
+    /** 闭合观测面（13e HTTP 传输位：闭合面新请求直接 503——不留半开档） */
+    get isClosed() {
+        return this.closed;
+    }
+    /** 宿主 writable 时冲刷在队帧（背压恢复腿） */
+    drain() {
+        return this.queue.drain();
+    }
+    /** 出站队列观测面（dropped 计数——宿主日志/指标） */
+    get droppedFrameCount() {
+        return this.queue.droppedCount;
+    }
+    /** 连接收口（宿主关传输时调——清订阅，后续 push/请求全静默） */
+    close() {
+        this.closed = true;
+        this.subs.clear();
+    }
+}