agent-comms 2.31.0 → 3.0.0

package/dist/core/federation.d.ts

@@ -1,125 +0,0 @@
-/**
- * FederationManager — manages TLS links between mesh coordinators.
- *
- * Federation links are persistent TLS connections between coordinators on
- * different machines. They forward agent presence, room memberships, and
- * messages for rooms marked as federated. Non-federated rooms never leave
- * the local mesh.
- *
- * Each link uses certificate pinning (the same trust model as TlsTransport).
- * The wire protocol runs over the same newline-delimited JSON framing as the
- * local mesh, but with `fed_*` method types.
- */
-import * as tls from "node:tls";
-import type { AgentIdentity, RoomMessage } from "./types.js";
-import type { PeerIdentity } from "./identity.js";
-/** Represents an active federation link (outbound or inbound). */
-export interface FedLink {
-    /** Unique ID for this link (assigned locally). */
-    id: string;
-    /** Remote mesh ID (received during handshake). */
-    remoteMeshId: string;
-    /** Human-readable name for the remote mesh. */
-    remoteName: string;
-    /** The TLS socket. */
-    socket: tls.TLSSocket;
-    /** Whether the handshake has completed successfully. */
-    ready: boolean;
-    /** Direction of the connection. */
-    direction: "outbound" | "inbound";
-}
-/** Callbacks the FederationManager uses to interact with local mesh state. */
-export interface FedCallbacks {
-    /** Called when a remote agent becomes visible over a federation link. */
-    onAgentVisible: (agent: AgentIdentity) => Promise<void>;
-    /** Called when a remote agent goes offline/disappears. */
-    onAgentGone: (agentId: string) => Promise<void>;
-    /** Called when a message arrives for a federated room. */
-    onRoomMessage: (roomId: string, message: RoomMessage) => Promise<void>;
-    /** Called when a remote agent joins a federated room. */
-    onRoomJoin: (roomId: string, agentId: string, agentName: string) => Promise<void>;
-    /** Called when a remote agent leaves a federated room. */
-    onRoomLeave: (roomId: string, agentId: string) => Promise<void>;
-    /** Get all visible agents in the local mesh (for syncing to new links). */
-    getVisibleAgents: () => AgentIdentity[];
-    /** Get all federated rooms and their member lists (for syncing to new links). */
-    getFederatedRoomMemberships: () => Map<string, string[]>;
-}
-export declare class FederationManager {
-    private readonly links;
-    private readonly identity;
-    private readonly meshId;
-    private readonly meshName;
-    private readonly callbacks;
-    private readonly pingTimers;
-    private shutDown;
-    private readonly pendingPongs;
-    /**
-     * Certificate fingerprints this instance will federate with, inbound or outbound. Empty by default — federation trusts nobody until an operator explicitly pins a remote mesh's fingerprint, the same no-CA, pin-the-key trust model ordinary peer connections already use.
-     */
-    private readonly trustedFingerprints;
-    private listener;
-    constructor(meshId: string, meshName: string, callbacks: Readonly<FedCallbacks>);
-    /** The TLS identity used for federation connections. */
-    get tlsIdentity(): PeerIdentity;
-    /** Pin a remote mesh's certificate fingerprint as trusted for federation. */
-    addTrustedFingerprint(fingerprint: string): void;
-    /** Remove a previously pinned fingerprint. Existing links using it are not torn down. */
-    removeTrustedFingerprint(fingerprint: string): void;
-    /** List currently trusted fingerprints. */
-    listTrustedFingerprints(): string[];
-    /**
-     * Verify the certificate a connected TLS socket presented against the trusted-fingerprint allowlist. Returns the presented fingerprint when trusted, `undefined` (and destroys the socket) otherwise.
-     *
-     * This is the check that was missing entirely before: the socket was accepted with `rejectUnauthorized: false` (required, since these are self-signed certs with no CA) but nothing then verified *which* self-signed cert was presented, so any certificate was accepted as a valid federation peer.
-     */
-    private verifyPeerOrDestroy;
-    /**
-     * Establish an outbound federation link to a remote coordinator.
-     * Returns the local link ID once the handshake completes.
-     */
-    connect(host: string, port: number, name?: string): Promise<string>;
-    /**
-     * Handle an incoming TLS connection that sent a fed_handshake.
-     * Called by the transport layer when a federation connection arrives.
-     */
-    handleInbound(socket: tls.TLSSocket): Promise<string>;
-    /** Disconnect a specific federation link. */
-    disconnect(linkId: string): Promise<void>;
-    /** List all active federation links. */
-    listLinks(): FedLink[];
-    /** Broadcast an agent visibility event to all ready links. */
-    broadcastAgentVisible(agent: AgentIdentity): Promise<void>;
-    /** Broadcast an agent gone event to all ready links. */
-    broadcastAgentGone(agentId: string): Promise<void>;
-    /** Forward a room message to all ready links (federated rooms only). */
-    forwardRoomMessage(roomId: string, message: RoomMessage): Promise<void>;
-    /** Broadcast a room join to all ready links. */
-    broadcastRoomJoin(roomId: string, agentId: string, agentName: string): Promise<void>;
-    /** Broadcast a room leave to all ready links. */
-    broadcastRoomLeave(roomId: string, agentId: string): Promise<void>;
-    /**
-     * Start listening for inbound federation connections. Every accepted connection is routed through `handleInbound()`, which enforces the trusted-fingerprint check before a link is ever created — nothing here bypasses that check.
-     *
-     * Previously nothing in the shipped product called `handleInbound()` at all: it existed only as a function the integration test invoked directly against a hand-rolled `tls.createServer`. This is that server, promoted to real code.
-     */
-    listen(host: string, port: number): Promise<void>;
-    /** Stop accepting new inbound federation connections. Existing links are unaffected. */
-    stopListening(): Promise<void>;
-    shutdown(): Promise<void>;
-    private tlsConnect;
-    private wireSocket;
-    private handleMessage;
-    /**
-     * After handshake, push our visible agents and federated room memberships
-     * to the newly connected link.
-     */
-    private syncStateToLink;
-    private waitForHandshake;
-    private startPing;
-    private sendPing;
-    private writeToSocket;
-    private broadcastToReady;
-    private clearLinkTimers;
-}
-//# sourceMappingURL=federation.d.ts.map

