@vellumai/assistant 0.8.2 → 0.8.4

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

@@ -73,6 +73,26 @@ mock.module("../skill-store.js", () => ({
   listSkillEntries: () => skillState.entries,
 }));
 
+// Stub `computeInjectionScores` so tier-2 tests can dictate scores
+// without spinning up a real bun:sqlite db. Real production wiring is
+// covered by the splitTier2 unit tests in page-index.test.ts and the
+// score-formula tests in injection-events.test.ts.
+const scoresStub = new Map<string, number>();
+mock.module("../injection-events.js", () => ({
+  computeInjectionScores: (
+    _db: unknown,
+    slugs: readonly string[],
+    _now: number,
+  ): Map<string, number> => {
+    const out = new Map<string, number>();
+    for (const slug of slugs) {
+      const score = scoresStub.get(slug);
+      if (score !== undefined && score > 0) out.set(slug, score);
+    }
+    return out;
+  },
+}));
+
 // Provider stub. Each test sets `providerStub` to control the response;
 // `null` simulates "no configured provider available".
 let providerStub: Provider | null = null;
@@ -112,6 +132,7 @@ beforeEach(() => {
   providerStub = null;
   providerCalls.length = 0;
   warnLogs.length = 0;
+  scoresStub.clear();
   invalidatePageIndex();
 });
 
