sandbox

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.

Maximum size of a binary file returned by read() as base64.

Files exceeding this size return a Binary file exceeds maximum preview size error rather than being base64-encoded in full. Backends overriding read() should import and reuse this constant to stay in sync with the base implementation. Kept in lockstep with the MAX_BINARY_BYTES literal in _READ_COMMAND_TEMPLATE (asserted by test_read_constants_match_template).

Maximum size of rendered text content returned by read().

Pages exceeding this cap are truncated and TRUNCATION_MSG is appended. Mirrors the MAX_OUTPUT_BYTES literal in _READ_COMMAND_TEMPLATE.

Sentinel appended to read() content when MAX_OUTPUT_BYTES is hit.

Result from backend edit operations.

Result of code execution.

Simplified schema optimized for LLM consumption.

Data structure for storing file contents with metadata.

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.

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.

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.

Result from backend glob operations.

A single match from a grep search.

Result from backend grep operations.

Result from backend ls operations.

Result from backend read 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.

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 execute(). Read uses a server-side Python script via execute() for paginated access. Write delegates content transfer to upload_files(). Edit uses a server-side script for small payloads and uploads old/new strings as temp files with a server-side replace for large ones.

Subclasses must implement execute(), upload_files(), download_files(), and the id property.