@framers/agentos 0.1.120 → 0.1.121

package/dist/query-router/QueryRouter.js

@@ -29,13 +29,14 @@
  * router falls back gracefully to {@link KeywordFallback} for all retrieval.
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join, extname } from 'node:path';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { QueryClassifier } from './QueryClassifier.js';
 import { QueryDispatcher } from './QueryDispatcher.js';
 import { QueryGenerator } from './QueryGenerator.js';
 import { TopicExtractor } from './TopicExtractor.js';
 import { KeywordFallback } from './KeywordFallback.js';
-import { DEFAULT_QUERY_ROUTER_CONFIG } from './types.js';
+import { DEFAULT_QUERY_ROUTER_CONFIG, DEFAULT_STRATEGY_CONFIG, } from './types.js';
 /** Regex for splitting markdown by h1-h3 headings. */
 const HEADING_REGEX = /^#{1,3}\s+(.+)/;
 /** Maximum character length for a single corpus chunk. */
@@ -44,6 +45,11 @@ const MAX_CHUNK_CHARS = 6000;
 const MIN_CHUNK_CHARS = 20;
 /** Supported markdown file extensions for corpus loading. */
 const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const GITHUB_EXTENSION_LOCAL_ENTRY_CANDIDATES = [
+    resolve(MODULE_DIR, '../../../../packages/agentos-extensions/registry/curated/integrations/github/dist/index.js'),
+    resolve(MODULE_DIR, '../../../../apps/wunderland-sol/packages/agentos-extensions/registry/curated/integrations/github/dist/index.js'),
+];
 // ============================================================================
 // QueryRouter
 // ============================================================================
