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: interactive mode in shell_exec (#2783)

Tao Sun89838eae7a43
diff --git a/camel/toolkits/terminal_toolkit.py b/camel/toolkits/terminal_toolkit.py
index c18b5d722..188ba8822 100644
--- a/camel/toolkits/terminal_toolkit.py
+++ b/camel/toolkits/terminal_toolkit.py
@@ -134,7 +134,14 @@ class TerminalToolkit(BaseToolkit):
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:
@@ -147,9 +154,6 @@ class TerminalToolkit(BaseToolkit):
# Directly append to the end of the file
with open(self.log_file, "a") as f:
f.write(output)
- # If the output does not end with a newline, add one
- if output and not output.endswith('\n'):
- f.write('\n')
# Ensure the agent also receives the output
self.agent_queue.put(output)
except Exception as e:
@@ -334,17 +338,24 @@ class TerminalToolkit(BaseToolkit):
def file_find_in_content(
self, file: str, regex: str, sudo: bool = False
) -> str:
- r"""Search for matching text within file content.
+ r"""Search for text within a file's content using a regular expression.
+
+ This function is useful for finding specific patterns or lines of text
+ within a given file. It uses `grep` on Unix-like systems and `findstr`
+ on Windows.
Args:
- file (str): Absolute path of the file to search within.
- regex (str): Regular expression pattern to match.
- sudo (bool, optional): Whether to use sudo privileges. Defaults to
- False. Note: Using sudo requires the process to have
- appropriate permissions.
+ file (str): The absolute path of the file to search within.
+ regex (str): The regular expression pattern to match.
+ sudo (bool, optional): Whether to use sudo privileges for the
+ search. Defaults to False. Note: Using sudo requires the
+ process to have appropriate permissions.
+ (default: :obj:`False`)
Returns:
- str: Matching content found in the file.
+ str: The matching content found in the file. If no matches are
+ found, an empty string is returned. Returns an error message
+ if the file does not exist or another error occurs.
"""
if not os.path.exists(file):
@@ -376,14 +387,21 @@ class TerminalToolkit(BaseToolkit):
return f"Error: {e!s}"
def file_find_by_name(self, path: str, glob: str) -> str:
- r"""Find files by name pattern in specified directory.
+ r"""Find files by name in a specified directory using a glob pattern.
+
+ This function recursively searches for files matching a given name or
+ pattern within a directory. It uses `find` on Unix-like systems and
+ `dir` on Windows.
Args:
- path (str): Absolute path of directory to search.
- glob (str): Filename pattern using glob syntax wildcards.
+ path (str): The absolute path of the directory to search in.
+ glob (str): The filename pattern to search for, using glob syntax
+ (e.g., "*.py", "data*").
Returns:
- str: List of files matching the pattern.
+ str: A newline-separated string containing the paths of the files
+ that match the pattern. Returns an error message if the
+ directory does not exist or another error occurs.
"""
if not os.path.exists(path):
return f"Directory not found: {path}"
@@ -649,18 +667,37 @@ class TerminalToolkit(BaseToolkit):
return True, command
- def shell_exec(self, id: str, command: str) -> str:
- r"""Execute commands. This can be used to execute various commands,
- such as writing code, executing code, and running commands.
+ def shell_exec(
+ self, id: str, command: str, interactive: bool = False
+ ) -> str:
+ r"""Executes a shell command in a specified session.
+
+ This function creates and manages shell sessions to execute commands,
+ simulating a real terminal. It can run commands in both non-interactive
+ (capturing output) and interactive modes. 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): Unique identifier of the target shell session.
- command (str): Shell command to execute.
+ 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.
+ interactive (bool, optional): If `True`, the command runs in
+ interactive mode, connecting it to the terminal's standard
+ input. This is useful for commands that require user input,
+ like `ssh`. Defaults to `False`. Interactive mode is only
+ supported on macOS and Linux. (default: :obj:`False`)
Returns:
- str: Output of the command execution or error message.
+ str: The standard output and standard error from the command. If an
+ error occurs during execution, a descriptive error message is
+ returned.
+
+ Note:
+ When `interactive` is set to `True`, this function may block if the
+ command requires input. In safe mode, some commands that are
+ considered dangerous are restricted.
"""
- # Command execution must be within the working directory
error_msg = self._enforce_working_dir_for_execution(self.working_dir)
if error_msg:
return error_msg
@@ -673,7 +710,6 @@ class TerminalToolkit(BaseToolkit):
return f"Command rejected: {sanitized_command}"
command = sanitized_command
- # If the session does not exist, create a new session
if id not in self.shell_sessions:
self.shell_sessions[id] = {
"process": None,
@@ -682,7 +718,6 @@ class TerminalToolkit(BaseToolkit):
}
try:
- # First, log the command to be executed
self._update_terminal_output(f"\n$ {command}\n")
if command.startswith('python') or command.startswith('pip'):
@@ -706,42 +741,130 @@ class TerminalToolkit(BaseToolkit):
elif command.startswith('pip'):
command = command.replace('pip', pip_path, 1)
- 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(),
- )
+ if not interactive:
+ 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(),
+ )
+
+ self.shell_sessions[id]["process"] = proc
+ self.shell_sessions[id]["running"] = True
+ stdout, stderr = proc.communicate()
+ output = stdout or ""
+ if stderr:
+ output += f"\nStderr Output:\n{stderr}"
+ self.shell_sessions[id]["output"] = output
+ 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)
- # Store the process and mark it as running
- self.shell_sessions[id]["process"] = proc
+ # 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)
- # Get output
- stdout, stderr = proc.communicate()
+ try:
+ tty.setraw(sys.stdin.fileno())
- output = stdout or ""
- if stderr:
- output += f"\nStderr Output:\n{stderr}"
+ 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
+ )
- # Update session information and terminal
- self.shell_sessions[id]["output"] = output
- self._update_terminal_output(output + "\n")
+ 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
- return output
+ 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")
-
- # More detailed error information
import traceback
detailed_error = traceback.format_exc()
@@ -751,13 +874,19 @@ class TerminalToolkit(BaseToolkit):
)
def shell_view(self, id: str) -> str:
- r"""View the content of a specified shell session.
+ 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): Unique identifier of the target shell session.
+ id (str): The unique identifier of the shell session to view.
Returns:
- str: Current output content of the shell session.
+ 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}"
@@ -788,16 +917,22 @@ class TerminalToolkit(BaseToolkit):
return f"Error: {e!s}"
def shell_wait(self, id: str, seconds: Optional[int] = None) -> str:
- r"""Wait for the running process in a specified shell session to
- return.
+ 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): Unique identifier of the target shell session.
- seconds (Optional[int], optional): Wait duration in seconds.
- If None, wait indefinitely. Defaults to None.
+ 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: Final output content after waiting.
+ 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}"
@@ -857,13 +992,20 @@ class TerminalToolkit(BaseToolkit):
) -> 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): Unique identifier of the target shell session.
- input (str): Input content to write to the process.
- press_enter (bool): Whether to press Enter key after input.
+ 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: Status message indicating whether the input was sent.
+ 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}"
@@ -899,11 +1041,17 @@ class TerminalToolkit(BaseToolkit):
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): Unique identifier of the target shell session.
+ id (str): The unique identifier of the shell session containing the
+ process to be terminated.
Returns:
- str: Status message indicating whether the process was terminated.
+ 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}"
@@ -939,22 +1087,24 @@ class TerminalToolkit(BaseToolkit):
return f"Error killing process: {e!s}"
def ask_user_for_help(self, id: str) -> str:
- r"""Pauses agent execution to ask a human for help in the terminal.
+ r"""Pause the agent and ask a human for help with a command.
- This function should be called when an agent is stuck or needs
- assistance with a task that requires manual intervention (e.g.,
- solving a CAPTCHA or complex debugging). The human will take over the
- specified terminal session to execute commands and then return control
- to the agent.
+ 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): Identifier of the shell session for the human to
- interact with. If the session does not yet exist, it will be
- created automatically.
+ 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.
+ 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):