agentic-qe 3.8.9 → 3.8.11

package/dist/optimization/session-cache.js

@@ -0,0 +1,227 @@
+/**
+ * Agentic QE v3 - Session Operation Cache
+ * Imp-15: Session Reuse for Repeated Operations
+ *
+ * Lightweight fingerprint-based cache for operation results that provides
+ * O(1) exact-match lookups before falling back to HNSW similarity search.
+ * Supplements (does not replace) the EarlyExitTokenOptimizer.
+ *
+ * Architecture:
+ * - SHA-256 fingerprint from canonicalized (domain + action + input)
+ * - In-memory Map for O(1) lookups
+ * - Optional SQLite persistence via kv_store (namespace: 'session_cache')
+ * - TTL-based expiry, LRU-ish eviction at capacity
+ */
+import { createHash } from 'crypto';
+export const DEFAULT_SESSION_CACHE_CONFIG = {
+    enabled: true,
+    maxEntries: 500,
+    ttlMs: 60 * 60 * 1000, // 1 hour
+    persistToDb: true,
+};
+// ============================================================================
+// Canonical JSON (deterministic, recursively sorted keys)
+// ============================================================================
+/**
+ * Produce a deterministic JSON string with recursively sorted object keys.
+ * Ensures identical logical objects always produce the same fingerprint.
+ */
+function canonicalStringify(value) {
+    if (value === null || value === undefined)
+        return JSON.stringify(value);
+    if (typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return '[' + value.map(v => canonicalStringify(v)).join(',') + ']';
+    }
+    const obj = value;
+    const sortedKeys = Object.keys(obj).sort();
+    const pairs = sortedKeys.map(k => JSON.stringify(k) + ':' + canonicalStringify(obj[k]));
+    return '{' + pairs.join(',') + '}';
+}
+// ============================================================================
+// Implementation
+// ============================================================================
+export class SessionOperationCache {
+    cache = new Map();
+    config;
+    hits = 0;
+    misses = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_SESSION_CACHE_CONFIG, ...config };
+    }
+    /**
+     * Compute a deterministic fingerprint from domain + action + input.
+     * Uses SHA-256 of the canonicalized JSON (recursively sorted keys), truncated to 16 hex chars.
+     */
+    computeFingerprint(domain, action, input) {
+        const canonical = canonicalStringify({ action, domain, input });
+        return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+    }
+    /**
+     * Look up a cached result by fingerprint.
+     * Returns null on miss or expired entry.
+     */
+    get(fingerprint) {
+        if (!this.config.enabled)
+            return null;
+        const entry = this.cache.get(fingerprint);
+        if (!entry) {
+            this.misses++;
+            return null;
+        }
+        // Check TTL
+        if (Date.now() - entry.cachedAt > this.config.ttlMs) {
+            this.cache.delete(fingerprint);
+            this.misses++;
+            return null;
+        }
+        entry.hitCount++;
+        entry.lastHitAt = Date.now();
+        this.hits++;
+        return entry;
+    }
+    /**
+     * Store an operation result in the cache.
+     */
+    set(fingerprint, domain, action, result, estimatedTokens) {
+        if (!this.config.enabled)
+            return;
+        // Evict oldest if at capacity
+        if (this.cache.size >= this.config.maxEntries) {
+            this.evictOldest();
+        }
+        const entry = {
+            fingerprint,
+            domain,
+            action,
+            result,
+            tokensSaved: estimatedTokens,
+            cachedAt: Date.now(),
+            hitCount: 0,
+            lastHitAt: 0,
+        };
+        this.cache.set(fingerprint, entry);
+        // Persist to DB (fire-and-forget, non-blocking)
+        if (this.config.persistToDb) {
+            this.persistEntry(entry);
+        }
+    }
+    /**
+     * Load persisted cache entries from SQLite kv_store.
+     * Called on service initialization. Gracefully degrades if DB unavailable.
+     */
+    loadFromDb() {
+        try {
+            const db = tryGetDb();
+            if (!db)
+                return;
+            const cutoffMs = Date.now() - this.config.ttlMs;
+            const rows = db.prepare(`SELECT key, value FROM kv_store
+         WHERE namespace = 'session_cache'
+         AND created_at > ?
+         ORDER BY created_at DESC LIMIT ?`).all(cutoffMs, this.config.maxEntries);
+            for (const row of rows) {
+                try {
+                    const entry = JSON.parse(row.value);
+                    if (Date.now() - entry.cachedAt <= this.config.ttlMs) {
+                        this.cache.set(entry.fingerprint, entry);
+                    }
+                }
+                catch {
+                    /* skip corrupt entries */
+                }
+            }
+        }
+        catch {
+            /* graceful degradation - cache works without persistence */
+        }
+    }
+    /** Get cache statistics */
+    getStats() {
+        const total = this.hits + this.misses;
+        let totalSaved = 0;
+        for (const entry of this.cache.values()) {
+            totalSaved += entry.tokensSaved * entry.hitCount;
+        }
+        return {
+            size: this.cache.size,
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: total > 0 ? this.hits / total : 0,
+            estimatedTokensSaved: totalSaved,
+        };
+    }
+    /** Clear all cache entries and reset counters */
+    clear() {
+        this.cache.clear();
+        this.hits = 0;
+        this.misses = 0;
+    }
+    /** Evict the oldest entry by cachedAt */
+    evictOldest() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache) {
+            if (entry.cachedAt < oldestTime) {
+                oldestTime = entry.cachedAt;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey)
+            this.cache.delete(oldestKey);
+    }
+    /** Persist a single entry to kv_store */
+    persistEntry(entry) {
+        try {
+            const db = tryGetDb();
+            if (!db)
+                return;
+            db.prepare(`INSERT OR REPLACE INTO kv_store (key, namespace, value, created_at)
+         VALUES (?, 'session_cache', ?, ?)`).run(`session_cache:${entry.fingerprint}`, JSON.stringify(entry), Date.now());
+        }
+        catch {
+            /* non-critical - cache works without persistence */
+        }
+    }
+}
+// ============================================================================
+// DB Helper
+// ============================================================================
+/**
+ * Attempt to get the unified memory database.
+ * Returns null if unavailable (graceful degradation).
+ */
+function tryGetDb() {
+    try {
+        // Dynamic require to avoid circular dependencies at import time
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { getUnifiedMemory } = require('../kernel/unified-memory.js');
+        const um = getUnifiedMemory();
+        if (!um.isInitialized())
+            return null;
+        return um.getDatabase();
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Singleton
+// ============================================================================
+let instance = null;
+export function getSessionCache(config) {
+    if (!instance) {
+        instance = new SessionOperationCache(config);
+        instance.loadFromDb();
+    }
+    return instance;
+}
+/** Reset the singleton (for testing) */
+export function resetSessionCache() {
+    if (instance) {
+        instance.clear();
+    }
+    instance = null;
+}
+//# sourceMappingURL=session-cache.js.map

package/dist/optimization/token-optimizer-service.d.ts

@@ -6,6 +6,7 @@
  * integrating with PatternStore and TokenMetricsCollector.
  */
 import { EarlyExitConfig, EarlyExitResult, EarlyExitTask, ReuseStats } from './early-exit-token-optimizer.js';
+import { type SessionCacheStats } from './session-cache.js';
 import type { MemoryBackend } from '../kernel/interfaces.js';
 import type { QEPattern, QEDomain } from '../learning/qe-patterns.js';
 /**
@@ -82,6 +83,15 @@ declare class TokenOptimizerServiceImpl {
      * @returns Multi-line dashboard string
      */
     getDashboardSummary(): string;
+    /**
+     * Imp-15: Store a result in the session cache for future O(1) reuse.
+     * Call this after a successful LLM execution to enable exact-match caching.
+     */
+    cacheOperationResult(domain: string, action: string, input: Record<string, unknown>, result: Record<string, unknown>, estimatedTokens: number): void;
+    /**
+     * Imp-15: Get session cache statistics (hit rate, tokens saved, cache size).
+     */
+    getSessionCacheStats(): SessionCacheStats;
     /**
      * Reset the service (useful for testing)
      */

package/dist/optimization/token-optimizer-service.js

@@ -9,6 +9,7 @@ import { randomUUID } from 'crypto';
 import { EarlyExitTokenOptimizer, DEFAULT_EARLY_EXIT_CONFIG } from './early-exit-token-optimizer.js';
 import { createPatternStore } from '../learning/pattern-store.js';
 import { TokenMetricsCollector, formatDashboardSummary } from '../learning/token-tracker.js';
+import { getSessionCache } from './session-cache.js';
 const DEFAULT_SERVICE_CONFIG = {
     enabled: true,
     earlyExit: DEFAULT_EARLY_EXIT_CONFIG,
@@ -72,6 +73,31 @@ class TokenOptimizerServiceImpl {
                 searchLatencyMs: 0,
             };
         }
+        // Imp-15: O(1) exact-match check via fingerprint cache BEFORE HNSW search
+        try {
+            const cache = getSessionCache();
+            const fingerprint = cache.computeFingerprint(task.domain ?? 'unknown', task.description, task.context ?? {});
+            const cached = cache.get(fingerprint);
+            if (cached) {
+                TokenMetricsCollector.recordEarlyExit(cached.tokensSaved);
+                if (this.config.verbose) {
+                    console.log(`[TokenOptimizerService] Session cache hit: ${fingerprint.slice(0, 8)}... ` +
+                        `(saved ${cached.tokensSaved} tokens)`);
+                }
+                return {
+                    canExit: true,
+                    estimatedTokensSaved: cached.tokensSaved,
+                    confidence: 1.0,
+                    similarityScore: 1.0,
+                    reason: 'pattern_reused',
+                    explanation: `Session cache exact match (fingerprint: ${fingerprint.slice(0, 8)}...)`,
+                    searchLatencyMs: 0,
+                };
+            }
+        }
+        catch {
+            // Graceful degradation: if session cache fails, fall through to HNSW
+        }
         const result = await this.optimizer.checkEarlyExit(task);
         // Record early exit in TokenMetricsCollector
         if (result.canExit && result.estimatedTokensSaved) {
@@ -166,6 +192,31 @@ class TokenOptimizerServiceImpl {
     getDashboardSummary() {
         return formatDashboardSummary();
     }
+    /**
+     * Imp-15: Store a result in the session cache for future O(1) reuse.
+     * Call this after a successful LLM execution to enable exact-match caching.
+     */
+    cacheOperationResult(domain, action, input, result, estimatedTokens) {
+        try {
+            const cache = getSessionCache();
+            const fingerprint = cache.computeFingerprint(domain, action, input);
+            cache.set(fingerprint, domain, action, result, estimatedTokens);
+        }
+        catch {
+            // Graceful degradation
+        }
+    }
+    /**
+     * Imp-15: Get session cache statistics (hit rate, tokens saved, cache size).
+     */
+    getSessionCacheStats() {
+        try {
+            return getSessionCache().getStats();
+        }
+        catch {
+            return { size: 0, hits: 0, misses: 0, hitRate: 0, estimatedTokensSaved: 0 };
+        }
+    }
     /**
      * Reset the service (useful for testing)
      */

package/dist/routing/economic-routing.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Economic Routing Model — Imp-18 (Issue #334)
+ *
+ * Quality-weighted cost optimization for the routing system.
+ * Scores tiers by quality-per-dollar efficiency, respects budget limits,
+ * and produces cost-adjusted rewards so the neural router learns to
+ * prefer cost-efficient tiers.
+ *
+ * @module routing/economic-routing
+ */
+import { CostTracker } from '../shared/llm/cost-tracker.js';
+import type { AgentTier } from './routing-config.js';
+import type { RoutingOutcome } from './types.js';
+/**
+ * Tier cost estimates (per typical QE task, in USD).
+ * Based on average token usage per task type.
+ */
+export declare const TIER_COST_ESTIMATES: Record<AgentTier, {
+    avgInputTokens: number;
+    avgOutputTokens: number;
+    costPerTask: number;
+}>;
+export interface EconomicScore {
+    tier: AgentTier;
+    /** Expected quality (0-1) */
+    qualityScore: number;
+    /** Estimated cost per task in USD */
+    estimatedCostUsd: number;
+    /** quality / cost (higher = more efficient). Infinity for zero-cost tiers. */
+    qualityPerDollar: number;
+    /** Combined score factoring quality + cost (higher = better) */
+    economicScore: number;
+}
+export interface EconomicRoutingConfig {
+    /** Weight for quality in combined score (0-1, default 0.6) */
+    qualityWeight: number;
+    /** Weight for cost efficiency in combined score (0-1, default 0.4) */
+    costWeight: number;
+    /** Budget limit per hour in USD (0 = unlimited) */
+    budgetPerHourUsd: number;
+    /** Budget limit per day in USD (0 = unlimited) */
+    budgetPerDayUsd: number;
+    /** Minimum quality threshold -- never route to cheaper tier below this (0-1) */
+    minQualityThreshold: number;
+    /** Enable economic routing (default: true) */
+    enabled: boolean;
+}
+export declare const DEFAULT_ECONOMIC_CONFIG: EconomicRoutingConfig;
+export interface EconomicReport {
+    tierEfficiency: EconomicScore[];
+    currentHourlyCostUsd: number;
+    currentDailyCostUsd: number;
+    budgetRemaining: {
+        hourly: number | null;
+        daily: number | null;
+    };
+    recommendation: string;
+    savingsOpportunity: {
+        usd: number;
+        description: string;
+    } | null;
+}
+export declare class EconomicRoutingModel {
+    private config;
+    private costTracker;
+    private tierQualityEstimates;
+    private tierOutcomeCounts;
+    constructor(costTracker: CostTracker, config?: Partial<EconomicRoutingConfig>);
+    /**
+     * Score each tier by quality-per-dollar efficiency.
+     * Returns all tiers sorted by economicScore descending.
+     */
+    scoreTiers(taskComplexity: number): EconomicScore[];
+    /**
+     * Select the best tier considering quality AND cost.
+     * Respects budget limits and minimum quality thresholds.
+     */
+    selectTier(taskComplexity: number): {
+        tier: AgentTier;
+        reason: string;
+        scores: EconomicScore[];
+    };
+    /**
+     * Check if a tier would exceed the budget.
+     */
+    wouldExceedBudget(tier: AgentTier): boolean;
+    /**
+     * Update quality estimates from observed outcomes.
+     * Uses EMA to smooth estimates.
+     */
+    updateFromOutcome(outcome: RoutingOutcome, tier: AgentTier): void;
+    /**
+     * Get economic efficiency report.
+     */
+    getEconomicReport(): EconomicReport;
+    /**
+     * Compute cost-adjusted reward for the neural router.
+     * Penalizes expensive tiers that don't deliver proportionally higher quality.
+     */
+    computeCostAdjustedReward(baseReward: number, tier: AgentTier, qualityScore: number): number;
+    /**
+     * Serialize quality estimates for persistence.
+     */
+    serializeEstimates(): Record<string, {
+        quality: number;
+        count: number;
+    }>;
+    /**
+     * Deserialize quality estimates from persistence.
+     */
+    deserializeEstimates(data: Record<string, {
+        quality: number;
+        count: number;
+    }>): void;
+    /**
+     * Get the current config (read-only copy).
+     */
+    getConfig(): Readonly<EconomicRoutingConfig>;
+    /**
+     * Get quality estimate for a tier, adjusted by task complexity.
+     * Higher complexity tasks benefit more from higher-tier models.
+     */
+    private getQualityEstimate;
+    private generateRecommendation;
+}
+//# sourceMappingURL=economic-routing.d.ts.map