@@ -102,6 +108,19 @@ export class QueryRouter {
         this.providerManager = null;
         /** Embedding dimension for the configured model. Zero if embeddings unavailable. */
         this.embeddingDimension = 0;
+        /** Current embedding availability state for corpus retrieval. */
+        this.embeddingStatus = 'disabled-no-key';
+        /**
+         * Optional UnifiedRetriever for plan-based retrieval.
+         *
+         * When set via {@link setUnifiedRetriever}, the `route()` method uses
+         * the UnifiedRetriever instead of the legacy QueryDispatcher for the
+         * retrieval phase. The UnifiedRetriever executes a structured
+         * {@link RetrievalPlan} across all available sources in parallel.
+         *
+         * @see setUnifiedRetriever
+         */
+        this.unifiedRetriever = null;
         /**
          * The data source ID used for corpus embeddings in the vector store.
          * Matches the collection name configured during init().
@@ -112,9 +131,77 @@ export class QueryRouter {
             ...config,
             deepResearchEnabled: config.deepResearchEnabled ?? Boolean(process.env.SERPER_API_KEY),
             availableTools: config.availableTools ?? [...DEFAULT_QUERY_ROUTER_CONFIG.availableTools],
+            strategyConfig: {
+                ...DEFAULT_STRATEGY_CONFIG,
+                ...config.strategyConfig,
+            },
         };
     }
     // ==========================================================================
+    // UNIFIED RETRIEVER INTEGRATION
+    // ==========================================================================
+    /**
+     * Attach a {@link UnifiedRetriever} for plan-based retrieval.
+     *
+     * When set, the `route()` method uses the UnifiedRetriever instead of
+     * the legacy QueryDispatcher for the retrieval phase. The classifier
+     * automatically produces a {@link RetrievalPlan} via `classifyWithPlan()`
+     * and the retriever executes it across all available sources in parallel.
+     *
+     * Pass `null` to revert to the legacy QueryDispatcher pipeline.
+     *
+     * @param retriever - A configured UnifiedRetriever instance, or `null` to disable.
+     *
+     * @example
+     * ```typescript
+     * const retriever = new UnifiedRetriever({
+     *   hybridSearcher, raptorTree, graphEngine, memoryManager,
+     * });
+     * router.setUnifiedRetriever(retriever);
+     * // Now route() uses plan-based retrieval automatically
+     * ```
+     */
+    setUnifiedRetriever(retriever) {
+        this.unifiedRetriever = retriever;
+    }
+    /**
+     * Get the attached UnifiedRetriever, or `null` if not configured.
+     *
+     * @returns The UnifiedRetriever instance, or `null`.
+     */
+    getUnifiedRetriever() {
+        return this.unifiedRetriever;
+    }
+    // ==========================================================================
+    // CAPABILITY DISCOVERY INTEGRATION
+    // ==========================================================================
+    /**
+     * Attach a {@link CapabilityDiscoveryEngine} for capability-aware classification.
+     *
+     * When set, the classifier injects Tier 0 capability summaries (~150 tokens)
+     * into its LLM prompt, enabling it to recommend which skills, tools, and
+     * extensions should be activated for each query. The recommendations are
+     * included in the {@link ExecutionPlan} returned by `classifyWithPlan()`.
+     *
+     * Pass `null` to detach and revert to keyword-based heuristic capability
+     * selection.
+     *
+     * @param engine - A configured and initialized CapabilityDiscoveryEngine, or `null` to detach.
+     *
+     * @example
+     * ```typescript
+     * const engine = new CapabilityDiscoveryEngine(embeddingManager, vectorStore);
+     * await engine.initialize({ tools, skills, extensions, channels });
+     * router.setCapabilityDiscoveryEngine(engine);
+     * // Now route() includes skill/tool/extension recommendations in the execution plan
+     * ```
+     */
+    setCapabilityDiscoveryEngine(engine) {
+        if (this.classifier) {
+            this.classifier.setCapabilityDiscoveryEngine(engine);
+        }
+    }
+    // ==========================================================================
     // PUBLIC API
     // ==========================================================================
     /**
@@ -132,6 +219,9 @@ export class QueryRouter {
     async init() {
         // 1. Load corpus chunks from the configured knowledge directories
         this.corpus = this.loadCorpus(this.config.knowledgeCorpus);
+        if (this.corpus.length === 0) {
+            throw new Error(this.buildEmptyCorpusError(this.config.knowledgeCorpus));
+        }
         // 2. Extract topics for the classifier's system prompt
         const topicExtractor = new TopicExtractor();
         this.topics = topicExtractor.extract(this.corpus);
@@ -143,36 +233,125 @@ export class QueryRouter {
         //    fallback will still work for all retrieval operations.
         await this.embedCorpus();
         // 5. Instantiate the classifier
-        this.classifier = new QueryClassifier({
-            model: this.config.classifierModel,
-            provider: this.config.classifierProvider,
-            confidenceThreshold: this.config.confidenceThreshold,
-            maxTier: this.config.maxTier,
-            topicList,
-            toolList: this.formatToolList(this.config.availableTools),
-            apiKey: this.config.apiKey,
-            baseUrl: this.config.baseUrl,
-        });
+        this.classifier = this.createClassifier(topicList);
         // 6. Instantiate the generator
         this.generator = new QueryGenerator({
             model: this.config.generationModel,
             modelDeep: this.config.generationModelDeep,
             provider: this.config.generationProvider,
-            apiKey: this.config.apiKey,
-            baseUrl: this.config.baseUrl,
+            apiKey: this.getLlmApiKey(),
+            baseUrl: this.getLlmBaseUrl(),
             maxContextTokens: this.config.maxContextTokens,
         });
         // 7. Instantiate the dispatcher with callback dependencies
         this.dispatcher = new QueryDispatcher({
             vectorSearch: (query, topK) => this.vectorSearch(query, topK),
-            graphExpand: (seeds) => this.graphExpand(seeds),
-            rerank: (query, chunks, topN) => this.rerank(query, chunks, topN),
-            deepResearch: (query, sources) => this.deepResearch(query, sources),
+            hydeSearch: (query, topK) => this.hydeSearch(query, topK),
+            decompose: (query, maxSubQueries) => this.decomposeQuery(query, maxSubQueries),
+            graphExpand: (seeds) => this.config.graphExpand ? this.config.graphExpand(seeds) : this.graphExpand(seeds),
+            rerank: (query, chunks, topN) => this.config.rerank
+                ? this.config.rerank(query, chunks, topN)
+                : this.rerank(query, chunks, topN),
+            deepResearch: (query, sources) => this.config.deepResearch
+                ? this.config.deepResearch(query, sources)
+                : this.deepResearch(query, sources),
             emit: (event) => this.emit(event),
             graphEnabled: this.config.graphEnabled,
             deepResearchEnabled: this.config.deepResearchEnabled,
+            maxSubQueries: this.config.strategyConfig.maxSubQueries,
         });
         this.initialized = true;
+        // ----------------------------------------------------------------
+        // Background GitHub repo indexing (non-blocking)
+        // ----------------------------------------------------------------
+        // Runs after the router is fully initialized so that query routing
+        // is available immediately. Indexed chunks are merged into the
+        // corpus, then the live retrieval/classification state is refreshed
+        // once indexing completes.
+        const repoConfig = this.config.githubRepos ?? {};
+        const includeEcosystem = repoConfig.includeEcosystem ?? true;
+        if (includeEcosystem || (repoConfig.repos && repoConfig.repos.length > 0)) {
+            Promise.resolve().then(async () => {
+                try {
+                    const { GitHubRepoIndexer, GitHubService } = await this.loadGitHubExtensionModule();
+                    const indexedChunks = [];
+                    const token = repoConfig.token || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
+                    const service = new GitHubService(token);
+                    // initialize() creates the Octokit and validates auth.
+                    // If the token is empty/invalid, Octokit is still created before
+                    // the auth check throws, so public-only API access still works.
+                    try {
+                        await service.initialize();
+                    }
+                    catch { /* public-only mode */ }
+                    const indexer = new GitHubRepoIndexer(service);
+                    if (includeEcosystem) {
+                        const results = await indexer.indexEcosystem();
+                        const totalChunks = results.reduce((s, r) => s + r.chunks.length, 0);
+                        for (const result of results) {
+                            indexedChunks.push(...result.chunks);
+                            this.emit({
+                                type: 'github:index:complete',
+                                repo: result.repo,
+                                chunksTotal: result.chunks.length,
+                                durationMs: result.durationMs,
+                                timestamp: Date.now(),
+                            });
+                        }
+                        console.log(`[QueryRouter] GitHub ecosystem indexed: ${results.length} repos, ${totalChunks} chunks`);
+                    }
+                    if (repoConfig.repos?.length) {
+                        for (const { owner, repo } of repoConfig.repos) {
+                            try {
+                                const result = await indexer.indexRepo(owner, repo);
+                                indexedChunks.push(...result.chunks);
+                                this.emit({
+                                    type: 'github:index:complete',
+                                    repo: result.repo,
+                                    chunksTotal: result.chunks.length,
+                                    durationMs: result.durationMs,
+                                    timestamp: Date.now(),
+                                });
+                            }
+                            catch (err) {
+                                this.emit({
+                                    type: 'github:index:error',
+                                    repo: `${owner}/${repo}`,
+                                    error: err instanceof Error ? err.message : String(err),
+                                    timestamp: Date.now(),
+                                });
+                            }
+                        }
+                    }
+                    await this.syncIndexedCorpusChunks(indexedChunks);
+                }
+                catch (err) {
+                    console.warn(`[QueryRouter] GitHub indexing failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            });
+        }
+    }
+    async loadGitHubExtensionModule() {
+        const specifiers = [
+            '@framers/agentos-ext-github',
+            ...GITHUB_EXTENSION_LOCAL_ENTRY_CANDIDATES
+                .filter((candidate) => existsSync(candidate))
+                .map((candidate) => pathToFileURL(candidate).href),
+        ];
+        const failures = [];
+        for (const specifier of specifiers) {
+            try {
+                const module = (await import(/* @vite-ignore */ specifier));
+                if (module.GitHubRepoIndexer && module.GitHubService) {
+                    return module;
+                }
+                failures.push(`${specifier} loaded without GitHubRepoIndexer/GitHubService exports`);
+            }
+            catch (error) {
+                failures.push(`${specifier}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new Error(`Unable to load GitHub extension runtime for QueryRouter indexing. ${failures.join(' | ')}`);
     }
     /**
      * Classify a query into a complexity tier without dispatching or generating.
@@ -248,9 +427,48 @@ export class QueryRouter {
         if (this.config.onClassification) {
             this.config.onClassification(classification);
         }
-        // --- Phase 2: Retrieval ---
+        // --- Phase 2: Retrieval (with capability recommendations) ---
+        // When a UnifiedRetriever is attached, use plan-based retrieval with
+        // full ExecutionPlan (including skill/tool/extension recommendations).
+        // Otherwise fall back to the legacy QueryDispatcher pipeline.
         const retrievalEventStart = this.events.length;
-        const retrieval = await this.dispatcher.dispatch(query, classification.tier, classification.suggestedSources);
+        let retrieval;
+        if (this.unifiedRetriever && this.classifier) {
+            // Plan-based retrieval via UnifiedRetriever
+            const { buildDefaultExecutionPlan } = await import('../rag/unified/types.js');
+            let plan;
+            try {
+                const [, classifiedPlan] = await this.classifier.classifyWithPlan(query, conversationHistory);
+                plan = classifiedPlan;
+            }
+            catch {
+                plan = buildDefaultExecutionPlan(classification.strategy);
+            }
+            // Emit capabilities:activate event when the plan recommends capabilities.
+            // The agent runtime is responsible for deciding which to honor — the
+            // router only recommends, it does not activate.
+            if (plan.skills.length > 0 || plan.tools.length > 0 || plan.extensions.length > 0) {
+                this.emit({
+                    type: 'capabilities:activate',
+                    skills: plan.skills,
+                    tools: plan.tools,
+                    extensions: plan.extensions,
+                    timestamp: Date.now(),
+                });
+            }
+            const unifiedResult = await this.unifiedRetriever.retrieve(query, plan);
+            retrieval = {
+                chunks: unifiedResult.chunks,
+                researchSynthesis: unifiedResult.researchSynthesis,
+                durationMs: unifiedResult.durationMs,
+            };
+        }
+        else {
+            // Legacy dispatcher pipeline (HyDE-aware strategy or tier-based)
+            retrieval = classification.strategy
+                ? await this.dispatcher.dispatchByStrategy(query, classification.strategy, classification.suggestedSources)
+                : await this.dispatcher.dispatch(query, classification.tier, classification.suggestedSources);
+        }
         const retrievalEvents = this.events.slice(retrievalEventStart);
         const fallbacksUsed = this.collectFallbacks(classification, retrievalEvents);
         const tiersUsed = this.collectTiersUsed(classification, fallbacksUsed);
@@ -285,6 +503,7 @@ export class QueryRouter {
             answer: generateResult.answer,
             classification,
             sources,
+            researchSynthesis: retrieval.researchSynthesis,
             durationMs: totalDuration,
             tiersUsed,
             fallbacksUsed,
@@ -329,6 +548,7 @@ export class QueryRouter {
         this.vectorStoreManager = null;
         this.providerManager = null;
         this.embeddingDimension = 0;
+        this.embeddingStatus = 'disabled-no-key';
         this.classifier = null;
         this.dispatcher = null;
         this.generator = null;
@@ -338,6 +558,45 @@ export class QueryRouter {
         this.events = [];
         this.initialized = false;
     }
+    /**
+     * Return lightweight corpus/index stats for observability and host startup
+     * logs.
+     *
+     * Useful after {@link init} so callers can confirm the router loaded a real
+     * corpus instead of only knowing that initialisation completed.
+     */
+    getCorpusStats() {
+        const vectorActive = Boolean(this.embeddingManager && this.vectorStoreManager);
+        const graphRuntimeMode = this.config.graphEnabled
+            ? (this.hasLiveGraphRuntime() ? 'active' : this.hasHeuristicGraphRuntime() ? 'heuristic' : 'placeholder')
+            : 'disabled';
+        const deepResearchRuntimeMode = this.config.deepResearchEnabled
+            ? (this.hasLiveDeepResearchRuntime()
+                ? 'active'
+                : this.hasHeuristicDeepResearchRuntime()
+                    ? 'heuristic'
+                    : 'placeholder')
+            : 'disabled';
+        return {
+            initialized: this.initialized,
+            configuredPathCount: this.config.knowledgeCorpus.length,
+            chunkCount: this.corpus.length,
+            topicCount: this.topics.length,
+            sourceCount: new Set(this.corpus.map((chunk) => chunk.sourcePath)).size,
+            retrievalMode: vectorActive ? 'vector+keyword-fallback' : 'keyword-only',
+            embeddingStatus: vectorActive ? 'active' : this.embeddingStatus,
+            embeddingDimension: vectorActive ? this.embeddingDimension : 0,
+            graphEnabled: this.config.graphEnabled,
+            deepResearchEnabled: this.config.deepResearchEnabled,
+            graphRuntimeMode,
+            rerankRuntimeMode: this.hasLiveRerankerRuntime()
+                ? 'active'
+                : this.hasHeuristicRerankerRuntime()
+                    ? 'heuristic'
+                    : 'placeholder',
+            deepResearchRuntimeMode,
+        };
+    }
     // ==========================================================================
     // PRIVATE — Corpus loading
     // ==========================================================================
@@ -386,6 +645,22 @@ export class QueryRouter {
         }
         return chunks;
     }
