agentic-flow 3.0.0-alpha.2 → 3.1.0

package/dist/reasoningbank/utils/embeddings.d.ts

@@ -1,13 +1,41 @@
 /**
  * Embedding generation for semantic similarity
  * Uses local transformers.js - no API key required!
+ *
+ * Logs go to stderr so that stdout stays clean for callers that pipe
+ * structured output (CLIs, MCP stdio servers).
  */
+/**
+ * The space every vector in this process belongs to. Set by the first
+ * embedding and kept until resetEmbeddingBackend(): model vectors and hash
+ * vectors are not comparable, so a process never mixes them (issue #246).
+ */
+export type EmbeddingKind = 'local' | 'hash';
+/**
+ * True when embeddings come from the transformer model; false when they come
+ * from the deterministic hash fallback, whose vectors carry no semantic
+ * similarity. Returns false until the first embedding call has initialized the
+ * model.
+ */
+export declare function isSemanticEmbedding(): boolean;
+/**
+ * The space this process's embeddings are in, or null before the first one.
+ * Vectors of different kinds must never be compared.
+ */
+export declare function getEmbeddingKind(): EmbeddingKind | null;
+/**
+ * Forget the backend choice and the cache, so the next embedding tries to load
+ * the model again. Vectors produced before the reset may be in a different
+ * space from those produced after it; re-embed anything you keep.
+ */
+export declare function resetEmbeddingBackend(): void;
 /**
  * Compute embedding for text using local model
  */
 export declare function computeEmbedding(text: string): Promise<Float32Array>;
 /**
- * Batch compute embeddings (more efficient)
+ * Batch compute embeddings. Cache misses are embedded with one pipeline call
+ * per chunk of texts rather than one call per text.
  */
 export declare function computeEmbeddingBatch(texts: string[]): Promise<Float32Array[]>;
 /**

package/dist/reasoningbank/utils/embeddings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../../src/reasoningbank/utils/embeddings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2DH;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiD1E;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAEpF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AA+CD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../../src/reasoningbank/utils/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyBH;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAyE7C;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAK5C;AAkBD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA4B1E;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA6CpF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AA+CD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/reasoningbank/utils/embeddings.js

@@ -1,72 +1,137 @@
 /**
  * Embedding generation for semantic similarity
  * Uses local transformers.js - no API key required!
+ *
+ * Logs go to stderr so that stdout stays clean for callers that pipe
+ * structured output (CLIs, MCP stdio servers).
  */
-import { pipeline, env } from '@xenova/transformers';
+import { pipeline, env } from '@huggingface/transformers';
 import { loadConfig } from './config.js';
 // Configure transformers.js to use WASM backend only (avoid ONNX runtime issues)
 // The native ONNX runtime causes "DefaultLogger not registered" errors in Node.js
 env.backends.onnx.wasm.proxy = false; // Disable ONNX runtime proxy
 env.backends.onnx.wasm.numThreads = 1; // Single thread for stability
+const MODEL_ID = 'Xenova/all-MiniLM-L6-v2';
+const MODEL_DIMS = 384;
+const CACHE_MAX_ENTRIES = 1000;
+// Texts per pipeline call in computeEmbeddingBatch. Bounds padding waste and
+// peak memory when a batch mixes short and long texts.
+//
+// The q8 model quantizes activations dynamically with one scale per tensor, so
+// a batched vector depends slightly on its batch-mates: cosine vs. the same
+// text embedded alone is ~0.99 (min ~0.985 measured). fp32 weights are exact
+// but slower for single texts and change every stored vector.
+const BATCH_CHUNK_SIZE = 32;
 let embeddingPipeline = null;
-let isInitializing = false;
+let initializationPromise = null;
+let embeddingKind = null;
 const embeddingCache = new Map();
+function cacheGet(key) {
+    const entry = embeddingCache.get(key);
+    if (!entry)
+        return undefined;
+    embeddingCache.delete(key);
+    if (entry.expiresAt <= Date.now())
+        return undefined;
+    embeddingCache.set(key, entry); // move to most-recently-used
+    return entry.vector;
+}
+function cacheSet(key, vector, ttlSeconds) {
+    embeddingCache.delete(key);
+    embeddingCache.set(key, { vector, expiresAt: Date.now() + ttlSeconds * 1000 });
+    while (embeddingCache.size > CACHE_MAX_ENTRIES) {
+        const oldest = embeddingCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        embeddingCache.delete(oldest);
+    }
+}
+function cacheTtlSeconds() {
+    return loadConfig()?.embeddings?.cache_ttl_seconds || 3600;
+}
 /**
  * Initialize the embedding pipeline (lazy load)
+ * RACE CONDITION FIX: Use promise-based initialization instead of busy-wait
  */
 async function initializeEmbeddings() {
+    // Already initialized
     if (embeddingPipeline)
         return;
-    if (isInitializing) {
-        // Wait for initialization to complete
-        while (isInitializing) {
-            await new Promise(resolve => setTimeout(resolve, 100));
-        }
-        return;
-    }
-    // Detect npx environment (known transformer initialization issues)
-    const isNpxEnv = process.env.npm_lifecycle_event === 'npx' ||
-        process.env.npm_execpath?.includes('npx') ||
-        process.cwd().includes('/_npx/') ||
-        process.cwd().includes('\\_npx\\');
-    if (isNpxEnv && !process.env.FORCE_TRANSFORMERS) {
-        console.log('[Embeddings] NPX environment detected - using hash-based embeddings');
-        console.log('[Embeddings] For semantic search, install globally: npm install -g claude-flow');
-        isInitializing = false;
-        return;
-    }
-    isInitializing = true;
-    console.log('[Embeddings] Initializing local embedding model (Xenova/all-MiniLM-L6-v2)...');
-    console.log('[Embeddings] First run will download ~23MB model...');
-    try {
-        embeddingPipeline = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true } // Smaller, faster
-        );
-        console.log('[Embeddings] Local model ready! (384 dimensions)');
+    // Initialization in progress - await existing promise
+    if (initializationPromise) {
+        return initializationPromise;
     }
