@openparachute/vault 0.7.3 → 0.7.4-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.3",
+  "version": "0.7.4-rc.1",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/embeddings-routes.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit coverage for the semantic-search (embeddings) opt-in toggle surface
+ * (0.7.3 fast-follow). Fully sandboxed — a throwaway `PARACHUTE_HOME` so the
+ * config read/write path operates on a scratch `config.yaml`, and the running
+ * "active" state is injected (never touches the real process-shared provider
+ * memo or downloads a model).
+ *
+ * The snapshot builder is pure over (env, persisted, active) so most of the
+ * matrix (env override wins, restart-required gap, default-off) is exercised
+ * without any I/O; the handler tests verify the config write path + 400s.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { readGlobalConfig, writeGlobalConfig } from "./config.ts";
+import {
+  buildEmbeddingsSnapshot,
+  handleEmbeddingsGet,
+  handleEmbeddingsPut,
+  EMBEDDING_MODEL_DOWNLOAD_MB,
+  type EmbeddingsSettingsSnapshot,
+} from "./embeddings-routes.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-embed-routes-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  // Seed a config.yaml so readGlobalConfig has a file (port only — embeddings unset).
+  writeGlobalConfig({ port: 1940 });
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  rmSync(tmpHome, { recursive: true, force: true });
+});
+
+// An env with no EMBEDDINGS_ENABLED — the common self-host case.
+const NO_ENV: NodeJS.ProcessEnv = {};
+
+describe("buildEmbeddingsSnapshot", () => {
+  test("default: persisted unset, no env, not active → all off, no restart", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: undefined, active: false });
+    expect(snap).toEqual({
+      enabled: false,
+      env_override: null,
+      env_forced: false,
+      effective: false,
+      active: false,
+      restart_required: false,
+      model_download_mb: EMBEDDING_MODEL_DOWNLOAD_MB,
+    });
+  });
+
+  test("persisted on but not yet active → effective on, restart required", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: true, active: false });
+    expect(snap.enabled).toBe(true);
+    expect(snap.effective).toBe(true);
+    expect(snap.active).toBe(false);
+    expect(snap.restart_required).toBe(true);
+  });
+
+  test("persisted on and active → no restart required", () => {
+    const snap = buildEmbeddingsSnapshot({ env: NO_ENV, persistedEnabled: true, active: true });
+    expect(snap.restart_required).toBe(false);
+  });
+
+  test("env override ON wins over persisted OFF", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "true" },
+      persistedEnabled: false,
+      active: true,
+    });
+    expect(snap.enabled).toBe(false); // toggle still reflects persisted
+    expect(snap.env_override).toBe(true);
+    expect(snap.env_forced).toBe(true);
+    expect(snap.effective).toBe(true); // env forces on
+    expect(snap.restart_required).toBe(false); // active matches env-forced effective
+  });
+
+  test("env override OFF wins over persisted ON (with a pending restart while still active)", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "false" },
+      persistedEnabled: true,
+      active: true,
+    });
+    expect(snap.enabled).toBe(true); // persisted intent preserved
+    expect(snap.env_override).toBe(false);
+    expect(snap.env_forced).toBe(true);
+    expect(snap.effective).toBe(false); // env forces off
+    expect(snap.active).toBe(true);
+    expect(snap.restart_required).toBe(true); // running still on, env wants off
+  });
+
+  test("unrecognized env value defers to persisted (no force)", () => {
+    const snap = buildEmbeddingsSnapshot({
+      env: { EMBEDDINGS_ENABLED: "maybe" },
+      persistedEnabled: true,
+      active: false,
+    });
+    expect(snap.env_override).toBeNull();
+    expect(snap.env_forced).toBe(false);
+    expect(snap.effective).toBe(true);
+  });
+});
+
+describe("handleEmbeddingsGet", () => {
+  test("reflects the persisted config.yaml value", async () => {
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    const res = handleEmbeddingsGet(false);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(true);
+    expect(body.effective).toBe(true);
+    expect(body.active).toBe(false);
+    expect(body.restart_required).toBe(true);
+  });
+
+  test("unset persisted → enabled false", async () => {
+    const res = handleEmbeddingsGet(false);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(false);
+  });
+});
+
+describe("handleEmbeddingsPut", () => {
+  function putReq(body: unknown): Request {
+    return new Request("http://x/vault/default/.parachute/embeddings", {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    });
+  }
+
+  test("enabling persists embeddings_enabled: true via the config write path", async () => {
+    const res = await handleEmbeddingsPut(putReq({ enabled: true }), false);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as EmbeddingsSettingsSnapshot;
+    expect(body.enabled).toBe(true);
+    expect(body.restart_required).toBe(true); // persisted on, injected active=false
+    // The setting is actually on disk (config write path reused, not hand-rolled).
+    expect(readGlobalConfig().embeddings_enabled).toBe(true);
+  });
+
+  test("disabling persists embeddings_enabled: false", async () => {
+    writeGlobalConfig({ port: 1940, embeddings_enabled: true });
+    const res = await handleEmbeddingsPut(putReq({ enabled: false }), true);
+    expect(res.status).toBe(200);
+    expect(readGlobalConfig().embeddings_enabled).toBe(false);
+  });
+
+  test("preserves other config fields on write (round-trips through serialize)", async () => {
+    writeGlobalConfig({ port: 1940, discovery: "disabled", autostart: true });
+    await handleEmbeddingsPut(putReq({ enabled: true }), false);
+    const cfg = readGlobalConfig();
+    expect(cfg.embeddings_enabled).toBe(true);
+    expect(cfg.discovery).toBe("disabled");
+    expect(cfg.autostart).toBe(true);
+    expect(cfg.port).toBe(1940);
+  });
+
+  test("non-boolean enabled → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq({ enabled: "yes" }), false);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { field?: string };
+    expect(body.field).toBe("enabled");
+  });
+
+  test("missing enabled → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq({}), false);
+    expect(res.status).toBe(400);
+  });
+
+  test("non-object body → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq("[]"), false);
+    expect(res.status).toBe(400);
+  });
+
+  test("invalid JSON → 400", async () => {
+    const res = await handleEmbeddingsPut(putReq("{not json"), false);
+    expect(res.status).toBe(400);
+  });
+});

