protocol

File storage format version.

• 'v1': Legacy format — content stored as list[str] (lines split on \\n), no encoding field.
• 'v2': Current format — content stored as a plain str (UTF-8 text or base64-encoded binary), with an encoding field ("utf-8" or "base64").

Default timeout in seconds for one sync grep phase.

Timeout in seconds for the async grep wrapper.

This gives FilesystemBackend enough headroom to finish the worst-case sync path: ripgrep timeout, then Python fallback timeout.

Standardized error codes for file upload/download operations.

These represent common, recoverable errors that an LLM can understand and potentially fix:

• file_not_found: The requested file doesn't exist (download)
• permission_denied: Access denied for the operation
• is_directory: Attempted to download a directory as a file
• invalid_path: Path syntax is malformed or contains invalid characters

Emit a deprecation warning with caller-controlled stack attribution.

langchain_core.warn_deprecated formats a standard message but hardcodes stacklevel=4 in its internal warnings.warn call. That value targets a decorator-wrapped frame layout; when called directly from a deprecated method's body the warning is attributed one frame too high (above the user's call site). This wrapper captures the formatted upstream warning and re-emits it with an explicit stacklevel, so the warning points at the user's call site.

Result of a single file download operation.

The response is designed to allow partial success in batch operations.

The errors are standardized using FileOperationError literals for certain recoverable conditions for use cases that involve LLMs performing file operations.

Result of a single file upload operation.

The response is designed to allow partial success in batch operations.

The errors are standardized using FileOperationError literals for certain recoverable conditions for use cases that involve LLMs performing file operations.

Structured file listing info.

Minimal contract used across backends. Only path is required. Other fields are best-effort and may be absent depending on backend.

A single match from a grep search.

Data structure for storing file contents with metadata.

Result from backend read operations.

Result from backend write operations.

Result from backend edit operations.

Result from backend ls operations.

Result from backend grep operations.

Result from backend glob operations.

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": str,  # Text content (utf-8) or base64-encoded binary
    "encoding": str,  # "utf-8" for text, "base64" for binary data
    "created_at": str,  # ISO format timestamp
    "modified_at": str,  # ISO format timestamp
}

Result of code execution.

Simplified schema optimized for LLM consumption.

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().