-    catch (error) {
-        console.error('[Embeddings] Failed to initialize:', error?.message || error);
-        console.warn('[Embeddings] Falling back to hash-based embeddings');
-    }
-    finally {
-        isInitializing = false;
+    // RACE CONDITION FIX: Create promise for concurrent callers to await
+    initializationPromise = (async () => {
+        console.error(`[Embeddings] Initializing local embedding model (${MODEL_ID})...`);
+        console.error('[Embeddings] First run will download ~23MB model...');
+        try {
+            embeddingPipeline = await pipeline('feature-extraction', MODEL_ID, { dtype: 'q8' } // quantized weights
+            );
+            console.error(`[Embeddings] Local model ready! (${MODEL_DIMS} dimensions)`);
+        }
+        catch (error) {
+            console.error('[Embeddings] Failed to initialize:', error?.message || error);
+            console.error('[Embeddings] Falling back to hash-based embeddings (not semantic)');
+            // No automatic retry: a later successful load would put new vectors in a
+            // different space from the hash vectors already handed out. Call
+            // resetEmbeddingBackend() to try the model again.
+        }
+    })();
+    return initializationPromise;
+}
+/**
+ * True when embeddings come from the transformer model; false when they come
+ * from the deterministic hash fallback, whose vectors carry no semantic
+ * similarity. Returns false until the first embedding call has initialized the
+ * model.
+ */
+export function isSemanticEmbedding() {
+    return embeddingKind === 'local' || (embeddingKind === null && embeddingPipeline !== null);
+}
+/**
+ * The space this process's embeddings are in, or null before the first one.
+ * Vectors of different kinds must never be compared.
+ */
+export function getEmbeddingKind() {
+    return embeddingKind;
+}
+/**
+ * Forget the backend choice and the cache, so the next embedding tries to load
+ * the model again. Vectors produced before the reset may be in a different
+ * space from those produced after it; re-embed anything you keep.
+ */
+export function resetEmbeddingBackend() {
+    embeddingPipeline = null;
+    initializationPromise = null;
+    embeddingKind = null;
+    embeddingCache.clear();
+}
+/** Fix the process to one space on first use; refuse to switch afterwards. */
+function commitKind(kind) {
+    if (embeddingKind === null)
+        embeddingKind = kind;
+    else if (embeddingKind !== kind) {
+        throw new Error(`[Embeddings] refusing to produce a ${kind} vector: this process already embeds with ${embeddingKind}`);
     }
 }
