protocol

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)
• parent_not_found: The parent directory doesn't exist (upload)
• 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

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.

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.

Structured grep match entry.

Result from backend write operations.

Result from backend edit 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": list[str], # Lines of text content "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().