@claude-flow/cli 3.23.0 → 3.25.0

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

@@ -15,6 +15,55 @@ import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText } from './validate-input.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
+let _corpusStatsCache = null;
+// (query, store) → embedding + cosine cache. Small LRU (not size-1): the flywheel
+// scores many configs across several queries in interleaved order, so a size-1
+// cache would thrash. Cap keeps memory bounded; eviction is oldest-first.
+const _cosineCache = new Map();
+const _COSINE_CACHE_MAX = 128;
+function _cosineCacheGet(key) {
+    const v = _cosineCache.get(key);
+    if (v) {
+        _cosineCache.delete(key);
+        _cosineCache.set(key, v);
+    } // LRU touch
+    return v;
+}
+function _cosineCacheSet(key, v) {
+    _cosineCache.set(key, v);
+    if (_cosineCache.size > _COSINE_CACHE_MAX)
+        _cosineCache.delete(_cosineCache.keys().next().value);
+}
+function corpusFingerprint(patterns) {
+    let h = 2166136261 >>> 0;
+    for (const p of patterns) {
+        const s = `${p.id}|${p.name?.length ?? 0}|${p.content?.length ?? 0}`;
+        for (let i = 0; i < s.length; i++) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 16777619) >>> 0;
+        }
+    }
+    return `${patterns.length}:${h.toString(16)}`;
+}
+let _champCache = null;
+function activeChampionParams() {
+    try {
+        if (_champCache && Date.now() - _champCache.at < 30_000)
+            return _champCache.params;
+        const p = join(getProjectCwd(), '.claude-flow', 'harness-active-policy.json');
+        let params = {};
+        if (existsSync(p)) {
+            const active = JSON.parse(readFileSync(p, 'utf-8'));
+            if (active && !active.rolledBack && active.params && typeof active.params === 'object')
+                params = active.params;
+        }
+        _champCache = { at: Date.now(), params };
+        return params;
+    }
+    catch {
+        return {};
+    }
+}
 // Real embeddings — resolved LAZILY on first use.
 // Perf (measured 2026-07): the previous top-level-await version of this block
 // ran `await import('ruvector')` + `initOnnxEmbedder()` + a probe embed at
