@twinsearth/dsh-master 3.3.3 → 3.3.5

package/dist-host/channel/protocol.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 智囊团通道协议（3.3.5）。
+ *
+ * 客户端 → 服务端：
+ *   { type: 'ping' }
+ *   { type: 'resync' }                          → 重新推一次快照
+ *   { type: 'chat', content: string, agent?: 'pm'|'pjm' }
+ *   { type: 'answer', callId: string, value: string }   ← 目前会返回 session-prompt-unavailable
+ *
+ * 服务端 → 客户端：
+ *   { type: 'hello', ... }                     连接建立（含协议版本与可用性）
+ *   { type: 'dual', snapshot }                 交接/计划/反馈/复核快照
+ *   { type: 'pong', at }
+ *   { type: 'error', code, message, detail? }
+ *
+ * 为什么 chat/answer 现在只返回错误：见 docs/CHANNEL-WEBSOCKET.md。
+ * 插件侧没有「向指定 preset 会话提交用户消息」的 Host API；假装能聊就是假聊天。
+ */
+export const CHANNEL_PROTOCOL_VERSION = 1;
+export const CHANNEL_MAX_MESSAGE_BYTES = 64 * 1024;
+export const CLIENT_MESSAGE_TYPES = Object.freeze(['ping', 'resync', 'chat', 'answer', 'interrupt']);
+function text(value) { return String(value ?? '').trim(); }
+/**
+ * 解析并校验一条客户端消息；非法输入给出具名错误而不是抛。
+ */
+export function parseClientMessage(raw) {
+    if (typeof raw === 'string' && raw.length > CHANNEL_MAX_MESSAGE_BYTES) {
+        return { ok: false, code: 'message-too-large', error: `message exceeds ${CHANNEL_MAX_MESSAGE_BYTES} bytes` };
+    }
+    let body = null;
+    if (typeof raw === 'string') {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            return { ok: false, code: 'invalid-json', error: 'message must be JSON' };
+        }
+    }
+    else if (raw && typeof raw === 'object') {
+        body = raw;
+    }
+    else {
+        return { ok: false, code: 'invalid-message', error: 'message must be a JSON object' };
+    }
+    const type = text(body.type);
+    if (!CLIENT_MESSAGE_TYPES.includes(type)) {
+        return { ok: false, code: 'unknown-type', error: `unknown message type: ${type || '(empty)'}`, types: CLIENT_MESSAGE_TYPES };
+    }
+    if (type === 'chat') {
+        const content = text(body.content);
+        if (!content)
+            return { ok: false, code: 'content-required', error: 'chat requires content' };
+        if (content.length > 8_000)
+            return { ok: false, code: 'content-too-long', error: 'chat content exceeds 8000 characters' };
+        const agent = text(body.agent) || 'pm';
+        if (!['pm', 'pjm'].includes(agent))
+            return { ok: false, code: 'agent-invalid', error: 'agent must be pm or pjm' };
+        return { ok: true, message: { type, content, agent } };
+    }
+    if (type === 'answer') {
+        const callId = text(body.callId);
+        const value = text(body.value);
+        if (!callId || !value)
+            return { ok: false, code: 'answer-incomplete', error: 'answer requires callId and value' };
+        return { ok: true, message: { type, callId, value } };
+    }
+    if (type === 'interrupt') {
+        // messageId 可选：省略表示“这一连接上所有正在生成的流都停”
+        const messageId = text(body.messageId);
+        return { ok: true, message: { type, messageId: messageId || null } };
+    }
+    return { ok: true, message: { type } };
+}
+/** 中断确认：`aborted` 表示是否真的掐断了一条在跑的流。 */
+export function interruptedMessage({ messageId, savedContent = '', aborted = true } = {}) {
+    return {
+        type: 'interrupted',
+        messageId: text(messageId) || null,
+        savedContent: String(savedContent ?? ''),
+        aborted: aborted === true,
+        at: Date.now(),
+    };
+}
+export function serverHello({ channelId, tokenRequired = true } = {}) {
+    return {
+        type: 'hello',
+        protocol: CHANNEL_PROTOCOL_VERSION,
+        channelId: text(channelId) || 'dsh-master-command-center',
+        capabilities: {
+            dualSnapshot: true,
+            chat: false,
+            answer: false,
+        },
+        limitations: {
+            chat: 'plugin cannot submit a user message into a preset agent session',
+            answer: 'user questions are answered inside their owning session',
+        },
+        tokenRequired: tokenRequired === true,
+        serverTime: Date.now(),
+    };
+}
+export function serverError(code, message, detail) {
+    const out = { type: 'error', code: text(code) || 'unknown', message: String(message ?? '') };
+    if (detail !== undefined)
+        out.detail = detail;
+    return out;
+}
+/** 把 dual 快照包成通道消息（保持字段原样，不在这里加工业务语义）。 */
+export function dualMessage(snapshot) {
+    return { type: 'dual', snapshot: snapshot ?? null };
+}

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 */ }
+        },
+    };
+}