@claude-flow/cli 3.32.1 → 3.32.3

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

@@ -1,83 +0,0 @@
-/**
- * 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

@@ -1,277 +0,0 @@
-/**
- * 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

@@ -1,227 +0,0 @@
-/**
- * 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