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

deepagents/middleware/filesystem.py

@@ -20,10 +20,8 @@ from langgraph.types import Command
 from typing_extensions import TypedDict
 
 from deepagents.backends import StateBackend
-
-# Re-export type here for backwards compatibility
-from deepagents.backends.protocol import BACKEND_TYPES as BACKEND_TYPES
 from deepagents.backends.protocol import (
+    BACKEND_TYPES as BACKEND_TYPES,  # Re-export for backwards compatibility
     BackendProtocol,
     EditResult,
     SandboxBackendProtocol,
@@ -35,12 +33,12 @@ from deepagents.backends.utils import (
     sanitize_tool_call_id,
     truncate_if_too_long,
 )
+from deepagents.middleware._utils import append_to_system_message
 
 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 = 500
+DEFAULT_READ_LIMIT = 100
 
 
 class FileData(TypedDict):
@@ -156,27 +154,24 @@ class FilesystemState(AgentState):
     """Files in the filesystem."""
 
 
-LIST_FILES_TOOL_DESCRIPTION = """Lists all files in the filesystem, filtering by directory.
+LIST_FILES_TOOL_DESCRIPTION = """Lists all files in a directory.
 
-Usage:
-- The path parameter must be an absolute path, not a relative path
-- The list_files tool will return a list of all files in the specified directory.
-- This is very useful for exploring the file system and finding the right file to read or edit.
-- You should almost ALWAYS use this tool before using the Read or Edit tools."""
+This is useful for exploring the filesystem and finding the right file to read or edit.
+You should almost ALWAYS use this tool before using the read_file or edit_file tools."""
 
-READ_FILE_TOOL_DESCRIPTION = """Reads a file from the filesystem. You can access any file directly by using this tool.
-Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+READ_FILE_TOOL_DESCRIPTION = """Reads a file from the filesystem.
+
+Assume this tool is able to read all files. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
 
 Usage:
-- The file_path parameter must be an absolute path, not a relative path
-- By default, it reads up to 500 lines starting from the beginning of the file
+- By default, it reads up to 100 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
+- Lines longer than 5,000 characters will be split into multiple lines with continuation markers (e.g., 5.1, 5.2, etc.). When you specify a limit, these continuation lines count towards the limit.
 - 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.
 - If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
 - You should ALWAYS make sure a file has been read before editing it."""
@@ -184,61 +179,46 @@ Usage:
 EDIT_FILE_TOOL_DESCRIPTION = """Performs exact string replacements in files.
 
 Usage:
-- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
-- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
-- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
-- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance."""
+- You must read the file before editing. This tool will error if you attempt an edit without reading the file first.
+- When editing, preserve the exact indentation (tabs/spaces) from the read output. Never include line number prefixes in old_string or new_string.
+- ALWAYS prefer editing existing files over creating new ones.
+- Only use emojis if the user explicitly requests it."""
 
 
 WRITE_FILE_TOOL_DESCRIPTION = """Writes to a new file in the filesystem.
 
 Usage:
-- The file_path parameter must be an absolute path, not a relative path
-- The content parameter must be a string
 - The write_file tool will create the a new file.
-- Prefer to edit existing files over creating new ones when possible."""
-
+- Prefer to edit existing files (with the edit_file tool) over creating new ones when possible.
+"""
 
 GLOB_TOOL_DESCRIPTION = """Find files matching a glob pattern.
 
-Usage:
-- The glob tool finds files by matching patterns with wildcards
-- Supports standard glob patterns: `*` (any characters), `**` (any directories), `?` (single character)
-- Patterns can be absolute (starting with `/`) or relative
-- Returns a list of absolute file paths that match the pattern
+Supports standard glob patterns: `*` (any characters), `**` (any directories), `?` (single character).
+Returns a list of absolute file paths that match the pattern.
 
 Examples:
 - `**/*.py` - Find all Python files
 - `*.txt` - Find all text files in root
 - `/subdir/**/*.md` - Find all markdown files under /subdir"""
 
-GREP_TOOL_DESCRIPTION = """Search for a pattern in files.
+GREP_TOOL_DESCRIPTION = """Search for a text pattern across files.
 
-Usage:
-- The grep tool searches for text patterns across files
-- The pattern parameter is the text to search for (literal string, not regex)
-- The path parameter filters which directory to search in (default is the current working directory)
-- The glob parameter accepts a glob pattern to filter which files to search (e.g., `*.py`)
-- The output_mode parameter controls the output format:
-  - `files_with_matches`: List only file paths containing matches (default)
-  - `content`: Show matching lines with file path and line numbers
-  - `count`: Show count of matches per file
+Searches for literal text (not regex) and returns matching files or content based on output_mode.
 
 Examples:
 - Search all files: `grep(pattern="TODO")`
 - Search Python files only: `grep(pattern="import", glob="*.py")`
 - Show matching lines: `grep(pattern="error", output_mode="content")`"""
 
-EXECUTE_TOOL_DESCRIPTION = """Executes a given command in the sandbox environment with proper handling and security measures.
+EXECUTE_TOOL_DESCRIPTION = """Executes a shell command in an isolated sandbox environment.
 
+Usage:
+Executes a given command in the sandbox environment with proper handling and security measures.
 Before executing the command, please follow these steps:
-
 1. Directory Verification:
    - If the command will create new directories or files, first use the ls tool to verify the parent directory exists and is the correct location
    - For example, before running "mkdir foo/bar", first use ls to check that "foo" exists and is the intended parent directory
-
 2. Command Execution:
    - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
    - Examples of proper quoting:
@@ -248,9 +228,7 @@ Before executing the command, please follow these steps:
      - python /path/with spaces/script.py (incorrect - will fail)
    - After ensuring proper quoting, execute the command
    - Capture the output of the command
-
 Usage notes:
-  - The command parameter is required
   - Commands run in an isolated sandbox environment
   - Returns combined stdout/stderr output with exit code
   - If the output is very large, it may be truncated
@@ -325,7 +303,10 @@ def _ls_tool_generator(
     """
     tool_description = custom_description or LIST_FILES_TOOL_DESCRIPTION
 
-    def sync_ls(runtime: ToolRuntime[None, FilesystemState], path: str) -> str:
+    def sync_ls(
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Absolute path to the directory to list. Must be absolute, not relative."],
+    ) -> str:
         """Synchronous wrapper for ls tool."""
         resolved_backend = _get_backend(backend, runtime)
         validated_path = _validate_path(path)
@@ -334,7 +315,10 @@ def _ls_tool_generator(
         result = truncate_if_too_long(paths)
         return str(result)
 
-    async def async_ls(runtime: ToolRuntime[None, FilesystemState], path: str) -> str:
+    async def async_ls(
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Absolute path to the directory to list. Must be absolute, not relative."],
+    ) -> str:
         """Asynchronous wrapper for ls tool."""
         resolved_backend = _get_backend(backend, runtime)
         validated_path = _validate_path(path)
@@ -367,26 +351,40 @@ def _read_file_tool_generator(
     tool_description = custom_description or READ_FILE_TOOL_DESCRIPTION
 
     def sync_read_file(
-        file_path: str,
+        file_path: Annotated[str, "Absolute path to the file to read. Must be absolute, not relative."],
         runtime: ToolRuntime[None, FilesystemState],
-        offset: int = DEFAULT_READ_OFFSET,
-        limit: int = DEFAULT_READ_LIMIT,
+        offset: Annotated[int, "Line number to start reading from (0-indexed). Use for pagination of large files."] = DEFAULT_READ_OFFSET,
+        limit: Annotated[int, "Maximum number of lines to read. Use for pagination of large files."] = DEFAULT_READ_LIMIT,
     ) -> str:
         """Synchronous wrapper for read_file tool."""
         resolved_backend = _get_backend(backend, runtime)
         file_path = _validate_path(file_path)
-        return resolved_backend.read(file_path, offset=offset, limit=limit)
+        result = resolved_backend.read(file_path, offset=offset, limit=limit)
+
+        lines = result.splitlines(keepends=True)
+        if len(lines) > limit:
+            lines = lines[:limit]
+            result = "".join(lines)
+
+        return result
 
     async def async_read_file(
-        file_path: str,
+        file_path: Annotated[str, "Absolute path to the file to read. Must be absolute, not relative."],
         runtime: ToolRuntime[None, FilesystemState],
-        offset: int = DEFAULT_READ_OFFSET,
-        limit: int = DEFAULT_READ_LIMIT,
+        offset: Annotated[int, "Line number to start reading from (0-indexed). Use for pagination of large files."] = DEFAULT_READ_OFFSET,
+        limit: Annotated[int, "Maximum number of lines to read. Use for pagination of large files."] = DEFAULT_READ_LIMIT,
     ) -> str:
         """Asynchronous wrapper for read_file tool."""
         resolved_backend = _get_backend(backend, runtime)
         file_path = _validate_path(file_path)
-        return await resolved_backend.aread(file_path, offset=offset, limit=limit)
+        result = await resolved_backend.aread(file_path, offset=offset, limit=limit)
+
+        lines = result.splitlines(keepends=True)
+        if len(lines) > limit:
+            lines = lines[:limit]
+            result = "".join(lines)
+
+        return result
 
     return StructuredTool.from_function(
         name="read_file",
@@ -412,8 +410,8 @@ def _write_file_tool_generator(
     tool_description = custom_description or WRITE_FILE_TOOL_DESCRIPTION
 
     def sync_write_file(
-        file_path: str,
-        content: str,
+        file_path: Annotated[str, "Absolute path where the file should be created. Must be absolute, not relative."],
+        content: Annotated[str, "The text content to write to the file. This parameter is required."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> Command | str:
         """Synchronous wrapper for write_file tool."""
@@ -438,8 +436,8 @@ def _write_file_tool_generator(
         return f"Updated file {res.path}"
 
     async def async_write_file(
-        file_path: str,
-        content: str,
+        file_path: Annotated[str, "Absolute path where the file should be created. Must be absolute, not relative."],
+        content: Annotated[str, "The text content to write to the file. This parameter is required."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> Command | str:
         """Asynchronous wrapper for write_file tool."""
@@ -487,12 +485,12 @@ def _edit_file_tool_generator(
     tool_description = custom_description or EDIT_FILE_TOOL_DESCRIPTION
 
     def sync_edit_file(
-        file_path: str,
-        old_string: str,
-        new_string: str,
+        file_path: Annotated[str, "Absolute path to the file to edit. Must be absolute, not relative."],
+        old_string: Annotated[str, "The exact text to find and replace. Must be unique in the file unless replace_all is True."],
+        new_string: Annotated[str, "The text to replace old_string with. Must be different from old_string."],
         runtime: ToolRuntime[None, FilesystemState],
         *,
-        replace_all: bool = False,
+        replace_all: Annotated[bool, "If True, replace all occurrences of old_string. If False (default), old_string must be unique."] = False,
     ) -> Command | str:
         """Synchronous wrapper for edit_file tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -515,12 +513,12 @@ def _edit_file_tool_generator(
         return f"Successfully replaced {res.occurrences} instance(s) of the string in '{res.path}'"
 
     async def async_edit_file(
-        file_path: str,
-        old_string: str,
-        new_string: str,
+        file_path: Annotated[str, "Absolute path to the file to edit. Must be absolute, not relative."],
+        old_string: Annotated[str, "The exact text to find and replace. Must be unique in the file unless replace_all is True."],
+        new_string: Annotated[str, "The text to replace old_string with. Must be different from old_string."],
         runtime: ToolRuntime[None, FilesystemState],
         *,
-        replace_all: bool = False,
+        replace_all: Annotated[bool, "If True, replace all occurrences of old_string. If False (default), old_string must be unique."] = False,
     ) -> Command | str:
         """Asynchronous wrapper for edit_file tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -565,7 +563,11 @@ def _glob_tool_generator(
     """
     tool_description = custom_description or GLOB_TOOL_DESCRIPTION
 
-    def sync_glob(pattern: str, runtime: ToolRuntime[None, FilesystemState], path: str = "/") -> str:
+    def sync_glob(
+        pattern: Annotated[str, "Glob pattern to match files (e.g., '**/*.py', '*.txt', '/subdir/**/*.md')."],
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Base directory to search from. Defaults to root '/'."] = "/",
+    ) -> str:
         """Synchronous wrapper for glob tool."""
         resolved_backend = _get_backend(backend, runtime)
         infos = resolved_backend.glob_info(pattern, path=path)
@@ -573,7 +575,11 @@ def _glob_tool_generator(
         result = truncate_if_too_long(paths)
         return str(result)
 
-    async def async_glob(pattern: str, runtime: ToolRuntime[None, FilesystemState], path: str = "/") -> str:
+    async def async_glob(
+        pattern: Annotated[str, "Glob pattern to match files (e.g., '**/*.py', '*.txt', '/subdir/**/*.md')."],
+        runtime: ToolRuntime[None, FilesystemState],
+        path: Annotated[str, "Base directory to search from. Defaults to root '/'."] = "/",
+    ) -> str:
         """Asynchronous wrapper for glob tool."""
         resolved_backend = _get_backend(backend, runtime)
         infos = await resolved_backend.aglob_info(pattern, path=path)
@@ -605,11 +611,14 @@ def _grep_tool_generator(
     tool_description = custom_description or GREP_TOOL_DESCRIPTION
 
     def sync_grep(
-        pattern: str,
+        pattern: Annotated[str, "Text pattern to search for (literal string, not regex)."],
         runtime: ToolRuntime[None, FilesystemState],
-        path: str | None = None,
-        glob: str | None = None,
-        output_mode: Literal["files_with_matches", "content", "count"] = "files_with_matches",
+        path: Annotated[str | None, "Directory to search in. Defaults to current working directory."] = None,
+        glob: Annotated[str | None, "Glob pattern to filter which files to search (e.g., '*.py')."] = None,
+        output_mode: Annotated[
+            Literal["files_with_matches", "content", "count"],
+            "Output format: 'files_with_matches' (file paths only, default), 'content' (matching lines with context), 'count' (match counts per file).",
+        ] = "files_with_matches",
     ) -> str:
         """Synchronous wrapper for grep tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -620,11 +629,14 @@ def _grep_tool_generator(
         return truncate_if_too_long(formatted)  # type: ignore[arg-type]
 
     async def async_grep(
-        pattern: str,
+        pattern: Annotated[str, "Text pattern to search for (literal string, not regex)."],
         runtime: ToolRuntime[None, FilesystemState],
-        path: str | None = None,
-        glob: str | None = None,
-        output_mode: Literal["files_with_matches", "content", "count"] = "files_with_matches",
+        path: Annotated[str | None, "Directory to search in. Defaults to current working directory."] = None,
+        glob: Annotated[str | None, "Glob pattern to filter which files to search (e.g., '*.py')."] = None,
+        output_mode: Annotated[
+            Literal["files_with_matches", "content", "count"],
+            "Output format: 'files_with_matches' (file paths only, default), 'content' (matching lines with context), 'count' (match counts per file).",
+        ] = "files_with_matches",
     ) -> str:
         """Asynchronous wrapper for grep tool."""
         resolved_backend = _get_backend(backend, runtime)
@@ -681,7 +693,7 @@ def _execute_tool_generator(
     tool_description = custom_description or EXECUTE_TOOL_DESCRIPTION
 
     def sync_execute(
-        command: str,
+        command: Annotated[str, "Shell command to execute in the sandbox environment."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> str:
         """Synchronous wrapper for execute tool."""
@@ -714,7 +726,7 @@ def _execute_tool_generator(
         return "".join(parts)
 
     async def async_execute(
-        command: str,
+        command: Annotated[str, "Shell command to execute in the sandbox environment."],
         runtime: ToolRuntime[None, FilesystemState],
     ) -> str:
         """Asynchronous wrapper for execute tool."""
@@ -801,21 +813,32 @@ Here are the first 10 lines of the result:
 class FilesystemMiddleware(AgentMiddleware):
     """Middleware for providing filesystem and optional execution tools to an agent.
 
-    This middleware adds filesystem tools to the agent: ls, read_file, write_file,
-    edit_file, glob, and grep. Files can be stored using any backend that implements
-    the BackendProtocol.
+    This middleware adds filesystem tools to the agent: `ls`, `read_file`, `write_file`,
+    `edit_file`, `glob`, and `grep`.
+
+    Files can be stored using any backend that implements the `BackendProtocol`.
 
-    If the backend implements SandboxBackendProtocol, an execute tool is also added
+    If the backend implements `SandboxBackendProtocol`, an `execute` tool is also added
     for running shell commands.
 
+    This middleware also automatically evicts large tool results to the file system when
+    they exceed a token threshold, preventing context window saturation.
+
     Args:
-        backend: Backend for file storage and optional execution. If not provided, defaults to StateBackend
-            (ephemeral storage in agent state). For persistent storage or hybrid setups,
-            use CompositeBackend with custom routes. For execution support, use a backend
-            that implements SandboxBackendProtocol.
+        backend: Backend for file storage and optional execution.
+
+            If not provided, defaults to `StateBackend` (ephemeral storage in agent state).
+
+            For persistent storage or hybrid setups, use `CompositeBackend` with custom routes.
+
+            For execution support, use a backend that implements `SandboxBackendProtocol`.
         system_prompt: Optional custom system prompt override.
         custom_tool_descriptions: Optional custom tool descriptions override.
-        tool_token_limit_before_evict: Optional token limit before evicting a tool result to the filesystem.
+        tool_token_limit_before_evict: Token limit before evicting a tool result to the
+            filesystem.
+
+            When exceeded, writes the result using the configured backend and replaces it
+            with a truncated preview and file reference.
 
     Example:
         ```python
@@ -923,7 +946,8 @@ class FilesystemMiddleware(AgentMiddleware):
             system_prompt = "\n\n".join(prompt_parts)
 
         if system_prompt:
-            request = request.override(system_prompt=request.system_prompt + "\n\n" + system_prompt if request.system_prompt else system_prompt)
+            new_system_message = append_to_system_message(request.system_message, system_prompt)
+            request = request.override(system_message=new_system_message)
 
         return handler(request)
 
@@ -970,7 +994,8 @@ class FilesystemMiddleware(AgentMiddleware):
             system_prompt = "\n\n".join(prompt_parts)
 
         if system_prompt:
-            request = request.override(system_prompt=request.system_prompt + "\n\n" + system_prompt if request.system_prompt else system_prompt)
+            new_system_message = append_to_system_message(request.system_message, system_prompt)
+            request = request.override(system_message=new_system_message)
 
         return await handler(request)
 
@@ -1044,6 +1069,66 @@ class FilesystemMiddleware(AgentMiddleware):
         processed_message = ToolMessage(
             content=replacement_text,
             tool_call_id=message.tool_call_id,
+            name=message.name,
+        )
+        return processed_message, result.files_update
+
+    async def _aprocess_large_message(
+        self,
+        message: ToolMessage,
+        resolved_backend: BackendProtocol,
+    ) -> tuple[ToolMessage, dict[str, FileData] | None]:
+        """Async version of _process_large_message.
+
+        Uses async backend methods to avoid sync calls in async context.
+        See _process_large_message for full documentation.
+        """
+        # Early exit if eviction not configured
+        if not self.tool_token_limit_before_evict:
+            return message, None
+
+        # Convert content to string once for both size check and eviction
+        # Special case: single text block - extract text directly for readability
+        if (
+            isinstance(message.content, list)
+            and len(message.content) == 1
+            and isinstance(message.content[0], dict)
+            and message.content[0].get("type") == "text"
+            and "text" in message.content[0]
+        ):
+            content_str = str(message.content[0]["text"])
+        elif isinstance(message.content, str):
+            content_str = message.content
+        else:
+            # Multiple blocks or non-text content - stringify entire structure
+            content_str = str(message.content)
+
+        # Check if content exceeds eviction threshold
+        # Using 4 chars per token as a conservative approximation (actual ratio varies by content)
+        # This errs on the high side to avoid premature eviction of content that might fit
+        if len(content_str) <= 4 * self.tool_token_limit_before_evict:
+            return message, None
+
+        # Write content to filesystem using async method
+        sanitized_id = sanitize_tool_call_id(message.tool_call_id)
+        file_path = f"/large_tool_results/{sanitized_id}"
+        result = await resolved_backend.awrite(file_path, content_str)
+        if result.error:
+            return message, None
+
+        # Create truncated preview for the replacement message
+        content_sample = format_content_with_line_numbers([line[:1000] for line in content_str.splitlines()[:10]], start_line=1)
+        replacement_text = TOO_LARGE_TOOL_MSG.format(
+            tool_call_id=message.tool_call_id,
+            file_path=file_path,
+            content_sample=content_sample,
+        )
+
+        # Always return as plain string after eviction
+        processed_message = ToolMessage(
+            content=replacement_text,
+            tool_call_id=message.tool_call_id,
+            name=message.name,
         )
         return processed_message, result.files_update
 
@@ -1103,6 +1188,52 @@ class FilesystemMiddleware(AgentMiddleware):
             return Command(update={**update, "messages": processed_messages, "files": accumulated_file_updates})
         raise AssertionError(f"Unreachable code reached in _intercept_large_tool_result: for tool_result of type {type(tool_result)}")
 
+    async def _aintercept_large_tool_result(self, tool_result: ToolMessage | Command, runtime: ToolRuntime) -> ToolMessage | Command:
+        """Async version of _intercept_large_tool_result.
+
+        Uses async backend methods to avoid sync calls in async context.
+        See _intercept_large_tool_result for full documentation.
+        """
+        if isinstance(tool_result, ToolMessage):
+            resolved_backend = self._get_backend(runtime)
+            processed_message, files_update = await self._aprocess_large_message(
+                tool_result,
+                resolved_backend,
+            )
+            return (
+                Command(
+                    update={
+                        "files": files_update,
+                        "messages": [processed_message],
+                    }
+                )
+                if files_update is not None
+                else processed_message
+            )
+
+        if isinstance(tool_result, Command):
+            update = tool_result.update
+            if update is None:
+                return tool_result
+            command_messages = update.get("messages", [])
+            accumulated_file_updates = dict(update.get("files", {}))
+            resolved_backend = self._get_backend(runtime)
+            processed_messages = []
+            for message in command_messages:
+                if not isinstance(message, ToolMessage):
+                    processed_messages.append(message)
+                    continue
+
+                processed_message, files_update = await self._aprocess_large_message(
+                    message,
+                    resolved_backend,
+                )
+                processed_messages.append(processed_message)
+                if files_update is not None:
+                    accumulated_file_updates.update(files_update)
+            return Command(update={**update, "messages": processed_messages, "files": accumulated_file_updates})
+        raise AssertionError(f"Unreachable code reached in _aintercept_large_tool_result: for tool_result of type {type(tool_result)}")
+
     def wrap_tool_call(
         self,
         request: ToolCallRequest,
@@ -1141,4 +1272,4 @@ class FilesystemMiddleware(AgentMiddleware):
             return await handler(request)
 
         tool_result = await handler(request)
-        return self._intercept_large_tool_result(tool_result, request.runtime)
+        return await self._aintercept_large_tool_result(tool_result, request.runtime)

deepagents/middleware/memory.py

@@ -53,7 +53,6 @@ import logging
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Annotated, NotRequired, TypedDict
 
-from langchain.messages import SystemMessage
 from langchain_core.runnables import RunnableConfig
 
 if TYPE_CHECKING:
@@ -69,11 +68,13 @@ from langchain.agents.middleware.types import (
 from langchain.tools import ToolRuntime
 from langgraph.runtime import Runtime
 
+from deepagents.middleware._utils import append_to_system_message
+
 logger = logging.getLogger(__name__)
 
 
 class MemoryState(AgentState):
-    """State schema for MemoryMiddleware.
+    """State schema for `MemoryMiddleware`.
 
     Attributes:
         memory_contents: Dict mapping source paths to their loaded content.
@@ -84,7 +85,7 @@ class MemoryState(AgentState):
 
 
 class MemoryStateUpdate(TypedDict):
-    """State update for MemoryMiddleware."""
+    """State update for `MemoryMiddleware`."""
 
     memory_contents: dict[str, str]
 
@@ -152,14 +153,15 @@ MEMORY_SYSTEM_PROMPT = """<agent_memory>
 
 
 class MemoryMiddleware(AgentMiddleware):
-    """Middleware for loading agent memory from AGENTS.md files.
+    """Middleware for loading agent memory from `AGENTS.md` files.
 
     Loads memory content from configured sources and injects into the system prompt.
+
     Supports multiple sources that are combined together.
 
     Args:
         backend: Backend instance or factory function for file operations.
-        sources: List of MemorySource configurations specifying paths and names.
+        sources: List of `MemorySource` configurations specifying paths and names.
     """
 
     state_schema = MemoryState
@@ -175,9 +177,12 @@ class MemoryMiddleware(AgentMiddleware):
         Args:
             backend: Backend instance or factory function that takes runtime
                      and returns a backend. Use a factory for StateBackend.
-            sources: List of memory file paths to load (e.g., ["~/.deepagents/AGENTS.md",
-                     "./.deepagents/AGENTS.md"]). Display names are automatically derived
-                     from the paths. Sources are loaded in order.
+            sources: List of memory file paths to load (e.g., `["~/.deepagents/AGENTS.md",
+                     "./.deepagents/AGENTS.md"]`).
+
+                     Display names are automatically derived from the paths.
+
+                     Sources are loaded in order.
         """
         self._backend = backend
         self.sources = sources
@@ -354,23 +359,20 @@ class MemoryMiddleware(AgentMiddleware):
         return MemoryStateUpdate(memory_contents=contents)
 
     def modify_request(self, request: ModelRequest) -> ModelRequest:
-        """Inject memory content into the system prompt.
+        """Inject memory content into the system message.
 
         Args:
             request: Model request to modify.
 
         Returns:
-            Modified request with memory injected into system prompt.
+            Modified request with memory injected into system message.
         """
         contents = request.state.get("memory_contents", {})
         agent_memory = self._format_agent_memory(contents)
 
-        if request.system_prompt:
-            system_prompt = agent_memory + "\n\n" + request.system_prompt
-        else:
-            system_prompt = agent_memory
+        new_system_message = append_to_system_message(request.system_message, agent_memory)
 
-        return request.override(system_message=SystemMessage(system_prompt))
+        return request.override(system_message=new_system_message)
 
     def wrap_model_call(
         self,