@@ -194,7 +215,12 @@ function makePage(
 // fields the router actually reads. Cast through `as unknown` because the
 // production type is a heavy nested schema; we only exercise the v2.router
 // branch in this test file.
-function makeConfig(overrides?: { maxPageIds?: number }) {
+function makeConfig(overrides?: {
+  maxPageIds?: number;
+  batchSize?: number | null;
+  tier1Size?: number | null;
+  tier2Size?: number | null;
+}) {
   return {
     memory: {
       v2: {
@@ -202,6 +228,9 @@ function makeConfig(overrides?: { maxPageIds?: number }) {
         router: {
           enabled: true,
           max_page_ids: overrides?.maxPageIds ?? 25,
+          batch_size: overrides?.batchSize ?? null,
+          tier1_size: overrides?.tier1Size ?? null,
+          tier2_size: overrides?.tier2Size ?? null,
         },
       },
     },
@@ -231,6 +260,7 @@ describe("runRouter — early bails", () => {
 
     expect(result).toEqual({
       selectedSlugs: [],
+      sourceBySlug: new Map(),
       failureReason: "empty_index",
     });
     // Provider must NOT be invoked when there is nothing to route.
@@ -286,6 +316,7 @@ describe("runRouter — successful tool_use", () => {
 
     expect(result).toEqual({
       selectedSlugs: [],
+      sourceBySlug: new Map(),
       failureReason: null,
     });
   });
@@ -529,3 +560,460 @@ describe("runRouter — failure modes", () => {
     expect(providerCalls[0].options?.signal).toBe(controller.signal);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Batched routing (config.memory.v2.router.batch_size).
+// ---------------------------------------------------------------------------
+
+describe("runRouter — batched (batch_size set)", () => {
+  beforeEach(async () => {
+    // 5 pages → at batch_size=2 we get ceil(5/2)=3 batches.
+    await writePage(workspaceDir, makePage("alpha", { summary: "A" }));
+    await writePage(workspaceDir, makePage("bravo", { summary: "B" }));
+    await writePage(workspaceDir, makePage("charlie", { summary: "C" }));
+    await writePage(workspaceDir, makePage("delta", { summary: "D" }));
+    await writePage(workspaceDir, makePage("echo", { summary: "E" }));
+  });
+
+  test("fires one provider call per batch in parallel", async () => {
+    // Every batch returns its local id 1 → at most 3 distinct slugs in the
+    // union (one per batch), but we don't assert WHICH slugs the FNV
+    // bucketing picks; just that the provider was called once per batch.
+    providerStub = makeProvider(toolUseResponse([1]));
+
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 2 }),
+    });
+
+    expect(result.failureReason).toBeNull();
+    expect(providerCalls.length).toBeGreaterThan(1);
+    expect(providerCalls.length).toBeLessThanOrEqual(3);
+    // Every batch picked its own local id 1 → distinct slugs in union.
+    expect(result.selectedSlugs.length).toBe(providerCalls.length);
+    expect(new Set(result.selectedSlugs).size).toBe(
+      result.selectedSlugs.length,
+    );
+  });
+
+  test("each batch's system prompt contains only its own subset of slugs", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 2 }),
+    });
+
+    // Across all batch calls, every slug appears in exactly one prompt.
+    const allSlugs = ["alpha", "bravo", "charlie", "delta", "echo"];
+    const appearances = new Map<string, number>(allSlugs.map((s) => [s, 0]));
+    for (const call of providerCalls) {
+      for (const slug of allSlugs) {
+        if (call.systemPrompt?.includes(slug)) {
+          appearances.set(slug, (appearances.get(slug) ?? 0) + 1);
+        }
+      }
+    }
+    for (const slug of allSlugs) {
+      expect(appearances.get(slug)).toBe(1);
+    }
+  });
+
+  test("union of selected slugs is deduplicated across batches", async () => {
+    // Every batch returns its local id 1. Same slug could appear in only
+    // one batch (since each slug lives in exactly one batch), so the union
+    // is naturally unique. Sanity-check the dedup path with a 2-call response.
+    providerStub = makeProvider(toolUseResponse([1, 1]));
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 2 }),
+    });
+    expect(result.failureReason).toBeNull();
+    expect(new Set(result.selectedSlugs).size).toBe(
+      result.selectedSlugs.length,
+    );
+  });
+
+  test("priorEverInjected is filtered to the batch's own slugs as local IDs", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      priorEverInjected: [
+        { slug: "alpha", turn: 1 },
+        { slug: "echo", turn: 1 },
+      ],
+      config: makeConfig({ batchSize: 2 }),
+    });
+
+    // Exactly the batches containing alpha or echo should mention any
+    // already_injected_id; other batches should have an empty list.
+    for (const call of providerCalls) {
+      const text =
+        (call.messages[0].content as Array<{ text?: string }>)[1]?.text ?? "";
+      const hasAlpha = call.systemPrompt?.includes("alpha");
+      const hasEcho = call.systemPrompt?.includes("echo");
+      const expectsId = hasAlpha || hasEcho;
+      // Block contents: "<already_injected_ids>\n{ids}\n</already_injected_ids>"
+      const match = text.match(
+        /<already_injected_ids>\n([^\n]*)\n<\/already_injected_ids>/,
+      );
+      const idsStr = match?.[1] ?? "";
+      if (expectsId) {
+        expect(idsStr.trim().length).toBeGreaterThan(0);
+      } else {
+        expect(idsStr.trim()).toBe("");
+      }
+    }
+  });
+
+  test("partial failure: one batch fails, others succeed → union returned with success", async () => {
+    let callCount = 0;
+    providerStub = {
+      name: "partial-failure",
+      sendMessage: async (messages, tools, systemPrompt, options) => {
+        callCount += 1;
+        providerCalls.push({ messages, tools, systemPrompt, options });
+        if (callCount === 1) throw new Error("batch 1 boom");
+        return toolUseResponse([1]);
+      },
+    };
+
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 2 }),
+    });
+
+    expect(result.failureReason).toBeNull();
+    expect(result.selectedSlugs.length).toBeGreaterThan(0);
+    expect(providerCalls.length).toBeGreaterThan(1);
+  });
+
+  test("all batches fail → unified failure with first batch's reason", async () => {
+    providerStub = {
+      name: "all-fail",
+      sendMessage: async () => {
+        throw new Error("all batches boom");
+      },
+    };
+
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 2 }),
+    });
+
+    expect(result.failureReason).toBe("api_error");
+    expect(result.selectedSlugs).toEqual([]);
+  });
+
+  test("union across batches is truncated to global max_page_ids", async () => {
+    // 5 pages, batch_size=1 → 5 batches, each picks its own local id 1.
+    // Without a global cap the union would be 5; max_page_ids=2 forces
+    // truncation back to 2.
+    providerStub = makeProvider(toolUseResponse([1]));
+
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 1, maxPageIds: 2 }),
+    });
+
+    expect(result.failureReason).toBeNull();
+    expect(result.selectedSlugs).toHaveLength(2);
+    // sourceBySlug must stay aligned with the truncated selection.
+    expect(result.sourceBySlug.size).toBe(2);
+    for (const slug of result.selectedSlugs) {
+      expect(result.sourceBySlug.get(slug)).toBeDefined();
+    }
+    const warned = warnLogs.some((l) =>
+      JSON.stringify(l.args).includes("union across batches exceeded"),
+    );
+    expect(warned).toBe(true);
+  });
+
+  test("batch_size larger than index size is single batch (same as v3)", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ batchSize: 1000 }),
+    });
+    expect(result.failureReason).toBeNull();
+    expect(providerCalls).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tier 1 (recently modified) splitting.
+// ---------------------------------------------------------------------------
+
+const { utimes } = await import("node:fs/promises");
+
+describe("runRouter — tier 1 (recently modified)", () => {
+  async function setMtime(slug: string, epochMs: number): Promise<void> {
+    const seconds = epochMs / 1000;
+    await utimes(
+      join(workspaceDir, "memory", "concepts", `${slug}.md`),
+      seconds,
+      seconds,
+    );
+  }
+
+  beforeEach(async () => {
+    await writePage(workspaceDir, makePage("alpha", { summary: "A" }));
+    await writePage(workspaceDir, makePage("bravo", { summary: "B" }));
+    await writePage(workspaceDir, makePage("charlie", { summary: "C" }));
+    await writePage(workspaceDir, makePage("delta", { summary: "D" }));
+    await writePage(workspaceDir, makePage("echo", { summary: "E" }));
+  });
+
+  test("tier1_size + batch_size both null is the v3 single-batch path", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig(),
+    });
+    expect(result.failureReason).toBeNull();
+    expect(providerCalls).toHaveLength(1);
+  });
+
+  test("tier1_size=2 + batch_size=null produces 2 batches (tier1 + rest)", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier1Size: 2 }),
+    });
+    expect(result.failureReason).toBeNull();
+    expect(providerCalls).toHaveLength(2);
+  });
+
+  test("tier 1 contains the most recently modified pages", async () => {
+    // Stamp distinct mtimes so the ordering is unambiguous.
+    await setMtime("alpha", 1_000_000);
+    await setMtime("bravo", 5_000_000); // most recent
+    await setMtime("charlie", 2_000_000);
+    await setMtime("delta", 4_000_000); // 2nd most recent
+    await setMtime("echo", 3_000_000);
+
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier1Size: 2 }),
+    });
+
+    // Tier 1 is the first provider call. Match `[N] slug` lines specifically
+    // — string-search on slug name alone would false-positive on prompt
+    // template text that may mention the same words.
+    const tier1Prompt = providerCalls[0].systemPrompt ?? "";
+    const indexedSlugs = new Set(
+      [...tier1Prompt.matchAll(/^\[\d+\] (\S+)/gm)].map((m) => m[1]),
+    );
+    expect(indexedSlugs).toEqual(new Set(["bravo", "delta"]));
+  });
+
+  test("tier1_size=2 + batch_size=2 puts every slug in exactly one batch", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier1Size: 2, batchSize: 2 }),
+    });
+    // 5 pages, tier1=2, rest=3 → 1 tier1 batch + 1-or-2 tier3 batches
+    // depending on whether FNV hash distributes the 3 rest slugs into both
+    // buckets. The empty-batch filter drops a bucket that lands empty, so
+    // the strong invariant is "every slug appears in exactly one batch."
+    expect(providerCalls.length).toBeGreaterThanOrEqual(2);
+    expect(providerCalls.length).toBeLessThanOrEqual(3);
+
+    const allSlugs = ["alpha", "bravo", "charlie", "delta", "echo"];
+    const appearances = new Map<string, number>(
+      allSlugs.map((s) => [s, 0] as [string, number]),
+    );
+    for (const call of providerCalls) {
+      for (const slug of allSlugs) {
+        if (call.systemPrompt?.includes(slug)) {
+          appearances.set(slug, (appearances.get(slug) ?? 0) + 1);
+        }
+      }
+    }
+    for (const slug of allSlugs) {
+      expect(appearances.get(slug)).toBe(1);
+    }
+  });
+
+  test("tier1_size >= total pages → single tier 1 batch, no rest", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier1Size: 100 }),
+    });
+    // 5 pages, tier1_size=100 → only tier 1 fires; the empty rest is dropped.
+    expect(providerCalls).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tier 2 (highest-EMA) splitting.
+// ---------------------------------------------------------------------------
+
+describe("runRouter — tier 2 (highest EMA)", () => {
+  // Any non-null value passes the `params.database` check in the orchestrator;
+  // the real db is never touched because computeInjectionScores is mocked.
+  const stubDb = {} as Parameters<typeof runRouter>[0]["database"];
+
+  beforeEach(async () => {
+    await writePage(workspaceDir, makePage("alpha", { summary: "A" }));
+    await writePage(workspaceDir, makePage("bravo", { summary: "B" }));
+    await writePage(workspaceDir, makePage("charlie", { summary: "C" }));
+    await writePage(workspaceDir, makePage("delta", { summary: "D" }));
+    await writePage(workspaceDir, makePage("echo", { summary: "E" }));
+  });
+
+  test("tier2_size + tier1_size both null is the v3 single-batch path", async () => {
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig(),
+      database: stubDb,
+    });
+    expect(providerCalls).toHaveLength(1);
+  });
+
+  test("tier2_size=2 produces 2 batches (tier 2 + rest)", async () => {
+    scoresStub.set("alpha", 1.0);
+    scoresStub.set("bravo", 5.0);
+    scoresStub.set("delta", 4.0);
+
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier2Size: 2 }),
+      database: stubDb,
+    });
+    expect(providerCalls.length).toBe(2);
+
+    // Tier 2 is the first batch (no tier 1 in this test). Its prompt should
+    // contain exactly the top-2 by score: bravo (5) and delta (4).
+    const tier2Prompt = providerCalls[0].systemPrompt ?? "";
+    const indexedSlugs = new Set(
+      [...tier2Prompt.matchAll(/^\[\d+\] (\S+)/gm)].map((m) => m[1]),
+    );
+    expect(indexedSlugs).toEqual(new Set(["bravo", "delta"]));
+  });
+
+  test("tier 1 then tier 2 then rest — three batches in that order", async () => {
+    // Pin mtimes so tier 1 is deterministic: alpha + bravo are the two
+    // most recent (highest mtime values). Tier 2 runs on the rest
+    // (charlie, delta, echo) using scores we control.
+    const { utimes } = await import("node:fs/promises");
+    const stamp = async (slug: string, s: number) =>
+      utimes(join(workspaceDir, "memory", "concepts", `${slug}.md`), s, s);
+    await stamp("alpha", 9000);
+    await stamp("bravo", 8000);
+    await stamp("charlie", 3000);
+    await stamp("delta", 2000);
+    await stamp("echo", 1000);
+    invalidatePageIndex();
+
+    scoresStub.set("charlie", 2.0);
+    scoresStub.set("delta", 3.0);
+    // echo has no score → ineligible for tier 2.
+
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier1Size: 2, tier2Size: 2 }),
+      database: stubDb,
+    });
+    expect(providerCalls.length).toBe(3);
+
+    // Tier 2 batch (index 1) contains charlie + delta. Echo went to rest.
+    const tier2Prompt = providerCalls[1].systemPrompt ?? "";
+    const tier2Slugs = new Set(
+      [...tier2Prompt.matchAll(/^\[\d+\] (\S+)/gm)].map((m) => m[1]),
+    );
+    expect(tier2Slugs).toEqual(new Set(["charlie", "delta"]));
+
+    // Echo (no score) must land in the rest batch, not tier 2.
+    const restPrompt = providerCalls[2].systemPrompt ?? "";
+    const restSlugs = new Set(
+      [...restPrompt.matchAll(/^\[\d+\] (\S+)/gm)].map((m) => m[1]),
+    );
+    expect(restSlugs).toEqual(new Set(["echo"]));
+  });
+
+  test("score=0 pages stay in rest even when tier2_size is large", async () => {
+    // Only one page has a positive score; tier2_size=100 should NOT pull in
+    // zero-score pages.
+    scoresStub.set("bravo", 5.0);
+
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier2Size: 100 }),
+      database: stubDb,
+    });
+    expect(providerCalls.length).toBe(2);
+    const tier2Prompt = providerCalls[0].systemPrompt ?? "";
+    expect(tier2Prompt).toContain("[1] bravo");
+    expect(tier2Prompt).not.toMatch(/^\[\d+\] alpha/m);
+  });
+
+  test("sourceBySlug tags each selection with its batch tier", async () => {
+    scoresStub.set("bravo", 5.0);
+    scoresStub.set("delta", 3.0);
+
+    providerStub = makeProvider(toolUseResponse([1]));
+    const result = await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier1Size: 1, tier2Size: 1 }),
+      database: stubDb,
+    });
+
+    // Every selected slug should have a tier tag — exactly one of:
+    // "tier1", "tier2", or "tier3:N" (N starts at 0).
+    for (const slug of result.selectedSlugs) {
+      const source = result.sourceBySlug.get(slug);
+      expect(source).toBeDefined();
+      expect(
+        source === "tier1" ||
+          source === "tier2" ||
+          source!.startsWith("tier3:"),
+      ).toBe(true);
+    }
+    // Tier 1 + tier 2 + (some tier 3 batches) ≥ 3 batches → at least one
+    // slug per tier should be present in the source map across the union.
+    const tags = new Set(result.sourceBySlug.values());
+    expect(tags.has("tier1")).toBe(true);
+    expect(tags.has("tier2")).toBe(true);
+  });
+
+  test("tier2_size set without database logs a warn and skips tier 2", async () => {
+    scoresStub.set("bravo", 5.0);
+    providerStub = makeProvider(toolUseResponse([1]));
+    await runRouter({
+      workspaceDir,
+      ...COMMON_PARAMS,
+      config: makeConfig({ tier2Size: 2 }),
+      // No database → tier 2 silently skipped.
+    });
+    expect(providerCalls).toHaveLength(1);
+    const warned = warnLogs.some((l) =>
+      JSON.stringify(l.args).includes("tier2_size set but no database"),
+    );
+    expect(warned).toBe(true);
+  });
+});

