import { spawn, SpawnOptions, ChildProcessWithoutNullStreams, } from 'child_process'; // Added 'exec' import path from 'path'; import os from 'os'; import crypto from 'crypto'; import { promises as fs } from 'fs'; import { BaseTool, ToolResult } from './tools.js'; import { SchemaValidator } from '../utils/schemaValidator.js'; import { ToolCallConfirmationDetails, ToolConfirmationOutcome, ToolExecuteConfirmationDetails, } from '../ui/types.js'; // Adjust path as needed import { BackgroundTerminalAnalyzer } from '../utils/BackgroundTerminalAnalyzer.js'; import { getErrorMessage, isNodeError } from '../utils/errors.js'; // --- Interfaces --- export interface TerminalToolParams { command: string; description?: string; timeout?: number; runInBackground?: boolean; } // --- Constants --- const MAX_OUTPUT_LENGTH = 10000; // Default max output length const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes (for foreground commands) const MAX_TIMEOUT_OVERRIDE_MS = 10 * 60 * 1000; // 10 minutes (max override for foreground) const BACKGROUND_LAUNCH_TIMEOUT_MS = 15 * 1000; // 15 seconds timeout for *launching* background tasks const BACKGROUND_POLL_TIMEOUT_MS = 30000; // 30 seconds total polling time for background process status const BANNED_COMMAND_ROOTS = [ // Session/flow control (excluding cd) 'alias', 'bg', 'command', 'declare', 'dirs', 'disown', 'enable', 'eval', 'exec', 'exit', 'export', 'fc', 'fg', 'getopts', 'hash', 'history', 'jobs', 'kill', 'let', 'local', 'logout', 'popd', 'printf', 'pushd', /* 'pwd' is safe */ 'read', 'readonly', 'set', 'shift', 'shopt', 'source', 'suspend', 'test', 'times', 'trap', 'type', 'typeset', 'ulimit', 'umask', 'unalias', 'unset', 'wait', // Network commands 'curl', 'wget', 'nc', 'telnet', 'ssh', 'scp', 'ftp', 'sftp', 'http', 'https', 'ftp', 'rsync', // Browsers/GUI launchers 'lynx', 'w3m', 'links', 'elinks', 'httpie', 'xh', 'http-prompt', 'chrome', 'firefox', 'safari', 'edge', 'xdg-open', 'open', ]; // --- Helper Type for Command Queue --- interface QueuedCommand { params: TerminalToolParams; resolve: (result: ToolResult) => void; reject: (error: Error) => void; confirmationDetails: ToolExecuteConfirmationDetails | false; // Kept for potential future use } /** * Implementation of the terminal tool that executes shell commands within a persistent session. */ export class TerminalTool extends BaseTool { static Name: string = 'execute_bash_command'; private readonly rootDirectory: string; private readonly outputLimit: number; private bashProcess: ChildProcessWithoutNullStreams | null = null; private currentCwd: string; private isExecuting: boolean = false; private commandQueue: QueuedCommand[] = []; private currentCommandCleanup: (() => void) | null = null; private shouldAlwaysExecuteCommands: Map = new Map(); // Track confirmation per root command private shellReady: Promise; private resolveShellReady: (() => void) | undefined; // Definite assignment assertion private rejectShellReady: ((reason?: unknown) => void) | undefined; // Definite assignment assertion private readonly backgroundTerminalAnalyzer: BackgroundTerminalAnalyzer; constructor(rootDirectory: string, outputLimit: number = MAX_OUTPUT_LENGTH) { const toolDisplayName = 'Terminal'; // --- LLM-Facing Description --- // Updated description for background tasks to mention polling and LLM analysis const toolDescription = `Executes one or more bash commands sequentially in a secure and persistent interactive shell session. Can run commands in the foreground (waiting for completion) or background (returning after launch, with subsequent status polling). Core Functionality: * Starts in project root: '${path.basename(rootDirectory)}'. Current Directory starts as: ${rootDirectory} (will update based on 'cd' commands). * Persistent State: Environment variables and the current working directory (\`pwd\`) persist between calls to this tool. * **Execution Modes:** * **Foreground (default):** Waits for the command to complete. Captures stdout, stderr, and exit code. Output is truncated if it exceeds ${outputLimit} characters. * **Background (\`runInBackground: true\`):** Appends \`&\` to the command and redirects its output to temporary files. Returns *after* the command is launched, providing the Process ID (PID) and launch status. Subsequently, the tool **polls** for the background process status for up to ${BACKGROUND_POLL_TIMEOUT_MS / 1000} seconds. Once the process finishes or polling times out, the tool reads the captured stdout/stderr from the temporary files, runs an internal LLM analysis on the output, cleans up the files, and returns the final status, captured output, and analysis. * Timeout: Optional timeout per 'execute' call (default: ${DEFAULT_TIMEOUT_MS / 60000} min, max override: ${MAX_TIMEOUT_OVERRIDE_MS / 60000} min for foreground). Background *launch* has a fixed shorter timeout (${BACKGROUND_LAUNCH_TIMEOUT_MS / 1000}s) for the launch attempt itself. Background *polling* has its own timeout (${BACKGROUND_POLL_TIMEOUT_MS / 1000}s). Timeout attempts SIGINT for foreground commands. Usage Guidance & Restrictions: 1. **Directory/File Verification (IMPORTANT):** * BEFORE executing commands that create files or directories (e.g., \`mkdir foo/bar\`, \`touch new/file.txt\`, \`git clone ...\`), use the dedicated File System tool (e.g., 'list_directory') to verify the target parent directory exists and is the correct location. * Example: Before running \`mkdir foo/bar\`, first use the File System tool to check that \`foo\` exists in the current directory (\`${rootDirectory}\` initially, check current CWD if it changed). 2. **Use Specialized Tools (CRITICAL):** * Do NOT use this tool for filesystem searching (\`find\`, \`grep\`). Use the dedicated Search tool instead. * Do NOT use this tool for reading files (\`cat\`, \`head\`, \`tail\`, \`less\`, \`more\`). Use the dedicated File Reader tool instead. * Do NOT use this tool for listing files (\`ls\`). Use the dedicated File System tool ('list_directory') instead. Relying on this tool's output for directory structure is unreliable due to potential truncation and lack of structured data. 3. **Security & Banned Commands:** * Certain commands are banned for security (e.g., network: ${BANNED_COMMAND_ROOTS.filter((c) => ['curl', 'wget', 'ssh'].includes(c)).join(', ')}; session: ${BANNED_COMMAND_ROOTS.filter((c) => ['exit', 'export', 'kill'].includes(c)).join(', ')}; etc.). The full list is extensive. * If you attempt a banned command, this tool will return an error explaining the restriction. You MUST relay this error clearly to the user. 4. **Command Execution Notes:** * Chain multiple commands using shell operators like ';' or '&&'. Do NOT use newlines within the 'command' parameter string itself (newlines are fine inside quoted arguments). * The shell's current working directory is tracked internally. While \`cd\` is permitted if the user explicitly asks or it's necessary for a workflow, **strongly prefer** using absolute paths or paths relative to the *known* current working directory to avoid errors. Check the '(Executed in: ...)' part of the previous command's output for the CWD. * Good example (if CWD is /workspace/project): \`pytest tests/unit\` or \`ls /workspace/project/data\` * Less preferred: \`cd tests && pytest unit\` (only use if necessary or requested) 5. **Background Tasks (\`runInBackground: true\`):** * Use this for commands that are intended to run continuously (e.g., \`node server.js\`, \`npm start\`). * The tool initially returns success if the process *launches* successfully, along with its PID. * **Polling & Final Result:** The tool then monitors the process. The *final* result (delivered after polling completes or times out) will include: * The final status (completed or timed out). * The complete stdout and stderr captured in temporary files (truncated if necessary). * An LLM-generated analysis/summary of the output. * The initial exit code (usually 0) signifies successful *launching*; the final status indicates completion or timeout after polling. Use this tool for running build steps (\`npm install\`, \`make\`), linters (\`eslint .\`), test runners (\`pytest\`, \`jest\`), code formatters (\`prettier --write .\`), package managers (\`pip install\`), version control operations (\`git status\`, \`git diff\`), starting background servers/services (\`node server.js --runInBackground true\`), or other safe, standard command-line operations within the project workspace.`; // --- Parameter Schema --- const toolParameterSchema = { type: 'object', properties: { command: { description: `The exact bash command or sequence of commands (using ';' or '&&') to execute. Must adhere to usage guidelines. Example: 'npm install && npm run build'`, type: 'string', }, description: { description: `Optional: A brief, user-centric explanation of what the command does and why it's being run. Used for logging and confirmation prompts. Example: 'Install project dependencies'`, type: 'string', }, timeout: { description: `Optional execution time limit in milliseconds for FOREGROUND commands. Max ${MAX_TIMEOUT_OVERRIDE_MS}ms (${MAX_TIMEOUT_OVERRIDE_MS / 60000} min). Defaults to ${DEFAULT_TIMEOUT_MS}ms (${DEFAULT_TIMEOUT_MS / 60000} min) if not specified or invalid. Ignored if 'runInBackground' is true.`, type: 'number', }, runInBackground: { description: `If true, execute the command in the background using '&'. Defaults to false. Use for servers or long tasks.`, type: 'boolean', }, }, required: ['command'], }; super( TerminalTool.Name, toolDisplayName, toolDescription, toolParameterSchema, ); this.rootDirectory = path.resolve(rootDirectory); this.currentCwd = this.rootDirectory; this.outputLimit = outputLimit; this.shellReady = new Promise((resolve, reject) => { this.resolveShellReady = resolve; this.rejectShellReady = reject; }); this.backgroundTerminalAnalyzer = new BackgroundTerminalAnalyzer(); this.initializeShell(); } // --- Shell Initialization and Management (largely unchanged) --- private initializeShell() { if (this.bashProcess) { try { this.bashProcess.kill(); } catch { /* Ignore */ } } const spawnOptions: SpawnOptions = { cwd: this.rootDirectory, shell: true, env: { ...process.env }, stdio: ['pipe', 'pipe', 'pipe'], }; try { const bashPath = os.platform() === 'win32' ? 'bash.exe' : 'bash'; this.bashProcess = spawn( bashPath, ['-s'], spawnOptions, ) as ChildProcessWithoutNullStreams; this.currentCwd = this.rootDirectory; // Reset CWD on restart this.bashProcess.on('error', (err) => { console.error('Persistent Bash Error:', err); this.rejectShellReady?.(err); // Use optional chaining as reject might be cleared this.bashProcess = null; this.isExecuting = false; this.clearQueue( new Error(`Persistent bash process failed to start: ${err.message}`), ); }); this.bashProcess.on('close', (code, signal) => { this.bashProcess = null; this.isExecuting = false; // Only reject if it hasn't been resolved/rejected already this.rejectShellReady?.( new Error( `Persistent bash process exited (code: ${code}, signal: ${signal})`, ), ); // Reset shell readiness promise for reinitialization attempts this.shellReady = new Promise((resolve, reject) => { this.resolveShellReady = resolve; this.rejectShellReady = reject; }); this.clearQueue( new Error( `Persistent bash process exited unexpectedly (code: ${code}, signal: ${signal}). State is lost. Queued commands cancelled.`, ), ); // Attempt to reinitialize after a short delay setTimeout(() => this.initializeShell(), 1000); }); // Readiness check - ensure shell is responsive // Slightly longer timeout to allow shell init setTimeout(() => { if (this.bashProcess && !this.bashProcess.killed) { this.resolveShellReady?.(); // Use optional chaining } else if (!this.bashProcess) { // Error likely already handled by 'error' or 'close' event } else { // Process was killed during init? this.rejectShellReady?.( new Error('Shell killed during initialization'), ); } }, 1000); // Increase readiness check timeout slightly } catch (error: unknown) { console.error('Failed to spawn persistent bash:', error); this.rejectShellReady?.(error); // Use optional chaining this.bashProcess = null; this.clearQueue( new Error(`Failed to spawn persistent bash: ${getErrorMessage(error)}`), ); } } // --- Parameter Validation (unchanged) --- validateToolParams(params: TerminalToolParams): string | null { if ( !SchemaValidator.validate( this.parameterSchema as Record, params, ) ) { return `Parameters failed schema validation.`; } const commandOriginal = params.command.trim(); if (!commandOriginal) { return 'Command cannot be empty.'; } const commandParts = commandOriginal.split(/[\s;&&|]+/); for (const part of commandParts) { if (!part) continue; // Improved check: strip leading special chars before checking basename const cleanPart = part .replace(/^[^a-zA-Z0-9]+/, '') .split(/[/\\]/) .pop() || part.replace(/^[^a-zA-Z0-9]+/, ''); if (cleanPart && BANNED_COMMAND_ROOTS.includes(cleanPart.toLowerCase())) { return `Command contains a banned keyword: '${cleanPart}'. Banned list includes network tools, session control, etc.`; } } if ( params.timeout !== undefined && (typeof params.timeout !== 'number' || params.timeout <= 0) ) { return 'Timeout must be a positive number of milliseconds.'; } return null; // Parameters are valid } // --- Description and Confirmation (unchanged) --- getDescription(params: TerminalToolParams): string { return params.description || params.command; } async shouldConfirmExecute( params: TerminalToolParams, ): Promise { const rootCommand = params.command .trim() .split(/[\s;&&|]+/)[0] ?.split(/[/\\]/) .pop() || 'unknown'; if (this.shouldAlwaysExecuteCommands.get(rootCommand)) { return false; } const description = this.getDescription(params); const confirmationDetails: ToolExecuteConfirmationDetails = { title: 'Confirm Shell Command', command: params.command, rootCommand, description: `Execute in '${this.currentCwd}':\n${description}`, onConfirm: async (outcome: ToolConfirmationOutcome) => { if (outcome === ToolConfirmationOutcome.ProceedAlways) { this.shouldAlwaysExecuteCommands.set(rootCommand, true); } }, }; return confirmationDetails; } // --- Command Execution and Queueing (unchanged structure) --- async execute(params: TerminalToolParams): Promise { const validationError = this.validateToolParams(params); if (validationError) { return { llmContent: `Command rejected: ${params.command}\nReason: ${validationError}`, returnDisplay: `Error: ${validationError}`, }; } // Assume confirmation is handled before calling execute return new Promise((resolve) => { const queuedItem: QueuedCommand = { params, resolve, // Resolve outer promise reject: (error) => resolve({ // Handle internal errors by resolving outer promise llmContent: `Internal tool error for command: ${params.command}\nError: ${error.message}`, returnDisplay: `Internal Tool Error: ${error.message}`, }), confirmationDetails: false, // Placeholder }; this.commandQueue.push(queuedItem); // Ensure queue processing is triggered *after* adding the item setImmediate(() => this.triggerQueueProcessing()); }); } private async triggerQueueProcessing(): Promise { if (this.isExecuting || this.commandQueue.length === 0) { return; } this.isExecuting = true; const { params, resolve, reject } = this.commandQueue.shift()!; try { await this.shellReady; // Wait for the shell to be ready (or reinitialized) if (!this.bashProcess || this.bashProcess.killed) { // Check if killed throw new Error( 'Persistent bash process is not available or was killed.', ); } // **** Core execution logic call **** const result = await this.executeCommandInShell(params); resolve(result); // Resolve the specific command's promise } catch (error: unknown) { console.error(`Error executing command "${params.command}":`, error); if (error instanceof Error) { reject(error); } else { reject(new Error('Unknown error occurred: ' + JSON.stringify(error))); } } finally { this.isExecuting = false; // Use setImmediate to avoid potential deep recursion setImmediate(() => this.triggerQueueProcessing()); } } // --- **** MODIFIED: Core Command Execution Logic **** --- private executeCommandInShell( params: TerminalToolParams, ): Promise { // Define temp file paths here to be accessible throughout let tempStdoutPath: string | null = null; let tempStderrPath: string | null = null; let originalResolve: (value: ToolResult | PromiseLike) => void; // To pass to polling let originalReject: (reason?: unknown) => void; const promise = new Promise((resolve, reject) => { originalResolve = resolve; // Assign outer scope resolve originalReject = reject; // Assign outer scope reject if (!this.bashProcess) { return reject( new Error('Bash process is not running. Cannot execute command.'), ); } const isBackgroundTask = params.runInBackground ?? false; const commandUUID = crypto.randomUUID(); const startDelimiter = `::START_CMD_${commandUUID}::`; const endDelimiter = `::END_CMD_${commandUUID}::`; const exitCodeDelimiter = `::EXIT_CODE_${commandUUID}::`; const pidDelimiter = `::PID_${commandUUID}::`; // For background PID // --- Initialize Temp Files for Background Task --- if (isBackgroundTask) { try { const tempDir = os.tmpdir(); tempStdoutPath = path.join(tempDir, `term_out_${commandUUID}.log`); tempStderrPath = path.join(tempDir, `term_err_${commandUUID}.log`); } catch (err: unknown) { // If temp dir setup fails, reject immediately return reject( new Error( `Failed to determine temporary directory: ${getErrorMessage(err)}`, ), ); } } // --- End Temp File Init --- let stdoutBuffer = ''; // For launch output let stderrBuffer = ''; // For launch output let commandOutputStarted = false; let exitCode: number | null = null; let backgroundPid: number | null = null; // Store PID let receivedEndDelimiter = false; // Timeout only applies to foreground execution or background *launch* phase const effectiveTimeout = isBackgroundTask ? BACKGROUND_LAUNCH_TIMEOUT_MS : Math.min( params.timeout ?? DEFAULT_TIMEOUT_MS, // Use default timeout if not provided MAX_TIMEOUT_OVERRIDE_MS, ); let onStdoutData: ((data: Buffer) => void) | null = null; let onStderrData: ((data: Buffer) => void) | null = null; let launchTimeoutId: NodeJS.Timeout | null = null; // Renamed for clarity launchTimeoutId = setTimeout(() => { const timeoutMessage = isBackgroundTask ? `Background command launch timed out after ${effectiveTimeout}ms.` : `Command timed out after ${effectiveTimeout}ms.`; if (!isBackgroundTask && this.bashProcess && !this.bashProcess.killed) { try { this.bashProcess.stdin.write('\x03'); // Ctrl+C for foreground timeout } catch (e: unknown) { console.error('Error writing SIGINT on timeout:', e); } } // Store listeners before calling cleanup, as cleanup nullifies them const listenersToClean = { onStdoutData, onStderrData }; cleanupListeners(listenersToClean); // Clean up listeners for this command // Clean up temp files if background launch timed out if (isBackgroundTask && tempStdoutPath && tempStderrPath) { this.cleanupTempFiles(tempStdoutPath, tempStderrPath).catch((err) => { console.warn( `Error cleaning up temp files on timeout: ${err.message}`, ); }); } // Resolve the main promise with timeout info originalResolve({ llmContent: `Command execution failed: ${timeoutMessage}\nCommand: ${params.command}\nExecuted in: ${this.currentCwd}\n${isBackgroundTask ? 'Mode: Background Launch' : `Mode: Foreground\nTimeout Limit: ${effectiveTimeout}ms`}\nPartial Stdout (Launch):\n${this.truncateOutput(stdoutBuffer)}\nPartial Stderr (Launch):\n${this.truncateOutput(stderrBuffer)}\nNote: ${isBackgroundTask ? 'Launch failed or took too long.' : 'Attempted interrupt (SIGINT). Shell state might be unpredictable if command ignored interrupt.'}`, returnDisplay: `Timeout: ${timeoutMessage}`, }); }, effectiveTimeout); // --- Data processing logic (refined slightly) --- const processDataChunk = (chunk: string, isStderr: boolean): boolean => { let dataToProcess = chunk; if (!commandOutputStarted) { const startIndex = dataToProcess.indexOf(startDelimiter); if (startIndex !== -1) { commandOutputStarted = true; dataToProcess = dataToProcess.substring( startIndex + startDelimiter.length, ); } else { return false; // Still waiting for start delimiter } } // Process PID delimiter (mostly expected on stderr for background) const pidIndex = dataToProcess.indexOf(pidDelimiter); if (pidIndex !== -1) { // Extract PID value strictly between delimiter and newline/end const pidMatch = dataToProcess .substring(pidIndex + pidDelimiter.length) .match(/^(\d+)/); if (pidMatch?.[1]) { backgroundPid = parseInt(pidMatch[1], 10); const pidEndIndex = pidIndex + pidDelimiter.length + pidMatch[1].length; const beforePid = dataToProcess.substring(0, pidIndex); if (isStderr) stderrBuffer += beforePid; else stdoutBuffer += beforePid; dataToProcess = dataToProcess.substring(pidEndIndex); } else { // Consume delimiter even if no number followed const beforePid = dataToProcess.substring(0, pidIndex); if (isStderr) stderrBuffer += beforePid; else stdoutBuffer += beforePid; dataToProcess = dataToProcess.substring( pidIndex + pidDelimiter.length, ); } } // Process Exit Code delimiter const exitCodeIndex = dataToProcess.indexOf(exitCodeDelimiter); if (exitCodeIndex !== -1) { const exitCodeMatch = dataToProcess .substring(exitCodeIndex + exitCodeDelimiter.length) .match(/^(\d+)/); if (exitCodeMatch?.[1]) { exitCode = parseInt(exitCodeMatch[1], 10); const beforeExitCode = dataToProcess.substring(0, exitCodeIndex); if (isStderr) stderrBuffer += beforeExitCode; else stdoutBuffer += beforeExitCode; dataToProcess = dataToProcess.substring( exitCodeIndex + exitCodeDelimiter.length + exitCodeMatch[1].length, ); } else { const beforeExitCode = dataToProcess.substring(0, exitCodeIndex); if (isStderr) stderrBuffer += beforeExitCode; else stdoutBuffer += beforeExitCode; dataToProcess = dataToProcess.substring( exitCodeIndex + exitCodeDelimiter.length, ); } } // Process End delimiter const endDelimiterIndex = dataToProcess.indexOf(endDelimiter); if (endDelimiterIndex !== -1) { receivedEndDelimiter = true; const beforeEndDelimiter = dataToProcess.substring( 0, endDelimiterIndex, ); if (isStderr) stderrBuffer += beforeEndDelimiter; else stdoutBuffer += beforeEndDelimiter; // Consume delimiter and potentially the exit code echoed after it const afterEndDelimiter = dataToProcess.substring( endDelimiterIndex + endDelimiter.length, ); const exitCodeEchoMatch = afterEndDelimiter.match(/^(\d+)/); dataToProcess = exitCodeEchoMatch ? afterEndDelimiter.substring(exitCodeEchoMatch[1].length) : afterEndDelimiter; } // Append remaining data if (dataToProcess.length > 0) { if (isStderr) stderrBuffer += dataToProcess; else stdoutBuffer += dataToProcess; } // Check completion criteria if (receivedEndDelimiter && exitCode !== null) { setImmediate(cleanupAndResolve); // Use setImmediate return true; // Signal completion of this command's stream processing } return false; // More data or delimiters expected }; // Assign listeners onStdoutData = (data: Buffer) => processDataChunk(data.toString(), false); onStderrData = (data: Buffer) => processDataChunk(data.toString(), true); // --- Cleanup Logic --- // Pass listeners to allow cleanup even if they are nullified later const cleanupListeners = (listeners?: { onStdoutData: ((data: Buffer) => void) | null; onStderrData: ((data: Buffer) => void) | null; }) => { if (launchTimeoutId) clearTimeout(launchTimeoutId); launchTimeoutId = null; // Use passed-in listeners if available, otherwise use current scope's const stdoutListener = listeners?.onStdoutData ?? onStdoutData; const stderrListener = listeners?.onStderrData ?? onStderrData; if (this.bashProcess && !this.bashProcess.killed) { if (stdoutListener) this.bashProcess.stdout.removeListener('data', stdoutListener); if (stderrListener) this.bashProcess.stderr.removeListener('data', stderrListener); } // Only nullify the *current command's* cleanup reference if it matches if (this.currentCommandCleanup === cleanupListeners) { this.currentCommandCleanup = null; } // Nullify the listener references in the outer scope regardless onStdoutData = null; onStderrData = null; }; // Store *this specific* cleanup function instance for the current command this.currentCommandCleanup = cleanupListeners; // --- Final Resolution / Polling Logic --- const cleanupAndResolve = async () => { // Prevent double execution if cleanup was already called (e.g., by timeout) if ( !this.currentCommandCleanup || this.currentCommandCleanup !== cleanupListeners ) { // Ensure temp files are cleaned if this command was superseded but might have created them if (isBackgroundTask && tempStdoutPath && tempStderrPath) { this.cleanupTempFiles(tempStdoutPath, tempStderrPath).catch( (err) => { console.warn( `Error cleaning up temp files for superseded command: ${err.message}`, ); }, ); } return; } // Capture initial output *before* cleanup nullifies buffers indirectly const launchStdout = this.truncateOutput(stdoutBuffer); const launchStderr = this.truncateOutput(stderrBuffer); // Store listeners before calling cleanup const listenersToClean = { onStdoutData, onStderrData }; cleanupListeners(listenersToClean); // Remove listeners and clear launch timeout NOW // --- Error check for missing exit code --- if (exitCode === null) { console.error( `CRITICAL: Command "${params.command}" (background: ${isBackgroundTask}) finished delimiter processing but exitCode is null.`, ); const errorMode = isBackgroundTask ? 'Background Launch' : 'Foreground'; if (isBackgroundTask && tempStdoutPath && tempStderrPath) { await this.cleanupTempFiles(tempStdoutPath, tempStderrPath); } originalResolve({ // Use originalResolve as this is a failure *before* polling starts llmContent: `Command: ${params.command}\nExecuted in: ${this.currentCwd}\nMode: ${errorMode}\nExit Code: -2 (Internal Error: Exit code not captured)\nStdout (during setup):\n${launchStdout}\nStderr (during setup):\n${launchStderr}`, returnDisplay: `Internal Error: Failed to capture command exit code.\n${launchStdout}\nStderr: ${launchStderr}`.trim(), }); return; } // --- CWD Update Logic (Only for Foreground Success or 'cd') --- let cwdUpdateError = ''; if (!isBackgroundTask) { // Only run for foreground const mightChangeCwd = params.command.trim().startsWith('cd '); if (exitCode === 0 || mightChangeCwd) { try { const latestCwd = await this.getCurrentShellCwd(); if (this.currentCwd !== latestCwd) { this.currentCwd = latestCwd; } } catch (e: unknown) { if (exitCode === 0) { // Only warn if the command itself succeeded cwdUpdateError = `\nWarning: Failed to verify/update current working directory after command: ${getErrorMessage(e)}`; console.error( 'Failed to update CWD after successful command:', e, ); } } } } // --- End CWD Update --- // --- Result Formatting & Polling Decision --- if (isBackgroundTask) { const launchSuccess = exitCode === 0; const pidString = backgroundPid !== null ? backgroundPid.toString() : 'Not Captured'; // Check if polling should start if ( launchSuccess && backgroundPid !== null && tempStdoutPath && tempStderrPath ) { // --- START POLLING --- // Don't await this, let it run in the background and resolve the original promise later this.inspectBackgroundProcess( backgroundPid, params.command, this.currentCwd, // CWD at time of launch launchStdout, // Initial output captured during launch launchStderr, // Initial output captured during launch tempStdoutPath, // Path for final stdout tempStderrPath, // Path for final stderr originalResolve, // The resolve function of the main promise ); // IMPORTANT: Do NOT resolve the promise here. pollBackgroundProcess will do it. // --- END POLLING --- } else { // Background launch failed OR PID was not captured OR temp files missing const reason = backgroundPid === null ? 'PID not captured' : `Launch failed (Exit Code: ${exitCode})`; const displayMessage = `Failed to launch process in background (${reason})`; console.error( `Background launch failed for command: ${params.command}. Reason: ${reason}`, ); // ERROR LOG // Ensure cleanup of temp files if launch failed if (tempStdoutPath && tempStderrPath) { await this.cleanupTempFiles(tempStdoutPath, tempStderrPath); } originalResolve({ // Use originalResolve as polling won't start llmContent: `Background Command Launch Failed: ${params.command}\nExecuted in: ${this.currentCwd}\nReason: ${reason}\nPID: ${pidString}\nExit Code (Launch): ${exitCode}\nStdout (During Launch):\n${launchStdout}\nStderr (During Launch):\n${launchStderr}`, returnDisplay: displayMessage, }); } } else { // --- Foreground task result (resolve immediately) --- let displayOutput = ''; const stdoutTrimmed = launchStdout.trim(); const stderrTrimmed = launchStderr.trim(); if (stderrTrimmed) { displayOutput = stderrTrimmed; } else if (stdoutTrimmed) { displayOutput = stdoutTrimmed; } if (exitCode !== 0 && !displayOutput) { displayOutput = `Failed with exit code: ${exitCode}`; } else if (exitCode === 0 && !displayOutput) { displayOutput = `Success (no output)`; } originalResolve({ // Use originalResolve for foreground result llmContent: `Command: ${params.command}\nExecuted in: ${this.currentCwd}\nExit Code: ${exitCode}\nStdout:\n${launchStdout}\nStderr:\n${launchStderr}${cwdUpdateError}`, returnDisplay: displayOutput.trim() || `Exit Code: ${exitCode}`, // Ensure some display }); // --- End Foreground Result --- } }; // End of cleanupAndResolve // --- Attach listeners --- if (!this.bashProcess || this.bashProcess.killed) { console.error( 'Bash process lost or killed before listeners could be attached.', ); // Ensure temp files are cleaned up if they exist if (isBackgroundTask && tempStdoutPath && tempStderrPath) { this.cleanupTempFiles(tempStdoutPath, tempStderrPath).catch((err) => { console.warn( `Error cleaning up temp files on attach failure: ${err.message}`, ); }); } return originalReject( new Error( 'Bash process lost or killed before listeners could be attached.', ), ); } // Defensive remove shouldn't be strictly necessary with current cleanup logic, but harmless // if (onStdoutData) this.bashProcess.stdout.removeListener('data', onStdoutData); // if (onStderrData) this.bashProcess.stderr.removeListener('data', onStderrData); // Attach the fresh listeners if (onStdoutData) this.bashProcess.stdout.on('data', onStdoutData); if (onStderrData) this.bashProcess.stderr.on('data', onStderrData); // --- Construct and Write Command --- let commandToWrite: string; if (isBackgroundTask && tempStdoutPath && tempStderrPath) { // Background: Redirect command's stdout/stderr to temp files. // Use subshell { ... } > file 2> file to redirect the command inside. // Capture PID of the subshell. Capture exit code of the subshell launch. // Ensure the subshell itself doesn't interfere with delimiter capture on stderr. commandToWrite = `echo "${startDelimiter}"; { { ${params.command} > "${tempStdoutPath}" 2> "${tempStderrPath}"; } & } 2>/dev/null; __LAST_PID=$!; echo "${pidDelimiter}$__LAST_PID" >&2; echo "${exitCodeDelimiter}$?" >&2; echo "${endDelimiter}$?" >&1\n`; } else if (!isBackgroundTask) { // Foreground: Original structure. Capture command exit code. commandToWrite = `echo "${startDelimiter}"; ${params.command}; __EXIT_CODE=$?; echo "${exitCodeDelimiter}$__EXIT_CODE" >&2; echo "${endDelimiter}$__EXIT_CODE" >&1\n`; } else { // Should not happen if background task setup failed, but handle defensively return originalReject( new Error( 'Internal setup error: Missing temporary file paths for background execution.', ), ); } try { if (this.bashProcess?.stdin?.writable) { this.bashProcess.stdin.write(commandToWrite, (err) => { if (err) { console.error( `Error writing command "${params.command}" to bash stdin (callback):`, err, ); // Store listeners before calling cleanup const listenersToClean = { onStdoutData, onStderrData, }; cleanupListeners(listenersToClean); // Attempt cleanup if (isBackgroundTask && tempStdoutPath && tempStderrPath) { this.cleanupTempFiles(tempStdoutPath, tempStderrPath).catch( (e) => console.warn(`Cleanup failed: ${e.message}`), ); } originalReject( new Error( `Shell stdin write error: ${err.message}. Command likely did not execute.`, ), ); } }); } else { throw new Error( 'Shell stdin is not writable or process closed when attempting to write command.', ); } } catch (e: unknown) { console.error( `Error writing command "${params.command}" to bash stdin (sync):`, e, ); // Store listeners before calling cleanup const listenersToClean = { onStdoutData, onStderrData }; cleanupListeners(listenersToClean); // Attempt cleanup if (isBackgroundTask && tempStdoutPath && tempStderrPath) { this.cleanupTempFiles(tempStdoutPath, tempStderrPath).catch((err) => console.warn(`Cleanup failed: ${err.message}`), ); } originalReject( new Error( `Shell stdin write exception: ${getErrorMessage(e)}. Command likely did not execute.`, ), ); } }); // End of main promise constructor return promise; // Return the promise created at the top } // End of executeCommandInShell // --- **** NEW: Background Process Polling **** --- private async inspectBackgroundProcess( pid: number, command: string, cwd: string, initialStdout: string, // Stdout during launch phase initialStderr: string, // Stderr during launch phase tempStdoutPath: string, // Path to redirected stdout tempStderrPath: string, // Path to redirected stderr resolve: (value: ToolResult | PromiseLike) => void, // The original promise's resolve ): Promise { // This function manages its own lifecycle but resolves the outer promise let finalStdout = ''; let finalStderr = ''; let llmAnalysis = ''; let fileReadError = ''; // --- Call LLM Analysis --- try { const { status, summary } = await this.backgroundTerminalAnalyzer.analyze( pid, tempStdoutPath, tempStderrPath, command, ); if (status === 'Unknown') llmAnalysis = `LLM analysis failed: ${summary}`; else llmAnalysis = summary; } catch (llmerror: unknown) { console.error( `LLM analysis failed for PID ${pid} command "${command}":`, llmerror, ); llmAnalysis = `LLM analysis failed: ${getErrorMessage(llmerror)}`; // Include error in analysis placeholder } // --- End LLM Call --- try { finalStdout = await fs.readFile(tempStdoutPath, 'utf-8'); finalStderr = await fs.readFile(tempStderrPath, 'utf-8'); } catch (err: unknown) { console.error(`Error reading temp output files for PID ${pid}:`, err); fileReadError = `\nWarning: Failed to read temporary output files (${getErrorMessage(err)}). Final output may be incomplete.`; } // --- Clean up temp files --- await this.cleanupTempFiles(tempStdoutPath, tempStderrPath); // --- End Cleanup --- const truncatedFinalStdout = this.truncateOutput(finalStdout); const truncatedFinalStderr = this.truncateOutput(finalStderr); // Resolve the original promise passed into pollBackgroundProcess resolve({ llmContent: `Background Command: ${command}\nLaunched in: ${cwd}\nPID: ${pid}\n--- LLM Analysis ---\n${llmAnalysis}\n--- Final Stdout (from ${path.basename(tempStdoutPath)}) ---\n${truncatedFinalStdout}\n--- Final Stderr (from ${path.basename(tempStderrPath)}) ---\n${truncatedFinalStderr}\n--- Launch Stdout ---\n${initialStdout}\n--- Launch Stderr ---\n${initialStderr}${fileReadError}`, returnDisplay: `(PID: ${pid}): ${this.truncateOutput(llmAnalysis, 200)}`, }); } // End of pollBackgroundProcess // --- **** NEW: Helper to cleanup temp files **** --- private async cleanupTempFiles( stdoutPath: string | null, stderrPath: string | null, ): Promise { const unlinkQuietly = async (filePath: string | null) => { if (!filePath) return; try { await fs.unlink(filePath); } catch (err: unknown) { // Ignore errors like file not found (it might have been deleted already or failed to create) if (!isNodeError(err) || err.code !== 'ENOENT') { console.warn( `Failed to delete temporary file '${filePath}': ${getErrorMessage(err)}`, ); } } }; // Run deletions concurrently and wait for both await Promise.all([unlinkQuietly(stdoutPath), unlinkQuietly(stderrPath)]); } // --- Get CWD (mostly unchanged, added robustness) --- private getCurrentShellCwd(): Promise { return new Promise((resolve, reject) => { if ( !this.bashProcess || !this.bashProcess.stdin?.writable || this.bashProcess.killed ) { return reject( new Error( 'Shell not running, stdin not writable, or killed for PWD check', ), ); } const pwdUuid = crypto.randomUUID(); const pwdDelimiter = `::PWD_${pwdUuid}::`; let pwdOutput = ''; let onPwdData: ((data: Buffer) => void) | null = null; let onPwdError: ((data: Buffer) => void) | null = null; // To catch errors during pwd let pwdTimeoutId: NodeJS.Timeout | null = null; let finished = false; // Prevent double resolution/rejection const cleanupPwdListeners = (err?: Error) => { if (finished) return; // Already handled finished = true; if (pwdTimeoutId) clearTimeout(pwdTimeoutId); pwdTimeoutId = null; const stdoutListener = onPwdData; // Capture current reference const stderrListener = onPwdError; // Capture current reference onPwdData = null; // Nullify before removing onPwdError = null; if (this.bashProcess && !this.bashProcess.killed) { if (stdoutListener) this.bashProcess.stdout.removeListener('data', stdoutListener); if (stderrListener) this.bashProcess.stderr.removeListener('data', stderrListener); } if (err) { reject(err); } else { // Trim whitespace and trailing newlines robustly resolve(pwdOutput.trim()); } }; onPwdData = (data: Buffer) => { if (!onPwdData) return; // Listener removed const dataStr = data.toString(); const delimiterIndex = dataStr.indexOf(pwdDelimiter); if (delimiterIndex !== -1) { pwdOutput += dataStr.substring(0, delimiterIndex); cleanupPwdListeners(); // Resolve successfully } else { pwdOutput += dataStr; } }; onPwdError = (data: Buffer) => { if (!onPwdError) return; // Listener removed const dataStr = data.toString(); // If delimiter appears on stderr, or any stderr occurs, treat as error console.error(`Error during PWD check: ${dataStr}`); cleanupPwdListeners( new Error( `Stderr received during pwd check: ${this.truncateOutput(dataStr, 100)}`, ), ); }; // Attach listeners this.bashProcess.stdout.on('data', onPwdData); this.bashProcess.stderr.on('data', onPwdError); // Set timeout pwdTimeoutId = setTimeout(() => { cleanupPwdListeners(new Error('Timeout waiting for pwd response')); }, 5000); // 5 second timeout for pwd // Write command try { // Use printf for robustness against special characters in PWD and ensure newline const pwdCommand = `printf "%s" "$PWD"; printf "${pwdDelimiter}";\n`; if (this.bashProcess?.stdin?.writable) { this.bashProcess.stdin.write(pwdCommand, (err) => { if (err) { // Error during write callback, likely means shell is unresponsive console.error('Error writing pwd command (callback):', err); cleanupPwdListeners( new Error(`Failed to write pwd command: ${err.message}`), ); } }); } else { throw new Error('Shell stdin not writable for pwd command.'); } } catch (e: unknown) { console.error('Exception writing pwd command:', e); cleanupPwdListeners( new Error(`Exception writing pwd command: ${getErrorMessage(e)}`), ); } }); } // --- Truncate Output (unchanged) --- private truncateOutput(output: string, limit?: number): string { const effectiveLimit = limit ?? this.outputLimit; if (output.length > effectiveLimit) { return ( output.substring(0, effectiveLimit) + `\n... [Output truncated at ${effectiveLimit} characters]` ); } return output; } // --- Clear Queue (unchanged) --- private clearQueue(error: Error) { const queue = this.commandQueue; this.commandQueue = []; queue.forEach(({ resolve, params }) => resolve({ llmContent: `Command cancelled: ${params.command}\nReason: ${error.message}`, returnDisplay: `Command Cancelled: ${error.message}`, }), ); } // --- Destroy (Added cleanup for pending background tasks if possible) --- destroy() { // Reject any pending shell readiness promise this.rejectShellReady?.( new Error('BashTool destroyed during initialization or operation.'), ); this.rejectShellReady = undefined; // Prevent further calls this.resolveShellReady = undefined; this.clearQueue(new Error('BashTool is being destroyed.')); // Attempt to cleanup listeners for the *currently executing* command, if any try { this.currentCommandCleanup?.(); } catch (e) { console.warn('Error during current command cleanup:', e); } // Handle the bash process itself if (this.bashProcess) { const proc = this.bashProcess; // Reference before nullifying const pid = proc.pid; this.bashProcess = null; // Nullify reference immediately proc.stdout?.removeAllListeners(); proc.stderr?.removeAllListeners(); proc.removeAllListeners('error'); proc.removeAllListeners('close'); // Ensure stdin is closed proc.stdin?.end(); try { // Don't wait for these, just attempt proc.kill('SIGTERM'); // Attempt graceful first setTimeout(() => { if (!proc.killed) { proc.kill('SIGKILL'); // Force kill if needed } }, 500); // 500ms grace period } catch (e: unknown) { // Catch errors if process already exited etc. console.warn( `Error trying to kill bash process PID: ${pid}: ${getErrorMessage(e)}`, ); } } // Note: We cannot reliably clean up temp files for background tasks // that were polling when destroy() was called without more complex state tracking. // OS should eventually clean /tmp, or implement a startup cleanup routine if needed. } } // End of TerminalTool class