agent-inbox 0.1.8 → 0.2.0

package/CLAUDE.md

@@ -13,7 +13,7 @@ npm test              # Run all tests (vitest)
 npm run test:watch    # Watch mode
 ```
 
-All tests use vitest. Run the full suite before committing — there are 256 tests across 18 files. Tests run fast (<2s total).
+All tests use vitest. Run the full suite before committing — there are 356 tests across 27 files. Tests run fast (<6s total).
 
 ## Project layout
 
@@ -38,22 +38,31 @@ src/
   mcp/mcp-server.ts             MCP tool server (send_message, check_inbox, read_thread, list_agents)
   jsonrpc/mail-server.ts        MAP JSON-RPC mail methods
   push/notifier.ts              Inbox file writes + inbox.message event emission
+  mesh/
+    mesh-transport.ts           MapConnection impl over agentic-mesh MessageChannel
+    mesh-connector.ts           Factory for creating MeshTransport connections (MapAgentConnectionClass)
+    delivery-bridge.ts          DeliveryHandler bridge — intercepts MAP delivery → inbox storage
+    type-mapper.ts              MAP Message ↔ Inbox Message bidirectional translation
 
 test/
   federation/                   Federation tests (connection-manager, routing, queue, address, trust, integration, sdk-integration)
+  mesh/                         Mesh transport tests (mesh-transport, mesh-connector, federation-mesh, delivery-bridge, type-mapper, meshpeer-integration, e2e)
   registry/                     Warm registry tests
   *.test.ts                     Core tests (storage, router, traceability, IPC, mail-server, push)
+
+docs/
+  CLAUDE-CODE-SWARM-PROPOSAL.md   Proposal: replace claude-code-swarm's sidecar with embedded MeshPeer + agent-inbox
 ```
 
 ## Key architecture concepts
 
 ### Message flow
 
-1. Message comes in via IPC socket, MCP tool, or MAP connection
+1. Message comes in via IPC socket, MCP tool, MAP connection, or MeshPeer delivery
 2. `MessageRouter.routeMessage()` resolves recipients, normalizes content, stores the message
 3. Local recipients: message stored in their inbox via storage
 4. Remote recipients (`agent@system`): delegated to `ConnectionManager.route()`
-5. Federation sends via MAP SDK transport (or queues if peer is offline)
+5. Federation sends via FederationGateway (mesh), MAP SDK (WebSocket), or queues if peer is offline
 6. Traceability layer auto-creates conversations/threads from events
 
 ### Federation addressing
@@ -64,6 +73,20 @@ test/
 
 Parsed by `parseAddress()` in `src/federation/address.ts`.
 
+### Federation transports
+
+Two federation transport options, configurable per-peer:
+
+**WebSocket (MAP SDK):** Traditional MAP federation over WebSocket. Configure with `FederationPeerConfig.url`.
+
+**Mesh (agentic-mesh):** Encrypted P2P federation over agentic-mesh. Two integration levels:
+
+- **Phase 1 (raw channel):** `MeshTransport` wraps a `MessageChannel` behind `MapConnection`. Configure with `CreateOptions.mesh` + `FederationPeerConfig.meshPeerId`. Uses channel name `"proto:agent-inbox"`.
+
+- **Phase 2 (full MeshPeer):** Agent-inbox registers as an agent on the MeshPeer's MapServer. Uses `FederationGateway` for cross-mesh routing with envelope wrapping, hop counting, and loop detection. `DeliveryBridge` intercepts MAP message delivery → inbox storage. Configure with `CreateOptions.meshPeer`.
+
+Both transports can coexist — configure per-peer via `url` vs `meshPeerId`.
+
 ### Storage interface
 
 All storage operations go through `Storage` interface (`src/storage/interface.ts`). Two implementations: `InMemoryStorage` (tests + ephemeral) and `SQLiteStorage` (persistent). Tests always use `InMemoryStorage`.
