claude-code-swarm 0.3.5 → 0.3.7

package/references/agent-inbox/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/references/agent-inbox/src/types.ts

@@ -140,6 +140,18 @@ export interface IpcCheckInboxCommand {
   clear?: boolean;
 }
 
+export interface IpcReadThreadCommand {
+  action: "read_thread";
+  threadTag: string;
+  scope?: string;
+}
+
+export interface IpcListAgentsCommand {
+  action: "list_agents";
+  scope?: string;
+  includeFederated?: boolean;
+}
+
 export interface IpcPingCommand {
   action: "ping";
 }
@@ -149,12 +161,26 @@ export type IpcCommand =
   | IpcEmitCommand
   | IpcNotifyCommand
   | IpcCheckInboxCommand
+  | IpcReadThreadCommand
+  | IpcListAgentsCommand
   | IpcPingCommand;
 
 export interface IpcResponse {
   ok: boolean;
   messageId?: string;
   messages?: Message[];
+  agents?: Array<{
+    agentId: string;
+    name?: string;
+    scope: string;
+    status: string;
+    program?: string;
+    lastActive?: string;
+    location: "local" | "federated";
+    peerId?: string;
+  }>;
+  count?: number;
+  threadTag?: string;
   error?: string;
   pid?: number;
 }

package/references/agent-inbox/test/ipc-new-commands.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+import { EventEmitter } from "node:events";
+import { InMemoryStorage } from "../src/storage/memory.js";
+import { MessageRouter } from "../src/router/message-router.js";
+import { IpcServer } from "../src/ipc/ipc-server.js";
+
+function tmpSocketPath(): string {
+  return path.join(os.tmpdir(), `inbox-test-${Date.now()}-${Math.random().toString(36).slice(2)}.sock`);
+}
+
+function sendCommand(socketPath: string, command: object): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socketPath, () => {
+      client.write(JSON.stringify(command) + "\n");
+    });
+    let buffer = "";
+    client.on("data", (data) => {
+      buffer += data.toString();
+      const idx = buffer.indexOf("\n");
+      if (idx !== -1) {
+        const line = buffer.slice(0, idx);
+        client.end();
+        resolve(JSON.parse(line));
+      }
+    });
+    client.on("error", reject);
+  });
+}
+
+describe("IPC read_thread command", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let server: IpcServer;
+  let socketPath: string;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+    socketPath = tmpSocketPath();
+    server = new IpcServer(socketPath, router, storage);
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it("should return empty thread for unknown tag", async () => {
+    const resp = await sendCommand(socketPath, {
+      action: "read_thread",
+      threadTag: "nonexistent",
+    });
+    expect(resp.ok).toBe(true);
+    expect(resp.threadTag).toBe("nonexistent");
+    expect(resp.count).toBe(0);
+    expect(resp.messages).toEqual([]);
+  });
+
+  it("should return messages in a thread", async () => {
+    // Send messages with same threadTag
+    await sendCommand(socketPath, {
+      action: "send",
+      from: "alice",
+      to: "bob",
+      payload: "first message",
+      threadTag: "task-42",
+    });
+    await sendCommand(socketPath, {
+      action: "send",
+      from: "bob",
+      to: "alice",
+      payload: "reply to first",
+      threadTag: "task-42",
+    });
+    // Different thread
+    await sendCommand(socketPath, {
+      action: "send",
+      from: "alice",
+      to: "charlie",
+      payload: "unrelated",
+      threadTag: "task-99",
+    });
+
+    const resp = await sendCommand(socketPath, {
+      action: "read_thread",
+      threadTag: "task-42",
+      scope: "default",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(2);
+    const messages = resp.messages as Array<{ sender_id: string }>;
+    expect(messages).toHaveLength(2);
+    const senders = messages.map((m) => m.sender_id);
+    expect(senders).toContain("alice");
+    expect(senders).toContain("bob");
+  });
+});
+
+describe("IPC list_agents command", () => {
+  let storage: InMemoryStorage;
+  let events: EventEmitter;
+  let router: MessageRouter;
+  let server: IpcServer;
+  let socketPath: string;
+
+  beforeEach(async () => {
+    storage = new InMemoryStorage();
+    events = new EventEmitter();
+    router = new MessageRouter(storage, events, "default");
+    socketPath = tmpSocketPath();
+    server = new IpcServer(socketPath, router, storage);
+    await server.start();
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it("should return empty list with no agents", async () => {
+    const resp = await sendCommand(socketPath, {
+      action: "list_agents",
+    });
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(0);
+    expect(resp.agents).toEqual([]);
+  });
+
+  it("should list registered agents", async () => {
+    // Register agents via notify
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: {
+          agentId: "gsd-executor",
+          name: "executor",
+          scopes: ["swarm:gsd"],
+          metadata: { role: "executor" },
+        },
+      },
+    });
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: {
+          agentId: "gsd-verifier",
+          name: "verifier",
+          scopes: ["swarm:gsd"],
+        },
+      },
+    });
+
+    const resp = await sendCommand(socketPath, {
+      action: "list_agents",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(2);
+    const agents = resp.agents as Array<{ agentId: string; location: string }>;
+    expect(agents).toHaveLength(2);
+    const ids = agents.map((a) => a.agentId);
+    expect(ids).toContain("gsd-executor");
+    expect(ids).toContain("gsd-verifier");
+    expect(agents[0].location).toBe("local");
+  });
+
+  it("should filter agents by scope", async () => {
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: { agentId: "team1-a", name: "a", scopes: ["team1"] },
+      },
+    });
+    await sendCommand(socketPath, {
+      action: "notify",
+      event: {
+        type: "agent.spawn",
+        agent: { agentId: "team2-b", name: "b", scopes: ["team2"] },
+      },
+    });
+
+    const resp = await sendCommand(socketPath, {
+      action: "list_agents",
+      scope: "team1",
+    });
+
+    expect(resp.ok).toBe(true);
+    expect(resp.count).toBe(1);
+    const agents = resp.agents as Array<{ agentId: string }>;
+    expect(agents[0].agentId).toBe("team1-a");
+  });
+});