deepagents 0.3.7a1__py3-none-any.whl → 0.3.9__py3-none-any.whl

deepagents/backends/filesystem.py

@@ -31,6 +31,39 @@ class FilesystemBackend(BackendProtocol):
     Files are accessed using their actual filesystem paths. Relative paths are
     resolved relative to the current working directory. Content is read/written
     as plain text, and metadata (timestamps) are derived from filesystem stats.
+
+    !!! warning "Security Warning"
+
+        This backend grants agents direct filesystem read/write access. Use with
+        caution and only in appropriate environments.
+
+        **Appropriate use cases:**
+
+        - Local development CLIs (coding assistants, development tools)
+        - CI/CD pipelines (see security considerations below)
+
+        **Inappropriate use cases:**
+
+        - Web servers or HTTP APIs - use `StateBackend`, `StoreBackend`, or
+            `SandboxBackend` instead
+
+        **Security risks:**
+
+        - Agents can read any accessible file, including secrets (API keys,
+            credentials, `.env` files)
+        - Combined with network tools, secrets may be exfiltrated via SSRF attacks
+        - File modifications are permanent and irreversible
+
+        **Recommended safeguards:**
+
+        1. Enable Human-in-the-Loop (HITL) middleware to review sensitive operations
+        2. Exclude secrets from accessible filesystem paths (especially in CI/CD)
+        3. Use `SandboxBackend` for production environments requiring filesystem
+            interaction
+        4. **Always** use `virtual_mode=True` with `root_dir` to enable path-based
+            access restrictions (blocks `..`, `~`, and absolute paths outside root).
+            Note that the default (`virtual_mode=False`) provides no security even with
+            `root_dir` set.
     """
 
     def __init__(
@@ -44,14 +77,29 @@ class FilesystemBackend(BackendProtocol):
         Args:
             root_dir: Optional root directory for file operations.
 
-                If provided, all file paths will be resolved relative to this directory.
-                If not provided, uses the current working directory.
-            virtual_mode: Enables sandboxed operation where all paths are treated as
-                virtual paths rooted at `root_dir`.
+                - If not provided, defaults to the current working directory.
+                - When `virtual_mode=False` (default): Only affects relative path
+                    resolution. Provides **no security** - agents can access any file
+                    using absolute paths or `..` sequences.
+                - When `virtual_mode=True`: All paths are restricted to this
+                    directory with traversal protection enabled.
+
+            virtual_mode: Enable path-based access restrictions.
+
+                When `True`, all paths are treated as virtual paths anchored to
+                `root_dir`. Path traversal (`..`, `~`) is blocked and all resolved paths
+                are verified to remain within `root_dir`.
+
+                When `False` (default), **no security is provided**:
+
+                - Absolute paths (e.g., `/etc/passwd`) bypass `root_dir` entirely
+                - Relative paths with `..` can escape `root_dir`
+                - Agents have unrestricted filesystem access
+
+                **Security note:** `virtual_mode=True` provides path-based access
+                control, not process isolation. It restricts which files can be
+                accessed via paths, but does not sandbox the Python process itself.
 
-                Path traversal (using `..` or `~`) is disallowed and all resolved paths
-                must remain within the root directory. When `False` (default), absolute
-                paths are allowed as-is and relative paths resolve under cwd.
             max_file_size_mb: Maximum file size in megabytes for operations like
                 grep's Python fallback search.
 

deepagents/backends/sandbox.py

@@ -46,12 +46,32 @@ for m in matches:
     print(json.dumps(result))
 " 2>/dev/null"""
 
+# Use heredoc to pass content via stdin to avoid ARG_MAX limits on large files.
+# ARG_MAX limits the total size of command-line arguments.
+# Previously, base64-encoded content was interpolated directly into the command
+# string, which would fail for files larger than ~100KB after base64 expansion.
+# Heredocs bypass this by passing data through stdin rather than as arguments.
+# Stdin format: first line is base64-encoded file path, second line is base64-encoded content.
 _WRITE_COMMAND_TEMPLATE = """python3 -c "
 import os
 import sys
 import base64
+import json
 
-file_path = '{file_path}'
+# Read JSON payload from stdin containing file_path and content (both base64-encoded)
+payload_b64 = sys.stdin.read().strip()
+if not payload_b64:
+    print('Error: No payload received for write operation', file=sys.stderr)
+    sys.exit(1)
+
+try:
+    payload = base64.b64decode(payload_b64).decode('utf-8')
+    data = json.loads(payload)
+    file_path = data['path']
+    content = base64.b64decode(data['content']).decode('utf-8')
+except Exception as e:
+    print(f'Error: Failed to decode write payload: {e}', file=sys.stderr)
+    sys.exit(1)
 
 # Check if file already exists (atomic with write)
 if os.path.exists(file_path):
@@ -62,24 +82,46 @@ if os.path.exists(file_path):
 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"""
