minovative-mind-cli 2.14.1 → 2.14.3

package/dist/services/agent-tools.d.ts

@@ -25,15 +25,18 @@ export interface ToolResult {
         mimeType: string;
         data: string;
     };
+    /** Optional structured JSON result extracted from the script execution. */
+    structuredResult?: unknown;
 }
 /**
  * Returns the list of available function declarations for Gemini function calling.
  *
- * @param options - Configuration options such as `isExecutionAgent`.
+ * @param options - Configuration options such as `isExecutionAgent` or `isResearchAgent`.
  * @returns An array of Google Generative AI `FunctionDeclaration` objects.
  */
 export declare function getToolDeclarations(options?: {
     isExecutionAgent?: boolean;
+    isResearchAgent?: boolean;
 }): FunctionDeclaration[];
 /**
  * FunctionDeclaration-compatible schema objects that describe
@@ -138,6 +141,22 @@ export declare function modifyFile(workspaceRoot: string, filePath: string, edit
  * @returns A promise resolving to a {@link ToolResult} containing the formatted tree output.
  */
 export declare function listDirectory(workspaceRoot: string, dirPath: string, maxDepth?: number): Promise<ToolResult>;
+/**
+ * Truncates large string output using bounded head and tail windows with a structured metadata receipt.
+ * Preserves early context (e.g. invocation, build targets) and late context (e.g. error summaries, exit codes)
+ * while bounding total character and line count.
+ *
+ * @param text - The raw output text to truncate.
+ * @param options - Configuration options for character/line limits and custom receipt notices.
+ * @returns The windowed text containing head, structured metadata receipt, and tail.
+ */
+export declare function truncateWithHeadTailWindow(text: string, options?: {
+    maxChars?: number;
+    maxLines?: number;
+    headRatio?: number;
+    receiptLabel?: string;
+    hint?: string;
+}): string;
 /**
  * Condenses verbose command and test failure outputs into high-signal diagnostic error logs
  * with dynamic tail sizing and stack trace boundary snapping.

package/dist/services/agent-tools.js

@@ -23,13 +23,15 @@ import { findBestMatch, applyMatch } from '../utils/fuzzyMatch.js';
 import { localValidate } from '../utils/localSyntaxValidator.js';
 import { validateAndFixSyntax, aiFuzzyMatch } from './agent/syntaxAgent.js';
 import { sanitizeForCDATA } from '../utils/contextPrompts.js';
-import { findDependencies, formatDependencyResult } from '../utils/dependencyTracer.js';
+import { findDependencies, formatDependencyResult, invalidateDependencyGraph } from '../utils/dependencyTracer.js';
 import { atomicWriteFile } from '../utils/atomicWrite.js';
 import { EXCLUDED_EXTENSIONS } from '../utils/excludedExtensions.js';
 import { extractSymbols } from '../utils/symbolExtractor.js';
 import { getMetricCollector, recordRecoveryPrunedLogVolume } from './metrics.js';
 import { getCurrentAgentId } from '../utils/asyncContext.js';
 import { recordFileRead, hasAgentReadFile } from '../utils/fileReadGuard.js';
+import { getCachedFileContent, invalidateFileReadCache, clearFileReadCache } from '../utils/fileReadCache.js';
+import { detectAntiCheatingViolations, isCriticalConfigFile } from '../utils/antiCheatingGuard.js';
 import { runFuzzProbe, checkHeapDelta as runCheckHeapDelta, checkBehavioralDrift as runCheckBehavioralDrift, runEphemeralScript, } from '../utils/analysisRunner.js';
 import ignore from 'ignore';
 const execAsync = promisify(exec);
@@ -37,13 +39,24 @@ const execAsync = promisify(exec);
 /**
  * Returns the list of available function declarations for Gemini function calling.
  *
- * @param options - Configuration options such as `isExecutionAgent`.
+ * @param options - Configuration options such as `isExecutionAgent` or `isResearchAgent`.
  * @returns An array of Google Generative AI `FunctionDeclaration` objects.
  */
 export function getToolDeclarations(options) {
     if (options?.isExecutionAgent) {
         return toolDeclarations;
     }
+    if (options?.isResearchAgent) {
+        const excludedForResearch = new Set([
+            'modify_file',
+            'write_file',
+            'delete_file',
+            'rename_file',
+            'create_todo_list',
+            'update_todo_status',
+        ]);
+        return toolDeclarations.filter((tool) => !excludedForResearch.has(tool.name));
+    }
     return toolDeclarations.filter((tool) => tool.name !== 'create_todo_list' && tool.name !== 'update_todo_status' && tool.name !== 'finish_task');
 }
 /**
@@ -278,11 +291,15 @@ export const toolDeclarations = [
     },
     {
         name: 'run_debug_script',
-        description: 'Write a disposable script to a sandboxed temporary file in os.tmpdir(), execute it using the specified runtime, and return the exact standard output and standard error without polluting the workspace or triggering IDE file watchers. ' +
-            'Use this to: (1) actively debug the codebase by inspecting variables or logging values, ' +
-            '(2) validate your changes by importing the modified module and asserting expected behavior with edge-case inputs, ' +
-            '(3) run quick sanity checks (e.g., verify a config file parses correctly, confirm exports are intact after a refactor, or check that a function returns the expected output), ' +
-            '(4) write lightweight ML scripts to solve complex problems — e.g., polynomial regression to estimate Big-O complexity, fuzz testing with Markov chain input generation, ' +
+        description: 'Write a disposable script to a sandboxed temporary file in os.tmpdir(), execute it using the specified runtime, and return the exact standard output, structured JSON result, and standard error without polluting the workspace or triggering IDE file watchers. ' +
+            'Sandbox Features: ' +
+            '(1) Preloaded Helpers: "emitResult(data)" / "__emitResult(data)" outputs structured JSON payloads parsed directly into structuredResult; "inspectSymbols(target)" / "inspectObject(target)" inspects functions, classes, and properties. ' +
+            '(2) Module & Path Resolution: Automatically inherits tsconfig.json path aliases (@/*), NODE_PATH, and workspace virtualenvs (.venv, venv) for Python. ' +
+            '(3) Diagnostics Middleware: Provides actionable [SANDBOX DIAGNOSTIC] advisories for missing imports, ESM/CJS interop, and compiler errors. ' +
+            'Use this to: (a) actively debug the codebase by inspecting variables or logging values, ' +
+            '(b) validate your changes by importing the modified module and asserting expected behavior with edge-case inputs, ' +
+            '(c) run quick sanity checks (e.g., verify a config file parses correctly, confirm exports are intact after a refactor, or check that a function returns the expected output), ' +
+            '(d) write lightweight ML scripts to solve complex problems — e.g., polynomial regression to estimate Big-O complexity, fuzz testing with Markov chain input generation, ' +
             'output regression detection via statistical similarity scoring, or error message classification with Naive Bayes. ' +
             'Default to "node" for generic tasks as a safe baseline, but act like a native inhabitant of the host environment — if Python, Go, Rust, or host-native libraries are active in the project, leverage the host\'s native runtimes for maximum efficiency. ' +
             'Do not guess whether your code works — test it directly!',
@@ -622,7 +639,7 @@ export async function readFile(workspaceRoot, filePath, startLine, endLine, targ
                 };
             }
         }
-        let content = await fs.readFile(absPath, 'utf-8');
+        let content = await getCachedFileContent(absPath);
         // Handle Jupyter Notebooks natively
         if (filePath.toLowerCase().endsWith('.ipynb')) {
             try {
@@ -825,9 +842,15 @@ export async function writeFile(workspaceRoot, filePath, content) {
                 };
             }
         }
+        const antiCheatError = detectAntiCheatingViolations(filePath, finalContent, existingContent ?? undefined);
+        if (antiCheatError) {
+            return { output: '', error: antiCheatError };
+        }
         await fs.mkdir(path.dirname(absPath), { recursive: true });
         changeLogger.logChange(filePath, existingContent, existingContent !== null ? 'modify' : 'create');
         await atomicWriteFile(absPath, finalContent, 'utf-8');
+        invalidateFileReadCache(absPath);
+        invalidateDependencyGraph(workspaceRoot);
         return { output: `Successfully wrote to "${filePath}".` };
     }
     catch (err) {
@@ -850,6 +873,12 @@ export async function writeFile(workspaceRoot, filePath, content) {
  */
 export async function deleteFile(workspaceRoot, filePath) {
     try {
+        if (isCriticalConfigFile(filePath)) {
+            return {
+                output: '',
+                error: `Anti-cheating violation: Deleting critical configuration file "${filePath}" is strictly prohibited. You must fix all build, compiler, type, and lint errors head-on in the source code.`,
+            };
+        }
         const absPath = resolveAndValidatePath(workspaceRoot, filePath);
         let existingContent = null;
         try {
@@ -860,6 +889,8 @@ export async function deleteFile(workspaceRoot, filePath) {
         }
         changeLogger.logChange(filePath, existingContent, 'delete');
         await fs.rm(absPath, { force: true });
+        invalidateFileReadCache(absPath);
+        invalidateDependencyGraph(workspaceRoot);
         return { output: `Successfully deleted "${filePath}".` };
     }
     catch (err) {
@@ -877,6 +908,12 @@ export async function deleteFile(workspaceRoot, filePath) {
  */
 export async function renameFile(workspaceRoot, sourcePath, targetPath) {
     try {
+        if (isCriticalConfigFile(sourcePath)) {
+            return {
+                output: '',
+                error: `Anti-cheating violation: Moving or renaming critical configuration file "${sourcePath}" is strictly prohibited. You must fix all build, compiler, type, and lint errors head-on in the source code.`,
+            };
+        }
         const absSource = resolveAndValidatePath(workspaceRoot, sourcePath);
         const absTarget = resolveAndValidatePath(workspaceRoot, targetPath);
         let existingContent = null;
@@ -892,6 +929,9 @@ export async function renameFile(workspaceRoot, sourcePath, targetPath) {
         changeLogger.logChange(targetPath, null, 'create');
         await fs.mkdir(path.dirname(absTarget), { recursive: true });
         await fs.rename(absSource, absTarget);
+        invalidateFileReadCache(absSource);
+        invalidateFileReadCache(absTarget);
+        invalidateDependencyGraph(workspaceRoot);
         return { output: `Successfully moved/renamed "${sourcePath}" to "${targetPath}".` };
     }
     catch (err) {
@@ -1014,10 +1054,16 @@ export async function modifyFile(workspaceRoot, filePath, edits) {
                     };
                 }
             }
+            const antiCheatError = detectAntiCheatingViolations(filePath, finalModified, existing);
+            if (antiCheatError) {
+                return { output: '', error: antiCheatError };
+            }
             changeLogger.logChange(filePath, existing, 'modify');
             await atomicWriteFile(absPath, finalModified, 'utf-8');
+            invalidateFileReadCache(absPath);
+            invalidateDependencyGraph(workspaceRoot);
             return {
-                output: `Successfully applied ${edits.length} edit(s) to "${filePath}".\\nStrategies used:\\n${strategies.join('\\n')}`,
+                output: `Successfully applied ${edits.length} edit(s) to "${filePath}".\nStrategies used:\n${strategies.join('\n')}`,
             };
         }
         catch (err) {
@@ -1124,6 +1170,7 @@ const HIGH_SIGNAL_ERROR_PATTERNS = [
     /undefined reference/i,
     /ld: symbol\(s\) not found/i,
     /clang: error:/i,
+    /gcc: error:/i,
     /referenced from:/i,
     /note: expanded from macro/i,
     /note: candidate:/i,
@@ -1133,29 +1180,59 @@ const HIGH_SIGNAL_ERROR_PATTERNS = [
     /TypeError:/i,
     /ImportError:/i,
     /ModuleNotFoundError:/i,
+    /AttributeError:/i,
+    /IndexError:/i,
+    /KeyError:/i,
+    /ValueError:/i,
     /FAILED \(failures=/i,
     /\bE\s{3}\b/,
     /\bFAIL\b/,
-    // Node.js / TypeScript / Jest / Mocha
+    /\bFAILED\b/,
+    /=== FAILURES ===/i,
+    /=== ERRORS ===/i,
+    // Sandbox Diagnostics & Structured Results
+    /\[SANDBOX DIAGNOSTIC\]/i,
+    /\[STRUCTURED RESULT\]/i,
+    /Module resolution failure/i,
+    /CommonJS require\(\) attempted to load an ES Module/i,
+    // Node.js / TypeScript / Jest / Mocha / Vitest
+    /TS\d+:/i,
+    /TS\d{4,5}:/i,
     /SyntaxError:/i,
     /ReferenceError:/i,
+    /TypeError:/i,
+    /RangeError:/i,
+    /URIError:/i,
     /Error: Cannot find module/i,
+    /Cannot find module/i,
+    /Cannot find name/i,
+    /Type '.*' is not assignable to type/i,
+    /Property '.*' does not exist on type/i,
     /\bFAIL\b/,
     /✕\s/,
-    /TS\d{4}:/,
     // Rust / Cargo
     /error\[E\d+\]:/i,
     /fatal runtime error:/i,
     /panicked at/i,
+    /thread '.*' panicked at/i,
+    /-->\s+.*:\d+:\d+/i,
+    /could not compile/i,
     // Go
     /panic:/i,
     /cannot find package/i,
     /undefined:/i,
     /FAIL\t/,
-    // Java / JVM
+    // Java / JVM / Kotlin / Scala
     /Exception in thread/i,
     /java\.lang\./i,
     /error: cannot find symbol/i,
+    /NullPointerException/i,
+    /ClassNotFoundException/i,
+    // C# / .NET
+    /CS\d{4}:/i,
+    /Unhandled exception/i,
+    // Swift
+    /error:\s+/i,
     // Generic Fallbacks
     /\b(cannot|unable to|not found|command not found|no such file)\b/i,
 ];
@@ -1170,8 +1247,77 @@ const STACK_TRACE_START_PATTERNS = [
     /Traceback \(most recent call last\):/i,
     /Exception in thread/i,
     /panic:/i,
+    /thread '.*' panicked at/i,
+    /panicked at/i,
     /Error:\s*$/i,
+    /TypeError:\s*$/i,
+    /ReferenceError:\s*$/i,
+    /AssertionError:\s*$/i,
+    /=== FAILURES ===/i,
+    /=== ERRORS ===/i,
 ];
+/**
+ * Truncates large string output using bounded head and tail windows with a structured metadata receipt.
+ * Preserves early context (e.g. invocation, build targets) and late context (e.g. error summaries, exit codes)
+ * while bounding total character and line count.
+ *
+ * @param text - The raw output text to truncate.
+ * @param options - Configuration options for character/line limits and custom receipt notices.
+ * @returns The windowed text containing head, structured metadata receipt, and tail.
+ */
+export function truncateWithHeadTailWindow(text, options) {
+    if (!text || typeof text !== 'string')
+        return '';
+    const maxChars = options?.maxChars ?? 30_000;
+    const maxLines = options?.maxLines ?? 500;
+    const headRatio = options?.headRatio ?? 0.35;
+    const receiptLabel = options?.receiptLabel ?? 'Output';
+    const hint = options?.hint ?? 'Pipe command to a file and read it in chunks, or use grep.';
+    const lines = text.split(/\r?\n/);
+    if (text.length <= maxChars && lines.length <= maxLines) {
+        return text;
+    }
+    const totalBytes = text.length;
+    const totalLines = lines.length;
+    // Calculate target characters for head and tail windows
+    const receiptReserve = 500;
+    const availableChars = Math.max(1000, maxChars - receiptReserve);
+    const targetHeadChars = Math.floor(availableChars * headRatio);
+    const targetTailChars = availableChars - targetHeadChars;
+    // Max lines for head and tail
+    const targetHeadLines = Math.max(5, Math.floor(maxLines * headRatio));
+    const targetTailLines = Math.max(10, maxLines - targetHeadLines);
+    // Accumulate head lines
+    const headLines = [];
+    let headCharsCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (headLines.length >= targetHeadLines ||
+            (headLines.length > 0 && headCharsCount + line.length + 1 > targetHeadChars)) {
+            break;
+        }
+        headLines.push(line);
+        headCharsCount += line.length + 1;
+    }
+    // Accumulate tail lines backwards (ensuring no overlap with head)
+    const tailLines = [];
+    let tailCharsCount = 0;
+    for (let i = lines.length - 1; i >= headLines.length; i--) {
+        const line = lines[i];
+        if (tailLines.length >= targetTailLines ||
+            (tailLines.length > 0 && tailCharsCount + line.length + 1 > targetTailChars)) {
+            break;
+        }
+        tailLines.unshift(line);
+        tailCharsCount += line.length + 1;
+    }
+    const omittedLines = Math.max(0, totalLines - headLines.length - tailLines.length);
+    const headText = headLines.join('\n');
+    const tailText = tailLines.join('\n');
+    const omittedBytes = Math.max(0, totalBytes - headText.length - tailText.length);
+    const receipt = `\n\n... [${receiptLabel} truncated: ${omittedLines} lines (${omittedBytes} bytes) omitted. Showing ${headLines.length} head lines and ${tailLines.length} tail lines. Total: ${totalLines} lines (${totalBytes} bytes). ${hint}] ...\n\n`;
+    return headText + receipt + tailText;
+}
 /**
  * Condenses verbose command and test failure outputs into high-signal diagnostic error logs
  * with dynamic tail sizing and stack trace boundary snapping.
@@ -1189,14 +1335,30 @@ export function extractHighSignalError(rawError) {
     }
     // Filter out noise lines (e.g. repetitive compiler warning flags)
     const nonNoiseLines = lines.filter((l) => !COMPILER_WARNING_NOISE_PATTERN.test(l));
-    // Find high-signal error lines
+    // Find high-signal error lines and associated compiler frames/context lines
     const highSignalLines = [];
     const highSignalIndices = new Set();
     for (let i = 0; i < nonNoiseLines.length; i++) {
         const line = nonNoiseLines[i];
         if (HIGH_SIGNAL_ERROR_PATTERNS.some((p) => p.test(line))) {
-            highSignalLines.push(line);
-            highSignalIndices.add(i);
+            if (!highSignalIndices.has(i)) {
+                highSignalLines.push(line);
+                highSignalIndices.add(i);
+            }
+            // Capture up to 5 immediate compiler frame continuation lines (e.g. code squiggles, expected/found, arrows)
+            for (let j = 1; j <= 5 && i + j < nonNoiseLines.length; j++) {
+                const nextLine = nonNoiseLines[i + j];
+                if (/^\s*(\||-->|\^|~|expected|found|note:|candidate:)/i.test(nextLine) ||
+                    /^\s*\d+\s*\|/.test(nextLine)) {
+                    if (!highSignalIndices.has(i + j)) {
+                        highSignalLines.push(nextLine);
+                        highSignalIndices.add(i + j);
+                    }
+                }
+                else {
+                    break;
+                }
+            }
         }
     }
     // Dynamic tail sizing: Math.min(50, Math.max(15, Math.floor(totalLines * 0.15)))
@@ -1233,7 +1395,15 @@ export function extractHighSignalError(rawError) {
     else {
         resultBlocks.push(tailLines.join('\n'));
     }
-    const condensedResult = resultBlocks.join('\n\n');
+    let condensedResult = resultBlocks.join('\n\n');
+    // Bounded head/tail window check on condensed result if still oversized
+    if (condensedResult.length > 30_000) {
+        condensedResult = truncateWithHeadTailWindow(condensedResult, {
+            maxChars: 30_000,
+            receiptLabel: 'Diagnostic output',
+            hint: 'Pipe to a file if you need full logs.',
+        });
+    }
     const condensedLines = condensedResult.split(/\r?\n/).length;
     const linesPruned = Math.max(0, lines.length - condensedLines);
     const charsPruned = Math.max(0, rawError.length - condensedResult.length);
@@ -1257,26 +1427,31 @@ export async function runCommand(workspaceRoot, command, abortSignal) {
             maxBuffer: 1024 * 1024 * 2, // 2 MB buffer
             signal: abortSignal,
         });
-        let output = [stdout, stderr].filter(Boolean).join('\n');
-        // Truncate command output to prevent memory blowout from massive build logs
-        const MAX_CMD_OUTPUT = 30_000;
-        if (output.length > MAX_CMD_OUTPUT) {
-            output =
-                output.substring(0, MAX_CMD_OUTPUT) +
-                    `\n\n... (Output truncated: ${output.length} bytes exceeded 30KB limit. To view the rest, pipe the command to a file and read it in chunks, or use grep.)`;
-        }
-        return { output: output || '(command produced no output)' };
+        // Invalidate caches as shell command may have modified the workspace filesystem
+        clearFileReadCache();
+        invalidateDependencyGraph(workspaceRoot);
+        const output = [stdout, stderr].filter(Boolean).join('\n');
+        // Bounded head/tail window truncation with structured metadata receipt
+        const windowedOutput = truncateWithHeadTailWindow(output, {
+            maxChars: 30_000,
+            receiptLabel: 'Output',
+            hint: 'To view the rest, pipe the command to a file and read it in chunks, or use grep.',
+        });
+        return { output: windowedOutput || '(command produced no output)' };
     }
     catch (err) {
+        // Also invalidate in case of partial command execution or errors that wrote files
+        clearFileReadCache();
+        invalidateDependencyGraph(workspaceRoot);
         const message = err instanceof Error ? err.message : String(err);
         // Condense error output with high-signal extraction and dynamic tail sizing
         const condensedError = extractHighSignalError(message);
-        const MAX_ERR_OUTPUT = 30_000;
-        const truncatedMsg = condensedError.length > MAX_ERR_OUTPUT
-            ? condensedError.substring(0, MAX_ERR_OUTPUT) +
-                `\n\n... (Error output truncated: ${condensedError.length} bytes exceeded 30KB limit. Pipe to a file if you need full logs.)`
-            : condensedError;
-        return { output: '', error: `Command failed: ${truncatedMsg}` };
+        const windowedError = truncateWithHeadTailWindow(condensedError, {
+            maxChars: 30_000,
+            receiptLabel: 'Error output',
+            hint: 'Pipe to a file if you need full logs.',
+        });
+        return { output: '', error: `Command failed: ${windowedError}` };
     }
 }
 /**
@@ -1305,14 +1480,18 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, fixedStrings,
         }
         // Use ignore package to evaluate path globs (e.g. src/**/*.ts)
         const globMatcher = fileGlob ? ignore().add(fileGlob) : null;
+        const MAX_SHOWN_MATCHES = 50;
+        const MAX_SCAN_MATCHES = 500;
         const results = [];
+        let totalMatches = 0;
+        const matchedFiles = new Set();
         /**
          * Recursively walks directory entries to search for pattern matches.
          *
          * @param dir - Absolute path to the current directory being searched.
          */
         async function walk(dir) {
-            if (results.length >= 50)
+            if (totalMatches >= MAX_SCAN_MATCHES)
                 return;
             if (abortSignal?.aborted)
                 return;
@@ -1324,7 +1503,7 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, fixedStrings,
                 return;
             }
             for (const entry of entries) {
-                if (results.length >= 50)
+                if (totalMatches >= MAX_SCAN_MATCHES)
                     return;
                 if (abortSignal?.aborted)
                     return;
@@ -1351,12 +1530,16 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, fixedStrings,
                         const content = await fs.readFile(filePath, 'utf-8');
                         const lines = content.split(/\r?\n/);
                         for (let i = 0; i < lines.length; i++) {
-                            if (results.length >= 50)
+                            if (totalMatches >= MAX_SCAN_MATCHES)
                                 break;
                             regexPattern.lastIndex = 0;
                             if (regexPattern.test(lines[i])) {
-                                const relativePath = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
-                                results.push(`${relativePath}:${i + 1}:${lines[i]}`);
+                                totalMatches++;
+                                matchedFiles.add(relPath);
+                                if (results.length < MAX_SHOWN_MATCHES) {
+                                    const relativePath = path.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+                                    results.push(`${relativePath}:${i + 1}:${lines[i]}`);
+                                }
                             }
                         }
                     }
@@ -1373,8 +1556,18 @@ export async function grepSearch(workspaceRoot, pattern, fileGlob, fixedStrings,
         }
         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]]\\u200B></content_data>\n</workspace_file>`;
+        let resultText = results.join('\n');
+        if (totalMatches > results.length) {
+            const moreSuffix = totalMatches >= MAX_SCAN_MATCHES ? '+' : '';
+            resultText += `\n\n[Showing ${results.length}/${totalMatches}${moreSuffix} matches across ${matchedFiles.size} files. Refine query with fileGlob or dirPath to narrow results.]`;
+        }
+        // Window large grep text if character count is huge
+        const windowedResult = truncateWithHeadTailWindow(resultText, {
+            maxChars: 30_000,
+            receiptLabel: 'Grep search results',
+            hint: 'Refine query with fileGlob or dirPath to narrow results.',
+        });
+        const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(windowedResult)}\n]]\\u200B></content_data>\n</workspace_file>`;
         return { output: wrappedResult };
     }
     catch (err) {
@@ -1513,6 +1706,12 @@ export async function runDebugScript(workspaceRoot, language, code, abortSignal)
         if (res.exitCode !== 0) {
             finalOutput += `Script failed with exit code ${res.exitCode}.\n`;
         }
+        if (res.structuredResult !== undefined) {
+            const formattedStructured = typeof res.structuredResult === 'string'
+                ? res.structuredResult
+                : JSON.stringify(res.structuredResult, null, 2);
+            finalOutput += `[STRUCTURED RESULT]\n${formattedStructured}\n`;
+        }
         if (res.stdout) {
             finalOutput += `[STDOUT]\n${res.stdout}\n`;
         }
@@ -1523,11 +1722,17 @@ export async function runDebugScript(workspaceRoot, language, code, abortSignal)
             finalOutput = 'Script executed successfully with no output.';
         }
         const condensedOutput = extractHighSignalError(finalOutput.trim());
+        const windowedOutput = truncateWithHeadTailWindow(condensedOutput, {
+            maxChars: 30_000,
+            receiptLabel: 'Debug script output',
+            hint: 'Inspect specific variables or refine script if full logs are needed.',
+        });
         return {
-            output: `<test_results>\n${sanitizeForCDATA(condensedOutput)}\n</test_results>`,
+            output: `<test_results>\n${sanitizeForCDATA(windowedOutput)}\n</test_results>`,
+            ...(res.structuredResult !== undefined ? { structuredResult: res.structuredResult } : {}),
             ...(res.exitCode !== 0
                 ? {
-                    error: `Script failed with exit code ${res.exitCode}:\n${extractHighSignalError(res.stderr || res.stdout || '')}`,
+                    error: `Script failed with exit code ${res.exitCode}:\n${truncateWithHeadTailWindow(extractHighSignalError(res.stderr || res.stdout || ''), { maxChars: 30_000, receiptLabel: 'Debug script error' })}`,
                 }
                 : {}),
         };
@@ -1573,6 +1778,7 @@ export async function executeFuzzProbe(workspaceRoot, code, language = 'node', c
             output += `\n[STDERR]\n${res.stderr}\n`;
         return {
             output: output.trim(),
+            ...(res.structuredResult !== undefined ? { structuredResult: res.structuredResult } : {}),
             ...(res.exitCode !== 0 && !res.passed ? { error: `Fuzz probe failed with exit code ${res.exitCode}` } : {}),
         };
     }
@@ -1616,6 +1822,7 @@ export async function executeHeapDelta(workspaceRoot, code, language = 'node', c
             output += `\n[STDERR]\n${res.stderr}\n`;
         return {
             output: output.trim(),
+            ...(res.structuredResult !== undefined ? { structuredResult: res.structuredResult } : {}),
             ...(res.exitCode !== 0 ? { error: `Heap delta failed with exit code ${res.exitCode}` } : {}),
         };
     }
@@ -1661,6 +1868,7 @@ export async function executeBehavioralDrift(workspaceRoot, baselineCode, candid
             output += `\n[STDERR]\n${res.stderr}\n`;
         return {
             output: output.trim(),
+            ...(res.structuredResult !== undefined ? { structuredResult: res.structuredResult } : {}),
             ...(res.exitCode !== 0 ? { error: `Behavioral drift check failed with exit code ${res.exitCode}` } : {}),
         };
     }
@@ -1727,6 +1935,9 @@ function resolveWorkspaceArgs(primaryRoot, toolName, args) {
 async function crossWorkspaceGrep(primaryRoot, pattern, fileGlob, fixedStrings, dirPath, abortSignal) {
     const allRoots = workspaceRegistry.getAllRoots(primaryRoot);
     const allResults = [];
+    let totalMatches = 0;
+    const matchedFiles = new Set();
+    const MAX_SHOWN_MATCHES = 80;
     for (const { alias, root } of allRoots) {
         const result = await grepSearch(root, pattern, fileGlob, fixedStrings, dirPath, abortSignal);
         if (result.error)
@@ -1740,10 +1951,14 @@ async function crossWorkspaceGrep(primaryRoot, pattern, fileGlob, fixedStrings,
         const prefix = alias ? `@${alias}/` : '';
         const lines = rawText.split('\n').filter((l) => l.trim());
         for (const line of lines) {
-            if (line.startsWith('...')) {
-                allResults.push(line);
+            if (line.startsWith('...') || line.startsWith('[')) {
+                continue;
             }
-            else {
+            totalMatches++;
+            const matchFile = line.split(':')[0];
+            if (matchFile)
+                matchedFiles.add(prefix ? `${prefix}${matchFile}` : matchFile);
+            if (allResults.length < MAX_SHOWN_MATCHES) {
                 // Lines are in format "./path:lineNum:content" — prepend alias prefix
                 allResults.push(prefix ? line.replace(/^\.?\//, `@${alias}/`) : line);
             }
@@ -1752,9 +1967,16 @@ async function crossWorkspaceGrep(primaryRoot, pattern, fileGlob, fixedStrings,
     if (allResults.length === 0) {
         return { output: `No matches found for "${pattern}" across all workspaces.` };
     }
-    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]]\\u200B></content_data>\n</workspace_file>`;
+    let resultText = allResults.join('\n');
+    if (totalMatches > allResults.length) {
+        resultText += `\n\n[Showing ${allResults.length}/${totalMatches} matches across ${matchedFiles.size} files in registered workspaces. Refine query to narrow results.]`;
+    }
+    const windowedResult = truncateWithHeadTailWindow(resultText, {
+        maxChars: 30_000,
+        receiptLabel: 'Cross-workspace grep results',
+        hint: 'Refine query to narrow results.',
+    });
+    const wrappedResult = `<workspace_file path="grep_search_results">\n<content_data><![CDATA[\n${sanitizeForCDATA(windowedResult)}\n]]\\u200B></content_data>\n</workspace_file>`;
     return { output: wrappedResult };
 }
 const currentTasksByAgent = new Map();
@@ -1946,7 +2168,10 @@ export async function executeTool(workspaceRoot, toolName, args, abortSignal) {
             result = await runCommand(effectiveRoot, resolvedArgs.command, abortSignal);
             break;
         case 'run_debug_script':
-            result = await runDebugScript(effectiveRoot, resolvedArgs.language, resolvedArgs.code, abortSignal);
+        case 'debug_script':
+        case 'run_analysis_script':
+        case 'analysis_script':
+            result = await runDebugScript(effectiveRoot, resolvedArgs.language || 'auto', resolvedArgs.code, abortSignal);
             break;
         case 'grep_search': {
             const wsParam = resolvedArgs.workspace;