review comments

Signed-off-by: Akihiko Kuroda <akihikokuroda2020@gmail.com>

Author: akihikokuroda

docs/examples/tools/shell_example.py

@@ -1,46 +1,60 @@
 # pytest: e2e, qualitative
-"""Example usage patterns for bash_executor and local_bash_executor tools.
+"""Example usage patterns for bash_executor and unsafe_local_bash_executor tools.
 
 Demonstrates multiple ways to use Mellea's bash execution capabilities:
 1. Direct execution for non-LLM tasks
 2. Wrapping as a MelleaTool for agent use
 3. LLM-based tool calling with forced tool use
 4. Integration with error handling
 
-Safety note: bash_executor uses Docker isolation via llm-sandbox (recommended
-for production). local_bash_executor runs commands directly (for dev/testing only).
+⚠️  Security note: bash_executor uses Docker isolation via llm-sandbox (recommended
+for production and LLM-generated code). unsafe_local_bash_executor runs commands
+directly with no isolation (development/testing only with trusted code).
 Both enforce a conservative safety denylist: no sudo, no rm -rf, no destructive
 git operations, no writes to /etc, /sys, /proc, etc. Write operations can also
 be constrained with ``working_dir`` and explicit ``allowed_paths``.
+
+Note: Commands must use argv-friendly syntax (no pipes, redirects, or shell builtins).
+Use individual commands and compose them in Python instead.
 """
 
 from mellea import MelleaSession, start_session
 from mellea.backends import ModelOption
 from mellea.backends.tools import MelleaTool
 from mellea.stdlib.requirements import uses_tool
-from mellea.stdlib.tools.shell import bash_executor, local_bash_executor
+from mellea.stdlib.tools.shell import bash_executor, unsafe_local_bash_executor
 
 
 def example_1_direct_execution() -> None:
     """Example 1: Execute bash commands directly."""
     print("=== Example 1: Direct Execution ===")
 
     # Execute a simple command
-    result = local_bash_executor("echo 'Hello from Bash'")
+    result = unsafe_local_bash_executor("echo 'Hello from Bash'")
     print("Command: echo 'Hello from Bash'")
     print(f"Success: {result.success}")
     print(f"Output: {result.stdout}")
     print()
 
-    # Execute a command with pipes and redirects
-    result = local_bash_executor("ls -la | wc -l")
-    print("Command: ls -la | wc -l")
+    # Execute a command to list files (no pipes/redirects)
+    result = unsafe_local_bash_executor("ls -la")
+    print("Command: ls -la")
     print(f"Success: {result.success}")
-    print(f"Output: {result.stdout}")
+    if result.stdout:
+        # Show first few lines
+        lines = result.stdout.split("\n")[:3]
+        print("Output (first 3 lines):\n" + "\n".join(lines))
+    print()
+
+    # Demonstrate that pipes are blocked (for security)
+    result = unsafe_local_bash_executor("ls -la | wc -l")
+    print("Command: ls -la | wc -l (pipe operator blocked)")
+    print(f"Rejected: {result.skipped}")
+    print(f"Reason: {result.skip_message}")
     print()
 
     # Attempt a dangerous command (will be rejected)
-    result = local_bash_executor("sudo echo unsafe")
+    result = unsafe_local_bash_executor("sudo echo unsafe")
     print("Command: sudo echo unsafe")
     print(f"Skipped: {result.skipped}")
     print(f"Reason: {result.skip_message}")
@@ -52,7 +66,7 @@ def example_2_wrapped_as_tool() -> None:
     print("=== Example 2: Wrapped as MelleaTool ===")
 
     # Create tool from bash executor
-    bash_tool = MelleaTool.from_callable(local_bash_executor)
+    bash_tool = MelleaTool.from_callable(unsafe_local_bash_executor)
     print(f"Tool name: {bash_tool.name}")
     print(f"Tool schema keys: {bash_tool.as_json_tool.keys()}")
     print()
@@ -75,9 +89,9 @@ def example_3_llm_with_forced_tool_use(m: MelleaSession) -> None:
 
     result = m.instruct(
         description="Use bash to count how many Python files are in the current directory.",
-        requirements=[uses_tool(local_bash_executor)],
+        requirements=[uses_tool(unsafe_local_bash_executor)],
         model_options={
-            ModelOption.TOOLS: [MelleaTool.from_callable(local_bash_executor)]
+            ModelOption.TOOLS: [MelleaTool.from_callable(unsafe_local_bash_executor)]
         },
         tool_calls=True,
     )
@@ -86,11 +100,11 @@ def example_3_llm_with_forced_tool_use(m: MelleaSession) -> None:
         raise ValueError("Expected tool_calls but got None")
 
     # Extract the bash command the LLM generated
-    command = result.tool_calls["local_bash_executor"].args["command"]
+    command = result.tool_calls["unsafe_local_bash_executor"].args["command"]
     print(f"LLM generated bash command:\n  {command}\n")
 
     # Execute the command
-    exec_result = result.tool_calls["local_bash_executor"].call_func()
+    exec_result = result.tool_calls["unsafe_local_bash_executor"].call_func()
 
     print("Execution result:")
     print(f"  Success: {exec_result.success}")
@@ -104,31 +118,42 @@ def example_3_with_working_dir() -> None:
     """Example 3: Restrict write validation and execution cwd to a directory."""
     print("=== Example 3: Working Directory Restriction ===")
 
+    import os
     import tempfile
 
     with tempfile.TemporaryDirectory() as tmpdir:
         print(f"Working directory: {tmpdir}")
 
-        # Create a file in the working directory
-        result = local_bash_executor(
-            f"echo 'project content' > {tmpdir}/myfile.txt", working_dir=tmpdir
-        )
-        print(f"Command: echo 'project content' > {tmpdir}/myfile.txt")
+        # Create a file using touch within the working directory (redirects blocked)
+        result = unsafe_local_bash_executor("touch myfile.txt", working_dir=tmpdir)
+        print(f"Command: touch myfile.txt (relative path, executed in {tmpdir})")
         print(f"Success: {result.success}")
         print()
 
+        # Verify the file was created
+        file_path = os.path.join(tmpdir, "myfile.txt")
+        if os.path.exists(file_path):
+            print(f"✓ File created at: {file_path}")
+        print()
+
         # Read it back
-        result = local_bash_executor(f"cat {tmpdir}/myfile.txt", working_dir=tmpdir)
-        print(f"Command: cat {tmpdir}/myfile.txt")
+        result = unsafe_local_bash_executor("cat myfile.txt", working_dir=tmpdir)
+        print("Command: cat myfile.txt")
         print(f"Output: {result.stdout}")
         print()
 
-        # Attempt to write outside the restricted working directory (will be rejected)
-        result = local_bash_executor(
-            "echo 'bad' > /tmp/outside.txt", working_dir=tmpdir
+        # Writing to /tmp is always allowed (temp directory exception)
+        result = unsafe_local_bash_executor(
+            "touch /tmp/tmpfile.txt", working_dir=tmpdir
         )
-        print(f"Command: echo 'bad' > /tmp/outside.txt (with working_dir={tmpdir})")
-        print(f"Skipped: {result.skipped}")
+        print(f"Command: touch /tmp/tmpfile.txt (with working_dir={tmpdir})")
+        print(f"Success: {result.success} (note: /tmp is always allowed)")
+        print()
+
+        # Attempt to write to system paths (will be rejected)
+        result = unsafe_local_bash_executor("touch /etc/config.txt", working_dir=tmpdir)
+        print(f"Command: touch /etc/config.txt (with working_dir={tmpdir})")
+        print(f"Rejected: {result.skipped}")
         print(f"Reason: {result.skip_message}")
         print()
 
@@ -146,7 +171,7 @@ def example_4_safety_features() -> None:
     ]
 
     for cmd, description in dangerous_commands:
-        result = local_bash_executor(cmd)
+        result = unsafe_local_bash_executor(cmd)
         print(f"{description}: {cmd}")
         print(f"  Rejected: {result.skipped}")
         print(f"  Reason: {result.skip_message}")
@@ -158,14 +183,14 @@ def example_5_error_handling() -> None:
     print("=== Example 5: Error Handling ===")
 
     # Command that fails (returns non-zero exit code)
-    result = local_bash_executor("exit 1")
-    print("Command: exit 1")
+    result = unsafe_local_bash_executor("false")
+    print("Command: false (POSIX command that returns exit code 1)")
     print(f"Success: {result.success}")
-    print(f"Stderr: {result.stderr}")
+    print(f"Return code indicates failure: {not result.success}")
     print()
 
     # Command that doesn't exist
-    result = local_bash_executor("nonexistent_command_xyz")
+    result = unsafe_local_bash_executor("nonexistent_command_xyz")
     print("Command: nonexistent_command_xyz")
     print(f"Success: {result.success}")
     if not result.success and result.stderr is not None:

mellea/stdlib/tools/__init__.py

@@ -1,11 +1,20 @@
 """Implementations of tools."""
 
 from .interpreter import code_interpreter, local_code_interpreter
-from .shell import bash_executor, local_bash_executor
+from .shell import (
+    BashEnvironment,
+    LLMSandboxBashEnvironment,
+    StaticBashEnvironment,
+    bash_executor,
+    unsafe_local_bash_executor,
+)
 
 __all__ = [
+    "BashEnvironment",
+    "LLMSandboxBashEnvironment",
+    "StaticBashEnvironment",
     "bash_executor",
     "code_interpreter",
-    "local_bash_executor",
     "local_code_interpreter",
+    "unsafe_local_bash_executor",
 ]