deepagents 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

deepagents/backends/composite.py

@@ -1,8 +1,15 @@
 """CompositeBackend: Route operations to different backends based on path prefix."""
 
-from deepagents.backends.protocol import BackendProtocol, EditResult, WriteResult
+from deepagents.backends.protocol import (
+    BackendProtocol,
+    EditResult,
+    ExecuteResponse,
+    FileInfo,
+    GrepMatch,
+    SandboxBackendProtocol,
+    WriteResult,
+)
 from deepagents.backends.state import StateBackend
-from deepagents.backends.utils import FileInfo, GrepMatch
 
 
 class CompositeBackend:
@@ -212,3 +219,31 @@ class CompositeBackend:
             except Exception:
                 pass
         return res
+
+    def execute(
+        self,
+        command: str,
+    ) -> ExecuteResponse:
+        """Execute a command via the default backend.
+
+        Execution is not path-specific, so it always delegates to the default backend.
+        The default backend must implement SandboxBackendProtocol for this to work.
+
+        Args:
+            command: Full shell command string to execute.
+
+        Returns:
+            ExecuteResponse with combined output, exit code, and truncation flag.
+
+        Raises:
+            NotImplementedError: If default backend doesn't support execution.
+        """
+        if isinstance(self.default, SandboxBackendProtocol):
+            return self.default.execute(command)
+
+        # This shouldn't be reached if the runtime check in the execute tool works correctly,
+        # but we include it as a safety fallback.
+        raise NotImplementedError(
+            "Default backend doesn't support command execution (SandboxBackendProtocol). "
+            "To enable execution, provide a default backend that implements SandboxBackendProtocol."
+        )

deepagents/backends/protocol.py

@@ -145,4 +145,52 @@ class BackendProtocol(Protocol):
         ...
 
 
+@dataclass
+class ExecuteResponse:
+    """Result of code execution.
+
+    Simplified schema optimized for LLM consumption.
+    """
+
+    output: str
+    """Combined stdout and stderr output of the executed command."""
+
+    exit_code: int | None = None
+    """The process exit code. 0 indicates success, non-zero indicates failure."""
+
+    truncated: bool = False
+    """Whether the output was truncated due to backend limitations."""
+
+
+@runtime_checkable
+class SandboxBackendProtocol(BackendProtocol, Protocol):
+    """Protocol for sandboxed backends with isolated runtime.
+
+    Sandboxed backends run in isolated environments (e.g., separate processes,
+    containers) and communicate via defined interfaces.
+    """
+
+    def execute(
+        self,
+        command: str,
+    ) -> ExecuteResponse:
+        """Execute a command in the process.
+
+        Simplified interface optimized for LLM consumption.
+
+        Args:
+            command: Full shell command string to execute.
+
+        Returns:
+            ExecuteResponse with combined output, exit code, optional signal, and truncation flag.
+        """
+        ...
+
+    @property
+    def id(self) -> str:
+        """Unique identifier for the sandbox backend."""
+        ...
+
+
 BackendFactory: TypeAlias = Callable[[ToolRuntime], BackendProtocol]
+BACKEND_TYPES = BackendProtocol | BackendFactory

deepagents/backends/sandbox.py

