deepagents 0.2.1rc2__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents
-Version: 0.2.1rc2
+Version: 0.2.2
 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.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepagents"
-version = "0.2.1rc2"
+version = "0.2.2"
 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" }
@@ -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.2}/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.2/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.2/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.2}/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.2/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.2/src/deepagents.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents
-Version: 0.2.1rc2
+Version: 0.2.2
 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.2}/src/deepagents.egg-info/SOURCES.txt

@@ -16,7 +16,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"]