claude-code-swarm 0.3.3 → 0.3.5

package/references/agent-inbox/src/index.ts

@@ -0,0 +1,390 @@
+import { EventEmitter } from "node:events";
+import * as path from "node:path";
+import * as os from "node:os";
+import { InMemoryStorage } from "./storage/memory.js";
+import { SqliteStorage } from "./storage/sqlite.js";
+import { MessageRouter } from "./router/message-router.js";
+import { TraceabilityLayer } from "./traceability/traceability.js";
+import { IpcServer } from "./ipc/ipc-server.js";
+import { MapClient } from "./map/map-client.js";
+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";
+
+export { InMemoryStorage } from "./storage/memory.js";
+export { SqliteStorage } from "./storage/sqlite.js";
+export { MessageRouter, normalizeContent } from "./router/message-router.js";
+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 { MailJsonRpcServer } from "./jsonrpc/mail-server.js";
+export { PushNotifier, formatInboxMarkdown, parseCommand } from "./push/notifier.js";
+export type { InboxMessageEvent, NotifierConfig, InboxFileEntry } from "./push/notifier.js";
+export { ConnectionManager } from "./federation/connection-manager.js";
+export type { DeliveryResult, IncomingMessageHandler } from "./federation/connection-manager.js";
+export type { MapConnection, MapAgentConnectionClass, IncomingMapMessage } from "./map/map-client.js";
+export { WarmRegistry } from "./registry/warm-registry.js";
+export { RoutingEngine } from "./federation/routing-engine.js";
+export { DeliveryQueue } from "./federation/delivery-queue.js";
+export { TrustManager } from "./federation/trust.js";
+export {
+  parseAddress,
+  formatAddress,
+  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";
+
+function defaultSocketPath(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inbox.sock");
+}
+
+function defaultInboxDir(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inboxes");
+}
+
+function defaultSqlitePath(): string {
+  const home = os.homedir();
+  return path.join(home, ".claude", "agent-inbox", "inbox.db");
+}
+
+function loadConfig(): InboxConfig {
+  return {
+    socketPath: process.env.INBOX_SOCKET_PATH ?? defaultSocketPath(),
+    scope: process.env.INBOX_SCOPE ?? "default",
+    map: {
+      enabled: process.env.INBOX_MAP_ENABLED === "true",
+      server: process.env.INBOX_MAP_SERVER,
+      scope: process.env.INBOX_MAP_SCOPE ?? process.env.INBOX_SCOPE ?? "default",
+      systemId: process.env.INBOX_MAP_SYSTEM_ID ?? "agent-inbox",
+    },
+  };
+}
+
+export interface AgentInbox {
+  storage: Storage;
+  router: MessageRouter;
+  traceability: TraceabilityLayer;
+  ipcServer: IpcServer;
+  mapClient: MapClient;
+  jsonRpc: MailJsonRpcServer;
+  notifier: PushNotifier;
+  federation: ConnectionManager | null;
+  registry: WarmRegistry | null;
+  events: EventEmitter;
+  stop(): Promise<void>;
+}
+
+export interface CreateOptions {
+  config?: Partial<InboxConfig>;
+  /** Use SQLite storage at this path (":memory:" for in-memory SQLite) */
+  sqlitePath?: string;
+  /** Use an external better-sqlite3 Database handle (co-locate tables in another DB) */
+  sqliteDb?: import("better-sqlite3").Database;
+  /** Table name prefix when co-locating in an external DB (e.g. "inbox_") */
+  sqlitePrefix?: string;
+  /** HTTP port for JSON-RPC endpoint (0 = disabled) */
+  httpPort?: number;
+  /** Webhook URLs for push notifications */
+  webhooks?: string[];
+  /** Enable federation with peer systems */
+  enableFederation?: boolean;
+  /** Use an externally-managed MAP connection instead of creating one.
+   *  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(
+  opts: CreateOptions = {}
+): Promise<AgentInbox> {
+  const config = { ...loadConfig(), ...opts.config };
+
+  // 1. Storage — SQLite (own file, external DB, or in-memory fallback)
+  let storage: Storage;
+  if (opts.sqliteDb) {
+    storage = new SqliteStorage({
+      db: opts.sqliteDb,
+      prefix: opts.sqlitePrefix,
+    });
+  } else if (opts.sqlitePath) {
+    storage = new SqliteStorage({
+      path: opts.sqlitePath,
+      prefix: opts.sqlitePrefix,
+    });
+  } else {
+    storage = new InMemoryStorage();
+  }
+
+  // 2. Event bus (internal)
+  const events = new EventEmitter();
+
+  // 3. Message router
+  const router = new MessageRouter(storage, events, config.scope);
+
+  // 4. Traceability layer (subscribes to message.created events)
+  const traceability = new TraceabilityLayer(storage, events);
+
+  // 5. Push notifier (per-agent inbox files + webhooks + event emission)
+  const notifier = new PushNotifier(
+    { inboxDir: defaultInboxDir(), webhooks: opts.webhooks },
+    storage,
+    events
+  );
+
+  // 6. MAP client (connects first to obtain SDK class for federation)
+  const mapClient = new MapClient(
+    storage,
+    router,
+    events,
+  );
+
+  // 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) {
+    const connected = await mapClient.connect(config.map);
+    if (connected) {
+      // Replay missed messages from MAP server
+      const replayed = await mapClient.replayMissed();
+      if (replayed > 0) {
+        console.error(`Replayed ${replayed} missed messages from MAP server`);
+      }
+    }
+  }
+
+  // 7. Registry + Federation (optional)
+  let federation: ConnectionManager | null = null;
+  let registry: WarmRegistry | null = null;
+
+  const needsRegistry = opts.enableFederation || config.federation?.peers?.length;
+
+  if (needsRegistry) {
+    registry = new WarmRegistry(storage, events, config.federation?.registry);
+  }
+
+  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.
+        const targetAgent = (meta?.targetAgent as string) ?? from;
+        router.routeMessage({
+          from: `${from}@${peerId}`,
+          to: targetAgent,
+          payload,
+          scope: meta?.scope as string | undefined,
+          subject: meta?.subject as string | undefined,
+          importance: meta?.importance as "high" | "normal" | undefined,
+          threadTag: meta?.threadTag as string | undefined,
+          inReplyTo: meta?.inReplyTo as string | undefined,
+          metadata: meta,
+        }).catch((err) => {
+          console.error(
+            `Failed to route incoming federation message from ${from}@${peerId}: ${err instanceof Error ? err.message : err}`
+          );
+        });
+      },
+    });
+    router.setFederation(federation);
+
+    // 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
+    if (config.federation?.peers) {
+      for (const peer of config.federation.peers) {
+        try {
+          await federation.federate(peer);
+          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}`
+          );
+        }
+      }
+    }
+
+    // Start delivery queue tick timer
+    federation.queue.startTicking();
+  }
+
+  // 8. JSON-RPC server (mail/* methods)
+  const jsonRpc = new MailJsonRpcServer(storage, router, events);
+  if (opts.httpPort && opts.httpPort > 0) {
+    await jsonRpc.startHttp(opts.httpPort);
+    console.error(`JSON-RPC HTTP server listening on port ${opts.httpPort}`);
+  }
+
+  // 9. IPC server (UNIX socket — handles both NDJSON commands and JSON-RPC inline)
+  const socketPath = config.socketPath ?? defaultSocketPath();
+  const ipcServer = new IpcServer(socketPath, router, storage, jsonRpc);
+  await ipcServer.start();
+
+  const stop = async () => {
+    await ipcServer.stop();
+    await jsonRpc.stopHttp();
+    await mapClient.disconnect();
+    if (federation) await federation.destroy();
+    if (registry) registry.destroy();
+    if ("close" in storage && typeof storage.close === "function") {
+      (storage as SqliteStorage).close();
+    }
+  };
+
+  return {
+    storage,
+    router,
+    traceability,
+    ipcServer,
+    mapClient,
+    jsonRpc,
+    notifier,
+    federation,
+    registry,
+    events,
+    stop,
+  };
+}
+
+// CLI entry point
+const isMainModule =
+  process.argv[1] &&
+  (process.argv[1].endsWith("/index.js") ||
+    process.argv[1].endsWith("/index.ts"));
+
+if (isMainModule) {
+  const mode = process.argv[2] ?? "ipc";
+
+  if (mode === "mcp") {
+    // MCP-only mode (stdio transport for Claude Code integration)
+    const config = loadConfig();
+    const sqlitePath = process.env.INBOX_SQLITE_PATH;
+    const storage: Storage = sqlitePath
+      ? new SqliteStorage({ path: sqlitePath })
+      : new InMemoryStorage();
+    const events = new EventEmitter();
+    const router = new MessageRouter(storage, events, config.scope);
+    const _traceability = new TraceabilityLayer(storage, events);
+    const mcpServer = new InboxMcpServer(router, storage, config.scope);
+    mcpServer.start().catch((err) => {
+      console.error("MCP server failed:", err);
+      process.exit(1);
+    });
+  } else {
+    // IPC server mode (default)
+    const httpPort = process.env.INBOX_HTTP_PORT
+      ? parseInt(process.env.INBOX_HTTP_PORT, 10)
+      : 0;
+    const sqlitePath = process.env.INBOX_SQLITE_PATH;
+
+    createAgentInbox({ httpPort, sqlitePath })
+      .then((inbox) => {
+        console.error(
+          `Agent Inbox IPC server listening on ${process.env.INBOX_SOCKET_PATH ?? defaultSocketPath()}`
+        );
+        process.on("SIGINT", async () => {
+          await inbox.stop();
+          process.exit(0);
+        });
+        process.on("SIGTERM", async () => {
+          await inbox.stop();
+          process.exit(0);
+        });
+      })
+      .catch((err) => {
+        console.error("Failed to start Agent Inbox:", err);
+        process.exit(1);
+      });
+  }
+}

package/references/agent-inbox/src/ipc/ipc-server.ts

@@ -0,0 +1,207 @@
+import * as net from "node:net";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type {
+  IpcCommand,
+  IpcResponse,
+  Agent,
+} from "../types.js";
+import type { Storage } from "../storage/interface.js";
+import type { MessageRouter } from "../router/message-router.js";
+import type { MailJsonRpcServer } from "../jsonrpc/mail-server.js";
+
+export class IpcServer {
+  private server: net.Server | null = null;
+
+  constructor(
+    private socketPath: string,
+    private router: MessageRouter,
+    private storage: Storage,
+    private jsonRpc?: MailJsonRpcServer
+  ) {}
+
+  async start(): Promise<void> {
+    // Clean up stale socket file
+    try {
+      fs.unlinkSync(this.socketPath);
+    } catch {
+      // Doesn't exist, fine
+    }
+
+    // Ensure directory exists
+    const dir = path.dirname(this.socketPath);
+    fs.mkdirSync(dir, { recursive: true });
+
+    return new Promise((resolve, reject) => {
+      this.server = net.createServer((conn) => this.handleConnection(conn));
+      this.server.on("error", reject);
+      this.server.listen(this.socketPath, () => resolve());
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (!this.server) return resolve();
+      this.server.close(() => {
+        try {
+          fs.unlinkSync(this.socketPath);
+        } catch {
+          // Already gone
+        }
+        resolve();
+      });
+    });
+  }
+
+  private handleConnection(conn: net.Socket): void {
+    let buffer = "";
+
+    conn.on("data", (data) => {
+      buffer += data.toString();
+      // Process complete lines (NDJSON)
+      let newlineIdx: number;
+      while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newlineIdx).trim();
+        buffer = buffer.slice(newlineIdx + 1);
+        if (!line) continue;
+
+        this.processLine(line)
+          .then((response) => {
+            conn.write(JSON.stringify(response) + "\n");
+          })
+          .catch((err) => {
+            conn.write(
+              JSON.stringify({ ok: false, error: String(err) }) + "\n"
+            );
+          });
+      }
+    });
+
+    conn.on("error", () => {
+      // Client disconnected, ignore
+    });
+  }
+
+  private async processLine(line: string): Promise<IpcResponse | object> {
+    let parsed: Record<string, unknown>;
+    try {
+      parsed = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return { ok: false, error: "Invalid JSON" };
+    }
+
+    // Detect JSON-RPC requests (have "jsonrpc" field) vs IPC commands (have "action" field)
+    if (parsed.jsonrpc === "2.0" && typeof parsed.method === "string") {
+      if (this.jsonRpc) {
+        return this.jsonRpc.handleRequest(
+          parsed as { jsonrpc: "2.0"; id?: string | number | null; method: string; params?: Record<string, unknown> }
+        );
+      }
+      return { jsonrpc: "2.0", id: parsed.id ?? null, error: { code: -32603, message: "JSON-RPC not configured" } };
+    }
+
+    return this.handleCommand(parsed as unknown as IpcCommand);
+  }
+
+  async handleCommand(command: IpcCommand): Promise<IpcResponse> {
+    switch (command.action) {
+      case "ping":
+        return { ok: true, pid: process.pid };
+
+      case "send":
+        return this.handleSend(command);
+
+      case "notify":
+        return this.handleNotify(command);
+
+      case "check_inbox":
+        return this.handleCheckInbox(command);
+
+      case "emit":
+        // For Phase 1, emit is acknowledged but not forwarded to MAP
+        return { ok: true };
+
+      default:
+        return { ok: false, error: `Unknown action: ${(command as { action: string }).action}` };
+    }
+  }
+
+  private async handleSend(
+    command: Extract<IpcCommand, { action: "send" }>
+  ): Promise<IpcResponse> {
+    try {
+      const message = await this.router.routeMessage({
+        from: command.from,
+        to: command.to,
+        payload: command.payload,
+        scope: command.scope,
+        threadTag: command.threadTag,
+        inReplyTo: command.inReplyTo,
+        importance: command.importance,
+        metadata: command.meta,
+      });
+      return { ok: true, messageId: message.id };
+    } catch (err) {
+      return { ok: false, error: String(err) };
+    }
+  }
+
+  private handleCheckInbox(
+    command: Extract<IpcCommand, { action: "check_inbox" }>
+  ): IpcResponse {
+    const agentId = command.agentId ?? command.scope ?? "default";
+    const messages = this.storage.getInbox(agentId, {
+      unreadOnly: command.unreadOnly,
+    });
+
+    // Mark messages as read
+    if (command.clear) {
+      const now = new Date().toISOString();
+      for (const msg of messages) {
+        for (const r of msg.recipients) {
+          if (r.agent_id === agentId && !r.read_at) {
+            r.read_at = now;
+          }
+        }
+        this.storage.putMessage(msg);
+      }
+    }
+
+    return { ok: true, messages };
+  }
+
+  private handleNotify(
+    command: Extract<IpcCommand, { action: "notify" }>
+  ): IpcResponse {
+    const event = command.event;
+
+    if (event.type === "agent.spawn" && event.agent) {
+      const now = new Date().toISOString();
+      const agent: Agent = {
+        agent_id: event.agent.agentId,
+        display_name: event.agent.name,
+        scope: event.agent.scopes?.[0] ?? "default",
+        status: "active",
+        metadata: event.agent.metadata ?? {},
+        registered_at: now,
+        last_active_at: now,
+      };
+      this.storage.putAgent(agent);
+      return { ok: true };
+    }
+
+    if (event.type === "agent.done") {
+      const agentId = event.agentId ?? event.agent?.agentId;
+      if (agentId) {
+        const agent = this.storage.getAgent(agentId);
+        if (agent) {
+          agent.status = "offline";
+          this.storage.putAgent(agent);
+        }
+      }
+      return { ok: true };
+    }
+
+    return { ok: true };
+  }
+}