+function modelFailure(error) {
+    return new Error(`[Embeddings] model failed (${error?.message || error}); not substituting a hash vector, which would not be comparable with the model vectors already produced`);
+}
 /**
  * Compute embedding for text using local model
  */
 export async function computeEmbedding(text) {
-    const config = loadConfig();
-    // Check cache
-    const cacheKey = `local:${text}`;
-    if (embeddingCache.has(cacheKey)) {
-        return embeddingCache.get(cacheKey);
-    }
+    const cached = cacheGet(text);
+    if (cached)
+        return cached;
+    // A process already in the hash space stays there; don't load the model.
+    if (embeddingKind !== 'hash')
+        await initializeEmbeddings();
     let embedding;
-    // Initialize if needed
-    await initializeEmbeddings();
     if (embeddingPipeline) {
+        commitKind('local');
         try {
-            // Use transformers.js for real embeddings
             const output = await embeddingPipeline(text, {
                 pooling: 'mean',
                 normalize: true
@@ -75,38 +140,70 @@ export async function computeEmbedding(text) {
         }
         catch (error) {
             console.error('[Embeddings] Generation failed:', error?.message || error);
-            embedding = hashEmbed(text, 384); // Fallback
+            throw modelFailure(error);
         }
     }
     else {
-        // Fallback to hash-based embeddings
-        const dims = config?.embeddings?.dimensions || 384;
+        commitKind('hash');
+        const dims = loadConfig()?.embeddings?.dimensions || MODEL_DIMS;
         embedding = hashEmbed(text, dims);
     }
-    // Cache with LRU (limit 1000 entries)
-    if (embeddingCache.size > 1000) {
-        const firstKey = embeddingCache.keys().next().value;
-        if (firstKey) {
-            embeddingCache.delete(firstKey);
-        }
-    }
-    embeddingCache.set(cacheKey, embedding);
-    // Set TTL for cache entry
-    const ttl = config?.embeddings?.cache_ttl_seconds || 3600;
-    setTimeout(() => embeddingCache.delete(cacheKey), ttl * 1000);
+    cacheSet(text, embedding, cacheTtlSeconds());
     return embedding;
 }
 /**
- * Batch compute embeddings (more efficient)
+ * Batch compute embeddings. Cache misses are embedded with one pipeline call
+ * per chunk of texts rather than one call per text.
  */
 export async function computeEmbeddingBatch(texts) {
-    return Promise.all(texts.map(text => computeEmbedding(text)));
+    if (embeddingKind !== 'hash')
+        await initializeEmbeddings();
+    if (!embeddingPipeline) {
+        return Promise.all(texts.map(text => computeEmbedding(text)));
+    }
+    commitKind('local');
+    const results = new Array(texts.length);
+    const missing = new Map(); // text -> result indices
+    texts.forEach((text, i) => {
+        const cached = cacheGet(text);
+        if (cached) {
+            results[i] = cached;
+            return;
+        }
+        const indices = missing.get(text);
+        if (indices)
+            indices.push(i);
+        else
+            missing.set(text, [i]);
+    });
+    const ttl = cacheTtlSeconds();
+    const uniqueTexts = Array.from(missing.keys());
+    for (let start = 0; start < uniqueTexts.length; start += BATCH_CHUNK_SIZE) {
+        const chunk = uniqueTexts.slice(start, start + BATCH_CHUNK_SIZE);
+        let vectors;
+        try {
+            const output = await embeddingPipeline(chunk, { pooling: 'mean', normalize: true });
+            const dims = output.dims[output.dims.length - 1];
+            const data = output.data;
+            vectors = chunk.map((_, j) => new Float32Array(data.subarray(j * dims, (j + 1) * dims)));
+        }
+        catch (error) {
+            console.error('[Embeddings] Batch generation failed:', error?.message || error);
+            throw modelFailure(error);
+        }
+        chunk.forEach((text, j) => {
+            cacheSet(text, vectors[j], ttl);
+            for (const i of missing.get(text))
+                results[i] = vectors[j];
+        });
+    }
+    return results;
 }
 /**
  * Get embedding dimensions
  */
 export function getEmbeddingDimensions() {
-    return 384; // all-MiniLM-L6-v2 uses 384 dimensions
+    return MODEL_DIMS; // all-MiniLM-L6-v2 uses 384 dimensions
 }
 /**
  * Deterministic hash-based embedding (fallback)

package/dist/reasoningbank/utils/embeddings.js.map

@@ -1 +1 @@
-{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../../src/reasoningbank/utils/embeddings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Embedding generation for semantic similarity\n * Uses local transformers.js - no API key required!\n */\n\nimport { pipeline, env } from '@xenova/transformers';\nimport { loadConfig } from './config.js';\n\n// Configure transformers.js to use WASM backend only (avoid ONNX runtime issues)\n// The native ONNX runtime causes \"DefaultLogger not registered\" errors in Node.js\nenv.backends.onnx.wasm.proxy = false; // Disable ONNX runtime proxy\nenv.backends.onnx.wasm.numThreads = 1; // Single thread for stability\n\nlet embeddingPipeline: any = null;\nlet isInitializing = false;\nconst embeddingCache = new Map<string, Float32Array>();\n\n/**\n * Initialize the embedding pipeline (lazy load)\n */\nasync function initializeEmbeddings(): Promise<void> {\n  if (embeddingPipeline) return;\n  if (isInitializing) {\n    // Wait for initialization to complete\n    while (isInitializing) {\n      await new Promise(resolve => setTimeout(resolve, 100));\n    }\n    return;\n  }\n\n  // Detect npx environment (known transformer initialization issues)\n  const isNpxEnv = process.env.npm_lifecycle_event === 'npx' ||\n                   process.env.npm_execpath?.includes('npx') ||\n                   process.cwd().includes('/_npx/') ||\n                   process.cwd().includes('\\\\_npx\\\\');\n\n  if (isNpxEnv && !process.env.FORCE_TRANSFORMERS) {\n    console.log('[Embeddings] NPX environment detected - using hash-based embeddings');\n    console.log('[Embeddings] For semantic search, install globally: npm install -g claude-flow');\n    isInitializing = false;\n    return;\n  }\n\n  isInitializing = true;\n  console.log('[Embeddings] Initializing local embedding model (Xenova/all-MiniLM-L6-v2)...');\n  console.log('[Embeddings] First run will download ~23MB model...');\n\n  try {\n    embeddingPipeline = await pipeline(\n      'feature-extraction',\n      'Xenova/all-MiniLM-L6-v2',\n      { quantized: true } // Smaller, faster\n    );\n    console.log('[Embeddings] Local model ready! (384 dimensions)');\n  } catch (error: any) {\n    console.error('[Embeddings] Failed to initialize:', error?.message || error);\n    console.warn('[Embeddings] Falling back to hash-based embeddings');\n  } finally {\n    isInitializing = false;\n  }\n}\n\n/**\n * Compute embedding for text using local model\n */\nexport async function computeEmbedding(text: string): Promise<Float32Array> {\n  const config = loadConfig();\n\n  // Check cache\n  const cacheKey = `local:${text}`;\n  if (embeddingCache.has(cacheKey)) {\n    return embeddingCache.get(cacheKey)!;\n  }\n\n  let embedding: Float32Array;\n\n  // Initialize if needed\n  await initializeEmbeddings();\n\n  if (embeddingPipeline) {\n    try {\n      // Use transformers.js for real embeddings\n      const output = await embeddingPipeline(text, {\n        pooling: 'mean',\n        normalize: true\n      });\n      embedding = new Float32Array(output.data);\n    } catch (error: any) {\n      console.error('[Embeddings] Generation failed:', error?.message || error);\n      embedding = hashEmbed(text, 384); // Fallback\n    }\n  } else {\n    // Fallback to hash-based embeddings\n    const dims = config?.embeddings?.dimensions || 384;\n    embedding = hashEmbed(text, dims);\n  }\n\n  // Cache with LRU (limit 1000 entries)\n  if (embeddingCache.size > 1000) {\n    const firstKey = embeddingCache.keys().next().value;\n    if (firstKey) {\n      embeddingCache.delete(firstKey);\n    }\n  }\n  embeddingCache.set(cacheKey, embedding);\n\n  // Set TTL for cache entry\n  const ttl = config?.embeddings?.cache_ttl_seconds || 3600;\n  setTimeout(\n    () => embeddingCache.delete(cacheKey),\n    ttl * 1000\n  );\n\n  return embedding;\n}\n\n/**\n * Batch compute embeddings (more efficient)\n */\nexport async function computeEmbeddingBatch(texts: string[]): Promise<Float32Array[]> {\n  return Promise.all(texts.map(text => computeEmbedding(text)));\n}\n\n/**\n * Get embedding dimensions\n */\nexport function getEmbeddingDimensions(): number {\n  return 384; // all-MiniLM-L6-v2 uses 384 dimensions\n}\n\n/**\n * Deterministic hash-based embedding (fallback)\n */\nfunction hashEmbed(text: string, dims: number): Float32Array {\n  const hash = simpleHash(text);\n  const vec = new Float32Array(dims);\n\n  // Generate deterministic pseudo-random vector from hash\n  for (let i = 0; i < dims; i++) {\n    vec[i] = Math.sin(hash * (i + 1) * 0.01) + Math.cos(hash * i * 0.02);\n  }\n\n  return normalize(vec);\n}\n\n/**\n * Simple string hash function\n */\nfunction simpleHash(str: string): number {\n  let hash = 0;\n  for (let i = 0; i < str.length; i++) {\n    hash = ((hash << 5) - hash) + str.charCodeAt(i);\n    hash |= 0;\n  }\n  return Math.abs(hash);\n}\n\n/**\n * Normalize vector to unit length\n */\nfunction normalize(vec: Float32Array): Float32Array {\n  let mag = 0;\n  for (let i = 0; i < vec.length; i++) {\n    mag += vec[i] * vec[i];\n  }\n  mag = Math.sqrt(mag);\n\n  if (mag === 0) return vec;\n\n  for (let i = 0; i < vec.length; i++) {\n    vec[i] /= mag;\n  }\n  return vec;\n}\n\n/**\n * Clear embedding cache\n */\nexport function clearEmbeddingCache(): void {\n  embeddingCache.clear();\n}\n"]}
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../../../src/reasoningbank/utils/embeddings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Embedding generation for semantic similarity\n * Uses local transformers.js - no API key required!\n *\n * Logs go to stderr so that stdout stays clean for callers that pipe\n * structured output (CLIs, MCP stdio servers).\n */\n\nimport { pipeline, env } from '@huggingface/transformers';\nimport { loadConfig } from './config.js';\n\n// Configure transformers.js to use WASM backend only (avoid ONNX runtime issues)\n// The native ONNX runtime causes \"DefaultLogger not registered\" errors in Node.js\nenv.backends.onnx.wasm.proxy = false; // Disable ONNX runtime proxy\nenv.backends.onnx.wasm.numThreads = 1; // Single thread for stability\n\nconst MODEL_ID = 'Xenova/all-MiniLM-L6-v2';\nconst MODEL_DIMS = 384;\nconst CACHE_MAX_ENTRIES = 1000;\n// Texts per pipeline call in computeEmbeddingBatch. Bounds padding waste and\n// peak memory when a batch mixes short and long texts.\n//\n// The q8 model quantizes activations dynamically with one scale per tensor, so\n// a batched vector depends slightly on its batch-mates: cosine vs. the same\n// text embedded alone is ~0.99 (min ~0.985 measured). fp32 weights are exact\n// but slower for single texts and change every stored vector.\nconst BATCH_CHUNK_SIZE = 32;\n\nlet embeddingPipeline: any = null;\nlet initializationPromise: Promise<void> | null = null;\n\n/**\n * The space every vector in this process belongs to. Set by the first\n * embedding and kept until resetEmbeddingBackend(): model vectors and hash\n * vectors are not comparable, so a process never mixes them (issue #246).\n */\nexport type EmbeddingKind = 'local' | 'hash';\nlet embeddingKind: EmbeddingKind | null = null;\n\n/**\n * LRU cache with lazy TTL expiry. No timers: an expired entry is dropped when\n * it is next read, so the cache never keeps the event loop alive.\n */\ninterface CacheEntry {\n  vector: Float32Array;\n  expiresAt: number;\n}\nconst embeddingCache = new Map<string, CacheEntry>();\n\nfunction cacheGet(key: string): Float32Array | undefined {\n  const entry = embeddingCache.get(key);\n  if (!entry) return undefined;\n  embeddingCache.delete(key);\n  if (entry.expiresAt <= Date.now()) return undefined;\n  embeddingCache.set(key, entry); // move to most-recently-used\n  return entry.vector;\n}\n\nfunction cacheSet(key: string, vector: Float32Array, ttlSeconds: number): void {\n  embeddingCache.delete(key);\n  embeddingCache.set(key, { vector, expiresAt: Date.now() + ttlSeconds * 1000 });\n  while (embeddingCache.size > CACHE_MAX_ENTRIES) {\n    const oldest = embeddingCache.keys().next().value;\n    if (oldest === undefined) break;\n    embeddingCache.delete(oldest);\n  }\n}\n\nfunction cacheTtlSeconds(): number {\n  return loadConfig()?.embeddings?.cache_ttl_seconds || 3600;\n}\n\n/**\n * Initialize the embedding pipeline (lazy load)\n * RACE CONDITION FIX: Use promise-based initialization instead of busy-wait\n */\nasync function initializeEmbeddings(): Promise<void> {\n  // Already initialized\n  if (embeddingPipeline) return;\n\n  // Initialization in progress - await existing promise\n  if (initializationPromise) {\n    return initializationPromise;\n  }\n\n  // RACE CONDITION FIX: Create promise for concurrent callers to await\n  initializationPromise = (async () => {\n    console.error(`[Embeddings] Initializing local embedding model (${MODEL_ID})...`);\n    console.error('[Embeddings] First run will download ~23MB model...');\n\n    try {\n      embeddingPipeline = await pipeline(\n        'feature-extraction',\n        MODEL_ID,\n        { dtype: 'q8' } // quantized weights\n      );\n      console.error(`[Embeddings] Local model ready! (${MODEL_DIMS} dimensions)`);\n    } catch (error: any) {\n      console.error('[Embeddings] Failed to initialize:', error?.message || error);\n      console.error('[Embeddings] Falling back to hash-based embeddings (not semantic)');\n      // No automatic retry: a later successful load would put new vectors in a\n      // different space from the hash vectors already handed out. Call\n      // resetEmbeddingBackend() to try the model again.\n    }\n  })();\n\n  return initializationPromise;\n}\n\n/**\n * True when embeddings come from the transformer model; false when they come\n * from the deterministic hash fallback, whose vectors carry no semantic\n * similarity. Returns false until the first embedding call has initialized the\n * model.\n */\nexport function isSemanticEmbedding(): boolean {\n  return embeddingKind === 'local' || (embeddingKind === null && embeddingPipeline !== null);\n}\n\n/**\n * The space this process's embeddings are in, or null before the first one.\n * Vectors of different kinds must never be compared.\n */\nexport function getEmbeddingKind(): EmbeddingKind | null {\n  return embeddingKind;\n}\n\n/**\n * Forget the backend choice and the cache, so the next embedding tries to load\n * the model again. Vectors produced before the reset may be in a different\n * space from those produced after it; re-embed anything you keep.\n */\nexport function resetEmbeddingBackend(): void {\n  embeddingPipeline = null;\n  initializationPromise = null;\n  embeddingKind = null;\n  embeddingCache.clear();\n}\n\n/** Fix the process to one space on first use; refuse to switch afterwards. */\nfunction commitKind(kind: EmbeddingKind): void {\n  if (embeddingKind === null) embeddingKind = kind;\n  else if (embeddingKind !== kind) {\n    throw new Error(\n      `[Embeddings] refusing to produce a ${kind} vector: this process already embeds with ${embeddingKind}`\n    );\n  }\n}\n\nfunction modelFailure(error: any): Error {\n  return new Error(\n    `[Embeddings] model failed (${error?.message || error}); not substituting a hash vector, which would not be comparable with the model vectors already produced`\n  );\n}\n\n/**\n * Compute embedding for text using local model\n */\nexport async function computeEmbedding(text: string): Promise<Float32Array> {\n  const cached = cacheGet(text);\n  if (cached) return cached;\n\n  // A process already in the hash space stays there; don't load the model.\n  if (embeddingKind !== 'hash') await initializeEmbeddings();\n\n  let embedding: Float32Array;\n  if (embeddingPipeline) {\n    commitKind('local');\n    try {\n      const output = await embeddingPipeline(text, {\n        pooling: 'mean',\n        normalize: true\n      });\n      embedding = new Float32Array(output.data);\n    } catch (error: any) {\n      console.error('[Embeddings] Generation failed:', error?.message || error);\n      throw modelFailure(error);\n    }\n  } else {\n    commitKind('hash');\n    const dims = loadConfig()?.embeddings?.dimensions || MODEL_DIMS;\n    embedding = hashEmbed(text, dims);\n  }\n\n  cacheSet(text, embedding, cacheTtlSeconds());\n  return embedding;\n}\n\n/**\n * Batch compute embeddings. Cache misses are embedded with one pipeline call\n * per chunk of texts rather than one call per text.\n */\nexport async function computeEmbeddingBatch(texts: string[]): Promise<Float32Array[]> {\n  if (embeddingKind !== 'hash') await initializeEmbeddings();\n  if (!embeddingPipeline) {\n    return Promise.all(texts.map(text => computeEmbedding(text)));\n  }\n  commitKind('local');\n\n  const results: Float32Array[] = new Array(texts.length);\n  const missing = new Map<string, number[]>(); // text -> result indices\n\n  texts.forEach((text, i) => {\n    const cached = cacheGet(text);\n    if (cached) {\n      results[i] = cached;\n      return;\n    }\n    const indices = missing.get(text);\n    if (indices) indices.push(i);\n    else missing.set(text, [i]);\n  });\n\n  const ttl = cacheTtlSeconds();\n  const uniqueTexts = Array.from(missing.keys());\n\n  for (let start = 0; start < uniqueTexts.length; start += BATCH_CHUNK_SIZE) {\n    const chunk = uniqueTexts.slice(start, start + BATCH_CHUNK_SIZE);\n    let vectors: Float32Array[];\n\n    try {\n      const output = await embeddingPipeline(chunk, { pooling: 'mean', normalize: true });\n      const dims = output.dims[output.dims.length - 1];\n      const data = output.data as Float32Array;\n      vectors = chunk.map((_, j) => new Float32Array(data.subarray(j * dims, (j + 1) * dims)));\n    } catch (error: any) {\n      console.error('[Embeddings] Batch generation failed:', error?.message || error);\n      throw modelFailure(error);\n    }\n\n    chunk.forEach((text, j) => {\n      cacheSet(text, vectors[j], ttl);\n      for (const i of missing.get(text)!) results[i] = vectors[j];\n    });\n  }\n\n  return results;\n}\n\n/**\n * Get embedding dimensions\n */\nexport function getEmbeddingDimensions(): number {\n  return MODEL_DIMS; // all-MiniLM-L6-v2 uses 384 dimensions\n}\n\n/**\n * Deterministic hash-based embedding (fallback)\n */\nfunction hashEmbed(text: string, dims: number): Float32Array {\n  const hash = simpleHash(text);\n  const vec = new Float32Array(dims);\n\n  // Generate deterministic pseudo-random vector from hash\n  for (let i = 0; i < dims; i++) {\n    vec[i] = Math.sin(hash * (i + 1) * 0.01) + Math.cos(hash * i * 0.02);\n  }\n\n  return normalize(vec);\n}\n\n/**\n * Simple string hash function\n */\nfunction simpleHash(str: string): number {\n  let hash = 0;\n  for (let i = 0; i < str.length; i++) {\n    hash = ((hash << 5) - hash) + str.charCodeAt(i);\n    hash |= 0;\n  }\n  return Math.abs(hash);\n}\n\n/**\n * Normalize vector to unit length\n */\nfunction normalize(vec: Float32Array): Float32Array {\n  let mag = 0;\n  for (let i = 0; i < vec.length; i++) {\n    mag += vec[i] * vec[i];\n  }\n  mag = Math.sqrt(mag);\n\n  if (mag === 0) return vec;\n\n  for (let i = 0; i < vec.length; i++) {\n    vec[i] /= mag;\n  }\n  return vec;\n}\n\n/**\n * Clear embedding cache\n */\nexport function clearEmbeddingCache(): void {\n  embeddingCache.clear();\n}\n"]}

package/dist/repair/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * `agentic-flow-repair` — thin CLI over {@link repair} (ADR-074).
+ *
+ * Usage:
+ *   node dist/repair/cli.js <repoRoot> [--generations N] [--children N]
+ *                           [--seed N] [--mock | --agent]
+ *
+ * Default substrate is 'real' (Test-Driven Repair): the repo's own test command
+ * gates every promotion. `--mock` is the deterministic, Docker-free smoke path.
+ * The full SWE-bench-Lite TDR product (issue checkout + Docker grading) is run
+ * via Darwin's own `metaharness-darwin` CLI — see ADR-074.
+ */
+import { type SandboxMode } from './darwin-repair.js';
+interface CliArgs {
+    repoRoot: string;
+    generations: number;
+    children: number;
+    seed: number;
+    sandboxMode: SandboxMode;
+}
+export declare function parseArgs(argv: string[]): CliArgs;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/repair/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/repair/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAU,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE9D,UAAU,OAAO;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAoBjD"}

package/dist/repair/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * `agentic-flow-repair` — thin CLI over {@link repair} (ADR-074).
+ *
+ * Usage:
+ *   node dist/repair/cli.js <repoRoot> [--generations N] [--children N]
+ *                           [--seed N] [--mock | --agent]
+ *
+ * Default substrate is 'real' (Test-Driven Repair): the repo's own test command
+ * gates every promotion. `--mock` is the deterministic, Docker-free smoke path.
+ * The full SWE-bench-Lite TDR product (issue checkout + Docker grading) is run
+ * via Darwin's own `metaharness-darwin` CLI — see ADR-074.
+ */
+import { repair } from './darwin-repair.js';
+export function parseArgs(argv) {
+    const args = {
+        repoRoot: '.',
+        generations: 3,
+        children: 4,
+        seed: 0,
+        sandboxMode: 'real',
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--generations')
+            args.generations = Number(argv[++i]);
+        else if (a === '--children')
+            args.children = Number(argv[++i]);
+        else if (a === '--seed')
+            args.seed = Number(argv[++i]);
+        else if (a === '--mock')
+            args.sandboxMode = 'mock';
+        else if (a === '--agent')
+            args.sandboxMode = 'agent';
+        else if (!a.startsWith('-'))
+            positional.push(a);
+    }
+    if (positional[0])
+        args.repoRoot = positional[0];
+    return args;
+}
+async function main() {
+    const a = parseArgs(process.argv.slice(2));
+    const res = await repair({
+        repoRoot: a.repoRoot,
+        generations: a.generations,
+        childrenPerGeneration: a.children,
+        seed: a.seed,
+        sandboxMode: a.sandboxMode,
+    });
+    console.log(`\nDarwin Repair — ${a.repoRoot} (${a.sandboxMode})`);
+    console.log(`  baseline finalScore : ${res.baselineScore.toFixed(3)}`);
+    if (res.winnerId) {
+        const sign = res.deltaOverBaseline >= 0 ? '+' : '';
+        console.log(`  winner              : ${res.winnerId}  (Δ ${sign}${res.deltaOverBaseline.toFixed(3)})`);
+    }
+    console.log(`  lineage             : ${res.winnerLineage.join(' → ') || '(baseline only)'}`);
+    console.log(`  variants evaluated  : ${res.variantsEvaluated} over ${res.generations} generation(s)`);
+    console.log(res.improved ? '  ✅ improved over baseline\n' : '  — no promoted improvement over baseline\n');
+}
+// Run only when invoked directly (ESM-safe; no CommonJS require.main).
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((err) => {
+        console.error('repair failed:', err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/repair/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/repair/cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n/**\n * `agentic-flow-repair` — thin CLI over {@link repair} (ADR-074).\n *\n * Usage:\n *   node dist/repair/cli.js <repoRoot> [--generations N] [--children N]\n *                           [--seed N] [--mock | --agent]\n *\n * Default substrate is 'real' (Test-Driven Repair): the repo's own test command\n * gates every promotion. `--mock` is the deterministic, Docker-free smoke path.\n * The full SWE-bench-Lite TDR product (issue checkout + Docker grading) is run\n * via Darwin's own `metaharness-darwin` CLI — see ADR-074.\n */\n\nimport { repair, type SandboxMode } from './darwin-repair.js';\n\ninterface CliArgs {\n  repoRoot: string;\n  generations: number;\n  children: number;\n  seed: number;\n  sandboxMode: SandboxMode;\n}\n\nexport function parseArgs(argv: string[]): CliArgs {\n  const args: CliArgs = {\n    repoRoot: '.',\n    generations: 3,\n    children: 4,\n    seed: 0,\n    sandboxMode: 'real',\n  };\n  const positional: string[] = [];\n  for (let i = 0; i < argv.length; i++) {\n    const a = argv[i];\n    if (a === '--generations') args.generations = Number(argv[++i]);\n    else if (a === '--children') args.children = Number(argv[++i]);\n    else if (a === '--seed') args.seed = Number(argv[++i]);\n    else if (a === '--mock') args.sandboxMode = 'mock';\n    else if (a === '--agent') args.sandboxMode = 'agent';\n    else if (!a.startsWith('-')) positional.push(a);\n  }\n  if (positional[0]) args.repoRoot = positional[0];\n  return args;\n}\n\nasync function main(): Promise<void> {\n  const a = parseArgs(process.argv.slice(2));\n  const res = await repair({\n    repoRoot: a.repoRoot,\n    generations: a.generations,\n    childrenPerGeneration: a.children,\n    seed: a.seed,\n    sandboxMode: a.sandboxMode,\n  });\n\n  console.log(`\\nDarwin Repair — ${a.repoRoot} (${a.sandboxMode})`);\n  console.log(`  baseline finalScore : ${res.baselineScore.toFixed(3)}`);\n  if (res.winnerId) {\n    const sign = res.deltaOverBaseline >= 0 ? '+' : '';\n    console.log(`  winner              : ${res.winnerId}  (Δ ${sign}${res.deltaOverBaseline.toFixed(3)})`);\n  }\n  console.log(`  lineage             : ${res.winnerLineage.join(' → ') || '(baseline only)'}`);\n  console.log(`  variants evaluated  : ${res.variantsEvaluated} over ${res.generations} generation(s)`);\n  console.log(res.improved ? '  ✅ improved over baseline\\n' : '  — no promoted improvement over baseline\\n');\n}\n\n// Run only when invoked directly (ESM-safe; no CommonJS require.main).\nif (import.meta.url === `file://${process.argv[1]}`) {\n  main().catch((err) => {\n    console.error('repair failed:', err);\n    process.exit(1);\n  });\n}\n"]}

package/dist/repair/darwin-repair.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Darwin Repair — autonomous harness evolution / Test-Driven Repair (ADR-074).
+ *
+ * A typed wrapper over `@metaharness/darwin`'s `evolve()`: freeze the model and
+ * evolve the harness around it (planner / context / reviewer / retry / tool /
+ * memory / score policy), keeping only variants that *measurably* improve under
+ * a frozen, reproducible scorer + safety gate.
+ *
+ * Modes (via `sandboxMode`):
+ *   - 'real'  (default) — Test-Driven Repair: the repo's own test command is the
+ *               oracle, run in Darwin's shell-free, env-scrubbed sandbox.
+ *   - 'mock'  — deterministic, surface-driven loop. No repo test, no Docker,
+ *               no network — used for hermetic smoke tests of the pipeline.
+ *   - 'agent' — runs the variant's real surface code (Node ≥ 22).
+ *
+ * NOTE: the headline SWE-bench-Lite TDR *product* (≈68.3% with-test) additionally
+ * needs the official `swebench` Docker harness for issue checkout + grading — see
+ * ADR-074 for that deployment path. This wrapper exposes the runnable `evolve()`
+ * core that does not require Docker.
+ *
+ * @see docs/adr/ADR-074-metaharness-darwin-test-driven-repair.md
+ */
+interface ArchiveRecord {
+    score?: {
+        finalScore?: number;
+    };
+}
+interface EvolutionResult {
+    baseline: ArchiveRecord | null;
+    winner: ArchiveRecord | null;
+    winnerLineage: string[];
+    generations: number;
+    records: ArchiveRecord[];
+}
+export type SandboxMode = 'real' | 'mock' | 'agent';
+export interface RepairOptions {
+    /** Path to the repo to repair/evolve. */
+    repoRoot: string;
+    /** Work tree for Darwin artifacts. Default `<repoRoot>/.metaharness`. */
+    workRoot?: string;
+    /** Generations to run. Default 3. */
+    generations?: number;
+    /** Children produced per parent per generation. Default 4. */
+    childrenPerGeneration?: number;
+    /** Max variants evaluated concurrently. Default 4. */
+    concurrency?: number;
+    /** Minimum finalScore margin a child must beat its parent by. Default 0.05. */
+    promotionDelta?: number;
+    /** Deterministic seed. Default 0. */
+    seed?: number;
+    /** Fixed scoring tasks (the variant cannot edit these). Defaults to REPAIR_TASKS. */
+    tasks?: string[];
+    /** Evaluation substrate. Default 'real' (Test-Driven Repair). */
+    sandboxMode?: SandboxMode;
+    /** Per-variant test-command wall-clock budget (ms). Default Darwin's 120000. */
+    taskTimeoutMs?: number;
+}
+export interface RepairResult {
+    /** True iff a child beat the baseline and was promoted. */
+    improved: boolean;
+    /** Winner variant id (lineage tail), or null when nothing beat the baseline. */
+    winnerId: string | null;
+    /** baseline → … → winner ids. */
+    winnerLineage: string[];
+    /** Baseline finalScore (0 if unevaluated). */
+    baselineScore: number;
+    /** Winner finalScore, or null. */
+    winnerScore: number | null;
+    /** winnerScore − baselineScore. */
+    deltaOverBaseline: number;
+    generations: number;
+    /** Total variants in the archive (baseline + descendants). */
+    variantsEvaluated: number;
+    /** Full Darwin result for callers that need the archive/traces. */
+    raw: EvolutionResult;
+}
+/** Default scoring tasks for a repair run. */
+export declare const REPAIR_TASKS: readonly string[];
+/**
+ * Run an autonomous repair/evolution pass over a repo and return a friendly
+ * summary. Defaults to Test-Driven Repair ('real' sandbox): the repo's own
+ * tests gate every promotion.
+ */
+export declare function repair(opts: RepairOptions): Promise<RepairResult>;
+/** Reusable repair runner with bound defaults (e.g. a fixed sandbox mode). */
+export declare class DarwinRepair {
+    private readonly defaults;
+    constructor(defaults?: Partial<RepairOptions>);
+    repair(opts: RepairOptions): Promise<RepairResult>;
+}
+export {};
+//# sourceMappingURL=darwin-repair.d.ts.map

package/dist/repair/darwin-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-repair.d.ts","sourceRoot":"","sources":["../../src/repair/darwin-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjC;AAED,UAAU,eAAe;IACvB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iEAAiE;IACjE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iCAAiC;IACjC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mCAAmC;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,8CAA8C;AAC9C,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAIzC,CAAC;AAMF;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAkCvE;AAED,8EAA8E;AAC9E,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,GAAE,OAAO,CAAC,aAAa,CAAM;IAElE,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;CAGnD"}