deepagents 0.3.5__py3-none-any.whl → 0.3.7__py3-none-any.whl

deepagents/backends/filesystem.py

@@ -1,11 +1,4 @@
-"""FilesystemBackend: Read and write files directly from the filesystem.
-
-Security and search upgrades:
-- Secure path resolution with root containment when in virtual_mode (sandboxed to cwd)
-- Prevent symlink-following on file I/O using O_NOFOLLOW when available
-- Ripgrep-powered grep with JSON parsing, plus Python fallback with regex
-  and optional glob include filtering, while preserving virtual path behavior
-"""
+"""`FilesystemBackend`: Read and write files directly from the filesystem."""
 
 import json
 import os
@@ -38,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__(
@@ -49,9 +75,35 @@ class FilesystemBackend(BackendProtocol):
         """Initialize filesystem backend.
 
         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.
+            root_dir: Optional root directory for file operations.
+
+                - 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.
+
+            max_file_size_mb: Maximum file size in megabytes for operations like
+                grep's Python fallback search.
+
+                Files exceeding this limit are skipped during search. Defaults to 10 MB.
         """
         self.cwd = Path(root_dir).resolve() if root_dir else Path.cwd()
         self.virtual_mode = virtual_mode
@@ -60,16 +112,22 @@ class FilesystemBackend(BackendProtocol):
     def _resolve_path(self, key: str) -> Path:
         """Resolve a file path with security checks.
 
-        When virtual_mode=True, treat incoming paths as virtual absolute paths under
-        self.cwd, disallow traversal (.., ~) and ensure resolved path stays within root.
-        When virtual_mode=False, preserve legacy behavior: absolute paths are allowed
+        When `virtual_mode=True`, treat incoming paths as virtual absolute paths under
+        `self.cwd`, disallow traversal (`..`, `~`) and ensure resolved path stays within
+        root.
+
+        When `virtual_mode=False`, preserve legacy behavior: absolute paths are allowed
         as-is; relative paths resolve under cwd.
 
         Args:
-            key: File path (absolute, relative, or virtual when virtual_mode=True)
+            key: File path (absolute, relative, or virtual when `virtual_mode=True`).
 
         Returns:
-            Resolved absolute Path object
+            Resolved absolute `Path` object.
+
+        Raises:
+            ValueError: If path traversal is attempted in `virtual_mode` or if the
+                resolved path escapes the root directory.
         """
         if self.virtual_mode:
             vpath = key if key.startswith("/") else "/" + key
@@ -94,8 +152,9 @@ class FilesystemBackend(BackendProtocol):
             path: Absolute directory path to list files from.
 
         Returns:
-            List of FileInfo-like dicts for files and directories directly in the directory.
-            Directories have a trailing / in their path and is_dir=True.
+            List of `FileInfo`-like dicts for files and directories directly in the
+                directory. Directories have a trailing `/` in their path and
+                `is_dir=True`.
         """
         dir_path = self._resolve_path(path)
         if not dir_path.exists() or not dir_path.is_dir():
@@ -242,7 +301,14 @@ class FilesystemBackend(BackendProtocol):
         content: str,
     ) -> WriteResult:
         """Create a new file with content.
-        Returns WriteResult. External storage sets files_update=None.
+
+        Args:
+            file_path: Path where the new file will be created.
+            content: Text content to write to the file.
+
+        Returns:
+            `WriteResult` with path on success, or error message if the file
+                already exists or write fails. External storage sets `files_update=None`.
         """
         resolved_path = self._resolve_path(file_path)
 
@@ -273,7 +339,18 @@ class FilesystemBackend(BackendProtocol):
         replace_all: bool = False,
     ) -> EditResult:
         """Edit a file by replacing string occurrences.
-        Returns EditResult. External storage sets files_update=None.
+
+        Args:
+            file_path: Path to the file to edit.
+            old_string: The text to search for and replace.
+            new_string: The replacement text.
+            replace_all: If `True`, replace all occurrences. If `False` (default),
+                replace only if exactly one occurrence exists.
+
+        Returns:
+            `EditResult` with path and occurrence count on success, or error
+                message if file not found or replacement fails. External storage sets
+                `files_update=None`.
         """
         resolved_path = self._resolve_path(file_path)
 
@@ -311,6 +388,19 @@ class FilesystemBackend(BackendProtocol):
         path: str | None = None,
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
+        """Search for a regex pattern in files.
+
+        Uses ripgrep if available, falling back to Python regex search.
+
+        Args:
+            pattern: Regular expression pattern to search for.
+            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)
@@ -338,6 +428,17 @@ 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.
+
+        Args:
+            pattern: Regex pattern to search for.
+            base_full: Resolved base path to search in.
+            include_glob: Optional glob pattern to filter files.
+
+        Returns:
+            Dict mapping file paths to list of `(line_number, line_text)` tuples.
+                Returns `None` if ripgrep is unavailable or times out.
+        """
         cmd = ["rg", "--json"]
         if include_glob:
             cmd.extend(["--glob", include_glob])
@@ -383,6 +484,18 @@ 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.
+
+        Recursively searches files, respecting `max_file_size_bytes` limit.
+
+        Args:
+            pattern: Regex pattern to search for.
+            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:
@@ -392,7 +505,10 @@ class FilesystemBackend(BackendProtocol):
         root = base_full if base_full.is_dir() else base_full.parent
 
         for fp in root.rglob("*"):
-            if not fp.is_file():
+            try:
+                if not fp.is_file():
+                    continue
+            except (PermissionError, OSError):
                 continue
             if include_glob and not wcglob.globmatch(fp.name, include_glob, flags=wcglob.BRACE):
                 continue
@@ -419,6 +535,16 @@ class FilesystemBackend(BackendProtocol):
         return results
 
     def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern to match files against (e.g., `'*.py'`, `'**/*.txt'`).
+            path: Base directory to search from. Defaults to root (`/`).
+
+        Returns:
+            List of `FileInfo` dicts for matching files, sorted by path. Each dict
+                contains `path`, `is_dir`, `size`, and `modified_at` fields.
+        """
         if pattern.startswith("/"):
             pattern = pattern.lstrip("/")
 