@@ -0,0 +1,341 @@
+"""Base sandbox implementation with execute() as the only abstract method.
+
+This module provides a base class that implements all SandboxBackendProtocol
+methods using shell commands executed via execute(). Concrete implementations
+only need to implement the execute() method.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from abc import ABC, abstractmethod
+
+from deepagents.backends.protocol import (
+    EditResult,
+    ExecuteResponse,
+    FileInfo,
+    GrepMatch,
+    SandboxBackendProtocol,
+    WriteResult,
+)
+
+_GLOB_COMMAND_TEMPLATE = """python3 -c "
+import glob
+import os
+import json
+import base64
+
+# Decode base64-encoded parameters
+path = base64.b64decode('{path_b64}').decode('utf-8')
+pattern = base64.b64decode('{pattern_b64}').decode('utf-8')
+
+os.chdir(path)
+matches = sorted(glob.glob(pattern, recursive=True))
+for m in matches:
+    stat = os.stat(m)
+    result = {{
+        'path': m,
+        'size': stat.st_size,
+        'mtime': stat.st_mtime,
+        'is_dir': os.path.isdir(m)
+    }}
+    print(json.dumps(result))
+" 2>/dev/null"""
+
+_WRITE_COMMAND_TEMPLATE = """python3 -c "
+import os
+import sys
+import base64
+
+file_path = '{file_path}'
+
+# Check if file already exists (atomic with write)
+if os.path.exists(file_path):
+    print(f'Error: File \\'{file_path}\\' already exists', file=sys.stderr)
+    sys.exit(1)
+
+# Create parent directory if needed
+parent_dir = os.path.dirname(file_path) or '.'
+os.makedirs(parent_dir, exist_ok=True)
+
+# Decode and write content
+content = base64.b64decode('{content_b64}').decode('utf-8')
+with open(file_path, 'w') as f:
+    f.write(content)
+" 2>&1"""
+
+_EDIT_COMMAND_TEMPLATE = """python3 -c "
+import sys
+import base64
+
+# Read file content
+with open('{file_path}', 'r') as f:
+    text = f.read()
+
+# Decode base64-encoded strings
+old = base64.b64decode('{old_b64}').decode('utf-8')
+new = base64.b64decode('{new_b64}').decode('utf-8')
+
+# Count occurrences
+count = text.count(old)
+
+# Exit with error codes if issues found
+if count == 0:
+    sys.exit(1)  # String not found
+elif count > 1 and not {replace_all}:
+    sys.exit(2)  # Multiple occurrences without replace_all
+
+# Perform replacement
+if {replace_all}:
+    result = text.replace(old, new)
+else:
+    result = text.replace(old, new, 1)
+
+# Write back to file
+with open('{file_path}', 'w') as f:
+    f.write(result)
+
+print(count)
+" 2>&1"""
+
+_READ_COMMAND_TEMPLATE = """python3 -c "
+import os
+import sys
+
+file_path = '{file_path}'
+offset = {offset}
+limit = {limit}
+
+# Check if file exists
+if not os.path.isfile(file_path):
+    print('Error: File not found')
+    sys.exit(1)
+
+# Check if file is empty
+if os.path.getsize(file_path) == 0:
+    print('System reminder: File exists but has empty contents')
+    sys.exit(0)
+
+# Read file with offset and limit
+with open(file_path, 'r') as f:
+    lines = f.readlines()
+
+# Apply offset and limit
+start_idx = offset
+end_idx = offset + limit
+selected_lines = lines[start_idx:end_idx]
+
+# Format with line numbers (1-indexed, starting from offset + 1)
+for i, line in enumerate(selected_lines):
+    line_num = offset + i + 1
+    # Remove trailing newline for formatting, then add it back
+    line_content = line.rstrip('\\n')
+    print(f'{{line_num:6d}}\\t{{line_content}}')
+" 2>&1"""
+
+
+class BaseSandbox(SandboxBackendProtocol, ABC):
+    """Base sandbox implementation with execute() as abstract method.
+
+    This class provides default implementations for all protocol methods
+    using shell commands. Subclasses only need to implement execute().
+    """
+
+    @abstractmethod
+    def execute(
+        self,
+        command: str,
+    ) -> ExecuteResponse:
+        """Execute a command in the sandbox and return ExecuteResponse.
+
+        Args:
+            command: Full shell command string to execute.
+
+        Returns:
+            ExecuteResponse with combined output, exit code, optional signal, and truncation flag.
+        """
+        ...
+
+    def ls_info(self, path: str) -> list[FileInfo]:
+        """Structured listing with file metadata using os.scandir."""
+        cmd = f"""python3 -c "
+import os
+import json
+
+path = '{path}'
+
+try:
+    with os.scandir(path) as it:
+        for entry in it:
+            result = {{
+                'path': entry.name,
+                'is_dir': entry.is_dir(follow_symlinks=False)
+            }}
+            print(json.dumps(result))
+except FileNotFoundError:
+    pass
+except PermissionError:
+    pass
+" 2>/dev/null"""
+
+        result = self.execute(cmd)
+
+        file_infos: list[FileInfo] = []
+        for line in result.output.strip().split("\n"):
+            if not line:
+                continue
+            try:
+                data = json.loads(line)
+                file_infos.append({"path": data["path"], "is_dir": data["is_dir"]})
+            except json.JSONDecodeError:
+                continue
+
+        return file_infos
+
+    def read(
+        self,
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000,
+    ) -> str:
+        """Read file content with line numbers using a single shell command."""
+        # Use template for reading file with offset and limit
+        cmd = _READ_COMMAND_TEMPLATE.format(file_path=file_path, offset=offset, limit=limit)
+        result = self.execute(cmd)
+
+        output = result.output.rstrip()
+        exit_code = result.exit_code
+
+        if exit_code != 0 or "Error: File not found" in output:
+            return f"Error: File '{file_path}' not found"
+
+        return output
+
+    def write(
+        self,
+        file_path: str,
+        content: str,
+    ) -> WriteResult:
+        """Create a new file. Returns WriteResult; error populated on failure."""
+        # Encode content as base64 to avoid any escaping issues
+        content_b64 = base64.b64encode(content.encode("utf-8")).decode("ascii")
+
+        # Single atomic check + write command
+        cmd = _WRITE_COMMAND_TEMPLATE.format(file_path=file_path, content_b64=content_b64)
+        result = self.execute(cmd)
+
+        # Check for errors (exit code or error message in output)
+        if result.exit_code != 0 or "Error:" in result.output:
+            error_msg = result.output.strip() or f"Failed to write file '{file_path}'"
+            return WriteResult(error=error_msg)
+
+        # External storage - no files_update needed
+        return WriteResult(path=file_path, files_update=None)
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Edit a file by replacing string occurrences. Returns EditResult."""
+        # Encode strings as base64 to avoid any escaping issues
+        old_b64 = base64.b64encode(old_string.encode("utf-8")).decode("ascii")
+        new_b64 = base64.b64encode(new_string.encode("utf-8")).decode("ascii")
+
+        # Use template for string replacement
+        cmd = _EDIT_COMMAND_TEMPLATE.format(file_path=file_path, old_b64=old_b64, new_b64=new_b64, replace_all=replace_all)
+        result = self.execute(cmd)
+
+        exit_code = result.exit_code
+        output = result.output.strip()
+
+        if exit_code == 1:
+            return EditResult(error=f"Error: String not found in file: '{old_string}'")
+        if exit_code == 2:
+            return EditResult(error=f"Error: String '{old_string}' appears multiple times. Use replace_all=True to replace all occurrences.")
+        if exit_code != 0:
+            return EditResult(error=f"Error: File '{file_path}' not found")
+
+        count = int(output)
+        # External storage - no files_update needed
+        return EditResult(path=file_path, files_update=None, occurrences=count)
+
+    def grep_raw(
+        self,
+        pattern: str,
+        path: str | None = None,
+        glob: str | None = None,
+    ) -> list[GrepMatch] | str:
+        """Structured search results or error string for invalid input."""
+        search_path = path or "."
+
+        # Build grep command to get structured output
+        grep_opts = "-rHn"  # recursive, with filename, with line number
+
+        # Add glob pattern if specified
+        glob_pattern = ""
+        if glob:
+            glob_pattern = f"--include='{glob}'"
+
+        # Escape pattern for shell
+        pattern_escaped = pattern.replace("'", "'\\\\''")
+
+        cmd = f"grep {grep_opts} {glob_pattern} -e '{pattern_escaped}' '{search_path}' 2>/dev/null || true"
+        result = self.execute(cmd)
+
+        output = result.output.rstrip()
+        if not output:
+            return []
+
+        # Parse grep output into GrepMatch objects
+        matches: list[GrepMatch] = []
+        for line in output.split("\n"):
+            # Format is: path:line_number:text
+            parts = line.split(":", 2)
+            if len(parts) >= 3:
+                matches.append(
+                    {
+                        "path": parts[0],
+                        "line": int(parts[1]),
+                        "text": parts[2],
+                    }
+                )
+
+        return matches
+
+    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Structured glob matching returning FileInfo dicts."""
+        # Encode pattern and path as base64 to avoid escaping issues
+        pattern_b64 = base64.b64encode(pattern.encode("utf-8")).decode("ascii")
+        path_b64 = base64.b64encode(path.encode("utf-8")).decode("ascii")
+
+        cmd = _GLOB_COMMAND_TEMPLATE.format(path_b64=path_b64, pattern_b64=pattern_b64)
+        result = self.execute(cmd)
+
+        output = result.output.strip()
+        if not output:
+            return []
+
+        # Parse JSON output into FileInfo dicts
+        file_infos: list[FileInfo] = []
+        for line in output.split("\n"):
+            try:
+                data = json.loads(line)
+                file_infos.append(
+                    {
+                        "path": data["path"],
+                        "is_dir": data["is_dir"],
+                    }
+                )
+            except json.JSONDecodeError:
+                continue
+
+        return file_infos
+
+    @property
+    @abstractmethod
+    def id(self) -> str:
+        """Unique identifier for this backend instance."""

