@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/ruvector/trajectory-tree.js

@@ -0,0 +1,237 @@
+/**
+ * trajectory-tree.ts — Execution-state-tree retrieval PROTOTYPE (MAGE-style).
+ *
+ * Research basis: MAGE (arXiv 2606.06090) observes that semantic-similarity
+ * retrieval fragments decision trajectories on long-horizon tasks; retrieving
+ * by POSITION in a hierarchical execution-state tree (the root→current path)
+ * preserves coherence. This module mirrors ruflo's existing trajectory
+ * recording (hooks_intelligence_trajectory-start/step/end) into such a tree
+ * and offers position-based recall — NO embedding search anywhere.
+ *
+ * Structure:
+ *   session root ─ trajectory ─ step
+ *                       └ trajectory (nested: a start while another is open
+ *                                     opens UNDER the open one) ─ step …
+ *
+ * - `trajectory-start` opens a node under the deepest open trajectory of the
+ *   session (or the session root).
+ * - `trajectory-step` appends a step child; the step becomes the "current"
+ *   position of the session.
+ * - `trajectory-end` closes the node; current returns to its parent.
+ * - `recallPath({sessionId, depth})` returns the root→current path (the
+ *   MAGE-style working context) plus the most recent siblings of the current
+ *   node.
+ *
+ * PROTOTYPE LIMITATIONS (deliberate — see the feature spec):
+ * - Persistence is a single best-effort JSON snapshot at
+ *   `.claude-flow/intelligence/trajectory-tree.json`, written on every
+ *   mutation. It sits ALONGSIDE the existing 'trajectories' memory-namespace
+ *   persistence; nothing is migrated and the semantic path is untouched.
+ * - No concurrency control: two MCP server processes sharing a cwd will
+ *   last-writer-win the snapshot.
+ * - No pruning/compaction: long-lived sessions grow the file unboundedly
+ *   (labels are truncated to 200 chars to bound row size, not row count).
+ * - sessionId defaults to CLAUDE_FLOW_SESSION_ID or 'default'; hosts that
+ *   never set it collapse into one tree.
+ * - Retrieval is position-only by design; hybrid position+semantic ranking
+ *   is future work.
+ *
+ * @module ruvector/trajectory-tree
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const DEFAULT_PERSIST_PATH = join('.claude-flow', 'intelligence', 'trajectory-tree.json');
+const LABEL_MAX = 200;
+function now() {
+    return new Date().toISOString();
+}
+function truncate(text) {
+    return text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}…` : text;
+}
+export class TrajectoryTree {
+    nodes = new Map();
+    /** sessionId → id of the deepest "current" node (step or open trajectory). */
+    currentBySession = new Map();
+    /** trajectoryId → sessionId, so step/end calls can omit the session. */
+    trajectorySession = new Map();
+    persistPath;
+    constructor(persistPath) {
+        this.persistPath = resolve(persistPath ?? DEFAULT_PERSIST_PATH);
+        this.load();
+    }
+    sessionRootId(sessionId) {
+        return `session:${sessionId}`;
+    }
+    ensureSession(sessionId) {
+        const id = this.sessionRootId(sessionId);
+        let node = this.nodes.get(id);
+        if (!node) {
+            node = {
+                id,
+                kind: 'session',
+                label: truncate(sessionId),
+                parentId: null,
+                childIds: [],
+                status: 'open',
+                openedAt: now(),
+            };
+            this.nodes.set(id, node);
+        }
+        return node;
+    }
+    /** Deepest OPEN trajectory node on the current path of a session, if any. */
+    deepestOpenTrajectory(sessionId) {
+        let cursor = this.nodes.get(this.currentBySession.get(sessionId) ?? '');
+        while (cursor) {
+            if (cursor.kind === 'trajectory' && cursor.status === 'open')
+                return cursor;
+            cursor = cursor.parentId ? this.nodes.get(cursor.parentId) : undefined;
+        }
+        return null;
+    }
+    openTrajectory(args) {
+        const session = this.ensureSession(args.sessionId);
+        const parent = this.deepestOpenTrajectory(args.sessionId) ?? session;
+        const node = {
+            id: args.trajectoryId,
+            kind: 'trajectory',
+            label: truncate(args.task),
+            parentId: parent.id,
+            childIds: [],
+            status: 'open',
+            openedAt: now(),
+            meta: args.agent ? { agent: args.agent } : undefined,
+        };
+        this.nodes.set(node.id, node);
+        parent.childIds.push(node.id);
+        this.trajectorySession.set(args.trajectoryId, args.sessionId);
+        this.currentBySession.set(args.sessionId, node.id);
+        this.save();
+        return node;
+    }
+    appendStep(args) {
+        const trajectory = this.nodes.get(args.trajectoryId);
+        if (!trajectory || trajectory.kind !== 'trajectory')
+            return null;
+        const sessionId = this.trajectorySession.get(args.trajectoryId);
+        // The upstream stepId scheme (`step-${Date.now()}`) can collide within a
+        // millisecond — uniquify locally instead of clobbering an existing node.
+        let stepId = args.stepId;
+        let bump = 1;
+        while (this.nodes.has(stepId))
+            stepId = `${args.stepId}-${bump++}`;
+        const node = {
+            id: stepId,
+            kind: 'step',
+            label: truncate(args.action),
+            parentId: trajectory.id,
+            childIds: [],
+            status: 'closed',
+            openedAt: now(),
+            closedAt: now(),
+            meta: args.quality !== undefined ? { quality: args.quality } : undefined,
+        };
+        this.nodes.set(node.id, node);
+        trajectory.childIds.push(node.id);
+        if (sessionId)
+            this.currentBySession.set(sessionId, node.id);
+        this.save();
+        return node;
+    }
+    closeTrajectory(args) {
+        const trajectory = this.nodes.get(args.trajectoryId);
+        if (!trajectory || trajectory.kind !== 'trajectory')
+            return null;
+        trajectory.status = 'closed';
+        trajectory.closedAt = now();
+        if (args.success !== undefined) {
+            trajectory.meta = { ...trajectory.meta, success: args.success };
+        }
+        const sessionId = this.trajectorySession.get(args.trajectoryId);
+        if (sessionId && trajectory.parentId) {
+            // Current position pops back to the enclosing trajectory / session root.
+            this.currentBySession.set(sessionId, trajectory.parentId);
+        }
+        this.save();
+        return trajectory;
+    }
+    /**
+     * MAGE-style positional recall: the exact root→current path for a session,
+     * plus the most recent siblings of the current node for local context.
+     *
+     * @param depth Max number of path nodes returned, counted from the CURRENT
+     *              node upward (deepest levels win). Default: full path.
+     * @param siblingWindow Max recent siblings of the current node. Default 3.
+     */
+    recallPath(args) {
+        const currentId = this.currentBySession.get(args.sessionId) ?? null;
+        const path = [];
+        let cursor = currentId ? this.nodes.get(currentId) : undefined;
+        while (cursor) {
+            path.unshift(cursor);
+            cursor = cursor.parentId ? this.nodes.get(cursor.parentId) : undefined;
+        }
+        const depth = args.depth && args.depth > 0 ? args.depth : path.length;
+        const trimmedPath = path.slice(Math.max(0, path.length - depth));
+        const siblingWindow = args.siblingWindow ?? 3;
+        let siblings = [];
+        const current = currentId ? this.nodes.get(currentId) : undefined;
+        const parent = current?.parentId ? this.nodes.get(current.parentId) : undefined;
+        if (current && parent) {
+            siblings = parent.childIds
+                .filter(id => id !== current.id)
+                .map(id => this.nodes.get(id))
+                .filter((n) => !!n)
+                .slice(-siblingWindow);
+        }
+        return { sessionId: args.sessionId, path: trimmedPath, siblings, currentId, strategy: 'state-tree' };
+    }
+    get size() {
+        return this.nodes.size;
+    }
+    // ── Persistence (best-effort JSON snapshot) ──────────────────────────────
+    load() {
+        try {
+            if (!existsSync(this.persistPath))
+                return;
+            const raw = JSON.parse(readFileSync(this.persistPath, 'utf-8'));
+            if (raw?.v !== 1 || typeof raw.nodes !== 'object')
+                return;
+            this.nodes = new Map(Object.entries(raw.nodes));
+            this.currentBySession = new Map(Object.entries(raw.currentBySession ?? {}));
+            this.trajectorySession = new Map(Object.entries(raw.trajectorySession ?? {}));
+        }
+        catch {
+            // Corrupt/unreadable snapshot — start fresh; the semantic trajectory
+            // persistence in the 'trajectories' namespace is unaffected.
+        }
+    }
+    save() {
+        try {
+            const snapshot = {
+                v: 1,
+                nodes: Object.fromEntries(this.nodes),
+                currentBySession: Object.fromEntries(this.currentBySession),
+                trajectorySession: Object.fromEntries(this.trajectorySession),
+            };
+            mkdirSync(dirname(this.persistPath), { recursive: true });
+            writeFileSync(this.persistPath, JSON.stringify(snapshot), 'utf-8');
+        }
+        catch {
+            // Best-effort — tree still lives in memory.
+        }
+    }
+}
+// ── Singleton (mirrors the lazy-singleton pattern used by model-router) ────
+let treeInstance = null;
+export function getTrajectoryTree(persistPath) {
+    if (!treeInstance)
+        treeInstance = new TrajectoryTree(persistPath);
+    return treeInstance;
+}
+/** Test/reset hook — drops the singleton so the next get() reloads from disk. */
+export function resetTrajectoryTree() {
+    treeInstance = null;
+}
+export default TrajectoryTree;
+//# sourceMappingURL=trajectory-tree.js.map

