@vellumai/assistant 0.10.3-staging.2 → 0.10.4-staging.1

package/src/plugins/defaults/memory-v3-shadow/__tests__/section-dense-store.test.ts

@@ -14,21 +14,109 @@ mock.module("../../../../memory/qdrant-client.js", () => ({
 
 // Stub the shared embedding backend. Records inputs and returns one
 // deterministic vector per input so `upsertSections` can map vectors → points.
+// `statusProvider/Model` is what `getMemoryBackendStatus` reports (the cache-read
+// identity); `embedProvider/Model` is what `embedWithBackend` returns — kept
+// separate so a test can simulate a provider rotation between the two.
 const embedState = {
   calls: [] as string[][],
   dim: 4,
+  statusProvider: "local" as string | null,
+  statusModel: "test-model" as string | null,
+  embedProvider: "local",
+  embedModel: "test-model",
+  // Gemini embedding options that change the vector for identical text. The
+  // mocked `geminiCacheExtras` renders these into cache-key fragments exactly
+  // as the production helper does, so a test can flip the task type and assert
+  // the section cache treats it as a miss.
+  geminiTaskType: undefined as string | undefined,
+  geminiDimensions: undefined as number | undefined,
 };
 mock.module("../../../../memory/embedding-backend.js", () => ({
+  getMemoryBackendStatus: async () => ({
+    enabled: true,
+    degraded: false,
+    provider: embedState.statusProvider,
+    model: embedState.statusModel,
+    reason: null,
+  }),
   embedWithBackend: async (_config: unknown, inputs: string[]) => {
     embedState.calls.push(inputs);
     return {
-      provider: "local",
-      model: "test-model",
+      provider: embedState.embedProvider,
+      model: embedState.embedModel,
       vectors: inputs.map((_input, i) =>
         Array.from({ length: embedState.dim }, (_v, j) => (i + 1) * (j + 1)),
       ),
     };
   },
+  geminiCacheExtras: () => {
+    const extras: string[] = [];
+    if (embedState.geminiTaskType) {
+      extras.push(`task=${embedState.geminiTaskType}`);
+    }
+    if (embedState.geminiDimensions != null) {
+      extras.push(`dim=${embedState.geminiDimensions}`);
+    }
+    return extras;
+  },
+}));
+
+// In-memory stand-in for the `memory_embeddings` dense cache. Lets each test
+// program hits/misses without a real DB; keyed exactly as the production helper
+// (`targetType|targetId|provider|model`) with a stored dimension for the
+// dim-match gate. `getDb` is stubbed to a sentinel since the mock ignores it.
+const cacheState = {
+  store: new Map<
+    string,
+    { dense: number[]; contentHash: string; dimensions: number }
+  >(),
+  reads: [] as string[],
+};
+function cacheKey(k: {
+  targetType: string;
+  targetId: string;
+  provider: string;
+  model: string;
+}): string {
+  return `${k.targetType}|${k.targetId}|${k.provider}|${k.model}`;
+}
+mock.module("../../../../memory/embedding-cache.js", () => ({
+  readEmbeddingCache: (
+    _db: unknown,
+    key: {
+      targetType: string;
+      targetId: string;
+      provider: string;
+      model: string;
+      expectedDim: number;
+    },
+  ) => {
+    cacheState.reads.push(cacheKey(key));
+    const row = cacheState.store.get(cacheKey(key));
+    if (!row || row.dimensions !== key.expectedDim) return null;
+    return { dense: row.dense, contentHash: row.contentHash };
+  },
+  writeEmbeddingCache: (
+    _db: unknown,
+    params: {
+      targetType: string;
+      targetId: string;
+      provider: string;
+      model: string;
+      dense: number[];
+      contentHash: string;
+    },
+  ) => {
+    cacheState.store.set(cacheKey(params), {
+      dense: params.dense,
+      contentHash: params.contentHash,
+      dimensions: params.dense.length,
+    });
+  },
+}));
+
+mock.module("../../../../memory/db-connection.js", () => ({
+  getDb: () => ({}),
 }));
 
 // Mock the underlying @qdrant/js-client-rest package. The mock client records
@@ -159,6 +247,14 @@ function resetState(): void {
   state.scrollCalls.length = 0;
   embedState.calls.length = 0;
   embedState.dim = 4;
+  embedState.statusProvider = "local";
+  embedState.statusModel = "test-model";
+  embedState.embedProvider = "local";
+  embedState.embedModel = "test-model";
+  embedState.geminiTaskType = undefined;
+  embedState.geminiDimensions = undefined;
+  cacheState.store.clear();
+  cacheState.reads.length = 0;
   _resetSectionDenseStoreForTests();
 }
 
@@ -376,6 +472,151 @@ describe("memory v3 section-dense-store — upsert", () => {
   });
 });
 
+describe("memory v3 section-dense-store — embedding cache", () => {
+  beforeEach(resetState);
+  afterEach(resetState);
+
+  test("re-upserting unchanged sections serves from cache (no second embed)", async () => {
+    state.collectionExists = true;
+    const sections = [
+      section("people/alice", 0, "alice lead text"),
+      section("people/alice", 1, "alice section one"),
+    ];
+
+    await upsertSections(CONFIG, sections);
+    expect(embedState.calls).toHaveLength(1); // cold cache → embedded once
+
+    await upsertSections(CONFIG, sections);
+    // No new backend call — the second pass reused both cached vectors.
+    expect(embedState.calls).toHaveLength(1);
+    // But the points were still upserted (rebuilt from cache), with identical
+    // vectors to the first pass.
+    expect(state.upsertCalls).toHaveLength(2);
+    expect(state.upsertCalls[1]!.points.map((p) => p.vector)).toEqual(
+      state.upsertCalls[0]!.points.map((p) => p.vector),
+    );
+  });
+
+  test("a changed section text re-embeds (content hash differs)", async () => {
+    state.collectionExists = true;
+
+    await upsertSections(CONFIG, [section("people/alice", 0, "text A")]);
+    await upsertSections(CONFIG, [section("people/alice", 0, "text B")]);
+
+    expect(embedState.calls).toEqual([["text A"], ["text B"]]);
+  });
+
+  test("partial hit embeds only the changed section, upserts both", async () => {
+    state.collectionExists = true;
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "lead"),
+      section("people/alice", 1, "one"),
+    ]);
+    embedState.calls.length = 0;
+
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "lead"), // unchanged → cache hit
+      section("people/alice", 1, "one changed"), // changed → miss
+    ]);
+
+    // Only the changed section's text reached the backend.
+    expect(embedState.calls).toEqual([["one changed"]]);
+    // Both points (cached + freshly embedded) were upserted.
+    expect(state.upsertCalls.at(-1)!.points).toHaveLength(2);
+  });
+
+  test("no resolved provider skips the cache and embeds every section", async () => {
+    state.collectionExists = true;
+    embedState.statusProvider = null;
+    embedState.statusModel = null;
+
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "x"),
+      section("people/alice", 1, "y"),
+    ]);
+
+    // Without an embedding identity the cache cannot be keyed, so it is never
+    // read and every section is embedded — matching the pre-cache behavior.
+    expect(cacheState.reads).toEqual([]);
+    expect(embedState.calls).toEqual([["x", "y"]]);
+  });
+
+  test("a provider rotation re-embeds the whole batch under the new identity", async () => {
+    state.collectionExists = true;
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "lead"),
+      section("people/alice", 1, "one"),
+    ]);
+    embedState.calls.length = 0;
+
+    // The cache-read identity still resolves to local/test-model (so section 0
+    // is a hit), but the backend now answers as a different provider.
+    embedState.embedProvider = "openai";
+    embedState.embedModel = "text-embedding-3";
+
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "lead"), // hit under the old identity
+      section("people/alice", 1, "one changed"), // miss
+    ]);
+
+    // First the misses are embedded; the rotated provider on that response
+    // forces a full re-embed of every section so the collection stays in one
+    // embedding space.
+    expect(embedState.calls).toEqual([
+      ["one changed"],
+      ["lead", "one changed"],
+    ]);
+  });
+
+  test("a Gemini task-type change re-embeds unchanged text (cache miss)", async () => {
+    state.collectionExists = true;
+    embedState.statusProvider = "gemini";
+    embedState.statusModel = "gemini-embedding-2";
+    embedState.embedProvider = "gemini";
+    embedState.embedModel = "gemini-embedding-2";
+    embedState.geminiTaskType = "RETRIEVAL_DOCUMENT";
+
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "alice lead text"),
+    ]);
+    expect(embedState.calls).toHaveLength(1); // cold cache → embedded once
+
+    // Same text, same provider/model — but a different Gemini task type yields a
+    // different vector, so the row cached under the old task type must not be
+    // served. The extras are folded into the content hash, so the comparison
+    // misses and the section re-embeds under the new task type.
+    embedState.geminiTaskType = "SEMANTIC_SIMILARITY";
+
+    await upsertSections(CONFIG, [
+      section("people/alice", 0, "alice lead text"),
+    ]);
+
+    expect(embedState.calls).toEqual([
+      ["alice lead text"],
+      ["alice lead text"],
+    ]);
+  });
+
+  test("an unchanged Gemini task type still serves from cache (no spurious miss)", async () => {
+    state.collectionExists = true;
+    embedState.statusProvider = "gemini";
+    embedState.statusModel = "gemini-embedding-2";
+    embedState.embedProvider = "gemini";
+    embedState.embedModel = "gemini-embedding-2";
+    embedState.geminiTaskType = "RETRIEVAL_DOCUMENT";
+
+    const sections = [section("people/alice", 0, "alice lead text")];
+
+    await upsertSections(CONFIG, sections);
+    await upsertSections(CONFIG, sections);
+
+    // Folding the extras into the hash must not break ordinary hits: with the
+    // task type unchanged the second pass reuses the cached vector.
+    expect(embedState.calls).toHaveLength(1);
+    expect(state.upsertCalls).toHaveLength(2);
+  });
+});
+
 describe("memory v3 section-dense-store — delete", () => {
   beforeEach(resetState);
   afterEach(resetState);

package/src/plugins/defaults/memory-v3-shadow/section-dense-store.ts

@@ -19,11 +19,23 @@
 // shared Qdrant client; the read side (`dense.ts`) reuses that client to query
 // this collection.
 
+import { createHash } from "node:crypto";
+
 import { QdrantClient as QdrantRestClient } from "@qdrant/js-client-rest";
 import { v5 as uuidv5 } from "uuid";
 
 import type { AssistantConfig } from "../../../config/types.js";
-import { embedWithBackend } from "../../../memory/embedding-backend.js";
+import { getDb } from "../../../memory/db-connection.js";
+import {
+  embedWithBackend,
+  geminiCacheExtras,
+  getMemoryBackendStatus,
+} from "../../../memory/embedding-backend.js";
+import {
+  readEmbeddingCache,
+  writeEmbeddingCache,
+} from "../../../memory/embedding-cache.js";
+import { embeddingInputContentHash } from "../../../memory/embedding-types.js";
 import { resolveQdrantUrl } from "../../../memory/qdrant-client.js";
 import { getLogger } from "../../../util/logger.js";
 import type { Section } from "./types.js";
@@ -166,6 +178,34 @@ export async function ensureSectionCollection(
   _collectionReady = true;
 }
 
+/**
+ * `target_type` marker on `memory_embeddings` rows that cache section vectors.
+ * Distinct from the v2 `concept_page` rows so the two caches never collide on a
+ * shared `(targetType, targetId, provider, model)` key.
+ */
+const V3_SECTION_TARGET_TYPE = "v3_section";
+
+/** Human-readable cache id for a section: `<article>#<ordinal>`. */
+function sectionCacheId(article: string, ordinal: number): string {
+  return `${article}#${ordinal}`;
+}
+
+/**
+ * Content hash a section's cached vector is keyed by. Folds the provider's
+ * embedding-option extras (Gemini task type / output dimensions) into the base
+ * text hash, so changing an option that alters the vector for identical text is
+ * a cache miss that re-embeds. With no extras the bare text hash is returned
+ * unchanged, keeping existing rows valid for non-Gemini and default-Gemini
+ * configs.
+ */
+function sectionContentHash(text: string, extras: string[]): string {
+  const base = embeddingInputContentHash({ type: "text", text });
+  if (extras.length === 0) return base;
+  return createHash("sha256")
+    .update(`${base}\0${extras.join("\0")}`)
+    .digest("hex");
+}
+
 /**
  * Embed each section's `text` and upsert one point per section, keyed by a
  * deterministic `(article, ordinal)`-derived ID. Stable IDs mean re-upserting
@@ -173,6 +213,10 @@ export async function ensureSectionCollection(
  * so the operation is idempotent. Payload carries `{ article, ordinal, title }`
  * for downstream filtering and rendering.
  *
+ * Unchanged sections are served from the `memory_embeddings` cache rather than
+ * re-embedded — see {@link embedSectionsCached} — so a maintain pass that
+ * re-selects an already-embedded page makes no backend round-trip for it.
+ *
  * An empty `sections` array is a no-op (no embedding round-trip).
  */
 export async function upsertSections(
@@ -183,20 +227,25 @@ export async function upsertSections(
 
   await ensureSectionCollection(config);
 
-  const { vectors } = await embedWithBackend(
-    config,
-    sections.map((s) => s.text),
-  );
+  const vectors = await embedSectionsCached(config, sections);
+
+  const points = sections.flatMap((section, i) => {
+    const vector = vectors[i];
+    if (!vector) return [];
+    return [
+      {
+        id: pointIdForSection(section.article, section.ordinal),
+        vector,
+        payload: {
+          article: section.article,
+          ordinal: section.ordinal,
+          title: section.title,
+        },
+      },
+    ];
+  });
 
-  const points = sections.map((section, i) => ({
-    id: pointIdForSection(section.article, section.ordinal),
-    vector: vectors[i]!,
-    payload: {
-      article: section.article,
-      ordinal: section.ordinal,
-      title: section.title,
-    },
-  }));
+  if (points.length === 0) return;
 
   await getSectionDenseClient(config).upsert(SECTION_COLLECTION, {
     wait: true,
@@ -204,6 +253,110 @@ export async function upsertSections(
   });
 }
 
+/**
+ * Resolve a dense vector per section, reusing cached vectors for sections whose
+ * `text` is unchanged and embedding only the misses in a single batched backend
+ * call. Returns one entry per input section, index-aligned; a position is left
+ * `undefined` only when a fresh embed produced no vector for it.
+ *
+ * The cache lives in the shared `memory_embeddings` table keyed on
+ * `(targetType="v3_section", targetId="<article>#<ordinal>", provider, model)`.
+ * It survives the `deleteSectionsForArticle` callers run before upserting (that
+ * delete clears only Qdrant points), so an unchanged section rebuilds its point
+ * from the cache without a backend round-trip. Vectors are stored and upserted
+ * raw — the section dense lane applies no anisotropy correction, so the cached
+ * vector equals the upserted one.
+ */
+async function embedSectionsCached(
+  config: AssistantConfig,
+  sections: Section[],
+): Promise<Array<number[] | undefined>> {
+  const expectedDim = config.memory.qdrant.vectorSize;
+
+  // Cache identity: read rows under the currently-selected provider/model. When
+  // no provider resolves (backend down/disabled) skip the cache and let the
+  // batched embed below surface the failure exactly as the uncached path did.
+  const status = await getMemoryBackendStatus(config);
+  const db = getDb();
+
+  // Only Gemini's options change the vector for identical text, so fold the
+  // extras into the cache identity only when Gemini is the resolved provider;
+  // other backends keep the bare text hash. See {@link sectionContentHash}.
+  const extras = status.provider === "gemini" ? geminiCacheExtras(config) : [];
+  const hashes = sections.map((s) => sectionContentHash(s.text, extras));
+
+  const result: Array<number[] | undefined> = new Array(sections.length);
+  const missIndices: number[] = [];
+  if (status.provider && status.model) {
+    for (let i = 0; i < sections.length; i++) {
+      const section = sections[i]!;
+      const cached = readEmbeddingCache(db, {
+        targetType: V3_SECTION_TARGET_TYPE,
+        targetId: sectionCacheId(section.article, section.ordinal),
+        provider: status.provider,
+        model: status.model,
+        expectedDim,
+      });
+      if (cached && cached.contentHash === hashes[i]) {
+        result[i] = cached.dense;
+      } else {
+        missIndices.push(i);
+      }
+    }
+  } else {
+    for (let i = 0; i < sections.length; i++) missIndices.push(i);
+  }
+
+  if (missIndices.length === 0) return result;
+
+  // Embed the misses in one batched call (the dominant cost).
+  let embedded = await embedWithBackend(
+    config,
+    missIndices.map((i) => sections[i]!.text),
+  );
+  let writeProvider = embedded.provider;
+  let writeModel = embedded.model;
+  let effectiveIndices = missIndices;
+
+  // A provider/model rotation between the cache read and the embed would mix two
+  // embedding spaces in one collection: cached hits carry the old identity, the
+  // fresh misses the new. Re-embed every section under the new identity so the
+  // whole batch (and the cache rows it writes) shares one space.
+  const hadHits = missIndices.length < sections.length;
+  const rotated =
+    hadHits &&
+    (embedded.provider !== status.provider || embedded.model !== status.model);
+  if (rotated) {
+    effectiveIndices = sections.map((_, i) => i);
+    embedded = await embedWithBackend(
+      config,
+      sections.map((s) => s.text),
+    );
+    writeProvider = embedded.provider;
+    writeModel = embedded.model;
+  }
+
+  const now = Date.now();
+  for (let j = 0; j < effectiveIndices.length; j++) {
+    const i = effectiveIndices[j]!;
+    const vector = embedded.vectors[j];
+    if (!vector) continue;
+    result[i] = vector;
+    const section = sections[i]!;
+    writeEmbeddingCache(db, {
+      targetType: V3_SECTION_TARGET_TYPE,
+      targetId: sectionCacheId(section.article, section.ordinal),
+      dense: vector,
+      contentHash: hashes[i]!,
+      provider: writeProvider,
+      model: writeModel,
+      now,
+    });
+  }
+
+  return result;
+}
+
 /**
  * Delete every section point belonging to an article. Used by incremental
  * rebuilds (in a later PR) to clear an article's stale sections before

package/src/plugins/disabled-state.ts

@@ -0,0 +1,31 @@
+/**
+ * Plugin disabled-state check.
+ *
+ * A plugin is disabled when a `.disabled` sentinel file exists inside its
+ * workspace plugin directory (`<workspace>/plugins/<name>/.disabled`). This
+ * is the single source of truth for the enabled/disabled state of both
+ * user-installed and default plugins.
+ *
+ * Each surface that exposes plugin contributions (hooks, tools, routes) calls
+ * {@link isPluginDisabled} at read time so that toggling a plugin via the CLI
+ * (`assistant plugins disable/enable <name>`) takes effect on the next turn
+ * without a daemon restart.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { getWorkspacePluginsDir } from "../util/platform.js";
+
+/**
+ * Return `true` when the `.disabled` sentinel exists for `pluginName`.
+ *
+ * The check is a synchronous `existsSync` — the same primitive already used
+ * by `scanPlugins` and `bootstrapPlugins`. It is cheap (one `stat` syscall)
+ * and does not need caching for the current call pattern: `getHooksFor` is
+ * invoked a handful of times per turn, one per hook event, and the number of
+ * default plugins is small.
+ */
+export function isPluginDisabled(pluginName: string): boolean {
+  return existsSync(join(getWorkspacePluginsDir(), pluginName, ".disabled"));
+}

package/src/plugins/registry.ts

@@ -19,6 +19,7 @@
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
+import { isPluginDisabled } from "./disabled-state.js";
 import { getUserHooksFor } from "./mtime-cache.js";
 import {
   type HookFunction,
@@ -35,6 +36,25 @@ import {
  */
 const registeredPlugins = new Map<string, Plugin>();
 
+/**
+ * Hook registry — the per-surface registry for default plugin hooks. Each
+ * hook name maps to an ordered list of `{fn, pluginName}` entries, one per
+ * plugin that contributes that hook. The list order matches registration
+ * order (i.e. {@link getAllDefaultPlugins} array order), which fixes
+ * hook-chain ordering the same way the old `registeredPlugins` map did.
+ *
+ * Populated by {@link registerPlugin} alongside `registeredPlugins` and
+ * depleted by {@link unregisterPlugin}. {@link getHooksFor} reads from this
+ * map (not `registeredPlugins`) so it can filter disabled plugins at read
+ * time via {@link isPluginDisabled} — the key mechanism that makes
+ * `assistant plugins disable default-*` take effect immediately in a
+ * running assistant.
+ */
+const hookRegistry = new Map<
+  string,
+  Array<{ fn: HookFunction; pluginName: string }>
+>();
+
 /**
  * Latch that closes the per-boot registration window. Flipped to `true` by
  * {@link closeRegistration} once `loadUserPlugins()` has returned. After that,
@@ -126,6 +146,22 @@ export function registerPlugin(plugin: Plugin): void {
   }
 
   registeredPlugins.set(name, plugin);
+
+  // Register each hook into the per-surface hook registry. `getHooksFor`
+  // reads from this map (filtered by `isPluginDisabled`) rather than from
+  // `registeredPlugins`, so toggling the `.disabled` sentinel at runtime
+  // takes effect on the next turn without mutating the plugin registry.
+  if (plugin.hooks) {
+    for (const [hookName, fn] of Object.entries(plugin.hooks)) {
+      if (typeof fn !== "function") continue;
+      let list = hookRegistry.get(hookName);
+      if (!list) {
+        list = [];
+        hookRegistry.set(hookName, list);
+      }
+      list.push({ fn: fn as HookFunction, pluginName: name });
+    }
+  }
 }
 
 // ─── Queries ─────────────────────────────────────────────────────────────────
@@ -159,12 +195,14 @@ export function getRegisteredPlugins(): Plugin[] {
 export async function getHooksFor<TCtx = unknown>(
   name: string,
 ): Promise<HookFunction<TCtx>[]> {
-  // First-party defaults from the registry (synchronous).
+  // First-party defaults from the hook registry, filtered by the `.disabled`
+  // sentinel at read time. This is what makes `assistant plugins disable
+  // default-*` take effect immediately in a running assistant: the hooks stay
+  // registered but are filtered out on the next turn.
   const defaultHooks: HookFunction<TCtx>[] = [];
-  for (const plugin of registeredPlugins.values()) {
-    const hook = plugin.hooks?.[name];
-    if (hook) {
-      defaultHooks.push(hook as HookFunction<TCtx>);
+  for (const entry of hookRegistry.get(name) ?? []) {
+    if (!isPluginDisabled(entry.pluginName)) {
+      defaultHooks.push(entry.fn as HookFunction<TCtx>);
     }
   }
 
@@ -199,14 +237,18 @@ export function closeRegistration(): void {
  */
 export function unregisterPlugin(name: string): void {
   registeredPlugins.delete(name);
-}
-
-export function getRegisteredPlugin(name: string): Plugin | undefined {
-  return registeredPlugins.get(name);
-}
 
-export function setRegisteredPlugin(plugin: Plugin): void {
-  registeredPlugins.set(plugin.manifest.name, plugin);
+  // Remove all hooks contributed by this plugin from the hook registry.
+  // Used by the bootstrap failure path (init threw) and the feature-flag
+  // skip path — both are boot-time decisions where the plugin's hooks should
+  // never participate in the turn lifecycle.
+  for (const [, list] of hookRegistry) {
+    for (let i = list.length - 1; i >= 0; i--) {
+      if (list[i]!.pluginName === name) {
+        list.splice(i, 1);
+      }
+    }
+  }
 }
 
 // ─── Test hooks ──────────────────────────────────────────────────────────────
@@ -228,6 +270,7 @@ export function resetPluginRegistryForTests(): void {
     );
   }
   registeredPlugins.clear();
+  hookRegistry.clear();
   // Re-open the registration window so subsequent tests can register plugins
   // again. Without this, the latch set by a prior `closeRegistration()` call
   // would leak across test cases and reject legitimate registrations.