agent-inbox 0.0.1 → 0.1.1

package/src/federation/connection-manager.ts

@@ -0,0 +1,458 @@
+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,
+} from "../map/map-client.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 systemId: SystemId;
+  private sdkClass: MapAgentConnectionClass | null;
+  private onIncoming: IncomingMessageHandler | null;
+  readonly routing: RoutingEngine;
+  readonly queue: DeliveryQueue;
+  readonly trust: TrustManager;
+
+  constructor(
+    private events: EventEmitter,
+    private config: FederationConfig = {},
+    opts?: {
+      sdkClass?: MapAgentConnectionClass;
+      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.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> {
+    // Trust check
+    if (!this.trust.canConnect(peer.systemId)) {
+      throw new Error(
+        `Federation denied: system "${peer.systemId}" not in allowed servers list`
+      );
+    }
+
+    // Open real MAP connection if SDK is available
+    let conn: MapConnection | undefined;
+    if (this.sdkClass) {
+      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,
+          },
+        });
+
+        // Register incoming message handler
+        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,
+      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") {
+        // TODO: When resolved peerId has no peer link (e.g., system-qualified address
+        // targeting a system we're not directly connected to), fall through to
+        // handleUnknownRoute so broadcast/hierarchical strategies can attempt delivery
+        // via connected peers or upstream hubs instead of immediately queuing.
+        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 real connection or event emission.
+   * Returns true if send succeeded (or event was emitted).
+   */
+  private async sendToPeer(
+    peerId: string,
+    addr: FederatedAddress,
+    message: Message
+  ): Promise<boolean> {
+    const conn = this.connections.get(peerId);
+    if (conn) {
+      // Real transport — send via MAP SDK 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.
+   */
+  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.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);
+  }
+}

package/src/federation/delivery-queue.ts

