@vellumai/assistant 0.6.4 → 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

@@ -5,7 +5,8 @@
  * Returns a typed result object so callers can distinguish success
  * from connection failures and method errors.
  *
- * The socket lives at `{workspaceDir}/assistant-cli.sock`.
+ * 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";

package/src/ipc/cli-server.ts

@@ -10,17 +10,18 @@
  * - Request:  { "id": string, "method": string, "params"?: Record<string, unknown> }
  * - Response: { "id": string, "result"?: unknown, "error"?: string }
  *
- * The socket lives at `{workspaceDir}/assistant-cli.sock` on the workspace
- * volume so CLI commands running in the same container can connect to it.
+ * 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, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
-import { join } from "node:path";
+import { dirname } from "node:path";
 
 import { getLogger } from "../util/logger.js";
-import { getWorkspaceDir } from "../util/platform.js";
 import { cliIpcRoutes } from "./routes/index.js";
+import { resolveIpcSocketPath } from "./socket-path.js";
 
 const log = getLogger("cli-ipc-server");
 
@@ -61,7 +62,19 @@ export class CliIpcServer {
   private socketPath: string;
 
   constructor() {
-    this.socketPath = getCliSocketPath();
+    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);
     }
@@ -74,6 +87,12 @@ export class CliIpcServer {
 
   /** 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 {
@@ -229,6 +248,5 @@ export class CliIpcServer {
 // ---------------------------------------------------------------------------
 
 export function getCliSocketPath(): string {
-  return join(getWorkspaceDir(), "assistant-cli.sock");
+  return resolveIpcSocketPath("assistant-cli.sock").path;
 }
-

package/src/ipc/gateway-client.ts

@@ -5,14 +5,14 @@
  * for reading gateway-owned data. Protocol: newline-delimited JSON
  * (same as gateway/src/ipc/server.ts).
  *
- * The socket lives at `{workspaceDir}/gateway.sock` on the shared volume.
+ * The preferred socket path is `{workspaceDir}/gateway.sock`, with a
+ * deterministic fallback for long AF_UNIX paths.
  */
 
 import { connect, type Socket } from "node:net";
-import { join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
-import { getWorkspaceDir } from "../util/platform.js";
+import { resolveIpcSocketPath } from "./socket-path.js";
 
 const log = getLogger("gateway-ipc-client");
 
@@ -176,5 +176,5 @@ export async function ipcGetFeatureFlags(): Promise<Record<string, boolean>> {
 // ---------------------------------------------------------------------------
 
 function getGatewaySocketPath(): string {
-  return join(getWorkspaceDir(), "gateway.sock");
+  return resolveIpcSocketPath("gateway.sock").path;
 }

package/src/ipc/routes/attachment.ts

@@ -0,0 +1,114 @@
+/**
+ * IPC routes for attachment operations.
+ *
+ * Exposes register and lookup operations so CLI commands and external
+ * processes can interact with the attachment store.
+ *
+ * Each operation is registered under both a slash-style method name
+ * (e.g. `attachment/register`) and an underscore alias (`attachment_register`)
+ * for ergonomics.
+ */
+
+import { statSync } from "node:fs";
+import { basename } from "node:path";
+
+import { z } from "zod";
+
+import {
+  getFilePathBySourcePath,
+  uploadFileBackedAttachment,
+  validateAttachmentUpload,
+} from "../../memory/attachments-store.js";
+import type { IpcRoute } from "../cli-server.js";
+
+// -- Param schemas --------------------------------------------------------
+
+const AttachmentRegisterParams = z.object({
+  path: z.string().min(1),
+  mimeType: z.string().min(1),
+  filename: z.string().optional(),
+});
+
+const AttachmentLookupParams = z.object({
+  sourcePath: z.string().min(1),
+  conversationId: z.string().min(1),
+});
+
+// -- Handlers -------------------------------------------------------------
+
+function handleAttachmentRegister(params?: Record<string, unknown>) {
+  const { path, mimeType, filename } = AttachmentRegisterParams.parse(params);
+
+  let sizeBytes: number;
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile()) {
+      throw new Error(
+        `Path is not a regular file: ${path}. Provide a path to a file, not a directory.`,
+      );
+    }
+    sizeBytes = stat.size;
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("Path is not")) {
+      throw err;
+    }
+    throw new Error(`File not found: ${path}`);
+  }
+
+  const resolvedFilename = filename ?? basename(path);
+
+  const validation = validateAttachmentUpload(resolvedFilename, mimeType);
+  if (!validation.ok) {
+    throw new Error(validation.error);
+  }
+
+  return uploadFileBackedAttachment(
+    resolvedFilename,
+    mimeType,
+    path,
+    sizeBytes,
+  );
+}
+
+function handleAttachmentLookup(params?: Record<string, unknown>) {
+  const { sourcePath, conversationId } = AttachmentLookupParams.parse(params);
+
+  const result = getFilePathBySourcePath(sourcePath, conversationId);
+  if (result === null) {
+    throw new Error(
+      `No attachment found for source path: ${sourcePath} in conversation ${conversationId}. Run 'assistant attachment register' to register a file first.`,
+    );
+  }
+
+  return { filePath: result };
+}
+
+// -- Route definitions ----------------------------------------------------
+
+export const attachmentRegisterRoute: IpcRoute = {
+  method: "attachment/register",
+  handler: handleAttachmentRegister,
+};
+
+const attachmentRegisterAliasRoute: IpcRoute = {
+  method: "attachment_register",
+  handler: handleAttachmentRegister,
+};
+
+export const attachmentLookupRoute: IpcRoute = {
+  method: "attachment/lookup",
+  handler: handleAttachmentLookup,
+};
+
+const attachmentLookupAliasRoute: IpcRoute = {
+  method: "attachment_lookup",
+  handler: handleAttachmentLookup,
+};
+
+/** All attachment IPC routes (canonical + aliases). */
+export const attachmentRoutes: IpcRoute[] = [
+  attachmentRegisterRoute,
+  attachmentRegisterAliasRoute,
+  attachmentLookupRoute,
+  attachmentLookupAliasRoute,
+];

