@konglx/rotom 2.21.0

package/dist/master/patrol-terminal.js

@@ -0,0 +1,275 @@
+/**
+ * 巡检 issue 终态处理 —— 巡检员完成 patrol issue 后,解析 result JSON 落库。
+ *
+ * 由 server.ts 的 _onIssueTerminal hook 在 issue 进入 terminal 状态时调用。
+ * 跟 e2ed/sync.js 同级,职责单一:解析 result → 写 issue_patrol_logs + finish run。
+ *
+ * 入口分两条路径:
+ *   - handleIssuePatrolTerminal: issue-patrol 巡检员 → 写 issue_patrol_logs
+ *   - handleLinkPatrolIssueTerminal: link-patrol 巡检员 → UPDATE links + 写 link_patrol_logs + memory
+ *
+ * 统一入口 dispatchPatrolTerminal(issue) 先按 issueId 反查 link_patrol_runs,
+ * 命中走 link 流程,否则 fallback 到 issue 流程。
+ */
+import { randomUUID } from "node:crypto";
+import { createLogger } from "../shared/logger.js";
+const log = createLogger("mesh-patrol-terminal");
+/**
+ * 统一入口:issue 终态时 server.ts 调这个。
+ * 优先反查 link_patrol_runs.patrol_issue_id —— 命中走 link 分类流程,
+ * 否则 fallback 到 issue 巡检流程。
+ */
+export function dispatchPatrolTerminal(db, issue) {
+    const linkRun = db.getLinkPatrolRunByIssueId(issue.id);
+    if (linkRun) {
+        handleLinkPatrolIssueTerminal(db, issue);
+        return;
+    }
+    handleIssuePatrolTerminal(db, issue);
+}
+/**
+ * 解析 patrol issue 的 result(JSON 数组),逐条写 issue_patrol_logs,
+ * 并 finish 对应的 run。解析失败 → run status='error'。
+ */
+export function handleIssuePatrolTerminal(db, issue) {
+    const run = db.getPatrolRunByIssueId(issue.id);
+    if (!run) {
+        log.warn(`patrol issue ${issue.id} terminal, but no run found (orphan?)`);
+        return;
+    }
+    // 巡检员把 JSON 放在 issue.result 里。result 可能是裸 JSON,也可能被包在 markdown 代码块里。
+    const raw = (issue.result ?? "").trim();
+    if (!raw) {
+        db.finishPatrolRun(run.run_id, "error", { note: "empty result" });
+        log.warn(`patrol run ${run.run_id}: empty result`);
+        return;
+    }
+    const parsed = parseVerdicts(raw);
+    if (!parsed) {
+        db.finishPatrolRun(run.run_id, "error", { note: `bad result JSON: ${raw.slice(0, 200)}` });
+        log.error(`patrol run ${run.run_id}: bad result JSON`);
+        return;
+    }
+    let readyCount = 0;
+    for (const v of parsed) {
+        const verdict = normalizeVerdict(v.verdict);
+        if (verdict === "ready")
+            readyCount++;
+        db.insertPatrolLog({
+            id: randomUUID(),
+            runId: run.run_id,
+            patrolGroupId: run.patrol_group_id,
+            issueId: v.issue_id ?? null,
+            candidateGroupId: resolveCandidateGroupId(db, v.issue_id),
+            verdict,
+            ruleMatched: v.rule_matched ?? null,
+            rationale: v.rationale ?? null,
+            raw: JSON.stringify(v),
+        });
+    }
+    db.finishPatrolRun(run.run_id, "completed", {
+        scanned: parsed.length,
+        ready: readyCount,
+        note: issue.status === "completed" ? undefined : `issue terminal as ${issue.status}`,
+    });
+    log.info(`patrol run ${run.run_id}: completed (scanned=${parsed.length}, ready=${readyCount})`);
+}
+/**
+ * 解析 link-patrol issue 的 result(JSON 数组),逐条:
+ *   - UPDATE links SET category/tags/title
+ *   - INSERT link_patrol_logs
+ * 然后合并本轮学到的规则写入 agent_memory(scope=global, tags=link_classification)。
+ * 解析失败 → run status='error'。
+ */
+export function handleLinkPatrolIssueTerminal(db, issue) {
+    const run = db.getLinkPatrolRunByIssueId(issue.id);
+    if (!run) {
+        log.warn(`link-patrol issue ${issue.id} terminal, but no run found (orphan?)`);
+        return;
+    }
+    const raw = (issue.result ?? "").trim();
+    if (!raw) {
+        db.finishLinkPatrolRun(run.run_id, "error", { note: "empty result" });
+        log.warn(`link-patrol run ${run.run_id}: empty result`);
+        return;
+    }
+    const parsed = parseLinkVerdicts(raw);
+    if (!parsed) {
+        db.finishLinkPatrolRun(run.run_id, "error", { note: `bad result JSON: ${raw.slice(0, 200)}` });
+        log.error(`link-patrol run ${run.run_id}: bad result JSON`);
+        return;
+    }
+    let classifiedCount = 0;
+    /** 按聚合:同 host 的多 link 共用一条规则 */
+    const rulesByHost = new Map();
+    for (const v of parsed) {
+        const linkId = v.link_id;
+        const category = (v.category ?? "other").toString();
+        const tags = Array.isArray(v.tags)
+            ? v.tags.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim())
+            : [];
+        const title = typeof v.title === "string" ? v.title : null;
+        const rationale = typeof v.rationale === "string" ? v.rationale : null;
+        if (!linkId)
+            continue;
+        const link = db.getLink(linkId);
+        if (!link) {
+            log.warn(`link-patrol: link ${linkId} not found, skip`);
+            continue;
+        }
+        db.updateLinkClassification(linkId, { category, tags, title });
+        db.insertLinkPatrolLog({
+            id: randomUUID(),
+            runId: run.run_id,
+            linkId,
+            category,
+            tags,
+            title,
+            rationale,
+            raw: JSON.stringify(v),
+        });
+        classifiedCount++;
+        // 累积 host 规则
+        const entry = rulesByHost.get(link.host);
+        if (entry) {
+            entry.tagsSet = new Set([...entry.tagsSet, ...tags]);
+        }
+        else {
+            rulesByHost.set(link.host, { category, tagsSet: new Set(tags), sampleLink: link.url_raw });
+        }
+    }
+    // 合并写入 agent_memory(每 host 一条,upsert:同 key 已存在就 update value/tags)
+    for (const [host, info] of rulesByHost.entries()) {
+        upsertLinkRuleMemory(db, issue.group_id, host, info.category, [...info.tagsSet], info.sampleLink, "system:link-patrol");
+    }
+    db.finishLinkPatrolRun(run.run_id, "completed", {
+        classified: classifiedCount,
+        note: issue.status === "completed" ? undefined : `issue terminal as ${issue.status}`,
+    });
+    log.info(`link-patrol run ${run.run_id}: completed (classified=${classifiedCount}, rules_learned=${rulesByHost.size})`);
+}
+/**
+ * 把一条 host 级规则写入 agent_memory,scope=group / group_id=patrolGroupId / category=convention
+ * / tags=["link_classification"]。注意:link-patrol 自动学到的规则放 patrol-link 群,不放 global
+ * —— global namespace 必须人工 review / promote 才能进。下一轮 link-patrol handler 拼 prompt 时
+ * 仍可被 listMemory({ groupId, tags:["link_classification"] }) 拉出。
+ * key = `link_rule:${host}`。同 key 已存在 → 合并 tags,刷新 value;不存在 → INSERT。
+ */
+function upsertLinkRuleMemory(db, groupId, host, category, tags, sampleUrl, createdBy) {
+    const key = `link_rule:${host}`;
+    const existing = db.db.prepare(`SELECT id, tags FROM agent_memory WHERE key = ? AND group_id = ? AND active = 1 LIMIT 1`).get(key, groupId);
+    const value = `host=${host} 默认分类 ${category}; tags=[${tags.join(", ")}]; 样例=${sampleUrl}`;
+    const summary = `${host} → ${category}`;
+    const mergedTags = Array.from(new Set(["link_classification", ...tags]));
+    if (existing) {
+        let oldTags = [];
+        try {
+            const parsed = JSON.parse(existing.tags);
+            if (Array.isArray(parsed))
+                oldTags = parsed.filter((t) => typeof t === "string");
+        }
+        catch { /* ignore */ }
+        const finalTags = Array.from(new Set([...mergedTags, ...oldTags]));
+        db.updateMemory(existing.id, { value, summary, tags: finalTags, category: "convention" });
+    }
+    else {
+        const memId = `mem_link_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+        db.addMemory({
+            id: memId,
+            scope: "group",
+            groupId,
+            category: "convention",
+            sourceType: "manual",
+            key,
+            value,
+            summary,
+            tags: mergedTags,
+            visibility: "group",
+            agentVisible: true,
+            createdBy,
+        });
+    }
+}
+function parseVerdicts(raw) {
+    // 1. 直接 JSON.parse
+    try {
+        const v = JSON.parse(raw);
+        if (Array.isArray(v))
+            return v;
+    }
+    catch { /* fall through */ }
+    // 2. 从 markdown ```json ... ``` 里抠
+    const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenceMatch) {
+        try {
+            const v = JSON.parse(fenceMatch[1]);
+            if (Array.isArray(v))
+                return v;
+        }
+        catch { /* fall through */ }
+    }
+    // 3. 抠最外层 [ ... ]
+    const bracketMatch = raw.match(/\[[\s\S]*\]/);
+    if (bracketMatch) {
+        try {
+            const v = JSON.parse(bracketMatch[0]);
+            if (Array.isArray(v))
+                return v;
+        }
+        catch { /* fall through */ }
+    }
+    return null;
+}
+/** 解析 link-patrol result JSON。复用 parseVerdicts 的三种 fallback,但类型不同。 */
+function parseLinkVerdicts(raw) {
+    try {
+        const v = JSON.parse(raw);
+        if (Array.isArray(v))
+            return v;
+    }
+    catch { /* fall through */ }
+    const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenceMatch) {
+        try {
+            const v = JSON.parse(fenceMatch[1]);
+            if (Array.isArray(v))
+                return v;
+        }
+        catch { /* fall through */ }
+    }
+    const bracketMatch = raw.match(/\[[\s\S]*\]/);
+    if (bracketMatch) {
+        try {
+            const v = JSON.parse(bracketMatch[0]);
+            if (Array.isArray(v))
+                return v;
+        }
+        catch { /* fall through */ }
+    }
+    return null;
+}
+function normalizeVerdict(v) {
+    if (!v)
+        return "uncertain";
+    const s = String(v).toLowerCase().replace(/[-\s]/g, "_");
+    if (s === "ready")
+        return "ready";
+    if (s === "not_ready")
+        return "not_ready";
+    if (s === "uncertain")
+        return "uncertain";
+    if (s === "skipped")
+        return "skipped";
+    // 兜底:关键字猜测
+    if (s.includes("ready") && !s.includes("not"))
+        return "ready";
+    if (s.includes("not_ready") || s.includes("not ready"))
+        return "not_ready";
+    return "uncertain";
+}
+function resolveCandidateGroupId(db, issueId) {
+    if (!issueId)
+        return null;
+    const issue = db.getIssueById(issueId);
+    return issue?.group_id ?? null;
+}

package/dist/master/repo-scan.js

@@ -0,0 +1,188 @@
+/**
+ * Master 侧的 worktree 扫描(只读)。
+ *
+ * worktree 物理上在 executor 本机(`~/.rotom/repos/`),但 master 与 executor
+ * 同机部署时可直接读 FS 暴露给 Dashboard。跨机器时本模块返回空列表(本机无缓存)。
+ *
+ * 不依赖 executor/repo-cache.ts(那是 executor 侧 spawn git 的模块),这里独立
+ * 实现 scan 逻辑,保持 master/executor 模块边界清晰。算法与 repo-cache 一致:
+ *   - repoId = SHA-1(归一化 URL) 前 12 位
+ *   - repoName = URL 最后一段(去 .git)
+ *   - bare 目录名 = <repoName>-<repoId8>.git
+ *   - worktree 根 = <repoName>-<repoId8>-wt/<slot>/
+ *
+ * slot 推算:group 模式 = `group-<groupId8>`,issue 模式 = `<issueId8>`。
+ * Dashboard 用这个推算"当前 group 的 worktree 应该在哪"。
+ */
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const REPOS_ROOT = path.join(os.homedir(), ".rotom", "repos");
+export function repoIdFor(url) {
+    let u = url.trim();
+    if (u.endsWith(".git"))
+        u = u.slice(0, -4);
+    u = u.replace(/^ssh:\/\/([^@]+@)?/, "").replace(/^https?:\/\//, "");
+    u = u.replace(/^git@/, "").replace(/\/$/, "");
+    return createHash("sha1").update(u).digest("hex").slice(0, 12);
+}
+export function repoNameFor(url) {
+    let u = url.trim();
+    if (u.endsWith(".git"))
+        u = u.slice(0, -4);
+    u = u.split("?")[0].split("#")[0].replace(/\/$/, "");
+    const last = u.split("/").pop() || "repo";
+    return last || "repo";
+}
+/** bare clone 路径(不查 FS,只算)。 */
+export function barePathForUrl(url) {
+    const repoId = repoIdFor(url);
+    const repoName = repoNameFor(url);
+    return path.join(REPOS_ROOT, `${repoName}-${repoId.slice(0, 8)}.git`);
+}
+/** worktree 路径(不查 FS,只算)。slot 由调用方决定(group-<groupId8> 或 <issueId8>)。 */
+export function worktreePathForUrl(url, slot) {
+    const repoId = repoIdFor(url);
+    const repoName = repoNameFor(url);
+    return path.join(REPOS_ROOT, `${repoName}-${repoId.slice(0, 8)}-wt`, slot);
+}
+/** 推算 group 模式下某 group 的 worktree 路径。 */
+export function groupWorktreePath(url, groupId) {
+    return worktreePathForUrl(url, `group-${groupId.slice(0, 8)}`);
+}
+function runGitSync(args, opts) {
+    const r = spawnSync("git", args, {
+        cwd: opts?.cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        ok: r.status === 0,
+        stdout: typeof r.stdout === "string" ? r.stdout : "",
+        stderr: typeof r.stderr === "string" ? r.stderr : "",
+    };
+}
+function dirSize(p) {
+    let total = 0;
+    try {
+        const walk = (dir) => {
+            for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, e.name);
+                if (e.isDirectory())
+                    walk(full);
+                else if (e.isFile()) {
+                    try {
+                        total += fs.statSync(full).size;
+                    }
+                    catch { /* skip */ }
+                }
+            }
+        };
+        walk(p);
+    }
+    catch { /* skip */ }
+    return total;
+}
+/**
+ * 扫描本机 `~/.rotom/repos/`,列出所有 bare clone 及其 worktree。
+ * 本机无 repos 目录(跨机器部署 master 不在 executor 机器)时返回空数组。
+ */
+export function scanAllRepos() {
+    if (!fs.existsSync(REPOS_ROOT))
+        return [];
+    const entries = fs.readdirSync(REPOS_ROOT, { withFileTypes: true });
+    const result = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || !e.name.endsWith(".git"))
+            continue;
+        const repoKey = e.name.slice(0, -4); // 去 .git
+        const bp = path.join(REPOS_ROOT, e.name);
+        // repoName = 去掉最后一段 -<repoId8>
+        const lastDash = repoKey.lastIndexOf("-");
+        const repoName = lastDash > 0 ? repoKey.slice(0, lastDash) : repoKey;
+        const wtList = runGitSync(["worktree", "list", "--porcelain"], { cwd: bp });
+        const worktrees = [];
+        if (wtList.ok) {
+            let cur = {};
+            for (const line of wtList.stdout.split("\n")) {
+                if (line.startsWith("worktree ")) {
+                    if (cur.path)
+                        worktrees.push(cur);
+                    cur = { path: line.slice("worktree ".length), branch: "", head: "" };
+                }
+                else if (line.startsWith("HEAD ")) {
+                    cur.head = line.slice("HEAD ".length).slice(0, 8);
+                }
+                else if (line.startsWith("branch ")) {
+                    const ref = line.slice("branch ".length);
+                    cur.branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+                }
+                else if (line === "") {
+                    if (cur.path)
+                        worktrees.push(cur);
+                    cur = {};
+                }
+            }
+            if (cur.path)
+                worktrees.push(cur);
+        }
+        // 第一条是 bare clone 自己,过滤掉
+        const realWorktrees = worktrees.filter(w => !w.path.endsWith(".git"));
+        result.push({
+            repoKey,
+            repoName,
+            barePath: bp,
+            worktrees: realWorktrees,
+            sizeBytes: dirSize(bp),
+        });
+    }
+    return result;
+}
+/**
+ * 推算某 group 的 worktree 信息(用于 Dashboard 显示"当前 worktree")。
+ *
+ * 返回:
+ *  - 若 group 没配 repo_url → null
+ *  - 若配了 → { url, branch, mode, primaryPath, extraRepos[], exists }
+ *    primaryPath 是推算路径(group 模式 slot = group-<groupId8>);
+ *    exists 表示该路径在本机 FS 是否已存在(executor 是否已创建)。
+ */
+export function resolveGroupWorktreeInfo(db, groupId) {
+    const group = db.getGroupById(groupId);
+    if (!group)
+        return null;
+    const url = group.repo_url?.trim();
+    if (!url)
+        return null;
+    const branch = group.repo_default_branch?.trim() || null;
+    const mode = group.worktree_mode === "issue" ? "issue" : "group";
+    const slot = mode === "group" ? `group-${groupId.slice(0, 8)}` : "issue-mode";
+    const primaryPath = worktreePathForUrl(url, slot);
+    const primaryExists = fs.existsSync(primaryPath);
+    let extras = [];
+    if (group.extra_repos) {
+        try {
+            const parsed = JSON.parse(group.extra_repos);
+            if (Array.isArray(parsed)) {
+                extras = parsed
+                    .filter((e) => !!e && typeof e === "object" && typeof e.id === "string" && typeof e.url === "string" && typeof e.mountPath === "string")
+                    .map(e => {
+                    const extraSlot = mode === "group" ? `group-${groupId.slice(0, 8)}` : "issue-mode";
+                    const p = worktreePathForUrl(e.url, extraSlot);
+                    return {
+                        id: e.id,
+                        url: e.url,
+                        branch: typeof e.branch === "string" && e.branch ? e.branch : null,
+                        mountPath: e.mountPath,
+                        path: p,
+                        exists: fs.existsSync(p),
+                    };
+                });
+            }
+        }
+        catch { /* malformed */ }
+    }
+    return { url, branch, mode, primaryPath, primaryExists, extras };
+}

package/dist/master/router.js

@@ -0,0 +1,214 @@
+/**
+ * Digital Employee Mesh — Router
+ *
+ * One routing mode: exact.
+ * Router only makes decisions — it does NOT send messages.
+ * WSHub reads the result and handles actual delivery.
+ */
+import { MessageDedup } from "../shared/dedup.js";
+import { DEDUP_TTL_MS, CLEANUP_INTERVAL_MS, PENDING_REQUEST_TTL_MS, } from "../shared/constants.js";
+import { parseAgentRef } from "../shared/protocol/federation.js";
+/** Sentinel fromAgentId for federated pending requests(本地 ws-hub 永远不会拿这个 id 去路由) */
+export const FEDERATED_REPLY_MARKER = "__federation__";
+export class Router {
+    db;
+    logger;
+    dedup = new MessageDedup(DEDUP_TTL_MS);
+    pendingRequests = new Map();
+    cleanupTimer;
+    /** Federation 客户端(member 模式);standalone 时为 undefined */
+    fedClient;
+    /** 已加入的 teamId(用于查 agent_visibility 缓存) */
+    teamId;
+    /** 本机 hostname(用于 from.hostname 字段) */
+    localHostname;
+    /** Federation 回复 hook:本地 agent 回复 federated 请求时调用,由 FederationManager 注入 */
+    fedReplyHook;
+    constructor(db, logger) {
+        this.db = db;
+        this.logger = logger;
+        // Periodic cleanup of dedup and pending requests
+        this.cleanupTimer = setInterval(() => {
+            this.dedup.cleanup();
+            const now = Date.now();
+            for (const [id, entry] of this.pendingRequests) {
+                if (now - entry.createdAt > PENDING_REQUEST_TTL_MS) {
+                    this.pendingRequests.delete(id);
+                }
+            }
+        }, CLEANUP_INTERVAL_MS);
+    }
+    /**
+     * 注入 federation 客户端(member 模式时由 server.ts 调用)。
+     * 注入后 Router 才会走 federated 路由分支。
+     */
+    setFederation(client, teamId, localHostname) {
+        this.fedClient = client;
+        this.teamId = teamId;
+        this.localHostname = localHostname;
+    }
+    /**
+     * Federation deliver 入口:协调 master / member 收到 FedDeliver 后调这个,
+     * 让本机 WSHub 投递到目标本地 agent。
+     * 返回 true=已找到目标并投递(由调用方实际 send)。
+     */
+    handleFedDeliver(msg, sendToLocal) {
+        // to.name 在本机查
+        const target = this.db.getLocalAgentByName(msg.to.name)
+            ?? this.db.getAgentByName(msg.to.name);
+        if (!target)
+            return false;
+        return sendToLocal(target.name, msg.payload);
+    }
+    /** Federation reply 入口:FedReply 到达后,resolve pendingRequest 路由回来源 */
+    handleFedReply(msg, sendReply) {
+        const entry = this.pendingRequests.get(msg.requestId);
+        if (entry) {
+            sendReply(entry.fromAgentId, msg.payload);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Public API
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Route a message. Returns a decision (targetAgentId) — caller handles delivery.
+     */
+    route(fromAgentId, msg) {
+        // Dedup
+        if (this.dedup.isDuplicate(msg.requestId)) {
+            return { delivered: false, queued: false, error: "Duplicate message" };
+        }
+        this.dedup.mark(msg.requestId);
+        // Resolve sender info
+        const fromAgent = this.db.getAgentById(fromAgentId);
+        const fromName = fromAgent?.name || "unknown";
+        const fromDomain = fromAgent?.domain;
+        const summary = (msg.payload?.message || "").slice(0, 100);
+        // Record for reply correlation (preserve conversation for reply path)
+        this.pendingRequests.set(msg.requestId, { fromAgentId, createdAt: Date.now(), conversation: msg.conversation });
+        // Route
+        if (msg.target) {
+            return this.routeExact(fromAgentId, fromName, fromDomain, msg.target, summary, msg.requestId, msg.payload);
+        }
+        return { delivered: false, queued: false, error: "No target specified" };
+    }
+    /**
+     * Resolve the original sender for a reply. Returns agentId or undefined.
+     * Does NOT consume the entry — allows multi-round replies on the same requestId.
+     * Entry is cleaned up by TTL instead.
+     */
+    resolveReplyTarget(requestId) {
+        const entry = this.pendingRequests.get(requestId);
+        if (entry) {
+            entry.createdAt = Date.now();
+            return entry.fromAgentId;
+        }
+        return undefined;
+    }
+    /** 查询 requestId 是否来自 federation(本地 agent 回复时若为 true,走 fedReplyHook 而非 sendToAgent) */
+    isFederatedRequest(requestId) {
+        return this.pendingRequests.get(requestId)?.isFederated === true;
+    }
+    /**
+     * 注册一个 federated 来源的 pending request。
+     *
+     * 协调 master / member 收到 FedDeliver 投到本地 agent 之前调用。
+     * fromAgentId 用一个 sentinel,使 ws-hub 的 sendToAgent 不会真投递到任何本地 agent
+     * (实际上 ws-hub reply handler 在 isFederated 时会改走 fedReplyHook,不会 sendToAgent)。
+     */
+    registerFederatedPendingRequest(requestId, conversation) {
+        this.pendingRequests.set(requestId, {
+            fromAgentId: FEDERATED_REPLY_MARKER,
+            createdAt: Date.now(),
+            conversation,
+            isFederated: true,
+        });
+    }
+    /** 消费并清掉一个 federated pending request(成功 dispatch reply 后调用) */
+    consumeFederatedPendingRequest(requestId) {
+        return this.pendingRequests.delete(requestId);
+    }
+    /**
+     * Get the conversation context associated with a pending request.
+     */
+    getConversation(requestId) {
+        return this.pendingRequests.get(requestId)?.conversation;
+    }
+    stop() {
+        clearInterval(this.cleanupTimer);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Private routing methods
+    // ═══════════════════════════════════════════════════════════════════════════
+    routeExact(_fromId, fromName, fromDomain, targetName, summary, requestId, payload) {
+        // 1. 本机 agent 查询(优先 hostname 复合键,fallback 全局 name)
+        const target = this.db.getLocalAgentByName(targetName)
+            ?? this.db.getAgentByName(targetName);
+        if (target) {
+            // Check if target agent is disabled
+            if (target.enabled === 0) {
+                this.db.audit({ fromName, fromDomain, toName: target.name, toDomain: target.domain, routeType: "exact", result: "rejected", messageSummary: summary });
+                return { delivered: false, queued: false, error: `Agent "${targetName}" is disabled` };
+            }
+            if (!this.db.canCrossDomain(fromDomain, target.domain)) {
+                this.db.audit({ fromName, fromDomain, toName: target.name, toDomain: target.domain, routeType: "exact", result: "rejected", messageSummary: summary });
+                return { delivered: false, queued: false, error: "Cross-domain not allowed" };
+            }
+            this.db.audit({ fromName, fromDomain, toName: target.name, toDomain: target.domain, routeType: "exact", result: "routed", messageSummary: summary });
+            return { targetAgentId: target.id, targetName: target.name, delivered: false, queued: false };
+        }
+        // 2. 本机找不到 → 走 federation 路由(如果配了)
+        if (this.fedClient && this.teamId && requestId && payload) {
+            const fedResult = this.routeFederated(fromName, targetName, requestId, payload, summary);
+            if (fedResult)
+                return fedResult;
+        }
+        this.db.audit({ fromName, fromDomain, toName: targetName, routeType: "exact", result: "failed", messageSummary: summary });
+        return { delivered: false, queued: false, error: `Agent "${targetName}" not found` };
+    }
+    /**
+     * 跨 master 路由:解析 targetName(alice@hostB 或裸 alice)→ 查 agent_visibility
+     * → 调 federationClient.route 发 FedRouteMessage。
+     */
+    routeFederated(fromName, targetName, requestId, payload, summary) {
+        if (!this.fedClient || !this.teamId || !this.localHostname)
+            return null;
+        const ref = parseAgentRef(targetName);
+        let targetMasterId;
+        let targetHostname;
+        if (ref.hostname && ref.hostname !== this.localHostname) {
+            // 形如 "alice@hostB" → 按 (hostname, name) 反查
+            const vis = this.db.findVisibleAgentByHostAndName(this.teamId, ref.hostname, ref.name);
+            if (!vis)
+                return null;
+            targetMasterId = vis.master_id;
+            targetHostname = vis.hostname;
+        }
+        else {
+            // 裸 name → 按 name 反查(department 内必须唯一)
+            const candidates = this.db.findVisibleAgentsByName(this.teamId, ref.name);
+            if (candidates.length === 0)
+                return null;
+            if (candidates.length > 1) {
+                this.db.audit({ fromName, toName: targetName, routeType: "federated", result: "failed", messageSummary: `ambiguous: ${candidates.length} matches` });
+                return { delivered: false, queued: false, error: `Ambiguous agent "${ref.name}" across masters (use name@hostname)` };
+            }
+            targetMasterId = candidates[0].master_id;
+            targetHostname = candidates[0].hostname;
+        }
+        // 发 FedRouteMessage 给协调 master(由协调 master 转 FedDeliver)
+        const ok = this.fedClient.route(requestId, { hostname: this.localHostname, name: fromName }, { hostname: targetHostname, name: ref.name }, { message: payload.message, files: payload.files });
+        if (!ok) {
+            return { delivered: false, queued: false, error: "Federation client not connected" };
+        }
+        this.db.audit({
+            fromName,
+            toName: `${ref.name}@${targetHostname}`,
+            routeType: "federated",
+            result: "routed",
+            messageSummary: summary,
+        });
+        // delivered=true 告诉 WSHub 不要再尝试本地投递
+        return { delivered: true, queued: false, targetName: `${ref.name}@${targetHostname}` };
+    }
+}