@vellumai/assistant 0.7.3 → 0.8.1

package/src/runtime/routes/__tests__/memory-v2-routes.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Tests for the memory v2 route handlers in `memory-v2-routes.ts`.
+ *
+ * Currently focused on `memory_v2_list_concept_pages`:
+ *   - empty workspace → returns no pages
+ *   - populated workspace → surfaces slug, bodyBytes, edgeCount, updatedAtMs
+ *   - corrupt page on disk → logged-and-skipped, does not poison listing
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { writePage } from "../../../memory/v2/page-store.js";
+import type { ConceptPage } from "../../../memory/v2/types.js";
+import type { MemoryV2ListConceptPagesResult } from "../memory-v2-routes.js";
+import { ROUTES } from "../memory-v2-routes.js";
+import type { RouteDefinition } from "../types.js";
+
+// ─── Setup ─────────────────────────────────────────────────────────────────
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = ROUTES.find((r) => r.operationId === operationId);
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-memv2-list-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+});
+
+afterEach(() => {
+  if (origWorkspaceDir === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = origWorkspaceDir;
+  }
+  try {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  } catch {
+    // best-effort cleanup
+  }
+});
+
+// ─── Tests ─────────────────────────────────────────────────────────────────
+
+describe("memory_v2_list_concept_pages handler", () => {
+  test("returns empty list for an empty workspace", async () => {
+    const handler = findHandler("memory_v2_list_concept_pages");
+    const result = (await handler({
+      body: {},
+    })) as MemoryV2ListConceptPagesResult;
+
+    expect(result).toEqual({ pages: [] });
+  });
+
+  test("returns slugs, body bytes, edge counts, and mtimes for populated workspace", async () => {
+    const before = Date.now();
+
+    const pages: ConceptPage[] = [
+      {
+        slug: "alice",
+        frontmatter: { edges: ["bob", "carol"], ref_files: [], ref_urls: [] },
+        body: "Alice prefers VS Code.\n",
+      },
+      {
+        slug: "bob",
+        frontmatter: { edges: [], ref_files: [], ref_urls: [] },
+        body: "Bob ships at end of day.\nLikes async standups.\n",
+      },
+      {
+        slug: "people/carol",
+        frontmatter: { edges: ["alice"], ref_files: [], ref_urls: [] },
+        body: "Carol leads the platform team.\n",
+      },
+    ];
+    for (const page of pages) {
+      await writePage(workspaceDir, page);
+    }
+
+    const handler = findHandler("memory_v2_list_concept_pages");
+    const result = (await handler({
+      body: {},
+    })) as MemoryV2ListConceptPagesResult;
+
+    expect(result.pages).toHaveLength(3);
+
+    const bySlug = new Map(result.pages.map((p) => [p.slug, p]));
+
+    const alice = bySlug.get("alice");
+    expect(alice).toBeDefined();
+    expect(alice!.bodyBytes).toBe(Buffer.byteLength(pages[0]!.body, "utf8"));
+    expect(alice!.edgeCount).toBe(2);
+    expect(alice!.updatedAtMs).toBeGreaterThanOrEqual(before);
+    // updatedAtMs must be an integer on the wire — Swift clients decode it as
+    // Int64 and a sub-millisecond float (which fs.Stats.mtimeMs returns by
+    // default) breaks JSONDecoder strict number parsing.
+    expect(Number.isInteger(alice!.updatedAtMs)).toBe(true);
+
+    const bob = bySlug.get("bob");
+    expect(bob).toBeDefined();
+    expect(bob!.bodyBytes).toBe(Buffer.byteLength(pages[1]!.body, "utf8"));
+    expect(bob!.edgeCount).toBe(0);
+    expect(bob!.updatedAtMs).toBeGreaterThanOrEqual(before);
+    expect(Number.isInteger(bob!.updatedAtMs)).toBe(true);
+
+    const carol = bySlug.get("people/carol");
+    expect(carol).toBeDefined();
+    expect(carol!.bodyBytes).toBe(Buffer.byteLength(pages[2]!.body, "utf8"));
+    expect(carol!.edgeCount).toBe(1);
+    expect(carol!.updatedAtMs).toBeGreaterThanOrEqual(before);
+    expect(Number.isInteger(carol!.updatedAtMs)).toBe(true);
+  });
+
+  test("tolerates a single corrupt page — returns valid pages and skips the broken one", async () => {
+    await writePage(workspaceDir, {
+      slug: "valid-page",
+      frontmatter: { edges: [], ref_files: [], ref_urls: [] },
+      body: "Body of the valid page.\n",
+    });
+
+    // A `.md` file with frontmatter that fails schema validation — `edges`
+    // must be a list of strings, not a single number — so `readPage` throws.
+    const conceptsDir = join(workspaceDir, "memory", "concepts");
+    await mkdir(conceptsDir, { recursive: true });
+    await writeFile(
+      join(conceptsDir, "broken.md"),
+      "---\nedges: 42\n---\nbroken body\n",
+      "utf-8",
+    );
+
+    const handler = findHandler("memory_v2_list_concept_pages");
+    const result = (await handler({
+      body: {},
+    })) as MemoryV2ListConceptPagesResult;
+
+    expect(result.pages).toHaveLength(1);
+    expect(result.pages.map((p) => p.slug)).toEqual(["valid-page"]);
+  });
+});

