@konglx/rotom 2.21.0

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

@@ -0,0 +1,295 @@
+/**
+ * Routing — send/broadcast primitives and issue-coordination pushes.
+ *
+ * Lower-level transport helpers (send / sendToAgent / broadcastToGroup) plus
+ * the issue-system notifications (assignment / approval / chat cancel /
+ * continue / append / new issue / change). All of these are pure routing —
+ * no message-handler logic lives here. Methods attach via Object.assign.
+ */
+import { WebSocket } from "ws";
+import { extractMentions } from "../../shared/mention.js";
+import { normalizeApprovalPolicy } from "./hub.js";
+import { enrichWorkerDispatch } from "./dispatch-enrich.js";
+import { resolveIssueRepoCtxLocalOnly } from "../group-paths.js";
+export const routingMethods = {
+    // ─────────────────────────────────────────────────────────────────────────
+    // Low-level transport
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Send a message to a connected agent. Returns false if not connected. */
+    sendToAgent(agentId, msg) {
+        const conn = this.connections.get(agentId);
+        if (!conn || conn.ws.readyState !== WebSocket.OPEN)
+            return false;
+        this.send(conn.ws, msg);
+        return true;
+    },
+    /** Lowest-level transport: serialize + ws.send. Public since connection,
+     *  directory, and conversation modules all need to push directly. */
+    send(ws, msg) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(msg));
+        }
+    },
+    /**
+     * Broadcast a message to all group members EXCEPT those in excludeAgentIds.
+     * Used for group message visibility — messages/replies are broadcast so all
+     * group members see them in real-time.
+     */
+    broadcastToGroup(groupId, msg, excludeAgentIds = []) {
+        const members = this.db.getGroupMembers(groupId);
+        const delivered = [];
+        for (const member of members) {
+            const memberAgent = this.db.getAgentByName(member.agent_name);
+            if (!memberAgent)
+                continue;
+            if (excludeAgentIds.includes(memberAgent.id))
+                continue;
+            const ok = this.sendToAgent(memberAgent.id, msg);
+            delivered.push({ name: member.agent_name, sent: ok });
+        }
+        // 流式 chunk 广播会每 chunk 调一次,记日志只会刷屏,跳过;其他类型
+        // （a2a_send 等）的广播日志保留,方便排查投递问题。
+        const isStreamingChunk = msg.type === "a2a_stream_chunk";
+        if (!isStreamingChunk) {
+            this.logger.info(`[mesh] broadcastToGroup ${groupId}: ${delivered.length} members, results=${JSON.stringify(delivered)}`);
+        }
+    },
+    /**
+     * Public entry point for broadcasting a group message from outside the hub
+     * (e.g. REST handlers in api/groups.ts). Thin wrapper over the private
+     * broadcastToGroup — keeps the internal helper encapsulated.
+     */
+    broadcastToGroupPublic(groupId, msg, excludeAgentIds = []) {
+        this.broadcastToGroup(groupId, msg, excludeAgentIds);
+    },
+    /**
+     * 发一条 sender=system 的群消息:入库 + 实时广播给在线群成员。
+     * 用于协作流转类消息(启动 / 进入下一轮 / 结束),让群里所有人同步看到状态。
+     * - excludeAgentNames:不往这些成员的 WS 推,但消息仍然入库。用于避免 @ 的对象被双触发。
+     * - ensureRecipientNames:保证这些 agent 能收到(即便它不在群成员里)。
+     *   用于 mention 了非群成员(如协作 firstParticipant 不在群里)的场景。
+     */
+    postSystemToGroup(groupId, content, excludeAgentNames = [], ensureRecipientNames = []) {
+        this.logger.info(`[mesh] postSystemToGroup groupId=${groupId} exclude=${JSON.stringify(excludeAgentNames)} ensure=${JSON.stringify(ensureRecipientNames)}`);
+        const mentions = extractMentions(content);
+        this.db.addGroupMessage(groupId, "system", content, mentions);
+        const excludeAgentIds = excludeAgentNames
+            .map((name) => this.db.getAgentByName(name)?.id)
+            .filter((id) => !!id);
+        const wireMsg = {
+            type: "a2a_message",
+            requestId: `sys-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            from: { name: "system", status: "online" },
+            payload: { message: content },
+            routeType: "exact",
+            conversation: { type: "group", groupId },
+        };
+        // 1) 推给群成员
+        this.broadcastToGroup(groupId, wireMsg, excludeAgentIds);
+        // 2) 保证这些 recipient 收到(即便它不在群里);与 broadcast 去重
+        const memberNames = new Set(this.db.getGroupMembers(groupId).map((m) => m.agent_name));
+        for (const name of ensureRecipientNames) {
+            if (excludeAgentNames.includes(name))
+                continue;
+            if (memberNames.has(name))
+                continue; // already covered by broadcastToGroup
+            const agent = this.db.getAgentByName(name);
+            if (!agent) {
+                this.logger.warn(`[mesh] postSystemToGroup: ensure recipient "${name}" not registered`);
+                continue;
+            }
+            const ok = this.sendToAgent(agent.id, wireMsg);
+            this.logger.info(`[mesh] postSystemToGroup ensure delivery → ${name}: sent=${ok}`);
+        }
+    },
+    // ─────────────────────────────────────────────────────────────────────────
+    // Issue system (task coordination)
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Push issue assignment notification to a specific executor agent. */
+    pushIssueAssignment(issueId, agentName) {
+        const issue = this.db.getIssueById(issueId);
+        if (!issue)
+            return false;
+        const agent = this.db.getAgentByName(agentName);
+        if (!agent)
+            return false;
+        const repo = resolveIssueRepoCtxLocalOnly(this.db, issue);
+        return this.sendToAgent(agent.id, enrichWorkerDispatch(this, {
+            type: "issue_assigned",
+            issueId: issue.id,
+            groupId: issue.group_id,
+            title: issue.title,
+            description: issue.description,
+            workingDir: issue.working_dir || undefined,
+            slashCommand: issue.slash_command || undefined,
+            approvalPolicy: normalizeApprovalPolicy(issue.approval_policy),
+            ...(repo ? { repoUrl: repo.repoUrl, repoBranch: repo.repoBranch, extraRepos: repo.extraRepos } : {}),
+        }, agentName, issue.group_id));
+    },
+    /**
+     * Push the user's approval decision to the worker that owns the parked
+     * codex JSON-RPC request. Returns false when the issue has no assignee or
+     * the assignee is offline (REST layer should still record the decision so
+     * it sticks once the agent reconnects).
+     */
+    pushApprovalResponse(issueId, approvalId, decision, feedback) {
+        const issue = this.db.getIssueById(issueId);
+        if (!issue?.assigned_to)
+            return false;
+        const agent = this.db.getAgentByName(issue.assigned_to);
+        if (!agent)
+            return false;
+        return this.sendToAgent(agent.id, {
+            type: "issue_approval_response",
+            issueId,
+            approvalId,
+            decision,
+            ...(decision === "deny" && feedback ? { feedback } : {}),
+        });
+    },
+    /**
+     * Push a chat-stream cancellation to the responder worker. The responder
+     * is the agent currently generating a reply (the dashboard knows its name
+     * from the streaming bubble's `from` field). Returns false when the agent
+     * is unknown or offline — in that case the stream is already broken (WS
+     * disconnect killed the subprocess via existing cleanup paths), so the
+     * HTTP caller can no-op.
+     *
+     * Worker-side: looks up `activeTasks["chat:" + requestId]`, flips aborted,
+     * and calls controller.abort() so the CLI executor kills its subprocess.
+     * If the task already completed naturally before this arrives, the worker
+     * logs "no active task" and returns — idempotent.
+     */
+    pushChatCancel(agentName, requestId, reason) {
+        const agent = this.db.getAgentByName(agentName);
+        if (!agent)
+            return false;
+        return this.sendToAgent(agent.id, {
+            type: "chat_cancelled",
+            requestId,
+            agentName,
+            ...(reason ? { reason } : {}),
+        });
+    },
+    /**
+     * Push a user-supplied follow-up prompt to the assigned worker so it can
+     * spawn its CLI with `--resume <sessionId>` (or start fresh when sessionId
+     * is missing) and continue the conversation. Returns false when the issue
+     * has no assignee or the assignee is offline.
+     */
+    pushIssueContinue(issueId, prompt) {
+        const issue = this.db.getIssueById(issueId);
+        if (!issue?.assigned_to)
+            return false;
+        const agent = this.db.getAgentByName(issue.assigned_to);
+        if (!agent)
+            return false;
+        const repo = resolveIssueRepoCtxLocalOnly(this.db, issue);
+        return this.sendToAgent(agent.id, enrichWorkerDispatch(this, {
+            type: "issue_continue",
+            issueId,
+            groupId: issue.group_id,
+            title: issue.title,
+            prompt,
+            sessionId: issue.session_id || undefined,
+            workingDir: issue.working_dir || undefined,
+            slashCommand: issue.slash_command || undefined,
+            approvalPolicy: normalizeApprovalPolicy(issue.approval_policy),
+            ...(repo ? { repoUrl: repo.repoUrl, repoBranch: repo.repoBranch, extraRepos: repo.extraRepos } : {}),
+        }, issue.assigned_to, issue.group_id));
+    },
+    /**
+     * Push an append-while-active prompt. Worker queues it onto the running
+     * task and consumes the queue when the current CLI invocation finishes
+     * (continuing with --resume <sessionId> if one is available). Distinct
+     * from pushIssueContinue, which the master only fires AFTER the issue
+     * has reached completed/failed.
+     */
+    pushIssueAppend(issueId, prompt) {
+        const issue = this.db.getIssueById(issueId);
+        if (!issue?.assigned_to)
+            return false;
+        const agent = this.db.getAgentByName(issue.assigned_to);
+        if (!agent)
+            return false;
+        const repo = resolveIssueRepoCtxLocalOnly(this.db, issue);
+        return this.sendToAgent(agent.id, enrichWorkerDispatch(this, {
+            type: "issue_append",
+            issueId,
+            groupId: issue.group_id,
+            title: issue.title,
+            prompt,
+            sessionId: issue.session_id || undefined,
+            workingDir: issue.working_dir || undefined,
+            slashCommand: issue.slash_command || undefined,
+            approvalPolicy: normalizeApprovalPolicy(issue.approval_policy),
+            ...(repo ? { repoUrl: repo.repoUrl, repoBranch: repo.repoBranch, extraRepos: repo.extraRepos } : {}),
+        }, issue.assigned_to, issue.group_id));
+    },
+    /** Broadcast to all connected agents that a new issue is available. */
+    notifyNewIssue(issueId, groupId, title, createdBy) {
+        const msg = {
+            type: "issue_created",
+            issueId, groupId, title, createdBy,
+        };
+        for (const conn of this.connections.values()) {
+            this.send(conn.ws, msg);
+        }
+    },
+    /**
+     * Notify the issue's group of a change so dashboards can refresh without
+     * polling. Safe to call after any DB write touching the issue.
+     */
+    notifyIssueChanged(issueId, groupId, kind) {
+        if (!groupId)
+            return;
+        this.broadcastToGroup(groupId, { type: "issue_changed", issueId, groupId, kind });
+    },
+    /**
+     * Add this agentId to the issue's subscriber set. Idempotent — re-subscribe
+     * on reconnect is safe. Used by dashboard clients to opt into
+     * issue_usage_progress pushes for the issue they're viewing.
+     */
+    subscribeIssue(issueId, agentId) {
+        let set = this.issueSubscriptions.get(issueId);
+        if (!set) {
+            set = new Set();
+            this.issueSubscriptions.set(issueId, set);
+        }
+        set.add(agentId);
+    },
+    /** Remove this agentId from the issue's subscriber set (no-op if absent). */
+    unsubscribeIssue(issueId, agentId) {
+        const set = this.issueSubscriptions.get(issueId);
+        if (!set)
+            return;
+        set.delete(agentId);
+        if (set.size === 0)
+            this.issueSubscriptions.delete(issueId);
+    },
+    /**
+     * Remove this agentId from ALL issue subscriptions. Called on disconnect /
+     * "Replaced by new connection" to prevent pushes to dead sockets. Iterating
+     * a snapshot via Array.from avoids mutating-during-iteration if cleanup
+     * deletes the Set (which would also delete the Map entry).
+     */
+    unsubscribeAllIssues(agentId) {
+        for (const issueId of Array.from(this.issueSubscriptions.keys())) {
+            this.unsubscribeIssue(issueId, agentId);
+        }
+    },
+    /**
+     * Push a ServerMessage to every agent currently subscribed to the issue.
+     * Used for issue_usage_progress — explicitly NOT a broadcast, since usage
+     * pushes are high-frequency (1Hz during execution) and only the client
+     * viewing that issue's detail cares.
+     */
+    sendToIssueSubscribers(issueId, msg) {
+        const set = this.issueSubscriptions.get(issueId);
+        if (!set || set.size === 0)
+            return;
+        for (const agentId of set) {
+            this.sendToAgent(agentId, msg);
+        }
+    },
+};

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

@@ -0,0 +1,130 @@
+/**
+ * Session management — Master ↔ Executor session routing.
+ *
+ * Dashboard 的 `/sessions` 端点现在直接读 master DB 的 `agent_sessions` 表
+ * (替代了之前的 in-memory `sessionSnapshots` 缓存)。worker 仍然推
+ * `session_snapshot`,master 在 connection.ts 里 upsert 到 DB + 更新内存
+ * 缓存(缓存保留给 online 判定 + routeToExecutor 用)。
+ *
+ * `routeToExecutor` 是反向:master 把 view/delete 请求转发给匹配的 worker,
+ * 取第一个响应。
+ *
+ * Methods attach via Object.assign.
+ */
+export const sessionsMethods = {
+    /**
+     * 列出该群所有 session(包括已失效的),按最近使用倒序。数据源是 DB。
+     * online 字段由 connections 内存表 join 算出:该 session 的 (agentName,
+     * cliTool) 对应的 worker 当前是否 WS 连着。
+     *
+     * `GET /sessions?groupId=X` 的快路径。
+     */
+    listSessionsByGroup(groupId) {
+        const rows = this.db.listAgentSessionsByGroup(groupId);
+        // 算 online:agent_name + cli_tool 同时匹配某个 connected worker
+        const onlineKeys = new Set();
+        for (const conn of this.connections.values()) {
+            if (conn.ws.readyState !== WebSocket.OPEN)
+                continue;
+            if (!conn.cliTool)
+                continue;
+            onlineKeys.add(`${conn.name}:${conn.cliTool}`);
+        }
+        return rows.map(r => {
+            const online = onlineKeys.has(`${r.agent_name}:${r.cli_tool}`);
+            const entry = {
+                cliTool: r.cli_tool,
+                groupId: r.group_id,
+                sessionId: r.session_id,
+                agentName: r.agent_name,
+                usage: (r.input_tokens == null && r.output_tokens == null && r.total_cost_usd == null)
+                    ? null
+                    : {
+                        inputTokens: r.input_tokens ?? undefined,
+                        outputTokens: r.output_tokens ?? undefined,
+                        cacheReadTokens: r.cache_read_tokens ?? undefined,
+                        cacheCreationTokens: r.cache_creation_tokens ?? undefined,
+                        totalCostUsd: r.total_cost_usd ?? undefined,
+                    },
+                model: r.model ?? null,
+                cumulativeCostUsd: r.cumulative_cost_usd,
+                cumulativeInputTokens: r.cumulative_input_tokens,
+                cumulativeOutputTokens: r.cumulative_output_tokens,
+                cumulativeCacheReadTokens: r.cumulative_cache_read_tokens,
+                cumulativeCacheCreationTokens: r.cumulative_cache_creation_tokens,
+                online,
+                invalidatedAt: r.invalidated_at,
+            };
+            return entry;
+        });
+    },
+    /**
+     * 反查单条 session 的 usage/model/cumulative/online/invalidatedAt。
+     * `GET /sessions/:.../usage` 用。直接读 DB,不再依赖 worker 在线。
+     */
+    findSessionEntry(sessionId) {
+        const r = this.db.findAgentSession(sessionId);
+        if (!r)
+            return undefined;
+        let online = false;
+        for (const conn of this.connections.values()) {
+            if (conn.ws.readyState !== WebSocket.OPEN)
+                continue;
+            if (conn.name === r.agent_name && conn.cliTool === r.cli_tool) {
+                online = true;
+                break;
+            }
+        }
+        return {
+            cliTool: r.cli_tool,
+            groupId: r.group_id,
+            sessionId: r.session_id,
+            agentName: r.agent_name,
+            usage: (r.input_tokens == null && r.output_tokens == null && r.total_cost_usd == null)
+                ? null
+                : {
+                    inputTokens: r.input_tokens ?? undefined,
+                    outputTokens: r.output_tokens ?? undefined,
+                    cacheReadTokens: r.cache_read_tokens ?? undefined,
+                    cacheCreationTokens: r.cache_creation_tokens ?? undefined,
+                    totalCostUsd: r.total_cost_usd ?? undefined,
+                },
+            model: r.model ?? null,
+            cumulativeCostUsd: r.cumulative_cost_usd,
+            cumulativeInputTokens: r.cumulative_input_tokens,
+            cumulativeOutputTokens: r.cumulative_output_tokens,
+            cumulativeCacheReadTokens: r.cumulative_cache_read_tokens,
+            cumulativeCacheCreationTokens: r.cumulative_cache_creation_tokens,
+            online,
+            invalidatedAt: r.invalidated_at,
+        };
+    },
+    /**
+     * Send a request to one or more online workers matching `predicate` and
+     * return the **first** response received within `timeoutMs`. Other responses
+     * (including late ones) are dropped.
+     *
+     * Used by /sessions endpoints:
+     *   - view:   predicate = cliTool match,        timeoutMs = 5s
+     *   - delete: predicate = cliTool match,        timeoutMs = 5s
+     *
+     * Rejects with a TimeoutError if no worker answers in time. The HTTP layer
+     * maps that to a 504.
+     */
+    routeToExecutor(predicate, payload, timeoutMs = 5_000) {
+        const targets = [...this.connections.values()].filter((c) => c.ws.readyState === WebSocket.OPEN && predicate(c));
+        if (targets.length === 0) {
+            return Promise.reject(new Error("no matching executor online"));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingSessionRequests.delete(payload.requestId);
+                reject(new Error(`executor did not respond within ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pendingSessionRequests.set(payload.requestId, { resolve, reject, timer });
+            for (const conn of targets) {
+                this.send(conn.ws, payload);
+            }
+        });
+    },
+};

