agent-inbox 0.0.1 → 0.1.2

package/test/federation/connection-manager.test.ts

@@ -0,0 +1,546 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { ConnectionManager } from "../../src/federation/connection-manager.js";
+import type { IncomingMessageHandler } from "../../src/federation/connection-manager.js";
+import type { Message } from "../../src/types.js";
+import type {
+  MapConnection,
+  MapAgentConnectionClass,
+  IncomingMapMessage,
+} from "../../src/map/map-client.js";
+
+function makeMessage(
+  recipientAddress: string,
+  scope = "default"
+): Message {
+  return {
+    id: "msg-1",
+    scope,
+    sender_id: "local-agent",
+    recipients: [{ agent_id: recipientAddress, kind: "to" }],
+    content: { type: "text", text: "hello" },
+    importance: "normal",
+    metadata: {},
+    created_at: new Date().toISOString(),
+  };
+}
+
+describe("ConnectionManager", () => {
+  let events: EventEmitter;
+  let cm: ConnectionManager;
+
+  beforeEach(() => {
+    events = new EventEmitter();
+    cm = new ConnectionManager(events, {
+      systemId: "test-system",
+      trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+    });
+  });
+
+  afterEach(() => {
+    cm.destroy();
+  });
+
+  describe("getSystemId", () => {
+    it("should return configured system ID", () => {
+      const sid = cm.getSystemId();
+      expect(sid.id).toBe("test-system");
+      expect(sid.source).toBe("config");
+    });
+  });
+
+  describe("federate", () => {
+    it("should establish a peer link", async () => {
+      const link = await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+      expect(link.peerId).toBe("backend-team");
+      expect(link.status).toBe("connected");
+      expect(cm.isConnected("backend-team")).toBe(true);
+    });
+
+    it("should emit federation.connected event", async () => {
+      const spy = vi.fn();
+      events.on("federation.connected", spy);
+      await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+      expect(spy).toHaveBeenCalledWith("backend-team");
+    });
+
+    it("should reject if not in allow-list", async () => {
+      const restricted = new ConnectionManager(events, {
+        trust: {
+          allowedServers: ["approved-only"],
+          scopePermissions: {},
+          requireAuth: false,
+        },
+      });
+      await expect(
+        restricted.federate({
+          systemId: "unapproved",
+          url: "ws://localhost:3001",
+        })
+      ).rejects.toThrow("Federation denied");
+      restricted.destroy();
+    });
+  });
+
+  describe("disconnect", () => {
+    it("should remove peer and routing entries", async () => {
+      await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+      cm.routing.updateFromExposure("backend-team", [
+        { agentId: "agent-1" },
+      ]);
+
+      await cm.disconnect("backend-team");
+      expect(cm.isConnected("backend-team")).toBe(false);
+      expect(cm.routing.lookupAgent("agent-1")).toBeNull();
+    });
+  });
+
+  describe("route", () => {
+    it("should route to connected peer", async () => {
+      await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+      cm.routing.updateFromExposure("backend-team", [
+        { agentId: "remote-agent" },
+      ]);
+
+      const spy = vi.fn();
+      events.on("federation.route", spy);
+
+      const msg = makeMessage("remote-agent@backend-team");
+      const result = await cm.route(msg);
+      expect(result.delivered).toBe(true);
+      expect(result.peerId).toBe("backend-team");
+      expect(spy).toHaveBeenCalled();
+    });
+
+    it("should queue for disconnected peer", async () => {
+      await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+      await cm.disconnect("backend-team");
+
+      // Agent is still in routing table (resolve via system address)
+      const msg = makeMessage("remote-agent@backend-team");
+      const result = await cm.route(msg);
+      expect(result.delivered).toBe(false);
+      expect(result.queued).toBe(true);
+      expect(cm.queue.size("backend-team")).toBe(1);
+    });
+
+    it("should return error for non-remote recipients", async () => {
+      const msg = makeMessage("local-agent");
+      const result = await cm.route(msg);
+      expect(result.delivered).toBe(false);
+      expect(result.error).toContain("No remote recipients");
+    });
+  });
+
+  describe("getPeers", () => {
+    it("should list all peers", async () => {
+      await cm.federate({
+        systemId: "peer-1",
+        url: "ws://localhost:3001",
+      });
+      await cm.federate({
+        systemId: "peer-2",
+        url: "ws://localhost:3002",
+      });
+      expect(cm.getPeers()).toHaveLength(2);
+      expect(cm.getConnectedPeers()).toHaveLength(2);
+    });
+  });
+
+  describe("flush-on-reconnect", () => {
+    it("should flush queued messages when peer reconnects", async () => {
+      await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+      await cm.disconnect("backend-team");
+
+      // Queue a message
+      cm.queue.enqueue("backend-team", makeMessage("agent@backend-team"));
+      expect(cm.queue.size("backend-team")).toBe(1);
+
+      // Reconnect triggers flush
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+
+      await cm.federate({
+        systemId: "backend-team",
+        url: "ws://localhost:3001",
+      });
+
+      // Queue should be flushed (flush happens synchronously on connect event)
+      expect(cm.queue.size("backend-team")).toBe(0);
+    });
+  });
+
+  describe("transport layer", () => {
+    function createMockSdk() {
+      const mockConnections: Array<{
+        url: string;
+        opts: unknown;
+        conn: MockMapConnection;
+      }> = [];
+
+      class MockMapConnection implements MapConnection {
+        private messageHandler: ((msg: IncomingMapMessage) => void) | null =
+          null;
+        readonly sentMessages: Array<{
+          to: { agentId?: string; scope?: string };
+          payload: unknown;
+          meta?: Record<string, unknown>;
+        }> = [];
+        disconnected = false;
+
+        async send(
+          to: { agentId?: string; scope?: string },
+          payload: unknown,
+          meta?: Record<string, unknown>
+        ): Promise<void> {
+          this.sentMessages.push({ to, payload, meta });
+        }
+
+        onMessage(handler: (msg: IncomingMapMessage) => void): void {
+          this.messageHandler = handler;
+        }
+
+        async disconnect(): Promise<void> {
+          this.disconnected = true;
+        }
+
+        // Test helper: simulate an incoming message from peer
+        simulateIncoming(msg: IncomingMapMessage): void {
+          this.messageHandler?.(msg);
+        }
+      }
+
+      const mockSdkClass: MapAgentConnectionClass = {
+        connect: async (url: string, opts: unknown) => {
+          const conn = new MockMapConnection();
+          mockConnections.push({ url, opts, conn });
+          return conn;
+        },
+      };
+
+      return { mockSdkClass, mockConnections, MockMapConnection };
+    }
+
+    it("should open real SDK connection when sdkClass is provided", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      expect(mockConnections).toHaveLength(1);
+      expect(mockConnections[0].url).toBe("ws://peer-1:3001");
+      expect(cmWithSdk.hasTransport("peer-1")).toBe(true);
+      await cmWithSdk.destroy();
+    });
+
+    it("should send via real connection when routing", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      const msg = makeMessage("agent-x@peer-1");
+      const result = await cmWithSdk.route(msg);
+
+      expect(result.delivered).toBe(true);
+      const conn = mockConnections[0].conn;
+      expect(conn.sentMessages).toHaveLength(1);
+      expect(conn.sentMessages[0].to.agentId).toBe("agent-x");
+      expect(conn.sentMessages[0].meta?.targetAgent).toBe("agent-x");
+      expect(conn.sentMessages[0].meta?.senderId).toBe("local-agent");
+      expect(conn.sentMessages[0].meta?.sourceSystem).toBe("test-system");
+      await cmWithSdk.destroy();
+    });
+
+    it("should NOT emit federation.route event when using real transport", async () => {
+      const { mockSdkClass } = createMockSdk();
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+
+      await cmWithSdk.route(makeMessage("agent-x@peer-1"));
+      expect(routeSpy).not.toHaveBeenCalled();
+      await cmWithSdk.destroy();
+    });
+
+    it("should queue when real send fails", async () => {
+      const failSdkClass: MapAgentConnectionClass = {
+        connect: async () => ({
+          send: async () => {
+            throw new Error("network error");
+          },
+          onMessage: () => {},
+          disconnect: async () => {},
+        }),
+      };
+
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: failSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      const msg = makeMessage("agent-x@peer-1");
+      const result = await cmWithSdk.route(msg);
+
+      expect(result.delivered).toBe(false);
+      expect(result.queued).toBe(true);
+      expect(cmWithSdk.queue.size("peer-1")).toBe(1);
+      await cmWithSdk.destroy();
+    });
+
+    it("should delegate incoming peer messages to onIncomingMessage handler", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const incomingSpy = vi.fn();
+
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass, onIncomingMessage: incomingSpy }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      // Simulate incoming message from peer
+      const conn = mockConnections[0].conn;
+      conn.simulateIncoming({
+        from: "remote-agent",
+        payload: { type: "text", text: "hello from peer" },
+        timestamp: "2026-01-01T00:00:00Z",
+      });
+
+      expect(incomingSpy).toHaveBeenCalledWith({
+        from: "remote-agent",
+        peerId: "peer-1",
+        payload: { type: "text", text: "hello from peer" },
+        meta: undefined,
+      });
+      await cmWithSdk.destroy();
+    });
+
+    it("should close real connections on disconnect", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      await cmWithSdk.disconnect("peer-1");
+
+      expect(mockConnections[0].conn.disconnected).toBe(true);
+      expect(cmWithSdk.hasTransport("peer-1")).toBe(false);
+      await cmWithSdk.destroy();
+    });
+
+    it("should close all real connections on destroy", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+      await cmWithSdk.federate({
+        systemId: "peer-2",
+        url: "ws://peer-2:3002",
+      });
+
+      await cmWithSdk.destroy();
+
+      expect(mockConnections[0].conn.disconnected).toBe(true);
+      expect(mockConnections[1].conn.disconnected).toBe(true);
+    });
+
+    it("should throw when SDK connection fails", async () => {
+      const failConnectSdk: MapAgentConnectionClass = {
+        connect: async () => {
+          throw new Error("connection refused");
+        },
+      };
+
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "test-system",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: failConnectSdk }
+      );
+
+      await expect(
+        cmWithSdk.federate({
+          systemId: "peer-1",
+          url: "ws://peer-1:3001",
+        })
+      ).rejects.toThrow("Federation connection failed");
+
+      expect(cmWithSdk.isConnected("peer-1")).toBe(false);
+      await cmWithSdk.destroy();
+    });
+
+    it("should connect with gateway identity using system ID", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const cmWithSdk = new ConnectionManager(
+        events,
+        {
+          systemId: "my-inbox",
+          trust: {
+            allowedServers: [],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+
+      await cmWithSdk.federate({
+        systemId: "peer-1",
+        url: "ws://peer-1:3001",
+      });
+
+      const connectOpts = mockConnections[0].opts as Record<string, unknown>;
+      expect(connectOpts.name).toBe("my-inbox");
+      expect(connectOpts.role).toBe("gateway");
+      expect((connectOpts.metadata as Record<string, unknown>).systemId).toBe(
+        "my-inbox"
+      );
+      expect(
+        (connectOpts.metadata as Record<string, unknown>).peerSystemId
+      ).toBe("peer-1");
+      await cmWithSdk.destroy();
+    });
+  });
+
+  describe("updateSystemIdFromMap", () => {
+    it("should update system ID from MAP when not explicitly configured", () => {
+      const autoCm = new ConnectionManager(events, {});
+      const before = autoCm.getSystemId();
+      expect(before.source).toBe("auto");
+
+      autoCm.updateSystemIdFromMap("map-derived-name");
+      const after = autoCm.getSystemId();
+      expect(after.id).toBe("map-derived-name");
+      expect(after.source).toBe("map");
+      autoCm.destroy();
+    });
+
+    it("should not override explicit config", () => {
+      cm.updateSystemIdFromMap("map-derived-name");
+      expect(cm.getSystemId().id).toBe("test-system"); // unchanged
+      expect(cm.getSystemId().source).toBe("config");
+    });
+  });
+});

