@konglx/rotom 2.21.0

package/dist/master/ws-hub/conversation.js

@@ -0,0 +1,290 @@
+/**
+ * Conversation enrichment + HTTP-side send + ask-bridge helpers.
+ *
+ * `enrichGroupConversation` attaches workingDir / activeIssues / memoryCounts /
+ * skillCount / guidancePrompt to outgoing conversation payloads so agents and
+ * dashboards see what the group is doing. Called from the connection handler's
+ * a2a_send / a2a_reply / a2a_reply_end paths.
+ *
+ * `sendAsAgent` is the HTTP-side mirror of `a2a_send` — used by REST handlers
+ * (CLI, dashboard API) to send messages on behalf of an agent.
+ *
+ * `autoCreateBridgeOnMention` / `checkAndCancelBridgesForMessage` drive the
+ * implicit ask-bridge timer when agents @ each other with #reply.
+ *
+ * Methods attach via Object.assign.
+ */
+import { randomUUID } from "node:crypto";
+import { safeJsonParse } from "../../shared/parse.js";
+import { extractMentions } from "../../shared/mention.js";
+import { enrichWorkerDispatch } from "./dispatch-enrich.js";
+import { TIMER_PERSONA_NAME } from "../util/persona.js";
+import { collectLinksFromText } from "../services/link-collector.js";
+export const conversationMethods = {
+    /**
+     * Attach workingDir / activeIssues / memoryCounts / skillCount /
+     * guidancePrompt to a conversation payload.
+     *
+     * `targetAgentName` 让 workingDir 走成员级 override 优先:dashboard 在
+     * MemberListModal 里设的 per-(group, agent) working_dir 写到了
+     * group_member_settings,必须在这里查出来才能透传给前端展示。
+     *
+     * 注意:`workingDir` 仅用于 dashboard 展示/解析,**不会**被 executor 当作
+     * spawn cwd —— 后者必须走本机 `resolveIssueCwd` 派生(见 worker.ts
+     * "跨机器部署安全"注释),否则多机部署下会把 master 本地路径推给别的机器。
+     */
+    enrichGroupConversation(conversation, targetAgentName) {
+        if (!conversation || !conversation.groupId)
+            return conversation;
+        // workingDir 优先级:成员级 override > 群级默认。仅作为元数据透传给前端,
+        // executor 不会消费(避免跨机器把 master 本地路径推到非 master executor)。
+        const memberOverride = targetAgentName
+            ? this.db.getGroupMemberSetting(conversation.groupId, targetAgentName)
+            : null;
+        const group = this.db.getGroupById(conversation.groupId);
+        const workingDir = memberOverride || group?.working_dir || undefined;
+        if (conversation.type !== "group") {
+            // DM / single chat — only workingDir enrichment is meaningful.
+            return workingDir ? { ...conversation, workingDir } : conversation;
+        }
+        // Active task issues for the group — used by agents to decide whether
+        // file writes are permitted. Cap at 8 to keep prompt small.
+        const openIssues = this.db
+            .listIssuesByGroup(conversation.groupId, "open", "task")
+            .slice(0, 8);
+        const inProgressIssues = this.db
+            .listIssuesByGroup(conversation.groupId, "in_progress", "task")
+            .slice(0, 8);
+        const activeIssues = [...inProgressIssues, ...openIssues].slice(0, 8).map((it) => ({
+            id: it.id,
+            title: it.title,
+            status: it.status,
+            assignedTo: it.assigned_to || undefined,
+            priority: it.priority || undefined,
+        }));
+        // 记忆计数(极简指针注入用,只算 agent_visible=1 且 active 且非 pending)
+        const memoryCounts = {
+            group: this.db.countMemory("group", conversation.groupId),
+            global: this.db.countMemory("global"),
+        };
+        // skill 计数(该 agent 在该群绑定的 active skill 数,per-agent)
+        const skillCount = targetAgentName
+            ? this.db.countSkillsForAgent(conversation.groupId, targetAgentName)
+            : 0;
+        return { ...conversation, activeIssues, workingDir, memoryCounts, skillCount, guidancePrompt: group?.guidance_prompt || undefined };
+    },
+    /**
+     * 隐式 bridge 创建:群消息落库后调。若 sender @ 了某 agent B,自动建 bridge
+     * (asker=sender, target=B) + 20s interval scheduled_task。A 不用调 rotom ask,
+     * 直接 @ B 即可,系统透明管 timer。
+     *
+     * 跳过条件:
+     *   - B == sender(自 @)
+     *   - B 是真人(category=真人,真人不参与 bridge)
+     *   - sender 是某 pending bridge 的 target(说明 sender 在回复别人问题,不是在提问)
+     *   - (sender, B) 已有 pending bridge(防重)
+     */
+    autoCreateBridgeOnMention(groupId, sender, mentions, msgId) {
+        if (mentions.length === 0 || sender === "system")
+            return;
+        // 只有消息含 #reply 标记才建 bridge——普通 @ 不需要回复,不建 timer
+        const content = this.db.getGroupMessageContent(msgId) || "";
+        if (!content.includes("#reply"))
+            return;
+        const senderAgent = this.db.getAgentByName(sender);
+        if (!senderAgent)
+            return;
+        for (const targetName of mentions) {
+            if (targetName === sender)
+                continue;
+            const targetAgent = this.db.getAgentByName(targetName);
+            if (!targetAgent)
+                continue;
+            // 跳过真人 target
+            const targetProfile = safeJsonParse(targetAgent.profile, {});
+            if (targetProfile.category === "真人")
+                continue;
+            // 跳过:sender 是某 pending bridge 的 target(在回复,不在提问)
+            const asTarget = this.db.findPendingBridge(groupId, targetName, sender);
+            if (asTarget)
+                continue;
+            // 跳过:已有 pending bridge (sender → targetName)
+            const existing = this.db.findPendingBridge(groupId, sender, targetName);
+            if (existing)
+                continue;
+            // 建 bridge
+            const bridgeId = randomUUID();
+            this.db.createAskBridge({
+                id: bridgeId,
+                groupId,
+                asker: sender,
+                target: targetName,
+                questionMsgId: msgId,
+                escalateTo: null,
+                timeoutMs: 5 * 60_000,
+            });
+            const task = this.db.createScheduledTask({
+                name: `${TIMER_PERSONA_NAME} · 等待 ${targetName} 回复`,
+                groupId,
+                mode: "message",
+                scheduleKind: "interval",
+                intervalSec: 20,
+                prompt: `${TIMER_PERSONA_NAME} 每 20s 检查一次 ${targetName} 有没有回复 ${sender} 的问题;有回复就复述给 ${sender},5 分钟没回复就升级 Issue。`,
+                handlerKey: "ask-bridge-check",
+                handlerPayload: JSON.stringify({ bridgeId, asker: sender, target: targetName }),
+            });
+            this.logger.info(`[mesh] bridge auto-created: ${bridgeId} (${sender}→${targetName}) msg=${msgId} (#reply), schedule task #${task.id}`);
+        }
+    },
+    /**
+     * 事件式 bridge 检测:群消息落库后调。若该消息"答中"了某 pending bridge
+     * (sender = bridge.target AND mentions 含 bridge.asker),mark answered + disable
+     * scheduled_task + **注入 system @ 消息给 asker**(带"汇报给原始提问者"上下文)。
+     *
+     * 不直接 WS 推 raw @ —— 那样 A 的 LLM 会回复给 B 而非汇报给原始提问者。
+     * 改用 postSystemToGroup 注入带上下文的 system 消息,A 的 LLM 知道该汇报给谁。
+     */
+    checkAndCancelBridgesForMessage(groupId, sender, mentions, msgId) {
+        if (mentions.length === 0)
+            return;
+        const bridges = this.db.findBridgesAnsweredByMessage(groupId, sender, mentions);
+        if (bridges.length === 0)
+            return;
+        // B @ A 回复:A 通过 a2a_message 广播已收到(session 复用,有上下文)。
+        // 这里只 cancel bridge + delete timer,不注入 system 消息——避免 A 收到两条消息(raw @ + system)顺序不确定。
+        // system 复述只在 handler 路径(非@回复,20s poll 检测)走,A 没被 @ 触发才需要 system 唤醒。
+        for (const bridge of bridges) {
+            this.db.markBridgeAnswered(bridge.id, msgId);
+            const task = this.db.findAskBridgeScheduledTask(bridge.id);
+            if (task && task.enabled) {
+                this.db.disableScheduledTask(task.id);
+            }
+            this.logger.info(`[mesh] bridge ${bridge.id} auto-answered: ${sender} @ ${bridge.asker} (msg ${msgId}), timer task #${task?.id ?? "?"} cancelled`);
+        }
+    },
+    /**
+     * Send a message on behalf of an agent, mirroring the WS `a2a_send` path
+     * for HTTP/CLI callers. If `groupId` is provided the message is treated as
+     * a group message: routed to `target` and recorded in group history.
+     */
+    sendAsAgent(opts) {
+        const fromAgent = this.db.getAgentByName(opts.fromName);
+        if (!fromAgent)
+            return { requestId: "", delivered: false, queued: false, error: `Sender agent "${opts.fromName}" not found` };
+        const targetAgent = this.db.getAgentByName(opts.target);
+        if (!targetAgent)
+            return { requestId: "", delivered: false, queued: false, error: `Target agent "${opts.target}" not found` };
+        const requestId = `cli_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+        const conversation = opts.groupId
+            ? { type: "group", groupId: opts.groupId, groupName: opts.groupName }
+            : undefined;
+        // needReply: 自动补 @target 到正文开头(若没有),确保 worker 的 @-mention 检查命中。
+        let messageBody = opts.message;
+        const mentionTag = `@${opts.target}`;
+        if (opts.needReply && !messageBody.startsWith(mentionTag)) {
+            messageBody = `${mentionTag} ${messageBody}`;
+        }
+        const result = this.router.route(fromAgent.id, {
+            requestId,
+            target: opts.target,
+            payload: { message: messageBody },
+            ...(conversation ? { conversation } : {}),
+            ...(opts.needReply ? { qaMode: true } : {}),
+        });
+        if (result.error)
+            return { requestId, delivered: false, queued: false, error: result.error };
+        // needReply: 登记 requestId → asker,master 收到 reply 时据此硬剥 @<asker>
+        if (opts.needReply) {
+            this.qaModeAskers.set(requestId, opts.fromName);
+        }
+        let delivered = false;
+        let queued = false;
+        let messageId;
+        if (result.targetAgentId) {
+            const enrichedConversation = this.enrichGroupConversation(conversation);
+            const wireMsg = enrichWorkerDispatch(this, {
+                type: "a2a_message",
+                requestId,
+                from: { name: opts.fromName, domain: fromAgent.domain || undefined, status: "online" },
+                payload: { message: messageBody },
+                routeType: "exact",
+                conversation: enrichedConversation,
+                ...(opts.needReply ? { qaMode: true } : {}),
+            }, result.targetName, enrichedConversation?.groupId);
+            // noDispatch:不直接推给 target 的 WS,也不入 offline_queue。
+            // 消息仍会广播给其他群成员 + 入库,target 只能通过 group history 看到。
+            if (!opts.noDispatch) {
+                delivered = this.sendToAgent(result.targetAgentId, wireMsg);
+            }
+            if (opts.groupId) {
+                // 兜底:发信人不在 group_members 时自动 addMembers(防"自激丢消息" +
+                // "多 tab 真人看不到自己的消息")。INSERT OR IGNORE 幂等。
+                const groupMembers = this.db.getGroupMembers(opts.groupId);
+                if (!groupMembers.some((m) => m.agent_name === opts.fromName)) {
+                    this.db.addGroupMembers(opts.groupId, [opts.fromName]);
+                    this.logger.info(`[mesh] sendAsAgent group: auto-joined sender "${opts.fromName}" as group member`);
+                }
+                // 群消息:除打给 target 外广播给全群(对齐 a2a_reply L462-465)。
+                // 排除列表含 target 防重复推送。同时排除所有 @mentioned agent 防
+                // Dashboard 多次发送 a2a_send 导致的广播重复投递。
+                //
+                // qaMode 不能漏给非 target 群成员:target 已通过 sendToAgent 收到
+                // qaMode=true 副本以 bypass @-mention 检查,但 broadcast 给其他成员
+                // 时若还带 qaMode=true,他们也会 bypass,导致群里全员被唤醒回复
+                // (典型症状:--need-reply 后群里非 @ 对象也冒泡接话)。
+                // 剥一份广播专用副本。
+                //
+                // 单播群(unicast, type=a2a_direct)默认静默:不广播、也不投递给非
+                // target 成员。消息只入库,asker 通过 group history / new-messages
+                // 拉,reply 通过 a2a_reply 路径同样静默(target sendToAgent 仅对
+                // asker 那条连接,其他成员 worker 不会被消息自动唤醒)。
+                const group = this.db.getGroupById(opts.groupId);
+                const a2aDirect = group?.type === "a2a_direct";
+                const sendAsMentions = extractMentions(messageBody);
+                if (!a2aDirect) {
+                    const sendAsMentionAgentIds = sendAsMentions
+                        .map((name) => this.db.getAgentByName(name)?.id)
+                        .filter((id) => !!id);
+                    const broadcastWire = (opts.needReply
+                        ? { ...wireMsg, qaMode: undefined }
+                        : wireMsg);
+                    this.broadcastToGroup(opts.groupId, broadcastWire, [fromAgent.id, result.targetAgentId, ...sendAsMentionAgentIds]);
+                }
+                else if (opts.needReply) {
+                    this.logger.info(`[mesh] sendAsAgent a2a_direct group: qaMode target engaged (no broadcast)`);
+                }
+                else {
+                    this.logger.info(`[mesh] sendAsAgent a2a_direct group: pure store, no broadcast, no target dispatch`);
+                }
+                const mentions = sendAsMentions;
+                messageId = this.db.addGroupMessage(opts.groupId, opts.fromName, messageBody, mentions);
+                this.autoCreateBridgeOnMention(opts.groupId, opts.fromName, mentions, messageId);
+                this.checkAndCancelBridgesForMessage(opts.groupId, opts.fromName, mentions, messageId);
+                // 链接采集(inline hook,失败不影响主路径)
+                collectLinksFromText(messageBody, {
+                    sourceType: "group_message",
+                    sourceId: String(messageId),
+                    sourceGroupId: opts.groupId,
+                    sourceSender: opts.fromName,
+                }, this.db);
+            }
+            if (!opts.noDispatch && !delivered) {
+                queued = this.offlineQueue.enqueue(result.targetAgentId, opts.fromName, fromAgent.domain || undefined, { message: opts.message }, "exact");
+            }
+        }
+        this.db.logMessage({
+            requestId,
+            fromName: opts.fromName,
+            fromDomain: fromAgent.domain || undefined,
+            toName: result.targetName,
+            toDomain: result.targetAgentId ? this.db.getAgentById(result.targetAgentId)?.domain ?? undefined : undefined,
+            routeType: "exact",
+            direction: "send",
+            payload: JSON.stringify({ message: opts.message }),
+            status: queued ? "queued" : delivered ? "routed" : "no_target",
+            groupId: opts.groupId,
+            source: "cli",
+        });
+        return { requestId, delivered, queued, messageId };
+    },
+};

package/dist/master/ws-hub/directory.js

@@ -0,0 +1,70 @@
+/**
+ * Directory — agent roster broadcast + per-agent config push.
+ *
+ * The directory is a denormalized view of the agents table that every
+ * connected agent holds in memory. Whenever an agent joins, leaves, or
+ * updates its description/profile, master fans out a `directory_update`
+ * to all connected agents so their local copies stay fresh.
+ *
+ * Methods attach via Object.assign. `parseProfile` is shared with hub.ts.
+ */
+import { parseProfile } from "./hub.js";
+export const directoryMethods = {
+    getDirectory() {
+        return this.db.listAgents().map((a) => ({
+            name: a.name,
+            domain: a.domain || undefined,
+            description: a.description || undefined,
+            status: a.status,
+            enabled: a.enabled !== 0,
+            profile: parseProfile(a.profile),
+        }));
+    },
+    /** Push a config_update to a specific connected Agent (called by API layer). */
+    pushConfigUpdate(agentId, config) {
+        const conn = this.connections.get(agentId);
+        if (!conn || conn.ws.readyState !== WebSocket.OPEN)
+            return false;
+        // Update in-memory connection state
+        if (config.domain !== undefined)
+            conn.domain = config.domain;
+        this.send(conn.ws, { type: "config_update", ...config });
+        this.logger.info(`[mesh] Pushed config_update to ${conn.name}: ${JSON.stringify(config)}`);
+        return true;
+    },
+    /** Read agent from DB and broadcast directory_update to all connected agents. */
+    broadcastAgentUpdate(agentId) {
+        const agent = this.db.getAgentById(agentId);
+        if (!agent)
+            return;
+        this.broadcastDirectory("update", {
+            name: agent.name,
+            domain: agent.domain || undefined,
+            description: agent.description || undefined,
+            status: agent.status,
+            enabled: agent.enabled !== 0,
+            profile: parseProfile(agent.profile),
+        });
+    },
+    broadcastDirectory(event, agent) {
+        const msg = { type: "directory_update", event, agent };
+        for (const conn of this.connections.values()) {
+            this.send(conn.ws, msg);
+        }
+    },
+    /**
+     * 返回所有 online agent 的 cliTool 映射(name → cliTool)。
+     * 给 API /agents 列表用 —— DB 不存 cliTool(那是 worker 的运行时属性),
+     * 但 dashboard 想展示"这个 agent 用什么 CLI 跑"。
+     * Offline agent 不在 map 里(没有连接)。
+     */
+    onlineCliTools() {
+        const out = new Map();
+        for (const conn of this.connections.values()) {
+            if (conn.cliTool) {
+                out.set(conn.name, conn.cliTool);
+            }
+        }
+        return out;
+    },
+};

package/dist/master/ws-hub/dispatch-enrich.js

@@ -0,0 +1,34 @@
+/**
+ * dispatch-enrich —— master 在向 worker 发送 WS 消息前,把 `agentProfile` 与
+ * `cwd` 注入 msg 的统一入口。
+ *
+ * 注入字段:
+ *  - `agentProfile`: 从 `agents.profile` JSON 解析;若 groupId 存在,再用
+ *    `group_member_settings.profile` 覆盖(群级别字段优先 merge 到 agent 全局
+ *    profile 上)。worker 收到后更新本地缓存,供 prompt-composer 渲染
+ *    `[Agent 角色]` 层。Dashboard 编辑后下一条 dispatch 即时生效,无需重启 executor。
+ *  - `cwd`: 由 `resolveGroupAgentWorkingDir` 派生,worker 收到后若本机存在该路径
+ *    则覆盖本地派生(跨机器部署时本机无该路径则静默回落)。
+ *
+ * 设计为纯函数,只依赖 `db`,ws-hub method bag 与 api 层都能直接调。
+ */
+import { parseAgentProfile, mergeGroupProfile } from "../../shared/agent-profile.js";
+import { resolveGroupAgentWorkingDir } from "../group-paths.js";
+/** 调用方仅需提供 db(ws-hub method bag 传 this,api 层传 hub 实例)。
+ *  agentName / groupId 任一缺失时跳过对应字段的注入(返回 undefined)。 */
+export function enrichWorkerDispatch(self, msg, agentName, groupId) {
+    const baseProfile = agentName
+        ? (() => {
+            const agent = self.db.getAgentByName(agentName);
+            return agent?.profile ? parseAgentProfile(agent.profile) ?? undefined : undefined;
+        })()
+        : undefined;
+    const groupProfile = agentName && groupId
+        ? parseAgentProfile(self.db.getGroupMemberProfile(groupId, agentName))
+        : null;
+    const profile = mergeGroupProfile(baseProfile, groupProfile);
+    const cwd = agentName && groupId
+        ? resolveGroupAgentWorkingDir(self.db, groupId, agentName)
+        : undefined;
+    return { ...msg, agentProfile: profile, cwd };
+}

package/dist/master/ws-hub/hub.js

@@ -0,0 +1,136 @@
+/**
+ * WSHubCore — constructor, lifecycle, heartbeat / cleanup timers, shared types.
+ *
+ * The class shell here owns the persistent in-memory state (connection map,
+ * pending session requests, snapshot cache) and the wss instance. Domain
+ * modules (./connection.ts, ./routing.ts, ./conversation.ts, ...) attach
+ * their methods to the WSHub class via `Object.assign(this, ...)` in the
+ * composition root (./internal.ts). The `this` inside each method is typed
+ * as `WSHubSelf` — a structural shape that exposes the cross-module surface
+ * (db, auth, router, offlineQueue, logger, connections, send, etc.).
+ *
+ * handleConnection is a single 715-line method that owns its own closure
+ * state (authenticated flag, agentId, generation). It's deliberately kept
+ * intact in ./connection.ts for now — a follow-up PR can split it by
+ * msg.type once we have confidence the dispatch + helper boundaries hold.
+ */
+import { WebSocketServer, WebSocket } from "ws";
+import { HEARTBEAT_CHECK_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, CLEANUP_INTERVAL_MS, PENDING_REQUEST_TTL_MS, WS_MAX_PAYLOAD, } from "../../shared/constants.js";
+export class WSHubCore {
+    db;
+    auth;
+    router;
+    offlineQueue;
+    logger;
+    wss;
+    connections = new Map(); // agentId → conn
+    sendTimestamps = new Map(); // requestId → send timestamp (for latency)
+    heartbeatTimer = null;
+    cleanupTimer = null;
+    generation = 0; // global generation counter — assigned on each successful auth
+    /**
+     * In-flight session management requests awaiting a worker response. Keyed
+     * by requestId; each entry holds a resolver + a setTimeout that fires
+     * routeToExecutor's rejection with a timeout error. Cleaned up in the
+     * session response handler (first response wins, except for broadcasts
+     * which collect all responses until timeout).
+     */
+    pendingSessionRequests = new Map();
+    /**
+     * In-memory cache of each worker's SessionStore. Workers push a
+     * `session_snapshot` after auth and after every mutation; we replace the
+     * entry on receipt. Powers the dashboard's `GET /sessions?groupId=X`
+     * without WS round-trips — fast list, no broadcast.
+     *
+     * Key is `ConnectedAgent.id` (workerAgentId). On disconnect we drop the
+     * entry so offline workers don't surface stale sessions; the next reconnect
+     * re-pushes a snapshot.
+     */
+    sessionSnapshots = new Map();
+    /**
+     * issueId → agentId Set。dashboard 客户端 subscribe_issue_detail 后加入。
+     * issue_usage_progress 只转发给订阅者(不广播、不落 DB)。disconnect 时
+     * 整个 agentId 条目从所有 Set 里清掉。
+     */
+    issueSubscriptions = new Map();
+    qaModeAskers = new Map();
+    constructor(httpServer, db, auth, router, offlineQueue, logger) {
+        this.db = db;
+        this.auth = auth;
+        this.router = router;
+        this.offlineQueue = offlineQueue;
+        this.logger = logger;
+        this.wss = new WebSocketServer({
+            server: httpServer,
+            path: "/ws",
+            maxPayload: WS_MAX_PAYLOAD,
+        });
+    }
+    start() {
+        const self = this;
+        this.wss.on("connection", (ws, req) => self.handleConnection(ws, req));
+        // Periodic heartbeat check
+        this.heartbeatTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [agentId, conn] of this.connections) {
+                if (conn.ws.readyState !== WebSocket.OPEN || now - conn.lastHeartbeat > HEARTBEAT_TIMEOUT_MS) {
+                    const reason = conn.ws.readyState !== WebSocket.OPEN ? "ws_closed" : "heartbeat_timeout";
+                    self.handleDisconnect(agentId, conn.generation, reason);
+                }
+            }
+        }, HEARTBEAT_CHECK_INTERVAL_MS);
+        // Periodic cleanup of sendTimestamps (prevents memory leak)
+        this.cleanupTimer = setInterval(() => {
+            const now = Date.now();
+            for (const [id, ts] of this.sendTimestamps) {
+                if (now - ts > PENDING_REQUEST_TTL_MS) {
+                    this.sendTimestamps.delete(id);
+                }
+            }
+            // Also clean up old logs periodically (every cycle)
+            try {
+                this.db.cleanupOldLogs();
+            }
+            catch { /* non-fatal */ }
+        }, CLEANUP_INTERVAL_MS);
+        this.logger.info("[mesh-master] WebSocket Hub started");
+    }
+    getOnlineCount() {
+        return this.connections.size;
+    }
+    stop() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        if (this.cleanupTimer)
+            clearInterval(this.cleanupTimer);
+        // Close all connections
+        for (const conn of this.connections.values()) {
+            if (conn.ws.readyState === WebSocket.OPEN) {
+                conn.ws.close(1001, "Server shutting down");
+            }
+        }
+        this.connections.clear();
+        this.wss.close();
+    }
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Helpers shared across modules
+// ────────────────────────────────────────────────────────────────────────────
+/** Parse a stored agent profile JSON string. Returns undefined on missing/malformed input. */
+export function parseProfile(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 把 DB 里宽松的 string 收敛成协议枚举。脏数据/空值统一回落到 'r_allow'，
+ * 避免 worker 端把未知值当成 bypass。
+ */
+export function normalizeApprovalPolicy(raw) {
+    return raw === "rw_allow" ? "rw_allow" : "r_allow";
+}

package/dist/master/ws-hub/index.js

@@ -0,0 +1,9 @@
+/**
+ * WS Hub public surface.
+ *
+ * The full implementation lives in `./internal.ts` while handler-by-handler
+ * extraction lands in follow-up PRs (planned: `connection.ts` for the
+ * message-dispatch if-chain, `routing.ts` for broadcasts/issue routing,
+ * `conversation.ts` for enrichment + ask-bridge).
+ */
+export { WSHub } from "./internal.js";

package/dist/master/ws-hub/internal.js

@@ -0,0 +1,35 @@
+/**
+ * WSHub — composition root that wires each domain module's methods onto a
+ * single instance. Public API surface (method names) is unchanged from the
+ * pre-split monolithic version, so the 29 call sites across
+ * `src/master/*.ts` and `tests/*.ts` need no edits.
+ *
+ * Domain modules (./connection.ts, ./routing.ts, ./directory.ts,
+ * ./sessions.ts, ./conversation.ts) export method bags whose `this` is
+ * typed as `WSHubSelf` (declared in ./hub.ts) — a structural shape with the
+ * cross-module surface (db, auth, router, offlineQueue, logger, connections,
+ * send, broadcast, etc.) so methods in one bag can call methods in another.
+ *
+ * The `declare` lines below are purely type annotations: they tell the
+ * TypeScript compiler that the runtime instance (built via Object.assign in
+ * the constructor) has every domain method, without forcing us to duplicate
+ * signatures. Implementations live in the domain modules.
+ */
+import { WSHubCore } from "./hub.js";
+import { connectionMethods } from "./connection.js";
+import { routingMethods } from "./routing.js";
+import { directoryMethods } from "./directory.js";
+import { sessionsMethods } from "./sessions.js";
+import { conversationMethods } from "./conversation.js";
+export class WSHub extends WSHubCore {
+    constructor(httpServer, db, auth, router, offlineQueue, logger) {
+        super(httpServer, db, auth, router, offlineQueue, logger);
+        // Each method bag's `this` resolves to this instance at call time.
+        // The `declare` lines above ensure TypeScript sees these as members.
+        Object.assign(this, connectionMethods);
+        Object.assign(this, routingMethods);
+        Object.assign(this, directoryMethods);
+        Object.assign(this, sessionsMethods);
+        Object.assign(this, conversationMethods);
+    }
+}