@cloudflare/sandbox 0.13.0-next.649.1 → 0.13.0-next.681.1

package/dist/index-B7QgIs0N.d.ts

@@ -0,0 +1,1841 @@
+import { RpcTarget } from "cloudflare:workers";
+
+//#region ../shared/dist/pty-types.d.ts
+interface PtyOptions {
+  cols?: number;
+  rows?: number;
+  shell?: string;
+}
+interface TerminalOptions {
+  id?: string;
+  cwd?: string;
+  shell?: string;
+}
+interface TerminalCreateOptions {
+  id: string;
+  cwd?: string;
+  shell?: string;
+  cols?: number;
+  rows?: number;
+}
+interface TerminalConnectOptions {
+  cols?: number;
+  rows?: number;
+}
+interface SandboxTerminal {
+  readonly id: string;
+  connect(request: Request, options?: TerminalConnectOptions): Promise<Response>;
+  destroy(): Promise<void>;
+}
+//#endregion
+//#region ../shared/dist/types.d.ts
+interface BaseExecOptions {
+  /**
+   * Maximum execution time in milliseconds
+   */
+  timeout?: number;
+  /**
+   * Environment variables for this command invocation.
+   * Values temporarily override session-level/container-level env for the
+   * duration of the command but do not persist after it completes.
+   * Undefined values are skipped (treated as "not configured").
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Working directory for command execution
+   */
+  cwd?: string;
+  /**
+   * Text encoding for output (default: 'utf8')
+   */
+  encoding?: string;
+}
+/**
+ * @deprecated Use `SandboxExecOptions` instead. Will be removed in a future
+ * release once all callers migrate to `sandbox.exec(cmd, options)` returning
+ * a `SandboxProcessPromise`. See `docs/EXEC_MIGRATION.md`.
+ */
+interface ExecOptions extends BaseExecOptions {
+  /**
+   * Enable real-time output streaming via callbacks
+   */
+  stream?: boolean;
+  /**
+   * Callback for real-time output data
+   */
+  onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;
+  /**
+   * Callback when command completes (only when stream: true)
+   */
+  onComplete?: (result: ExecResult) => void;
+  /**
+   * Callback for execution errors
+   */
+  onError?: (error: Error) => void;
+  /**
+   * AbortSignal for cancelling execution
+   */
+  signal?: AbortSignal;
+  /**
+   * Whether this command was initiated by the user or by internal
+   * infrastructure (backup, bucket mount, env setup, etc.).
+   * Defaults to 'user' when omitted.
+   */
+  origin?: 'user' | 'internal';
+}
+/**
+ * @deprecated Use `SandboxExecOutput` (returned by
+ * `SandboxProcess.output()`) instead. Will be removed alongside `ExecOptions`.
+ */
+interface ExecResult {
+  /**
+   * Whether the command succeeded (exitCode === 0)
+   */
+  success: boolean;
+  /**
+   * Process exit code
+   */
+  exitCode: number;
+  /**
+   * Standard output content
+   */
+  stdout: string;
+  /**
+   * Standard error content
+   */
+  stderr: string;
+  /**
+   * Command that was executed
+   */
+  command: string;
+  /**
+   * Execution duration in milliseconds
+   */
+  duration: number;
+  /**
+   * ISO timestamp when command started
+   */
+  timestamp: string;
+  /**
+   * Session ID if provided
+   */
+  sessionId?: string;
+}
+/**
+ * Result from waiting for a log pattern
+ */
+interface WaitForLogResult {
+  /** The log line that matched */
+  line: string;
+  /** Regex capture groups (if condition was a RegExp) */
+  match?: RegExpMatchArray;
+}
+/**
+ * Result from waiting for process exit
+ */
+interface WaitForExitResult {
+  /** Process exit code */
+  exitCode: number;
+}
+/**
+ * Options for waiting for a port to become ready
+ */
+interface WaitForPortOptions {
+  /**
+   * Check mode
+   * - 'http': Make an HTTP request and check for success status (default)
+   * - 'tcp': Just check if TCP connection succeeds
+   * @default 'http'
+   */
+  mode?: 'http' | 'tcp';
+  /**
+   * HTTP path to check (only used when mode is 'http')
+   * @default '/'
+   */
+  path?: string;
+  /**
+   * Expected HTTP status code or range (only used when mode is 'http')
+   * - Single number: exact match (e.g., 200)
+   * - Object with min/max: range match (e.g., { min: 200, max: 399 })
+   * @default { min: 200, max: 399 }
+   */
+  status?: number | {
+    min: number;
+    max: number;
+  };
+  /**
+   * Maximum time to wait in milliseconds
+   * @default no timeout
+   */
+  timeout?: number;
+  /**
+   * Interval between checks in milliseconds
+   * @default 500
+   */
+  interval?: number;
+}
+/**
+ * Request body for port readiness check endpoint
+ */
+interface PortCheckRequest {
+  port: number;
+  mode: 'http' | 'tcp';
+  path?: string;
+  statusMin?: number;
+  statusMax?: number;
+}
+/**
+ * Request body for streaming port watch endpoint
+ */
+interface PortWatchRequest extends PortCheckRequest {
+  /** Process ID to monitor - stream closes if process exits */
+  processId?: string;
+  /** Internal polling interval in ms (default: 500) */
+  interval?: number;
+}
+interface ProcessQueryOptions {
+  /**
+   * Optional session ID used to bind returned process handles to an explicit session.
+   */
+  sessionId?: string;
+}
+/**
+ * @deprecated Use `SandboxExecOptions` with `processId` set instead. The
+ * unified `sandbox.exec()` returns the same `SandboxProcess` handle whether
+ * the caller wants a foreground or background process.
+ */
+interface ProcessOptions extends BaseExecOptions {
+  /**
+   * Optional session ID to run the background process in.
+   *
+   * When omitted, the sandbox's default execution policy applies.
+   */
+  sessionId?: string;
+  /**
+   * Custom process ID for later reference
+   * If not provided, a UUID will be generated
+   */
+  processId?: string;
+  /**
+   * Automatically cleanup process record after exit (default: true)
+   */
+  autoCleanup?: boolean;
+  /**
+   * Callback when process exits
+   */
+  onExit?: (code: number | null) => void;
+  /**
+   * Callback for real-time output (background processes)
+   */
+  onOutput?: (stream: 'stdout' | 'stderr', data: string) => void;
+  /**
+   * Callback when process starts successfully
+   */
+  onStart?: (process: Process) => void;
+  /**
+   * Callback for process errors
+   */
+  onError?: (error: Error) => void;
+}
+type ProcessStatus = 'starting' | 'running' | 'completed' | 'failed' | 'killed' | 'error';
+/**
+ * @deprecated Use `SandboxProcess` instead. The unified handle has the same
+ * `id`/`pid`/`command`/`status`/`startTime`/`sessionId` fields plus
+ * `stdin`/`stdout`/`stderr` streams, an `exitCode` promise, `output()` and
+ * `kill()` that mirror the `ctx.container.exec()` contract.
+ */
+interface Process {
+  /**
+   * Unique process identifier
+   */
+  readonly id: string;
+  /**
+   * System process ID (if available and running)
+   */
+  readonly pid?: number;
+  /**
+   * Command that was executed
+   */
+  readonly command: string;
+  /**
+   * Current process status
+   */
+  readonly status: ProcessStatus;
+  /**
+   * When the process was started
+   */
+  readonly startTime: Date;
+  /**
+   * When the process ended (if completed)
+   */
+  readonly endTime?: Date;
+  /**
+   * Process exit code (if completed)
+   */
+  readonly exitCode?: number;
+  /**
+   * Session ID if provided
+   */
+  readonly sessionId?: string;
+  /**
+   * Kill the process
+   */
+  kill(signal?: string): Promise<void>;
+  /**
+   * Get current process status (refreshed)
+   */
+  getStatus(): Promise<ProcessStatus>;
+  /**
+   * Get accumulated logs
+   */
+  getLogs(): Promise<{
+    stdout: string;
+    stderr: string;
+  }>;
+  /**
+   * Wait for a log pattern to appear in process output
+   *
+   * @example
+   * const proc = await sandbox.startProcess("python train.py");
+   * await proc.waitForLog("Epoch 1 complete");
+   * await proc.waitForLog(/Epoch (\d+) complete/);
+   */
+  waitForLog(pattern: string | RegExp, timeout?: number): Promise<WaitForLogResult>;
+  /**
+   * Wait for a port to become ready
+   *
+   * @example
+   * // Wait for HTTP endpoint to return 200-399
+   * const proc = await sandbox.startProcess("npm run dev");
+   * await proc.waitForPort(3000);
+   *
+   * @example
+   * // Wait for specific health endpoint
+   * await proc.waitForPort(3000, { path: '/health', status: 200 });
+   *
+   * @example
+   * // TCP-only check (just verify port is accepting connections)
+   * await proc.waitForPort(5432, { mode: 'tcp' });
+   */
+  waitForPort(port: number, options?: WaitForPortOptions): Promise<void>;
+  /**
+   * Wait for the process to exit
+   *
+   * Returns the exit code. Use getProcessLogs() or streamProcessLogs()
+   * to retrieve output after the process exits.
+   */
+  waitForExit(timeout?: number): Promise<WaitForExitResult>;
+}
+/**
+ * @deprecated Internal SSE frame type. Consumers should read
+ * `SandboxProcess.stdout` / `.stderr` (raw byte streams) instead of parsing
+ * SSE frames. Retained while the legacy `execStream` HTTP route exists.
+ */
+interface ExecEvent {
+  type: 'start' | 'stdout' | 'stderr' | 'complete' | 'error';
+  timestamp: string;
+  data?: string;
+  command?: string;
+  exitCode?: number;
+  result?: ExecResult;
+  error?: string;
+  sessionId?: string;
+  pid?: number;
+}
+/**
+ * @deprecated Internal SSE frame type for `streamProcessLogs`. Consumers
+ * should read `SandboxProcess.stdout` / `.stderr` instead.
+ */
+interface LogEvent {
+  type: 'stdout' | 'stderr' | 'exit' | 'error';
+  timestamp: string;
+  data: string;
+  processId: string;
+  sessionId?: string;
+  exitCode?: number;
+}
+/**
+ * Options for `sandbox.exec(cmd, options)`.
+ *
+ * Mirrors `ContainerExecOptions` from
+ * `@cloudflare/workers-types/experimental` (`cwd`, `env`, `stdin`, `stdout`,
+ * `stderr`) with sandbox-specific extensions for sessions, named process
+ * ids, timeouts, and cancellation.
+ *
+ * Notable differences from the runtime contract:
+ * - `env` values may be `undefined` (treated as "not configured"). The
+ *   container API requires `Record<string, string>`; the SDK strips
+ *   `undefined` entries before forwarding.
+ * - `stdin` additionally accepts a plain `string` for convenience.
+ * - `user` is not yet supported (no session-backend story).
+ */
+interface SandboxExecOptions {
+  /** Working directory for command execution. */
+  cwd?: string;
+  /**
+   * Environment variables for this command invocation.
+   *
+   * Values temporarily override session-level/container-level env for the
+   * duration of the command but do not persist after it completes.
+   * Undefined values are skipped (treated as "not configured").
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Standard input source.
+   *
+   * - `"pipe"` — `SandboxProcess.stdin` is a `WritableStream<Uint8Array>` the
+   *   caller can write to.
+   * - `ReadableStream<Uint8Array>` — the stream is piped into the command.
+   * - `string` — convenience: the string is utf-8 encoded and piped in.
+   * - omitted — stdin is closed.
+   */
+  stdin?: ReadableStream<Uint8Array> | string | 'pipe';
+  /**
+   * Standard output disposition.
+   *
+   * - `"pipe"` (default) — `SandboxProcess.stdout` exposes a
+   *   `ReadableStream<Uint8Array>` of the output.
+   * - `"ignore"` — output is discarded; `SandboxProcess.stdout` is `null`.
+   */
+  stdout?: 'pipe' | 'ignore';
+  /**
+   * Standard error disposition.
+   *
+   * - `"pipe"` (default) — `SandboxProcess.stderr` exposes a
+   *   `ReadableStream<Uint8Array>` of the error output.
+   * - `"ignore"` — stderr is discarded; `SandboxProcess.stderr` is `null`.
+   * - `"combined"` — stderr is merged into stdout; `SandboxProcess.stderr`
+   *   is `null`.
+   */
+  stderr?: 'pipe' | 'ignore' | 'combined';
+  /**
+   * Session ID providing working-directory and environment scope.
+   *
+   * When omitted, the sandbox's default execution policy applies (typically
+   * the persistent default session).
+   */
+  sessionId?: string;
+  /**
+   * Client-chosen process id for later re-attach via
+   * `sandbox.getProcess(id)`.
+   *
+   * When omitted, a UUID is generated.
+   */
+  processId?: string;
+  /**
+   * Whether to remove the process record on exit.
+   *
+   * Currently retained for compatibility with legacy process options. Process
+   * records are kept so `output()`, `getLogs()`, and re-attach can read logs;
+   * callers can use `cleanupCompletedProcesses()` to remove completed records.
+   */
+  autoCleanup?: boolean;
+  /**
+   * Wall-clock timeout in milliseconds. When the timeout fires the
+   * implementation sends `SIGTERM`; `exitCode` resolves with the resulting
+   * code (typically `143` / `-15`).
+   */
+  timeout?: number;
+  /**
+   * External cancellation signal. Aborting triggers `kill()` and propagates
+   * to in-flight stream consumers.
+   */
+  signal?: AbortSignal;
+  /**
+   * Whether this command was initiated by the user or by internal
+   * infrastructure (backup, bucket mount, env setup, etc.).
+   *
+   * Sandbox-only; not part of the containers contract. Defaults to
+   * `'user'` when omitted.
+   */
+  origin?: 'user' | 'internal';
+}
+/**
+ * Buffered output returned by `SandboxProcess.output()`.
+ *
+ * Mirrors `ExecOutput` from the containers contract (`stdout`, `stderr`,
+ * `exitCode`) with sandbox-specific telemetry fields preserved from the
+ * legacy `ExecResult` so existing callers can migrate without losing
+ * information.
+ *
+ * `stdout` / `stderr` are `string` by default (utf-8) or `ArrayBuffer`
+ * when `output({ encoding: 'buffer' })` is requested.
+ */
+type SandboxOutputMode = 'pipe' | 'ignore';
+type SandboxStderrMode = 'pipe' | 'ignore' | 'combined';
+type SandboxOutputEncoding = 'utf8' | 'buffer';
+interface SandboxExecOutputBase<T> {
+  /** Standard output content. */
+  stdout: T;
+  /** Standard error content. */
+  stderr: T;
+  /** Process exit code. */
+  exitCode: number;
+  /** True iff `exitCode === 0`. */
+  success: boolean;
+  /** Execution duration in milliseconds, measured by the SDK. */
+  duration: number;
+  /** Command that was executed (display form). */
+  command: string;
+  /** ISO timestamp when the command started. */
+  timestamp: string;
+  /** Session ID, if the command ran in a session. */
+  sessionId?: string;
+}
+type SandboxExecStringOutput = SandboxExecOutputBase<string>;
+type SandboxExecBufferOutput = SandboxExecOutputBase<ArrayBuffer>;
+type SandboxExecOutput = SandboxExecStringOutput | SandboxExecBufferOutput;
+/**
+ * Unified process handle returned (resolved) by `sandbox.exec()`.
+ *
+ * The first nine members are a superset of `ExecProcess` from the
+ * containers runtime contract (`stdin`, `stdout`, `stderr`, `pid`,
+ * `exitCode`, `output()`, `kill()`). The remaining members are
+ * sandbox-specific extensions for log replay, named processes, and the
+ * existing `waitFor*` helpers.
+ *
+ * On re-attach (via `sandbox.getProcess(id)`):
+ * - `stdin` is `null` (the original writer owns the pipe).
+ * - `stdout`/`stderr` are replay-then-tail streams sourced from the
+ *   per-process log file.
+ */
+interface SandboxProcess {
+  readonly stdin: WritableStream<Uint8Array> | null;
+  readonly stdout: ReadableStream<Uint8Array> | null;
+  readonly stderr: ReadableStream<Uint8Array> | null;
+  readonly pid: number;
+  readonly exitCode: Promise<number>;
+  /**
+   * Drain stdout/stderr and await exit. Mirrors `ExecProcess.output()`.
+   *
+   * Default encoding is utf-8 strings; pass `{ encoding: 'buffer' }` to get
+   * `ArrayBuffer` instead (matches the containers contract).
+   */
+  output(options: {
+    encoding: 'buffer';
+  }): Promise<SandboxExecBufferOutput>;
+  output(options?: {
+    encoding?: 'utf8';
+  }): Promise<SandboxExecStringOutput>;
+  output(options?: {
+    encoding?: SandboxOutputEncoding;
+  }): Promise<SandboxExecOutput>;
+  /** Sugar for `(await this.output({ encoding: 'utf8' })).stdout` as a string. */
+  text(): Promise<string>;
+  /** Sugar for `JSON.parse(await this.text())`. */
+  json<T = unknown>(): Promise<T>;
+  /**
+   * Terminate the process.
+   *
+   * Defaults to `SIGTERM` (15).
+   */
+  kill(signal?: number | string): void;
+  /** Stable sandbox process id (survives re-attach). */
+  readonly id: string;
+  /** Command that was executed (display form). */
+  readonly command: string;
+  /** Session ID, if the command was scoped to a session. */
+  readonly sessionId?: string;
+  /** When the process started. */
+  readonly startTime: Date;
+  /** Current status snapshot. Cheap; uses local state where possible. */
+  status(): Promise<ProcessStatus>;
+  /** Replay buffered logs (post-exit or mid-flight). */
+  getLogs(): Promise<{
+    stdout: string;
+    stderr: string;
+  }>;
+  /** Wait for a log pattern to appear in stdout/stderr. */
+  waitForLog(pattern: string | RegExp, timeoutMs?: number): Promise<WaitForLogResult>;
+  /** Wait for a TCP port (or HTTP endpoint) to become ready. */
+  waitForPort(port: number, options?: WaitForPortOptions): Promise<void>;
+  /** Wait for the process to exit. */
+  waitForExit(timeoutMs?: number): Promise<WaitForExitResult>;
+}
+/**
+ * The thenable returned by `sandbox.exec(cmd, options)`.
+ *
+ * Resolves to a `SandboxProcess` (so `await sandbox.exec(cmd)` works as
+ * expected) and additionally exposes the convenience members directly so
+ * callers can write `await sandbox.exec(cmd).output()` / `.text()` /
+ * `.json()` / `.kill()` without an extra `await`.
+ *
+ * Modeled on `Bun.spawn()` / `Deno.Command`.
+ */
+interface SandboxProcessPromise extends Promise<SandboxProcess> {
+  /** Equivalent to `(await this).output(options)`. */
+  output(options: {
+    encoding: 'buffer';
+  }): Promise<SandboxExecBufferOutput>;
+  output(options?: {
+    encoding?: 'utf8';
+  }): Promise<SandboxExecStringOutput>;
+  output(options?: {
+    encoding?: SandboxOutputEncoding;
+  }): Promise<SandboxExecOutput>;
+  /** Sugar for `(await this.output({ encoding: 'utf8' })).stdout` as a string. */
+  text(): Promise<string>;
+  /** Sugar for `JSON.parse(await this.text())`. */
+  json<T = unknown>(): Promise<T>;
+  /** Equivalent to `(await this).kill(signal)`. */
+  kill(signal?: number | string): Promise<void>;
+}
+interface SessionOptions {
+  /**
+   * Optional session ID (auto-generated if not provided)
+   */
+  id?: string;
+  /**
+   * Session name for identification
+   */
+  name?: string;
+  /**
+   * Environment variables for this session.
+   * Undefined values are skipped (treated as "not configured").
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Working directory
+   */
+  cwd?: string;
+  /**
+   * Enable PID namespace isolation (requires CAP_SYS_ADMIN)
+   */
+  isolation?: boolean;
+  /**
+   * Maximum amount of time a command can run in milliseconds
+   */
+  commandTimeoutMs?: number;
+}
+interface SandboxOptions {
+  /**
+   * Duration after which the sandbox instance will sleep if no requests are received
+   * Can be:
+   * - A string like "30s", "3m", "5m", "1h" (seconds, minutes, or hours)
+   * - A number representing seconds (e.g., 180 for 3 minutes)
+   * Default: "10m" (10 minutes)
+   *
+   * Note: Ignored when keepAlive is true
+   */
+  sleepAfter?: string | number;
+  /**
+   * Keep the container alive indefinitely by preventing automatic shutdown
+   * When true, the container will never auto-timeout and must be explicitly destroyed
+   * - Any scenario where activity can't be automatically detected
+   *
+   * Important: You MUST call sandbox.destroy() when done to avoid resource leaks
+   *
+   * Default: false
+   */
+  keepAlive?: boolean;
+  /**
+   * When true (the default), implicit operations automatically create and reuse
+   * a persistent default shell session. Set to false to run implicit top-level
+   * operations sessionlessly, where each command spawns a fresh process with no
+   * shared shell state. Explicit per-call session IDs continue to work normally
+   * when this is false.
+   *
+   * Default: true
+   */
+  enableDefaultSession?: boolean;
+  /**
+   * Normalize sandbox ID to lowercase for preview URL compatibility
+   *
+   * Required for preview URLs because hostnames are case-insensitive (RFC 3986), which
+   * would route requests to a different Durable Object instance with IDs containing uppercase letters.
+   *
+   * **Important:** Different normalizeId values create different Durable Object instances:
+   * - `getSandbox(ns, "MyProject")` → DO key: "MyProject"
+   * - `getSandbox(ns, "MyProject", {normalizeId: true})` → DO key: "myproject"
+   *
+   * **Future change:** In a future version, this will default to `true` (automatically lowercase all IDs).
+   * IDs with uppercase letters will trigger a warning. To prepare, use lowercase IDs or explicitly
+   * pass `normalizeId: true`.
+   *
+   * @example
+   * getSandbox(ns, "my-project")  // Works with preview URLs (lowercase)
+   * getSandbox(ns, "MyProject", {normalizeId: true})  // Normalized to "myproject"
+   *
+   * @default false
+   */
+  normalizeId?: boolean;
+  /**
+   * Container startup timeout configuration
+   *
+   * Tune timeouts based on your container's characteristics. SDK defaults (30s instance, 90s ports)
+   * work for most use cases. Adjust for heavy containers or fail-fast applications.
+   *
+   * Can also be configured via environment variables:
+   * - SANDBOX_INSTANCE_TIMEOUT_MS
+   * - SANDBOX_PORT_TIMEOUT_MS
+   * - SANDBOX_POLL_INTERVAL_MS
+   *
+   * Precedence: options > env vars > SDK defaults
+   *
+   * @example
+   * // Heavy containers (ML models, large apps)
+   * getSandbox(ns, id, {
+   *   containerTimeouts: { portReadyTimeoutMS: 180_000 }
+   * })
+   *
+   * @example
+   * // Fail-fast for latency-sensitive apps
+   * getSandbox(ns, id, {
+   *   containerTimeouts: {
+   *     instanceGetTimeoutMS: 15_000,
+   *     portReadyTimeoutMS: 30_000
+   *   }
+   * })
+   */
+  containerTimeouts?: {
+    /**
+     * Time to wait for container instance provisioning
+     * @default 30000 (30s) - or SANDBOX_INSTANCE_TIMEOUT_MS env var
+     */
+    instanceGetTimeoutMS?: number;
+    /**
+     * Time to wait for application startup and ports to be ready
+     * @default 90000 (90s) - or SANDBOX_PORT_TIMEOUT_MS env var
+     */
+    portReadyTimeoutMS?: number;
+    /**
+     * How often to poll for container readiness
+     * @default 300 (300ms) - or SANDBOX_POLL_INTERVAL_MS env var
+     */
+    waitIntervalMS?: number;
+  };
+}
+/**
+ * Execution session - isolated execution context within a sandbox
+ * Returned by sandbox.createSession()
+ * Provides the same API as ISandbox but bound to a specific session
+ */
+interface MkdirResult {
+  success: boolean;
+  path: string;
+  recursive: boolean;
+  timestamp: string;
+  exitCode?: number;
+}
+interface WriteFileResult {
+  success: boolean;
+  path: string;
+  timestamp: string;
+  exitCode?: number;
+}
+/**
+ * Valid `encoding` values accepted by `readFile` / `writeFile` options.
+ *
+ * - `'utf-8'` / `'utf8'` — treat content as text.
+ * - `'base64'` — treat content as base64-encoded binary.
+ * - `'none'` — streaming variant of `readFile`, returns a
+ *   `ReadableStream<Uint8Array>` of raw bytes (see `ReadFileStreamResult`).
+ */
+type FileEncoding = 'utf-8' | 'utf8' | 'base64' | 'none';
+interface ReadFileResult {
+  success: boolean;
+  path: string;
+  content: string;
+  timestamp: string;
+  exitCode?: number;
+  /**
+   * Encoding used for content (utf-8 for text, base64 for binary)
+   */
+  encoding?: 'utf-8' | 'base64';
+  /**
+   * Whether the file is detected as binary
+   */
+  isBinary?: boolean;
+  /**
+   * MIME type of the file (e.g., 'image/png', 'text/plain')
+   */
+  mimeType?: string;
+  /**
+   * File size in bytes
+   */
+  size?: number;
+}
+/**
+ * Result of `readFile()` with `encoding: 'none'`.
+ *
+ * `content` is a raw binary `ReadableStream<Uint8Array>` delivered directly
+ * over the capnp channel — no base64 encoding, no SSE framing, no buffering.
+ */
+interface ReadFileStreamResult {
+  success: true;
+  path: string;
+  content: ReadableStream<Uint8Array>;
+  size: number;
+  mimeType: string;
+  timestamp: string;
+}
+interface DeleteFileResult {
+  success: boolean;
+  path: string;
+  timestamp: string;
+  exitCode?: number;
+}
+interface RenameFileResult {
+  success: boolean;
+  path: string;
+  newPath: string;
+  timestamp: string;
+  exitCode?: number;
+}
+interface MoveFileResult {
+  success: boolean;
+  path: string;
+  newPath: string;
+  timestamp: string;
+  exitCode?: number;
+}
+interface FileExistsResult {
+  success: boolean;
+  path: string;
+  exists: boolean;
+  timestamp: string;
+}
+interface FileInfo {
+  name: string;
+  absolutePath: string;
+  relativePath: string;
+  type: 'file' | 'directory' | 'symlink' | 'other';
+  size: number;
+  modifiedAt: string;
+  mode: string;
+  permissions: {
+    readable: boolean;
+    writable: boolean;
+    executable: boolean;
+  };
+}
+interface ListFilesOptions {
+  recursive?: boolean;
+  includeHidden?: boolean;
+  /**
+   * Optional session ID used to resolve relative paths and execution context.
+   *
+   * When omitted, the sandbox's default execution policy applies.
+   */
+  sessionId?: string;
+}
+interface ListFilesResult {
+  success: boolean;
+  path: string;
+  files: FileInfo[];
+  count: number;
+  timestamp: string;
+  exitCode?: number;
+}
+/**
+ * SSE events for file streaming
+ */
+type FileStreamEvent = {
+  type: 'metadata';
+  mimeType: string;
+  size: number;
+  isBinary: boolean;
+  encoding: 'utf-8' | 'base64';
+} | {
+  type: 'chunk';
+  data: string;
+} | {
+  type: 'complete';
+  bytesRead: number;
+} | {
+  type: 'error';
+  error: string;
+};
+/**
+ * File metadata from streaming
+ */
+interface FileMetadata {
+  mimeType: string;
+  size: number;
+  isBinary: boolean;
+  encoding: 'utf-8' | 'base64';
+}
+/**
+ * File stream chunk - either string (text) or Uint8Array (binary, auto-decoded)
+ */
+type FileChunk = string | Uint8Array;
+/**
+ * Options for watching a directory.
+ *
+ * `watch()` resolves only after the watcher is established on the filesystem.
+ * The returned SSE stream can be consumed with `parseSSEStream()`.
+ */
+interface WatchOptions {
+  /**
+   * Watch subdirectories recursively
+   * @default true
+   */
+  recursive?: boolean;
+  /**
+   * Glob patterns to include (e.g., '*.ts', '*.js').
+   * If not specified, all files are included.
+   * Cannot be used together with `exclude`.
+   */
+  include?: string[];
+  /**
+   * Glob patterns to exclude (e.g., 'node_modules', '.git').
+   * Cannot be used together with `include`.
+   * @default ['.git', 'node_modules', '.DS_Store']
+   */
+  exclude?: string[];
+  /**
+   * Session to run the watch in.
+   * If omitted, the default session is used.
+   */
+  sessionId?: string;
+}
+/**
+ * Options for checking whether a path changed while disconnected.
+ *
+ * Pass the `version` returned from a previous `checkChanges()` call to learn
+ * whether the path is unchanged, changed, or needs a full resync because the
+ * retained change state was reset. Change state lives only for the current
+ * container lifetime and may expire while idle.
+ */
+interface CheckChangesOptions extends WatchOptions {
+  /**
+   * Version returned by a previous `checkChanges()` call.
+   */
+  since?: string;
+}
+/**
+ * @internal SSE event types for container communication
+ */
+type FileWatchEventType = 'create' | 'modify' | 'delete' | 'move_from' | 'move_to' | 'attrib';
+/**
+ * @internal Request body for starting a file watch
+ */
+interface WatchRequest {
+  path: string;
+  recursive?: boolean;
+  events?: FileWatchEventType[];
+  include?: string[];
+  exclude?: string[];
+  sessionId?: string;
+}
+/**
+ * @internal Request body for checking retained change state.
+ */
+interface CheckChangesRequest extends WatchRequest {
+  since?: string;
+}
+/**
+ * SSE events emitted by `sandbox.watch()`.
+ */
+type FileWatchSSEEvent = {
+  type: 'watching';
+  path: string;
+  watchId: string;
+} | {
+  type: 'event';
+  eventType: FileWatchEventType;
+  path: string;
+  isDirectory: boolean;
+  timestamp: string;
+} | {
+  type: 'error';
+  error: string;
+} | {
+  type: 'stopped';
+  reason: string;
+};
+/**
+ * Result returned by `checkChanges()`.
+ */
+type CheckChangesResult = {
+  success: true;
+  status: 'unchanged' | 'changed';
+  version: string;
+  timestamp: string;
+} | {
+  success: true;
+  status: 'resync';
+  reason: 'expired' | 'restarted';
+  version: string;
+  timestamp: string;
+};
+interface ProcessStartResult {
+  success: boolean;
+  processId: string;
+  pid?: number;
+  command: string;
+  timestamp: string;
+}
+interface ProcessListResult {
+  success: boolean;
+  processes: Array<{
+    id: string;
+    pid?: number;
+    command: string;
+    status: ProcessStatus;
+    startTime: string;
+    endTime?: string;
+    exitCode?: number;
+    stdout?: SandboxOutputMode;
+    stderr?: SandboxStderrMode;
+  }>;
+  timestamp: string;
+}
+interface ProcessInfoResult {
+  success: boolean;
+  process: {
+    id: string;
+    pid?: number;
+    command: string;
+    status: ProcessStatus;
+    startTime: string;
+    endTime?: string;
+    exitCode?: number;
+    stdout?: SandboxOutputMode;
+    stderr?: SandboxStderrMode;
+  };
+  timestamp: string;
+}
+interface ProcessKillResult {
+  success: boolean;
+  processId: string;
+  signal?: string;
+  timestamp: string;
+}
+interface ProcessLogsResult {
+  success: boolean;
+  processId: string;
+  stdout: string;
+  stderr: string;
+  timestamp: string;
+}
+interface ProcessCleanupResult {
+  success: boolean;
+  message?: string;
+  killedCount?: number;
+  cleanedCount: number;
+  timestamp: string;
+}
+interface SessionDeleteResult {
+  success: boolean;
+  sessionId: string;
+  timestamp: string;
+}
+interface ExecutionSession {
+  /** Unique session identifier */
+  readonly id: string;
+  /**
+   * Session-scoped exec primitive. See `ISandbox.exec`.
+   *
+   * Caller-provided `options.sessionId` is ignored — this wrapper pins
+   * execution to the session that produced it.
+   */
+  exec(command: string | string[], options?: SandboxExecOptions): SandboxProcessPromise;
+  /** Session-scoped buffered execution helper. See `ISandbox.run`. */
+  run(command: string, options?: ExecOptions): Promise<ExecResult>;
+  getProcess(id: string): Promise<SandboxProcess | null>;
+  listProcesses(): Promise<SandboxProcess[]>;
+  killAllProcesses(): Promise<number>;
+  cleanupCompletedProcesses(): Promise<number>;
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+    encoding?: string;
+  }): Promise<WriteFileResult>;
+  readFile(path: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
+  readFile(path: string, options?: {
+    encoding?: Exclude<FileEncoding, 'none'>;
+  }): Promise<ReadFileResult>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  watch(path: string, options?: Omit<WatchOptions, 'sessionId'>): Promise<ReadableStream<Uint8Array>>;
+  checkChanges(path: string, options?: Omit<CheckChangesOptions, 'sessionId'>): Promise<CheckChangesResult>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<MkdirResult>;
+  deleteFile(path: string): Promise<DeleteFileResult>;
+  renameFile(oldPath: string, newPath: string): Promise<RenameFileResult>;
+  moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
+  listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string): Promise<FileExistsResult>;
+  setEnvVars(envVars: Record<string, string | undefined>): Promise<void>;
+  mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+  unmountBucket(mountPath: string): Promise<void>;
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
+  terminal(request: Request, options?: PtyOptions): Promise<Response>;
+}
+/**
+ * Options for creating a directory backup
+ */
+interface BackupCompressionOptions {
+  format?: 'gzip' | 'lz4' | 'zstd';
+  threads?: number;
+}
+interface BackupOptions {
+  /** Directory to back up. Must be absolute and under `/workspace`, `/home`, `/tmp`, `/var/tmp`, or `/app`. */
+  dir: string;
+  /** Human-readable name for this backup. Optional. */
+  name?: string;
+  /** Seconds until automatic garbage collection. Default: 259200 (3 days). No upper limit. */
+  ttl?: number;
+  /**
+   * Respect git ignore rules for the backup directory when it is inside a git repository.
+   *
+   * Default: false.
+   * If the directory is not inside a git repository, no git-based exclusions are applied.
+   * If git is not installed in the container, a warning is logged and gitignore rules are skipped.
+   */
+  gitignore?: boolean;
+  /**
+   * Glob patterns to exclude from the backup.
+   * These are passed directly to mksquashfs as wildcard exclude patterns.
+   *
+   * @example ['node_modules', '*.log', '.cache']
+   */
+  excludes?: string[];
+  /**
+   * Use local R2 binding for backup storage instead of presigned URLs.
+   * Required for local development where presigned URLs and FUSE are unavailable.
+   * When true, the DO resolves BACKUP_BUCKET from its own env as an R2 binding.
+   */
+  localBucket?: boolean;
+  compression?: BackupCompressionOptions;
+  /**
+   * Use parallel multipart upload to R2 for large archives.
+   * Significantly speeds up uploads for archives over 10 MiB.
+   * Default: true.
+   */
+  multipart?: boolean;
+}
+/**
+ * Handle representing a stored directory backup.
+ * Serializable metadata returned by createBackup().
+ * Store it anywhere and later pass it to restoreBackup().
+ */
+interface DirectoryBackup {
+  /** Unique backup identifier */
+  readonly id: string;
+  /** Directory to restore into. Must be under `/workspace`, `/home`, `/tmp`, `/var/tmp`, or `/app`. */
+  readonly dir: string;
+  /** Whether this backup was created with local R2 binding mode. */
+  readonly localBucket?: boolean;
+}
+/**
+ * Result returned from a successful restoreBackup() call
+ */
+interface RestoreBackupResult {
+  success: boolean;
+  /** The directory that was restored */
+  dir: string;
+  /** Backup ID that was restored */
+  id: string;
+}
+/**
+ * Supported S3-compatible storage providers
+ */
+type BucketProvider = 'r2' | 's3' | 'gcs';
+/**
+ * Credentials for S3-compatible storage
+ */
+interface BucketCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+}
+/**
+ * Options for mounting an S3-compatible bucket via s3fs-FUSE (production)
+ */
+interface RemoteMountBucketOptions {
+  /**
+   * S3-compatible endpoint URL
+   *
+   * Examples:
+   * - R2: 'https://abc123.r2.cloudflarestorage.com'
+   * - AWS S3: 'https://s3.us-west-2.amazonaws.com'
+   * - GCS: 'https://storage.googleapis.com'
+   */
+  endpoint: string;
+  /**
+   * Optional provider hint for automatic s3fs flag configuration
+   * If not specified, will attempt to detect from endpoint URL.
+   *
+   * Examples:
+   * - 'r2' - Cloudflare R2 (adds nomixupload)
+   * - 's3' - Amazon S3 (standard configuration)
+   * - 'gcs' - Google Cloud Storage (no special flags needed)
+   */
+  provider?: BucketProvider;
+  /**
+   * Explicit credentials (overrides env var auto-detection)
+   */
+  credentials?: BucketCredentials;
+  /**
+   * Mount filesystem as read-only
+   * Default: false
+   */
+  readOnly?: boolean;
+  /**
+   * Advanced: Override or extend s3fs options
+   *
+   * These will be merged with provider-specific defaults.
+   * To override defaults completely, specify all options here.
+   *
+   * Common options:
+   * - 'use_path_request_style' - Use path-style URLs (bucket/path vs bucket.host/path)
+   * - 'nomixupload' - Disable mixed multipart uploads (needed for some providers)
+   * - 'nomultipart' - Disable all multipart operations
+   * - 'sigv2' - Use signature version 2 instead of v4
+   * - 'no_check_certificate' - Skip SSL certificate validation (dev/testing only)
+   */
+  s3fsOptions?: string[];
+  /**
+   * Optional prefix/subdirectory within the bucket to mount.
+   *
+   * When specified, only the contents under this prefix are visible at the
+   * mount point, scoping the mount to a subdirectory of the bucket.
+   *
+   * Must start with '/' (e.g., '/workspaces/project123' or '/data/uploads/')
+   */
+  prefix?: string;
+  /**
+   * Keep real credentials in the Durable Object; write dummy credentials into
+   * the container-side s3fs password file. Outbound s3fs requests are
+   * intercepted by the DO, signed with real credentials, and forwarded to the
+   * configured endpoint.
+   *
+   * Default: false (real credentials are written into the container)
+   */
+  credentialProxy?: boolean;
+}
+/**
+ * Options for mounting a local R2 binding via bidirectional sync (local dev)
+ *
+ * Used during local development with `wrangler dev`. The Durable Object
+ * resolves the R2 binding from its own env using the `bucket` parameter
+ * and syncs files via polling instead of s3fs-FUSE.
+ */
+interface LocalMountBucketOptions {
+  /**
+   * Must be true to indicate local R2 binding mode.
+   */
+  localBucket: true;
+  /**
+   * Optional prefix/subdirectory within the bucket to sync.
+   *
+   * When specified, only the contents under this prefix will be visible
+   * at the mount point.
+   */
+  prefix?: string;
+  /**
+   * Mount filesystem as read-only
+   * Default: false
+   */
+  readOnly?: boolean;
+}
+/**
+ * Options for mounting an R2 binding via credential-less egress interception.
+ */
+interface R2BindingMountBucketOptions {
+  /**
+   * Must not be set — distinguishes this variant from RemoteMountBucketOptions.
+   */
+  endpoint?: never;
+  /**
+   * Optional prefix/subdirectory within the bucket to mount.
+   *
+   * When specified, only the contents under this prefix will be visible
+   * at the mount point.
+   */
+  prefix?: string;
+  /**
+   * Mount filesystem as read-only
+   * Default: false
+   */
+  readOnly?: boolean;
+  /**
+   * Advanced: Override or extend s3fs options.
+   * Provider defaults for R2 are still applied automatically.
+   */
+  s3fsOptions?: string[];
+}
+/**
+ * Options for mounting a bucket — remote (s3fs-FUSE), local (R2 binding sync),
+ * or R2 egress (credential-less s3fs via egress interception).
+ */
+type MountBucketOptions = RemoteMountBucketOptions | LocalMountBucketOptions | R2BindingMountBucketOptions;
+interface ISandbox {
+  /**
+   * Execute a command in the sandbox.
+   *
+   * Mirrors the `ctx.container.exec()` contract from the Cloudflare
+   * Containers runtime, with sandbox-specific extensions for sessions,
+   * named process ids, and re-attach.
+   *
+   * Returns a `SandboxProcessPromise` — a thenable that resolves to a
+   * `SandboxProcess` (`stdin` / `stdout` / `stderr` / `exitCode` /
+   * `kill()` / `output()` plus sandbox extensions) and exposes
+   * `.output()` / `.text()` / `.json()` / `.kill()` directly for the
+   * common "run a command" case:
+   *
+   * @example
+   * // Buffered result
+   * const { stdout } = await sandbox.exec("npm test").output();
+   *
+   * @example
+   * // Long-running, with re-attach by id
+   * const dev = await sandbox.exec("npm run dev", { processId: "dev" });
+   * await dev.waitForPort(3000);
+   *
+   * @example
+   * // Stream stdout straight to the client
+   * const proc = await sandbox.exec(["python", "train.py"]);
+   * return new Response(proc.stdout);
+   */
+  exec(command: string | string[], options?: SandboxExecOptions): SandboxProcessPromise;
+  /**
+   * Buffered, session-state-preserving execution helper.
+   *
+   * Uses the foreground session execution path, so shell state changes
+   * (`cd`, aliases, functions, exports) persist across calls. Prefer
+   * `exec()` for the containers-compatible process handle; use `run()`
+   * when you explicitly want buffered session-shell semantics.
+   */
+  run(command: string, options?: ExecOptions & {
+    sessionId?: string;
+  }): Promise<ExecResult>;
+  /**
+   * Re-attach to an existing process by id.
+   *
+   * The returned `SandboxProcess`'s `stdin` is `null` and `stdout`/`stderr`
+   * are replay-then-tail streams sourced from the per-process log file.
+   * Mirrors `ExecProcess` ownership semantics where a non-owner has
+   * nullable pipes.
+   *
+   * Returns `null` if no such process exists.
+   */
+  getProcess(id: string, options?: ProcessQueryOptions): Promise<SandboxProcess | null>;
+  /**
+   * Snapshot of all known processes.
+   *
+   * Snapshot entries have `stdin`/`stdout`/`stderr` set to `null`; call
+   * `getProcess(id)` to acquire a re-attached handle with live streams.
+   */
+  listProcesses(options?: ProcessQueryOptions): Promise<SandboxProcess[]>;
+  killAllProcesses(): Promise<number>;
+  cleanupCompletedProcesses(): Promise<number>;
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+    encoding?: string;
+  }): Promise<WriteFileResult>;
+  readFile(path: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
+  readFile(path: string, options?: {
+    encoding?: Exclude<FileEncoding, 'none'>;
+  }): Promise<ReadFileResult>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
+  checkChanges(path: string, options?: CheckChangesOptions): Promise<CheckChangesResult>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<MkdirResult>;
+  deleteFile(path: string): Promise<DeleteFileResult>;
+  renameFile(oldPath: string, newPath: string): Promise<RenameFileResult>;
+  moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
+  listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string, options?: {
+    sessionId?: string;
+  }): Promise<FileExistsResult>;
+  setEnvVars(envVars: Record<string, string | undefined>): Promise<void>;
+  mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+  unmountBucket(mountPath: string): Promise<void>;
+  createSession(options?: SessionOptions): Promise<ExecutionSession>;
+  deleteSession(sessionId: string): Promise<SessionDeleteResult>;
+  /**
+   * Returns the Cloudflare placement ID observed during the most recent
+   * session-create handshake with the container. `null` when the container
+   * does not expose `CLOUDFLARE_PLACEMENT_ID` (local development). `undefined`
+   * when no handshake has been observed yet on this sandbox.
+   */
+  getContainerPlacementId(): Promise<string | null | undefined>;
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
+  wsConnect(request: Request, port: number): Promise<Response>;
+}
+declare function isExecResult(value: any): value is ExecResult;
+declare function isProcess(value: any): value is Process;
+declare function isProcessStatus(value: string): value is ProcessStatus;
+//#endregion
+//#region ../shared/dist/request-types.d.ts
+/**
+ * Result for a single uploaded part (ETag returned by R2).
+ */
+interface UploadedPart {
+  partNumber: number;
+  etag: string;
+}
+/**
+ * Response after the container has uploaded all parts.
+ */
+interface UploadPartsResponse {
+  success: boolean;
+  parts: UploadedPart[];
+}
+/**
+ * Response from the container after creating a backup archive
+ */
+interface CreateBackupResponse {
+  success: boolean;
+  /** Size of the archive in bytes */
+  sizeBytes: number;
+  /** Path to the archive file in the container */
+  archivePath: string;
+}
+/**
+ * Response from the container after restoring a backup
+ */
+interface RestoreBackupResponse {
+  success: boolean;
+  /** Directory that was restored */
+  dir: string;
+}
+//#endregion
+//#region ../shared/dist/rpc-types.d.ts
+interface SandboxAPI {
+  commands: SandboxCommandsAPI;
+  files: SandboxFilesAPI;
+  processes: SandboxProcessesAPI;
+  ports: SandboxPortsAPI;
+  utils: SandboxUtilsAPI;
+  backup: SandboxBackupAPI;
+  watch: SandboxWatchAPI;
+  tunnels: SandboxTunnelsAPI;
+  terminals: SandboxTerminalsAPI;
+  extensions: SandboxExtensionsAPI;
+}
+interface CommandExecuteOptions {
+  sessionId?: string;
+  timeoutMs?: number;
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  origin?: 'user' | 'internal';
+}
+interface SandboxCommandsAPI {
+  execute(command: string, options?: CommandExecuteOptions): Promise<{
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string;
+    timestamp: string;
+  }>;
+}
+interface FileSessionOptions {
+  sessionId?: string;
+}
+interface ReadFileStreamOptions extends FileSessionOptions {}
+interface ReadFileBinaryOptions extends FileSessionOptions {
+  encoding: 'none';
+}
+interface ReadFileOptions extends FileSessionOptions {
+  encoding?: Exclude<FileEncoding, 'none'>;
+}
+interface WriteFileOptions extends FileSessionOptions {
+  encoding?: string;
+  permissions?: string;
+}
+interface MkdirOptions extends FileSessionOptions {
+  recursive?: boolean;
+}
+interface SandboxFilesAPI {
+  readFile(path: string, options: ReadFileBinaryOptions): Promise<ReadFileStreamResult>;
+  readFile(path: string, options?: ReadFileOptions): Promise<ReadFileResult>;
+  readFileStream(path: string, options?: ReadFileStreamOptions): Promise<ReadableStream<Uint8Array>>;
+  writeFile(path: string, content: string, options?: WriteFileOptions): Promise<WriteFileResult>;
+  writeFileStream(path: string, stream: ReadableStream<Uint8Array>, options?: FileSessionOptions): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  }>;
+  deleteFile(path: string, options?: FileSessionOptions): Promise<DeleteFileResult>;
+  renameFile(oldPath: string, newPath: string, options?: FileSessionOptions): Promise<RenameFileResult>;
+  moveFile(sourcePath: string, destinationPath: string, options?: FileSessionOptions): Promise<MoveFileResult>;
+  mkdir(path: string, options?: MkdirOptions): Promise<MkdirResult>;
+  listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string, options?: FileSessionOptions): Promise<FileExistsResult>;
+}
+interface ProcessStartOptions {
+  sessionId?: string;
+  processId?: string;
+  timeoutMs?: number;
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  encoding?: string;
+  autoCleanup?: boolean;
+  origin?: 'user' | 'internal';
+  stdout?: 'pipe' | 'ignore';
+  stderr?: 'pipe' | 'ignore' | 'combined';
+}
+interface SandboxProcessesAPI {
+  startProcess(command: string, options?: ProcessStartOptions, stdin?: ReadableStream<Uint8Array>): Promise<ProcessStartResult>;
+  listProcesses(): Promise<ProcessListResult>;
+  getProcess(id: string): Promise<ProcessInfoResult>;
+  killProcess(id: string, signal?: number): Promise<ProcessKillResult>;
+  killAllProcesses(): Promise<ProcessCleanupResult>;
+  getProcessLogs(id: string): Promise<ProcessLogsResult>;
+  streamProcessLogs(id: string): Promise<ReadableStream<Uint8Array>>;
+}
+interface SandboxPortsAPI {
+  watchPort(request: PortWatchRequest): Promise<ReadableStream<Uint8Array>>;
+}
+interface SessionCreateOptions {
+  id: string;
+  env?: Record<string, string | undefined>;
+  cwd?: string;
+  commandTimeoutMs?: number;
+}
+interface SandboxUtilsAPI {
+  ping(): Promise<string>;
+  getVersion(): Promise<string>;
+  getCommands(): Promise<string[]>;
+  createSession(options: SessionCreateOptions): Promise<{
+    success: boolean;
+    id: string;
+    message: string;
+    timestamp: string;
+    containerPlacementId?: string | null;
+  }>;
+  deleteSession(sessionId: string): Promise<{
+    success: boolean;
+    sessionId: string;
+    timestamp: string;
+  }>;
+  listSessions(): Promise<{
+    sessions: string[];
+  }>;
+}
+interface BackupCreateArchiveOptions {
+  sessionId?: string;
+  excludes?: string[];
+  gitignore?: boolean;
+  compression?: BackupCompressionOptions;
+}
+interface BackupRestoreArchiveOptions {
+  sessionId?: string;
+}
+interface SandboxBackupAPI {
+  createArchive(dir: string, archivePath: string, options?: BackupCreateArchiveOptions): Promise<CreateBackupResponse>;
+  restoreArchive(dir: string, archivePath: string, options?: BackupRestoreArchiveOptions): Promise<RestoreBackupResponse>;
+  uploadParts(request: {
+    archivePath: string;
+    parts: Array<{
+      partNumber: number;
+      url: string;
+      offset: number;
+      size: number;
+    }>;
+    sessionId?: string;
+  }): Promise<UploadPartsResponse>;
+}
+interface SandboxWatchAPI {
+  watch(request: WatchRequest): Promise<ReadableStream<Uint8Array>>;
+  checkChanges(request: CheckChangesRequest): Promise<CheckChangesResult>;
+}
+/**
+ * Public-facing tunnel record. Discriminated on the presence of `name`:
+ * quick tunnels (`*.trycloudflare.com`) omit it, named tunnels carry the
+ * label that was passed to `get(port, { name })`.
+ */
+type TunnelInfo = QuickTunnelInfo | NamedTunnelInfo;
+interface QuickTunnelInfo {
+  id: string;
+  port: number;
+  /** `https://<random>.trycloudflare.com`. */
+  url: string;
+  /** Hostname portion of `url`. */
+  hostname: string;
+  createdAt: string;
+  /** Absent on quick tunnels; narrows the union. */
+  name?: never;
+}
+interface NamedTunnelInfo {
+  /** Cloudflare tunnel UUID (8-4-4-4-12). */
+  id: string;
+  port: number;
+  /** `https://<hostname>`. */
+  url: string;
+  /** Full hostname bound to the tunnel (without scheme). */
+  hostname: string;
+  createdAt: string;
+  /** Label originally passed via `TunnelOptions.name`. */
+  name: string;
+}
+/**
+ * Options accepted by `sandbox.tunnels.get(port, options)`. Omitting
+ * `name` (or omitting the options object) selects the zero-config quick
+ * tunnel; setting `name` selects the named-tunnel flow.
+ */
+interface TunnelOptions {
+  /**
+   * Single DNS label under the configured zone. The full hostname is
+   * `<name>.<zone-name>`. See `validateTunnelName` for the format rules.
+   */
+  name?: string;
+}
+type TunnelRunMode = 'quick' | 'named';
+interface TunnelRunIdentity {
+  tunnelId: string;
+  runId: string;
+}
+type TunnelRunRef = TunnelRunIdentity;
+interface EnsureQuickTunnelRunRequest extends TunnelRunIdentity {
+  mode: 'quick';
+  port: number;
+  readyTimeoutMs?: number;
+  stopGraceMs?: number;
+}
+interface EnsureNamedTunnelRunRequest extends TunnelRunIdentity {
+  mode: 'named';
+  port: number;
+  cloudflaredToken: string;
+  readyTimeoutMs?: number;
+  stopGraceMs?: number;
+}
+type EnsureTunnelRunRequest = EnsureQuickTunnelRunRequest | EnsureNamedTunnelRunRequest;
+interface QuickTunnelRunSnapshot extends TunnelRunIdentity {
+  mode: 'quick';
+  port: number;
+  url: string;
+  hostname: string;
+  startedAt: string;
+}
+interface NamedTunnelRunSnapshot extends TunnelRunIdentity {
+  mode: 'named';
+  port: number;
+  startedAt: string;
+}
+type TunnelRunSnapshot = QuickTunnelRunSnapshot | NamedTunnelRunSnapshot;
+interface EnsureTunnelRunResult {
+  run: TunnelRunSnapshot;
+  started: boolean;
+}
+type StopTunnelRunRequest = TunnelRunRef;
+interface StopTunnelRunResult {
+  stopped: boolean;
+}
+interface TunnelRunExitEvent extends TunnelRunIdentity {
+  mode: TunnelRunMode;
+  port: number;
+  exitCode: number | null;
+}
+interface SandboxTerminalsAPI {
+  createTerminal(options: TerminalCreateOptions): Promise<{
+    success: true;
+    id: string;
+  }>;
+  destroyTerminal(id: string): Promise<{
+    success: true;
+    id: string;
+  }>;
+}
+interface SandboxTunnelsAPI {
+  /** Ensure a runtime-local cloudflared process for a DO-issued run id. */
+  ensureTunnelRun(request: EnsureTunnelRunRequest): Promise<EnsureTunnelRunResult>;
+  /** Stop the matching runtime-local cloudflared process. */
+  stopTunnelRun(request: StopTunnelRunRequest): Promise<StopTunnelRunResult>;
+}
+/**
+ * Author-facing description of a sidecar extension. An extension is an
+ * npm-style package: an `.tgz` whose embedded `package.json` declares the
+ * sidecar entrypoint (via `bin`) and any extension metadata (under the
+ * `sandboxExtension` key).
+ *
+ * The SDK ships the tarball bytes; the container hashes them, provisions a
+ * dedicated directory keyed by content hash, derives identity from the
+ * embedded `package.json`, installs the package with `bun add`, and spawns
+ * the declared bin under Bun.
+ *
+ * `ExtensionPackage` carries tarball bytes produced by an extension build.
+ * The SDK sends those bytes only when the container has not provisioned the
+ * package hash yet.
+ */
+interface ExtensionPackage {
+  /** Raw `.tgz` bytes. */
+  tarball: Uint8Array;
+  /**
+   * Bin entry to run when the embedded `package.json` declares more than one.
+   * Defaults to the value of `sandboxExtension.bin` in `package.json`, then
+   * to the single bin entry if there is exactly one.
+   */
+  bin?: string;
+  /**
+   * Max time to wait for the sidecar to accept a capnweb connection on its
+   * unix socket. Falls back to `sandboxExtension.readinessTimeoutMs` in
+   * `package.json`, then to a host default.
+   */
+  readinessTimeoutMs?: number;
+  /**
+   * Run lifecycle scripts during `bun add`. Defaults to false — provisioning
+   * happens before the sidecar is supervised, so install-time side effects
+   * are deliberately opt-in.
+   */
+  allowInstallScripts?: boolean;
+}
+/** Health snapshot for a provisioned extension. */
+interface ExtensionHealth {
+  packageHash: string;
+  id: string;
+  version: string;
+  /** Tarball is on disk and the package.json has been read. */
+  provisioned: boolean;
+  /** Sidecar process is currently running. */
+  running: boolean;
+  pid: number | null;
+  /** Whether a `__ping__` round-tripped over capnweb. */
+  responsive: boolean;
+}
+/**
+ * Connect request payload. The SDK hashes the tarball locally and first sends
+ * only the hash. If the current host process has not provisioned that hash,
+ * it responds with an `ExtensionTarballRequired` error and the SDK retries
+ * with `tarball` populated.
+ */
+interface ExtensionConnectRequest {
+  packageHash: string;
+  /** Only sent when the host has not seen this hash yet. */
+  tarball?: Uint8Array;
+  bin?: string;
+  readinessTimeoutMs?: number;
+  allowInstallScripts?: boolean;
+}
+/**
+ * Control surface for container sidecar extensions.
+ *
+ * `connect` is the only entry point: it provisions on first use, supervises
+ * lazily, and returns the sidecar's capnweb remote main as a stub. Calls on
+ * the stub are proxied through the container's capnweb session to the
+ * sidecar's capnweb session — callback parameters (including streaming
+ * handlers) round-trip across both hops.
+ */
+interface SandboxExtensionsAPI {
+  /**
+   * Provision the package (if new) and return the sidecar's typed remote
+   * main. The result is a capnweb stub whose methods correspond to the
+   * sidecar's `RpcTarget` surface.
+   */
+  connect(req: ExtensionConnectRequest): Promise<unknown>;
+  /** Health snapshot, probing the sidecar with a `__ping__` when running. */
+  health(packageHash: string): Promise<ExtensionHealth>;
+  /** Stop a sidecar and release its capnweb session. */
+  stop(packageHash: string): Promise<void>;
+}
+/**
+ * RPC surface the Sandbox DO exposes to the container over the existing
+ * capnweb session. The container reaches it via
+ * `session.getRemoteMain<SandboxControlCallback>()` and invokes methods
+ * to push control-plane events (today: tunnel exits) back to the DO.
+ *
+ * One stable target per sandbox; not per-tunnel. Reusable seam for
+ * future container→DO events.
+ */
+interface SandboxControlCallback {
+  /** Called by the container when a runtime-local tunnel run exits. */
+  onTunnelRunExit(event: TunnelRunExitEvent): Promise<void>;
+}
+//#endregion
+//#region src/extensions/index.d.ts
+interface HTTPAuthHostConfig {
+  token: string;
+  username?: string;
+  type?: 'basic' | 'bearer';
+}
+interface HTTPAuthInterceptorParams {
+  hosts: Record<string, HTTPAuthHostConfig>;
+}
+/**
+ * The slice of the Sandbox an extension captures: its control `client`, unified
+ * `exec()` surface, and sandbox-level environment variables. Narrow on purpose
+ * \u2014 an extension never holds the whole instance.
+ *
+ * `envVars` mirrors what the Sandbox applies to sessionless execution, so an
+ * extension that drives commands through `client` directly can still honour
+ * sandbox-level env (tokens, proxy settings) without an explicit session.
+ */
+type SandboxLike = {
+  readonly client: SandboxAPI;
+  readonly exec?: (command: string | string[], options?: SandboxExecOptions) => SandboxProcessPromise;
+  readonly envVars?: Record<string, string>;
+  registerGitAuthInterceptor?: (params: HTTPAuthInterceptorParams) => Promise<void>;
+};
+/**
+ * The one base class for *every* extension.
+ *
+ * - SDK-only: just drives existing sub-APIs.
+ * - Sidecar: pass an {@link ExtensionPackage} to `super(sandbox, pkg)` and
+ *   call `this.sidecar<T>()` to get a typed capnweb stub of the sidecar.
+ *
+ * The sidecar accessor throws a clear error if no package was supplied, so an
+ * extension only "becomes" a sidecar extension when it opts in.
+ *
+ * ```ts
+ * // SDK-only
+ * class Git extends SandboxExtension {
+ *   constructor(s: SandboxLike) { super(s); }
+ *   async status(sid: string) {
+ *     return this.exec('git status', { sessionId: sid }).output();
+ *   }
+ * }
+ *
+ * // Sidecar
+ * import sidecarTarballBytes from './sidecar-package.tgz';
+ * import type { MyAPI } from './shared';
+ *
+ * class MyExt extends SandboxExtension {
+ *   constructor(s: SandboxLike) { super(s, { tarball: new Uint8Array(sidecarTarballBytes) }); }
+ *   async run(input: string): Promise<string> {
+ *     const api = await this.sidecar<MyAPI>();
+ *     return api.run(input);
+ *   }
+ * }
+ * ```
+ *
+ * RPC-safety: the sandbox lives in `#sandbox` and is reached only through the
+ * `protected` `client` getter (a prototype accessor, not an own property),
+ * so it is never serialised across RPC. Only the public methods you add form
+ * the extension's RPC surface.
+ */
+declare abstract class SandboxExtension extends RpcTarget {
+  #private;
+  protected constructor(sandbox: SandboxLike, pkg?: ExtensionPackage);
+  /** The container control client. Use inside your own methods, lazily. */
+  protected get client(): SandboxAPI;
+  /** Unified process-handle exec surface from the owning Sandbox. */
+  protected exec(command: string | string[], options?: SandboxExecOptions): SandboxProcessPromise;
+  /**
+   * Sandbox-level environment variables. Apply these to sessionless execution
+   * so commands driven straight through `client` still inherit sandbox env
+   * (tokens, proxy settings) the way the Sandbox's own sessionless path does.
+   */
+  protected get envVars(): Record<string, string>;
+  protected get httpAuthInterceptor(): ((params: HTTPAuthInterceptorParams) => Promise<void>) | undefined;
+  /**
+   * Return the sidecar's capnweb remote main, provisioning + spawning on
+   * demand. `T` is the typed interface the sidecar exposes (its
+   * `SandboxSidecar` subclass shape). Each call reconnects through the host
+   * so a crashed sidecar can be restarted transparently on the next use.
+   *
+   * Streaming is just a method that takes a callback parameter: capnweb
+   * stubs the callback and routes invocations back through the SDK\u2192container
+   * \u2192sidecar hops.
+   */
+  protected sidecar<T extends object>(): Promise<T>;
+  /** Health snapshot for this extension's sidecar. */
+  protected sidecarHealth(): Promise<ExtensionHealth>;
+  /**
+   * Stop this extension's sidecar. The next `sidecar()` call will respawn on
+   * demand.
+   */
+  protected stopSidecar(): Promise<void>;
+}
+//#endregion
+export { ReadFileStreamResult as $, ExecEvent as A, ISandbox as B, BaseExecOptions as C, CheckChangesResult as D, CheckChangesOptions as E, FileEncoding as F, MkdirResult as G, ListFilesResult as H, FileExistsResult as I, Process as J, MountBucketOptions as K, FileMetadata as L, ExecResult as M, ExecutionSession as N, DeleteFileResult as O, FileChunk as P, ReadFileResult as Q, FileStreamEvent as R, BackupOptions as S, BucketProvider as T, LocalMountBucketOptions as U, ListFilesOptions as V, LogEvent as W, ProcessQueryOptions as X, ProcessOptions as Y, ProcessStatus as Z, SandboxTunnelsAPI as _, PtyOptions as _t, ExtensionHealth as a, SandboxOptions as at, TunnelInfo as b, TerminalCreateOptions as bt, QuickTunnelInfo as c, SessionDeleteResult as ct, SandboxControlCallback as d, WaitForPortOptions as dt, RemoteMountBucketOptions as et, SandboxExtensionsAPI as f, WatchOptions as ft, SandboxTerminalsAPI as g, isProcessStatus as gt, SandboxProcessesAPI as h, isProcess as ht, SandboxLike as i, SandboxExecOutput as it, ExecOptions as j, DirectoryBackup as k, SandboxBackupAPI as l, SessionOptions as lt, SandboxPortsAPI as m, isExecResult as mt, HTTPAuthInterceptorParams as n, RestoreBackupResult as nt, ExtensionPackage as o, SandboxProcess as ot, SandboxFilesAPI as p, WriteFileResult as pt, MoveFileResult as q, SandboxExtension as r, SandboxExecOptions as rt, NamedTunnelInfo as s, SandboxProcessPromise as st, HTTPAuthHostConfig as t, RenameFileResult as tt, SandboxCommandsAPI as u, WaitForLogResult as ut, SandboxUtilsAPI as v, SandboxTerminal as vt, BucketCredentials as w, TunnelOptions as x, TerminalOptions as xt, SandboxWatchAPI as y, TerminalConnectOptions as yt, FileWatchSSEEvent as z };
+//# sourceMappingURL=index-B7QgIs0N.d.ts.map