Camel.toolkits.terminal toolkit
TerminalToolkit
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.
Parameters:
- timeout (Optional[float]): The timeout for terminal operations.
- shell_sessions (Optional[Dict[str, Any]]): A dictionary to store shell session information. If None, an empty dictionary will be used. (default: :obj:
{}
) - working_dir (str): The working directory for operations. If specified, all execution and write operations will be restricted to this directory. Read operations can access paths outside this directory.(default: :obj:
"./workspace"
) - 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
) - Note: Most functions are compatible with Unix-based systems (macOS, Linux). For Windows compatibility, additional implementation details are needed.
init
_setup_file_output
Set up file output to replace GUI, using a fixed file to simulate terminal.
_clone_current_environment
Create a new Python virtual environment.
_create_terminal
Create a terminal GUI.
_update_terminal_output
Update terminal output and send to agent.
Parameters:
- output (str): The output to be sent to the agent
_is_path_within_working_dir
Check if the path is within the working directory.
Parameters:
- path (str): The path to check
Returns:
bool: Returns True if the path is within the working directory, otherwise returns False
_enforce_working_dir_for_execution
Enforce working directory restrictions, return error message if execution path is not within the working directory.
Parameters:
- 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
_copy_external_file_to_workdir
Copy external file to working directory.
Parameters:
- external_file (str): The path of the external file
Returns:
Optional[str]: New path after copying to the working directory, returns None on failure
file_find_in_content
Search for matching text within file content.
Parameters:
- 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.
Returns:
str: Matching content found in the file.
file_find_by_name
Find files by name pattern in specified directory.
Parameters:
- path (str): Absolute path of directory to search.
- glob (str): Filename pattern using glob syntax wildcards.
Returns:
str: List of files matching the pattern.
_sanitize_command
Check and modify command to ensure safety.
Parameters:
- 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)
shell_exec
Execute commands. This can be used to execute various commands, such as writing code, executing code, and running commands.
Parameters:
- id (str): Unique identifier of the target shell session.
- command (str): Shell command to execute.
Returns:
str: Output of the command execution or error message.
shell_view
View the content of a specified shell session.
Parameters:
- id (str): Unique identifier of the target shell session.
Returns:
str: Current output content of the shell session.
shell_wait
Wait for the running process in a specified shell session to return.
Parameters:
- id (str): Unique identifier of the target shell session.
- seconds (Optional[int], optional): Wait duration in seconds. If None, wait indefinitely. Defaults to None.
Returns:
str: Final output content after waiting.
shell_write_to_process
Write input to a running process in a specified shell session.
Parameters:
- 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.
Returns:
str: Status message indicating whether the input was sent.
shell_kill_process
Terminate a running process in a specified shell session.
Parameters:
- id (str): Unique identifier of the target shell session.
Returns:
str: Status message indicating whether the process was terminated.
del
Clean up resources when the object is being destroyed. Terminates all running processes and closes any open file handles.
get_tools
Returns:
List[FunctionTool]: A list of FunctionTool objects representing the functions in the toolkit.