+    /**
+     * Build a clear init-time error for empty or unreadable corpora.
+     *
+     * The router can technically operate with keyword fallback only, but it
+     * should not silently mark itself ready when no corpus content was loaded
+     * at all. Callers usually interpret a successful `init()` as "docs loaded".
+     *
+     * @param paths - Configured knowledge corpus directory paths.
+     * @returns Human-readable error message for throwing from {@link init}.
+     */
+    buildEmptyCorpusError(paths) {
+        return ('QueryRouter init failed: no readable markdown corpus chunks were loaded. ' +
+            `Checked paths: ${paths.join(', ')}. ` +
+            'Make sure at least one configured directory exists and contains readable ' +
+            '.md or .mdx files with non-trivial section content.');
+    }
     /**
      * Recursively walk a directory tree, invoking a callback for each file.
      *
@@ -480,8 +755,9 @@ export class QueryRouter {
         // Quick check: bail out early if there's obviously no API key configured.
         // This avoids the overhead of dynamic imports and provider initialization
         // in test environments and when no embedding provider is available.
-        const apiKey = this.config.apiKey || process.env.OPENAI_API_KEY || '';
-        if (!apiKey) {
+        const embeddingApiKey = this.getEmbeddingApiKey();
+        if (!embeddingApiKey) {
+            this.disableVectorRetrieval('disabled-no-key');
             console.debug('[QueryRouter] No embedding API key configured; skipping vector store embedding (keyword fallback active).');
             return;
         }
@@ -500,8 +776,8 @@ export class QueryRouter {
                         providerId: this.config.embeddingProvider,
                         enabled: true,
                         config: {
-                            apiKey: this.config.apiKey || process.env.OPENAI_API_KEY || '',
-                            ...(this.config.baseUrl ? { baseUrl: this.config.baseUrl } : {}),
+                            apiKey: embeddingApiKey,
+                            ...(this.getEmbeddingBaseUrl() ? { baseUrl: this.getEmbeddingBaseUrl() } : {}),
                         },
                         isDefault: true,
                     },
@@ -539,6 +815,7 @@ export class QueryRouter {
                 }
             }
             this.embeddingDimension = dimension;
+            this.embeddingStatus = 'active';
             // --- 3. Initialise the vector store manager (in-memory) ---
             const vsm = new VectorStoreManagerClass();
             const collectionName = this.corpusDataSourceId;
@@ -596,12 +873,161 @@ export class QueryRouter {
             // Non-fatal: warn and continue — keyword fallback still works
             const message = error instanceof Error ? error.message : String(error);
             console.warn(`[QueryRouter] Embedding initialisation failed, falling back to keyword search: ${message}`);
-            // Clean up any partial state
-            this.embeddingManager = null;
-            this.vectorStoreManager = null;
-            this.providerManager = null;
-            this.embeddingDimension = 0;
+            this.disableVectorRetrieval('failed-init');
+        }
+    }
+    async syncIndexedCorpusChunks(chunks) {
+        if (chunks.length === 0) {
+            return;
+        }
+        const appendedChunks = this.appendCorpusChunks(chunks);
+        await this.indexAdditionalCorpusChunks(appendedChunks);
+        this.rebuildCorpusSearchState();
+    }
+    appendCorpusChunks(chunks) {
+        const existingKeys = new Set(this.corpus.map((chunk) => `${chunk.sourcePath}\u0000${chunk.heading}\u0000${chunk.content}`));
+        const filteredChunks = chunks
+            .map((chunk) => ({
+            heading: chunk.heading,
+            sourcePath: chunk.sourcePath,
+            content: chunk.content.slice(0, MAX_CHUNK_CHARS).trim(),
+        }))
+            .filter((chunk) => {
+            if (chunk.content.length < MIN_CHUNK_CHARS) {
+                return false;
+            }
+            const dedupeKey = `${chunk.sourcePath}\u0000${chunk.heading}\u0000${chunk.content}`;
+            if (existingKeys.has(dedupeKey)) {
+                return false;
+            }
+            existingKeys.add(dedupeKey);
+            return true;
+        });
+        const startIndex = this.corpus.length;
+        const appendedChunks = filteredChunks.map((chunk, index) => ({
+            id: `gh_${startIndex + index}`,
+            heading: chunk.heading,
+            content: chunk.content,
+            sourcePath: chunk.sourcePath,
+        }));
+        this.corpus.push(...appendedChunks);
+        return appendedChunks;
+    }
+    rebuildCorpusSearchState() {
+        this.keywordFallback = new KeywordFallback(this.corpus);
+        const topicExtractor = new TopicExtractor();
+        this.topics = topicExtractor.extract(this.corpus);
+        if (this.classifier) {
+            this.classifier = this.createClassifier(topicExtractor.formatForPrompt(this.topics));
+        }
+    }
+    createClassifier(topicList) {
+        return new QueryClassifier({
+            model: this.config.classifierModel,
+            provider: this.config.classifierProvider,
+            confidenceThreshold: this.config.confidenceThreshold,
+            maxTier: this.config.maxTier,
+            topicList,
+            toolList: this.formatToolList(this.config.availableTools),
+            apiKey: this.getLlmApiKey(),
+            baseUrl: this.getLlmBaseUrl(),
+        });
+    }
+    async indexAdditionalCorpusChunks(chunks) {
+        if (chunks.length === 0 ||
+            !this.embeddingManager ||
+            !this.vectorStoreManager ||
+            this.embeddingStatus !== 'active') {
+            return;
+        }
+        try {
+            const { store, collectionName } = await this.vectorStoreManager.getStoreForDataSource(this.corpusDataSourceId);
+            const BATCH_SIZE = 50;
+            const allDocuments = [];
+            for (let i = 0; i < chunks.length; i += BATCH_SIZE) {
+                const batch = chunks.slice(i, i + BATCH_SIZE);
+                const result = await this.embeddingManager.generateEmbeddings({
+                    texts: batch.map((chunk) => chunk.content),
+                });
+                for (let j = 0; j < batch.length; j++) {
+                    const embedding = result.embeddings[j];
+                    if (!embedding || embedding.length === 0) {
+                        continue;
+                    }
+                    batch[j].embedding = embedding;
+                    allDocuments.push({
+                        id: batch[j].id,
+                        embedding,
+                        textContent: batch[j].content,
+                        metadata: {
+                            heading: batch[j].heading,
+                            sourcePath: batch[j].sourcePath,
+                        },
+                    });
+                }
+            }
+            if (allDocuments.length > 0) {
+                await store.upsert(collectionName, allDocuments);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[QueryRouter] Incremental GitHub corpus embedding failed; falling back to keyword search: ${message}`);
+            this.disableVectorRetrieval('failed-init');
+        }
+    }
+    disableVectorRetrieval(status) {
+        this.embeddingManager = null;
+        this.vectorStoreManager = null;
+        this.providerManager = null;
+        this.embeddingDimension = 0;
+        this.embeddingStatus = status;
+    }
+    getEmbeddingApiKey() {
+        return (this.config.embeddingApiKey ??
+            this.config.apiKey ??
+            process.env.OPENAI_API_KEY ??
+            process.env.OPENROUTER_API_KEY ??
+            '');
+    }
+    getEmbeddingBaseUrl() {
+        if (this.config.embeddingBaseUrl !== undefined) {
+            return this.config.embeddingBaseUrl;
+        }
+        if (this.config.embeddingApiKey !== undefined) {
+            return undefined;
+        }
+        if (this.config.baseUrl !== undefined) {
+            return this.config.baseUrl;
         }
+        if (this.config.apiKey !== undefined) {
+            return undefined;
+        }
+        if (process.env.OPENAI_API_KEY) {
+            return undefined;
+        }
+        if (process.env.OPENROUTER_API_KEY) {
+            return 'https://openrouter.ai/api/v1';
+        }
+        return undefined;
+    }
+    getLlmApiKey() {
+        return this.config.apiKey ?? process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY ?? '';
+    }
+    getLlmBaseUrl() {
+        if (this.config.baseUrl !== undefined) {
+            return this.config.baseUrl;
+        }
+        if (this.config.apiKey !== undefined) {
+            return undefined;
+        }
+        if (process.env.OPENAI_API_KEY) {
+            return undefined;
+        }
+        if (process.env.OPENROUTER_API_KEY) {
+            return 'https://openrouter.ai/api/v1';
+        }
+        return undefined;
     }
     /**
      * Return a known embedding dimension for common models.
@@ -620,9 +1046,93 @@ export class QueryRouter {
         };
         return KNOWN_DIMENSIONS[modelId] ?? 0;
     }
+    /**
+     * Whether graph expansion is backed by a live implementation.
+     *
+     * Hosts should not treat `graphEnabled` as meaning GraphRAG is actually live.
+     * `active` is reserved for a host-injected or future provider-backed graph
+     * runtime rather than the built-in heuristic.
+     */
+    hasLiveGraphRuntime() {
+        return typeof this.config.graphExpand === 'function';
+    }
+    /**
+     * Whether graph expansion is backed by the built-in heuristic expansion.
+     */
+    hasHeuristicGraphRuntime() {
+        return true;
+    }
+    /**
+     * Whether reranking is backed by a live implementation.
+     *
+     * `active` is reserved for a host-injected or future provider-backed
+     * reranker rather than the built-in lexical heuristic.
+     */
+    hasLiveRerankerRuntime() {
+        return typeof this.config.rerank === 'function';
+    }
+    /**
+     * Whether reranking is backed by the built-in lexical reranker.
+     */
+    hasHeuristicRerankerRuntime() {
+        return true;
+    }
+    /**
+     * Whether deep research is backed by a live implementation.
+     *
+     * `deepResearchEnabled` only means the branch may be attempted by config.
+     * `active` is reserved for a host-injected or future provider-backed
+     * research runtime rather than the built-in local-corpus heuristic.
+     */
+    hasLiveDeepResearchRuntime() {
+        return typeof this.config.deepResearch === 'function';
+    }
+    /**
+     * Whether deep research is backed by the built-in corpus-only heuristic.
+     */
+    hasHeuristicDeepResearchRuntime() {
+        return true;
+    }
     // ==========================================================================
     // PRIVATE — Retrieval callbacks (injected into QueryDispatcher)
     // ==========================================================================
