claude-code-swarm 0.3.3 → 0.3.5

package/references/agent-inbox/test/mesh/federation-mesh.test.ts

@@ -0,0 +1,269 @@
+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 { MeshConnector } from "../../src/mesh/mesh-connector.js";
+import type { Message } from "../../src/types.js";
+import type {
+  MapConnection,
+  MapAgentConnectionClass,
+  IncomingMapMessage,
+} from "../../src/map/map-client.js";
+import { createLinkedMeshPair, MockMeshContext } from "./mock-mesh.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(),
+  };
+}
+
+function createMockSdk() {
+  const mockConnections: Array<MapConnection & { url: string }> = [];
+  const mockSdkClass: MapAgentConnectionClass = {
+    async connect(server: string, _opts: unknown) {
+      const handlers: ((msg: IncomingMapMessage) => void)[] = [];
+      const conn: MapConnection & { url: string } = {
+        url: server,
+        send: vi.fn().mockResolvedValue(undefined),
+        onMessage: (handler) => handlers.push(handler),
+        disconnect: vi.fn().mockResolvedValue(undefined),
+      };
+      mockConnections.push(conn);
+      return conn;
+    },
+  };
+  return { mockSdkClass, mockConnections };
+}
+
+describe("Federation with mesh transport", () => {
+  let events: EventEmitter;
+  let meshA: MockMeshContext;
+  let meshB: MockMeshContext;
+
+  beforeEach(() => {
+    events = new EventEmitter();
+    [meshA, meshB] = createLinkedMeshPair("system-a", "system-b");
+  });
+
+  describe("federate() with meshPeerId", () => {
+    it("should connect via mesh transport", async () => {
+      const meshConnector = new MeshConnector(meshA, "system-a");
+      const cm = new ConnectionManager(
+        events,
+        {
+          systemId: "system-a",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        },
+        { meshConnector }
+      );
+
+      const link = await cm.federate({
+        systemId: "system-b",
+        meshPeerId: "system-b",
+      });
+
+      expect(link.peerId).toBe("system-b");
+      expect(link.status).toBe("connected");
+      expect(link.transport).toBe("mesh");
+      expect(link.url).toBe(""); // No URL for mesh peers
+      expect(cm.hasTransport("system-b")).toBe(true);
+
+      await cm.destroy();
+    });
+
+    it("should emit federation.connected event", async () => {
+      const meshConnector = new MeshConnector(meshA, "system-a");
+      const cm = new ConnectionManager(
+        events,
+        {
+          systemId: "system-a",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        },
+        { meshConnector }
+      );
+
+      const spy = vi.fn();
+      events.on("federation.connected", spy);
+
+      await cm.federate({
+        systemId: "system-b",
+        meshPeerId: "system-b",
+      });
+
+      expect(spy).toHaveBeenCalledWith("system-b");
+      await cm.destroy();
+    });
+  });
+
+  describe("federate() with url uses SDK transport", () => {
+    it("should prefer url when both are present", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const meshConnector = new MeshConnector(meshA, "system-a");
+      const cm = new ConnectionManager(
+        events,
+        {
+          systemId: "system-a",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        },
+        { sdkClass: mockSdkClass, meshConnector }
+      );
+
+      // When meshPeerId is set but url is not, use mesh
+      const meshLink = await cm.federate({
+        systemId: "mesh-peer",
+        meshPeerId: "mesh-peer",
+      });
+      expect(meshLink.transport).toBe("mesh");
+
+      // When url is set (without meshPeerId), use websocket
+      const wsLink = await cm.federate({
+        systemId: "ws-peer",
+        url: "ws://ws-peer:3001",
+      });
+      expect(wsLink.transport).toBe("websocket");
+      expect(mockConnections).toHaveLength(1);
+
+      await cm.destroy();
+    });
+  });
+
+  describe("federate() validation", () => {
+    it("should throw when neither url nor meshPeerId provided", async () => {
+      const cm = new ConnectionManager(events, {
+        systemId: "system-a",
+        trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+      });
+
+      await expect(
+        cm.federate({ systemId: "peer-x" })
+      ).rejects.toThrow("must have either url or meshPeerId");
+
+      await cm.destroy();
+    });
+  });
+
+  describe("route() delivers over mesh", () => {
+    it("should send messages to the remote peer via mesh", async () => {
+      // Set up two ConnectionManagers connected via mesh
+      const meshConnectorA = new MeshConnector(meshA, "system-a");
+      const meshConnectorB = new MeshConnector(meshB, "system-b");
+
+      const eventsA = new EventEmitter();
+      const eventsB = new EventEmitter();
+
+      const incomingOnB: Array<{ from: string; payload: unknown }> = [];
+      const onIncomingB: IncomingMessageHandler = (incoming) => {
+        incomingOnB.push({ from: incoming.from, payload: incoming.payload });
+      };
+
+      const cmA = new ConnectionManager(
+        eventsA,
+        {
+          systemId: "system-a",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        },
+        { meshConnector: meshConnectorA }
+      );
+      const cmB = new ConnectionManager(
+        eventsB,
+        {
+          systemId: "system-b",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        },
+        { meshConnector: meshConnectorB, onIncomingMessage: onIncomingB }
+      );
+
+      // Federate: A → B
+      await cmA.federate({ systemId: "system-b", meshPeerId: "system-b" });
+      // Federate: B → A (so B listens on the channel)
+      await cmB.federate({ systemId: "system-a", meshPeerId: "system-a" });
+
+      // Route a message from A to agent "bob@system-b"
+      const msg = makeMessage("bob@system-b");
+      const result = await cmA.route(msg);
+
+      // Wait for async delivery
+      await new Promise((r) => setTimeout(r, 20));
+
+      expect(result.delivered).toBe(true);
+      expect(result.peerId).toBe("system-b");
+
+      // B should have received the message
+      expect(incomingOnB).toHaveLength(1);
+      expect(incomingOnB[0].from).toBe("system-a");
+
+      await cmA.destroy();
+      await cmB.destroy();
+    });
+  });
+
+  describe("mixed federation: websocket + mesh peers", () => {
+    it("should support both transports simultaneously", async () => {
+      const { mockSdkClass, mockConnections } = createMockSdk();
+      const meshConnector = new MeshConnector(meshA, "system-a");
+
+      const cm = new ConnectionManager(
+        events,
+        {
+          systemId: "system-a",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        },
+        { sdkClass: mockSdkClass, meshConnector }
+      );
+
+      // Connect to a websocket peer
+      await cm.federate({ systemId: "ws-peer", url: "ws://ws:3001" });
+      // Connect to a mesh peer
+      await cm.federate({ systemId: "mesh-peer", meshPeerId: "system-b" });
+
+      expect(cm.isConnected("ws-peer")).toBe(true);
+      expect(cm.isConnected("mesh-peer")).toBe(true);
+      expect(cm.hasTransport("ws-peer")).toBe(true);
+      expect(cm.hasTransport("mesh-peer")).toBe(true);
+
+      const peers = cm.getPeers();
+      expect(peers).toHaveLength(2);
+
+      const wsPeer = peers.find((p) => p.peerId === "ws-peer");
+      const meshPeer = peers.find((p) => p.peerId === "mesh-peer");
+      expect(wsPeer?.transport).toBe("websocket");
+      expect(meshPeer?.transport).toBe("mesh");
+
+      await cm.destroy();
+    });
+  });
+
+  describe("offline mesh peer triggers queue", () => {
+    it("should queue messages when mesh peer is not connected", async () => {
+      const cm = new ConnectionManager(
+        events,
+        {
+          systemId: "system-a",
+          trust: { allowedServers: [], scopePermissions: {}, requireAuth: false },
+        }
+      );
+
+      // Register a routing entry but don't federate (no real connection)
+      cm.routing.updateFromExposure("system-b", ["bob"]);
+
+      const msg = makeMessage("bob@system-b");
+      const result = await cm.route(msg);
+
+      expect(result.delivered).toBe(false);
+      expect(result.queued).toBe(true);
+      expect(result.peerId).toBe("system-b");
+
+      await cm.destroy();
+    });
+  });
+});