@@ -40,14 +89,34 @@ function ensureEmbeddings() {
         return embeddingsPromise;
     embeddingsPromise = (async () => {
         try {
+            // Tier -1 (PRIMARY): Lattice WASM — real multi-model semantic embeddings
+            // (miniLM / bge / paraphrase-miniLM / GPU qwen3-0.6b) ahead of everything.
+            // Optional + FAIL-CLOSED: absent/init-fail ⇒ fall straight through to the
+            // existing ruvector-ONNX → hash tiers with zero regression.
+            try {
+                const lat = await import('../ruvector/lattice-wasm.js').catch(() => null);
+                if (lat && await lat.latticeAvailable()) {
+                    const model = lat.DEFAULT_LATTICE_MODEL;
+                    realEmbeddings = {
+                        embed: async (text) => {
+                            const v = await lat.latticeEmbed(text, model);
+                            if (!v || !v.length)
+                                throw new Error('lattice embed failed'); // → generateEmbedding falls to next tier
+                            return v;
+                        },
+                    };
+                    embeddingServiceName = `lattice-wasm/${model} (${lat.latticeModels().length} model${lat.latticeModels().length === 1 ? '' : 's'})`;
+                }
+            }
+            catch { /* lattice absent — fall through */ }
             // Tier 0: ruvector@0.2.27 — bundled all-MiniLM-L6-v2 + parallel worker pool.
             // Probe with isOnnxAvailable() and verify an actual embed succeeds (avoids
             // the type-load-success-but-runtime-fails trap from ADR-086). The probe now
             // runs on first embed request instead of at import time.
             // NOTE: ruvector's embed() returns `{embedding, dimension, timeMs}` — we
             // unwrap to plain number[] for the shared interface.
-            const rv = await import('ruvector').catch(() => null);
-            if (rv?.embed && typeof rv.embed === 'function' && rv.isOnnxAvailable?.()) {
+            const rv = !realEmbeddings ? await import('ruvector').catch(() => null) : null;
+            if (!realEmbeddings && rv?.embed && typeof rv.embed === 'function' && rv.isOnnxAvailable?.()) {
                 try {
                     if (typeof rv.initOnnxEmbedder === 'function')
                         await rv.initOnnxEmbedder();
@@ -159,6 +228,19 @@ function loadNeuralStore() {
     }
     return { models: {}, patterns: {}, version: '3.0.0' };
 }
+/**
+ * ADR-176 flywheel: expose the stored patterns (id/name/content) so the
+ * self-optimizing loop can harvest a benchmark corpus from real usage. Additive,
+ * read-only, never throws.
+ */
+export function getStorePatterns() {
+    try {
+        return Object.values(loadNeuralStore().patterns ?? {}).map((p) => ({ id: p.id, name: p.name, content: p.content }));
+    }
+    catch {
+        return [];
+    }
+}
 function saveNeuralStore(store) {
     ensureNeuralDir();
     writeFileSync(getNeuralPath(), JSON.stringify(store, null, 2), 'utf-8');
@@ -604,13 +686,28 @@ export const neuralTools = [
                 // sub-params than non-rerank (the cross-encoder adds semantic depth,
                 // so the hybrid stage can be more keyword-focused). nDCG@3 0.900 →
                 // 0.963 on rerank just by switching sw 2.0 → 3.0 in the hybrid stage.
-                const alpha = Number(input.alpha ?? 0.5);
-                const mmrLambda = Number(input.mmrLambda ?? 0.7);
+                // Champion-provided defaults (ADR-176/177): explicit input wins, then the
+                // adopted proven-config champion, then the hardcoded ADR-082 defaults.
+                const champ = activeChampionParams();
+                const alpha = Number(input.alpha ?? champ.alpha ?? 0.5);
+                const mmrLambda = Number(input.mmrLambda ?? champ.mmrLambda ?? 0.7);
                 const { tokenize, buildCorpusStats, hybridScores, mmrRerank, multiFieldBM25, typePenalty } = await import('../memory/hybrid-retrieval.js');
-                const queryEmbedding = await generateEmbedding(query, 384);
                 const patterns = Object.values(store.patterns);
-                // Compute cosine for every pattern (this is what the old path did).
-                const cosineArr = patterns.map((p) => cosineSimilarity(queryEmbedding, p.embedding));
+                // Query embedding + cosine array depend only on (query, store) — NOT the
+                // retrieval config. Cache them so scoring many configs for one query
+                // (the flywheel's access pattern) embeds + cosines once, not per config.
+                const _cosKey = `${corpusFingerprint(patterns)}::${query}`;
+                let queryEmbedding, cosineArr;
+                const _hit = _cosineCacheGet(_cosKey);
+                if (_hit) {
+                    queryEmbedding = _hit.queryEmbedding;
+                    cosineArr = _hit.cosineArr;
+                }
+                else {
+                    queryEmbedding = await generateEmbedding(query, 384);
+                    cosineArr = patterns.map((p) => cosineSimilarity(queryEmbedding, p.embedding));
+                    _cosineCacheSet(_cosKey, { queryEmbedding, cosineArr });
+                }
                 if (mode === 'cosine') {
                     const ranked = patterns
                         .map((p, i) => ({ ...p, similarity: cosineArr[i] }))
@@ -630,23 +727,35 @@ export const neuralTools = [
                 // Hybrid path — multi-field BM25 (subject 3×, body 1×) + type penalty
                 // for meta-commits (release bumps / merges) per ADR-079. Falls back
                 // to single-field BM25 when no content is stored.
-                const subjectDocs = patterns.map((p) => tokenize(p.name ?? ''));
-                const bodyDocs = patterns.map((p) => {
-                    // Body is content minus the subject — if content starts with name,
-                    // strip it; otherwise use full content (with name removed if duplicated).
-                    const c = p.content ?? '';
-                    const n = p.name ?? '';
-                    return tokenize(c.startsWith(n) ? c.slice(n.length) : c);
-                });
-                const subjectStats = buildCorpusStats(subjectDocs);
-                const bodyStats = buildCorpusStats(bodyDocs);
+                // Cache the (config-independent) tokenized docs + BM25 stats by store fingerprint.
+                const _fp = corpusFingerprint(patterns);
+                let subjectDocs, bodyDocs, subjectStats, bodyStats;
+                if (_corpusStatsCache && _corpusStatsCache.fp === _fp) {
+                    subjectDocs = _corpusStatsCache.subjectDocs;
+                    bodyDocs = _corpusStatsCache.bodyDocs;
+                    subjectStats = _corpusStatsCache.subjectStats;
+                    bodyStats = _corpusStatsCache.bodyStats;
+                }
+                else {
+                    subjectDocs = patterns.map((p) => tokenize(p.name ?? ''));
+                    bodyDocs = patterns.map((p) => {
+                        // Body is content minus the subject — if content starts with name,
+                        // strip it; otherwise use full content (with name removed if duplicated).
+                        const c = p.content ?? '';
+                        const n = p.name ?? '';
+                        return tokenize(c.startsWith(n) ? c.slice(n.length) : c);
+                    });
+                    subjectStats = buildCorpusStats(subjectDocs);
+                    bodyStats = buildCorpusStats(bodyDocs);
+                    _corpusStatsCache = { fp: _fp, subjectDocs, bodyDocs, subjectStats, bodyStats };
+                }
                 const queryTokens = tokenize(query);
                 // ADR-082: subjectWeight 3.0 → 2.0 from grid (sw=2 dominates at hybrid-only).
                 // ADR-083 joint grid: when rerank is on, the cross-encoder handles
                 // semantic understanding, so the hybrid stage can be MORE
                 // subject-focused (sw=3) — recovers nDCG@3 0.963.
-                const subjectWeight = Number(input.subjectWeight ?? (useRerank ? 3.0 : 2.0));
-                const bodyWeight = Number(input.bodyWeight ?? 1.0);
+                const subjectWeight = Number(input.subjectWeight ?? champ.subjectWeight ?? (useRerank ? 3.0 : 2.0));
+                const bodyWeight = Number(input.bodyWeight ?? champ.bodyWeight ?? 1.0);
                 const bm25Arr = patterns.map((_, i) => multiFieldBM25(queryTokens, subjectDocs[i], bodyDocs[i], subjectStats, bodyStats, subjectWeight, bodyWeight));
                 const baseHybrid = hybridScores(cosineArr, bm25Arr, alpha);
                 // Type penalty — opt-in (default 1.0 = disabled). Ablation in ADR-079
@@ -654,7 +763,7 @@ export const neuralTools = [
                 // penalty enabled) because some relevant work commits also match the
                 // Merge/release regex. Callers wanting aggressive meta-commit
                 // suppression can set {typePenaltyFactor: 0.5}.
-                const typeFactor = Number(input.typePenaltyFactor ?? 1.0);
+                const typeFactor = Number(input.typePenaltyFactor ?? champ.typePenaltyFactor ?? 1.0);
                 const hybridArr = typeFactor === 1.0
                     ? baseHybrid
                     : baseHybrid.map((s, i) => s * typePenalty(patterns[i].name, typeFactor));

package/dist/src/ruvector/lattice-wasm.d.ts

@@ -0,0 +1,14 @@
+/** Default package name (ruvnet WASM convention); override with RUFLO_LATTICE_WASM_PKG. */
+export declare const LATTICE_WASM_PKG: string;
+export type LatticeModel = 'minilm' | 'bge' | 'paraphrase-minilm' | 'qwen3-0.6b' | string;
+export declare const DEFAULT_LATTICE_MODEL: LatticeModel;
+/** Is the Lattice WASM embedder installed + initializable? Cached; never throws. */
+export declare function latticeAvailable(): Promise<boolean>;
+/** The models Lattice reports (empty until availability is probed). */
+export declare function latticeModels(): LatticeModel[];
+/**
+ * Embed `text` with `model` via Lattice WASM. Returns null on any failure so the
+ * caller can fall through to the next tier. Never throws.
+ */
+export declare function latticeEmbed(text: string, model?: LatticeModel): Promise<number[] | null>;
+//# sourceMappingURL=lattice-wasm.d.ts.map

package/dist/src/ruvector/lattice-wasm.js

@@ -0,0 +1,144 @@
+/**
+ * Lattice WASM embedder adapter — the primary embedding tier (ADR: embedding
+ * substrate upgrade). Replaces hash placeholders with real semantic embeddings
+ * and adds multiple models (miniLM, bge, multi-paraphrase-miniLM, GPU qwen3-0.6B).
+ *
+ * Built on the proven `@ruvector/ruvllm-wasm` optional-dependency convention:
+ *   - dynamically imported (never a hard dependency),
+ *   - WASM initialized from bundled bytes,
+ *   - fully FAIL-CLOSED: if the package is absent, the WASM fails to init, or the
+ *     embed API differs, `latticeAvailable()` returns false and callers fall
+ *     through to the existing ruvector-ONNX → hash tiers with ZERO regression.
+ *
+ * The package specifier is configurable (`RUFLO_LATTICE_WASM_PKG`) so the exact
+ * published name can be set without a code change; the API is probed tolerantly.
+ * Opt-in for the GPU model: qwen3 is only selected when explicitly requested.
+ */
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+const require_ = createRequire(import.meta.url);
+/** Default package name (ruvnet WASM convention); override with RUFLO_LATTICE_WASM_PKG. */
+export const LATTICE_WASM_PKG = process.env.RUFLO_LATTICE_WASM_PKG || '@ruvector/lattice-wasm';
+export const DEFAULT_LATTICE_MODEL = process.env.RUFLO_EMBED_MODEL || 'minilm';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let _mod = null;
+let _ready = false;
+let _probed = false;
+let _available = false;
+let _models = [];
+async function loadModule() {
+    if (_mod)
+        return _mod;
+    const spec = LATTICE_WASM_PKG;
+    _mod = await import(spec).catch(() => null); // optional — absent ⇒ null ⇒ unavailable
+    return _mod;
+}
+async function ensureInit() {
+    if (_ready)
+        return true;
+    const mod = await loadModule();
+    if (!mod)
+        return false;
+    try {
+        // ruvnet WASM convention: initSync({ module: <wasm bytes> }); tolerate variants.
+        if (!_ready && typeof mod.initSync === 'function') {
+            let wasmBytes;
+            for (const cand of ['lattice_wasm_bg.wasm', 'lattice_bg.wasm', 'index_bg.wasm']) {
+                try {
+                    wasmBytes = readFileSync(require_.resolve(`${LATTICE_WASM_PKG}/${cand}`));
+                    break;
+                }
+                catch { /* try next */ }
+            }
+            mod.initSync(wasmBytes ? { module: wasmBytes } : undefined);
+        }
+        else if (typeof mod.default === 'function') {
+            await mod.default(); // some wasm-bindgen builds export an async default init
+        }
+        _ready = true;
+        return true;
+    }
+    catch {
+        return false; // init failed ⇒ fail closed
+    }
+}
+/** Extract a plain number[] from whatever shape the module's embed returns. */
+function toVec(r) {
+    const v = (r && typeof r === 'object' && 'embedding' in r) ? r.embedding : r;
+    if (!v)
+        return null;
+    if (Array.isArray(v))
+        return v;
+    if (v.length !== undefined)
+        return Array.from(v);
+    return null;
+}
+/** Is the Lattice WASM embedder installed + initializable? Cached; never throws. */
+export async function latticeAvailable() {
+    if (_probed)
+        return _available;
+    _probed = true;
+    try {
+        if (!(await ensureInit())) {
+            _available = false;
+            return false;
+        }
+        const mod = _mod;
+        // discover models (tolerant): listModels() / models / MODELS
+        try {
+            const list = typeof mod.listModels === 'function' ? mod.listModels() : (mod.models ?? mod.MODELS);
+            if (Array.isArray(list) && list.length)
+                _models = list;
+        }
+        catch { /* leave default */ }
+        if (!_models.length)
+            _models = [DEFAULT_LATTICE_MODEL];
+        // verify an actual embed succeeds (the ADR-086 "loads but runtime-fails" trap).
+        const probe = await latticeEmbedRaw('probe', DEFAULT_LATTICE_MODEL);
+        _available = !!probe && probe.length > 0;
+        return _available;
+    }
+    catch {
+        _available = false;
+        return false;
+    }
+}
+/** The models Lattice reports (empty until availability is probed). */
+export function latticeModels() { return [..._models]; }
+async function latticeEmbedRaw(text, model) {
+    const mod = _mod;
+    if (!mod)
+        return null;
+    // tolerant API probing across plausible wasm-bindgen surfaces.
+    const attempts = [
+        () => typeof mod.embed === 'function' ? mod.embed(text, model) : undefined,
+        () => typeof mod.embed === 'function' ? mod.embed(text) : undefined,
+        () => typeof mod.embedText === 'function' ? mod.embedText(text, model) : undefined,
+        () => typeof mod.Embedder === 'function' ? new mod.Embedder(model).embed(text) : undefined,
+    ];
+    for (const a of attempts) {
+        try {
+            const r = await a();
+            const v = toVec(r);
+            if (v)
+                return v;
+        }
+        catch { /* try next surface */ }
+    }
+    return null;
+}
+/**
+ * Embed `text` with `model` via Lattice WASM. Returns null on any failure so the
+ * caller can fall through to the next tier. Never throws.
+ */
+export async function latticeEmbed(text, model = DEFAULT_LATTICE_MODEL) {
+    try {
+        if (!(await latticeAvailable()))
+            return null;
+        return await latticeEmbedRaw(text, model);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=lattice-wasm.js.map

package/dist/src/services/daemon-autostart.d.ts

@@ -0,0 +1,17 @@
+/** True if a live daemon already holds the project's pidfile. */
+export declare function isDaemonAlive(projectRoot: string): boolean;
+export interface EnsureResult {
+    started: boolean;
+    reason?: string;
+}
+/** Spawn `daemon start` detached, reusing all its lock/TTL machinery. Injectable for tests. */
+export type SpawnDaemonFn = (projectRoot: string) => void;
+/**
+ * Ensure a daemon is running for `projectRoot`. No-op when disabled or when one
+ * is already alive. Best-effort; never throws.
+ */
+export declare function ensureDaemonRunning(projectRoot: string, opts?: {
+    spawnFn?: SpawnDaemonFn;
+    isAlive?: (root: string) => boolean;
+}): EnsureResult;
+//# sourceMappingURL=daemon-autostart.d.ts.map

package/dist/src/services/daemon-autostart.js

@@ -0,0 +1,79 @@
+/**
+ * Self-running daemon (auto-start).
+ *
+ * The self-optimizing loop's workers (distillation, backup, and the future
+ * evolve worker) are inert unless the daemon runs — but it required a manual
+ * `ruflo daemon start`. This ensures a daemon is running on CLI use, SAFELY:
+ *
+ *   - single-instance: only starts when no live daemon holds the pidfile, and
+ *     the spawned `daemon start` independently enforces single-instance via its
+ *     own lock + checkExistingDaemon() — so a race spawns at most one survivor,
+ *   - bounded lifetime: the daemon self-terminates on TTL/idle (12h default,
+ *     RUFLO_DAEMON_TTL_SECS) — auto-start never means "runs forever",
+ *   - opt-out: RUFLO_DAEMON_AUTOSTART=0|false|no disables it entirely,
+ *   - cheap: a pidfile read + a signal-0 liveness check on the fast path,
+ *   - best-effort + silent: never blocks or fails a command.
+ *
+ * Reuses `daemon start` verbatim (all its lock/TTL/worker machinery) — this
+ * module only decides WHETHER to spawn, never reimplements the daemon.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+/** True if a live daemon already holds the project's pidfile. */
+export function isDaemonAlive(projectRoot) {
+    const pidFile = path.join(projectRoot, '.claude-flow', 'daemon.pid');
+    try {
+        if (!fs.existsSync(pidFile))
+            return false;
+        const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+        if (Number.isNaN(pid) || pid === process.pid)
+            return false;
+        process.kill(pid, 0); // signal 0 = existence check
+        return true;
+    }
+    catch {
+        // Dead process → stale pidfile. Clean it so `daemon start` proceeds cleanly.
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { /* ignore */ }
+        return false;
+    }
+}
+function autostartDisabled() {
+    return /^(0|false|no|off)$/i.test(process.env.RUFLO_DAEMON_AUTOSTART ?? '');
+}
+const defaultSpawn = (projectRoot) => {
+    const cliBin = process.argv[1]; // the running bin/cli.js
+    const child = spawn(process.execPath, [cliBin, 'daemon', 'start', '--quiet'], {
+        cwd: projectRoot,
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env },
+    });
+    child.unref();
+};
+/**
+ * Ensure a daemon is running for `projectRoot`. No-op when disabled or when one
+ * is already alive. Best-effort; never throws.
+ */
+export function ensureDaemonRunning(projectRoot, opts = {}) {
+    try {
+        if (autostartDisabled())
+            return { started: false, reason: 'disabled (RUFLO_DAEMON_AUTOSTART=0)' };
+        // Only in an initialized project (avoid scaffolding a daemon in a random dir).
+        if (!fs.existsSync(path.join(projectRoot, '.claude-flow')) && !fs.existsSync(path.join(projectRoot, '.claude'))) {
+            return { started: false, reason: 'not a ruflo project' };
+        }
+        const alive = (opts.isAlive ?? isDaemonAlive)(projectRoot);
+        if (alive)
+            return { started: false, reason: 'already running' };
+        (opts.spawnFn ?? defaultSpawn)(projectRoot);
+        return { started: true };
+    }
+    catch (e) {
+        return { started: false, reason: `error: ${e?.message ?? e}` };
+    }
+}
+//# sourceMappingURL=daemon-autostart.js.map