filesystem

Check whether a backend class's execute accepts a timeout kwarg.

Older backend packages didn't lower-bound their SDK dependency, so they may not accept the timeout keyword added to SandboxBackendProtocol.

Results are cached per class to avoid repeated introspection overhead.

Format file content with line numbers (cat -n style).

Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2).

Format structured grep matches using existing formatting logic.

Sanitize tool_call_id to prevent path traversal and separator issues.

Replaces dangerous characters (., /, ) with underscores.

Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).

Validate and normalize file path for security.

Ensures paths are safe to use by preventing directory traversal attacks and enforcing consistent formatting. All paths are normalized to use forward slashes and start with a leading slash.

This function is designed for virtual filesystem paths and rejects Windows absolute paths (e.g., C:/..., F:/...) to maintain consistency and prevent path format ambiguity.

Append text to a system message.

Backend that stores files in agent state (ephemeral).

Uses LangGraph's state management and checkpointing. Files persist within a conversation thread but not across threads. State is automatically checkpointed after each agent step.

Special handling: Since LangGraph state must be updated via Command objects (not direct mutation), operations return Command objects instead of None. This is indicated by the uses_state=True flag.

Routes file operations to different backends by path prefix.

Matches paths against route prefixes (longest first) and delegates to the corresponding backend. Unmatched paths use the default backend.

Protocol for pluggable memory backends (single, unified).

Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.

All file data is represented as dicts with the following structure: { "content": list[str], # Lines of text content "created_at": str, # ISO format timestamp "modified_at": str, # ISO format timestamp }

Result from backend edit operations.

Extension of BackendProtocol that adds shell command execution.

Designed for backends running in isolated environments (containers, VMs, remote hosts).

Adds execute()/aexecute() for shell commands and an id property.

See BaseSandbox for a base class that implements all inherited file operations by delegating to execute().

Result from backend write operations.

Data structure for storing file contents with metadata.

State for the filesystem middleware.

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.

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.