@vellumai/assistant 0.7.3 → 0.8.1

package/src/memory/v2/__tests__/migration.test.ts

@@ -403,7 +403,11 @@ describe("synthesizeConceptPage", () => {
     );
     const page = await synthesizeConceptPage(cluster, null, provider);
     expect(page.slug).toBe("alice-ides");
-    expect(page.frontmatter).toEqual({ edges: [], ref_files: [] });
+    expect(page.frontmatter).toEqual({
+      edges: [],
+      ref_files: [],
+      ref_urls: [],
+    });
     expect(page.body).toContain("VS Code");
     expect(page.body.endsWith("\n")).toBe(true);
   });
@@ -625,7 +629,7 @@ describe("collapseEdges", () => {
 
 describe("enqueueEmbeds", () => {
   test("enqueues one embed_concept_page job per slug", () => {
-    expect(enqueueEmbeds(["alice", "bob", "carol"])).toBe(3);
+    expect(enqueueEmbeds(["alice", "bob", "carol"], database)).toBe(3);
     expect(enqueuedJobs).toEqual([
       { type: "embed_concept_page", payload: { slug: "alice" } },
       { type: "embed_concept_page", payload: { slug: "bob" } },
@@ -634,7 +638,7 @@ describe("enqueueEmbeds", () => {
   });
 
   test("empty list is a no-op", () => {
-    expect(enqueueEmbeds([])).toBe(0);
+    expect(enqueueEmbeds([], database)).toBe(0);
     expect(enqueuedJobs).toEqual([]);
   });
 });

package/src/memory/v2/__tests__/page-index.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for `memory/v2/page-index.ts` — the router-prompt page index built
+ * from concept pages plus seeded skill entries.
+ *
+ * Tests live in temp workspaces (`mkdtemp`) and never touch `~/.vellum/`. The
+ * skill-store module is mocked so `listSkillEntries()` returns deterministic
+ * fixtures, and `page-store.js` is wrapped so we can simulate read failures
+ * without breaking writes.
+ */
+
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { makeMockLogger } from "../../../__tests__/helpers/mock-logger.js";
+import type { ConceptPage, SkillEntry } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Mocks — programmable skill list, programmable readPage failure set,
+// recursive no-op logger. Mocks are installed BEFORE any imports of the
+// module under test so the page-index module observes them at load time.
+// ---------------------------------------------------------------------------
+
+const skillState: { entries: SkillEntry[] } = { entries: [] };
+const failingSlugs = new Set<string>();
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+mock.module("../skill-store.js", () => ({
+  SKILL_SLUG_PREFIX: "skills/",
+  listSkillEntries: () => skillState.entries,
+}));
+
+// Wrap page-store so we can simulate read failures via `failingSlugs`.
+// Re-export every other binding identity-style so writes still work.
+//
+// Capture each real export into a local const BEFORE installing the mock —
+// module namespaces hold live bindings, so a post-mock dereference of
+// `realPageStore.readPage` would resolve to the mocked function and recurse
+// infinitely.
+const realPageStore = await import("../page-store.js");
+const realReadPage = realPageStore.readPage;
+mock.module("../page-store.js", () => ({
+  ...realPageStore,
+  readPage: async (workspaceDir: string, slug: string) => {
+    if (failingSlugs.has(slug)) {
+      throw new Error(`simulated read failure for ${slug}`);
+    }
+    return realReadPage(workspaceDir, slug);
+  },
+}));
+
+const { getPageIndex, invalidatePageIndex } = await import("../page-index.js");
+const { writePage } = await import("../page-store.js");
+const { invalidateEdgeIndex } = await import("../edge-index.js");
+
+let workspaceDir: string;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-memory-v2-page-index-"));
+  skillState.entries = [];
+  failingSlugs.clear();
+});
+
+afterEach(() => {
+  invalidatePageIndex();
+  invalidateEdgeIndex();
+  if (existsSync(workspaceDir)) {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  }
+});
+
+function makePage(
+  slug: string,
+  opts: { edges?: string[]; summary?: string; body?: string } = {},
+): ConceptPage {
+  return {
+    slug,
+    frontmatter: {
+      edges: opts.edges ?? [],
+      ref_files: [],
+      ref_urls: [],
+      ...(opts.summary !== undefined ? { summary: opts.summary } : {}),
+    },
+    body: opts.body ?? "",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Build & cache
+// ---------------------------------------------------------------------------
+
+describe("getPageIndex", () => {
+  test("returns an empty index when there are no pages and no skills", async () => {
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.entries).toEqual([]);
+    expect(idx.bySlug.size).toBe(0);
+    expect(idx.byId.size).toBe(0);
+    expect(idx.rendered).toBe("");
+  });
+
+  test("caches the result so repeat calls reuse the prior build", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "First" }));
+
+    const first = await getPageIndex(workspaceDir);
+    // Mutate disk after the first read WITHOUT going through `writePage`,
+    // which would invalidate the page-index cache by design. The raw
+    // filesystem write simulates an out-of-band file appearing — without
+    // the cache the second call would observe it and return a different
+    // object.
+    writeFileSync(
+      join(workspaceDir, "memory", "concepts", "bob.md"),
+      "---\nedges: []\nref_files: []\nref_urls: []\nsummary: Second\n---\n",
+      "utf-8",
+    );
+
+    const second = await getPageIndex(workspaceDir);
+    expect(second).toBe(first);
+    expect(second.entries.map((e) => e.slug)).toEqual(["alice"]);
+  });
+
+  test("writePage invalidates the cache so the next call sees the new page", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "First" }));
+    const before = await getPageIndex(workspaceDir);
+
+    // `writePage` calls `invalidatePageIndex(workspaceDir)` as a side
+    // effect — verify that contract here so the cache-hit test above
+    // can't accidentally pass because writePage stopped invalidating.
+    await writePage(workspaceDir, makePage("bob", { summary: "Second" }));
+
+    const after = await getPageIndex(workspaceDir);
+    expect(after).not.toBe(before);
+    expect(after.entries.map((e) => e.slug)).toEqual(["alice", "bob"]);
+  });
+
+  test("invalidatePageIndex(workspaceDir) forces a rebuild on the next call", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "First" }));
+    const before = await getPageIndex(workspaceDir);
+
+    invalidatePageIndex(workspaceDir);
+    await writePage(workspaceDir, makePage("bob", { summary: "Second" }));
+
+    const after = await getPageIndex(workspaceDir);
+    expect(after).not.toBe(before);
+    expect(after.entries.map((e) => e.slug)).toEqual(["alice", "bob"]);
+  });
+
+  test("invalidatePageIndex() with no arg clears any cached workspace", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "First" }));
+    const before = await getPageIndex(workspaceDir);
+    invalidatePageIndex();
+    const after = await getPageIndex(workspaceDir);
+    expect(after).not.toBe(before);
+  });
+
+  test("sorts entries by slug ASCII deterministically across rebuilds", async () => {
+    await writePage(workspaceDir, makePage("zulu", { summary: "Z" }));
+    await writePage(workspaceDir, makePage("alpha", { summary: "A" }));
+    await writePage(workspaceDir, makePage("mike", { summary: "M" }));
+
+    const first = await getPageIndex(workspaceDir);
+    invalidatePageIndex();
+    const second = await getPageIndex(workspaceDir);
+
+    expect(first.entries.map((e) => e.slug)).toEqual(["alpha", "mike", "zulu"]);
+    expect(first.entries).toEqual(second.entries);
+  });
+
+  test("assigns dense 1-based IDs in slug order", async () => {
+    await writePage(workspaceDir, makePage("bravo", { summary: "B" }));
+    await writePage(workspaceDir, makePage("alpha", { summary: "A" }));
+    await writePage(workspaceDir, makePage("charlie", { summary: "C" }));
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.entries.map((e) => e.id)).toEqual([1, 2, 3]);
+    expect(idx.entries.map((e) => e.slug)).toEqual([
+      "alpha",
+      "bravo",
+      "charlie",
+    ]);
+    expect(idx.byId.get(1)?.slug).toBe("alpha");
+    expect(idx.bySlug.get("charlie")?.id).toBe(3);
+  });
+
+  test("drops pages whose read fails and continues the build", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "Alice" }));
+    await writePage(workspaceDir, makePage("bob", { summary: "Bob" }));
+    await writePage(workspaceDir, makePage("carol", { summary: "Carol" }));
+
+    failingSlugs.add("bob");
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.entries.map((e) => e.slug)).toEqual(["alice", "carol"]);
+    // IDs remain dense — the dropped page does not leave a hole.
+    expect(idx.entries.map((e) => e.id)).toEqual([1, 2]);
+  });
+
+  test("integrates seeded skill entries under the skills/ slug prefix", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "Alice" }));
+    skillState.entries = [
+      { id: "browser", content: "Drive a browser." },
+      { id: "calendar", content: "Schedule meetings." },
+    ];
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.entries.map((e) => e.slug)).toEqual([
+      "alice",
+      "skills/browser",
+      "skills/calendar",
+    ]);
+    expect(idx.bySlug.get("skills/browser")?.summary).toBe("Drive a browser.");
+    // Skill entries always carry an empty edge list.
+    expect(idx.bySlug.get("skills/browser")?.edges).toEqual([]);
+  });
+
+  test("resolves outgoing edges to numeric IDs and drops missing targets", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", { summary: "A", edges: ["bob", "ghost"] }),
+    );
+    await writePage(workspaceDir, makePage("bob", { summary: "B" }));
+
+    const idx = await getPageIndex(workspaceDir);
+    const alice = idx.bySlug.get("alice")!;
+    const bob = idx.bySlug.get("bob")!;
+    expect(alice.edges).toEqual([bob.id]);
+  });
+
+  test("falls back to body when frontmatter.summary is absent", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", { body: "  Body fallback content.  " }),
+    );
+
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("alice")?.summary).toBe("Body fallback content.");
+  });
+
+  test("truncates summary to 200 characters", async () => {
+    const long = "x".repeat(500);
+    await writePage(workspaceDir, makePage("alice", { summary: long }));
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.bySlug.get("alice")?.summary.length).toBe(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+describe("rendered prompt block", () => {
+  test("renders [id] slug — summary lines with edges parenthetical when present", async () => {
+    await writePage(
+      workspaceDir,
+      makePage("alice", { summary: "A page", edges: ["bob"] }),
+    );
+    await writePage(workspaceDir, makePage("bob", { summary: "B page" }));
+
+    const idx = await getPageIndex(workspaceDir);
+    const alice = idx.bySlug.get("alice")!;
+    const bob = idx.bySlug.get("bob")!;
+
+    const expected =
+      `[${alice.id}] alice — A page (edges: ${bob.id})\n` +
+      `[${bob.id}] bob — B page\n`;
+    expect(idx.rendered).toBe(expected);
+  });
+
+  test("omits the parenthetical for entries with no outgoing edges", async () => {
+    await writePage(workspaceDir, makePage("alice", { summary: "A page" }));
+    const idx = await getPageIndex(workspaceDir);
+    expect(idx.rendered).toBe("[1] alice — A page\n");
+  });
+});

package/src/memory/v2/__tests__/page-store.test.ts

@@ -62,7 +62,7 @@ afterEach(() => {
 function makePage(overrides: Partial<ConceptPage> = {}): ConceptPage {
   return {
     slug: "alice-preferences",
-    frontmatter: { edges: ["bob-handoff"], ref_files: [] },
+    frontmatter: { edges: ["bob-handoff"], ref_files: [], ref_urls: [] },
     body: "Alice prefers VS Code over Vim.\nShe ships at end of day.\n",
     ...overrides,
   };
@@ -238,6 +238,19 @@ describe("writePage + readPage round-trip", () => {
     expect(read!.body).toBe(body);
   });
 
+  test("readPage throws on unknown frontmatter keys instead of silently dropping them", async () => {
+    const slug = "extra-keys";
+    const raw =
+      "---\nedges: []\nref_files: []\nunknown_field: oops\n---\nbody\n";
+    writeFileSync(
+      join(workspaceDir, "memory", "concepts", `${slug}.md`),
+      raw,
+      "utf-8",
+    );
+
+    await expect(readPage(workspaceDir, slug)).rejects.toThrow();
+  });
+
   test("writePage overwrites an existing page", async () => {
     const page1 = makePage({ body: "first version\n" });
     await writePage(workspaceDir, page1);

package/src/memory/v2/__tests__/prompts-router.test.ts

@@ -0,0 +1,257 @@
+/**
+ * Tests for `assistant/src/memory/v2/prompts/router.ts` —
+ * `renderRouterPrompt` (placeholder substitution in the bundled body) and
+ * `resolveRouterPrompt` (file-override path with fallback).
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { renderRouterPrompt, resolveRouterPrompt } from "../prompts/router.js";
+
+const SAMPLE_INDEX = `[1] morning-routine — coffee, walk, journal (edges: 2)
+[2] journal-style — terse, dated, no fluff (edges: 1)
+[3] taxes-2025 — Q1 estimate due April 15 (edges: )`;
+
+describe("renderRouterPrompt — substitution", () => {
+  test("replaces all three placeholders with the supplied values", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).not.toContain("{{ASSISTANT_NAME}}");
+    expect(out).not.toContain("{{USER_NAME}}");
+    expect(out).not.toContain("{{PAGE_INDEX}}");
+    expect(out).toContain("Aria");
+    expect(out).toContain("Alice");
+    expect(out).toContain(SAMPLE_INDEX);
+  });
+
+  test("substitutes every occurrence of the assistant name placeholder", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    // Body references the assistant name in multiple sentences; ensure none
+    // of them leak the raw placeholder.
+    const matches = out.match(/Aria/g) ?? [];
+    expect(matches.length).toBeGreaterThanOrEqual(2);
+  });
+});
+
+describe("renderRouterPrompt — neutral fallbacks", () => {
+  test("falls back to 'the assistant' when assistantName is null", () => {
+    const out = renderRouterPrompt({
+      assistantName: null,
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain("the assistant");
+    expect(out).not.toContain("{{ASSISTANT_NAME}}");
+  });
+
+  test("falls back to 'the user' when userName is null", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: null,
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain("the user");
+    expect(out).not.toContain("{{USER_NAME}}");
+  });
+
+  test("uses both fallbacks when both names are null", () => {
+    const out = renderRouterPrompt({
+      assistantName: null,
+      userName: null,
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain("the assistant");
+    expect(out).toContain("the user");
+  });
+
+  test("falls back when names are whitespace-only strings", () => {
+    const out = renderRouterPrompt({
+      assistantName: "   ",
+      userName: "\t\n",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain("the assistant");
+    expect(out).toContain("the user");
+  });
+});
+
+describe("renderRouterPrompt — page index handling", () => {
+  test("substitutes an empty pageIndexBlock cleanly without double-newline artifacts", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: "",
+    });
+
+    expect(out).not.toContain("{{PAGE_INDEX}}");
+    // The header should still be present and not followed by a stray
+    // triple-newline run from collapsing the empty block.
+    expect(out).toContain("# Concept Page Index");
+    expect(out).not.toMatch(/\n\n\n/);
+    // Output should end at the header section without trailing whitespace.
+    expect(out.endsWith("# Concept Page Index\n\n")).toBe(true);
+  });
+
+  test("preserves the page index body verbatim, including edges syntax", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain(
+      "[1] morning-routine — coffee, walk, journal (edges: 2)",
+    );
+    expect(out).toContain(
+      "[3] taxes-2025 — Q1 estimate due April 15 (edges: )",
+    );
+  });
+});
+
+describe("renderRouterPrompt — determinism & snapshot stability", () => {
+  test("returns the same string for the same inputs", () => {
+    const opts = {
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    };
+    expect(renderRouterPrompt(opts)).toBe(renderRouterPrompt(opts));
+  });
+
+  test("snapshot of fixed inputs", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toMatchSnapshot();
+  });
+});
+
+describe("renderRouterPrompt — content expectations", () => {
+  test("references the select_pages_to_inject tool name", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain("select_pages_to_inject");
+  });
+
+  test("describes the already_injected_ids and now markers", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out).toContain("<already_injected_ids>");
+    expect(out).toContain("<now>");
+  });
+
+  test("biases toward inclusion when in doubt", () => {
+    const out = renderRouterPrompt({
+      assistantName: "Aria",
+      userName: "Alice",
+      pageIndexBlock: SAMPLE_INDEX,
+    });
+
+    expect(out.toLowerCase()).toContain("lean toward inclusion");
+    expect(out.toLowerCase()).toContain("missing a relevant page");
+  });
+});
+
+describe("resolveRouterPrompt — override path", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "vellum-router-prompt-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const STD_OPTS = {
+    assistantName: "Aria",
+    userName: "Alice",
+    pageIndexBlock: SAMPLE_INDEX,
+  };
+
+  test("null overridePath returns the bundled prompt verbatim", () => {
+    expect(resolveRouterPrompt(null, STD_OPTS)).toEqual(
+      renderRouterPrompt(STD_OPTS),
+    );
+  });
+
+  test("loads override and substitutes placeholders", () => {
+    const overridePath = join(tmpDir, "router.md");
+    writeFileSync(
+      overridePath,
+      "Hi {{ASSISTANT_NAME}}, you are routing for {{USER_NAME}}.\n\n{{PAGE_INDEX}}",
+      "utf-8",
+    );
+
+    const out = resolveRouterPrompt(overridePath, STD_OPTS);
+    expect(out).toContain("Hi Aria, you are routing for Alice.");
+    expect(out).toContain(SAMPLE_INDEX);
+    expect(out).not.toContain("{{ASSISTANT_NAME}}");
+    expect(out).not.toContain("{{PAGE_INDEX}}");
+  });
+
+  test("missing override file falls back to bundled prompt", () => {
+    const overridePath = join(tmpDir, "does-not-exist.md");
+    expect(resolveRouterPrompt(overridePath, STD_OPTS)).toEqual(
+      renderRouterPrompt(STD_OPTS),
+    );
+  });
+
+  test("empty override file falls back to bundled prompt", () => {
+    const overridePath = join(tmpDir, "empty.md");
+    writeFileSync(overridePath, "   \n\t\n", "utf-8");
+    expect(resolveRouterPrompt(overridePath, STD_OPTS)).toEqual(
+      renderRouterPrompt(STD_OPTS),
+    );
+  });
+
+  test("override that is a directory falls back to bundled prompt", () => {
+    // Pass the temp directory itself as the override path — lstat sees a
+    // directory, not a regular file, so the loader bails to bundled.
+    expect(resolveRouterPrompt(tmpDir, STD_OPTS)).toEqual(
+      renderRouterPrompt(STD_OPTS),
+    );
+  });
+
+  test("override applies neutral fallbacks for missing names", () => {
+    const overridePath = join(tmpDir, "neutral.md");
+    writeFileSync(
+      overridePath,
+      "Hi {{ASSISTANT_NAME}}, routing for {{USER_NAME}}.",
+      "utf-8",
+    );
+
+    const out = resolveRouterPrompt(overridePath, {
+      assistantName: null,
+      userName: null,
+      pageIndexBlock: "",
+    });
+    expect(out).toBe("Hi the assistant, routing for the user.");
+  });
+});