deepagents/backends/store.py

@@ -1,17 +1,12 @@
 """StoreBackend: Adapter for LangGraph's BaseStore (persistent, cross-thread)."""
 
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from langchain.tools import ToolRuntime
+from typing import Any
 
 from langgraph.config import get_config
 from langgraph.store.base import BaseStore, Item
 
-from deepagents.backends.protocol import EditResult, WriteResult
+from deepagents.backends.protocol import BackendProtocol, EditResult, FileInfo, GrepMatch, WriteResult
 from deepagents.backends.utils import (
-    FileInfo,
-    GrepMatch,
     _glob_search_files,
     create_file_data,
     file_data_to_string,
@@ -22,7 +17,7 @@ from deepagents.backends.utils import (
 )
 
 
-class StoreBackend:
+class StoreBackend(BackendProtocol):
     """Backend that stores files in LangGraph's BaseStore (persistent).
 
     Uses LangGraph's Store for persistent, cross-conversation storage.
@@ -381,6 +376,3 @@ class StoreBackend:
                 }
             )
         return infos
-
-
-# Provider classes removed: prefer callables like `lambda rt: StoreBackend(rt)`

deepagents/graph.py

@@ -57,9 +57,12 @@ def create_deep_agent(
     """Create a deep agent.
 
     This agent will by default have access to a tool to write todos (write_todos),
-    six file editing tools: write_file, ls, read_file, edit_file, glob_search, grep_search,
+    seven file and execution tools: ls, read_file, write_file, edit_file, glob, grep, execute,
     and a tool to call subagents.
 
+    The execute tool allows running shell commands if the backend implements SandboxBackendProtocol.
+    For non-sandbox backends, the execute tool will return an error message.
+
     Args:
         model: The model to use. Defaults to Claude Sonnet 4.
         tools: The tools the agent should have access to.
@@ -80,8 +83,9 @@ def create_deep_agent(
         context_schema: The schema of the deep agent.
         checkpointer: Optional checkpointer for persisting agent state between runs.
         store: Optional store for persistent storage (required if backend uses StoreBackend).
-        backend: Optional backend for file storage. Pass either a Backend instance or a
-            callable factory like `lambda rt: StateBackend(rt)`.
+        backend: Optional backend for file storage and execution. Pass either a Backend instance
+            or a callable factory like `lambda rt: StateBackend(rt)`. For execution support,
+            use a backend that implements SandboxBackendProtocol.
         interrupt_on: Optional Dict[str, bool | InterruptOnConfig] mapping tool names to
             interrupt configs.
         debug: Whether to enable debug mode. Passed through to create_agent.