agent-inbox 0.1.8 → 0.2.0

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 {

package/src/mcp/mcp-proxy.ts

@@ -0,0 +1,326 @@
+/**
+ * mcp-proxy.ts — MCP server that proxies all tools to an existing inbox IPC socket.
+ *
+ * Instead of creating its own storage/router, this connects to a running
+ * agent-inbox IPC server (e.g., the sidecar's inbox instance) and translates
+ * MCP tool calls into IPC commands.
+ *
+ * This ensures a single source of truth for messages, agents, and routing.
+ */
+
+import * as net from "node:net";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import type { IpcResponse } from "../types.js";
+
+const IPC_TIMEOUT_MS = 5000;
+const CONNECT_RETRY_MS = 500;
+const CONNECT_MAX_RETRIES = 10;
+
+export class InboxMcpProxy {
+  private mcp: McpServer;
+
+  constructor(
+    private socketPath: string,
+    private defaultAgentId: string = "anonymous",
+    private defaultScope: string = "default"
+  ) {
+    this.mcp = new McpServer({
+      name: "agent-inbox",
+      version: "0.1.0",
+    });
+
+    this.registerTools();
+  }
+
+  /**
+   * Send an IPC command to the inbox socket and return the response.
+   * Retries connection if socket is not yet available.
+   */
+  private async sendIpc(command: Record<string, unknown>): Promise<IpcResponse> {
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt < CONNECT_MAX_RETRIES; attempt++) {
+      try {
+        return await this.sendIpcOnce(command);
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        // Only retry on connection errors (socket not ready yet)
+        if (lastError.message.includes("ENOENT") || lastError.message.includes("ECONNREFUSED")) {
+          if (attempt < CONNECT_MAX_RETRIES - 1) {
+            await new Promise((r) => setTimeout(r, CONNECT_RETRY_MS));
+            continue;
+          }
+        }
+        break;
+      }
+    }
+
+    return { ok: false, error: `Inbox unavailable: ${lastError?.message ?? "unknown error"}` };
+  }
+
+  private sendIpcOnce(command: Record<string, unknown>): Promise<IpcResponse> {
+    return new Promise((resolve, reject) => {
+      const client = net.createConnection(this.socketPath);
+      let buffer = "";
+      let settled = false;
+
+      const timer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          client.destroy();
+          reject(new Error("IPC timeout"));
+        }
+      }, IPC_TIMEOUT_MS);
+
+      client.on("connect", () => {
+        client.write(JSON.stringify(command) + "\n");
+      });
+
+      client.on("data", (data) => {
+        buffer += data.toString();
+        const newlineIdx = buffer.indexOf("\n");
+        if (newlineIdx !== -1) {
+          clearTimeout(timer);
+          settled = true;
+          const line = buffer.slice(0, newlineIdx).trim();
+          client.destroy();
+          try {
+            resolve(JSON.parse(line) as IpcResponse);
+          } catch {
+            reject(new Error("Invalid IPC response"));
+          }
+        }
+      });
+
+      client.on("error", (err) => {
+        if (!settled) {
+          clearTimeout(timer);
+          settled = true;
+          reject(err);
+        }
+      });
+    });
+  }
+
+  private registerTools(): void {
+    this.mcp.tool(
+      "send_message",
+      "Send a message to one or more agents. Supports replies (inReplyTo), threading (threadTag), and federated addressing (agent@system).",
+      {
+        to: z
+          .union([z.string(), z.array(z.string())])
+          .describe(
+            "Recipient agent ID(s). Use 'agent@system' for federated addressing."
+          ),
+        body: z
+          .string()
+          .optional()
+          .describe("Plain text message body (shorthand for content)"),
+        content: z
+          .object({ type: z.string() })
+          .passthrough()
+          .optional()
+          .describe("Structured message content"),
+        from: z
+          .string()
+          .optional()
+          .describe("Sender agent ID (defaults to caller)"),
+        threadTag: z
+          .string()
+          .optional()
+          .describe("Thread tag for grouping related messages"),
+        inReplyTo: z
+          .string()
+          .optional()
+          .describe("Message ID this is a reply to"),
+        importance: z
+          .enum(["low", "normal", "high", "urgent"])
+          .optional()
+          .describe("Message importance level"),
+        subject: z.string().optional().describe("Message subject"),
+      },
+      async ({ to, body, content, from, threadTag, inReplyTo, importance, subject }) => {
+        const payload = content ?? body ?? "";
+        const senderId = from ?? this.defaultAgentId;
+        const resp = await this.sendIpc({
+          action: "send",
+          from: senderId,
+          to,
+          payload,
+          threadTag,
+          inReplyTo,
+          importance,
+          subject,
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify(
+                resp.ok
+                  ? { ok: true, messageId: resp.messageId }
+                  : { ok: false, error: resp.error }
+              ),
+            },
+          ],
+        };
+      }
+    );
+
+    this.mcp.tool(
+      "check_inbox",
+      "Check inbox for messages addressed to an agent. Auto-registers the agent if not already registered.",
+      {
+        agentId: z.string().describe("Agent ID to check inbox for"),
+        unreadOnly: z
+          .boolean()
+          .optional()
+          .describe("Only return unread messages (default true)"),
+        limit: z
+          .number()
+          .optional()
+          .describe("Max messages to return"),
+      },
+      async ({ agentId, unreadOnly, limit }) => {
+        const resp = await this.sendIpc({
+          action: "check_inbox",
+          agentId,
+          unreadOnly: unreadOnly ?? true,
+          clear: true, // Mark as read after retrieval
+        });
+
+        if (!resp.ok) {
+          return {
+            content: [
+              { type: "text" as const, text: JSON.stringify({ ok: false, error: resp.error }) },
+            ],
+          };
+        }
+
+        let messages = resp.messages ?? [];
+        if (limit && messages.length > limit) {
+          messages = messages.slice(0, limit);
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                count: messages.length,
+                messages: messages.map((m) => ({
+                  id: m.id,
+                  from: m.sender_id,
+                  subject: m.subject,
+                  content: m.content,
+                  threadTag: m.thread_tag,
+                  importance: m.importance,
+                  createdAt: m.created_at,
+                  inReplyTo: m.in_reply_to,
+                })),
+              }),
+            },
+          ],
+        };
+      }
+    );
+
+    this.mcp.tool(
+      "read_thread",
+      "Read all messages in a thread (by thread_tag)",
+      {
+        threadTag: z.string().describe("Thread tag to read"),
+        scope: z
+          .string()
+          .optional()
+          .describe("Scope (defaults to 'default')"),
+      },
+      async ({ threadTag, scope }) => {
+        const resp = await this.sendIpc({
+          action: "read_thread",
+          threadTag,
+          scope: scope ?? this.defaultScope,
+        });
+
+        if (!resp.ok) {
+          return {
+            content: [
+              { type: "text" as const, text: JSON.stringify({ ok: false, error: resp.error }) },
+            ],
+          };
+        }
+
+        const messages = resp.messages ?? [];
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                threadTag,
+                count: messages.length,
+                messages: messages.map((m) => ({
+                  id: m.id,
+                  from: m.sender_id,
+                  content: m.content,
+                  createdAt: m.created_at,
+                  inReplyTo: m.in_reply_to,
+                })),
+              }),
+            },
+          ],
+        };
+      }
+    );
+
+    this.mcp.tool(
+      "list_agents",
+      "List agents registered in the inbox (local and optionally federated)",
+      {
+        scope: z.string().optional().describe("Filter by scope"),
+        includeFederated: z
+          .boolean()
+          .optional()
+          .describe("Include agents known from federation routing table"),
+      },
+      async ({ scope, includeFederated }) => {
+        const resp = await this.sendIpc({
+          action: "list_agents",
+          scope,
+          includeFederated,
+        });
+
+        if (!resp.ok) {
+          return {
+            content: [
+              { type: "text" as const, text: JSON.stringify({ ok: false, error: resp.error }) },
+            ],
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                count: resp.count ?? resp.agents?.length ?? 0,
+                agents: resp.agents ?? [],
+              }),
+            },
+          ],
+        };
+      }
+    );
+  }
+
+  async start(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.mcp.connect(transport);
+  }
+
+  /** Expose for testing */
+  get server(): McpServer {
+    return this.mcp;
+  }
+}