package/src/memory/v2/__tests__/static-context.test.ts

@@ -32,11 +32,15 @@ mock.module("../../../util/logger.js", () => ({
 }));
 
 let configMemoryV2Enabled = true;
+let configMemoryEnabled = true;
 
 mock.module("../../../config/loader.js", () => ({
   getConfig: () => ({}),
   loadConfig: () => ({
-    memory: { v2: { enabled: configMemoryV2Enabled } },
+    memory: {
+      enabled: configMemoryEnabled,
+      v2: { enabled: configMemoryV2Enabled },
+    },
   }),
   loadRawConfig: () => ({}),
   saveRawConfig: () => {},
@@ -71,6 +75,7 @@ describe("readMemoryV2StaticContent", () => {
   beforeEach(() => {
     mkdirSync(TEST_DIR, { recursive: true });
     configMemoryV2Enabled = true;
+    configMemoryEnabled = true;
   });
 
   afterEach(() => {
@@ -83,6 +88,12 @@ describe("readMemoryV2StaticContent", () => {
     expect(readMemoryV2StaticContent()).toBeNull();
   });
 
+  test("returns null when config.memory.enabled is off even with v2 on", () => {
+    configMemoryEnabled = false;
+    for (const file of MEMORY_FILES) writeMemoryFile(file, `Content ${file}`);
+    expect(readMemoryV2StaticContent()).toBeNull();
+  });
+
   test("returns headed sections in canonical order when all files have content", () => {
     writeMemoryFile("essentials.md", "Alice prefers dark mode.");
     writeMemoryFile("threads.md", "Open thread: ship PR-123 review.");

package/src/memory/v2/activation-store.ts

@@ -11,11 +11,7 @@ import { eq } from "drizzle-orm";
 
 import type { DrizzleDb } from "../db-connection.js";
 import { activationState } from "../schema.js";
-import {
-  type ActivationState,
-  ActivationStateSchema,
-  type EverInjectedEntry,
-} from "./types.js";
+import { type ActivationState, ActivationStateSchema } from "./types.js";
 
 /**
  * Load the activation state for a conversation, or `null` if no row exists.
@@ -123,16 +119,18 @@ export function forkActivationState(
 }
 
 /**
- * Drop `everInjected` entries whose `turn` is at or below `upToTurn`.
- * Used after compaction evicts older turns — slugs that lived only on those
- * turns become eligible for re-injection on the next turn.
+ * Clear all `everInjected` entries. Used after compaction: the cached
+ * `<memory>` attachments those slugs lived on are gone, so future turns
+ * should be free to re-inject them.
+ *
+ * Unconditionally empties the list rather than filtering by turn number.
+ * `everInjected` is persisted on every turn while the in-memory tracker's
+ * `currentTurn` is only snapshotted on graceful conversation dispose, so a
+ * non-graceful shutdown (SIGKILL, crash) followed by a reload can leave
+ * `everInjected` entries with `turn` values above the restored tracker's
+ * `currentTurn`. A turn-bounded filter misses those stale entries and they
+ * dedupe forever; a full clear is robust to that drift.
  */
-export function evictCompactedTurns(
-  state: ActivationState,
-  upToTurn: number,
-): ActivationState {
-  const everInjected: EverInjectedEntry[] = state.everInjected.filter(
-    (entry) => entry.turn > upToTurn,
-  );
-  return { ...state, everInjected };
+export function clearEverInjected(state: ActivationState): ActivationState {
+  return { ...state, everInjected: [] };
 }

package/src/memory/v2/cli-command-content.ts

@@ -0,0 +1,19 @@
+/**
+ * Render the prose-style capability statement embedded into the unified
+ * `memory_v2_concept_pages` Qdrant collection (under the `cli-commands/<name>`
+ * slug prefix). Mirrors `buildSkillContent` in shape — a short prose lead-in
+ * followed by the dense capability material — so activation scoring weighs
+ * both natural-language intent and structured help text.
+ *
+ * Intentionally uncapped: CLI `--help` output averages 1–2 KB and the longest
+ * (browser, oauth) hits ~3.4 KB. The embedding backend handles inputs of this
+ * size without trouble, and trimming would drop the very examples and flag
+ * descriptions that make commands semantically findable.
+ */
+export function buildCliCommandContent(
+  name: string,
+  description: string,
+  helpText: string,
+): string {
+  return `The "assistant ${name}" CLI command is available. ${description}.\n\nFull help:\n${helpText}`;
+}