@vellumai/assistant 0.6.5 → 0.7.0

package/src/ipc/__tests__/watcher-ipc.test.ts

@@ -1,19 +1,19 @@
 /**
  * Integration tests for the watcher IPC routes.
  *
- * Exercises the full IPC round-trip: CliIpcServer + cliIpcCall over
+ * Exercises the full IPC round-trip: AssistantIpcServer + cliIpcCall over
  * the Unix domain socket, with the real SQLite watcher store backing
  * the route handlers.
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
-import { initializeDb } from "../../memory/db.js";
+import { initializeDb } from "../../memory/db-init.js";
 import { registerWatcherProvider } from "../../watcher/provider-registry.js";
 import type { WatcherProvider } from "../../watcher/provider-types.js";
 import type { Watcher, WatcherEvent } from "../../watcher/watcher-store.js";
+import { AssistantIpcServer } from "../assistant-server.js";
 import { cliIpcCall } from "../cli-client.js";
-import { CliIpcServer } from "../cli-server.js";
 
 // ---------------------------------------------------------------------------
 // DB + provider setup
@@ -40,14 +40,14 @@ registerWatcherProvider(mockProvider);
 // Helpers
 // ---------------------------------------------------------------------------
 
-let server: CliIpcServer | null = null;
+let server: AssistantIpcServer | null = null;
 
 /** IDs of watchers created during a test, cleaned up in afterEach. */
 const createdWatcherIds: string[] = [];
 
 beforeEach(async () => {
-  server = new CliIpcServer();
-  server.start();
+  server = new AssistantIpcServer();
+  await server.start();
   // Allow the server socket to bind.
   await new Promise((resolve) => setTimeout(resolve, 50));
 });
