@konglx/rotom 2.21.0

package/dist/master/federation/client.js

@@ -0,0 +1,283 @@
+/**
+ * Federation Client —— member master 主动连协调 master。
+ *
+ * Member 是 outbound 主动连接,所以**移动电脑/笔记本切网无影响**(只要协调 master
+ * 地址稳定)。断网自动重连,3s backoff,最多 30s。
+ *
+ * 职责(Phase 2):
+ *   1. 读 ~/.rotom/team.json → 启动 client
+ *   2. 连协调 master(/federation 路径)
+ *   3. 握手 FedHandshake → 处理 FedHandshakeAck(HOSTNAME_CONFLICT 时停止重连)
+ *   4. 维护本地 agent_visibility 缓存(从 FedDirectorySync 同步)
+ *   5. 提供 route() 接口给 Router 用 → 封装 FedRouteMessage 发给协调
+ *   6. 提供 publish() / unpublish() 给 publisher.ts 用
+ *   7. 接收 FedDeliver → 投递到本地 agent(通过 handlers.deliverLocal)
+ *   8. 接收 FedReply → 路由回本地 pendingRequests
+ */
+import WebSocket from "ws";
+import { FED_PROTOCOL_VERSION, isFedMessage, } from "../../shared/protocol/federation.js";
+import { createLogger } from "../../shared/logger.js";
+const log = createLogger("fed-client");
+export class FedClient {
+    db;
+    opts;
+    ws = null;
+    reconnectTimer;
+    connected = false;
+    handshakeAccepted = false;
+    stopped = false;
+    handlers = {};
+    constructor(db, opts) {
+        this.db = db;
+        this.opts = opts;
+    }
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        if (this.ws) {
+            try {
+                this.ws.close(1000, "fed client stopping");
+            }
+            catch { /* ignore */ }
+            this.ws = null;
+        }
+        this.connected = false;
+        this.handshakeAccepted = false;
+    }
+    setHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    isConnected() {
+        return this.connected && this.handshakeAccepted;
+    }
+    /** 发消息到协调 master(握手成功后才有 ws) */
+    send(msg) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.handshakeAccepted)
+            return false;
+        this.ws.send(JSON.stringify(msg));
+        return true;
+    }
+    /** Router 调:把消息跨 master 投递(协调 master 中转到目标) */
+    route(requestId, from, to, payload, conversation) {
+        return this.send({
+            type: "fed_route",
+            teamId: this.opts.teamId,
+            requestId,
+            from,
+            to,
+            payload,
+            conversation,
+        });
+    }
+    /** publisher.ts 调:上报本地 agent 状态 */
+    publish(agents) {
+        if (!this.handshakeAccepted)
+            return false;
+        return this.send({
+            type: "fed_agent_publish",
+            teamId: this.opts.teamId,
+            masterId: this.opts.identity.id,
+            hostname: this.opts.identity.hostname,
+            agents: agents.map((a) => ({
+                hostname: this.opts.identity.hostname,
+                name: a.name,
+                displayName: a.displayName,
+                isHuman: a.isHuman,
+                online: a.online,
+            })),
+        });
+    }
+    unpublish(agentNames) {
+        if (!this.handshakeAccepted)
+            return false;
+        return this.send({
+            type: "fed_agent_unpublish",
+            teamId: this.opts.teamId,
+            masterId: this.opts.identity.id,
+            agents: agentNames.map((name) => ({ hostname: this.opts.identity.hostname, name })),
+        });
+    }
+    /**
+     * Member 本地 agent 给一个 federated 请求回了消息 → 发 FedReply 给协调 master,
+     * 协调 master 广播给所有 member(含发起方),发起方 FedClient.handleReply 用 requestId
+     * 反查自己 pendingRequests 解 promise。
+     */
+    reply(requestId, from, payload) {
+        return this.send({
+            type: "fed_reply",
+            requestId,
+            from,
+            payload,
+        });
+    }
+    // ─── 内部 ─────────────────────────────────────────────────────────────────
+    connect() {
+        if (this.stopped)
+            return;
+        const endpoint = this.opts.coordEndpoints[0];
+        if (!endpoint) {
+            log.error("[fed-client] no coord endpoint configured");
+            return;
+        }
+        const url = endpoint.replace(/\/$/, "") + "/federation";
+        log.info(`[fed-client] connecting to ${url}...`);
+        try {
+            this.ws = new WebSocket(url);
+        }
+        catch (err) {
+            log.error(`[fed-client] ws construct failed: ${err.message}`);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.on("open", () => this.handleOpen());
+        this.ws.on("message", (raw) => this.handleMessage(raw.toString()));
+        this.ws.on("close", (code, reason) => this.handleClose(code, reason.toString()));
+        this.ws.on("error", (err) => {
+            log.error(`[fed-client] ws error: ${err.message}`);
+        });
+    }
+    handleOpen() {
+        log.info("[fed-client] connected, sending handshake...");
+        this.connected = true;
+        this.handshakeAccepted = false;
+        // 握手(无认证,只声明身份)
+        const handshake = {
+            type: "fed_handshake",
+            masterId: this.opts.identity.id,
+            hostname: this.opts.identity.hostname,
+            role: this.opts.role,
+            protocol: FED_PROTOCOL_VERSION,
+        };
+        this.ws?.send(JSON.stringify(handshake));
+        // 握手超时(10s)
+        setTimeout(() => {
+            if (!this.handshakeAccepted && this.ws) {
+                log.warn("[fed-client] handshake timeout, closing");
+                try {
+                    this.ws.close(4401, "handshake timeout");
+                }
+                catch { /* ignore */ }
+            }
+        }, 10_000);
+    }
+    handleMessage(raw) {
+        let msg;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!isFedMessage(parsed)) {
+                log.warn("[fed-client] invalid fed message");
+                return;
+            }
+            msg = parsed;
+        }
+        catch {
+            log.warn("[fed-client] invalid JSON");
+            return;
+        }
+        if (!this.handshakeAccepted) {
+            if (msg.type === "fed_handshake_ack") {
+                this.handleHandshakeAck(msg);
+                return;
+            }
+            log.warn(`[fed-client] pre-handshake unexpected: ${msg.type}`);
+            return;
+        }
+        switch (msg.type) {
+            case "fed_directory_sync":
+                return this.handleDirectorySync(msg);
+            case "fed_deliver":
+                return this.handleDeliver(msg);
+            case "fed_reply":
+                return this.handleReply(msg);
+            case "fed_route_failed":
+                return this.handleRouteFailed(msg);
+            case "fed_handshake_ack":
+                log.warn("[fed-client] duplicate handshake_ack, ignoring");
+                return;
+            default:
+                // 其他类型(publish/unpublish/route)是 member → coord 方向,member 不该收到
+                log.warn(`[fed-client] unexpected message type: ${msg.type}`);
+        }
+    }
+    handleHandshakeAck(msg) {
+        if (!msg.accepted) {
+            log.error(`[fed-client] handshake rejected: ${msg.error ?? "unknown"}`);
+            if (msg.error === "HOSTNAME_CONFLICT") {
+                log.error(`[fed-client] hostname "${this.opts.identity.hostname}" already taken in team — change ROTOM_HOSTNAME and restart`);
+                // 不重连,等用户改 hostname
+                this.stopped = true;
+            }
+            try {
+                this.ws?.close(4404, msg.error ?? "rejected");
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        this.handshakeAccepted = true;
+        log.info(`[fed-client] joined team ${msg.teamId} (coord=${msg.serverMasterId}/${msg.serverHostname})`);
+    }
+    handleDirectorySync(msg) {
+        // 全量 upsert + remove(简单实现:Phase 3 可优化为 diff)
+        if (msg.remove.length > 0) {
+            // remove 需要逐条删
+            for (const r of msg.remove) {
+                this.db.removeVisibleAgent(msg.teamId, r.masterId, r.name);
+            }
+        }
+        if (msg.upsert.length > 0) {
+            // upsert 全量替换:简单起见,先 clear 再 insert(Phase 3 优化)
+            // 注意只 clear 非本机的(本机的由 publisher 维护)
+            const localMasterId = this.opts.identity.id;
+            const all = this.db.listVisibleAgents(msg.teamId);
+            for (const r of all) {
+                if (r.master_id !== localMasterId) {
+                    this.db.removeVisibleAgent(msg.teamId, r.master_id, r.agent_name);
+                }
+            }
+            for (const u of msg.upsert) {
+                if (u.masterId === localMasterId)
+                    continue; // 不缓存自己
+                this.db.upsertVisibleAgent({
+                    team_id: msg.teamId,
+                    master_id: u.masterId,
+                    agent_name: u.name,
+                    hostname: u.hostname,
+                    display_name: u.displayName,
+                    is_human: u.isHuman,
+                    online: u.online,
+                });
+            }
+        }
+    }
+    handleDeliver(msg) {
+        const ok = this.handlers.deliverLocal?.(msg) ?? false;
+        if (!ok) {
+            log.warn(`[fed-client] local deliver failed for requestId=${msg.requestId}`);
+        }
+    }
+    handleReply(msg) {
+        this.handlers.handleReply?.(msg);
+    }
+    handleRouteFailed(msg) {
+        this.handlers.handleRouteFailed?.(msg);
+    }
+    handleClose(code, reason) {
+        this.connected = false;
+        this.handshakeAccepted = false;
+        this.ws = null;
+        log.info(`[fed-client] disconnected (code=${code}, reason=${reason})`);
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = setTimeout(() => this.connect(), 3_000);
+    }
+}

package/dist/master/federation/identity.js

@@ -0,0 +1,133 @@
+/**
+ * Master identity — masterId 生成、hostname 解析与校验、role 解析。
+ *
+ * masterId 是 8 字符 base36 小写短 ID(36^8 ≈ 2.8 万亿),首次启动生成、
+ * 持久化在 `~/.rotom/master.json`,之后永远稳定。机器换网络 / 改 IP / 改
+ * os.hostname 都不影响 masterId —— 它是路由的真正主键,IP 不可靠。
+ *
+ * hostname 仅作显示用(`alice@hostA`),不是路由键;但启动时强制校验拒绝 IP,
+ * 因为移动电脑 IP 会变。优先级:
+ *   ROTOM_HOSTNAME 环境变量 > ~/.rotom/hostname 文件 > os.hostname()
+ *
+ * role 同样每次启动从 ROTOM_MASTER_ROLE 解析;Phase 1 实际只启用 standalone 行为,
+ * coordination/member 的语义在 Phase 2 federation 落地后才有意义。
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+const ID_LENGTH = 8;
+const ID_PATTERN = /^[0-9a-z]{8}$/;
+// IPv4 字面量: 192.168.1.1 / 10.0.0.1
+const IPV4_PATTERN = /^\d{1,3}(\.\d{1,3}){3}$/;
+// IPv6 字面量(粗略:包含 : 的十六进制串)
+const IPV6_PATTERN = /^[0-9a-fA-F:]+$/;
+const MAX_HOSTNAME_LEN = 63;
+/** 生成一个 8 字符 base36 小写 masterId。 */
+export function generateMasterId() {
+    const bytes = crypto.randomBytes(ID_LENGTH);
+    let out = "";
+    for (let i = 0; i < ID_LENGTH; i++) {
+        out += ALPHABET[bytes[i] % ALPHABET.length];
+    }
+    return out;
+}
+/**
+ * 校验 hostname 是否合法。拒绝 IP 字面量(移动电脑 IP 不稳定)、空串、超长串。
+ * 注意:`localhost`、`.local` mDNS 名等不拒绝 —— 由用户判断是否稳定。
+ */
+export function isValidHostname(name) {
+    if (!name || typeof name !== "string")
+        return false;
+    if (name.length === 0 || name.length > MAX_HOSTNAME_LEN)
+        return false;
+    if (IPV4_PATTERN.test(name))
+        return false;
+    if (name.includes(":") && IPV6_PATTERN.test(name))
+        return false;
+    return true;
+}
+/**
+ * 解析本机 master 身份。首次启动会生成 masterId 并写入 `~/.rotom/master.json`;
+ * 后续启动读回 masterId(永远稳定),hostname / role 则每次重新解析(可变)。
+ *
+ * @throws 如果 hostname 校验失败(IP 字面量、空串等)
+ */
+export function getMasterIdentity(opts = {}) {
+    const rotomHome = opts.rotomHome || process.env.ROTOM_HOME || path.join(os.homedir(), ".rotom");
+    const masterJsonPath = path.join(rotomHome, "master.json");
+    const hostname = resolveHostname(rotomHome);
+    if (!isValidHostname(hostname)) {
+        throw new Error(`Invalid hostname "${hostname}". ` +
+            `Set ROTOM_HOSTNAME to a stable machine name ` +
+            `(IP literals are not allowed because laptop IPs change across networks).`);
+    }
+    const role = resolveRole();
+    // teamName 优先级:ROTOM_TEAM_NAME 环境变量 > master.json 持久化值 > undefined(由 OPC bootstrap 兜底)
+    // OPC bootstrap 会查本机真人 agent,用其 name + "团队" 作默认(如"西花团队")
+    const storedTeamName = readStoredIdentity(masterJsonPath)?.teamName;
+    const teamName = resolveTeamName() ?? storedTeamName ?? "";
+    let stored = readStoredIdentity(masterJsonPath);
+    if (!stored || !ID_PATTERN.test(stored.id)) {
+        stored = {
+            id: generateMasterId(),
+            hostname,
+            role,
+            teamName: teamName || undefined,
+            createdAt: new Date().toISOString(),
+        };
+        writeStoredIdentity(masterJsonPath, stored);
+    }
+    return { id: stored.id, hostname, role, teamName };
+}
+/** 解析 ROTOM_HOME(给外部模块用,避免重复实现)。 */
+export function resolveRotomHome() {
+    return process.env.ROTOM_HOME || path.join(os.homedir(), ".rotom");
+}
+function resolveHostname(rotomHome) {
+    const fromEnv = process.env.ROTOM_HOSTNAME;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    const hostnameFile = path.join(rotomHome, "hostname");
+    try {
+        const raw = fs.readFileSync(hostnameFile, "utf-8").trim();
+        if (raw)
+            return raw;
+    }
+    catch {
+        // 文件不存在,fallback
+    }
+    return os.hostname();
+}
+function resolveRole() {
+    const raw = process.env.ROTOM_MASTER_ROLE;
+    if (raw === "standalone" || raw === "coordination" || raw === "member") {
+        return raw;
+    }
+    return "standalone";
+}
+/** 解析团队展示名。优先 ROTOM_TEAM_NAME 环境变量,否则用 master.json 里的,否则 = hostname。 */
+function resolveTeamName() {
+    const fromEnv = process.env.ROTOM_TEAM_NAME;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    return undefined;
+}
+function readStoredIdentity(p) {
+    try {
+        const raw = fs.readFileSync(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.id === "string" && typeof parsed.hostname === "string" && typeof parsed.role === "string") {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeStoredIdentity(p, identity) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(identity, null, 2) + "\n", "utf-8");
+}

package/dist/master/federation/manager.js

@@ -0,0 +1,267 @@
+/**
+ * FederationManager —— federation 子系统的运行时管理器。
+ *
+ * 把 fedClient / fedPublisher / fedServer 的创建/启动/停止封装在一起,
+ * 让 API 层(POST /api/teams/join / leave)能在 master 运行时切换 federation 状态,
+ * 不需要重启 master。
+ *
+ * 生命周期:
+ *   - initFromRole():master 启动时调用,根据 identity.role 启动对应子系统
+ *   - joinTeam(teamId, coordEndpoints):runtime 从 standalone 切到 member
+ *   - leaveTeam():runtime 从 member 切回 standalone
+ *
+ * 单例:server.ts 初始化一次,API 层通过 getFederationManager() 访问。
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { FedServer } from "./server.js";
+import { FedClient } from "./client.js";
+import { FedPublisher } from "./publisher.js";
+import { SelfPublisher } from "./self-publisher.js";
+import { createLogger } from "../../shared/logger.js";
+const log = createLogger("fed-manager");
+export class FederationManager {
+    opts;
+    fedClient = null;
+    fedPublisher = null;
+    fedServer = null;
+    fedSelfPublisher = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Master 启动时调用:根据 identity.role + team.json 启动对应子系统 */
+    initFromRole() {
+        const { identity, db, hub, router, httpServer, rotomHome, masterPort } = this.opts;
+        if (identity.role === "member") {
+            const teamConfigPath = path.join(rotomHome, "team.json");
+            if (fs.existsSync(teamConfigPath)) {
+                this.startMember(JSON.parse(fs.readFileSync(teamConfigPath, "utf-8")));
+            }
+            else {
+                log.warn(`role=member but no ${teamConfigPath} — falling back to standalone`);
+            }
+        }
+        else if (identity.role === "coordination") {
+            this.startCoordination();
+        }
+    }
+    /** Runtime:从 standalone 切到 member,连协调 master */
+    async joinTeam(input) {
+        if (this.fedClient) {
+            throw new Error("Already a member of a team — leave first");
+        }
+        const { identity, db, hub, router, rotomHome } = this.opts;
+        // 1. 连协调 master,握手拿 teamId(协调的 masterId)
+        const teamId = await this.fetchCoordIdentity(input.coordEndpoint);
+        const teamName = input.teamName || `团队@${identity.hostname}`;
+        // 2. 写 team.json
+        const teamConfigPath = path.join(rotomHome, "team.json");
+        fs.writeFileSync(teamConfigPath, JSON.stringify({
+            id: teamId,
+            name: teamName,
+            coord_endpoints: [input.coordEndpoint],
+        }, null, 2) + "\n", "utf-8");
+        // 3. 建本地 team 行(本机视角)
+        if (!db.getTeam(teamId)) {
+            db.insertTeam({
+                id: teamId,
+                name: teamName,
+                my_role: "member",
+                coord_endpoints: input.coordEndpoint,
+            });
+        }
+        // 4. 启动 fedClient + fedPublisher
+        this.startMember({ id: teamId, name: teamName, coord_endpoints: [input.coordEndpoint] });
+        return { teamId, teamName };
+    }
+    /** Runtime:离开团队,切回 standalone */
+    leaveTeam() {
+        const { rotomHome, db, router } = this.opts;
+        // 停 fedClient + fedPublisher
+        this.fedPublisher?.stop();
+        this.fedClient?.stop();
+        this.fedPublisher = null;
+        this.fedClient = null;
+        // 撤回 Router 的 federation 注入
+        // (setFederation 接受 undefined?不,签名要求 client。简单起见用类型断言)
+        router.fedClient = undefined;
+        router.teamId = undefined;
+        // 删 team.json
+        const teamConfigPath = path.join(rotomHome, "team.json");
+        try {
+            fs.unlinkSync(teamConfigPath);
+        }
+        catch { /* 不存在 */ }
+        // 清本地 team 行 + peer 缓存 + agent_visibility 缓存
+        const teams = db.listTeams();
+        for (const t of teams) {
+            if (t.my_role === "member") {
+                db.clearPeers(t.id);
+                db.clearVisibleAgents(t.id);
+                db.deleteTeam(t.id);
+            }
+        }
+        log.info("Left team — back to standalone");
+    }
+    getRole() {
+        return this.opts.identity.role;
+    }
+    getFedClient() {
+        return this.fedClient;
+    }
+    // ─── 内部 ─────────────────────────────────────────────────────────────
+    /** 拉协调 master 的 /api/identity 拿 masterId(作 teamId) */
+    async fetchCoordIdentity(coordEndpoint) {
+        const httpUrl = coordEndpoint
+            .replace(/^wss:/, "https:")
+            .replace(/^ws:/, "http:")
+            .replace(/\/$/, "");
+        const res = await fetch(`${httpUrl}/api/identity`);
+        if (!res.ok) {
+            throw new Error(`Failed to fetch coord identity: ${res.status} ${res.statusText}`);
+        }
+        const data = await res.json();
+        if (data.role !== "coordination") {
+            throw new Error(`Target master is not a coordination master (role=${data.role})`);
+        }
+        return data.id;
+    }
+    startMember(teamCfg) {
+        const { identity, db, hub, router } = this.opts;
+        this.fedClient = new FedClient(db, {
+            identity,
+            coordEndpoints: teamCfg.coord_endpoints,
+            teamId: teamCfg.id,
+            role: "member",
+        });
+        this.fedClient.setHandlers({
+            deliverLocal: (msg) => {
+                const target = db.getLocalAgentByName(msg.to.name) ?? db.getAgentByName(msg.to.name);
+                if (!target)
+                    return false;
+                const fromAgent = db.getAgentByName(msg.from.name);
+                const fromInfo = {
+                    name: msg.from.name,
+                    status: "online",
+                    domain: fromAgent?.domain ?? undefined,
+                    description: fromAgent?.description ?? undefined,
+                    enabled: (fromAgent?.enabled ?? 1) !== 0,
+                };
+                // 注册 federated pending request,让本地 agent 的 a2a_reply 走 fedReplyHook
+                router.registerFederatedPendingRequest(msg.requestId, msg.conversation);
+                return hub.sendToAgent(target.id, {
+                    type: "a2a_message",
+                    requestId: msg.requestId,
+                    from: fromInfo,
+                    payload: msg.payload,
+                    routeType: "federated",
+                    conversation: msg.conversation,
+                });
+            },
+            handleReply: (msg) => {
+                const targetId = router.resolveReplyTarget(msg.requestId);
+                if (!targetId)
+                    return;
+                hub.sendToAgent(targetId, {
+                    type: "a2a_reply",
+                    requestId: msg.requestId,
+                    from: msg.from.name,
+                    payload: msg.payload,
+                });
+            },
+            handleRouteFailed: (msg) => {
+                // Member 端发起跨机请求(本机 alice 经 fedClient.route 给 B 上 carol)失败时,
+                // 把失败当作 a2a_reply 回给本机 alice,让 CLI/worker 拿到错误。
+                // 注意:这里 router.pendingRequests 里 entry 是 isFederated=false(本机发起,
+                // 不是远端投来),所以不用 consumeFederatedPendingRequest。
+                // MVP:member 起发起跨机请求是 Phase 4 群组跨机场景,这里先 log + reject 思路 stub。
+                log.warn(`[fed-manager] route_failed for requestId=${msg.requestId} reason=${msg.reason} ` +
+                    `to=${msg.to?.name}@${msg.to?.hostname} — Phase 4 才接 member 端 PendingRequests reject`);
+            },
+        });
+        this.fedClient.start();
+        router.setFederation(this.fedClient, teamCfg.id, identity.hostname);
+        // 本地 agent 给 federated 请求回复 → 通过 fedClient 把 FedReply 发给协调 master
+        router.fedReplyHook = (requestId, fromName, payload) => {
+            if (!this.fedClient)
+                return;
+            this.fedClient.reply(requestId, { hostname: identity.hostname, name: fromName }, payload);
+            router.consumeFederatedPendingRequest(requestId);
+        };
+        this.fedPublisher = new FedPublisher(db, this.fedClient, { teamId: teamCfg.id });
+        this.fedPublisher.start();
+        log.info(`Started member mode — team=${teamCfg.id}, endpoints=${teamCfg.coord_endpoints.join(",")}`);
+    }
+    startCoordination() {
+        const { identity, db, httpServer, masterPort, router } = this.opts;
+        const teamId = identity.id;
+        const teamName = identity.teamName || `${identity.hostname} 团队`;
+        if (!db.getTeam(teamId)) {
+            db.insertTeam({
+                id: teamId,
+                name: teamName,
+                my_role: "coordination",
+                coord_endpoints: `ws://${identity.hostname}:${masterPort}`,
+            });
+        }
+        db.upsertPeer({
+            team_id: teamId,
+            master_id: identity.id,
+            hostname: identity.hostname,
+            role: "coordination",
+        });
+        this.fedServer = new FedServer(httpServer, db, { identity, teamId });
+        this.fedServer.setHandlers({
+            deliverLocal: (msg) => {
+                const { hub, db, router } = this.opts;
+                const target = db.getLocalAgentByName(msg.to.name) ?? db.getAgentByName(msg.to.name);
+                if (!target)
+                    return false;
+                const fromAgent = db.getAgentByName(msg.from.name);
+                const fromInfo = {
+                    name: msg.from.name,
+                    status: "online",
+                    domain: fromAgent?.domain ?? undefined,
+                    description: fromAgent?.description ?? undefined,
+                    enabled: (fromAgent?.enabled ?? 1) !== 0,
+                };
+                // 注册 federated pending request,让本地 agent 的 a2a_reply 走 fedReplyHook
+                router.registerFederatedPendingRequest(msg.requestId, msg.conversation);
+                return hub.sendToAgent(target.id, {
+                    type: "a2a_message",
+                    requestId: msg.requestId,
+                    from: fromInfo,
+                    payload: msg.payload,
+                    routeType: "federated",
+                    conversation: msg.conversation,
+                });
+            },
+        });
+        this.fedServer.start();
+        // 本地 agent 给 federated 请求回复 → 通过 fedServer 广播 FedReply 给所有 member
+        router.fedReplyHook = (requestId, fromName, payload) => {
+            if (!this.fedServer)
+                return;
+            this.fedServer.sendReply(requestId, { hostname: identity.hostname, name: fromName }, payload);
+            router.consumeFederatedPendingRequest(requestId);
+        };
+        this.fedSelfPublisher = new SelfPublisher(db, identity);
+        this.fedSelfPublisher.start();
+        log.info(`Started coordination mode — team=${teamId}`);
+    }
+    stop() {
+        this.fedSelfPublisher?.stop();
+        this.fedPublisher?.stop();
+        this.fedClient?.stop();
+        this.fedServer?.stop();
+    }
+}
+// 全局单例
+let manager = null;
+export function initFederationManager(opts) {
+    manager = new FederationManager(opts);
+    return manager;
+}
+export function getFederationManager() {
+    return manager;
+}