hippo-memory 1.70.0 → 1.72.0

package/dist/embeddings/local.js

@@ -0,0 +1,146 @@
+// The local Transformers.js embedder, a leaf so provider.ts can wrap it without importing index.ts.
+import { MINUTE_MS } from '../util/time.js';
+import { envModelCache } from '../util/env.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadConfig } from '../core/config.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
+import { createModelLoads, importTransformers, MODEL_LOAD_POLICY, resolveTransformersPackage } from './transformers.js';
+export const DEFAULT_EMBEDDING_MODEL = 'Xenova/all-MiniLM-L6-v2';
+/** BGE was trained with CLS pooling; everything else gets mean, the sentence-transformers default, since CLS degrades mean-trained models. */
+export function poolingFor(model) {
+    return /\bbge\b/i.test(model) ? 'cls' : 'mean';
+}
+/** e5 models only match a query to a passage when each side carries its trained prefix. */
+export function prefixFor(model, role) {
+    if (!role)
+        return '';
+    if (/\be5\b/i.test(model)) {
+        return role === 'query' ? 'query: ' : 'passage: ';
+    }
+    return '';
+}
+const INSTALLED_TRANSFORMERS = {
+    installed: () => resolveTransformersPackage() !== null,
+    load: () => importTransformers(),
+};
+/** One pipeline per model for the embedder's life, since a pipeline is expensive to load. */
+export function createLocalEmbedder(transformers = INSTALLED_TRANSFORMERS) {
+    let available = null;
+    const gates = new Map();
+    const pipelines = createModelLoads(MODEL_LOAD_POLICY, warnLoadFailure);
+    const load = (model) => pipelines.load(model, () => createPipeline(transformers, model, gates));
+    const isAvailable = () => (available ??= transformers.installed());
+    return {
+        isAvailable,
+        requirePipeline: (model, signal) => waitForPipeline(load(model), signal && gateOf(gates, model).opened, signal),
+        async embed(text, model, role) {
+            if (!isAvailable())
+                return [];
+            try {
+                const pipe = await load(model);
+                const prefix = prefixFor(model, role);
+                const output = await pipe(prefix ? `${prefix}${text}` : text, { pooling: poolingFor(model), normalize: true });
+                return Array.from(output.data);
+            }
+            catch (err) {
+                // The caller sees `[]` and names the memory; a failed load already warned once for its backoff window.
+                log.debug(`local embedding failed: ${errorMessage(err)}`);
+                return [];
+            }
+        },
+    };
+}
+function warnLoadFailure(model, err) {
+    const retry = `the next try is in ${MODEL_LOAD_POLICY.backoffMs / MINUTE_MS} minutes`;
+    log.warn(`local embedding model ${model} did not load (${errorMessage(err)}); embeddings stay off and ${retry}`, errorFields(err));
+}
+/** The model's pipeline; throws the reason it cannot load. */
+async function createPipeline(transformers, model, gates) {
+    // The package is an optional peer, so the dynamic import is typed by what this file reads; a missing export throws below.
+    const imported = await transformers.load();
+    if (!imported)
+        throw new Error('no transformers package is installed');
+    const { name, mod } = imported;
+    const cache = envModelCache();
+    if (cache && mod.env) {
+        mod.env.cacheDir = cache;
+        mod.env.localModelPath = cache;
+        mod.env.allowRemoteModels = false;
+    }
+    const pipelineFn = mod.pipeline ?? mod.default?.pipeline;
+    if (!pipelineFn)
+        throw new Error(`${name} exports no pipeline function`);
+    // The offline bundle used in egress-blocked sandboxes ships only the FP32 model, so use whichever file is on disk.
+    const quantized = !cache || fs.existsSync(path.join(cache, model, 'onnx', 'model_quantized.onnx'));
+    if (fetchesWeights(mod.env, model))
+        gateOf(gates, model).open();
+    try {
+        return await pipelineFn('feature-extraction', model, { quantized });
+    }
+    finally {
+        gates.delete(model);
+    }
+}
+/** Whether the load will download: remote models are allowed and no folder the package reads holds the model's ONNX files. */
+function fetchesWeights(env, model) {
+    if (env?.allowRemoteModels === false)
+        return false;
+    return ![env?.localModelPath, env?.cacheDir].some((dir) => dir !== undefined && fs.existsSync(path.join(dir, model, 'onnx')));
+}
+function gateOf(gates, model) {
+    let gate = gates.get(model);
+    if (!gate) {
+        let open;
+        const opened = new Promise((resolve) => {
+            open = resolve;
+        });
+        gate = { opened, open };
+        gates.set(model, gate);
+    }
+    return gate;
+}
+function rejectOnAbort(signal) {
+    return new Promise((_resolve, reject) => {
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+}
+async function waitForPipeline(loading, downloading, signal) {
+    try {
+        await (downloading && signal ? Promise.race([loading, downloading.then(() => rejectOnAbort(signal))]) : loading);
+    }
+    catch (err) {
+        // The download goes on, and the first call after it lands gets the model.
+        if (signal?.aborted && err === signal.reason)
+            throw err;
+        throw new Error(`local embedding model did not load: ${errorMessage(err)}`, { cause: err });
+    }
+}
+/** The process's embedder, shared by every provider and caller so each model loads once. */
+export const sharedLocalEmbedder = createLocalEmbedder();
+/** Check (synchronously) if @xenova/transformers or @huggingface/transformers is installed. */
+export function isEmbeddingAvailable() {
+    return sharedLocalEmbedder.isAvailable();
+}
+export function resolveEmbeddingModel(hippoRoot, explicitModel) {
+    const direct = explicitModel?.trim();
+    if (direct)
+        return direct;
+    try {
+        const configured = loadConfig(hippoRoot).embeddings.model?.trim();
+        if (configured)
+            return configured;
+    }
+    catch (err) {
+        log.warn(`embedding model config unreadable, using the default model: ${errorMessage(err)}`);
+    }
+    return DEFAULT_EMBEDDING_MODEL;
+}
+/** Embeds `text` with the local model, or returns `[]` when Transformers.js is missing or fails; `role` adds e5-style prefixes. */
+export function getEmbedding(text, model = DEFAULT_EMBEDDING_MODEL, role) {
+    return sharedLocalEmbedder.embed(text, model, role);
+}
+//# sourceMappingURL=local.js.map

package/dist/embeddings/provider.d.ts

@@ -0,0 +1,43 @@
+/** Pluggable embedding providers; local `@huggingface/transformers` is the zero-dependency default, OpenAI / Voyage / Cohere are opt-in via native `fetch`.
+ * Local `id` is the bare model string, API `id` is `${kind}:${model}`; the stored identity adds `#t<N>` (`embeddingIndexIdentity`), so changes reindex.
+ * `embed()` MAY throw on hard transport/auth failure so a reindex aborts atomically; hot paths wrap it and fall back to BM25. */
+import { type EmbeddingRole, type LocalTransformers } from './local.js';
+export type EmbeddingProviderKind = 'local' | 'openai' | 'voyage' | 'cohere';
+export declare const API_PROVIDER_KINDS: readonly EmbeddingProviderKind[];
+export interface EmbedCallOptions {
+    /** Ends the whole call when it aborts, every batch and retry included. The local provider stops waiting only on a model download,
+     * since nothing stops a load from disk or an in-process inference. */
+    signal?: AbortSignal;
+}
+export interface EmbeddingProvider {
+    readonly kind: EmbeddingProviderKind;
+    readonly model: string;
+    /** Identity recorded in DB meta to drive reindex-on-change: bare model string for local, `${kind}:${model}` for api. */
+    readonly id: string;
+    /** Known fixed output dimension, if any (undefined for local / unknown). */
+    readonly dimensions?: number;
+    /** Env var holding this provider's API key (undefined for the local provider). */
+    readonly keyEnv?: string;
+    /** local -> dependency installed; api -> key present. NEVER throws. */
+    isAvailable(): boolean;
+    /** Batch-embed: one row per input in order, `[]` when that item could not be embedded.
+     * MAY throw on a hard transport/auth failure so a reindex aborts before saving a partial index. */
+    embed(texts: string[], role?: EmbeddingRole, call?: EmbedCallOptions): Promise<number[][]>;
+}
+export interface ResolveProviderOptions {
+    /** Explicit model override (mirrors resolveEmbeddingModel's explicitModel). */
+    model?: string;
+    /** Explicit provider override (mainly for tests). */
+    provider?: EmbeddingProviderKind;
+    /** The Transformers.js package a local provider loads from, with its own models; the process's shared embedder when unset. */
+    transformers?: LocalTransformers;
+}
+/** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
+ * only an invalid config (e.g. insecure apiBaseUrl) throws, deliberately loud, so hot-path callers wrap it. */
+export declare function resolveEmbeddingProvider(hippoRoot: string, opts?: ResolveProviderOptions): EmbeddingProvider;
+/** The reindex identity for the active provider; use it, NOT resolveEmbeddingModel, wherever `embeddingModelRequiresReindex` / stored-model comparisons
+ * happen. */
+export declare function resolveEmbeddingIdentity(hippoRoot: string, opts?: ResolveProviderOptions): string;
+/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision to embed is made. */
+export declare function isEmbeddingConfigured(hippoRoot: string): boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/{store/embeddings → embeddings}/provider.js

@@ -1,38 +1,19 @@
-/**
- * Pluggable embedding providers for Hippo.
- *
- * The local `@huggingface/transformers` path stays the zero-DEPENDENCY DEFAULT. Opt-in
- * API providers (OpenAI / Voyage / Cohere) let a user bring a frontier embedder
- * (e.g. text-embedding-3-large) for frontier-class retrieval. They use the native
- * `fetch` global (Node >= 22.16, see package.json engines; NO new dependency) and
- * read their key from a conventional env var. The provider is selected by
- * `config.embeddings.provider` (default `'local'`).
- *
- * Design contract:
- *   - Local provider `id` is the BARE model string; the STORED identity adds a `#t<N>`
- *     embed-text-format suffix (`embeddingIndexIdentity`), so older stores reindex once:
- *     their vectors were computed over path-contaminated text.
- *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
- *     (or a dimension change) flips the identity and triggers the existing
- *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
- *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
- *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
- *     a hard transport/auth failure so a reindex can abort atomically; hot paths
- *     wrap it and fall back to BM25.
- *
- * The exact request/response shapes for the API providers are documented from each
- * vendor's public embeddings API; they are unit-tested here against a mocked
- * `fetch` and are integration-verified in Workstream C (real API calls are
- * egress-blocked in the build sandbox).
- */
-import { envByName } from '../../util/env.js';
-import { getEmbedding, isEmbeddingAvailable, requireLocalPipeline, resolveEmbeddingModel, DEFAULT_EMBEDDING_MODEL, } from './local.js';
-import { loadConfig } from '../../core/config.js';
-import { errorMessage, log } from '../../util/log.js';
-import { redactSecretsStrict } from '../../util/secret-detect.js';
-import { fetchWithRetry } from '../../util/http-retry.js';
+/** Pluggable embedding providers; local `@huggingface/transformers` is the zero-dependency default, OpenAI / Voyage / Cohere are opt-in via native `fetch`.
+ * Local `id` is the bare model string, API `id` is `${kind}:${model}`; the stored identity adds `#t<N>` (`embeddingIndexIdentity`), so changes reindex.
+ * `embed()` MAY throw on hard transport/auth failure so a reindex aborts atomically; hot paths wrap it and fall back to BM25. */
+import { envByName } from '../util/env.js';
+import { createLocalEmbedder, resolveEmbeddingModel, sharedLocalEmbedder, DEFAULT_EMBEDDING_MODEL, } from './local.js';
+import { loadConfig } from '../core/config.js';
+import { errorMessage, log } from '../util/log.js';
+import { redactSecretsStrict } from '../util/secret-detect.js';
+import { fetchWithRetry } from '../util/http-retry.js';
+import { readCappedJson, readCappedText } from '../util/capped-json.js';
 const ERROR_DETAIL_CHARS = 300;
+// An error body is read for its first lines only; 4x leaves room for multi-byte text.
+const ERROR_BODY_MAX_BYTES = ERROR_DETAIL_CHARS * 4;
+// 16,384 dimensions at 32 bytes a number: four times a 4,096-dimension model.
+const EMBED_REPLY_BYTES_PER_INPUT = 512 * 1024;
+const EMBED_REPLY_BASE_BYTES = 64 * 1024;
 export const API_PROVIDER_KINDS = ['openai', 'voyage', 'cohere'];
 function isApiProviderKind(x) {
     return x === 'openai' || x === 'voyage' || x === 'cohere';
@@ -41,30 +22,31 @@ const DEFAULT_API_BATCH_SIZE = 64;
 /** Per-request timeout for API embedding calls. A provider/proxy that accepts
  *  the connection but never responds must not hang embed/recall indefinitely. */
 const REQUEST_TIMEOUT_MS = 30_000;
-// ---------------------------------------------------------------------------
-// Local provider — wraps the existing zero-dep transformers.js path.
-// ---------------------------------------------------------------------------
+// Under a caller's deadline a longer Retry-After hands the reply back at once; the remote rerankers use the same cap.
+const DEADLINE_RETRY_WAIT_CAP_MS = 2_000;
 class LocalEmbeddingProvider {
     model;
     enabled;
+    embedder;
     kind = 'local';
-    constructor(model, enabled = true) {
+    constructor(model, enabled, embedder) {
         this.model = model;
         this.enabled = enabled;
+        this.embedder = embedder;
     }
     get id() {
         return this.model;
     }
     isAvailable() {
-        return this.enabled && isEmbeddingAvailable();
+        return this.enabled && this.embedder.isAvailable();
     }
-    async embed(texts, role) {
+    async embed(texts, role, call = {}) {
         // A model that cannot load fails the call, as an API outage does; items then run one at a time on the shared pipeline.
         if (texts.length > 0)
-            await requireLocalPipeline(this.model);
+            await this.embedder.requirePipeline(this.model, call.signal);
         const out = [];
         for (const text of texts) {
-            out.push(await getEmbedding(text, this.model, role));
+            out.push(await this.embedder.embed(text, this.model, role));
         }
         return out;
     }
@@ -78,8 +60,7 @@ const API_PROVIDER_SPECS = {
         // OpenAI has no asymmetric query/passage input type for embeddings.
         buildBody: (model, texts) => ({ model, input: texts }),
         extractVectors: (json) => {
-            // SAFETY: OpenAI's documented embeddings response envelope; embedChunk
-            // validates vector count/non-emptiness against the request afterward,
+            // SAFETY: OpenAI's documented embeddings envelope; embedChunk validates vector count and non-emptiness afterward,
             // so a malformed response degrades to [] here and throws there.
             const data = json.data ?? [];
             return data.map((d) => d.embedding ?? []);
@@ -97,8 +78,7 @@ const API_PROVIDER_SPECS = {
             return body;
         },
         extractVectors: (json) => {
-            // SAFETY: Voyage's documented embeddings response envelope; embedChunk
-            // validates vector count/non-emptiness against the request afterward,
+            // SAFETY: Voyage's documented embeddings envelope; embedChunk validates vector count and non-emptiness afterward,
             // so a malformed response degrades to [] here and throws there.
             const data = json.data ?? [];
             return data.map((d) => d.embedding ?? []);
@@ -116,10 +96,8 @@ const API_PROVIDER_SPECS = {
             embedding_types: ['float'],
         }),
         extractVectors: (json) => {
-            // Cohere v2: { embeddings: { float: number[][] } }
-            // SAFETY: matches Cohere's documented v2 response envelope; embedChunk
-            // validates vector count/non-emptiness against the request afterward,
-            // so a malformed response degrades to [] here and throws there.
+            // Cohere v2 shape: { embeddings: { float: number[][] } }
+            // SAFETY: documented v2 envelope; embedChunk validates the vectors afterward, so a malformed response degrades to [] here and throws there.
             const emb = json.embeddings;
             return emb?.float ?? [];
         },
@@ -169,7 +147,7 @@ class ApiEmbeddingProvider {
     isAvailable() {
         return this.enabled && !!envByName(this.keyEnv)?.trim();
     }
-    async embed(texts, role) {
+    async embed(texts, role, call = {}) {
         if (texts.length === 0)
             return [];
         const key = envByName(this.keyEnv)?.trim();
@@ -181,21 +159,19 @@ class ApiEmbeddingProvider {
         const out = [];
         for (let i = 0; i < texts.length; i += this.batchSize) {
             const chunk = texts.slice(i, i + this.batchSize);
-            const vecs = await this.embedChunk(chunk, key, role);
+            const vecs = await this.embedChunk(chunk, key, role, call.signal);
             for (const v of vecs)
                 out.push(v.length > 0 ? l2normalize(v) : v);
         }
         return out;
     }
-    async embedChunk(chunk, key, role) {
+    async embedChunk(chunk, key, role, signal) {
         const spec = API_PROVIDER_SPECS[this.kind];
-        const resp = await this.postChunk(chunk, key, role);
-        const json = await this.responseJson(resp, key);
+        const resp = await this.postChunk(chunk, key, role, signal);
+        const json = await this.responseJson(resp, key, chunk.length);
         const vectors = spec.extractVectors(json);
-        // A 200 response with the wrong number of vectors (or any empty/malformed
-        // vector) is a provider/proxy contract violation, NOT a per-item miss. Throw
-        // so a reindex aborts atomically (preserving the prior usable index) and the
-        // explicit backfill surfaces it, instead of silently saving []-padded rows.
+        // A 200 with the wrong vector count (or any empty/malformed vector) is a provider contract violation, not a per-item miss:
+        // throw so a reindex aborts atomically and the explicit backfill surfaces it, instead of saving []-padded rows.
         if (vectors.length !== chunk.length) {
             throw new Error(redact(`${this.kind} embeddings returned ${vectors.length} vectors for ${chunk.length} inputs`, key));
         }
@@ -206,7 +182,7 @@ class ApiEmbeddingProvider {
         }
         return vectors;
     }
-    async postChunk(chunk, key, role) {
+    async postChunk(chunk, key, role, signal) {
         const spec = API_PROVIDER_SPECS[this.kind];
         const url = `${this.baseUrl.replace(/\/$/, '')}/${spec.path}`;
         try {
@@ -217,7 +193,13 @@ class ApiEmbeddingProvider {
                     authorization: `Bearer ${key}`,
                 },
                 body: JSON.stringify(spec.buildBody(this.model, chunk.map(redactSecretsStrict), role)),
-            }, { timeoutMs: REQUEST_TIMEOUT_MS });
+                signal,
+            }, {
+                timeoutMs: REQUEST_TIMEOUT_MS,
+                // Embedding the same text twice changes nothing on the far side, so a dropped connection or a stalled attempt is replayed.
+                retryTransport: true,
+                maxDelayMs: signal ? DEADLINE_RETRY_WAIT_CAP_MS : undefined,
+            });
         }
         catch (err) {
             const msg = errorMessage(err);
@@ -225,23 +207,25 @@ class ApiEmbeddingProvider {
         }
     }
     /** The body of an OK reply; any other status, or a body that is not JSON, throws with the key cut out. */
-    async responseJson(resp, key) {
+    async responseJson(resp, key, inputs) {
         if (!resp.ok) {
             let detail = '';
             try {
-                detail = await resp.text();
+                detail = await readCappedText(resp, ERROR_BODY_MAX_BYTES);
             }
-            catch {
-                /* ignore body read error */
+            catch (err) {
+                log.debug(`${this.kind} embeddings error body unreadable: ${errorMessage(err)}`);
             }
             throw new Error(redact(`${this.kind} embeddings HTTP ${resp.status}: ${detail.slice(0, ERROR_DETAIL_CHARS)}`, key));
         }
         try {
-            return await resp.json();
+            return await readCappedJson(resp, EMBED_REPLY_BASE_BYTES + inputs * EMBED_REPLY_BYTES_PER_INPUT);
         }
         catch (err) {
             const msg = errorMessage(err);
-            throw new Error(redact(`${this.kind} embeddings returned invalid JSON: ${msg}`, key), { cause: redactedCause(err, key) });
+            throw new Error(redact(`${this.kind} embeddings returned invalid JSON: ${msg}`, key), {
+                cause: redactedCause(err instanceof Error && err.cause ? err.cause : err, key)
+            });
         }
     }
 }
@@ -273,13 +257,8 @@ function validateBaseUrl(url, fallback) {
     }
     return candidate;
 }
-/**
- * Build the active embedding provider from config (or an explicit override).
- * Never throws for a missing key — that surfaces via `isAvailable()` on the hot
- * paths and as a hard error only from the explicit `hippo embed` command. The
- * only hard throw is an invalid config (e.g. an insecure apiBaseUrl), a
- * deliberate loud failure; hot-path callers (search) wrap this in try/catch.
- */
+/** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
+ * only an invalid config (e.g. insecure apiBaseUrl) throws, deliberately loud, so hot-path callers wrap it. */
 export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
     const cfg = readEmbeddingsConfig(hippoRoot);
     const requested = opts.provider ?? cfg.provider ?? 'local';
@@ -287,7 +266,8 @@ export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
     // and API providers — for API this prevents unwanted paid off-box calls.
     const enabled = cfg.enabled !== false;
     if (requested === 'local') {
-        return new LocalEmbeddingProvider(resolveEmbeddingModel(hippoRoot, opts.model), enabled);
+        const embedder = opts.transformers ? createLocalEmbedder(opts.transformers) : sharedLocalEmbedder;
+        return new LocalEmbeddingProvider(resolveEmbeddingModel(hippoRoot, opts.model), enabled, embedder);
     }
     if (!isApiProviderKind(requested)) {
         // Fail loud on a typo'd provider rather than silently using local (which
@@ -306,17 +286,12 @@ export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
         : DEFAULT_API_BATCH_SIZE;
     return new ApiEmbeddingProvider(kind, model, baseUrl, batchSize, enabled);
 }
-/**
- * The reindex identity for the active provider. Use this (NOT resolveEmbeddingModel)
- * everywhere `embeddingModelRequiresReindex` / stored-model comparisons happen.
- */
+/** The reindex identity for the active provider; use it, NOT resolveEmbeddingModel, wherever `embeddingModelRequiresReindex` / stored-model comparisons
+ * happen. */
 export function resolveEmbeddingIdentity(hippoRoot, opts = {}) {
     return resolveEmbeddingProvider(hippoRoot, opts).id;
 }
-/**
- * Provider-aware availability for a store: local -> dependency installed;
- * api -> key present. Use at the call sites that decide whether to embed.
- */
+/** Provider-aware availability for a store (local: dependency installed; api: key present); use where the decision to embed is made. */
 export function isEmbeddingConfigured(hippoRoot) {
     try {
         return resolveEmbeddingProvider(hippoRoot).isAvailable();

package/dist/embeddings/transformers.d.ts

@@ -0,0 +1,26 @@
+export interface TransformersPackage {
+    readonly name: string;
+    /** The ESM entry; a require-style import picks the CommonJS build and puts a second copy of the library, with its own ONNX sessions, in the process. */
+    readonly url: string;
+}
+/** The installed package to import, or null when neither is installed. */
+export declare function resolveTransformersPackage(): TransformersPackage | null;
+/** The package's module namespace, typed by the parts the caller reads; null when neither package is installed. */
+export declare function importTransformers<M>(): Promise<{
+    readonly name: string;
+    readonly mod: M;
+} | null>;
+export interface ModelLoadPolicy {
+    /** How long one load may run before it counts as failed; nothing can cancel it, so it keeps running and a late model is still kept. */
+    readonly timeoutMs: number;
+    /** How long a failure is answered from memory before the next call loads again. */
+    readonly backoffMs: number;
+}
+export declare const MODEL_LOAD_POLICY: ModelLoadPolicy;
+export interface ModelLoads<T> {
+    /** The model under `key`: the loaded one, the load in flight, the failure inside its backoff window, or a new `start()`. */
+    load(key: string, start: () => Promise<T>): Promise<T>;
+}
+/** One load per key at a time, bounded by the policy's timeout; `onFailure` hears each failed attempt, so once per backoff window. */
+export declare function createModelLoads<T>(policy: ModelLoadPolicy, onFailure?: (key: string, err: Error) => void): ModelLoads<T>;
+//# sourceMappingURL=transformers.d.ts.map

package/dist/embeddings/transformers.js

@@ -0,0 +1,89 @@
+// The optional Transformers.js package, and a bounded load of a model from it, shared by the local embedder and the cross-encoder.
+import { MINUTE_MS } from '../util/time.js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { errorCode, errorMessage } from '../util/log.js';
+const _require = createRequire(import.meta.url);
+// Importing both loads two onnxruntime-node builds whose finalizers can double-free on exit, so one is picked:
+// the maintained package hippo ships, with Xenova only as a fallback a user installed.
+const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
+/** The installed package to import, or null when neither is installed. */
+export function resolveTransformersPackage() {
+    for (const name of TRANSFORMERS_PACKAGES) {
+        const url = entryUrl(name);
+        if (url)
+            return { name, url };
+    }
+    return null;
+}
+function entryUrl(name) {
+    try {
+        return import.meta.resolve(name);
+    }
+    catch {
+        // import.meta.resolve is missing under some module runners (vitest's included), so the require-based resolve stands in there.
+        try {
+            return pathToFileURL(_require.resolve(name)).href;
+        }
+        catch {
+            return null; // not installed; the caller tries the next package
+        }
+    }
+}
+/** The package's module namespace, typed by the parts the caller reads; null when neither package is installed. */
+export async function importTransformers() {
+    const pkg = resolveTransformersPackage();
+    if (!pkg)
+        return null;
+    try {
+        return { name: pkg.name, mod: await import(/* @vite-ignore */ pkg.url) };
+    }
+    catch (err) {
+        // A Node error's code (ERR_MODULE_NOT_FOUND and the like) says more than its message alone.
+        const code = errorCode(err);
+        throw new Error(`transformers import failed (${pkg.name}): ${code ? `${code} ` : ''}${errorMessage(err)}`, { cause: err });
+    }
+}
+// A quantized MiniLM is about 23 MB, so two minutes is a 1.5 Mbit/s link; a load from disk takes about a second.
+// The backoff matches the reranker outage warning's repeat window, so each window has one attempt and one warning.
+export const MODEL_LOAD_POLICY = { timeoutMs: 2 * MINUTE_MS, backoffMs: 5 * MINUTE_MS };
+/** One load per key at a time, bounded by the policy's timeout; `onFailure` hears each failed attempt, so once per backoff window. */
+export function createModelLoads(policy, onFailure) {
+    const loaded = new Map();
+    const inFlight = new Map();
+    const failed = new Map();
+    const attempt = (key, start) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${key} did not load within ${policy.timeoutMs / 1000} s`)), policy.timeoutMs);
+        timer.unref();
+        Promise.resolve().then(start).then((model) => {
+            clearTimeout(timer);
+            loaded.set(key, model);
+            failed.delete(key);
+            resolve(model);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(errorMessage(err)));
+        });
+    });
+    return {
+        load(key, start) {
+            const model = loaded.get(key);
+            if (model !== undefined)
+                return Promise.resolve(model);
+            const pending = inFlight.get(key);
+            if (pending)
+                return pending;
+            const failure = failed.get(key);
+            if (failure && Date.now() < failure.until)
+                return Promise.reject(failure.error);
+            const next = attempt(key, start).catch((err) => {
+                failed.set(key, { error: err, until: Date.now() + policy.backoffMs });
+                onFailure?.(key, err);
+                throw err;
+            }).finally(() => inFlight.delete(key));
+            inFlight.set(key, next);
+            return next;
+        },
+    };
+}
+//# sourceMappingURL=transformers.js.map

package/dist/entry/session-text.d.ts

@@ -3,5 +3,5 @@ export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport, type FailureReport } from '../capture/failure-reading.js';
 export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../util/compaction-items.js';
 //# sourceMappingURL=session-text.d.ts.map

package/dist/entry/session-text.js

@@ -1,8 +1,9 @@
-// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures, git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
+// The hippo-memory/session-text subpath: what a hook reads from a session (turns, working state, failures,
+// git state, compaction items) and the sharing scrub, with no store, database or server in its imports.
 export { collectSessionTurns, sessionTail } from '../capture/transcript.js';
 export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport } from '../capture/failure-reading.js';
 export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../util/compaction-items.js';
 //# sourceMappingURL=session-text.js.map