agent-inbox 0.1.7 → 0.1.9

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;
+  }
+}

package/src/mesh/mesh-transport.ts

@@ -0,0 +1,157 @@
+import type {
+  MapConnection,
+  IncomingMapMessage,
+} from "../map/map-client.js";
+
+// ---------------------------------------------------------------------------
+// Minimal type stubs for agentic-mesh.
+// We only reference the subset of MeshContext / IMessageChannel that
+// MeshTransport actually uses, so agent-inbox compiles without importing
+// the full agentic-mesh package (it's an optional peer dep).
+// ---------------------------------------------------------------------------
+
+/** Subset of agentic-mesh PeerInfo used by MeshTransport. */
+export interface MeshPeerInfo {
+  id: string;
+  name?: string;
+  groups: string[];
+}
+
+/** Subset of agentic-mesh IMessageChannel<T>. */
+export interface MeshChannel<T> {
+  readonly name: string;
+  readonly isOpen: boolean;
+  open(): Promise<void>;
+  close(): Promise<void>;
+  send(peerId: string, message: T): boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  off(event: string | symbol, listener: (...args: any[]) => void): this;
+}
+
+/** Subset of agentic-mesh MeshContext used by MeshTransport. */
+export interface MeshContextLike {
+  createChannel<T>(name: string): MeshChannel<T>;
+  _getPeerId(): string;
+}
+
+// ---------------------------------------------------------------------------
+// Wire format
+// ---------------------------------------------------------------------------
+
+/**
+ * Payload exchanged over the mesh channel between agent-inbox instances.
+ * Flat structure that maps 1-to-1 with IncomingMapMessage.
+ */
+export interface InboxWireMessage {
+  to?: { agentId?: string; scope?: string };
+  payload: unknown;
+  from: string;
+  timestamp?: string;
+  meta?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// MeshTransport
+// ---------------------------------------------------------------------------
+
+/** Default channel name used for agent-inbox federation traffic.
+ *  Uses the "proto:" prefix to distinguish protocol channels from
+ *  application channels on the same mesh. */
+export const DEFAULT_CHANNEL_NAME = "proto:agent-inbox";
+
+/**
+ * Implements the MapConnection interface over an agentic-mesh MessageChannel.
+ *
+ * Each instance represents a connection to a single remote peer. Multiple
+ * MeshTransport instances share the same underlying channel (one channel
+ * per mesh, not per peer) and filter incoming messages by remotePeerId.
+ */
+export class MeshTransport implements MapConnection {
+  private channel: MeshChannel<InboxWireMessage>;
+  private handlers: ((msg: IncomingMapMessage) => void)[] = [];
+  private messageListener: ((message: InboxWireMessage, from: MeshPeerInfo) => void) | null = null;
+  private closed = false;
+  readonly systemName: string;
+
+  constructor(
+    private mesh: MeshContextLike,
+    private localPeerId: string,
+    private remotePeerId: string,
+    channelName: string = DEFAULT_CHANNEL_NAME
+  ) {
+    this.systemName = remotePeerId;
+    this.channel = mesh.createChannel<InboxWireMessage>(channelName);
+  }
+
+  /**
+   * Open the underlying channel and start listening for messages.
+   * Must be called before send() or onMessage().
+   */
+  async open(): Promise<void> {
+    if (!this.channel.isOpen) {
+      await this.channel.open();
+    }
+    this.messageListener = (message: InboxWireMessage, from: MeshPeerInfo) => {
+      if (this.closed) return;
+      // Only process messages from our remote peer
+      if (from.id !== this.remotePeerId) return;
+      const incoming = wireToIncoming(message);
+      for (const handler of this.handlers) {
+        handler(incoming);
+      }
+    };
+    this.channel.on("message", this.messageListener);
+  }
+
+  async send(
+    to: { agentId?: string; scope?: string },
+    payload: unknown,
+    meta?: Record<string, unknown>
+  ): Promise<void> {
+    if (this.closed) {
+      throw new Error("MeshTransport is closed");
+    }
+    const wire: InboxWireMessage = {
+      to,
+      payload,
+      from: this.localPeerId,
+      timestamp: new Date().toISOString(),
+      meta,
+    };
+    const sent = this.channel.send(this.remotePeerId, wire);
+    if (!sent) {
+      throw new Error(
+        `Failed to send to peer "${this.remotePeerId}" — peer may be offline`
+      );
+    }
+  }
+
+  onMessage(handler: (msg: IncomingMapMessage) => void): void {
+    this.handlers.push(handler);
+  }
+
+  async disconnect(): Promise<void> {
+    this.closed = true;
+    if (this.messageListener) {
+      this.channel.off("message", this.messageListener);
+      this.messageListener = null;
+    }
+    this.handlers = [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function wireToIncoming(wire: InboxWireMessage): IncomingMapMessage {
+  return {
+    from: wire.from,
+    to: wire.to,
+    payload: wire.payload,
+    timestamp: wire.timestamp,
+    meta: wire.meta,
+  };
+}