package/test/federation/delivery-queue.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { DeliveryQueue } from "../../src/federation/delivery-queue.js";
+import type { Message } from "../../src/types.js";
+
+function makeMessage(id: string): Message {
+  return {
+    id,
+    scope: "default",
+    sender_id: "sender",
+    recipients: [{ agent_id: "remote@peer", kind: "to" }],
+    content: { type: "text", text: `msg-${id}` },
+    importance: "normal",
+    metadata: {},
+    created_at: new Date().toISOString(),
+  };
+}
+
+describe("DeliveryQueue", () => {
+  let events: EventEmitter;
+  let queue: DeliveryQueue;
+
+  beforeEach(() => {
+    events = new EventEmitter();
+    queue = new DeliveryQueue(events, {
+      persistence: "memory",
+      maxTTL: 10000,
+      maxQueueSize: 3,
+      retryStrategy: "exponential",
+      retryBaseInterval: 100,
+      retryMaxAttempts: 3,
+      flushOnReconnect: true,
+      overflow: "drop-oldest",
+    });
+  });
+
+  describe("enqueue", () => {
+    it("should add message to queue", () => {
+      const id = queue.enqueue("peer-1", makeMessage("m1"));
+      expect(id).toBeTruthy();
+      expect(queue.size("peer-1")).toBe(1);
+    });
+
+    it("should drop oldest on overflow (drop-oldest)", () => {
+      queue.enqueue("peer-1", makeMessage("m1"));
+      queue.enqueue("peer-1", makeMessage("m2"));
+      queue.enqueue("peer-1", makeMessage("m3"));
+      queue.enqueue("peer-1", makeMessage("m4"));
+      expect(queue.size("peer-1")).toBe(3);
+      // m1 should have been dropped
+    });
+
+    it("should reject on overflow (reject-new)", () => {
+      const q = new DeliveryQueue(events, {
+        persistence: "memory",
+        maxTTL: 10000,
+        maxQueueSize: 2,
+        retryStrategy: "exponential",
+        retryBaseInterval: 100,
+        retryMaxAttempts: 0,
+        flushOnReconnect: true,
+        overflow: "reject-new",
+      });
+      q.enqueue("peer-1", makeMessage("m1"));
+      q.enqueue("peer-1", makeMessage("m2"));
+      const id = q.enqueue("peer-1", makeMessage("m3"));
+      expect(id).toBeNull();
+      expect(q.size("peer-1")).toBe(2);
+    });
+
+    it("should emit enqueued event", () => {
+      const spy = vi.fn();
+      events.on("queue.enqueued", spy);
+      queue.enqueue("peer-1", makeMessage("m1"));
+      expect(spy).toHaveBeenCalled();
+    });
+  });
+
+  describe("flush", () => {
+    it("should return all queued messages and clear queue", () => {
+      queue.enqueue("peer-1", makeMessage("m1"));
+      queue.enqueue("peer-1", makeMessage("m2"));
+      const flushed = queue.flush("peer-1");
+      expect(flushed).toHaveLength(2);
+      expect(queue.size("peer-1")).toBe(0);
+    });
+
+    it("should return empty array for empty queue", () => {
+      expect(queue.flush("peer-1")).toEqual([]);
+    });
+
+    it("should emit flushed event", () => {
+      const spy = vi.fn();
+      events.on("queue.flushed", spy);
+      queue.enqueue("peer-1", makeMessage("m1"));
+      queue.flush("peer-1");
+      expect(spy).toHaveBeenCalledWith({ peerId: "peer-1", count: 1 });
+    });
+  });
+
+  describe("recordAttempt", () => {
+    it("should increment attempts", () => {
+      queue.enqueue("peer-1", makeMessage("m1"));
+      const entries = queue.flush("peer-1");
+      // Re-enqueue for testing
+      queue.enqueue("peer-1", makeMessage("m1"));
+      const retryable = queue.getRetryable("peer-1");
+      expect(retryable.length).toBeGreaterThan(0);
+    });
+
+    it("should return false when max attempts exceeded", () => {
+      const id = queue.enqueue("peer-1", makeMessage("m1"))!;
+      queue.recordAttempt("peer-1", id);
+      queue.recordAttempt("peer-1", id);
+      const ok = queue.recordAttempt("peer-1", id);
+      expect(ok).toBe(false); // 3 attempts = max
+      expect(queue.size("peer-1")).toBe(0); // removed
+    });
+  });
+
+  describe("tick", () => {
+    it("should expire old messages past TTL", () => {
+      vi.useFakeTimers();
+      queue.enqueue("peer-1", makeMessage("m1"));
+      vi.advanceTimersByTime(10001);
+      const expired = queue.tick();
+      expect(expired).toBe(1);
+      expect(queue.size("peer-1")).toBe(0);
+      vi.useRealTimers();
+    });
+
+    it("should keep messages within TTL", () => {
+      vi.useFakeTimers();
+      queue.enqueue("peer-1", makeMessage("m1"));
+      vi.advanceTimersByTime(5000);
+      const expired = queue.tick();
+      expect(expired).toBe(0);
+      expect(queue.size("peer-1")).toBe(1);
+      vi.useRealTimers();
+    });
+  });
+
+  describe("totalSize", () => {
+    it("should sum across all peers", () => {
+      queue.enqueue("peer-1", makeMessage("m1"));
+      queue.enqueue("peer-2", makeMessage("m2"));
+      queue.enqueue("peer-2", makeMessage("m3"));
+      expect(queue.totalSize()).toBe(3);
+    });
+  });
+
+  describe("peers", () => {
+    it("should list peers with queued messages", () => {
+      queue.enqueue("peer-1", makeMessage("m1"));
+      queue.enqueue("peer-2", makeMessage("m2"));
+      expect(queue.peers().sort()).toEqual(["peer-1", "peer-2"]);
+    });
+  });
+});