agent-inbox 0.1.7 → 0.1.9

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 {

package/src/map/map-client.ts

@@ -4,6 +4,8 @@ import type { MessageRouter } from "../router/message-router.js";
 import { normalizeContent } from "../router/message-router.js";
 import { ulid } from "ulid";
 import type { Message, Recipient, InboxConfig } from "../types.js";
+import { mapMessageToInbox } from "../mesh/type-mapper.js";
+import type { MapMessage } from "../mesh/type-mapper.js";
 
 /**
  * Wrapper around @multi-agent-protocol/sdk for Agent Inbox's MAP connection.
@@ -15,6 +17,9 @@ export class MapClient {
   private conn: MapConnection | null = null;
   private agentConnectionClass: MapAgentConnectionClass | null = null;
   private externalConn = false;
+  private meshPeer: MeshPeerLike | null = null;
+  private meshAgentConn: MeshAgentConnection | null = null;
+  private meshMessageHandler: ((agentId: string, message: MeshMapMessage) => void) | null = null;
 
   constructor(
     private storage: Storage,
@@ -78,7 +83,60 @@ export class MapClient {
     });
   }
 
+  /**
+   * Connect to an agentic-mesh MeshPeer as a local agent.
+   *
+   * Registers agent-inbox as an agent on the MeshPeer's MapServer,
+   * receives messages via the MapServer's message handler mechanism.
+   * This is the Phase 2 integration path — full MAP protocol over mesh.
+   *
+   * Returns the MapServer's systemId for federation system ID resolution.
+   */
+  async connectViaMesh(meshPeer: MeshPeerLike): Promise<string> {
+    this.meshPeer = meshPeer;
+
+    // Register agent-inbox as an agent on the MeshPeer's MapServer
+    this.meshAgentConn = await meshPeer.createAgent({
+      agentId: "agent-inbox",
+      name: "Agent Inbox",
+      role: "inbox",
+      scopes: ["default"],
+      capabilities: { trajectory: { canReport: false } },
+      metadata: { type: "agent-inbox" },
+    });
+
+    // Set up message handler on the MapServer for this agent
+    this.meshMessageHandler = (_agentId: string, message: MeshMapMessage) => {
+      this.handleMeshMessage(message);
+    };
+    meshPeer.server.setMessageHandler("agent-inbox", this.meshMessageHandler);
+
+    return meshPeer.server.systemId;
+  }
+
+  /**
+   * Get the MeshPeer this client is connected to, if any.
+   */
+  getMeshPeer(): MeshPeerLike | null {
+    return this.meshPeer;
+  }
+
   async disconnect(): Promise<void> {
+    // Disconnect mesh agent connection
+    if (this.meshAgentConn) {
+      if (this.meshPeer && this.meshMessageHandler) {
+        this.meshPeer.server.removeMessageHandler("agent-inbox");
+      }
+      try {
+        await this.meshAgentConn.unregister();
+      } catch {
+        // Best-effort
+      }
+      this.meshAgentConn = null;
+      this.meshPeer = null;
+      this.meshMessageHandler = null;
+    }
+
     if (this.conn) {
       if (!this.externalConn) {
         await this.conn.disconnect();
@@ -174,6 +232,16 @@ export class MapClient {
     );
   }
 
+  /**
+   * Handle an incoming MAP message from the MeshPeer's MapServer.
+   * Uses the type-mapper for full MAP Message → Inbox Message translation.
+   */
+  private handleMeshMessage(msg: MeshMapMessage): void {
+    const inboxMsg = mapMessageToInbox(msg as MapMessage);
+    this.storage.putMessage(inboxMsg);
+    this.events.emit("message.created", inboxMsg);
+  }
+
   private handleIncoming(msg: IncomingMapMessage): void {
     const now = new Date().toISOString();
     const content = normalizeContent(msg.payload);
@@ -220,6 +288,90 @@ export class MapClient {
   }
 }
 
+// ---------------------------------------------------------------------------
+// MeshPeer integration (Phase 2)
+// ---------------------------------------------------------------------------
+
+/** Subset of agentic-mesh AgentConnection used by MapClient. */
+export interface MeshAgentConnection {
+  readonly agentId: string;
+  readonly isRegistered: boolean;
+  register(): Promise<unknown>;
+  unregister(reason?: string): Promise<void>;
+  send(
+    to: unknown,
+    payload: unknown,
+    meta?: Record<string, unknown>
+  ): Promise<{ messageId: string; delivered: string[] }>;
+  on(event: "message", handler: (message: MeshMapMessage) => void): this;
+  off(event: string, handler: (...args: unknown[]) => void): this;
+}
+
+/** Subset of agentic-mesh MapServer used by MapClient (v0.2.0+). */
+export interface MeshMapServer {
+  readonly systemId: string;
+  readonly systemName?: string;
+  /** Replace the default delivery handler. Returns the previous handler. */
+  setDeliveryHandler(handler: MeshDeliveryHandler): MeshDeliveryHandler;
+  setMessageHandler(agentId: string, handler: (agentId: string, message: MeshMapMessage) => void | Promise<void>): void;
+  removeMessageHandler(agentId: string): void;
+  registerAgent(params: {
+    agentId?: string;
+    name?: string;
+    role?: string;
+    scopes?: string[];
+    capabilities?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+  }): unknown;
+  unregisterAgent(agentId: string, reason?: string): unknown;
+}
+
+/** Subset of agentic-mesh DeliveryHandler (v0.2.0+). */
+export interface MeshDeliveryHandler {
+  deliverToAgent(agentId: string, message: MeshMapMessage): Promise<boolean>;
+  forwardToPeer(peerId: string, agentIds: string[], message: MeshMapMessage): Promise<boolean>;
+  routeToFederation?(systemId: string, agentIds: string[], message: MeshMapMessage): Promise<boolean>;
+}
+
+/** Subset of agentic-mesh MeshPeer used by MapClient and ConnectionManager (v0.2.0+). */
+export interface MeshPeerLike {
+  readonly peerId: string;
+  readonly server: MeshMapServer;
+  createAgent(config: {
+    agentId?: string;
+    name?: string;
+    role?: string;
+    scopes?: string[];
+    capabilities?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+  }): Promise<MeshAgentConnection>;
+  /** Establish a federation link with a remote MAP system. */
+  federateWith(remoteSystemId: string, config?: unknown): Promise<MeshFederationGateway>;
+  /** Get an existing federation gateway by remote system ID. */
+  getFederationGateway(remoteSystemId: string): MeshFederationGateway | undefined;
+}
+
+/** Subset of agentic-mesh FederationGateway (v0.2.0+). */
+export interface MeshFederationGateway {
+  readonly localSystemId: string;
+  readonly remoteSystemId: string;
+  readonly isConnected: boolean;
+  route(message: unknown, targetAgentIds: string[]): Promise<boolean>;
+  on(event: string, handler: (...args: unknown[]) => void): this;
+  off(event: string, handler: (...args: unknown[]) => void): this;
+}
+
+/** Subset of agentic-mesh MAP Message. */
+export interface MeshMapMessage {
+  id: string;
+  from: string;
+  to: unknown;
+  timestamp: number;
+  payload?: unknown;
+  meta?: { priority?: string; correlationId?: string; _meta?: Record<string, unknown>; [key: string]: unknown };
+  _meta?: Record<string, unknown>;
+}
+
 // --- MAP SDK type stubs (for when the SDK isn't installed) ---
 
 export interface IncomingMapMessage {