claude-code-swarm 0.3.3 → 0.3.5

package/references/agent-inbox/src/federation/connection-manager.ts

@@ -0,0 +1,573 @@
+import { EventEmitter } from "node:events";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+import type {
+  FederatedAddress,
+  FederationConfig,
+  FederationLink,
+  FederationPeerConfig,
+  Message,
+  SystemId,
+} from "../types.js";
+import type {
+  MapConnection,
+  MapAgentConnectionClass,
+  IncomingMapMessage,
+  MeshPeerLike,
+  MeshFederationGateway,
+} from "../map/map-client.js";
+import type { MeshConnector } from "../mesh/mesh-connector.js";
+import { inboxMessageToMap } from "../mesh/type-mapper.js";
+import { RoutingEngine } from "./routing-engine.js";
+import { DeliveryQueue } from "./delivery-queue.js";
+import { TrustManager } from "./trust.js";
+import { parseAddress, isRemoteAddress } from "./address.js";
+
+export interface DeliveryResult {
+  delivered: boolean;
+  peerId?: string;
+  queued?: boolean;
+  error?: string;
+}
+
+/**
+ * Callback for handling incoming federation messages.
+ * Wired to router.routeMessage() by index.ts.
+ */
+export type IncomingMessageHandler = (incoming: {
+  from: string;
+  peerId: string;
+  payload: unknown;
+  meta?: Record<string, unknown>;
+}) => void;
+
+/**
+ * Manages MAP connections and federation peer links.
+ *
+ * Coordinates routing, delivery queuing, and trust enforcement
+ * for cross-system messaging. When an SDK connect function is provided,
+ * opens real MAP connections to federation peers for actual message transport.
+ */
+export class ConnectionManager {
+  private peers = new Map<string, FederationLink>();
+  private connections = new Map<string, MapConnection>();
+  private gateways = new Map<string, MeshFederationGateway>();
+  private systemId: SystemId;
+  private sdkClass: MapAgentConnectionClass | null;
+  private meshConnector: MeshConnector | null;
+  private meshPeer: MeshPeerLike | null;
+  private onIncoming: IncomingMessageHandler | null;
+  readonly routing: RoutingEngine;
+  readonly queue: DeliveryQueue;
+  readonly trust: TrustManager;
+
+  constructor(
+    private events: EventEmitter,
+    private config: FederationConfig = {},
+    opts?: {
+      sdkClass?: MapAgentConnectionClass;
+      meshConnector?: MeshConnector;
+      /** Full MeshPeer for Phase 2 FederationGateway delegation */
+      meshPeer?: MeshPeerLike;
+      onIncomingMessage?: IncomingMessageHandler;
+    }
+  ) {
+    this.systemId = this.resolveSystemId();
+    this.routing = new RoutingEngine(events, config.routing);
+    this.queue = new DeliveryQueue(events, config.deliveryQueue);
+    this.trust = new TrustManager(config.trust);
+    this.sdkClass = opts?.sdkClass ?? null;
+    this.meshConnector = opts?.meshConnector ?? null;
+    this.meshPeer = opts?.meshPeer ?? null;
+    this.onIncoming = opts?.onIncomingMessage ?? null;
+
+    // Wire up flush-on-reconnect
+    this.events.on("federation.connected", (peerId: string) => {
+      if (config.deliveryQueue?.flushOnReconnect !== false) {
+        const queued = this.queue.flush(peerId);
+        if (queued.length > 0) {
+          this.events.emit("federation.flushing", {
+            peerId,
+            count: queued.length,
+          });
+          for (const entry of queued) {
+            this.route(entry.message).catch(() => {
+              // Re-queue if delivery still fails
+              this.queue.enqueue(peerId, entry.message);
+            });
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * Get the resolved system ID for this Agent Inbox instance.
+   */
+  getSystemId(): SystemId {
+    return this.systemId;
+  }
+
+  /**
+   * Establish federation with a peer. Uses MAP federation/connect protocol.
+   * If an SDK class was injected, opens a real MAP connection to the peer.
+   * Returns the federation link, or throws if trust check fails.
+   */
+  async federate(peer: FederationPeerConfig): Promise<FederationLink> {
+    if (!peer.url && !peer.meshPeerId) {
+      throw new Error(
+        `Federation peer "${peer.systemId}" must have either url or meshPeerId`
+      );
+    }
+
+    // Trust check
+    if (!this.trust.canConnect(peer.systemId)) {
+      throw new Error(
+        `Federation denied: system "${peer.systemId}" not in allowed servers list`
+      );
+    }
+
+    let conn: MapConnection | undefined;
+    let transport: "websocket" | "mesh" = "websocket";
+
+    if (peer.meshPeerId && this.meshPeer) {
+      // Phase 2: Full MeshPeer integration with FederationGateway (v0.2.0+)
+      transport = "mesh";
+      try {
+        // Try to get an existing gateway first (e.g. pre-connected in test setup),
+        // otherwise create one via federateWith()
+        let gateway: MeshFederationGateway | undefined =
+          this.meshPeer.getFederationGateway(peer.systemId);
+        if (!gateway) {
+          gateway = await this.meshPeer.federateWith(peer.systemId, {
+            localSystemId: this.meshPeer.peerId,
+            remoteSystemId: peer.systemId,
+            buffer: { enabled: true, maxMessages: 1000 },
+            routing: { maxHops: 5, trackPath: true },
+          });
+        }
+
+        this.gateways.set(peer.systemId, gateway);
+
+        // Listen for incoming federated messages
+        gateway.on("message:received", (envelope: unknown) => {
+          const env = envelope as { payload?: { from?: string; payload?: unknown; meta?: Record<string, unknown> } };
+          if (env.payload) {
+            this.handlePeerMessage(peer.systemId, {
+              from: env.payload.from ?? peer.systemId,
+              payload: env.payload.payload,
+              meta: env.payload.meta,
+            });
+          }
+        });
+      } catch (err) {
+        throw new Error(
+          `Mesh federation connection failed for "${peer.systemId}": ${err instanceof Error ? err.message : err}`
+        );
+      }
+    } else if (peer.meshPeerId && this.meshConnector) {
+      // Phase 1 fallback: Mesh transport via raw channel (no MeshPeer)
+      transport = "mesh";
+      try {
+        conn = await this.meshConnector.connect(peer.meshPeerId);
+
+        conn.onMessage((msg: IncomingMapMessage) => {
+          this.handlePeerMessage(peer.systemId, msg);
+        });
+
+        this.connections.set(peer.systemId, conn);
+      } catch (err) {
+        throw new Error(
+          `Mesh federation connection failed for "${peer.systemId}": ${err instanceof Error ? err.message : err}`
+        );
+      }
+    } else if (peer.url && this.sdkClass) {
+      // WebSocket transport — connect via MAP SDK
+      try {
+        conn = await this.sdkClass.connect(peer.url, {
+          name: this.systemId.id,
+          role: "gateway",
+          scopes: ["federation"],
+          capabilities: { trajectory: { canReport: false } },
+          metadata: {
+            systemId: this.systemId.id,
+            type: "federation-gateway",
+            peerSystemId: peer.systemId,
+          },
+          reconnection: {
+            enabled: true,
+            maxRetries: 5,
+            baseDelayMs: 1000,
+            maxDelayMs: 30000,
+          },
+        });
+
+        conn.onMessage((msg: IncomingMapMessage) => {
+          this.handlePeerMessage(peer.systemId, msg);
+        });
+
+        this.connections.set(peer.systemId, conn);
+      } catch (err) {
+        throw new Error(
+          `Federation connection failed for "${peer.systemId}": ${err instanceof Error ? err.message : err}`
+        );
+      }
+    }
+
+    const link: FederationLink = {
+      peerId: peer.systemId,
+      sessionId: crypto.randomUUID(),
+      status: "connected",
+      exposure: peer.exposure ?? { agents: "all" },
+      url: peer.url ?? "",
+      transport,
+      connectedAt: new Date().toISOString(),
+    };
+
+    this.peers.set(peer.systemId, link);
+    this.events.emit("federation.connected", peer.systemId);
+    return link;
+  }
+
+  /**
+   * Disconnect from a federation peer.
+   * Closes the real MAP connection if one exists.
+   */
+  async disconnect(peerId: string): Promise<void> {
+    const link = this.peers.get(peerId);
+    if (!link) return;
+
+    // Close real connection
+    const conn = this.connections.get(peerId);
+    if (conn) {
+      try {
+        await conn.disconnect();
+      } catch {
+        // Best-effort disconnect
+      }
+      this.connections.delete(peerId);
+    }
+
+    link.status = "disconnected";
+    this.routing.removePeer(peerId);
+    this.peers.delete(peerId);
+    this.events.emit("federation.disconnected", peerId);
+  }
+
+  /**
+   * Route a message to the correct federation peer.
+   * Resolves the address, checks trust, and delivers or queues.
+   * If a real connection exists, sends via conn.send(); otherwise emits event.
+   */
+  async route(message: Message): Promise<DeliveryResult> {
+    // Determine target for each recipient
+    for (const recipient of message.recipients) {
+      const addr = parseAddress(recipient.agent_id);
+      if (!isRemoteAddress(addr)) continue;
+
+      const peerId = this.routing.resolveRoute(addr);
+      if (!peerId) {
+        // Route unknown — try strategies
+        return this.handleUnknownRoute(addr, message);
+      }
+
+      // Check trust
+      if (!this.trust.canRoute(peerId, message.scope)) {
+        return {
+          delivered: false,
+          peerId,
+          error: `Trust policy denies routing to scope "${message.scope}" from system "${peerId}"`,
+        };
+      }
+
+      const link = this.peers.get(peerId);
+      if (!link || link.status !== "connected") {
+        // No direct peer link — try broadcast/hierarchical strategies before queuing.
+        // This handles cases like system-qualified addresses (bob@system-2) targeting
+        // a system we're not directly connected to but could reach via relay or hub.
+        const strategy = this.routing.getStrategy();
+        if (strategy !== "table") {
+          return this.handleUnknownRoute(addr, message);
+        }
+        this.queue.enqueue(peerId, message);
+        return { delivered: false, peerId, queued: true };
+      }
+
+      // Deliver — use real connection if available, otherwise emit event
+      const sendResult = await this.sendToPeer(peerId, addr, message);
+      if (sendResult) {
+        recipient.delivered_at = new Date().toISOString();
+        return { delivered: true, peerId };
+      }
+      // Send failed — queue for retry
+      this.queue.enqueue(peerId, message);
+      return { delivered: false, peerId, queued: true };
+    }
+
+    return { delivered: false, error: "No remote recipients found" };
+  }
+
+  /**
+   * Send a message to a peer via FederationGateway, real connection, or event.
+   * Returns true if send succeeded (or event was emitted).
+   */
+  private async sendToPeer(
+    peerId: string,
+    addr: FederatedAddress,
+    message: Message
+  ): Promise<boolean> {
+    // Phase 2: Try FederationGateway first (provides envelope, hop/loop detection)
+    const gateway = this.gateways.get(peerId);
+    if (gateway) {
+      try {
+        const mapMsg = inboxMessageToMap(message);
+        // Build a MAP-compatible message for the gateway.
+        // Use local agent address (not federated) since the gateway
+        // already handles cross-system routing. A federated `to` like
+        // { system: "system-b", agent: "bob" } would cause the remote
+        // MapServer to call routeToFederation() instead of deliverToAgent().
+        const targetAgentIds = addr.agent ? [addr.agent] : [];
+        const localTo =
+          targetAgentIds.length === 1
+            ? { agent: targetAgentIds[0] }
+            : targetAgentIds.length > 1
+              ? { agents: targetAgentIds }
+              : mapMsg.to;
+        const gatewayMessage = {
+          id: message.id,
+          from: message.sender_id,
+          to: localTo,
+          timestamp: Date.now(),
+          payload: mapMsg.payload,
+          meta: mapMsg.meta,
+        };
+        const routed = await gateway.route(gatewayMessage, targetAgentIds);
+        if (routed) return true;
+        // Fall through to direct connection if gateway route fails
+      } catch {
+        // Fall through to direct connection
+      }
+    }
+
+    const conn = this.connections.get(peerId);
+    if (conn) {
+      // Real transport — send via MAP SDK or mesh channel connection
+      try {
+        await conn.send(
+          { agentId: addr.agent, scope: addr.scope },
+          message.content,
+          {
+            messageId: message.id,
+            senderId: message.sender_id,
+            sourceSystem: this.systemId.id,
+            targetAgent: addr.agent,
+            importance: message.importance,
+            ...(message.subject ? { subject: message.subject } : {}),
+            ...(message.thread_tag ? { threadTag: message.thread_tag } : {}),
+            ...(message.in_reply_to ? { inReplyTo: message.in_reply_to } : {}),
+          }
+        );
+        return true;
+      } catch {
+        return false;
+      }
+    }
+
+    // No real connection — emit event (for testing / event-based mode)
+    this.events.emit("federation.route", { peerId, message });
+    return true;
+  }
+
+  /**
+   * Handle an incoming message from a federation peer connection.
+   * Delegates to the injected message handler (wired to router.routeMessage).
+   */
+  private handlePeerMessage(peerId: string, msg: IncomingMapMessage): void {
+    this.events.emit("federation.message.received", { peerId, message: msg });
+
+    if (this.onIncoming) {
+      this.onIncoming({
+        from: msg.from,
+        peerId,
+        payload: msg.payload,
+        meta: msg.meta,
+      });
+    }
+  }
+
+  /**
+   * Handle routing to an unknown agent. Behavior depends on strategy.
+   */
+  private async handleUnknownRoute(
+    addr: FederatedAddress,
+    message: Message
+  ): Promise<DeliveryResult> {
+    const strategy = this.routing.getStrategy();
+
+    if (strategy === "broadcast") {
+      // Forward to all connected peers
+      const connectedPeers = this.getConnectedPeers();
+      if (connectedPeers.length === 0) {
+        return { delivered: false, error: "No connected peers for broadcast" };
+      }
+
+      // Try real connections first, fall back to event
+      for (const peer of connectedPeers) {
+        await this.sendToPeer(peer.peerId, addr, message);
+      }
+
+      this.events.emit("federation.broadcast", {
+        message,
+        peers: connectedPeers.map((p) => p.peerId),
+        timeout: this.routing.getBroadcastTimeout(),
+      });
+      return { delivered: true };
+    }
+
+    if (strategy === "hierarchical") {
+      // Delegate to upstream hubs
+      const upstream = this.routing.getUpstream();
+      for (const hubId of upstream) {
+        const link = this.peers.get(hubId);
+        if (link?.status === "connected") {
+          const sent = await this.sendToPeer(hubId, addr, message);
+          if (sent) {
+            return { delivered: true, peerId: hubId };
+          }
+        }
+      }
+      return { delivered: false, error: "No reachable upstream hubs" };
+    }
+
+    // Table strategy with refreshOnMiss — emit event for transport layer
+    if (this.routing.shouldRefreshOnMiss()) {
+      this.events.emit("federation.refresh", { address: addr });
+    }
+
+    // Queue for later if we have a system hint
+    if (addr.system) {
+      this.queue.enqueue(addr.system, message);
+      return { delivered: false, peerId: addr.system, queued: true };
+    }
+
+    return {
+      delivered: false,
+      error: `No route to agent "${addr.agent}"`,
+    };
+  }
+
+  /**
+   * Get all federation peer links.
+   */
+  getPeers(): FederationLink[] {
+    return Array.from(this.peers.values());
+  }
+
+  /**
+   * Get only connected peers.
+   */
+  getConnectedPeers(): FederationLink[] {
+    return Array.from(this.peers.values()).filter(
+      (p) => p.status === "connected"
+    );
+  }
+
+  /**
+   * Get a specific peer link.
+   */
+  getPeer(peerId: string): FederationLink | undefined {
+    return this.peers.get(peerId);
+  }
+
+  /**
+   * Check if a peer is connected.
+   */
+  isConnected(peerId: string): boolean {
+    return this.peers.get(peerId)?.status === "connected";
+  }
+
+  /**
+   * Check if a real MAP SDK connection exists for a peer.
+   */
+  hasTransport(peerId: string): boolean {
+    return this.connections.has(peerId);
+  }
+
+  /**
+   * Clean up all state. Call on shutdown.
+   */
+  /**
+   * Check if a FederationGateway exists for a peer.
+   */
+  hasGateway(peerId: string): boolean {
+    return this.gateways.has(peerId);
+  }
+
+  async destroy(): Promise<void> {
+    // Close all real connections
+    for (const [peerId, conn] of this.connections) {
+      try {
+        await conn.disconnect();
+      } catch {
+        // Best-effort
+      }
+      this.connections.delete(peerId);
+    }
+
+    this.gateways.clear();
+    this.routing.destroy();
+    this.queue.destroy();
+    this.peers.clear();
+  }
+
+  /**
+   * Resolve the system ID using tiered precedence:
+   * 1. Explicit config (INBOX_SYSTEM_ID)
+   * 2. Auto-generated (persisted to file for stability across restarts)
+   *
+   * Note: Tier 2 (MAP systemInfo) is handled after MAP connection is established.
+   */
+  private resolveSystemId(): SystemId {
+    // Tier 1: Explicit config
+    if (this.config.systemId) {
+      return { id: this.config.systemId, source: "config" };
+    }
+
+    // Tier 3: Auto-generated (with persistence)
+    const idFile = path.join(
+      os.homedir(),
+      ".claude",
+      "agent-inbox",
+      "system-id"
+    );
+    try {
+      const existing = fs.readFileSync(idFile, "utf-8").trim();
+      if (existing) {
+        return { id: existing, source: "auto" };
+      }
+    } catch {
+      // File doesn't exist — generate new ID
+    }
+
+    const newId = `inbox-${crypto.randomBytes(4).toString("hex")}`;
+    try {
+      fs.mkdirSync(path.dirname(idFile), { recursive: true });
+      fs.writeFileSync(idFile, newId);
+    } catch {
+      // Best-effort persistence
+    }
+    return { id: newId, source: "auto" };
+  }
+
+  /**
+   * Update system ID from MAP server's systemInfo (Tier 2).
+   * Only used if no explicit config was set.
+   */
+  updateSystemIdFromMap(mapSystemName: string): void {
+    if (this.systemId.source === "config") return; // Explicit config takes precedence
+    this.systemId = { id: mapSystemName, source: "map" };
+    this.events.emit("system.id.updated", this.systemId);
+  }
+}