+    /**
+     * HyDE (Hypothetical Document Embeddings) search callback for the dispatcher.
+     *
+     * Generates a hypothetical answer to the query using the LLM, then searches
+     * for documents similar to that hypothetical answer. Falls back to standard
+     * vector search if no generation provider is available.
+     *
+     * @param query - The user's query string.
+     * @param topK - Maximum number of chunks to return.
+     * @returns Promise resolving to an array of matched chunks.
+     */
+    async hydeSearch(query, topK) {
+        // HyDE falls back to standard vector search in the built-in implementation.
+        // A host-injected HyDE retriever would generate a hypothetical document first.
+        return this.vectorSearch(query, topK);
+    }
+    /**
+     * Query decomposition callback for the dispatcher.
+     *
+     * Splits a complex multi-part query into independent sub-queries.
+     * The built-in implementation uses simple sentence splitting as a heuristic.
+     * A host-injected decomposer would use an LLM for semantic decomposition.
+     *
+     * @param query - The original multi-part user query.
+     * @param maxSubQueries - Maximum number of sub-queries to generate.
+     * @returns Array of decomposed sub-query strings.
+     */
+    async decomposeQuery(query, maxSubQueries) {
+        // Built-in heuristic: split on sentence boundaries or question marks.
+        const parts = query
+            .split(/[?.!]\s+/)
+            .map(s => s.trim())
+            .filter(s => s.length > 0);
+        if (parts.length <= 1)
+            return [query];
+        return parts.slice(0, maxSubQueries);
+    }
     /**
      * Vector search callback for the dispatcher.
      *
@@ -696,44 +1206,156 @@ export class QueryRouter {
     /**
      * Graph expansion callback for the dispatcher.
      *
-     * Placeholder — returns empty array.
-     * // Follow-up: wire GraphRAGEngine
+     * Built-in heuristic graph expansion over the loaded corpus.
      *
-     * @param _seeds - Seed chunks to expand from (unused for now).
-     * @returns Promise resolving to an empty array.
+     * This is not yet a true GraphRAG engine. It expands from seed chunks by
+     * preferring:
+     * - chunks from the same source document
+     * - heading overlap with seed headings/content
+     * - content overlap with seed headings/content
+     *
+     * @param seeds - Seed chunks to expand from.
+     * @returns Promise resolving to related chunks marked as `graph`.
      */