package/dist/src/ruvector/vector-db.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Vector Database Module
+ *
+ * Provides optional ruvector WASM-accelerated vector operations for:
+ * - Semantic similarity search
+ * - HNSW indexing (150x faster)
+ * - Embedding generation
+ *
+ * Gracefully degrades when ruvector is not installed.
+ *
+ * Created with love by ruv.io
+ */
+export interface VectorDB {
+    insert(embedding: Float32Array, id: string, metadata?: Record<string, unknown>): void | Promise<void>;
+    search(query: Float32Array, k?: number): Array<{
+        id: string;
+        score: number;
+        metadata?: Record<string, unknown>;
+    }> | Promise<Array<{
+        id: string;
+        score: number;
+        metadata?: Record<string, unknown>;
+    }>>;
+    remove(id: string): boolean | Promise<boolean>;
+    size(): number | Promise<number>;
+    clear(): void | Promise<void>;
+}
+export interface RuVectorModule {
+    createVectorDB(dimensions: number): Promise<VectorDB>;
+    generateEmbedding(text: string, dimensions?: number): Float32Array;
+    cosineSimilarity(a: Float32Array, b: Float32Array): number;
+    isWASMAccelerated(): boolean;
+}
+/**
+ * Attempt to load the ruvector module
+ * Returns true if successfully loaded, false otherwise
+ */
+export declare function loadRuVector(): Promise<boolean>;
+/**
+ * Check if ruvector is available
+ */
+export declare function isRuVectorAvailable(): boolean;
+/**
+ * Check if WASM acceleration is enabled
+ */
+export declare function isWASMAccelerated(): boolean;
+/**
+ * Create a vector database
+ * Uses ruvector HNSW if available, falls back to brute-force search
+ */
+export declare function createVectorDB(dimensions?: number): Promise<VectorDB>;
+/**
+ * Generate an embedding for text
+ * Uses ruvector if available, falls back to hash-based embedding
+ *
+ * @returns The embedding vector. When using hash fallback, the returned
+ *          Float32Array will have a `_warning` property (non-enumerable)
+ *          indicating it lacks semantic meaning.
+ */
+export declare function generateEmbedding(text: string, dimensions?: number): Float32Array;
+/**
+ * Compute cosine similarity between two vectors
+ */
+export declare function computeSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * Get status information about the ruvector module
+ */
+export declare function getStatus(): {
+    available: boolean;
+    wasmAccelerated: boolean;
+    backend: 'ruvector-stub-search-disabled' | 'ruvector-native' | 'fallback';
+};
+//# sourceMappingURL=vector-db.d.ts.map

