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.
BaseSandbox()Execute a command in the sandbox and return ExecuteResponse.
Structured listing with file metadata using os.scandir.
Read file content with server-side line-based pagination.
Runs a Python script on the sandbox via execute() that reads the
file, detects encoding, and applies offset/limit pagination for text
files. Only the requested page is returned over the wire.
Binary files (non-UTF-8) are returned base64-encoded without pagination.
Create a new file, failing if it already exists.
Runs a small preflight command to check existence and create parent
directories, then transfers content via upload_files().
Edit a file by replacing exact string occurrences.
For small payloads (combined old/new under _EDIT_INLINE_MAX_BYTES),
runs a server-side Python script via execute() — single round-trip,
no file transfer. For larger payloads, uploads old/new strings as
temp files and runs a server-side replace script — the source file
never leaves the sandbox.
Search file contents for a literal string using grep -F.
Structured glob matching returning GlobResult.
Upload multiple files to the sandbox.
Implementations must support partial success - catch exceptions per-file
and return errors in FileUploadResponse objects rather than raising.
Download multiple files from the sandbox.
Implementations must support partial success - catch exceptions per-file
and return errors in FileDownloadResponse objects rather than raising.
Async version of ls.
Async version of read.
Async version of grep.
Async version of glob.
Async version of write.
Async version of edit.
Async version of upload_files.
Async version of download_files.
List all files in a directory with metadata.
Async version of ls_info.
Find files matching a glob pattern.
Async version of glob_info.
Search for a literal text pattern in files.
Async version of grep_raw.