package/references/agent-inbox/test/mesh/mesh-connector.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { MeshConnector } from "../../src/mesh/mesh-connector.js";
+import { MeshTransport } from "../../src/mesh/mesh-transport.js";
+import { createLinkedMeshPair, MockMeshContext } from "./mock-mesh.js";
+
+describe("MeshConnector", () => {
+  let meshA: MockMeshContext;
+  let meshB: MockMeshContext;
+
+  beforeEach(() => {
+    [meshA, meshB] = createLinkedMeshPair("peer-a", "peer-b");
+  });
+
+  it("should create a MeshTransport implementing MapConnection", async () => {
+    const connector = new MeshConnector(meshA, "peer-a");
+    const conn = await connector.connect("peer-b");
+
+    // Should satisfy MapConnection interface
+    expect(typeof conn.send).toBe("function");
+    expect(typeof conn.onMessage).toBe("function");
+    expect(typeof conn.disconnect).toBe("function");
+
+    await conn.disconnect();
+  });
+
+  it("should target the correct remote peer", async () => {
+    const connector = new MeshConnector(meshA, "peer-a");
+    const conn = await connector.connect("peer-b");
+
+    // The transport should be a MeshTransport with systemName = remotePeerId
+    expect(conn.systemName).toBe("peer-b");
+
+    await conn.disconnect();
+  });
+
+  it("should use custom channel name", async () => {
+    const connector = new MeshConnector(meshA, "peer-a", "custom-channel");
+    const conn = await connector.connect("peer-b");
+
+    // The channel should exist on the mesh with the custom name
+    expect(meshA._getChannel("custom-channel")).toBeDefined();
+    expect(meshA._getChannel("proto:agent-inbox")).toBeUndefined();
+
+    await conn.disconnect();
+  });
+
+  it("should produce working connections that can exchange messages", async () => {
+    const connectorA = new MeshConnector(meshA, "peer-a");
+    const connectorB = new MeshConnector(meshB, "peer-b");
+
+    const connA = await connectorA.connect("peer-b");
+    const connB = await connectorB.connect("peer-a");
+
+    const received: unknown[] = [];
+    connB.onMessage((msg) => received.push(msg.payload));
+
+    await connA.send({ agentId: "bob" }, "hello from connector");
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(received).toHaveLength(1);
+    expect(received[0]).toBe("hello from connector");
+
+    await connA.disconnect();
+    await connB.disconnect();
+  });
+});

