minovative-mind-cli 1.0.5 → 1.1.0

package/dist/services/agent.js

@@ -1,36 +1,107 @@
+/**
+ * @fileoverview Core agent execution service.
+ *
+ * This file coordinates the central execution environment for Minovative Mind,
+ * an AI-powered developer CLI. It orchestrates:
+ *
+ * 1. **Interactive REPL Loop**: Collects multiline user input, supports slash-commands,
+ *    reverting changes, switching models, auto-commit, and clipboard paste injection.
+ * 2. **Context-Aware Investigation**: Gathers repo-wide context and compresses it using
+ *    low-cost, high-speed LLM summarization.
+ * 3. **Autonomous Tool Loop (processResponse)**: Allows the AI model to execute file-system,
+ *    shell-command, and search operations, feeding outcomes back in a recursive, multi-turn loop.
+ * 4. **Asynchronous Interrupt Handling (AsyncInputHandler)**: Intercepts keyboard events
+ *    on standard input to let users pause execution, queue live feedback, or abort generation.
+ * 5. **Self-Correction Pipeline**: Compares modified files against TS/Linter diagnostics,
+ *    providing feedback on syntax or semantic failures back to the AI for self-healing.
+ */
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
+import { debugLog, toggleDebugMode } from '../utils/logger.js';
 const execAsync = promisify(exec);
