@vellumai/assistant 0.10.1 → 0.10.2-dev.202606241651.2d2b40d

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

@@ -619,6 +619,86 @@ Write a local article draft.
     expect(after).toEqual(before);
   });
 
+  test("populates the cache from the local catalog on the first seed even when the embedding backend is unavailable (cold-start needle resilience)", async () => {
+    // Regression: on a brand-new managed assistant the startup seed runs before
+    // the platform provisions the managed embedding credential, so the very
+    // first `embedWithBackend` throws. The in-memory cache (which the v3 needle
+    // lane and the page index read) must still populate from the local catalog
+    // so skills are discoverable from first boot; only the dense Qdrant upsert
+    // is deferred until the backend recovers.
+    const skillA = makeSummary({
+      id: "example-skill-a",
+      displayName: "Skill A",
+    });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    // No prior successful seed — the backend is unconfigured from the start.
+    state.embedThrows = new Error(
+      'Embedding backend "gemini" is not configured',
+    );
+
+    // Best-effort callers (the startup seed) must resolve.
+    await expect(seedV2SkillEntries()).resolves.toBeUndefined();
+
+    // The needle-lane cache is populated despite the dense-embed failure.
+    const entry = getSkillCapability("example-skill-a");
+    expect(entry).not.toBeNull();
+    expect(entry?.id).toBe("example-skill-a");
+    expect(entry?.content).toContain("Skill A");
+    expect(listSkillEntries().map((e) => e.id)).toEqual(["example-skill-a"]);
+
+    // No dense vectors were produced, so the Qdrant write is skipped entirely.
+    expect(state.upsertCalls).toHaveLength(0);
+    expect(state.pruneCalls).toHaveLength(0);
+  });
+
+  test("surfaces the dense-embed failure to throwOnError callers while still populating the needle cache", async () => {
+    // The managed-credential reseed and the operator reembed route pass
+    // `throwOnError` so they learn the dense lane didn't complete and the
+    // retry/maintain machinery backfills it — but the needle cache is fixed
+    // regardless before the error propagates.
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.embedThrows = new Error("backend down");
+
+    await expect(seedV2SkillEntries({ throwOnError: true })).rejects.toThrow(
+      "backend down",
+    );
+
+    expect(getSkillCapability("example-skill-a")).not.toBeNull();
+    expect(state.upsertCalls).toHaveLength(0);
+  });
+
+  test("drops a locally-disabled installed skill even when the catalog is unavailable (local state is authoritative)", async () => {
+    // Regression: the local resolution is authoritative, so a skill that is
+    // still installed but explicitly disabled must NOT be kept alive by remote-
+    // catalog uncertainty — `getSkillCapability` and the page index must drop it.
+    const skillA = makeSummary({ id: "example-skill-a" });
+    state.catalog = [skillA];
+    state.resolved = [{ summary: skillA, state: "enabled" }];
+    state.fullCatalog = [
+      { id: "example-skill-a", name: "example-skill-a", description: "A" },
+    ];
+    state.embedReturn = [[0.1, 0.2, 0.3]];
+
+    // First run: skillA enabled and cached.
+    await seedV2SkillEntries();
+    expect(getSkillCapability("example-skill-a")).not.toBeNull();
+
+    // Second run: skillA is still locally installed but now disabled; the remote
+    // catalog is unavailable. It stays in `installedIds`, so the carry-forward
+    // must skip it and the cache drops it.
+    state.resolved = [{ summary: skillA, state: "disabled" }];
+    state.fullCatalog = [];
+    state.fullCatalogThrows = new Error("catalog fetch failed");
+
+    await seedV2SkillEntries();
+
+    expect(getSkillCapability("example-skill-a")).toBeNull();
+    expect(listSkillEntries()).toEqual([]);
+  });
+
   test("no enabled skills yields empty cache and no prune when catalog is empty", async () => {
     state.catalog = [];
     state.resolved = [];

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

@@ -161,22 +161,23 @@ async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
       seeds.push({ id: name, description, content });
     }
 
+    // Sparse (BM25/TF) encoding is computed locally; only the dense vectors
+    // require `embedWithBackend`, which is unconfigured during the cold-start
+    // window before a managed-proxy embedding credential is provisioned. A
+    // dense-embed failure is non-fatal to the in-memory cache: the v3 needle
+    // finder lane reads CLI capabilities from `entries` / the page index, NOT
+    // from Qdrant, so the cache is populated from the local Commander tree
+    // regardless of backend state and commands stay discoverable from first
+    // boot. Only the dense Qdrant upsert is skipped; the managed-credential
+    // reseed and the v3 maintain pass backfill the dense vectors on recovery.
     const nextEntries = new Map<string, CliCommandEntry>();
     let denseVectors: number[][] = [];
+    let denseAvailable = false;
+    let denseError: unknown = null;
     let encodeSparse: (
       input: string,
     ) => ReturnType<typeof generateSparseEmbedding> = generateSparseEmbedding;
     if (seeds.length > 0) {
-      const embedded = await embedWithBackend(
-        config,
-        seeds.map((s) => s.content),
-      );
-      denseVectors = await Promise.all(
-        embedded.vectors.map((v) =>
-          applyCorrectionIfCalibrated(v, embedded.provider, embedded.model),
-        ),
-      );
-
       // CLI commands share the concept-page Qdrant collection, so the sparse
       // vector must use the same stemmed BM25 encoding as the concept-page
       // documents. Fall back to the legacy TF encoder only during the cold-
@@ -190,6 +191,24 @@ async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
               b: config.memory.v2.bm25_b,
             })
           : generateSparseEmbedding(input);
