minovative-mind-cli 2.5.1 → 2.6.0

package/dist/services/agent-tools.js

@@ -1,3 +1,9 @@
+/**
+ * @file agent-tools.ts
+ * @description Implements tool declarations, approval state management, ignore rule parser,
+ * atomic file operations, search/grep engines, dependency tracer, scratchpad script runner,
+ * and central tool dispatcher used by the Minovative Mind AI agents.
+ */
 import { exec } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -9,7 +15,7 @@ import { workspaceRegistry } from './workspaceRegistry.js';
 import { changeLogger } from './changeLogger.js';
 import { findBestMatch, applyMatch } from '../utils/fuzzyMatch.js';
 import { localValidate } from '../utils/localSyntaxValidator.js';
-import { validateAndFixSyntax } from './agent/syntaxAgent.js';
+import { validateAndFixSyntax, aiFuzzyMatch } from './agent/syntaxAgent.js';
 import { sanitizeForCDATA } from '../utils/contextPrompts.js';
 import { findDependencies, formatDependencyResult } from '../utils/dependencyTracer.js';
 import { atomicWriteFile } from '../utils/atomicWrite.js';
@@ -20,6 +26,12 @@ import { getCurrentAgentId } from '../utils/asyncContext.js';
 import ignore from 'ignore';
 const execAsync = promisify(exec);
 // ─── Tool Declarations for Gemini Function Calling ───────────────────
