@vellumai/assistant 0.8.6 → 0.8.7

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

@@ -0,0 +1,192 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { leavesOf, loadLeafTree, membersOf, resolveDataDir } from "../tree.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_DATA_DIR = join(HERE, "..", "data");
+
+describe("loadLeafTree", () => {
+  test("loads leaves with frontmatter, description, and domain", async () => {
+    const tree = await loadLeafTree(BUNDLED_DATA_DIR);
+
+    expect([...tree.leaves.keys()].sort()).toEqual([
+      "domain-a/topic-x",
+      "domain-a/topic-y",
+      "domain-b/topic-z",
+    ]);
+
+    const topicX = tree.leaves.get("domain-a/topic-x");
+    expect(topicX).toBeDefined();
+    expect(topicX?.path).toBe("domain-a/topic-x");
+    expect(topicX?.frontmatter).toEqual({
+      path: "domain-a/topic-x",
+      in_core: true,
+    });
+    expect(topicX?.domain).toBe("domain-a");
+    expect(topicX?.description.length).toBeGreaterThan(0);
+    expect(topicX?.description.startsWith("---")).toBe(false);
+
+    const topicZ = tree.leaves.get("domain-b/topic-z");
+    expect(topicZ?.frontmatter.in_core).toBe(false);
+    expect(topicZ?.domain).toBe("domain-b");
+
+    // Bundled leaves predate the optional `id` field.
+    expect(topicX?.frontmatter.id).toBeUndefined();
+  });
+
+  test("parses the optional stable id when present, omits it otherwise", async () => {
+    const dataDir = await mkdtemp(join(tmpdir(), "v3-leaf-id-"));
+    try {
+      await mkdir(join(dataDir, "leaves", "domain-a"), { recursive: true });
+      await writeFile(
+        join(dataDir, "leaves", "domain-a", "topic-x.md"),
+        "---\npath: domain-a/topic-x\nin_core: true\nid: leaf-123\n---\n\nWith id.\n",
+      );
+      await writeFile(
+        join(dataDir, "leaves", "domain-a", "topic-y.md"),
+        "---\npath: domain-a/topic-y\nin_core: false\n---\n\nNo id.\n",
+      );
+      await writeFile(
+        join(dataDir, "assignments.json"),
+        JSON.stringify({ "page-a": ["domain-a/topic-x"] }),
+      );
+
+      const tree = await loadLeafTree(dataDir);
+      expect(tree.leaves.get("domain-a/topic-x")?.frontmatter.id).toBe(
+        "leaf-123",
+      );
+      expect(
+        tree.leaves.get("domain-a/topic-y")?.frontmatter.id,
+      ).toBeUndefined();
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  test("builds members and byPage from assignments", async () => {
+    const tree = await loadLeafTree(BUNDLED_DATA_DIR);
+
+    // byPage is the inverted assignment map.
+    expect(tree.byPage.get("page-a")).toEqual(["domain-a/topic-x"]);
+    expect(tree.byPage.get("page-b")).toEqual([
+      "domain-a/topic-x",
+      "domain-a/topic-y",
+    ]);
+    expect(tree.byPage.get("page-c")).toEqual(["domain-b/topic-z"]);
+
+    // members are the slugs assigned to each leaf.
+    expect(membersOf(tree, "domain-a/topic-x").sort()).toEqual([
+      "page-a",
+      "page-b",
+    ]);
+    expect(membersOf(tree, "domain-a/topic-y")).toEqual(["page-b"]);
+    expect(membersOf(tree, "domain-b/topic-z")).toEqual(["page-c"]);
+  });
+
+  test("membersOf and leavesOf return empty arrays for unknown keys", async () => {
+    const tree = await loadLeafTree(BUNDLED_DATA_DIR);
+    expect(membersOf(tree, "nope/missing")).toEqual([]);
+    expect(leavesOf(tree, "missing-slug")).toEqual([]);
+  });
+
+  test("leavesOf mirrors byPage", async () => {
+    const tree = await loadLeafTree(BUNDLED_DATA_DIR);
+    expect(leavesOf(tree, "page-b")).toEqual([
+      "domain-a/topic-x",
+      "domain-a/topic-y",
+    ]);
+  });
+
+  test("frontmatter pageLeaves win over assignments.json per page", async () => {
+    const tree = await loadLeafTree(
+      BUNDLED_DATA_DIR,
+      new Map([["page-a", ["domain-a/topic-y"]]]),
+    );
+
+    // page-a is overridden by frontmatter; assignments.json said topic-x.
+    expect(leavesOf(tree, "page-a")).toEqual(["domain-a/topic-y"]);
+    expect(membersOf(tree, "domain-a/topic-y").sort()).toEqual([
+      "page-a",
+      "page-b",
+    ]);
+    expect(membersOf(tree, "domain-a/topic-x")).toEqual(["page-b"]);
+  });
+
+  test("pages absent from pageLeaves fall back to assignments.json", async () => {
+    // page-a override + a page-with-empty-frontmatter that must fall back.
+    const tree = await loadLeafTree(
+      BUNDLED_DATA_DIR,
+      new Map([
+        ["page-a", ["domain-a/topic-y"]],
+        ["page-c", []],
+      ]),
+    );
+
+    // page-b never appeared in pageLeaves → assignments.json.
+    expect(leavesOf(tree, "page-b")).toEqual([
+      "domain-a/topic-x",
+      "domain-a/topic-y",
+    ]);
+    // page-c had an empty frontmatter array → falls back to assignments.json.
+    expect(leavesOf(tree, "page-c")).toEqual(["domain-b/topic-z"]);
+  });
+
+  test("omitting pageLeaves preserves assignments.json behavior", async () => {
+    const withMap = await loadLeafTree(BUNDLED_DATA_DIR, new Map());
+    const without = await loadLeafTree(BUNDLED_DATA_DIR);
+
+    // An empty map is equivalent to omitting it: pure assignments.json.
+    for (const slug of ["page-a", "page-b", "page-c"]) {
+      expect(leavesOf(withMap, slug)).toEqual(leavesOf(without, slug));
+    }
+    expect(leavesOf(without, "page-a")).toEqual(["domain-a/topic-x"]);
+  });
+});
+
+describe("resolveDataDir", () => {
+  let tmpRoot: string;
+  const prevWorkspace = process.env.VELLUM_WORKSPACE_DIR;
+
+  beforeEach(async () => {
+    tmpRoot = await mkdtemp(join(tmpdir(), "v3-tree-"));
+  });
+
+  afterEach(async () => {
+    if (prevWorkspace === undefined) delete process.env.VELLUM_WORKSPACE_DIR;
+    else process.env.VELLUM_WORKSPACE_DIR = prevWorkspace;
+    await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  test("falls back to bundled stub when no workspace override exists", () => {
+    process.env.VELLUM_WORKSPACE_DIR = join(tmpRoot, "workspace");
+    expect(resolveDataDir()).toBe(BUNDLED_DATA_DIR);
+  });
+
+  test("prefers workspace override when <workspace>/memory/v3/data exists", async () => {
+    const workspace = join(tmpRoot, "workspace");
+    const workspaceData = join(workspace, "memory", "v3", "data");
+    const leafDir = join(workspaceData, "leaves", "domain-w");
+    await mkdir(leafDir, { recursive: true });
+    await writeFile(
+      join(leafDir, "topic-real.md"),
+      "---\npath: domain-w/topic-real\nin_core: false\n---\n\nReal workspace leaf.\n",
+    );
+    await writeFile(
+      join(workspaceData, "assignments.json"),
+      JSON.stringify({ "real-page": ["domain-w/topic-real"] }),
+    );
+
+    process.env.VELLUM_WORKSPACE_DIR = workspace;
+
+    expect(resolveDataDir()).toBe(workspaceData);
+
+    const tree = await loadLeafTree(resolveDataDir());
+    expect([...tree.leaves.keys()]).toEqual(["domain-w/topic-real"]);
+    expect(membersOf(tree, "domain-w/topic-real")).toEqual(["real-page"]);
+    expect(leavesOf(tree, "real-page")).toEqual(["domain-w/topic-real"]);
+  });
+});

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

@@ -0,0 +1,54 @@
+import { expect, test } from "bun:test";
+
+import type {
+  LeafFrontmatter,
+  LeafNode,
+  LeafPath,
+  LeafTree,
+  SelectionSource,
+  Slug,
+  TurnContext,
+  WorkingSetEntry,
+} from "../types.js";
+
+test("v3 core types instantiate", () => {
+  const path: LeafPath = "domain/topic/leaf";
+  const slug: Slug = "page-123";
+
+  const frontmatter: LeafFrontmatter = { path, in_core: true };
+
+  const node: LeafNode = {
+    path,
+    frontmatter,
+    description: "an example leaf node",
+    members: [slug],
+    domain: "example",
+  };
+
+  const tree: LeafTree = {
+    leaves: new Map<LeafPath, LeafNode>([[path, node]]),
+    byPage: new Map<Slug, LeafPath[]>([[slug, [path]]]),
+  };
+
+  const entry: WorkingSetEntry = {
+    slug,
+    selectedAtTurn: 1,
+    pinned: false,
+    lastSeenTurn: 2,
+  };
+
+  const turnContext: TurnContext = {
+    conversationId: "conv-xyz",
+    turnNumber: 3,
+    currentMessage: "hello",
+    recentContext: "prior turns",
+  };
+
+  const source: SelectionSource = "carry-forward";
+
+  expect(tree.leaves.get(path)).toBe(node);
+  expect(tree.byPage.get(slug)).toEqual([path]);
+  expect(entry.slug).toBe(slug);
+  expect(turnContext.turnNumber).toBe(3);
+  expect(source).toBe("carry-forward");
+});

package/src/memory/v3/__tests__/working-set-eviction.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from "bun:test";
+
+import { WorkingSetEntry } from "../types.js";
+import { ScoreFn, WorkingSet } from "../working-set.js";
+
+describe("WorkingSet.evict", () => {
+  test("evicts a page unseen past the window", () => {
+    const ws = new WorkingSet(150, 5);
+    ws.recordSelection("alpha", 0, false);
+
+    // currentTurn 6, lastSeen 0 → gap 6 > window 5 → evict.
+    ws.evict(6, new Set());
+
+    expect(ws.union().has("alpha")).toBe(false);
+    expect(ws.size()).toBe(0);
+  });
+
+  test("keeps a page still inside the window", () => {
+    const ws = new WorkingSet(150, 5);
+    ws.recordSelection("alpha", 0, false);
+
+    // gap 5 is not > 5 → keep.
+    ws.evict(5, new Set());
+
+    expect(ws.union().has("alpha")).toBe(true);
+  });
+
+  test("pinned page never evicts past the window", () => {
+    const ws = new WorkingSet(150, 5);
+    ws.recordSelection("alpha", 0, true);
+
+    ws.evict(100, new Set());
+
+    expect(ws.union().has("alpha")).toBe(true);
+  });
+
+  test("exceeding maxPages evicts the least-recently-selected non-pinned page first", () => {
+    const ws = new WorkingSet(2, 1000);
+    ws.recordSelection("oldest", 1, false);
+    ws.recordSelection("middle", 2, false);
+    ws.recordSelection("newest", 3, false);
+
+    // No window eviction (window huge); cap is 2 → drop lowest lastSeenTurn.
+    ws.evict(3, new Set());
+
+    expect(ws.size()).toBe(2);
+    expect(ws.union().has("oldest")).toBe(false);
+    expect(ws.union().has("middle")).toBe(true);
+    expect(ws.union().has("newest")).toBe(true);
+  });
+
+  test("cap eviction never drops pinned pages even when over capacity", () => {
+    const ws = new WorkingSet(1, 1000);
+    ws.recordSelection("pinned-a", 1, true);
+    ws.recordSelection("pinned-b", 2, true);
+    ws.recordSelection("loose", 3, false);
+
+    ws.evict(3, new Set());
+
+    // Only the non-pinned page can go; pinned pages stay even over cap.
+    expect(ws.union().has("pinned-a")).toBe(true);
+    expect(ws.union().has("pinned-b")).toBe(true);
+    expect(ws.union().has("loose")).toBe(false);
+    expect(ws.size()).toBe(2);
+  });
+
+  test("core slugs passed to evict are dropped if present", () => {
+    const ws = new WorkingSet(150, 5);
+    ws.recordSelection("alpha", 5, false);
+    ws.recordSelection("beta", 5, true); // pinned, but core still wins
+    ws.recordSelection("gamma", 5, false);
+
+    ws.evict(5, new Set(["alpha", "beta"]));
+
+    expect(ws.union().has("alpha")).toBe(false);
+    expect(ws.union().has("beta")).toBe(false);
+    expect(ws.union().has("gamma")).toBe(true);
+  });
+
+  test("custom scoreFn reorders cap-evictions", () => {
+    // Score by selectedAtTurn instead of lastSeenTurn: the page selected
+    // earliest becomes most evictable regardless of recent activity.
+    const bySelectedAt: ScoreFn = (e: WorkingSetEntry) => e.selectedAtTurn;
+    const ws = new WorkingSet(2, 1000, bySelectedAt);
+
+    ws.recordSelection("first", 0, false);
+    ws.recordSelection("second", 1, false);
+    ws.recordSelection("third", 2, false);
+    // Bump "first" so plain LRU would protect it, but selectedAt still lowest.
+    ws.recordSelection("first", 9, false);
+
+    ws.evict(9, new Set());
+
+    expect(ws.size()).toBe(2);
+    // Under custom score, "first" (selectedAt 0) evicts despite recent touch.
+    expect(ws.union().has("first")).toBe(false);
+    expect(ws.union().has("second")).toBe(true);
+    expect(ws.union().has("third")).toBe(true);
+  });
+
+  test("default no-arg constructor still works for existing callers", () => {
+    const ws = new WorkingSet();
+    ws.recordSelection("alpha", 0, false);
+    expect(ws.size()).toBe(1);
+  });
+});

package/src/memory/v3/__tests__/working-set-skeleton.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import { WorkingSet } from "../working-set.js";
+
+describe("WorkingSet (skeleton)", () => {
+  test("recording a selection adds it to union()", () => {
+    const ws = new WorkingSet();
+    ws.recordSelection("alpha", 1, false);
+
+    expect(ws.union().has("alpha")).toBe(true);
+    expect(ws.size()).toBe(1);
+  });
+
+  test("recording the same slug twice preserves selectedAtTurn and updates lastSeenTurn", () => {
+    const ws = new WorkingSet();
+    ws.recordSelection("alpha", 1, false);
+    ws.recordSelection("alpha", 5, false);
+
+    expect(ws.size()).toBe(1);
+    const entry = [...ws.union()];
+    expect(entry).toEqual(["alpha"]);
+    // selectedAtTurn preserved at original turn, lastSeenTurn advanced.
+    const internal = (
+      ws as unknown as {
+        entries: Map<string, { selectedAtTurn: number; lastSeenTurn: number }>;
+      }
+    ).entries.get("alpha");
+    expect(internal?.selectedAtTurn).toBe(1);
+    expect(internal?.lastSeenTurn).toBe(5);
+  });
+
+  test("pinned propagates: non-pinned then pinned keeps pinned true", () => {
+    const ws = new WorkingSet();
+    ws.recordSelection("alpha", 1, false);
+    ws.recordSelection("alpha", 2, true);
+
+    const internal = (
+      ws as unknown as {
+        entries: Map<string, { pinned: boolean }>;
+      }
+    ).entries.get("alpha");
+    expect(internal?.pinned).toBe(true);
+  });
+});

package/src/memory/v3/assign.ts

@@ -0,0 +1,268 @@
+/**
+ * v3 page→leaf classifier: assigns pages to leaf topics and UNIONS the result
+ * into each page's `leaves:` frontmatter.
+ *
+ * This ports an offline classifier into a daemon module. For each target page
+ * it runs a single tool-forced LLM call against the cache-stable numbered leaf
+ * index (system prompt) with the page content in the user message, maps the
+ * returned 1-based ids back to leaf paths, and writes back the UNION of the
+ * page's existing picks and the freshly classified picks.
+ *
+ * Recall-safe by construction:
+ * - UNION semantics never drop a page's existing leaf assignments.
+ * - A classification that fails (provider unavailable/throws, no tool use, or
+ *   empty result) leaves the page's `leaves:` frontmatter UNCHANGED.
+ *
+ * Provider-injectable: pass `opts.provider` to bypass the configured-provider
+ * lookup (used by tests and callers that force a specific provider). When
+ * omitted, resolves the `memoryV3RouteL1` callsite provider.
+ */
+
+import {
+  extractToolUse,
+  getConfiguredProvider,
+  userMessage,
+} from "../../providers/provider-send-message.js";
+import type { Provider, ToolDefinition } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { listPages, readPage, writePage } from "../v2/page-store.js";
+import type { ConceptPage } from "../v2/types.js";
+import type { LeafPath, LeafTree, Slug } from "./types.js";
+
+const log = getLogger("memory-v3-assign");
+
+const ASSIGN_TOOL_NAME = "assign_leaves";
+
+/** Default delay between classification calls to avoid hammering the provider. */
+const DEFAULT_THROTTLE_MS = 200;
+
+/** Description length cap in the cache-stable leaf index lines. */
+const DESCRIPTION_CAP = 450;
+
+/** Bounded output budget — the tool only emits a small id array. */
+const MAX_TOKENS = 512;
+
+export interface AssignPagesOptions {
+  /** The leaf tree the page is classified against. */
+  tree: LeafTree;
+  /** Workspace root; pages live under `<workspaceDir>/memory/concepts/`. */
+  workspaceDir: string;
+  /**
+   * Slugs to classify. When omitted, defaults to every page whose `leaves:`
+   * frontmatter is empty or missing (the unclassified set).
+   */
+  slugs?: Slug[];
+  /**
+   * Provider override. When omitted, resolves the `memoryV3RouteL1` callsite
+   * provider once and reuses it across all pages.
+   */
+  provider?: Provider;
+  /** Delay between calls in ms. Defaults to {@link DEFAULT_THROTTLE_MS}. */
+  throttleMs?: number;
+}
+
+/** Per-page classification outcome, for the job + health report to consume. */
+export interface AssignPageResult {
+  slug: Slug;
+  /** The page's leaf assignments before this run. */
+  before: LeafPath[];
+  /** The page's leaf assignments after this run (== before when failed). */
+  after: LeafPath[];
+  /** True when classification failed and the page was left unchanged. */
+  failed: boolean;
+}
+
+/**
+ * Build the cache-stable system prompt: a numbered list of every leaf path with
+ * its (trimmed) description. Stable ordering (sorted by path) keeps the prompt
+ * prefix identical across calls so the provider can cache it.
+ */
+function buildLeafIndexSystemPrompt(
+  sortedLeafPaths: LeafPath[],
+  tree: LeafTree,
+): string {
+  const lines = sortedLeafPaths.map((path, i) => {
+    const description = tree.leaves.get(path)?.description.trim() ?? "";
+    const summary = description.slice(0, DESCRIPTION_CAP);
+    return `[${i + 1}] ${path} — ${summary}`;
+  });
+  return [
+    "You are a memory classifier. Given a page's content, pick the leaf topics",
+    "the page belongs to. A page may belong to several leaves; pick every leaf",
+    "whose topic the page meaningfully covers. Return the leaf numbers via the",
+    "assign_leaves tool.",
+    "",
+    "Leaf index:",
+    ...lines,
+  ].join("\n");
+}
+
+const ASSIGN_TOOL: ToolDefinition = {
+  name: ASSIGN_TOOL_NAME,
+  description: "Return the leaf numbers this page belongs to.",
+  input_schema: {
+    type: "object",
+    properties: {
+      ids: {
+        type: "array",
+        items: { type: "integer" },
+      },
+    },
+  },
+};
+
+/** Map 1-based ids to sorted leaf paths, dropping out-of-range/0/non-integer ids. */
+function idsToLeafPaths(ids: unknown, sortedLeafPaths: LeafPath[]): LeafPath[] {
+  if (!Array.isArray(ids)) return [];
+  const out: LeafPath[] = [];
+  for (const id of ids) {
+    if (typeof id !== "number" || !Number.isInteger(id)) continue;
+    const idx = id - 1;
+    if (idx < 0 || idx >= sortedLeafPaths.length) continue;
+    const leafPath = sortedLeafPaths[idx];
+    if (!out.includes(leafPath)) out.push(leafPath);
+  }
+  return out;
+}
+
+/** Stable union of two leaf-path lists (existing order first, then new). */
+function unionLeafPaths(existing: LeafPath[], added: LeafPath[]): LeafPath[] {
+  const out = [...existing];
+  for (const leaf of added) {
+    if (!out.includes(leaf)) out.push(leaf);
+  }
+  return out;
+}
+
+/** A page's existing `leaves:` frontmatter, or `[]` when empty/missing. */
+function pageLeaves(page: ConceptPage): LeafPath[] {
+  return page.frontmatter.leaves ?? [];
+}
+
+/** The flat text a page contributes to the classifier user message. */
+function pageClassifierInput(page: ConceptPage): string {
+  const { summary } = page.frontmatter;
+  return [summary ?? "", page.body]
+    .filter((s) => s.trim().length > 0)
+    .join("\n\n");
+}
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Classify pages into leaf topics and UNION the result into each page's
+ * `leaves:` frontmatter. See the module docstring for the recall-safety
+ * guarantees.
+ */
+export async function assignPages(
+  opts: AssignPagesOptions,
+): Promise<AssignPageResult[]> {
+  const { tree, workspaceDir } = opts;
+  const throttleMs = opts.throttleMs ?? DEFAULT_THROTTLE_MS;
+
+  const sortedLeafPaths = [...tree.leaves.keys()].sort((a, b) =>
+    a.localeCompare(b),
+  );
+  const systemPrompt = buildLeafIndexSystemPrompt(sortedLeafPaths, tree);
+
+  const targetSlugs = opts.slugs ?? (await unclassifiedSlugs(workspaceDir));
+
+  // Resolve the provider once and reuse it across pages.
+  const provider =
+    opts.provider ?? (await getConfiguredProvider("memoryV3RouteL1"));
+
+  const results: AssignPageResult[] = [];
+  for (let i = 0; i < targetSlugs.length; i++) {
+    const slug = targetSlugs[i];
+    const page = await readPage(workspaceDir, slug);
+    if (!page) {
+      log.warn({ slug }, "assign: page not found, skipping");
+      results.push({ slug, before: [], after: [], failed: true });
+      continue;
+    }
+
+    const before = pageLeaves(page);
+
+    if (!provider) {
+      log.warn(
+        { slug },
+        "assign: no provider available, leaving page unchanged",
+      );
+      results.push({ slug, before, after: before, failed: true });
+      continue;
+    }
+
+    const classified = await classifyPage(
+      provider,
+      systemPrompt,
+      pageClassifierInput(page),
+      sortedLeafPaths,
+    );
+
+    if (!classified) {
+      // Non-destructive: leave the page's existing picks untouched.
+      results.push({ slug, before, after: before, failed: true });
+    } else {
+      const after = unionLeafPaths(before, classified);
+      if (after.length !== before.length) {
+        await writePage(workspaceDir, {
+          ...page,
+          frontmatter: { ...page.frontmatter, leaves: after },
+        });
+      }
+      results.push({ slug, before, after, failed: false });
+    }
+
+    if (throttleMs > 0 && i < targetSlugs.length - 1) {
+      await sleep(throttleMs);
+    }
+  }
+
+  return results;
+}
+
+/** Pages whose `leaves:` frontmatter is empty or missing — the default targets. */
+async function unclassifiedSlugs(workspaceDir: string): Promise<Slug[]> {
+  const slugs = await listPages(workspaceDir);
+  const unclassified: Slug[] = [];
+  for (const slug of slugs) {
+    const page = await readPage(workspaceDir, slug);
+    if (page && pageLeaves(page).length === 0) unclassified.push(slug);
+  }
+  return unclassified;
+}
+
+/**
+ * Run a single tool-forced classification call. Returns the classified leaf
+ * paths, or `null` when the call fails (throws, no tool use, or empty ids) so
+ * the caller can treat it as non-destructive.
+ */
+async function classifyPage(
+  provider: Provider,
+  systemPrompt: string,
+  pageInput: string,
+  sortedLeafPaths: LeafPath[],
+): Promise<LeafPath[] | null> {
+  let response;
+  try {
+    response = await provider.sendMessage([userMessage(pageInput)], {
+      systemPrompt,
+      tools: [ASSIGN_TOOL],
+      config: {
+        callSite: "memoryV3RouteL1",
+        maxTokens: MAX_TOKENS,
+        tool_choice: { type: "tool", name: ASSIGN_TOOL_NAME },
+      },
+    });
+  } catch (err) {
+    log.warn({ err }, "assign: classification provider call failed");
+    return null;
+  }
+
+  const toolUse = extractToolUse(response);
+  if (!toolUse || toolUse.name !== ASSIGN_TOOL_NAME) return null;
+
+  const leafPaths = idsToLeafPaths(toolUse.input.ids, sortedLeafPaths);
+  return leafPaths.length > 0 ? leafPaths : null;
+}