🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat: refactor terminal_toolkit (#3015)
Tao Sun7d74fcba8a87
diff --git a/camel/toolkits/terminal_toolkit.py b/camel/toolkits/terminal_toolkit.pydeleted file mode 100644index 540811f02..000000000--- a/camel/toolkits/terminal_toolkit.py+++ /dev/null@@ -1,1798 +0,0 @@-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========-# Licensed under the Apache License, Version 2.0 (the "License");-# you may not use this file except in compliance with the License.-# You may obtain a copy of the License at-#-# http://www.apache.org/licenses/LICENSE-2.0-#-# Unless required by applicable law or agreed to in writing, software-# distributed under the License is distributed on an "AS IS" BASIS,-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.-# See the License for the specific language governing permissions and-# limitations under the License.-# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========--import atexit-import os-import platform-import queue-import shutil-import signal-import subprocess-import sys-import threading-import venv-from queue import Queue-from typing import Any, Dict, List, Optional, Tuple--from camel.logger import get_logger-from camel.toolkits.base import BaseToolkit-from camel.toolkits.function_tool import FunctionTool-from camel.utils import MCPServer--logger = get_logger(__name__)---@MCPServer()-class TerminalToolkit(BaseToolkit):- r"""A toolkit for terminal operations across multiple operating systems.-- This toolkit provides a set of functions for terminal operations such as- searching for files by name or content, executing shell commands, and- managing terminal sessions.-- Args:- timeout (Optional[float]): The timeout for terminal operations.- (default: :obj:`20.0`)- shell_sessions (Optional[Dict[str, Any]]): A dictionary to store- shell session information. If :obj:`None`, an empty dictionary- will be used. (default: :obj:`None`)- working_directory (Optional[str]): The working directory for- operations. If not provided, it will be determined by the- `CAMEL_WORKDIR` environment variable (if set). If the- environment variable is not set, it defaults to `./workspace`. All- execution and write operations will be restricted to this- directory. Read operations can access paths outside this- directory. (default: :obj:`None`)- need_terminal (bool): Whether to create a terminal interface.- (default: :obj:`True`)- use_shell_mode (bool): Whether to use shell mode for command- execution. (default: :obj:`True`)- clone_current_env (bool): Whether to clone the current Python- environment. (default: :obj:`False`)- safe_mode (bool): Whether to enable safe mode to restrict- operations. (default: :obj:`True`)- interactive (bool): Whether to use interactive mode for shell commands,- connecting them to the terminal's standard input. This is useful- for commands that require user input, like `ssh`. Interactive mode- is only supported on macOS and Linux. (default: :obj:`False`)- log_dir (Optional[str]): Custom directory path for log files.- If None, logs are saved to the current working directory.- (default: :obj:`None`)-- Note:- Most functions are compatible with Unix-based systems (macOS, Linux).- For Windows compatibility, additional implementation details are- needed.- """-- def __init__(- self,- timeout: Optional[float] = 20.0,- shell_sessions: Optional[Dict[str, Any]] = None,- working_directory: Optional[str] = None,- need_terminal: bool = True,- use_shell_mode: bool = True,- clone_current_env: bool = False,- safe_mode: bool = True,- interactive: bool = False,- log_dir: Optional[str] = None,- ):- # Store timeout before calling super().__init__- self._timeout = timeout- super().__init__(timeout=timeout)- self.shell_sessions = shell_sessions or {}- self.os_type = platform.system()- self.output_queue: Queue[str] = Queue()- self.agent_queue: Queue[str] = Queue()- self.terminal_ready = threading.Event()- self.gui_thread = None- self.safe_mode = safe_mode- self._file_initialized = False- self.cloned_env_path = None- self.use_shell_mode = use_shell_mode- self._human_takeover_active = False- self.interactive = interactive- self.log_dir = log_dir-- self.python_executable = sys.executable- self.is_macos = platform.system() == 'Darwin'- self.initial_env_path: Optional[str] = None- self.initial_env_prepared = False- self.uv_path: Optional[str] = None-- atexit.register(self.__del__)-- if working_directory:- self.working_dir = os.path.abspath(working_directory)- else:- camel_workdir = os.environ.get("CAMEL_WORKDIR")- if camel_workdir:- self.working_dir = os.path.abspath(camel_workdir)- else:- self.working_dir = os.path.abspath("./workspace")-- if not os.path.exists(self.working_dir):- os.makedirs(self.working_dir, exist_ok=True)- self._update_terminal_output(- f"Working directory set to: {self.working_dir}\n"- )- if self.safe_mode:- self._update_terminal_output(- "Safe mode enabled: Write operations can only "- "be performed within the working directory\n"- )-- if clone_current_env:- self.cloned_env_path = os.path.join(self.working_dir, ".venv")- self._clone_current_environment()- else:- self.cloned_env_path = None- self._prepare_initial_environment()-- if need_terminal:- if self.is_macos:- # macOS uses non-GUI mode- logger.info("Detected macOS environment, using non-GUI mode")- self._setup_file_output()- self.terminal_ready.set()- else:- # Other platforms use normal GUI- self.gui_thread = threading.Thread(- target=self._create_terminal, daemon=True- )- self.gui_thread.start()- self.terminal_ready.wait(timeout=5)-- def _setup_file_output(self):- r"""Set up file output to replace GUI, using a fixed file to simulate- terminal.- """- # Use custom log directory if provided, otherwise use current directory- if self.log_dir:- # Create the log directory if it doesn't exist- os.makedirs(self.log_dir, exist_ok=True)- self.log_file = os.path.join(self.log_dir, "camel_terminal.txt")- else:- self.log_file = os.path.join(os.getcwd(), "camel_terminal.txt")-- # Inform the user- logger.info(f"Terminal output will be redirected to: {self.log_file}")-- def file_update(output: str):- import sys-- try:- # For macOS/Linux file-based mode, also write to stdout- # to provide real-time feedback in the user's terminal.- sys.stdout.write(output)- sys.stdout.flush()-- # Initialize file on first write- if not self._file_initialized:- with open(self.log_file, "w") as f:- f.write("CAMEL Terminal Session\n")- f.write("=" * 50 + "\n")- f.write(f"Working Directory: {os.getcwd()}\n")- f.write("=" * 50 + "\n\n")- self._file_initialized = True-- # Directly append to the end of the file- with open(self.log_file, "a") as f:- f.write(output)- # Ensure the agent also receives the output- self.agent_queue.put(output)- except Exception as e:- logger.error(f"Failed to write to terminal: {e}")-- # Replace the update method- self._update_terminal_output = file_update-- def _clone_current_environment(self):- r"""Create a new Python virtual environment."""- try:- if self.cloned_env_path is None:- self._update_terminal_output(- "Error: No environment path specified\n"- )- return-- if os.path.exists(self.cloned_env_path):- self._update_terminal_output(- f"Using existing environment: {self.cloned_env_path}\n"- )- return-- self._update_terminal_output(- f"Creating new Python environment at: {self.cloned_env_path}\n"- )-- # Try to use uv if available- if self._ensure_uv_available():- # Use uv to create environment with current Python version- uv_command = self.uv_path if self.uv_path else "uv"-- # Get current Python version- current_version = (- f"{sys.version_info.major}.{sys.version_info.minor}"- )-- subprocess.run(- [- uv_command,- "venv",- "--python",- current_version,- self.cloned_env_path,- ],- check=True,- capture_output=True,- cwd=self.working_dir,- timeout=300,- )-- # Get the python path from the new environment- if self.os_type == 'Windows':- python_path = os.path.join(- self.cloned_env_path, "Scripts", "python.exe"- )- else:- python_path = os.path.join(- self.cloned_env_path, "bin", "python"- )-- # Install pip and setuptools using uv- subprocess.run(- [- uv_command,- "pip",- "install",- "--python",- python_path,- "pip",- "setuptools",- "wheel",- ],- check=True,- capture_output=True,- cwd=self.working_dir,- timeout=300,- )-- self._update_terminal_output(- "[UV] Cloned Python environment created successfully!\n"- )-- else:- # Fallback to standard venv- self._update_terminal_output(- "Falling back to standard venv for cloning environment\n"- )-- # Create virtual environment with pip. On macOS, use- # symlinks=False to avoid dyld library loading issues- venv.create(- self.cloned_env_path, with_pip=True, symlinks=False- )-- # Ensure pip is properly available by upgrading it- if self.os_type == 'Windows':- python_path = os.path.join(- self.cloned_env_path, "Scripts", "python.exe"- )- else:- python_path = os.path.join(- self.cloned_env_path, "bin", "python"- )-- # Verify python executable exists- if os.path.exists(python_path):- # Use python -m pip to ensure pip is available- subprocess.run(- [- python_path,- "-m",- "pip",- "install",- "--upgrade",- "pip",- ],- check=True,- capture_output=True,- cwd=self.working_dir,- timeout=60,- )- self._update_terminal_output(- "New Python environment created successfully "- "with pip!\n"- )- else:- self._update_terminal_output(- f"Warning: Python executable not found "- f"at {python_path}\n"- )-- except subprocess.CalledProcessError as e:- error_msg = e.stderr.decode() if e.stderr else str(e)- self._update_terminal_output(- f"Failed to upgrade pip in cloned environment: {error_msg}\n"- )- logger.error(f"Failed to upgrade pip: {error_msg}")- except subprocess.TimeoutExpired:- self._update_terminal_output(- "Pip upgrade timed out, but environment may still be usable\n"- )- except Exception as e:- self._update_terminal_output(- f"Failed to create environment: {e!s}\n"- )- logger.error(f"Failed to create environment: {e}")-- def _is_uv_environment(self) -> bool:- r"""Detect whether the current Python runtime is managed by uv."""- return (- "UV_CACHE_DIR" in os.environ- or "uv" in sys.executable- or shutil.which("uv") is not None- )-- def _ensure_uv_available(self) -> bool:- r"""Ensure uv is available, installing it if necessary.-- Returns:- bool: True if uv is available (either already installed or- successfully installed), False otherwise.- """- # Check if uv is already available- existing_uv = shutil.which("uv")- if existing_uv is not None:- self.uv_path = existing_uv- self._update_terminal_output(- f"uv is already available at: {self.uv_path}\n"- )- return True-- try:- self._update_terminal_output("uv not found, installing...\n")-- # Install uv using the official installer script- if self.os_type in ['Darwin', 'Linux']:- # Use curl to download and execute the installer- install_cmd = "curl -LsSf https://astral.sh/uv/install.sh | sh"- result = subprocess.run(- install_cmd,- shell=True,- capture_output=True,- text=True,- timeout=60,- )-- if result.returncode != 0:- self._update_terminal_output(- f"Failed to install uv: {result.stderr}\n"- )- return False-- # Check if uv was installed in the expected location- home = os.path.expanduser("~")- uv_bin_path = os.path.join(home, ".cargo", "bin")- uv_executable = os.path.join(uv_bin_path, "uv")-- if os.path.exists(uv_executable):- # Store the full path to uv instead of modifying PATH- self.uv_path = uv_executable- self._update_terminal_output(- f"uv installed successfully at: {self.uv_path}\n"- )- return True-- elif self.os_type == 'Windows':- # Use PowerShell to install uv on Windows- install_cmd = (- "powershell -ExecutionPolicy Bypass -c "- "\"irm https://astral.sh/uv/install.ps1 | iex\""- )- result = subprocess.run(- install_cmd,- shell=True,- capture_output=True,- text=True,- timeout=60,- )-- if result.returncode != 0:- self._update_terminal_output(- f"Failed to install uv: {result.stderr}\n"- )- return False-- # Check if uv was installed in the expected location on Windows- home = os.path.expanduser("~")- uv_bin_path = os.path.join(home, ".cargo", "bin")- uv_executable = os.path.join(uv_bin_path, "uv.exe")-- if os.path.exists(uv_executable):- # Store the full path to uv instead of modifying PATH- self.uv_path = uv_executable- self._update_terminal_output(- f"uv installed successfully at: {self.uv_path}\n"- )- return True-- self._update_terminal_output("Failed to verify uv installation\n")- return False-- except Exception as e:- self._update_terminal_output(f"Error installing uv: {e!s}\n")- logger.error(f"Failed to install uv: {e}")- return False-- def _prepare_initial_environment(self):- r"""Prepare initial environment with Python 3.10, pip, and other- essential tools.- """- try:- self.initial_env_path = os.path.join(- self.working_dir, ".initial_env"- )-- if os.path.exists(self.initial_env_path):- self._update_terminal_output(- f"Using existing initial environment"- f": {self.initial_env_path}\n"- )- self.initial_env_prepared = True- return-- self._update_terminal_output(- f"Preparing initial environment at: {self.initial_env_path}\n"- )-- # Create the initial environment directory- os.makedirs(self.initial_env_path, exist_ok=True)-- # Try to ensure uv is available and use it preferentially- if self._ensure_uv_available():- self._setup_initial_env_with_uv()- else:- # Fallback to venv if uv installation failed- self._update_terminal_output(- "Falling back to standard venv for environment setup\n"- )- self._setup_initial_env_with_venv()-- self.initial_env_prepared = True- self._update_terminal_output(- "Initial environment prepared successfully!\n"- )-- except Exception as e:- self._update_terminal_output(- f"Failed to prepare initial environment: {e!s}\n"- )- logger.error(f"Failed to prepare initial environment: {e}")-- def _setup_initial_env_with_uv(self):- r"""Set up initial environment using uv."""- if self.initial_env_path is None:- raise Exception("Initial environment path not set")-- try:- # Use the stored uv path if available, otherwise fall back to "uv"- uv_command = self.uv_path if self.uv_path else "uv"-- # Create virtual environment with Python 3.10 using uv- subprocess.run(- [- uv_command,- "venv",- "--python",- "3.10",- self.initial_env_path,- ],- check=True,- capture_output=True,- cwd=self.working_dir,- timeout=300,- )-- # Get the python path from the new environment- if self.os_type == 'Windows':- python_path = os.path.join(- self.initial_env_path, "Scripts", "python.exe"- )- else:- python_path = os.path.join(- self.initial_env_path, "bin", "python"- )-- # Install essential packages using uv- essential_packages = [- "pip",- "setuptools",- "wheel",- "pyautogui",- "plotly",- "ffmpeg",- ]- subprocess.run(- [- uv_command,- "pip",- "install",- "--python",- python_path,- *essential_packages,- ],- check=True,- capture_output=True,- cwd=self.working_dir,- timeout=300,- )-- # Check if Node.js is available (but don't install it)- self._check_nodejs_availability()-- self._update_terminal_output(- "[UV] Initial environment created with Python 3.10 "- "and essential packages\n"- )-- except subprocess.CalledProcessError as e:- error_msg = e.stderr.decode() if e.stderr else str(e)- raise Exception(f"UV setup failed: {error_msg}")- except subprocess.TimeoutExpired:- raise Exception("UV setup timed out after 5 minutes")-- def _setup_initial_env_with_venv(self):- r"""Set up initial environment using standard venv."""- if self.initial_env_path is None:- raise Exception("Initial environment path not set")-- try:- # Create virtual environment with system Python- # On macOS, use symlinks=False to avoid dyld library loading issues- venv.create(- self.initial_env_path,- with_pip=True,- system_site_packages=False,- symlinks=False,- )-- # Get pip path- if self.os_type == 'Windows':- pip_path = os.path.join(- self.initial_env_path, "Scripts", "pip.exe"- )- else:- pip_path = os.path.join(self.initial_env_path, "bin", "pip")-- # Upgrade pip and install essential packages- essential_packages = [- "pip",- "setuptools",- "wheel",- "pyautogui",- "plotly",- "ffmpeg",- ]- subprocess.run(- [pip_path, "install", "--upgrade", *essential_packages],- check=True,- capture_output=True,- cwd=self.working_dir,- timeout=300,- )-- # Check if Node.js is available (but don't install it)- self._check_nodejs_availability()-- self._update_terminal_output(- "Initial environment created with system Python and "- "essential packages\n"- )-- except subprocess.CalledProcessError as e:- error_msg = e.stderr.decode() if e.stderr else str(e)- raise Exception(f"Venv setup failed: {error_msg}")- except subprocess.TimeoutExpired:- raise Exception("Venv setup timed out after 5 minutes")-- def _check_nodejs_availability(self):- r"""Check if Node.js is available without modifying the system."""- try:- # Check if Node.js is already available in the system- node_result = subprocess.run(- ["node", "--version"],- check=False,- capture_output=True,- timeout=10,- )-- npm_result = subprocess.run(- ["npm", "--version"],- check=False,- capture_output=True,- timeout=10,- )-- if node_result.returncode == 0 and npm_result.returncode == 0:- node_version = node_result.stdout.decode().strip()- npm_version = npm_result.stdout.decode().strip()- self._update_terminal_output(- f"Node.js {node_version} and npm {npm_version} "- "are available\n"- )- else:- self._update_terminal_output(- "Note: Node.js not found. If needed, please install it "- "manually.\n"- )-- except Exception as e:- self._update_terminal_output(- f"Note: Could not check Node.js availability - {e}.\n"- )- logger.warning(f"Failed to check Node.js: {e}")-- def _create_terminal(self):- r"""Create a terminal GUI. If GUI creation fails, fallback- to file output."""-- try:- import tkinter as tk- from tkinter import scrolledtext-- def update_terminal():- try:- while True:- output = self.output_queue.get_nowait()- if isinstance(output, bytes):- output = output.decode('utf-8', errors='replace')- self.terminal.insert(tk.END, output)- self.terminal.see(tk.END)- except queue.Empty:- if hasattr(self, 'root') and self.root:- self.root.after(100, update_terminal)-- self.root = tk.Tk()- self.root.title(f"{self.os_type} Terminal")-- self.root.geometry("800x600")- self.root.minsize(400, 300)-- self.terminal = scrolledtext.ScrolledText(- self.root,- wrap=tk.WORD,- bg='black',- fg='white',- font=('Consolas', 10),- insertbackground='white', # Cursor color- )- self.terminal.pack(fill=tk.BOTH, expand=True)-- # Set the handling for closing the window- def on_closing():- self.root.quit()- self.root.destroy()- self.root = None-- self.root.protocol("WM_DELETE_WINDOW", on_closing)-- # Start updating- update_terminal()-- # Mark the terminal as ready- self.terminal_ready.set()-- # Start the main loop- self.root.mainloop()-- except Exception as e:- logger.warning(- f"Failed to create GUI terminal: {e}, "- f"falling back to file output mode"- )- # Fallback to file output mode when GUI creation fails- self._setup_file_output()- self.terminal_ready.set()-- def _update_terminal_output(self, output: str):- r"""Update terminal output and send to agent.-- Args:- output (str): The output to be sent to the agent- """- try:- # If it is macOS or if we have a log_file (fallback mode),- # write to file- if self.is_macos or hasattr(self, 'log_file'):- if hasattr(self, 'log_file'):- with open(self.log_file, "a") as f:- f.write(output)- # Ensure the agent also receives the output- self.agent_queue.put(output)- return-- # For other cases, try to update the GUI (if it exists)- if hasattr(self, 'root') and self.root:- self.output_queue.put(output)-- # Always send to agent queue- self.agent_queue.put(output)-- except Exception as e:- logger.error(f"Failed to update terminal output: {e}")-- def _is_path_within_working_dir(self, path: str) -> bool:- r"""Check if the path is within the working directory.-- Args:- path (str): The path to check-- Returns:- bool: Returns True if the path is within the working directory,- otherwise returns False- """- abs_path = os.path.abspath(path)- return abs_path.startswith(self.working_dir)-- def _enforce_working_dir_for_execution(self, path: str) -> Optional[str]:- r"""Enforce working directory restrictions, return error message- if execution path is not within the working directory.-- Args:- path (str): The path to be used for executing operations-- Returns:- Optional[str]: Returns error message if the path is not within- the working directory, otherwise returns None- """- if not self._is_path_within_working_dir(path):- return (- f"Operation restriction: Execution path {path} must "- f"be within working directory {self.working_dir}"- )- return None-- def _copy_external_file_to_workdir(- self, external_file: str- ) -> Optional[str]:- r"""Copy external file to working directory.-- Args:- external_file (str): The path of the external file-- Returns:- Optional[str]: New path after copying to the working directory,- returns None on failure- """- try:- import shutil-- filename = os.path.basename(external_file)- new_path = os.path.join(self.working_dir, filename)- shutil.copy2(external_file, new_path)- return new_path- except Exception as e:- logger.error(f"Failed to copy file: {e}")- return None-- def _sanitize_command(self, command: str, exec_dir: str) -> Tuple:- r"""Check and modify command to ensure safety.-- Args:- command (str): The command to check- exec_dir (str): The directory to execute the command in-- Returns:- Tuple: (is safe, modified command or error message)- """- if not self.safe_mode:- return True, command-- if not command or command.strip() == "":- return False, "Empty command"-- # Use shlex for safer command parsing- import shlex-- try:- parts = shlex.split(command)- except ValueError as e:- # Handle malformed commands (e.g., unbalanced quotes)- return False, f"Invalid command format: {e}"-- if not parts:- return False, "Empty command"-- # Get base command- base_cmd = parts[0].lower()-- # Handle special commands- if base_cmd in ['cd', 'chdir']:- # Check if cd command attempts to leave the working directory- if len(parts) > 1:- target_dir = parts[1].strip('"\'')- if (- target_dir.startswith('/')- or target_dir.startswith('\\')- or ':' in target_dir- ):- # Absolute path- abs_path = os.path.abspath(target_dir)- else:- # Relative path- abs_path = os.path.abspath(- os.path.join(exec_dir, target_dir)- )-- if not self._is_path_within_working_dir(abs_path):- return False, (- f"Safety restriction: Cannot change to directory "- f"outside of working directory {self.working_dir}"- )-- # Check file operation commands- elif base_cmd in [- 'rm',- 'del',- 'rmdir',- 'rd',- 'deltree',- 'erase',- 'unlink',- 'shred',- 'srm',- 'wipe',- 'remove',- ]:- # Check targets of delete commands- for _, part in enumerate(parts[1:], 1):- if part.startswith('-') or part.startswith(- '/'- ): # Skip options- continue-- target = part.strip('"\'')- if (- target.startswith('/')- or target.startswith('\\')- or ':' in target- ):- # Absolute path- abs_path = os.path.abspath(target)- else:- # Relative path- abs_path = os.path.abspath(os.path.join(exec_dir, target))-- if not self._is_path_within_working_dir(abs_path):- return False, (- f"Safety restriction: Cannot delete files outside "- f"of working directory {self.working_dir}"- )-- # Check write/modify commands- elif base_cmd in [- 'touch',- 'mkdir',- 'md',- 'echo',- 'cat',- 'cp',- 'copy',- 'mv',- 'move',- 'rename',- 'ren',- 'write',- 'output',- ]:- # Check for redirection symbols- full_cmd = command.lower()- if '>' in full_cmd:- # Find the file path after redirection- redirect_parts = command.split('>')- if len(redirect_parts) > 1:- output_file = (- redirect_parts[1].strip().split()[0].strip('"\'')- )- if (- output_file.startswith('/')- or output_file.startswith('\\')- or ':' in output_file- ):- # Absolute path- abs_path = os.path.abspath(output_file)- else:- # Relative path- abs_path = os.path.abspath(- os.path.join(exec_dir, output_file)- )-- if not self._is_path_within_working_dir(abs_path):- return False, (- f"Safety restriction: Cannot write to file "- f"outside of working directory {self.working_dir}"- )-- # For cp/mv commands, check target paths- if base_cmd in ['cp', 'copy', 'mv', 'move']:- # Simple handling, assuming the last parameter is the target- if len(parts) > 2:- target = parts[-1].strip('"\'')- if (- target.startswith('/')- or target.startswith('\\')- or ':' in target- ):- # Absolute path- abs_path = os.path.abspath(target)- else:- # Relative path- abs_path = os.path.abspath(- os.path.join(exec_dir, target)- )-- if not self._is_path_within_working_dir(abs_path):- return False, (- f"Safety restriction: Cannot write to file "- f"outside of working directory {self.working_dir}"- )-- # Check dangerous commands- elif base_cmd in [- 'sudo',- 'su',- 'chmod',- 'chown',- 'chgrp',- 'passwd',- 'mkfs',- 'fdisk',- 'dd',- 'shutdown',- 'reboot',- 'halt',- 'poweroff',- 'init',- ]:- return False, (- f"Safety restriction: Command '{base_cmd}' may affect system "- f"security and is prohibited"- )-- # Check network commands- elif base_cmd in ['ssh', 'telnet', 'ftp', 'sftp', 'nc', 'netcat']:- return False, (- f"Safety restriction: Network command '{base_cmd}' "- f"is prohibited"- )-- # Add copy functionality - copy from external to working directory- elif base_cmd == 'safecopy':- # Custom command: safecopy <source file> <target file>- if len(parts) != 3:- return False, "Usage: safecopy <source file> <target file>"-- source = parts[1].strip('\'"')- target = parts[2].strip('\'"')-- # Check if source file exists- if not os.path.exists(source):- return False, f"Source file does not exist: {source}"-- # Ensure target is within working directory- if (- target.startswith('/')- or target.startswith('\\')- or ':' in target- ):- # Absolute path- abs_target = os.path.abspath(target)- else:- # Relative path- abs_target = os.path.abspath(os.path.join(exec_dir, target))-- if not self._is_path_within_working_dir(abs_target):- return False, (- f"Safety restriction: Target file must be within "- f"working directory {self.working_dir}"- )-- # Replace with safe copy command- if self.os_type == 'Windows':- return True, f"copy \"{source}\" \"{abs_target}\""- else:- return True, f"cp \"{source}\" \"{abs_target}\""-- return True, command-- def shell_exec(self, id: str, command: str) -> str:- r"""Executes a shell command in a specified session.-- This function creates and manages shell sessions to execute commands,- simulating a real terminal. The behavior depends on the toolkit's- interactive mode setting. Each session is identified by a unique ID.- If a session with the given ID does not exist, it will be created.-- Args:- id (str): A unique identifier for the shell session. This is used- to manage multiple concurrent shell processes.- command (str): The shell command to be executed.-- Returns:- str: The standard output and standard error from the command. If an- error occurs during execution, a descriptive error message is- returned.-- Note:- When the toolkit is initialized with interactive mode, commands may- block if they require input. In safe mode, some commands that are- considered dangerous are restricted.- """- error_msg = self._enforce_working_dir_for_execution(self.working_dir)- if error_msg:- return error_msg-- if self.safe_mode:- is_safe, sanitized_command = self._sanitize_command(- command, self.working_dir- )- if not is_safe:- return f"Command rejected: {sanitized_command}"- command = sanitized_command-- if id not in self.shell_sessions:- self.shell_sessions[id] = {- "process": None,- "output": "",- "running": False,- }-- try:- self._update_terminal_output(f"\n$ {command}\n")-- if command.startswith('python') or command.startswith('pip'):- python_path = None- pip_path = None-- # Try cloned environment first- if self.cloned_env_path and os.path.exists(- self.cloned_env_path- ):- if self.os_type == 'Windows':- base_path = os.path.join(- self.cloned_env_path, "Scripts"- )- python_candidate = os.path.join(- base_path, "python.exe"- )- pip_candidate = os.path.join(base_path, "pip.exe")- else:- base_path = os.path.join(self.cloned_env_path, "bin")- python_candidate = os.path.join(base_path, "python")- pip_candidate = os.path.join(base_path, "pip")-- # Verify the executables exist- if os.path.exists(python_candidate):- python_path = python_candidate- # For pip, use python -m pip if pip executable doesn't- # exist- if os.path.exists(pip_candidate):- pip_path = pip_candidate- else:- pip_path = f'"{python_path}" -m pip'-- # Try initial environment if cloned environment failed- if (- python_path is None- and self.initial_env_prepared- and self.initial_env_path- and os.path.exists(self.initial_env_path)- ):- if self.os_type == 'Windows':- base_path = os.path.join(- self.initial_env_path, "Scripts"- )- python_candidate = os.path.join(- base_path, "python.exe"- )- pip_candidate = os.path.join(base_path, "pip.exe")- else:- base_path = os.path.join(self.initial_env_path, "bin")- python_candidate = os.path.join(base_path, "python")- pip_candidate = os.path.join(base_path, "pip")-- # Verify the executables exist- if os.path.exists(python_candidate):- python_path = python_candidate- # For pip, use python -m pip if pip executable doesn't- # exist- if os.path.exists(pip_candidate):- pip_path = pip_candidate- else:- pip_path = f'"{python_path}" -m pip'-- # Fall back to system Python- if python_path is None:- python_path = self.python_executable- pip_path = f'"{python_path}" -m pip'-- # Ensure we have valid paths before replacement- if python_path and command.startswith('python'):- command = command.replace('python', f'"{python_path}"', 1)- elif pip_path and command.startswith('pip'):- command = command.replace('pip', pip_path, 1)-- if not self.interactive:- # Use preexec_fn to create a new process group on Unix systems- preexec_fn = None- if self.os_type in ['Darwin', 'Linux']:- preexec_fn = os.setsid-- proc = subprocess.Popen(- command,- shell=True,- cwd=self.working_dir,- stdout=subprocess.PIPE,- stderr=subprocess.PIPE,- stdin=subprocess.PIPE,- text=True,- bufsize=1,- universal_newlines=True,- env=os.environ.copy(),- preexec_fn=preexec_fn,- errors='replace', # Handle non-UTF-8 characters- )-- self.shell_sessions[id]["process"] = proc- self.shell_sessions[id]["running"] = True- try:- # Use the instance timeout if available- stdout, stderr = proc.communicate(timeout=self.timeout)- output = stdout or ""- if stderr:- output += f"\nStderr Output:\n{stderr}"- self.shell_sessions[id]["output"] = output- self.shell_sessions[id]["running"] = False- self._update_terminal_output(output + "\n")- return output- except subprocess.TimeoutExpired:- # Kill the entire process group on Unix systems- if self.os_type in ['Darwin', 'Linux']:- try:- os.killpg(os.getpgid(proc.pid), signal.SIGTERM)- # Give it a short time to terminate- stdout, stderr = proc.communicate(timeout=1)- except subprocess.TimeoutExpired:- # Force kill the process group- os.killpg(os.getpgid(proc.pid), signal.SIGKILL)- stdout, stderr = proc.communicate()- except ProcessLookupError:- # Process already dead- stdout, stderr = proc.communicate()- else:- # Windows fallback- proc.terminate()- try:- stdout, stderr = proc.communicate(timeout=1)- except subprocess.TimeoutExpired:- proc.kill()- stdout, stderr = proc.communicate()-- output = stdout or ""- if stderr:- output += f"\nStderr Output:\n{stderr}"- error_msg = (- f"\nCommand timed out after {self.timeout} seconds"- )- output += error_msg- self.shell_sessions[id]["output"] = output- self.shell_sessions[id]["running"] = False- self._update_terminal_output(output + "\n")- return output-- # Interactive mode with real-time streaming via PTY- if self.os_type not in ['Darwin', 'Linux']:- return (- "Interactive mode is not supported on "- f"{self.os_type} due to PTY limitations."- )-- import pty- import select- import sys- import termios- import tty-- # Fork a new process with a PTY- pid, master_fd = pty.fork()-- if pid == 0: # Child process- # Execute the command in the child process- try:- import shlex-- parts = shlex.split(command)- if not parts:- logger.error("Error: Empty command")- os._exit(1)-- os.chdir(self.working_dir)- os.execvp(parts[0], parts)- except (ValueError, IndexError, OSError) as e:- logger.error(f"Command execution error: {e}")- os._exit(127)- except Exception as e:- logger.error(f"Unexpected error: {e}")- os._exit(1)-- # Parent process- self.shell_sessions[id]["process_id"] = pid- self.shell_sessions[id]["running"] = True- output_lines: List[str] = []- original_settings = termios.tcgetattr(sys.stdin)-- try:- tty.setraw(sys.stdin.fileno())-- while True:- # Check if the child process has exited- try:- wait_pid, status = os.waitpid(pid, os.WNOHANG)- if wait_pid == pid:- self.shell_sessions[id]["running"] = False- break- except OSError:- # Process already reaped- self.shell_sessions[id]["running"] = False- break-- # Use select to wait for I/O on stdin or master PTY- r, _, _ = select.select(- [sys.stdin, master_fd], [], [], 0.1- )-- if master_fd in r:- try:- data = os.read(master_fd, 1024)- if not data:- break- decoded_data = data.decode(- 'utf-8', errors='replace'- )- # Echo to user's terminal and log- self._update_terminal_output(decoded_data)- output_lines.append(decoded_data)- except OSError:- break # PTY has been closed-- if sys.stdin in r:- try:- user_input = os.read(sys.stdin.fileno(), 1024)- if not user_input:- break- os.write(master_fd, user_input)- except OSError:- break-- finally:- if original_settings is not None:- termios.tcsetattr(- sys.stdin, termios.TCSADRAIN, original_settings- )- if master_fd:- os.close(master_fd)-- final_output = "".join(output_lines)- self.shell_sessions[id]["output"] = final_output- return final_output-- except Exception as e:- error_msg = f"Command execution error: {e!s}"- logger.error(error_msg)- self._update_terminal_output(f"\nError: {error_msg}\n")- import traceback-- detailed_error = traceback.format_exc()- return (- f"Error: {error_msg}\n\n"- f"Detailed information: {detailed_error}"- )-- # Mark shell_exec to skip automatic timeout wrapping- shell_exec._manual_timeout = True # type: ignore[attr-defined]-- def shell_view(self, id: str) -> str:- r"""View the full output history of a specified shell session.-- Retrieves the accumulated output (both stdout and stderr) generated by- commands in the specified session since its creation. This is useful- for checking the complete history of a session, especially after a- command has finished execution.-- Args:- id (str): The unique identifier of the shell session to view.-- Returns:- str: The complete output history of the shell session. Returns an- error message if the session is not found.- """- if id not in self.shell_sessions:- return f"Shell session not found: {id}"-- session = self.shell_sessions[id]-- try:- # Check process status- if session["process"].poll() is not None:- session["running"] = False-- # Collect all new output from agent queue- new_output = ""- try:- while True:- output = self.agent_queue.get_nowait()- new_output += output- session["output"] += output- except queue.Empty:- pass-- return new_output or session["output"]-- except Exception as e:- error_msg = f"Error reading terminal output: {e}"- self._update_terminal_output(f"\nError: {error_msg}\n")- logger.error(error_msg)- return f"Error: {e!s}"-- def shell_wait(self, id: str, seconds: Optional[int] = None) -> str:- r"""Wait for a command to finish in a specified shell session.-- Blocks execution and waits for the running process in a shell session- to complete. This is useful for ensuring a long-running command has- finished before proceeding.-- Args:- id (str): The unique identifier of the target shell session.- seconds (Optional[int], optional): The maximum time to wait, in- seconds. If `None`, it waits indefinitely.- (default: :obj:`None`)-- Returns:- str: A message indicating that the process has completed, including- the final output. If the process times out, it returns a- timeout message.- """- if id not in self.shell_sessions:- return f"Shell session not found: {id}"-- session = self.shell_sessions[id]- process = session.get("process")-- if process is None:- return f"No active process in session '{id}'"-- if not session["running"] or process.poll() is not None:- return f"Process in session '{id}' is not running"-- try:- if hasattr(process, 'communicate'):- # Use communicate with timeout- stdout, stderr = process.communicate(timeout=seconds)-- if stdout:- stdout_str = (- stdout.decode('utf-8')- if isinstance(stdout, bytes)- else stdout- )- session["output"] += stdout_str- if stderr:- stderr_str = (- stderr.decode('utf-8')- if isinstance(stderr, bytes)- else stderr- )- if stderr_str:- session["output"] += f"\nStderr Output:\n{stderr_str}"-- session["running"] = False- return (- f"Process completed in session '{id}'. "- f"Output: {session['output']}"- )- else:- return (- f"Process already completed in session '{id}'. "- f"Output: {session['output']}"- )-- except subprocess.TimeoutExpired:- return (- f"Process in session '{id}' is still running "- f"after {seconds} seconds"- )- except Exception as e:- logger.error(f"Error waiting for process: {e}")- return f"Error waiting for process: {e!s}"-- def shell_write_to_process(- self, id: str, input: str, press_enter: bool- ) -> str:- r"""Write input to a running process in a specified shell session.-- Sends a string of text to the standard input of a running process.- This is useful for interacting with commands that require input. This- function cannot be used with a command that was started in- interactive mode.-- Args:- id (str): The unique identifier of the target shell session.- input (str): The text to write to the process's stdin.- press_enter (bool): If `True`, a newline character (`\n`) is- appended to the input, simulating pressing the Enter key.-- Returns:- str: A status message indicating whether the input was sent, or an- error message if the operation fails.- """- if id not in self.shell_sessions:- return f"Shell session not found: {id}"-- session = self.shell_sessions[id]- process = session.get("process")-- if process is None:- return f"No active process in session '{id}'"-- if not session["running"] or process.poll() is not None:- return f"Process in session '{id}' is not running"-- try:- if not process.stdin or process.stdin.closed:- return (- f"Cannot write to process in session '{id}': "- f"stdin is closed"- )-- if press_enter:- input = input + "\n"-- # Write to stdin - handle encoding- if hasattr(process.stdin, 'write'):- if isinstance(input, str):- process.stdin.write(input)- else:- process.stdin.write(- input.decode('utf-8', errors='replace')- )- else:- # Fallback for byte mode- process.stdin.write(input.encode('utf-8', errors='replace'))- process.stdin.flush()-- return f"Input sent to process in session '{id}'"- except Exception as e:- logger.error(f"Error writing to process: {e}")- return f"Error writing to process: {e!s}"-- def shell_kill_process(self, id: str) -> str:- r"""Terminate a running process in a specified shell session.-- Forcibly stops a command that is currently running in a shell session.- This is useful for ending processes that are stuck, running too long,- or need to be cancelled.-- Args:- id (str): The unique identifier of the shell session containing the- process to be terminated.-- Returns:- str: A status message indicating that the process has been- terminated, or an error message if the operation fails.- """- if id not in self.shell_sessions:- return f"Shell session not found: {id}"-- session = self.shell_sessions[id]- process = session.get("process")-- if process is None:- return f"No active process in session '{id}'"-- if not session["running"] or process.poll() is not None:- return f"Process in session '{id}' is not running"-- try:- # Clean up process resources before termination- if process.stdin and not process.stdin.closed:- process.stdin.close()-- process.terminate()- try:- process.wait(timeout=5)- except subprocess.TimeoutExpired:- logger.warning(- f"Process in session '{id}' did not terminate gracefully"- f", forcing kill"- )- process.kill()-- session["running"] = False- return f"Process in session '{id}' has been terminated"- except Exception as e:- logger.error(f"Error killing process: {e}")- return f"Error killing process: {e!s}"-- def ask_user_for_help(self, id: str) -> str:- r"""Pause the agent and ask a human for help with a command.-- This function should be used when the agent is stuck and requires- manual intervention, such as solving a CAPTCHA or debugging a complex- issue. It pauses the agent's execution and allows a human to take- control of a specified shell session. The human can execute one- command to resolve the issue, and then control is returned to the- agent.-- Args:- id (str): The identifier of the shell session for the human to- interact with. If the session does not exist, it will be- created.-- Returns:- str: A status message indicating that the human has finished,- including the number of commands executed. If the takeover- times out or fails, an error message is returned.- """- # Input validation- if not id or not isinstance(id, str):- return "Error: Invalid session ID provided"-- # Prevent concurrent human takeovers- if (- hasattr(self, '_human_takeover_active')- and self._human_takeover_active- ):- return "Error: Human takeover already in progress"-- try:- self._human_takeover_active = True-- # Ensure the session exists so that the human can reuse it- if id not in self.shell_sessions:- self.shell_sessions[id] = {- "process": None,- "output": "",- "running": False,- }-- command_count = 0- error_occurred = False-- # Create clear banner message for user- takeover_banner = (- f"\n{'='*60}\n"- f"🤖 CAMEL Agent needs human help! Session: {id}\n"- f"📂 Working directory: {self.working_dir}\n"- f"{'='*60}\n"- f"💡 Type commands or '/exit' to return control to agent.\n"- f"{'='*60}\n"- )-- # Print once to console for immediate visibility- print(takeover_banner, flush=True)- # Log for terminal output tracking- self._update_terminal_output(takeover_banner)-- # Helper flag + event for coordination- done_event = threading.Event()-- def _human_loop() -> None:- r"""Blocking loop that forwards human input to shell_exec."""- nonlocal command_count, error_occurred- try:- while True:- try:- # Clear, descriptive prompt for user input- user_cmd = input(f"🧑💻 [{id}]> ")- if (- user_cmd.strip()- ): # Only count non-empty commands- command_count += 1- except EOFError:- # e.g. Ctrl_D / stdin closed, treat as exit.- break- except (KeyboardInterrupt, Exception) as e:- logger.warning(- f"Input error during human takeover: {e}"- )- error_occurred = True- break-- if user_cmd.strip() in {"/exit", "exit", "quit"}:- break-- try:- exec_result = self.shell_exec(id, user_cmd)- # Show the result immediately to the user- if exec_result.strip():- print(exec_result)- logger.info(- f"Human command executed: {user_cmd[:50]}..."- )- # Auto-exit after successful command- break- except Exception as e:- error_msg = f"Error executing command: {e}"- logger.error(f"Error executing human command: {e}")- print(error_msg) # Show error to user immediately- self._update_terminal_output(f"{error_msg}\n")- error_occurred = True-- except Exception as e:- logger.error(f"Unexpected error in human loop: {e}")- error_occurred = True- finally:- # Notify completion clearly- finish_msg = (- f"\n{'='*60}\n"- f"✅ Human assistance completed! "- f"Commands: {command_count}\n"- f"🤖 Returning control to CAMEL agent...\n"- f"{'='*60}\n"- )- print(finish_msg, flush=True)- self._update_terminal_output(finish_msg)- done_event.set()-- # Start interactive thread (non-daemon for proper cleanup)- thread = threading.Thread(target=_human_loop, daemon=False)- thread.start()-- # Block until human signals completion with timeout- if done_event.wait(timeout=600): # 10 minutes timeout- thread.join(timeout=10) # Give thread time to cleanup-- # Generate detailed status message- status = "completed successfully"- if error_occurred:- status = "completed with some errors"-- result_msg = (- f"Human assistance {status} for session '{id}'. "- f"Total commands executed: {command_count}. "- f"Working directory: {self.working_dir}"- )- logger.info(result_msg)- return result_msg- else:- timeout_msg = (- f"Human takeover for session '{id}' timed out after 10 "- "minutes"- )- logger.warning(timeout_msg)- return timeout_msg-- except Exception as e:- error_msg = f"Error during human takeover for session '{id}': {e}"- logger.error(error_msg)- # Notify user of the error clearly- error_banner = (- f"\n{'='*60}\n"- f"❌ Error in human takeover! Session: {id}\n"- f"❗ {e}\n"- f"{'='*60}\n"- )- print(error_banner, flush=True)- return error_msg- finally:- # Always reset the flag- self._human_takeover_active = False-- def __del__(self):- r"""Clean up resources when the object is being destroyed.- Terminates all running processes and closes any open file handles.- """- # Log that cleanup is starting- logger.info("TerminalToolkit cleanup initiated")-- # Clean up all processes in shell sessions- if hasattr(self, 'shell_sessions'):- for session_id, session in self.shell_sessions.items():- process = session.get("process")- if process is not None and session.get("running", False):- try:- logger.info(- f"Terminating process in session '{session_id}'"- )-- # Close process input/output streams if open- if (- hasattr(process, 'stdin')- and process.stdin- and not process.stdin.closed- ):- process.stdin.close()-- # Terminate the process- process.terminate()- try:- # Give the process a short time to terminate- # gracefully- process.wait(timeout=3)- except subprocess.TimeoutExpired:- # Force kill if the process doesn't terminate- # gracefully- logger.warning(- f"Process in session '{session_id}' did not "- f"terminate gracefully, forcing kill"- )- process.kill()-- # Mark the session as not running- session["running"] = False-- except Exception as e:- logger.error(- f"Error cleaning up process in session "- f"'{session_id}': {e}"- )-- # Clean up file output if it exists- if hasattr(self, 'log_file') and self.is_macos:- try:- logger.info(f"Final terminal log saved to: {self.log_file}")- except Exception as e:- logger.error(f"Error logging file information: {e}")-- # Clean up initial environment if it exists- if hasattr(self, 'initial_env_path') and self.initial_env_path:- try:- if os.path.exists(self.initial_env_path):- shutil.rmtree(self.initial_env_path)- logger.info(- f"Cleaned up initial environment: "- f"{self.initial_env_path}"- )- except Exception as e:- logger.error(f"Error cleaning up initial environment: {e}")-- # Clean up GUI resources if they exist- if hasattr(self, 'root') and self.root:- try:- logger.info("Closing terminal GUI")- self.root.quit()- self.root.destroy()- except Exception as e:- logger.error(f"Error closing terminal GUI: {e}")-- logger.info("TerminalToolkit cleanup completed")-- def get_tools(self) -> List[FunctionTool]:- r"""Returns a list of FunctionTool objects representing the functions- in the toolkit.-- Returns:- List[FunctionTool]: A list of FunctionTool objects representing the- functions in the toolkit.- """- return [- FunctionTool(self.shell_exec),- FunctionTool(self.shell_view),- FunctionTool(self.shell_wait),- FunctionTool(self.shell_write_to_process),- FunctionTool(self.shell_kill_process),- FunctionTool(self.ask_user_for_help),- ]diff --git a/camel/toolkits/terminal_toolkit/__init__.py b/camel/toolkits/terminal_toolkit/__init__.pynew file mode 100644index 000000000..da4467043--- /dev/null+++ b/camel/toolkits/terminal_toolkit/__init__.py@@ -0,0 +1,18 @@+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========+from .terminal_toolkit import TerminalToolkit++__all__ = [+ "TerminalToolkit",+]diff --git a/camel/toolkits/terminal_toolkit/terminal_toolkit.py b/camel/toolkits/terminal_toolkit/terminal_toolkit.pynew file mode 100644index 000000000..6839bc7f4--- /dev/null+++ b/camel/toolkits/terminal_toolkit/terminal_toolkit.py@@ -0,0 +1,874 @@+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========+import atexit+import os+import platform+import select+import subprocess+import sys+import threading+import time+from queue import Empty, Queue+from typing import Any, Dict, List, Optional++from camel.logger import get_logger+from camel.toolkits.base import BaseToolkit+from camel.toolkits.function_tool import FunctionTool+from camel.toolkits.terminal_toolkit.utils import (+ check_nodejs_availability,+ clone_current_environment,+ ensure_uv_available,+ sanitize_command,+ setup_initial_env_with_uv,+ setup_initial_env_with_venv,+)+from camel.utils import MCPServer++logger = get_logger(__name__)++# Try to import docker, but don't make it a hard requirement+try:+ import docker+ from docker.errors import APIError, NotFound+ from docker.models.containers import Container+except ImportError:+ docker = None+ NotFound = None+ APIError = None+ Container = None+++def _to_plain(text: str) -> str:+ r"""Convert ANSI text to plain text using rich if available."""+ try:+ from rich.text import Text as _RichText++ return _RichText.from_ansi(text).plain+ except Exception:+ return text+++@MCPServer()+class TerminalToolkit(BaseToolkit):+ r"""A toolkit for LLM agents to execute and interact with terminal commands+ in either a local or a sandboxed Docker environment.++ Args:+ use_docker_backend (bool): If True, all commands are executed in a+ Docker container. Defaults to False.+ docker_container_name (Optional[str]): The name of the Docker+ container to use. Required if use_docker_backend is True.+ working_dir (str): The base directory for all operations.+ For the local backend, this acts as a security sandbox.+ session_logs_dir (Optional[str]): The directory to store session+ logs. Defaults to a 'terminal_logs' subfolder in the+ working_dir.+ timeout (int): The default timeout in seconds for blocking+ commands. Defaults to 60.+ """++ def __init__(+ self,+ timeout: Optional[float] = 20.0,+ working_directory: Optional[str] = None,+ use_docker_backend: bool = False,+ docker_container_name: Optional[str] = None,+ session_logs_dir: Optional[str] = None,+ safe_mode: bool = True,+ allowed_commands: Optional[List[str]] = None,+ clone_current_env: bool = False,+ ):+ self.use_docker_backend = use_docker_backend+ self.timeout = timeout+ self.shell_sessions: Dict[str, Dict[str, Any]] = {}+ # Thread-safe guard for concurrent access to+ # shell_sessions and session state+ self._session_lock = threading.RLock()+ if working_directory:+ self.working_dir = os.path.abspath(working_directory)+ else:+ camel_workdir = os.environ.get("CAMEL_WORKDIR")+ if camel_workdir:+ self.working_dir = os.path.abspath(camel_workdir)+ else:+ self.working_dir = os.path.abspath("./workspace")++ if not os.path.exists(self.working_dir):+ os.makedirs(self.working_dir, exist_ok=True)+ self.safe_mode = safe_mode++ # Initialize whitelist of allowed commands if provided+ self.allowed_commands = (+ set(allowed_commands) if allowed_commands else None+ )++ # Environment management attributes+ self.clone_current_env = clone_current_env+ self.cloned_env_path: Optional[str] = None+ self.initial_env_path: Optional[str] = None+ self.python_executable = sys.executable++ atexit.register(self.__del__)++ self.log_dir = os.path.abspath(+ session_logs_dir or os.path.join(self.working_dir, "terminal_logs")+ )+ self.blocking_log_file = os.path.join(+ self.log_dir, "blocking_commands.log"+ )+ self.os_type = platform.system()++ os.makedirs(self.log_dir, exist_ok=True)++ # Clean the file in terminal_logs folder+ for file in os.listdir(self.log_dir):+ if file.endswith(".log"):+ os.remove(os.path.join(self.log_dir, file))++ if self.use_docker_backend:+ if docker is None:+ raise ImportError(+ "The 'docker' library is required to use the "+ "Docker backend. Please install it with "+ "'pip install docker'."+ )+ if not docker_container_name:+ raise ValueError(+ "docker_container_name must be "+ "provided when using Docker backend."+ )+ try:+ # APIClient is used for operations that need a timeout,+ # like exec_start+ self.docker_api_client = docker.APIClient(+ base_url='unix://var/run/docker.sock', timeout=self.timeout+ )+ self.docker_client = docker.from_env()+ self.container = self.docker_client.containers.get(+ docker_container_name+ )+ logger.info(+ f"Successfully attached to Docker container "+ f"'{docker_container_name}'."+ )+ except NotFound:+ raise RuntimeError(+ f"Docker container '{docker_container_name}' not found."+ )+ except APIError as e:+ raise RuntimeError(f"Failed to connect to Docker daemon: {e}")++ # Set up environments (only for local backend)+ if not self.use_docker_backend:+ if self.clone_current_env:+ self._setup_cloned_environment()+ else:+ # Default: set up initial environment with Python 3.10+ self._setup_initial_environment()+ elif self.clone_current_env:+ logger.info(+ "[ENV CLONE] Skipping environment setup for Docker backend "+ "- container is already isolated"+ )++ def _setup_cloned_environment(self):+ r"""Set up a cloned Python environment."""+ self.cloned_env_path = os.path.join(self.working_dir, ".venv")++ def update_callback(msg: str):+ logger.info(f"[ENV CLONE] {msg.strip()}")++ success = clone_current_environment(+ self.cloned_env_path, self.working_dir, update_callback+ )++ if success:+ # Update python executable to use the cloned environment+ if self.os_type == 'Windows':+ self.python_executable = os.path.join(+ self.cloned_env_path, "Scripts", "python.exe"+ )+ else:+ self.python_executable = os.path.join(+ self.cloned_env_path, "bin", "python"+ )+ else:+ logger.info(+ "[ENV CLONE] Failed to create cloned environment, "+ "using system Python"+ )++ def _setup_initial_environment(self):+ r"""Set up an initial environment with Python 3.10."""+ self.initial_env_path = os.path.join(self.working_dir, ".initial_env")++ def update_callback(msg: str):+ logger.info(f"[ENV INIT] {msg.strip()}")++ # Try to ensure uv is available first+ success, uv_path = ensure_uv_available(update_callback)++ if success and uv_path:+ success = setup_initial_env_with_uv(+ self.initial_env_path,+ uv_path,+ self.working_dir,+ update_callback,+ )+ else:+ update_callback(+ "Falling back to standard venv for environment setup\n"+ )+ success = setup_initial_env_with_venv(+ self.initial_env_path, self.working_dir, update_callback+ )++ if success:+ # Update python executable to use the initial environment+ if self.os_type == 'Windows':+ self.python_executable = os.path.join(+ self.initial_env_path, "Scripts", "python.exe"+ )+ else:+ self.python_executable = os.path.join(+ self.initial_env_path, "bin", "python"+ )++ # Check Node.js availability+ check_nodejs_availability(update_callback)+ else:+ logger.info(+ "[ENV INIT] Failed to create initial environment, "+ "using system Python"+ )++ def _adapt_command_for_environment(self, command: str) -> str:+ r"""Adapt command to use virtual environment if available."""+ # Only adapt for local backend+ if self.use_docker_backend:+ return command++ # Check if we have any virtual environment (cloned or initial)+ env_path = None+ if self.cloned_env_path and os.path.exists(self.cloned_env_path):+ env_path = self.cloned_env_path+ elif self.initial_env_path and os.path.exists(self.initial_env_path):+ env_path = self.initial_env_path++ if not env_path:+ return command++ # Check if command starts with python or pip+ command_lower = command.strip().lower()+ if command_lower.startswith('python'):+ # Replace 'python' with the virtual environment python+ return command.replace('python', f'"{self.python_executable}"', 1)+ elif command_lower.startswith('pip'):+ # Replace 'pip' with python -m pip from virtual environment+ return command.replace(+ 'pip', f'"{self.python_executable}" -m pip', 1+ )++ return command++ def _write_to_log(self, log_file: str, content: str) -> None:+ r"""Write content to log file with optional ANSI stripping.++ Args:+ log_file (str): Path to the log file+ content (str): Content to write+ """+ # Convert ANSI escape sequences to plain text+ with open(log_file, "a", encoding="utf-8") as f:+ f.write(_to_plain(content) + "\n")++ def _sanitize_command(self, command: str) -> tuple[bool, str]:+ r"""A comprehensive command sanitizer for both local and+ Docker backends."""+ return sanitize_command(+ command=command,+ use_docker_backend=self.use_docker_backend,+ safe_mode=self.safe_mode,+ working_dir=self.working_dir,+ allowed_commands=self.allowed_commands,+ )++ def _start_output_reader_thread(self, session_id: str):+ r"""Starts a thread to read stdout from a non-blocking process."""+ with self._session_lock:+ session = self.shell_sessions[session_id]++ def reader():+ try:+ if session["backend"] == "local":+ # For local processes, read line by line from stdout+ try:+ for line in iter(+ session["process"].stdout.readline, ''+ ):+ session["output_stream"].put(line)+ self._write_to_log(session["log_file"], line)+ finally:+ session["process"].stdout.close()+ elif session["backend"] == "docker":+ # For Docker, read from the raw socket+ socket = session["process"]._sock+ while True:+ # Check if the socket is still open before reading+ if socket.fileno() == -1:+ break+ try:+ ready, _, _ = select.select([socket], [], [], 0.1)+ except (ValueError, OSError):+ # Socket may have been closed by another thread+ break+ if ready:+ data = socket.recv(4096)+ if not data:+ break+ decoded_data = data.decode(+ 'utf-8', errors='ignore'+ )+ session["output_stream"].put(decoded_data)+ self._write_to_log(+ session["log_file"], decoded_data+ )+ # Check if the process is still running+ if not self.docker_api_client.exec_inspect(+ session["exec_id"]+ )['Running']:+ break+ except Exception as e:+ # Log the exception for diagnosis and store it on the session+ logger.exception(f"[SESSION {session_id}] Reader thread error")+ try:+ with self._session_lock:+ if session_id in self.shell_sessions:+ self.shell_sessions[session_id]["error"] = str(e)+ except Exception:+ # Swallow any secondary errors during cleanup+ pass+ finally:+ try:+ with self._session_lock:+ if session_id in self.shell_sessions:+ self.shell_sessions[session_id]["running"] = False+ except Exception:+ pass++ thread = threading.Thread(target=reader, daemon=True)+ thread.start()++ def _collect_output_until_idle(+ self,+ id: str,+ idle_duration: float = 0.5,+ check_interval: float = 0.1,+ max_wait: float = 5.0,+ ) -> str:+ r"""Collects output from a session until it's idle or a max wait time+ is reached.++ Args:+ id (str): The session ID.+ idle_duration (float): How long the stream must be empty to be+ considered idle.(default: 0.5)+ check_interval (float): The time to sleep between checks.+ (default: 0.1)+ max_wait (float): The maximum total time to wait for the process+ to go idle. (default: 5.0)++ Returns:+ str: The collected output. If max_wait is reached while+ the process is still outputting, a warning is appended.+ """+ with self._session_lock:+ if id not in self.shell_sessions:+ return f"Error: No session found with ID '{id}'."++ output_parts = []+ idle_time = 0.0+ start_time = time.time()++ while time.time() - start_time < max_wait:+ new_output = self.shell_view(id)++ # Check for terminal state messages from shell_view+ if "--- SESSION TERMINATED ---" in new_output:+ # Append the final output before the termination message+ final_part = new_output.replace(+ "--- SESSION TERMINATED ---", ""+ ).strip()+ if final_part:+ output_parts.append(final_part)+ # Session is dead, return what we have plus the message+ return "".join(output_parts) + "\n--- SESSION TERMINATED ---"++ if new_output.startswith("Error: No session found"):+ return new_output++ if new_output:+ output_parts.append(new_output)+ idle_time = 0.0 # Reset idle timer+ else:+ idle_time += check_interval+ if idle_time >= idle_duration:+ # Process is idle, success+ return "".join(output_parts)+ time.sleep(check_interval)++ # If we exit the loop, it means max_wait was reached.+ # Check one last time for any final output.+ final_output = self.shell_view(id)+ if final_output:+ output_parts.append(final_output)++ warning_message = (+ "\n--- WARNING: Process is still actively outputting "+ "after max wait time. Consider using shell_wait() "+ "before sending the next command. ---"+ )+ return "".join(output_parts) + warning_message++ def shell_exec(self, id: str, command: str, block: bool = True) -> str:+ r"""This function executes a shell command. The command can run in+ blocking mode (waits for completion) or non-blocking mode+ (runs in the background). A unique session ID is created for+ each session.++ Args:+ command (str): The command to execute.+ block (bool): If True, the command runs synchronously,+ waiting for it to complete or time out, and returns+ its full output. If False, the command runs+ asynchronously in the background.+ id (Optional[str]): A specific ID for the session. If not provided,+ a unique ID is generated for non-blocking sessions.++ Returns:+ str: If block is True, returns the complete stdout and stderr.+ If block is False, returns a message containing the new+ session ID and the initial output from the command after+ it goes idle.+ """+ if self.safe_mode:+ is_safe, message = self._sanitize_command(command)+ if not is_safe:+ return f"Error: {message}"+ command = message+ else:+ command = command++ if self.use_docker_backend:+ # For Docker, we always run commands in a shell+ # to support complex commands+ command = f'bash -c "{command}"'+ else:+ # For local execution, check if we need to use cloned environment+ command = self._adapt_command_for_environment(command)++ session_id = id++ if block:+ # --- BLOCKING EXECUTION ---+ log_entry = (+ f"--- Executing blocking command at "+ f"{time.ctime()} ---\n> {command}\n"+ )+ output = ""+ try:+ if not self.use_docker_backend:+ # LOCAL BLOCKING+ result = subprocess.run(+ command,+ capture_output=True,+ text=True,+ shell=True,+ timeout=self.timeout,+ cwd=self.working_dir,+ encoding="utf-8",+ )+ stdout = result.stdout or ""+ stderr = result.stderr or ""+ output = stdout + (+ f"\nSTDERR:\n{stderr}" if stderr else ""+ )+ else:+ # DOCKER BLOCKING+ exec_instance = self.docker_api_client.exec_create(+ self.container.id, command, workdir="/workspace"+ )+ exec_output = self.docker_api_client.exec_start(+ exec_instance['Id']+ )+ output = exec_output.decode('utf-8', errors='ignore')++ log_entry += f"--- Output ---\n{output}\n"+ return _to_plain(output)+ except subprocess.TimeoutExpired:+ error_msg = (+ f"Error: Command timed out after {self.timeout} seconds."+ )+ log_entry += f"--- Error ---\n{error_msg}\n"+ return error_msg+ except Exception as e:+ if "Read timed out" in str(e):+ error_msg = (+ f"Error: Command timed out after "+ f"{self.timeout} seconds."+ )+ else:+ error_msg = f"Error executing command: {e}"+ log_entry += f"--- Error ---\n{error_msg}\n"+ return error_msg+ finally:+ self._write_to_log(self.blocking_log_file, log_entry + "\n")+ else:+ # --- NON-BLOCKING EXECUTION ---+ session_log_file = os.path.join(+ self.log_dir, f"session_{session_id}.log"+ )++ self._write_to_log(+ session_log_file,+ f"--- Starting non-blocking session at {time.ctime()} ---\n"+ f"> {command}\n",+ )++ with self._session_lock:+ self.shell_sessions[session_id] = {+ "id": session_id,+ "process": None,+ "output_stream": Queue(),+ "command_history": [command],+ "running": True,+ "log_file": session_log_file,+ "backend": "docker"+ if self.use_docker_backend+ else "local",+ }++ try:+ if not self.use_docker_backend:+ process = subprocess.Popen(+ command,+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ stderr=subprocess.STDOUT,+ shell=True,+ text=True,+ cwd=self.working_dir,+ encoding="utf-8",+ )+ with self._session_lock:+ self.shell_sessions[session_id]["process"] = process+ else:+ exec_instance = self.docker_api_client.exec_create(+ self.container.id,+ command,+ stdin=True,+ tty=True,+ workdir="/workspace",+ )+ exec_id = exec_instance['Id']+ exec_socket = self.docker_api_client.exec_start(+ exec_id, tty=True, stream=True, socket=True+ )+ with self._session_lock:+ self.shell_sessions[session_id]["process"] = (+ exec_socket+ )+ self.shell_sessions[session_id]["exec_id"] = exec_id++ self._start_output_reader_thread(session_id)++ # time.sleep(0.1)+ initial_output = self._collect_output_until_idle(session_id)++ return (+ f"Session started with ID: {session_id}\n\n"+ f"[Initial Output]:\n{initial_output}"+ )++ except Exception as e:+ with self._session_lock:+ if session_id in self.shell_sessions:+ self.shell_sessions[session_id]["running"] = False+ error_msg = f"Error starting non-blocking command: {e}"+ self._write_to_log(+ session_log_file, f"--- Error ---\n{error_msg}\n"+ )+ return error_msg++ def shell_write_to_process(self, id: str, command: str) -> str:+ r"""This function sends command to a running non-blocking+ process and returns the resulting output after the process+ becomes idle again. A newline \n is automatically appended+ to the input command.++ Args:+ id (str): The unique session ID of the non-blocking process.+ command (str): The text to write to the process's standard input.++ Returns:+ str: The output from the process after the command is sent.+ """+ with self._session_lock:+ if (+ id not in self.shell_sessions+ or not self.shell_sessions[id]["running"]+ ):+ return (+ f"Error: No active non-blocking "+ f"session found with ID '{id}'."+ )+ session = self.shell_sessions[id]++ # Flush any lingering output from previous commands.+ self._collect_output_until_idle(id, idle_duration=0.3, max_wait=2.0)++ with self._session_lock:+ session["command_history"].append(command)+ log_file = session["log_file"]+ backend = session["backend"]+ process = session["process"]++ # Log command to the raw log file+ self._write_to_log(log_file, f"> {command}\n")++ try:+ if backend == "local":+ process.stdin.write(command + '\n')+ process.stdin.flush()+ else: # docker+ socket = process._sock+ socket.sendall((command + '\n').encode('utf-8'))++ # Wait for and collect the new output+ output = self._collect_output_until_idle(id)++ return output++ except Exception as e:+ return f"Error writing to session '{id}': {e}"++ def shell_view(self, id: str) -> str:+ r"""This function retrieves any new output from a non-blocking session+ since the last time this function was called. If the process has+ terminated, it drains the output queue and appends a termination+ message. If the process is still running, it simply returns any+ new output.++ Args:+ id (str): The unique session ID of the non-blocking process.++ Returns:+ str: The new output from the process's stdout and stderr. Returns+ an empty string if there is no new output.+ """+ with self._session_lock:+ if id not in self.shell_sessions:+ return f"Error: No session found with ID '{id}'."+ session = self.shell_sessions[id]+ is_running = session["running"]++ # If session is terminated, drain the queue and return+ # with a status message.+ if not is_running:+ final_output = []+ try:+ while True:+ final_output.append(session["output_stream"].get_nowait())+ except Empty:+ pass+ return "".join(final_output) + "\n--- SESSION TERMINATED ---"++ # Otherwise, just drain the queue for a live session.+ output = []+ try:+ while True:+ output.append(session["output_stream"].get_nowait())+ except Empty:+ pass++ return "".join(output)++ def shell_wait(self, id: str, wait_seconds: float = 5.0) -> str:+ r"""This function waits for a specified duration for a+ non-blocking process to produce more output or terminate.++ Args:+ id (str): The unique session ID of the non-blocking process.+ wait_seconds (float): The maximum number of seconds to wait.++ Returns:+ str: All output collected during the wait period.+ """+ with self._session_lock:+ if id not in self.shell_sessions:+ return f"Error: No session found with ID '{id}'."+ session = self.shell_sessions[id]+ if not session["running"]:+ return (+ "Session is no longer running. "+ "Use shell_view to get final output."+ )++ output_collected = []+ end_time = time.time() + wait_seconds+ while time.time() < end_time and session["running"]:+ new_output = self.shell_view(id)+ if new_output:+ output_collected.append(new_output)+ time.sleep(0.2)++ return "".join(output_collected)++ def shell_kill_process(self, id: str) -> str:+ r"""This function forcibly terminates a running non-blocking process.++ Args:+ id (str): The unique session ID of the process to kill.++ Returns:+ str: A confirmation message indicating the process was terminated.+ """+ with self._session_lock:+ if (+ id not in self.shell_sessions+ or not self.shell_sessions[id]["running"]+ ):+ return f"Error: No active session found with ID '{id}'."+ session = self.shell_sessions[id]+ try:+ if session["backend"] == "local":+ session["process"].terminate()+ time.sleep(0.5)+ if session["process"].poll() is None:+ session["process"].kill()+ # Ensure stdio streams are closed to unblock reader thread+ try:+ if getattr(session["process"], "stdin", None):+ session["process"].stdin.close()+ except Exception:+ pass+ try:+ if getattr(session["process"], "stdout", None):+ session["process"].stdout.close()+ except Exception:+ pass+ else: # docker+ # Docker exec processes stop when the socket is closed.+ session["process"].close()+ with self._session_lock:+ if id in self.shell_sessions:+ self.shell_sessions[id]["running"] = False+ return f"Process in session '{id}' has been terminated."+ except Exception as e:+ return f"Error killing process in session '{id}': {e}"++ def shell_ask_user_for_help(self, id: str, prompt: str) -> str:+ r"""This function pauses execution and asks a human for help+ with an interactive session.++ This method can handle different scenarios:+ 1. If session exists: Shows session output and allows interaction+ 2. If session doesn't exist: Creates a temporary session for help++ Args:+ id (str): The session ID of the interactive process needing help.+ Can be empty string for general help without session context.+ prompt (str): The question or instruction from the LLM to show the+ human user (e.g., "The program is asking for a filename. Please+ enter 'config.json'.").++ Returns:+ str: The output from the shell session after the user's command has+ been executed, or help information for general queries.+ """+ logger.info("\n" + "=" * 60)+ logger.info("🤖 LLM Agent needs your help!")+ logger.info(f"PROMPT: {prompt}")++ # Case 1: Session doesn't exist - offer to create one+ if id not in self.shell_sessions:+ try:+ user_input = input("Your response: ").strip()+ if not user_input:+ return "No user response."+ else:+ logger.info(+ f"Creating session '{id}' and executing command..."+ )+ result = self.shell_exec(id, user_input, block=True)+ return (+ f"Session '{id}' created and "+ f"executed command:\n{result}"+ )+ except EOFError:+ return f"User input interrupted for session '{id}' creation."++ # Case 2: Session exists - show context and interact+ else:+ # Get the latest output to show the user the current state+ last_output = self._collect_output_until_idle(id)++ logger.info(f"SESSION: '{id}' (active)")+ logger.info("=" * 60)+ logger.info("--- LAST OUTPUT ---")+ logger.info(+ last_output.strip()+ if last_output.strip()+ else "(no recent output)"+ )+ logger.info("-------------------")++ try:+ user_input = input("Your input: ").strip()+ if not user_input:+ return f"User provided no input for session '{id}'."+ else:+ # Send input to the existing session+ return self.shell_write_to_process(id, user_input)+ except EOFError:+ return f"User input interrupted for session '{id}'."++ def __del__(self):+ # Clean up any sessions+ with self._session_lock:+ session_ids = list(self.shell_sessions.keys())+ for session_id in session_ids:+ with self._session_lock:+ is_running = self.shell_sessions.get(session_id, {}).get(+ "running", False+ )+ if is_running:+ self.shell_kill_process(session_id)++ def get_tools(self) -> List[FunctionTool]:+ r"""Returns a list of FunctionTool objects representing the functions+ in the toolkit.++ Returns:+ List[FunctionTool]: A list of FunctionTool objects representing the+ functions in the toolkit.+ """+ return [+ FunctionTool(self.shell_exec),+ FunctionTool(self.shell_view),+ FunctionTool(self.shell_wait),+ FunctionTool(self.shell_write_to_process),+ FunctionTool(self.shell_kill_process),+ FunctionTool(self.shell_ask_user_for_help),+ ]diff --git a/camel/toolkits/terminal_toolkit/utils.py b/camel/toolkits/terminal_toolkit/utils.pynew file mode 100644index 000000000..174e865c1--- /dev/null+++ b/camel/toolkits/terminal_toolkit/utils.py@@ -0,0 +1,580 @@+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========+# Licensed under the Apache License, Version 2.0 (the "License");+# you may not use this file except in compliance with the License.+# You may obtain a copy of the License at+#+# http://www.apache.org/licenses/LICENSE-2.0+#+# Unless required by applicable law or agreed to in writing, software+# distributed under the License is distributed on an "AS IS" BASIS,+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+# See the License for the specific language governing permissions and+# limitations under the License.+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========++import os+import platform+import re+import shlex+import shutil+import subprocess+import sys+import venv+from typing import Optional, Set, Tuple++from camel.logger import get_logger++logger = get_logger(__name__)+++def contains_command_chaining(command: str) -> bool:+ r"""Check if command contains chaining operators that could be used to+ bypass security.+ """+ # Pattern to match command chaining operators: ;, &&, ||, |+ # But exclude cases where they are inside quotes or escaped+ chaining_pattern = r'''+ (?<!\\) # Not preceded by backslash (not escaped)+ (?: # Group for alternation+ ; # Semicolon+ | # OR+ \|\| # Logical OR+ | # OR+ && # Logical AND+ | # OR+ (?<!\|) # Not preceded by pipe (to avoid matching ||)+ \| # Single pipe+ (?!\|) # Not followed by pipe (to avoid matching ||)+ )+ (?= # Positive lookahead+ (?: # Group+ [^"'] # Not a quote+ | # OR+ "[^"]*" # Content in double quotes+ | # OR+ '[^']*' # Content in single quotes+ )* # Zero or more times+ $ # End of string+ )+ '''++ return bool(re.search(chaining_pattern, command, re.VERBOSE))+++def sanitize_command(+ command: str,+ use_docker_backend: bool = False,+ safe_mode: bool = True,+ working_dir: Optional[str] = None,+ allowed_commands: Optional[Set[str]] = None,+) -> Tuple[bool, str]:+ r"""A comprehensive command sanitizer for both local and Docker backends.++ Args:+ command (str): The command to sanitize+ use_docker_backend (bool): Whether using Docker backend+ safe_mode (bool): Whether to apply security checks+ working_dir (Optional[str]): Working directory for path validation+ allowed_commands (Optional[Set[str]]): Set of allowed commands++ Returns:+ Tuple[bool, str]: (is_safe, message_or_command)+ """+ # Apply security checks to both backends - security should be consistent+ if not safe_mode:+ return True, command # Skip all checks if safe_mode is disabled++ # First check for command chaining and pipes+ if contains_command_chaining(command):+ return (+ False,+ "Command chaining (;, &&, ||, |) is not allowed "+ "for security reasons.",+ )++ parts = shlex.split(command)+ if not parts:+ return False, "Empty command is not allowed."+ base_cmd = parts[0].lower()++ # If whitelist is defined, only allow whitelisted commands+ if allowed_commands is not None:+ if base_cmd not in allowed_commands:+ return (+ False,+ f"Command '{base_cmd}' is not in the allowed commands list.",+ )+ # If command is whitelisted, skip the dangerous commands check+ # but still apply other safety checks+ else:+ # Block dangerous commands (only when no whitelist is defined)+ dangerous_commands = [+ # System administration+ 'sudo',+ 'su',+ 'reboot',+ 'shutdown',+ 'halt',+ 'poweroff',+ 'init',+ # File system manipulation+ 'rm',+ 'mv',+ 'chmod',+ 'chown',+ 'chgrp',+ 'umount',+ 'mount',+ # Disk operations+ 'dd',+ 'mkfs',+ 'fdisk',+ 'parted',+ 'fsck',+ 'mkswap',+ 'swapon',+ 'swapoff',+ # Process management+ 'kill',+ 'killall',+ 'pkill',+ 'service',+ 'systemctl',+ 'systemd',+ # Network configuration+ 'iptables',+ 'ip6tables',+ 'ifconfig',+ 'route',+ 'iptables-save',+ # Cron and scheduling+ 'crontab',+ 'at',+ 'batch',+ # User management+ 'useradd',+ 'userdel',+ 'usermod',+ 'passwd',+ 'chpasswd',+ 'newgrp',+ # Kernel modules+ 'modprobe',+ 'rmmod',+ 'insmod',+ 'lsmod',+ # System information that could leak sensitive data+ 'dmesg',+ 'last',+ 'lastlog',+ 'who',+ 'w',+ ]+ if base_cmd in dangerous_commands:+ # Special handling for rm command - use regex for precise checking+ if base_cmd == 'rm':+ # Check for dangerous rm options using regex+ dangerous_rm_pattern = (+ r'\s-[^-\s]*[rf][^-\s]*\s|\s--force\s|'+ r'\s--recursive\s|\s-rf\s|\s-fr\s'+ )+ if re.search(dangerous_rm_pattern, command, re.IGNORECASE):+ return (+ False,+ f"Command '{base_cmd}' with forceful or "+ f"recursive options is blocked for safety.",+ )+ # Also block rm without any target (could be dangerous)+ if len(parts) < 2:+ return (+ False,+ "rm command requires target "+ "file/directory specification.",+ )+ else:+ return False, f"Command '{base_cmd}' is blocked for safety."++ # For local backend only: prevent changing+ # directory outside the workspace+ # Docker containers are already sandboxed,+ # so this check is not needed there+ if (+ not use_docker_backend+ and base_cmd == 'cd'+ and len(parts) > 1+ and working_dir+ ):+ target_dir = os.path.abspath(os.path.join(working_dir, parts[1]))+ if not target_dir.startswith(working_dir):+ return False, "Cannot 'cd' outside of the working directory."++ return True, command+++# Environment management utilities+++def is_uv_environment() -> bool:+ r"""Detect whether the current Python runtime is managed by uv."""+ return (+ "UV_CACHE_DIR" in os.environ+ or "uv" in sys.executable+ or shutil.which("uv") is not None+ )+++def ensure_uv_available(update_callback=None) -> Tuple[bool, Optional[str]]:+ r"""Ensure uv is available, installing it if necessary.++ Args:+ update_callback: Optional callback function to receive status updates++ Returns:+ Tuple[bool, Optional[str]]: (success, uv_path)+ """+ # Check if uv is already available+ existing_uv = shutil.which("uv")+ if existing_uv is not None:+ if update_callback:+ update_callback(f"uv is already available at: {existing_uv}\n")+ return True, existing_uv++ try:+ if update_callback:+ update_callback("uv not found, installing...\n")++ os_type = platform.system()++ # Install uv using the official installer script+ if os_type in ['darwin', 'linux'] or os_type.startswith('linux'):+ # Use curl to download and execute the installer+ install_cmd = "curl -LsSf https://astral.sh/uv/install.sh | sh"+ result = subprocess.run(+ install_cmd,+ shell=True,+ capture_output=True,+ text=True,+ timeout=60,+ )++ if result.returncode != 0:+ if update_callback:+ update_callback(f"Failed to install uv: {result.stderr}\n")+ return False, None++ # Check if uv was installed in the expected location+ home = os.path.expanduser("~")+ uv_bin_path = os.path.join(home, ".cargo", "bin")+ uv_executable = os.path.join(uv_bin_path, "uv")++ if os.path.exists(uv_executable):+ if update_callback:+ update_callback(+ f"uv installed successfully at: {uv_executable}\n"+ )+ return True, uv_executable++ elif os_type == 'Windows':+ # Use PowerShell to install uv on Windows+ install_cmd = (+ "powershell -ExecutionPolicy Bypass -c "+ "\"irm https://astral.sh/uv/install.ps1 | iex\""+ )+ result = subprocess.run(+ install_cmd,+ shell=True,+ capture_output=True,+ text=True,+ timeout=60,+ )++ if result.returncode != 0:+ if update_callback:+ update_callback(f"Failed to install uv: {result.stderr}\n")+ return False, None++ # Check if uv was installed in the expected location on Windows+ home = os.path.expanduser("~")+ uv_bin_path = os.path.join(home, ".cargo", "bin")+ uv_executable = os.path.join(uv_bin_path, "uv.exe")++ if os.path.exists(uv_executable):+ if update_callback:+ update_callback(+ f"uv installed successfully at: {uv_executable}\n"+ )+ return True, uv_executable++ if update_callback:+ update_callback("Failed to verify uv installation\n")+ return False, None++ except Exception as e:+ if update_callback:+ update_callback(f"Error installing uv: {e!s}\n")+ logger.error(f"Failed to install uv: {e}")+ return False, None+++def setup_initial_env_with_uv(+ env_path: str, uv_path: str, working_dir: str, update_callback=None+) -> bool:+ r"""Set up initial environment using uv."""+ try:+ # Create virtual environment with Python 3.10 using uv+ subprocess.run(+ [uv_path, "venv", "--python", "3.10", env_path],+ check=True,+ capture_output=True,+ cwd=working_dir,+ timeout=300,+ )++ # Get the python path from the new environment+ if platform.system() == 'Windows':+ python_path = os.path.join(env_path, "Scripts", "python.exe")+ else:+ python_path = os.path.join(env_path, "bin", "python")++ # Install essential packages using uv+ essential_packages = [+ "pip",+ "setuptools",+ "wheel",+ "pyautogui",+ "plotly",+ ]+ subprocess.run(+ [+ uv_path,+ "pip",+ "install",+ "--python",+ python_path,+ *essential_packages,+ ],+ check=True,+ capture_output=True,+ cwd=working_dir,+ timeout=300,+ )++ if update_callback:+ update_callback(+ "[UV] Initial environment created with Python 3.10 "+ "and essential packages"+ )+ return True++ except subprocess.CalledProcessError as e:+ error_msg = e.stderr.decode() if e.stderr else str(e)+ if update_callback:+ update_callback(f"UV setup failed: {error_msg}\n")+ return False+ except subprocess.TimeoutExpired:+ if update_callback:+ update_callback("UV setup timed out after 5 minutes\n")+ return False+++def setup_initial_env_with_venv(+ env_path: str, working_dir: str, update_callback=None+) -> bool:+ r"""Set up initial environment using standard venv."""+ try:+ # Create virtual environment with system Python+ venv.create(+ env_path, with_pip=True, system_site_packages=False, symlinks=False+ )++ # Get pip path+ if platform.system() == 'Windows':+ pip_path = os.path.join(env_path, "Scripts", "pip.exe")+ else:+ pip_path = os.path.join(env_path, "bin", "pip")++ # Upgrade pip and install essential packages+ essential_packages = [+ "pip",+ "setuptools",+ "wheel",+ "pyautogui",+ "plotly",+ ]+ subprocess.run(+ [pip_path, "install", "--upgrade", *essential_packages],+ check=True,+ capture_output=True,+ cwd=working_dir,+ timeout=300,+ )++ if update_callback:+ update_callback(+ "Initial environment created with system Python "+ "and essential packages"+ )+ return True++ except subprocess.CalledProcessError as e:+ error_msg = e.stderr.decode() if e.stderr else str(e)+ if update_callback:+ update_callback(f"Venv setup failed: {error_msg}\n")+ return False+ except subprocess.TimeoutExpired:+ if update_callback:+ update_callback("Venv setup timed out after 5 minutes\n")+ return False+++def clone_current_environment(+ env_path: str, working_dir: str, update_callback=None+) -> bool:+ r"""Create a new Python virtual environment, optionally using uv."""+ try:+ if os.path.exists(env_path):+ if update_callback:+ update_callback(f"Using existing environment: {env_path}\n")+ return True++ if update_callback:+ update_callback(+ f"Creating new Python environment at: {env_path}\n"+ )++ # Try to use uv if available+ success, uv_path = ensure_uv_available(update_callback)+ if success and uv_path:+ # Get current Python version+ current_version = (+ f"{sys.version_info.major}.{sys.version_info.minor}"+ )++ subprocess.run(+ [uv_path, "venv", "--python", current_version, env_path],+ check=True,+ capture_output=True,+ cwd=working_dir,+ timeout=300,+ )++ # Get the python path from the new environment+ if platform.system() == 'Windows':+ python_path = os.path.join(env_path, "Scripts", "python.exe")+ else:+ python_path = os.path.join(env_path, "bin", "python")++ # Install pip and setuptools using uv+ subprocess.run(+ [+ uv_path,+ "pip",+ "install",+ "--python",+ python_path,+ "pip",+ "setuptools",+ "wheel",+ ],+ check=True,+ capture_output=True,+ cwd=working_dir,+ timeout=300,+ )++ if update_callback:+ update_callback(+ "[UV] Cloned Python environment created successfully!\n"+ )+ return True+ else:+ # Fallback to standard venv+ if update_callback:+ update_callback(+ "Falling back to standard venv for cloning environment\n"+ )++ venv.create(env_path, with_pip=True, symlinks=False)++ # Ensure pip is properly available+ if platform.system() == 'Windows':+ python_path = os.path.join(env_path, "Scripts", "python.exe")+ else:+ python_path = os.path.join(env_path, "bin", "python")++ if os.path.exists(python_path):+ subprocess.run(+ [python_path, "-m", "pip", "install", "--upgrade", "pip"],+ check=True,+ capture_output=True,+ cwd=working_dir,+ timeout=60,+ )+ if update_callback:+ update_callback(+ "New Python environment created successfully with pip!"+ )+ else:+ if update_callback:+ update_callback(+ f"Warning: Python executable not found at "+ f"{python_path}"+ )+ return True++ except subprocess.CalledProcessError as e:+ error_msg = e.stderr.decode() if e.stderr else str(e)+ if update_callback:+ update_callback(f"Failed to create environment: {error_msg}\n")+ logger.error(f"Failed to create environment: {error_msg}")+ return False+ except subprocess.TimeoutExpired:+ if update_callback:+ update_callback("Environment creation timed out\n")+ return False+ except Exception as e:+ if update_callback:+ update_callback(f"Failed to create environment: {e!s}\n")+ logger.error(f"Failed to create environment: {e}")+ return False+++def check_nodejs_availability(update_callback=None) -> Tuple[bool, str]:+ r"""Check if Node.js is available without modifying the system."""+ try:+ # Check if Node.js is already available in the system+ node_result = subprocess.run(+ ["node", "--version"],+ check=False,+ capture_output=True,+ timeout=10,+ )++ npm_result = subprocess.run(+ ["npm", "--version"],+ check=False,+ capture_output=True,+ timeout=10,+ )++ if node_result.returncode == 0 and npm_result.returncode == 0:+ node_version = node_result.stdout.decode().strip()+ npm_version = npm_result.stdout.decode().strip()+ info = (+ f"Node.js {node_version} and npm {npm_version} are available"+ )+ if update_callback:+ update_callback(f"{info}\n")+ return True, info+ else:+ info = "Node.js not found. If needed, please install it manually."+ if update_callback:+ update_callback(f"Note: {info}\n")+ return False, info++ except Exception as e:+ info = f"Could not check Node.js availability - {e}"+ if update_callback:+ update_callback(f"Note: {info}.\n")+ logger.warning(f"Failed to check Node.js: {e}")+ return False, infodiff --git a/test/toolkits/test_terminal_toolkit.py b/test/toolkits/test_terminal_toolkit.pyindex e2c24dd51..3d4e02a41 100644--- a/test/toolkits/test_terminal_toolkit.py+++ b/test/toolkits/test_terminal_toolkit.py@@ -61,28 +61,32 @@ def test_shell_exec(terminal_toolkit, temp_dir):)assert "not found" in result.lower()- # Test session persistence+ # Test session persistence - use non-blocking mode to create sessionssession_id = "persistent_session"- terminal_toolkit.shell_exec(session_id, "echo 'test1'")+ terminal_toolkit.shell_exec(session_id, "echo 'test1'", block=False)assert session_id in terminal_toolkit.shell_sessions- assert terminal_toolkit.shell_sessions[session_id]["output"] != ""+ # For non-blocking mode, check if session was created+ # (output might be empty initially)+ assert "output_stream" in terminal_toolkit.shell_sessions[session_id]def test_shell_exec_multiple_sessions(terminal_toolkit, temp_dir):- # Test multiple concurrent sessions+ # Test multiple concurrent sessions - use non-blocking mode+ # to create sessionssession1 = "session1"session2 = "session2"- result1 = terminal_toolkit.shell_exec(+ terminal_toolkit.shell_exec(session1,"echo 'Session 1'",+ block=False,)- result2 = terminal_toolkit.shell_exec(+ terminal_toolkit.shell_exec(session2,"echo 'Session 2'",+ block=False,)- assert "Session 1" in result1- assert "Session 2" in result2+ # For non-blocking mode, sessions should be created immediatelyassert session1 in terminal_toolkit.shell_sessionsassert session2 in terminal_toolkit.shell_sessions