byterover-cli 1.7.2 → 2.0.0

package/dist/server/infra/executor/query-executor.d.ts

@@ -1,5 +1,19 @@
 import type { ICipherAgent } from '../../../agent/core/interfaces/i-cipher-agent.js';
+import type { IFileSystem } from '../../../agent/core/interfaces/i-file-system.js';
+import type { ISearchKnowledgeService } from '../../../agent/infra/sandbox/tools-sdk.js';
 import type { IQueryExecutor, QueryExecuteOptions } from '../../core/interfaces/executor/i-query-executor.js';
+/**
+ * Optional dependencies for QueryExecutor.
+ * All fields are optional — without them, the executor falls back to the original behavior.
+ */
+export interface QueryExecutorDeps {
+    /** Enable query result caching (default: false) */
+    enableCache?: boolean;
+    /** File system for reading full document content and computing fingerprints */
+    fileSystem?: IFileSystem;
+    /** Search service for pre-fetching relevant context before calling the LLM */
+    searchService?: ISearchKnowledgeService;
+}
 /**
  * QueryExecutor - Executes query tasks with an injected CipherAgent.
  *
@@ -7,20 +21,69 @@ import type { IQueryExecutor, QueryExecuteOptions } from '../../core/interfaces/
  * It's an Executor that wraps agent.execute() with query-specific options.
  *
  * Architecture:
- * - TaskProcessor injects the long-lived CipherAgent
- * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - AgentProcess injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-process (subscribes to agentEventBus)
  * - Transport handles task lifecycle (task:started, task:completed, task:error)
  * - Executor focuses solely on query execution
  *
- * Uses code_exec with tools.* SDK for programmatic search.
+ * Tiered response strategy (fastest to slowest):
+ * - Tier 0: Exact cache hit (0ms)
+ * - Tier 1: Fuzzy cache match via Jaccard similarity (~50ms)
+ * - Tier 2: Direct search response without LLM (~100-200ms)
+ * - Tier 3: Optimized single LLM call with pre-fetched context (<5s)
+ * - Tier 4: Full agentic loop fallback (8-15s)
  */
 export declare class QueryExecutor implements IQueryExecutor {
+    private static readonly FINGERPRINT_CACHE_TTL_MS;
+    private readonly cache?;
+    private cachedFingerprint?;
+    private readonly fileSystem?;
+    private readonly searchService?;
+    constructor(deps?: QueryExecutorDeps);
     executeWithAgent(agent: ICipherAgent, options: QueryExecuteOptions): Promise<string>;
     /**
-     * Build a streamlined query prompt optimized for fast, accurate responses.
+     * Build pre-fetched context string from search results for LLM prompt injection.
+     * Synchronous — uses already-fetched search results (no additional I/O for excerpts).
+     * Full document reads happen only for high-confidence results.
+     */
+    private buildPrefetchedContext;
+    /**
+     * Build a query prompt using RLM pattern (variable references, not embedded data).
+     *
+     * Search results are pre-loaded into sandbox variables. The prompt references
+     * variable names so the LLM accesses results via code_exec, not via the prompt.
      *
-     * Uses code_exec with tools.* SDK for programmatic search.
-     * Designed to minimize iterations while maintaining answer quality.
+     * @param query - User query
+     * @param options - Prompt options with variable names and metadata
      */
     private buildQueryPrompt;
+    /**
+     * Compute a context tree fingerprint cheaply using file mtimes.
+     * Used for cache invalidation — if any file in the context tree changes,
+     * the fingerprint changes and cached results are invalidated.
+     */
+    private computeContextTreeFingerprint;
+    /**
+     * Extract key entities from a query for supplementary searches.
+     * Simple heuristic: split query, filter stopwords, keep significant terms.
+     */
+    private extractQueryEntities;
+    /**
+     * Run supplementary entity-based searches to improve recall.
+     * Extracts key entities from the query and searches for each independently,
+     * then merges unique results (by path) into the original search result.
+     *
+     * @param query - Original user query
+     * @param searchResult - Initial search result to supplement
+     * @returns Merged search result with additional entity-based matches
+     */
+    private supplementEntitySearches;
+    /**
+     * Attempt to produce a direct response from search results without LLM.
+     * Returns formatted response if high-confidence dominant match found, undefined otherwise.
+     *
+     * Uses higher thresholds than smart routing (score >= 8, 2x dominance)
+     * to ensure only clearly answerable queries bypass the LLM.
+     */
+    private tryDirectSearchResponse;
 }

