Backends

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 ch

Backend that stores files in LangGraph's BaseStore (persistent).

Uses LangGraph's Store for persistent, cross-conversation storage. Files are organized via namespaces and persist across all threads.

Backend that reads and writes files directly from the filesystem.

Files are accessed using their actual filesystem paths. Relative paths are resolved relative to the current working directory. Conten

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.

Base sandbox implementation with execute() as the core abstract method.

This class provides default implementations for all protocol methods. File listing, grep, and glob use shell commands via `ex

Extension of BackendProtocol that adds shell command execution.

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

Adds execute()/aexecute() for shell comm

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.

Fil

A glob pattern the shared matcher refuses to compile.

Subclasses ValueError so existing except ValueError handlers keep working. Callers that catch this specific type can label the failure a *pat

Compile a grep include-glob into a matcher with ripgrep-like semantics.

Provides one shared include-glob behavior for every backend so the same grep(..., glob=...) call closely mirrors ripgrep for

Return a bounded, path-safe component for a tool call ID.

Format file content with line numbers.

Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2). Line markers are separated from source content with two spaces so sou

Check if content is empty and return warning message.

Convert current or legacy persisted file content to a string.

Create a FileData object with timestamps.

Update FileData with new content, preserving creation timestamp.

Floor a requested read window at a zero offset and zero lines.

Models occasionally emit degenerate read_file arguments (offset=-1, limit=0). Clamping offset keeps backends from reporting a li

Slice file data to the requested line range without formatting.

The returned ReadResult carries the raw (unformatted) window in file_data; line-number formatting is applied downstream by the midd

Perform string replacement with occurrence validation.

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

Normalize backslash separators to forward slashes for PurePosixPath use.

Backends running on Windows return OS-native paths using backslashes. PurePosixPath treats backslashes as literal filename

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 sla

Return structured grep matches from an in-memory files mapping.

Performs literal text search (not regex).

Returns a GrepResult with matches on success. When max_count is set, at most that many m

Group structured matches into the legacy dict form used by formatters.

Format structured grep matches using existing formatting logic.

Return a hint when a pattern looks like an (unsupported) regex.

grep matches literal text, so regex metacharacters are searched verbatim and silently miss. Callers gate this on a no-match result; t

Maximum raw video payload size accepted by read_file frame extraction.

Marker standing in for lines dropped from the middle of a head/tail preview.

Shared by _message_eviction._create_content_preview and the capture wrapper in backends.sandbox so both emit identical

Classification of a file by extension.