@vellumai/assistant 0.8.6 → 0.8.7

package/src/memory/v3/__tests__/reconcile.test.ts

@@ -0,0 +1,274 @@
+import { mkdir, mkdtemp, readFile, rm, 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 type { Provider } from "../../../providers/types.js";
+import { readPage, writePage } from "../../v2/page-store.js";
+import { type LeafRef, reconcileTree } from "../reconcile.js";
+
+/**
+ * A canned provider whose `assign_leaves` tool-use response is computed from
+ * the user message (the page content) via `idsForMessage`. This lets a test
+ * deterministically re-home each page onto specific surviving leaves without a
+ * real LLM. The leaf index in the system prompt is sorted by path; tests pass
+ * the 1-based id of the target leaf in that sorted order.
+ */
+function stubProvider(
+  idsForMessage: (message: string, systemPrompt: string) => number[],
+): Provider {
+  return {
+    name: "stub",
+    async sendMessage(messages: unknown, opts: unknown) {
+      const msg = messages as Array<{
+        content: Array<{ type: string; text?: string }>;
+      }>;
+      const text = msg[0]?.content?.map((c) => c.text ?? "").join("") ?? "";
+      const systemPrompt =
+        (opts as { systemPrompt?: string }).systemPrompt ?? "";
+      const ids = idsForMessage(text, systemPrompt);
+      return {
+        id: "msg_stub",
+        role: "assistant",
+        model: "stub-model",
+        stopReason: "tool_use",
+        content: [
+          {
+            type: "tool_use",
+            id: "tool_1",
+            name: "assign_leaves",
+            input: { ids },
+          },
+        ],
+      };
+    },
+  } as unknown as Provider;
+}
+
+let workspaceDir: string;
+let dataDir: string;
+
+beforeEach(async () => {
+  workspaceDir = await mkdtemp(join(tmpdir(), "reconcile-ws-"));
+  dataDir = await mkdtemp(join(tmpdir(), "reconcile-data-"));
+});
+
+afterEach(async () => {
+  await rm(workspaceDir, { recursive: true, force: true });
+  await rm(dataDir, { recursive: true, force: true });
+  await rm(join(dataDir, "..", "v3-snapshots"), {
+    recursive: true,
+    force: true,
+  }).catch(() => {});
+});
+
+/** Write a leaf `.md` with `{path, in_core, id}` frontmatter. */
+async function writeLeaf(
+  path: string,
+  opts: { id?: string; inCore?: boolean; body?: string } = {},
+): Promise<void> {
+  const full = join(dataDir, "leaves", `${path}.md`);
+  await mkdir(join(full, ".."), { recursive: true });
+  const lines = [`path: ${path}`, `in_core: ${opts.inCore ?? false}`];
+  if (opts.id) lines.push(`id: ${opts.id}`);
+  await writeFile(
+    full,
+    `---\n${lines.join("\n")}\n---\n${opts.body ?? `Leaf ${path}.`}\n`,
+  );
+}
+
+async function writeCore(alwaysOn: string[]): Promise<void> {
+  await writeFile(join(dataDir, "core.json"), JSON.stringify({ alwaysOn }));
+}
+
+/**
+ * `loadLeafTree` (used by the re-homing path) reads `assignments.json`
+ * unconditionally, so seed an empty one. Page→leaf membership comes from page
+ * frontmatter, not this file.
+ */
+async function seedAssignments(): Promise<void> {
+  await writeFile(join(dataDir, "assignments.json"), "{}");
+}
+
+async function writePageWithLeaves(
+  slug: string,
+  leaves: string[],
+): Promise<void> {
+  await writePage(workspaceDir, {
+    slug,
+    frontmatter: { edges: [], ref_files: [], ref_urls: [], leaves },
+    body: `Body of ${slug}.`,
+  });
+}
+
+async function pageLeaves(slug: string): Promise<string[]> {
+  const page = await readPage(workspaceDir, slug);
+  return page?.frontmatter.leaves ?? [];
+}
+
+async function coreOf(): Promise<string[]> {
+  const raw = await readFile(join(dataDir, "core.json"), "utf8");
+  return (JSON.parse(raw) as { alwaysOn: string[] }).alwaysOn;
+}
+
+describe("reconcileTree", () => {
+  test("rename preserves assignments (refs rewritten old → new)", async () => {
+    // Current tree: the leaf moved from domain-a/topic-x → domain-b/topic-x,
+    // keeping its stable id.
+    await writeLeaf("domain-b/topic-x", { id: "leaf-x" });
+    await writeCore(["domain-a/topic-x"]);
+    await writePageWithLeaves("page-a", ["domain-a/topic-x"]);
+
+    const prev: LeafRef[] = [{ id: "leaf-x", path: "domain-a/topic-x" }];
+    const result = await reconcileTree({
+      prevLeaves: prev,
+      dataDir,
+      workspaceDir,
+    });
+
+    expect(await pageLeaves("page-a")).toEqual(["domain-b/topic-x"]);
+    expect(await coreOf()).toEqual(["domain-b/topic-x"]);
+    expect(result.renames).toEqual([
+      {
+        id: "leaf-x",
+        oldPath: "domain-a/topic-x",
+        newPath: "domain-b/topic-x",
+      },
+    ]);
+    expect(result.idToNewPath.get("leaf-x")).toBe("domain-b/topic-x");
+  });
+
+  test("delete re-homes members with no orphan", async () => {
+    // leaf-x is deleted; leaf-y survives. page-a was only on leaf-x.
+    await writeLeaf("domain-a/topic-y", { id: "leaf-y" });
+    await writeCore([]);
+    await seedAssignments();
+    await writePageWithLeaves("page-a", ["domain-a/topic-x"]);
+
+    // Surviving leaf is sorted index 1 (only leaf in tree).
+    const provider = stubProvider(() => [1]);
+
+    const prev: LeafRef[] = [
+      { id: "leaf-x", path: "domain-a/topic-x" },
+      { id: "leaf-y", path: "domain-a/topic-y" },
+    ];
+    const result = await reconcileTree({
+      prevLeaves: prev,
+      dataDir,
+      workspaceDir,
+      provider,
+    });
+
+    const after = await pageLeaves("page-a");
+    // No orphan: at least one surviving leaf, and the dead path is gone.
+    expect(after.length).toBeGreaterThanOrEqual(1);
+    expect(after).not.toContain("domain-a/topic-x");
+    expect(after).toContain("domain-a/topic-y");
+    expect(result.deleted).toEqual(["domain-a/topic-x"]);
+  });
+
+  test("split distributes members across toPaths", async () => {
+    // leaf-x splits into leaf-x1 (domain-a/x1) and leaf-x2 (domain-a/x2).
+    await writeLeaf("domain-a/x1", { id: "leaf-x1" });
+    await writeLeaf("domain-a/x2", { id: "leaf-x2" });
+    // A third surviving leaf NOT in the split target set — members must not
+    // land here.
+    await writeLeaf("domain-b/other", { id: "leaf-other" });
+    await writeCore([]);
+    await seedAssignments();
+    await writePageWithLeaves("page-a", ["domain-a/topic-x"]);
+    await writePageWithLeaves("page-b", ["domain-a/topic-x"]);
+
+    // Restricted tree (split.toPaths) sorts as [domain-a/x1, domain-a/x2].
+    // page-a → x1 (id 1), page-b → x2 (id 2).
+    const provider = stubProvider((message) =>
+      message.includes("page-a") ? [1] : [2],
+    );
+
+    const prev: LeafRef[] = [{ id: "leaf-x", path: "domain-a/topic-x" }];
+    await reconcileTree({
+      prevLeaves: prev,
+      dataDir,
+      workspaceDir,
+      provider,
+      splits: [{ fromId: "leaf-x", toPaths: ["domain-a/x1", "domain-a/x2"] }],
+    });
+
+    expect(await pageLeaves("page-a")).toEqual(["domain-a/x1"]);
+    expect(await pageLeaves("page-b")).toEqual(["domain-a/x2"]);
+    // Neither page landed on the off-target leaf.
+    expect(await pageLeaves("page-a")).not.toContain("domain-b/other");
+    expect(await pageLeaves("page-b")).not.toContain("domain-b/other");
+  });
+
+  test("dangling core entry is pruned", async () => {
+    await writeLeaf("domain-a/topic-x", { id: "leaf-x" });
+    // core.json points at a leaf that no longer exists in the tree.
+    await writeCore(["domain-a/topic-x", "domain-a/gone"]);
+    await writePageWithLeaves("page-a", ["domain-a/topic-x"]);
+
+    // No prev entry for the gone leaf and no page references it, so reconcile
+    // succeeds and prunes the stale core entry.
+    const prev: LeafRef[] = [{ id: "leaf-x", path: "domain-a/topic-x" }];
+    const result = await reconcileTree({
+      prevLeaves: prev,
+      dataDir,
+      workspaceDir,
+    });
+
+    expect(await coreOf()).toEqual(["domain-a/topic-x"]);
+    expect(result.prunedCore).toEqual(["domain-a/gone"]);
+  });
+
+  test("out-of-band dangling page ref converges (prune pass)", async () => {
+    // The current tree has only leaf-x. page-a references leaf-x (fine) PLUS a
+    // residual leaf path that exists in NEITHER prev nor current — an out-of-band
+    // ref a maintainer left when deleting a leaf file without a `prevLeaves`
+    // entry. v1 reconcile is a convergence/prune pass: it drops the dangling ref
+    // (the page keeps its surviving leaf, so no re-home is needed) instead of
+    // failing closed.
+    await writeLeaf("domain-a/topic-x", { id: "leaf-x" });
+    await writeCore(["domain-a/topic-x"]);
+    await seedAssignments();
+    await writePageWithLeaves("page-a", [
+      "domain-a/topic-x",
+      "domain-a/residual",
+    ]);
+
+    const prev: LeafRef[] = [{ id: "leaf-x", path: "domain-a/topic-x" }];
+    const result = await reconcileTree({
+      prevLeaves: prev,
+      dataDir,
+      workspaceDir,
+    });
+
+    // Converged: the dangling residual ref is gone; the surviving leaf remains.
+    expect(await pageLeaves("page-a")).toEqual(["domain-a/topic-x"]);
+    expect(await coreOf()).toEqual(["domain-a/topic-x"]);
+    // The out-of-band drop is not a reconciler-tracked delete (no prev entry),
+    // so it is not reported in `deleted`.
+    expect(result.deleted).toEqual([]);
+  });
+
+  test("page whose ONLY leaf dangles out-of-band is re-homed, not orphaned", async () => {
+    // page-a's sole leaf was deleted on disk with no `prevLeaves` entry. The
+    // convergence pass must re-home it onto a surviving leaf before dropping the
+    // dead ref, so the page is never left with zero leaves.
+    await writeLeaf("domain-a/topic-x", { id: "leaf-x" });
+    await writeCore([]);
+    await seedAssignments();
+    // page-a points only at a leaf absent from the tree (out-of-band delete).
+    await writePageWithLeaves("page-a", ["domain-a/gone"]);
+
+    // Only surviving leaf is sorted index 1 → re-home target.
+    const provider = stubProvider(() => [1]);
+
+    const prev: LeafRef[] = [{ id: "leaf-x", path: "domain-a/topic-x" }];
+    await reconcileTree({ prevLeaves: prev, dataDir, workspaceDir, provider });
+
+    const after = await pageLeaves("page-a");
+    expect(after).not.toContain("domain-a/gone"); // dangling ref dropped
+    expect(after).toEqual(["domain-a/topic-x"]); // re-homed onto the survivor
+    expect(after.length).toBeGreaterThanOrEqual(1); // never orphaned
+  });
+});

package/src/memory/v3/__tests__/render-injection.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+
+import { wrapMemoryBlock } from "../../memory-marker.js";
+import { renderMemoryBlock } from "../render-injection.js";
+import { Slug } from "../types.js";
+
+const resolver =
+  (pages: Record<Slug, string>) =>
+  async (slug: Slug): Promise<string> =>
+    pages[slug] ?? "";
+
+describe("renderMemoryBlock", () => {
+  test("wraps the selection in a single <memory> block, in order", async () => {
+    const pages: Record<Slug, string> = {
+      "page-a": "alpha body",
+      "page-b": "beta body",
+    };
+
+    const block = await renderMemoryBlock(
+      ["page-a", "page-b"],
+      resolver(pages),
+    );
+
+    expect(block).toBe("<memory>\nalpha body\nbeta body\n</memory>");
+  });
+
+  test("empty selection renders the empty string", async () => {
+    const block = await renderMemoryBlock([], async () => "unused");
+    expect(block).toBe("");
+  });
+
+  test("preserves input order deterministically", async () => {
+    const pages: Record<Slug, string> = {
+      "page-a": "A",
+      "page-b": "B",
+      "page-c": "C",
+    };
+
+    const forward = await renderMemoryBlock(
+      ["page-a", "page-b", "page-c"],
+      resolver(pages),
+    );
+    const reversed = await renderMemoryBlock(
+      ["page-c", "page-b", "page-a"],
+      resolver(pages),
+    );
+
+    expect(forward).toBe("<memory>\nA\nB\nC\n</memory>");
+    expect(reversed).toBe("<memory>\nC\nB\nA\n</memory>");
+  });
+
+  test("emits the shared wrapMemoryBlock marker the v2 stripper recognizes", async () => {
+    const block = await renderMemoryBlock(
+      ["page-a"],
+      resolver({ "page-a": "x" }),
+    );
+    // Guard the v2/v3 marker contract: the rendered block must be byte-identical
+    // to wrapping the joined content with the shared helper.
+    expect(block).toBe(wrapMemoryBlock("x"));
+  });
+});

package/src/memory/v3/__tests__/router.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Tests for `assistant/src/memory/v3/router.ts`.
+ *
+ * Coverage matrix:
+ *   - Returned IDs map to the right leaves by 1-based index, in model order.
+ *   - Omitted `ids` → ALL leaves (recall-safe).
+ *   - Explicit `ids: []` → no leaves (deliberate abstention).
+ *   - Out-of-range / duplicate IDs ignored, no throw.
+ *   - No provider / missing tool_use / schema mismatch / throw → ALL leaves.
+ *   - The rendered leaf block is byte-identical across two calls with
+ *     different queries (the cache invariant).
+ *   - The system prompt mentions "register" (locks the routing commitment).
+ *
+ * The provider is stubbed so no network calls fire.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type {
+  Message,
+  Provider,
+  ProviderResponse,
+  SendMessageOptions,
+  ToolUseContent,
+} from "../../../providers/types.js";
+import type { LeafNode, LeafPath, LeafTree, TurnContext } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Mocks installed BEFORE the router import so the module observes them at
+// load time.
+// ---------------------------------------------------------------------------
+
+let providerStub: Provider | null = null;
+
+interface ProviderCall {
+  messages: Message[];
+  options: SendMessageOptions | undefined;
+}
+const providerCalls: ProviderCall[] = [];
+
+mock.module("../../../providers/provider-send-message.js", () => ({
+  getConfiguredProvider: async () => providerStub,
+  extractToolUse: (response: ProviderResponse) =>
+    response.content.find((b): b is ToolUseContent => b.type === "tool_use"),
+}));
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: (_t, prop) => (prop === "child" ? () => ({}) : () => {}),
+    }),
+}));
+
+const { routeL1, renderLeafBlock } = await import("../router.js");
+
+// ---------------------------------------------------------------------------
+// Helpers.
+// ---------------------------------------------------------------------------
+
+function makeProvider(response: ProviderResponse): Provider {
+  return {
+    name: "stub",
+    sendMessage: async (messages, options) => {
+      providerCalls.push({ messages, options });
+      return response;
+    },
+  };
+}
+
+function toolUseResponse(input: Record<string, unknown>): ProviderResponse {
+  return {
+    model: "stub-model",
+    stopReason: "tool_use",
+    usage: { inputTokens: 0, outputTokens: 0 },
+    content: [{ type: "tool_use", id: "tu-1", name: "open_leaves", input }],
+  };
+}
+
+function makeLeaf(path: LeafPath, description: string): LeafNode {
+  return {
+    path,
+    frontmatter: { path, in_core: false },
+    description,
+    members: [],
+    domain: path.split("/")[0],
+  };
+}
+
+/** Tree whose leaves are intentionally inserted out of sorted order so the
+ * tests verify the router sorts by path (not insertion order) before
+ * assigning 1-based IDs. Sorted → [people/alice, people/bob, projects/atlas]. */
+function makeTree(): LeafTree {
+  const entries: LeafNode[] = [
+    makeLeaf("projects/atlas", "The Atlas project roadmap and status."),
+    makeLeaf("people/bob", "Bob — colleague, prefers async."),
+    makeLeaf("people/alice", "Alice — manager, weekly 1:1s."),
+  ];
+  return {
+    leaves: new Map(entries.map((n) => [n.path, n])),
+    byPage: new Map(),
+  };
+}
+
+const SORTED_PATHS = ["people/alice", "people/bob", "projects/atlas"];
+
+function makeTurn(currentMessage: string): TurnContext {
+  return {
+    conversationId: "conv-xyz",
+    turnNumber: 1,
+    currentMessage,
+    recentContext: "earlier we talked about the timeline",
+  };
+}
+
+beforeEach(() => {
+  providerStub = null;
+  providerCalls.length = 0;
+});
+
+// ---------------------------------------------------------------------------
+// Tests.
+// ---------------------------------------------------------------------------
+
+describe("routeL1 — id mapping", () => {
+  test("returned IDs map to leaves by 1-based index, in model order", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [3, 1] }));
+    const result = await routeL1(makeTurn("how's atlas?"), makeTree());
+    expect(result).toEqual(["projects/atlas", "people/alice"]);
+  });
+
+  test("omitted ids opens ALL leaves (recall-safe)", async () => {
+    providerStub = makeProvider(toolUseResponse({}));
+    const result = await routeL1(makeTurn("anything"), makeTree());
+    expect(result).toEqual(SORTED_PATHS);
+  });
+
+  test("explicit empty ids opens no leaves (abstention)", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [] }));
+    const result = await routeL1(makeTurn("nothing relevant"), makeTree());
+    expect(result).toEqual([]);
+  });
+
+  test("out-of-range and duplicate IDs are ignored without throwing", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [2, 99, 0, -1, 2] }));
+    const result = await routeL1(makeTurn("bob?"), makeTree());
+    expect(result).toEqual(["people/bob"]);
+  });
+
+  test("empty tree returns no leaves and never calls the provider", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [1] }));
+    const result = await routeL1(makeTurn("hi"), {
+      leaves: new Map(),
+      byPage: new Map(),
+    });
+    expect(result).toEqual([]);
+    expect(providerCalls).toHaveLength(0);
+  });
+});
+
+describe("routeL1 — recall-safe fallbacks", () => {
+  test("no provider → ALL leaves", async () => {
+    providerStub = null;
+    const result = await routeL1(makeTurn("x"), makeTree());
+    expect(result).toEqual(SORTED_PATHS);
+  });
+
+  test("missing tool_use → ALL leaves", async () => {
+    providerStub = makeProvider({
+      model: "stub-model",
+      stopReason: "end_turn",
+      usage: { inputTokens: 0, outputTokens: 0 },
+      content: [{ type: "text", text: "no tool call" }],
+    });
+    const result = await routeL1(makeTurn("x"), makeTree());
+    expect(result).toEqual(SORTED_PATHS);
+  });
+
+  test("schema mismatch → ALL leaves", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: "not-an-array" }));
+    const result = await routeL1(makeTurn("x"), makeTree());
+    expect(result).toEqual(SORTED_PATHS);
+  });
+
+  test("provider throw → ALL leaves", async () => {
+    providerStub = {
+      name: "throwing",
+      sendMessage: async () => {
+        throw new Error("boom");
+      },
+    };
+    const result = await routeL1(makeTurn("x"), makeTree());
+    expect(result).toEqual(SORTED_PATHS);
+  });
+});
+
+describe("routeL1 — request shape", () => {
+  test("forces tool_choice to open_leaves with the v3 call site", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [1] }));
+    await routeL1(makeTurn("alice?"), makeTree());
+
+    expect(providerCalls).toHaveLength(1);
+    const [call] = providerCalls;
+    const cfg = call.options?.config as Record<string, unknown>;
+    expect(cfg?.callSite).toBe("memoryV3RouteL1");
+    expect(cfg?.tool_choice).toEqual({ type: "tool", name: "open_leaves" });
+    expect(call.options?.tools?.[0]?.name).toBe("open_leaves");
+  });
+
+  test("leaf block is the first content block with an ephemeral cache breakpoint", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [1] }));
+    await routeL1(makeTurn("alice?"), makeTree());
+
+    const [blockA, blockB] = providerCalls[0].messages[0].content as Array<{
+      type: string;
+      text: string;
+      cache_control?: { type: string };
+    }>;
+    expect(blockA.type).toBe("text");
+    expect(blockA.text).toContain("<leaves>");
+    expect(blockA.cache_control).toEqual({ type: "ephemeral" });
+
+    expect(blockB.type).toBe("text");
+    expect(blockB.text).toContain("<current_message>alice?</current_message>");
+    expect(blockB.text).toContain("<recent_context>");
+    expect(blockB.cache_control).toBeUndefined();
+  });
+
+  test("system prompt mentions register (locks the routing commitment)", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [1] }));
+    await routeL1(makeTurn("x"), makeTree());
+    expect(providerCalls[0].options?.systemPrompt).toMatch(/register/);
+  });
+});
+
+describe("renderLeafBlock — cache invariant", () => {
+  test("is byte-identical across two calls with different queries", async () => {
+    const tree = makeTree();
+    providerStub = makeProvider(toolUseResponse({ ids: [1] }));
+
+    await routeL1(makeTurn("first query about alice"), tree);
+    await routeL1(makeTurn("totally different query about atlas"), tree);
+
+    const prefixA = (
+      providerCalls[0].messages[0].content[0] as { text: string }
+    ).text;
+    const prefixB = (
+      providerCalls[1].messages[0].content[0] as { text: string }
+    ).text;
+    expect(prefixA).toBe(prefixB);
+    // And it equals the pure renderer's output.
+    expect(prefixA).toBe(renderLeafBlock(tree));
+  });
+
+  test("renders leaves sorted by path with 1-based numbering", () => {
+    const block = renderLeafBlock(makeTree());
+    expect(block).toContain("[1] people/alice — ");
+    expect(block).toContain("[2] people/bob — ");
+    expect(block).toContain("[3] projects/atlas — ");
+  });
+});