agent-inbox 0.0.1 → 0.1.2

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

package/src/jsonrpc/mail-server.ts

@@ -0,0 +1,356 @@
+import * as net from "node:net";
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { EventEmitter } from "node:events";
+import type { Storage } from "../storage/interface.js";
+import type { MessageRouter } from "../router/message-router.js";
+import type { Conversation, Turn, Thread } from "../types.js";
+import { ulid } from "ulid";
+
+/**
+ * MAP mail/* JSON-RPC 2.0 endpoint.
+ * Serves over both UNIX socket (IPC inline) and HTTP (dashboard access).
+ */
+
+interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+type MethodHandler = (
+  params: Record<string, unknown>
+) => Promise<unknown> | unknown;
+
+export class MailJsonRpcServer {
+  private methods = new Map<string, MethodHandler>();
+  private httpServer: http.Server | null = null;
+  private subscribers = new Set<http.ServerResponse>();
+
+  constructor(
+    private storage: Storage,
+    private router: MessageRouter,
+    private events: EventEmitter
+  ) {
+    this.registerMethods();
+    this.setupEventForwarding();
+  }
+
+  private registerMethods(): void {
+    // mail/create — create a conversation
+    this.methods.set("mail/create", (params) => {
+      const now = new Date().toISOString();
+      const conv: Conversation = {
+        id: (params.id as string) ?? `conv-${ulid()}`,
+        scope: (params.scope as string) ?? "default",
+        subject: params.subject as string | undefined,
+        status: "active",
+        participants: [],
+        metadata: (params.metadata as Record<string, unknown>) ?? {},
+        created_at: now,
+        updated_at: now,
+      };
+      this.storage.putConversation(conv);
+      return conv;
+    });
+
+    // mail/get — get conversation details
+    this.methods.set("mail/get", (params) => {
+      const conv = this.storage.getConversation(params.id as string);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      const turns = this.storage.getTurns(conv.id);
+      const threads = this.storage.getThreadsByConversation(conv.id);
+      return { conversation: conv, turns, threads };
+    });
+
+    // mail/list — list conversations
+    this.methods.set("mail/list", (params) => {
+      const conversations = this.storage.listConversations(
+        params.scope as string | undefined
+      );
+      return { conversations };
+    });
+
+    // mail/close — close a conversation
+    this.methods.set("mail/close", (params) => {
+      const conv = this.storage.getConversation(params.id as string);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      conv.status = "completed";
+      conv.updated_at = new Date().toISOString();
+      this.storage.putConversation(conv);
+      return { ok: true };
+    });
+
+    // mail/join — add self as participant
+    this.methods.set("mail/join", (params) => {
+      const conv = this.storage.getConversation(
+        params.conversationId as string
+      );
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      const agentId = params.agentId as string;
+      if (!conv.participants.some((p) => p.agent_id === agentId)) {
+        conv.participants.push({
+          agent_id: agentId,
+          joined_at: new Date().toISOString(),
+        });
+        conv.updated_at = new Date().toISOString();
+        this.storage.putConversation(conv);
+      }
+      return { ok: true };
+    });
+
+    // mail/leave — remove self from conversation
+    this.methods.set("mail/leave", (params) => {
+      const conv = this.storage.getConversation(
+        params.conversationId as string
+      );
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      const agentId = params.agentId as string;
+      conv.participants = conv.participants.filter(
+        (p) => p.agent_id !== agentId
+      );
+      conv.updated_at = new Date().toISOString();
+      this.storage.putConversation(conv);
+      return { ok: true };
+    });
+
+    // mail/invite — add agent to conversation
+    this.methods.set("mail/invite", (params) => {
+      const conv = this.storage.getConversation(
+        params.conversationId as string
+      );
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      const agentId = params.agentId as string;
+      if (!conv.participants.some((p) => p.agent_id === agentId)) {
+        conv.participants.push({
+          agent_id: agentId,
+          role: params.role as string | undefined,
+          joined_at: new Date().toISOString(),
+        });
+        conv.updated_at = new Date().toISOString();
+        this.storage.putConversation(conv);
+      }
+      return { ok: true };
+    });
+
+    // mail/turn — add a turn to a conversation
+    this.methods.set("mail/turn", async (params) => {
+      const conv = this.storage.getConversation(
+        params.conversationId as string
+      );
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+
+      const turn: Turn = {
+        id: `turn-${ulid()}`,
+        conversation_id: conv.id,
+        participant_id: params.participantId as string,
+        source_message_id: params.sourceMessageId as string | undefined,
+        content_type: (params.contentType as string) ?? "text",
+        content: params.content as Turn["content"],
+        thread_id: params.threadId as string | undefined,
+        in_reply_to: params.inReplyTo as string | undefined,
+        created_at: new Date().toISOString(),
+      };
+
+      this.storage.addTurn(turn);
+      conv.updated_at = turn.created_at;
+      this.storage.putConversation(conv);
+      return turn;
+    });
+
+    // mail/turns/list — list turns in a conversation
+    this.methods.set("mail/turns/list", (params) => {
+      const turns = this.storage.getTurns(params.conversationId as string);
+      return { turns };
+    });
+
+    // mail/thread/create — create a thread
+    this.methods.set("mail/thread/create", (params) => {
+      const thread: Thread = {
+        id: `thread-${ulid()}`,
+        conversation_id: params.conversationId as string,
+        root_turn_id: params.rootTurnId as string,
+        parent_thread_id: params.parentThreadId as string | undefined,
+        subject: params.subject as string | undefined,
+        created_at: new Date().toISOString(),
+      };
+      this.storage.putThread(thread);
+      return thread;
+    });
+
+    // mail/thread/list — list threads in a conversation
+    this.methods.set("mail/thread/list", (params) => {
+      const threads = this.storage.getThreadsByConversation(
+        params.conversationId as string
+      );
+      return { threads };
+    });
+
+    // mail/replay — replay conversation history (all turns, ordered)
+    this.methods.set("mail/replay", (params) => {
+      const conv = this.storage.getConversation(params.id as string);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      const turns = this.storage.getTurns(conv.id);
+      return {
+        conversation: conv,
+        turns,
+        threads: this.storage.getThreadsByConversation(conv.id),
+      };
+    });
+  }
+
+  /** Process a JSON-RPC request (used by both IPC and HTTP transports) */
+  async handleRequest(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    if (request.jsonrpc !== "2.0") {
+      return {
+        jsonrpc: "2.0",
+        id: request.id ?? null,
+        error: { code: -32600, message: "Invalid JSON-RPC version" },
+      };
+    }
+
+    const handler = this.methods.get(request.method);
+    if (!handler) {
+      return {
+        jsonrpc: "2.0",
+        id: request.id ?? null,
+        error: { code: -32601, message: `Method not found: ${request.method}` },
+      };
+    }
+
+    try {
+      const result = await handler(request.params ?? {});
+      return { jsonrpc: "2.0", id: request.id ?? null, result };
+    } catch (err) {
+      if (isRpcError(err)) {
+        return {
+          jsonrpc: "2.0",
+          id: request.id ?? null,
+          error: { code: err.code, message: err.message },
+        };
+      }
+      return {
+        jsonrpc: "2.0",
+        id: request.id ?? null,
+        error: { code: -32603, message: String(err) },
+      };
+    }
+  }
+
+  /** Start HTTP server for dashboard/external access */
+  async startHttp(port: number): Promise<void> {
+    return new Promise((resolve) => {
+      this.httpServer = http.createServer((req, res) => {
+        // SSE endpoint for map/subscribe
+        if (req.url === "/subscribe" && req.method === "GET") {
+          this.handleSseSubscribe(res);
+          return;
+        }
+
+        // JSON-RPC endpoint
+        if (req.method !== "POST") {
+          res.writeHead(405, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              id: null,
+              error: { code: -32600, message: "Method not allowed" },
+            })
+          );
+          return;
+        }
+
+        let body = "";
+        req.on("data", (chunk) => {
+          body += chunk;
+        });
+        req.on("end", async () => {
+          try {
+            const request = JSON.parse(body) as JsonRpcRequest;
+            const response = await this.handleRequest(request);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(response));
+          } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({
+                jsonrpc: "2.0",
+                id: null,
+                error: { code: -32700, message: "Parse error" },
+              })
+            );
+          }
+        });
+      });
+
+      this.httpServer.listen(port, () => resolve());
+    });
+  }
+
+  async stopHttp(): Promise<void> {
+    // Close all SSE connections
+    for (const res of this.subscribers) {
+      res.end();
+    }
+    this.subscribers.clear();
+
+    return new Promise((resolve) => {
+      if (!this.httpServer) return resolve();
+      this.httpServer.close(() => resolve());
+    });
+  }
+
+  /** SSE endpoint: stream events to subscribers */
+  private handleSseSubscribe(res: http.ServerResponse): void {
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    });
+    res.write(":\n\n"); // SSE comment to establish connection
+
+    this.subscribers.add(res);
+    res.on("close", () => {
+      this.subscribers.delete(res);
+    });
+  }
+
+  /** Forward internal events to SSE subscribers */
+  private setupEventForwarding(): void {
+    this.events.on("message.created", (msg) => {
+      this.broadcast("message.created", msg);
+    });
+  }
+
+  private broadcast(eventType: string, data: unknown): void {
+    const payload = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const res of this.subscribers) {
+      res.write(payload);
+    }
+  }
+}
+
+// --- Error helpers ---
+
+interface RpcError extends Error {
+  code: number;
+}
+
+function rpcError(code: number, message: string): RpcError {
+  const err = new Error(message) as RpcError;
+  err.code = code;
+  return err;
+}
+
+function isRpcError(err: unknown): err is RpcError {
+  return err instanceof Error && typeof (err as RpcError).code === "number";
+}