+      try {
+        const embedded = await embedWithBackend(
+          config,
+          seeds.map((s) => s.content),
+        );
+        denseVectors = await Promise.all(
+          embedded.vectors.map((v) =>
+            applyCorrectionIfCalibrated(v, embedded.provider, embedded.model),
+          ),
+        );
+        denseAvailable = true;
+      } catch (err) {
+        denseError = err;
+        log.warn(
+          { err },
+          "Embedding backend unavailable — seeding CLI-command cache without dense Qdrant vectors; the needle lane surfaces commands from the cache and the dense lane backfills when the backend recovers",
+        );
+      }
     }
 
     if (generation !== requestedSeedGeneration) {
@@ -201,7 +220,17 @@ async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
       return;
     }
 
-    if (seeds.length > 0) {
+    // Populate the in-memory cache (and therefore the page index / needle lane)
+    // from the local Commander tree regardless of dense availability.
+    for (const seed of seeds) {
+      nextEntries.set(seed.id, seed);
+    }
+
+    // Write the dense+sparse Qdrant points only when dense vectors were
+    // produced. In the degraded (backend-unavailable) path we skip the upsert
+    // so we never write half-formed points; the dense lane backfills on
+    // recovery.
+    if (seeds.length > 0 && denseAvailable) {
       const now = Date.now();
       await Promise.all(
         seeds.map((seed, i) =>
@@ -214,40 +243,48 @@ async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
           }),
         ),
       );
-      for (const seed of seeds) {
-        nextEntries.set(seed.id, seed);
-      }
     }
 
