agent-inbox 0.0.1 → 0.1.1

package/src/map/map-client.ts

@@ -0,0 +1,260 @@
+import { EventEmitter } from "node:events";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Storage } from "../storage/interface.js";
+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";
+
+/**
+ * Wrapper around @multi-agent-protocol/sdk for Agent Inbox's MAP connection.
+ *
+ * The MAP SDK is an optional peer dependency. This client gracefully degrades
+ * to a no-op when the SDK is not installed.
+ */
+export class MapClient {
+  private conn: MapConnection | null = null;
+  private agentConnectionClass: MapAgentConnectionClass | null = null;
+  private externalConn = false;
+
+  constructor(
+    private storage: Storage,
+    private router: MessageRouter,
+    private events: EventEmitter,
+    private inboxJsonlPath?: string
+  ) {}
+
+  async connect(config: NonNullable<InboxConfig["map"]>): Promise<boolean> {
+    if (!config.enabled || !config.server) return false;
+
+    let AgentConnection: MapAgentConnectionClass;
+    try {
+      // Dynamic import — optional peer dependency
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const sdk = await (Function('return import("@multi-agent-protocol/sdk")')() as Promise<{ AgentConnection: MapAgentConnectionClass }>);
+      AgentConnection = sdk.AgentConnection;
+      this.agentConnectionClass = AgentConnection;
+    } catch {
+      // MAP SDK not installed — standalone mode
+      return false;
+    }
+
+    try {
+      this.conn = await AgentConnection.connect(config.server, {
+        name: "agent-inbox",
+        role: "inbox",
+        scopes: [config.scope ?? "default"],
+        capabilities: { trajectory: { canReport: false } },
+        metadata: {
+          systemId: config.systemId ?? "agent-inbox",
+          type: "agent-inbox",
+        },
+        reconnection: {
+          enabled: true,
+          maxRetries: 5,
+          baseDelayMs: 1000,
+          maxDelayMs: 30000,
+        },
+      });
+
+      this.conn.onMessage((msg: IncomingMapMessage) => {
+        this.handleIncoming(msg);
+      });
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Use an externally-created MAP connection instead of creating one.
+   * The caller owns the connection lifecycle — disconnect() will detach
+   * but not close it. Incoming messages are still routed into storage.
+   */
+  useConnection(conn: MapConnection): void {
+    this.conn = conn;
+    this.externalConn = true;
+    conn.onMessage((msg: IncomingMapMessage) => {
+      this.handleIncoming(msg);
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.conn) {
+      if (!this.externalConn) {
+        await this.conn.disconnect();
+      }
+      this.conn = null;
+    }
+  }
+
+  async sendViaMap(
+    target: { agentId?: string; scope?: string },
+    payload: unknown
+  ): Promise<boolean> {
+    if (!this.conn) return false;
+    try {
+      await this.conn.send(target, payload);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  get connected(): boolean {
+    return this.conn !== null;
+  }
+
+  /**
+   * Get the underlying MAP connection, if connected.
+   * Returns the full AgentConnection instance from the SDK, exposing
+   * lifecycle methods (spawn, updateState, callExtension) beyond
+   * what Agent Inbox uses internally for messaging.
+   */
+  getConnection(): MapConnection | null {
+    return this.conn;
+  }
+
+  /**
+   * Get the system name from the MAP connection, if available.
+   * This is used for Tier 2 system ID resolution (MAP systemInfo).
+   */
+  getSystemName(): string | undefined {
+    if (!this.conn) return undefined;
+    return this.conn.systemName;
+  }
+
+  /**
+   * Get the AgentConnection class from the MAP SDK, if available.
+   * Used to inject the SDK into ConnectionManager for federation peer connections.
+   */
+  getAgentConnectionClass(): MapAgentConnectionClass | null {
+    return this.agentConnectionClass;
+  }
+
+  /**
+   * Startup replay: query MAP server for messages received while offline.
+   * Compares MAP server's message history against local storage and ingests
+   * any missing messages. Falls back to trusting local storage if the query fails.
+   */
+  async replayMissed(): Promise<number> {
+    if (!this.conn) return 0;
+
+    try {
+      // Query MAP server for recent messages via extension
+      const result = await this.conn.callExtension?.(
+        "mail/recent",
+        { limit: 200 }
+      ) as { messages?: unknown[] } | undefined;
+
+      if (!result || !Array.isArray(result.messages)) return 0;
+
+      let ingested = 0;
+      for (const msg of result.messages as IncomingMapMessage[]) {
+        // Check if we already have this message (by timestamp + sender dedup)
+        const existing = this.findExistingMessage(msg);
+        if (!existing) {
+          this.handleIncoming(msg);
+          ingested++;
+        }
+      }
+      return ingested;
+    } catch {
+      // MAP server doesn't support mail/recent or query failed
+      // Fall back to trusting local storage
+      return 0;
+    }
+  }
+
+  private findExistingMessage(msg: IncomingMapMessage): boolean {
+    // Simple dedup: check if a message with the same sender and timestamp exists
+    if (!msg.timestamp) return false;
+    const candidates = this.storage.searchMessages(msg.from);
+    return candidates.some(
+      (m) => m.sender_id === msg.from && m.created_at === msg.timestamp
+    );
+  }
+
+  private handleIncoming(msg: IncomingMapMessage): void {
+    const now = new Date().toISOString();
+    const content = normalizeContent(msg.payload);
+
+    // Store as a message
+    const message: Message = {
+      id: ulid(),
+      scope: "default",
+      sender_id: msg.from,
+      recipients: [] as Recipient[],
+      content,
+      importance: msg.meta?.priority === "high" ? "high" : "normal",
+      metadata: msg.meta ?? {},
+      created_at: msg.timestamp ?? now,
+    };
+
+    this.storage.putMessage(message);
+    this.events.emit("message.created", message);
+
+    // Append to inbox.jsonl if configured
+    if (this.inboxJsonlPath) {
+      this.appendToInboxJsonl(msg);
+    }
+  }
+
+  private appendToInboxJsonl(msg: IncomingMapMessage): void {
+    if (!this.inboxJsonlPath) return;
+    try {
+      const dir = path.dirname(this.inboxJsonlPath);
+      fs.mkdirSync(dir, { recursive: true });
+      const line = JSON.stringify({
+        from: msg.from,
+        timestamp: msg.timestamp ?? new Date().toISOString(),
+        payload: msg.payload,
+        meta: msg.meta,
+      });
+      fs.appendFileSync(this.inboxJsonlPath, line + "\n");
+    } catch {
+      // Best-effort write
+    }
+  }
+}
+
+// --- MAP SDK type stubs (for when the SDK isn't installed) ---
+
+export interface IncomingMapMessage {
+  from: string;
+  payload: unknown;
+  timestamp?: string;
+  meta?: { priority?: string; [key: string]: unknown };
+}
+
+export interface MapConnection {
+  send(
+    to: { agentId?: string; scope?: string },
+    payload: unknown,
+    meta?: Record<string, unknown>
+  ): Promise<void>;
+  onMessage(handler: (msg: IncomingMapMessage) => void): void;
+  disconnect(): Promise<void>;
+  // Agent lifecycle (available on full SDK AgentConnection)
+  spawn?(opts: {
+    agentId: string;
+    name?: string;
+    role?: string;
+    scopes?: string[];
+    metadata?: Record<string, unknown>;
+  }): Promise<unknown>;
+  updateState?(state: string): Promise<void>;
+  updateMetadata?(metadata: Record<string, unknown>): Promise<void>;
+  callExtension?(
+    name: string,
+    params: Record<string, unknown>
+  ): Promise<unknown>;
+  // System info (populated by some MAP servers)
+  systemName?: string;
+}
+
+export interface MapAgentConnectionClass {
+  connect(server: string, opts: unknown): Promise<MapConnection>;
+}

package/src/mcp/mcp-server.ts

@@ -0,0 +1,272 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import type { Storage } from "../storage/interface.js";
+import type { MessageRouter } from "../router/message-router.js";
+import type { Agent } from "../types.js";
+import type { WarmRegistry } from "../registry/warm-registry.js";
+
+export class InboxMcpServer {
+  private mcp: McpServer;
+  private registry: WarmRegistry | null = null;
+
+  constructor(
+    private router: MessageRouter,
+    private storage: Storage,
+    private defaultScope: string = "default"
+  ) {
+    this.mcp = new McpServer({
+      name: "agent-inbox",
+      version: "0.1.0",
+    });
+
+    this.registerTools();
+  }
+
+  /**
+   * Attach a warm registry for federation-aware agent registration.
+   */
+  setRegistry(registry: WarmRegistry): void {
+    this.registry = registry;
+  }
+
+  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 ?? "anonymous";
+        const message = await this.router.routeMessage({
+          from: senderId,
+          to,
+          payload,
+          threadTag,
+          inReplyTo,
+          importance,
+          subject,
+        });
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ ok: true, messageId: message.id }),
+            },
+          ],
+        };
+      }
+    );
+
+    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 }) => {
+        // Auto-register the agent if not already known
+        this.ensureAgent(agentId);
+
+        const messages = this.storage.getInbox(agentId, {
+          unreadOnly: unreadOnly ?? true,
+          limit,
+        });
+
+        // Auto-mark as read
+        for (const msg of messages) {
+          this.router.markRead(msg.id, agentId);
+        }
+
+        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 messages = this.storage.getThread({
+          threadTag,
+          scope: scope ?? this.defaultScope,
+        });
+        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 agents = this.storage.listAgents(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: Array<{
+          agentId: string;
+          peerId: string;
+          status: string;
+          location: "federated";
+        }> = [];
+        if (includeFederated && this.router.getFederation()) {
+          const federation = this.router.getFederation()!;
+          const routingTable = federation.routing.getTable();
+          federatedList = routingTable.map((entry) => ({
+            agentId: entry.agentId,
+            peerId: entry.peerId,
+            status: entry.status,
+            location: "federated" as const,
+          }));
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                count: localList.length + federatedList.length,
+                agents: [...localList, ...federatedList],
+              }),
+            },
+          ],
+        };
+      }
+    );
+  }
+
+  /** Auto-register an agent if not already known (lazy registration on first inbox check) */
+  private ensureAgent(agentId: string): void {
+    const existing = this.storage.listAgents().find(
+      (a) => a.agent_id === agentId
+    );
+    if (existing) return;
+
+    const now = new Date().toISOString();
+    const agent: Agent = {
+      agent_id: agentId,
+      scope: this.defaultScope,
+      status: "active",
+      metadata: {},
+      registered_at: now,
+      last_active_at: now,
+    };
+
+    if (this.registry) {
+      this.registry.register(agent);
+    } else {
+      this.storage.putAgent(agent);
+    }
+  }
+
+  async start(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.mcp.connect(transport);
+  }
+
+  /** Expose for testing — returns the underlying McpServer */
+  get server(): McpServer {
+    return this.mcp;
+  }
+}