package/src/runtime/routes/__tests__/stt-routes.test.ts

@@ -100,7 +100,7 @@ describe("stt-routes", () => {
   // -- Route metadata -------------------------------------------------------
 
   test("exports route definitions for stt/providers and stt/transcribe", () => {
-    expect(ROUTES).toHaveLength(2);
+    expect(ROUTES).toHaveLength(3);
 
     const providers = getRoute("stt/providers");
     expect(providers.method).toBe("GET");
@@ -109,6 +109,10 @@ describe("stt-routes", () => {
     const transcribe = getRoute("stt/transcribe");
     expect(transcribe.method).toBe("POST");
     expect(transcribe.policyKey).toBe("stt/transcribe");
+
+    const transcribeFile = getRoute("stt/transcribe-file");
+    expect(transcribeFile.method).toBe("POST");
+    expect(transcribeFile.policyKey).toBe("stt/transcribe-file");
   });
 
   // -- Success path ---------------------------------------------------------

package/src/runtime/routes/__tests__/surface-action-routes.test.ts

@@ -0,0 +1,384 @@
+/**
+ * Tests for surface-action route handlers.
+ *
+ * Focus is the rehydrate-on-miss path: after daemon restart or LRU eviction,
+ * the in-memory conversation map is empty even though the surface still
+ * persists as a `ui_surface` content block in the messages table. The handler
+ * must fall back to a DB scan, then call `getOrCreateConversation` so the
+ * action dispatches against a live conversation with restored `surfaceState`.
+ *
+ * Strategy: mock `conversation-store` and `raw-query` at module boundaries,
+ * import ROUTES afterwards, find each handler by operationId, and exercise.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock state
+// ---------------------------------------------------------------------------
+
+interface StubConversation {
+  id: string;
+  handleSurfaceActionResult?:
+    | { accepted: true; conversationId?: string }
+    | { accepted: false; error: string };
+  handleSurfaceActionThrows?: Error;
+  handleSurfaceUndoCalled?: boolean;
+  handleSurfaceUndoThrows?: Error;
+  surfaceActionCalls: Array<{
+    surfaceId: string;
+    actionId: string;
+    data: unknown;
+  }>;
+}
+
+let memoryById: StubConversation | null = null;
+let memoryBySurface: StubConversation | null = null;
+let rehydrated: StubConversation | null = null;
+let rawGetReturn: { conversation_id: string } | null = null;
+
+const findConvCalls: string[] = [];
+const findBySurfaceCalls: string[] = [];
+const getOrCreateCalls: string[] = [];
+const rawGetCalls: Array<{ sql: string; params: unknown[] }> = [];
+
+mock.module("../../../daemon/conversation-store.js", () => ({
+  findConversation: (id: string) => {
+    findConvCalls.push(id);
+    return memoryById ?? undefined;
+  },
+  findConversationBySurfaceId: (surfaceId: string) => {
+    findBySurfaceCalls.push(surfaceId);
+    return memoryBySurface ?? undefined;
+  },
+  getOrCreateConversation: async (id: string) => {
+    getOrCreateCalls.push(id);
+    if (!rehydrated) {
+      throw new Error(
+        `getOrCreateConversation(${id}) called but no rehydrated stub configured`,
+      );
+    }
+    return rehydrated;
+  },
+}));
+
+mock.module("../../../memory/raw-query.js", () => ({
+  rawGet: (sql: string, ...params: unknown[]) => {
+    rawGetCalls.push({ sql, params });
+    return rawGetReturn;
+  },
+}));
+
+// Defer route import until after mocks are installed.
+const { ROUTES } = await import("../surface-action-routes.js");
+const { NotFoundError } = await import("../errors.js");
+import type { RouteDefinition } from "../types.js";
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = ROUTES.find((r) => r.operationId === operationId);
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+function makeStub(id: string): StubConversation {
+  const stub: StubConversation = {
+    id,
+    handleSurfaceActionResult: { accepted: true },
+    surfaceActionCalls: [],
+  };
+  // Methods reference `stub` so handler invocations land on the same object.
+  Object.assign(stub, {
+    handleSurfaceAction: async (
+      surfaceId: string,
+      actionId: string,
+      data: unknown,
+    ) => {
+      stub.surfaceActionCalls.push({ surfaceId, actionId, data });
+      if (stub.handleSurfaceActionThrows) throw stub.handleSurfaceActionThrows;
+      return stub.handleSurfaceActionResult;
+    },
+    handleSurfaceUndo: (_surfaceId: string) => {
+      stub.handleSurfaceUndoCalled = true;
+      if (stub.handleSurfaceUndoThrows) throw stub.handleSurfaceUndoThrows;
+    },
+  });
+  return stub;
+}
+
+// ---------------------------------------------------------------------------
+// Setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  memoryById = null;
+  memoryBySurface = null;
+  rehydrated = null;
+  rawGetReturn = null;
+  findConvCalls.length = 0;
+  findBySurfaceCalls.length = 0;
+  getOrCreateCalls.length = 0;
+  rawGetCalls.length = 0;
+});
+
+// ---------------------------------------------------------------------------
+// triggerSurfaceAction
+// ---------------------------------------------------------------------------
+
+describe("triggerSurfaceAction handler", () => {
+  test("dispatches against live in-memory conversation when found by surfaceId", async () => {
+    const live = makeStub("conv-live");
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    const result = await handler({
+      body: { surfaceId: "surf-1", actionId: "act-1" },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(findBySurfaceCalls).toEqual(["surf-1"]);
+    expect(findConvCalls).toEqual([]);
+    expect(rawGetCalls).toEqual([]);
+    expect(getOrCreateCalls).toEqual([]);
+    expect(live.surfaceActionCalls).toEqual([
+      { surfaceId: "surf-1", actionId: "act-1", data: undefined },
+    ]);
+  });
+
+  test("uses caller-supplied conversationId for in-memory hit", async () => {
+    const live = makeStub("conv-explicit");
+    memoryById = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: {
+        conversationId: "conv-explicit",
+        surfaceId: "surf-2",
+        actionId: "act-2",
+        data: { foo: "bar" },
+      },
+    });
+
+    expect(findConvCalls).toEqual(["conv-explicit"]);
+    expect(findBySurfaceCalls).toEqual([]);
+    expect(rawGetCalls).toEqual([]);
+    expect(getOrCreateCalls).toEqual([]);
+    expect(live.surfaceActionCalls).toEqual([
+      { surfaceId: "surf-2", actionId: "act-2", data: { foo: "bar" } },
+    ]);
+  });
+
+  test("rehydrates via DB fallback when in-memory lookup misses", async () => {
+    rawGetReturn = { conversation_id: "conv-from-db" };
+    rehydrated = makeStub("conv-from-db");
+
+    const handler = findHandler("triggerSurfaceAction");
+    const result = await handler({
+      body: { surfaceId: "surf-evicted", actionId: "act-3" },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(findBySurfaceCalls).toEqual(["surf-evicted"]);
+    expect(findConvCalls).toEqual([]);
+    expect(rawGetCalls).toHaveLength(1);
+    // SQL must filter the messages table by ui_surface payload pattern.
+    expect(rawGetCalls[0]!.sql).toContain("FROM messages");
+    expect(rawGetCalls[0]!.sql).toContain("LIKE");
+    expect(rawGetCalls[0]!.params).toEqual([
+      `%"surfaceId":"surf-evicted"%`,
+    ]);
+    expect(getOrCreateCalls).toEqual(["conv-from-db"]);
+    expect(rehydrated.surfaceActionCalls).toEqual([
+      { surfaceId: "surf-evicted", actionId: "act-3", data: undefined },
+    ]);
+  });
+
+  test("rehydrates with caller-supplied conversationId after validating DB row", async () => {
+    rawGetReturn = { conversation_id: "conv-caller" };
+    rehydrated = makeStub("conv-caller");
+
+    const handler = findHandler("triggerSurfaceAction");
+    await handler({
+      body: {
+        conversationId: "conv-caller",
+        surfaceId: "surf-caller",
+        actionId: "act-4",
+      },
+    });
+
+    expect(findConvCalls).toEqual(["conv-caller"]);
+    expect(findBySurfaceCalls).toEqual([]);
+    // DB scan validates the surface actually exists before rehydrating.
+    expect(rawGetCalls).toHaveLength(1);
+    expect(getOrCreateCalls).toEqual(["conv-caller"]);
+    expect(rehydrated.surfaceActionCalls).toEqual([
+      { surfaceId: "surf-caller", actionId: "act-4", data: undefined },
+    ]);
+  });
+
+  test("returns 404 when surface is not in memory and not in DB", async () => {
+    const handler = findHandler("triggerSurfaceAction");
+
+    let caught: unknown;
+    try {
+      await handler({
+        body: { surfaceId: "surf-ghost", actionId: "act-5" },
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(NotFoundError);
+    expect(rawGetCalls).toHaveLength(1);
+    // No phantom conversation created.
+    expect(getOrCreateCalls).toEqual([]);
+  });
+
+  test("returns 404 when caller-supplied conversationId has no matching surface in DB", async () => {
+    // rawGetReturn stays null → DB has no row for this surface, so we
+    // refuse to rehydrate even though the caller named a conversation.
+    const handler = findHandler("triggerSurfaceAction");
+
+    let caught: unknown;
+    try {
+      await handler({
+        body: {
+          conversationId: "conv-deleted",
+          surfaceId: "surf-x",
+          actionId: "act-x",
+        },
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(NotFoundError);
+    // Crucially, we did NOT call getOrCreateConversation — the previous
+    // version would have created a phantom empty conversation here.
+    expect(getOrCreateCalls).toEqual([]);
+  });
+
+  test("returns 404 when caller-supplied conversationId mismatches the DB row", async () => {
+    // Surface exists in conv-real, but caller asserts conv-other.
+    rawGetReturn = { conversation_id: "conv-real" };
+    const handler = findHandler("triggerSurfaceAction");
+
+    let caught: unknown;
+    try {
+      await handler({
+        body: {
+          conversationId: "conv-other",
+          surfaceId: "surf-shared",
+          actionId: "act-x",
+        },
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(NotFoundError);
+    expect(getOrCreateCalls).toEqual([]);
+  });
+
+  test("escapes LIKE wildcards in surfaceId", async () => {
+    // A request with `surfaceId: "%"` must not match unrelated rows. We
+    // assert the SQL uses ESCAPE and the bound parameter has the wildcard
+    // backslash-escaped.
+    const handler = findHandler("triggerSurfaceAction");
+
+    try {
+      await handler({
+        body: { surfaceId: "%", actionId: "act-evil" },
+      });
+    } catch {
+      /* expected NotFoundError, we only care about the SQL */
+    }
+
+    expect(rawGetCalls).toHaveLength(1);
+    expect(rawGetCalls[0]!.sql).toContain("ESCAPE");
+    expect(rawGetCalls[0]!.params).toEqual([`%"surfaceId":"\\%"%`]);
+  });
+
+  test("propagates accepted=false rejection as BadRequestError", async () => {
+    const live = makeStub("conv-reject");
+    live.handleSurfaceActionResult = {
+      accepted: false,
+      error: "surface already completed",
+    };
+    memoryBySurface = live;
+
+    const handler = findHandler("triggerSurfaceAction");
+
+    let caught: unknown;
+    try {
+      await handler({
+        body: { surfaceId: "surf-done", actionId: "act-y" },
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    // BadRequestError is a RouteError — verify the error message bubbled.
+    expect(caught).toBeDefined();
+    expect((caught as Error).message).toContain("surface already completed");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// undoSurfaceAction
+// ---------------------------------------------------------------------------
+
+describe("undoSurfaceAction handler", () => {
+  test("dispatches against live in-memory conversation", async () => {
+    const live = makeStub("conv-undo-live");
+    memoryById = live;
+
+    const handler = findHandler("undoSurfaceAction");
+    const result = await handler({
+      body: { conversationId: "conv-undo-live" },
+      pathParams: { id: "surf-undo-1" },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(findConvCalls).toEqual(["conv-undo-live"]);
+    expect(rawGetCalls).toEqual([]);
+    expect(getOrCreateCalls).toEqual([]);
+    expect(live.handleSurfaceUndoCalled).toBe(true);
+  });
+
+  test("rehydrates via DB fallback when conversation evicted", async () => {
+    rawGetReturn = { conversation_id: "conv-undo-from-db" };
+    rehydrated = makeStub("conv-undo-from-db");
+
+    const handler = findHandler("undoSurfaceAction");
+    const result = await handler({
+      body: {},
+      pathParams: { id: "surf-undo-evicted" },
+    });
+
+    expect(result).toEqual({ ok: true });
+    expect(findBySurfaceCalls).toEqual(["surf-undo-evicted"]);
+    expect(rawGetCalls).toHaveLength(1);
+    expect(rawGetCalls[0]!.params).toEqual([
+      `%"surfaceId":"surf-undo-evicted"%`,
+    ]);
+    expect(getOrCreateCalls).toEqual(["conv-undo-from-db"]);
+    expect(rehydrated.handleSurfaceUndoCalled).toBe(true);
+  });
+
+  test("returns 404 when surface cannot be located", async () => {
+    const handler = findHandler("undoSurfaceAction");
+
+    let caught: unknown;
+    try {
+      await handler({
+        body: {},
+        pathParams: { id: "surf-undo-ghost" },
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(NotFoundError);
+    expect(getOrCreateCalls).toEqual([]);
+  });
+});

package/src/runtime/routes/__tests__/tts-routes.test.ts

@@ -164,8 +164,8 @@ afterEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("tts-routes", () => {
-  test("exports route definitions for messages/:messageId/tts and tts/synthesize", () => {
-    expect(ROUTES).toHaveLength(2);
+  test("exports route definitions for messages/:messageId/tts, tts/synthesize, and tts/synthesize-cli", () => {
+    expect(ROUTES).toHaveLength(3);
 
     const msgTts = getRoute("messages/:messageId/tts");
     expect(msgTts.method).toBe("POST");
@@ -174,6 +174,10 @@ describe("tts-routes", () => {
     const synthesize = getRoute("tts/synthesize");
     expect(synthesize.method).toBe("POST");
     expect(synthesize.policyKey).toBe("tts/synthesize");
+
+    const synthesizeCli = getRoute("tts/synthesize-cli");
+    expect(synthesizeCli.method).toBe("POST");
+    expect(synthesizeCli.policyKey).toBe("tts/synthesize-cli");
   });
 
   // -- Feature flag gating --------------------------------------------------

package/src/runtime/routes/acp-routes.ts

@@ -56,9 +56,7 @@ async function spawnSession({ body }: RouteHandlerArgs) {
   const cwd = (body?.cwd as string | undefined) ?? process.cwd();
 
   if (!agent || !task || !conversationId) {
-    throw new BadRequestError(
-      "agent, task, and conversationId are required",
-    );
+    throw new BadRequestError("agent, task, and conversationId are required");
   }
 
   const resolved = resolveAcpAgent(agent);
@@ -182,10 +180,7 @@ function deleteSession({ pathParams }: RouteHandlerArgs) {
     // Not in memory — fall through to the (idempotent) DB delete.
   }
 
-  getDb()
-    .delete(acpSessionHistory)
-    .where(eq(acpSessionHistory.id, id))
-    .run();
+  getDb().delete(acpSessionHistory).where(eq(acpSessionHistory.id, id)).run();
   const deleted = rawChanges() > 0;
   log.info({ acpSessionId: id, deleted }, "ACP session history delete");
   return { deleted };
@@ -376,7 +371,14 @@ function listMergedSessions(opts: {
         eq(acpSessionHistory.parentConversationId, opts.conversationId),
       )
     : baseQuery;
-  const historyRows = filtered.orderBy(desc(acpSessionHistory.startedAt)).all();
+  // Fetch only enough rows to fill the requested page after merging with
+  // in-memory sessions. In-memory entries take precedence on id collision,
+  // so we pad by inMemory.length to guarantee we still surface `limit`
+  // distinct rows even when every in-memory session shadows a DB row.
+  const historyRows = filtered
+    .orderBy(desc(acpSessionHistory.startedAt))
+    .limit(opts.limit + inMemory.length)
+    .all();
 
   for (const row of historyRows) {
     if (merged.has(row.id)) continue;