-
+" <<'__DEEPAGENTS_EOF__'
+{payload_b64}
+__DEEPAGENTS_EOF__"""
+
+# Use heredoc to pass edit parameters via stdin to avoid ARG_MAX limits.
+# Stdin format: base64-encoded JSON with {"path": str, "old": str, "new": str}.
+# JSON bundles all parameters; base64 ensures safe transport of arbitrary content
+# (special chars, newlines, etc.) through the heredoc without escaping issues.
 _EDIT_COMMAND_TEMPLATE = """python3 -c "
 import sys
 import base64
+import json
+import os
+
+# Read and decode JSON payload from stdin
+payload_b64 = sys.stdin.read().strip()
+if not payload_b64:
+    print('Error: No payload received for edit operation', file=sys.stderr)
+    sys.exit(4)
+
+try:
+    payload = base64.b64decode(payload_b64).decode('utf-8')
+    data = json.loads(payload)
+    file_path = data['path']
+    old = data['old']
+    new = data['new']
+except Exception as e:
+    print(f'Error: Failed to decode edit payload: {e}', file=sys.stderr)
+    sys.exit(4)
+
+# Check if file exists
+if not os.path.isfile(file_path):
+    sys.exit(3)  # File not found
 
 # Read file content
-with open('{file_path}', 'r') as f:
+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)
 
@@ -96,11 +138,13 @@ else:
     result = text.replace(old, new, 1)
 
 # Write back to file
-with open('{file_path}', 'w') as f:
+with open(file_path, 'w') as f:
     f.write(result)
 
 print(count)
-" 2>&1"""
+" <<'__DEEPAGENTS_EOF__'
+{payload_b64}
+__DEEPAGENTS_EOF__"""
 
 _READ_COMMAND_TEMPLATE = """python3 -c "
 import os
@@ -221,11 +265,14 @@ except PermissionError:
         content: str,
     ) -> WriteResult:
         """Create a new file. Returns WriteResult; error populated on failure."""
-        # Encode content as base64 to avoid any escaping issues
+        # Create JSON payload with file path and base64-encoded content
+        # This avoids shell injection via file_path and ARG_MAX limits on content
         content_b64 = base64.b64encode(content.encode("utf-8")).decode("ascii")
+        payload = json.dumps({"path": file_path, "content": content_b64})
+        payload_b64 = base64.b64encode(payload.encode("utf-8")).decode("ascii")
 
         # Single atomic check + write command
-        cmd = _WRITE_COMMAND_TEMPLATE.format(file_path=file_path, content_b64=content_b64)
+        cmd = _WRITE_COMMAND_TEMPLATE.format(payload_b64=payload_b64)
         result = self.execute(cmd)
 
         # Check for errors (exit code or error message in output)
@@ -244,23 +291,29 @@ except PermissionError:
         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")