@@ -432,7 +558,7 @@ class FilesystemBackend(BackendProtocol):
             for matched_path in search_path.rglob(pattern):
                 try:
                     is_file = matched_path.is_file()
-                except OSError:
+                except (PermissionError, OSError):
                     continue
                 if not is_file:
                     continue

deepagents/backends/sandbox.py

@@ -172,7 +172,7 @@ try:
     with os.scandir(path) as it:
         for entry in it:
             result = {{
-                'path': entry.name,
+                'path': os.path.join(path, entry.name),
                 'is_dir': entry.is_dir(follow_symlinks=False)
             }}
             print(json.dumps(result))

deepagents/backends/store.py

@@ -279,6 +279,30 @@ class StoreBackend(BackendProtocol):
 
         return format_read_response(file_data, offset, limit)
 
+    async def aread(
+        self,
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000,
+    ) -> str:
+        """Async version of read using native store async methods.
+
+        This avoids sync calls in async context by using store.aget directly.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+        item: Item | None = await store.aget(namespace, file_path)
+
+        if item is None:
+            return f"Error: File '{file_path}' not found"
+
+        try:
+            file_data = self._convert_store_item_to_file_data(item)
+        except ValueError as e:
+            return f"Error: {e}"
+
+        return format_read_response(file_data, offset, limit)
+
     def write(
         self,
         file_path: str,
@@ -301,6 +325,29 @@ class StoreBackend(BackendProtocol):
         store.put(namespace, file_path, store_value)
         return WriteResult(path=file_path, files_update=None)
 
+    async def awrite(
+        self,
+        file_path: str,
+        content: str,
+    ) -> WriteResult:
+        """Async version of write using native store async methods.
+
+        This avoids sync calls in async context by using store.aget/aput directly.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+
+        # Check if file exists using async method
+        existing = await store.aget(namespace, file_path)
+        if existing is not None:
+            return WriteResult(error=f"Cannot write to {file_path} because it already exists. Read and then make an edit, or write to a new path.")
+
+        # Create new file using async method
+        file_data = create_file_data(content)
+        store_value = self._convert_file_data_to_store_value(file_data)
+        await store.aput(namespace, file_path, store_value)
+        return WriteResult(path=file_path, files_update=None)
+
     def edit(
         self,
         file_path: str,
@@ -338,6 +385,44 @@ class StoreBackend(BackendProtocol):
         store.put(namespace, file_path, store_value)
         return EditResult(path=file_path, files_update=None, occurrences=int(occurrences))
 
+    async def aedit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Async version of edit using native store async methods.
+
+        This avoids sync calls in async context by using store.aget/aput directly.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+
+        # Get existing file using async method
+        item = await store.aget(namespace, file_path)
+        if item is None:
+            return EditResult(error=f"Error: File '{file_path}' not found")
+
+        try:
+            file_data = self._convert_store_item_to_file_data(item)
+        except ValueError as e:
+            return EditResult(error=f"Error: {e}")
+
+        content = file_data_to_string(file_data)
+        result = perform_string_replacement(content, old_string, new_string, replace_all)
+
+        if isinstance(result, str):
+            return EditResult(error=result)
+
+        new_content, occurrences = result
+        new_file_data = update_file_data(file_data, new_content)
+
+        # Update file in store using async method
+        store_value = self._convert_file_data_to_store_value(new_file_data)
+        await store.aput(namespace, file_path, store_value)
+        return EditResult(path=file_path, files_update=None, occurrences=int(occurrences))
+
     # Removed legacy grep() convenience to keep lean surface
 
     def grep_raw(

deepagents/backends/utils.py

@@ -12,11 +12,10 @@ from typing import Any, Literal
 
 import wcmatch.glob as wcglob
 
-from deepagents.backends.protocol import FileInfo as _FileInfo
-from deepagents.backends.protocol import GrepMatch as _GrepMatch
+from deepagents.backends.protocol import FileInfo as _FileInfo, GrepMatch as _GrepMatch
 
 EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
-MAX_LINE_LENGTH = 10000
+MAX_LINE_LENGTH = 5000
 LINE_NUMBER_WIDTH = 6
 TOOL_RESULT_TOKEN_LIMIT = 20000  # Same threshold as eviction
 TRUNCATION_GUIDANCE = "... [results truncated, try being more specific with your parameters]"

deepagents/graph.py

@@ -5,13 +5,13 @@ 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
 from langchain_anthropic import ChatAnthropic
 from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
 from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import SystemMessage
 from langchain_core.tools import BaseTool
 from langgraph.cache.base import BaseCache
 from langgraph.graph.state import CompiledStateGraph
@@ -25,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."
 
@@ -37,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]
     )
 
 
