@vellumai/assistant 0.11.0 → 0.11.1-staging.1

package/src/persistence/embeddings/plugin-index.ts

@@ -0,0 +1,341 @@
+// ---------------------------------------------------------------------------
+// Plugin embeddings: compute-only primitives and a plugin-owned semantic index.
+// ---------------------------------------------------------------------------
+//
+// Host-side implementations behind the `@vellumai/plugin-api` embeddings
+// facade. They take the live workspace `config` and the calling plugin's
+// manifest name explicitly; the thin facade in `plugin-facade.ts` injects both
+// (`getConfig()` and `getCurrentPluginName()`) so plugins hold no config and
+// cannot spoof another plugin's namespace.
+//
+// Compute-only: embed / generateSparseEmbedding run the workspace embedding
+// backend and hand the raw vectors back with no persistence.
+//
+// Index: index / query / get / remove a document in a plugin-scoped Qdrant
+// namespace. Points are written into the shared host collection (the same one
+// `embedAndUpsert` uses) under a dedicated `plugin_index` target_type, tagged
+// with the owning plugin's name, and keyed by a namespace-qualified point id so
+// two plugins that pick the same documentId never collide. No recall lane
+// queries `plugin_index`, so this index never participates in agent recall: it
+// is search inside the plugin only.
+//
+// Durability: the index is a derived cache of the plugin's own source data. Its
+// vectors are tied to the workspace embedding model; when that model (or its
+// dimension) changes, the shared collection is rebuilt and these vectors are
+// dropped along with the host's, since a dimension change invalidates every
+// stored vector. Plugins own their source rows (per plugin self-containment)
+// and re-index after such a change. Nothing plugin-owned is persisted in the
+// main database.
+
+import { randomUUID } from "node:crypto";
+
+import type { AssistantConfig } from "../../config/types.js";
+import { BackendUnavailableError } from "../../util/errors.js";
+import { getLogger } from "../../util/logger.js";
+import { embedWithRetry } from "./embed.js";
+import {
+  generateSparseEmbedding,
+  getMemoryBackendStatus,
+} from "./embedding-backend.js";
+import {
+  type EmbeddingInput,
+  normalizeEmbeddingInput,
+  type SparseEmbedding,
+} from "./embedding-types.js";
+import { withQdrantBreaker } from "./qdrant-circuit-breaker.js";
+import { getQdrantClient } from "./qdrant-client.js";
+
+const log = getLogger("plugin-index");
+
+/** Qdrant target_type reserved for plugin-owned index documents. */
+const PLUGIN_INDEX_TARGET_TYPE = "plugin_index" as const;
+
+/**
+ * Namespace-qualified Qdrant point id for a plugin document. `VellumQdrantClient`
+ * dedupes points by (target_type, target_id), so the plugin name must be part of
+ * the target_id: otherwise two plugins that pick the same documentId would map
+ * to one point and clobber each other. Plugin manifest names are kebab-case and
+ * cannot contain ":", so the first ":" always splits the namespace from the id.
+ */
+function pointTargetId(plugin: string, documentId: string): string {
+  return `${plugin}:${documentId}`;
+}
+
+/** Recover the plugin-facing documentId from a namespace-qualified point id. */
+function documentIdFromPoint(plugin: string, targetId: string): string {
+  const prefix = `${plugin}:`;
+  return targetId.startsWith(prefix) ? targetId.slice(prefix.length) : targetId;
+}
+
+// ── Result / option shapes (re-exported to plugins via the facade) ─────────
+
+/** A computed embedding with the provider/model that produced it. */
+export interface EmbedResult {
+  vector: number[];
+  provider: string;
+  model: string;
+  dimensions: number;
+}
+
+export interface IndexDocumentOptions {
+  /**
+   * Reuse a caller-owned id to upsert a document in place (the update path:
+   * same id, overwrite). Omit to have the host mint a fresh document id.
+   */
+  documentId?: string;
+  /**
+   * Opaque provenance carried with the document (e.g. `{ rowId, fileId }`).
+   * Round-tripped verbatim on query/get; never interpreted by the host.
+   */
+  metadata?: Record<string, unknown>;
+  /** Override the stored creation timestamp (defaults to now). */
+  createdAt?: number;
+}
+
+export interface IndexDocumentResult {
+  documentId: string;
+  provider: string;
+  model: string;
+  dimensions: number;
+}
+
+export interface QueryIndexOptions {
+  /** Max hits to return. Defaults to 10. */
+  limit?: number;
+  /** Per-branch prefetch depth for the hybrid fusion. */
+  prefetchLimit?: number;
+}
+
+export interface IndexHit {
+  documentId: string;
+  score: number;
+  text: string;
+  modality: "text" | "image" | "audio" | "video";
+  metadata?: Record<string, unknown>;
+}
+
+export interface IndexedDocument {
+  documentId: string;
+  text: string;
+  modality: "text" | "image" | "audio" | "video";
+  metadata?: Record<string, unknown>;
+  createdAt: number;
+}
+
+// ── Internal helpers ───────────────────────────────────────────────────────
+
+/** The initialized Qdrant client, as a retryable unavailability if it is not up. */
+function requireQdrant(): ReturnType<typeof getQdrantClient> {
+  try {
+    return getQdrantClient();
+  } catch {
+    throw new BackendUnavailableError("Qdrant client not initialized");
+  }
+}
+
+/** Embed a single input to a dense vector, failing loudly if no backend is up. */
+async function embedDense(
+  config: AssistantConfig,
+  input: EmbeddingInput,
+): Promise<EmbedResult> {
+  const status = await getMemoryBackendStatus(config);
+  if (!status.provider) {
+    throw new BackendUnavailableError(
+      `Embedding backend unavailable (${status.reason ?? "no provider"})`,
+    );
+  }
+  const embedded = await embedWithRetry(config, [input]);
+  const vector = embedded.vectors[0];
+  if (!vector) {
+    throw new BackendUnavailableError("Embedding backend returned no vector");
+  }
+  return {
+    vector,
+    provider: embedded.provider,
+    model: embedded.model,
+    dimensions: vector.length,
+  };
+}
+
+/** Text projection stored on a point's payload (raw text or a media marker). */
+function payloadTextFor(input: EmbeddingInput): string {
+  const normalized = normalizeEmbeddingInput(input);
+  return normalized.type === "text"
+    ? normalized.text
+    : `[${normalized.type}:${normalized.mimeType}]`;
+}
+
+/** Sparse vector for the text side of an input, or undefined for media. */
+function sparseFor(input: EmbeddingInput): SparseEmbedding | undefined {
+  const normalized = normalizeEmbeddingInput(input);
+  return normalized.type === "text"
+    ? generateSparseEmbedding(normalized.text)
+    : undefined;
+}
+
+// ── Compute-only ────────────────────────────────────────────────────────────
+
+/** Embed an input and return the raw dense vector, with no persistence. */
+export async function computeEmbedding(
+  config: AssistantConfig,
+  input: EmbeddingInput,
+): Promise<EmbedResult> {
+  return embedDense(config, input);
+}
+
+/**
+ * Generate the sparse (lexical) vector for a text, using the same encoder the
+ * host uses for hybrid search. Pure and local: no backend call, no persistence.
+ */
+export function computeSparseEmbedding(text: string): SparseEmbedding {
+  return generateSparseEmbedding(text);
+}
+
+// ── Plugin-owned index ───────────────────────────────────────────────────────
+
+/**
+ * Embed a document and upsert it into the given plugin's private index.
+ * Returns the document id (minted here unless `opts.documentId` is supplied).
+ */
+export async function indexDocument(
+  config: AssistantConfig,
+  plugin: string,
+  input: EmbeddingInput,
+  opts?: IndexDocumentOptions,
+): Promise<IndexDocumentResult> {
+  const embedding = await embedDense(config, input);
+  const sparseVector = sparseFor(input);
+  const normalized = normalizeEmbeddingInput(input);
+  const documentId = opts?.documentId ?? randomUUID();
+  const now = opts?.createdAt ?? Date.now();
+  const qdrant = requireQdrant();
+
+  await withQdrantBreaker(() =>
+    qdrant.upsert(
+      PLUGIN_INDEX_TARGET_TYPE,
+      pointTargetId(plugin, documentId),
+      embedding.vector,
+      {
+        text: payloadTextFor(input),
+        modality: normalized.type,
+        created_at: now,
+        plugin,
+        document_id: documentId,
+        ...(opts?.metadata !== undefined ? { meta: opts.metadata } : {}),
+      },
+      sparseVector,
+    ),
+  );
+
+  return {
+    documentId,
+    provider: embedding.provider,
+    model: embedding.model,
+    dimensions: embedding.dimensions,
+  };
+}
+
+/**
+ * Hybrid (dense + sparse) search over the given plugin's index only. Falls back
+ * to dense-only when the query carries no lexical tokens (e.g. a media query or
+ * an all-stopword string).
+ */
+export async function queryIndex(
+  config: AssistantConfig,
+  plugin: string,
+  query: EmbeddingInput,
+  opts?: QueryIndexOptions,
+): Promise<IndexHit[]> {
+  const embedding = await embedDense(config, query);
+  const sparseVector = sparseFor(query);
+  const limit = opts?.limit ?? 10;
+  const qdrant = requireQdrant();
+
+  const filter = {
+    must: [
+      { key: "target_type", match: { value: PLUGIN_INDEX_TARGET_TYPE } },
+      { key: "plugin", match: { value: plugin } },
+    ],
+    must_not: [{ key: "_meta", match: { value: true } }],
+  };
+
+  const results =
+    sparseVector && sparseVector.indices.length > 0
+      ? await withQdrantBreaker(() =>
+          qdrant.hybridSearch({
+            denseVector: embedding.vector,
+            sparseVector,
+            filter,
+            limit,
+            prefetchLimit: opts?.prefetchLimit,
+          }),
+        )
+      : await withQdrantBreaker(() =>
+          qdrant.search(embedding.vector, limit, filter),
+        );
+
+  return results.map((r) => ({
+    documentId:
+      (r.payload.document_id as string | undefined) ??
+      documentIdFromPoint(plugin, r.payload.target_id),
+    score: r.score,
+    text: r.payload.text,
+    modality: r.payload.modality ?? "text",
+    metadata: r.payload.meta,
+  }));
+}
+
+/** Fetch a single document from the given plugin's index, or null. */
+export async function getDocument(
+  plugin: string,
+  documentId: string,
+): Promise<IndexedDocument | null> {
+  const qdrant = requireQdrant();
+  const found = await withQdrantBreaker(() =>
+    qdrant.getByTarget(
+      PLUGIN_INDEX_TARGET_TYPE,
+      pointTargetId(plugin, documentId),
+      { plugin },
+    ),
+  );
+  if (!found) {
+    return null;
+  }
+  return {
+    documentId,
+    text: found.payload.text,
+    modality: found.payload.modality ?? "text",
+    metadata: found.payload.meta,
+    createdAt: found.payload.created_at,
+  };
+}
+
+/** Remove a single document from the given plugin's index. */
+export async function removeDocument(
+  plugin: string,
+  documentId: string,
+): Promise<void> {
+  const qdrant = requireQdrant();
+  await withQdrantBreaker(() =>
+    qdrant.deleteByTargetAndPlugin(
+      PLUGIN_INDEX_TARGET_TYPE,
+      pointTargetId(plugin, documentId),
+      plugin,
+    ),
+  );
+}
+
+/**
+ * Delete every embedding a plugin owns, its whole index namespace. Host-only:
+ * meant for plugin uninstall so no vectors outlive the plugin directory. Not
+ * exposed on the plugin API, since one plugin must never purge another's data.
+ * Best-effort: logs and swallows so a purge failure never blocks teardown.
+ */
+export async function purgeEmbeddingsForPlugin(plugin: string): Promise<void> {
+  try {
+    const qdrant = requireQdrant();
+    await withQdrantBreaker(() => qdrant.deleteByPlugin(plugin));
+  } catch (err) {
+    log.warn({ err, plugin }, "Failed to purge plugin embeddings");
+  }
+}