package/dist/core/federation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"federation.d.ts","sourceRoot":"","sources":["../../src/core/federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAGhC,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG7D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAMlD,kEAAkE;AAClE,MAAM,WAAW,OAAO;IACtB,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC;IACtB,wDAAwD;IACxD,KAAK,EAAE,OAAO,CAAC;IACf,mCAAmC;IACnC,SAAS,EAAE,UAAU,GAAG,SAAS,CAAC;CACnC;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,0DAA0D;IAC1D,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,0DAA0D;IAC1D,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,yDAAyD;IACzD,UAAU,EAAE,CACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,2EAA2E;IAC3E,gBAAgB,EAAE,MAAM,aAAa,EAAE,CAAC;IACxC,iFAAiF;IACjF,2BAA2B,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC1D;AAsBD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAGvB;IACJ,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAGzB;IACJ;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD,OAAO,CAAC,QAAQ,CAAyB;gBAGvC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,QAAQ,CAAC,YAAY,CAAC;IAQnC,wDAAwD;IACxD,IAAI,WAAW,IAAI,YAAY,CAE9B;IAMD,6EAA6E;IAC7E,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIhD,yFAAyF;IACzF,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAInD,2CAA2C;IAC3C,uBAAuB,IAAI,MAAM,EAAE;IAInC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA6CzE;;;OAGG;IACG,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IAoC3D,6CAA6C;IACvC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/C,wCAAwC;IACxC,SAAS,IAAI,OAAO,EAAE;IAQtB,8DAA8D;IACxD,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhE,wDAAwD;IAClD,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD,wEAAwE;IAClE,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;IAKhB,gDAAgD;IAC1C,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;IAUhB,iDAAiD;IAC3C,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASxE;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BvD,wFAAwF;IAClF,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAe9B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAYjB,UAAU;IAkCxB,OAAO,CAAC,UAAU;YAyBJ,aAAa;IA0F3B;;;OAGG;YACW,eAAe;YAkCf,gBAAgB;IA6B9B,OAAO,CAAC,SAAS;YAUH,QAAQ;YAoBR,aAAa;YAcb,gBAAgB;IAmB9B,OAAO,CAAC,eAAe;CAYxB"}