package/dist/master/ws-hub.js

@@ -0,0 +1,11 @@
+/**
+ * Backwards-compatible facade for the WebSocket hub.
+ *
+ * Implementation has moved into `./ws-hub/`:
+ *   • `./ws-hub/internal.ts` — WSHub runtime class (still monolithic; handler
+ *                              extraction lands in follow-up PRs)
+ *   • `./ws-hub/index.ts`    — Public surface
+ *
+ * Existing callers (`import { WSHub } from "./ws-hub.js"`) continue to work.
+ */
+export * from "./ws-hub/index.js";

package/dist/shared/agent-profile.js

@@ -0,0 +1,44 @@
+/**
+ * Agent 档案 —— `agents.profile` 列存的 JSON 字符串的解析。
+ *
+ * 字段定义见 `src/shared/protocol.ts:AgentProfile`(本文件 re-export 保持旧 import path 兼容)。
+ * 本文件只做"JSON 字符串 → 强类型"还原,容忍 null/损坏输入(返回 null 而不是抛错,
+ * 因为运行时 prompt 渲染可以接受缺角色)。
+ */
+export function parseAgentProfile(json) {
+    if (!json)
+        return null;
+    try {
+        const obj = JSON.parse(json);
+        if (!obj || typeof obj !== "object")
+            return null;
+        const out = {};
+        if (typeof obj.category === "string")
+            out.category = obj.category;
+        if (typeof obj.position === "string")
+            out.position = obj.position;
+        if (typeof obj.bio === "string")
+            out.bio = obj.bio;
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 群级别 profile 覆盖 merge 到 agent 全局 profile 上,群级别非 undefined 字段胜出。
+ * 供 dispatch-enrich(WS 推送 self profile)与 GET /groups/:id(返回群成员花名册)共用,
+ * 避免两份 merge 逻辑漂移。
+ */
+export function mergeGroupProfile(base, group) {
+    if (!group)
+        return base ?? undefined;
+    const merged = { ...(base ?? {}) };
+    if (typeof group.category === "string")
+        merged.category = group.category;
+    if (typeof group.position === "string")
+        merged.position = group.position;
+    if (typeof group.bio === "string")
+        merged.bio = group.bio;
+    return merged;
+}

package/dist/shared/constants.js

@@ -0,0 +1,55 @@
+/**
+ * Digital Employee Mesh — Constants
+ */
+/** Protocol version — bump when wire format changes (v2: field ownership + config_update) */
+export const PROTOCOL_VERSION = 2;
+/** Default Master WebSocket port */
+export const DEFAULT_MASTER_PORT = 28800;
+/** Default Master bind host */
+export const DEFAULT_MASTER_HOST = "0.0.0.0";
+/** Agent heartbeat interval (ms) */
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+/** Master heartbeat timeout — disconnect if no heartbeat for this long (ms) */
+export const HEARTBEAT_TIMEOUT_MS = 90_000;
+/** Master heartbeat check interval (ms) */
+export const HEARTBEAT_CHECK_INTERVAL_MS = 30_000;
+/** Auth timeout — Agent must authenticate within this time (ms) */
+export const AUTH_TIMEOUT_MS = 10_000;
+/** JWT expiration */
+export const JWT_EXPIRY = "7d";
+/** JWT algorithm */
+export const JWT_ALGORITHM = "HS256";
+/** Offline message TTL (24 hours) */
+export const OFFLINE_MESSAGE_TTL_HOURS = 24;
+/** Offline message per-agent limit */
+export const OFFLINE_MESSAGE_LIMIT = 100;
+/** Message dedup TTL (5 minutes) */
+export const DEDUP_TTL_MS = 5 * 60 * 1000;
+/** Pending request TTL — reply correlation expires after this (5 minutes) */
+export const PENDING_REQUEST_TTL_MS = 5 * 60 * 1000;
+/** Cleanup interval for dedup and pending requests (60 seconds) */
+export const CLEANUP_INTERVAL_MS = 60_000;
+/** Agent reconnect base delay (ms) */
+export const RECONNECT_BASE_DELAY_MS = 1_000;
+/** Agent reconnect max delay (ms) */
+export const RECONNECT_MAX_DELAY_MS = 30_000;
+/** WebSocket max payload size (1 MB) — prevents OOM from oversized messages */
+export const WS_MAX_PAYLOAD = 1_048_576;
+/** Per-agent rate limit: max messages per window */
+export const RATE_LIMIT_MAX = 60;
+/** Rate limit sliding window (ms) */
+export const RATE_LIMIT_WINDOW_MS = 60_000;
+/** Audit / message log retention (days) */
+export const LOG_RETENTION_DAYS = 30;
+/** Max concurrent inbound dispatches per agent */
+export const MAX_CONCURRENT_DISPATCHES = 10;
+/** WebSocket close codes */
+export const WS_CLOSE = {
+    AUTH_TIMEOUT: 4001,
+    AUTH_FAILED: 4002,
+    INVALID_JSON: 4400,
+    NOT_AUTHENTICATED: 4401,
+    RATE_LIMITED: 4429,
+};
+/** 合法的 issue 状态(对应 issues.status 列,见 migrations/008-issues.sql) */
+export const ISSUE_STATUSES = ["open", "in_progress", "completed", "failed", "cancelled"];

package/dist/shared/dedup.js

@@ -0,0 +1,33 @@
+/**
+ * Message deduplication — in-memory requestId → timestamp map with TTL cleanup.
+ */
+export class MessageDedup {
+    seen = new Map();
+    ttlMs;
+    constructor(ttlMs = 5 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    /** Returns true if this requestId was seen recently (within TTL). */
+    isDuplicate(requestId) {
+        const ts = this.seen.get(requestId);
+        if (!ts)
+            return false;
+        if (Date.now() - ts > this.ttlMs) {
+            this.seen.delete(requestId);
+            return false;
+        }
+        return true;
+    }
+    /** Mark a requestId as seen. */
+    mark(requestId) {
+        this.seen.set(requestId, Date.now());
+    }
+    /** Evict entries older than TTL. Call periodically (e.g. every 60s). */
+    cleanup() {
+        const now = Date.now();
+        for (const [id, ts] of this.seen) {
+            if (now - ts > this.ttlMs)
+                this.seen.delete(id);
+        }
+    }
+}

package/dist/shared/group-context.js

@@ -0,0 +1,62 @@
+/**
+ * Group context prompt injection — shared by InboundDispatcher and ExecutorWorker.
+ *
+ * Prepends group metadata (groupId, groupName, selfName) to the prompt so that
+ * any CLI-backed agent knows which group it is responding in.
+ */
+function renderActiveIssues(issues) {
+    if (!issues || issues.length === 0) {
+        return (`[当前群活跃 issue]\n` +
+            `无\n` +
+            `提示：本群当前没有进行中的 issue。如需修改文件，请先 \`rotom issue create\` 建任务承载，否则只允许 Read/Grep/Glob。\n`);
+    }
+    const lines = issues.map((it) => {
+        const id = it.id.slice(0, 8);
+        const owner = it.assignedTo ? ` by ${it.assignedTo}` : " 未认领";
+        const prio = it.priority ? ` [${it.priority}]` : "";
+        return `- #${id}  ${it.status}${prio}  "${it.title}"${owner}`;
+    });
+    return (`[当前群活跃 issue]\n` +
+        lines.join("\n") + "\n" +
+        `提示：涉及文件改动请关联以上某个 issue;若无匹配的,先 \`rotom issue create\` 新建,确认 in_progress 后再写盘。\n`);
+}
+/**
+ * If `conversation` represents a group chat, return the prompt wrapped with
+ * group-context metadata; otherwise return the prompt unchanged.
+ */
+export function injectGroupContext(prompt, conversation, selfName) {
+    const isGroup = conversation?.type === "group" && !!conversation.groupId;
+    if (!isGroup)
+        return prompt;
+    const groupId = conversation.groupId;
+    const groupName = conversation.groupName || groupId;
+    const header = `[群消息 context: groupId=${groupId}, groupName="${groupName}", ` +
+        `你自己是="${selfName}"。` +
+        `重要：如果 @ 的是你自己（"${selfName}"），那就是在叫你回答，直接回答即可，` +
+        `不要再调用发送消息给自己。]\n`;
+    const issuesBlock = renderActiveIssues(conversation.activeIssues);
+    return `${header}${issuesBlock}\n${prompt}`;
+}
+/**
+ * Prefix the prompt with the working directory so CLI agents resolve paths
+ * (`src/foo.ts` etc.) consistently with the cwd we pass to spawn(). The
+ * spawn cwd alone is invisible to the model — it only sees the prompt text.
+ *
+ * No-op when cwd is empty (e.g. fallback to executor default).
+ *
+ * Read-only semantics: the working directory is a **read-only** mount for the
+ * agent. The agent may Read / Grep / Glob / Bash (read-only commands) but
+ * must NOT call Write / Edit or any other disk-mutating tool on paths under
+ * this directory. Cross-machine deployments enforce this so each executor
+ * machine's local FS doesn't diverge.
+ */
+export function prependWorkingDir(prompt, cwd) {
+    if (!cwd)
+        return prompt;
+    return (`[artifacts目录] ${cwd}\n` +
+        `所有相对路径基于此目录解析；spawn 的子进程 cwd 已设置在这里，` +
+        `Read/Grep/Glob 直接用相对路径即可，不要用 \`cd\` 切换到其他目录。\n` +
+        `**重要：此目录为只读，agent 仅可 Read/Grep/Glob/Bash（只读命令），不得调用 Write/Edit 等写盘工具。**\n` +
+        `需要持久化的产出请通过 issue 评论 / artifact 工具回传 master，或用 Bash 写到非 workingDir 的沙箱目录。\n\n` +
+        prompt);
+}

package/dist/shared/json-codec.js

@@ -0,0 +1,33 @@
+/**
+ * JSON frame encode/decode helpers shared across the three transport sites
+ * that previously each hand-rolled `JSON.stringify` / `JSON.parse`:
+ *   - executor/jsonrpc-transport.ts (stdio newline-delimited JSON-RPC)
+ *   - executor/worker-connection.ts  (agent-protocol WebSocket)
+ *   - master/terminal-hub.ts         (browser xterm WebSocket)
+ *
+ * `encodeJsonLine` adds the trailing newline that the stdio JSON-RPC
+ * transport needs; WS callers use plain `JSON.stringify` since the socket
+ * is message-framed.
+ *
+ * `decodeJson` returns `undefined` on parse failure — callers decide whether
+ * to silently drop (WS hubs) or log a warning (JSON-RPC transport with its
+ * own labelled warn). Passing the raw Buffer through keeps a `toString()`
+ * allocation out of the WS hot path.
+ */
+export function encodeJsonLine(msg) {
+    return JSON.stringify(msg) + "\n";
+}
+export function decodeJson(data) {
+    try {
+        if (typeof data === "string")
+            return JSON.parse(data);
+        if (Array.isArray(data))
+            return JSON.parse(Buffer.concat(data).toString());
+        if (data instanceof ArrayBuffer)
+            return JSON.parse(Buffer.from(data).toString());
+        return JSON.parse(data.toString());
+    }
+    catch {
+        return undefined;
+    }
+}