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

deepagents/backends/state.py

@@ -1,44 +1,38 @@
 """StateBackend: Store files in LangGraph agent state (ephemeral)."""
 
-import re
-from typing import Any, Literal, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
-from langchain.tools import ToolRuntime
-
-from langchain_core.messages import ToolMessage
-from langgraph.types import Command
-
-from .utils import (
+from deepagents.backends.protocol import BackendProtocol, EditResult, FileInfo, GrepMatch, WriteResult
+from deepagents.backends.utils import (
+    _glob_search_files,
     create_file_data,
-    update_file_data,
     file_data_to_string,
     format_read_response,
-    perform_string_replacement,
-    _glob_search_files,
     grep_matches_from_files,
+    perform_string_replacement,
+    update_file_data,
 )
-from deepagents.backends.utils import FileInfo, GrepMatch
-from deepagents.backends.protocol import WriteResult, EditResult
 
+if TYPE_CHECKING:
+    from langchain.tools import ToolRuntime
 
-class StateBackend:
+
+class StateBackend(BackendProtocol):
     """Backend that stores files in agent state (ephemeral).
-    
+
     Uses LangGraph's state management and checkpointing. Files persist within
     a conversation thread but not across threads. State is automatically
     checkpointed after each agent step.
-    
+
     Special handling: Since LangGraph state must be updated via Command objects
     (not direct mutation), operations return Command objects instead of None.
     This is indicated by the uses_state=True flag.
     """
-    
+
     def __init__(self, runtime: "ToolRuntime"):
-        """Initialize StateBackend with runtime.
-        
-        Args:"""
+        """Initialize StateBackend with runtime."""
         self.runtime = runtime
-    
+
     def ls_info(self, path: str) -> list[FileInfo]:
         """List files and directories in the specified directory (non-recursive).
 
@@ -62,7 +56,7 @@ class StateBackend:
                 continue
 
             # Get the relative path after the directory
-            relative = k[len(normalized_path):]
+            relative = k[len(normalized_path) :]
 
             # If relative path contains '/', it's in a subdirectory
             if "/" in relative:
@@ -73,35 +67,39 @@ class StateBackend:
 
             # This is a file directly in the current directory
             size = len("\n".join(fd.get("content", [])))
-            infos.append({
-                "path": k,
-                "is_dir": False,
-                "size": int(size),
-                "modified_at": fd.get("modified_at", ""),
-            })
+            infos.append(
+                {
+                    "path": k,
+                    "is_dir": False,
+                    "size": int(size),
+                    "modified_at": fd.get("modified_at", ""),
+                }
+            )
 
         # Add directories to the results
         for subdir in sorted(subdirs):
-            infos.append({
-                "path": subdir,
-                "is_dir": True,
-                "size": 0,
-                "modified_at": "",
-            })
+            infos.append(
+                {
+                    "path": subdir,
+                    "is_dir": True,
+                    "size": 0,
+                    "modified_at": "",
+                }
+            )
 
         infos.sort(key=lambda x: x.get("path", ""))
         return infos
 
     # Removed legacy ls() convenience to keep lean surface
-    
+
     def read(
-        self, 
+        self,
         file_path: str,
         offset: int = 0,
         limit: int = 2000,
     ) -> str:
         """Read file content with line numbers.
-        
+
         Args:
             file_path: Absolute file path
             offset: Line offset to start reading from (0-indexed)
@@ -110,14 +108,14 @@ class StateBackend:
         """
         files = self.runtime.state.get("files", {})
         file_data = files.get(file_path)
-        
+
         if file_data is None:
             return f"Error: File '{file_path}' not found"
-        
+
         return format_read_response(file_data, offset, limit)
-    
+
     def write(
-        self, 
+        self,
         file_path: str,
         content: str,
     ) -> WriteResult:
@@ -125,15 +123,15 @@ class StateBackend:
         Returns WriteResult with files_update to update LangGraph state.
         """
         files = self.runtime.state.get("files", {})
-        
+
         if file_path in files:
             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.")
-        
+
         new_file_data = create_file_data(content)
         return WriteResult(path=file_path, files_update={file_path: new_file_data})
-    
+
     def edit(
-        self, 
+        self,
         file_path: str,
         old_string: str,
         new_string: str,
@@ -144,31 +142,31 @@ class StateBackend:
         """
         files = self.runtime.state.get("files", {})
         file_data = files.get(file_path)
-        
+
         if file_data is None:
             return EditResult(error=f"Error: File '{file_path}' not found")
-        
+
         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)
         return EditResult(path=file_path, files_update={file_path: new_file_data}, occurrences=int(occurrences))
-    
+
     # Removed legacy grep() convenience to keep lean surface
 
     def grep_raw(
         self,
         pattern: str,
         path: str = "/",
-        glob: Optional[str] = None,
+        glob: str | None = None,
     ) -> list[GrepMatch] | str:
         files = self.runtime.state.get("files", {})
         return grep_matches_from_files(files, pattern, path, glob)
-    
+
     def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
         files = self.runtime.state.get("files", {})
         result = _glob_search_files(files, pattern, path)
@@ -179,12 +177,15 @@ class StateBackend:
         for p in paths:
             fd = files.get(p)
             size = len("\n".join(fd.get("content", []))) if fd else 0
-            infos.append({
-                "path": p,
-                "is_dir": False,
-                "size": int(size),
-                "modified_at": fd.get("modified_at", "") if fd else "",
-            })
+            infos.append(
+                {
+                    "path": p,
+                    "is_dir": False,
+                    "size": int(size),
+                    "modified_at": fd.get("modified_at", "") if fd else "",
+                }
+            )
         return infos
 
+
 # Provider classes removed: prefer callables like `lambda rt: StateBackend(rt)`

deepagents/backends/store.py

@@ -1,48 +1,44 @@
 """StoreBackend: Adapter for LangGraph's BaseStore (persistent, cross-thread)."""
 
-import re
-from typing import Any, Optional, TYPE_CHECKING
-
-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 WriteResult, EditResult
 
+from deepagents.backends.protocol import BackendProtocol, EditResult, FileInfo, GrepMatch, WriteResult
 from deepagents.backends.utils import (
+    _glob_search_files,
     create_file_data,
-    update_file_data,
     file_data_to_string,
     format_read_response,
-    perform_string_replacement,
-    _glob_search_files,
     grep_matches_from_files,
+    perform_string_replacement,
+    update_file_data,
 )
-from deepagents.backends.utils import FileInfo, GrepMatch
 
 
-class StoreBackend:
+class StoreBackend(BackendProtocol):
     """Backend that stores files in LangGraph's BaseStore (persistent).
-    
+
     Uses LangGraph's Store for persistent, cross-conversation storage.
     Files are organized via namespaces and persist across all threads.
-    
+
     The namespace can include an optional assistant_id for multi-agent isolation.
     """
+
     def __init__(self, runtime: "ToolRuntime"):
         """Initialize StoreBackend with runtime.
-        
-        Args:"""
-        self.runtime = runtime
 
+        Args:
+        """
+        self.runtime = runtime
 
     def _get_store(self) -> BaseStore:
         """Get the store instance.
-        
+
         Args:Returns:
             BaseStore instance
-        
+
         Raises:
             ValueError: If no store is available or runtime not provided
         """
@@ -51,15 +47,15 @@ class StoreBackend:
             msg = "Store is required but not available in runtime"
             raise ValueError(msg)
         return store
-    
+
     def _get_namespace(self) -> tuple[str, ...]:
         """Get the namespace for store operations.
-        
+
         Preference order:
         1) Use `self.runtime.config` if present (tests pass this explicitly).
         2) Fallback to `langgraph.config.get_config()` if available.
         3) Default to ("filesystem",).