-    async graphExpand(_seeds) {
-        // Follow-up: wire GraphRAGEngine
-        return [];
+    async graphExpand(seeds) {
+        if (seeds.length === 0 || this.corpus.length === 0) {
+            return [];
+        }
+        const seedIds = new Set(seeds.map((seed) => seed.id));
+        const seedSourcePaths = new Set(seeds.map((seed) => seed.sourcePath));
+        const seedTerms = new Set();
+        for (const seed of seeds) {
+            for (const term of this.tokenizeForRerank(`${seed.heading} ${seed.content}`)) {
+                seedTerms.add(term);
+            }
+        }
+        const scored = this.corpus
+            .filter((chunk) => !seedIds.has(chunk.id))
+            .map((chunk, index) => {
+            const sameSourceBoost = seedSourcePaths.has(chunk.sourcePath) ? 0.48 : 0;
+            const headingOverlap = this.computeTermOverlap(seedTerms, this.tokenizeForRerank(chunk.heading));
+            const contentOverlap = this.computeTermOverlap(seedTerms, this.tokenizeForRerank(chunk.content));
+            const score = sameSourceBoost + headingOverlap * 0.32 + contentOverlap * 0.2;
+            return { chunk, index, score };
+        })
+            .filter((entry) => entry.score >= 0.18);
+        scored.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            return left.index - right.index;
+        });
+        return scored.slice(0, 8).map(({ chunk, score }) => ({
+            id: chunk.id,
+            heading: chunk.heading,
+            content: chunk.content,
+            sourcePath: chunk.sourcePath,
+            relevanceScore: Math.min(0.99, score),
+            matchType: 'graph',
+        }));
     }
     /**
      * Reranking callback for the dispatcher.
      *
-     * Placeholder — returns the first topN chunks without actual reranking.
-     * // Follow-up: wire RerankerService
+     * Built-in heuristic reranker.
+     *
+     * This is not yet a cross-encoder. It reorders candidate chunks by combining:
+     * - original retrieval score
+     * - heading term overlap
+     * - content term overlap
+     * - exact phrase containment
+     *
+     * This gives tier-2 routing a real second-pass ranking step today without
+     * pretending the deeper reranker service is already wired.
      *
-     * @param _query - The user's query (unused for now).
+     * @param query - The user's query.
      * @param chunks - Candidate chunks to rerank.
      * @param topN - Maximum number of chunks to keep.
-     * @returns Promise resolving to the first topN chunks.
+     * @returns Promise resolving to the best-ranked chunks.
      */