package/dist/core/federation.js

@@ -1,523 +0,0 @@
-/**
- * FederationManager — manages TLS links between mesh coordinators.
- *
- * Federation links are persistent TLS connections between coordinators on
- * different machines. They forward agent presence, room memberships, and
- * messages for rooms marked as federated. Non-federated rooms never leave
- * the local mesh.
- *
- * Each link uses certificate pinning (the same trust model as TlsTransport).
- * The wire protocol runs over the same newline-delimited JSON framing as the
- * local mesh, but with `fed_*` method types.
- */
-import * as tls from "node:tls";
-import { encode, isMeshMessage, MessageBuffer } from "./wire-protocol.js";
-import { nanoid } from "./nanoid.js";
-import { fingerprintDer, generateIdentity } from "./identity.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const FED_PING_INTERVAL_MS = 30_000;
-const FED_PING_TIMEOUT_MS = 10_000;
-const FED_VERSION = "1.0.0";
-/** Length (in bytes of entropy) of a locally-assigned federation link ID. */
-const FED_LINK_ID_LENGTH = 8;
-/** How long to wait for the remote side to complete the fed_handshake/fed_ack exchange before giving up. */
-const FED_HANDSHAKE_TIMEOUT_MS = 5000;
-/** How long to wait for the underlying TLS socket itself to connect before giving up. */
-const FED_CONNECT_TIMEOUT_MS = 5000;
-/** How often {@link FederationManager.waitForHandshake} polls link readiness. */
-const FED_HANDSHAKE_POLL_INTERVAL_MS = 50;
-// ---------------------------------------------------------------------------
-// FederationManager
-// ---------------------------------------------------------------------------
-export class FederationManager {
-    links = new Map();
-    identity;
-    meshId;
-    meshName;
-    callbacks;
-    pingTimers = new Map();
-    shutDown = false;
-    pendingPongs = new Map();
-    /**
-     * Certificate fingerprints this instance will federate with, inbound or outbound. Empty by default — federation trusts nobody until an operator explicitly pins a remote mesh's fingerprint, the same no-CA, pin-the-key trust model ordinary peer connections already use.
-     */
-    trustedFingerprints = new Set();
-    listener;
-    constructor(meshId, meshName, callbacks) {
-        this.meshId = meshId;
-        this.meshName = meshName;
-        this.callbacks = callbacks;
-        this.identity = generateIdentity();
-    }
-    /** The TLS identity used for federation connections. */
-    get tlsIdentity() {
-        return this.identity;
-    }
-    // -----------------------------------------------------------------------
-    // Trust — which remote mesh fingerprints this instance will federate with
-    // -----------------------------------------------------------------------
-    /** Pin a remote mesh's certificate fingerprint as trusted for federation. */
-    addTrustedFingerprint(fingerprint) {
-        this.trustedFingerprints.add(fingerprint);
-    }
-    /** Remove a previously pinned fingerprint. Existing links using it are not torn down. */
-    removeTrustedFingerprint(fingerprint) {
-        this.trustedFingerprints.delete(fingerprint);
-    }
-    /** List currently trusted fingerprints. */
-    listTrustedFingerprints() {
-        return [...this.trustedFingerprints];
-    }
-    /**
-     * Verify the certificate a connected TLS socket presented against the trusted-fingerprint allowlist. Returns the presented fingerprint when trusted, `undefined` (and destroys the socket) otherwise.
-     *
-     * This is the check that was missing entirely before: the socket was accepted with `rejectUnauthorized: false` (required, since these are self-signed certs with no CA) but nothing then verified *which* self-signed cert was presented, so any certificate was accepted as a valid federation peer.
-     */
-    verifyPeerOrDestroy(socket) {
-        const cert = socket.getPeerCertificate();
-        // Node's types declare every PeerCertificate field non-optional, but the documented runtime behaviour when the peer presents no certificate at all is an empty object — not null/undefined, and not a Buffer-typed `raw`. Detect that real shape rather than trusting the declared type.
-        if (Object.keys(cert).length === 0) {
-            socket.destroy();
-            return undefined;
-        }
-        const fingerprint = fingerprintDer(cert.raw);
-        if (!this.trustedFingerprints.has(fingerprint)) {
-            socket.destroy();
-            return undefined;
-        }
-        return fingerprint;
-    }
-    // -----------------------------------------------------------------------
-    // Outbound links
-    // -----------------------------------------------------------------------
-    /**
-     * Establish an outbound federation link to a remote coordinator.
-     * Returns the local link ID once the handshake completes.
-     */
-    async connect(host, port, name) {
-        if (this.shutDown)
-            throw new Error("FederationManager is shut down");
-        const linkId = nanoid(FED_LINK_ID_LENGTH);
-        const socket = await this.tlsConnect(host, port);
-        if (this.verifyPeerOrDestroy(socket) === undefined) {
-            throw new Error(`Federation connection to ${host}:${String(port)} rejected: ` +
-                "the presented certificate is not in the trusted-fingerprint allowlist. " +
-                "Call addTrustedFingerprint() with the remote mesh's fingerprint first.");
-        }
-        const link = {
-            id: linkId,
-            remoteMeshId: "",
-            remoteName: name ?? `${host}:${String(port)}`,
-            socket,
-            ready: false,
-            direction: "outbound",
-        };
-        this.links.set(linkId, link);
-        // Send handshake
-        const handshake = {
-            method: "fed_handshake",
-            meshId: this.meshId,
-            name: this.meshName,
-            version: FED_VERSION,
-        };
-        await this.writeToSocket(socket, handshake);
-        // Wire up incoming message handling
-        this.wireSocket(linkId, socket);
-        // Wait for fed_ack (with timeout)
-        await this.waitForHandshake(linkId, FED_HANDSHAKE_TIMEOUT_MS);
-        return linkId;
-    }
-    // -----------------------------------------------------------------------
-    // Inbound links (server)
-    // -----------------------------------------------------------------------
-    /**
-     * Handle an incoming TLS connection that sent a fed_handshake.
-     * Called by the transport layer when a federation connection arrives.
-     */
-    async handleInbound(socket) {
-        if (this.shutDown) {
-            socket.destroy();
-            throw new Error("FederationManager is shut down");
-        }
-        if (this.verifyPeerOrDestroy(socket) === undefined) {
-            throw new Error("Inbound federation connection rejected: the presented certificate " +
-                "is not in the trusted-fingerprint allowlist.");
-        }
-        const linkId = nanoid(FED_LINK_ID_LENGTH);
-        const link = {
-            id: linkId,
-            remoteMeshId: "",
-            remoteName: "unknown",
-            socket,
-            ready: false,
-            direction: "inbound",
-        };
-        this.links.set(linkId, link);
-        this.wireSocket(linkId, socket);
-        // Wait for the remote side's handshake
-        await this.waitForHandshake(linkId, FED_HANDSHAKE_TIMEOUT_MS);
-        return linkId;
-    }
-    // -----------------------------------------------------------------------
-    // Link management
-    // -----------------------------------------------------------------------
-    /** Disconnect a specific federation link. */
-    async disconnect(linkId) {
-        const link = this.links.get(linkId);
-        if (!link)
-            return Promise.resolve();
-        this.clearLinkTimers(linkId);
-        link.ready = false;
-        link.socket.unref();
-        link.socket.destroy();
-        this.links.delete(linkId);
-        return Promise.resolve();
-    }
-    /** List all active federation links. */
-    listLinks() {
-        return [...this.links.values()].filter((l) => l.ready);
-    }
-    // -----------------------------------------------------------------------
-    // Broadcasting to federated links
-    // -----------------------------------------------------------------------
-    /** Broadcast an agent visibility event to all ready links. */
-    async broadcastAgentVisible(agent) {
-        const msg = { method: "fed_agent_visible", agent };
-        await this.broadcastToReady(msg);
-    }
-    /** Broadcast an agent gone event to all ready links. */
-    async broadcastAgentGone(agentId) {
-        const msg = { method: "fed_agent_gone", agentId };
-        await this.broadcastToReady(msg);
-    }
-    /** Forward a room message to all ready links (federated rooms only). */
-    async forwardRoomMessage(roomId, message) {
-        const msg = { method: "fed_room_message", roomId, message };
-        await this.broadcastToReady(msg);
-    }
-    /** Broadcast a room join to all ready links. */
-    async broadcastRoomJoin(roomId, agentId, agentName) {
-        const msg = {
-            method: "fed_room_join",
-            roomId,
-            agentId,
-            agentName,
-        };
-        await this.broadcastToReady(msg);
-    }
-    /** Broadcast a room leave to all ready links. */
-    async broadcastRoomLeave(roomId, agentId) {
-        const msg = { method: "fed_room_leave", roomId, agentId };
-        await this.broadcastToReady(msg);
-    }
-    // -----------------------------------------------------------------------
-    // Inbound listener — accepts federation links from remote coordinators
-    // -----------------------------------------------------------------------
-    /**
-     * Start listening for inbound federation connections. Every accepted connection is routed through `handleInbound()`, which enforces the trusted-fingerprint check before a link is ever created — nothing here bypasses that check.
-     *
-     * Previously nothing in the shipped product called `handleInbound()` at all: it existed only as a function the integration test invoked directly against a hand-rolled `tls.createServer`. This is that server, promoted to real code.
-     */
-    async listen(host, port) {
-        if (this.listener) {
-            throw new Error("FederationManager is already listening");
-        }
-        return new Promise((resolve, reject) => {
-            const server = tls.createServer({
-                key: this.identity.privateKey,
-                cert: this.identity.certificate,
-                // Same as the outbound side: no CA, so we don't ask Node to verify the chain. requestCert is what makes the connecting peer's own certificate available to verifyPeerOrDestroy() inside handleInbound() — without it there is nothing to check.
-                rejectUnauthorized: false,
-                requestCert: true,
-            }, (socket) => {
-                this.handleInbound(socket).catch(() => {
-                    // Rejected (untrusted fingerprint, or shutting down) — the socket is already destroyed inside handleInbound/verifyPeerOrDestroy.
-                });
-            });
-            server.listen(port, host, () => {
-                this.listener = server;
-                resolve();
-            });
-            server.on("error", reject);
-        });
-    }
-    /** Stop accepting new inbound federation connections. Existing links are unaffected. */
-    async stopListening() {
-        const server = this.listener;
-        if (!server)
-            return Promise.resolve();
-        this.listener = undefined;
-        return new Promise((resolve) => {
-            server.close(() => {
-                resolve();
-            });
-        });
-    }
-    // -----------------------------------------------------------------------
-    // Shutdown
-    // -----------------------------------------------------------------------
-    async shutdown() {
-        this.shutDown = true;
-        await this.stopListening();
-        for (const linkId of [...this.links.keys()]) {
-            await this.disconnect(linkId);
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Internal — TLS connection
-    // -----------------------------------------------------------------------
-    async tlsConnect(host, port) {
-        return new Promise((resolve, reject) => {
-            const socket = tls.connect({
-                key: this.identity.privateKey,
-                cert: this.identity.certificate,
-                host,
-                port,
-                rejectUnauthorized: false,
-                requestCert: true,
-            }, () => {
-                resolve(socket);
-            });
-            const timer = setTimeout(() => {
-                socket.destroy();
-                reject(new Error(`Federation connection timeout to ${host}:${String(port)}`));
-            }, FED_CONNECT_TIMEOUT_MS);
-            socket.on("error", (err) => {
-                clearTimeout(timer);
-                reject(err);
-            });
-        });
-    }
-    // -----------------------------------------------------------------------
-    // Internal — socket wiring
-    // -----------------------------------------------------------------------
-    wireSocket(linkId, socket) {
-        const buffer = new MessageBuffer();
-        socket.on("data", (data) => {
-            const items = buffer.append(data.toString());
-            for (const item of items) {
-                if (isMeshMessage(item)) {
-                    void this.handleMessage(linkId, item);
-                }
-            }
-        });
-        socket.on("error", () => {
-            void this.disconnect(linkId);
-        });
-        socket.on("close", () => {
-            void this.disconnect(linkId);
-        });
-    }
-    // -----------------------------------------------------------------------
-    // Internal — message handling
-    // -----------------------------------------------------------------------
-    async handleMessage(linkId, msg) {
-        const link = this.links.get(linkId);
-        if (!link || this.shutDown)
-            return;
-        switch (msg.method) {
-            case "fed_handshake": {
-                // Inbound connection sending its handshake
-                link.remoteMeshId = msg.meshId;
-                link.remoteName = msg.name;
-                link.ready = true;
-                // Respond with ack
-                const ack = {
-                    method: "fed_ack",
-                    meshId: this.meshId,
-                    name: this.meshName,
-                    version: FED_VERSION,
-                };
-                await this.writeToSocket(link.socket, ack);
-                // Sync local state to the new link
-                await this.syncStateToLink(linkId);
-                // Start ping for this link
-                this.startPing(linkId);
-                break;
-            }
-            case "fed_ack": {
-                link.remoteMeshId = msg.meshId;
-                link.remoteName = msg.name;
-                link.ready = true;
-                // Sync local state to the new link
-                await this.syncStateToLink(linkId);
-                // Start ping for this link
-                this.startPing(linkId);
-                break;
-            }
-            case "fed_agent_visible": {
-                await this.callbacks.onAgentVisible(msg.agent);
-                break;
-            }
-            case "fed_agent_gone": {
-                await this.callbacks.onAgentGone(msg.agentId);
-                break;
-            }
-            case "fed_room_message": {
-                await this.callbacks.onRoomMessage(msg.roomId, msg.message);
-                break;
-            }
-            case "fed_room_join": {
-                await this.callbacks.onRoomJoin(msg.roomId, msg.agentId, msg.agentName);
-                break;
-            }
-            case "fed_room_leave": {
-                await this.callbacks.onRoomLeave(msg.roomId, msg.agentId);
-                break;
-            }
-            case "fed_ping": {
-                const pong = { method: "fed_pong" };
-                await this.writeToSocket(link.socket, pong);
-                break;
-            }
-            case "fed_pong": {
-                const pending = this.pendingPongs.get(linkId);
-                if (pending) {
-                    clearTimeout(pending);
-                    this.pendingPongs.delete(linkId);
-                }
-                break;
-            }
-            case "state_sync":
-            case "state_update":
-            case "introduce":
-            case "connect_request":
-            case "peer_list":
-            case "peer_joined":
-            case "peer_left":
-            case "become_coordinator": {
-                // Local-mesh-only message kinds — never sent over a federation link; ignore rather than throw so an unexpected wire message can't tear down the link.
-                break;
-            }
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Internal — state sync
-    // -----------------------------------------------------------------------
-    /**
-     * After handshake, push our visible agents and federated room memberships
-     * to the newly connected link.
-     */
-    async syncStateToLink(linkId) {
-        const link = this.links.get(linkId);
-        if (link?.ready !== true)
-            return;
-        // Sync visible agents
-        const agents = this.callbacks.getVisibleAgents();
-        for (const agent of agents) {
-            const msg = { method: "fed_agent_visible", agent };
-            await this.writeToSocket(link.socket, msg);
-        }
-        // Sync federated room memberships
-        const rooms = this.callbacks.getFederatedRoomMemberships();
-        for (const [roomId, memberIds] of rooms) {
-            for (const memberId of memberIds) {
-                const agent = this.callbacks
-                    .getVisibleAgents()
-                    .find((a) => a.id === memberId);
-                const agentName = agent?.name ?? memberId;
-                const msg = {
-                    method: "fed_room_join",
-                    roomId,
-                    agentId: memberId,
-                    agentName,
-                };
-                await this.writeToSocket(link.socket, msg);
-            }
-        }
-    }
-    // -----------------------------------------------------------------------
-    // Internal — handshake waiting
-    // -----------------------------------------------------------------------
-    async waitForHandshake(linkId, timeoutMs) {
-        return new Promise((resolve, reject) => {
-            const startTime = Date.now();
-            const check = () => {
-                const link = this.links.get(linkId);
-                if (link?.ready === true) {
-                    resolve();
-                    return;
-                }
-                if (Date.now() - startTime > timeoutMs) {
-                    void this.disconnect(linkId);
-                    reject(new Error(`Federation handshake timeout for link ${linkId}`));
-                    return;
-                }
-                setTimeout(check, FED_HANDSHAKE_POLL_INTERVAL_MS);
-            };
-            check();
-        });
-    }
-    // -----------------------------------------------------------------------
-    // Internal — ping/pong health monitoring
-    // -----------------------------------------------------------------------
-    startPing(linkId) {
-        if (this.pingTimers.has(linkId))
-            return;
-        const timer = setInterval(() => {
-            void this.sendPing(linkId);
-        }, FED_PING_INTERVAL_MS);
-        this.pingTimers.set(linkId, timer);
-    }
-    async sendPing(linkId) {
-        const link = this.links.get(linkId);
-        if (link?.ready !== true)
-            return;
-        const msg = { method: "fed_ping" };
-        await this.writeToSocket(link.socket, msg);
-        // Set pong timeout
-        const timer = setTimeout(() => {
-            // No pong received — disconnect the link
-            void this.disconnect(linkId);
-        }, FED_PING_TIMEOUT_MS);
-        this.pendingPongs.set(linkId, timer);
-    }
-    // -----------------------------------------------------------------------
-    // Internal — helpers
-    // -----------------------------------------------------------------------
-    async writeToSocket(socket, msg) {
-        if (socket.destroyed)
-            return;
-        const data = encode(msg);
-        await new Promise((resolve, reject) => {
-            socket.write(data, "utf-8", (err) => {
-                if (err)
-                    reject(err);
-                else
-                    resolve();
-            });
-        });
-    }
-    async broadcastToReady(msg) {
-        const data = encode(msg);
-        const writes = [];
-        for (const [, link] of this.links) {
-            if (!link.ready || link.socket.destroyed)
-                continue;
-            writes.push(new Promise((resolve) => {
-                link.socket.write(data, "utf-8", (err) => {
-                    if (err) {
-                        void this.disconnect(link.id);
-                    }
-                    resolve();
-                });
-            }));
-        }
-        await Promise.all(writes);
-    }
-    clearLinkTimers(linkId) {
-        const pingTimer = this.pingTimers.get(linkId);
-        if (pingTimer !== undefined) {
-            clearInterval(pingTimer);
-            this.pingTimers.delete(linkId);
-        }
-        const pongTimer = this.pendingPongs.get(linkId);
-        if (pongTimer !== undefined) {
-            clearTimeout(pongTimer);
-            this.pendingPongs.delete(linkId);
-        }
-    }
-}
-//# sourceMappingURL=federation.js.map