+/**
+ * Asynchronous Input Handler (AsyncInputHandler)
+ *
+ * This class intercepts user keyboard input from standard input (stdin) while
+ * background processes (e.g., Gemini model generations or long shell tool runs)
+ * are executing. It provides seamless execution management by letting users:
+ *
+ * 1. **Pause execution** at any time by pressing a key.
+ * 2. **Queue feedback** ("chained messages") without waiting for the entire run to finish.
+ * 3. **Force abort** the current model or tool run by entering "stop" or "stop!".
+ *
+ * ### Raw Mode & Terminal States
+ * In normal CLI execution, Node.js waits for a line feed (Enter) before emitting input.
+ * To intercept immediate keystrokes, we put `process.stdin` into *raw mode*.
+ * While in raw mode, we listen for direct data buffers.
+ * To avoid visual conflicts with our logging output and Clack's CLI spinners,
+ * we dynamically pause spinners, detach listeners, disable raw mode, open standard
+ * interactive text-prompt forms, and resume raw mode and spinners upon completion.
+ */
 export class AsyncInputHandler {
+    /** Queue of pending user feedback/instructions typed during active background execution */
     queue = [];
+    /** Guard flag preventing multiple simultaneous input prompt overlays */
     isPrompting = false;
+    /** Reference to the Clack CLI spinner which must be paused/restarted during prompts */
     spinner = null;
+    /** Stores the terminal's raw mode configuration state before handler activation */
     originalRawMode = false;
+    /** Indicates whether the input handler is currently inactive/stopped */
     stopped = true;
+    /** Reference to the AbortController controlling the active AI request to trigger cancellations */
     ac = null;
+    /**
+     * Registers the active AbortController for the current AI request.
+     * This is triggered when the user commands a process cancel (e.g., typing "stop").
+     *
+     * @param ac - The AbortController controlling the current generation.
+     */
     setAbortController(ac) {
         this.ac = ac;
     }
+    /**
+     * Determines if a user-prompt dialog is actively running.
+     * Useful for coordinating other console logging output to avoid UI overlap.
+     *
+     * @returns True if a text prompt is currently displayed, false otherwise.
+     */
     isCurrentlyPrompting() {
         return this.isPrompting;
     }
+    /**
+     * Blocks and waits until any active prompting action is completed.
+     * Guarantees terminal stdout is clean before resuming logs.
+     */
     async waitForPrompt() {
         while (this.isPrompting) {
             await new Promise((resolve) => setTimeout(resolve, 100));
         }
     }
+    /**
+     * Core stdin event listener. Detects pressed keys, pauses background visual elements,
+     * handles exit interrupts, and opens a Clack text dialog for input.
+     *
+     * Handles recovery of the standard input stream and raw mode states even if
+     * errors occur during prompt initialization.
+     *
+     * @param chunk - The raw terminal buffer containing keypress data.
+     * @private
+     */
     onData = async (chunk) => {
         try {
             if (this.isPrompting)
                 return;
             const char = chunk.toString();
+            // Handle Ctrl+C (End of Text ASCII 0x03) immediately
             if (char === '\u0003') {
                 process.exit(0);
             }
+            // Ignore standard non-printable control keys, escape sequences, etc.
             if (char.charCodeAt(0) < 32 || char === '\u007f')
                 return;
             this.isPrompting = true;
@@ -38,9 +109,12 @@ export class AsyncInputHandler {
             if (process.stdin.isTTY) {
                 process.stdin.setRawMode(false);
             }
+            // Hide the background spinner before prompt output to avoid corrupting terminal lines
             if (this.spinner) {
                 this.spinner.stop('Paused to receive input');
             }
+            // Capture the user feedback. The character typed to trigger this event is passed
+            // as the initial value of the prompt to avoid losing the first keystroke.
             const userInput = await p.text({
                 message: 'Add chained message:',
                 placeholder: '(Leave blank and press Enter to cancel)',
@@ -64,13 +138,14 @@ export class AsyncInputHandler {
             }
         }
         catch (err) {
-            // Ignore
+            // Absorb and suppress errors safely during raw stream intercepts
         }
         finally {
             if (!this.stopped) {
                 if (process.stdin.isTTY) {
                     process.stdin.setRawMode(true);
                 }
+                // Small delay before reattaching listener to avoid capturing duplicate keypress frames
                 setTimeout(() => {
                     if (!this.stopped) {
                         process.stdin.on('data', this.onData);
@@ -83,6 +158,12 @@ export class AsyncInputHandler {
             }
         }
     };
+    /**
+     * Starts intercepting keystrokes and enables raw terminal processing.
+     * Saves the original raw mode configuration to ensure a clean restoration later.
+     *
+     * @param spinner - The current active Clack spinner UI reference, if any.
+     */
     start(spinner) {
         this.stopped = false;
         if (spinner) {
@@ -95,6 +176,10 @@ export class AsyncInputHandler {
         process.stdin.resume();
         process.stdin.on('data', this.onData);
     }
+    /**
+     * Disables raw mode, stops intercepting keystrokes, and restores
+     * the terminal stdin stream to its original raw/cooked state.
+     */
     stop() {
         this.stopped = true;
         process.stdin.removeListener('data', this.onData);
@@ -103,6 +188,12 @@ export class AsyncInputHandler {
         }
         this.spinner = null;
     }
+    /**
+     * Retrieves and flushes all user feedback messages accumulated during execution.
+     *
+     * @returns A concatenated string of all queued user messages separated by newlines,
+     *          or an empty string if nothing was queued.
+     */
     getAndClear() {
         if (this.queue.length === 0)
             return '';
@@ -112,17 +203,20 @@ export class AsyncInputHandler {
     }
 }
 import { consumeSkipOnce, executeTool, getApprovalMode, setApprovalMode } from './agent-tools.js';
-import { createSharedChatSession, getGeneralChatConfig, getPlanExecutionConfig, ProxyChatSession } from './ai.js';
+import { createSharedChatSession, getGeneralChatConfig, getPlanExecutionConfig, ProxyChatSession, compressTextUsingFlashLite } from './ai.js';
 import { changeLogger } from './changeLogger.js';
 import { gatherContext, routeIntent } from './contextAgent.js';
 import { verifyChangedFiles } from './verificationService.js';
 import { buildContextInjection } from '../utils/contextPrompts.js';
-import { debugLog, toggleDebugMode } from '../utils/logger.js';
 import { readPaste } from '../utils/paste.js';
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 marked.use(markedTerminal());
 // ─── Constants ───────────────────────────────────────────────────────
+/**
+ * Mapping of tool identifiers to user-friendly terminal emojis.
+ * Enhances the visual feedback during background tool execution turns.
+ */
 const TOOL_ICONS = {
     read_file: '📖',
     write_file: '✏️',
@@ -134,6 +228,10 @@ const TOOL_ICONS = {
     rename_file: '🚚',
     find_dependencies: '🔗',
 };
+/**
+ * Human-readable translations for tool actions.
+ * Used for constructing clear, active-verb descriptive log headers in the CLI.
+ */
 const TOOL_LABELS = {
     read_file: 'Reading file',
     write_file: 'Writing file',
@@ -146,12 +244,33 @@ const TOOL_LABELS = {
     find_dependencies: 'Tracing dependencies',
 };
 // ─── Helpers ─────────────────────────────────────────────────────────
+/**
+ * Formats a tool execution call into a beautifully stylized console status line.
+ * Extracts context-specific arguments to display relevant parameters in real-time.
+ *
+ * E.g., for `read_file`, it outputs line-range constraints. For `rename_file`, it prints
+ * a path redirection arrow.
+ *
+ * @param name - The identifier of the tool being called (e.g. 'read_file').
+ * @param args - The dictionary of parameters supplied to the tool.
+ * @returns A fully colorized and formatted ANSI console string.
+ */
 function formatToolCall(name, args) {
     const icon = TOOL_ICONS[name] ?? '🔧';
     const label = TOOL_LABELS[name] ?? name;
     switch (name) {
-        case 'read_file':
-            return `${icon} ${label}: ${pc.cyan(String(args.filePath))}`;
+        case 'read_file': {
+            let extra = '';
+            if (args.startLine !== undefined || args.endLine !== undefined) {
+                const start = args.startLine ?? 1;
+                const end = args.endLine ?? 'end';
+                extra = pc.dim(` (Lines ${start}-${end})`);
+            }
+            else if (Array.isArray(args.targetElements) && args.targetElements.length > 0) {
+                extra = pc.dim(` (Elements: ${args.targetElements.join(', ')})`);
+            }
+            return `${icon} ${label}${extra}: ${pc.cyan(String(args.filePath))}`;
+        }
         case 'write_file':
             return `${icon} ${label}: ${pc.cyan(String(args.filePath))}`;
         case 'modify_file':
@@ -173,10 +292,16 @@ function formatToolCall(name, args) {
     }
 }
 /**
- * Prompts the user to approve a shell command, respecting the current
- * approval mode (ask / skip-once / skip-all).
+ * Prompts the user to approve a pending shell command requested by the AI.
+ * Implements a safety gate to protect the host machine's environment from arbitrary code execution.
  *
- * Returns `true` if the command should run, `false` to deny.
+ * Supports three approval models:
+ * 1. **Ask**: Prompts the user for every shell execution command.
+ * 2. **Skip-Once**: Automatically grants permission to the current command, then resets.
+ * 3. **Skip-All / Auto-Approve**: Grants permission to all future terminal commands in the current session.
+ *
+ * @param command - The terminal string requested for execution.
+ * @returns A promise resolving to `true` if approved, or `false` if denied/cancelled.
  */
 async function requestCommandApproval(command) {
     const mode = getApprovalMode();
@@ -218,11 +343,49 @@ async function requestCommandApproval(command) {
  * Processes a single model response that may contain tool calls.
  * Handles the full tool-call loop: execute → feed results → repeat
  * until the model produces a final text response.
+ *
+ * @param chat - The current active proxy chat session.
+ * @param result - The current result returned from sending a message to the model.
+ * @param workspaceRoot - The absolute/relative path to the workspace root.
+ * @param inputHandler - The input handler to check for queued interrupts.
+ * @param agentState - State tracker for whether the target agent configuration is CHAT or EXECUTE.
+ * @param abortSignal - Signal to detect when the operation has been cancelled.
+ * @returns A promise that resolves to the final text response.
+ */
+/**
+ * Coordinates and executes the recursive model-response tool-execution loop.
+ *
+ * ### Execution Mechanism:
+ * This function processes the initial response from the generative model. If the model determines
+ * it needs to execute tools (e.g. read_file, run_command, modify_file) to answer or fulfill the request:
+ *
+ * 1. **Analyze Tool Requirements**: Parses requested `functionCalls` from the LLM.
+ * 2. **Check for User Abortion**: Periodically examines the `AbortSignal` to stop execution if requested.
+ * 3. **Manage Safety Approvals**: For high-risk operations (like `run_command`), requests explicit confirmation from the user (or uses auto-approve configurations).
+ * 4. **Execute Operations**: Runs requested tool actions via `executeTool` in parallel or series as requested.
+ * 5. **Handle Interrupts**: Integrates background user inputs queued in `inputHandler` as new context prompts back into the active LLM context.
+ * 6. **Submit Loop Frame**: Feeds execution outcomes back to the Gemini session and recursively repeats this sequence until the LLM produces a final text answer without further tool requests.
+ *
+ * ### Limits & Recovery Guardrails:
+ * - **Turn-Limiting**: Capped at `MAX_TURNS` (25) to prevent infinite loops, API token drain, or excessive billing if the AI gets stuck in a repetitive loop.
+ * - **Empty-Response Healing**: If the API returns an empty text response with no tools, the system initiates up to `MAX_EMPTY_RETRIES` (3) system-driven wake-up prompts to re-engage the model.
+ *
+ * @param chat - The current active proxy chat session.
+ * @param result - The current result returned from sending a message to the model.
+ * @param workspaceRoot - The absolute/relative path to the workspace root.
+ * @param inputHandler - The input handler to check for queued interrupts.
+ * @param agentState - State tracker for whether the target agent configuration is CHAT or EXECUTE.
+ * @param abortSignal - Signal to detect when the operation has been cancelled.
+ * @returns A promise that resolves to the final text response.
  */
 async function processResponse(chat, result, workspaceRoot, inputHandler, agentState, abortSignal) {
     let response = result.response;
+    // Upper limit on autonomous sequential tool executions to prevent out-of-control loops
     let turnCount = 0;
     const MAX_TURNS = 25;
+    // Recovery thresholds for handling unexpected empty API payloads
+    let emptyRetryCount = 0;
+    const MAX_EMPTY_RETRIES = 3;
     // Loop while the model keeps requesting tool calls
     while (true) {
         turnCount++;
@@ -233,21 +396,50 @@ async function processResponse(chat, result, workspaceRoot, inputHandler, agentS
         const functionCalls = response.functionCalls();
         if (!functionCalls || functionCalls.length === 0) {
             // No more tool calls — return the final text response
-            return response.text() ?? '';
+            let finalOutput = response.text() ?? '';
+            if (!finalOutput.trim()) {
+                if (emptyRetryCount < MAX_EMPTY_RETRIES) {
+                    emptyRetryCount++;
+                    p.log.warn(pc.yellow(`AI returned an empty response. Attempting to recover (retry ${emptyRetryCount}/${MAX_EMPTY_RETRIES})...`));
+                    // System-driven injection to kickstart the LLM's conversation generation
+                    const wakeUpMessage = 'SYSTEM: You just returned a completely empty response with no tool calls. If you are stuck, please use your tools to explore the workspace, or explain what you are trying to do and ask the user for clarification. Do not return empty responses.';
+                    try {
+                        const retry = await chat.sendMessage(wakeUpMessage, undefined, abortSignal);
+                        response = retry.response;
+                        continue;
+                    }
+                    catch (e) {
+                        if (e.name === 'AbortError' || e.message?.includes('abort')) {
+                            p.log.warn(pc.yellow('Generation stopped by user during recovery.'));
+                            return '[Generation stopped by user]';
+                        }
+                        finalOutput = '[System Error: The AI returned an empty response and failed to recover.]';
+                    }
+                }
+                else {
+                    finalOutput =
+                        '[The AI repeatedly returned empty responses and could not recover. This usually means it hit an API filter/limit or is stuck. Try rewording your prompt.]';
+                }
+            }
+            return finalOutput;
         }
-        // Process each tool call
+        // Process each tool call requested by the model
         const toolResponses = [];
         for (const fc of functionCalls) {
+            if (abortSignal.aborted) {
+                p.log.warn(pc.yellow('Execution aborted by user.'));
+                return '[Generation stopped by user]';
+            }
             const toolName = fc.name;
             const toolArgs = (fc.args ?? {});
-            // Display what the agent is doing
+            // Log the ongoing tool action to the console
             p.log.step(formatToolCall(toolName, toolArgs));
-            // For run_command, request user approval
+            // If executing a CLI/shell command, wait for approval
             if (toolName === 'run_command') {
                 await inputHandler.waitForPrompt();
-                inputHandler.stop();
+                inputHandler.stop(); // Temporarily release raw-mode during blocking interactive prompt
                 const approved = await requestCommandApproval(toolArgs.command);
-                inputHandler.start();
+                inputHandler.start(); // Re-engage raw-mode for continuous background monitoring
                 if (!approved) {
                     toolResponses.push({
                         functionResponse: {
@@ -261,14 +453,17 @@ async function processResponse(chat, result, workspaceRoot, inputHandler, agentS
                     continue;
                 }
             }
-            // Execute the tool
-            const toolResult = await executeTool(workspaceRoot, toolName, toolArgs);
+            // Execute the underlying filesystem, shell or search tool logic
+            const toolResult = await executeTool(workspaceRoot, toolName, toolArgs, abortSignal);
             if (toolResult.error) {
                 debugLog(`Raw Tool Error for ${toolName}: ${toolResult.error}`);
-                // Truncate the error message for the terminal UI to prevent console clutter
-                // (e.g. hiding the large file previews sent to the AI)
-                const displayError = toolResult.error.split('\n')[0].substring(0, 100);
-                p.log.warn(`${pc.red('Tool error:')} [${displayError}]`);
+                // Do not spam the user with expected chunking warnings
+                if (!toolResult.error.includes('File is too large')) {
+                    // Truncate the error message for the terminal UI to prevent console clutter
+                    // (e.g. hiding the large file previews sent to the AI)
+                    const displayError = toolResult.error.split('\n')[0].substring(0, 100);
+                    p.log.warn(`${pc.red('Tool error:')} [${displayError}]`);
+                }
             }
             toolResponses.push({
                 functionResponse: {
@@ -280,12 +475,14 @@ async function processResponse(chat, result, workspaceRoot, inputHandler, agentS
                 },
             });
         }
+        // Check if the user entered any feedback or interrupt commands during the tool execution cycle
         await inputHandler.waitForPrompt();
         const queuedMsg = inputHandler.getAndClear();
         let additionalText = undefined;
         if (queuedMsg) {
             additionalText = `[USER INTERRUPTION] The user sent the following message during your execution:\n"${queuedMsg}"\n\nPlease incorporate this feedback into your ongoing work. Address the user's message, but DO NOT lose track of your original overall plan or focus. After addressing this interruption, continue with your broader objective.`;
             p.log.info(pc.cyan(`Sending queued message to AI...`));
+            // Dynamically upgrade agent permissions/intent to EXECUTE mode if the interrupted instruction requires system modifications
             const newIntent = await routeIntent(queuedMsg);
             if (agentState.targetAgent === 'CHAT') {
                 if (newIntent.targetAgent === 'EXECUTE' || newIntent.needsContext) {
@@ -296,7 +493,7 @@ async function processResponse(chat, result, workspaceRoot, inputHandler, agentS
                 }
             }
         }
-        // Feed tool results back to the model
+        // Feed tool results and potential interruption text back to the model
         let followUp;
         try {
             followUp = await chat.sendMessage(toolResponses, additionalText, abortSignal);
@@ -318,12 +515,54 @@ async function processResponse(chat, result, workspaceRoot, inputHandler, agentS
 /**
  * Starts the interactive agent chat loop.
  * Runs until the user types "exit", "quit", or presses Ctrl+C.
+ *
+ * @param workspaceRoot - The root directory of the workspace.
+ * @param version - The active version of the CLI utility.
+ */
+/**
+ * Starts and orchestrates the primary interactive command-line interface (REPL) loop.
+ *
+ * This is the central control loop of the CLI application. It runs indefinitely until
+ * the user explicitly issues an exit directive (e.g., typing "exit", "quit", `/` command menu selections,
+ * or using keyboard breaks like Ctrl+C).
+ *
+ * ### Architectural Pipeline:
+ * 1. **User Input Collection**:
+ *    - Captures multiline text strings by checking for trailing backslash characters (`\`).
+ *    - Prevents visual terminal glitches during multi-line typing on varying themes.
+ *    - Automatically handles command menu redirection when users enter a forward slash (`/`).
+ *    - Intercepts and filters OS clipboard paste buffers to allow inserting massive scripts cleanly.
+ *
+ * 2. **Slash Commands Processing**:
+ *    - `/paste`: Interactively captures large copy-pasted blocks using EOF tracking.
+ *    - `/clear`: Hard-clears active terminal histories and resets session state.
+ *    - `/models`: Dynamic runtime model hot-swapping (e.g., swapping between Flash and Pro variants).
+ *    - `/debug`: Toggles active runtime execution telemetry logging.
+ *    - `/auto-approve`: Grants blanket terminal script permissions to bypass prompt approval blocks.
+ *    - `/revert`: Pops the most recent change-set log and rolls back mutated files to original states.
+ *    - `/commit`: Performs git diff staging, executes model summaries to write micro-commits, and executes local git commits.
+ *
+ * 3. **Workspace Context Gathering & Intention Routing**:
+ *    - Leverages the Context Agent (`gatherContext`) to perform exploratory scans of the active repository.
+ *    - Identifies user intention to hot-swap system prompt strategies (`CHAT` for conversational assistance vs. `EXECUTE` for multi-turn modifications).
+ *    - Compresses gathered repo structures and file contents using high-speed Flash-Lite engines to respect context boundaries and budget costs.
+ *
+ * 4. **Model Execution & Self-Correction Feedback Loop**:
+ *    - Passes the target request to Gemini alongside compressed workspace injections.
+ *    - Recursively processes tool invocations via `processResponse`.
+ *    - Runs static validation checks (`verifyChangedFiles`) against mutated files to check for compiler/linter bugs.
+ *    - If files fail validation, enters a self-healing loop by submitting raw diagnostic errors directly back to the AI for remediation.
+ *
+ * @param workspaceRoot - The relative or absolute path representing the active workspace environment.
+ * @param version - The Semantic Version string of the active tool distribution.
  */
 export async function startAgentLoop(workspaceRoot, version) {
     const chat = createSharedChatSession();
     const inputHandler = new AsyncInputHandler();
     let isRawPasteMode = false;
-    // Intercept terminal paste events to prevent accidental early-submission of multi-line pastes
+    // Hook process.stdin.emit to intercept fast stream inputs.
+    // When large buffers containing newlines arrive rapidly, we interpret them as a clipboard paste,
+    // sanitizing and collapsing them to prevent premature command line submission.
     const originalEmit = process.stdin.emit.bind(process.stdin);
     process.stdin.emit = function (event, ...args) {
         if (!isRawPasteMode && event === 'data' && Buffer.isBuffer(args[0])) {
@@ -343,9 +582,10 @@ export async function startAgentLoop(workspaceRoot, version) {
         let lines = [];
         let isMultiLine = false;
         let canceledGlobal = false;
+        // Input collection sub-loop (handles multiline line-by-line gathering)
         while (true) {
             const userInputRaw = await p.text({
-                message: isMultiLine ? '  ' : '❯',
+                message: isMultiLine ? '  ' : pc.magenta('❯'),
                 placeholder: isMultiLine ? '' : 'Use "\\" for new lines',
             });
             if (p.isCancel(userInputRaw)) {
@@ -385,6 +625,7 @@ export async function startAgentLoop(workspaceRoot, version) {
         if (!userInput) {
             continue;
         }
+        // Capture standalone forward slash triggers to open the selection console
         if (userInput === '/') {
             const commandMenu = await p.select({
                 message: 'Command Menu',
@@ -412,7 +653,10 @@ export async function startAgentLoop(workspaceRoot, version) {
         if (userInput.length === 0) {
             continue;
         }
-        // Handle special commands
+        if (userInput.startsWith('/')) {
+            debugLog(`Executing slash command: ${userInput}`);
+        }
+        // ─── Slash Commands Handling ─────────────────────────────────────
         if (userInput.toLowerCase() === '/paste') {
             p.log.info(pc.cyan('Paste mode activated. Paste your text below, then press Ctrl+D on an empty line to submit. (Ctrl+C to cancel)'));
             try {
@@ -437,7 +681,7 @@ export async function startAgentLoop(workspaceRoot, version) {
             process.stdout.write('\x1B[2J\x1B[3J\x1B[H'); // Hard clear screen and scrollback
             p.intro(`${pc.bgCyan(pc.black(' Minovative Mind '))} ${pc.dim('v' + version)}`);
             p.log.info(`${pc.dim('Workspace:')} ${pc.cyan(workspaceRoot)}`);
-            p.log.info(`${pc.dim('Commands:')} Type ${pc.yellow('/')} to open the command menu. Type ${pc.yellow('exit')} to leave.`);
+            p.log.info(`${pc.dim('Commands:')} Type ${pc.yellow('/')} to open the command menu and "${pc.yellow('stop')}" to stop the ai generation. Type ${pc.yellow('exit')} to leave.`);
             p.log.success('Chat history cleared.');
             console.log(pc.dim('\nType your coding request below. Type "exit" or "quit" to leave.\n'));
             continue;
@@ -446,6 +690,8 @@ export async function startAgentLoop(workspaceRoot, version) {
             const selectedModel = await p.select({
                 message: 'Select AI Model',
                 options: [
+                    { value: 'gemini-3.1-pro', label: 'Gemini 3.1 Pro', hint: 'The newest Pro model for complex logic' },
+                    { value: 'gemini-3.5-flash', label: 'Gemini 3.5 Flash', hint: 'The newest Flash model for high speed' },
                     { value: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro', hint: 'Best for complex coding & large context' },
                     { value: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash', hint: 'Balanced performance' },
                     // {value: 'claude-opus-4-6', label: 'Claude Opus 4.6', hint: 'Anthropic: Highly capable, complex reasoning'},
@@ -459,12 +705,12 @@ export async function startAgentLoop(workspaceRoot, version) {
             continue;
         }
         if (userInput.toLowerCase() === '/debug') {
-            const isEnabled = toggleDebugMode();
-            if (isEnabled) {
-                p.log.success('Debug mode enabled. Internal logs will now be shown.');
+            const debugMode = toggleDebugMode();
+            if (debugMode) {
+                p.log.info('Debug mode enabled. Internal logs will now be shown.');
             }
             else {
-                p.log.success('Debug mode disabled.');
+                p.log.info('Debug mode disabled.');
             }
             continue;
         }
@@ -540,6 +786,7 @@ ${diffOut}
             }
             continue;
         }
+        // ─── Main Execution Cycle ────────────────────────────────────────
         const spinner = p.spinner();
         const ac = new AbortController();
         inputHandler.setAbortController(ac);
@@ -547,6 +794,7 @@ ${diffOut}
             inputHandler.start(spinner);
             changeLogger.startChangeSet(userInput);
             let finalInput = userInput;
+            // Stage 1: Gather Workspace Context and route intentions
             spinner.start('🔍 Investigating workspace...');
             const chatHistory = chat.getRecentHistory(3);
             const gatherRes = await gatherContext(workspaceRoot, userInput, chatHistory, inputHandler, ac.signal, (msg) => {
@@ -555,27 +803,28 @@ ${diffOut}
                 }
             });
             let latestUsage = undefined;
-            // Also grab any messages queued exactly between gatherContext ending and here
+            // Collect any inputs that were queued while the Context Agent was investigating
             const leftoverMsg = inputHandler.getAndClear();
             if (leftoverMsg) {
                 gatherRes.chainedMessages.push(leftoverMsg);
             }
+            // Resolve the effective target agent mode based on original intent + any chained commands
             let effectiveTargetAgent = gatherRes.targetAgent;
             if (gatherRes.chainedMessages.length > 0) {
                 const chainedContent = gatherRes.chainedMessages.join('\n');
                 const newIntent = await routeIntent(chainedContent);
                 if (gatherRes.contextResult !== null) {
-                    // Was SEARCH: Can change to EXECUTE or CHAT based on chained message
+                    // If the model previously needed search context, determine if followups change the mode
                     effectiveTargetAgent = newIntent.targetAgent;
                 }
                 else {
-                    // Was NOT SEARCH
+                    // If not in a context-search flow
                     if (gatherRes.targetAgent === 'EXECUTE') {
-                        // Executing cannot downgrade to CHAT
+                        // EXECUTE permission sets are immutable during follow-ups to prevent downgrades
                         effectiveTargetAgent = 'EXECUTE';
                     }
                     else {
-                        // Was CHAT: Can change to SEARCH or EXECUTE. Both are treated as EXECUTE to grant tools.
+                        // Conversational prompts can escalate to EXECUTE if chained instructions dictate
                         if (newIntent.targetAgent === 'EXECUTE' || newIntent.needsContext) {
                             effectiveTargetAgent = 'EXECUTE';
                         }
@@ -583,30 +832,38 @@ ${diffOut}
                 }
                 finalInput += `\n\n[USER FOLLOW-UP INSTRUCTIONS SENT DURING INVESTIGATION]:\n${chainedContent}\n\nPlease incorporate these instructions into your work. Address them appropriately, but ensure you do not lose track of the original request's primary objective.`;
             }
-            // Hot-swap the agent configuration based on intent
+            // Hot-swap the underlying LLM system instruction context depending on intent (conversational vs execution)
             debugLog(`Intent Router output: original targetAgent = ${gatherRes.targetAgent}, effective = ${effectiveTargetAgent}`);
             const config = effectiveTargetAgent === 'CHAT' ? getGeneralChatConfig() : getPlanExecutionConfig();
             let dynamicSystemInstruction = config.systemInstruction;
+            // Inject gathered workspace directories, dependency configurations, and matching search patterns
             if (gatherRes.contextResult) {
-                const contextInjection = buildContextInjection(gatherRes.contextResult);
-                debugLog(`Context injection size: ${contextInjection.length} chars`);
+                let contextInjection = buildContextInjection(gatherRes.contextResult);
+                debugLog(`Raw context injection size: ${contextInjection.length} chars`);
+                // Compress context inputs using Gemini Flash Lite to optimize prompt density and prevent token bloat
+                contextInjection = await compressTextUsingFlashLite(contextInjection, 'Summarize the following project context concisely. Preserve all file paths, project types, and the high-level purpose of the read files. Keep it under 2000 characters if possible.');
+                debugLog(`Compressed context injection size: ${contextInjection.length} chars`);
                 dynamicSystemInstruction += '\n\n' + contextInjection;
             }
+            // Apply the dynamic prompt updates and tool registrations to the active chat session
             chat.setAgentConfig(dynamicSystemInstruction, config.tools);
             if (!inputHandler.isCurrentlyPrompting()) {
                 spinner.message('Thinking...');
             }
+            // Send the formulated prompt payload to the generative model
             let result;
             try {
                 result = await chat.sendMessage(finalInput, undefined, ac.signal);
             }
             catch (e) {
+                spinner.stop('');
                 if (e.name === 'AbortError' || e.message?.includes('abort')) {
                     p.log.warn(pc.yellow('Generation aborted by user.'));
-                    spinner.stop('');
-                    continue;
                 }
-                throw e;
+                else {
+                    p.log.error(pc.red(`Error communicating with AI: ${e.message || String(e)}`));
+                }
+                continue;
             }
             latestUsage = result.response.usageMetadata?.();
             const grounding = result.response.groundingMetadata?.();
@@ -620,17 +877,29 @@ ${diffOut}
             const calls = result.response.functionCalls();
             debugLog(`Initial functionCalls: ${calls && calls.length > 0 ? JSON.stringify(calls) : 'None'}`);
             let agentState = { targetAgent: effectiveTargetAgent };
+            let previousChangeCount = changeLogger.getCurrentChangeSet()?.changes.length || 0;
+            // Stage 2: Recursive Tool Loops and Automated Self-Correction
             while (correctionAttempts <= MAX_CORRECTIONS) {
                 if (finalText === '[Generation stopped by user]')
                     break;
                 finalText = await processResponse(chat, result, workspaceRoot, inputHandler, agentState, ac.signal);
-                debugLog(`processResponse returned finalText (length ${finalText.length}): "${finalText.substring(0, 50)}..."`);
+                debugLog(`processResponse returned finalText (length ${finalText.length}): "${finalText.substring(0, 10)}..."`);
+                if (finalText.startsWith('[The AI repeatedly returned empty responses')) {
+                    break;
+                }
                 const currentChanges = changeLogger.getCurrentChangeSet()?.changes || [];
+                // If the correction cycle is active but no new changes were registered, the model gave up
+                if (correctionAttempts > 0 && currentChanges.length <= previousChangeCount) {
+                    p.log.warn('AI failed to modify any files during the correction attempt. Aborting auto-correction.');
+                    break;
+                }
+                previousChangeCount = currentChanges.length;
                 const changedFiles = currentChanges
                     .filter((c) => c.action === 'create' || c.action === 'modify')
                     .map((c) => c.filePath);
                 if (changedFiles.length === 0)
                     break;
+                // Stage 3: Static code analysis / verification
                 p.log.step('Verifying modified files...');
                 const verificationErrors = await verifyChangedFiles(workspaceRoot, changedFiles);
                 if (!verificationErrors) {
@@ -643,19 +912,22 @@ ${diffOut}
                     break;
                 }
                 p.log.warn(`${pc.yellow('Verification failed. Auto-correcting errors')} (Attempt ${correctionAttempts}/${MAX_CORRECTIONS})...`);
-                // Optionally show a snippet of the error to the user so they aren't left in the dark
                 const displayError = verificationErrors.split('\n').slice(0, 5).join('\n');
                 console.log(pc.dim(`  ${displayError.replace(/\n/g, '\n  ')}\n  ...`));
                 debugLog(`Verification failed on attempt ${correctionAttempts}/${MAX_CORRECTIONS}. Errors:\n${verificationErrors}`);
+                // Compile compilation and syntax diagnostic warnings into an auto-correction prompt
                 const correctionPrompt = `AUTOMATED SYSTEM CHECK: Your previous changes resulted in the following errors:\n\n${verificationErrors}\n\nPlease analyze these errors and use your file modification tools to fix them.`;
                 spinner.start('Thinking (Correction)...');
                 result = await chat.sendMessage(correctionPrompt);
                 spinner.stop('');
             }
+            // Persist the verified changes into our session change ledger
             changeLogger.commitChangeSet();
             if (finalText) {
                 console.log(`\n${pc.blue('◆')} ${pc.bold('Minovative Mind')} ${pc.dim(`(${chat.getModel()})`)}\n`);
-                console.log(marked.parse(finalText));
+                // Strip out excessive empty lines generated by LLMs to prevent huge visual gaps in marked-terminal
+                const cleanText = finalText.replace(/\n([ \t]*\n){2,}/g, '\n\n');
+                console.log(marked.parse(cleanText));
             }
             if (latestUsage && latestUsage.remainingBalance !== undefined) {
                 p.log.info(`${pc.dim('Credits Remaining:')} ${pc.cyan(latestUsage.remainingBalance.toLocaleString())}`);