@twinsearth/dsh-master 3.3.4 → 3.3.6

package/dist-host/channel/server.js

@@ -0,0 +1,349 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 智囊团 WebSocket 通道（宿主侧）。
+ *
+ * 能力边界（重要）：
+ *   * 可以：握手、鉴权、心跳、推 dual 快照、收到 chat/answer 时返回具名错误；
+ *   * 不可以：把用户消息提交给 PM/PJM 会话 —— 插件侧没有该 Host API；
+ *   * 不假装：`chat` 返回 `session-prompt-unavailable`，并把缺失能力写进 hello 的 capabilities。
+ *
+ * 为什么不用 `ws` 依赖：房主坚持零运行时依赖；`registerUpgrade` 已由宿主提供，
+ * 帧编解码在 `ws.ts` 里自己实现（有 RFC 测试向量）。
+ */
+import { createFrameParser, encodeClose, encodePing, encodePong, encodeText, rejectionResponse, upgradeResponse, validateUpgradeRequest } from "./ws.js";
+import { dualMessage, interruptedMessage, parseClientMessage, serverError, serverHello } from "./protocol.js";
+import { createAbortRegistry } from "./abort-registry.js";
+export const CHANNEL_PATH = '/dsh-master/ws/command-center';
+const DEFAULTS = Object.freeze({ heartbeatMs: 30_000, maxConnections: 8 });
+function text(value) { return String(value ?? '').trim(); }
+/** 从升级请求的 URL 里取 token（`?token=`）或 Authorization 头。 */
+export function tokenOf(req) {
+    const raw = String(req?.url ?? '');
+    const queryIndex = raw.indexOf('?');
+    const query = queryIndex >= 0 ? raw.slice(queryIndex + 1) : '';
+    for (const pair of query.split('&')) {
+        const [key, value = ''] = pair.split('=');
+        if (decodeURIComponent(key) === 'token')
+            return decodeURIComponent(value);
+    }
+    const header = String(req?.headers?.authorization ?? '');
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match ? match[1].trim() : '';
+}
+/**
+ * @param {{
+ *   webServer: object,
+ *   token: string,
+ *   dualSnapshot: () => object,
+ *   logger?: { info?: Function, warn?: Function, error?: Function },
+ *   heartbeatMs?: number,
+ *   maxConnections?: number,
+ *   now?: () => number,
+ * }} deps
+ */
+export function attachCommandCenterChannel(deps = {}) {
+    const webServer = deps.webServer;
+    const token = text(deps.token);
+    const logger = deps.logger ?? {};
+    const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
+    const heartbeatMs = Number(deps.heartbeatMs) > 0 ? Number(deps.heartbeatMs) : DEFAULTS.heartbeatMs;
+    const maxConnections = Number(deps.maxConnections) > 0 ? Number(deps.maxConnections) : DEFAULTS.maxConnections;
+    const log = (level, message) => { try {
+        logger[level]?.(message);
+    }
+    catch { /* ignore */ } };
+    if (!webServer || typeof webServer.registerUpgrade !== 'function') {
+        return { attached: false, reason: 'web-server-unavailable' };
+    }
+    if (!token) {
+        // fail-closed：没有 token 就不开通道，避免任何本地进程都能订阅看板数据
+        return { attached: false, reason: 'channel-token-missing' };
+    }
+    const connections = new Set();
+    let closed = false;
+    /** 最近一次成功握手的连接：生产者登记流时默认绑定到它（单面板本地场景）。 */
+    let lastConnection = null;
+    /** 全局取消登记表（messageId → AbortController）；所有权按连接记录，断连时只中止自己的流。 */
+    const streams = createAbortRegistry();
+    const ownedStreams = new Map();
+    const snapshot = () => {
+        try {
+            return typeof deps.dualSnapshot === 'function' ? deps.dualSnapshot() : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const send = (connection, message) => {
+        if (connection.closed || !connection.socket.writable)
+            return;
+        try {
+            connection.socket.write(encodeText(JSON.stringify(message)));
+        }
+        catch (error) {
+            log('warn', `[channel] write failed: ${String(error?.message ?? error)}`);
+            closeConnection(connection, 1011, 'write-failed');
+        }
+    };
+    /** 中止某连接拥有的全部流（断连、卸载都走这里，避免僵尸流继续烧 token）。 */
+    const abortOwnedStreams = (connection, reason) => {
+        const owned = ownedStreams.get(connection);
+        if (!owned || owned.size === 0) {
+            ownedStreams.delete(connection);
+            return [];
+        }
+        const aborted = [];
+        for (const messageId of owned) {
+            if (streams.abort(messageId, reason))
+                aborted.push(messageId);
+        }
+        ownedStreams.delete(connection);
+        if (aborted.length > 0)
+            log('info', `[channel] aborted ${aborted.length} stream(s) (${reason})`);
+        return aborted;
+    };
+    const closeConnection = (connection, code = 1000, reason = '') => {
+        if (connection.closed)
+            return;
+        connection.closed = true;
+        connections.delete(connection);
+        abortOwnedStreams(connection, reason || 'connection-closed');
+        try {
+            connection.socket.write(encodeClose(code, reason));
+        }
+        catch { /* ignore */ }
+        try {
+            connection.socket.end();
+        }
+        catch { /* ignore */ }
+        try {
+            connection.socket.destroy();
+        }
+        catch { /* ignore */ }
+    };
+    const broadcast = (message) => { for (const connection of connections)
+        send(connection, message); };
+    const handleClientMessage = (connection, raw) => {
+        const parsed = parseClientMessage(raw);
+        if (!parsed.ok) {
+            send(connection, serverError(parsed.code, parsed.error, parsed.types ? { types: parsed.types } : undefined));
+            return;
+        }
+        const message = parsed.message;
+        if (message.type === 'ping') {
+            send(connection, { type: 'pong', at: now() });
+            return;
+        }
+        if (message.type === 'resync') {
+            send(connection, dualMessage(snapshot()));
+            return;
+        }
+        if (message.type === 'interrupt') {
+            const target = message.messageId;
+            const owned = ownedStreams.get(connection) ?? new Set();
+            let aborted = [];
+            if (target) {
+                if (streams.abort(target, 'user-interrupt'))
+                    aborted = [target];
+            }
+            else {
+                for (const messageId of owned) {
+                    if (streams.abort(messageId, 'user-interrupt'))
+                        aborted.push(messageId);
+                }
+            }
+            if (aborted.length === 0) {
+                // 没有在跑的流：如实说，不假装已中止
+                send(connection, serverError('no-active-stream', 'no stream is running on this connection', { messageId: target }));
+                return;
+            }
+            send(connection, interruptedMessage({ messageId: target, aborted: true, savedContent: '' }));
+            log('info', `[channel] interrupt: aborted ${aborted.length} stream(s)`);
+            return;
+        }
+        if (message.type === 'chat') {
+            // 防御性兜底（“打断施法”）：同一连接上已有在跑的流时，先中止旧的再处理新请求。
+            // 即便前端被绕过（多端/直调），也不会出现两路生成并发烧 token。
+            const owned = ownedStreams.get(connection);
+            if (owned && owned.size > 0) {
+                const aborted = [];
+                for (const messageId of owned) {
+                    if (streams.abort(messageId, 'superseded-by-new-chat'))
+                        aborted.push(messageId);
+                }
+                if (aborted.length > 0)
+                    log('warn', `[channel] new chat superseded ${aborted.length} running stream(s)`);
+            }
+            // 真实缺口，不编造成功。
+            send(connection, serverError('session-prompt-unavailable', 'this host has no API to submit a user message into a preset agent session; use a PM/PJM session to chat', { agent: message.agent, protocol: 1 }));
+            return;
+        }
+        if (message.type === 'answer') {
+            send(connection, serverError('session-answer-unavailable', 'user questions are answered inside their owning session, not through this channel', { callId: message.callId }));
+        }
+    };
+    /**
+     * 心跳扫描（单一定时器，不是每连接一个）：
+     *   * 超过 2×heartbeat 没收到任何数据（含浏览器自动回的 pong）→ 判定僵尸连接；
+     *   * 僵尸连接先中止它拥有的所有流，再 destroy socket（不等对端回 close 帧）。
+     * 拔网线/休眠/强杀进程都不会发 close 帧，只有这里能把资源收回来。
+     */
+    function heartbeatSweep() {
+        for (const connection of [...connections]) {
+            if (connection.closed)
+                continue;
+            if (now() - connection.lastSeenAt > heartbeatMs * 2) {
+                log('warn', '[channel] zombie connection detected, terminating');
+                closeConnection(connection, 1001, 'heartbeat-timeout');
+                continue;
+            }
+            try {
+                connection.socket.write(encodePing());
+            }
+            catch {
+                closeConnection(connection, 1011, 'ping-failed');
+            }
+        }
+    }
+    const heartbeatTimer = setInterval(heartbeatSweep, Math.max(1_000, Math.floor(heartbeatMs / 2)));
+    if (typeof heartbeatTimer.unref === 'function')
+        heartbeatTimer.unref();
+    const accept = (req, socket) => {
+        const validation = validateUpgradeRequest(req);
+        if (!validation.ok) {
+            socket.write(rejectionResponse(400, validation.code, 'invalid websocket handshake'));
+            socket.destroy();
+            return;
+        }
+        // Origin 必须与宿主一致（浏览器 WS 一定带 Origin）：挡掉跨站页面直连看板。
+        const origin = text(req?.headers?.origin);
+        const allowedOrigin = text(deps.allowedOrigin);
+        if (origin && allowedOrigin && origin !== allowedOrigin) {
+            log('warn', `[channel] rejected connection: bad origin ${origin}`);
+            socket.write(rejectionResponse(403, 'channel-origin-rejected', 'origin does not match the host'));
+            socket.destroy();
+            return;
+        }
+        if (tokenOf(req) !== token) {
+            log('warn', '[channel] rejected connection: bad token');
+            socket.write(rejectionResponse(401, 'channel-unauthorized', 'missing or invalid channel token'));
+            socket.destroy();
+            return;
+        }
+        if (connections.size >= maxConnections) {
+            socket.write(rejectionResponse(403, 'channel-full', `at most ${maxConnections} connections`));
+            socket.destroy();
+            return;
+        }
+        socket.write(upgradeResponse(validation.accept));
+        const connection = { socket, closed: false, parser: createFrameParser(), lastSeenAt: now(), pingedAt: null };
+        connections.add(connection);
+        lastConnection = connection;
+        log('info', `[channel] connection accepted (${connections.size}/${maxConnections})`);
+        send(connection, serverHello({ tokenRequired: true }));
+        send(connection, dualMessage(snapshot()));
+        socket.on('data', (chunk) => {
+            if (connection.closed)
+                return;
+            connection.lastSeenAt = now();
+            let parsed = null;
+            try {
+                parsed = connection.parser.push(chunk);
+            }
+            catch (error) {
+                log('warn', `[channel] frame parse failed: ${String(error?.message ?? error)}`);
+                closeConnection(connection, 1002, 'protocol-error');
+                return;
+            }
+            for (const error of parsed.errors ?? []) {
+                closeConnection(connection, 1002, error);
+                return;
+            }
+            for (const control of parsed.controls ?? []) {
+                if (control.type === 'ping') {
+                    try {
+                        connection.socket.write(encodePong(control.payload));
+                    }
+                    catch { /* ignore */ }
+                }
+                if (control.type === 'close') {
+                    closeConnection(connection, 1000, 'client-close');
+                    return;
+                }
+            }
+            for (const message of parsed.messages ?? [])
+                handleClientMessage(connection, message);
+        });
+        socket.on('error', (error) => {
+            log('warn', `[channel] socket error: ${String(error?.message ?? error)}`);
+            closeConnection(connection, 1011, 'socket-error');
+        });
+        socket.on('close', () => {
+            if (connection.heartbeat)
+                clearInterval(connection.heartbeat);
+            abortOwnedStreams(connection, 'connection-closed');
+            connection.closed = true;
+            connections.delete(connection);
+        });
+    };
+    let dispose = null;
+    try {
+        dispose = webServer.registerUpgrade({
+            path: CHANNEL_PATH,
+            handler: (req, socket) => { try {
+                accept(req, socket);
+            }
+            catch (error) {
+                log('error', `[channel] upgrade failed: ${String(error?.message ?? error)}`);
+                try {
+                    socket.destroy();
+                }
+                catch { /* ignore */ }
+            } },
+        });
+    }
+    catch (error) {
+        return { attached: false, reason: 'register-upgrade-failed', error: String(error?.message ?? error) };
+    }
+    return {
+        attached: true,
+        path: CHANNEL_PATH,
+        connections: () => connections.size,
+        /** 主动推一次快照（供 dual 状态变化时调用）。 */
+        publish: () => broadcast(dualMessage(snapshot())),
+        /**
+         * 生产者登记一条可中断的流（会话桥接入后由它调用）。
+         * 返回值里的 `signal` 被中止时必须停止推送；`end()` 收尾清理。
+         */
+        openStream: (messageId, { connection = lastConnection, onAbort = null } = {}) => {
+            const id = text(messageId);
+            if (!id)
+                throw new Error('openStream: messageId is required');
+            const entry = streams.begin(id, { onAbort });
+            if (connection) {
+                const owned = ownedStreams.get(connection) ?? new Set();
+                owned.add(id);
+                ownedStreams.set(connection, owned);
+            }
+            return entry;
+        },
+        activeStreams: () => streams.keys(),
+        /** 手动触发一次心跳扫描（测试与运维用）。 */
+        heartbeatTick: heartbeatSweep,
+        dispose: () => {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(heartbeatTimer);
+            streams.abortAll('server-shutdown');
+            for (const connection of [...connections])
+                closeConnection(connection, 1001, 'server-shutdown');
+            try {
+                dispose?.();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}

package/dist-host/channel/stream-state.js

@@ -0,0 +1,343 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 流式消息状态机（3.3.5）。
+ *
+ * 结构（3.3.5 性能版）：**历史与当前流式分开**
+ *   state.history  —— 已定稿的消息数组，**引用稳定**：只有消息被定稿时才换新数组；
+ *   state.active   —— 当前正在流式的那条（或 null），每 chunk 只换这一个对象；
+ *   state.messages —— 兼容视图（history + active），供旧代码/简单渲染使用。
+ *
+ * 为什么要拆：每 chunk 都让 UI `map` 一遍上百条历史是 O(N) 的 reconciliation 开销，
+ * `React.memo` 只能省 DOM，省不了上层遍历。消费方应当：
+ *   * 历史列表订阅 `history`（引用没变就不重渲染）；
+ *   * 当前气泡只订阅 `active`（每次 chunk 只重渲染它）。
+ *
+ * 语义：
+ *   * 幂等：重复 `stream_start` 不新建第二条；重复 `card_choice` 原地更新；
+ *   * 容忍乱序：`stream_chunk` 早于 `stream_start` 只计数（orphan），不造数据；
+ *   * 块级锁：`card_*` 到达时先定稿当前气泡，再插入卡片，并释放流式槽位；
+ *   * 有界：历史条数、单条内容、选项数、快照大小都有上限。
+ */
+export const STREAM_LIMITS = Object.freeze({
+    maxMessages: 200,
+    maxContentChars: 200_000,
+    maxOptions: 20,
+    maxSnapshotBytes: 256 * 1024,
+});
+export const MESSAGE_KINDS = Object.freeze(['text', 'choice', 'doc', 'status', 'error']);
+function text(value) { return String(value ?? ''); }
+function emptyState() {
+    return {
+        messages: [],
+        history: [],
+        active: null,
+        activeStreamId: null,
+        capabilities: null,
+        snapshot: null,
+        orphanChunks: 0,
+        ignored: 0,
+        truncated: 0,
+        lastError: null,
+    };
+}
+function capHistory(history) {
+    return history.length > STREAM_LIMITS.maxMessages
+        ? history.slice(history.length - STREAM_LIMITS.maxMessages)
+        : history;
+}
+function capContent(content, truncatedBefore) {
+    const value = text(content);
+    if (value.length <= STREAM_LIMITS.maxContentChars)
+        return { content: value, truncated: truncatedBefore };
+    return { content: value.slice(0, STREAM_LIMITS.maxContentChars), truncated: truncatedBefore + 1 };
+}
+/** 当前正在流式的那条消息；没有则 null。 */
+export function activeMessage(state) {
+    return state?.active ?? null;
+}
+/** 是否有消息仍在流式输出（UI 据此切换“发送/停止”按钮）。 */
+export function isGenerating(state) {
+    return Boolean(state?.active && state.active.streaming === true);
+}
+/**
+ * 光标微状态（UI 直接消费，不要在组件里重复推导）：
+ *   * `thinking`   —— 收到 stream_start 但还没有第一个字：显示跳动点，不显示竖线；
+ *   * `streaming`  —— 正在吐字：竖线紧贴最后一个字符；
+ *   * `interrupted` —— 最近一条消息是被中止的：红色闪烁两次后收起；
+ *   * `idle`       —— 没有正在生成的内容。
+ */
+export function cursorState(state) {
+    if (state?.active && state.active.streaming === true) {
+        return text(state.active.content).length === 0 ? 'thinking' : 'streaming';
+    }
+    const history = Array.isArray(state?.history) ? state.history : [];
+    const last = history.length > 0 ? history[history.length - 1] : null;
+    if (last && last.interrupted === true)
+        return 'interrupted';
+    return 'idle';
+}
+/**
+ * @param {{now?: () => number}} [options]
+ */
+export function createChatStream(options = {}) {
+    const now = typeof options.now === 'function' ? options.now : () => Date.now();
+    let state = emptyState();
+    const listeners = new Set();
+    const notify = () => { for (const listener of [...listeners]) {
+        try {
+            listener(state);
+        }
+        catch { /* 订阅者异常不影响状态机 */ }
+    } };
+    /** 由 history + active 构造完整 state（messages 为兼容视图）。 */
+    function bundle(next, history, active) {
+        const trimmed = capHistory(history);
+        const activeValue = active ?? null;
+        const messages = activeValue ? [...trimmed, activeValue] : trimmed;
+        return {
+            ...state,
+            ...next,
+            history: trimmed,
+            active: activeValue,
+            activeStreamId: activeValue ? activeValue.id : null,
+            messages,
+        };
+    }
+    /** 把当前 active 定稿进 history（不改变 active 对象的 streaming 标记，调用方负责）。 */
+    function finalized(next, item) {
+        const active = state.active;
+        const history = active ? [...state.history, { ...active, ...(item ?? {}) }] : state.history;
+        return bundle(next, history, null);
+    }
+    function applyOne(message) {
+        const type = text(message?.type);
+        const id = text(message?.messageId ?? message?.id);
+        switch (type) {
+            case 'stream_start': {
+                if (!id)
+                    return state;
+                const existingHistory = state.history.find((entry) => entry.id === id);
+                if (existingHistory)
+                    return state; // 已定稿的同 id 消息不再复活
+                if (state.active && state.active.id === id) {
+                    // 幂等：重复 start 保持同一条
+                    return bundle({}, state.history, { ...state.active, streaming: true });
+                }
+                const role = text(message.role) === 'pjm' ? 'pjm' : 'pm';
+                const entry = { id, role, kind: 'text', content: '', streaming: true, at: now() };
+                const history = state.active ? [...state.history, { ...state.active, streaming: false }] : state.history;
+                return bundle({}, history, entry);
+            }
+            case 'stream_chunk': {
+                if (!id)
+                    return state;
+                if (!state.active || state.active.id !== id) {
+                    return { ...state, orphanChunks: state.orphanChunks + 1 };
+                }
+                const content = `${text(state.active.content)}${text(message.delta)}`;
+                const capped = capContent(content, state.truncated);
+                return bundle({ truncated: capped.truncated }, state.history, { ...state.active, content: capped.content, truncated: capped.content.length >= STREAM_LIMITS.maxContentChars });
+            }
+            case 'stream_end': {
+                if (!id)
+                    return state;
+                if (!state.active || state.active.id !== id)
+                    return { ...state, orphanChunks: state.orphanChunks + 1 };
+                const full = text(message.fullContent);
+                const current = state.active;
+                const finalContent = full.length > text(current.content).length
+                    ? full.slice(0, STREAM_LIMITS.maxContentChars)
+                    : current.content;
+                const entry = {
+                    ...current,
+                    streaming: false,
+                    interrupted: message.interrupted === true ? true : current.interrupted === true,
+                    content: finalContent,
+                };
+                return bundle({}, [...state.history, entry], null);
+            }
+            case 'interrupted': {
+                if (!id)
+                    return state;
+                if (!state.active || state.active.id !== id)
+                    return { ...state, orphanChunks: state.orphanChunks + 1 };
+                const saved = text(message.savedContent);
+                const current = state.active;
+                const entry = {
+                    ...current,
+                    streaming: false,
+                    interrupted: message.aborted !== false,
+                    content: saved.length > text(current.content).length ? saved : current.content,
+                };
+                return bundle({}, [...state.history, entry], null);
+            }
+            case 'card_choice': {
+                if (!id)
+                    return state;
+                const existing = state.history.findIndex((entry) => entry.id === id && entry.kind === 'choice');
+                const options = Array.isArray(message.options)
+                    ? message.options.slice(0, STREAM_LIMITS.maxOptions).map((option) => (typeof option === 'string' ? { label: option, value: option } : { label: text(option?.label), value: text(option?.value ?? option?.label) }))
+                    : [];
+                const card = {
+                    id,
+                    role: 'pm',
+                    kind: 'choice',
+                    content: text(message.question),
+                    options,
+                    answered: false,
+                    answer: null,
+                    streaming: false,
+                    at: now(),
+                };
+                if (existing >= 0) {
+                    const history = state.history.slice();
+                    history[existing] = { ...history[existing], ...card };
+                    return bundle({}, history, state.active);
+                }
+                const history = state.active
+                    ? [...state.history, { ...state.active, streaming: false }, card]
+                    : [...state.history, card];
+                return bundle({}, history, null);
+            }
+            case 'card_prd': {
+                if (!id)
+                    return state;
+                const doc = {
+                    id,
+                    role: 'pm',
+                    kind: 'doc',
+                    content: text(message.title),
+                    summary: text(message.summary ?? message.content ?? ''),
+                    status: ['draft', 'approved', 'shipped'].includes(text(message.status)) ? text(message.status) : 'draft',
+                    streaming: false,
+                    at: now(),
+                };
+                const history = state.active
+                    ? [...state.history, { ...state.active, streaming: false }, doc]
+                    : [...state.history, doc];
+                return bundle({}, history, null);
+            }
+            case 'card_status': {
+                if (!id)
+                    return state;
+                const progress = Math.max(0, Math.min(100, Number(message.progress) || 0));
+                const entry = {
+                    id,
+                    role: 'pjm',
+                    kind: 'status',
+                    content: text(message.content),
+                    progress,
+                    statusText: text(message.statusText),
+                    streaming: false,
+                    at: now(),
+                };
+                const existing = state.history.findIndex((item) => item.id === id && item.kind === 'status');
+                if (existing >= 0) {
+                    const history = state.history.slice();
+                    history[existing] = { ...history[existing], ...entry };
+                    return bundle({}, history, state.active);
+                }
+                const history = state.active
+                    ? [...state.history, { ...state.active, streaming: false }, entry]
+                    : [...state.history, entry];
+                return bundle({}, history, null);
+            }
+            case 'error': {
+                const entry = {
+                    id: id || `error-${now()}`,
+                    role: 'system',
+                    kind: 'error',
+                    content: text(message.message),
+                    code: text(message.code),
+                    streaming: false,
+                    at: now(),
+                };
+                const history = state.active
+                    ? [...state.history, { ...state.active, streaming: false }, entry]
+                    : [...state.history, entry];
+                return bundle({ lastError: entry }, history, null);
+            }
+            case 'dual': {
+                const snapshot = message.snapshot ?? null;
+                let safeSnapshot = snapshot;
+                try {
+                    if (snapshot && JSON.stringify(snapshot).length > STREAM_LIMITS.maxSnapshotBytes)
+                        safeSnapshot = null;
+                }
+                catch {
+                    safeSnapshot = null;
+                }
+                return { ...state, snapshot: safeSnapshot };
+            }
+            case 'hello': {
+                return {
+                    ...state,
+                    capabilities: {
+                        protocol: Number(message.protocol) || 0,
+                        dualSnapshot: message?.capabilities?.dualSnapshot === true,
+                        chat: message?.capabilities?.chat === true,
+                        answer: message?.capabilities?.answer === true,
+                        limitations: message?.limitations ?? null,
+                    },
+                };
+            }
+            case 'pong':
+                return state;
+            default:
+                return { ...state, ignored: state.ignored + 1 };
+        }
+    }
+    return {
+        getState: () => state,
+        apply: (message) => { state = applyOne(message); notify(); return state; },
+        /**
+         * 用户回答选择题（本地乐观更新）：
+         *   * 只把那张卡片改成 answered 并写入 answer；
+         *   * 可选追加一条本地用户气泡（`local: true`）；
+         *   * history 换新数组，其余消息对象引用保持不变。
+         *   * 重复回答同一张卡片会被拒绝。
+         */
+        answerChoice: (messageId, value, options = {}) => {
+            const id = text(messageId);
+            const answer = text(value);
+            if (!id || !answer)
+                return { ok: false, code: 'answer-incomplete', error: 'answerChoice requires messageId and value' };
+            const index = state.history.findIndex((entry) => entry.id === id);
+            if (index < 0)
+                return { ok: false, code: 'choice-not-found', error: `no message with id ${id}` };
+            const current = state.history[index];
+            if (current.kind !== 'choice')
+                return { ok: false, code: 'not-a-choice', error: `${id} is not a choice card` };
+            if (current.answered === true)
+                return { ok: false, code: 'choice-already-answered', error: `choice ${id} was already answered` };
+            const history = state.history.slice();
+            history[index] = { ...current, answered: true, answer };
+            const echo = text(options.echo);
+            if (echo) {
+                history.push({ id: `local-${now()}`, role: 'user', kind: 'text', content: echo, local: true, streaming: false, at: now() });
+            }
+            state = bundle({}, history, state.active);
+            notify();
+            return { ok: true, state };
+        },
+        /** 批量应用，只通知一次（UI 可按帧 flush）。 */
+        applyBatch: (messages) => {
+            const list = Array.isArray(messages) ? messages : [];
+            for (const message of list)
+                state = applyOne(message);
+            if (list.length > 0)
+                notify();
+            return state;
+        },
+        /** 外部 store 订阅（配合 useSyncExternalStore）。返回取消订阅函数。 */
+        subscribe: (listener) => {
+            if (typeof listener !== 'function')
+                return () => { };
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        reset: () => { state = emptyState(); notify(); return state; },
+    };
+}