@@ -72,6 +95,22 @@ All storage operations go through `Storage` interface (`src/storage/interface.ts
 
 The `@multi-agent-protocol/sdk` is a peer dependency loaded dynamically in `src/map/map-client.ts`. Agent Inbox works without it (IPC + MCP only, no MAP transport). The SDK class is injected into `ConnectionManager` when available.
 
+### Mesh transport (agentic-mesh) is optional
+
+[agentic-mesh](https://github.com/alexngai/agentic-mesh) is an optional peer dependency for encrypted P2P federation. When a `MeshPeer` is provided via `CreateOptions.meshPeer`, agent-inbox gets:
+
+- Direct P2P federation (no central MAP server required)
+- Encrypted tunnels (Nebula/Tailscale handle PKI and NAT traversal)
+- Federation with hop/loop detection via `FederationGateway`
+- Automatic agent discovery via MapServer registry
+- `_meta` field passthrough for inbox semantics (threading, importance, subjects)
+
+Key mesh components:
+- `MeshTransport` (`src/mesh/mesh-transport.ts`) — `MapConnection` over `MessageChannel`
+- `MeshConnector` (`src/mesh/mesh-connector.ts`) — factory implementing `MapAgentConnectionClass`
+- `DeliveryBridge` (`src/mesh/delivery-bridge.ts`) — intercepts MAP delivery for inbox storage
+- `TypeMapper` (`src/mesh/type-mapper.ts`) — bidirectional MAP ↔ Inbox message translation
+
 ### Event-driven internals
 
 Components communicate via `EventEmitter`. Key events:
@@ -90,10 +129,8 @@ Components communicate via `EventEmitter`. Key events:
 - IDs generated with `ulid` or `crypto.randomUUID()`
 - Content normalization: string payloads auto-wrapped to `{ type: "text", text: "..." }`
 - Federation tests use `MockMapServer` (in-process broker) in `test/federation/sdk-integration.test.ts`
-
-## Known design gaps
-
-- **Broadcast/hierarchical routing strategies** are unreachable through `ConnectionManager.route()` for system-qualified addresses (`bob@system-2`). `resolveRoute()` always returns `addr.system` directly, never falling through to `handleUnknownRoute()`. Agent-only addresses that would trigger it are filtered by `isRemoteAddress()`. Documented in `test/federation/integration.test.ts` and `test/federation/sdk-integration.test.ts`.
+- Mesh tests use `MockMeshContext` (linked pair) in `test/mesh/mock-mesh.ts`
+- Mesh channel name convention: protocol channels use `"proto:"` prefix (e.g., `"proto:agent-inbox"`)
 
 ## Common tasks
 

package/README.md

@@ -2,32 +2,34 @@
 
 A MAP-native message router for multi-agent systems. Provides structured inbox/outbox semantics, message threading, delivery tracking, and cross-system federation on top of the [Multi-Agent Protocol](https://github.com/anthropics/multi-agent-protocol) transport layer.
 
-Built to work with [claude-code-swarm](https://github.com/alexngai/claude-code-swarm) and any MAP-compatible agent framework.
+Built to work with [claude-code-swarm](https://github.com/alexngai/claude-code-swarm) and any MAP-compatible agent framework. Optionally integrates with [agentic-mesh](https://github.com/alexngai/agentic-mesh) for encrypted P2P federation.
 
 ## What it does
 
 - **Message routing** — Send messages between agents with `to`, `cc`, `bcc` semantics. Messages are stored in per-agent inboxes with delivery and read tracking.
 - **Threading** — Messages can be grouped by `thread_tag` and linked via `in_reply_to` for conversation threading.
 - **Traceability** — Auto-creates conversations, turns, and threads from messaging events following MAP's mail conventions.
-- **Federation** — Route messages across independent systems via MAP federation. Supports configurable routing strategies (table, broadcast, hierarchical).
+- **Federation** — Route messages across independent systems. Supports WebSocket (MAP SDK) and encrypted P2P mesh (agentic-mesh) transports, configurable per-peer. Routing strategies: table, broadcast, hierarchical.
 - **Multiple interfaces** — IPC (UNIX socket), MCP tools (stdio), MAP JSON-RPC, and event-based push via `inbox.message` events.
 
 ## Architecture
 
 ```
-Claude Code Session
-  |
-  Plugin (map-hook.mjs)
-  |
-  +-- spawn/done/trajectory --> MAP Sidecar (lifecycle)
-  |
-  +-- send/emit (messaging) --> Agent Inbox (routing + storage)
-                                  |
-                                  +-- Local delivery (same system)
-                                  +-- Federation (cross-system via MAP)
+Agent Runtime (Claude Code, OpenAI, etc.)
+  │
+  Adapter (~200 lines)
+  │
+  └── agent-inbox (routing, threading, storage, MCP tools)
+        │
+        ├── Local delivery (same system)
+        ├── Federation via MAP SDK (WebSocket)
+        └── Federation via agentic-mesh (encrypted P2P)
+              │
+              MeshPeer (MAP server, FederationGateway,
+                        agent discovery, hop/loop detection)
 ```
 
-Agent Inbox runs as an independent service alongside the MAP sidecar. The plugin dispatches messaging commands to Agent Inbox and lifecycle commands to the sidecar.
+Agent Inbox can run standalone (IPC + MCP only), with a MAP server (WebSocket federation), or with an embedded agentic-mesh `MeshPeer` (encrypted P2P federation with full MAP protocol support).
 
 ## Quick start
 
@@ -44,8 +46,10 @@ npm start
 | `INBOX_SOCKET_PATH` | `~/.claude/agent-inbox/inbox.sock` | IPC socket path |
 | `INBOX_SCOPE` | `default` | Default message scope |
 | `INBOX_SYSTEM_ID` | auto-generated | System identity for federation |
-| `MAP_SERVER_URL` | — | MAP server URL (optional) |
-| `MAP_AGENT_NAME` | `agent-inbox` | Agent name for MAP connection |
+| `INBOX_MAP_ENABLED` | `false` | Enable MAP server connection |
+| `INBOX_MAP_SERVER` | — | MAP server URL |
+| `INBOX_SQLITE_PATH` | — | SQLite database path (enables persistent storage) |
+| `INBOX_HTTP_PORT` | `0` | HTTP port for JSON-RPC endpoint |
 
 ### As an MCP tool server
 
@@ -58,6 +62,11 @@ Agent Inbox exposes 4 MCP tools that agents can call directly:
 | `read_thread` | Read all messages in a thread by `threadTag` |
 | `list_agents` | List registered agents (local and optionally federated) |
 
+```bash
+# Run in MCP mode (stdio transport for Claude Code integration)
+npm start -- mcp
+```
+
 ### IPC protocol
 
 NDJSON over UNIX socket. Commands:
@@ -86,25 +95,51 @@ Agents on different systems can message each other using `agent@system` addressi
 alice@system-1  -->  bob@system-2
 ```
 
-### Configuration
+### Transports
+
+Two federation transport options, configurable per-peer:
+
+**WebSocket (MAP SDK)** — Traditional MAP federation. Requires a reachable MAP server endpoint.
 
-Federation peers are configured explicitly:
+```typescript
+await createAgentInbox({
+  enableFederation: true,
+  config: {
+    federation: {
+      peers: [{ systemId: "partner", url: "ws://partner:3001" }]
+    }
+  }
+});
+```
+
+**Mesh (agentic-mesh)** — Encrypted P2P federation via Nebula/Tailscale tunnels. No central server required. Provides hop/loop detection, message buffering, and automatic agent discovery.
 
 ```typescript
-await inbox.federate({
-  systemId: "partner-system",
-  url: "ws://partner.example.com:3001",
-  exposure: { agents: "all" },
+import { MeshPeer } from "agentic-mesh";
+
+const peer = MeshPeer.createEmbedded({ peerId: "my-system" });
+await peer.start();
+
+await createAgentInbox({
+  meshPeer: peer,
+  enableFederation: true,
+  config: {
+    federation: {
+      peers: [{ systemId: "partner", meshPeerId: "partner-peer" }]
+    }
+  }
 });
 ```
 
+Both transports can coexist — some peers use WebSocket, others use mesh.
+
 ### Routing strategies
 
 | Strategy | Behavior |
 |----------|----------|
 | `table` (default) | In-memory routing table populated from peer exposure data. TTL-based expiry. |
 | `broadcast` | Forward to all connected peers. First responder wins. |
-| `hierarchical` | Local table first, then delegate to upstream hubs. |
+| `hierarchical` | Local table first, then delegate to upstream hubs. Works with system-qualified addresses for indirect relay. |
 
 ### Trust
 
@@ -153,6 +188,11 @@ src/
     mail-server.ts              MAP JSON-RPC mail methods
   push/
     notifier.ts                 Inbox file writes + inbox.message event emission
+  mesh/
+    mesh-transport.ts           MapConnection impl over agentic-mesh MessageChannel
+    mesh-connector.ts           Factory for MeshTransport connections
+    delivery-bridge.ts          DeliveryHandler bridge (MAP delivery → inbox storage)
+    type-mapper.ts              Bidirectional MAP ↔ Inbox message translation
 ```
 
 ## Testing
@@ -162,7 +202,7 @@ npm test              # Run all tests
 npm run test:watch    # Watch mode
 ```
 
-256 tests across 18 test files covering:
+357 tests across 27 test files covering:
 
 - Storage (in-memory + SQLite)
 - Message routing and content normalization
@@ -174,6 +214,9 @@ npm run test:watch    # Watch mode
 - MAP JSON-RPC mail methods
 - Warm agent registry lifecycle
 - Push model (inbox.message events + inbox file writes)
+- Mesh transport (MeshTransport, MeshConnector, federation-mesh integration)
+- Mesh Phase 2 (DeliveryBridge, TypeMapper, MeshPeer integration)
+- E2E with real agentic-mesh MeshPeer instances (bidirectional messaging, reply chains, concurrent load)
 
 ## Development
 
@@ -188,7 +231,7 @@ Requires Node.js >= 18.
 ## Further reading
 
 - [docs/DESIGN.md](docs/DESIGN.md) — Detailed architecture and design decisions
-- [docs/PLAN.md](docs/PLAN.md) — Implementation plan and phasing
+- [docs/CLAUDE-CODE-SWARM-PROPOSAL.md](docs/CLAUDE-CODE-SWARM-PROPOSAL.md) — Proposal: replace claude-code-swarm's sidecar with embedded MeshPeer + agent-inbox
 
 ## License
 

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+#!/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
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/cli.js

@@ -0,0 +1,89 @@
+#!/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";
+function defaultSocketPath() {
+    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 = 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);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/federation/connection-manager.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import type { FederationConfig, FederationLink, FederationPeerConfig, Message, SystemId } from "../types.js";
-import type { MapAgentConnectionClass } from "../map/map-client.js";
+import type { MapAgentConnectionClass, MeshPeerLike } from "../map/map-client.js";
+import type { MeshConnector } from "../mesh/mesh-connector.js";
 import { RoutingEngine } from "./routing-engine.js";
 import { DeliveryQueue } from "./delivery-queue.js";
 import { TrustManager } from "./trust.js";
@@ -32,14 +33,20 @@ export declare class ConnectionManager {
     private config;
     private peers;
     private connections;
+    private gateways;
     private systemId;
     private sdkClass;
+    private meshConnector;
+    private meshPeer;
     private onIncoming;
     readonly routing: RoutingEngine;
     readonly queue: DeliveryQueue;
     readonly trust: TrustManager;
     constructor(events: EventEmitter, config?: FederationConfig, opts?: {
         sdkClass?: MapAgentConnectionClass;
+        meshConnector?: MeshConnector;
+        /** Full MeshPeer for Phase 2 FederationGateway delegation */
+        meshPeer?: MeshPeerLike;
         onIncomingMessage?: IncomingMessageHandler;
     });
     /**
@@ -64,7 +71,7 @@ export declare class ConnectionManager {
      */
     route(message: Message): Promise<DeliveryResult>;
     /**
-     * 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 sendToPeer;
@@ -100,6 +107,10 @@ export declare class ConnectionManager {
     /**
      * Clean up all state. Call on shutdown.
      */
+    /**
+     * Check if a FederationGateway exists for a peer.
+     */
+    hasGateway(peerId: string): boolean;
     destroy(): Promise<void>;
     /**
      * Resolve the system ID using tiered precedence:

package/dist/federation/connection-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../src/federation/connection-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAK3C,OAAO,KAAK,EAEV,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,OAAO,EACP,QAAQ,EACT,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAEV,uBAAuB,EAExB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,KAAK,IAAI,CAAC;AAEX;;;;;;GAMG;AACH,qBAAa,iBAAiB;IAW1B,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IAXhB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,UAAU,CAAgC;IAClD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;gBAGnB,MAAM,EAAE,YAAY,EACpB,MAAM,GAAE,gBAAqB,EACrC,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,uBAAuB,CAAC;QACnC,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;KAC5C;IA6BH;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;;OAIG;IACG,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAyDnE;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB/C;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IA6CtD;;;OAGG;YACW,UAAU;IAkCxB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;YACW,kBAAkB;IA0DhC;;OAEG;IACH,QAAQ,IAAI,cAAc,EAAE;IAI5B;;OAEG;IACH,iBAAiB,IAAI,cAAc,EAAE;IAMrC;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAInD;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIpC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAIrC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAgCvB;;;OAGG;IACH,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI;CAKnD"}
+{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../src/federation/connection-manager.ts"],"names":[],"mappings":"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"}

package/dist/federation/connection-manager.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import * as crypto from "node:crypto";
+import { inboxMessageToMap } from "../mesh/type-mapper.js";
 import { RoutingEngine } from "./routing-engine.js";
 import { DeliveryQueue } from "./delivery-queue.js";
 import { TrustManager } from "./trust.js";
@@ -18,8 +19,11 @@ export class ConnectionManager {
     config;
     peers = new Map();
     connections = new Map();
+    gateways = new Map();
     systemId;
     sdkClass;
+    meshConnector;
+    meshPeer;
     onIncoming;
     routing;
     queue;
@@ -32,6 +36,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
         this.events.on("federation.connected", (peerId) => {
@@ -64,13 +70,63 @@ export class ConnectionManager {
      * Returns the federation link, or throws if trust check fails.
      */
     async federate(peer) {
+        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(`Federation denied: system "${peer.systemId}" not in allowed servers list`);
         }
-        // Open real MAP connection if SDK is available
         let conn;
-        if (this.sdkClass) {
+        let transport = "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 = 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) => {
+                    const env = envelope;
+                    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) => {
+                    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,
@@ -89,7 +145,6 @@ export class ConnectionManager {
                         maxDelayMs: 30000,
                     },
                 });
-                // Register incoming message handler
                 conn.onMessage((msg) => {
                     this.handlePeerMessage(peer.systemId, msg);
                 });
@@ -104,7 +159,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(),
         };
         this.peers.set(peer.systemId, link);
@@ -161,10 +217,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 };
             }
@@ -181,13 +240,46 @@ export class ConnectionManager {
         return { delivered: false, error: "No remote recipients found" };
     }
     /**
-     * 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).
      */
     async sendToPeer(peerId, addr, message) {
+        // 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 }, message.content, {
                     messageId: message.id,
@@ -307,6 +399,12 @@ export class ConnectionManager {
     /**
      * Clean up all state. Call on shutdown.
      */
+    /**
+     * Check if a FederationGateway exists for a peer.
+     */
+    hasGateway(peerId) {
+        return this.gateways.has(peerId);
+    }
     async destroy() {
         // Close all real connections
         for (const [peerId, conn] of this.connections) {
@@ -318,6 +416,7 @@ export class ConnectionManager {
             }
             this.connections.delete(peerId);
         }
+        this.gateways.clear();
         this.routing.destroy();
         this.queue.destroy();
         this.peers.clear();