deepagents 0.2.1rc2__tar.gz → 0.2.3__tar.gz

{deepagents-0.2.1rc2/src/deepagents.egg-info → deepagents-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents
-Version: 0.2.1rc2
+Version: 0.2.3
 Summary: General purpose 'deep agent' with sub-agent spawning, todo list capabilities, and mock file system. Built on LangGraph.
 License: MIT
 Requires-Python: <4.0,>=3.11

{deepagents-0.2.1rc2 → deepagents-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepagents"
-version = "0.2.1rc2"
+version = "0.2.3"
 description = "General purpose 'deep agent' with sub-agent spawning, todo list capabilities, and mock file system. Built on LangGraph."
 readme = "README.md"
 license = { text = "MIT" }
@@ -42,7 +42,7 @@ include = ["deepagents*"]
 "" = "src"
 
 [tool.setuptools.package-data]
-"*" = ["py.typed"]
+"*" = ["py.typed", "*.md"]
 
 [tool.ruff]
 line-length = 150
@@ -93,3 +93,8 @@ enable_error_code = ["deprecated"]
 # Optional: reduce strictness if needed
 disallow_any_generics = false
 warn_return_any = false
+
+[tool.uv.workspace]
+members = [
+    "libs/deepagents-cli",
+]

{deepagents-0.2.1rc2 → deepagents-0.2.3}/src/deepagents/backends/utils.py

@@ -6,10 +6,11 @@ enable composition without fragile string parsing.
 """
 
 import re
-import wcmatch.glob as wcglob
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import Any, Literal, TypedDict, List, Dict
+from typing import Any, Literal, TypedDict
+
+import wcmatch.glob as wcglob
 
 EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
 MAX_LINE_LENGTH = 10000
@@ -24,6 +25,7 @@ class FileInfo(TypedDict, total=False):
     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)
@@ -32,14 +34,15 @@ class FileInfo(TypedDict, total=False):
 
 class GrepMatch(TypedDict):
     """Structured grep match entry."""
+
     path: str
     line: int
     text: str
 
 
 def sanitize_tool_call_id(tool_call_id: str) -> str:
-    """Sanitize tool_call_id to prevent path traversal and separator issues. 
-    
+    r"""Sanitize tool_call_id to prevent path traversal and separator issues.
+
     Replaces dangerous characters (., /, \) with underscores.
     """
     sanitized = tool_call_id.replace(".", "_").replace("/", "_").replace("\\", "_")
@@ -94,10 +97,10 @@ def format_content_with_line_numbers(
 
 def check_empty_content(content: str) -> str | None:
     """Check if content is empty and return warning message.
-    
+
     Args:
         content: Content to check
-    
+
     Returns:
         Warning message if empty, None otherwise
     """
@@ -108,10 +111,10 @@ def check_empty_content(content: str) -> str | None:
 
 def file_data_to_string(file_data: dict[str, Any]) -> str:
     """Convert FileData to plain string content.
-    
+
     Args:
         file_data: FileData dict with 'content' key
-    
+
     Returns:
         Content as string with lines joined by newlines
     """
@@ -164,12 +167,12 @@ def format_read_response(
     limit: int,
 ) -> str:
     """Format file data for read response with line numbers.
-    
+
     Args:
         file_data: FileData dict
         offset: Line offset (0-indexed)
         limit: Maximum number of lines
-    
+
     Returns:
         Formatted content or error message
     """
@@ -177,14 +180,14 @@ def format_read_response(
     empty_msg = check_empty_content(content)
     if empty_msg:
         return empty_msg
-    
+
     lines = content.splitlines()
     start_idx = offset
     end_idx = min(start_idx + limit, len(lines))
-    
+
     if start_idx >= len(lines):
         return f"Error: Line offset {offset} exceeds file length ({len(lines)} lines)"
-    
+
     selected_lines = lines[start_idx:end_idx]
     return format_content_with_line_numbers(selected_lines, start_line=start_idx + 1)
 
@@ -196,24 +199,24 @@ def perform_string_replacement(
     replace_all: bool,
 ) -> tuple[str, int] | str:
     """Perform string replacement with occurrence validation.
-    
+
     Args:
         content: Original content
         old_string: String to replace
         new_string: Replacement string
         replace_all: Whether to replace all occurrences
-    
+
     Returns:
         Tuple of (new_content, occurrences) on success, or error message string
     """
     occurrences = content.count(old_string)
-    
+
     if occurrences == 0:
         return f"Error: String not found in file: '{old_string}'"
-    
+
     if occurrences > 1 and not replace_all:
         return f"Error: String '{old_string}' appears {occurrences} times in file. Use replace_all=True to replace all instances, or provide a more specific string with surrounding context."
-    
+
     new_content = content.replace(old_string, new_string)
     return new_content, occurrences
 
@@ -225,33 +228,33 @@ def truncate_if_too_long(result: list[str] | str) -> list[str] | str:
         if total_chars > TOOL_RESULT_TOKEN_LIMIT * 4:
             return result[: len(result) * TOOL_RESULT_TOKEN_LIMIT * 4 // total_chars] + [TRUNCATION_GUIDANCE]
         return result
-    else:  # string
-        if len(result) > TOOL_RESULT_TOKEN_LIMIT * 4:
-            return result[: TOOL_RESULT_TOKEN_LIMIT * 4] + "\n" + TRUNCATION_GUIDANCE
-        return result
+    # string
+    if len(result) > TOOL_RESULT_TOKEN_LIMIT * 4:
+        return result[: TOOL_RESULT_TOKEN_LIMIT * 4] + "\n" + TRUNCATION_GUIDANCE
+    return result
 
 
 def _validate_path(path: str | None) -> str:
     """Validate and normalize a path.
-    
+
     Args:
         path: Path to validate
-    
+
     Returns:
         Normalized path starting with /
-    
+
     Raises:
         ValueError: If path is invalid
     """
     path = path or "/"
     if not path or path.strip() == "":
         raise ValueError("Path cannot be empty")
-    
+
     normalized = path if path.startswith("/") else "/" + path
-    
+
     if not normalized.endswith("/"):
         normalized += "/"
-    
+
     return normalized
 
 
@@ -261,16 +264,16 @@ def _glob_search_files(
     path: str = "/",
 ) -> str:
     """Search files dict for paths matching glob pattern.
-    
+
     Args:
         files: Dictionary of file paths to FileData.
         pattern: Glob pattern (e.g., "*.py", "**/*.ts").
         path: Base path to search from.
-    
+
     Returns:
         Newline-separated file paths, sorted by modification time (most recent first).
         Returns "No files found" if no matches.
-    
+
     Example:
         ```python
         files = {"/src/main.py": FileData(...), "/test.py": FileData(...)}
@@ -313,29 +316,28 @@ def _format_grep_results(
     output_mode: Literal["files_with_matches", "content", "count"],
 ) -> str:
     """Format grep search results based on output mode.
-    
+
     Args:
         results: Dictionary mapping file paths to list of (line_num, line_content) tuples
         output_mode: Output format - "files_with_matches", "content", or "count"
-    
+
     Returns:
         Formatted string output
     """
     if output_mode == "files_with_matches":
         return "\n".join(sorted(results.keys()))
-    elif output_mode == "count":
+    if output_mode == "count":
         lines = []
         for file_path in sorted(results.keys()):
             count = len(results[file_path])
             lines.append(f"{file_path}: {count}")
         return "\n".join(lines)
-    else:
-        lines = []
-        for file_path in sorted(results.keys()):
-            lines.append(f"{file_path}:")
-            for line_num, line in results[file_path]:
-                lines.append(f"  {line_num}: {line}")
-        return "\n".join(lines)
+    lines = []
+    for file_path in sorted(results.keys()):
+        lines.append(f"{file_path}:")
+        for line_num, line in results[file_path]:
+            lines.append(f"  {line_num}: {line}")
+    return "\n".join(lines)
 
 
 def _grep_search_files(
@@ -346,17 +348,17 @@ def _grep_search_files(
     output_mode: Literal["files_with_matches", "content", "count"] = "files_with_matches",
 ) -> str:
     """Search file contents for regex pattern.
-    
+
     Args:
         files: Dictionary of file paths to FileData.
         pattern: Regex pattern to search for.
         path: Base path to search from.
         glob: Optional glob pattern to filter files (e.g., "*.py").
         output_mode: Output format - "files_with_matches", "content", or "count".
-    
+
     Returns:
         Formatted search results. Returns "No matches found" if no results.
-    
+
     Example:
         ```python
         files = {"/file.py": FileData(content=["import os", "print('hi')"], ...)}
@@ -394,6 +396,7 @@ def _grep_search_files(
 
 # -------- Structured helpers for composition --------
 
+
 def grep_matches_from_files(
     files: dict[str, Any],
     pattern: str,
@@ -419,11 +422,7 @@ def grep_matches_from_files(
     filtered = {fp: fd for fp, fd in files.items() if fp.startswith(normalized_path)}
 
     if glob:
-        filtered = {
-            fp: fd
-            for fp, fd in filtered.items()
-            if wcglob.globmatch(Path(fp).name, glob, flags=wcglob.BRACE)
-        }
+        filtered = {fp: fd for fp, fd in filtered.items() if wcglob.globmatch(Path(fp).name, glob, flags=wcglob.BRACE)}
 
     matches: list[GrepMatch] = []
     for file_path, file_data in filtered.items():
@@ -433,16 +432,16 @@ def grep_matches_from_files(
     return matches
 
 
-def build_grep_results_dict(matches: List[GrepMatch]) -> Dict[str, list[tuple[int, str]]]:
+def build_grep_results_dict(matches: list[GrepMatch]) -> dict[str, list[tuple[int, str]]]:
     """Group structured matches into the legacy dict form used by formatters."""
-    grouped: Dict[str, list[tuple[int, str]]] = {}
+    grouped: dict[str, list[tuple[int, str]]] = {}
     for m in matches:
         grouped.setdefault(m["path"], []).append((m["line"], m["text"]))
     return grouped
 
 
 def format_grep_matches(
-    matches: List[GrepMatch],
+    matches: list[GrepMatch],
     output_mode: Literal["files_with_matches", "content", "count"],
 ) -> str:
     """Format structured grep matches using existing formatting logic."""

deepagents-0.2.3/src/deepagents/default_agent_prompt.md

@@ -0,0 +1,110 @@
+You are an AI assistant that helps users with various tasks including coding, research, and analysis.
+
+# Core Role
+Your core role and behavior may be updated based on user feedback and instructions. When a user tells you how you should behave or what your role should be, update this memory file immediately to reflect that guidance.
+
+## Memory-First Protocol
+You have access to a persistent memory system. ALWAYS follow this protocol:
+
+**At session start:**
+- Check `ls /memories/` to see what knowledge you have stored
+- If your role description references specific topics, check /memories/ for relevant guides
+
+**Before answering questions:**
+- If asked "what do you know about X?" or "how do I do Y?" → Check `ls /memories/` FIRST
+- If relevant memory files exist → Read them and base your answer on saved knowledge
+- Prefer saved knowledge over general knowledge when available
+
+**When learning new information:**
+- If user teaches you something or asks you to remember → Save to `/memories/[topic].md`
+- Use descriptive filenames: `/memories/deep-agents-guide.md` not `/memories/notes.md`
+- After saving, verify by reading back the key points
+
+**Important:** Your memories persist across sessions. Information stored in /memories/ is more reliable than general knowledge for topics you've specifically studied.
+
+# Tone and Style
+Be concise and direct. Answer in fewer than 4 lines unless the user asks for detail.
+After working on a file, just stop - don't explain what you did unless asked.
+Avoid unnecessary introductions or conclusions.
+
+When you run non-trivial bash commands, briefly explain what they do.
+
+## Proactiveness
+Take action when asked, but don't surprise users with unrequested actions.
+If asked how to approach something, answer first before taking action.
+
+## Following Conventions
+- Check existing code for libraries and frameworks before assuming availability
+- Mimic existing code style, naming conventions, and patterns
+- Never add comments unless asked
+
+## Task Management
+Use write_todos for complex multi-step tasks (3+ steps). Mark tasks in_progress before starting, completed immediately after finishing.
+For simple 1-2 step tasks, just do them without todos.
+
+## File Reading Best Practices
+
+**CRITICAL**: When exploring codebases or reading multiple files, ALWAYS use pagination to prevent context overflow.
+
+**Pattern for codebase exploration:**
+1. First scan: `read_file(path, limit=100)` - See file structure and key sections
+2. Targeted read: `read_file(path, offset=100, limit=200)` - Read specific sections if needed
+3. Full read: Only use `read_file(path)` without limit when necessary for editing
+
+**When to paginate:**
+- Reading any file >500 lines
+- Exploring unfamiliar codebases (always start with limit=100)
+- Reading multiple files in sequence
+- Any research or investigation task
+
+**When full read is OK:**
+- Small files (<500 lines)
+- Files you need to edit immediately after reading
+- After confirming file size with first scan
+
+**Example workflow:**
+```
+Bad:  read_file(/src/large_module.py)  # Floods context with 2000+ lines
+Good: read_file(/src/large_module.py, limit=100)  # Scan structure first
+      read_file(/src/large_module.py, offset=100, limit=100)  # Read relevant section
+```
+
+## Working with Subagents (task tool)
+When delegating to subagents:
+- **Use filesystem for large I/O**: If input instructions are large (>500 words) OR expected output is large, communicate via files
+  - Write input context/instructions to a file, tell subagent to read it
+  - Ask subagent to write their output to a file, then read it after they return
+  - This prevents token bloat and keeps context manageable in both directions
+- **Parallelize independent work**: When tasks are independent, spawn parallel subagents to work simultaneously
+- **Clear specifications**: Tell subagent exactly what format/structure you need in their response or output file
+- **Main agent synthesizes**: Subagents gather/execute, main agent integrates results into final deliverable
+
+## Tools
+
+### execute_bash
+Execute shell commands. Always quote paths with spaces.
+Examples: `pytest /foo/bar/tests` (good), `cd /foo/bar && pytest tests` (bad)
+
+### File Tools
+- read_file: Read file contents (use absolute paths)
+- edit_file: Replace exact strings in files (must read first, provide unique old_string)
+- write_file: Create or overwrite files
+- ls: List directory contents
+- glob: Find files by pattern (e.g., "**/*.py")
+- grep: Search file contents
+
+Always use absolute paths starting with /.
+
+### web_search
+Search for documentation, error solutions, and code examples.
+
+### http_request
+Make HTTP requests to APIs (GET, POST, etc.).
+
+## Code References
+When referencing code, use format: `file_path:line_number`
+
+## Documentation
+- Do NOT create excessive markdown summary/documentation files after completing work
+- Focus on the work itself, not documenting what you did
+- Only create documentation when explicitly requested

{deepagents-0.2.1rc2 → deepagents-0.2.3}/src/deepagents/graph.py

@@ -123,10 +123,10 @@ def create_deep_agent(
         AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
         PatchToolCallsMiddleware(),
     ]
+    if middleware:
+        deepagent_middleware.extend(middleware)
     if interrupt_on is not None:
         deepagent_middleware.append(HumanInTheLoopMiddleware(interrupt_on=interrupt_on))
-    if middleware is not None:
-        deepagent_middleware.extend(middleware)
 
     return create_agent(
         model,

deepagents-0.2.3/src/deepagents/middleware/__init__.py

@@ -0,0 +1,13 @@
+"""Middleware for the DeepAgent."""
+
+from deepagents.middleware.filesystem import FilesystemMiddleware
+from deepagents.middleware.resumable_shell import ResumableShellToolMiddleware
+from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
+
+__all__ = [
+    "CompiledSubAgent",
+    "FilesystemMiddleware",
+    "ResumableShellToolMiddleware",
+    "SubAgent",
+    "SubAgentMiddleware",
+]

deepagents-0.2.3/src/deepagents/middleware/agent_memory.py

@@ -0,0 +1,222 @@
+"""Middleware for loading agent-specific long-term memory into the system prompt."""
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from langgraph.runtime import Runtime
+
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ModelRequest,
+    ModelResponse,
+)
+from typing_extensions import NotRequired, TypedDict
+
+from deepagents.backends.protocol import BackendProtocol
+
+
+class AgentMemoryState(AgentState):
+    """State for the agent memory middleware."""
+
+    agent_memory: NotRequired[str | None]
+    """Long-term memory content for the agent."""
+
+
+AGENT_MEMORY_FILE_PATH = "/agent.md"
+
+# Long-term Memory Documentation
+LONGTERM_MEMORY_SYSTEM_PROMPT = """
+
+## Long-term Memory
+
+You have access to a long-term memory system using the {memory_path} path prefix.
+Files stored in {memory_path} persist across sessions and conversations.
+
+Your system prompt is loaded from {memory_path}agent.md at startup. You can update your own instructions by editing this file.
+
+**When to CHECK/READ memories (CRITICAL - do this FIRST):**
+- **At the start of ANY new session**: Run `ls {memory_path}` to see what you know
+- **BEFORE answering questions**: If asked "what do you know about X?" or "how do I do Y?", check `ls {memory_path}` for relevant files FIRST
+- **When user asks you to do something**: Check if you have guides, examples, or patterns in {memory_path} before proceeding
+- **When user references past work or conversations**: Search {memory_path} for related content
+- **If you're unsure**: Check your memories rather than guessing or using only general knowledge
+
+**Memory-first response pattern:**
+1. User asks a question → Run `ls {memory_path}` to check for relevant files
+2. If relevant files exist → Read them with `read_file {memory_path}[filename]`
+3. Base your answer on saved knowledge (from memories) supplemented by general knowledge
+4. If no relevant memories exist → Use general knowledge, then consider if this is worth saving
+
+**When to update memories:**
+- **IMMEDIATELY when the user describes your role or how you should behave** (e.g., "you are a web researcher", "you are an expert in X")
+- **IMMEDIATELY when the user gives feedback on your work** - Before continuing, update memories to capture what was wrong and how to do it better
+- When the user explicitly asks you to remember something
+- When patterns or preferences emerge (coding styles, conventions, workflows)
+- After significant work where context would help in future sessions
+
+**Learning from feedback:**
+- When user says something is better/worse, capture WHY and encode it as a pattern
+- Each correction is a chance to improve permanently - don't just fix the immediate issue, update your instructions
+- When user says "you should remember X" or "be careful about Y", treat this as HIGH PRIORITY - update memories IMMEDIATELY
+- Look for the underlying principle behind corrections, not just the specific mistake
+- If it's something you "should have remembered", identify where that instruction should live permanently
+
+**What to store where:**
+- **{memory_path}agent.md**: Update this to modify your core instructions and behavioral patterns
+- **Other {memory_path} files**: Use for project-specific context, reference information, or structured notes
+  - If you create additional memory files, add references to them in {memory_path}agent.md so you remember to consult them
+
+The portion of your system prompt that comes from {memory_path}agent.md is marked with `<agent_memory>` tags so you can identify what instructions come from your persistent memory.
+
+Example: `ls {memory_path}` to see what memories you have
+Example: `read_file '{memory_path}deep-agents-guide.md'` to recall saved knowledge
+Example: `edit_file('{memory_path}agent.md', ...)` to update your instructions
+Example: `write_file('{memory_path}project_context.md', ...)` for project-specific notes, then reference it in agent.md
+
+Remember: To interact with the longterm filesystem, you must prefix the filename with the {memory_path} path."""
+
+
+DEFAULT_MEMORY_SNIPPET = """<agent_memory>
+{agent_memory}
+</agent_memory>
+"""
+
+class AgentMemoryMiddleware(AgentMiddleware):
+    """Middleware for loading agent-specific long-term memory.
+
+    This middleware loads the agent's long-term memory from a file (agent.md)
+    and injects it into the system prompt. The memory is loaded once at the
+    start of the conversation and stored in state.
+
+    Args:
+        backend: Backend to use for loading the agent memory file.
+        system_prompt_template: Optional custom template for how to inject
+            the agent memory into the system prompt. Use {agent_memory} as
+            a placeholder. Defaults to a simple section header.
+
+    Example:
+        ```python
+        from deepagents.middleware.agent_memory import AgentMemoryMiddleware
+        from deepagents.memory.backends import FilesystemBackend
+        from pathlib import Path
+
+        # Set up backend pointing to agent's directory
+        agent_dir = Path.home() / ".deepagents" / "my-agent"
+        backend = FilesystemBackend(root_dir=agent_dir)
+        
+        # Create middleware
+        middleware = AgentMemoryMiddleware(backend=backend)
+        ```
+    """
+
+    state_schema = AgentMemoryState
+
+    def __init__(
+        self,
+        *,
+        backend: BackendProtocol,
+        memory_path: str,
+        system_prompt_template: str | None = None,
+    ) -> None:
+        """Initialize the agent memory middleware.
+
+        Args:
+            backend: Backend to use for loading the agent memory file.
+            system_prompt_template: Optional custom template for injecting
+                agent memory into system prompt.
+        """
+        self.backend = backend
+        self.memory_path = memory_path
+        self.system_prompt_template = system_prompt_template or DEFAULT_MEMORY_SNIPPET
+
+    def before_agent(
+        self,
+        state: AgentMemoryState,
+        runtime,
+    ) -> AgentMemoryState:
+        """Load agent memory from file before agent execution.
+
+        Args:
+            state: Current agent state.
+            handler: Handler function to call after loading memory.
+
+        Returns:
+            Updated state with agent_memory populated.
+        """
+        # Only load memory if it hasn't been loaded yet
+        if "agent_memory" not in state or state.get("agent_memory") is None:
+            file_data = self.backend.read(AGENT_MEMORY_FILE_PATH)
+            return {"agent_memory": file_data}
+
+    async def abefore_agent(
+        self,
+        state: AgentMemoryState,
+        runtime,
+    ) -> AgentMemoryState:
+        """(async) Load agent memory from file before agent execution.
+
+        Args:
+            state: Current agent state.
+            handler: Handler function to call after loading memory.
+
+        Returns:
+            Updated state with agent_memory populated.
+        """
+        # Only load memory if it hasn't been loaded yet
+        if "agent_memory" not in state or state.get("agent_memory") is None:
+            file_data = self.backend.read(AGENT_MEMORY_FILE_PATH)
+            return {"agent_memory": file_data}
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        """Inject agent memory into the system prompt.
+
+        Args:
+            request: The model request being processed.
+            handler: The handler function to call with the modified request.
+
+        Returns:
+            The model response from the handler.
+        """
+        # Get agent memory from state
+        agent_memory = request.state.get("agent_memory", "")
+        
+        memory_section = self.system_prompt_template.format(agent_memory=agent_memory)
+        if request.system_prompt:
+            request.system_prompt = memory_section + "\n\n" + request.system_prompt
+        else:
+            request.system_prompt = memory_section
+        request.system_prompt = request.system_prompt + "\n\n" + LONGTERM_MEMORY_SYSTEM_PROMPT.format(memory_path=self.memory_path)
+
+        return handler(request)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelResponse:
+        """(async) Inject agent memory into the system prompt.
+
+        Args:
+            request: The model request being processed.
+            handler: The handler function to call with the modified request.
+
+        Returns:
+            The model response from the handler.
+        """
+        # Get agent memory from state
+        agent_memory = request.state.get("agent_memory", "")
+        
+        memory_section = self.system_prompt_template.format(agent_memory=agent_memory)
+        if request.system_prompt:
+            request.system_prompt = memory_section + "\n\n" + request.system_prompt
+        else:
+            request.system_prompt = memory_section
+        request.system_prompt = request.system_prompt + "\n\n" + LONGTERM_MEMORY_SYSTEM_PROMPT.format(memory_path=self.memory_path)
+
+        return await handler(request)

{deepagents-0.2.1rc2 → deepagents-0.2.3}/src/deepagents/middleware/filesystem.py

@@ -35,7 +35,7 @@ EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"
 MAX_LINE_LENGTH = 2000
 LINE_NUMBER_WIDTH = 6
 DEFAULT_READ_OFFSET = 0
-DEFAULT_READ_LIMIT = 2000
+DEFAULT_READ_LIMIT = 500
 BACKEND_TYPES = (
     BackendProtocol
     | BackendFactory
@@ -155,8 +155,12 @@ Assume this tool is able to read all files on the machine. If the User provides
 
 Usage:
 - The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to 2000 lines starting from the beginning of the file
-- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
+- By default, it reads up to 500 lines starting from the beginning of the file
+- **IMPORTANT for large files and codebase exploration**: Use pagination with offset and limit parameters to avoid context overflow
+  - First scan: read_file(path, limit=100) to see file structure
+  - Read more sections: read_file(path, offset=100, limit=200) for next 200 lines
+  - Only omit limit (read full file) when necessary for editing
+- Specify offset and limit: read_file(path, offset=0, limit=100) reads first 100 lines
 - Any lines longer than 2000 characters will be truncated
 - Results are returned using cat -n format, with line numbers starting at 1
 - You have the capability to call multiple tools in a single response. It is always better to speculatively read multiple files as a batch that are potentially useful.

deepagents-0.2.3/src/deepagents/middleware/resumable_shell.py

@@ -0,0 +1,85 @@
+"""Shell tool middleware that survives HITL pauses."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, cast
+
+from langchain.agents.middleware.shell_tool import (
+    ShellToolMiddleware,
+    _PersistentShellTool,
+    _SessionResources,
+    ShellToolState,
+)
+from langchain.agents.middleware.types import AgentState
+from langchain_core.messages import ToolMessage
+from langchain.tools.tool_node import ToolCallRequest
+from langgraph.types import Command
+
+
+class ResumableShellToolMiddleware(ShellToolMiddleware):
+    """Shell middleware that recreates session resources after human interrupts.
+
+    ``ShellToolMiddleware`` stores its session handle in middleware state using an
+    ``UntrackedValue``. When a run pauses for human approval, that attribute is not
+    checkpointed. Upon resuming, LangGraph restores the state without the shell
+    resources, so the next tool execution fails with
+    ``Shell session resources are unavailable``.
+
+    This subclass lazily recreates the shell session the first time a resumed run
+    touches the shell tool again and only performs shutdown when a session is
+    actually active. This keeps behaviour identical for uninterrupted runs while
+    allowing HITL pauses to succeed.
+    """
+
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command],
+    ) -> ToolMessage | Command:
+        if isinstance(request.tool, _PersistentShellTool):
+            resources = self._get_or_create_resources(request.state)
+            return self._run_shell_tool(
+                resources,
+                request.tool_call["args"],
+                tool_call_id=request.tool_call.get("id"),
+            )
+        return super().wrap_tool_call(request, handler)
+
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
+    ) -> ToolMessage | Command:
+        if isinstance(request.tool, _PersistentShellTool):
+            resources = self._get_or_create_resources(request.state)
+            return self._run_shell_tool(
+                resources,
+                request.tool_call["args"],
+                tool_call_id=request.tool_call.get("id"),
+            )
+        return await super().awrap_tool_call(request, handler)
+
+    def after_agent(self, state: ShellToolState, runtime) -> None:  # type: ignore[override]
+        if self._has_resources(state):
+            super().after_agent(state, runtime)
+
+    async def aafter_agent(self, state: ShellToolState, runtime) -> None:  # type: ignore[override]
+        if self._has_resources(state):
+            await super().aafter_agent(state, runtime)
+
+    @staticmethod
+    def _has_resources(state: AgentState) -> bool:
+        resources = state.get("shell_session_resources")
+        return isinstance(resources, _SessionResources)
+
+    def _get_or_create_resources(self, state: AgentState) -> _SessionResources:
+        resources = state.get("shell_session_resources")
+        if isinstance(resources, _SessionResources):
+            return resources
+
+        new_resources = self._create_resources()
+        cast(dict[str, Any], state)["shell_session_resources"] = new_resources
+        return new_resources
+
+
+__all__ = ["ResumableShellToolMiddleware"]

{deepagents-0.2.1rc2 → deepagents-0.2.3/src/deepagents.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents
-Version: 0.2.1rc2
+Version: 0.2.3
 Summary: General purpose 'deep agent' with sub-agent spawning, todo list capabilities, and mock file system. Built on LangGraph.
 License: MIT
 Requires-Python: <4.0,>=3.11

{deepagents-0.2.1rc2 → deepagents-0.2.3}/src/deepagents.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 src/deepagents/__init__.py
+src/deepagents/default_agent_prompt.md
 src/deepagents/graph.py
 src/deepagents.egg-info/PKG-INFO
 src/deepagents.egg-info/SOURCES.txt
@@ -16,7 +17,9 @@ src/deepagents/backends/state.py
 src/deepagents/backends/store.py
 src/deepagents/backends/utils.py
 src/deepagents/middleware/__init__.py
+src/deepagents/middleware/agent_memory.py
 src/deepagents/middleware/filesystem.py
 src/deepagents/middleware/patch_tool_calls.py
+src/deepagents/middleware/resumable_shell.py
 src/deepagents/middleware/subagents.py
 tests/test_middleware.py

deepagents-0.2.1rc2/src/deepagents/middleware/__init__.py

@@ -1,6 +0,0 @@
-"""Middleware for the DeepAgent."""
-
-from deepagents.middleware.filesystem import FilesystemMiddleware
-from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
-
-__all__ = ["CompiledSubAgent", "FilesystemMiddleware", "SubAgent", "SubAgentMiddleware"]