claude-flow 3.7.0-alpha.46 → 3.7.0-alpha.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.46",
+  "version": "3.7.0-alpha.48",
   "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/dist/src/mcp-tools/embeddings-tools.js

@@ -940,5 +940,185 @@ export const embeddingsTools = [
             };
         },
     },
+    // ============================================================
+    // 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() };
+        },
+    },
+    // ============================================================
+    // ADR-121 Phase 8 (CLI) — AnnRouter MCP tools (alpha.48)
+    // ============================================================
+    //
+    // Composition layer: agents declare the workload shape
+    // (corpusSize/persistent/mutable) and the router picks between
+    // HNSW / RaBitQ / DiskANN. The decision is returned to the agent
+    // so they can see what was picked + why (useful for routing
+    // explanations + cost attribution).
+    {
+        name: 'embeddings_ann_router_build',
+        description: "Build an ANN index using AnnRouter — auto-selects between HNSW / RaBitQ / DiskANN based on workload. Use when you have a corpus to index and don't want to choose between the three backings yourself — declare the workload ({corpusSize, persistent, mutable}) and the router picks. Pair with embeddings_ann_router_search to query, embeddings_ann_router_status to see what was picked. For direct DiskANN control (e.g. for known billion-scale persistent indexes), use embeddings_diskann_build instead.",
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Handle name. Must be unique per process.' },
+                workload: {
+                    type: 'object',
+                    properties: {
+                        corpusSize: { type: 'number', description: 'Approximate corpus size.' },
+                        dimension: { type: 'number' },
+                        persistent: { type: 'boolean', description: 'Survive process restarts? Forces DiskANN.' },
+                        mutable: { type: 'boolean', description: 'Streaming inserts/deletes after build? Prefers HNSW.' },
+                        storagePath: { type: 'string', description: 'On-disk path; required when persistent=true.' },
+                    },
+                    required: ['corpusSize', 'dimension'],
+                },
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: { id: { type: 'string' }, vector: { type: 'array', items: { type: 'number' } } },
+                        required: ['id', 'vector'],
+                    },
+                },
+            },
+            required: ['name', 'workload', 'entries'],
+        },
+        handler: async (input) => {
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            try {
+                const result = await registry.build({
+                    name: input.name,
+                    workload: input.workload,
+                    entries: input.entries,
+                });
+                return { success: true, name: input.name, ...result };
+            }
+            catch (err) {
+                return { success: false, name: input.name, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    },
+    {
+        name: 'embeddings_ann_router_search',
+        description: 'Search a named AnnRouter handle for the k nearest neighbors. Returns hits with the routing-decision-aware score (cosine sim for HNSW; L2 distance for RaBitQ/DiskANN — interpret relative to embeddings_ann_router_status). For raw DiskANN search use embeddings_diskann_search; for raw HNSW use SearchableEmbeddingCache.search directly.',
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                vector: { type: 'array', items: { type: 'number' } },
+                k: { type: 'number' },
+            },
+            required: ['name', 'vector', 'k'],
+        },
+        handler: async (input) => {
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            try {
+                const hits = await registry.search(input.name, new Float32Array(input.vector), input.k);
+                return { success: true, name: input.name, k: input.k, hits };
+            }
+            catch (err) {
+                return { success: false, name: input.name, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    },
+    {
+        name: 'embeddings_ann_router_status',
+        description: 'List all AnnRouter handles, each with its decided backing, routing reason, and current count. Use to inventory routed indexes + confirm the router picked what you expected. For peer-dep family availability use embeddings_check_ruvector_sidecar.',
+        category: 'embeddings',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            return { success: true, handles: registry.list() };
+        },
+    },
 ];
 //# sourceMappingURL=embeddings-tools.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * Process-level registry of named AnnRouter handles backing the
+ * `embeddings_ann_router_*` MCP tools.
+ *
+ * Mirrors the shape of `diskann-registry.ts` but for the unified
+ * routing layer. Lifecycle:
+ *   - `build({ name, workload, entries })` creates an AnnRouter with
+ *     the given workload, adds the entries, calls build, stashes the
+ *     handle under `name`. Returns the routing decision so agents
+ *     can see which backing was picked + why.
+ *   - `search(name, vector, k)` runs top-k against the named handle.
+ *   - `list()` returns all handles with their decision + count.
+ *
+ * ADR-121 Phase 8 (CLI) — cli alpha.48.
+ */
+export interface AnnRouterBuildInput {
+    readonly name: string;
+    readonly workload: {
+        readonly corpusSize: number;
+        readonly dimension: number;
+        readonly persistent?: boolean;
+        readonly mutable?: boolean;
+        readonly storagePath?: string;
+    };
+    readonly entries: ReadonlyArray<{
+        id: string;
+        vector: number[];
+    }>;
+}
+export interface AnnRouterDecisionView {
+    readonly backing: string;
+    readonly reason: string;
+    readonly degraded: boolean;
+    readonly degradationReason?: string;
+}
+export interface AnnRouterBuildResult {
+    readonly decision: AnnRouterDecisionView;
+    readonly count: number;
+    readonly buildMs: number;
+}
+export interface AnnRouterSearchHit {
+    readonly id: string;
+    readonly score: number;
+}
+export interface AnnRouterHandleInfo {
+    readonly name: string;
+    readonly decision: AnnRouterDecisionView;
+    readonly count: number;
+}
+declare class AnnRouterRegistry {
+    private readonly entries;
+    private ctor;
+    private loadCtor;
+    build(input: AnnRouterBuildInput): Promise<AnnRouterBuildResult>;
+    search(name: string, vector: Float32Array, k: number): Promise<AnnRouterSearchHit[]>;
+    list(): AnnRouterHandleInfo[];
+    clear(): void;
+}
+export declare function getAnnRouterRegistry(): AnnRouterRegistry;
+export {};
+//# sourceMappingURL=ann-router-registry.d.ts.map

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

@@ -0,0 +1,72 @@
+/**
+ * Process-level registry of named AnnRouter handles backing the
+ * `embeddings_ann_router_*` MCP tools.
+ *
+ * Mirrors the shape of `diskann-registry.ts` but for the unified
+ * routing layer. Lifecycle:
+ *   - `build({ name, workload, entries })` creates an AnnRouter with
+ *     the given workload, adds the entries, calls build, stashes the
+ *     handle under `name`. Returns the routing decision so agents
+ *     can see which backing was picked + why.
+ *   - `search(name, vector, k)` runs top-k against the named handle.
+ *   - `list()` returns all handles with their decision + count.
+ *
+ * ADR-121 Phase 8 (CLI) — cli alpha.48.
+ */
+class AnnRouterRegistry {
+    entries = new Map();
+    ctor = null;
+    async loadCtor() {
+        if (this.ctor)
+            return this.ctor;
+        const mod = await import('@claude-flow/embeddings/ann-router');
+        this.ctor = mod.AnnRouter;
+        return this.ctor;
+    }
+    async build(input) {
+        const Ctor = await this.loadCtor();
+        const t0 = Date.now();
+        const router = await Ctor.create(input.workload);
+        const float32 = input.entries.map(e => ({
+            id: e.id,
+            vector: new Float32Array(e.vector),
+        }));
+        await router.add(float32);
+        await router.build();
+        const buildMs = Date.now() - t0;
+        this.entries.set(input.name, { router, decision: router.decision });
+        return {
+            decision: router.decision,
+            count: router.count(),
+            buildMs,
+        };
+    }
+    async search(name, vector, k) {
+        const entry = this.entries.get(name);
+        if (!entry) {
+            throw new Error(`embeddings_ann_router_search: no router named "${name}" — call embeddings_ann_router_build first`);
+        }
+        return entry.router.search(vector, k);
+    }
+    list() {
+        const out = [];
+        for (const [name, entry] of this.entries) {
+            out.push({
+                name,
+                decision: entry.decision,
+                count: entry.router.count(),
+            });
+        }
+        return out;
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+let singleton = null;
+export function getAnnRouterRegistry() {
+    if (!singleton)
+        singleton = new AnnRouterRegistry();
+    return singleton;
+}
+//# sourceMappingURL=ann-router-registry.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.46",
+  "version": "3.7.0-alpha.48",
   "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",