@claude-flow/cli 3.42.5 → 3.44.0

package/dist/src/mcp-tools/memory-tools.js

@@ -61,6 +61,26 @@ function validateMemoryInput(key, value, query, namespace) {
         throw new Error('Namespace contains disallowed characters');
     }
 }
+/**
+ * #3374 — presence check for a schema-`required` string parameter.
+ *
+ * `validateMemoryInput` above is a bounds-and-charset validator: every branch
+ * is truthiness-guarded, so an omitted parameter passes it silently. Nothing
+ * else enforces `inputSchema.required` for these tools, so without this an
+ * omitted `query` travelled down to `generateHashEmbedding`'s
+ * `text.toLowerCase()` and came back as an unrelated TypeError.
+ */
+const MISSING_REQUIRED_PARAM = 'MISSING_REQUIRED_PARAM';
+function missingRequiredString(input, param, tool) {
+    const v = input[param];
+    if (typeof v === 'string' && v.length > 0)
+        return null;
+    const got = v === undefined ? 'it was omitted' : v === '' ? 'it was an empty string' : `got ${v === null ? 'null' : typeof v}`;
+    return {
+        error: `${tool}: required parameter "${param}" must be a non-empty string (${got})`,
+        code: MISSING_REQUIRED_PARAM,
+    };
+}
 // #1884 — sanitize a key produced from arbitrary input (markdown headings,
 // frontmatter names, file names) so it survives validateMemoryInput on the
 // read/delete path. Replaces every dangerous char with `_`. Truncates to
