Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: refactor terminal_toolkit (#3015)

Tao Sun7d74fcba8a87
diff --git a/camel/toolkits/terminal_toolkit.py b/camel/toolkits/terminal_toolkit.py
deleted file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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, info
diff --git a/test/toolkits/test_terminal_toolkit.py b/test/toolkits/test_terminal_toolkit.py
index 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 sessions
session_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 sessions
session1 = "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 immediately
assert session1 in terminal_toolkit.shell_sessions
assert session2 in terminal_toolkit.shell_sessions