@@ -45,7 +46,7 @@ def create_deep_agent(
     model: str | BaseChatModel | None = None,
     tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
     *,
-    system_prompt: str | None = None,
+    system_prompt: str | SystemMessage | None = None,
     middleware: Sequence[AgentMiddleware] = (),
     subagents: list[SubAgent | CompiledSubAgent] | None = None,
     skills: list[str] | None = None,
@@ -62,19 +63,36 @@ def create_deep_agent(
 ) -> CompiledStateGraph:
     """Create a deep agent.
 
-    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.
+    !!! warning "Deep agents require a LLM that supports tool calling!"
+
+    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.
 
     Args:
-        model: The model to use. Defaults to `claude-sonnet-4-5-20250929`.
+        model: The model to use.
+
+            Defaults to `claude-sonnet-4-5-20250929`.
+
+            Use the `provider:model` format (e.g., `openai:gpt-5`) to quickly switch between models.
         tools: The tools the agent should have access to.
-        system_prompt: The additional instructions the agent should have. Will go in
-            the system prompt.
-        middleware: Additional middleware to apply after standard middleware.
+
+            In addition to custom tools you provide, deep agents include built-in tools for planning,
+            file management, and subagent spawning.
+        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:
@@ -93,7 +111,10 @@ def create_deep_agent(
             to the backend's `root_dir`. Later sources override earlier ones for skills with the
             same name (last one wins).
         memory: Optional list of memory file paths (`AGENTS.md` files) to load
-            (e.g., `["/memory/AGENTS.md"]`). Display names are automatically derived from paths.
+            (e.g., `["/memory/AGENTS.md"]`).
+
+            Display names are automatically derived from paths.
+
             Memory is loaded at agent startup and added into the system prompt.
         response_format: A structured output response format to use for the agent.
         context_schema: The schema of the deep agent.
@@ -104,6 +125,10 @@ def create_deep_agent(
             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: Mapping of tool names to interrupt configs.
+
+            Pass to pause agent execution at specified tool calls for human approval or modification.
+
+            Example: `interrupt_on={"edit_file": True}` pauses before every edit.
         debug: Whether to enable debug mode. Passed through to `create_agent`.
         name: The name of the agent. Passed through to `create_agent`.
         cache: The cache to use for the agent. Passed through to `create_agent`.
@@ -124,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] = [
@@ -142,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(),
@@ -172,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(),
@@ -185,9 +222,23 @@ def create_deep_agent(
     if interrupt_on is not None:
         deepagent_middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))
 
+    # Combine system_prompt with BASE_AGENT_PROMPT
+    if system_prompt is None:
+        final_system_prompt: str | SystemMessage = BASE_AGENT_PROMPT
+    elif isinstance(system_prompt, SystemMessage):
+        # SystemMessage: append BASE_AGENT_PROMPT to content_blocks
+        new_content = [
+            *system_prompt.content_blocks,
+            {"type": "text", "text": f"\n\n{BASE_AGENT_PROMPT}"},
+        ]
+        final_system_prompt = SystemMessage(content=new_content)
+    else:
+        # String: simple concatenation
+        final_system_prompt = system_prompt + "\n\n" + BASE_AGENT_PROMPT
+
     return create_agent(
         model,
-        system_prompt=system_prompt + "\n\n" + BASE_AGENT_PROMPT if system_prompt else BASE_AGENT_PROMPT,
+        system_prompt=final_system_prompt,
         tools=tools,
         middleware=deepagent_middleware,
         response_format=response_format,

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",
 ]

deepagents/middleware/_utils.py

@@ -0,0 +1,23 @@
+"""Utility functions for middleware."""
+
+from langchain_core.messages import SystemMessage
+
+
+def append_to_system_message(
+    system_message: SystemMessage | None,
+    text: str,
+) -> SystemMessage:
+    """Append text to a system message.
+
+    Args:
+        system_message: Existing system message or None.
+        text: Text to add to the system message.
+
+    Returns:
+        New SystemMessage with the text appended.
+    """
+    new_content: list[str | dict[str, str]] = list(system_message.content_blocks) if system_message else []
+    if new_content:
+        text = f"\n\n{text}"
+    new_content.append({"type": "text", "text": text})
+    return SystemMessage(content=new_content)