path: root/packages/cli/src/tools/terminal.tool.ts

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<TerminalToolParams, ToolResult> {
  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<string, boolean> = new Map(); // Track confirmation per root command
  private shellReady: Promise<void>;
  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<string, unknown>,
        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<ToolCallConfirmationDetails | false> {
    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<ToolResult> {
    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<void> {
    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<ToolResult> {
    // Define temp file paths here to be accessible throughout
    let tempStdoutPath: string | null = null;
    let tempStderrPath: string | null = null;
    let originalResolve: (value: ToolResult | PromiseLike<ToolResult>) => void; // To pass to polling
    let originalReject: (reason?: unknown) => void;

    const promise = new Promise<ToolResult>((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<ToolResult>) => void, // The original promise's resolve
  ): Promise<void> {
    // 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<void> {
    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<string> {
    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