claude-code-swarm 0.3.3 → 0.3.5

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

@@ -0,0 +1,857 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../../src/storage/memory.js";
+import { MessageRouter } from "../../src/router/message-router.js";
+import { ConnectionManager } from "../../src/federation/connection-manager.js";
+import { WarmRegistry } from "../../src/registry/warm-registry.js";
+import {
+  parseAddress,
+  formatAddress,
+  isRemoteAddress,
+  isBroadcastAddress,
+} from "../../src/federation/address.js";
+import type { Agent, Message } from "../../src/types.js";
+import type {
+  MapConnection,
+  MapAgentConnectionClass,
+  IncomingMapMessage,
+} from "../../src/map/map-client.js";
+
+function makeAgent(id: string, scope = "default"): Agent {
+  const now = new Date().toISOString();
+  return {
+    agent_id: id,
+    display_name: id,
+    scope,
+    status: "active",
+    metadata: {},
+    registered_at: now,
+    last_active_at: now,
+  };
+}
+
+/**
+ * Integration tests — Step 19 from PLAN.md.
+ *
+ * These tests exercise the full flow across multiple components:
+ * MessageRouter + ConnectionManager + RoutingEngine + DeliveryQueue +
+ * TrustManager + WarmRegistry + address parsing.
+ */
+describe("Federation Integration", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let federation: ConnectionManager;
+  let registry: WarmRegistry;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+
+    federation = new ConnectionManager(events, {
+      systemId: "system-1",
+      trust: {
+        allowedServers: ["system-2", "hub-system"],
+        scopePermissions: {},
+        requireAuth: false,
+      },
+      routing: { strategy: "table" },
+    });
+
+    registry = new WarmRegistry(storage, events, {
+      gracePeriodMs: 5000,
+      retainExpiredMs: 30000,
+      requeueOnReconnect: true,
+    });
+
+    router.setFederation(federation);
+  });
+
+  afterEach(async () => {
+    await federation.destroy();
+    registry.destroy();
+    vi.useRealTimers();
+  });
+
+  describe("1. Federated send — local agent to remote agent", () => {
+    it("should route a message from local agent to remote agent via federation", async () => {
+      // Register local sender
+      storage.putAgent(makeAgent("agent-a"));
+
+      // Establish federation with system-2 and expose remote agent
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      federation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-c" },
+      ]);
+
+      // Track federation routing event
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+
+      // Send message from agent-a to agent-c@system-2
+      const msg = await router.routeMessage({
+        from: "agent-a",
+        to: "agent-c@system-2",
+        payload: "Hello from system-1!",
+      });
+
+      expect(msg.id).toBeDefined();
+      expect(msg.sender_id).toBe("agent-a");
+      expect(msg.recipients[0].agent_id).toBe("agent-c@system-2");
+      // Federation route completes synchronously, so delivered_at is set
+      expect(msg.recipients[0].delivered_at).toBeDefined();
+
+      // The federation route event should have fired
+      expect(routeSpy).toHaveBeenCalledWith(
+        expect.objectContaining({
+          peerId: "system-2",
+          message: expect.objectContaining({ id: msg.id }),
+        })
+      );
+    });
+
+    it("should store the message locally even when routing remotely", async () => {
+      storage.putAgent(makeAgent("agent-a"));
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      federation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-c" },
+      ]);
+
+      const msg = await router.routeMessage({
+        from: "agent-a",
+        to: "agent-c@system-2",
+        payload: "Stored locally",
+      });
+
+      const stored = storage.getMessage(msg.id);
+      expect(stored).toBeDefined();
+      expect(stored!.content).toEqual({ type: "text", text: "Stored locally" });
+    });
+  });
+
+  describe("2. Hub relay — hierarchical routing", () => {
+    it("should delegate to upstream hub for agent-only address not in routing table", async () => {
+      const hubFederation = new ConnectionManager(events, {
+        systemId: "system-1",
+        trust: {
+          allowedServers: ["hub-system"],
+          scopePermissions: {},
+          requireAuth: false,
+        },
+        routing: {
+          strategy: "hierarchical",
+          upstream: ["hub-system"],
+        },
+      });
+
+      await hubFederation.federate({
+        systemId: "hub-system",
+        url: "ws://hub:3000",
+      });
+
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+
+      // Use agent-only address (no @system) that's not in routing table.
+      // resolveRoute returns null → handleUnknownRoute → hierarchical → upstream hub
+      const msg: Message = {
+        id: "msg-hub-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "unknown-agent@hub-system", kind: "to" }],
+        content: { type: "text", text: "relay me" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await hubFederation.route(msg);
+      // Address has @hub-system so resolveRoute returns "hub-system" directly,
+      // and since hub-system is connected, it delivers
+      expect(result.delivered).toBe(true);
+      expect(result.peerId).toBe("hub-system");
+      expect(routeSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ peerId: "hub-system" })
+      );
+
+      await hubFederation.destroy();
+    });
+
+    it("should relay via upstream hub when system-qualified address has no direct peer link", async () => {
+      const hubFederation = new ConnectionManager(events, {
+        systemId: "system-1",
+        trust: {
+          allowedServers: ["hub-system"],
+          scopePermissions: {},
+          requireAuth: false,
+        },
+        routing: {
+          strategy: "hierarchical",
+          upstream: ["hub-system"],
+        },
+      });
+
+      await hubFederation.federate({
+        systemId: "hub-system",
+        url: "ws://hub:3000",
+      });
+
+      // Route to far-system which has no direct peer link.
+      // With hierarchical strategy, falls through to upstream hub relay.
+      const msg: Message = {
+        id: "msg-hub-2",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-x@far-system", kind: "to" }],
+        content: { type: "text", text: "no direct link" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await hubFederation.route(msg);
+      // Hierarchical strategy delegates to upstream hub instead of queuing
+      expect(result.delivered).toBe(true);
+      expect(result.peerId).toBe("hub-system");
+
+      await hubFederation.destroy();
+    });
+
+    it("should queue when system-qualified address has no peer link (table strategy)", async () => {
+      const tableFederation = new ConnectionManager(events, {
+        systemId: "system-1",
+        trust: {
+          allowedServers: [],
+          scopePermissions: {},
+          requireAuth: false,
+        },
+        routing: {
+          strategy: "table",
+        },
+      });
+
+      // No peers connected — route to far-system queues immediately
+      const msg: Message = {
+        id: "msg-table-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-x@far-system", kind: "to" }],
+        content: { type: "text", text: "no direct link" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await tableFederation.route(msg);
+      expect(result.delivered).toBe(false);
+      expect(result.queued).toBe(true);
+      expect(result.peerId).toBe("far-system");
+
+      await tableFederation.destroy();
+    });
+  });
+
+  describe("3. Warm registry — disconnect, queue, reconnect, flush", () => {
+    it("should queue messages for away agent and flush on reconnect", async () => {
+      // Register agent-b via warm registry
+      registry.register(makeAgent("agent-b"));
+      expect(registry.getStatus("agent-b")).toBe("active");
+
+      // Agent disconnects — goes to "away"
+      registry.disconnect("agent-b");
+      expect(registry.getStatus("agent-b")).toBe("away");
+      expect(registry.isRoutable("agent-b")).toBe(true);
+
+      // Agent reconnects before grace period
+      registry.reconnect("agent-b");
+      expect(registry.getStatus("agent-b")).toBe("active");
+
+      // Verify it didn't expire
+      vi.advanceTimersByTime(6000);
+      expect(registry.getStatus("agent-b")).toBe("active");
+    });
+
+    it("should expire agent after grace period", () => {
+      registry.register(makeAgent("agent-b"));
+      registry.disconnect("agent-b");
+
+      vi.advanceTimersByTime(5001);
+      expect(registry.getStatus("agent-b")).toBe("expired");
+      expect(registry.isRoutable("agent-b")).toBe(false);
+    });
+  });
+
+  describe("4. Offline peer — messages queue and flush on reconnect", () => {
+    it("should queue messages when peer goes offline and flush on reconnect", async () => {
+      // Federate then disconnect peer
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      federation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-c" },
+      ]);
+      await federation.disconnect("system-2");
+
+      // Send message to offline peer — should be queued
+      const msg: Message = {
+        id: "msg-q-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-c@system-2", kind: "to" }],
+        content: { type: "text", text: "you're offline" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await federation.route(msg);
+      expect(result.delivered).toBe(false);
+      expect(result.queued).toBe(true);
+      expect(federation.queue.size("system-2")).toBe(1);
+
+      // Peer reconnects — queue should flush
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+      events.on("federation.flushing", (data) => {
+        expect(data.count).toBe(1);
+      });
+
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+
+      // Queue should be drained
+      expect(federation.queue.size("system-2")).toBe(0);
+    });
+  });
+
+  describe("5. Trust enforcement — unknown system rejected", () => {
+    it("should reject federation from unknown system", async () => {
+      await expect(
+        federation.federate({
+          systemId: "evil-system",
+          url: "ws://evil:6666",
+        })
+      ).rejects.toThrow("Federation denied");
+
+      expect(federation.isConnected("evil-system")).toBe(false);
+    });
+
+    it("should allow federation from approved systems", async () => {
+      const link = await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      expect(link.status).toBe("connected");
+    });
+
+    it("should deny routing when scope trust fails", async () => {
+      const restrictedFederation = new ConnectionManager(events, {
+        systemId: "system-1",
+        trust: {
+          allowedServers: ["system-2"],
+          scopePermissions: { "system-2": ["allowed-scope"] },
+          requireAuth: false,
+        },
+      });
+
+      await restrictedFederation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      restrictedFederation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-x" },
+      ]);
+
+      // Scope trust is currently a stub (always passes), so this verifies
+      // the trust check is called in the route path
+      const msg: Message = {
+        id: "msg-trust-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-x@system-2", kind: "to" }],
+        content: { type: "text", text: "test" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await restrictedFederation.route(msg);
+      // Stub always allows, so delivery succeeds
+      expect(result.delivered).toBe(true);
+
+      await restrictedFederation.destroy();
+    });
+  });
+
+  describe("6. Routing strategies", () => {
+    // NOTE: In the current implementation, route() only processes recipients
+    // where isRemoteAddress() is true (i.e., address contains @system).
+    // resolveRoute() returns addr.system directly for system-qualified addresses.
+    // This means handleUnknownRoute (broadcast/hierarchical) is only reachable
+    // via direct calls or future changes to support agent-only federation routing.
+    // These tests verify the actual routing behavior through ConnectionManager.
+
+    it("table strategy: system-qualified address delivers to connected peer", async () => {
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+
+      const msg: Message = {
+        id: "msg-direct-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "unknown-agent@system-2", kind: "to" }],
+        content: { type: "text", text: "direct to system" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await federation.route(msg);
+      expect(result.delivered).toBe(true);
+      expect(result.peerId).toBe("system-2");
+      expect(routeSpy).toHaveBeenCalled();
+    });
+
+    it("table strategy: system-qualified address queues when peer offline", async () => {
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      await federation.disconnect("system-2");
+
+      const msg: Message = {
+        id: "msg-miss-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-c@system-2", kind: "to" }],
+        content: { type: "text", text: "peer offline" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await federation.route(msg);
+      expect(result.delivered).toBe(false);
+      expect(result.queued).toBe(true);
+      expect(result.peerId).toBe("system-2");
+    });
+
+    it("agent-only addresses are not treated as remote", async () => {
+      const msg: Message = {
+        id: "msg-local-1",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "local-agent", kind: "to" }],
+        content: { type: "text", text: "local only" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+
+      const result = await federation.route(msg);
+      expect(result.delivered).toBe(false);
+      expect(result.error).toContain("No remote recipients");
+    });
+
+    it("routing engine resolveRoute uses table for agent-only lookups", () => {
+      federation.routing.updateFromExposure("system-2", [
+        { agentId: "known-agent" },
+      ]);
+      expect(federation.routing.resolveRoute({ agent: "known-agent" })).toBe(
+        "system-2"
+      );
+      expect(
+        federation.routing.resolveRoute({ agent: "unknown-agent" })
+      ).toBeNull();
+    });
+
+    it("routing engine strategy accessors work correctly", () => {
+      expect(federation.routing.getStrategy()).toBe("table");
+
+      const broadcastCm = new ConnectionManager(events, {
+        systemId: "s",
+        routing: { strategy: "broadcast", broadcastTimeout: 3000 },
+      });
+      expect(broadcastCm.routing.getStrategy()).toBe("broadcast");
+      expect(broadcastCm.routing.getBroadcastTimeout()).toBe(3000);
+      broadcastCm.destroy();
+
+      const hierCm = new ConnectionManager(events, {
+        systemId: "s",
+        routing: { strategy: "hierarchical", upstream: ["hub-1"] },
+      });
+      expect(hierCm.routing.getStrategy()).toBe("hierarchical");
+      expect(hierCm.routing.getUpstream()).toEqual(["hub-1"]);
+      hierCm.destroy();
+    });
+
+    it("routing table entries expire based on TTL", () => {
+      const shortTtlCm = new ConnectionManager(events, {
+        systemId: "s",
+        routing: { strategy: "table", tableTTL: 100 },
+      });
+
+      shortTtlCm.routing.updateFromExposure("peer-1", [
+        { agentId: "temp-agent" },
+      ]);
+      expect(shortTtlCm.routing.lookupAgent("temp-agent")).toBe("peer-1");
+
+      // Advance past TTL
+      vi.advanceTimersByTime(150);
+      expect(shortTtlCm.routing.lookupAgent("temp-agent")).toBeNull();
+
+      shortTtlCm.destroy();
+    });
+  });
+
+  describe("7. Address parsing — all formats resolve correctly", () => {
+    it("local address", () => {
+      const addr = parseAddress("agent-beta");
+      expect(addr).toEqual({ agent: "agent-beta" });
+      expect(isRemoteAddress(addr)).toBe(false);
+      expect(isBroadcastAddress(addr)).toBe(false);
+      expect(formatAddress(addr)).toBe("agent-beta");
+    });
+
+    it("federated address", () => {
+      const addr = parseAddress("agent-beta@backend-team");
+      expect(addr).toEqual({ agent: "agent-beta", system: "backend-team" });
+      expect(isRemoteAddress(addr)).toBe(true);
+      expect(isBroadcastAddress(addr)).toBe(false);
+      expect(formatAddress(addr)).toBe("agent-beta@backend-team");
+    });
+
+    it("broadcast to system", () => {
+      const addr = parseAddress("@backend-team");
+      expect(addr).toEqual({ system: "backend-team" });
+      expect(isRemoteAddress(addr)).toBe(true);
+      expect(isBroadcastAddress(addr)).toBe(true);
+      expect(formatAddress(addr)).toBe("@backend-team");
+    });
+
+    it("scoped federated address", () => {
+      const addr = parseAddress("agent-beta@backend-team/engineering");
+      expect(addr).toEqual({
+        agent: "agent-beta",
+        system: "backend-team",
+        scope: "engineering",
+      });
+      expect(isRemoteAddress(addr)).toBe(true);
+      expect(formatAddress(addr)).toBe("agent-beta@backend-team/engineering");
+    });
+
+    it("round-trip all formats", () => {
+      const addresses = [
+        "agent-1",
+        "agent-1@system-2",
+        "@system-2",
+        "agent-1@system-2/scope-a",
+      ];
+      for (const original of addresses) {
+        expect(formatAddress(parseAddress(original))).toBe(original);
+      }
+    });
+  });
+
+  describe("8. System ID resolution", () => {
+    it("explicit config takes highest precedence", () => {
+      const cm = new ConnectionManager(events, { systemId: "explicit-id" });
+      expect(cm.getSystemId()).toEqual({ id: "explicit-id", source: "config" });
+      cm.destroy();
+    });
+
+    it("MAP systemInfo is tier 2 (overrides auto, not config)", () => {
+      const cm = new ConnectionManager(events, {}); // auto-generated
+      expect(cm.getSystemId().source).toBe("auto");
+
+      cm.updateSystemIdFromMap("map-derived");
+      expect(cm.getSystemId()).toEqual({ id: "map-derived", source: "map" });
+      cm.destroy();
+    });
+
+    it("explicit config cannot be overridden by MAP", () => {
+      const cm = new ConnectionManager(events, { systemId: "explicit-id" });
+      cm.updateSystemIdFromMap("map-derived");
+      expect(cm.getSystemId()).toEqual({ id: "explicit-id", source: "config" });
+      cm.destroy();
+    });
+
+    it("auto-generated ID is stable format", () => {
+      const cm = new ConnectionManager(events, {});
+      const sid = cm.getSystemId();
+      expect(sid.source).toBe("auto");
+      expect(sid.id).toMatch(/^inbox-[0-9a-f]{8}$/);
+      cm.destroy();
+    });
+  });
+
+  describe("End-to-end: full message lifecycle with federation", () => {
+    it("should handle send → store → route → queue → flush cycle", async () => {
+      // Setup: local agent + federated peer
+      storage.putAgent(makeAgent("agent-a"));
+      registry.register(makeAgent("agent-a"));
+
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      federation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-c" },
+      ]);
+
+      // Step 1: Send a message — should route via federation
+      const msg1 = await router.routeMessage({
+        from: "agent-a",
+        to: "agent-c@system-2",
+        payload: "Hello agent-c!",
+        subject: "Greeting",
+      });
+      expect(storage.getMessage(msg1.id)).toBeDefined();
+
+      // Step 2: Peer goes offline — next message gets queued
+      await federation.disconnect("system-2");
+
+      // Direct route (not via router, to test queue)
+      const msg2: Message = {
+        id: "msg-e2e-2",
+        scope: "default",
+        sender_id: "agent-a",
+        recipients: [{ agent_id: "agent-c@system-2", kind: "to" }],
+        content: { type: "text", text: "Are you there?" },
+        importance: "normal",
+        metadata: {},
+        created_at: new Date().toISOString(),
+      };
+      const result2 = await federation.route(msg2);
+      expect(result2.queued).toBe(true);
+      expect(federation.queue.size("system-2")).toBe(1);
+
+      // Step 3: Peer comes back — queue flushes
+      const flushSpy = vi.fn();
+      events.on("federation.flushing", flushSpy);
+
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+
+      expect(flushSpy).toHaveBeenCalledWith(
+        expect.objectContaining({ peerId: "system-2", count: 1 })
+      );
+      expect(federation.queue.size("system-2")).toBe(0);
+    });
+
+    it("should handle incoming federation message and store with correct recipient", async () => {
+      // Setup: local agent that should receive the message
+      storage.putAgent(makeAgent("agent-b"));
+
+      // Create federation with transport mock that captures onMessage handlers
+      const peerMessageHandlers: Array<(msg: IncomingMapMessage) => void> = [];
+      const sentMessages: Array<{
+        to: { agentId?: string; scope?: string };
+        payload: unknown;
+        meta?: Record<string, unknown>;
+      }> = [];
+
+      const mockSdkClass: MapAgentConnectionClass = {
+        connect: async () => ({
+          send: async (to, payload, meta) => {
+            sentMessages.push({ to, payload, meta });
+          },
+          onMessage: (handler: (msg: IncomingMapMessage) => void) => {
+            peerMessageHandlers.push(handler);
+          },
+          disconnect: async () => {},
+        }),
+      };
+
+      // Create federation with real transport + incoming message handler wired to router
+      const transportFederation = new ConnectionManager(
+        events,
+        {
+          systemId: "system-1",
+          trust: {
+            allowedServers: ["system-2"],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        {
+          sdkClass: mockSdkClass,
+          onIncomingMessage: ({ from, peerId, payload, meta }) => {
+            const targetAgent = (meta?.targetAgent as string) ?? from;
+            router.routeMessage({
+              from: `${from}@${peerId}`,
+              to: targetAgent,
+              payload,
+              subject: meta?.subject as string | undefined,
+              importance: meta?.importance as "high" | "normal" | undefined,
+              metadata: meta,
+            });
+          },
+        }
+      );
+      router.setFederation(transportFederation);
+
+      await transportFederation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+
+      // Simulate peer sending a message targeting local agent-b
+      expect(peerMessageHandlers).toHaveLength(1);
+      peerMessageHandlers[0]({
+        from: "agent-c",
+        payload: { type: "text", text: "Hello from system-2!" },
+        meta: {
+          targetAgent: "agent-b",
+          senderId: "agent-c",
+          sourceSystem: "system-2",
+          subject: "Cross-system greeting",
+          importance: "high",
+        },
+      });
+
+      // Wait for async routeMessage to complete
+      await vi.advanceTimersByTimeAsync(0);
+
+      // Verify the message landed in agent-b's inbox
+      const inbox = storage.getInbox("agent-b");
+      expect(inbox).toHaveLength(1);
+      expect(inbox[0].sender_id).toBe("agent-c@system-2");
+      expect(inbox[0].content).toEqual({
+        type: "text",
+        text: "Hello from system-2!",
+      });
+      expect(inbox[0].subject).toBe("Cross-system greeting");
+      expect(inbox[0].importance).toBe("high");
+
+      // Verify recipient is agent-b and is marked delivered
+      expect(inbox[0].recipients[0].agent_id).toBe("agent-b");
+      expect(inbox[0].recipients[0].delivered_at).toBeDefined();
+
+      await transportFederation.destroy();
+    });
+
+    it("should round-trip: send outbound with meta, receive inbound with meta", async () => {
+      storage.putAgent(makeAgent("agent-a"));
+      storage.putAgent(makeAgent("agent-b"));
+
+      const sentMessages: Array<{
+        to: { agentId?: string; scope?: string };
+        payload: unknown;
+        meta?: Record<string, unknown>;
+      }> = [];
+
+      const mockSdkClass: MapAgentConnectionClass = {
+        connect: async () => ({
+          send: async (to, payload, meta) => {
+            sentMessages.push({ to, payload, meta });
+          },
+          onMessage: () => {},
+          disconnect: async () => {},
+        }),
+      };
+
+      const transportFederation = new ConnectionManager(
+        events,
+        {
+          systemId: "system-1",
+          trust: {
+            allowedServers: ["system-2"],
+            scopePermissions: {},
+            requireAuth: false,
+          },
+        },
+        { sdkClass: mockSdkClass }
+      );
+      router.setFederation(transportFederation);
+
+      await transportFederation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      transportFederation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-c" },
+      ]);
+
+      // Send a message with subject and thread
+      await router.routeMessage({
+        from: "agent-a",
+        to: "agent-c@system-2",
+        payload: "Thread message",
+        subject: "Important thread",
+        threadTag: "thread-1",
+        importance: "high",
+      });
+
+      // Verify the outbound meta includes targetAgent and all fields
+      expect(sentMessages).toHaveLength(1);
+      expect(sentMessages[0].to.agentId).toBe("agent-c");
+      expect(sentMessages[0].meta?.targetAgent).toBe("agent-c");
+      expect(sentMessages[0].meta?.senderId).toBe("agent-a");
+      expect(sentMessages[0].meta?.sourceSystem).toBe("system-1");
+      expect(sentMessages[0].meta?.subject).toBe("Important thread");
+      expect(sentMessages[0].meta?.threadTag).toBe("thread-1");
+      expect(sentMessages[0].meta?.importance).toBe("high");
+
+      await transportFederation.destroy();
+    });
+
+    it("should handle mixed local and remote recipients", async () => {
+      storage.putAgent(makeAgent("agent-a"));
+      storage.putAgent(makeAgent("agent-b"));
+
+      await federation.federate({
+        systemId: "system-2",
+        url: "ws://system-2:3001",
+      });
+      federation.routing.updateFromExposure("system-2", [
+        { agentId: "agent-c" },
+      ]);
+
+      const routeSpy = vi.fn();
+      events.on("federation.route", routeSpy);
+
+      const msg = await router.routeMessage({
+        from: "agent-a",
+        to: [
+          { agent_id: "agent-b", kind: "to" },
+          { agent_id: "agent-c@system-2", kind: "cc" },
+        ],
+        payload: "Hello everyone",
+      });
+
+      // Local recipient gets delivered_at
+      const localRecipient = msg.recipients.find(
+        (r) => r.agent_id === "agent-b"
+      );
+      expect(localRecipient?.delivered_at).toBeDefined();
+
+      // Remote recipient gets delivered_at from federation route (synchronous)
+      const remoteRecipient = msg.recipients.find(
+        (r) => r.agent_id === "agent-c@system-2"
+      );
+      expect(remoteRecipient?.delivered_at).toBeDefined();
+
+      // Federation route event should have fired for the remote recipient
+      expect(routeSpy).toHaveBeenCalled();
+    });
+  });
+});