@@ -0,0 +1,222 @@
+import { EventEmitter } from "node:events";
+import { ulid } from "ulid";
+import type { Message, DeliveryQueueConfig, QueuedMessage } from "../types.js";
+
+const DEFAULT_CONFIG: DeliveryQueueConfig = {
+  persistence: "memory",
+  maxTTL: 86_400_000, // 24h
+  maxQueueSize: 10_000,
+  retryStrategy: "exponential",
+  retryBaseInterval: 1_000,
+  retryMaxAttempts: 0, // unlimited until TTL
+  flushOnReconnect: true,
+  overflow: "drop-oldest",
+};
+
+/**
+ * Delivery queue for messages to offline or unreachable federation peers.
+ *
+ * Supports configurable TTL, overflow policy, and retry strategy.
+ * Currently memory-only; SQLite persistence is a future enhancement.
+ */
+export class DeliveryQueue {
+  private queues = new Map<string, QueuedMessage[]>();
+  private config: DeliveryQueueConfig;
+  private tickTimer?: ReturnType<typeof setInterval>;
+
+  constructor(
+    private events: EventEmitter,
+    config?: Partial<DeliveryQueueConfig>
+  ) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Enqueue a message for a peer. Returns the queued message ID, or null if rejected.
+   */
+  enqueue(peerId: string, message: Message): string | null {
+    let queue = this.queues.get(peerId);
+    if (!queue) {
+      queue = [];
+      this.queues.set(peerId, queue);
+    }
+
+    // Check queue size limit
+    if (queue.length >= this.config.maxQueueSize) {
+      switch (this.config.overflow) {
+        case "drop-oldest":
+          queue.shift();
+          break;
+        case "drop-newest":
+          return null; // Don't enqueue
+        case "reject-new":
+          return null;
+      }
+    }
+
+    const now = new Date().toISOString();
+    const entry: QueuedMessage = {
+      id: ulid(),
+      peerId,
+      message,
+      enqueuedAt: now,
+      attempts: 0,
+      nextRetry: now, // Ready to send immediately
+    };
+
+    queue.push(entry);
+    this.events.emit("queue.enqueued", { peerId, messageId: entry.id });
+    return entry.id;
+  }
+
+  /**
+   * Flush all queued messages for a peer (on reconnect).
+   * Returns the messages and removes them from the queue.
+   */
+  flush(peerId: string): QueuedMessage[] {
+    const queue = this.queues.get(peerId);
+    if (!queue || queue.length === 0) return [];
+
+    const messages = [...queue];
+    this.queues.delete(peerId);
+    this.events.emit("queue.flushed", { peerId, count: messages.length });
+    return messages;
+  }
+
+  /**
+   * Get messages ready for retry. Does not remove them from the queue.
+   */
+  getRetryable(peerId: string): QueuedMessage[] {
+    const queue = this.queues.get(peerId);
+    if (!queue) return [];
+
+    const now = Date.now();
+    return queue.filter((entry) => {
+      if (!entry.nextRetry) return true;
+      return new Date(entry.nextRetry).getTime() <= now;
+    });
+  }
+
+  /**
+   * Record a retry attempt for a message. Updates attempt count and next retry time.
+   * Returns false if max attempts exceeded (message should be dropped).
+   */
+  recordAttempt(peerId: string, messageId: string): boolean {
+    const queue = this.queues.get(peerId);
+    if (!queue) return false;
+
+    const entry = queue.find((e) => e.id === messageId);
+    if (!entry) return false;
+
+    entry.attempts++;
+    entry.lastAttempt = new Date().toISOString();
+
+    // Check max attempts
+    if (this.config.retryMaxAttempts > 0 && entry.attempts >= this.config.retryMaxAttempts) {
+      this.removeEntry(peerId, messageId);
+      return false;
+    }
+
+    // Calculate next retry
+    const delay =
+      this.config.retryStrategy === "exponential"
+        ? this.config.retryBaseInterval * Math.pow(2, entry.attempts - 1)
+        : this.config.retryBaseInterval;
+    entry.nextRetry = new Date(Date.now() + delay).toISOString();
+    return true;
+  }
+
+  /**
+   * Remove a specific entry (e.g., after successful delivery).
+   */
+  removeEntry(peerId: string, messageId: string): boolean {
+    const queue = this.queues.get(peerId);
+    if (!queue) return false;
+
+    const idx = queue.findIndex((e) => e.id === messageId);
+    if (idx === -1) return false;
+
+    queue.splice(idx, 1);
+    if (queue.length === 0) this.queues.delete(peerId);
+    return true;
+  }
+
+  /**
+   * Process tick: expire old messages past TTL.
+   */
+  tick(): number {
+    const now = Date.now();
+    let expired = 0;
+
+    for (const [peerId, queue] of this.queues.entries()) {
+      const before = queue.length;
+      const remaining = queue.filter((entry) => {
+        const age = now - new Date(entry.enqueuedAt).getTime();
+        return age < this.config.maxTTL;
+      });
+      expired += before - remaining.length;
+
+      if (remaining.length === 0) {
+        this.queues.delete(peerId);
+      } else {
+        this.queues.set(peerId, remaining);
+      }
+    }
+
+    if (expired > 0) {
+      this.events.emit("queue.expired", { count: expired });
+    }
+    return expired;
+  }
+
+  /**
+   * Start periodic tick timer for TTL expiry.
+   */
+  startTicking(intervalMs: number = 60_000): void {
+    this.stopTicking();
+    this.tickTimer = setInterval(() => this.tick(), intervalMs);
+  }
+
+  /**
+   * Stop periodic tick timer.
+   */
+  stopTicking(): void {
+    if (this.tickTimer) {
+      clearInterval(this.tickTimer);
+      this.tickTimer = undefined;
+    }
+  }
+
+  /**
+   * Get queue depth for a peer.
+   */
+  size(peerId: string): number {
+    return this.queues.get(peerId)?.length ?? 0;
+  }
+
+  /**
+   * Get total queue depth across all peers.
+   */
+  totalSize(): number {
+    let total = 0;
+    for (const queue of this.queues.values()) {
+      total += queue.length;
+    }
+    return total;
+  }
+
+  /**
+   * List peers with queued messages.
+   */
+  peers(): string[] {
+    return Array.from(this.queues.keys());
+  }
+
+  /**
+   * Clean up all state. Call on shutdown.
+   */
+  destroy(): void {
+    this.stopTicking();
+    this.queues.clear();
+  }
+}

package/src/federation/index.ts

@@ -0,0 +1,6 @@
+export { parseAddress, formatAddress, isRemoteAddress, isBroadcastAddress } from "./address.js";
+export { ConnectionManager } from "./connection-manager.js";
+export type { DeliveryResult } from "./connection-manager.js";
+export { DeliveryQueue } from "./delivery-queue.js";
+export { RoutingEngine } from "./routing-engine.js";
+export { TrustManager } from "./trust.js";