package/references/agent-inbox/test/mesh/mesh-transport.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { MeshTransport } from "../../src/mesh/mesh-transport.js";
+import type { IncomingMapMessage } from "../../src/map/map-client.js";
+import { createLinkedMeshPair, MockMeshContext } from "./mock-mesh.js";
+
+describe("MeshTransport", () => {
+  let meshA: MockMeshContext;
+  let meshB: MockMeshContext;
+
+  beforeEach(() => {
+    [meshA, meshB] = createLinkedMeshPair("peer-a", "peer-b");
+  });
+
+  describe("send and receive", () => {
+    it("should deliver a message from A to B", async () => {
+      const transportA = new MeshTransport(meshA, "peer-a", "peer-b");
+      const transportB = new MeshTransport(meshB, "peer-b", "peer-a");
+      await transportA.open();
+      await transportB.open();
+
+      const received: IncomingMapMessage[] = [];
+      transportB.onMessage((msg) => received.push(msg));
+
+      await transportA.send(
+        { agentId: "agent-bob" },
+        { type: "text", text: "hello" },
+        { importance: "normal" }
+      );
+
+      // Wait for async delivery
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(received).toHaveLength(1);
+      expect(received[0].from).toBe("peer-a");
+      expect(received[0].to).toEqual({ agentId: "agent-bob" });
+      expect(received[0].payload).toEqual({ type: "text", text: "hello" });
+      expect(received[0].meta).toEqual({ importance: "normal" });
+
+      await transportA.disconnect();
+      await transportB.disconnect();
+    });
+
+    it("should support bidirectional messaging", async () => {
+      const transportA = new MeshTransport(meshA, "peer-a", "peer-b");
+      const transportB = new MeshTransport(meshB, "peer-b", "peer-a");
+      await transportA.open();
+      await transportB.open();
+
+      const receivedByA: IncomingMapMessage[] = [];
+      const receivedByB: IncomingMapMessage[] = [];
+      transportA.onMessage((msg) => receivedByA.push(msg));
+      transportB.onMessage((msg) => receivedByB.push(msg));
+
+      await transportA.send({ agentId: "bob" }, "ping");
+      await transportB.send({ agentId: "alice" }, "pong");
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(receivedByB).toHaveLength(1);
+      expect(receivedByB[0].payload).toBe("ping");
+      expect(receivedByA).toHaveLength(1);
+      expect(receivedByA[0].payload).toBe("pong");
+
+      await transportA.disconnect();
+      await transportB.disconnect();
+    });
+  });
+
+  describe("peer filtering", () => {
+    it("should only receive messages from the configured remote peer", async () => {
+      // Three peers: A, B, C. A listens only for B.
+      const meshC = new MockMeshContext("peer-c");
+      meshA.linkPeer(meshC);
+
+      const transportA = new MeshTransport(meshA, "peer-a", "peer-b");
+      const transportB = new MeshTransport(meshB, "peer-b", "peer-a");
+      const transportC = new MeshTransport(meshC, "peer-c", "peer-a");
+      await transportA.open();
+      await transportB.open();
+      await transportC.open();
+
+      const receivedByA: IncomingMapMessage[] = [];
+      transportA.onMessage((msg) => receivedByA.push(msg));
+
+      // B sends to A — should arrive
+      await transportB.send({ agentId: "alice" }, "from-b");
+      // C sends to A — should NOT arrive (filtered by remotePeerId)
+      await transportC.send({ agentId: "alice" }, "from-c");
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(receivedByA).toHaveLength(1);
+      expect(receivedByA[0].payload).toBe("from-b");
+
+      await transportA.disconnect();
+      await transportB.disconnect();
+      await transportC.disconnect();
+    });
+  });
+
+  describe("multiple onMessage handlers", () => {
+    it("should fire all registered handlers", async () => {
+      const transportA = new MeshTransport(meshA, "peer-a", "peer-b");
+      const transportB = new MeshTransport(meshB, "peer-b", "peer-a");
+      await transportA.open();
+      await transportB.open();
+
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+      transportB.onMessage(handler1);
+      transportB.onMessage(handler2);
+
+      await transportA.send({ agentId: "bob" }, "hello");
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(handler1).toHaveBeenCalledTimes(1);
+      expect(handler2).toHaveBeenCalledTimes(1);
+
+      await transportA.disconnect();
+      await transportB.disconnect();
+    });
+  });
+
+  describe("disconnect", () => {
+    it("should reject sends after disconnect", async () => {
+      const transport = new MeshTransport(meshA, "peer-a", "peer-b");
+      await transport.open();
+      await transport.disconnect();
+
+      await expect(
+        transport.send({ agentId: "bob" }, "hello")
+      ).rejects.toThrow("MeshTransport is closed");
+    });
+
+    it("should stop delivering messages after disconnect", async () => {
+      const transportA = new MeshTransport(meshA, "peer-a", "peer-b");
+      const transportB = new MeshTransport(meshB, "peer-b", "peer-a");
+      await transportA.open();
+      await transportB.open();
+
+      const handler = vi.fn();
+      transportB.onMessage(handler);
+      await transportB.disconnect();
+
+      await transportA.send({ agentId: "bob" }, "hello");
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("systemName", () => {
+    it("should return the remote peer ID", () => {
+      const transport = new MeshTransport(meshA, "peer-a", "peer-b");
+      expect(transport.systemName).toBe("peer-b");
+    });
+  });
+
+  describe("offline peer", () => {
+    it("should throw when sending to an unlinked peer", async () => {
+      const isolated = new MockMeshContext("isolated");
+      const transport = new MeshTransport(isolated, "isolated", "nobody");
+      await transport.open();
+
+      await expect(
+        transport.send({ agentId: "bob" }, "hello")
+      ).rejects.toThrow('Failed to send to peer "nobody"');
+
+      await transport.disconnect();
+    });
+  });
+
+  describe("channel sharing", () => {
+    it("should reuse the same channel for multiple transports to different peers", async () => {
+      const meshC = new MockMeshContext("peer-c");
+      meshA.linkPeer(meshC);
+
+      const t1 = new MeshTransport(meshA, "peer-a", "peer-b");
+      const t2 = new MeshTransport(meshA, "peer-a", "peer-c");
+      await t1.open();
+      await t2.open();
+
+      // Both transports should use the same underlying channel
+      const ch1 = meshA._getChannel("proto:agent-inbox");
+      expect(ch1).toBeDefined();
+      // Only one channel should exist on meshA
+      expect(meshA._getChannel("proto:agent-inbox")).toBe(ch1);
+
+      await t1.disconnect();
+      await t2.disconnect();
+    });
+  });
+});