@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/ruvector/semantic-router.js

@@ -0,0 +1,178 @@
+/**
+ * Pure JavaScript SemanticRouter implementation
+ *
+ * Provides intent routing using cosine similarity.
+ * This is a fallback implementation since @ruvector/router's native VectorDb has bugs.
+ *
+ * Performance: ~50,000 routes/sec with 100 intents (sufficient for agent routing)
+ */
+export class SemanticRouter {
+    dimension;
+    metric;
+    intents = new Map();
+    totalVectors = 0;
+    constructor(config) {
+        if (!config || typeof config.dimension !== 'number') {
+            throw new Error('SemanticRouter requires a dimension in config');
+        }
+        this.dimension = config.dimension;
+        this.metric = config.metric ?? 'cosine';
+    }
+    /**
+     * Add an intent with pre-computed embeddings
+     */
+    addIntentWithEmbeddings(name, embeddings, metadata = {}) {
+        if (!name || !Array.isArray(embeddings)) {
+            throw new Error('Must provide name and embeddings array');
+        }
+        // Validate embeddings
+        for (const emb of embeddings) {
+            if (!(emb instanceof Float32Array) || emb.length !== this.dimension) {
+                throw new Error(`Embedding must be Float32Array of length ${this.dimension}`);
+            }
+        }
+        // Normalize embeddings for cosine similarity
+        const normalizedEmbeddings = embeddings.map(emb => this.normalize(emb));
+        this.intents.set(name, {
+            name,
+            embeddings: normalizedEmbeddings,
+            metadata,
+        });
+        this.totalVectors += embeddings.length;
+    }
+    /**
+     * Route a query using a pre-computed embedding
+     */
+    routeWithEmbedding(embedding, k = 5) {
+        if (!(embedding instanceof Float32Array) || embedding.length !== this.dimension) {
+            throw new Error(`Embedding must be Float32Array of length ${this.dimension}`);
+        }
+        const normalizedQuery = this.normalize(embedding);
+        const scores = [];
+        // Calculate best score for each intent
+        for (const [intentName, intent] of this.intents) {
+            let bestScore = -Infinity;
+            for (const storedEmb of intent.embeddings) {
+                const score = this.similarity(normalizedQuery, storedEmb);
+                if (score > bestScore) {
+                    bestScore = score;
+                }
+            }
+            scores.push({
+                intent: intentName,
+                score: bestScore,
+                metadata: intent.metadata,
+            });
+        }
+        // Sort by score descending and take top k
+        return scores
+            .sort((a, b) => b.score - a.score)
+            .slice(0, k);
+    }
+    /**
+     * Remove an intent
+     */
+    removeIntent(name) {
+        const intent = this.intents.get(name);
+        if (!intent)
+            return false;
+        this.totalVectors -= intent.embeddings.length;
+        this.intents.delete(name);
+        return true;
+    }
+    /**
+     * Get all intent names
+     */
+    getIntents() {
+        return Array.from(this.intents.keys());
+    }
+    /**
+     * Get intent details
+     */
+    getIntent(name) {
+        const data = this.intents.get(name);
+        if (!data)
+            return null;
+        return {
+            name: data.name,
+            utterances: [], // We don't store utterances, only embeddings
+            metadata: data.metadata,
+        };
+    }
+    /**
+     * Clear all intents
+     */
+    clear() {
+        this.intents.clear();
+        this.totalVectors = 0;
+    }
+    /**
+     * Get total vector count
+     */
+    count() {
+        return this.totalVectors;
+    }
+    /**
+     * Get number of intents
+     */
+    intentCount() {
+        return this.intents.size;
+    }
+    /**
+     * Normalize a vector for cosine similarity
+     */
+    normalize(vec) {
+        let norm = 0;
+        for (let i = 0; i < vec.length; i++) {
+            norm += vec[i] * vec[i];
+        }
+        norm = Math.sqrt(norm);
+        if (norm === 0)
+            return vec;
+        const normalized = new Float32Array(vec.length);
+        for (let i = 0; i < vec.length; i++) {
+            normalized[i] = vec[i] / norm;
+        }
+        return normalized;
+    }
+    /**
+     * Calculate similarity between two normalized vectors
+     */
+    similarity(a, b) {
+        switch (this.metric) {
+            case 'cosine':
+                // For normalized vectors, cosine similarity = dot product
+                return this.dotProduct(a, b);
+            case 'dotProduct':
+                return this.dotProduct(a, b);
+            case 'euclidean':
+                // Convert Euclidean distance to similarity
+                return 1 / (1 + this.euclideanDistance(a, b));
+            default:
+                return this.dotProduct(a, b);
+        }
+    }
+    dotProduct(a, b) {
+        let sum = 0;
+        for (let i = 0; i < a.length; i++) {
+            sum += a[i] * b[i];
+        }
+        return sum;
+    }
+    euclideanDistance(a, b) {
+        let sum = 0;
+        for (let i = 0; i < a.length; i++) {
+            const diff = a[i] - b[i];
+            sum += diff * diff;
+        }
+        return Math.sqrt(sum);
+    }
+}
+/**
+ * Create a SemanticRouter with the given configuration
+ */
+export function createSemanticRouter(config) {
+    return new SemanticRouter(config);
+}
+export default SemanticRouter;
+//# sourceMappingURL=semantic-router.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * task-embedder.ts — Shared lazy task embedder + LRU cache (ADR-149 iter 9).
+ *
+ * The cost-optimal neural router (ADR-149) fires only when `route(task, embedding)`
+ * is called with a real embedding. Two call sites in the dispatcher chain need
+ * embeddings: `agent-tools.ts` (initial routing) and `agent-execute-core.ts`
+ * (the fallback chain on 429/5xx). Before this module they each loaded their
+ * own @xenova/transformers MiniLM pipeline and recomputed embeddings on every
+ * call — including for repeated prompts.
+ *
+ * This module:
+ *   1. Loads the pipeline once per process (`loadTaskEmbedder`).
+ *   2. Caches embeddings per task text via an LRU of configurable size
+ *      (default 500 entries ≈ 1.5 MB at 384-dim).
+ *   3. Hashes by FNV-1a-32 + length to keep the key compact and collision-safe
+ *      for typical prompt sizes.
+ *   4. Returns `undefined` on any failure so callers gracefully fall back to
+ *      the heuristic+bandit path.
+ *
+ * @module task-embedder
+ */
+/**
+ * Compute (or fetch from cache) the 384-dim MiniLM embedding for `task`.
+ * Returns `undefined` on any failure (missing @xenova/transformers, ONNX
+ * runtime error, etc.) so callers can gracefully fall back to the
+ * heuristic+bandit path. Best-effort and never throws.
+ *
+ * Cache hit-rate accumulates across the process lifetime and is observable
+ * via `embedderStats()` for diagnostics.
+ */
+export declare function embedTaskWithCache(task: string): Promise<number[] | undefined>;
+/**
+ * Batch counterpart to `embedTaskWithCache`. For each task, returns the
+ * cached embedding when present, else schedules a fresh inference. The
+ * fresh-inference set is computed in a SINGLE ONNX pass via
+ * @xenova/transformers' array-input mode, amortizing tensor setup +
+ * model-load overhead across the batch. Order of the output array
+ * matches the input order.
+ *
+ * Returns `undefined` for any task that failed to embed (missing dep,
+ * runtime error). Cache state updates as if each task had been called
+ * separately through embedTaskWithCache (hits/misses counters update
+ * accordingly).
+ */
+export declare function embedTaskWithCacheBatch(tasks: string[]): Promise<Array<number[] | undefined>>;
+/** Diagnostic surface — hit/miss counters + cache state. */
+export declare function embedderStats(): {
+    size: number;
+    maxSize: number;
+    hits: number;
+    misses: number;
+    hitRate: number;
+};
+/** Test seam — clear LRU + counters so tests get a fresh baseline. */
+export declare function __resetTaskEmbedderForTests(): void;
+//# sourceMappingURL=task-embedder.d.ts.map