+/**
+ * Returns the list of available function declarations for Gemini function calling.
+ *
+ * @param options - Configuration options such as `isExecutionAgent`.
+ * @returns An array of Google Generative AI `FunctionDeclaration` objects.
+ */
 export function getToolDeclarations(options) {
     if (options?.isExecutionAgent) {
         return toolDeclarations;
@@ -31,6 +43,17 @@ export function getToolDeclarations(options) {
  * every tool the agent can invoke. Passed to the model at init.
  */
 export const toolDeclarations = [
+    {
+        name: 'perform_web_search',
+        description: 'Search the web for documentation, solutions, or real-time information.',
+        parameters: {
+            type: SchemaType.OBJECT,
+            properties: {
+                query: { type: SchemaType.STRING, description: 'The search query to look up on the web' },
+            },
+            required: ['query'],
+        },
+    },
     {
         name: 'read_file',
         description: 'Read the contents of a file at the given path relative to the workspace root. Supports text files and native parsing of .pdf files (including math and diagrams). Use startLine and endLine to read specific chunks of massive files to avoid context limits. For files in external workspaces, prefix the path with @alias/ (e.g., @backend/src/routes.ts).',
@@ -110,7 +133,7 @@ export const toolDeclarations = [
     },
     {
         name: 'modify_file',
-        description: 'Perform one or multiple targeted search-and-replace edits in a single file. CRITICAL REQUIREMENT: You MUST use read_file or grep_search to fetch the exact current file content BEFORE using this tool. Do NOT guess or hallucinate the searchContent without reading the exact lines first, or the edit will fail. The search strings must match the current file exactly (including whitespace). This is preferred over write_file for editing existing files. For files in external workspaces, prefix the path with @alias/ (e.g., @backend/src/routes.ts).',
+        description: 'Perform one or multiple targeted search-and-replace edits in a single file. CRITICAL REQUIREMENT: You MUST have the exact current file content before using this tool. If the file is NOT already in your context, you MUST use read_file or grep_search to fetch it. Do NOT guess or hallucinate the searchContent without reading the exact lines first, or the edit will fail. The search strings must match the current file exactly (including whitespace). This is preferred over write_file for editing existing files. For files in external workspaces, prefix the path with @alias/ (e.g., @backend/src/routes.ts).',
         parameters: {
             type: SchemaType.OBJECT,
             properties: {
@@ -174,7 +197,7 @@ export const toolDeclarations = [
     },
     {
         name: 'grep_search',
-        description: 'Search for a text pattern across files in the workspace. Returns matching file paths with line numbers and content snippets. Uses Extended Regular Expressions (grep -E). IMPORTANT: grep searches line-by-line. Do NOT search for long lists of Tailwind classes or multi-line strings, as they will fail if line-wrapped. Search for short, unique substrings. Use the workspace parameter to search external workspaces.',
+        description: 'Search for a text pattern across files in the workspace. Returns matching file paths with line numbers and content snippets. Uses Extended Regular Expressions (grep -E) by default, or fixed strings (grep -F) if fixedStrings is true. IMPORTANT: grep searches line-by-line. Do NOT search for long lists of Tailwind classes or multi-line strings, as they will fail if line-wrapped. Search for short, unique substrings. Use the workspace parameter to search external workspaces.',
         parameters: {
             type: SchemaType.OBJECT,
             properties: {
@@ -186,6 +209,14 @@ export const toolDeclarations = [
                     type: SchemaType.STRING,
                     description: 'Optional glob to restrict file types, e.g. "*.ts" or "*.py". Defaults to all files.',
                 },
+                fixedStrings: {
+                    type: SchemaType.BOOLEAN,
+                    description: 'Optional. If true, treats the pattern as a fixed string instead of a regular expression (grep -F). Useful for searching code containing regex special characters.',
+                },
+                dirPath: {
+                    type: SchemaType.STRING,
+                    description: 'Optional. The directory path to restrict the search to, relative to the workspace root. Defaults to the workspace root.',
+                },
                 workspace: {
                     type: SchemaType.STRING,
                     description: 'Optional. Workspace alias to search in (e.g., "backend"), or "all" to search all registered workspaces. Defaults to the primary workspace.',
@@ -297,16 +328,36 @@ export const toolDeclarations = [
     },
 ];
 let currentApprovalMode = 'ask';
+/**
+ * Retrieves the current command execution approval mode.
+ *
+ * @returns The active {@link ApprovalMode}.
+ */
 export function getApprovalMode() {
     return currentApprovalMode;
 }
+/**
+ * Sets the command execution approval mode.
+ *
+ * @param mode - The {@link ApprovalMode} to set.
+ */
 export function setApprovalMode(mode) {
     currentApprovalMode = mode;
 }
 let subAgentsEnabled = true;
+/**
+ * Checks whether sub-agents are currently enabled.
+ *
+ * @returns `true` if sub-agents are enabled, `false` otherwise.
+ */
 export function isSubAgentsEnabled() {
     return subAgentsEnabled;
 }
+/**
+ * Enables or disables sub-agents.
+ *
+ * @param enabled - Boolean indicating whether sub-agents should be enabled.
+ */
 export function setSubAgentsEnabled(enabled) {
     subAgentsEnabled = enabled;
 }
@@ -347,6 +398,9 @@ const DEFAULT_IGNORED_FILES = new Set([
 ]);
 /**
  * Parses .gitignore and .minovativemindignore to supplement the default ignore lists.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @returns An object containing `ignoredDirs` (Set), `ignoredFiles` (Set), and `ig` (ignore instance).
  */
 async function getIgnoredPaths(workspaceRoot) {
     const ignoredDirs = new Set(DEFAULT_IGNORED_DIRS);
@@ -378,6 +432,18 @@ async function getIgnoredPaths(workspaceRoot) {
     return { ignoredDirs, ignoredFiles, ig };
 }
 // ─── Tool Implementations ────────────────────────────────────────────
+/**
+ * Reads the contents of a file at the given relative or absolute path, supporting text files,
+ * native PDF parsing, SQLite database schema dumping, Jupyter Notebook (.ipynb) cell extraction,
+ * and CSV-to-Markdown table formatting.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the target file (or `@alias/` prefixed path).
+ * @param startLine - Optional 1-indexed starting line number.
+ * @param endLine - Optional 1-indexed ending line number.
+ * @param targetElements - Optional array of specific symbol or function names to extract.
+ * @returns A promise resolving to a {@link ToolResult} containing the file content or error details.
+ */
 export async function readFile(workspaceRoot, filePath, startLine, endLine, targetElements) {
     try {
         const absPath = resolveAndValidatePath(workspaceRoot, filePath);
@@ -573,7 +639,7 @@ export async function readFile(workspaceRoot, filePath, startLine, endLine, targ
         }
         const attrLines = startLine || endLine ? ` lines="${startLine || 1}-${endLine || 'end'}"` : '';
         const attrTargets = targetElements && targetElements.length > 0 ? ` elements="${targetElements.join(',')}"` : '';
-        const wrappedContent = `<workspace_file path="${filePath}"${attrLines}${attrTargets}>\n<content_data><![CDATA[\n${sanitizeForCDATA(content)}\n]]></content_data>\n</workspace_file>`;
+        const wrappedContent = `<workspace_file path="${filePath}"${attrLines}${attrTargets}>\n<content_data><![CDATA[\n${sanitizeForCDATA(content)}\n]]\\u200B></content_data>\n</workspace_file>`;
         return { output: wrappedContent };
     }
     catch (err) {
@@ -581,6 +647,15 @@ export async function readFile(workspaceRoot, filePath, startLine, endLine, targ
         return { output: '', error: `Failed to read file "${filePath}": ${message}` };
     }
 }
+/**
+ * Creates a new file or completely overwrites an existing file with the provided content,
+ * performing local syntax validation and iterative AI syntax auto-correction if validation fails.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the target file.
+ * @param content - The complete content to write.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export async function writeFile(workspaceRoot, filePath, content) {
     try {
         const absPath = resolveAndValidatePath(workspaceRoot, filePath);
@@ -640,6 +715,13 @@ export async function writeFile(workspaceRoot, filePath, content) {
         };
     }
 }
+/**
+ * Deletes a file from the filesystem and records the deletion in the change logger.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the file to delete.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export async function deleteFile(workspaceRoot, filePath) {
     try {
         const absPath = resolveAndValidatePath(workspaceRoot, filePath);
@@ -659,6 +741,14 @@ export async function deleteFile(workspaceRoot, filePath) {
         return { output: '', error: `Failed to delete file "${filePath}": ${message}` };
     }
 }
+/**
+ * Moves or renames a file from `sourcePath` to `targetPath`.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param sourcePath - Original relative file path.
+ * @param targetPath - New destination relative file path.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export async function renameFile(workspaceRoot, sourcePath, targetPath) {
     try {
         const absSource = resolveAndValidatePath(workspaceRoot, sourcePath);
@@ -683,6 +773,15 @@ export async function renameFile(workspaceRoot, sourcePath, targetPath) {
         return { output: '', error: `Failed to move/rename file: ${message}` };
     }
 }
+/**
+ * Performs one or multiple targeted search-and-replace edits on a file, utilizing deterministic fuzzy matching,
+ * fallback AI fuzzy matching, syntax validation, and atomic writes.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the target file.
+ * @param edits - An array of edit objects containing `searchContent` and `replaceContent`.
+ * @returns A promise resolving to a {@link ToolResult} indicating success or failure.
+ */
 export async function modifyFile(workspaceRoot, filePath, edits) {
     const MAX_MODIFY_RETRIES = 4;
     const absPath = resolveAndValidatePath(workspaceRoot, filePath);
@@ -691,6 +790,7 @@ export async function modifyFile(workspaceRoot, filePath, edits) {
             const existing = await fs.readFile(absPath, 'utf-8');
             let modified = existing;
             const strategies = [];
+            const appliedEdits = [];
             for (let i = 0; i < edits.length; i++) {
                 const edit = edits[i];
                 const match = findBestMatch(modified, edit.searchContent);
@@ -703,15 +803,29 @@ export async function modifyFile(workspaceRoot, filePath, edits) {
                         modified = existing; // reset
                         break;
                     }
+                    // Fall back to AI fuzzy search matching when deterministic findBestMatch fails after retries
+                    const aiResult = await aiFuzzyMatch(modified, edit.searchContent, edit.replaceContent, filePath);
+                    if (aiResult.success && aiResult.content) {
+                        modified = aiResult.content;
+                        strategies.push(`Edit #${i + 1}: AI Fuzzy Match`);
+                        appliedEdits.push({ index: i + 1, line: -1, strategy: 'AI Fuzzy Match' });
+                        continue;
+                    }
                     // Provide a preview of the file to help the AI self-correct
                     const preview = modified.split('\n').slice(0, 30).join('\n');
+                    const priorEditsSummary = appliedEdits.length > 0
+                        ? `\nPrior applied edits before failure:\n` + appliedEdits.map((e) => `  - Edit #${e.index}: Line ${e.line === -1 ? 'N/A' : e.line} (${e.strategy})`).join('\n') + '\n'
+                        : '';
                     return {
                         output: '',
-                        error: `Edit #${i + 1} failed: Search content not found in "${filePath}". Please call 'read_file' to check the exact lines of code before retrying modify_file.\n\nFile start preview:\n${preview}\n...`,
+                        error: `Edit #${i + 1} failed: Search content not found in "${filePath}".${priorEditsSummary}\n` +
+                            `Actionable guidance: Ensure searchContent contains sufficient unique context (e.g. 5-10 surrounding lines) to match distinctly. Call 'read_file' to examine the latest file contents before retrying.\n\nFile start preview:\n${preview}\n...`,
                     };
                 }
+                const matchLine = modified.slice(0, match.start).split('\n').length;
                 modified = applyMatch(modified, match, edit.replaceContent);
-                strategies.push(`Edit #${i + 1}: ${match.strategy}`);
+                strategies.push(`Edit #${i + 1}: Line ${matchLine} (${match.strategy})`);
+                appliedEdits.push({ index: i + 1, line: matchLine, strategy: match.strategy });
                 const collector = getMetricCollector();
                 if (collector) {
                     if (match.strategy.startsWith('Exact Match')) {
@@ -741,22 +855,29 @@ export async function modifyFile(workspaceRoot, filePath, edits) {
                 let success = false;
                 while (attempts < MAX_RETRIES && !success) {
                     attempts++;
-                    const fixed = await validateAndFixSyntax(finalModified, filePath);
+                    const fixed = await validateAndFixSyntax(finalModified, filePath, localResult.error);
                     if (fixed) {
                         finalModified = fixed;
                         const recheck = localValidate(filePath, finalModified);
                         if (recheck.isValid) {
                             success = true;
                         }
+                        else {
+                            localResult = recheck;
+                        }
                     }
                     else {
                         break;
                     }
                 }
                 if (!success) {
+                    const appliedSummary = appliedEdits.length > 0
+                        ? `\nApplied edit details:\n` + appliedEdits.map((e) => `  - Edit #${e.index}: Line ${e.line === -1 ? 'N/A' : e.line} (${e.strategy})`).join('\n')
+                        : '';
                     return {
                         output: '',
-                        error: `Syntax validation failed after ${attempts} attempts: ${localResult.error || 'Unknown syntax error'}`,
+                        error: `Syntax validation failed after ${attempts} attempts: ${localResult.error || 'Unknown syntax error'}${appliedSummary}\n` +
+                            `Actionable guidance: A search block may have matched at an incorrect line due to non-unique search context in a large file. Re-examine the target file with 'read_file' and provide a searchContent block with more unique surrounding lines (e.g. 5-10 lines of distinct context).`,
                     };
                 }
             }
@@ -779,6 +900,15 @@ export async function modifyFile(workspaceRoot, filePath, edits) {
     }
     return { output: '', error: 'Modify failed.' };
 }
+/**
+ * Lists files and subdirectories within a directory, returning a recursive ASCII tree structure
+ * while respecting ignore rules and excluded extensions.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param dirPath - Relative path to the target directory.
+ * @param maxDepth - Maximum recursion depth (defaults to 3).
+ * @returns A promise resolving to a {@link ToolResult} containing the formatted tree output.
+ */
 export async function listDirectory(workspaceRoot, dirPath, maxDepth = 3) {
     try {
         const absPath = resolveAndValidatePath(workspaceRoot, dirPath);
@@ -833,11 +963,19 @@ export async function listDirectory(workspaceRoot, dirPath, maxDepth = 3) {
         };
     }
 }
+/**
+ * Executes a shell command within the workspace root with a timeout and buffer limit.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param command - The shell command string to execute.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing stdout/stderr or an error.
+ */
 export async function runCommand(workspaceRoot, command, abortSignal) {
     try {
         const { stdout, stderr } = await execAsync(command, {
             cwd: workspaceRoot,
-            timeout: 120_000, // 120 secgot these ond timeout
+            timeout: 120_000, // 120 second timeout
             maxBuffer: 1024 * 1024 * 2, // 2 MB buffer
             signal: abortSignal,
         });
@@ -862,45 +1000,38 @@ export async function runCommand(workspaceRoot, command, abortSignal) {
         return { output: '', error: `Command failed: ${truncatedMsg}` };
     }
 }
-export async function grepSearch(workspaceRoot, pattern, fileGlob, abortSignal) {
+/**
+ * Performs a grep text or regular expression search across files in the workspace.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param pattern - The search text or regex pattern.
+ * @param fileGlob - Optional file glob to restrict matched files.
+ * @param fixedStrings - If true, treats the pattern as a literal fixed string.
+ * @param dirPath - Optional subdirectory path to restrict the search.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing matching lines and file paths.
+ */
+export async function grepSearch(workspaceRoot, pattern, fileGlob, fixedStrings, dirPath, abortSignal) {
     try {
-        const { ignoredDirs, ig } = await getIgnoredPaths(workspaceRoot);
-        if (os.platform() !== 'win32') {
-            const excludeDirArgs = Array.from(ignoredDirs)
-                .map((dir) => `--exclude-dir="${dir}"`)
-                .concat('--exclude-dir=".*"') // Exclude all hidden directories
-                .join(' ');
-            const excludeFileArgs = EXCLUDED_EXTENSIONS.map((ext) => `--exclude="${ext}"`)
-                .concat('--exclude=".*"') // Exclude all hidden files
-                .join(' ');
-            // Build a grep command that works cross-platform via node
-            // We use grep -rnIEi for recursive, line numbers, skip binary, extended regex, case-insensitive
-            const globArg = fileGlob ? ` --include="${fileGlob}"` : '';
-            const cmd = `grep -rnIEi --color=never ${excludeDirArgs} ${excludeFileArgs}${globArg} "${pattern.replace(/"/g, '\\"')}" .`;
-            const { stdout } = await execAsync(cmd, {
-                cwd: workspaceRoot,
-                timeout: 15_000,
-                maxBuffer: 1024 * 1024 * 2,
-                signal: abortSignal,
-            });
-            // Limit output to 50 results
-            const lines = stdout.trim().split('\n');
-            const limited = lines.slice(0, 50);
-            const resultText = limited.join('\n') + (lines.length > 50 ? `\n\n... (${lines.length - 50} more results truncated)` : '');
-            if (!resultText)
-                return { output: `No matches found for "${pattern}".` };
-            const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]></content_data>\n</workspace_file>`;
-            return { output: wrappedResult };
+        const { ig } = await getIgnoredPaths(workspaceRoot);
+        // Node.js cross-platform implementation
+        // This avoids shell injection risks and correctly supports path globs via 'ignore' package.
+        const finalPattern = fixedStrings ? pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : pattern;
+        let regexPattern;
+        try {
+            regexPattern = new RegExp(finalPattern, 'gi');
+        }
+        catch (err) {
+            return { output: `Invalid search pattern: ${err.message}` };
         }
-        // Node.js fallback for Windows
-        const regexPattern = new RegExp(pattern, 'gi'); // Emulate grep -i and global match
-        const globPattern = fileGlob
-            ? new RegExp('^' + fileGlob.replace(/\./g, '\\.').replace(/\*/g, '.*') + '$', 'i')
-            : null;
+        // Use ignore package to evaluate path globs (e.g. src/**/*.ts)
+        const globMatcher = fileGlob ? ignore().add(fileGlob) : null;
         const results = [];
         async function walk(dir) {
             if (results.length >= 50)
                 return;
+            if (abortSignal?.aborted)
+                return;
             let entries;
             try {
                 entries = await fs.readdir(dir, { withFileTypes: true });
@@ -911,11 +1042,14 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, abortSignal)
             for (const entry of entries) {
                 if (results.length >= 50)
                     return;
+                if (abortSignal?.aborted)
+                    return;
                 if (entry.name.startsWith('.'))
                     continue;
                 const entryPath = path.join(dir, entry.name);
                 const relPath = path.relative(workspaceRoot, entryPath).replace(/\\/g, '/');
                 if (entry.isDirectory()) {
+                    // Check if directory is ignored by .gitignore
                     if (ig.ignores(relPath + '/'))
                         continue;
                     await walk(entryPath);
@@ -925,7 +1059,8 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, abortSignal)
                         continue;
                     if (EXCLUDED_EXTENSIONS.some((ext) => entry.name.endsWith(ext.replace('*', ''))))
                         continue;
-                    if (globPattern && !globPattern.test(entry.name))
+                    // If a fileGlob was provided, verify this path matches the glob (i.e. 'ignore' would ignore it)
+                    if (globMatcher && !globMatcher.ignores(relPath))
                         continue;
                     try {
                         const filePath = path.join(dir, entry.name);
@@ -936,8 +1071,8 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, abortSignal)
                                 break;
                             regexPattern.lastIndex = 0;
                             if (regexPattern.test(lines[i])) {
-                                const relPath = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
-                                results.push(`${relPath}:${i + 1}:${lines[i]}`);
+                                const relativePath = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+                                results.push(`${relativePath}:${i + 1}:${lines[i]}`);
                             }
                         }
                     }
@@ -947,36 +1082,38 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, abortSignal)
                 }
             }
         }
-        await walk(workspaceRoot);
+        const searchRoot = dirPath ? path.resolve(workspaceRoot, dirPath) : workspaceRoot;
+        await walk(searchRoot);
+        if (abortSignal?.aborted) {
+            return { output: '', error: 'Grep search aborted by user.' };
+        }
         if (results.length === 0)
             return { output: `No matches found for "${pattern}".` };
         const resultText = results.join('\n') + (results.length >= 50 ? `\n\n... (more results truncated)` : '');
-        const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]></content_data>\n</workspace_file>`;
+        const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]\\u200B></content_data>\n</workspace_file>`;
         return { output: wrappedResult };
     }
     catch (err) {
-        if (err instanceof Error && 'code' in err && err.code === 1) {
-            return { output: `No matches found for "${pattern}".` };
-        }
-        if (err instanceof Error && err.name === 'AbortError') {
-            return { output: '', error: 'Grep search aborted by user.' };
-        }
         const message = err instanceof Error ? err.message : String(err);
-        // Also handle stringified exit codes just in case
-        if (message.includes('Command failed') &&
-            (message.includes('exit code 1') || message.includes('exited with code 1'))) {
-            return { output: `No matches found for "${pattern}".` };
-        }
-        return { output: '', error: `Grep failed: ${message}` };
+        return { output: '', error: `Grep search failed: ${message}` };
     }
 }
+/**
+ * Traces file dependencies (forward imports and reverse dependants) to determine the blast radius of changes.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param filePath - Relative path to the file to trace.
+ * @param direction - Trace direction (`'both'`, `'forward'`, or `'reverse'`).
+ * @param maxDepth - Maximum recursion depth (defaults to 3).
+ * @returns A promise resolving to a {@link ToolResult} containing formatted dependency results.
+ */
 export async function traceDependencies(workspaceRoot, filePath, direction, maxDepth) {
     try {
         const dir = direction === 'forward' || direction === 'reverse' ? direction : 'both';
         const depth = maxDepth && maxDepth > 0 ? Math.min(maxDepth, 5) : 3;
         const result = await findDependencies(workspaceRoot, filePath, dir, depth);
         const formatted = formatDependencyResult(result);
-        const wrappedResult = `<workspace_file path="dependency_trace_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(formatted)}\n]]></content_data>\n</workspace_file>`;
+        const wrappedResult = `<workspace_file path="dependency_trace_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(formatted)}\n]]\\u200B></content_data>\n</workspace_file>`;
         return { output: wrappedResult };
     }
     catch (err) {
@@ -984,6 +1121,15 @@ export async function traceDependencies(workspaceRoot, filePath, direction, maxD
         return { output: '', error: `Dependency tracing failed for "${filePath}": ${message}` };
     }
 }
+/**
+ * Finds files modified within the workspace recently (within a specified time window).
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param dirPath - Subdirectory path to search from (defaults to `'.'`).
+ * @param minutes - Time window in minutes (defaults to 60).
+ * @param maxDepth - Maximum directory traversal depth (defaults to 5).
+ * @returns A promise resolving to a {@link ToolResult} containing recently modified files.
+ */
 export async function findRecentChanges(workspaceRoot, dirPath = '.', minutes = 60, maxDepth = 5) {
     try {
         const absPath = resolveAndValidatePath(workspaceRoot, dirPath);
@@ -1041,7 +1187,7 @@ export async function findRecentChanges(workspaceRoot, dirPath = '.', minutes =
             return `- ${f.path} (${minsAgo} minutes ago)`;
         });
         const resultText = `Files modified in the last ${minutes} minutes:\n${lines.join('\n')}`;
-        const wrappedResult = `<workspace_file path="recent_changes">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]></content_data>\n</workspace_file>`;
+        const wrappedResult = `<workspace_file path="recent_changes">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]\\u200B></content_data>\n</workspace_file>`;
         return { output: wrappedResult };
     }
     catch (err) {
@@ -1053,6 +1199,16 @@ export async function findRecentChanges(workspaceRoot, dirPath = '.', minutes =
     }
 }
 // ─── Tool Dispatcher ─────────────────────────────────────────────────
+/**
+ * Writes a disposable scratchpad script to a temporary file, executes it using the specified runtime,
+ * and returns standard output and standard error.
+ *
+ * @param workspaceRoot - Absolute path to the workspace root directory.
+ * @param language - Runtime language (`'node'`, `'ts-node'`, `'python'`, `'bash'`, `'go'`, or `'rust'`).
+ * @param code - The exact script source code to execute.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing execution output.
+ */
 export async function runDebugScript(workspaceRoot, language, code, abortSignal) {
     const extMap = {
         node: '.js',
@@ -1144,6 +1300,11 @@ export async function runDebugScript(workspaceRoot, language, code, abortSignal)
 /**
  * Resolves `@alias/` prefixed paths in tool arguments to the correct workspace root
  * and relative path. Returns the effective workspaceRoot and the cleaned arguments.
+ *
+ * @param primaryRoot - Absolute path to the primary workspace root.
+ * @param toolName - Name of the tool being executed.
+ * @param args - Tool arguments object.
+ * @returns An object containing `effectiveRoot` and `resolvedArgs`.
  */
 function resolveWorkspaceArgs(primaryRoot, toolName, args) {
     // Only resolve if workspaces are registered
@@ -1183,12 +1344,20 @@ function resolveWorkspaceArgs(primaryRoot, toolName, args) {
 /**
  * Runs grep across all registered workspaces (primary + external) and merges results.
  * Results from external workspaces are prefixed with @alias/ for disambiguation.
+ *
+ * @param primaryRoot - Absolute path to the primary workspace root.
+ * @param pattern - The search text or regex pattern.
+ * @param fileGlob - Optional file glob restriction.
+ * @param fixedStrings - If true, treats the pattern as a literal fixed string.
+ * @param dirPath - Optional subdirectory restriction.
+ * @param abortSignal - Optional AbortSignal to cancel execution.
+ * @returns A promise resolving to a {@link ToolResult} containing merged search results.
  */
-async function crossWorkspaceGrep(primaryRoot, pattern, fileGlob, abortSignal) {
+async function crossWorkspaceGrep(primaryRoot, pattern, fileGlob, fixedStrings, dirPath, abortSignal) {
     const allRoots = workspaceRegistry.getAllRoots(primaryRoot);
     const allResults = [];
     for (const { alias, root } of allRoots) {
-        const result = await grepSearch(root, pattern, fileGlob, abortSignal);
+        const result = await grepSearch(root, pattern, fileGlob, fixedStrings, dirPath, abortSignal);
         if (result.error)
             continue;
         // Extract the raw text from the XML wrapper
@@ -1214,10 +1383,20 @@ async function crossWorkspaceGrep(primaryRoot, pattern, fileGlob, abortSignal) {
     }
     const limited = allResults.slice(0, 80);
     const resultText = limited.join('\n') + (allResults.length > 80 ? `\n\n... (${allResults.length - 80} more results truncated)` : '');
-    const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]></content_data>\n</workspace_file>`;
+    const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(resultText)}\n]]\\u200B></content_data>\n</workspace_file>`;
     return { output: wrappedResult };
 }
 const currentTasksByAgent = new Map();
+/**
+ * Central tool dispatcher that resolves multi-workspace paths, executes the requested tool
+ * with the provided arguments, records metrics, and returns the standardized {@link ToolResult}.
+ *
+ * @param workspaceRoot - Absolute path to the primary workspace root directory.
+ * @param toolName - Name of the tool to invoke.
+ * @param args - Key-value map of tool arguments.
+ * @param abortSignal - Optional AbortSignal to cancel tool execution.
+ * @returns A promise resolving to a {@link ToolResult}.
+ */
 export async function executeTool(workspaceRoot, toolName, args, abortSignal) {
     // ─── Multi-Workspace Path Resolution ─────────────────────────────
     // Intercept @alias/ prefixed paths and swap workspaceRoot + relative path
@@ -1225,6 +1404,19 @@ export async function executeTool(workspaceRoot, toolName, args, abortSignal) {
     const { effectiveRoot, resolvedArgs } = resolveWorkspaceArgs(workspaceRoot, toolName, args);
     let result;
     switch (toolName) {
+        case 'perform_web_search': {
+            const { createWebSearchAgentSession } = await import('./ai.js');
+            const webSession = createWebSearchAgentSession();
+            try {
+                const webResult = await webSession.sendMessage(`Please search the web for the following query and summarize your findings:\n"${resolvedArgs.query}"`, undefined, abortSignal);
+                const searchSummary = webResult.response.text()?.trim() || 'No relevant information found.';
+                result = { output: `Web Search Findings:\n${searchSummary}` };
+            }
+            catch (e) {
+                result = { error: e.message || 'Failed to search the web', output: '' };
+            }
+            break;
+        }
         case 'read_file':
             result = await readFile(effectiveRoot, resolvedArgs.filePath, resolvedArgs.startLine, resolvedArgs.endLine, resolvedArgs.targetElements);
             break;
@@ -1317,15 +1509,15 @@ export async function executeTool(workspaceRoot, toolName, args, abortSignal) {
             const wsParam = resolvedArgs.workspace;
             if (wsParam === 'all') {
                 // Cross-workspace search across all registered workspaces
-                result = await crossWorkspaceGrep(workspaceRoot, resolvedArgs.pattern, resolvedArgs.fileGlob, abortSignal);
+                result = await crossWorkspaceGrep(workspaceRoot, resolvedArgs.pattern, resolvedArgs.fileGlob, resolvedArgs.fixedStrings, resolvedArgs.dirPath, abortSignal);
             }
             else if (wsParam && workspaceRegistry.get(wsParam)) {
                 // Search in a specific external workspace
                 const ws = workspaceRegistry.get(wsParam);
-                result = await grepSearch(ws.absolutePath, resolvedArgs.pattern, resolvedArgs.fileGlob, abortSignal);
+                result = await grepSearch(ws.absolutePath, resolvedArgs.pattern, resolvedArgs.fileGlob, resolvedArgs.fixedStrings, resolvedArgs.dirPath, abortSignal);
             }
             else {
-                result = await grepSearch(effectiveRoot, resolvedArgs.pattern, resolvedArgs.fileGlob, abortSignal);
+                result = await grepSearch(effectiveRoot, resolvedArgs.pattern, resolvedArgs.fileGlob, resolvedArgs.fixedStrings, resolvedArgs.dirPath, abortSignal);
             }
             break;
         }