deepagents 0.3.9__py3-none-any.whl → 0.3.10__py3-none-any.whl

deepagents/__init__.py

@@ -1,5 +1,6 @@
-"""DeepAgents package."""
+"""Deep Agents package."""
 
+from deepagents._version import __version__
 from deepagents.graph import create_deep_agent
 from deepagents.middleware.filesystem import FilesystemMiddleware
 from deepagents.middleware.memory import MemoryMiddleware
@@ -11,5 +12,6 @@ __all__ = [
     "MemoryMiddleware",
     "SubAgent",
     "SubAgentMiddleware",
+    "__version__",
     "create_deep_agent",
 ]

deepagents/_version.py

@@ -0,0 +1,3 @@
+"""deepagents version information."""
+
+__version__ = "0.3.10"  # x-release-please-version

deepagents/backends/__init__.py

@@ -2,6 +2,7 @@
 
 from deepagents.backends.composite import CompositeBackend
 from deepagents.backends.filesystem import FilesystemBackend
+from deepagents.backends.local_shell import LocalShellBackend
 from deepagents.backends.protocol import BackendProtocol
 from deepagents.backends.state import StateBackend
 from deepagents.backends.store import StoreBackend
@@ -10,6 +11,7 @@ __all__ = [
     "BackendProtocol",
     "CompositeBackend",
     "FilesystemBackend",
+    "LocalShellBackend",
     "StateBackend",
     "StoreBackend",
 ]

deepagents/backends/composite.py

@@ -222,13 +222,13 @@ class CompositeBackend(BackendProtocol):
         path: str | None = None,
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
-        """Search files for regex pattern.
+        """Search files for literal text pattern.
 
         Routes to backends based on path: specific route searches one backend,
         "/" or None searches all backends, otherwise searches default backend.
 
         Args:
-            pattern: Regex pattern to search for.
+            pattern: Literal text to search for (NOT regex).
             path: Directory to search. None searches all backends.
             glob: Glob pattern to filter files (e.g., "*.py", "**/*.txt").
                 Filters by filename, not content.

deepagents/backends/filesystem.py

@@ -388,25 +388,18 @@ class FilesystemBackend(BackendProtocol):
         path: str | None = None,
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
-        """Search for a regex pattern in files.
+        """Search for a literal text pattern in files.
 
-        Uses ripgrep if available, falling back to Python regex search.
+        Uses ripgrep if available, falling back to Python search.
 
         Args:
-            pattern: Regular expression pattern to search for.
+            pattern: Literal string to search for (NOT regex).
             path: Directory or file path to search in. Defaults to current directory.
             glob: Optional glob pattern to filter which files to search.
 
         Returns:
             List of GrepMatch dicts containing path, line number, and matched text.
-            Returns an error string if the regex pattern is invalid.
         """
-        # Validate regex
-        try:
-            re.compile(pattern)
-        except re.error as e:
-            return f"Invalid regex pattern: {e}"
-
         # Resolve base path
         try:
             base_full = self._resolve_path(path or ".")
@@ -416,10 +409,11 @@ class FilesystemBackend(BackendProtocol):
         if not base_full.exists():
             return []
 
-        # Try ripgrep first
+        # Try ripgrep first (with -F flag for literal search)
         results = self._ripgrep_search(pattern, base_full, glob)
         if results is None:
-            results = self._python_search(pattern, base_full, glob)
+            # Python fallback needs escaped pattern for literal search
+            results = self._python_search(re.escape(pattern), base_full, glob)
 
         matches: list[GrepMatch] = []
         for fpath, items in results.items():
@@ -428,10 +422,10 @@ class FilesystemBackend(BackendProtocol):
         return matches
 
     def _ripgrep_search(self, pattern: str, base_full: Path, include_glob: str | None) -> dict[str, list[tuple[int, str]]] | None:
-        """Search using ripgrep with JSON output parsing.
+        """Search using ripgrep with fixed-string (literal) mode.
 
         Args:
-            pattern: Regex pattern to search for.
+            pattern: Literal string to search for (unescaped).
             base_full: Resolved base path to search in.
             include_glob: Optional glob pattern to filter files.
 
@@ -439,7 +433,7 @@ class FilesystemBackend(BackendProtocol):
             Dict mapping file paths to list of `(line_number, line_text)` tuples.
                 Returns `None` if ripgrep is unavailable or times out.
         """