package/src/persistence/embeddings/qdrant-circuit-breaker.ts

@@ -29,7 +29,9 @@ export class QdrantCircuitOpenError extends Error {
 }
 
 function allows(): boolean {
-  if (breakerState === "closed") return true;
+  if (breakerState === "closed") {
+    return true;
+  }
   if (breakerState === "open") {
     if (Date.now() - openedAt >= COOLDOWN_MS) {
       breakerState = "half-open";
@@ -42,7 +44,9 @@ function allows(): boolean {
     return false;
   }
   // half-open: only allow through if no probe is already in flight
-  if (halfOpenProbeInFlight) return false;
+  if (halfOpenProbeInFlight) {
+    return false;
+  }
   halfOpenProbeInFlight = true;
   return true;
 }

package/src/persistence/embeddings/qdrant-client.test.ts

@@ -16,10 +16,16 @@ describe("resolveQdrantUrl", () => {
   });
 
   afterEach(() => {
-    if (savedPort === undefined) delete process.env.QDRANT_HTTP_PORT;
-    else process.env.QDRANT_HTTP_PORT = savedPort;
-    if (savedUrl === undefined) delete process.env.QDRANT_URL;
-    else process.env.QDRANT_URL = savedUrl;
+    if (savedPort === undefined) {
+      delete process.env.QDRANT_HTTP_PORT;
+    } else {
+      process.env.QDRANT_HTTP_PORT = savedPort;
+    }
+    if (savedUrl === undefined) {
+      delete process.env.QDRANT_URL;
+    } else {
+      process.env.QDRANT_URL = savedUrl;
+    }
   });
 
   test("falls back to config when no env vars are set", () => {

package/src/persistence/embeddings/qdrant-client.ts

@@ -29,9 +29,13 @@ const log = getLogger("qdrant-client");
  */
 export function resolveQdrantUrl(config: AssistantConfig): string {
   const port = getQdrantHttpPortEnv();
-  if (port) return `http://127.0.0.1:${port}`;
+  if (port) {
+    return `http://127.0.0.1:${port}`;
+  }
   const url = getQdrantUrlEnv();
-  if (url) return url;
+  if (url) {
+    return url;
+  }
   return config.memory.qdrant.url;
 }
 
@@ -56,7 +60,10 @@ export interface QdrantPointPayload {
     | "summary"
     | "media"
     | "graph_node"
-    | "pkb_file";
+    | "pkb_file"
+    // Plugin-owned semantic index. Never queried by any recall lane; scoped to
+    // the owning plugin via the `plugin` field.
+    | "plugin_index";
   target_id: string;
   text: string;
   kind?: string;
@@ -69,6 +76,25 @@ export interface QdrantPointPayload {
   conversation_id?: string;
   message_id?: string;
   modality?: "text" | "image" | "audio" | "video";
+  /**
+   * Manifest name of the plugin that owns this point. Set on `plugin_index`
+   * points so every read/delete can be scoped to the calling plugin and an
+   * uninstall can purge the plugin's entire namespace. Absent on host points.
+   */
+  plugin?: string;
+  /**
+   * The plugin-facing document id for a `plugin_index` point. The Qdrant
+   * `target_id` is namespace-qualified (`<plugin>:<documentId>`) to keep point
+   * identity unique across plugins; this field carries the bare id back to the
+   * owning plugin on query/get. Absent on host points.
+   */
+  document_id?: string;
+  /**
+   * Opaque, plugin-supplied metadata carried alongside a `plugin_index` point
+   * (provenance such as a row id, file id, or source tool). Round-tripped
+   * verbatim on query/get; never interpreted by the host.
+   */
+  meta?: Record<string, unknown>;
 }
 
 export interface QdrantSearchResult {
@@ -182,7 +208,9 @@ export class VellumQdrantClient {
   }
 
   async ensureCollection(): Promise<{ migrated: boolean }> {
-    if (this.collectionReady) return { migrated: false };
+    if (this.collectionReady) {
+      return { migrated: false };
+    }
 
     // A leftover sentinel means a prior boot deleted the collection but never
     // got to enqueue the rebuild (createCollection threw, or the process died
@@ -407,10 +435,14 @@ export class VellumQdrantClient {
     )?.sparse_vectors;
     // No sparse config in the probe — nothing to move. (A collection without
     // the `sparse` named vector cannot accept an index update for it.)
-    if (!sparseParams || !("sparse" in sparseParams)) return;
+    if (!sparseParams || !("sparse" in sparseParams)) {
+      return;
+    }
 
     const current = sparseParams.sparse?.index?.on_disk ?? false;
-    if (current === this.onDisk) return;
+    if (current === this.onDisk) {
+      return;
+    }
 
     try {
       await this.client.updateCollection(this.collection, {
@@ -716,6 +748,128 @@ export class VellumQdrantClient {
     }
   }
 
+  /**
+   * Fetch a single point by (target_type, target_id) with its payload,
+   * optionally requiring a matching `plugin` scope. Returns null when no such
+   * point exists (or it belongs to a different plugin). Used by the plugin
+   * index facade to implement `getPluginDocument` without exposing raw scroll.
+   */
+  async getByTarget(
+    targetType: string,
+    targetId: string,
+    opts?: { plugin?: string },
+  ): Promise<{ id: string; payload: QdrantPointPayload } | null> {
+    await this.ensureCollection();
+
+    const must: Array<Record<string, unknown>> = [
+      { key: "target_type", match: { value: targetType } },
+      { key: "target_id", match: { value: targetId } },
+    ];
+    if (opts?.plugin !== undefined) {
+      must.push({ key: "plugin", match: { value: opts.plugin } });
+    }
+    const filter = {
+      must,
+      must_not: [{ key: "_meta", match: { value: true } }],
+    };
+
+    const doScroll = () =>
+      this.client.scroll(this.collection, {
+        filter,
+        limit: 1,
+        with_payload: true,
+        with_vector: false,
+      });
+
+    let result;
+    try {
+      result = await doScroll();
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        result = await doScroll();
+      } else {
+        throw err;
+      }
+    }
+
+    const point = result.points[0];
+    if (!point) {
+      return null;
+    }
+    return {
+      id: typeof point.id === "string" ? point.id : String(point.id),
+      payload: point.payload as unknown as QdrantPointPayload,
+    };
+  }
+
+  /**
+   * Delete a single plugin-owned point, scoped to (target_type, target_id,
+   * plugin). The `plugin` predicate guarantees one plugin can never remove
+   * another plugin's point even if it guesses the target id.
+   */
+  async deleteByTargetAndPlugin(
+    targetType: string,
+    targetId: string,
+    plugin: string,
+  ): Promise<void> {
+    await this.ensureCollection();
+
+    const doDelete = () =>
+      this.client.delete(this.collection, {
+        wait: true,
+        filter: {
+          must: [
+            { key: "target_type", match: { value: targetType } },
+            { key: "target_id", match: { value: targetId } },
+            { key: "plugin", match: { value: plugin } },
+          ],
+        },
+      });
+
+    try {
+      await doDelete();
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        await doDelete();
+      } else {
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Delete every point owned by a plugin (all `plugin` matches, any
+   * target_type). Backs `purgePluginEmbeddings` on plugin uninstall so no
+   * orphaned vectors survive removal of the plugin directory.
+   */
+  async deleteByPlugin(plugin: string): Promise<void> {
+    await this.ensureCollection();
+
+    const doDelete = () =>
+      this.client.delete(this.collection, {
+        wait: true,
+        filter: {
+          must: [{ key: "plugin", match: { value: plugin } }],
+        },
+      });
+
+    try {
+      await doDelete();
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        await doDelete();
+      } else {
+        throw err;
+      }
+    }
+  }
+
   async count(): Promise<number> {
     await this.ensureCollection();
 
@@ -738,7 +892,9 @@ export class VellumQdrantClient {
   async deleteCollection(): Promise<boolean> {
     try {
       const exists = await this.client.collectionExists(this.collection);
-      if (!exists.exists) return false;
+      if (!exists.exists) {
+        return false;
+      }
       await this.client.deleteCollection(this.collection);
       this.collectionReady = false;
       return true;
@@ -825,6 +981,10 @@ export class VellumQdrantClient {
         field_name: "path",
         field_schema: "keyword",
       }),
+      this.client.createPayloadIndex(this.collection, {
+        field_name: "plugin",
+        field_schema: "keyword",
+      }),
     ]);
   }
 
@@ -835,7 +995,9 @@ export class VellumQdrantClient {
         with_payload: true,
         with_vector: false,
       });
-      if (points.length === 0) return null;
+      if (points.length === 0) {
+        return null;
+      }
       return (
         ((points[0].payload as Record<string, unknown>)
           ?.embedding_model as string) ?? null
@@ -907,7 +1069,9 @@ export class VellumQdrantClient {
           out.push({ id, payload });
         }
         const next = result.next_page_offset;
-        if (next == null) break;
+        if (next == null) {
+          break;
+        }
         offset = typeof next === "string" ? next : (next as number);
       }
       return out;

package/src/persistence/embeddings/qdrant-manager.ts

@@ -306,8 +306,12 @@ export class QdrantManager {
           () => ({ type: "fetch" as const, ok: false }),
         ),
       ]);
-      if (fetchOutcome.type === "exited") await throwOnExit(fetchOutcome.code);
-      if (fetchOutcome.type === "fetch" && fetchOutcome.ok) return;
+      if (fetchOutcome.type === "exited") {
+        await throwOnExit(fetchOutcome.code);
+      }
+      if (fetchOutcome.type === "fetch" && fetchOutcome.ok) {
+        return;
+      }
 
       // Race the poll-interval sleep with process exit so we don't waste time
       // sleeping after the subprocess has already died.
@@ -320,7 +324,9 @@ export class QdrantManager {
           ),
         ),
       ]);
-      if (sleepOutcome.type === "exited") await throwOnExit(sleepOutcome.code);
+      if (sleepOutcome.type === "exited") {
+        await throwOnExit(sleepOutcome.code);
+      }
     }
     throw new Error(
       `Qdrant did not become ready within ${this.readyzTimeoutMs}ms at ${this.url}` +
@@ -361,7 +367,9 @@ export class QdrantManager {
     try {
       for (;;) {
         const { done, value } = await reader.read();
-        if (done) break;
+        if (done) {
+          break;
+        }
         buffer += decoder.decode(value, { stream: true });
         if (buffer.length > limit) {
           buffer = buffer.slice(-limit);
@@ -392,7 +400,9 @@ export class QdrantManager {
 
   private cleanupStaleProcess(): void {
     const pid = this.readPid();
-    if (pid == null) return;
+    if (pid == null) {
+      return;
+    }
 
     try {
       process.kill(pid, 0); // Check if process exists
@@ -406,7 +416,9 @@ export class QdrantManager {
   }
 
   private readPid(): number | null {
-    if (!existsSync(this.pidPath)) return null;
+    if (!existsSync(this.pidPath)) {
+      return null;
+    }
     try {
       const pid = parseInt(readFileSync(this.pidPath, "utf-8").trim(), 10);
       return isNaN(pid) ? null : pid;
@@ -491,6 +503,8 @@ export function createQdrantManager(
  * never ran (e.g. shutdown before background init started).
  */
 export async function stopQdrantManager(): Promise<void> {
-  if (!instance) return;
+  if (!instance) {
+    return;
+  }
   await instance.stop();
 }