agent-inbox 0.1.8 → 0.2.0

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "agent-inbox",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Agent Inbox — message routing, traceability, and MCP tools for multi-agent systems",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "agent-inbox": "dist/cli.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -37,16 +40,21 @@
     "ulid": "^2.3.0"
   },
   "peerDependencies": {
-    "@multi-agent-protocol/sdk": "^0.1.4"
+    "@multi-agent-protocol/sdk": "^0.1.4",
+    "agentic-mesh": ">=0.2.0"
   },
   "peerDependenciesMeta": {
     "@multi-agent-protocol/sdk": {
       "optional": true
+    },
+    "agentic-mesh": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
+    "agentic-mesh": "^0.2.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/src/cli.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for agent-inbox.
+ *
+ * Usage:
+ *   agent-inbox              # IPC server mode (default)
+ *   agent-inbox mcp          # MCP stdio server (standalone or proxy if INBOX_SOCKET_PATH set)
+ *   agent-inbox mcp-proxy    # MCP proxy to existing IPC socket
+ *
+ * Environment variables:
+ *   INBOX_SOCKET_PATH   — IPC socket path (also triggers proxy mode for `mcp`)
+ *   INBOX_SQLITE_PATH   — SQLite DB path (default: in-memory)
+ *   INBOX_SCOPE          — Message scope (default: "default")
+ *   INBOX_AGENT_ID       — Agent ID for proxy mode (default: "anonymous")
+ *   INBOX_HTTP_PORT      — HTTP port for JSON-RPC (0 = disabled)
+ *   INBOX_MAP_ENABLED    — Enable MAP transport ("true")
+ *   INBOX_MAP_SERVER     — MAP server URL
+ */
+
+import { EventEmitter } from "node:events";
+import * as path from "node:path";
+import * as os from "node:os";
+import { InMemoryStorage } from "./storage/memory.js";
+import { SqliteStorage } from "./storage/sqlite.js";
+import { MessageRouter } from "./router/message-router.js";
+import { TraceabilityLayer } from "./traceability/traceability.js";
+import { InboxMcpServer } from "./mcp/mcp-server.js";
+import type { Storage } from "./storage/interface.js";
+
+function defaultSocketPath(): string {
+  return path.join(os.homedir(), ".claude", "agent-inbox", "inbox.sock");
+}
+
+const mode = process.argv[2] ?? "mcp";
+
+if (mode === "mcp-proxy" || (mode === "mcp" && process.env.INBOX_SOCKET_PATH)) {
+  // MCP proxy mode — forward tool calls to an existing inbox IPC socket
+  const { InboxMcpProxy } = await import("./mcp/mcp-proxy.js");
+  const socketPath = process.env.INBOX_SOCKET_PATH ?? defaultSocketPath();
+  const agentId = process.env.INBOX_AGENT_ID ?? "anonymous";
+  const scope = process.env.INBOX_SCOPE ?? "default";
+  console.error(`[agent-inbox] MCP proxy mode → ${socketPath} (agent: ${agentId})`);
+  const proxy = new InboxMcpProxy(socketPath, agentId, scope);
+  proxy.start().catch((err) => {
+    console.error("MCP proxy failed:", err);
+    process.exit(1);
+  });
+} else if (mode === "mcp") {
+  // MCP standalone mode — stdio transport, own storage
+  const scope = process.env.INBOX_SCOPE ?? "default";
+  const sqlitePath = process.env.INBOX_SQLITE_PATH;
+  const storage: Storage = sqlitePath
+    ? new SqliteStorage({ path: sqlitePath })
+    : new InMemoryStorage();
+  const events = new EventEmitter();
+  const router = new MessageRouter(storage, events, scope);
+  const _traceability = new TraceabilityLayer(storage, events);
+  const mcpServer = new InboxMcpServer(router, storage, scope);
+  console.error("[agent-inbox] MCP standalone mode (stdio)");
+  mcpServer.start().catch((err) => {
+    console.error("MCP server failed:", err);
+    process.exit(1);
+  });
+} else if (mode === "ipc") {
+  const { createAgentInbox } = await import("./index.js");
+  const httpPort = process.env.INBOX_HTTP_PORT
+    ? parseInt(process.env.INBOX_HTTP_PORT, 10)
+    : 0;
+  const sqlitePath = process.env.INBOX_SQLITE_PATH;
+
+  createAgentInbox({ httpPort, sqlitePath })
+    .then((inbox) => {
+      console.error(
+        `[agent-inbox] IPC server listening on ${process.env.INBOX_SOCKET_PATH ?? defaultSocketPath()}`
+      );
+      process.on("SIGINT", async () => {
+        await inbox.stop();
+        process.exit(0);
+      });
+      process.on("SIGTERM", async () => {
+        await inbox.stop();
+        process.exit(0);
+      });
+    })
+    .catch((err) => {
+      console.error("Failed to start Agent Inbox:", err);
+      process.exit(1);
+    });
+} else {
+  console.error(`Unknown mode: ${mode}`);
+  console.error("Usage: agent-inbox [mcp|mcp-proxy|ipc]");
+  process.exit(1);
+}

package/src/federation/connection-manager.ts

@@ -15,7 +15,11 @@ import type {
   MapConnection,
   MapAgentConnectionClass,
   IncomingMapMessage,
+  MeshPeerLike,
+  MeshFederationGateway,
 } from "../map/map-client.js";
+import type { MeshConnector } from "../mesh/mesh-connector.js";
+import { inboxMessageToMap } from "../mesh/type-mapper.js";
 import { RoutingEngine } from "./routing-engine.js";
 import { DeliveryQueue } from "./delivery-queue.js";
 import { TrustManager } from "./trust.js";
@@ -49,8 +53,11 @@ export type IncomingMessageHandler = (incoming: {
 export class ConnectionManager {
   private peers = new Map<string, FederationLink>();
   private connections = new Map<string, MapConnection>();
+  private gateways = new Map<string, MeshFederationGateway>();
   private systemId: SystemId;
   private sdkClass: MapAgentConnectionClass | null;
+  private meshConnector: MeshConnector | null;
+  private meshPeer: MeshPeerLike | null;
   private onIncoming: IncomingMessageHandler | null;
   readonly routing: RoutingEngine;
   readonly queue: DeliveryQueue;
@@ -61,6 +68,9 @@ export class ConnectionManager {
     private config: FederationConfig = {},
     opts?: {
       sdkClass?: MapAgentConnectionClass;
+      meshConnector?: MeshConnector;
+      /** Full MeshPeer for Phase 2 FederationGateway delegation */
+      meshPeer?: MeshPeerLike;
       onIncomingMessage?: IncomingMessageHandler;
     }
   ) {
@@ -69,6 +79,8 @@ export class ConnectionManager {
     this.queue = new DeliveryQueue(events, config.deliveryQueue);
     this.trust = new TrustManager(config.trust);
     this.sdkClass = opts?.sdkClass ?? null;
+    this.meshConnector = opts?.meshConnector ?? null;
+    this.meshPeer = opts?.meshPeer ?? null;
     this.onIncoming = opts?.onIncomingMessage ?? null;
 
     // Wire up flush-on-reconnect
@@ -104,6 +116,12 @@ export class ConnectionManager {
    * Returns the federation link, or throws if trust check fails.
    */
   async federate(peer: FederationPeerConfig): Promise<FederationLink> {
+    if (!peer.url && !peer.meshPeerId) {
+      throw new Error(
+        `Federation peer "${peer.systemId}" must have either url or meshPeerId`
+      );
+    }
+
     // Trust check
     if (!this.trust.canConnect(peer.systemId)) {
       throw new Error(
@@ -111,9 +129,62 @@ export class ConnectionManager {
       );
     }
 
-    // Open real MAP connection if SDK is available
     let conn: MapConnection | undefined;
-    if (this.sdkClass) {
+    let transport: "websocket" | "mesh" = "websocket";
+
+    if (peer.meshPeerId && this.meshPeer) {
+      // Phase 2: Full MeshPeer integration with FederationGateway (v0.2.0+)
+      transport = "mesh";
+      try {
+        // Try to get an existing gateway first (e.g. pre-connected in test setup),
+        // otherwise create one via federateWith()
+        let gateway: MeshFederationGateway | undefined =
+          this.meshPeer.getFederationGateway(peer.systemId);
+        if (!gateway) {
+          gateway = await this.meshPeer.federateWith(peer.systemId, {
+            localSystemId: this.meshPeer.peerId,
+            remoteSystemId: peer.systemId,
+            buffer: { enabled: true, maxMessages: 1000 },
+            routing: { maxHops: 5, trackPath: true },
+          });
+        }
+
+        this.gateways.set(peer.systemId, gateway);
+
+        // Listen for incoming federated messages
+        gateway.on("message:received", (envelope: unknown) => {
+          const env = envelope as { payload?: { from?: string; payload?: unknown; meta?: Record<string, unknown> } };
+          if (env.payload) {
+            this.handlePeerMessage(peer.systemId, {
+              from: env.payload.from ?? peer.systemId,
+              payload: env.payload.payload,
+              meta: env.payload.meta,
+            });
+          }
+        });
+      } catch (err) {
+        throw new Error(
+          `Mesh federation connection failed for "${peer.systemId}": ${err instanceof Error ? err.message : err}`
+        );
+      }
+    } else if (peer.meshPeerId && this.meshConnector) {
+      // Phase 1 fallback: Mesh transport via raw channel (no MeshPeer)
+      transport = "mesh";
+      try {
+        conn = await this.meshConnector.connect(peer.meshPeerId);
+
+        conn.onMessage((msg: IncomingMapMessage) => {
+          this.handlePeerMessage(peer.systemId, msg);
+        });
+
+        this.connections.set(peer.systemId, conn);
+      } catch (err) {
+        throw new Error(
+          `Mesh federation connection failed for "${peer.systemId}": ${err instanceof Error ? err.message : err}`
+        );
+      }
+    } else if (peer.url && this.sdkClass) {
+      // WebSocket transport — connect via MAP SDK
       try {
         conn = await this.sdkClass.connect(peer.url, {
           name: this.systemId.id,
@@ -133,7 +204,6 @@ export class ConnectionManager {
           },
         });
 
-        // Register incoming message handler
         conn.onMessage((msg: IncomingMapMessage) => {
           this.handlePeerMessage(peer.systemId, msg);
         });
@@ -151,7 +221,8 @@ export class ConnectionManager {
       sessionId: crypto.randomUUID(),
       status: "connected",
       exposure: peer.exposure ?? { agents: "all" },
-      url: peer.url,
+      url: peer.url ?? "",
+      transport,
       connectedAt: new Date().toISOString(),
     };
 
@@ -213,10 +284,13 @@ export class ConnectionManager {
 
       const link = this.peers.get(peerId);
       if (!link || link.status !== "connected") {
-        // TODO: When resolved peerId has no peer link (e.g., system-qualified address
-        // targeting a system we're not directly connected to), fall through to
-        // handleUnknownRoute so broadcast/hierarchical strategies can attempt delivery
-        // via connected peers or upstream hubs instead of immediately queuing.
+        // No direct peer link — try broadcast/hierarchical strategies before queuing.
+        // This handles cases like system-qualified addresses (bob@system-2) targeting
+        // a system we're not directly connected to but could reach via relay or hub.
+        const strategy = this.routing.getStrategy();
+        if (strategy !== "table") {
+          return this.handleUnknownRoute(addr, message);
+        }
         this.queue.enqueue(peerId, message);
         return { delivered: false, peerId, queued: true };
       }
@@ -236,7 +310,7 @@ export class ConnectionManager {
   }
 
   /**
-   * Send a message to a peer via real connection or event emission.
+   * Send a message to a peer via FederationGateway, real connection, or event.
    * Returns true if send succeeded (or event was emitted).
    */
   private async sendToPeer(
@@ -244,9 +318,42 @@ export class ConnectionManager {
     addr: FederatedAddress,
     message: Message
   ): Promise<boolean> {
+    // Phase 2: Try FederationGateway first (provides envelope, hop/loop detection)
+    const gateway = this.gateways.get(peerId);
+    if (gateway) {
+      try {
+        const mapMsg = inboxMessageToMap(message);
+        // Build a MAP-compatible message for the gateway.
+        // Use local agent address (not federated) since the gateway
+        // already handles cross-system routing. A federated `to` like
+        // { system: "system-b", agent: "bob" } would cause the remote
+        // MapServer to call routeToFederation() instead of deliverToAgent().
+        const targetAgentIds = addr.agent ? [addr.agent] : [];
+        const localTo =
+          targetAgentIds.length === 1
+            ? { agent: targetAgentIds[0] }
+            : targetAgentIds.length > 1
+              ? { agents: targetAgentIds }
+              : mapMsg.to;
+        const gatewayMessage = {
+          id: message.id,
+          from: message.sender_id,
+          to: localTo,
+          timestamp: Date.now(),
+          payload: mapMsg.payload,
+          meta: mapMsg.meta,
+        };
+        const routed = await gateway.route(gatewayMessage, targetAgentIds);
+        if (routed) return true;
+        // Fall through to direct connection if gateway route fails
+      } catch {
+        // Fall through to direct connection
+      }
+    }
+
     const conn = this.connections.get(peerId);
     if (conn) {
-      // Real transport — send via MAP SDK connection
+      // Real transport — send via MAP SDK or mesh channel connection
       try {
         await conn.send(
           { agentId: addr.agent, scope: addr.scope },
@@ -391,6 +498,13 @@ export class ConnectionManager {
   /**
    * Clean up all state. Call on shutdown.
    */
+  /**
+   * Check if a FederationGateway exists for a peer.
+   */
+  hasGateway(peerId: string): boolean {
+    return this.gateways.has(peerId);
+  }
+
   async destroy(): Promise<void> {
     // Close all real connections
     for (const [peerId, conn] of this.connections) {
@@ -402,6 +516,7 @@ export class ConnectionManager {
       this.connections.delete(peerId);
     }
 
+    this.gateways.clear();
     this.routing.destroy();
     this.queue.destroy();
     this.peers.clear();

package/src/index.ts

@@ -11,6 +11,10 @@ import { InboxMcpServer } from "./mcp/mcp-server.js";
 import { MailJsonRpcServer } from "./jsonrpc/mail-server.js";
 import { PushNotifier } from "./push/notifier.js";
 import { ConnectionManager } from "./federation/connection-manager.js";
+import { MeshConnector } from "./mesh/mesh-connector.js";
+import { DeliveryBridge } from "./mesh/delivery-bridge.js";
+import type { MeshContextLike } from "./mesh/mesh-transport.js";
+import type { MeshPeerLike, MeshMapServer } from "./map/map-client.js";
 import { WarmRegistry } from "./registry/warm-registry.js";
 import type { InboxConfig } from "./types.js";
 import type { Storage } from "./storage/interface.js";
@@ -22,6 +26,7 @@ export { TraceabilityLayer } from "./traceability/traceability.js";
 export { IpcServer } from "./ipc/ipc-server.js";
 export { MapClient } from "./map/map-client.js";
 export { InboxMcpServer } from "./mcp/mcp-server.js";
+export { InboxMcpProxy } from "./mcp/mcp-proxy.js";
 export { MailJsonRpcServer } from "./jsonrpc/mail-server.js";
 export { PushNotifier, formatInboxMarkdown, parseCommand } from "./push/notifier.js";
 export type { InboxMessageEvent, NotifierConfig, InboxFileEntry } from "./push/notifier.js";
@@ -38,6 +43,14 @@ export {
   isRemoteAddress,
   isBroadcastAddress,
 } from "./federation/address.js";
+export { MeshTransport, DEFAULT_CHANNEL_NAME } from "./mesh/mesh-transport.js";
+export type { MeshContextLike, MeshChannel, MeshPeerInfo, InboxWireMessage } from "./mesh/mesh-transport.js";
+export { MeshConnector } from "./mesh/mesh-connector.js";
+export { DeliveryBridge } from "./mesh/delivery-bridge.js";
+export type { MeshDeliveryHandler } from "./mesh/delivery-bridge.js";
+export { mapMessageToInbox, inboxMessageToMap } from "./mesh/type-mapper.js";
+export type { MapMessage as MeshMapMessage, MapAddress as MeshMapAddress } from "./mesh/type-mapper.js";
+export type { MeshPeerLike, MeshAgentConnection, MeshMapServer } from "./map/map-client.js";
 export type * from "./types.js";
 export type { Storage, InboxQuery, ThreadQuery } from "./storage/interface.js";
 
@@ -101,6 +114,20 @@ export interface CreateOptions {
    *  When provided, Agent Inbox borrows this connection for messaging
    *  but does not own its lifecycle (won't disconnect it on stop()). */
   connection?: import("./map/map-client.js").MapConnection;
+  /** Phase 1: agentic-mesh context for P2P federation transport.
+   *  When provided, federation peers with meshPeerId use encrypted
+   *  mesh channels instead of WebSocket MAP connections. */
+  mesh?: {
+    context: MeshContextLike;
+    localPeerId: string;
+    channelName?: string;
+  };
+  /** Phase 2: Full MeshPeer integration.
+   *  When provided, agent-inbox registers as an agent on the MeshPeer's
+   *  MapServer, uses FederationGateway for cross-mesh routing, and
+   *  installs a DeliveryHandler bridge for incoming messages.
+   *  Supersedes `mesh` option — if both are set, meshPeer takes priority. */
+  meshPeer?: MeshPeerLike;
 }
 
 export async function createAgentInbox(
@@ -146,7 +173,35 @@ export async function createAgentInbox(
     router,
     events,
   );
-  if (opts.connection) {
+
+  // Phase 2: MeshPeer integration (if provided)
+  if (opts.meshPeer) {
+    const meshSystemId = await mapClient.connectViaMesh(opts.meshPeer);
+
+    // Install DeliveryHandler bridge on the MeshPeer's MapServer
+    const server = opts.meshPeer.server as MeshMapServer & {
+      setDeliveryHandler?(handler: unknown): unknown;
+    };
+    if (typeof server.setDeliveryHandler === "function") {
+      // Get the current handler, then replace with our bridge that delegates back
+      const prev = server.setDeliveryHandler(
+        new DeliveryBridge(storage, events, config.scope)
+      );
+      if (prev) {
+        // Re-install with the previous handler as fallback
+        server.setDeliveryHandler(
+          new DeliveryBridge(
+            storage,
+            events,
+            config.scope,
+            prev as import("./mesh/delivery-bridge.js").MeshDeliveryHandler
+          )
+        );
+      }
+    }
+
+    console.error(`Connected to MeshPeer (systemId: ${meshSystemId})`);
+  } else if (opts.connection) {
     // External connection — borrow it, don't manage its lifecycle
     mapClient.useConnection(opts.connection);
   } else if (config.map?.enabled) {
@@ -173,8 +228,28 @@ export async function createAgentInbox(
   if (opts.enableFederation || config.federation?.peers?.length) {
     const sdkClass = mapClient.getAgentConnectionClass() ?? undefined;
 
+    let meshConnector: MeshConnector | undefined;
+    if (opts.mesh) {
+      meshConnector = new MeshConnector(
+        opts.mesh.context,
+        opts.mesh.localPeerId,
+        opts.mesh.channelName
+      );
+    } else if (opts.meshPeer) {
+      // Phase 2: Derive mesh context from MeshPeer if available
+      const peerObj = opts.meshPeer as MeshPeerLike & { mesh?: MeshContextLike };
+      if (peerObj.mesh) {
+        meshConnector = new MeshConnector(
+          peerObj.mesh,
+          opts.meshPeer.peerId
+        );
+      }
+    }
+
     federation = new ConnectionManager(events, config.federation, {
       sdkClass,
+      meshConnector,
+      meshPeer: opts.meshPeer,
       onIncomingMessage: ({ from, peerId, payload, meta }) => {
         // Delegate incoming federation messages to the router.
         // The targetAgent in meta tells us which local agent this is for.
@@ -198,10 +273,12 @@ export async function createAgentInbox(
     });
     router.setFederation(federation);
 
-    // Tier 2 system ID resolution: update from MAP systemInfo if available
+    // Tier 2 system ID resolution: update from MAP or MeshPeer systemInfo
     const mapSystemName = mapClient.getSystemName();
     if (mapSystemName) {
       federation.updateSystemIdFromMap(mapSystemName);
+    } else if (opts.meshPeer) {
+      federation.updateSystemIdFromMap(opts.meshPeer.server.systemId);
     }
 
     // Connect to configured federation peers
@@ -209,7 +286,8 @@ export async function createAgentInbox(
       for (const peer of config.federation.peers) {
         try {
           await federation.federate(peer);
-          console.error(`Federated with peer: ${peer.systemId} (${peer.url})`);
+          const via = peer.meshPeerId ? `mesh:${peer.meshPeerId}` : peer.url;
+          console.error(`Federated with peer: ${peer.systemId} (${via})`);
         } catch (err) {
           console.error(
             `Failed to federate with ${peer.systemId}: ${err instanceof Error ? err.message : err}`
@@ -269,8 +347,21 @@ const isMainModule =
 if (isMainModule) {
   const mode = process.argv[2] ?? "ipc";
 
-  if (mode === "mcp") {
-    // MCP-only mode (stdio transport for Claude Code integration)
+  if (mode === "mcp-proxy" || (mode === "mcp" && process.env.INBOX_SOCKET_PATH)) {
+    // MCP proxy mode — forward all tool calls to an existing inbox IPC socket.
+    // Auto-detected when INBOX_SOCKET_PATH is set in mcp mode.
+    const { InboxMcpProxy } = await import("./mcp/mcp-proxy.js");
+    const socketPath = process.env.INBOX_SOCKET_PATH ?? defaultSocketPath();
+    const agentId = process.env.INBOX_AGENT_ID ?? "anonymous";
+    const scope = process.env.INBOX_SCOPE ?? "default";
+    console.error(`[agent-inbox] MCP proxy mode → ${socketPath} (agent: ${agentId})`);
+    const proxy = new InboxMcpProxy(socketPath, agentId, scope);
+    proxy.start().catch((err) => {
+      console.error("MCP proxy failed:", err);
+      process.exit(1);
+    });
+  } else if (mode === "mcp") {
+    // MCP standalone mode (stdio transport, own storage)
     const config = loadConfig();
     const sqlitePath = process.env.INBOX_SQLITE_PATH;
     const storage: Storage = sqlitePath

package/src/ipc/ipc-server.ts

@@ -117,6 +117,12 @@ export class IpcServer {
       case "check_inbox":
         return this.handleCheckInbox(command);
 
+      case "read_thread":
+        return this.handleReadThread(command);
+
+      case "list_agents":
+        return this.handleListAgents(command);
+
       case "emit":
         // For Phase 1, emit is acknowledged but not forwarded to MAP
         return { ok: true };
@@ -170,6 +176,58 @@ export class IpcServer {
     return { ok: true, messages };
   }
 
+  private handleReadThread(
+    command: Extract<IpcCommand, { action: "read_thread" }>
+  ): IpcResponse {
+    const messages = this.storage.getThread({
+      threadTag: command.threadTag,
+      scope: command.scope ?? "default",
+    });
+    return {
+      ok: true,
+      threadTag: command.threadTag,
+      count: messages.length,
+      messages: messages.map((m) => ({
+        ...m,
+        // Flatten for IPC consumers — keep full message but ensure key fields are accessible
+      })),
+    };
+  }
+
+  private handleListAgents(
+    command: Extract<IpcCommand, { action: "list_agents" }>
+  ): IpcResponse {
+    const agents = this.storage.listAgents(command.scope);
+    const localList = agents.map((a) => ({
+      agentId: a.agent_id,
+      name: a.display_name,
+      scope: a.scope,
+      status: a.status,
+      program: a.program,
+      lastActive: a.last_active_at,
+      location: "local" as const,
+    }));
+
+    let federatedList: IpcResponse["agents"] = [];
+    if (command.includeFederated && this.router.getFederation?.()) {
+      const federation = this.router.getFederation!()!;
+      const routingTable = federation.routing.getTable();
+      federatedList = routingTable.map((entry) => ({
+        agentId: entry.agentId,
+        peerId: entry.peerId,
+        scope: command.scope ?? "default",
+        status: entry.status,
+        location: "federated" as const,
+      }));
+    }
+
+    return {
+      ok: true,
+      count: localList.length + (federatedList?.length ?? 0),
+      agents: [...localList, ...(federatedList ?? [])],
+    };
+  }
+
   private handleNotify(
     command: Extract<IpcCommand, { action: "notify" }>
   ): IpcResponse {