claude-flow 3.18.1 → 3.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.18.1",
+  "version": "3.19.0",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",
@@ -116,7 +116,8 @@
     "ws": ">=8.21.0",
     "@grpc/grpc-js": ">=1.14.4",
     "form-data": ">=4.0.6",
-    "http-proxy-middleware": ">=3.0.7"
+    "http-proxy-middleware": ">=3.0.7",
+    "@ruvector/ruvllm": ">=2.5.7"
   },
   "devDependencies": {
     "@openai/codex": "^0.98.0",

package/v3/@claude-flow/cli/dist/src/commands/neural.js

@@ -23,6 +23,7 @@ const trainCommand = {
         { name: 'hyperbolic', type: 'boolean', description: 'Enable hyperbolic attention for hierarchical patterns', default: 'false' },
         { name: 'contrastive', type: 'boolean', description: 'Use contrastive learning (InfoNCE)', default: 'true' },
         { name: 'curriculum', type: 'boolean', description: 'Enable curriculum learning', default: 'false' },
+        { name: 'backend', type: 'string', description: 'Training backend: auto (native when available), native (@ruvector/ruvllm TrainingPipeline, disk checkpoints), wasm (RuVector MicroLoRA/InfoNCE)', default: 'auto' },
     ],
     examples: [
         { command: 'claude-flow neural train -p coordination -e 100', description: 'Train coordination patterns' },
@@ -35,6 +36,11 @@ const trainCommand = {
         const learningRate = parseFloat(ctx.flags['learning-rate'] || '0.01');
         const batchSize = parseInt(ctx.flags['batch-size'] || '32', 10);
         const dim = Math.min(parseInt(ctx.flags.dim || '256', 10), 256);
+        // #2549 follow-up — backend routing: 'native' = @ruvector/ruvllm
+        // TrainingPipeline (real epochs/early-stopping/disk checkpoints),
+        // 'wasm' = RuVector MicroLoRA/InfoNCE (pre-3.19 behavior),
+        // 'auto' = native when the module resolves, else wasm.
+        const backendFlag = String(ctx.flags.backend || 'auto');
         const useWasm = ctx.flags.wasm !== false;
         const useFlash = ctx.flags.flash !== false;
         const useMoE = ctx.flags.moe === true;
@@ -181,6 +187,34 @@ const trainCommand = {
                 }
             }
             spinner.setText(`Training with ${embeddings.length} embeddings...`);
+            // #2549 — native TrainingPipeline leg. In 'auto'/'native' mode the
+            // LoRA training runs through @ruvector/ruvllm with the checkpoint
+            // taken from the TRAINED pipeline (the old best-effort block saved
+            // a fresh adapter's untrained weights). SONA/ReasoningBank
+            // persistence in the loop below runs regardless of backend.
+            const nativeTraining = await import('../services/native-training.js');
+            const useNative = backendFlag === 'native'
+                || (backendFlag === 'auto' && nativeTraining.nativeTrainingAvailable());
+            let nativeResult = null;
+            if (useNative) {
+                spinner.setText(`Training ${patternType} on native @ruvector/ruvllm pipeline...`);
+                const path = await import('path');
+                nativeResult = await nativeTraining.runNativeTraining({
+                    embeddings,
+                    epochs,
+                    batchSize,
+                    learningRate,
+                    dim,
+                    checkpointPath: path.join(process.cwd(), '.claude-flow', 'neural', `lora-checkpoint-${Date.now()}.json`),
+                });
+                if (!nativeResult && backendFlag === 'native') {
+                    spinner.fail('Native backend requested (--backend native) but @ruvector/ruvllm training failed');
+                    return { success: false, exitCode: 1 };
+                }
+            }
+            // Native handles the LoRA leg; WASM contrastive runs when native
+            // didn't (absent module, or explicit --backend wasm).
+            const runWasmLeg = !nativeResult;
             // Main training loop with WASM acceleration
             for (let epoch = 0; epoch < epochs; epoch++) {
                 const epochStart = performance.now();
@@ -192,7 +226,7 @@ const trainCommand = {
                 if (batch.length === 0)
                     continue;
                 // Training step with contrastive learning
-                if (useContrastive && batch.length >= 3 && useWasm && wasmFeatures.length > 0) {
+                if (runWasmLeg && useContrastive && batch.length >= 3 && useWasm && wasmFeatures.length > 0) {
                     const anchor = batch[0];
                     const positives = [batch[1]];
                     const negatives = batch.slice(2);
@@ -260,17 +294,22 @@ const trainCommand = {
             // Flush patterns to disk
             flushPatterns();
             const persistence = getPersistenceStatus();
-            // Save LoRA checkpoint via ruvllm TrainingPipeline if available
-            try {
-                const { LoRAAdapter } = await import('../ruvector/lora-adapter.js');
-                const path = await import('path');
-                const cpDir = path.join(process.cwd(), '.claude-flow', 'neural');
-                const cpPath = path.join(cpDir, `lora-checkpoint-${Date.now()}.json`);
-                const adapter = new LoRAAdapter({ inputDim: dim, outputDim: dim, rank: 4 });
-                await adapter.initBackend();
-                await adapter.saveCheckpoint(cpPath);
+            // Checkpoint: when the native pipeline trained, its checkpoint (the
+            // TRAINED weights) was already written by runNativeTraining. The
+            // pre-3.19 fallback below saved a FRESH adapter's weights — only
+            // meaningful as a fallback when the native leg didn't run.
+            if (!nativeResult?.checkpointPath) {
+                try {
+                    const { LoRAAdapter } = await import('../ruvector/lora-adapter.js');
+                    const path = await import('path');
+                    const cpDir = path.join(process.cwd(), '.claude-flow', 'neural');
+                    const cpPath = path.join(cpDir, `lora-checkpoint-${Date.now()}.json`);
+                    const adapter = new LoRAAdapter({ inputDim: dim, outputDim: dim, rank: 4 });
+                    await adapter.initBackend();
+                    await adapter.saveCheckpoint(cpPath);
+                }
+                catch { /* checkpoint save is best-effort */ }
             }
-            catch { /* checkpoint save is best-effort */ }
             output.writeln();
             // Display results
             const tableData = [
@@ -284,8 +323,18 @@ const trainCommand = {
                 { metric: 'Total Time', value: `${(totalTime / 1000).toFixed(1)}s` },
                 { metric: 'Avg Epoch Time', value: `${(epochTimes.reduce((a, b) => a + b, 0) / epochTimes.length).toFixed(2)}ms` },
             ];
+            // Native pipeline metrics (#2549 — the LoRA leg trained on ruvllm)
+            if (nativeResult) {
+                tableData.push({ metric: 'Backend', value: 'native (@ruvector/ruvllm TrainingPipeline)' }, { metric: 'Native Steps', value: String(nativeResult.steps) }, { metric: 'Final Loss', value: nativeResult.finalLoss.toExponential(3) }, { metric: 'Early Stopped', value: nativeResult.earlyStopped ? 'yes' : 'no' });
+                if (nativeResult.checkpointPath) {
+                    tableData.push({
+                        metric: 'Checkpoint',
+                        value: `${nativeResult.checkpointPath}${nativeResult.checkpointBytes ? ` (${(nativeResult.checkpointBytes / 1024).toFixed(1)} KB)` : ''}`,
+                    });
+                }
+            }
             // Add WASM-specific metrics
-            if (useWasm && wasmFeatures.length > 0) {
+            if (runWasmLeg && useWasm && wasmFeatures.length > 0) {
                 const backendUsed = ruvectorStats?.backend || 'unknown';
                 tableData.push({ metric: 'Backend', value: backendUsed === 'wasm' ? 'WASM (native)' : 'JS (fallback)' }, { metric: 'WASM Features', value: wasmFeatures.slice(0, 3).join(', ') }, { metric: 'LoRA Adaptations', value: String(adaptations) }, { metric: 'Avg Loss', value: (totalLoss / Math.max(1, epochs)).toFixed(4) });
                 if (ruvectorStats?.microLoraStats) {
@@ -469,8 +518,20 @@ const statusCommand = {
                     {
                         component: 'Training Pipeline',
                         status: stats._trainingBackend === 'ruvllm' ? output.success('Available') : output.dim(stats._trainingBackend || 'Unavailable'),
+                        // Checkpoint capability is version-gated: saveCheckpoint(path)
+                        // was a silent no-op before @ruvector/ruvllm 2.5.7 (#2549).
                         details: stats._trainingBackend === 'ruvllm'
-                            ? 'native @ruvector/ruvllm pipeline'
+                            ? await (async () => {
+                                try {
+                                    const { nativeCheckpointsSupported } = await import('../ruvector/lora-adapter.js');
+                                    return nativeCheckpointsSupported()
+                                        ? 'native @ruvector/ruvllm pipeline + disk checkpoints'
+                                        : 'native @ruvector/ruvllm pipeline (checkpoints need >=2.5.7)';
+                                }
+                                catch {
+                                    return 'native @ruvector/ruvllm pipeline';
+                                }
+                            })()
                             : 'JS fallback',
                     },
                     await (async () => {

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.d.ts

@@ -106,6 +106,14 @@ export interface LoRAStats {
  * module resolution.
  */
 export declare function resolveTrainingBackend(): 'ruvllm' | 'js-fallback';
+/**
+ * Whether the resolved @ruvector/ruvllm persists checkpoints to disk.
+ * saveCheckpoint(path) was a silent no-op (private, void, wrote 0 bytes)
+ * before 2.5.7 — status surfaces must not advertise checkpoints against
+ * older versions. Reads the resolved package's version; the package does
+ * not export ./package.json, so walk up from the resolved entry instead.
+ */
+export declare function nativeCheckpointsSupported(): boolean;
 /**
  * Low-Rank Adaptation module for efficient embedding fine-tuning
  */

package/v3/@claude-flow/cli/dist/src/ruvector/lora-adapter.js

@@ -77,6 +77,34 @@ export function resolveTrainingBackend() {
         return 'js-fallback';
     }
 }
+/**
+ * Whether the resolved @ruvector/ruvllm persists checkpoints to disk.
+ * saveCheckpoint(path) was a silent no-op (private, void, wrote 0 bytes)
+ * before 2.5.7 — status surfaces must not advertise checkpoints against
+ * older versions. Reads the resolved package's version; the package does
+ * not export ./package.json, so walk up from the resolved entry instead.
+ */
+export function nativeCheckpointsSupported() {
+    try {
+        const req = createRequire(import.meta.url);
+        let dir = dirname(req.resolve('@ruvector/ruvllm'));
+        for (let i = 0; i < 5; i++) {
+            const pkgPath = join(dir, 'package.json');
+            if (existsSync(pkgPath)) {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name !== '@ruvector/ruvllm') {
+                    dir = dirname(dir);
+                    continue;
+                }
+                const [maj, min, pat] = String(pkg.version).split('.').map(Number);
+                return maj > 2 || (maj === 2 && (min > 5 || (min === 5 && pat >= 7)));
+            }
+            dir = dirname(dir);
+        }
+    }
+    catch { /* unresolved — no native checkpoints */ }
+    return false;
+}
 async function loadTrainingPipeline(adapter) {
     if (pipelineLoaded)
         return ruvllmPipeline;
@@ -408,11 +436,18 @@ export class LoRAAdapter {
      * Falls back to writing our own weight JSON if ruvllm is unavailable.
      */
     async saveCheckpoint(path) {
+        // Parent dir must exist for BOTH paths: ruvllm <2.5.7 never wrote a
+        // file at all, and the JS fallback's writeFileSync throws ENOENT on a
+        // missing dir — which the catch silently converted to `false` (#2549).
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch { /* fs errors surface on write below */ }
         const pipeline = await loadTrainingPipeline(this);
         if (pipeline) {
             try {
                 pipeline.saveCheckpoint(path);
-                // Verify ruvllm actually wrote the file (some versions are no-op)
+                // Verify ruvllm actually wrote the file (<2.5.7 is a silent no-op)
                 const fs = await import('fs');
                 if (fs.existsSync(path))
                     return true;

package/v3/@claude-flow/cli/dist/src/services/native-training.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Native training via @ruvector/ruvllm's TrainingPipeline (#2549 follow-up).
+ *
+ * `neural train` historically trained only on the RuVector WASM path
+ * (MicroLoRA + InfoNCE) and its "checkpoint" was a freshly-constructed
+ * adapter's weights — the native TrainingPipeline (real epochs, loss
+ * history, early stopping, EWC registration, disk checkpoints since
+ * ruvllm 2.5.7) was never exercised. This service routes the LoRA
+ * training leg through it.
+ *
+ * Batch formulation: pattern-alignment pairs — input = embedding[i],
+ * target = embedding[i+1 mod n], quality 1.0 — the MSE analogue of the
+ * WASM path's anchor→positive contrastive objective (adjacent training
+ * items belong to the same pattern family by construction).
+ *
+ * Graceful: returns null when @ruvector/ruvllm is absent or anything
+ * throws — callers fall back to the WASM path.
+ */
+export interface NativeTrainingResult {
+    epochs: number;
+    steps: number;
+    finalLoss: number;
+    bestValLoss: number | null;
+    durationMs: number;
+    earlyStopped: boolean;
+    checkpointPath?: string;
+    checkpointBytes?: number;
+}
+export interface NativeTrainingOptions {
+    embeddings: Float32Array[];
+    epochs: number;
+    batchSize: number;
+    learningRate: number;
+    dim: number;
+    /** When set, the TRAINED pipeline checkpoints here (ruvllm >=2.5.7). */
+    checkpointPath?: string;
+}
+export declare function nativeTrainingAvailable(): boolean;
+export declare function runNativeTraining(opts: NativeTrainingOptions): Promise<NativeTrainingResult | null>;
+//# sourceMappingURL=native-training.d.ts.map

package/v3/@claude-flow/cli/dist/src/services/native-training.js

@@ -0,0 +1,84 @@
+/**
+ * Native training via @ruvector/ruvllm's TrainingPipeline (#2549 follow-up).
+ *
+ * `neural train` historically trained only on the RuVector WASM path
+ * (MicroLoRA + InfoNCE) and its "checkpoint" was a freshly-constructed
+ * adapter's weights — the native TrainingPipeline (real epochs, loss
+ * history, early stopping, EWC registration, disk checkpoints since
+ * ruvllm 2.5.7) was never exercised. This service routes the LoRA
+ * training leg through it.
+ *
+ * Batch formulation: pattern-alignment pairs — input = embedding[i],
+ * target = embedding[i+1 mod n], quality 1.0 — the MSE analogue of the
+ * WASM path's anchor→positive contrastive objective (adjacent training
+ * items belong to the same pattern family by construction).
+ *
+ * Graceful: returns null when @ruvector/ruvllm is absent or anything
+ * throws — callers fall back to the WASM path.
+ */
+import { createRequire } from 'module';
+import { mkdirSync, existsSync } from 'fs';
+import { dirname } from 'path';
+export function nativeTrainingAvailable() {
+    try {
+        createRequire(import.meta.url).resolve('@ruvector/ruvllm');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runNativeTraining(opts) {
+    const { embeddings, epochs, batchSize, learningRate, dim, checkpointPath } = opts;
+    if (embeddings.length < 2)
+        return null;
+    try {
+        const req = createRequire(import.meta.url);
+        const ruvllm = req('@ruvector/ruvllm');
+        const pipeline = new ruvllm.TrainingPipeline({
+            learningRate,
+            batchSize,
+            epochs,
+            inputDim: dim,
+            outputDim: dim,
+        });
+        // Pattern-alignment pairs, chunked into pipeline batches.
+        const inputs = [];
+        const targets = [];
+        const qualities = [];
+        for (let i = 0; i < embeddings.length; i++) {
+            inputs.push(Array.from(embeddings[i]));
+            targets.push(Array.from(embeddings[(i + 1) % embeddings.length]));
+            qualities.push(1.0);
+        }
+        for (let i = 0; i < inputs.length; i += batchSize) {
+            pipeline.addBatch(inputs.slice(i, i + batchSize), targets.slice(i, i + batchSize), qualities.slice(i, i + batchSize));
+        }
+        const r = pipeline.train();
+        const result = {
+            epochs: r.epochs,
+            steps: r.steps,
+            finalLoss: r.finalLoss,
+            bestValLoss: r.bestValLoss ?? null,
+            durationMs: r.durationMs,
+            earlyStopped: !!r.earlyStopped,
+        };
+        if (checkpointPath) {
+            try {
+                mkdirSync(dirname(checkpointPath), { recursive: true });
+                const saved = pipeline.saveCheckpoint(checkpointPath);
+                // <2.5.7 returns undefined and writes nothing — verify on disk.
+                if (existsSync(checkpointPath)) {
+                    result.checkpointPath = checkpointPath;
+                    result.checkpointBytes = saved?.bytes;
+                }
+            }
+            catch { /* checkpoint is best-effort; training result stands */ }
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=native-training.js.map

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.18.1",
+  "version": "3.19.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",