package/dist/src/ruvector/vector-db.js

@@ -0,0 +1,301 @@
+/**
+ * Vector Database Module
+ *
+ * Provides optional ruvector WASM-accelerated vector operations for:
+ * - Semantic similarity search
+ * - HNSW indexing (150x faster)
+ * - Embedding generation
+ *
+ * Gracefully degrades when ruvector is not installed.
+ *
+ * Created with love by ruv.io
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { enforceNoStub } from '../memory/embedding-policy.js';
+// ============================================================================
+// Fallback Implementation (when ruvector not available)
+// ============================================================================
+class FallbackVectorDB {
+    vectors = new Map();
+    dimensions;
+    constructor(dimensions) {
+        this.dimensions = dimensions;
+    }
+    insert(embedding, id, metadata) {
+        this.vectors.set(id, { embedding, metadata });
+    }
+    search(query, k = 10) {
+        const results = [];
+        for (const [id, { embedding, metadata }] of this.vectors) {
+            const score = cosineSimilarity(query, embedding);
+            results.push({ id, score, metadata });
+        }
+        return results
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+    }
+    remove(id) {
+        return this.vectors.delete(id);
+    }
+    size() {
+        return this.vectors.size;
+    }
+    clear() {
+        this.vectors.clear();
+    }
+}
+/**
+ * Compute cosine similarity between two vectors
+ */
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dotProduct / denom;
+}
+/**
+ * Whether the hash-embedding one-time warning has been emitted
+ */
+let hashEmbeddingWarned = false;
+/**
+ * Generate a simple hash-based embedding (fallback when ruvector not available)
+ * WARNING: Produces deterministic vectors with NO semantic meaning.
+ */
+function generateHashEmbedding(text, dimensions = 768) {
+    if (!hashEmbeddingWarned) {
+        hashEmbeddingWarned = true;
+        console.warn('[vector-db] Using hash-based pseudo-embeddings (no semantic similarity). ' +
+            'Install ruvector or @claude-flow/embeddings for real ML embeddings.');
+    }
+    const embedding = new Float32Array(dimensions);
+    const normalized = text.toLowerCase().trim();
+    // Simple hash function
+    let hash = 0;
+    for (let i = 0; i < normalized.length; i++) {
+        hash = ((hash << 5) - hash) + normalized.charCodeAt(i);
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    // Generate pseudo-random embedding based on hash
+    for (let i = 0; i < dimensions; i++) {
+        embedding[i] = Math.sin(hash * (i + 1) * 0.001) * 0.5 + 0.5;
+    }
+    // Normalize
+    let norm = 0;
+    for (let i = 0; i < dimensions; i++) {
+        norm += embedding[i] * embedding[i];
+    }
+    norm = Math.sqrt(norm);
+    for (let i = 0; i < dimensions; i++) {
+        embedding[i] /= norm;
+    }
+    return embedding;
+}
+// ============================================================================
+// Module State
+// ============================================================================
+let ruvectorModule = null;
+let loadAttempted = false;
+let isAvailable = false;
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Attempt to load the ruvector module
+ * Returns true if successfully loaded, false otherwise
+ */
+export async function loadRuVector() {
+    if (loadAttempted) {
+        return isAvailable;
+    }
+    loadAttempted = true;
+    try {
+        // Dynamic import to handle missing dependency gracefully
+        const ruvector = await import('ruvector').catch(() => null);
+        // ruvector exports VectorDB class, not createVectorDB function
+        if (ruvector && (typeof ruvector.VectorDB === 'function' || typeof ruvector.VectorDb === 'function')) {
+            // Create adapter module that matches our expected interface
+            const VectorDBClass = ruvector.VectorDB || ruvector.VectorDb;
+            ruvectorModule = {
+                createVectorDB: async (dimensions) => {
+                    // Build the HNSW graph with explicit, high-recall parameters instead
+                    // of relying on the native layer's undocumented defaults. Measured on
+                    // a 384-dim clustered corpus (scripts/benchmark-intelligence.mjs):
+                    //   - sparser graphs (e.g. m=16/efConstruction=64) are faster but
+                    //     drop recall@10 to ~0.68 at N=20k — unacceptable for a memory
+                    //     store, so we use the standard high-recall HNSW setting
+                    //     m=32/efConstruction=200, which keeps recall@10 ~0.99 while still
+                    //     scaling sub-linearly (log-graph traversal) above the crossover.
+                    // These map onto ruvector's DbOptions.hnsw { m, efConstruction }.
+                    //
+                    // storagePath: the native ruvector DB takes an exclusive file lock on
+                    // its storage path. Without an explicit path it defaults to a shared
+                    // file in the CWD (e.g. agentdb.rvf), which is frequently already
+                    // held by a running daemon/MCP server. When the lock cannot be
+                    // acquired the constructor THROWS, and createVectorDB() below
+                    // silently degrades to the O(n) brute-force FallbackVectorDB — so the
+                    // "HNSW" index is never actually used. Giving each transient index a
+                    // unique path avoids that contention so the real HNSW graph is built.
+                    const db = new VectorDBClass({
+                        dimensions,
+                        hnswConfig: { m: 32, efConstruction: 200 },
+                        storagePath: path.join(os.tmpdir(), `ruvector-${process.pid}-${randomUUID()}.rvf`),
+                    });
+                    // Wrap ruvector's VectorDB to match our interface
+                    return {
+                        insert: (embedding, id, metadata) => {
+                            db.insert({ id, vector: embedding, metadata });
+                        },
+                        search: async (query, k = 10) => {
+                            const results = await db.search({ vector: query, k });
+                            return results.map((r) => ({
+                                id: r.id,
+                                score: r.score,
+                                metadata: r.metadata,
+                            }));
+                        },
+                        remove: (id) => {
+                            db.delete(id);
+                            return true;
+                        },
+                        size: async () => {
+                            const len = await db.len();
+                            return len;
+                        },
+                        clear: () => {
+                            // Not directly supported - would need to recreate
+                        },
+                    };
+                },
+                generateEmbedding: (text, dimensions = 768) => {
+                    // ruvector may not have this - use fallback
+                    return generateHashEmbedding(text, dimensions);
+                },
+                cosineSimilarity: (a, b) => {
+                    return cosineSimilarity(a, b);
+                },
+                isWASMAccelerated: () => {
+                    return ruvector.isWasm?.() ?? false;
+                },
+            };
+            isAvailable = true;
+            return true;
+        }
+    }
+    catch {
+        // Silently fail - ruvector is optional
+    }
+    isAvailable = false;
+    return false;
+}
+/**
+ * Check if ruvector is available
+ */
+export function isRuVectorAvailable() {
+    return isAvailable;
+}
+/**
+ * Check if WASM acceleration is enabled
+ */
+export function isWASMAccelerated() {
+    if (ruvectorModule && typeof ruvectorModule.isWASMAccelerated === 'function') {
+        return ruvectorModule.isWASMAccelerated();
+    }
+    return false;
+}
+/**
+ * Create a vector database
+ * Uses ruvector HNSW if available, falls back to brute-force search
+ */
+export async function createVectorDB(dimensions = 768) {
+    await loadRuVector();
+    if (ruvectorModule && typeof ruvectorModule.createVectorDB === 'function') {
+        try {
+            return await ruvectorModule.createVectorDB(dimensions);
+        }
+        catch (err) {
+            // Fall back to simple implementation, but make the degradation VISIBLE.
+            // A silent fall-through here turns HNSW into O(n) brute force without any
+            // signal — exactly the failure mode that masked the lock-contention bug.
+            console.warn(`[vector-db] ruvector HNSW init failed, falling back to brute-force search: ${err?.message ?? err}`);
+        }
+    }
+    return new FallbackVectorDB(dimensions);
+}
+/**
+ * Generate an embedding for text
+ * Uses ruvector if available, falls back to hash-based embedding
+ *
+ * @returns The embedding vector. When using hash fallback, the returned
+ *          Float32Array will have a `_warning` property (non-enumerable)
+ *          indicating it lacks semantic meaning.
+ */
+export function generateEmbedding(text, dimensions = 768) {
+    if (ruvectorModule && typeof ruvectorModule.generateEmbedding === 'function') {
+        try {
+            return ruvectorModule.generateEmbedding(text, dimensions);
+        }
+        catch {
+            // Fall back to hash-based embedding
+        }
+    }
+    enforceNoStub('vector-db.generateEmbedding'); // "no stubs" strict mode → throw instead of hash
+    const embedding = generateHashEmbedding(text, dimensions);
+    // Tag the result so consumers can detect it came from hash fallback
+    Object.defineProperty(embedding, '_warning', {
+        value: 'hash-based pseudo-embedding — no semantic similarity',
+        enumerable: false,
+        configurable: true,
+    });
+    return embedding;
+}
+/**
+ * Compute cosine similarity between two vectors
+ */
+export function computeSimilarity(a, b) {
+    if (ruvectorModule && typeof ruvectorModule.cosineSimilarity === 'function') {
+        try {
+            return ruvectorModule.cosineSimilarity(a, b);
+        }
+        catch {
+            // Fall back to JS implementation
+        }
+    }
+    return cosineSimilarity(a, b);
+}
+/**
+ * Get status information about the ruvector module
+ */
+export function getStatus() {
+    if (!isAvailable) {
+        return {
+            available: false,
+            wasmAccelerated: false,
+            backend: 'fallback',
+        };
+    }
+    // HONESTY (audit docs/reviews/intelligence-system-audit-2026-05-29.md):
+    // ruvector's `isWasm()` does NOT mean "WASM-accelerated" — there is no WASM
+    // HNSW build in this stack. `isWasm()===true` means the do-nothing STUB is
+    // active (search() returns []), i.e. native NAPI failed to load. So
+    // wasmAccelerated===false is the HEALTHY state (native NAPI is the fastest
+    // backend available). We label the stub honestly so a regression into it is
+    // visible instead of being mistaken for a faster mode.
+    const stubActive = isWASMAccelerated();
+    return {
+        available: true,
+        wasmAccelerated: stubActive,
+        backend: stubActive ? 'ruvector-stub-search-disabled' : 'ruvector-native',
+    };
+}
+//# sourceMappingURL=vector-db.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export declare const EMBED_WASM_PKG: string;
+export declare const DEFAULT_EMBED_MODEL: string;
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export declare function wasmEmbedderAvailable(): Promise<boolean>;
+/** Models the configured WASM embedder reports (empty until available). */
+export declare function wasmEmbedderModels(): string[];
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export declare function wasmEmbed(text: string, model?: string): Promise<number[] | null>;
+//# sourceMappingURL=wasm-embedder.d.ts.map