Shell Command Tool Documentation

Overview

The ShellCommandTool provides a secure and controlled interface for executing shell commands within the mindX system. It enables agents to perform system operations while maintaining proper error handling and logging.

File: tools/shell_command_tool.py Class: ShellCommandTool Version: 1.0.0 Status: ✅ Active

Architecture

Design Principles

Async Execution: Uses asyncio for non-blocking command execution

Error Isolation: Captures and returns errors without crashing

Comprehensive Logging: Logs all command executions and results

Security: Executes commands in controlled environment

Core Components

class ShellCommandTool(BaseTool):
    - logger: Logger instance for command tracking
    - execute(): Main execution method

Usage

Basic Execution

from tools.shell_command_tool import ShellCommandTool

tool = ShellCommandTool()
Execute a command
success, output = await tool.execute(command="ls -la")

if success:
    print(f"Command output: {output}")
else:
    print(f"Command failed: {output}")

Response Format

The tool returns a tuple:

First element (bool): True if command succeeded (return code 0), False otherwise

Second element (str): Command output (stdout) on success, error message (stderr) on failure

Features

1. Async Subprocess Execution

Uses asyncio.create_subprocess_shell for non-blocking execution:

process = await asyncio.create_subprocess_shell(
    command,
    stdout=asyncio.subprocess.PIPE,
    stderr=asyncio.subprocess.PIPE
)

2. Output Capture

Captures both stdout and stderr

Decodes output to UTF-8 strings

Strips whitespace for clean output

3. Error Handling

Catches subprocess errors

Returns structured error messages

Logs all errors with full context

Security Considerations

Current Implementation

No Sandboxing: Commands execute with full system permissions

No Input Validation: Command strings are not validated before execution

No Command Whitelisting: Any command can be executed

Recommended Security Enhancements

Command Whitelisting: Only allow specific safe commands

Path Validation: Validate file paths in commands

User Permissions: Execute commands with limited user permissions

Timeout Enforcement: Add command execution timeouts

Resource Limits: Limit CPU and memory usage

Integration

With BDI Agents

# In agent plan
plan = [
    {
        "action": "execute_shell_command",
        "command": "git status",
        "expected_result": "success"
    }
]

With Other Tools

The ShellCommandTool is used by other tools like TreeAgent for file system operations.

Limitations

Current Limitations

No Timeout: Commands can run indefinitely

No Resource Limits: No CPU or memory constraints

No Command Validation: Any command string is accepted

No Output Parsing: Raw string output only

No Command History: No tracking of executed commands

Recommended Improvements

Add Timeout Support: Prevent hanging commands

Resource Limits: Set CPU and memory limits

Command Validation: Validate commands before execution

Output Parsing: Parse structured output (JSON, YAML, etc.)

Command History: Track command execution history

Retry Logic: Automatic retry for transient failures

Examples

Simple Command

success, output = await tool.execute("pwd")
Returns: (True, "/home/user/mindX")

Command with Error

success, output = await tool.execute("nonexistent_command")
Returns: (False, "Command 'nonexistent_command' not found")

Complex Command

success, output = await tool.execute("find . -name '*.py' | head -10")
Returns: (True, "file1.py\nfile2.py\n...")

Technical Details

Dependencies

asyncio - Async subprocess execution

core.bdi_agent.BaseTool - Base tool class

utils.logging_config.get_logger - Logging utility

Error Handling

try:
    process = await asyncio.create_subprocess_shell(...)
    stdout, stderr = await process.communicate()
    
    if process.returncode == 0:
        return True, stdout.decode().strip()
    else:
        return False, stderr.decode().strip()
except Exception as e:
    return False, f"An exception occurred: {e}"

Future Enhancements

Command Templates: Pre-defined command templates

Output Formatting: Structured output parsing

Command Chaining: Support for command pipelines

Environment Variables: Configurable environment setup

Working Directory: Support for changing working directory

Interactive Commands: Support for interactive command execution

---