package/src/embeddings-routes.ts

@@ -0,0 +1,178 @@
+/**
+ * HTTP surface for the semantic-search (embeddings) opt-in toggle.
+ *
+ *   GET  /vault/<name>/.parachute/embeddings — read the persisted setting +
+ *                                              the running/effective/env state
+ *   PUT  /vault/<name>/.parachute/embeddings — flip the persisted setting
+ *
+ * The 0.7.3 fast-follow: 0.7.3 shipped the persisted `embeddings_enabled`
+ * config.yaml setting + `resolveEmbeddingsEnabled` (env override → persisted
+ * → off), but the ONLY way to flip it was hand-editing config.yaml or setting
+ * an env var. This module gives the vault admin SPA a real toggle over that
+ * setting.
+ *
+ * URL note: same reasoning as `mirror-routes.ts` — the admin SPA's static
+ * bundle owns `/vault/<name>/admin/*` (vault#252), so the API surface lives
+ * under the `.parachute/` module-protocol namespace (sibling to
+ * `.parachute/config`, `.parachute/mirror`, `.parachute/usage`).
+ *
+ * Auth: `vault:admin`, gated upstream in `routing.ts` (this module is the
+ * after-auth handler). `embeddings_enabled` is host-global config that affects
+ * every vault on the server, but it's reached through the same per-vault admin
+ * surface every other settings page uses; the UI copy names the host-wide
+ * scope.
+ *
+ * **Activation is restart-to-apply, not hot.** The embedding provider is
+ * resolved ONCE at boot (`getSharedEmbeddingProvider`) and captured into every
+ * open store (`Store.embeddingProvider` + `embeddingDisabledReason`, baked at
+ * construction) and into the embedding worker (`EmbeddingWorker.provider`, a
+ * private readonly field). Re-resolving the provider mid-run would mean
+ * mutating readonly fields across the worker AND every already-open store AND
+ * resetting a deliberately-once module memo — not clean. So this endpoint
+ * PERSISTS the setting and reports `restart_required` when the persisted
+ * change hasn't taken effect in the running process yet. Hot-reconfigure is a
+ * possible follow-up.
+ *
+ * **The `EMBEDDINGS_ENABLED` env var still wins.** It's the low-level override
+ * (`true`/`1` on, `false`/`0` off, else defer). When it's forcing a value the
+ * snapshot carries `env_override` so the UI can flag that the persisted toggle
+ * is advisory until the env var is removed — the toggle never lies about
+ * what's actually in force.
+ */
+
+import { readGlobalConfig, writeGlobalConfig } from "./config.ts";
+import { embeddingsEnabledEnvOverride, resolveEmbeddingsEnabled } from "./embedding/select.ts";
+import { isSharedEmbeddingProviderActive } from "./vault-store.ts";
+
+/**
+ * Approximate size of the bundled ONNX model (`bge-small-en-v1.5`, q8) that
+ * lazy-downloads on the FIRST embed after enabling. Surfaced so the UI can
+ * warn before the operator flips the switch. (The npm dependency ships ~270MB
+ * of runtime, but the model weights fetched on first use are ~34MB.)
+ */
+export const EMBEDDING_MODEL_DOWNLOAD_MB = 34;
+
+const CORS = { "Access-Control-Allow-Origin": "*" } as const;
+
+/**
+ * The wire shape the admin SPA reads/writes. Both GET and PUT return this so
+ * the SPA reuses one decoder.
+ */
+export interface EmbeddingsSettingsSnapshot {
+  /**
+   * The persisted `embeddings_enabled` in config.yaml — the value the toggle
+   * reflects. `false` when unset (semantic search is opt-in, default off).
+   */
+  enabled: boolean;
+  /**
+   * The `EMBEDDINGS_ENABLED` env override, tri-state: `true` (forced on),
+   * `false` (forced off), or `null` (no env var — defers to `enabled`). When
+   * non-null the env var wins over the persisted setting.
+   */
+  env_override: boolean | null;
+  /**
+   * Convenience flag: `true` exactly when `env_override` is non-null. The UI
+   * shows an advisory banner ("an env var is forcing this") when set.
+   */
+  env_forced: boolean;
+  /**
+   * What a fresh boot would resolve: env override, else persisted, else off.
+   * This is the state the running process will land in on next restart.
+   */
+  effective: boolean;
+  /**
+   * Whether semantic search is LIVE in the running process right now (the
+   * boot-resolved provider is present). Distinct from `effective`: a flip of
+   * the persisted setting changes `effective` immediately but not `active`.
+   */
+  active: boolean;
+  /**
+   * `true` when `active !== effective` — the operator's intended state is
+   * persisted but the running process hasn't picked it up. Restart to apply.
+   */
+  restart_required: boolean;
+  /** First-enable model-download size hint (MB) for the UI copy. */
+  model_download_mb: number;
+}
+
+/**
+ * Build the snapshot from the persisted setting + env + running state. Pure
+ * over its inputs (env + persisted + active) so it's unit-testable without a
+ * live server; the `active` reading is injected (defaults to the real
+ * process-shared provider state).
+ */
+export function buildEmbeddingsSnapshot(opts?: {
+  env?: NodeJS.ProcessEnv;
+  persistedEnabled?: boolean;
+  active?: boolean;
+}): EmbeddingsSettingsSnapshot {
+  const env = opts?.env ?? process.env;
+  const persisted = opts?.persistedEnabled ?? false;
+  const active = opts?.active ?? isSharedEmbeddingProviderActive();
+  const override = embeddingsEnabledEnvOverride(env);
+  const effective = resolveEmbeddingsEnabled(env, persisted);
+  return {
+    enabled: persisted,
+    env_override: override ?? null,
+    env_forced: override !== undefined,
+    effective,
+    active,
+    restart_required: active !== effective,
+    model_download_mb: EMBEDDING_MODEL_DOWNLOAD_MB,
+  };
+}
+
+/**
+ * `GET /vault/<name>/.parachute/embeddings` — return the current settings
+ * snapshot. Always 200 (auth enforced upstream). `activeOverride` is a test
+ * seam; production passes nothing and the running provider state is read.
+ */
+export function handleEmbeddingsGet(activeOverride?: boolean): Response {
+  const persisted = readGlobalConfig().embeddings_enabled;
+  const snapshot = buildEmbeddingsSnapshot({ persistedEnabled: persisted, active: activeOverride });
+  return Response.json(snapshot, { headers: CORS });
+}
+
+/**
+ * `PUT /vault/<name>/.parachute/embeddings` — persist a new
+ * `embeddings_enabled` value. Body: `{ "enabled": boolean }`.
+ *
+ * Reuses the config write path (`writeGlobalConfig` — never hand-rolls YAML),
+ * so the serialize logic that already knows how to persist `embeddings_enabled`
+ * is the single source of truth. Persists even when the env var is forcing a
+ * value (the operator's persisted intent is recorded; the env override still
+ * wins for `effective`/`active`, and the snapshot says so). Returns the same
+ * shape as GET, reflecting the new persisted value + the unchanged running
+ * state (so `restart_required` is honest right after the write).
+ */
+export async function handleEmbeddingsPut(req: Request, activeOverride?: boolean): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch (err) {
+    return Response.json(
+      { error: "Invalid JSON body", message: (err as Error).message ?? String(err) },
+      { status: 400 },
+    );
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return Response.json(
+      { error: "Invalid body", field: "enabled", message: "Expected a JSON object { enabled: boolean }." },
+      { status: 400 },
+    );
+  }
+  const enabled = (body as { enabled?: unknown }).enabled;
+  if (typeof enabled !== "boolean") {
+    return Response.json(
+      { error: "Invalid body", field: "enabled", message: "`enabled` must be a boolean." },
+      { status: 400 },
+    );
+  }
+
+  const config = readGlobalConfig();
+  config.embeddings_enabled = enabled;
+  writeGlobalConfig(config);
+
+  const snapshot = buildEmbeddingsSnapshot({ persistedEnabled: enabled, active: activeOverride });
+  return Response.json(snapshot, { headers: CORS });
+}