package/dist/src/ruvector/task-embedder.js

@@ -0,0 +1,237 @@
+/**
+ * task-embedder.ts — Shared lazy task embedder + LRU cache (ADR-149 iter 9).
+ *
+ * The cost-optimal neural router (ADR-149) fires only when `route(task, embedding)`
+ * is called with a real embedding. Two call sites in the dispatcher chain need
+ * embeddings: `agent-tools.ts` (initial routing) and `agent-execute-core.ts`
+ * (the fallback chain on 429/5xx). Before this module they each loaded their
+ * own @xenova/transformers MiniLM pipeline and recomputed embeddings on every
+ * call — including for repeated prompts.
+ *
+ * This module:
+ *   1. Loads the pipeline once per process (`loadTaskEmbedder`).
+ *   2. Caches embeddings per task text via an LRU of configurable size
+ *      (default 500 entries ≈ 1.5 MB at 384-dim).
+ *   3. Hashes by FNV-1a-32 + length to keep the key compact and collision-safe
+ *      for typical prompt sizes.
+ *   4. Returns `undefined` on any failure so callers gracefully fall back to
+ *      the heuristic+bandit path.
+ *
+ * @module task-embedder
+ */
+// ============================================================================
+// FNV-1a-32 hash (matches scripts/gen-seed-corpus.mjs + router-trajectory.ts)
+// ============================================================================
+function fnv1a32(s) {
+    let h = 0x811c9dc5 >>> 0;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}
+/** Compact cache key — hash + length so distinct prompts of similar shape collide rarely. */
+function cacheKey(task) {
+    return `${fnv1a32(task)}:${task.length}`;
+}
+// Single shared extractor. Both single-text and array-input modes call this
+// same function (xenova's pipeline returns a callable that accepts either),
+// so we don't pay the ONNX model-load cost twice.
+let _extractorPromise = null;
+function loadExtractor() {
+    if (_extractorPromise !== null)
+        return _extractorPromise;
+    _extractorPromise = (async () => {
+        try {
+            const specifier = '@xenova/transformers';
+            const mod = await import(/* @vite-ignore */ specifier).catch(() => null);
+            if (!mod || typeof mod.pipeline !== 'function')
+                return null;
+            return await mod.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { quantized: true });
+        }
+        catch {
+            return null;
+        }
+    })();
+    return _extractorPromise;
+}
+async function loadEmbedder() {
+    const ex = await loadExtractor();
+    if (!ex)
+        return null;
+    return async (text) => {
+        const out = await ex(text, { pooling: 'mean', normalize: true });
+        return Array.from(out.data);
+    };
+}
+/**
+ * Array-input batch embedder — xenova's pipeline accepts `string[]` and
+ * returns a stacked tensor of shape `[N, dim]`. Shares the same loaded
+ * pipeline with `loadEmbedder` so cold-load cost is paid once across
+ * single + batch usage. Measured speedup: ~1.83× on 30-task batches
+ * against the same-pipeline single-call loop.
+ */
+async function loadEmbedderBatch() {
+    const ex = await loadExtractor();
+    if (!ex)
+        return null;
+    return async (texts) => {
+        const out = await ex(texts, { pooling: 'mean', normalize: true });
+        const dims = out.dims ?? [texts.length, 384];
+        const N = dims[0] ?? texts.length;
+        const dim = dims[1] ?? Math.floor(out.data.length / N);
+        const data = out.data;
+        const result = new Array(N);
+        for (let i = 0; i < N; i++) {
+            result[i] = Array.from(data.subarray(i * dim, (i + 1) * dim));
+        }
+        return result;
+    };
+}
+// ============================================================================
+// LRU cache — Map preserves insertion order, so delete+set on hit = O(1) LRU
+// ============================================================================
+const MAX_SIZE = (() => {
+    const v = parseInt(process.env.CLAUDE_FLOW_ROUTER_EMBED_CACHE_SIZE ?? '500', 10);
+    return Number.isFinite(v) && v >= 0 ? v : 500;
+})();
+const _cache = new Map();
+let _hits = 0;
+let _misses = 0;
+function lruGet(key) {
+    const hit = _cache.get(key);
+    if (hit === undefined)
+        return undefined;
+    // Refresh recency: re-insert at the end.
+    _cache.delete(key);
+    _cache.set(key, hit);
+    return hit;
+}
+function lruSet(key, value) {
+    if (MAX_SIZE === 0)
+        return;
+    if (_cache.has(key))
+        _cache.delete(key);
+    _cache.set(key, value);
+    while (_cache.size > MAX_SIZE) {
+        const oldest = _cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        _cache.delete(oldest);
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Compute (or fetch from cache) the 384-dim MiniLM embedding for `task`.
+ * Returns `undefined` on any failure (missing @xenova/transformers, ONNX
+ * runtime error, etc.) so callers can gracefully fall back to the
+ * heuristic+bandit path. Best-effort and never throws.
+ *
+ * Cache hit-rate accumulates across the process lifetime and is observable
+ * via `embedderStats()` for diagnostics.
+ */
+export async function embedTaskWithCache(task) {
+    if (typeof task !== 'string' || task.length === 0)
+        return undefined;
+    const key = cacheKey(task);
+    const cached = lruGet(key);
+    if (cached !== undefined) {
+        _hits++;
+        return cached;
+    }
+    try {
+        const embed = await loadEmbedder();
+        if (!embed)
+            return undefined;
+        const v = await embed(task);
+        lruSet(key, v);
+        _misses++;
+        return v;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Batch counterpart to `embedTaskWithCache`. For each task, returns the
+ * cached embedding when present, else schedules a fresh inference. The
+ * fresh-inference set is computed in a SINGLE ONNX pass via
+ * @xenova/transformers' array-input mode, amortizing tensor setup +
+ * model-load overhead across the batch. Order of the output array
+ * matches the input order.
+ *
+ * Returns `undefined` for any task that failed to embed (missing dep,
+ * runtime error). Cache state updates as if each task had been called
+ * separately through embedTaskWithCache (hits/misses counters update
+ * accordingly).
+ */
+export async function embedTaskWithCacheBatch(tasks) {
+    const out = new Array(tasks.length).fill(undefined);
+    // Validate + split into (cached-hits) and (missing-needs-inference).
+    const missingIdx = [];
+    const missingTasks = [];
+    const missingKeys = [];
+    for (let i = 0; i < tasks.length; i++) {
+        const t = tasks[i];
+        if (typeof t !== 'string' || t.length === 0)
+            continue;
+        const key = cacheKey(t);
+        const hit = lruGet(key);
+        if (hit !== undefined) {
+            _hits++;
+            out[i] = hit;
+        }
+        else {
+            missingIdx.push(i);
+            missingTasks.push(t);
+            missingKeys.push(key);
+        }
+    }
+    if (missingTasks.length === 0)
+        return out;
+    try {
+        const embedBatch = await loadEmbedderBatch();
+        if (!embedBatch) {
+            for (let j = 0; j < missingIdx.length; j++)
+                _misses++;
+            return out;
+        }
+        // Real array-input batch: xenova returns one stacked tensor we slice
+        // back into N embeddings. Amortizes tensor setup + ONNX overhead
+        // across the batch (measured 1.83× speedup at N=30).
+        const fresh = await embedBatch(missingTasks);
+        for (let j = 0; j < missingIdx.length; j++) {
+            const v = fresh[j];
+            if (v) {
+                lruSet(missingKeys[j], v);
+                out[missingIdx[j]] = v;
+            }
+            _misses++;
+        }
+    }
+    catch {
+        // best-effort — leave undefined entries as is
+    }
+    return out;
+}
+/** Diagnostic surface — hit/miss counters + cache state. */
+export function embedderStats() {
+    const total = _hits + _misses;
+    return {
+        size: _cache.size,
+        maxSize: MAX_SIZE,
+        hits: _hits,
+        misses: _misses,
+        hitRate: total > 0 ? _hits / total : 0,
+    };
+}
+/** Test seam — clear LRU + counters so tests get a fresh baseline. */
+export function __resetTaskEmbedderForTests() {
+    _cache.clear();
+    _hits = 0;
+    _misses = 0;
+    _extractorPromise = null;
+}
+//# sourceMappingURL=task-embedder.js.map

package/dist/src/ruvector/trajectory-tree.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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
+ */
+export type TreeNodeKind = 'session' | 'trajectory' | 'step';
+export interface TreeNode {
+    id: string;
+    kind: TreeNodeKind;
+    /** Task text (trajectory), action text (step), or session id — ≤200 chars. */
+    label: string;
+    parentId: string | null;
+    childIds: string[];
+    status: 'open' | 'closed';
+    openedAt: string;
+    closedAt?: string;
+    meta?: Record<string, unknown>;
+}
+export interface RecallResult {
+    sessionId: string;
+    /** Root→current node path (the MAGE-style working context). */
+    path: TreeNode[];
+    /** Most recent siblings of the current node (excluding it), oldest→newest. */
+    siblings: TreeNode[];
+    /** Id of the current node (deepest position in the session). */
+    currentId: string | null;
+    strategy: 'state-tree';
+}
+export declare class TrajectoryTree {
+    private nodes;
+    /** sessionId → id of the deepest "current" node (step or open trajectory). */
+    private currentBySession;
+    /** trajectoryId → sessionId, so step/end calls can omit the session. */
+    private trajectorySession;
+    private readonly persistPath;
+    constructor(persistPath?: string);
+    private sessionRootId;
+    private ensureSession;
+    /** Deepest OPEN trajectory node on the current path of a session, if any. */
+    private deepestOpenTrajectory;
+    openTrajectory(args: {
+        sessionId: string;
+        trajectoryId: string;
+        task: string;
+        agent?: string;
+    }): TreeNode;
+    appendStep(args: {
+        trajectoryId: string;
+        stepId: string;
+        action: string;
+        quality?: number;
+    }): TreeNode | null;
+    closeTrajectory(args: {
+        trajectoryId: string;
+        success?: boolean;
+    }): TreeNode | null;
+    /**
+     * 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: {
+        sessionId: string;
+        depth?: number;
+        siblingWindow?: number;
+    }): RecallResult;
+    get size(): number;
+    private load;
+    private save;
+}
+export declare function getTrajectoryTree(persistPath?: string): TrajectoryTree;
+/** Test/reset hook — drops the singleton so the next get() reloads from disk. */
+export declare function resetTrajectoryTree(): void;
+export default TrajectoryTree;
+//# sourceMappingURL=trajectory-tree.d.ts.map