package/src/mesh/delivery-bridge.ts

@@ -0,0 +1,110 @@
+/**
+ * DeliveryHandler bridge: connects agentic-mesh's MapServer message routing
+ * to agent-inbox's storage layer.
+ *
+ * When MapServer's MessageRouter resolves a message to a local agent,
+ * it calls `deliverToAgent()`. This bridge translates the MAP Message
+ * into an agent-inbox Message and stores it, triggering the full inbox
+ * pipeline (traceability, push notifications, etc.).
+ *
+ * For `forwardToPeer()` and `routeToFederation()`, we delegate back to
+ * the previous (default) handler so MeshPeer's own transport handles it.
+ */
+
+import { EventEmitter } from "node:events";
+import type { Storage } from "../storage/interface.js";
+import { mapMessageToInbox } from "./type-mapper.js";
+import type { MapMessage } from "./type-mapper.js";
+
+// ---------------------------------------------------------------------------
+// DeliveryHandler interface (matches agentic-mesh v0.2.0)
+// ---------------------------------------------------------------------------
+
+/**
+ * Subset of agentic-mesh's DeliveryHandler interface.
+ * We define it here to avoid importing the full package at compile time.
+ */
+export interface MeshDeliveryHandler {
+  deliverToAgent(agentId: string, message: MapMessage): Promise<boolean>;
+  forwardToPeer(
+    peerId: string,
+    agentIds: string[],
+    message: MapMessage
+  ): Promise<boolean>;
+  routeToFederation?(
+    systemId: string,
+    agentIds: string[],
+    message: MapMessage
+  ): Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+// DeliveryBridge
+// ---------------------------------------------------------------------------
+
+export class DeliveryBridge implements MeshDeliveryHandler {
+  constructor(
+    private storage: Storage,
+    private events: EventEmitter,
+    private scope: string = "default",
+    private previousHandler?: MeshDeliveryHandler
+  ) {}
+
+  /**
+   * Called by MapServer's MessageRouter when a message is resolved
+   * to a local agent. Translates and stores in agent-inbox.
+   */
+  async deliverToAgent(agentId: string, message: MapMessage): Promise<boolean> {
+    try {
+      const inboxMsg = mapMessageToInbox(message, this.scope);
+
+      // Ensure the target agent is in the recipients list
+      const hasAgent = inboxMsg.recipients.some(
+        (r) => r.agent_id === agentId
+      );
+      if (!hasAgent) {
+        inboxMsg.recipients.push({
+          agent_id: agentId,
+          kind: "to",
+          delivered_at: new Date().toISOString(),
+        });
+      }
+
+      this.storage.putMessage(inboxMsg);
+      this.events.emit("message.created", inboxMsg);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Forward to a connected peer. Delegates to the previous handler
+   * (MeshPeer's default transport handles actual peer forwarding).
+   */
+  async forwardToPeer(
+    peerId: string,
+    agentIds: string[],
+    message: MapMessage
+  ): Promise<boolean> {
+    if (this.previousHandler) {
+      return this.previousHandler.forwardToPeer(peerId, agentIds, message);
+    }
+    return false;
+  }
+
+  /**
+   * Route to a federated system. Delegates to the previous handler
+   * (FederationGateway handles cross-mesh routing).
+   */
+  async routeToFederation(
+    systemId: string,
+    agentIds: string[],
+    message: MapMessage
+  ): Promise<boolean> {
+    if (this.previousHandler?.routeToFederation) {
+      return this.previousHandler.routeToFederation(systemId, agentIds, message);
+    }
+    return false;
+  }
+}

package/src/mesh/mesh-connector.ts

@@ -0,0 +1,41 @@
+import type { MapAgentConnectionClass, MapConnection } from "../map/map-client.js";
+import type { MeshContextLike } from "./mesh-transport.js";
+import { MeshTransport, DEFAULT_CHANNEL_NAME } from "./mesh-transport.js";
+
+/**
+ * Factory for creating MeshTransport connections to remote peers.
+ *
+ * Implements MapAgentConnectionClass so it can be injected into
+ * ConnectionManager alongside (or instead of) the MAP SDK class.
+ *
+ * Usage:
+ * ```ts
+ * const connector = new MeshConnector(mesh, "my-peer-id");
+ * const conn = await connector.connect("remote-peer-id");
+ * ```
+ */
+export class MeshConnector implements MapAgentConnectionClass {
+  constructor(
+    private mesh: MeshContextLike,
+    private localPeerId: string,
+    private channelName: string = DEFAULT_CHANNEL_NAME
+  ) {}
+
+  /**
+   * Create a MeshTransport connection to a remote peer.
+   *
+   * The `server` parameter is the remote peer ID (not a URL).
+   * The `opts` parameter is ignored — mesh peers don't need
+   * MAP handshake parameters.
+   */
+  async connect(server: string, _opts?: unknown): Promise<MapConnection> {
+    const transport = new MeshTransport(
+      this.mesh,
+      this.localPeerId,
+      server,
+      this.channelName
+    );
+    await transport.open();
+    return transport;
+  }
+}