-        
+
         If an assistant_id is available in the config metadata, return
         (assistant_id, "filesystem") to provide per-assistant isolation.
         """
@@ -88,16 +84,16 @@ class StoreBackend:
         if assistant_id:
             return (assistant_id, namespace)
         return (namespace,)
-    
+
     def _convert_store_item_to_file_data(self, store_item: Item) -> dict[str, Any]:
         """Convert a store Item to FileData format.
-        
+
         Args:
             store_item: The store Item containing file data.
-        
+
         Returns:
             FileData dict with content, created_at, and modified_at fields.
-        
+
         Raises:
             ValueError: If required fields are missing or have incorrect types.
         """
@@ -115,13 +111,13 @@ class StoreBackend:
             "created_at": store_item.value["created_at"],
             "modified_at": store_item.value["modified_at"],
         }
-    
+
     def _convert_file_data_to_store_value(self, file_data: dict[str, Any]) -> dict[str, Any]:
         """Convert FileData to a dict suitable for store.put().
-        
+
         Args:
             file_data: The FileData to convert.
-        
+
         Returns:
             Dictionary with content, created_at, and modified_at fields.
         """
@@ -177,7 +173,7 @@ class StoreBackend:
             offset += page_size
 
         return all_items
-    
+
     def ls_info(self, path: str) -> list[FileInfo]:
         """List files and directories in the specified directory (non-recursive).
 
@@ -206,7 +202,7 @@ class StoreBackend:
                 continue
 
             # Get the relative path after the directory
-            relative = str(item.key)[len(normalized_path):]
+            relative = str(item.key)[len(normalized_path) :]
 
             # If relative path contains '/', it's in a subdirectory
             if "/" in relative:
@@ -221,58 +217,62 @@ class StoreBackend:
             except ValueError:
                 continue
             size = len("\n".join(fd.get("content", [])))