+        # Create JSON payload with file path, old string, and new string
+        # This avoids shell injection via file_path and ARG_MAX limits on strings
+        payload = json.dumps({"path": file_path, "old": old_string, "new": new_string})
+        payload_b64 = base64.b64encode(payload.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)
+        cmd = _EDIT_COMMAND_TEMPLATE.format(payload_b64=payload_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.")
+        # Map exit codes to error messages
+        error_messages = {
+            1: f"Error: String not found in file: '{old_string}'",
+            2: f"Error: String '{old_string}' appears multiple times. Use replace_all=True to replace all occurrences.",
+            3: f"Error: File '{file_path}' not found",
+            4: f"Error: Failed to decode edit payload: {output}",
+        }
+        if exit_code in error_messages:
+            return EditResult(error=error_messages[exit_code])
         if exit_code != 0:
-            return EditResult(error=f"Error: File '{file_path}' not found")
+            return EditResult(error=f"Error editing file (exit code {exit_code}): {output or 'Unknown error'}")
 
         count = int(output)
         # External storage - no files_update needed

deepagents/graph.py

@@ -5,7 +5,6 @@ from typing import Any
 
 from langchain.agents import create_agent
 from langchain.agents.middleware import HumanInTheLoopMiddleware, InterruptOnConfig, TodoListMiddleware
-from langchain.agents.middleware.summarization import SummarizationMiddleware
 from langchain.agents.middleware.types import AgentMiddleware
 from langchain.agents.structured_output import ResponseFormat
 from langchain.chat_models import init_chat_model
@@ -26,6 +25,7 @@ from deepagents.middleware.memory import MemoryMiddleware
 from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
 from deepagents.middleware.skills import SkillsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
+from deepagents.middleware.summarization import SummarizationMiddleware
 
 BASE_AGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools."
 
@@ -38,7 +38,7 @@ def get_default_model() -> ChatAnthropic:
     """
     return ChatAnthropic(
         model_name="claude-sonnet-4-5-20250929",
-        max_tokens=20000,
+        max_tokens=20000,  # type: ignore[call-arg]
     )
 
 
@@ -63,11 +63,14 @@ def create_deep_agent(
 ) -> CompiledStateGraph:
     """Create a deep agent.
 
-    Deep agents require a LLM that supports tool calling.
+    !!! warning "Deep agents require a LLM that supports tool calling!"
 
-    This agent will by default have access to a tool to write todos (`write_todos`),
-    seven file and execution tools: `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`,
-    and a tool to call subagents (`task`).
+    By default, this agent has access to the following tools:
+
+    - `write_todos`: manage a todo list
+    - `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`: file operations
+    - `execute`: run shell commands
+    - `task`: 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.
@@ -82,10 +85,14 @@ def create_deep_agent(
 
             In addition to custom tools you provide, deep agents include built-in tools for planning,
             file management, and subagent spawning.
-        system_prompt: The additional instructions the agent should have.
-
-            Will go in the system prompt. Can be a string or a `SystemMessage`.
-        middleware: Additional middleware to apply after standard middleware.
+        system_prompt: Custom system instructions to prepend before the base deep agent
+            prompt.
+
+            If a string, it's concatenated with the base prompt.
+        middleware: Additional middleware to apply after the standard middleware stack
+            (`TodoListMiddleware`, `FilesystemMiddleware`, `SubAgentMiddleware`,
+            `SummarizationMiddleware`, `AnthropicPromptCachingMiddleware`,
+            `PatchToolCallsMiddleware`).
         subagents: The subagents to use.
 
             Each subagent should be a `dict` with the following keys:
@@ -142,9 +149,17 @@ def create_deep_agent(
     ):
         trigger = ("fraction", 0.85)
         keep = ("fraction", 0.10)
+        truncate_args_settings = {
+            "trigger": ("fraction", 0.85),
+            "keep": ("fraction", 0.10),
+        }
     else:
         trigger = ("tokens", 170000)
         keep = ("messages", 6)
+        truncate_args_settings = {
+            "trigger": ("messages", 20),
+            "keep": ("messages", 20),
+        }
 
     # Build middleware stack for subagents (includes skills if provided)
     subagent_middleware: list[AgentMiddleware] = [
@@ -160,9 +175,11 @@ def create_deep_agent(
             FilesystemMiddleware(backend=backend),
             SummarizationMiddleware(
                 model=model,
+                backend=backend,
                 trigger=trigger,
                 keep=keep,
                 trim_tokens_to_summarize=None,
+                truncate_args_settings=truncate_args_settings,
             ),
             AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
             PatchToolCallsMiddleware(),
@@ -190,9 +207,11 @@ def create_deep_agent(
             ),
             SummarizationMiddleware(
                 model=model,
+                backend=backend,
                 trigger=trigger,
                 keep=keep,
                 trim_tokens_to_summarize=None,
+                truncate_args_settings=truncate_args_settings,
             ),
             AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
             PatchToolCallsMiddleware(),

deepagents/middleware/__init__.py

@@ -1,9 +1,10 @@
-"""Middleware for the DeepAgent."""
+"""Middleware for the agent."""
 
 from deepagents.middleware.filesystem import FilesystemMiddleware
 from deepagents.middleware.memory import MemoryMiddleware
 from deepagents.middleware.skills import SkillsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
+from deepagents.middleware.summarization import SummarizationMiddleware
 
 __all__ = [
     "CompiledSubAgent",
@@ -12,4 +13,5 @@ __all__ = [
     "SkillsMiddleware",
     "SubAgent",
     "SubAgentMiddleware",
+    "SummarizationMiddleware",
 ]