-    async rerank(_query, chunks, topN) {
-        // Follow-up: wire RerankerService
-        return chunks.slice(0, topN);
+    async rerank(query, chunks, topN) {
+        if (chunks.length <= 1) {
+            return chunks.slice(0, topN);
+        }
+        const queryTerms = this.tokenizeForRerank(query);
+        const normalizedQuery = this.normalizeForRerank(query);
+        const scored = chunks.map((chunk, index) => {
+            const headingTerms = this.tokenizeForRerank(chunk.heading);
+            const contentTerms = this.tokenizeForRerank(chunk.content);
+            const headingOverlap = this.computeTermOverlap(queryTerms, headingTerms);
+            const contentOverlap = this.computeTermOverlap(queryTerms, contentTerms);
+            const normalizedText = this.normalizeForRerank(`${chunk.heading} ${chunk.content}`);
+            const exactPhraseBoost = normalizedQuery.length >= 4 && normalizedText.includes(normalizedQuery) ? 0.2 : 0;
+            const score = chunk.relevanceScore * 0.55 +
+                headingOverlap * 0.25 +
+                contentOverlap * 0.2 +
+                exactPhraseBoost;
+            return { chunk, index, score };
+        });
+        scored.sort((left, right) => {
+            if (right.score !== left.score) {
+                return right.score - left.score;
+            }
+            if (right.chunk.relevanceScore !== left.chunk.relevanceScore) {
+                return right.chunk.relevanceScore - left.chunk.relevanceScore;
+            }
+            return left.index - right.index;
+        });
+        return scored.slice(0, topN).map((entry) => entry.chunk);
     }
     /**
      * Deep research callback for the dispatcher.
      *
-     * Placeholder — returns empty synthesis and empty sources.
-     * // Follow-up: wire DeepResearchEngine
+     * Built-in corpus-only research heuristic.
+     *
+     * This is not web-backed research. It runs a few local keyword-based passes
+     * over the loaded corpus using slightly different query formulations, merges
+     * the results, and returns a compact synthesis built from the top findings.
      *
-     * @param _query - The user's query (unused for now).
-     * @param _sources - Source identifiers to consult (unused for now).
-     * @returns Promise resolving to empty synthesis and sources.
+     * @param query - The user's query.
+     * @param sources - Optional source hints used to broaden local matching.
+     * @returns Promise resolving to synthesized local-corpus findings.
      */
-    async deepResearch(_query, _sources) {
-        // Follow-up: wire DeepResearchEngine
-        return { synthesis: '', sources: [] };
+    async deepResearch(query, sources) {
+        if (!this.keywordFallback || this.corpus.length === 0) {
+            return { synthesis: '', sources: [] };
+        }
+        const normalizedSourceHints = sources
+            .map((source) => this.normalizeForRerank(source))
+            .filter(Boolean);
+        const queryTerms = [...this.tokenizeForRerank(query)];
+        const narrowedTerms = queryTerms.slice(0, 4).join(' ');
+        const researchQueries = [
+            query,
+            [query, normalizedSourceHints.join(' ')].filter(Boolean).join(' ').trim(),
+            [query, 'architecture tradeoffs details'].join(' ').trim(),
+            narrowedTerms,
+        ].filter(Boolean);
+        const merged = new Map();
+        for (const researchQuery of researchQueries) {
+            const hits = this.keywordFallback.search(researchQuery, 4);
+            for (const hit of hits) {
+                const existing = merged.get(hit.id);
+                const researchChunk = {
+                    ...hit,
+                    relevanceScore: Math.min(0.99, hit.relevanceScore),
+                    matchType: 'research',
+                };
+                if (!existing || researchChunk.relevanceScore > existing.relevanceScore) {
+                    merged.set(researchChunk.id, researchChunk);
+                }
+            }
+        }
+        const researchChunks = [...merged.values()]
+            .sort((left, right) => right.relevanceScore - left.relevanceScore)
+            .slice(0, 5);
+        if (researchChunks.length === 0) {
+            return { synthesis: '', sources: [] };
+        }
+        const synthesis = researchChunks
+            .map((chunk, index) => `${index + 1}. ${chunk.heading}: ${this.firstSentence(chunk.content)}`)
+            .join('\n');
+        return { synthesis, sources: researchChunks };
     }
     /**
      * Format available tools for the classifier prompt.
@@ -741,6 +1363,72 @@ export class QueryRouter {
     formatToolList(availableTools) {
         return availableTools.length > 0 ? availableTools.join(', ') : '(none available)';
     }
+    /**
+     * Normalize text for simple lexical reranking.
+     */
+    normalizeForRerank(text) {
+        return text.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+    }
+    /**
+     * Tokenize text for lexical reranking.
+     */
+    tokenizeForRerank(text) {
+        const STOP_WORDS = new Set([
+            'a',
+            'an',
+            'and',
+            'are',
+            'as',
+            'at',
+            'be',
+            'by',
+            'for',
+            'from',
+            'how',
+            'in',
+            'is',
+            'it',
+            'of',
+            'on',
+            'or',
+            'that',
+            'the',
+            'this',
+            'to',
+            'what',
+            'when',
+            'where',
+            'which',
+            'why',
+            'with',
+        ]);
+        return new Set(this.normalizeForRerank(text)
+            .split(/\s+/)
+            .filter((term) => term.length >= 2 && !STOP_WORDS.has(term)));
+    }
+    /**
+     * Compute overlap ratio between query terms and candidate terms.
+     */
+    computeTermOverlap(queryTerms, candidateTerms) {
+        if (queryTerms.size === 0 || candidateTerms.size === 0) {
+            return 0;
+        }
+        let matches = 0;
+        for (const term of queryTerms) {
+            if (candidateTerms.has(term)) {
+                matches += 1;
+            }
+        }
+        return matches / queryTerms.size;
+    }
+    /**
+     * Extract a short first-sentence style summary from a chunk for synthesis.
+     */
+    firstSentence(text) {
+        const normalized = text.replace(/\s+/g, ' ').trim();
+        const sentence = normalized.match(/^(.{1,220}?[.!?])(?:\s|$)/);
+        return sentence?.[1] ?? normalized.slice(0, 220);
+    }
     /**
      * Derive fallback strategy names from classification + retrieval events.
      */