@vellumai/assistant 0.6.3 → 0.6.5

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

@@ -0,0 +1,295 @@
+/**
+ * Integration tests for the watcher IPC routes.
+ *
+ * Exercises the full IPC round-trip: CliIpcServer + 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 { registerWatcherProvider } from "../../watcher/provider-registry.js";
+import type { WatcherProvider } from "../../watcher/provider-types.js";
+import type { Watcher, WatcherEvent } from "../../watcher/watcher-store.js";
+import { cliIpcCall } from "../cli-client.js";
+import { CliIpcServer } from "../cli-server.js";
+
+// ---------------------------------------------------------------------------
+// DB + provider setup
+// ---------------------------------------------------------------------------
+
+initializeDb();
+
+const mockProvider: WatcherProvider = {
+  id: "test-provider",
+  displayName: "Test Provider",
+  requiredCredentialService: "test-cred",
+  async fetchNew() {
+    return { items: [], watermark: "w1" };
+  },
+  async getInitialWatermark() {
+    return "initial";
+  },
+  cleanup() {},
+};
+
+registerWatcherProvider(mockProvider);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let server: CliIpcServer | null = null;
+
+/** IDs of watchers created during a test, cleaned up in afterEach. */
+const createdWatcherIds: string[] = [];
+
+beforeEach(async () => {
+  server = new CliIpcServer();
+  server.start();
+  // Allow the server socket to bind.
+  await new Promise((resolve) => setTimeout(resolve, 50));
+});
+
+afterEach(async () => {
+  // Clean up watchers created during the test.
+  for (const id of createdWatcherIds) {
+    await cliIpcCall("watcher/delete", { watcher_id: id });
+  }
+  createdWatcherIds.length = 0;
+
+  server?.stop();
+  server = null;
+});
+
+/** Helper to create a watcher and track it for cleanup. */
+async function createTestWatcher(
+  overrides?: Record<string, unknown>,
+): Promise<Watcher> {
+  const result = await cliIpcCall<Watcher>("watcher/create", {
+    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);
+  return result.result!;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("watcher IPC routes", () => {
+  // -- CRUD round-trip --------------------------------------------------------
+
+  test("create -> list -> update -> delete round-trip", async () => {
+    // Create
+    const watcher = await createTestWatcher();
+    expect(watcher.name).toBe("Test Watcher");
+    expect(watcher.providerId).toBe("test-provider");
+    expect(watcher.actionPrompt).toBe("Handle events");
+    expect(watcher.enabled).toBe(true);
+    expect(watcher.status).toBe("idle");
+
+    // List all
+    const listResult = await cliIpcCall<Watcher[]>("watcher/list", {});
+    expect(listResult.ok).toBe(true);
+    expect(Array.isArray(listResult.result)).toBe(true);
+    const found = listResult.result!.find((w) => w.id === watcher.id);
+    expect(found).toBeDefined();
+
+    // List single
+    const detailResult = await cliIpcCall<{
+      watcher: Watcher;
+      events: WatcherEvent[];
+    }>("watcher/list", { 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", {
+      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 },
+    );
+    expect(deleteResult.ok).toBe(true);
+    expect(deleteResult.result!.deleted).toBe(true);
+    expect(deleteResult.result!.name).toBe("Updated Watcher");
+
+    // Remove from cleanup tracking since we already deleted it.
+    const idx = createdWatcherIds.indexOf(watcher.id);
+    if (idx >= 0) createdWatcherIds.splice(idx, 1);
+
+    // Confirm gone
+    const afterDelete = await cliIpcCall<Watcher[]>("watcher/list", {});
+    expect(afterDelete.ok).toBe(true);
+    const gone = afterDelete.result!.find((w) => w.id === watcher.id);
+    expect(gone).toBeUndefined();
+  });
+
+  // -- Create: unknown provider -----------------------------------------------
+
+  test("watcher/create rejects unknown provider", async () => {
+    const result = await cliIpcCall("watcher/create", {
+      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");
+  });
+
+  // -- Create: poll interval too low ------------------------------------------
+
+  test("watcher/create rejects poll_interval_ms < 15000", async () => {
+    const result = await cliIpcCall("watcher/create", {
+      name: "Fast Watcher",
+      provider: "test-provider",
+      action_prompt: "Handle events",
+      poll_interval_ms: 5000,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.error).toBeDefined();
+  });
+
+  // -- List: empty state ------------------------------------------------------
+
+  test("watcher/list returns empty array when no watchers exist", async () => {
+    const result = await cliIpcCall<Watcher[]>("watcher/list", {});
+    expect(result.ok).toBe(true);
+    expect(Array.isArray(result.result)).toBe(true);
+    // There might be leftover watchers from other tests, but the important
+    // thing is that the call succeeds and returns an array.
+  });
+
+  // -- Update: no fields provided ---------------------------------------------
+
+  test("watcher/update rejects when no update fields provided", async () => {
+    const watcher = await createTestWatcher();
+    const result = await cliIpcCall("watcher/update", {
+      watcher_id: watcher.id,
+    });
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("No updates provided");
+  });
+
+  // -- Delete: non-existent watcher -------------------------------------------
+
+  test("watcher/delete returns error for non-existent watcher", async () => {
+    const result = await cliIpcCall("watcher/delete", {
+      watcher_id: "does-not-exist",
+    });
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain("Watcher not found");
+  });
+
+  // -- Digest: empty events ---------------------------------------------------
+
+  test("watcher/digest returns empty events when no events exist", async () => {
+    const result = await cliIpcCall<{
+      events: WatcherEvent[];
+      watcherNames: Record<string, string>;
+    }>("watcher/digest", {});
+    expect(result.ok).toBe(true);
+    expect(Array.isArray(result.result!.events)).toBe(true);
+    expect(typeof result.result!.watcherNames).toBe("object");
+  });
+
+  // -- Underscore aliases -----------------------------------------------------
+
+  test("watcher_create alias works identically to watcher/create", async () => {
+    const result = await cliIpcCall<Watcher>("watcher_create", {
+      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);
+  });
+
+  test("watcher_list alias works identically to watcher/list", async () => {
+    const watcher = await createTestWatcher();
+    const result = await cliIpcCall<Watcher[]>("watcher_list", {});
+    expect(result.ok).toBe(true);
+    expect(Array.isArray(result.result)).toBe(true);
+    const found = result.result!.find((w) => w.id === watcher.id);
+    expect(found).toBeDefined();
+  });
+
+  test("watcher_update alias works identically to watcher/update", async () => {
+    const watcher = await createTestWatcher();
+    const result = await cliIpcCall<Watcher>("watcher_update", {
+      watcher_id: watcher.id,
+      name: "Alias Updated",
+    });
+    expect(result.ok).toBe(true);
+    expect(result.result!.name).toBe("Alias Updated");
+  });
+
+  test("watcher_delete alias works identically to watcher/delete", async () => {
+    const watcher = await createTestWatcher();
+    const result = await cliIpcCall<{ deleted: boolean; name: string }>(
+      "watcher_delete",
+      { watcher_id: watcher.id },
+    );
+    expect(result.ok).toBe(true);
+    expect(result.result!.deleted).toBe(true);
+
+    // Remove from cleanup tracking.
+    const idx = createdWatcherIds.indexOf(watcher.id);
+    if (idx >= 0) createdWatcherIds.splice(idx, 1);
+  });
+
+  test("watcher_digest alias works identically to watcher/digest", async () => {
+    const result = await cliIpcCall<{
+      events: WatcherEvent[];
+      watcherNames: Record<string, string>;
+    }>("watcher_digest", {});
+    expect(result.ok).toBe(true);
+    expect(Array.isArray(result.result!.events)).toBe(true);
+  });
+
+  // -- Create: credential_service override ------------------------------------
+
+  test("watcher/create uses provider default credential_service when not overridden", async () => {
+    const watcher = await createTestWatcher();
+    expect(watcher.credentialService).toBe("test-cred");
+  });
+
+  test("watcher/create accepts credential_service override", async () => {
+    const watcher = await createTestWatcher({
+      credential_service: "custom-cred",
+    });
+    expect(watcher.credentialService).toBe("custom-cred");
+  });
+
+  // -- Create: config passthrough ---------------------------------------------
+
+  test("watcher/create passes config as configJson", async () => {
+    const watcher = await createTestWatcher({
+      config: { filter: "important" },
+    });
+    expect(watcher.configJson).toBe(JSON.stringify({ filter: "important" }));
+  });
+
+  // -- Create: custom poll interval -------------------------------------------
+
+  test("watcher/create accepts valid poll_interval_ms", async () => {
+    const watcher = await createTestWatcher({ poll_interval_ms: 30000 });
+    expect(watcher.pollIntervalMs).toBe(30000);
+  });
+});

package/src/ipc/cli-client.ts

@@ -0,0 +1,152 @@
+/**
+ * CLI IPC client for communicating with the assistant daemon.
+ *
+ * One-shot connect → call → disconnect over the CLI IPC socket.
+ * Returns a typed result object so callers can distinguish success
+ * from connection failures and method errors.
+ *
+ * The preferred socket path is `{workspaceDir}/assistant-cli.sock`, with a
+ * deterministic fallback for long AF_UNIX paths.
+ */
+
+import { connect, type Socket } from "node:net";
+
+import { getLogger } from "../util/logger.js";
+import { getCliSocketPath } from "./cli-server.js";
+
+const log = getLogger("cli-ipc-client");
+
+// ---------------------------------------------------------------------------
+// Types (mirror cli-server.ts protocol)
+// ---------------------------------------------------------------------------
+
+type IpcRequest = {
+  id: string;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type IpcResponse = {
+  id: string;
+  result?: unknown;
+  error?: string;
+};
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CALL_TIMEOUT_MS = 60_000; // wake may take time (agent loop runs)
+const CONNECT_TIMEOUT_MS = 3_000;
+
+export interface CliIpcCallResult<T = unknown> {
+  ok: boolean;
+  result?: T;
+  error?: string;
+}
+
+/**
+ * One-shot IPC helper: connect to the daemon socket, call a method,
+ * return the result, disconnect.
+ *
+ * Returns a typed result object so callers can distinguish success from
+ * connection failures and method errors.
+ */
+export async function cliIpcCall<T = unknown>(
+  method: string,
+  params?: Record<string, unknown>,
+  options?: { timeoutMs?: number },
+): Promise<CliIpcCallResult<T>> {
+  const socketPath = getCliSocketPath();
+  const callTimeoutMs = options?.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+
+  return new Promise<CliIpcCallResult<T>>((resolve) => {
+    let settled = false;
+    let callTimer: ReturnType<typeof setTimeout> | undefined;
+
+    const finish = (result: CliIpcCallResult<T>) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(connectTimer);
+      if (callTimer) clearTimeout(callTimer);
+      socket.destroy();
+      resolve(result);
+    };
+
+    const connectTimer = setTimeout(() => {
+      log.debug(
+        { method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS },
+        "CLI IPC connect timed out",
+      );
+      finish({
+        ok: false,
+        error: "Could not connect to assistant daemon. Is it running?",
+      });
+    }, CONNECT_TIMEOUT_MS);
+
+    const socket: Socket = connect(socketPath);
+    socket.unref();
+
+    let buffer = "";
+    const reqId = crypto.randomUUID();
+
+    socket.on("connect", () => {
+      clearTimeout(connectTimer);
+      const req: IpcRequest = { id: reqId, method, params };
+      socket.write(JSON.stringify(req) + "\n");
+
+      callTimer = setTimeout(() => {
+        log.debug(
+          { method, socketPath, timeoutMs: callTimeoutMs },
+          "CLI IPC call timed out waiting for response",
+        );
+        finish({ ok: false, error: "Request timed out" });
+      }, callTimeoutMs);
+
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString();
+        let newlineIdx: number;
+        while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, newlineIdx).trim();
+          buffer = buffer.slice(newlineIdx + 1);
+          if (!line) continue;
+
+          try {
+            const msg = JSON.parse(line) as IpcResponse;
+            if (msg.id === reqId) {
+              if (msg.error) {
+                finish({ ok: false, error: msg.error });
+              } else {
+                finish({ ok: true, result: msg.result as T });
+              }
+              return;
+            }
+          } catch {
+            // Ignore malformed lines
+          }
+        }
+      });
+    });
+
+    socket.on("error", (err) => {
+      const code = (err as NodeJS.ErrnoException).code;
+      log.debug({ err, code, method, socketPath }, "CLI IPC socket error");
+      finish({
+        ok: false,
+        error:
+          code === "ENOENT" || code === "ECONNREFUSED"
+            ? "Could not connect to assistant daemon. Is it running?"
+            : `Connection error: ${code ?? err.message}`,
+      });
+    });
+
+    socket.on("close", () => {
+      if (!settled) {
+        finish({
+          ok: false,
+          error: "Connection closed before response",
+        });
+      }
+    });
+  });
+}

package/src/ipc/cli-server.ts

@@ -0,0 +1,252 @@
+/**
+ * CLI 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: newline-delimited JSON over a Unix domain socket.
+ * - Request:  { "id": string, "method": string, "params"?: Record<string, unknown> }
+ * - Response: { "id": string, "result"?: unknown, "error"?: string }
+ *
+ * The preferred socket path is `{workspaceDir}/assistant-cli.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 { getLogger } from "../util/logger.js";
+import { cliIpcRoutes } from "./routes/index.js";
+import { resolveIpcSocketPath } from "./socket-path.js";
+
+const log = getLogger("cli-ipc-server");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type IpcRequest = {
+  id: string;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+export type IpcResponse = {
+  id: string;
+  result?: unknown;
+  error?: string;
+};
+
+export type IpcMethodHandler = (
+  params?: Record<string, unknown>,
+) => unknown | Promise<unknown>;
+
+/** A single IPC route definition — method name + handler function. */
+export type IpcRoute = {
+  method: string;
+  handler: IpcMethodHandler;
+};
+
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+
+export class CliIpcServer {
+  private server: Server | null = null;
+  private clients = new Set<Socket>();
+  private methods = new Map<string, IpcMethodHandler>();
+  private socketPath: string;
+
+  constructor() {
+    const socketResolution = resolveIpcSocketPath("assistant-cli.sock");
+    this.socketPath = socketResolution.path;
+    if (socketResolution.source !== "workspace") {
+      log.warn(
+        {
+          source: socketResolution.source,
+          workspacePath: socketResolution.workspacePath,
+          resolvedPath: socketResolution.path,
+          maxPathBytes: socketResolution.maxPathBytes,
+        },
+        "CLI IPC socket path exceeded platform limit; using fallback path",
+      );
+    }
+    for (const route of cliIpcRoutes) {
+      this.methods.set(route.method, route.handler);
+    }
+  }
+
+  /** Register an additional method handler after construction. */
+  registerMethod(method: string, handler: IpcMethodHandler): void {
+    this.methods.set(method, handler);
+  }
+
+  /** Start listening on the Unix domain socket. */
+  start(): void {
+    // Ensure the parent directory exists before listening.
+    const socketDir = dirname(this.socketPath);
+    if (!existsSync(socketDir)) {
+      mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+    }
+
+    // Clean up stale socket file from a previous run
+    if (existsSync(this.socketPath)) {
+      try {
+        unlinkSync(this.socketPath);
+      } catch {
+        // Ignore — may already be gone
+      }
+    }
+
+    this.server = createServer((socket) => {
+      this.clients.add(socket);
+      log.debug("IPC client connected");
+
+      let buffer = "";
+
+      socket.on("data", (chunk) => {
+        buffer += chunk.toString();
+        let newlineIdx: number;
+        while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, newlineIdx).trim();
+          buffer = buffer.slice(newlineIdx + 1);
+          if (line) {
+            this.handleMessage(socket, line);
+          }
+        }
+      });
+
+      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 }, "CLI IPC server error");
+    });
+
+    this.server.listen(this.socketPath, () => {
+      log.info({ path: this.socketPath }, "CLI 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 handleMessage(socket: Socket, line: string): void {
+    let req: IpcRequest;
+    try {
+      req = JSON.parse(line) as IpcRequest;
+    } catch {
+      this.sendResponse(socket, {
+        id: "unknown",
+        error: "Invalid JSON",
+      });
+      return;
+    }
+
+    if (
+      !req ||
+      typeof req !== "object" ||
+      Array.isArray(req) ||
+      !req.id ||
+      !req.method
+    ) {
+      const id =
+        req &&
+        typeof req === "object" &&
+        !Array.isArray(req) &&
+        typeof req.id === "string"
+          ? req.id
+          : "unknown";
+      this.sendResponse(socket, {
+        id,
+        error: "Missing 'id' or 'method' field",
+      });
+      return;
+    }
+
+    const handler = this.methods.get(req.method);
+    if (!handler) {
+      this.sendResponse(socket, {
+        id: req.id,
+        error: `Unknown method: ${req.method}`,
+      });
+      return;
+    }
+
+    try {
+      const result = handler(req.params);
+      if (result instanceof Promise) {
+        result
+          .then((value) => {
+            this.sendResponse(socket, { id: req.id, result: value });
+          })
+          .catch((err) => {
+            log.warn({ err, method: req.method }, "IPC handler error");
+            this.sendResponse(socket, {
+              id: req.id,
+              error: String(err),
+            });
+          });
+      } else {
+        this.sendResponse(socket, { id: req.id, result });
+      }
+    } catch (err) {
+      log.warn({ err, method: req.method }, "IPC handler error");
+      this.sendResponse(socket, {
+        id: req.id,
+        error: String(err),
+      });
+    }
+  }
+
+  private sendResponse(socket: Socket, response: IpcResponse): void {
+    if (!socket.destroyed) {
+      socket.write(JSON.stringify(response) + "\n");
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function getCliSocketPath(): string {
+  return resolveIpcSocketPath("assistant-cli.sock").path;
+}