@claude-flow/cli 3.32.3 → 3.32.4

package/dist/src/ruvector/output-verifier.d.ts

@@ -0,0 +1,83 @@
+/**
+ * output-verifier.ts — Confidence-gated tier escalation (post-generation).
+ *
+ * ADR-026/143 route tasks to a tier BEFORE generation. 2026 SOTA cascade
+ * routing adds a post-generation gate: attempt the cheap tier, run a CHEAP
+ * verifier over the produced output, and escalate to the next tier only when
+ * the verifier is not confident. This module is that verifier.
+ *
+ * Design constraints (load-bearing):
+ * - $0 by default — NO LLM call. Every signal is a structural / lexical
+ *   check: emptiness, refusal patterns, truncation, delimiter balance,
+ *   degenerate repetition, and (for code tasks) a real syntax parse via the
+ *   TypeScript compiler (lazy-imported; degrades to delimiter checks when
+ *   typescript is not installed) or JSON.parse for JSON output.
+ * - Pure with respect to router state — recording the verdict into the
+ *   bandit's learning stream is the CALLER's job (the hooks_model-verify
+ *   MCP tool does it via ModelRouter.recordOutcome), keeping this module
+ *   trivially unit-testable.
+ * - Escalation ladder mirrors the tier table: tier 2 (haiku) → tier 3
+ *   (sonnet), sonnet → opus, opus has no bump (escalate=false even when the
+ *   verdict is not confident — the caller should retry or surface instead).
+ *
+ * Verdict semantics: `confident=false` means "cheap signals say this output
+ * is likely unusable"; it is NOT a semantic-quality judgment. False
+ * negatives (bad output that parses fine) are expected — this gate trades
+ * recall for being free.
+ *
+ * @module ruvector/output-verifier
+ */
+export type VerifyTier = 1 | 2 | 3;
+export type VerifyModel = 'haiku' | 'sonnet' | 'opus';
+export type VerifyTaskKind = 'code' | 'json' | 'text' | 'auto';
+export interface VerifyInput {
+    /** The task the output was generated for. */
+    task: string;
+    /** The generated output to verify. */
+    output: string;
+    /** Model that produced the output (drives the escalation ladder). */
+    model?: VerifyModel;
+    /** Tier that produced the output; derived from `model` when absent. */
+    tierUsed?: VerifyTier;
+    /** Force the task kind; 'auto' (default) detects from task + output. */
+    taskKind?: VerifyTaskKind;
+    /** Minimum trimmed output length considered plausible (default 20). */
+    minLength?: number;
+}
+export interface VerifySignal {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface VerifyVerdict {
+    confident: boolean;
+    /** Fraction of signals that passed (0..1). */
+    score: number;
+    /** Human-readable failure reasons; empty when confident. */
+    reasons: string[];
+    /** Every signal evaluated, pass or fail. */
+    signals: VerifySignal[];
+    /** Tier the caller should use next: unchanged when confident, bumped 2→3 on failure. */
+    suggestedTier: VerifyTier;
+    /** Concrete next model on the ladder (haiku→sonnet→opus); null when no bump exists. */
+    suggestedModel: VerifyModel | null;
+    /** True when not confident AND a higher tier exists to escalate to. */
+    escalate: boolean;
+    /** Detected task kind after 'auto' resolution. */
+    taskKind: Exclude<VerifyTaskKind, 'auto'>;
+}
+interface ExtractedCode {
+    lang: string;
+    code: string;
+}
+/** Pull fenced code blocks out of markdown-ish output. */
+export declare function extractCodeBlocks(output: string): ExtractedCode[];
+/** Cheap stack-based bracket balance check that skips string/comment-ish content. */
+export declare function bracketsBalanced(code: string): boolean;
+/**
+ * Compute a confidence verdict for `output` from cheap structural signals,
+ * and suggest an escalation target when not confident.
+ */
+export declare function verifyAndEscalate(input: VerifyInput): Promise<VerifyVerdict>;
+export default verifyAndEscalate;
+//# sourceMappingURL=output-verifier.d.ts.map

package/dist/src/ruvector/output-verifier.js

@@ -0,0 +1,277 @@
+/**
+ * output-verifier.ts — Confidence-gated tier escalation (post-generation).
+ *
+ * ADR-026/143 route tasks to a tier BEFORE generation. 2026 SOTA cascade
+ * routing adds a post-generation gate: attempt the cheap tier, run a CHEAP
+ * verifier over the produced output, and escalate to the next tier only when
+ * the verifier is not confident. This module is that verifier.
+ *
+ * Design constraints (load-bearing):
+ * - $0 by default — NO LLM call. Every signal is a structural / lexical
+ *   check: emptiness, refusal patterns, truncation, delimiter balance,
+ *   degenerate repetition, and (for code tasks) a real syntax parse via the
+ *   TypeScript compiler (lazy-imported; degrades to delimiter checks when
+ *   typescript is not installed) or JSON.parse for JSON output.
+ * - Pure with respect to router state — recording the verdict into the
+ *   bandit's learning stream is the CALLER's job (the hooks_model-verify
+ *   MCP tool does it via ModelRouter.recordOutcome), keeping this module
+ *   trivially unit-testable.
+ * - Escalation ladder mirrors the tier table: tier 2 (haiku) → tier 3
+ *   (sonnet), sonnet → opus, opus has no bump (escalate=false even when the
+ *   verdict is not confident — the caller should retry or surface instead).
+ *
+ * Verdict semantics: `confident=false` means "cheap signals say this output
+ * is likely unusable"; it is NOT a semantic-quality judgment. False
+ * negatives (bad output that parses fine) are expected — this gate trades
+ * recall for being free.
+ *
+ * @module ruvector/output-verifier
+ */
+const MODEL_TIER = { haiku: 2, sonnet: 3, opus: 3 };
+const NEXT_MODEL = {
+    haiku: 'sonnet',
+    sonnet: 'opus',
+    opus: null,
+};
+// Refusal phrasings scanned near the start of the output. Anchored to the
+// head so a legitimate answer that *discusses* refusals doesn't trip it.
+const REFUSAL_HEAD_CHARS = 240;
+const REFUSAL_PATTERNS = [
+    /\bI\s+(?:can(?:no|')t|cannot)\s+(?:help|assist|do|provide|comply|fulfill|complete|write|generate)\b/i,
+    /\bI(?:'m| am)\s+(?:sorry|afraid)\b[\s\S]{0,60}\b(?:can(?:no|')t|cannot|unable)\b/i,
+    /\bI(?:'m| am)\s+(?:unable|not able)\s+to\b/i,
+    /\bI\s+(?:must|have to)\s+(?:decline|refuse)\b/i,
+    /\bI\s+won'?t\s+be\s+able\s+to\b/i,
+    /\bas an AI(?:\s+(?:language\s+)?model)?[,\s]+I\b/i,
+];
+// A trailing dangling operator / opener strongly suggests a mid-expression cutoff.
+const TRUNCATION_TAIL = /(?:,|&&|\|\||=>|[+*/%=]|\(|\[|\{|\bconst|\blet|\bvar|\bfunction|\breturn|:)\s*$/;
+/** Pull fenced code blocks out of markdown-ish output. */
+export function extractCodeBlocks(output) {
+    const blocks = [];
+    const re = /```([A-Za-z0-9_-]*)\n([\s\S]*?)```/g;
+    let m;
+    while ((m = re.exec(output)) !== null) {
+        blocks.push({ lang: (m[1] || '').toLowerCase(), code: m[2] });
+    }
+    return blocks;
+}
+/** Cheap stack-based bracket balance check that skips string/comment-ish content. */
+export function bracketsBalanced(code) {
+    const stack = [];
+    const pairs = { ')': '(', ']': '[', '}': '{' };
+    let inString = null;
+    let inLineComment = false;
+    let inBlockComment = false;
+    for (let i = 0; i < code.length; i++) {
+        const c = code[i];
+        const next = code[i + 1];
+        if (inLineComment) {
+            if (c === '\n')
+                inLineComment = false;
+            continue;
+        }
+        if (inBlockComment) {
+            if (c === '*' && next === '/') {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            if (c === '\\') {
+                i++;
+                continue;
+            }
+            if (c === inString)
+                inString = null;
+            continue;
+        }
+        if (c === '/' && next === '/') {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (c === '/' && next === '*') {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === '`') {
+            inString = c;
+            continue;
+        }
+        if (c === '(' || c === '[' || c === '{')
+            stack.push(c);
+        else if (c === ')' || c === ']' || c === '}') {
+            if (stack.pop() !== pairs[c])
+                return false;
+        }
+    }
+    return stack.length === 0;
+}
+const CODE_TASK_HINT = /\b(?:code|function|class|implement|refactor|typescript|javascript|python|script|method|api endpoint|unit test)\b/i;
+const CODE_OUTPUT_HINT = /(?:^|\n)\s*(?:import\s|export\s|function\s|class\s|const\s|let\s|def\s|return\s)/;
+function detectTaskKind(input) {
+    if (input.taskKind && input.taskKind !== 'auto')
+        return input.taskKind;
+    if (/\bjson\b/i.test(input.task) && /^[\s]*[[{]/.test(input.output.trim()))
+        return 'json';
+    if (extractCodeBlocks(input.output).length > 0)
+        return 'code';
+    if (CODE_TASK_HINT.test(input.task) && CODE_OUTPUT_HINT.test(input.output))
+        return 'code';
+    return 'text';
+}
+/**
+ * Syntax-check a JS/TS snippet. Uses the TypeScript compiler when available
+ * (transpileModule with reportDiagnostics catches syntactic errors without
+ * type-checking — cheap, no program construction). Falls back to bracket
+ * balance when typescript is not installed.
+ */
+async function checkCodeParses(code, lang) {
+    if (lang === 'json') {
+        try {
+            JSON.parse(code);
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, detail: `JSON.parse failed: ${e instanceof Error ? e.message : String(e)}` };
+        }
+    }
+    const jsLike = ['', 'js', 'jsx', 'ts', 'tsx', 'javascript', 'typescript', 'mjs', 'cjs'].includes(lang);
+    if (!jsLike) {
+        // Non-JS languages: bracket balance is the best free proxy we have.
+        return bracketsBalanced(code)
+            ? { ok: true, detail: `no parser for lang="${lang}"; delimiter check only` }
+            : { ok: false, detail: `unbalanced delimiters in ${lang} block` };
+    }
+    try {
+        const ts = (await import('typescript')).default;
+        const result = ts.transpileModule(code, {
+            reportDiagnostics: true,
+            compilerOptions: { jsx: ts.JsxEmit.Preserve, allowJs: true },
+        });
+        const syntaxErrors = (result.diagnostics ?? []).filter(d => d.category === ts.DiagnosticCategory.Error);
+        if (syntaxErrors.length > 0) {
+            const first = syntaxErrors[0];
+            const msg = ts.flattenDiagnosticMessageText(first.messageText, ' ');
+            return { ok: false, detail: `syntax error: ${msg}` };
+        }
+        return { ok: true };
+    }
+    catch {
+        // typescript not installed — graceful degradation, delimiter check only.
+        return bracketsBalanced(code)
+            ? { ok: true, detail: 'typescript unavailable; delimiter check only' }
+            : { ok: false, detail: 'typescript unavailable; unbalanced delimiters' };
+    }
+}
+/** Detect degenerate repetition (same non-trivial line repeated many times in a row). */
+function isDegenerate(output) {
+    const lines = output.split('\n').map(l => l.trim()).filter(l => l.length > 8);
+    let run = 1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === lines[i - 1]) {
+            run++;
+            if (run >= 5)
+                return true;
+        }
+        else {
+            run = 1;
+        }
+    }
+    return false;
+}
+/**
+ * Compute a confidence verdict for `output` from cheap structural signals,
+ * and suggest an escalation target when not confident.
+ */
+export async function verifyAndEscalate(input) {
+    const output = input.output ?? '';
+    const trimmed = output.trim();
+    const minLength = input.minLength ?? 20;
+    const taskKind = detectTaskKind(input);
+    const model = input.model ?? 'haiku';
+    const tierUsed = input.tierUsed ?? MODEL_TIER[model] ?? 2;
+    const signals = [];
+    const reasons = [];
+    const fail = (name, detail) => {
+        signals.push({ name, ok: false, detail });
+        reasons.push(`${name}: ${detail}`);
+    };
+    const pass = (name, detail) => signals.push({ name, ok: true, detail });
+    // 1. Emptiness
+    if (trimmed.length === 0)
+        fail('empty-output', 'output is empty or whitespace-only');
+    else
+        pass('empty-output');
+    // 2. Plausible length (skip when already flagged empty)
+    if (trimmed.length > 0 && trimmed.length < minLength) {
+        fail('too-short', `output is ${trimmed.length} chars (< ${minLength})`);
+    }
+    else if (trimmed.length > 0) {
+        pass('too-short');
+    }
+    // 3. Refusal patterns near the head
+    const head = trimmed.slice(0, REFUSAL_HEAD_CHARS);
+    const refusal = REFUSAL_PATTERNS.find(p => p.test(head));
+    if (refusal)
+        fail('refusal', `refusal pattern near start of output (${refusal.source.slice(0, 40)}…)`);
+    else
+        pass('refusal');
+    // 4. Truncation: unclosed code fence, or dangling operator/opener at the tail
+    const fenceCount = (output.match(/```/g) ?? []).length;
+    if (fenceCount % 2 !== 0) {
+        fail('truncation', 'unclosed code fence (odd number of ``` markers)');
+    }
+    else if (trimmed.length > 0 && TRUNCATION_TAIL.test(trimmed)) {
+        fail('truncation', `output ends mid-expression ("…${trimmed.slice(-24).replace(/\n/g, '\\n')}")`);
+    }
+    else {
+        pass('truncation');
+    }
+    // 5. Degenerate repetition
+    if (isDegenerate(trimmed))
+        fail('degenerate-repetition', 'same line repeated 5+ times consecutively');
+    else
+        pass('degenerate-repetition');
+    // 6. Code / JSON parse checks
+    if (taskKind === 'code' || taskKind === 'json') {
+        const blocks = extractCodeBlocks(output);
+        const targets = blocks.length > 0
+            ? blocks
+            : [{ lang: taskKind === 'json' ? 'json' : '', code: output }];
+        let allOk = true;
+        const details = [];
+        for (const block of targets) {
+            const check = await checkCodeParses(block.code, taskKind === 'json' ? 'json' : block.lang);
+            if (!check.ok) {
+                allOk = false;
+                details.push(check.detail ?? 'parse failed');
+            }
+            else if (check.detail) {
+                details.push(check.detail);
+            }
+        }
+        if (allOk)
+            pass('code-parses', details.join('; ') || undefined);
+        else
+            fail('code-parses', details.join('; '));
+    }
+    const passed = signals.filter(s => s.ok).length;
+    const score = signals.length > 0 ? passed / signals.length : 0;
+    const confident = reasons.length === 0;
+    const nextModel = NEXT_MODEL[model] ?? null;
+    const suggestedModel = confident ? null : nextModel;
+    const suggestedTier = confident
+        ? tierUsed
+        : (nextModel !== null ? Math.min(3, tierUsed + 1) : tierUsed);
+    const escalate = !confident && nextModel !== null;
+    if (!confident && nextModel === null) {
+        reasons.push('already-at-top-tier: no higher tier to escalate to — retry or surface to the user');
+    }
+    return { confident, score, reasons, signals, suggestedTier, suggestedModel, escalate, taskKind };
+}
+export default verifyAndEscalate;
+//# sourceMappingURL=output-verifier.js.map

package/dist/src/ruvector/q-learning-router.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Q-Learning Router for Task Routing
+ *
+ * Uses reinforcement learning to optimize task routing decisions
+ * based on historical performance and context.
+ *
+ * Features:
+ * - Caching for repeated task patterns (LRU cache)
+ * - Optimized state space with feature hashing
+ * - Epsilon decay with exponential annealing
+ * - Experience replay buffer for stable learning
+ * - Model persistence to .swarm/q-learning-model.json
+ *
+ * @module q-learning-router
+ */
+/**
+ * Q-Learning Router Configuration
+ */
+export interface QLearningRouterConfig {
+    /** Learning rate (default: 0.1) */
+    learningRate: number;
+    /** Discount factor (default: 0.99) */
+    gamma: number;
+    /** Initial exploration rate (default: 1.0) */
+    explorationInitial: number;
+    /** Final exploration rate (default: 0.01) */
+    explorationFinal: number;
+    /** Exploration decay steps (default: 10000) */
+    explorationDecay: number;
+    /** Exploration decay type (default: 'exponential') */
+    explorationDecayType: 'linear' | 'exponential' | 'cosine';
+    /** Maximum states in Q-table (default: 10000) */
+    maxStates: number;
+    /** Number of actions/routes (default: 8) */
+    numActions: number;
+    /** Experience replay buffer size (default: 1000) */
+    replayBufferSize: number;
+    /** Mini-batch size for replay (default: 32) */
+    replayBatchSize: number;
+    /** Enable experience replay (default: true) */
+    enableReplay: boolean;
+    /** Route cache size (default: 256) */
+    cacheSize: number;
+    /** Cache TTL in milliseconds (default: 300000 = 5 minutes) */
+    cacheTTL: number;
+    /** Model persistence path (default: '.swarm/q-learning-model.json') */
+    modelPath: string;
+    /** Auto-save interval in updates (default: 100) */
+    autoSaveInterval: number;
+    /** State space dimensionality for feature hashing (default: 64) */
+    stateSpaceDim: number;
+}
+/**
+ * Route decision result
+ */
+export interface RouteDecision {
+    /** Selected route/action */
+    route: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Q-values for all routes */
+    qValues: number[];
+    /** Was exploration used */
+    explored: boolean;
+    /** Route alternatives */
+    alternatives: Array<{
+        route: string;
+        score: number;
+    }>;
+}
+/**
+ * Q-Learning Router for intelligent task routing
+ *
+ * Optimized with:
+ * - LRU cache for repeated task patterns
+ * - Feature hashing for efficient state space
+ * - Exponential epsilon decay
+ * - Prioritized experience replay
+ * - Model persistence
+ */
+export declare class QLearningRouter {
+    private config;
+    private qTable;
+    private epsilon;
+    private stepCount;
+    private updateCount;
+    private avgTDError;
+    private ruvectorEngine;
+    private useNative;
+    private replayBuffer;
+    private replayBufferIdx;
+    private totalExperiences;
+    private routeCache;
+    private cacheOrder;
+    private cacheHits;
+    private cacheMisses;
+    private featureHashCache;
+    constructor(config?: Partial<QLearningRouterConfig>);
+    /**
+     * Initialize the router, attempting to load ruvector native module
+     * and restore persisted model if available
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load model from persistence file
+     */
+    loadModel(path?: string): Promise<boolean>;
+    /**
+     * Save model to persistence file
+     */
+    saveModel(path?: string): Promise<boolean>;
+    /**
+     * Route a task based on its context
+     * Uses LRU cache for repeated task patterns
+     */
+    route(taskContext: string, explore?: boolean): RouteDecision;
+    /**
+     * Get cached route decision (LRU cache)
+     */
+    private getCachedRoute;
+    /**
+     * Cache a route decision (LRU eviction)
+     */
+    private cacheRoute;
+    /**
+     * Invalidate cache (call after significant Q-table updates)
+     */
+    invalidateCache(): void;
+    /** Invalidate a single state's cached route (called after its Q-values change
+     * so the next route() reflects the update immediately). */
+    private invalidateCacheEntry;
+    /**
+     * Update Q-values based on feedback
+     * Includes experience replay for stable learning
+     */
+    update(taskContext: string, action: string, reward: number, nextContext?: string): number;
+    /**
+     * Internal Q-value update
+     */
+    private updateQValue;
+    /**
+     * Add experience to circular replay buffer
+     */
+    private addToReplayBuffer;
+    /**
+     * Perform prioritized experience replay
+     * Samples mini-batch from buffer and updates Q-values
+     */
+    private experienceReplay;
+    /**
+     * Sample a prioritized batch from replay buffer
+     * Uses proportional prioritization
+     */
+    private samplePrioritizedBatch;
+    /**
+     * Calculate epsilon using configured decay strategy
+     */
+    private calculateEpsilon;
+    /**
+     * Get statistics including cache and replay buffer metrics
+     */
+    getStats(): Record<string, number>;
+    /**
+     * Reset the router (clears all learned data)
+     */
+    reset(): void;
+    /**
+     * Export Q-table for persistence
+     */
+    export(): Record<string, {
+        qValues: number[];
+        visits: number;
+    }>;
+    /**
+     * Import Q-table from persistence
+     */
+    import(data: Record<string, {
+        qValues: number[];
+        visits: number;
+    }>): void;
+    /**
+     * Legacy hash function (kept for backward compatibility)
+     */
+    private hashState;
+    /**
+     * Public state-key encoder (#2239). This is exactly what `route()` uses
+     * to look up Q-values, so testing it directly is testing the binding the
+     * Q-learner actually sees.
+     */
+    getStateKey(context: string): string;
+    /**
+     * Optimized state hashing using feature extraction
+     * Creates a more semantic representation of the task context
+     */
+    private hashStateOptimized;
+    /**
+     * Extract feature vector from task context
+     * Uses keyword matching and n-gram hashing
+     */
+    private extractFeatures;
+    /**
+     * Convert feature vector to state key
+     * Uses locality-sensitive hashing for similar contexts.
+     *
+     * #2239 — the previous fold was `((hash << 4) ^ q[i]) & 0x7fffffff` over 16
+     * 4-bit groups: each group i landed at bit 4·(15−i), so groups 0–7 (= the
+     * entire keyword block, features 0–31) shifted past the 31-bit mask and were
+     * discarded. Keyword-distinct tasks collapsed to one Q-state. We now use a
+     * 32-bit FNV-1a hash, which mixes every quantized group losslessly into the
+     * state key. Encoder version bumped to 2; see PersistedModel.encoderVersion.
+     */
+    private featureVectorToKey;
+    /**
+     * MurmurHash3 32-bit implementation for n-gram hashing
+     */
+    private murmurhash3;
+    private getQValues;
+    private getOrCreateEntry;
+    private argmax;
+    private softmaxConfidence;
+    private pruneQTable;
+}
+/**
+ * Factory function
+ */
+export declare function createQLearningRouter(config?: Partial<QLearningRouterConfig>): QLearningRouter;
+//# sourceMappingURL=q-learning-router.d.ts.map