minovative-mind-cli 1.5.1 → 2.0.0

package/dist/services/embeddingIndex.js

@@ -0,0 +1,613 @@
+import { promises as fs } from 'node:fs';
+import * as crypto from 'node:crypto';
+import path from 'node:path';
+import { debugLog } from '../utils/logger.js';
+import { getAuthorizedIdToken } from './auth.js';
+import { ProxyClient } from './proxyClient.js';
+import { EXCLUDED_EXTENSIONS } from '../utils/excludedExtensions.js';
+import { GEMINI_MODELS } from '../utils/config.js';
+import { readCache, writeCache } from '../utils/projectStorage.js';
+// ─── Constants ───────────────────────────────────────────────────────
+/** Maximum characters per chunk before splitting */
+const MAX_CHUNK_CHARS = 3000;
+/** Minimum characters for a chunk to be worth embedding */
+const MIN_CHUNK_CHARS = 50;
+/** Maximum file size (chars) to index — skip likely generated/vendored files */
+const MAX_FILE_CHARS = 50_000;
+/** Number of texts to embed per API call */
+const EMBED_BATCH_SIZE = 25;
+/** Sliding window size for non-AST files */
+const SLIDING_WINDOW_CHARS = 800;
+/** Sliding window overlap for context continuity */
+const SLIDING_WINDOW_OVERLAP = 200;
+/** Index file path within .minovativemind */
+const INDEX_FILENAME = 'embeddings/index.json';
+/** Directories to always skip during indexing */
+const IGNORED_DIRS = new Set([
+    'node_modules', '.git', 'dist', '.next', '.nuxt', '__pycache__',
+    '.venv', 'venv', '.cache', 'coverage', '.turbo', '.minovativemind',
+    '.tmp', 'build', 'out', '.output', '.svelte-kit',
+]);
+/** File extensions that support AST-aware chunking via declaration regex */
+const AST_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.py', '.go', '.rs', '.java', '.kt', '.swift',
+    '.dart', '.rb', '.php', '.c', '.cpp', '.h', '.hpp',
+]);
+// ─── Proxy Client (shared instance) ─────────────────────────────────
+const proxyClient = new ProxyClient();
+// ─── AST-Aware Chunking (reuses symbolExtractor logic) ──────────────
+/**
+ * Builds a regex that matches declaration-level constructs for a given file extension.
+ * Adapted from symbolExtractor.ts but generalized to match ANY declaration,
+ * not a specific named symbol.
+ */
+function buildGenericDeclarationRegex(ext) {
+    if (ext === '.py') {
+        return /^\s*(?:async\s+)?(?:def|class)\s+\w+/;
+    }
+    if (ext === '.go') {
+        return /^\s*(?:func(?:\s+\([^)]+\))?\s+\w+|type\s+\w+|var\s+\w+|const\s+\w+)/;
+    }
+    if (ext === '.rs') {
+        return /^\s*(?:(?:pub\s+)?(?:async\s+)?fn\s+\w+|(?:pub\s+)?(?:struct|enum|trait|impl)\s+\w+)/;
+    }
+    if (ext === '.rb') {
+        return /^\s*(?:def\s+\w+|class\s+\w+|module\s+\w+)/;
+    }
+    if (ext === '.php') {
+        return /^\s*(?:(?:public|private|protected|static)\s+)?function\s+\w+|^\s*class\s+\w+/;
+    }
+    if (ext === '.java' || ext === '.kt') {
+        return /^\s*(?:(?:public|private|protected|static|abstract|final|override|suspend)\s+)*(?:class|interface|enum|fun|void|int|String|boolean|object)\s+\w+/;
+    }
+    if (ext === '.swift') {
+        return /^\s*(?:(?:public|private|internal|open|fileprivate|static|class|override)\s+)*(?:func|class|struct|enum|protocol|extension)\s+\w+/;
+    }
+    if (ext === '.dart') {
+        return /^\s*(?:(?:abstract|static)\s+)?(?:class|mixin|extension|void|Future|Stream|int|String|bool|double)\s+\w+/;
+    }
+    if (ext === '.c' || ext === '.cpp' || ext === '.h' || ext === '.hpp') {
+        return /^\s*(?:(?:static|inline|extern|virtual|const)\s+)*(?:void|int|char|float|double|bool|auto|class|struct|enum|namespace|template)\s+\w+/;
+    }
+    // Default: JS/TS family
+    return /^\s*(?:(?:export\s+|default\s+|async\s+|abstract\s+|static\s+|public\s+|private\s+|protected\s+|readonly\s+)*(?:class|function|const|let|var|type|interface|enum)\s+\w+|^\s*(?:async\s+)?\w+\s*[<]?\w*[>]?\s*\()/;
+}
+/**
+ * Extracts a human-readable label from a declaration line.
+ * e.g., "export async function fetchUser(" → "function fetchUser"
+ */
+function extractLabel(line, ext) {
+    const trimmed = line.trim();
+    // Try to extract the key parts: keyword + name
+    const patterns = ext === '.py'
+        ? [/(?:async\s+)?(def|class)\s+(\w+)/, /(\w+)\s*[:=]/]
+        : [
+            /(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:abstract\s+)?(function|class|interface|type|enum|const|let|var)\s+(\w+)/,
+            /(?:pub\s+)?(?:async\s+)?(fn|struct|enum|trait|impl)\s+(\w+)/,
+            /(def|class|module)\s+(\w+)/,
+            /(func|type|var|const)\s+(\w+)/,
+        ];
+    for (const pat of patterns) {
+        const match = trimmed.match(pat);
+        if (match)
+            return `${match[1]} ${match[2]}`;
+    }
+    // Fallback: first 60 chars of the trimmed line
+    return trimmed.substring(0, 60);
+}
+/**
+ * Finds the end of a brace/indent-delimited block starting at a given line.
+ * Reuses the same balanced-brace tracking logic from symbolExtractor.ts.
+ */
+function findBlockEndLine(lines, startIdx, ext) {
+    if (ext === '.py') {
+        // Python: indentation-based
+        const baseIndent = lines[startIdx].match(/^(\s*)/)?.[1].length ?? 0;
+        let endIdx = startIdx;
+        for (let j = startIdx + 1; j < lines.length; j++) {
+            const line = lines[j];
+            if (!line.trim()) {
+                endIdx = j;
+                continue;
+            }
+            if ((line.match(/^(\s*)/)?.[1].length ?? 0) <= baseIndent)
+                break;
+            endIdx = j;
+        }
+        return endIdx;
+    }
+    // Brace-based languages
+    let braces = 0;
+    let foundOpen = false;
+    let inStr = null;
+    let inComment = false;
+    let endIdx = startIdx;
+    for (let j = startIdx; j < lines.length; j++) {
+        endIdx = j;
+        const line = lines[j];
+        for (let c = 0; c < line.length; c++) {
+            const ch = line[c];
+            if (inComment) {
+                if (ch === '*' && line[c + 1] === '/') {
+                    inComment = false;
+                    c++;
+                }
+                continue;
+            }
+            if (inStr) {
+                if (ch === '\\') {
+                    c++;
+                    continue;
+                }
+                if (ch === inStr)
+                    inStr = null;
+                continue;
+            }
+            if (ch === '/' && line[c + 1] === '/')
+                break;
+            if (ch === '/' && line[c + 1] === '*') {
+                inComment = true;
+                c++;
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === '`') {
+                inStr = ch;
+                continue;
+            }
+            if (ch === '{') {
+                braces++;
+                foundOpen = true;
+            }
+            else if (ch === '}')
+                braces--;
+        }
+        if (foundOpen && braces <= 0)
+            break;
+        // One-liners without braces (e.g., `const x = 5;`)
+        if (!foundOpen && j > startIdx) {
+            const prevTrimmed = lines[j - 1].trim();
+            if (!prevTrimmed.endsWith(',') && !prevTrimmed.endsWith('.')) {
+                endIdx = j - 1;
+                break;
+            }
+        }
+    }
+    return endIdx;
+}
+/**
+ * Chunks a single source file into semantic units.
+ * Uses AST-aware declaration detection for supported languages,
+ * falls back to sliding-window chunking for everything else.
+ */
+function chunkFile(filePath, content) {
+    const ext = path.extname(filePath).toLowerCase();
+    const lines = content.split('\n');
+    const chunks = [];
+    if (AST_EXTENSIONS.has(ext)) {
+        // AST-aware chunking: split at declaration boundaries
+        const declRegex = buildGenericDeclarationRegex(ext);
+        let i = 0;
+        while (i < lines.length) {
+            if (declRegex.test(lines[i])) {
+                const startIdx = i;
+                const endIdx = findBlockEndLine(lines, i, ext);
+                const chunkContent = lines.slice(startIdx, endIdx + 1).join('\n');
+                if (chunkContent.length >= MIN_CHUNK_CHARS) {
+                    // Split oversized chunks at the MAX_CHUNK_CHARS boundary
+                    if (chunkContent.length > MAX_CHUNK_CHARS) {
+                        const subChunks = splitOversizedChunk(chunkContent, filePath, startIdx);
+                        chunks.push(...subChunks);
+                    }
+                    else {
+                        chunks.push({
+                            filePath,
+                            startLine: startIdx + 1,
+                            endLine: endIdx + 1,
+                            label: extractLabel(lines[startIdx], ext),
+                            content: chunkContent,
+                        });
+                    }
+                }
+                i = endIdx + 1;
+            }
+            else {
+                i++;
+            }
+        }
+        // If AST parsing found nothing (e.g., a config file with no declarations),
+        // fall back to treating the whole file as one chunk
+        if (chunks.length === 0 && content.length >= MIN_CHUNK_CHARS) {
+            if (content.length > MAX_CHUNK_CHARS) {
+                chunks.push(...slidingWindowChunk(filePath, content));
+            }
+            else {
+                chunks.push({
+                    filePath,
+                    startLine: 1,
+                    endLine: lines.length,
+                    label: path.basename(filePath),
+                    content,
+                });
+            }
+        }
+    }
+    else {
+        // Non-AST files: sliding window chunking
+        if (content.length >= MIN_CHUNK_CHARS) {
+            if (content.length <= MAX_CHUNK_CHARS) {
+                chunks.push({
+                    filePath,
+                    startLine: 1,
+                    endLine: lines.length,
+                    label: path.basename(filePath),
+                    content,
+                });
+            }
+            else {
+                chunks.push(...slidingWindowChunk(filePath, content));
+            }
+        }
+    }
+    return chunks;
+}
+/**
+ * Splits an oversized function/class chunk into smaller pieces.
+ */
+function splitOversizedChunk(content, filePath, globalStartIdx) {
+    const lines = content.split('\n');
+    const results = [];
+    let chunkStart = 0;
+    while (chunkStart < lines.length) {
+        let chunkEnd = chunkStart;
+        let charCount = 0;
+        while (chunkEnd < lines.length && charCount + lines[chunkEnd].length < MAX_CHUNK_CHARS) {
+            charCount += lines[chunkEnd].length + 1; // +1 for newline
+            chunkEnd++;
+        }
+        if (chunkEnd === chunkStart)
+            chunkEnd = chunkStart + 1; // Prevent infinite loop on very long lines
+        const chunkLines = lines.slice(chunkStart, chunkEnd);
+        const chunkContent = chunkLines.join('\n');
+        if (chunkContent.length >= MIN_CHUNK_CHARS) {
+            results.push({
+                filePath,
+                startLine: globalStartIdx + chunkStart + 1,
+                endLine: globalStartIdx + chunkEnd,
+                label: `${path.basename(filePath)}:${globalStartIdx + chunkStart + 1}`,
+                content: chunkContent,
+            });
+        }
+        chunkStart = chunkEnd;
+    }
+    return results;
+}
+/**
+ * Sliding window chunker for non-AST files (markdown, JSON, HTML, CSS, etc).
+ * Uses character-level windowing with overlap for context continuity.
+ */
+function slidingWindowChunk(filePath, content) {
+    const lines = content.split('\n');
+    const results = [];
+    let charOffset = 0;
+    let lineOffset = 0;
+    while (charOffset < content.length) {
+        const windowEnd = Math.min(charOffset + SLIDING_WINDOW_CHARS, content.length);
+        const windowContent = content.substring(charOffset, windowEnd);
+        // Calculate line numbers for this window
+        const windowLines = windowContent.split('\n');
+        const startLine = lineOffset + 1;
+        const endLine = lineOffset + windowLines.length;
+        if (windowContent.length >= MIN_CHUNK_CHARS) {
+            results.push({
+                filePath,
+                startLine,
+                endLine,
+                label: `${path.basename(filePath)}:${startLine}`,
+                content: windowContent,
+            });
+        }
+        // Advance by (window - overlap) characters
+        const advance = SLIDING_WINDOW_CHARS - SLIDING_WINDOW_OVERLAP;
+        // Count how many lines we advanced through
+        const advancedContent = content.substring(charOffset, Math.min(charOffset + advance, content.length));
+        const advancedLines = advancedContent.split('\n').length - 1;
+        lineOffset += advancedLines;
+        charOffset += advance;
+    }
+    return results;
+}
+// ─── Math Utilities ──────────────────────────────────────────────────
+/**
+ * Computes cosine similarity between two vectors.
+ * Pure arithmetic — no dependencies, ~1ms for 10K comparisons.
+ */
+function cosineSimilarity(a, b) {
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// ─── Embedding Index Class ───────────────────────────────────────────
+/**
+ * Manages a persistent local vector index for semantic code search.
+ *
+ * Lifecycle:
+ * 1. On first `gatherContext` call, if no index exists on disk, `buildIndex()` is called.
+ * 2. After the Execution Agent modifies files, `updateIndex()` delta-reindexes only changed files.
+ * 3. `search()` embeds the query (1 API call) and scans the local index via cosine similarity.
+ * 4. Index is persisted to `.minovativemind/embeddings/index.json` via atomic writes.
+ */
+export class EmbeddingIndex {
+    chunks = [];
+    modelVersion = GEMINI_MODELS.EMBEDDING;
+    /**
+     * Builds the full index for a workspace by scanning all eligible source files,
+     * chunking them at function/class boundaries, and batch-embedding them.
+     *
+     * @param workspaceRoot - Absolute path to the workspace root directory.
+     * @param onProgress - Optional callback for user-facing progress messages.
+     */
+    async buildIndex(workspaceRoot, onProgress) {
+        this.chunks = [];
+        this.modelVersion = GEMINI_MODELS.EMBEDDING;
+        // Phase 1: Discover and chunk all eligible files
+        const allChunks = [];
+        await this.walkAndChunk(workspaceRoot, workspaceRoot, allChunks);
+        if (allChunks.length === 0) {
+            debugLog('Embedding index: No eligible files found to index.');
+            return;
+        }
+        if (onProgress)
+            onProgress(`Indexing ${allChunks.length} code chunks...`);
+        debugLog(`Embedding index: Found ${allChunks.length} chunks to embed.`);
+        // Phase 2: Batch-embed all chunks
+        const idToken = await getAuthorizedIdToken();
+        if (!idToken) {
+            debugLog('Embedding index: No auth token available, skipping index build.');
+            return;
+        }
+        const batchCount = Math.ceil(allChunks.length / EMBED_BATCH_SIZE);
+        for (let b = 0; b < batchCount; b++) {
+            const batchStart = b * EMBED_BATCH_SIZE;
+            const batchEnd = Math.min(batchStart + EMBED_BATCH_SIZE, allChunks.length);
+            const batch = allChunks.slice(batchStart, batchEnd);
+            if (onProgress) {
+                onProgress(`Embedding batch ${b + 1}/${batchCount} (${batch.length} chunks)...`);
+            }
+            try {
+                const result = await proxyClient.embedTextsViaProxy(idToken, batch.map((c) => c.content), 'RETRIEVAL_DOCUMENT');
+                for (let i = 0; i < batch.length; i++) {
+                    if (result.embeddings[i]) {
+                        this.chunks.push({
+                            filePath: batch[i].filePath,
+                            startLine: batch[i].startLine,
+                            endLine: batch[i].endLine,
+                            contentHash: this.hashChunk(batch[i].filePath, batch[i].content),
+                            label: batch[i].label,
+                            preview: batch[i].content.substring(0, 200).replace(/\n/g, ' '),
+                            embedding: result.embeddings[i],
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                debugLog(`Embedding index: Batch ${b + 1} failed: ${e.message}`);
+                // Continue with remaining batches — partial index is better than none
+            }
+        }
+        debugLog(`Embedding index: Built index with ${this.chunks.length} chunks.`);
+    }
+    /**
+     * Delta-updates the index for files that have changed.
+     * Removes stale chunks for modified/deleted files, then re-chunks and
+     * re-embeds only the affected files.
+     *
+     * @param workspaceRoot - Absolute path to the workspace root.
+     * @param changedFiles - Array of relative file paths that were modified.
+     */
+    async updateIndex(workspaceRoot, changedFiles) {
+        if (changedFiles.length === 0)
+            return;
+        // Remove all chunks belonging to changed files
+        const changedSet = new Set(changedFiles);
+        this.chunks = this.chunks.filter((c) => !changedSet.has(c.filePath));
+        // Re-chunk and re-embed the changed files
+        const newChunks = [];
+        for (const relPath of changedFiles) {
+            const absPath = path.join(workspaceRoot, relPath);
+            if (absPath.toLowerCase().endsWith('.pdf'))
+                continue;
+            try {
+                const content = await fs.readFile(absPath, 'utf-8');
+                if (content.length > MAX_FILE_CHARS || content.length < MIN_CHUNK_CHARS)
+                    continue;
+                const fileChunks = chunkFile(relPath, content);
+                newChunks.push(...fileChunks);
+            }
+            catch {
+                // File was deleted or unreadable — chunks already removed above
+            }
+        }
+        if (newChunks.length === 0)
+            return;
+        const idToken = await getAuthorizedIdToken();
+        if (!idToken)
+            return;
+        const batchCount = Math.ceil(newChunks.length / EMBED_BATCH_SIZE);
+        for (let b = 0; b < batchCount; b++) {
+            const batchStart = b * EMBED_BATCH_SIZE;
+            const batchEnd = Math.min(batchStart + EMBED_BATCH_SIZE, newChunks.length);
+            const batch = newChunks.slice(batchStart, batchEnd);
+            try {
+                const result = await proxyClient.embedTextsViaProxy(idToken, batch.map((c) => c.content), 'RETRIEVAL_DOCUMENT');
+                for (let i = 0; i < batch.length; i++) {
+                    if (result.embeddings[i]) {
+                        this.chunks.push({
+                            filePath: batch[i].filePath,
+                            startLine: batch[i].startLine,
+                            endLine: batch[i].endLine,
+                            contentHash: this.hashChunk(batch[i].filePath, batch[i].content),
+                            label: batch[i].label,
+                            preview: batch[i].content.substring(0, 200).replace(/\n/g, ' '),
+                            embedding: result.embeddings[i],
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                debugLog(`Embedding index: Delta batch failed: ${e.message}`);
+            }
+        }
+        debugLog(`Embedding index: Delta-updated ${changedFiles.length} file(s). Total chunks: ${this.chunks.length}`);
+    }
+    /**
+     * Executes a semantic search against the local index.
+     *
+     * 1. Embeds the query string (single API call).
+     * 2. Computes cosine similarity against all indexed chunks.
+     * 3. Returns the top-K results sorted by descending similarity score.
+     *
+     * @param query - Natural language description of what to search for.
+     * @param topK - Number of results to return (default 5, max 15).
+     * @returns Array of search results with file paths, line ranges, and scores.
+     */
+    async search(query, topK = 5) {
+        if (this.chunks.length === 0)
+            return [];
+        const clampedK = Math.min(Math.max(topK, 1), 15);
+        const idToken = await getAuthorizedIdToken();
+        if (!idToken)
+            return [];
+        // Embed the query (single API call)
+        let queryEmbedding;
+        try {
+            const result = await proxyClient.embedTextsViaProxy(idToken, [query], 'RETRIEVAL_QUERY');
+            if (!result.embeddings[0])
+                return [];
+            queryEmbedding = result.embeddings[0];
+        }
+        catch (e) {
+            debugLog(`Embedding index: Failed to embed query: ${e.message}`);
+            return [];
+        }
+        // Cosine similarity scan (pure math, ~1ms for 10K chunks)
+        const scored = this.chunks.map((chunk) => ({
+            filePath: chunk.filePath,
+            startLine: chunk.startLine,
+            endLine: chunk.endLine,
+            label: chunk.label,
+            preview: chunk.preview,
+            score: cosineSimilarity(queryEmbedding, chunk.embedding),
+        }));
+        // Sort by descending similarity and take top-K
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, clampedK);
+    }
+    /**
+     * Persists the index to disk using the atomic write pattern from projectStorage.
+     */
+    async save(workspaceRoot) {
+        const data = {
+            modelVersion: this.modelVersion,
+            chunks: this.chunks,
+        };
+        await writeCache(workspaceRoot, INDEX_FILENAME, data);
+        debugLog(`Embedding index: Saved ${this.chunks.length} chunks to disk.`);
+    }
+    /**
+     * Loads the index from disk. Returns false if no index exists or the model
+     * version has changed (requiring a full rebuild).
+     */
+    async load(workspaceRoot) {
+        const data = readCache(workspaceRoot, INDEX_FILENAME);
+        if (!data || !data.chunks)
+            return false;
+        // Auto-invalidate if the embedding model has been upgraded
+        if (data.modelVersion !== GEMINI_MODELS.EMBEDDING) {
+            debugLog(`Embedding index: Model version mismatch (${data.modelVersion} vs ${GEMINI_MODELS.EMBEDDING}). Rebuilding.`);
+            return false;
+        }
+        this.chunks = data.chunks;
+        this.modelVersion = data.modelVersion;
+        debugLog(`Embedding index: Loaded ${this.chunks.length} chunks from disk.`);
+        return true;
+    }
+    /** Check if the index is loaded and contains chunks */
+    isReady() {
+        return this.chunks.length > 0;
+    }
+    /** Get the number of chunks in the index */
+    get size() {
+        return this.chunks.length;
+    }
+    // ─── Private Helpers ─────────────────────────────────────────────
+    /**
+     * Recursively walks the workspace, reading and chunking eligible files.
+     * Respects .gitignore patterns and EXCLUDED_EXTENSIONS.
+     */
+    async walkAndChunk(rootDir, currentDir, results) {
+        let entries;
+        try {
+            entries = await fs.readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') && entry.name !== '.env')
+                continue;
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRS.has(entry.name))
+                    continue;
+                await this.walkAndChunk(rootDir, path.join(currentDir, entry.name), results);
+            }
+            else if (entry.isFile()) {
+                if (EXCLUDED_EXTENSIONS.some((ext) => entry.name.endsWith(ext.replace('*', ''))))
+                    continue;
+                if (entry.name.toLowerCase().endsWith('.pdf'))
+                    continue;
+                const absPath = path.join(currentDir, entry.name);
+                const relPath = path.relative(rootDir, absPath).replace(/\\/g, '/');
+                try {
+                    const content = await fs.readFile(absPath, 'utf-8');
+                    if (content.length > MAX_FILE_CHARS || content.length < MIN_CHUNK_CHARS)
+                        continue;
+                    const fileChunks = chunkFile(relPath, content);
+                    results.push(...fileChunks);
+                }
+                catch {
+                    // Skip unreadable files (binary detection, permission errors)
+                }
+            }
+        }
+    }
+    /**
+     * Generates a content hash for delta-detection.
+     * Uses SHA-256 of (filePath + content) to detect changes.
+     */
+    hashChunk(filePath, content) {
+        return crypto
+            .createHash('sha256')
+            .update(filePath + content)
+            .digest('hex');
+    }
+}
+// ─── Singleton Instance ──────────────────────────────────────────────
+let embeddingIndexInstance = null;
+/**
+ * Returns the global singleton EmbeddingIndex instance.
+ * Lazily created on first access.
+ */
+export function getEmbeddingIndex() {
+    if (!embeddingIndexInstance) {
+        embeddingIndexInstance = new EmbeddingIndex();
+    }
+    return embeddingIndexInstance;
+}

package/dist/services/investigationComplexity.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Investigation Complexity Evaluator.
+ *
+ * Lightweight LLM-powered gatekeeper that determines whether a user prompt
+ * warrants parallel investigation or should use the existing single Context
+ * Agent path. This prevents wasteful multi-agent spawns on simple prompts
+ * like "fix the typo in README" while enabling parallelism for broad
+ * architectural prompts like "refactor auth to OAuth2."
+ *
+ * Only invoked when the `/sub-agents` toggle is ON and the Intent Router
+ * has already determined that context gathering is needed (SEARCH).
+ */
+/** A single agent assignment grouping related investigation domains. */
+export interface AgentAssignment {
+    /** Human-readable label for this agent (e.g., "Frontend", "Backend") */
+    agentLabel: string;
+    /** The investigation domains this agent is responsible for */
+    domains: string[];
+}
+/** Result returned by the investigation complexity evaluator. */
+export interface InvestigationComplexityResult {
+    /** Whether investigation should use a single agent or parallel agents */
+    strategy: 'SINGLE' | 'PARALLEL';
+    /** All identified investigation domains (flat list) */
+    domains: string[];
+    /** Grouped domain assignments — one per agent to spawn */
+    agentAssignments: AgentAssignment[];
+    /** Brief justification from the PM for its decision */
+    reasoning: string;
+}
+/**
+ * Evaluates whether the investigation phase should be parallelized.
+ *
+ * Uses `gemini-3.1-flash-lite` at temperature 0 to classify the prompt's
+ * investigation complexity. The PM dynamically identifies domains and groups
+ * them into agent assignments. Agent count = `agentAssignments.length`, which
+ * may be fewer than `domains.length` when related domains are batched together.
+ *
+ * @param userRequest - The user's prompt.
+ * @param projectType - Detected project type (e.g., "Node.js / TypeScript / React").
+ * @param approximateFileCount - Rough file count from the project tree.
+ * @param chatHistory - Recent conversation history for context.
+ * @returns The complexity classification with domain decomposition.
+ */
+export declare function evaluateInvestigationComplexity(userRequest: string, projectType: string, approximateFileCount: number, chatHistory?: string): Promise<InvestigationComplexityResult>;