-    // The CLI tree is always available (no remote catalog), so pruning is
-    // unconditional. Run the legacy `kind` backfill once per process so
-    // pre-discriminator rows become prunable.
-    const knownIds = new Set(seeds.map((s) => s.id));
-    if (!legacyKindBackfillDone) {
-      try {
-        await backfillKindOnPointsWithPrefix(
-          CLI_COMMAND_SLUG_PREFIX,
-          CLI_COMMAND_PAYLOAD_KIND,
-          knownIds,
-        );
-        legacyKindBackfillDone = true;
-      } catch (err) {
-        log.warn(
-          { err },
-          "Failed to backfill kind on legacy CLI-command points — pruning may leave orphans this run",
-        );
+    // The CLI tree is always available (no remote catalog), so pruning to clear
+    // stale rows runs whenever we wrote the current set this run OR there was
+    // nothing to embed (empty tree). The cold-start degraded path (commands
+    // present but dense embedding unavailable) skips the prune so we never
+    // reconcile the collection against a set we did not persist. Run the legacy
+    // `kind` backfill once per process so pre-discriminator rows become prunable.
+    if (denseAvailable || seeds.length === 0) {
+      const knownIds = new Set(seeds.map((s) => s.id));
+      if (!legacyKindBackfillDone) {
+        try {
+          await backfillKindOnPointsWithPrefix(
+            CLI_COMMAND_SLUG_PREFIX,
+            CLI_COMMAND_PAYLOAD_KIND,
+            knownIds,
+          );
+          legacyKindBackfillDone = true;
+        } catch (err) {
+          log.warn(
+            { err },
+            "Failed to backfill kind on legacy CLI-command points — pruning may leave orphans this run",
+          );
+        }
       }
+      await pruneSlugsWithPrefixExcept(
+        CLI_COMMAND_SLUG_PREFIX,
+        seeds.map((s) => s.id),
+        { kind: CLI_COMMAND_PAYLOAD_KIND },
+      );
     }
-    await pruneSlugsWithPrefixExcept(
-      CLI_COMMAND_SLUG_PREFIX,
-      seeds.map((s) => s.id),
-      { kind: CLI_COMMAND_PAYLOAD_KIND },
-    );
 
-    // Atomically replace the cache only after every step above succeeds.
+    // Atomically replace the cache from the freshly enumerated commands. Drop
+    // the page-index cache so the next router invocation observes the new
+    // command set.
     entries = nextEntries;
     invalidatePageIndex();
-    lastSeedError = null;
+
+    // Surface a dense-embed failure to `throwOnError` callers so the existing
+    // retry + maintain machinery backfills the dense lane. The in-memory cache
+    // is already updated above, so the needle lane is fixed regardless.
+    lastSeedError = denseError;
   } catch (err) {
     lastSeedError = err;
     log.warn({ err }, "Failed to seed v2 CLI-command entries");

package/src/memory/v2/prompts/consolidation.ts

@@ -18,12 +18,9 @@
  * the convention established for the sweep prompt.
  */
 
-import { lstatSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
-
 import { getLogger } from "../../../util/logger.js";
 import { getWorkspaceDir } from "../../../util/platform.js";
+import { loadPromptOverride } from "../../prompt-override.js";
 
 const log = getLogger("memory-v2-consolidate-prompt");
 
@@ -61,14 +58,6 @@ export const CORE_PAGES_CONSOLIDATION_SECTION = `## 10. Review \`memory/core-pag
 
 `;
 
-/**
- * Upper bound for the override file. Real consolidation prompts are kilobytes;
- * 1 MiB is generous headroom while preventing a `settings.write` principal from
- * pointing the field at a multi-gigabyte file (or `/dev/zero`-like stream that
- * `lstat` can't size cap on its own) and exfiltrating it through the wake hint.
- */
-const MAX_PROMPT_BYTES = 1 * 1024 * 1024;
-
 /**
  * Consolidation prompt — live-mode only. The agent runs as itself (full
  * SOUL.md + IDENTITY.md + persona + memory autoloads) with the standard
@@ -837,90 +826,32 @@ export function renderConsolidationPrompt(
 /**
  * Load the consolidation prompt template, optionally overridden from the file
  * referenced by `memory.v2.consolidation_prompt_path`, then substitute
- * `{{CUTOFF}}`. Path-resolution rules are documented on the schema field.
+ * `{{CUTOFF}}`. File loading (path resolution, size guard, and the permissive
+ * fall-back to the bundled prompt on a missing/unreadable/empty/oversized
+ * override) is handled by the shared {@link loadPromptOverride}.
  *
  * Override files get the same placeholder substitutions as the bundled
  * template: `{{CUTOFF}}` always, and `{{CORE_PAGES_SECTION}}` per the same
  * flag gate — so a prompt copied from the bundled source never leaks a raw
  * placeholder, and a customized prompt can opt into the managed section.
- *
- * Failure handling is intentionally permissive — missing file, read error, or
- * empty/whitespace-only body all log a warning and fall back to the bundled
- * prompt. Consolidation must never break because of a bad override: the
- * daemon's startup philosophy is "log and recover."
  */
 export function resolveConsolidationPrompt(
   overridePath: string | null,
   cutoff: string,
   options: ConsolidationPromptOptions,
 ): string {
-  if (overridePath === null) return renderConsolidationPrompt(cutoff, options);
-
-  const resolvedPath = resolveOverridePath(overridePath);
-  let contents: string;
-  try {
-    const stat = lstatSync(resolvedPath);
-    if (!stat.isFile()) {
-      log.warn(
-        {
-          configuredPath: overridePath,
-          resolvedPath,
-          reason: "not_regular_file",
-          fallback: "bundled",
-        },
-        "consolidation prompt override is not a regular file; using bundled prompt",
-      );
-      return renderConsolidationPrompt(cutoff, options);
-    }
-    if (stat.size > MAX_PROMPT_BYTES) {
-      log.warn(
-        {
-          configuredPath: overridePath,
-          resolvedPath,
-          size: stat.size,
-          limit: MAX_PROMPT_BYTES,
-          reason: "oversized_override",
-          fallback: "bundled",
-        },
-        "consolidation prompt override exceeds size limit; using bundled prompt",
-      );
-      return renderConsolidationPrompt(cutoff, options);
-    }
-    contents = readFileSync(resolvedPath, "utf-8");
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    log.warn(
-      { configuredPath: overridePath, resolvedPath, code, fallback: "bundled" },
-      "consolidation prompt override unreadable; using bundled prompt",
-    );
-    return renderConsolidationPrompt(cutoff, options);
-  }
-
-  if (contents.trim().length === 0) {
-    log.warn(
-      {
-        configuredPath: overridePath,
-        resolvedPath,
-        reason: "empty_override",
-        fallback: "bundled",
-      },
-      "consolidation prompt override is empty; using bundled prompt",
-    );
-    return renderConsolidationPrompt(cutoff, options);
-  }
-
-  return contents
+  const override = loadPromptOverride({
+    overridePath,
+    workspaceDir: getWorkspaceDir(),
+    log,
+    label: "consolidation prompt",
+  });
+  if (override === null) return renderConsolidationPrompt(cutoff, options);
+
+  return override
     .replaceAll(CUTOFF_PLACEHOLDER, cutoff)
     .replaceAll(
       CORE_PAGES_PLACEHOLDER,
       options.includeCorePagesSection ? CORE_PAGES_CONSOLIDATION_SECTION : "",
     );
 }
-
-function resolveOverridePath(overridePath: string): string {
-  if (overridePath.startsWith("~/")) {
-    return join(homedir(), overridePath.slice(2));
-  }
-  if (isAbsolute(overridePath)) return overridePath;
-  return join(getWorkspaceDir(), overridePath);
-}

package/src/memory/v2/prompts/router.ts

@@ -22,22 +22,14 @@
  * same placeholder substitution applies to overrides.
  */
 
-import { lstatSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
-
 import { getLogger } from "../../../util/logger.js";
+import {
+  loadPromptOverride,
+  MAX_PROMPT_OVERRIDE_BYTES,
+} from "../../prompt-override.js";
 
 const log = getLogger("memory-v2-router-prompt");
 
-/**
- * Hard upper bound on the override file size. The bundled prompt is well
- * under 4 KiB; 1 MiB is generous-enough for any reasonable hand-edit while
- * still preventing pathological inputs from being slurped into memory on
- * every router call.
- */
-const MAX_PROMPT_BYTES = 1 * 1024 * 1024;
-
 /** Sentinel substituted with the assistant's display name at runtime. */
 const ASSISTANT_NAME_PLACEHOLDER = "{{ASSISTANT_NAME}}";
 
@@ -102,14 +94,12 @@ export function renderRouterPrompt(opts: RenderRouterPromptOpts): string {
 /**
  * Load the router prompt template, optionally overridden from the file
  * referenced by `memory.v2.router.router_prompt_path`, then substitute the
- * standard placeholders. Path-resolution rules mirror the consolidation
- * prompt override: absolute paths used as-is, leading `~/` expanded to home,
- * relative paths resolved under `workspaceDir`.
+ * standard placeholders. File loading (path resolution, size guard, and the
+ * permissive fall-back to the bundled prompt on a missing/unreadable/empty/
+ * oversized override) is handled by the shared {@link loadPromptOverride}.
  *
- * Failure handling is intentionally permissive — missing file, read error,
- * oversized file, or empty/whitespace-only body all log a warning and fall
- * back to the bundled prompt. Router selection must never break because of
- * a bad override.
+ * An `inlineOverride` (e.g. the simulator playground) takes precedence over the
+ * configured file path; same placeholder substitution and size guard apply.
  */
 export function resolveRouterPrompt(
   overridePath: string | null,
@@ -117,17 +107,15 @@ export function resolveRouterPrompt(
   opts: RenderRouterPromptOpts,
   inlineOverride?: string | null,
 ): string {
-  // Inline override (e.g. simulator playground) takes precedence over the
-  // configured file path and the bundled prompt. Same placeholder
-  // substitution + size guard as the file-path branch; empty/whitespace
-  // bodies fall through to file/bundled resolution so a "cleared" textarea
-  // is treated as no override.
+  // Inline override takes precedence over the configured file path and the
+  // bundled prompt. Empty/whitespace bodies fall through to file/bundled
+  // resolution so a "cleared" textarea is treated as no override.
   if (inlineOverride !== undefined && inlineOverride !== null) {
-    if (inlineOverride.length > MAX_PROMPT_BYTES) {
+    if (inlineOverride.length > MAX_PROMPT_OVERRIDE_BYTES) {
       log.warn(
         {
           size: inlineOverride.length,
-          limit: MAX_PROMPT_BYTES,
+          limit: MAX_PROMPT_OVERRIDE_BYTES,
           reason: "oversized_inline_override",
           fallback: "path_or_bundled",
         },
@@ -138,62 +126,13 @@ export function resolveRouterPrompt(
     }
   }
 
-  if (overridePath === null) return renderRouterPrompt(opts);
-
-  const resolvedPath = resolveOverridePath(overridePath, workspaceDir);
-  let contents: string;
-  try {
-    const stat = lstatSync(resolvedPath);
-    if (!stat.isFile()) {
-      log.warn(
-        {
-          configuredPath: overridePath,
-          resolvedPath,
-          reason: "not_regular_file",
-          fallback: "bundled",
-        },
-        "router prompt override is not a regular file; using bundled prompt",
-      );
-      return renderRouterPrompt(opts);
-    }
-    if (stat.size > MAX_PROMPT_BYTES) {
-      log.warn(
-        {
-          configuredPath: overridePath,
-          resolvedPath,
-          size: stat.size,
-          limit: MAX_PROMPT_BYTES,
-          reason: "oversized_override",
-          fallback: "bundled",
-        },
-        "router prompt override exceeds size limit; using bundled prompt",
-      );
-      return renderRouterPrompt(opts);
-    }
-    contents = readFileSync(resolvedPath, "utf-8");
-  } catch (err) {
-    const code = (err as NodeJS.ErrnoException).code;
-    log.warn(
-      { configuredPath: overridePath, resolvedPath, code, fallback: "bundled" },
-      "router prompt override unreadable; using bundled prompt",
-    );
-    return renderRouterPrompt(opts);
-  }
-
-  if (contents.trim().length === 0) {
-    log.warn(
-      {
-        configuredPath: overridePath,
-        resolvedPath,
-        reason: "empty_override",
-        fallback: "bundled",
-      },
-      "router prompt override is empty; using bundled prompt",
-    );
-    return renderRouterPrompt(opts);
-  }
-
-  return substitutePlaceholders(contents, opts);
+  const override = loadPromptOverride({
+    overridePath,
+    workspaceDir,
+    log,
+    label: "router prompt",
+  });
+  return substitutePlaceholders(override ?? ROUTER_PROMPT, opts);
 }
 
 function substitutePlaceholders(
@@ -207,14 +146,3 @@ function substitutePlaceholders(
     .replaceAll(USER_NAME_PLACEHOLDER, () => user)
     .replaceAll(PAGE_INDEX_PLACEHOLDER, () => opts.pageIndexBlock);
 }
-
-function resolveOverridePath(
-  overridePath: string,
-  workspaceDir: string,
-): string {
-  if (overridePath.startsWith("~/")) {
-    return join(homedir(), overridePath.slice(2));
-  }
-  if (isAbsolute(overridePath)) return overridePath;
-  return join(workspaceDir, overridePath);
-}