package/src/routing.test.ts

@@ -2716,6 +2716,135 @@ describe("/vault/<name>/.parachute/mirror — auth + dispatch", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// /vault/<name>/.parachute/embeddings — semantic-search (embeddings) opt-in
+// toggle admin surface (0.7.3 fast-follow, vault#624).
+//
+// Pins the auth gate + GET/PUT dispatch at the routing layer: the endpoint is
+// `vault:admin`-only (a host-global setting reached through the same per-vault
+// admin surface as the sibling `.parachute/mirror` / `.parachute/config`
+// pages). Snapshot shape + the env-override / restart-required semantics are
+// covered in embeddings-routes.test.ts; here we pin the *security* property —
+// unauth → 401, read/write → 403, admin → 200 + the flip persists — so it
+// can't silently regress below the rest of the admin surface. Mirrors the
+// `.parachute/mirror` auth+dispatch describe above.
+// ---------------------------------------------------------------------------
+
+describe("/vault/<name>/.parachute/embeddings — auth + dispatch", () => {
+  const P = "/vault/journal/.parachute/embeddings";
+
+  test("unauthenticated GET → 401", async () => {
+    createVault("journal");
+    const res = await route(new Request(`http://localhost:1940${P}`), P);
+    expect(res.status).toBe(401);
+  });
+
+  test("unauthenticated PUT → 401", async () => {
+    createVault("journal");
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(401);
+  });
+
+  test("vault:read token PUT → 403 insufficient_scope", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:read"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("vault:write token PUT → 403 insufficient_scope (write ranks below admin)", async () => {
+    createVault("journal");
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:journal:write"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string; required_scope?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+    expect(body.required_scope).toBe("vault:admin");
+  });
+
+  test("cross-vault admin token → 403 (scope names a different vault)", async () => {
+    createVault("journal");
+    createVault("other");
+    // Audience is `journal` (auth passes) but the admin scope names `other`,
+    // so hasScopeForVault denies it against `journal`.
+    const token = await mintJwt({ vaultName: "journal", scopes: ["vault:other:admin"] });
+    const res = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type?: string };
+    expect(body.error_type).toBe("insufficient_scope");
+  });
+
+  test("vault:admin token GET → 200 (default off); admin PUT persists the flip", async () => {
+    createVault("journal");
+    const token = await createAdminToken("journal");
+
+    // GET reaches the handler (auth + admin scope satisfied) → 200 snapshot,
+    // default-off (config seeded with `port` only).
+    const getRes = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(getRes.status).toBe(200);
+    const getBody = (await getRes.json()) as { enabled?: boolean };
+    expect(getBody.enabled).toBe(false);
+
+    // PUT flips the persisted setting → 200, echoing the new value.
+    const putRes = await route(
+      new Request(`http://localhost:1940${P}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify({ enabled: true }),
+      }),
+      P,
+    );
+    expect(putRes.status).toBe(200);
+    const putBody = (await putRes.json()) as { enabled?: boolean };
+    expect(putBody.enabled).toBe(true);
+
+    // A follow-up GET reads the persisted value back → the write stuck.
+    const reGet = await route(
+      new Request(`http://localhost:1940${P}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      P,
+    );
+    expect(reGet.status).toBe(200);
+    const reBody = (await reGet.json()) as { enabled?: boolean };
+    expect(reBody.enabled).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // /vault/<name>/.parachute/mirror/run-now — manual-trigger endpoint added
 // alongside the SPA UI. Tests pin the auth gate matches the parent

package/src/routing.ts

@@ -116,6 +116,7 @@ import {
   handleMirrorPut,
   handleMirrorRunNow,
 } from "./mirror-routes.ts";
+import { handleEmbeddingsGet, handleEmbeddingsPut } from "./embeddings-routes.ts";
 import { getMirrorManager } from "./mirror-registry.ts";
 import { buildUsageReport } from "./usage.ts";
 import { handleTicketSpend } from "./attachment-tickets.ts";
@@ -687,6 +688,33 @@ export async function route(
     return Response.json(buildUsageReport(vaultName, stats, { fresh }));
   }
 
+  // /.parachute/embeddings — Admin-gated read+write of the semantic-search
+  // (embeddings) opt-in toggle. The 0.7.3 fast-follow: gives the admin SPA a
+  // real toggle over the persisted `embeddings_enabled` config.yaml setting so
+  // an operator flips semantic search on from the UI instead of hand-editing
+  // config or setting an env var. Host-global setting (affects every vault),
+  // reached through the same per-vault admin surface as the other settings
+  // pages. Activation is restart-to-apply — the endpoint persists the setting
+  // and reports `restart_required`; see embeddings-routes.ts for why the boot-
+  // captured provider isn't hot-reconfigured.
+  if (subpath === "/.parachute/embeddings") {
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    if (req.method === "GET") return handleEmbeddingsGet();
+    if (req.method === "PUT") return handleEmbeddingsPut(req);
+    return Response.json({ error: "Method not allowed" }, { status: 405 });
+  }
+
   // The per-vault `/tokens` REST surface (pvt_* mint/list/revoke) was removed
   // at 0.5.0 (vault#282 Stage 2 — vault is a pure hub resource-server). Hub
   // JWTs are minted via hub's registry (`/api/auth/mint-token`); a `/tokens`

package/src/vault-store.ts

@@ -68,6 +68,21 @@ export function getSharedEmbeddingProvider(): EmbeddingProvider | undefined {
   return sharedEmbeddingProvider;
 }
 
+/**
+ * Whether semantic search is LIVE in this running process right now — i.e.
+ * the boot-resolved shared provider is present. This is the honest
+ * "currently active" signal the admin settings surface reports, distinct
+ * from the *persisted* `embeddings_enabled` setting: because the provider
+ * is memoized at boot (into every open store + the embedding worker),
+ * flipping the persisted setting does NOT change this until the next
+ * server restart. The admin toggle compares this against the freshly
+ * resolved effective state to tell the operator when a restart is pending
+ * (see `src/embeddings-routes.ts`).
+ */
+export function isSharedEmbeddingProviderActive(): boolean {
+  return getSharedEmbeddingProvider() !== undefined;
+}
+
 /** Test-only: force a fresh provider on the next `getSharedEmbeddingProvider()` call. */
 export function resetSharedEmbeddingProviderForTests(): void {
   sharedEmbeddingProvider = undefined;