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

deepagents-cli/deepagents_cli/agent.py

@@ -0,0 +1,278 @@
+"""Agent management and creation for the CLI."""
+
+import os
+import shutil
+from pathlib import Path
+
+from deepagents import create_deep_agent
+from deepagents.backends import CompositeBackend
+from deepagents.backends.filesystem import FilesystemBackend
+from deepagents.middleware.resumable_shell import ResumableShellToolMiddleware
+from langchain.agents.middleware import HostExecutionPolicy
+from langgraph.checkpoint.memory import InMemorySaver
+
+from .agent_memory import AgentMemoryMiddleware
+from .config import COLORS, config, console, get_default_coding_instructions
+
+
+def list_agents():
+    """List all available agents."""
+    agents_dir = Path.home() / ".deepagents"
+
+    if not agents_dir.exists() or not any(agents_dir.iterdir()):
+        console.print("[yellow]No agents found.[/yellow]")
+        console.print(
+            "[dim]Agents will be created in ~/.deepagents/ when you first use them.[/dim]",
+            style=COLORS["dim"],
+        )
+        return
+
+    console.print("\n[bold]Available Agents:[/bold]\n", style=COLORS["primary"])
+
+    for agent_path in sorted(agents_dir.iterdir()):
+        if agent_path.is_dir():
+            agent_name = agent_path.name
+            agent_md = agent_path / "agent.md"
+
+            if agent_md.exists():
+                console.print(f"  • [bold]{agent_name}[/bold]", style=COLORS["primary"])
+                console.print(f"    {agent_path}", style=COLORS["dim"])
+            else:
+                console.print(
+                    f"  • [bold]{agent_name}[/bold] [dim](incomplete)[/dim]", style=COLORS["tool"]
+                )
+                console.print(f"    {agent_path}", style=COLORS["dim"])
+
+    console.print()
+
+
+def reset_agent(agent_name: str, source_agent: str = None):
+    """Reset an agent to default or copy from another agent."""
+    agents_dir = Path.home() / ".deepagents"
+    agent_dir = agents_dir / agent_name
+
+    if source_agent:
+        source_dir = agents_dir / source_agent
+        source_md = source_dir / "agent.md"
+
+        if not source_md.exists():
+            console.print(
+                f"[bold red]Error:[/bold red] Source agent '{source_agent}' not found or has no agent.md"
+            )
+            return
+
+        source_content = source_md.read_text()
+        action_desc = f"contents of agent '{source_agent}'"
+    else:
+        source_content = get_default_coding_instructions()
+        action_desc = "default"
+
+    if agent_dir.exists():
+        shutil.rmtree(agent_dir)
+        console.print(f"Removed existing agent directory: {agent_dir}", style=COLORS["tool"])
+
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    agent_md = agent_dir / "agent.md"
+    agent_md.write_text(source_content)
+
+    console.print(f"✓ Agent '{agent_name}' reset to {action_desc}", style=COLORS["primary"])
+    console.print(f"Location: {agent_dir}\n", style=COLORS["dim"])
+
+
+def get_system_prompt() -> str:
+    """Get the base system prompt for the agent.
+
+    Returns:
+        The system prompt string (without agent.md content)
+    """
+    return f"""### Current Working Directory
+
+The filesystem backend is currently operating in: `{Path.cwd()}`
+
+### Memory System Reminder
+
+Your long-term memory is stored in /memories/ and persists across sessions.
+
+**IMPORTANT - Check memories before answering:**
+- When asked "what do you know about X?" → Run `ls /memories/` FIRST, then read relevant files
+- When starting a task → Check if you have guides or examples in /memories/
+- At the beginning of new sessions → Consider checking `ls /memories/` to see what context you have
+
+Base your answers on saved knowledge (from /memories/) when available, supplemented by general knowledge.
+
+### Human-in-the-Loop Tool Approval
+
+Some tool calls require user approval before execution. When a tool call is rejected by the user:
+1. Accept their decision immediately - do NOT retry the same command
+2. Explain that you understand they rejected the action
+3. Suggest an alternative approach or ask for clarification
+4. Never attempt the exact same rejected command again
+
+Respect the user's decisions and work with them collaboratively.
+
+### Web Search Tool Usage
+
+When you use the web_search tool:
+1. The tool will return search results with titles, URLs, and content excerpts
+2. You MUST read and process these results, then respond naturally to the user
+3. NEVER show raw JSON or tool results directly to the user
+4. Synthesize the information from multiple sources into a coherent answer
+5. Cite your sources by mentioning page titles or URLs when relevant
+6. If the search doesn't find what you need, explain what you found and ask clarifying questions
+
+The user only sees your text responses - not tool results. Always provide a complete, natural language answer after using web_search.
+
+### Todo List Management
+
+When using the write_todos tool:
+1. Keep the todo list MINIMAL - aim for 3-6 items maximum
+2. Only create todos for complex, multi-step tasks that truly need tracking
+3. Break down work into clear, actionable items without over-fragmenting
+4. For simple tasks (1-2 steps), just do them directly without creating todos
+5. When first creating a todo list for a task, ALWAYS ask the user if the plan looks good before starting work
+   - Create the todos, let them render, then ask: "Does this plan look good?" or similar
+   - Wait for the user's response before marking the first todo as in_progress
+   - If they want changes, adjust the plan accordingly
+6. Update todo status promptly as you complete each item
+
+The todo list is a planning tool - use it judiciously to avoid overwhelming the user with excessive task tracking."""
+
+
+def create_agent_with_config(model, assistant_id: str, tools: list):
+    """Create and configure an agent with the specified model and tools."""
+    shell_middleware = ResumableShellToolMiddleware(
+        workspace_root=os.getcwd(), execution_policy=HostExecutionPolicy()
+    )
+
+    # For long-term memory, point to ~/.deepagents/AGENT_NAME/ with /memories/ prefix
+    agent_dir = Path.home() / ".deepagents" / assistant_id
+    agent_dir.mkdir(parents=True, exist_ok=True)
+    agent_md = agent_dir / "agent.md"
+    if not agent_md.exists():
+        source_content = get_default_coding_instructions()
+        agent_md.write_text(source_content)
+
+    # Long-term backend - rooted at agent directory
+    # This handles both /memories/ files and /agent.md
+    long_term_backend = FilesystemBackend(root_dir=agent_dir, virtual_mode=True)
+
+    # Composite backend: current working directory for default, agent directory for /memories/
+    backend = CompositeBackend(
+        default=FilesystemBackend(), routes={"/memories/": long_term_backend}
+    )
+
+    # Use the same backend for agent memory middleware
+    agent_middleware = [
+        AgentMemoryMiddleware(backend=long_term_backend, memory_path="/memories/"),
+        shell_middleware,
+    ]
+
+    # Get the system prompt
+    system_prompt = get_system_prompt()
+
+    # Helper functions for formatting tool descriptions in HITL prompts
+    def format_write_file_description(tool_call: dict) -> str:
+        """Format write_file tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        file_path = args.get("file_path", "unknown")
+        content = args.get("content", "")
+
+        action = "Overwrite" if os.path.exists(file_path) else "Create"
+        line_count = len(content.splitlines())
+        size = len(content.encode("utf-8"))
+
+        return f"File: {file_path}\nAction: {action} file\nLines: {line_count} · Bytes: {size}"
+
+    def format_edit_file_description(tool_call: dict) -> str:
+        """Format edit_file tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        file_path = args.get("file_path", "unknown")
+        old_string = args.get("old_string", "")
+        new_string = args.get("new_string", "")
+        replace_all = bool(args.get("replace_all", False))
+
+        delta = len(new_string) - len(old_string)
+
+        return (
+            f"File: {file_path}\n"
+            f"Action: Replace text ({'all occurrences' if replace_all else 'single occurrence'})\n"
+            f"Snippet delta: {delta:+} characters"
+        )
+
+    def format_web_search_description(tool_call: dict) -> str:
+        """Format web_search tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        query = args.get("query", "unknown")
+        max_results = args.get("max_results", 5)
+
+        return f"Query: {query}\nMax results: {max_results}\n\n⚠️  This will use Tavily API credits"
+
+    def format_task_description(tool_call: dict) -> str:
+        """Format task (subagent) tool call for approval prompt."""
+        args = tool_call.get("args", {})
+        description = args.get("description", "unknown")
+        prompt = args.get("prompt", "")
+
+        # Truncate prompt if too long
+        prompt_preview = prompt[:300]
+        if len(prompt) > 300:
+            prompt_preview += "..."
+
+        return (
+            f"Task: {description}\n\n"
+            f"Instructions to subagent:\n"
+            f"{'─' * 40}\n"
+            f"{prompt_preview}\n"
+            f"{'─' * 40}\n\n"
+            f"⚠️  Subagent will have access to file operations and shell commands"
+        )
+
+    # Configure human-in-the-loop for potentially destructive tools
+    from langchain.agents.middleware import InterruptOnConfig
+
+    shell_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: (
+            f"Shell Command: {tool_call['args'].get('command', 'N/A')}\n"
+            f"Working Directory: {os.getcwd()}"
+        ),
+    }
+
+    write_file_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_write_file_description(tool_call),
+    }
+
+    edit_file_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_edit_file_description(tool_call),
+    }
+
+    web_search_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_web_search_description(tool_call),
+    }
+
+    task_interrupt_config: InterruptOnConfig = {
+        "allowed_decisions": ["approve", "reject"],
+        "description": lambda tool_call, state, runtime: format_task_description(tool_call),
+    }
+
+    agent = create_deep_agent(
+        model=model,
+        system_prompt=system_prompt,
+        tools=tools,
+        backend=backend,
+        middleware=agent_middleware,
+        interrupt_on={
+            "shell": shell_interrupt_config,
+            "write_file": write_file_interrupt_config,
+            "edit_file": edit_file_interrupt_config,
+            "web_search": web_search_interrupt_config,
+            "task": task_interrupt_config,
+        },
+    ).with_config(config)
+
+    agent.checkpointer = InMemorySaver()
+
+    return agent

deepagents-cli/deepagents_cli/agent_memory.py

@@ -0,0 +1,226 @@
+"""Middleware for loading agent-specific long-term memory into the system prompt."""
+
+from collections.abc import Awaitable, Callable
+from typing import NotRequired
+
+from deepagents.backends.protocol import BackendProtocol
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ModelRequest,
+    ModelResponse,
+)
+
+
+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-cli/deepagents_cli/commands.py

@@ -0,0 +1,89 @@
+"""Command handlers for slash commands and bash execution."""
+
+import subprocess
+from pathlib import Path
+
+from langgraph.checkpoint.memory import InMemorySaver
+
+from .config import COLORS, DEEP_AGENTS_ASCII, console
+from .ui import TokenTracker, show_interactive_help
+
+
+def handle_command(command: str, agent, token_tracker: TokenTracker) -> str | bool:
+    """Handle slash commands. Returns 'exit' to exit, True if handled, False to pass to agent."""
+    cmd = command.lower().strip().lstrip("/")
+
+    if cmd in ["quit", "exit", "q"]:
+        return "exit"
+
+    if cmd == "clear":
+        # Reset agent conversation state
+        agent.checkpointer = InMemorySaver()
+
+        # Reset token tracking to baseline
+        token_tracker.reset()
+
+        # Clear screen and show fresh UI
+        console.clear()
+        console.print(DEEP_AGENTS_ASCII, style=f"bold {COLORS['primary']}")
+        console.print()
+        console.print(
+            "... Fresh start! Screen cleared and conversation reset.", style=COLORS["agent"]
+        )
+        console.print()
+        return True
+
+    if cmd == "help":
+        show_interactive_help()
+        return True
+
+    if cmd == "tokens":
+        token_tracker.display_session()
+        return True
+
+    console.print()
+    console.print(f"[yellow]Unknown command: /{cmd}[/yellow]")
+    console.print("[dim]Type /help for available commands.[/dim]")
+    console.print()
+    return True
+
+    return False
+
+
+def execute_bash_command(command: str) -> bool:
+    """Execute a bash command and display output. Returns True if handled."""
+    cmd = command.strip().lstrip("!")
+
+    if not cmd:
+        return True
+
+    try:
+        console.print()
+        console.print(f"[dim]$ {cmd}[/dim]")
+
+        # Execute the command
+        result = subprocess.run(
+            cmd, check=False, shell=True, capture_output=True, text=True, timeout=30, cwd=Path.cwd()
+        )
+
+        # Display output
+        if result.stdout:
+            console.print(result.stdout, style=COLORS["dim"], markup=False)
+        if result.stderr:
+            console.print(result.stderr, style="red", markup=False)
+
+        # Show return code if non-zero
+        if result.returncode != 0:
+            console.print(f"[dim]Exit code: {result.returncode}[/dim]")
+
+        console.print()
+        return True
+
+    except subprocess.TimeoutExpired:
+        console.print("[red]Command timed out after 30 seconds[/red]")
+        console.print()
+        return True
+    except Exception as e:
+        console.print(f"[red]Error executing command: {e}[/red]")
+        console.print()
+        return True