-        cmd = ["rg", "--json"]
+        cmd = ["rg", "--json", "-F"]  # -F enables fixed-string (literal) mode
         if include_glob:
             cmd.extend(["--glob", include_glob])
         cmd.extend(["--", pattern, str(base_full)])
@@ -484,22 +478,20 @@ class FilesystemBackend(BackendProtocol):
         return results
 
     def _python_search(self, pattern: str, base_full: Path, include_glob: str | None) -> dict[str, list[tuple[int, str]]]:
-        """Fallback search using Python regex when ripgrep is unavailable.
+        """Fallback search using Python when ripgrep is unavailable.
 
         Recursively searches files, respecting `max_file_size_bytes` limit.
 
         Args:
-            pattern: Regex pattern to search for.
+            pattern: Escaped regex pattern (from re.escape) for literal search.
             base_full: Resolved base path to search in.
             include_glob: Optional glob pattern to filter files by name.
 
         Returns:
             Dict mapping file paths to list of `(line_number, line_text)` tuples.
         """
-        try:
-            regex = re.compile(pattern)
-        except re.error:
-            return {}
+        # Compile escaped pattern once for efficiency (used in loop)
+        regex = re.compile(pattern)
 
         results: dict[str, list[tuple[int, str]]] = {}
         root = base_full if base_full.is_dir() else base_full.parent

deepagents/backends/local_shell.py

@@ -0,0 +1,305 @@
+"""`LocalShellBackend`: Filesystem backend with unrestricted local shell execution.
+
+This backend extends FilesystemBackend to add shell command execution on the local
+host system. It provides NO sandboxing or isolation - all operations run directly
+on the host machine with full system access.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import uuid
+from typing import TYPE_CHECKING
+
+from deepagents.backends.filesystem import FilesystemBackend
+from deepagents.backends.protocol import ExecuteResponse, SandboxBackendProtocol
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class LocalShellBackend(FilesystemBackend, SandboxBackendProtocol):
+    """Filesystem backend with unrestricted local shell command execution.
+
+    This backend extends `FilesystemBackend` to add shell command execution
+    capabilities. Commands are executed directly on the host system without any
+    sandboxing, process isolation, or security restrictions.
+
+    !!! warning "Security Warning"
+
+        This backend grants agents BOTH direct filesystem access AND unrestricted
+        shell execution on your local machine. Use with extreme caution and only in
+        appropriate environments.
+
+        **Appropriate use cases:**
+
+        - Local development CLIs (coding assistants, development tools)
+        - Personal development environments where you trust the agent's code
+        - CI/CD pipelines with proper secret management (see security considerations)
+
+        **Inappropriate use cases:**
+
+        - Production environments (e.g., web servers, APIs, multi-tenant systems)
+        - Processing untrusted user input or executing untrusted code
+
+        Use `StateBackend`, `StoreBackend`, or extend `BaseSandbox` for production.
+
+        **Security risks:**
+
+        - Agents can execute **arbitrary shell commands** with your user's permissions
+        - Agents can read **any accessible file**, including secrets (API keys,
+            credentials, `.env` files, SSH keys, etc.)
+        - Combined with network tools, secrets may be exfiltrated via SSRF attacks
+        - File modifications and command execution are **permanent and irreversible**
+        - Agents can install packages, modify system files, spawn processes, etc.
+        - **No process isolation** - commands run directly on your host system
+        - **No resource limits** - commands can consume unlimited CPU, memory, disk
+
+        **Recommended safeguards:**
+
+        Since shell access is unrestricted and can bypass filesystem restrictions:
+
+        1. **Enable Human-in-the-Loop (HITL) middleware** to review and approve ALL
+            operations before execution. This is STRONGLY RECOMMENDED as your primary
+            safeguard when using this backend.
+        2. Run in dedicated development environments only - never on shared or
+            production systems
+        3. Never expose to untrusted users or allow execution of untrusted code
+        4. For production environments requiring code execution, extend `BaseSandbox`
+            to create a properly isolated backend (Docker containers, VMs, or other
+            sandboxed execution environments)
+
+        !!! note
+
+            `virtual_mode=True` and path-based restrictions provide NO security
+            with shell access enabled, since commands can access any path on the system
+
+    Examples:
+        ```python
+        from deepagents.backends import LocalShellBackend
+
+        # Create backend with explicit environment
+        backend = LocalShellBackend(root_dir="/home/user/project", env={"PATH": "/usr/bin:/bin"})
+
+        # Execute shell commands (runs directly on host)
+        result = backend.execute("ls -la")
+        print(result.output)
+        print(result.exit_code)
+
+        # Use filesystem operations (inherited from FilesystemBackend)
+        content = backend.read("/README.md")
+        backend.write("/output.txt", "Hello world")
+
+        # Inherit all environment variables
+        backend = LocalShellBackend(root_dir="/home/user/project", inherit_env=True)
+        ```
+    """
+
+    def __init__(
+        self,
+        root_dir: str | Path | None = None,
+        *,
+        virtual_mode: bool = False,
+        timeout: float = 120.0,
+        max_output_bytes: int = 100_000,
+        env: dict[str, str] | None = None,
+        inherit_env: bool = False,
+    ) -> None:
+        """Initialize local shell backend with filesystem access.
+
+        Args:
+            root_dir: Working directory for both filesystem operations and shell commands.
+
+                - If not provided, defaults to the current working directory.
+                - Shell commands execute with this as their working directory.
+                - When `virtual_mode=False` (default): Paths are used as-is. Agents can
+                    access any file using absolute paths or `..` sequences.
+                - When `virtual_mode=True`: Acts as a virtual root for filesystem operations.
+                    Useful with `CompositeBackend` to support routing file operations across
+                    different backend implementations. **Note:** This does NOT restrict shell
+                    commands.
+
+            virtual_mode: Enable virtual path mode for filesystem operations.
+
+                When `True`, treats `root_dir` as a virtual root filesystem. All paths
+                are interpreted relative to `root_dir` (e.g., `/file.txt` maps to
+                `{root_dir}/file.txt`). Path traversal (`..`, `~`) is blocked.
+
+                **Primary use case:** Working with `CompositeBackend`, which routes
+                different path prefixes to different backends. Virtual mode allows the
+                CompositeBackend to strip route prefixes and pass normalized paths to
+                each backend, enabling file operations to work correctly across multiple
+                backend implementations.
+
+                **Important:** This only affects filesystem operations. Shell commands
+                executed via `execute()` are NOT restricted and can access any path.
+
+            timeout: Maximum time in seconds to wait for shell command execution.
+                Commands exceeding this timeout will be terminated. Defaults to 120 seconds.
+
+            max_output_bytes: Maximum number of bytes to capture from command output.
+                Output exceeding this limit will be truncated. Defaults to 100,000 bytes.
+
+            env: Environment variables for shell commands. If None, starts with an empty
+                environment (unless `inherit_env=True`).
+
+            inherit_env: Whether to inherit the parent process's environment variables.
+                When False (default), only variables in `env` dict are available.
+                When True, inherits all `os.environ` variables and applies `env` overrides.
+        """
+        # Initialize parent FilesystemBackend
+        super().__init__(
+            root_dir=root_dir,
+            virtual_mode=virtual_mode,
+            max_file_size_mb=10,
+        )
+
+        # Store execution parameters
+        self._timeout = timeout
+        self._max_output_bytes = max_output_bytes
+
+        # Build environment based on inherit_env setting
+        if inherit_env:
+            self._env = os.environ.copy()
+            if env is not None:
+                self._env.update(env)
+        else:
+            self._env = env if env is not None else {}
+
+        # Generate unique sandbox ID
+        self._sandbox_id = f"local-{uuid.uuid4().hex[:8]}"
+
+    @property
+    def id(self) -> str:
+        """Unique identifier for this backend instance.
+
+        Returns:
+            String identifier in format "local-{random_hex}".
+        """
+        return self._sandbox_id
+
+    def execute(
+        self,
+        command: str,
+    ) -> ExecuteResponse:
+        r"""Execute a shell command directly on the host system.
+
+        !!! danger "Unrestricted Execution"
+            Commands are executed directly on your host system using `subprocess.run()`
+            with `shell=True`. There is **no sandboxing, isolation, or security
+            restrictions**. The command runs with your user's full permissions and can:
+
+            - Access any file on the filesystem (regardless of `virtual_mode`)
+            - Execute any program or script
+            - Make network connections
+            - Modify system configuration
+            - Spawn additional processes
+            - Install packages or modify dependencies
+
+            **Always use Human-in-the-Loop (HITL) middleware when using this method.**
+
+        The command is executed using the system shell (`/bin/sh` or equivalent) with
+        the working directory set to the backend's `root_dir`. Stdout and stderr are
+        combined into a single output stream.
+
+        Args:
+            command: Shell command string to execute.
+                Examples: "python script.py", "ls -la", "grep pattern file.txt"
+
+                **Security:** This string is passed directly to the shell. Agents can
+                execute arbitrary commands including pipes, redirects, command
+                substitution, etc.
+
+        Returns:
+            ExecuteResponse containing:
+                - output: Combined stdout and stderr (stderr lines prefixed with [stderr])
+                - exit_code: Process exit code (0 for success, non-zero for failure)
+                - truncated: True if output was truncated due to size limits
+
+        Examples:
+            ```python
+            # Run a simple command
+            result = backend.execute("echo hello")
+            assert result.output == "hello\\n"
+            assert result.exit_code == 0
+
+            # Handle errors
+            result = backend.execute("cat nonexistent.txt")
+            assert result.exit_code != 0
+            assert "[stderr]" in result.output
+
+            # Check for truncation
+            result = backend.execute("cat huge_file.txt")
+            if result.truncated:
+                print("Output was truncated")
+
+            # Commands run in root_dir, but can access any path
+            result = backend.execute("cat /etc/passwd")  # Can read system files!
+            ```
+        """
+        if not command or not isinstance(command, str):
+            return ExecuteResponse(
+                output="Error: Command must be a non-empty string.",
+                exit_code=1,
+                truncated=False,
+            )
+
+        try:
+            result = subprocess.run(  # noqa: S602
+                command,
+                check=False,
+                shell=True,  # Intentional: designed for LLM-controlled shell execution
+                capture_output=True,
+                text=True,
+                timeout=self._timeout,
+                env=self._env,
+                cwd=str(self.cwd),  # Use the root_dir from FilesystemBackend
+            )
+
+            # Combine stdout and stderr
+            # Prefix each stderr line with [stderr] for clear attribution.
+            # Example: "hello\n[stderr] error: file not found"  # noqa: ERA001
+            output_parts = []
+            if result.stdout:
+                output_parts.append(result.stdout)
+            if result.stderr:
+                stderr_lines = result.stderr.strip().split("\n")
+                output_parts.extend(f"[stderr] {line}" for line in stderr_lines)
+
+            output = "\n".join(output_parts) if output_parts else "<no output>"
+
+            # Check for truncation
+            truncated = False
+            if len(output) > self._max_output_bytes:
+                output = output[: self._max_output_bytes]
+                output += f"\n\n... Output truncated at {self._max_output_bytes} bytes."
+                truncated = True
+
+            # Add exit code info if non-zero
+            if result.returncode != 0:
+                output = f"{output.rstrip()}\n\nExit code: {result.returncode}"
+
+            return ExecuteResponse(
+                output=output,
+                exit_code=result.returncode,
+                truncated=truncated,
+            )
+
+        except subprocess.TimeoutExpired:
+            return ExecuteResponse(
+                output=f"Error: Command timed out after {self._timeout:.1f} seconds.",
+                exit_code=124,  # Standard timeout exit code
+                truncated=False,
+            )
+        except Exception as e:  # noqa: BLE001
+            # Broad exception catch is intentional: we want to catch all execution errors
+            # and return a consistent ExecuteResponse rather than propagating exceptions
+            return ExecuteResponse(
+                output=f"Error executing command: {e}",
+                exit_code=1,
+                truncated=False,
+            )
+
+
+__all__ = ["LocalShellBackend"]