@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

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

@@ -1,192 +0,0 @@
-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/assign.ts

@@ -1,268 +0,0 @@
-/**
- * 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;
-}

package/src/memory/v3/capabilities.ts

@@ -1,124 +0,0 @@
-/**
- * Memory v3 — synthetic "capabilities" leaf (skills + `assistant` CLI commands).
- *
- * v2 surfaces the assistant's invokable capabilities — installed/catalog skills
- * and top-level CLI subcommands — by seeding them as synthetic concept-collection
- * rows (`skills/<id>`, `cli-commands/<name>`) into the unified router pool, then
- * rendering the router-selected ones under `### Skills You Can Use` / `### CLI
- * Commands You Can Use`. They are NOT always-injected — they are router-selected
- * per turn, same as concept pages.
- *
- * v3 reproduces that behavior with one always-on leaf:
- *  - The leaf is synthesized in code (not a `leaves/*.md` data file) and injected
- *    ONLY into the live lane tree (see `shadow-plugin.ts`). Because the classifier
- *    builds its own tree without this injection, concept pages are never routed
- *    INTO the capabilities leaf.
- *  - Its members are the synthetic skill/CLI slugs, so the BM25 needle indexes
- *    them for free (the needle corpus is `tree.byPage`).
- *  - It is added to the always-on core set, so L1 always opens it and the per-leaf
- *    L2 selects the relevant subset each turn — the semantic equivalent of v2's
- *    "always in the pool, selected per turn".
- *
- * Page summaries for synthetic slugs already resolve through the existing
- * `pageSummary` lane (the v2 page index appends skill/CLI rows with a summary),
- * so only full-content rendering for the live `<memory>` block needs a synthetic
- * fallback — see {@link renderCapabilityContent}.
- */
-
-import {
-  getCliCommandCapability,
-  isCliCommandSlug,
-} from "../v2/cli-command-store.js";
-import { getSkillCapability, isSkillSlug } from "../v2/skill-store.js";
-import type { LeafNode, LeafPath, LeafTree, Slug } from "./types.js";
-
-/** Path of the always-on synthetic leaf that owns skill + CLI capability rows. */
-export const CAPABILITIES_LEAF_PATH: LeafPath = "capabilities";
-
-/** L1/needle label for the capabilities leaf. */
-export const CAPABILITIES_LEAF_DESCRIPTION =
-  "Tools the assistant can invoke: installed and available skills, and the " +
-  "top-level `assistant` CLI subcommands — what the assistant can DO and how " +
-  "to reach for each capability.";
-
-/** True iff the slug is a synthetic skill or CLI-command capability row. */
-export function isCapabilitySlug(slug: Slug): boolean {
-  return isSkillSlug(slug) || isCliCommandSlug(slug);
-}
-
-/**
- * Inject the synthetic capabilities leaf into a live lane tree: register the leaf
- * node with `syntheticSlugs` as members, add the leaf to each member's `byPage`
- * entry (UNION — never drops existing leaves), and mark the leaf always-on by
- * adding its path to `core`. Mutates `tree` and `core` in place. Idempotent.
- *
- * Must run BEFORE the needle is built so the synthetic members land in the needle
- * corpus (`tree.byPage`).
- */
-export function injectCapabilitiesLeaf(
-  tree: LeafTree,
-  core: Set<LeafPath>,
-  syntheticSlugs: Slug[],
-): void {
-  const node: LeafNode = {
-    path: CAPABILITIES_LEAF_PATH,
-    frontmatter: { path: CAPABILITIES_LEAF_PATH, in_core: true },
-    description: CAPABILITIES_LEAF_DESCRIPTION,
-    members: [...syntheticSlugs],
-    domain: CAPABILITIES_LEAF_PATH,
-  };
-  tree.leaves.set(CAPABILITIES_LEAF_PATH, node);
-
-  for (const slug of syntheticSlugs) {
-    const existing = tree.byPage.get(slug) ?? [];
-    if (!existing.includes(CAPABILITIES_LEAF_PATH)) {
-      tree.byPage.set(slug, [...existing, CAPABILITIES_LEAF_PATH]);
-    }
-  }
-
-  // Always-on: L1 always opens it, L2 selects the relevant subset per turn.
-  core.add(CAPABILITIES_LEAF_PATH);
-}
-
-interface CapabilityEntry {
-  id: string;
-  content: string;
-}
-
-export interface CapabilityResolvers {
-  skill: (idOrSlug: string) => CapabilityEntry | null;
-  cli: (idOrSlug: string) => CapabilityEntry | null;
-}
-
-const defaultResolvers: CapabilityResolvers = {
-  skill: getSkillCapability,
-  cli: getCliCommandCapability,
-};
-
-/**
- * Render a synthetic skill/CLI slug's full capability content for the live
- * `<memory>` block, mirroring {@link renderV3PageContent}'s `# header\n<content>`
- * shape. Returns:
- *  - the rendered block when the slug is a capability slug and resolves;
- *  - `""` when it is a capability slug but the cache has no entry (degrade to a
- *    blank section rather than throwing or falling through to an on-disk read
- *    that would also miss);
- *  - `null` when the slug is NOT a capability slug, so the caller falls through
- *    to its normal on-disk page rendering.
- *
- * `resolvers` is injectable for tests; production uses the v2 store caches.
- */
-export function renderCapabilityContent(
-  slug: Slug,
-  resolvers: CapabilityResolvers = defaultResolvers,
-): string | null {
-  if (isSkillSlug(slug)) {
-    const entry = resolvers.skill(slug);
-    return entry ? `# Skill: ${entry.id}\n${entry.content}` : "";
-  }
-  if (isCliCommandSlug(slug)) {
-    const entry = resolvers.cli(slug);
-    return entry ? `# CLI command: ${entry.id}\n${entry.content}` : "";
-  }
-  return null;
-}

package/src/memory/v3/core.ts

@@ -1,26 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-
-import { LeafPath } from "./types.js";
-
-/**
- * Loads the always-on core leaf set from `<dataDir>/core.json`.
- *
- * The caller is responsible for resolving `dataDir` (including any
- * workspace-local override — see `resolveDataDir` in `tree.ts`). A missing
- * `core.json` yields an empty set (new workspaces may have no curated core).
- */
-export async function loadCore(dataDir: string): Promise<Set<LeafPath>> {
-  const path = join(dataDir, "core.json");
-  let raw: string;
-  try {
-    raw = await readFile(path, "utf8");
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      return new Set();
-    }
-    throw err;
-  }
-  const parsed = JSON.parse(raw) as { alwaysOn?: LeafPath[] };
-  return new Set(parsed.alwaysOn ?? []);
-}