@@ -55,7 +55,7 @@ beforeEach(async () => {
 afterEach(async () => {
   // Clean up watchers created during the test.
   for (const id of createdWatcherIds) {
-    await cliIpcCall("watcher/delete", { watcher_id: id });
+    await cliIpcCall("watcher_delete", { body: { watcher_id: id } });
   }
   createdWatcherIds.length = 0;
 
@@ -67,12 +67,12 @@ afterEach(async () => {
 async function createTestWatcher(
   overrides?: Record<string, unknown>,
 ): Promise<Watcher> {
-  const result = await cliIpcCall<Watcher>("watcher/create", {
+  const result = await cliIpcCall<Watcher>("watcher_create", { body: {
     name: "Test Watcher",
     provider: "test-provider",
     action_prompt: "Handle events",
     ...overrides,
-  });
+  } });
   expect(result.ok).toBe(true);
   expect(result.result).toBeDefined();
   createdWatcherIds.push(result.result!.id);
@@ -96,7 +96,7 @@ describe("watcher IPC routes", () => {
     expect(watcher.status).toBe("idle");
 
     // List all
-    const listResult = await cliIpcCall<Watcher[]>("watcher/list", {});
+    const listResult = await cliIpcCall<Watcher[]>("watcher_list", { body: {} });
     expect(listResult.ok).toBe(true);
     expect(Array.isArray(listResult.result)).toBe(true);
     const found = listResult.result!.find((w) => w.id === watcher.id);
@@ -106,23 +106,23 @@ describe("watcher IPC routes", () => {
     const detailResult = await cliIpcCall<{
       watcher: Watcher;
       events: WatcherEvent[];
-    }>("watcher/list", { watcher_id: watcher.id });
+    }>("watcher_list", { body: { watcher_id: watcher.id } });
     expect(detailResult.ok).toBe(true);
     expect(detailResult.result!.watcher.id).toBe(watcher.id);
     expect(Array.isArray(detailResult.result!.events)).toBe(true);
 
     // Update
-    const updateResult = await cliIpcCall<Watcher>("watcher/update", {
+    const updateResult = await cliIpcCall<Watcher>("watcher_update", { body: {
       watcher_id: watcher.id,
       name: "Updated Watcher",
-    });
+    } });
     expect(updateResult.ok).toBe(true);
     expect(updateResult.result!.name).toBe("Updated Watcher");
 
     // Delete
     const deleteResult = await cliIpcCall<{ deleted: boolean; name: string }>(
-      "watcher/delete",
-      { watcher_id: watcher.id },
+      "watcher_delete",
+      { body: { watcher_id: watcher.id } },
     );
     expect(deleteResult.ok).toBe(true);
     expect(deleteResult.result!.deleted).toBe(true);
@@ -133,7 +133,7 @@ describe("watcher IPC routes", () => {
     if (idx >= 0) createdWatcherIds.splice(idx, 1);
 
     // Confirm gone
-    const afterDelete = await cliIpcCall<Watcher[]>("watcher/list", {});
+    const afterDelete = await cliIpcCall<Watcher[]>("watcher_list", { body: {} });
     expect(afterDelete.ok).toBe(true);
     const gone = afterDelete.result!.find((w) => w.id === watcher.id);
     expect(gone).toBeUndefined();
@@ -142,11 +142,11 @@ describe("watcher IPC routes", () => {
   // -- Create: unknown provider -----------------------------------------------
 
   test("watcher/create rejects unknown provider", async () => {
-    const result = await cliIpcCall("watcher/create", {
+    const result = await cliIpcCall("watcher_create", { body: {
       name: "Bad Watcher",
       provider: "nonexistent",
       action_prompt: "Do stuff",
-    });
+    } });
     expect(result.ok).toBe(false);
     expect(result.error).toContain('Unknown provider "nonexistent"');
     expect(result.error).toContain("test-provider");
@@ -155,12 +155,12 @@ describe("watcher IPC routes", () => {
   // -- Create: poll interval too low ------------------------------------------
 
   test("watcher/create rejects poll_interval_ms < 15000", async () => {
-    const result = await cliIpcCall("watcher/create", {
+    const result = await cliIpcCall("watcher_create", { body: {
       name: "Fast Watcher",
       provider: "test-provider",
       action_prompt: "Handle events",
       poll_interval_ms: 5000,
-    });
+    } });
     expect(result.ok).toBe(false);
     expect(result.error).toBeDefined();
   });
@@ -168,7 +168,7 @@ describe("watcher IPC routes", () => {
   // -- List: empty state ------------------------------------------------------
 
   test("watcher/list returns empty array when no watchers exist", async () => {
-    const result = await cliIpcCall<Watcher[]>("watcher/list", {});
+    const result = await cliIpcCall<Watcher[]>("watcher_list", { body: {} });
     expect(result.ok).toBe(true);
     expect(Array.isArray(result.result)).toBe(true);
     // There might be leftover watchers from other tests, but the important
@@ -179,9 +179,9 @@ describe("watcher IPC routes", () => {
 
   test("watcher/update rejects when no update fields provided", async () => {
     const watcher = await createTestWatcher();
-    const result = await cliIpcCall("watcher/update", {
+    const result = await cliIpcCall("watcher_update", { body: {
       watcher_id: watcher.id,
-    });
+    } });
     expect(result.ok).toBe(false);
     expect(result.error).toContain("No updates provided");
   });
@@ -189,9 +189,9 @@ describe("watcher IPC routes", () => {
   // -- Delete: non-existent watcher -------------------------------------------
 
   test("watcher/delete returns error for non-existent watcher", async () => {
-    const result = await cliIpcCall("watcher/delete", {
+    const result = await cliIpcCall("watcher_delete", { body: {
       watcher_id: "does-not-exist",
-    });
+    } });
     expect(result.ok).toBe(false);
     expect(result.error).toContain("Watcher not found");
   });
@@ -202,7 +202,7 @@ describe("watcher IPC routes", () => {
     const result = await cliIpcCall<{
       events: WatcherEvent[];
       watcherNames: Record<string, string>;
-    }>("watcher/digest", {});
+    }>("watcher_digest", { body: {} });
     expect(result.ok).toBe(true);
     expect(Array.isArray(result.result!.events)).toBe(true);
     expect(typeof result.result!.watcherNames).toBe("object");
@@ -211,11 +211,11 @@ describe("watcher IPC routes", () => {
   // -- Underscore aliases -----------------------------------------------------
 
   test("watcher_create alias works identically to watcher/create", async () => {
-    const result = await cliIpcCall<Watcher>("watcher_create", {
+    const result = await cliIpcCall<Watcher>("watcher_create", { body: {
       name: "Alias Watcher",
       provider: "test-provider",
       action_prompt: "Handle events",
-    });
+    } });
     expect(result.ok).toBe(true);
     expect(result.result!.name).toBe("Alias Watcher");
     createdWatcherIds.push(result.result!.id);
@@ -223,7 +223,7 @@ describe("watcher IPC routes", () => {
 
   test("watcher_list alias works identically to watcher/list", async () => {
     const watcher = await createTestWatcher();
-    const result = await cliIpcCall<Watcher[]>("watcher_list", {});
+    const result = await cliIpcCall<Watcher[]>("watcher_list", { body: {} });
     expect(result.ok).toBe(true);
     expect(Array.isArray(result.result)).toBe(true);
     const found = result.result!.find((w) => w.id === watcher.id);
@@ -232,10 +232,10 @@ describe("watcher IPC routes", () => {
 
   test("watcher_update alias works identically to watcher/update", async () => {
     const watcher = await createTestWatcher();
-    const result = await cliIpcCall<Watcher>("watcher_update", {
+    const result = await cliIpcCall<Watcher>("watcher_update", { body: {
       watcher_id: watcher.id,
       name: "Alias Updated",
-    });
+    } });
     expect(result.ok).toBe(true);
     expect(result.result!.name).toBe("Alias Updated");
   });
@@ -244,7 +244,7 @@ describe("watcher IPC routes", () => {
     const watcher = await createTestWatcher();
     const result = await cliIpcCall<{ deleted: boolean; name: string }>(
       "watcher_delete",
-      { watcher_id: watcher.id },
+      { body: { watcher_id: watcher.id } },
     );
     expect(result.ok).toBe(true);
     expect(result.result!.deleted).toBe(true);
@@ -258,7 +258,7 @@ describe("watcher IPC routes", () => {
     const result = await cliIpcCall<{
       events: WatcherEvent[];
       watcherNames: Record<string, string>;
-    }>("watcher_digest", {});
+    }>("watcher_digest", { body: {} });
     expect(result.ok).toBe(true);
     expect(Array.isArray(result.result!.events)).toBe(true);
   });

package/src/ipc/assistant-server.ts

@@ -0,0 +1,450 @@
+/**
+ * Assistant IPC server — exposes daemon capabilities to CLI commands and external
+ * processes over a Unix domain socket.
+ *
+ * This is the preferred method of inter-process communication between the
+ * CLI and the daemon. File-based signals and the HTTP port are deprecated
+ * in favor of this IPC socket.
+ *
+ * Protocol: length-prefixed binary frames over a Unix domain socket.
+ * Each frame: [4-byte big-endian length][payload bytes]
+ *
+ * Messages use a JSON envelope:
+ * - Request:  { id, method, params?, headers? }
+ * - Response: { id, result?, error?, headers? }
+ *
+ * When a message's headers map contains "content-length", a binary data
+ * frame immediately follows the JSON frame.
+ *
+ * Chunked streaming: when the response headers contain
+ * "transfer-encoding: chunked", multiple binary data frames follow the
+ * JSON envelope. A zero-length frame terminates the stream.
+ *
+ * Legacy newline-delimited JSON is auto-detected and supported for
+ * backward compatibility with older CLI clients.
+ *
+ * The preferred socket path is `{workspaceDir}/assistant.sock`. On
+ * platforms with strict AF_UNIX path limits (notably macOS), the server falls
+ * back to a shorter deterministic path so CLI commands can still connect.
+ */
+
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { createServer, type Server, type Socket } from "node:net";
+import { dirname } from "node:path";
+
+import { RouteError } from "../runtime/routes/errors.js";
+import { ROUTES } from "../runtime/routes/index.js";
+import type { RouteDefinition } from "../runtime/routes/types.js";
+import { getLogger } from "../util/logger.js";
+import {
+  type IpcEnvelope,
+  IpcFrameReader,
+  writeLegacyMessage,
+  writeMessage,
+  writeStreamChunk,
+  writeStreamEnd,
+} from "./ipc-framing.js";
+import { type DbProxyParams,handleDbProxy } from "./routes/db-proxy.js";
+import { routeDefinitionsToIpcMethods } from "./routes/route-adapter.js";
+import { ensureSocketPathFree } from "./socket-cleanup.js";
+import { resolveIpcSocketPath } from "./socket-path.js";
+
+const log = getLogger("assistant-ipc-server");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type IpcRequest = {
+  id: string;
+  method: string;
+  params?: Record<string, unknown>;
+  headers?: Record<string, string>;
+};
+
+export type IpcResponse = {
+  id: string;
+  result?: unknown;
+  error?: string;
+  /** HTTP status code — present for all responses, not just errors. */
+  statusCode?: number;
+  /** Machine-readable error code (e.g. "NOT_FOUND") for RouteError instances. */
+  errorCode?: string;
+  headers?: Record<string, string>;
+};
+
+
+
+
+/**
+ * Wrapper returned by route handlers that produce a streaming response.
+ * The IPC server detects this and pipes the ReadableStream as chunked
+ * binary frames instead of serializing to JSON.
+ */
+export interface IpcStreamingResponse {
+  stream: ReadableStream<Uint8Array>;
+  headers: Record<string, string>;
+}
+
+/**
+ * Wrapper returned by route handlers that produce a single binary response.
+ * Sent as a JSON envelope with content-length followed by one binary frame.
+ */
+export interface IpcBinaryResponse {
+  binary: Uint8Array;
+  headers: Record<string, string>;
+}
+
+export function isIpcStreamingResponse(
+  value: unknown,
+): value is IpcStreamingResponse {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "stream" in value &&
+    (value as IpcStreamingResponse).stream instanceof ReadableStream &&
+    "headers" in value &&
+    typeof (value as IpcStreamingResponse).headers === "object"
+  );
+}
+
+export function isIpcBinaryResponse(
+  value: unknown,
+): value is IpcBinaryResponse {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "binary" in value &&
+    (value as IpcBinaryResponse).binary instanceof Uint8Array &&
+    "headers" in value &&
+    typeof (value as IpcBinaryResponse).headers === "object"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+
+export class AssistantIpcServer {
+  private server: Server | null = null;
+  private clients = new Set<Socket>();
+  private methods = new Map<string, RouteDefinition["handler"]>();
+  private socketPath: string;
+
+  constructor() {
+    const resolution = resolveIpcSocketPath("assistant");
+    this.socketPath = resolution.path;
+    log.info(
+      { source: resolution.source, path: resolution.path },
+      "Assistant IPC socket path resolved",
+    );
+    for (const route of routeDefinitionsToIpcMethods(ROUTES)) {
+      this.methods.set(route.operationId, route.handler);
+    }
+
+    // ⚠️  TEMPORARY — gateway→assistant DB proxy (see ipc/routes/db-proxy.ts).
+    // Remove once contacts/guardian-binding logic is fully migrated to the
+    // gateway's own database.
+    this.methods.set("db_proxy", (params) =>
+      handleDbProxy(params as unknown as DbProxyParams),
+    );
+  }
+
+  /** Start listening on the Unix domain socket. */
+  async start(): Promise<void> {
+    // Ensure the parent directory exists before listening.
+    const socketDir = dirname(this.socketPath);
+    if (!existsSync(socketDir)) {
+      mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+    }
+
+    // Probe before unlink so a second daemon can't silently orphan an active
+    // listener (Unix lets you unlink a still-bound socket file). See
+    // `ensureSocketPathFree` for the behavior matrix.
+    await ensureSocketPathFree(this.socketPath);
+
+    this.server = createServer((socket) => {
+      this.clients.add(socket);
+      log.debug("IPC client connected");
+
+      const reader = new IpcFrameReader(
+        (envelope, binary) =>
+          this.handleEnvelope(socket, reader, envelope, binary),
+        (err) => log.warn({ err }, "IPC frame read error"),
+      );
+
+      socket.on("data", (chunk) => {
+        reader.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+
+      socket.on("close", () => {
+        this.clients.delete(socket);
+        log.debug("IPC client disconnected");
+      });
+
+      socket.on("error", (err) => {
+        log.warn({ err }, "IPC client socket error");
+        this.clients.delete(socket);
+      });
+    });
+
+    this.server.on("error", (err) => {
+      log.error({ err }, "Assistant IPC server error");
+    });
+
+    this.server.listen(this.socketPath, () => {
+      log.info({ path: this.socketPath }, "Assistant IPC server listening");
+    });
+  }
+
+  /** Stop the server and disconnect all clients. */
+  stop(): void {
+    for (const client of this.clients) {
+      if (!client.destroyed) client.destroy();
+    }
+    this.clients.clear();
+
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+
+    if (existsSync(this.socketPath)) {
+      try {
+        unlinkSync(this.socketPath);
+      } catch {
+        // Ignore
+      }
+    }
+  }
+
+  /** Get the socket path (for diagnostics). */
+  getSocketPath(): string {
+    return this.socketPath;
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────
+
+  private handleEnvelope(
+    socket: Socket,
+    reader: IpcFrameReader,
+    envelope: IpcEnvelope,
+    binary: Uint8Array | undefined,
+  ): void {
+    const req = envelope as IpcRequest;
+
+    if (!req.id || !req.method) {
+      const id = typeof req.id === "string" ? req.id : "unknown";
+      this.sendResponse(socket, reader, {
+        id,
+        error: "Missing 'id' or 'method' field",
+      });
+      return;
+    }
+
+    const handler = this.methods.get(req.method);
+    if (!handler) {
+      this.sendResponse(socket, reader, {
+        id: req.id,
+        error: `Unknown method: ${req.method}`,
+      });
+      return;
+    }
+
+    void binary;
+
+    try {
+      const result = handler(req.params ?? {});
+
+      if (result instanceof Promise) {
+        result
+          .then((value) => {
+            this.sendResult(socket, reader, req.id, value);
+          })
+          .catch((err) => {
+            log.warn({ err, method: req.method }, "IPC handler error");
+            this.sendResponse(
+              socket,
+              reader,
+              this.buildErrorResponse(req.id, err),
+            );
+          });
+      } else {
+        this.sendResult(socket, reader, req.id, result);
+      }
+    } catch (err) {
+      log.warn({ err, method: req.method }, "IPC handler error");
+      this.sendResponse(socket, reader, this.buildErrorResponse(req.id, err));
+    }
+  }
+
+  private buildErrorResponse(id: string, err: unknown): IpcResponse {
+    if (err instanceof RouteError) {
+      return {
+        id,
+        error: err.message,
+        statusCode: err.statusCode,
+        errorCode: err.code,
+      };
+    }
+    return { id, error: String(err) };
+  }
+
+  /**
+   * Route a handler result to the appropriate send path:
+   * - IpcStreamingResponse → chunked binary frames
+   * - IpcBinaryResponse → single binary frame with content-length
+   * - Everything else → JSON response
+   */
+  private sendResult(
+    socket: Socket,
+    reader: IpcFrameReader,
+    requestId: string,
+    value: unknown,
+  ): void {
+    if (isIpcStreamingResponse(value)) {
+      this.sendStreamingResponse(socket, reader, requestId, value);
+    } else if (isIpcBinaryResponse(value)) {
+      const envelope: IpcResponse = {
+        id: requestId,
+        headers: {
+          ...value.headers,
+          "content-length": String(value.binary.byteLength),
+        },
+      };
+      this.sendResponse(socket, reader, envelope, value.binary);
+    } else {
+      this.sendResponse(socket, reader, { id: requestId, result: value });
+    }
+  }
+
+  /**
+   * Pipe a ReadableStream as chunked binary frames over IPC.
+   *
+   * Wire format:
+   *   [JSON envelope: { id, headers: { "transfer-encoding": "chunked", ... } }]
+   *   [chunk frame 1]
+   *   [chunk frame 2]
+   *   ...
+   *   [zero-length terminator]
+   */
+  private sendStreamingResponse(
+    socket: Socket,
+    reader: IpcFrameReader,
+    requestId: string,
+    response: IpcStreamingResponse,
+  ): void {
+    if (socket.destroyed) return;
+
+    // Legacy clients can't handle chunked streaming — fall back to
+    // buffering the full stream and sending as a single binary response.
+    if (reader.isLegacy) {
+      this.bufferAndSendStream(socket, reader, requestId, response);
+      return;
+    }
+
+    const envelope: IpcResponse = {
+      id: requestId,
+      headers: {
+        ...response.headers,
+        "transfer-encoding": "chunked",
+      },
+    };
+    writeMessage(socket, envelope);
+
+    const streamReader = response.stream.getReader();
+    const pump = (): void => {
+      streamReader
+        .read()
+        .then(({ done, value }) => {
+          if (socket.destroyed) {
+            streamReader.cancel().catch(() => {});
+            return;
+          }
+          if (done) {
+            writeStreamEnd(socket);
+            return;
+          }
+          writeStreamChunk(socket, value);
+          pump();
+        })
+        .catch((err) => {
+          log.warn({ err }, "IPC stream read error");
+          if (!socket.destroyed) {
+            writeStreamEnd(socket);
+          }
+        });
+    };
+    pump();
+  }
+
+  /**
+   * Legacy fallback: buffer the entire stream, then send as a single
+   * binary response with content-length.
+   */
+  private bufferAndSendStream(
+    socket: Socket,
+    reader: IpcFrameReader,
+    requestId: string,
+    response: IpcStreamingResponse,
+  ): void {
+    const chunks: Uint8Array[] = [];
+    const streamReader = response.stream.getReader();
+
+    const pump = (): void => {
+      streamReader
+        .read()
+        .then(({ done, value }) => {
+          if (done) {
+            const totalLength = chunks.reduce(
+              (sum, c) => sum + c.byteLength,
+              0,
+            );
+            const merged = new Uint8Array(totalLength);
+            let offset = 0;
+            for (const c of chunks) {
+              merged.set(c, offset);
+              offset += c.byteLength;
+            }
+            const envelope: IpcResponse = {
+              id: requestId,
+              headers: {
+                ...response.headers,
+                "content-length": String(totalLength),
+              },
+            };
+            this.sendResponse(socket, reader, envelope, merged);
+            return;
+          }
+          chunks.push(value);
+          pump();
+        })
+        .catch((err) => {
+          log.warn({ err }, "IPC legacy stream buffer error");
+          this.sendResponse(socket, reader, {
+            id: requestId,
+            error: "Stream read failed",
+          });
+        });
+    };
+    pump();
+  }
+
+  private sendResponse(
+    socket: Socket,
+    reader: IpcFrameReader,
+    response: IpcResponse,
+    binary?: Uint8Array,
+  ): void {
+    if (socket.destroyed) return;
+    if (reader.isLegacy) {
+      writeLegacyMessage(socket, response);
+    } else {
+      writeMessage(socket, response, binary);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------