@@ -360,6 +380,10 @@ export const memoryTools = [
             required: ['key', 'value'],
         },
         handler: async (input) => {
+            const missingKey = missingRequiredString(input, 'key', 'memory_store');
+            if (missingKey) {
+                return { success: false, key: input.key, stored: false, hasEmbedding: false, ...missingKey };
+            }
             await ensureInitialized();
             const { storeEntry } = await getMemoryFunctions();
             const key = input.key;
@@ -408,6 +432,8 @@ export const memoryTools = [
                     backend: await describeBackend(),
                     storeTime: `${duration.toFixed(2)}ms`,
                     error: result.error,
+                    // #3325: why hasEmbedding is false, when the bridge could not embed.
+                    ...(result.embeddingError ? { embeddingError: result.embeddingError } : {}),
                 };
             }
             catch (error) {
@@ -432,6 +458,10 @@ export const memoryTools = [
             required: ['key'],
         },
         handler: async (input) => {
+            const missingKey = missingRequiredString(input, 'key', 'memory_retrieve');
+            if (missingKey) {
+                return { key: input.key, namespace: input.namespace, value: null, found: false, ...missingKey };
+            }
             await ensureInitialized();
             const { getEntry } = await getMemoryFunctions();
             const key = input.key;
@@ -500,6 +530,10 @@ export const memoryTools = [
             required: ['query'],
         },
         handler: async (input) => {
+            const missingQuery = missingRequiredString(input, 'query', 'memory_search');
+            if (missingQuery) {
+                return { query: input.query, results: [], total: 0, ...missingQuery };
+            }
             await ensureInitialized();
             const { searchEntries } = await getMemoryFunctions();
             const query = input.query;
@@ -664,6 +698,10 @@ export const memoryTools = [
             required: ['key'],
         },
         handler: async (input) => {
+            const missingKey = missingRequiredString(input, 'key', 'memory_delete');
+            if (missingKey) {
+                return { success: false, key: input.key, namespace: input.namespace, deleted: false, ...missingKey };
+            }
             await ensureInitialized();
             const { deleteEntry } = await getMemoryFunctions();
             const key = input.key;
@@ -1145,6 +1183,10 @@ export const memoryTools = [
             required: ['query'],
         },
         handler: async (input) => {
+            const missingQuery = missingRequiredString(input, 'query', 'memory_search_unified');
+            if (missingQuery) {
+                return { success: false, query: input.query, results: [], total: 0, ...missingQuery };
+            }
             await ensureInitialized();
             const { searchEntries, listEntries } = await getMemoryFunctions();
             validateMemoryInput(undefined, undefined, input.query);

package/dist/src/memory/graph-edge-writer.d.ts

@@ -29,6 +29,16 @@
  *
  * @module v3/cli/memory/graph-edge-writer
  */
+/**
+ * Checkpoint and close the cached handle if it is open (optionally only if it
+ * is open on `dbPath`). Returns true if a handle was released. Never throws.
+ *
+ * busy_timeout is dropped to 0 first so the TRUNCATE checkpoint cannot stall
+ * the event loop behind another connection: if another native connection is
+ * attached the sidecars stay anyway (it owns them), so a busy checkpoint loses
+ * nothing; if this is the only connection, the checkpoint is never busy.
+ */
+export declare function releaseBridgeDb(dbPath?: string): boolean;
 /**
  * Return the better-sqlite3 Database instance for graph_edges writes.
  * Creates the graph_edges table if it is absent (idempotent).

package/dist/src/memory/graph-edge-writer.js

@@ -40,6 +40,72 @@ import { encodeEmbedding } from './embedding-quantization.js';
 let _db = null;
 let _dbPath = '';
 let _dbInitializing = false;
+// #3397 — the handle used to live for the whole MCP server process, keeping
+// the -wal/-shm sidecars on disk forever; the #2735 guard then refused every
+// later sql.js whole-image write (memory_store on Windows, where the native
+// bridge is off by default). The handle is now released after a short idle
+// window, and memory-initializer releases it on demand before its guard.
+//
+// Invariant this relies on: every caller of getBridgeDb() finishes using the
+// returned handle synchronously after the await (no await between it and the
+// last `db.` call), so a release can only land between operations. If a
+// caller ever breaks that, it gets "database connection is not open", which
+// every call site already catches.
+const DEFAULT_IDLE_RELEASE_MS = 1000;
+let _idleTimer = null;
+let _exitHookInstalled = false;
+function idleReleaseMs() {
+    const configured = Number(process.env.CLAUDE_FLOW_GRAPH_EDGE_IDLE_MS);
+    return Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_IDLE_RELEASE_MS;
+}
+function armIdleRelease() {
+    if (_idleTimer)
+        clearTimeout(_idleTimer);
+    _idleTimer = setTimeout(() => { _idleTimer = null; releaseBridgeDb(); }, idleReleaseMs());
+    _idleTimer.unref?.();
+    if (!_exitHookInstalled) {
+        _exitHookInstalled = true;
+        // 'exit' (not SIGINT/SIGTERM handlers, which would change Node's default
+        // termination) — sync-only work, so a clean shutdown checkpoints and
+        // removes the sidecars instead of leaving them for the next process.
+        process.once('exit', () => { releaseBridgeDb(); });
+    }
+}
+/**
+ * Checkpoint and close the cached handle if it is open (optionally only if it
+ * is open on `dbPath`). Returns true if a handle was released. Never throws.
+ *
+ * busy_timeout is dropped to 0 first so the TRUNCATE checkpoint cannot stall
+ * the event loop behind another connection: if another native connection is
+ * attached the sidecars stay anyway (it owns them), so a busy checkpoint loses
+ * nothing; if this is the only connection, the checkpoint is never busy.
+ */
+export function releaseBridgeDb(dbPath) {
+    if (!_db)
+        return false;
+    if (dbPath !== undefined && path.resolve(dbPath) !== path.resolve(_dbPath))
+        return false;
+    if (_idleTimer) {
+        clearTimeout(_idleTimer);
+        _idleTimer = null;
+    }
+    const db = _db;
+    _db = null;
+    _dbPath = '';
+    try {
+        db.pragma('busy_timeout = 0');
+    }
+    catch { /* best-effort */ }
+    try {
+        db.pragma('wal_checkpoint(TRUNCATE)');
+    }
+    catch { /* best-effort */ }
+    try {
+        db.close();
+    }
+    catch { /* best-effort */ }
+    return true;
+}
 /**
  * Return the better-sqlite3 Database instance for graph_edges writes.
  * Creates the graph_edges table if it is absent (idempotent).
@@ -56,8 +122,10 @@ let _dbInitializing = false;
 export async function getBridgeDb(customDbPath, opts) {
     const dbPath = customDbPath ?? path.join(getMemoryRoot(), 'memory.db');
     const createIfMissing = opts?.createIfMissing === true;
-    if (_db && _dbPath === dbPath)
+    if (_db && _dbPath === dbPath) {
+        armIdleRelease();
         return _db;
+    }
     if (_dbInitializing)
         return null;
     _dbInitializing = true;
@@ -120,8 +188,12 @@ export async function getBridgeDb(customDbPath, opts) {
       CREATE INDEX IF NOT EXISTS idx_graph_edges_relation ON graph_edges (relation);
       CREATE INDEX IF NOT EXISTS idx_graph_edges_reinforced ON graph_edges (last_reinforced);
     `);
+        // A handle cached for a different path would otherwise be orphaned
+        // (still open, sidecars still on disk) by the reassignment below.
+        releaseBridgeDb();
         _db = db;
         _dbPath = dbPath;
+        armIdleRelease();
         return db;
     }
     catch {
@@ -214,6 +286,10 @@ export async function countGraphEdges(dbPath) {
  * writes deterministically, regardless of platform/timing.
  */
 export function _resetBridgeDb() {
+    if (_idleTimer) {
+        clearTimeout(_idleTimer);
+        _idleTimer = null;
+    }
     if (_db) {
         try {
             _db.pragma('wal_checkpoint(TRUNCATE)');

package/dist/src/memory/memory-bridge.d.ts

@@ -86,6 +86,10 @@ export declare function bridgeStoreEntry(options: {
      *  still true — this is advisory, not a failure — but callers should
      *  surface it instead of only printing an unconditional success message. */
     persistWarning?: string;
+    /** #3325: set when an embedding was requested but none could be produced
+     *  (agentdb embedder absent/threw AND no real local model). The row was
+     *  written without a vector, so semantic search cannot find it. */
+    embeddingError?: string;
 } | null>;
 /**
  * Search entries via AgentDB v3.
@@ -337,6 +341,8 @@ export declare function bridgeStorePattern(options: {
     success: boolean;
     patternId: string;
     controller: string;
+    hasEmbedding?: boolean;
+    embeddingError?: string;
 } | null>;
 /**
  * Search patterns via ReasoningBank controller.

package/dist/src/memory/memory-bridge.js

@@ -801,6 +801,52 @@ async function rescueAgentdbEmbedder(agentdb) {
     emb.__ruvectorRescued = true;
     _embedderPatched = true;
 }
+/**
+ * #3325: embed text for a bridge row or query.
+ *
+ * AgentDB's embedder is tried first. If it is absent or throws, fall back to
+ * the LOCAL chain — `generateLocalEmbedding`, never the bridge-first
+ * `generateEmbedding`, which would re-enter this bridge (#2312). Only a real
+ * ONNX vector is accepted from the local chain; a hash vector would make the
+ * row look embedded while carrying no meaning. Previously both failure modes
+ * were a bare `catch {}` that stored embedding=NULL and reported nothing.
+ */
+async function embedForBridge(agentdb, text) {
+    let agentdbProblem;
+    const embedder = agentdb?.embedder;
+    // Same mock signal bridgeGenerateEmbedding honours (AUDIT #3): the rescue
+    // tags a degraded embedder backend='mock' when it cannot replace it.
+    const agentdbIsMock = embedder?.isMock === true || embedder?.backend === 'mock';
+    if (agentdbIsMock) {
+        agentdbProblem = 'agentdb embedder is serving mock vectors';
+    }
+    else if (embedder && typeof embedder.embed === 'function') {
+        try {
+            const emb = await embedder.embed(text);
+            if (emb && emb.length > 0) {
+                return { vector: Array.from(emb), model: 'Xenova/all-MiniLM-L6-v2' };
+            }
+            agentdbProblem = 'agentdb embedder returned no vector';
+        }
+        catch (err) {
+            agentdbProblem = `agentdb embedder threw: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    else {
+        agentdbProblem = 'agentdb embedder unavailable';
+    }
+    try {
+        const { generateLocalEmbedding } = await import('./memory-initializer.js');
+        const local = await generateLocalEmbedding(text);
+        if (local.backend === 'onnx' && local.embedding.length > 0) {
+            return { vector: Array.from(local.embedding), model: local.model };
+        }
+        return { vector: null, reason: `${agentdbProblem}; local embedding chain has no real model (backend=${local.backend})` };
+    }
+    catch (err) {
+        return { vector: null, reason: `${agentdbProblem}; local embedding chain failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 // ===== Bridge functions — match memory-initializer.ts signatures =====
 /**
  * Store an entry via AgentDB v3.
@@ -851,26 +897,24 @@ export async function bridgeStoreEntry(options) {
         if (!guardResult.allowed) {
             return { success: false, id, error: `MutationGuard rejected: ${guardResult.reason}` };
         }
-        // Generate embedding via AgentDB's embedder
+        // Generate embedding via AgentDB's embedder, falling back to the local
+        // chain (#3325). If neither can produce one, the row is still written but
+        // the result says why instead of silently storing embedding=NULL.
         let embeddingJson = null;
         let embeddingArr = null;
         let dimensions = 0;
         let model = 'local';
+        let embeddingError;
         if (options.generateEmbeddingFlag !== false && value.length > 0) {
-            try {
-                const embedder = ctx.agentdb.embedder;
-                if (embedder) {
-                    const emb = await embedder.embed(value);
-                    if (emb) {
-                        embeddingArr = Array.from(emb);
-                        embeddingJson = JSON.stringify(embeddingArr);
-                        dimensions = emb.length;
-                        model = 'Xenova/all-MiniLM-L6-v2';
-                    }
-                }
+            const emb = await embedForBridge(ctx.agentdb, value);
+            if (emb.vector) {
+                embeddingArr = emb.vector;
+                embeddingJson = JSON.stringify(embeddingArr);
+                dimensions = embeddingArr.length;
+                model = emb.model;
             }
-            catch {
-                // Embedding failed — store without
+            else {
+                embeddingError = emb.reason;
             }
         }
         // #2775: strict-insert path now auto-resurrects soft-deleted tombstones
@@ -1011,6 +1055,7 @@ export async function bridgeStoreEntry(options) {
             cached: true,
             attested: true,
             ...(persistWarning ? { persistWarning } : {}),
+            ...(embeddingError ? { embeddingError } : {}),
         };
     }
     catch (err) {
@@ -1061,18 +1106,10 @@ export async function bridgeSearchEntries(options) {
         const { query: queryStr, namespace, limit = 10, threshold = 0.3, provenanceFilter } = options;
         const effectiveNamespace = namespace || 'all';
         const startTime = Date.now();
-        // Generate query embedding
-        let queryEmbedding = null;
-        try {
-            const embedder = ctx.agentdb.embedder;
-            if (embedder) {
-                const emb = await embedder.embed(queryStr);
-                queryEmbedding = Array.from(emb);
-            }
-        }
-        catch {
-            // Fall back to keyword search
-        }
+        // Generate query embedding — same agentdb-then-local chain as the write
+        // path (#3325), so rows embedded by the local fallback are searchable.
+        // No vector → keyword (BM25) search only.
+        const queryEmbedding = (await embedForBridge(ctx.agentdb, queryStr)).vector;
         // better-sqlite3: .prepare().all() returns array of objects
         // ADR-323: compose namespace + provenance filters into one WHERE clause.
         const filters = [];
@@ -1300,7 +1337,10 @@ export async function bridgeGetEntry(options) {
                     accessCount: cached.accessCount ?? 0,
                     createdAt: cached.createdAt || new Date().toISOString(),
                     updatedAt: cached.updatedAt || new Date().toISOString(),
-                    hasEmbedding: !!cached.embedding,
+                    // #3325: the cache holds the `entry` object built below, which has
+                    // `hasEmbedding` but no `embedding` field — so `!!cached.embedding`
+                    // reported false on every cache hit, even for embedded rows.
+                    hasEmbedding: typeof cached.hasEmbedding === 'boolean' ? cached.hasEmbedding : !!cached.embedding,
                     tags: cached.tags || [],
                 },
             };
@@ -1888,7 +1928,15 @@ export async function bridgeStorePattern(options) {
         // was actually stored under. getEntry/memory_retrieve look up by `key`,
         // so returning result.id here handed the caller a handle that can never
         // be read back — return `patternId` (the real key) instead.
-        return { success: true, patternId, controller: 'bridge-fallback' };
+        // #3325: say whether the row got a vector. Without one, Tier-1 (semantic)
+        // pattern search cannot find it — report that here, at write time.
+        return {
+            success: true,
+            patternId,
+            controller: 'bridge-fallback',
+            hasEmbedding: !!result.embedding,
+            ...(result.embeddingError ? { embeddingError: result.embeddingError } : {}),
+        };
     }
     catch (err) {
         // #3327 Finding A — this catch is what hid the defect for months. When

package/dist/src/memory/memory-initializer.d.ts

@@ -452,6 +452,9 @@ export declare function storeEntry(options: {
     /** #2968: set when the bridge's checkpoint failed in a way indicating
      *  this write may not be durably persisted (sql.js fallback driver). */
     persistWarning?: string;
+    /** #3325: set by the bridge when an embedding was requested but none could
+     *  be produced — the row is stored without a vector. */
+    embeddingError?: string;
 }>;
 /**
  * Search entries using sql.js with vector similarity

package/dist/src/memory/memory-initializer.js

@@ -81,6 +81,23 @@ function hasNativeWalSidecars(dbPath) {
         return true;
     }
 }
+/**
+ * #3397 — this process's own graph-edge-writer handle keeps -wal/-shm on disk
+ * between its idle-release ticks. Release (checkpoint + close) it before the
+ * #2735 guard runs, so the guard only sees sidecars some OTHER native
+ * connection is holding. The guard itself is unchanged: even a same-process
+ * open WAL connection makes a whole-image sql.js write unsafe until its WAL
+ * has been checkpointed, which is exactly what releasing does.
+ */
+async function releaseOwnNativeHandle(dbPath) {
+    try {
+        const { releaseBridgeDb } = await import('./graph-edge-writer.js');
+        releaseBridgeDb(dbPath);
+    }
+    catch {
+        // Writer module unavailable — nothing of ours to release; the guard decides.
+    }
+}
 /**
  * #1854: previously every site that needed the memory directory hardcoded
  * `getMemoryRoot()`, so the documented config entry
@@ -1957,7 +1974,17 @@ export async function applyTemporalDecay(dbPath) {
         };
     }
 }
+/**
+ * State of the LOCAL embedding chain only (transformers.js / agentic-flow /
+ * ruvector ONNX / hash). #3375: the AgentDB bridge's result is cached
+ * separately in `bridgeEmbeddingInfo` and must never be written here — it used
+ * to be recorded as `{ loaded: true, model: null }`, which made
+ * generateLocalEmbedding() skip loading any local model and always return the
+ * hash fallback, so rescueAgentdbEmbedder()'s `backend === 'onnx'` probe could
+ * never pass.
+ */
 let embeddingModelState = null;
+let bridgeEmbeddingInfo = null;
 /**
  * Lazy load ONNX embedding model
  * Only loads when first embedding is requested
@@ -1966,10 +1993,11 @@ export async function loadEmbeddingModel(options) {
     const { verbose = false } = options || {};
     const startTime = Date.now();
     // Already loaded
-    if (embeddingModelState?.loaded) {
+    const cached = bridgeEmbeddingInfo ?? (embeddingModelState?.loaded ? embeddingModelState : null);
+    if (cached) {
         return {
             success: true,
-            dimensions: embeddingModelState.dimensions,
+            dimensions: cached.dimensions,
             modelName: 'cached',
             loadTime: 0
         };
@@ -1979,16 +2007,24 @@ export async function loadEmbeddingModel(options) {
     if (bridge) {
         const bridgeResult = await bridge.bridgeLoadEmbeddingModel();
         if (bridgeResult && bridgeResult.success) {
-            // Mark local state as loaded too so subsequent calls use cache
-            embeddingModelState = {
-                loaded: true,
-                model: null, // Bridge handles embedding
-                tokenizer: null,
-                dimensions: bridgeResult.dimensions
-            };
+            // #3375: cache the bridge result on its own. Do NOT mark the local
+            // chain as loaded — the bridge's model is not callable from here.
+            bridgeEmbeddingInfo = { dimensions: bridgeResult.dimensions };
             return bridgeResult;
         }
     }
+    return loadLocalEmbeddingChain(verbose, startTime);
+}
+/**
+ * Load the LOCAL embedding chain into `embeddingModelState`, never consulting
+ * the AgentDB bridge. Used by loadEmbeddingModel() after the bridge declines,
+ * and directly by generateLocalEmbedding() so the "bridge-free" contract the
+ * #2312 comment on that function describes actually holds (#3375).
+ */
+async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now()) {
+    if (embeddingModelState?.loaded) {
+        return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+    }
     try {
         // ADR-094: prefer @huggingface/transformers (clears protobufjs <7.5.5
         // critical RCE chain), fall back to legacy @xenova/transformers.
@@ -2195,9 +2231,12 @@ export async function generateEmbedding(text) {
  * Keeping the local chain as its own export breaks that cycle structurally.
  */
 export async function generateLocalEmbedding(text) {
-    // Ensure model is loaded
+    // Ensure the LOCAL model is loaded. #3375: this must not go through
+    // loadEmbeddingModel(), which is bridge-first — when the bridge answered
+    // there, no local model was ever loaded and this function always returned
+    // the hash fallback.
     if (!embeddingModelState?.loaded) {
-        await loadEmbeddingModel();
+        await loadLocalEmbeddingChain();
     }
     // #2461: loadEmbeddingModel() can leave embeddingModelState null when an
     // earlier loader (transformers fetch, ruvector init) throws and we never
@@ -2535,6 +2574,7 @@ export async function storeEntry(options) {
         // this closes and its known residual (the narrow assess-then-write
         // race). This check gates ensureSchemaColumns()'s own whole-image
         // write below too, not just this function's.
+        await releaseOwnNativeHandle(dbPath);
         if (hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
@@ -3043,6 +3083,7 @@ export async function getEntry(options) {
         // this closes. Applies here too because the fallback's access_count
         // bump is itself a whole-image write, not a lightweight read, even
         // though this function's contract reads as a "get".
+        await releaseOwnNativeHandle(dbPath);
         if (hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,
@@ -3162,6 +3203,7 @@ export async function deleteEntry(options) {
         }
         // #2735 — see storeEntry's identical gate for the corruption mechanism
         // this closes.
+        await releaseOwnNativeHandle(dbPath);
         if (hasNativeWalSidecars(dbPath)) {
             return {
                 success: false,

package/dist/src/ruvector/router-embedder.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Router embedder (ADR-390).
+ *
+ * `hooks_route` compares a task with each agent pattern's keywords in a 384-d
+ * vector index. Historically both sides came from a character hash
+ * (`generateSimpleEmbedding`), which measures spelling, not meaning. This
+ * module lets the router use the local sentence model (all-MiniLM-L6-v2, 384-d)
+ * instead, with the hash as the fallback.
+ *
+ * Rules (ADR-390 §Decision):
+ *  - The MiniLM path uses `generateLocalEmbedding` ONLY. Never the bridge-first
+ *    `generateEmbedding` — that recursed without bound in #2312.
+ *  - One embedder per index: if ANY text cannot be embedded by the real model
+ *    (throw, backend !== 'onnx', or a non-384 vector), EVERY text in the call
+ *    is embedded with the hash, and the result says so.
+ *  - The default stays `hash` until ADR-391's benchmark says otherwise.
+ *
+ * Selection: `CLAUDE_FLOW_ROUTER_EMBEDDER=minilm|hash`. The router index is
+ * process-lifetime state, so the env var is read when the index is (re)built,
+ * not per CLI invocation.
+ */
+export type RouterEmbedderKind = 'minilm' | 'hash';
+/** Default embedder. ADR-391 decides whether this flips to 'minilm'. */
+export declare const DEFAULT_ROUTER_EMBEDDER: RouterEmbedderKind;
+/** Dimension of the router index (VectorDb + SemanticRouter are built at 384). */
+export declare const ROUTER_EMBEDDING_DIM = 384;
+export declare const ROUTER_EMBEDDER_ENV = "CLAUDE_FLOW_ROUTER_EMBEDDER";
+export interface RouterEmbedderSelection {
+    kind: RouterEmbedderKind;
+    /** Set when the requested value was invalid and the default was used. */
+    reason?: string;
+}
+export interface RouterEmbeddingResult {
+    vectors: Float32Array[];
+    /** The embedder that actually produced `vectors` (after any degradation). */
+    embedder: RouterEmbedderKind;
+    /** Why the result is `hash` when `minilm` was requested. */
+    reason?: string;
+}
+/**
+ * Resolve which embedder the router should use.
+ * Precedence: explicit override > CLAUDE_FLOW_ROUTER_EMBEDDER > DEFAULT_ROUTER_EMBEDDER.
+ */
+export declare function resolveRouterEmbedder(override?: RouterEmbedderKind, env?: NodeJS.ProcessEnv): RouterEmbedderSelection;
+/**
+ * Deterministic character-hash embedding (the router's historical embedder).
+ * Moved verbatim from hooks-tools.ts; do not change the math — existing routes
+ * and thresholds were calibrated against it.
+ */
+export declare function generateSimpleEmbedding(text: string, dimension?: number): Float32Array;
+/**
+ * Embed texts for the router. All vectors in one result come from ONE embedder.
+ * `hash` never touches the model (no load cost for default users).
+ */
+export declare function embedForRouter(texts: readonly string[], kind?: RouterEmbedderKind): Promise<RouterEmbeddingResult>;
+/** Test hook: clear the MiniLM vector memo. */
+export declare function clearRouterEmbedderCache(): void;
+//# sourceMappingURL=router-embedder.d.ts.map