package/dist/server/infra/executor/query-executor.js

@@ -1,3 +1,13 @@
+import { join } from 'node:path';
+import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../constants.js';
+import { canRespondDirectly, formatDirectResponse, formatNotFoundResponse, } from './direct-search-responder.js';
+import { QueryResultCache } from './query-result-cache.js';
+/** Attribution footer appended to all query responses */
+const ATTRIBUTION_FOOTER = '\n\n---\nSource: ByteRover Knowledge Base';
+/** Minimum normalized score to consider a result high-confidence for pre-fetching */
+const SMART_ROUTING_SCORE_THRESHOLD = 0.7;
+/** Maximum number of documents to pre-fetch and inject into the prompt */
+const SMART_ROUTING_MAX_DOCS = 5;
 /**
  * QueryExecutor - Executes query tasks with an injected CipherAgent.
  *
@@ -5,45 +15,326 @@
  * It's an Executor that wraps agent.execute() with query-specific options.
  *
  * Architecture:
- * - TaskProcessor injects the long-lived CipherAgent
- * - Event streaming is handled by agent-worker (subscribes to agentEventBus)
+ * - AgentProcess injects the long-lived CipherAgent
+ * - Event streaming is handled by agent-process (subscribes to agentEventBus)
  * - Transport handles task lifecycle (task:started, task:completed, task:error)
  * - Executor focuses solely on query execution
  *
- * Uses code_exec with tools.* SDK for programmatic search.
+ * Tiered response strategy (fastest to slowest):
+ * - Tier 0: Exact cache hit (0ms)
+ * - Tier 1: Fuzzy cache match via Jaccard similarity (~50ms)
+ * - Tier 2: Direct search response without LLM (~100-200ms)
+ * - Tier 3: Optimized single LLM call with pre-fetched context (<5s)
+ * - Tier 4: Full agentic loop fallback (8-15s)
  */
 export class QueryExecutor {
+    static FINGERPRINT_CACHE_TTL_MS = 30_000;
+    cache;
+    cachedFingerprint;
+    fileSystem;
+    searchService;
+    constructor(deps) {
+        this.fileSystem = deps?.fileSystem;
+        this.searchService = deps?.searchService;
+        if (deps?.enableCache) {
+            this.cache = new QueryResultCache();
+        }
+    }
     async executeWithAgent(agent, options) {
         const { query, taskId } = options;
-        // Execute with query commandType
-        // Agent uses its default session (created during start())
-        // Task lifecycle is managed by Transport (task:started, task:completed, task:error)
-        const prompt = this.buildQueryPrompt(query);
-        const response = await agent.execute(prompt, {
-            executionContext: { commandType: 'query' },
-            taskId,
+        // Start search early — runs in parallel with fingerprint computation (independent operations)
+        const searchPromise = this.searchService?.search(query, { limit: SMART_ROUTING_MAX_DOCS });
+        // Prevent unhandled rejection if we return early (cache hit) while search is still pending
+        searchPromise?.catch(() => { });
+        // === Tier 0: Exact cache hit (0ms) ===
+        let fingerprint;
+        if (this.cache && this.fileSystem) {
+            fingerprint = await this.computeContextTreeFingerprint();
+            const cached = this.cache.get(query, fingerprint);
+            if (cached) {
+                return cached + ATTRIBUTION_FOOTER;
+            }
+        }
+        // === Tier 1: Fuzzy cache match (~50ms) ===
+        if (this.cache && fingerprint) {
+            const fuzzyHit = this.cache.findSimilar(query, fingerprint);
+            if (fuzzyHit) {
+                return fuzzyHit + ATTRIBUTION_FOOTER;
+            }
+        }
+        // Await search result (already started in parallel with fingerprint computation)
+        let searchResult;
+        try {
+            searchResult = await searchPromise;
+        }
+        catch {
+            // Search failed, proceed without pre-fetched context
+        }
+        // Supplementary entity-based searches for better multi-session recall
+        if (this.searchService && searchResult && searchResult.totalFound < 3) {
+            searchResult = await this.supplementEntitySearches(query, searchResult);
+        }
+        // === OOD short-circuit: no results means topic not covered ===
+        if (searchResult && searchResult.results.length === 0) {
+            const response = formatNotFoundResponse(query);
+            if (this.cache && fingerprint) {
+                this.cache.set(query, response, fingerprint);
+            }
+            return response + ATTRIBUTION_FOOTER;
+        }
+        // === Tier 2: Direct search response (~100-200ms) ===
+        if (searchResult && this.fileSystem) {
+            const directResult = await this.tryDirectSearchResponse(query, searchResult);
+            if (directResult) {
+                if (this.cache && fingerprint) {
+                    this.cache.set(query, directResult, fingerprint);
+                }
+                return directResult + ATTRIBUTION_FOOTER;
+            }
+        }
+        // === Tier 3/4: LLM call with RLM pattern (variable-based search results) ===
+        let prefetchedContext;
+        if (searchResult && this.fileSystem) {
+            prefetchedContext = this.buildPrefetchedContext(searchResult);
+        }
+        // Create per-task session for parallel isolation (own sandbox + history + LLM service)
+        const taskSessionId = await agent.createTaskSession(taskId, 'query');
+        // Task-scoped variable names for sandbox injection (RLM pattern).
+        // Replace hyphens with underscores: UUIDs have hyphens which are invalid in JS identifiers,
+        // so the LLM uses underscores when writing code-exec calls — matching curate-executor pattern.
+        const taskIdSafe = taskId.replaceAll('-', '_');
+        const resultsVar = `__query_results_${taskIdSafe}`;
+        const metaVar = `__query_meta_${taskIdSafe}`;
+        // Compute metadata for LLM guidance
+        const metadata = {
+            hasPreFetched: Boolean(prefetchedContext),
+            resultCount: searchResult?.results.length ?? 0,
+            topScore: searchResult?.results[0]?.score ?? 0,
+            totalFound: searchResult?.totalFound ?? 0,
+        };
+        // Inject search results + metadata into the TASK session's sandbox
+        agent.setSandboxVariableOnSession(taskSessionId, resultsVar, searchResult?.results ?? []);
+        agent.setSandboxVariableOnSession(taskSessionId, metaVar, metadata);
+        const prompt = this.buildQueryPrompt(query, {
+            metadata,
+            metaVar,
+            prefetchedContext,
+            resultsVar,
         });
-        return response;
+        // Query-optimized LLM overrides: tokens and lower temperature
+        const queryOverrides = prefetchedContext
+            ? { maxIterations: 50, maxTokens: 1024, temperature: 0.3 }
+            : { maxIterations: 50, maxTokens: 2048, temperature: 0.5 };
+        try {
+            const response = await agent.executeOnSession(taskSessionId, prompt, {
+                executionContext: { commandType: 'query', ...queryOverrides },
+                taskId,
+            });
+            // Store in cache for future Tier 0/1 hits
+            if (this.cache && fingerprint) {
+                this.cache.set(query, response, fingerprint);
+            }
+            return response + ATTRIBUTION_FOOTER;
+        }
+        finally {
+            // Clean up entire task session (sandbox + history) in one call
+            await agent.deleteTaskSession(taskSessionId);
+        }
     }
     /**
-     * Build a streamlined query prompt optimized for fast, accurate responses.
+     * Build pre-fetched context string from search results for LLM prompt injection.
+     * Synchronous — uses already-fetched search results (no additional I/O for excerpts).
+     * Full document reads happen only for high-confidence results.
+     */
+    buildPrefetchedContext(searchResult) {
+        if (searchResult.totalFound === 0)
+            return undefined;
+        const highConfidenceResults = searchResult.results.filter((r) => r.score >= SMART_ROUTING_SCORE_THRESHOLD);
+        if (highConfidenceResults.length === 0)
+            return undefined;
+        const sections = highConfidenceResults.map((r) => `### ${r.title}\n**Source**: .brv/context-tree/${r.path}\n\n${r.excerpt}`);
+        return sections.join('\n\n---\n\n');
+    }
+    /**
+     * Build a query prompt using RLM pattern (variable references, not embedded data).
+     *
+     * Search results are pre-loaded into sandbox variables. The prompt references
+     * variable names so the LLM accesses results via code_exec, not via the prompt.
      *
-     * Uses code_exec with tools.* SDK for programmatic search.
-     * Designed to minimize iterations while maintaining answer quality.
+     * @param query - User query
+     * @param options - Prompt options with variable names and metadata
      */
-    buildQueryPrompt(query) {
+    buildQueryPrompt(query, options) {
+        const { metadata, metaVar, prefetchedContext, resultsVar } = options;
+        const groundingRules = `### Grounding Rules (CRITICAL)
+- ONLY use information from the curated knowledge base (.brv/context-tree/)
+- If no relevant knowledge is found, respond: "This topic is not covered in the knowledge base."
+- Do NOT extrapolate, infer, or generate information beyond what is explicitly stated in sources
+- Every claim MUST be traceable to a specific source file
+- When uncertain, say "Based on available knowledge..." and note the limitation`;
+        const responseFormat = `### Response Format
+- **Summary**: Direct answer (2-3 sentences)
+- **Details**: Key findings with explanations
+- **Sources**: File paths from .brv/context-tree/
+- **Gaps**: Note any aspects not covered`;
+        if (prefetchedContext) {
+            return `## User Query
+${query}
+
+## Pre-fetched Context
+The following relevant knowledge was found in the context tree:
+
+${prefetchedContext}
+
+## Search Results Variable
+Additional search results: \`${resultsVar}\` (${metadata.resultCount} results, top score: ${metadata.topScore.toFixed(2)})
+Metadata: \`${metaVar}\`
+
+## Instructions
+
+Answer the user's question using the pre-fetched context above.
+If the pre-fetched context does not directly address the user's query topic, respond that the topic is not covered in the knowledge base. Do not attempt to answer from tangentially related content.
+If the context is insufficient but relevant, use \`code_exec\` with \`silent: true\` to read additional documents from the search results variable. Use \`setFinalResult(answer)\` when done.
+
+${groundingRules}
+
+${responseFormat}`;
+        }
         return `## User Query
 ${query}
 
+## Search Results Variable
+Search results: \`${resultsVar}\` (${metadata.resultCount} results, top score: ${metadata.topScore.toFixed(2)})
+Metadata: \`${metaVar}\`
+
 ## Instructions
 
-Search the context tree (.brv/context-tree/) to answer this question.
-Use \`code_exec\` to run a programmatic search with the \`tools.*\` SDK.
+Use \`code_exec\` to examine the search results in \`${resultsVar}\`, read relevant documents with \`tools.readFile()\`, and synthesize an answer.
+Use \`silent: true\` for data-loading code_exec calls. Use \`setFinalResult(answer)\` to return the final answer immediately.
 
-### Response Format
-- **Summary**: Direct answer (2-3 sentences)
-- **Details**: Key findings with explanations
-- **Sources**: File paths from .brv/context-tree/
-- **Gaps**: Note any aspects not covered`;
+${groundingRules}
+
+${responseFormat}`;
+    }
+    /**
+     * Compute a context tree fingerprint cheaply using file mtimes.
+     * Used for cache invalidation — if any file in the context tree changes,
+     * the fingerprint changes and cached results are invalidated.
+     */
+    async computeContextTreeFingerprint() {
+        // Fast path: return cached fingerprint if still valid (avoids globFiles I/O)
+        if (this.cachedFingerprint && Date.now() < this.cachedFingerprint.expiresAt) {
+            return this.cachedFingerprint.value;
+        }
+        try {
+            const contextTreePath = join(BRV_DIR, CONTEXT_TREE_DIR);
+            const globResult = await this.fileSystem.globFiles(`**/*${CONTEXT_FILE_EXTENSION}`, {
+                cwd: contextTreePath,
+                includeMetadata: true,
+                maxResults: 10_000,
+                respectGitignore: false,
+            });
+            const files = globResult.files.map((f) => ({
+                mtime: f.modified?.getTime() ?? 0,
+                path: f.path,
+            }));
+            const fingerprint = QueryResultCache.computeFingerprint(files);
+            this.cachedFingerprint = {
+                expiresAt: Date.now() + QueryExecutor.FINGERPRINT_CACHE_TTL_MS,
+                value: fingerprint,
+            };
+            return fingerprint;
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /**
+     * Extract key entities from a query for supplementary searches.
+     * Simple heuristic: split query, filter stopwords, keep significant terms.
+     */
+    extractQueryEntities(query) {
+        const stopwords = new Set([
+            'a', 'about', 'an', 'and', 'by', 'did', 'do', 'does', 'for', 'from',
+            'how', 'in', 'is', 'my', 'of', 'or', 'our', 'that', 'the', 'their',
+            'this', 'to', 'was', 'were', 'what', 'when', 'where', 'which', 'who', 'with',
+        ]);
+        const words = query.toLowerCase().split(/\s+/);
+        return words.filter((w) => w.length >= 3 && !stopwords.has(w));
+    }
+    /**
+     * Run supplementary entity-based searches to improve recall.
+     * Extracts key entities from the query and searches for each independently,
+     * then merges unique results (by path) into the original search result.
+     *
+     * @param query - Original user query
+     * @param searchResult - Initial search result to supplement
+     * @returns Merged search result with additional entity-based matches
+     */
+    async supplementEntitySearches(query, searchResult) {
+        const entities = this.extractQueryEntities(query);
+        if (entities.length <= 1)
+            return searchResult;
+        try {
+            const entitySearches = await Promise.allSettled(entities.slice(0, 3).map((entity) => this.searchService.search(entity, { limit: 3 })));
+            // Collect existing paths to deduplicate
+            const existingPaths = new Set(searchResult.results.map((r) => r.path));
+            const supplementary = [];
+            for (const settled of entitySearches) {
+                if (settled.status === 'fulfilled' && settled.value.results) {
+                    for (const result of settled.value.results) {
+                        if (!existingPaths.has(result.path)) {
+                            existingPaths.add(result.path);
+                            supplementary.push(result);
+                        }
+                    }
+                }
+            }
+            if (supplementary.length === 0)
+                return searchResult;
+            return {
+                ...searchResult,
+                results: [...searchResult.results, ...supplementary],
+                totalFound: searchResult.totalFound + supplementary.length,
+            };
+        }
+        catch {
+            return searchResult;
+        }
+    }
+    /**
+     * Attempt to produce a direct response from search results without LLM.
+     * Returns formatted response if high-confidence dominant match found, undefined otherwise.
+     *
+     * Uses higher thresholds than smart routing (score >= 8, 2x dominance)
+     * to ensure only clearly answerable queries bypass the LLM.
+     */
+    async tryDirectSearchResponse(query, searchResult) {
+        try {
+            if (searchResult.totalFound === 0)
+                return undefined;
+            // Build full results with content
+            const fullResults = await Promise.all(searchResult.results
+                .filter((r) => r.score >= SMART_ROUTING_SCORE_THRESHOLD)
+                .slice(0, SMART_ROUTING_MAX_DOCS)
+                .map(async (result) => {
+                let content = result.excerpt;
+                try {
+                    const ctPath = join(BRV_DIR, CONTEXT_TREE_DIR, result.path);
+                    const { content: fullContent } = await this.fileSystem.readFile(ctPath);
+                    content = fullContent;
+                }
+                catch {
+                    // Use excerpt if full read fails
+                }
+                return { content, path: result.path, score: result.score, title: result.title };
+            }));
+            if (!canRespondDirectly(fullResults))
+                return undefined;
+            return formatDirectResponse(query, fullResults);
+        }
+        catch {
+            return undefined;
+        }
     }
 }

package/dist/server/infra/executor/query-result-cache.d.ts

@@ -0,0 +1,87 @@
+import { type QueryTokens } from './query-similarity.js';
+/**
+ * Cached query result entry.
+ */
+export interface QueryCacheEntry {
+    /** Cached response content */
+    content: string;
+    /** Context tree fingerprint at cache time */
+    fingerprint: string;
+    /** Timestamp when cached */
+    storedAt: number;
+    /** Pre-computed tokens for fuzzy similarity matching */
+    tokens: QueryTokens;
+}
+/**
+ * Configuration for QueryResultCache.
+ */
+export interface QueryResultCacheOptions {
+    /** Maximum number of entries (default: 50) */
+    maxSize?: number;
+    /** TTL in milliseconds (default: 60000) */
+    ttlMs?: number;
+}
+/**
+ * In-memory LRU cache for query results with TTL and context tree fingerprint validation.
+ *
+ * Follows the same pattern as PromptCache (src/agent/infra/system-prompt/prompt-cache.ts):
+ * - Map-based storage with configurable max size
+ * - LRU eviction when at capacity
+ * - TTL-based expiration
+ * - Fingerprint-based invalidation when the context tree changes
+ * - Fuzzy matching for semantically similar queries via Jaccard similarity
+ */
+export declare class QueryResultCache {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(options?: QueryResultCacheOptions);
+    /**
+     * Compute a context tree fingerprint from file mtimes.
+     * Uses sorted paths + mtimes to create a deterministic hash.
+     * If any file changes (added, removed, modified), the fingerprint changes.
+     *
+     * @param files - Array of file paths with modification times
+     * @returns 16-character hex fingerprint
+     */
+    static computeFingerprint(files: Array<{
+        mtime: number;
+        path: string;
+    }>): string;
+    /** Clear all entries. */
+    clear(): void;
+    /**
+     * Find a cached result by fuzzy similarity.
+     * Returns the highest-similarity match above threshold, or undefined.
+     * Called after exact-match `get()` fails.
+     *
+     * @param query - User query string
+     * @param currentFingerprint - Current context tree fingerprint
+     * @returns Cached response content or undefined
+     */
+    findSimilar(query: string, currentFingerprint: string): string | undefined;
+    /**
+     * Get a cached result if valid.
+     * Returns undefined if entry doesn't exist, TTL expired, or fingerprint mismatch.
+     *
+     * @param query - User query string
+     * @param currentFingerprint - Current context tree fingerprint
+     * @returns Cached response content or undefined
+     */
+    get(query: string, currentFingerprint: string): string | undefined;
+    /** Get cache statistics. */
+    getStats(): {
+        maxSize: number;
+        size: number;
+    };
+    /**
+     * Store a result in the cache.
+     *
+     * @param query - User query string
+     * @param content - Response content to cache
+     * @param fingerprint - Context tree fingerprint at cache time
+     */
+    set(query: string, content: string, fingerprint: string): void;
+    /** Normalize query for cache key consistency. */
+    private normalizeQuery;
+}

package/dist/server/infra/executor/query-result-cache.js

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { FUZZY_SIMILARITY_THRESHOLD, jaccardSimilarity, tokenizeQuery } from './query-similarity.js';
+/**
+ * In-memory LRU cache for query results with TTL and context tree fingerprint validation.
+ *
+ * Follows the same pattern as PromptCache (src/agent/infra/system-prompt/prompt-cache.ts):
+ * - Map-based storage with configurable max size
+ * - LRU eviction when at capacity
+ * - TTL-based expiration
+ * - Fingerprint-based invalidation when the context tree changes
+ * - Fuzzy matching for semantically similar queries via Jaccard similarity
+ */
+export class QueryResultCache {
+    cache = new Map();
+    maxSize;
+    ttlMs;
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? 50;
+        this.ttlMs = options.ttlMs ?? 60_000;
+    }
+    /**
+     * Compute a context tree fingerprint from file mtimes.
+     * Uses sorted paths + mtimes to create a deterministic hash.
+     * If any file changes (added, removed, modified), the fingerprint changes.
+     *
+     * @param files - Array of file paths with modification times
+     * @returns 16-character hex fingerprint
+     */
+    static computeFingerprint(files) {
+        if (files.length === 0)
+            return 'empty';
+        const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+        const data = sorted.map((f) => `${f.path}:${f.mtime}`).join('|');
+        return createHash('md5').update(data).digest('hex').slice(0, 16);
+    }
+    /** Clear all entries. */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Find a cached result by fuzzy similarity.
+     * Returns the highest-similarity match above threshold, or undefined.
+     * Called after exact-match `get()` fails.
+     *
+     * @param query - User query string
+     * @param currentFingerprint - Current context tree fingerprint
+     * @returns Cached response content or undefined
+     */
+    findSimilar(query, currentFingerprint) {
+        const queryTokens = tokenizeQuery(query);
+        // Skip fuzzy matching if query has very few meaningful tokens
+        if (queryTokens.tokenSet.size < 2)
+            return undefined;
+        let bestMatch;
+        for (const [, entry] of this.cache) {
+            // Check fingerprint + TTL first (cheap filters)
+            if (entry.fingerprint !== currentFingerprint)
+                continue;
+            if (Date.now() - entry.storedAt > this.ttlMs)
+                continue;
+            const similarity = jaccardSimilarity(queryTokens.tokenSet, entry.tokens.tokenSet);
+            if (similarity >= FUZZY_SIMILARITY_THRESHOLD && (!bestMatch || similarity > bestMatch.similarity)) {
+                bestMatch = { content: entry.content, similarity };
+            }
+        }
+        return bestMatch?.content;
+    }
+    /**
+     * Get a cached result if valid.
+     * Returns undefined if entry doesn't exist, TTL expired, or fingerprint mismatch.
+     *
+     * @param query - User query string
+     * @param currentFingerprint - Current context tree fingerprint
+     * @returns Cached response content or undefined
+     */
+    get(query, currentFingerprint) {
+        const key = this.normalizeQuery(query);
+        const entry = this.cache.get(key);
+        if (!entry)
+            return undefined;
+        // Check TTL
+        if (Date.now() - entry.storedAt > this.ttlMs) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Check fingerprint (context tree changed?)
+        if (entry.fingerprint !== currentFingerprint) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        return entry.content;
+    }
+    /** Get cache statistics. */
+    getStats() {
+        return {
+            maxSize: this.maxSize,
+            size: this.cache.size,
+        };
+    }
+    /**
+     * Store a result in the cache.
+     *
+     * @param query - User query string
+     * @param content - Response content to cache
+     * @param fingerprint - Context tree fingerprint at cache time
+     */
+    set(query, content, fingerprint) {
+        const key = this.normalizeQuery(query);
+        const tokens = tokenizeQuery(query);
+        // Evict oldest entry if at capacity
+        if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey)
+                this.cache.delete(oldestKey);
+        }
+        this.cache.set(key, {
+            content,
+            fingerprint,
+            storedAt: Date.now(),
+            tokens,
+        });
+    }
+    /** Normalize query for cache key consistency. */
+    normalizeQuery(query) {
+        return query.toLowerCase().trim().replaceAll(/\s+/g, ' ');
+    }
+}