-            infos.append({
-                "path": item.key,
-                "is_dir": False,
-                "size": int(size),
-                "modified_at": fd.get("modified_at", ""),
-            })
+            infos.append(
+                {
+                    "path": item.key,
+                    "is_dir": False,
+                    "size": int(size),
+                    "modified_at": fd.get("modified_at", ""),
+                }
+            )
 
         # Add directories to the results
         for subdir in sorted(subdirs):
-            infos.append({
-                "path": subdir,
-                "is_dir": True,
-                "size": 0,
-                "modified_at": "",
-            })
+            infos.append(
+                {
+                    "path": subdir,
+                    "is_dir": True,
+                    "size": 0,
+                    "modified_at": "",
+                }
+            )
 
         infos.sort(key=lambda x: x.get("path", ""))
         return infos
 
     # Removed legacy ls() convenience to keep lean surface
-    
+
     def read(
-        self, 
+        self,
         file_path: str,
         offset: int = 0,
         limit: int = 2000,
     ) -> str:
         """Read file content with line numbers.
-        
+
         Args:
             file_path: Absolute file path
             offset: Line offset to start reading from (0-indexed)limit: Maximum number of lines to read
-        
+
         Returns:
             Formatted file content with line numbers, or error message.
         """
         store = self._get_store()
         namespace = self._get_namespace()
-        item: Optional[Item] = store.get(namespace, file_path)
-        
+        item: Item | None = store.get(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, 
+        self,
         file_path: str,
         content: str,
     ) -> WriteResult:
@@ -281,20 +281,20 @@ class StoreBackend:
         """
         store = self._get_store()
         namespace = self._get_namespace()
-        
+
         # Check if file exists
         existing = store.get(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
         file_data = create_file_data(content)
         store_value = self._convert_file_data_to_store_value(file_data)
         store.put(namespace, file_path, store_value)
         return WriteResult(path=file_path, files_update=None)
-    
+
     def edit(
-        self, 
+        self,
         file_path: str,
         old_string: str,
         new_string: str,
@@ -305,38 +305,38 @@ class StoreBackend:
         """
         store = self._get_store()
         namespace = self._get_namespace()
-        
+
         # Get existing file
         item = store.get(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
         store_value = self._convert_file_data_to_store_value(new_file_data)
         store.put(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(
         self,
         pattern: str,
         path: str = "/",
-        glob: Optional[str] = None,
+        glob: str | None = None,
     ) -> list[GrepMatch] | str:
         store = self._get_store()
         namespace = self._get_namespace()
@@ -348,7 +348,7 @@ class StoreBackend:
             except ValueError:
                 continue
         return grep_matches_from_files(files, pattern, path, glob)
-    
+
     def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
         store = self._get_store()
         namespace = self._get_namespace()
@@ -367,13 +367,12 @@ class StoreBackend:
         for p in paths:
             fd = files.get(p)
             size = len("\n".join(fd.get("content", []))) if fd else 0
-            infos.append({
-                "path": p,
-                "is_dir": False,
-                "size": int(size),
-                "modified_at": fd.get("modified_at", "") if fd else "",
-            })
+            infos.append(
+                {
+                    "path": p,
+                    "is_dir": False,
+                    "size": int(size),
+                    "modified_at": fd.get("modified_at", "") if fd else "",
+                }
+            )
         return infos
-
-
-# Provider classes removed: prefer callables like `lambda rt: StoreBackend(rt)`

deepagents/backends/utils.py

@@ -8,36 +8,22 @@ enable composition without fragile string parsing.
 import re
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any, Literal, TypedDict
+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
+
 EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
 MAX_LINE_LENGTH = 10000
 LINE_NUMBER_WIDTH = 6
 TOOL_RESULT_TOKEN_LIMIT = 20000  # Same threshold as eviction
 TRUNCATION_GUIDANCE = "... [results truncated, try being more specific with your parameters]"
 
-
-class FileInfo(TypedDict, total=False):
-    """Structured file listing info.
-
-    Minimal contract used across backends. Only "path" is required.
-    Other fields are best-effort and may be absent depending on backend.
-    """
-
-    path: str
-    is_dir: bool
-    size: int  # bytes (approx)
-    modified_at: str  # ISO timestamp if known
-
-
-class GrepMatch(TypedDict):
-    """Structured grep match entry."""
-
-    path: str
-    line: int
-    text: str
+# Re-export protocol types for backwards compatibility
+FileInfo = _FileInfo
+GrepMatch = _GrepMatch
 
 
 def sanitize_tool_call_id(tool_call_id: str) -> str:

deepagents/graph.py

@@ -17,7 +17,7 @@ from langgraph.graph.state import CompiledStateGraph
 from langgraph.store.base import BaseStore
 from langgraph.types import Checkpointer
 
-from deepagents.backends.protocol import BackendProtocol, BackendFactory
+from deepagents.backends.protocol import BackendFactory, BackendProtocol
 from deepagents.middleware.filesystem import FilesystemMiddleware
 from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
@@ -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.