@claude-flow/cli 3.42.4 → 3.43.0

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 || [],
                 },
             };
@@ -1830,16 +1870,33 @@ export async function bridgeStorePattern(options) {
     try {
         const reasoningBank = registry.get('reasoningBank');
         const patternId = generateId('pattern');
-        if (reasoningBank && typeof reasoningBank.store === 'function') {
-            await reasoningBank.store({
-                id: patternId,
-                content: options.pattern,
-                type: options.type,
-                confidence: options.confidence,
+        // #3327 Finding A — the real method is `storePattern`, and it takes a
+        // ReasoningPattern, NOT the {id, content, type, confidence} shape used
+        // here before. `reasoningBank.store` has never existed on agentdb's
+        // ReasoningBank, so `typeof ... === 'function'` was always false and this
+        // branch was dead code — every write fell through to bridge-fallback while
+        // `agentdb_controllers` cheerfully reported `reasoningBank: enabled=true`.
+        //
+        // Contract (agentdb ReasoningBank.d.ts):
+        //   storePattern({ taskType, approach, successRate, uses?, avgReward?,
+        //                  tags?, metadata? }) => Promise<number>   // sqlite rowid
+        // The embedded text is `${taskType}: ${approach}`, so the caller's pattern
+        // text must land in `approach` for search to match on it.
+        if (reasoningBank && typeof reasoningBank.storePattern === 'function') {
+            const rowId = await reasoningBank.storePattern({
+                taskType: options.type,
+                approach: options.pattern,
+                successRate: options.confidence,
+                tags: [options.type, 'reasoning-pattern'],
                 metadata: options.metadata,
-                timestamp: Date.now(),
             });
-            return { success: true, patternId, controller: 'reasoningBank' };
+            // storePattern returns a numeric rowid; surface it as the caller-facing
+            // id so a later getPattern/deletePattern by this id resolves.
+            return {
+                success: true,
+                patternId: rowId != null ? String(rowId) : patternId,
+                controller: 'reasoningBank',
+            };
         }
         // Fallback: store via bridge SQL
         const patternValue = JSON.stringify({ pattern: options.pattern, type: options.type, confidence: options.confidence, metadata: options.metadata });
@@ -1871,9 +1928,23 @@ 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 {
+    catch (err) {
+        // #3327 Finding A — this catch is what hid the defect for months. When
+        // ReasoningBank threw `embedPassage is not a function`, the error was
+        // discarded and the caller saw an ordinary fallback, indistinguishable
+        // from "no controller registered". Record it so `agentdb_health` and the
+        // degraded `reason` can name the real cause instead of guessing.
+        bridgeFailureReason = err instanceof Error ? err.message : String(err);
         return null;
     }
 }
@@ -1895,11 +1966,17 @@ export async function bridgeSearchPatterns(options) {
             else {
                 results = await reasoningBank.search(options.query, { topK: options.topK || 5, minScore: options.minConfidence || 0.3 });
             }
+            // #3327 Finding A — agentdb returns ReasoningPattern[]: the text lives in
+            // `approach` and the cosine score in `similarity`. Neither `content`/
+            // `pattern` nor `score`/`confidence` exists on that shape, so the old
+            // mapping produced `content: ''` and `score: 0` for every hit even when
+            // the search itself succeeded. Read the real fields first, keeping the
+            // legacy names as fallbacks for the pre-agentdb shape.
             return {
                 results: Array.isArray(results) ? results.map((r) => ({
-                    id: r.id || r.patternId || '',
-                    content: r.content || r.pattern || '',
-                    score: r.score ?? r.confidence ?? 0,
+                    id: String(r.id ?? r.patternId ?? ''),
+                    content: r.approach ?? r.content ?? r.pattern ?? '',
+                    score: r.similarity ?? r.score ?? r.successRate ?? r.confidence ?? 0,
                 })) : [],
                 controller: 'reasoningBank',
             };
@@ -1954,7 +2031,12 @@ export async function bridgeSearchPatterns(options) {
             controller: 'bridge-fallback',
         } : null;
     }
-    catch {
+    catch (err) {
+        // #3327 Finding A — see bridgeStorePattern's catch. `embedQuery is not a
+        // function` died here silently, which is why search reported
+        // `reasoningBank-unavailable:registry-null` (a null return) even though
+        // the registry was present and the controller was reported enabled.
+        bridgeFailureReason = err instanceof Error ? err.message : String(err);
         return null;
     }
 }

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/typesafe-router.d.ts

@@ -0,0 +1,119 @@
+/**
+ * typesafe-router.ts — opt-in `@ruvector/typesafe` augmentation for `hooks_route`.
+ *
+ * Mirrors ADR-150's MetaHarness rules for optional integrations:
+ *   1. Removable — the package is loaded with a dynamic import only; any load,
+ *      construction or decide error falls back to the existing router.
+ *   2. Opt-in    — does nothing unless `CLAUDE_FLOW_ROUTER_TYPESAFE=1`. With the
+ *      flag unset the package is never imported and the legacy result is
+ *      returned unchanged (same object, no added fields).
+ *   3. Optional  — declared as an optional peer of `@claude-flow/cli`.
+ *   4. Honest    — the result carries `routedBy`, typesafe's confidence, abstain
+ *      mass and `calibrated` flag verbatim. The default `hash` embedder is
+ *      uncalibrated, so its confidence is reported as `confidenceCalibrated:
+ *      false` and is never copied into `estimatedMetrics.successProbability`.
+ *
+ * Gate: typesafe's answer is used only when all hold —
+ *   - `abstain <= maxAbstain` (default 0.30)
+ *   - lift = top-1 probability × option count >= `minLift` (default 1.2, i.e.
+ *     20% above chance). Lift, not raw confidence, because confidence scales
+ *     with the option count (~0.1 for ten agents) and differs per embedder.
+ *   - top-1 beats the runner-up by >= `minMargin` (default 0.005); a uniform
+ *     distribution — text that matches nothing — has margin 0.
+ * Otherwise the legacy route is kept and `typesafe.reason` says which gate failed.
+ *
+ * @module typesafe-router
+ */
+/** Keyword/agent table shape shared with hooks-tools' TASK_PATTERNS. */
+export interface RoutingPatternLike {
+    keywords: string[];
+    agents: string[];
+}
+/** One `choice` option in typesafe's `{ what, not_for, examples }` form. */
+export interface TypesafeCriterion {
+    what: string;
+    not_for?: string;
+    examples?: string[];
+}
+/** The subset of a typesafe choice answer this adapter reads. */
+export interface TypesafeChoiceAnswer {
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+    abstain: number;
+    calibrated: boolean;
+    head?: string;
+    model?: string;
+}
+/** The subset of `@ruvector/typesafe`'s module surface this adapter uses. */
+export interface TypesafeModuleLike {
+    createTypesafe(opts?: Record<string, unknown>): {
+        readonly backend?: string;
+        decide(state: string, questions: Record<string, unknown>): Promise<Record<string, unknown>>;
+    };
+    choice?(criteria: Record<string, TypesafeCriterion>): unknown;
+}
+export interface TypesafeRouterConfig {
+    enabled: boolean;
+    minLift: number;
+    maxAbstain: number;
+    minMargin: number;
+    /** `'hash'` (default, uncalibrated) or an ONNX model dir + manifest. */
+    embedder: 'hash' | {
+        kind: 'onnx';
+        modelDir: string;
+        manifest: string;
+    };
+}
+export interface TypesafeRouteOutcome {
+    used: boolean;
+    reason: string;
+    answer?: TypesafeChoiceAnswer;
+    backend?: string;
+    embedder?: string;
+    /** top-1 probability × option count (1.0 = chance). */
+    lift?: number;
+    thresholds: Pick<TypesafeRouterConfig, 'minLift' | 'maxAbstain' | 'minMargin'>;
+}
+/** Injectable deps (tests). `loadModule` defaults to a dynamic import of the package. */
+export interface TypesafeRouterDeps {
+    env?: NodeJS.ProcessEnv;
+    loadModule?: () => Promise<unknown>;
+    debug?: (msg: string) => void;
+}
+/**
+ * Build choice options from the router's pattern table: every primary agent of
+ * a pattern, plus the profiled roles (researcher/reviewer) the table only lists
+ * as alternates. Each pattern's keywords are appended to its primary agent's
+ * `what`, so the options track TASK_PATTERNS rather than a parallel list.
+ */
+export declare function buildAgentCriteria(patterns: Record<string, RoutingPatternLike>): Record<string, TypesafeCriterion>;
+/** Read config from env. Invalid numeric values fall back to the defaults. */
+export declare function readTypesafeConfig(env?: NodeJS.ProcessEnv): TypesafeRouterConfig;
+/**
+ * Stateful router: loads the module and builds one engine on first use, caches
+ * a load failure so a missing package costs one import attempt per process.
+ */
+export declare class TypesafeRouter {
+    private engine;
+    private mod;
+    private loadError;
+    private readonly env;
+    private readonly loadModule;
+    private readonly debug;
+    constructor(deps?: TypesafeRouterDeps);
+    isEnabled(): boolean;
+    private ensureEngine;
+    /** Ask typesafe for an agent. Never throws; `used: false` means keep the legacy route. */
+    route(task: string, patterns: Record<string, RoutingPatternLike>): Promise<TypesafeRouteOutcome>;
+}
+type RouteResult = Record<string, unknown>;
+/**
+ * Merge a typesafe outcome into a legacy `hooks_route` result. Disabled or
+ * error results (`success: false`) pass through untouched.
+ */
+export declare function applyTypesafeRouting(params: Record<string, unknown>, legacy: RouteResult, patterns: Record<string, RoutingPatternLike>, router: TypesafeRouter): Promise<RouteResult>;
+/** Process-wide router used by hooks_route. */
+export declare function getTypesafeRouter(): TypesafeRouter;
+export {};
+//# sourceMappingURL=typesafe-router.d.ts.map