claude-flow 3.7.0-alpha.45 → 3.7.0-alpha.47

package/README.md

@@ -395,6 +395,15 @@ User Guide section index:
 
 ---
 
+## Contributing
+
+Humans and AI agents are both welcome. The one rule that matters: **file an issue before opening a PR** — even a 3-line one — so we can collaborate on the shape of the change before you sink time into it.
+
+| Read | Where |
+|------|-------|
+| **Contributor guide** — full conventions, testing, publishing, contrastive eval, AI-agent specifics | [`docs/AGENT_CONTRIBUTOR.md`](docs/AGENT_CONTRIBUTOR.md) |
+| **Pinned issue — read this first** | [How to contribute (#2035)](https://github.com/ruvnet/ruflo/issues/2035) |
+
 ## Support
 
 | Resource | Link |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.45",
+  "version": "3.7.0-alpha.47",
   "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",

package/v3/@claude-flow/cli/README.md

@@ -395,6 +395,15 @@ User Guide section index:
 
 ---
 
+## Contributing
+
+Humans and AI agents are both welcome. The one rule that matters: **file an issue before opening a PR** — even a 3-line one — so we can collaborate on the shape of the change before you sink time into it.
+
+| Read | Where |
+|------|-------|
+| **Contributor guide** — full conventions, testing, publishing, contrastive eval, AI-agent specifics | [`docs/AGENT_CONTRIBUTOR.md`](docs/AGENT_CONTRIBUTOR.md) |
+| **Pinned issue — read this first** | [How to contribute (#2035)](https://github.com/ruvnet/ruflo/issues/2035) |
+
 ## Support
 
 | Resource | Link |

package/v3/@claude-flow/cli/dist/src/mcp-tools/embeddings-tools.js

@@ -900,5 +900,134 @@ export const embeddingsTools = [
             return { success: true, ...getRabitqStatus() };
         },
     },
+    {
+        // ADR-121 Phase 5 (full) — sidecar MCP tool. Proxies through
+        // @claude-flow/embeddings's probeRuvectorSidecar so LLM agents
+        // can ask "is the optimized ruvector backend reachable?" before
+        // dispatching embedding-heavy work that would benefit from it.
+        // Composable: pair with `embeddings_status` for the full local
+        // capability picture, or with `agentdb_health` for the full
+        // memory-substrate picture.
+        name: 'embeddings_check_ruvector_sidecar',
+        description: 'Check whether the ruvector CLI MCP sidecar is reachable and report its version + MCP tool surface. Use when a multi-step embedding pipeline could delegate to the optimized native Rust backend instead of going through this JS layer — the report tells you whether that path is available. For "is anything broken?" use ruflo doctor; for "should I use ruvector for this batch?" use this tool. Never throws.',
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                timeoutMs: {
+                    type: 'number',
+                    description: 'Per-shellout timeout (default 5000ms).',
+                },
+            },
+        },
+        handler: async (input) => {
+            // Deep import — the top-level @claude-flow/embeddings barrel's
+            // type re-exports don't resolve cleanly through the CLI's
+            // bundler-mode TypeScript at workspace-symlink time (the dist
+            // file is present + has the export, but TS sees stale types).
+            // The dist sub-module path is stable across alpha bumps because
+            // `files: ['dist']` ships it.
+            // Use the `./<file>` wildcard sub-path (no `.js` suffix) — the
+            // exports map appends `.js` for the import target.
+            const mod = await import('@claude-flow/embeddings/ruvector-mcp-probe');
+            const timeoutMs = typeof input?.timeoutMs === 'number' ? input.timeoutMs : 5_000;
+            const report = await mod.probeRuvectorSidecar({ timeoutMs });
+            return {
+                success: true,
+                ...report,
+                // Single-line summary suitable for inline display.
+                summary: mod.formatRuvectorAvailability(report),
+            };
+        },
+    },
+    // ============================================================
+    // ADR-121 Phase 5b — DiskannSnapshot MCP tools (alpha.47 CLI)
+    // ============================================================
+    //
+    // Process-level registry of named DiskannSnapshot handles. Build
+    // an index once, search it many times. Persistence to disk via
+    // the snapshot's storagePath; the handle is keyed by `name`.
+    // For in-memory snapshots, set persist: false and the index is
+    // re-built only while this process lives.
+    {
+        name: 'embeddings_diskann_build',
+        description: 'Build a DiskANN/Vamana ANN index from a batch of (id, vector) pairs. Use when you have a fixed corpus (≥10k vectors typical) that needs sub-millisecond ANN search and you want persistence across process restarts — for streaming inserts at smaller scale use SearchableEmbeddingCache instead, for batch in-memory 32×-compressed use RabitqSnapshot. Pair with embeddings_diskann_search to query, embeddings_diskann_status to inspect. Requires @ruvector/diskann (optional peer dep — throws a clear named error if missing).',
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Snapshot handle name (used by search + status). Must be unique per process.' },
+                dimension: { type: 'number', description: 'Embedding dimension.' },
+                entries: {
+                    type: 'array',
+                    description: 'Vectors to index. Each entry: { id: string, vector: number[] }.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            vector: { type: 'array', items: { type: 'number' } },
+                        },
+                        required: ['id', 'vector'],
+                    },
+                },
+                storagePath: { type: 'string', description: 'Optional directory for on-disk persistence (snapshot survives restarts via embeddings_diskann_load).' },
+            },
+            required: ['name', 'dimension', 'entries'],
+        },
+        handler: async (input) => {
+            const { getDiskannRegistry } = await import('../memory/diskann-registry.js');
+            const registry = getDiskannRegistry();
+            const name = input.name;
+            const dimension = input.dimension;
+            const entries = input.entries;
+            const storagePath = input.storagePath;
+            try {
+                const stats = await registry.build({ name, dimension, entries, storagePath });
+                return { success: true, name, ...stats };
+            }
+            catch (err) {
+                return { success: false, name, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    },
+    {
+        name: 'embeddings_diskann_search',
+        description: 'Search a previously-built DiskANN index for the k nearest neighbors of a query vector. Use when you built an index via embeddings_diskann_build and now need ANN retrieval — returns ids + L2² distances sorted ascending. For text→vector→search in one call, pair with embeddings_generate first. For exact-match key lookup over a streaming cache, use SearchableEmbeddingCache.get instead.',
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Snapshot handle name (set by embeddings_diskann_build).' },
+                vector: { type: 'array', items: { type: 'number' }, description: 'Query vector. Must match the index dimension.' },
+                k: { type: 'number', description: 'Number of nearest neighbors to return.' },
+            },
+            required: ['name', 'vector', 'k'],
+        },
+        handler: async (input) => {
+            const { getDiskannRegistry } = await import('../memory/diskann-registry.js');
+            const registry = getDiskannRegistry();
+            const name = input.name;
+            const vector = new Float32Array(input.vector);
+            const k = input.k;
+            try {
+                const hits = await registry.search(name, vector, k);
+                return { success: true, name, k, hits };
+            }
+            catch (err) {
+                return { success: false, name, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    },
+    {
+        name: 'embeddings_diskann_status',
+        description: 'List all DiskANN snapshots currently held by this MCP server, with their dimension, vector count, and storage path. Use when you want to inventory in-process indexes before opening a new one, or when debugging "which snapshot did I build?". For checking whether the @ruvector/diskann peer dep itself is installed, use embeddings_check_ruvector_sidecar (the family probe) instead.',
+        category: 'embeddings',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const { getDiskannRegistry } = await import('../memory/diskann-registry.js');
+            const registry = getDiskannRegistry();
+            return { success: true, snapshots: registry.list() };
+        },
+    },
 ];
 //# sourceMappingURL=embeddings-tools.js.map

package/v3/@claude-flow/cli/dist/src/memory/diskann-registry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Process-level registry of named `DiskannSnapshot` handles backing
+ * the `embeddings_diskann_*` MCP tools.
+ *
+ * Lifecycle:
+ *   - `build({ name, dimension, entries, storagePath? })` →
+ *     creates a snapshot, adds the entries, builds the Vamana graph,
+ *     persists if storagePath is set, stashes the handle under `name`.
+ *   - `search(name, vector, k)` → top-k against the named snapshot.
+ *   - `list()` → inventory of all current snapshots (name, dimension,
+ *     count, storagePath?).
+ *
+ * The registry is process-level; agents that want cross-restart
+ * persistence should pass `storagePath` on build and reload from
+ * disk via a separate `embeddings_diskann_load` follow-up tool.
+ *
+ * ADR-121 Phase 5b — cli alpha.47.
+ */
+export interface DiskannBuildInput {
+    readonly name: string;
+    readonly dimension: number;
+    readonly entries: ReadonlyArray<{
+        id: string;
+        vector: number[];
+    }>;
+    readonly storagePath?: string;
+}
+export interface DiskannBuildResult {
+    readonly dimension: number;
+    readonly count: number;
+    readonly buildMs: number;
+    readonly storagePath?: string;
+}
+export interface DiskannSearchHit {
+    readonly id: string;
+    readonly distance: number;
+}
+export interface DiskannSnapshotInfo {
+    readonly name: string;
+    readonly dimension: number;
+    readonly count: number;
+    readonly storagePath?: string;
+}
+declare class DiskannRegistry {
+    private readonly entries;
+    private snapshotCtor;
+    private loadCtor;
+    build(input: DiskannBuildInput): Promise<DiskannBuildResult>;
+    search(name: string, vector: Float32Array, k: number): Promise<DiskannSearchHit[]>;
+    list(): DiskannSnapshotInfo[];
+    /** Test seam — clear the registry between tests. */
+    clear(): void;
+}
+export declare function getDiskannRegistry(): DiskannRegistry;
+export {};
+//# sourceMappingURL=diskann-registry.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/diskann-registry.js

@@ -0,0 +1,88 @@
+/**
+ * Process-level registry of named `DiskannSnapshot` handles backing
+ * the `embeddings_diskann_*` MCP tools.
+ *
+ * Lifecycle:
+ *   - `build({ name, dimension, entries, storagePath? })` →
+ *     creates a snapshot, adds the entries, builds the Vamana graph,
+ *     persists if storagePath is set, stashes the handle under `name`.
+ *   - `search(name, vector, k)` → top-k against the named snapshot.
+ *   - `list()` → inventory of all current snapshots (name, dimension,
+ *     count, storagePath?).
+ *
+ * The registry is process-level; agents that want cross-restart
+ * persistence should pass `storagePath` on build and reload from
+ * disk via a separate `embeddings_diskann_load` follow-up tool.
+ *
+ * ADR-121 Phase 5b — cli alpha.47.
+ */
+class DiskannRegistry {
+    entries = new Map();
+    snapshotCtor = null;
+    async loadCtor() {
+        if (this.snapshotCtor)
+            return this.snapshotCtor;
+        // Same wildcard sub-path import the sidecar tool uses (Phase 5 full).
+        const mod = await import('@claude-flow/embeddings/diskann-snapshot');
+        this.snapshotCtor = mod.DiskannSnapshot;
+        return this.snapshotCtor;
+    }
+    async build(input) {
+        const ctor = await this.loadCtor();
+        const t0 = Date.now();
+        const snap = await ctor.create({
+            dimension: input.dimension,
+            storagePath: input.storagePath,
+        });
+        // Convert plain-number arrays from the MCP input into Float32Array.
+        const float32Entries = input.entries.map(e => ({
+            id: e.id,
+            vector: new Float32Array(e.vector),
+        }));
+        snap.add(float32Entries);
+        await snap.build();
+        const buildMs = Date.now() - t0;
+        // Replace any existing snapshot under this name.
+        this.entries.set(input.name, {
+            snapshot: snap,
+            dimension: input.dimension,
+            storagePath: input.storagePath,
+        });
+        return {
+            dimension: input.dimension,
+            count: snap.count(),
+            buildMs,
+            storagePath: input.storagePath,
+        };
+    }
+    async search(name, vector, k) {
+        const entry = this.entries.get(name);
+        if (!entry) {
+            throw new Error(`embeddings_diskann_search: no snapshot named "${name}" — call embeddings_diskann_build first`);
+        }
+        return entry.snapshot.search(vector, k);
+    }
+    list() {
+        const out = [];
+        for (const [name, entry] of this.entries) {
+            out.push({
+                name,
+                dimension: entry.dimension,
+                count: entry.snapshot.count(),
+                storagePath: entry.storagePath,
+            });
+        }
+        return out;
+    }
+    /** Test seam — clear the registry between tests. */
+    clear() {
+        this.entries.clear();
+    }
+}
+let singleton = null;
+export function getDiskannRegistry() {
+    if (!singleton)
+        singleton = new DiskannRegistry();
+    return singleton;
+}
+//# sourceMappingURL=diskann-registry.js.map

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

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.7.0-alpha.45",
+  "version": "3.7.0-alpha.47",
   "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",
@@ -104,14 +104,14 @@
     "semver": "^7.6.0",
     "yaml": "^2.8.0",
     "@claude-flow/memory": "^3.0.0-alpha.17",
-    "@claude-flow/embeddings": "^3.0.0-alpha.18",
+    "@claude-flow/embeddings": "^3.0.0-alpha.26",
     "@claude-flow/security": "^3.0.0-alpha.8",
     "@claude-flow/swarm": "^3.0.0-alpha.8"
   },
   "optionalDependencies": {
     "@claude-flow/aidefence": "^3.0.2",
     "@claude-flow/codex": "^3.0.0-alpha.8",
-    "@claude-flow/embeddings": "^3.0.0-alpha.18",
+    "@claude-flow/embeddings": "^3.0.0-alpha.26",
     "@claude-flow/guidance": "^3.0.0-alpha.1",
     "@claude-flow/memory": "^3.0.0-alpha.17",
     "@claude-flow/plugin-gastown-bridge": "^0.1.3",

package/v3/@claude-flow/cli/dist/src/ruvector/flash-attention.d.ts

@@ -1,195 +0,0 @@
-/**
- * Flash Attention Implementation for RuVector Intelligence System
- *
- * Implements block-wise attention computation for faster similarity calculations.
- * Achieves O(N) memory instead of O(N^2) through tiling strategy.
- *
- * Key optimizations:
- * - Block-wise computation to fit in L1 cache
- * - Fused softmax-matmul operations
- * - Float32Array for all operations
- * - Online softmax for numerical stability
- *
- * Target: 2-5x speedup on CPU vs naive attention
- *
- * Created with love by ruv.io
- */
-export interface FlashAttentionConfig {
-    /** Block size for tiling (32-64 optimal for CPU L1 cache) */
-    blockSize: number;
-    /** Number of dimensions in embedding vectors */
-    dimensions: number;
-    /** Temperature for softmax scaling */
-    temperature: number;
-    /** Enable numerical stability optimizations */
-    useStableMode: boolean;
-    /** Use optimized CPU path (default: true) */
-    useCPUOptimizations: boolean;
-}
-export interface AttentionResult {
-    /** Output vectors after attention */
-    output: Float32Array[];
-    /** Attention weights (optional, for debugging) */
-    weights?: Float32Array[];
-    /** Computation time in milliseconds */
-    computeTimeMs: number;
-}
-export interface BenchmarkResult {
-    /** Naive attention time in milliseconds */
-    naiveTimeMs: number;
-    /** Flash attention time in milliseconds */
-    flashTimeMs: number;
-    /** Speedup factor (naive / flash) */
-    speedup: number;
-    /** Number of vectors benchmarked */
-    numVectors: number;
-    /** Dimensions of vectors */
-    dimensions: number;
-    /** Memory usage estimate for naive (bytes) */
-    naiveMemoryBytes: number;
-    /** Memory usage estimate for flash (bytes) */
-    flashMemoryBytes: number;
-    /** Memory reduction factor */
-    memoryReduction: number;
-}
-export declare class FlashAttention {
-    private config;
-    private lastSpeedup;
-    private benchmarkHistory;
-    private scoreBuffer;
-    private expBuffer;
-    private accumBuffer;
-    constructor(config?: Partial<FlashAttentionConfig>);
-    /**
-     * Main attention computation using Flash Attention algorithm
-     *
-     * @param queries - Query vectors [N x D]
-     * @param keys - Key vectors [M x D]
-     * @param values - Value vectors [M x D]
-     * @returns Attention output [N x D]
-     */
-    attention(queries: Float32Array[], keys: Float32Array[], values: Float32Array[]): AttentionResult;
-    /**
-     * CPU-optimized attention with aggressive optimizations
-     *
-     * Key optimizations:
-     * - Blocked score computation (better cache utilization)
-     * - Top-K sparse attention (only use most relevant keys)
-     * - Pre-allocated buffers to avoid GC pressure
-     * - 8x loop unrolling for dot products
-     * - Fused max-finding during score computation
-     */
-    private cpuOptimizedAttention;
-    /**
-     * Partial dot product using only first N dimensions (for screening)
-     */
-    private partialDotProduct;
-    /**
-     * Partial sort to get top-K elements (QuickSelect-like)
-     * Only ensures first K elements are the largest, not sorted
-     */
-    private partialSort;
-    /**
-     * Swap two indices in array
-     */
-    private swapIndices;
-    /**
-     * Fast dot product with 8x unrolling
-     */
-    private fastDotProduct;
-    /**
-     * Block-wise attention computation (Flash Attention core algorithm)
-     *
-     * Algorithm:
-     * For each block of queries Q_b:
-     *   For each block of keys K_b:
-     *     S_b = Q_b @ K_b.T / sqrt(d)  // Block scores
-     *     P_b = softmax(S_b)           // Block attention
-     *     O_b += P_b @ V_b             // Accumulate output
-     *
-     * @param Q - Query vectors
-     * @param K - Key vectors
-     * @param V - Value vectors
-     * @param blockSize - Block size for tiling
-     */
-    blockAttention(Q: Float32Array[], K: Float32Array[], V: Float32Array[], blockSize: number): Float32Array[];
-    /**
-     * Get the speedup factor from the last benchmark
-     */
-    getSpeedup(): number;
-    /**
-     * Run benchmark comparing naive vs CPU-optimized attention
-     *
-     * @param numVectors - Number of vectors to test
-     * @param dimensions - Dimensions per vector
-     * @param iterations - Number of iterations for averaging
-     */
-    benchmark(numVectors?: number, dimensions?: number, iterations?: number): BenchmarkResult;
-    /**
-     * Get benchmark history
-     */
-    getBenchmarkHistory(): BenchmarkResult[];
-    /**
-     * Get configuration
-     */
-    getConfig(): FlashAttentionConfig;
-    /**
-     * Update configuration
-     */
-    setConfig(config: Partial<FlashAttentionConfig>): void;
-    /**
-     * Naive O(N^2) attention implementation for comparison
-     */
-    private naiveAttention;
-    /**
-     * Compute block of attention scores
-     */
-    private computeBlockScores;
-    /**
-     * Online softmax with output accumulation (key to Flash Attention)
-     *
-     * Uses the online softmax trick to maintain numerical stability
-     * while processing blocks incrementally.
-     */
-    private onlineSoftmaxAccumulate;
-    /**
-     * Compute dot product of two vectors
-     */
-    private dotProduct;
-    /**
-     * Stable softmax implementation
-     */
-    private softmax;
-    /**
-     * Generate random vectors for benchmarking
-     */
-    private generateRandomVectors;
-    /**
-     * Validate input arrays
-     */
-    private validateInputs;
-}
-/**
- * Get singleton FlashAttention instance
- *
- * @param config - Optional configuration (only used on first call)
- * @returns FlashAttention instance
- */
-export declare function getFlashAttention(config?: Partial<FlashAttentionConfig>): FlashAttention;
-/**
- * Reset singleton (for testing)
- */
-export declare function resetFlashAttention(): void;
-/**
- * Compute attention using Flash Attention
- */
-export declare function computeAttention(queries: Float32Array[], keys: Float32Array[], values: Float32Array[], config?: Partial<FlashAttentionConfig>): AttentionResult;
-/**
- * Run Flash Attention benchmark
- */
-export declare function benchmarkFlashAttention(numVectors?: number, dimensions?: number, iterations?: number): BenchmarkResult;
-/**
- * Get current speedup from last benchmark
- */
-export declare function getFlashAttentionSpeedup(): number;
-//# sourceMappingURL=flash-attention.d.ts.map