package/src/ipc/routes/browser-context.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared context resolver for `browser_execute` IPC calls.
+ *
+ * The browser CLI can optionally pass a live conversation ID (for example
+ * from `__CONVERSATION_ID` in a nested `bash` tool invocation). When that
+ * conversation is currently active in daemon memory, we can reuse its
+ * host-browser proxy wiring so browser operations (including `status`) see
+ * extension connectivity exactly as the parent turn does.
+ *
+ * If no resolver is registered, or the requested conversation isn't active,
+ * callers fall back to the deterministic `browser-cli:<sessionId>` context.
+ */
+
+import type { InterfaceId } from "../../channels/types.js";
+import type { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
+import type { TrustClass } from "../../runtime/actor-trust-resolver.js";
+
+export interface BrowserIpcContextResolution {
+  conversationId: string;
+  trustClass: TrustClass;
+  hostBrowserProxy?: HostBrowserProxy;
+  transportInterface?: InterfaceId;
+}
+
+export type BrowserIpcContextResolver = (
+  conversationId: string,
+) => BrowserIpcContextResolution | null;
+
+let resolver: BrowserIpcContextResolver | null = null;
+
+export function registerBrowserIpcContextResolver(
+  nextResolver: BrowserIpcContextResolver,
+): void {
+  resolver = nextResolver;
+}
+
+/**
+ * Test-only helper to clear the module-level resolver.
+ *
+ * @internal
+ */
+export function resetBrowserIpcContextResolverForTests(): void {
+  resolver = null;
+}
+
+export function resolveBrowserIpcContext(params: {
+  requestedConversationId?: string;
+  fallbackConversationId: string;
+}): BrowserIpcContextResolution {
+  const { requestedConversationId, fallbackConversationId } = params;
+
+  if (requestedConversationId && resolver) {
+    const resolved = resolver(requestedConversationId);
+    if (resolved) return resolved;
+  }
+
+  return {
+    conversationId: fallbackConversationId,
+    trustClass: "guardian",
+  };
+}

package/src/ipc/routes/browser.ts

@@ -0,0 +1,96 @@
+/**
+ * IPC route for browser operations.
+ *
+ * Exposes `browser_execute` so CLI commands and external processes can
+ * invoke browser operations without going through skill tool wrappers.
+ *
+ * The `sessionId` parameter (default `"default"`) is mapped to a
+ * deterministic conversation key `browser-cli:<sessionId>` so that
+ * sequential IPC calls with the same session reuse browser state.
+ */
+
+import { z } from "zod";
+
+import { executeBrowserOperation } from "../../browser/operations.js";
+import {
+  BROWSER_OPERATIONS,
+  type BrowserOperation,
+} from "../../browser/types.js";
+import type { ContentBlock } from "../../providers/types.js";
+import type { IpcRoute } from "../cli-server.js";
+import { resolveBrowserIpcContext } from "./browser-context.js";
+
+// ── Param validation ─────────────────────────────────────────────────
+
+const BrowserExecuteParams = z.object({
+  operation: z.enum(BROWSER_OPERATIONS as unknown as [string, ...string[]]),
+  input: z.record(z.string(), z.unknown()).default({}),
+  sessionId: z.string().min(1).default("default"),
+  conversationId: z.string().min(1).optional(),
+});
+
+// ── Conversation key ─────────────────────────────────────────────────
+
+/**
+ * Build a deterministic conversation key from a session ID.
+ * All CLI browser calls with the same session share browser state.
+ */
+export function browserCliConversationKey(sessionId: string): string {
+  return `browser-cli:${sessionId}`;
+}
+
+// ── Screenshot extraction ────────────────────────────────────────────
+
+/**
+ * Extract base64 screenshot payloads from tool execution content blocks.
+ * Returns an array of `{ mediaType, data }` objects for each image found.
+ */
+function extractScreenshots(
+  contentBlocks?: ContentBlock[],
+): Array<{ mediaType: string; data: string }> {
+  if (!contentBlocks) return [];
+  const screenshots: Array<{ mediaType: string; data: string }> = [];
+  for (const block of contentBlocks) {
+    if (block.type === "image" && block.source.type === "base64") {
+      screenshots.push({
+        mediaType: block.source.media_type,
+        data: block.source.data,
+      });
+    }
+  }
+  return screenshots;
+}
+
+// ── Route definition ─────────────────────────────────────────────────
+
+export const browserExecuteRoute: IpcRoute = {
+  method: "browser_execute",
+  handler: async (params) => {
+    const { operation, input, sessionId, conversationId } =
+      BrowserExecuteParams.parse(params);
+    const resolvedContext = resolveBrowserIpcContext({
+      requestedConversationId: conversationId,
+      fallbackConversationId: browserCliConversationKey(sessionId),
+    });
+
+    const result = await executeBrowserOperation(
+      operation as BrowserOperation,
+      input,
+      {
+        workingDir: process.cwd(),
+        conversationId: resolvedContext.conversationId,
+        trustClass: resolvedContext.trustClass,
+        hostBrowserProxy: resolvedContext.hostBrowserProxy,
+        transportInterface: resolvedContext.transportInterface,
+      },
+    );
+
+    const screenshots = extractScreenshots(result.contentBlocks);
+
+    return {
+      content: result.content,
+      isError: result.isError,
+      ...(screenshots.length > 0 ? { screenshots } : {}),
+    };
+  },
+};