agent-inbox 0.0.1 → 0.1.1

package/test/map-client.test.ts

@@ -0,0 +1,408 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { MessageRouter } from "../src/router/message-router.js";
+import { MapClient } from "../src/map/map-client.js";
+import type {
+  MapConnection,
+  IncomingMapMessage,
+} from "../src/map/map-client.js";
+
+// ---------------------------------------------------------------------------
+// Mock MAP connection that implements the full MapConnection interface,
+// including lifecycle methods (spawn, updateState, updateMetadata, callExtension).
+// ---------------------------------------------------------------------------
+
+interface SpawnCall {
+  agentId: string;
+  name?: string;
+  role?: string;
+  scopes?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+function createMockConnection(): MapConnection & {
+  _messageHandler: ((msg: IncomingMapMessage) => void) | null;
+  _sent: Array<{ to: unknown; payload: unknown; meta?: unknown }>;
+  _spawned: SpawnCall[];
+  _state: string | null;
+  _metadata: Record<string, unknown>;
+  _extensions: Array<{ name: string; params: unknown }>;
+  _disconnected: boolean;
+  _deliver: (msg: IncomingMapMessage) => void;
+} {
+  const mock = {
+    _messageHandler: null as ((msg: IncomingMapMessage) => void) | null,
+    _sent: [] as Array<{ to: unknown; payload: unknown; meta?: unknown }>,
+    _spawned: [] as SpawnCall[],
+    _state: null as string | null,
+    _metadata: {} as Record<string, unknown>,
+    _extensions: [] as Array<{ name: string; params: unknown }>,
+    _disconnected: false,
+
+    send: async (
+      to: { agentId?: string; scope?: string },
+      payload: unknown,
+      meta?: Record<string, unknown>
+    ) => {
+      mock._sent.push({ to, payload, meta });
+    },
+    onMessage: (handler: (msg: IncomingMapMessage) => void) => {
+      mock._messageHandler = handler;
+    },
+    disconnect: async () => {
+      mock._disconnected = true;
+    },
+    spawn: async (opts: SpawnCall) => {
+      mock._spawned.push(opts);
+      return { agentId: opts.agentId };
+    },
+    updateState: async (state: string) => {
+      mock._state = state;
+    },
+    updateMetadata: async (metadata: Record<string, unknown>) => {
+      mock._metadata = { ...mock._metadata, ...metadata };
+    },
+    callExtension: async (name: string, params: Record<string, unknown>) => {
+      mock._extensions.push({ name, params });
+      return undefined;
+    },
+    systemName: "test-system",
+
+    _deliver: (msg: IncomingMapMessage) => {
+      if (mock._messageHandler) {
+        mock._messageHandler(msg);
+      }
+    },
+  };
+  return mock;
+}
+
+describe("MapClient", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+
+  beforeEach(() => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "test-scope");
+  });
+
+  describe("getConnection()", () => {
+    it("returns null when not connected", () => {
+      const client = new MapClient(storage, router, events);
+      expect(client.getConnection()).toBeNull();
+    });
+
+    it("returns the connection after manual injection", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+
+      // Inject connection via internal field (simulating what connect() does)
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      const conn = client.getConnection();
+      expect(conn).toBe(mockConn);
+    });
+
+    it("exposes lifecycle methods on the returned connection", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      const conn = client.getConnection()!;
+
+      // spawn
+      await conn.spawn!({
+        agentId: "sess_abc/coordinator",
+        name: "coordinator",
+        role: "coordinator",
+        scopes: ["swarm:gsd"],
+        metadata: { template: "gsd" },
+      });
+      expect(mockConn._spawned).toHaveLength(1);
+      expect(mockConn._spawned[0].agentId).toBe("sess_abc/coordinator");
+      expect(mockConn._spawned[0].role).toBe("coordinator");
+
+      // updateState
+      await conn.updateState!("idle");
+      expect(mockConn._state).toBe("idle");
+
+      // updateMetadata
+      await conn.updateMetadata!({ lastStopReason: "end_turn" });
+      expect(mockConn._metadata.lastStopReason).toBe("end_turn");
+
+      // callExtension
+      await conn.callExtension!("trajectory/checkpoint", {
+        checkpoint: { id: "cp-1" },
+      });
+      expect(mockConn._extensions).toHaveLength(1);
+      expect(mockConn._extensions[0].name).toBe("trajectory/checkpoint");
+    });
+
+    it("exposes systemName on the returned connection", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      const conn = client.getConnection()!;
+      expect(conn.systemName).toBe("test-system");
+    });
+  });
+
+  describe("getSystemName()", () => {
+    it("returns undefined when not connected", () => {
+      const client = new MapClient(storage, router, events);
+      expect(client.getSystemName()).toBeUndefined();
+    });
+
+    it("returns systemName from the connection", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      expect(client.getSystemName()).toBe("test-system");
+    });
+  });
+
+  describe("sendViaMap()", () => {
+    it("returns false when not connected", async () => {
+      const client = new MapClient(storage, router, events);
+      const result = await client.sendViaMap({ scope: "test" }, "hello");
+      expect(result).toBe(false);
+    });
+
+    it("sends via the connection when connected", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      const result = await client.sendViaMap(
+        { agentId: "bob", scope: "test" },
+        { text: "hello" }
+      );
+      expect(result).toBe(true);
+      expect(mockConn._sent).toHaveLength(1);
+      expect(mockConn._sent[0].to).toEqual({ agentId: "bob", scope: "test" });
+    });
+  });
+
+  describe("disconnect()", () => {
+    it("disconnects and nulls the connection", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      expect(client.connected).toBe(true);
+      await client.disconnect();
+      expect(client.connected).toBe(false);
+      expect(client.getConnection()).toBeNull();
+      expect(mockConn._disconnected).toBe(true);
+    });
+  });
+
+  describe("incoming message handling", () => {
+    it("stores incoming MAP messages in storage", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      // Simulate connect's onMessage registration
+      mockConn.onMessage((msg) => {
+        (client as unknown as { handleIncoming: (m: IncomingMapMessage) => void }).handleIncoming(msg);
+      });
+
+      const messageCreated: unknown[] = [];
+      events.on("message.created", (m) => messageCreated.push(m));
+
+      mockConn._deliver({
+        from: "alice",
+        payload: "hello from federation",
+        timestamp: new Date().toISOString(),
+      });
+
+      expect(messageCreated).toHaveLength(1);
+      const stored = storage.getInbox("default");
+      // Message should be in storage (may be under scope "default")
+      const allMessages = storage.getInbox("default");
+      expect(allMessages.length).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("useConnection() — external connection injection", () => {
+    it("accepts an external connection", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+
+      expect(client.connected).toBe(false);
+      client.useConnection(mockConn);
+      expect(client.connected).toBe(true);
+      expect(client.getConnection()).toBe(mockConn);
+    });
+
+    it("wires up incoming message handling automatically", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      const messageCreated: unknown[] = [];
+      events.on("message.created", (m) => messageCreated.push(m));
+
+      mockConn._deliver({
+        from: "external-agent",
+        payload: "hello via external connection",
+        timestamp: new Date().toISOString(),
+      });
+
+      expect(messageCreated).toHaveLength(1);
+    });
+
+    it("does not disconnect the external connection on disconnect()", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      await client.disconnect();
+
+      // Client detaches but does NOT close the external connection
+      expect(client.connected).toBe(false);
+      expect(client.getConnection()).toBeNull();
+      expect(mockConn._disconnected).toBe(false); // caller still owns it
+    });
+
+    it("disconnects self-created connections on disconnect()", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      // Simulate self-created connection (not via useConnection)
+      (client as unknown as { conn: MapConnection }).conn = mockConn;
+
+      await client.disconnect();
+
+      expect(mockConn._disconnected).toBe(true); // client owns it
+    });
+
+    it("allows sendViaMap through external connection", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      const result = await client.sendViaMap(
+        { agentId: "bob" },
+        { type: "text", text: "hello" }
+      );
+
+      expect(result).toBe(true);
+      expect(mockConn._sent).toHaveLength(1);
+    });
+
+    it("exposes lifecycle methods via getConnection()", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      const conn = client.getConnection()!;
+      await conn.spawn!({ agentId: "test/worker", role: "worker" });
+      await conn.updateState!("active");
+
+      expect(mockConn._spawned).toHaveLength(1);
+      expect(mockConn._state).toBe("active");
+    });
+
+    it("exposes systemName from external connection", () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      expect(client.getSystemName()).toBe("test-system");
+    });
+  });
+
+  describe("swarm sidecar composition pattern", () => {
+    it("supports the two-socket-one-process pattern", async () => {
+      // This test validates the composition pattern where swarm's sidecar
+      // creates an agent-inbox instance and uses getConnection() for lifecycle
+      // while agent-inbox handles messaging on its own socket.
+
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      // --- Messaging via agent-inbox ---
+      await client.sendViaMap(
+        { agentId: "sess_def/researcher" },
+        { type: "text", text: "research this topic" }
+      );
+      expect(mockConn._sent).toHaveLength(1);
+
+      // --- Lifecycle via getConnection() (what swarm's lifecycle socket would do) ---
+      const conn = client.getConnection()!;
+
+      // Spawn an agent
+      await conn.spawn!({
+        agentId: "sess_def/researcher",
+        name: "researcher",
+        role: "researcher",
+        scopes: ["sess_abc"],
+        metadata: { template: "gsd", isTeamRole: true },
+      });
+
+      // Update state
+      await conn.updateState!("active");
+
+      // Mark done
+      await conn.callExtension!("map/agents/unregister", {
+        agentId: "sess_def/researcher",
+        reason: "completed",
+      });
+
+      // Report trajectory
+      await conn.callExtension!("trajectory/checkpoint", {
+        checkpoint: { id: "cp-1", agentId: "sess_def/researcher" },
+      });
+
+      // Verify all operations went through the same connection
+      expect(mockConn._spawned).toHaveLength(1);
+      expect(mockConn._state).toBe("active");
+      expect(mockConn._extensions).toHaveLength(2);
+      expect(mockConn._extensions[0].name).toBe("map/agents/unregister");
+      expect(mockConn._extensions[1].name).toBe("trajectory/checkpoint");
+
+      // Total: 1 send (messaging) + lifecycle ops all on same connection
+      expect(mockConn._sent).toHaveLength(1);
+    });
+
+    it("handles multiple agents with session-based IDs", async () => {
+      const client = new MapClient(storage, router, events);
+      const mockConn = createMockConnection();
+      client.useConnection(mockConn);
+
+      const conn = client.getConnection()!;
+
+      // Spawn multiple agents with session-id/role format
+      const agents = [
+        { agentId: "sess_111/coordinator", role: "coordinator" },
+        { agentId: "sess_222/researcher", role: "researcher" },
+        { agentId: "sess_333/researcher", role: "researcher" }, // duplicate role, unique session
+        { agentId: "sess_444/architect", role: "architect" },
+      ];
+
+      for (const agent of agents) {
+        await conn.spawn!({
+          agentId: agent.agentId,
+          name: agent.role,
+          role: agent.role,
+          scopes: ["leader_sess_000"],
+          metadata: { template: "gsd", isTeamRole: true },
+        });
+      }
+
+      expect(mockConn._spawned).toHaveLength(4);
+
+      // Verify duplicate roles get unique IDs
+      const ids = mockConn._spawned.map((s) => s.agentId);
+      expect(new Set(ids).size).toBe(4); // all unique
+      expect(ids.filter((id) => id.includes("/researcher"))).toHaveLength(2);
+    });
+  });
+});

package/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);
+    });
+  });
+});