Sandbox

Defined in: src/sandbox/base.ts:35

Abstract execution environment.

A Sandbox provides the runtime context where tools execute code, run commands, and interact with a filesystem. Multiple tools share the same Sandbox instance, giving them a common working directory and filesystem.

Streaming methods (executeStreaming, executeCodeStreaming) are the abstract primitives. Non-streaming convenience methods (execute, executeCode) consume the stream and return the final result.

Extended by

• PosixShellSandbox

Constructors

Constructor

new Sandbox(): Sandbox;

Returns

Sandbox

Methods

executeStreaming()

abstract executeStreaming(command, options?): AsyncIterable<
  | StreamChunk
| ExecutionResult>;

Defined in: src/sandbox/base.ts:47

Execute a shell command, streaming output.

Yields StreamChunk objects for stdout and stderr as output arrives. The final yield is an ExecutionResult with the exit code and complete output.

Parameters

Parameter	Type	Description
command	string	The shell command to execute.
options?	ExecuteOptions	Execution options (timeout, cwd).

Returns

AsyncIterable< | StreamChunk | ExecutionResult>

Async iterable yielding StreamChunks followed by a final ExecutionResult.

---

executeCodeStreaming()

abstract executeCodeStreaming(
   code,
   language,
   options?): AsyncIterable<
  | StreamChunk
| ExecutionResult>;

Defined in: src/sandbox/base.ts:57

Execute source code via a language interpreter, streaming output.

Parameters

Parameter	Type	Description
code	string	The source code to execute.
language	string	The interpreter to use (e.g., "python3", "node").
options?	ExecuteOptions	Execution options (timeout, cwd).

Returns

AsyncIterable< | StreamChunk | ExecutionResult>

Async iterable yielding StreamChunks followed by a final ExecutionResult.

---

readFile()

abstract readFile(path): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: src/sandbox/base.ts:73

Read a file from the sandbox filesystem as raw bytes.

Returns Uint8Array to support both text and binary files. Use readText for a convenience wrapper that decodes to a string.

Parameters

Parameter	Type	Description
path	string	Path to the file to read.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The file contents as raw bytes.

Throws

Error if the file does not exist.

---

writeFile()

abstract writeFile(path, content): Promise<void>;

Defined in: src/sandbox/base.ts:84

Write raw bytes to a file in the sandbox filesystem.

Implementations should create parent directories if they do not exist. Use writeText for a convenience wrapper that encodes a string.

Parameters

Parameter	Type	Description
path	string	Path to the file to write.
content	Uint8Array	The content to write.

Returns

Promise<void>

---

removeFile()

abstract removeFile(path): Promise<void>;

Defined in: src/sandbox/base.ts:92

Remove a file from the sandbox filesystem.

Parameters

Parameter	Type	Description
path	string	Path to the file to remove.

Returns

Promise<void>

Throws

Error if the file does not exist.

---

listFiles()

abstract listFiles(path): Promise<FileInfo[]>;

Defined in: src/sandbox/base.ts:105

List files in a sandbox directory.

Returns FileInfo entries with name, isDir, and size metadata. Fields isDir and size may be undefined if the backend cannot determine them.

Parameters

Parameter	Type	Description
path	string	Path to the directory to list.

Returns

Promise<FileInfo[]>

Array of FileInfo entries for the directory contents.

Throws

Error if the directory does not exist.

---

execute()

execute(command, options?): Promise<ExecutionResult>;

Defined in: src/sandbox/base.ts:119

Execute a shell command and return the result.

Consumes executeStreaming and returns the final ExecutionResult. Use executeStreaming when you need to process output as it arrives.

Parameters

Parameter	Type	Description
command	string	The shell command to execute.
options?	ExecuteOptions	Execution options (timeout, cwd).

Returns

Promise<ExecutionResult>

The execution result with exit code and output.

---

executeCode()

executeCode(
   code,
   language,
options?): Promise<ExecutionResult>;

Defined in: src/sandbox/base.ts:139

Execute source code and return the result.

Consumes executeCodeStreaming and returns the final ExecutionResult. Use executeCodeStreaming when you need to process output as it arrives.

Parameters

Parameter	Type	Description
code	string	The source code to execute.
language	string	The interpreter to use.
options?	ExecuteOptions	Execution options (timeout, cwd).

Returns

Promise<ExecutionResult>

The execution result with exit code and output.

---

readText()

readText(path): Promise<string>;

Defined in: src/sandbox/base.ts:157

Read a text file from the sandbox filesystem.

Convenience wrapper over readFile that decodes bytes as UTF-8. For other encodings, call readFile and decode manually.

Parameters

Parameter	Type	Description
path	string	Path to the file to read.

Returns

Promise<string>

The file contents decoded as a UTF-8 string.

---

writeText()

writeText(path, content): Promise<void>;

Defined in: src/sandbox/base.ts:170

Write a text file to the sandbox filesystem.

Convenience wrapper over writeFile that encodes a string as UTF-8. For other encodings, encode manually and call writeFile.

Parameters

Parameter	Type	Description
path	string	Path to the file to write.
content	string	The text content to write.

Returns

Promise<void>