claude-code-swarm 0.3.3 → 0.3.5

package/references/agent-inbox/test/mesh/mock-meshpeer.ts

@@ -0,0 +1,266 @@
+/**
+ * Linked MockMeshPeer pair for e2e testing.
+ *
+ * Two MockMeshPeer instances are linked so that:
+ * - FederationGateway.route() on peer A delivers to peer B's message handler
+ * - Messages flow bidirectionally through the gateway bridge
+ *
+ * This simulates what happens in a real agentic-mesh network where
+ * MeshPeer federation gateways exchange messages over TunnelStreams.
+ */
+
+import { EventEmitter } from "node:events";
+import type {
+  MeshPeerLike,
+  MeshAgentConnection,
+  MeshMapServer,
+  MeshMapMessage,
+  MeshDeliveryHandler,
+  MeshFederationGateway,
+} from "../../src/map/map-client.js";
+
+// ---------------------------------------------------------------------------
+// MockAgentConnection
+// ---------------------------------------------------------------------------
+
+class MockAgentConnection extends EventEmitter implements MeshAgentConnection {
+  readonly agentId: string;
+  readonly isRegistered = true;
+
+  constructor(
+    agentId: string,
+    private server: LinkedMockMapServer
+  ) {
+    super();
+    this.agentId = agentId;
+  }
+
+  async register() {
+    return { id: this.agentId, name: this.agentId, state: "active" as const, ownerId: null };
+  }
+
+  async unregister() {
+    this.server.removeMessageHandler(this.agentId);
+  }
+
+  async send(to: unknown, payload: unknown, meta?: Record<string, unknown>) {
+    // Delegate to server's send (which may route locally or remotely)
+    return { messageId: `msg-${Date.now()}`, delivered: [] as string[] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// LinkedMockMapServer
+// ---------------------------------------------------------------------------
+
+export class LinkedMockMapServer extends EventEmitter implements MeshMapServer {
+  readonly systemId: string;
+  readonly systemName?: string;
+
+  private messageHandlers = new Map<
+    string,
+    (agentId: string, message: MeshMapMessage) => void | Promise<void>
+  >();
+  private deliveryHandler: MeshDeliveryHandler | null = null;
+  private agents = new Map<string, { id: string; name?: string; role?: string; state: string }>();
+
+  constructor(systemId: string, systemName?: string) {
+    super();
+    this.systemId = systemId;
+    this.systemName = systemName;
+  }
+
+  registerAgent(params: { agentId?: string; name?: string; role?: string }) {
+    const id = params.agentId ?? `agent-${Date.now()}`;
+    const agent = { id, name: params.name, role: params.role, state: "active", ownerId: null };
+    this.agents.set(id, agent);
+    return agent;
+  }
+
+  unregisterAgent(agentId: string) {
+    this.agents.delete(agentId);
+    this.messageHandlers.delete(agentId);
+    return { id: agentId, state: "stopped", ownerId: null };
+  }
+
+  setMessageHandler(
+    agentId: string,
+    handler: (agentId: string, message: MeshMapMessage) => void | Promise<void>
+  ) {
+    this.messageHandlers.set(agentId, handler);
+  }
+
+  removeMessageHandler(agentId: string) {
+    this.messageHandlers.delete(agentId);
+  }
+
+  setDeliveryHandler(handler: MeshDeliveryHandler): MeshDeliveryHandler {
+    const prev = this.deliveryHandler ?? {
+      async deliverToAgent() { return false; },
+      async forwardToPeer() { return false; },
+    };
+    this.deliveryHandler = handler;
+    return prev;
+  }
+
+  hasAgent(agentId: string): boolean {
+    return this.agents.has(agentId);
+  }
+
+  /**
+   * Deliver a message to a local agent.
+   * First tries the DeliveryHandler bridge (Phase 2),
+   * then falls back to the message handler (Phase 1 style).
+   */
+  async deliverLocally(agentId: string, message: MeshMapMessage): Promise<boolean> {
+    // Try delivery handler first (DeliveryBridge from agent-inbox)
+    if (this.deliveryHandler) {
+      const result = await this.deliveryHandler.deliverToAgent(agentId, message);
+      if (result) return true;
+    }
+
+    // Fall back to per-agent message handler
+    const handler = this.messageHandlers.get(agentId);
+    if (handler) {
+      await handler(agentId, message);
+      return true;
+    }
+
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// LinkedFederationGateway
+// ---------------------------------------------------------------------------
+
+/**
+ * A mock FederationGateway that actually delivers messages to the
+ * linked peer's MapServer, simulating real cross-mesh federation.
+ */
+class LinkedFederationGateway extends EventEmitter implements MeshFederationGateway {
+  readonly localSystemId: string;
+  readonly remoteSystemId: string;
+  isConnected = true;
+
+  private remotePeer: LinkedMockMeshPeer;
+
+  constructor(
+    localSystemId: string,
+    remoteSystemId: string,
+    remotePeer: LinkedMockMeshPeer
+  ) {
+    super();
+    this.localSystemId = localSystemId;
+    this.remoteSystemId = remoteSystemId;
+    this.remotePeer = remotePeer;
+  }
+
+  async route(message: unknown, targetAgentIds: string[]): Promise<boolean> {
+    const msg = message as MeshMapMessage;
+
+    // Deliver to each target agent on the remote peer's MapServer
+    let anyDelivered = false;
+    for (const agentId of targetAgentIds) {
+      const delivered = await this.remotePeer.server.deliverLocally(agentId, msg);
+      if (delivered) anyDelivered = true;
+    }
+
+    // If no specific targets, try delivering to "agent-inbox" (the inbox agent)
+    if (targetAgentIds.length === 0) {
+      anyDelivered = await this.remotePeer.server.deliverLocally("agent-inbox", msg);
+    }
+
+    return anyDelivered;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// LinkedMockMeshPeer
+// ---------------------------------------------------------------------------
+
+export class LinkedMockMeshPeer extends EventEmitter implements MeshPeerLike {
+  readonly peerId: string;
+  readonly server: LinkedMockMapServer;
+  private agentConnections = new Map<string, MockAgentConnection>();
+  private gateways = new Map<string, LinkedFederationGateway>();
+  private linkedPeers = new Map<string, LinkedMockMeshPeer>();
+
+  constructor(peerId: string, systemId?: string) {
+    super();
+    this.peerId = peerId;
+    this.server = new LinkedMockMapServer(systemId ?? peerId, `${peerId}-server`);
+  }
+
+  async createAgent(config: {
+    agentId?: string;
+    name?: string;
+    role?: string;
+    scopes?: string[];
+    capabilities?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+  }): Promise<MeshAgentConnection> {
+    const agentId = config.agentId ?? `agent-${Date.now()}`;
+    this.server.registerAgent({ agentId, name: config.name, role: config.role });
+    const conn = new MockAgentConnection(agentId, this.server);
+    await conn.register();
+    this.agentConnections.set(agentId, conn);
+    return conn;
+  }
+
+  /** Link this peer to another for bidirectional message delivery. */
+  linkPeer(other: LinkedMockMeshPeer): void {
+    this.linkedPeers.set(other.peerId, other);
+    other.linkedPeers.set(this.peerId, this);
+  }
+
+  async federateWith(
+    remoteSystemId: string,
+    _config?: unknown
+  ): Promise<LinkedFederationGateway> {
+    // Find the linked peer by matching system ID or peer ID
+    let remotePeer: LinkedMockMeshPeer | undefined;
+    for (const [, peer] of this.linkedPeers) {
+      if (peer.server.systemId === remoteSystemId || peer.peerId === remoteSystemId) {
+        remotePeer = peer;
+        break;
+      }
+    }
+
+    if (!remotePeer) {
+      throw new Error(
+        `No linked peer found for system "${remoteSystemId}". Link peers first with linkPeer().`
+      );
+    }
+
+    const gateway = new LinkedFederationGateway(
+      this.server.systemId,
+      remoteSystemId,
+      remotePeer
+    );
+    this.gateways.set(remoteSystemId, gateway);
+    return gateway;
+  }
+
+  getFederationGateway(remoteSystemId: string): LinkedFederationGateway | undefined {
+    return this.gateways.get(remoteSystemId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a pair of linked MockMeshPeers that can exchange messages
+ * through their FederationGateways.
+ */
+export function createLinkedMeshPeerPair(
+  peerA: { peerId: string; systemId?: string },
+  peerB: { peerId: string; systemId?: string }
+): [LinkedMockMeshPeer, LinkedMockMeshPeer] {
+  const a = new LinkedMockMeshPeer(peerA.peerId, peerA.systemId);
+  const b = new LinkedMockMeshPeer(peerB.peerId, peerB.systemId);
+  a.linkPeer(b);
+  return [a, b];
+}

package/references/agent-inbox/test/mesh/type-mapper.test.ts

@@ -0,0 +1,226 @@
+import { describe, it, expect } from "vitest";
+import { mapMessageToInbox, inboxMessageToMap } from "../../src/mesh/type-mapper.js";
+import type { MapMessage } from "../../src/mesh/type-mapper.js";
+import type { Message } from "../../src/types.js";
+
+function makeMapMessage(overrides: Partial<MapMessage> = {}): MapMessage {
+  return {
+    id: "map-msg-1",
+    from: "agent-alice",
+    to: { agent: "agent-bob" },
+    timestamp: Date.now(),
+    payload: { type: "text", text: "hello from MAP" },
+    meta: { priority: "normal" },
+    ...overrides,
+  };
+}
+
+describe("mapMessageToInbox", () => {
+  it("should convert a basic MAP message to inbox format", () => {
+    const mapMsg = makeMapMessage();
+    const inboxMsg = mapMessageToInbox(mapMsg, "test-scope");
+
+    expect(inboxMsg.scope).toBe("test-scope");
+    expect(inboxMsg.sender_id).toBe("agent-alice");
+    expect(inboxMsg.recipients).toHaveLength(1);
+    expect(inboxMsg.recipients[0].agent_id).toBe("agent-bob");
+    expect(inboxMsg.recipients[0].kind).toBe("to");
+    expect(inboxMsg.content).toEqual({ type: "text", text: "hello from MAP" });
+    expect(inboxMsg.importance).toBe("normal");
+  });
+
+  it("should map priority to importance", () => {
+    const urgent = mapMessageToInbox(
+      makeMapMessage({ meta: { priority: "urgent" } })
+    );
+    expect(urgent.importance).toBe("urgent");
+
+    const high = mapMessageToInbox(
+      makeMapMessage({ meta: { priority: "high" } })
+    );
+    expect(high.importance).toBe("high");
+
+    const low = mapMessageToInbox(
+      makeMapMessage({ meta: { priority: "low" } })
+    );
+    expect(low.importance).toBe("low");
+  });
+
+  it("should extract inbox fields from _meta", () => {
+    const mapMsg = makeMapMessage({
+      _meta: {
+        subject: "Code review",
+        threadTag: "thread-42",
+        inReplyTo: "prev-msg-1",
+        conversationId: "conv-1",
+        inboxMessageId: "custom-id-1",
+        recipientKind: "cc",
+      },
+    });
+
+    const inboxMsg = mapMessageToInbox(mapMsg);
+
+    expect(inboxMsg.id).toBe("custom-id-1");
+    expect(inboxMsg.subject).toBe("Code review");
+    expect(inboxMsg.thread_tag).toBe("thread-42");
+    expect(inboxMsg.in_reply_to).toBe("prev-msg-1");
+    expect(inboxMsg.conversation_id).toBe("conv-1");
+    expect(inboxMsg.recipients[0].kind).toBe("cc");
+  });
+
+  it("should fall back to meta.correlationId for thread_tag", () => {
+    const mapMsg = makeMapMessage({
+      meta: { priority: "normal", correlationId: "corr-123" },
+    });
+
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.thread_tag).toBe("corr-123");
+  });
+
+  it("should handle string address", () => {
+    const mapMsg = makeMapMessage({ to: "bob" });
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.recipients[0].agent_id).toBe("bob");
+  });
+
+  it("should handle multi-agent address", () => {
+    const mapMsg = makeMapMessage({ to: { agents: ["bob", "carol"] } });
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.recipients).toHaveLength(2);
+    expect(inboxMsg.recipients[0].agent_id).toBe("bob");
+    expect(inboxMsg.recipients[1].agent_id).toBe("carol");
+  });
+
+  it("should handle scope address", () => {
+    const mapMsg = makeMapMessage({ to: { scope: "engineering" } });
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.recipients[0].agent_id).toBe("engineering");
+  });
+
+  it("should handle federated address", () => {
+    const mapMsg = makeMapMessage({
+      to: { system: "remote-sys", agent: "bob" },
+    });
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.recipients[0].agent_id).toBe("bob@remote-sys");
+  });
+
+  it("should handle broadcast address", () => {
+    const mapMsg = makeMapMessage({ to: { broadcast: true } });
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.recipients[0].agent_id).toBe("*");
+  });
+
+  it("should normalize string payload", () => {
+    const mapMsg = makeMapMessage({ payload: "just a string" });
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.content).toEqual({ type: "text", text: "just a string" });
+  });
+
+  it("should strip inbox-specific keys from metadata", () => {
+    const mapMsg = makeMapMessage({
+      _meta: {
+        subject: "Test",
+        threadTag: "t1",
+        customField: "keep-me",
+        anotherField: 42,
+      },
+    });
+
+    const inboxMsg = mapMessageToInbox(mapMsg);
+    expect(inboxMsg.metadata).toEqual({
+      customField: "keep-me",
+      anotherField: 42,
+    });
+    expect(inboxMsg.metadata).not.toHaveProperty("subject");
+    expect(inboxMsg.metadata).not.toHaveProperty("threadTag");
+  });
+});
+
+describe("inboxMessageToMap", () => {
+  function makeInboxMessage(overrides: Partial<Message> = {}): Message {
+    return {
+      id: "inbox-msg-1",
+      scope: "default",
+      sender_id: "agent-alice",
+      recipients: [{ agent_id: "agent-bob", kind: "to" }],
+      content: { type: "text", text: "hello" },
+      importance: "normal",
+      metadata: {},
+      created_at: new Date().toISOString(),
+      ...overrides,
+    };
+  }
+
+  it("should convert a basic inbox message to MAP format", () => {
+    const msg = makeInboxMessage();
+    const result = inboxMessageToMap(msg);
+
+    expect(result.to).toEqual({ agent: "agent-bob" });
+    expect(result.payload).toEqual({ type: "text", text: "hello" });
+    expect(result.meta.priority).toBe("normal");
+    expect(result.meta._meta.inboxMessageId).toBe("inbox-msg-1");
+  });
+
+  it("should encode inbox fields in _meta", () => {
+    const msg = makeInboxMessage({
+      subject: "Review",
+      thread_tag: "thread-1",
+      in_reply_to: "prev-1",
+      conversation_id: "conv-1",
+    });
+
+    const result = inboxMessageToMap(msg);
+    expect(result.meta._meta.subject).toBe("Review");
+    expect(result.meta._meta.threadTag).toBe("thread-1");
+    expect(result.meta._meta.inReplyTo).toBe("prev-1");
+    expect(result.meta._meta.conversationId).toBe("conv-1");
+    expect(result.meta.correlationId).toBe("thread-1");
+  });
+
+  it("should map importance to priority", () => {
+    expect(inboxMessageToMap(makeInboxMessage({ importance: "urgent" })).meta.priority).toBe("urgent");
+    expect(inboxMessageToMap(makeInboxMessage({ importance: "high" })).meta.priority).toBe("high");
+    expect(inboxMessageToMap(makeInboxMessage({ importance: "low" })).meta.priority).toBe("low");
+  });
+
+  it("should handle federated recipient address", () => {
+    const msg = makeInboxMessage({
+      recipients: [{ agent_id: "bob@remote-sys", kind: "to" }],
+    });
+    const result = inboxMessageToMap(msg);
+    expect(result.to).toEqual({ system: "remote-sys", agent: "bob" });
+  });
+
+  it("should handle multiple recipients", () => {
+    const msg = makeInboxMessage({
+      recipients: [
+        { agent_id: "bob", kind: "to" },
+        { agent_id: "carol", kind: "to" },
+      ],
+    });
+    const result = inboxMessageToMap(msg);
+    expect(result.to).toEqual({ agents: ["bob", "carol"] });
+  });
+
+  it("should only include 'to' recipients in address", () => {
+    const msg = makeInboxMessage({
+      recipients: [
+        { agent_id: "bob", kind: "to" },
+        { agent_id: "carol", kind: "cc" },
+      ],
+    });
+    const result = inboxMessageToMap(msg);
+    // Only "to" recipients go in the address
+    expect(result.to).toEqual({ agent: "bob" });
+  });
+
+  it("should handle no recipients with broadcast", () => {
+    const msg = makeInboxMessage({
+      recipients: [{ agent_id: "carol", kind: "cc" }],
+    });
+    // No "to" recipients → broadcast
+    const result = inboxMessageToMap(msg);
+    expect(result.to).toEqual({ broadcast: true });
+  });
+});

package/references/agent-inbox/test/message-router.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { MessageRouter, normalizeContent } from "../src/router/message-router.js";
+
+describe("MessageRouter", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+
+  beforeEach(() => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+  });
+
+  describe("normalizeContent", () => {
+    it("should wrap strings as text content", () => {
+      expect(normalizeContent("hello")).toEqual({ type: "text", text: "hello" });
+    });
+
+    it("should pass through typed objects", () => {
+      const content = { type: "data", data: { foo: 1 } };
+      expect(normalizeContent(content)).toEqual(content);
+    });
+
+    it("should wrap untyped objects as data content", () => {
+      const payload = { foo: "bar" };
+      expect(normalizeContent(payload)).toEqual({ type: "data", data: payload });
+    });
+
+    it("should wrap null as data content", () => {
+      expect(normalizeContent(null)).toEqual({ type: "data", data: null });
+    });
+  });
+
+  describe("resolveRecipients", () => {
+    it("should resolve a single string", () => {
+      const result = router.resolveRecipients("agent-1");
+      expect(result).toEqual([{ agent_id: "agent-1", kind: "to" }]);
+    });
+
+    it("should resolve an array of strings", () => {
+      const result = router.resolveRecipients(["a1", "a2"]);
+      expect(result).toEqual([
+        { agent_id: "a1", kind: "to" },
+        { agent_id: "a2", kind: "to" },
+      ]);
+    });
+
+    it("should resolve structured recipients", () => {
+      const result = router.resolveRecipients([
+        { agent_id: "a1", kind: "to" },
+        { agent_id: "a2", kind: "cc" },
+      ]);
+      expect(result).toEqual([
+        { agent_id: "a1", kind: "to" },
+        { agent_id: "a2", kind: "cc" },
+      ]);
+    });
+  });
+
+  describe("routeMessage", () => {
+    it("should create and store a message", async () => {
+      const message = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello bob",
+      });
+
+      expect(message.id).toBeTruthy();
+      expect(message.sender_id).toBe("alice");
+      expect(message.recipients[0].agent_id).toBe("bob");
+      expect(message.content).toEqual({ type: "text", text: "hello bob" });
+      expect(message.scope).toBe("default");
+      expect(message.importance).toBe("normal");
+
+      // Should be stored
+      expect(storage.getMessage(message.id)).toBeDefined();
+    });
+
+    it("should emit message.created event", async () => {
+      let emitted: unknown = null;
+      events.on("message.created", (msg) => { emitted = msg; });
+
+      const message = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello",
+      });
+
+      expect(emitted).toBe(message);
+    });
+
+    it("should mark local agents as delivered", async () => {
+      storage.putAgent({
+        agent_id: "bob",
+        scope: "default",
+        status: "active",
+        metadata: {},
+        registered_at: "2025-01-01T00:00:00Z",
+        last_active_at: "2025-01-01T00:00:00Z",
+      });
+
+      const message = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello",
+      });
+
+      expect(message.recipients[0].delivered_at).toBeTruthy();
+    });
+
+    it("should inherit thread_tag from parent on reply", async () => {
+      const original = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "start thread",
+        threadTag: "sprint-1",
+      });
+
+      const reply = await router.routeMessage({
+        from: "bob",
+        to: "alice",
+        payload: "reply",
+        inReplyTo: original.id,
+      });
+
+      expect(reply.thread_tag).toBe("sprint-1");
+      expect(reply.in_reply_to).toBe(original.id);
+    });
+
+    it("should appear in recipient's inbox", async () => {
+      await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello",
+      });
+
+      const inbox = storage.getInbox("bob");
+      expect(inbox).toHaveLength(1);
+      expect(inbox[0].sender_id).toBe("alice");
+    });
+  });
+
+  describe("markRead / markAcknowledged", () => {
+    it("should mark a message as read", async () => {
+      const msg = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello",
+      });
+
+      expect(router.markRead(msg.id, "bob")).toBe(true);
+      const updated = storage.getMessage(msg.id)!;
+      expect(updated.recipients[0].read_at).toBeTruthy();
+    });
+
+    it("should mark a message as acknowledged", async () => {
+      const msg = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello",
+      });
+
+      expect(router.markAcknowledged(msg.id, "bob")).toBe(true);
+      const updated = storage.getMessage(msg.id)!;
+      expect(updated.recipients[0].ack_at).toBeTruthy();
+    });
+
+    it("should return false for nonexistent message", () => {
+      expect(router.markRead("nonexistent", "bob")).toBe(false);
+    });
+
+    it("should return false for non-recipient", async () => {
+      const msg = await router.routeMessage({
+        from: "alice",
+        to: "bob",
+        payload: "hello",
+      });
+      expect(router.markRead(msg.id, "charlie")).toBe(false);
+    });
+  });
+});