@cloudflare/sandbox 0.5.1 → 0.5.3

package/dist/sandbox-HQazw9bn.d.ts

@@ -0,0 +1,1741 @@
+import { Container } from "@cloudflare/containers";
+
+//#region ../shared/dist/logger/types.d.ts
+
+type LogComponent = 'container' | 'sandbox-do' | 'executor';
+/**
+ * Context metadata included in every log entry
+ */
+interface LogContext {
+  /**
+   * Unique trace ID for request correlation across distributed components
+   * Format: "tr_" + 16 hex chars (e.g., "tr_7f3a9b2c4e5d6f1a")
+   */
+  traceId: string;
+  /**
+   * Component that generated the log
+   */
+  component: LogComponent;
+  /**
+   * Sandbox identifier (which sandbox instance)
+   */
+  sandboxId?: string;
+  /**
+   * Session identifier (which session within sandbox)
+   */
+  sessionId?: string;
+  /**
+   * Process identifier (which background process)
+   */
+  processId?: string;
+  /**
+   * Command identifier (which command execution)
+   */
+  commandId?: string;
+  /**
+   * Operation name (e.g., 'exec', 'startProcess', 'writeFile')
+   */
+  operation?: string;
+  /**
+   * Duration in milliseconds
+   */
+  duration?: number;
+  /**
+   * Extensible for additional metadata
+   */
+  [key: string]: unknown;
+}
+/**
+ * Logger interface for structured logging
+ *
+ * All methods accept optional context that gets merged with the logger's base context.
+ */
+interface Logger {
+  /**
+   * Log debug-level message (most verbose, typically disabled in production)
+   *
+   * @param message Human-readable message
+   * @param context Optional additional context
+   */
+  debug(message: string, context?: Partial<LogContext>): void;
+  /**
+   * Log info-level message (normal operational events)
+   *
+   * @param message Human-readable message
+   * @param context Optional additional context
+   */
+  info(message: string, context?: Partial<LogContext>): void;
+  /**
+   * Log warning-level message (recoverable issues, degraded state)
+   *
+   * @param message Human-readable message
+   * @param context Optional additional context
+   */
+  warn(message: string, context?: Partial<LogContext>): void;
+  /**
+   * Log error-level message (failures, exceptions)
+   *
+   * @param message Human-readable message
+   * @param error Optional Error object to include
+   * @param context Optional additional context
+   */
+  error(message: string, error?: Error, context?: Partial<LogContext>): void;
+  /**
+   * Create a child logger with additional context
+   *
+   * The child logger inherits all context from the parent and adds new context.
+   * This is useful for adding operation-specific context without passing through parameters.
+   *
+   * @param context Additional context to merge
+   * @returns New logger instance with merged context
+   *
+   * @example
+   * const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc123' });
+   * const execLogger = logger.child({ operation: 'exec', commandId: 'cmd-456' });
+   * execLogger.info('Command started'); // Includes all context: component, traceId, operation, commandId
+   */
+  child(context: Partial<LogContext>): Logger;
+}
+//#endregion
+//#region ../shared/dist/interpreter-types.d.ts
+interface CreateContextOptions {
+  /**
+   * Programming language for the context
+   * @default 'python'
+   */
+  language?: 'python' | 'javascript' | 'typescript';
+  /**
+   * Working directory for the context
+   * @default '/workspace'
+   */
+  cwd?: string;
+  /**
+   * Environment variables for the context
+   */
+  envVars?: Record<string, string>;
+  /**
+   * Request timeout in milliseconds
+   * @default 30000
+   */
+  timeout?: number;
+}
+interface CodeContext {
+  /**
+   * Unique identifier for the context
+   */
+  readonly id: string;
+  /**
+   * Programming language of the context
+   */
+  readonly language: string;
+  /**
+   * Current working directory
+   */
+  readonly cwd: string;
+  /**
+   * When the context was created
+   */
+  readonly createdAt: Date;
+  /**
+   * When the context was last used
+   */
+  readonly lastUsed: Date;
+}
+interface RunCodeOptions {
+  /**
+   * Context to run the code in. If not provided, uses default context for the language
+   */
+  context?: CodeContext;
+  /**
+   * Language to use if context is not provided
+   * @default 'python'
+   */
+  language?: 'python' | 'javascript' | 'typescript';
+  /**
+   * Environment variables for this execution
+   */
+  envVars?: Record<string, string>;
+  /**
+   * Execution timeout in milliseconds
+   * @default 60000
+   */
+  timeout?: number;
+  /**
+   * AbortSignal for cancelling execution
+   */
+  signal?: AbortSignal;
+  /**
+   * Callback for stdout output
+   */
+  onStdout?: (output: OutputMessage) => void | Promise<void>;
+  /**
+   * Callback for stderr output
+   */
+  onStderr?: (output: OutputMessage) => void | Promise<void>;
+  /**
+   * Callback for execution results (charts, tables, etc)
+   */
+  onResult?: (result: Result) => void | Promise<void>;
+  /**
+   * Callback for execution errors
+   */
+  onError?: (error: ExecutionError) => void | Promise<void>;
+}
+interface OutputMessage {
+  /**
+   * The output text
+   */
+  text: string;
+  /**
+   * Timestamp of the output
+   */
+  timestamp: number;
+}
+interface Result {
+  /**
+   * Plain text representation
+   */
+  text?: string;
+  /**
+   * HTML representation (tables, formatted output)
+   */
+  html?: string;
+  /**
+   * PNG image data (base64 encoded)
+   */
+  png?: string;
+  /**
+   * JPEG image data (base64 encoded)
+   */
+  jpeg?: string;
+  /**
+   * SVG image data
+   */
+  svg?: string;
+  /**
+   * LaTeX representation
+   */
+  latex?: string;
+  /**
+   * Markdown representation
+   */
+  markdown?: string;
+  /**
+   * JavaScript code to execute
+   */
+  javascript?: string;
+  /**
+   * JSON data
+   */
+  json?: any;
+  /**
+   * Chart data if the result is a visualization
+   */
+  chart?: ChartData;
+  /**
+   * Raw data object
+   */
+  data?: any;
+  /**
+   * Available output formats
+   */
+  formats(): string[];
+}
+interface ChartData {
+  /**
+   * Type of chart
+   */
+  type: 'line' | 'bar' | 'scatter' | 'pie' | 'histogram' | 'heatmap' | 'unknown';
+  /**
+   * Chart title
+   */
+  title?: string;
+  /**
+   * Chart data (format depends on library)
+   */
+  data: any;
+  /**
+   * Chart layout/configuration
+   */
+  layout?: any;
+  /**
+   * Additional configuration
+   */
+  config?: any;
+  /**
+   * Library that generated the chart
+   */
+  library?: 'matplotlib' | 'plotly' | 'altair' | 'seaborn' | 'unknown';
+  /**
+   * Base64 encoded image if available
+   */
+  image?: string;
+}
+interface ExecutionError {
+  /**
+   * Error name/type (e.g., 'NameError', 'SyntaxError')
+   */
+  name: string;
+  /**
+   * Error message
+   */
+  message: string;
+  /**
+   * Stack trace
+   */
+  traceback: string[];
+  /**
+   * Line number where error occurred
+   */
+  lineNumber?: number;
+}
+interface ExecutionResult {
+  code: string;
+  logs: {
+    stdout: string[];
+    stderr: string[];
+  };
+  error?: ExecutionError;
+  executionCount?: number;
+  results: Array<{
+    text?: string;
+    html?: string;
+    png?: string;
+    jpeg?: string;
+    svg?: string;
+    latex?: string;
+    markdown?: string;
+    javascript?: string;
+    json?: any;
+    chart?: ChartData;
+    data?: any;
+  }>;
+}
+declare class Execution {
+  readonly code: string;
+  readonly context: CodeContext;
+  /**
+   * All results from the execution
+   */
+  results: Result[];
+  /**
+   * Accumulated stdout and stderr
+   */
+  logs: {
+    stdout: string[];
+    stderr: string[];
+  };
+  /**
+   * Execution error if any
+   */
+  error?: ExecutionError;
+  /**
+   * Execution count (for interpreter)
+   */
+  executionCount?: number;
+  constructor(code: string, context: CodeContext);
+  /**
+   * Convert to a plain object for serialization
+   */
+  toJSON(): ExecutionResult;
+}
+//#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.
+   */
+  env?: Record<string, string>;
+  /**
+   * Working directory for command execution
+   */
+  cwd?: string;
+  /**
+   * Text encoding for output (default: 'utf8')
+   */
+  encoding?: string;
+}
+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;
+}
+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;
+}
+interface ProcessOptions extends BaseExecOptions {
+  /**
+   * 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';
+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;
+  }>;
+}
+interface ExecEvent {
+  type: 'start' | 'stdout' | 'stderr' | 'complete' | 'error';
+  timestamp: string;
+  data?: string;
+  command?: string;
+  exitCode?: number;
+  result?: ExecResult;
+  error?: string;
+  sessionId?: string;
+}
+interface LogEvent {
+  type: 'stdout' | 'stderr' | 'exit' | 'error';
+  timestamp: string;
+  data: string;
+  processId: string;
+  sessionId?: string;
+  exitCode?: number;
+}
+interface StreamOptions extends BaseExecOptions {
+  /**
+   * Buffer size for streaming output
+   */
+  bufferSize?: number;
+  /**
+   * AbortSignal for cancelling stream
+   */
+  signal?: AbortSignal;
+}
+interface SessionOptions {
+  /**
+   * Optional session ID (auto-generated if not provided)
+   */
+  id?: string;
+  /**
+   * Session name for identification
+   */
+  name?: string;
+  /**
+   * Environment variables for this session
+   */
+  env?: Record<string, string>;
+  /**
+   * Working directory
+   */
+  cwd?: string;
+  /**
+   * Enable PID namespace isolation (requires CAP_SYS_ADMIN)
+   */
+  isolation?: boolean;
+}
+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;
+  /**
+   * Base URL for the sandbox API
+   */
+  baseUrl?: string;
+  /**
+   * 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;
+  /**
+   * 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 1000 (1s) - 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;
+}
+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;
+}
+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;
+}
+interface ListFilesResult {
+  success: boolean;
+  path: string;
+  files: FileInfo[];
+  count: number;
+  timestamp: string;
+  exitCode?: number;
+}
+interface GitCheckoutResult {
+  success: boolean;
+  repoUrl: string;
+  branch: string;
+  targetDir: string;
+  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;
+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;
+  }>;
+  timestamp: string;
+}
+interface ProcessInfoResult {
+  success: boolean;
+  process: {
+    id: string;
+    pid?: number;
+    command: string;
+    status: ProcessStatus;
+    startTime: string;
+    endTime?: string;
+    exitCode?: number;
+  };
+  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;
+  cleanedCount: number;
+  timestamp: string;
+}
+interface SessionDeleteResult {
+  success: boolean;
+  sessionId: string;
+  timestamp: string;
+}
+interface PortExposeResult {
+  success: boolean;
+  port: number;
+  url: string;
+  timestamp: string;
+}
+interface PortListResult {
+  success: boolean;
+  ports: Array<{
+    port: number;
+    url: string;
+    status: 'active' | 'inactive';
+  }>;
+  timestamp: string;
+}
+interface PortCloseResult {
+  success: boolean;
+  port: number;
+  timestamp: string;
+}
+interface ExecutionSession {
+  /** Unique session identifier */
+  readonly id: string;
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
+  startProcess(command: string, options?: ProcessOptions): Promise<Process>;
+  listProcesses(): Promise<Process[]>;
+  getProcess(id: string): Promise<Process | null>;
+  killProcess(id: string, signal?: string): Promise<void>;
+  killAllProcesses(): Promise<number>;
+  cleanupCompletedProcesses(): Promise<number>;
+  getProcessLogs(id: string): Promise<{
+    stdout: string;
+    stderr: string;
+    processId: string;
+  }>;
+  streamProcessLogs(processId: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<ReadableStream<Uint8Array>>;
+  writeFile(path: string, content: string, options?: {
+    encoding?: string;
+  }): Promise<WriteFileResult>;
+  readFile(path: string, options?: {
+    encoding?: string;
+  }): Promise<ReadFileResult>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  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>;
+  gitCheckout(repoUrl: string, options?: {
+    branch?: string;
+    targetDir?: string;
+  }): Promise<GitCheckoutResult>;
+  setEnvVars(envVars: Record<string, string>): Promise<void>;
+  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
+  runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream<Uint8Array>>;
+  listCodeContexts(): Promise<CodeContext[]>;
+  deleteCodeContext(contextId: string): Promise<void>;
+  mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+  unmountBucket(mountPath: string): Promise<void>;
+}
+/**
+ * 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
+ */
+interface MountBucketOptions {
+  /**
+   * 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'
+   *
+   * Required field
+   */
+  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[];
+}
+interface ISandbox {
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  startProcess(command: string, options?: ProcessOptions): Promise<Process>;
+  listProcesses(): Promise<Process[]>;
+  getProcess(id: string): Promise<Process | null>;
+  killProcess(id: string, signal?: string): Promise<void>;
+  killAllProcesses(): Promise<number>;
+  execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
+  streamProcessLogs(processId: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<ReadableStream<Uint8Array>>;
+  cleanupCompletedProcesses(): Promise<number>;
+  getProcessLogs(id: string): Promise<{
+    stdout: string;
+    stderr: string;
+    processId: string;
+  }>;
+  writeFile(path: string, content: string, options?: {
+    encoding?: string;
+  }): Promise<WriteFileResult>;
+  readFile(path: string, options?: {
+    encoding?: string;
+  }): Promise<ReadFileResult>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  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, sessionId?: string): Promise<FileExistsResult>;
+  gitCheckout(repoUrl: string, options?: {
+    branch?: string;
+    targetDir?: string;
+  }): Promise<GitCheckoutResult>;
+  setEnvVars(envVars: Record<string, string>): 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>;
+  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
+  runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
+  listCodeContexts(): Promise<CodeContext[]>;
+  deleteCodeContext(contextId: string): Promise<void>;
+  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 src/clients/types.d.ts
+/**
+ * Minimal interface for container fetch functionality
+ */
+interface ContainerStub {
+  containerFetch(url: string, options: RequestInit, port?: number): Promise<Response>;
+}
+/**
+ * Shared HTTP client configuration options
+ */
+interface HttpClientOptions {
+  logger?: Logger;
+  baseUrl?: string;
+  port?: number;
+  stub?: ContainerStub;
+  onCommandComplete?: (success: boolean, exitCode: number, stdout: string, stderr: string, command: string) => void;
+  onError?: (error: string, command?: string) => void;
+}
+/**
+ * Base response interface for all API responses
+ */
+interface BaseApiResponse {
+  success: boolean;
+  timestamp: string;
+}
+/**
+ * Legacy error response interface - deprecated, use ApiErrorResponse
+ */
+interface ErrorResponse {
+  error: string;
+  details?: string;
+  code?: string;
+}
+/**
+ * HTTP request configuration
+ */
+interface RequestConfig extends RequestInit {
+  endpoint: string;
+  data?: Record<string, any>;
+}
+/**
+ * Typed response handler
+ */
+type ResponseHandler<T> = (response: Response) => Promise<T>;
+/**
+ * Common session-aware request interface
+ */
+interface SessionRequest {
+  sessionId?: string;
+}
+//#endregion
+//#region src/clients/base-client.d.ts
+/**
+ * Abstract base class providing common HTTP functionality for all domain clients
+ */
+declare abstract class BaseHttpClient {
+  protected baseUrl: string;
+  protected options: HttpClientOptions;
+  protected logger: Logger;
+  constructor(options?: HttpClientOptions);
+  /**
+   * Core HTTP request method with automatic retry for container startup delays
+   * Retries both 503 (provisioning) and 500 (startup failure) errors when they're container-related
+   */
+  protected doFetch(path: string, options?: RequestInit): Promise<Response>;
+  /**
+   * Make a POST request with JSON body
+   */
+  protected post<T>(endpoint: string, data: unknown, responseHandler?: ResponseHandler<T>): Promise<T>;
+  /**
+   * Make a GET request
+   */
+  protected get<T>(endpoint: string, responseHandler?: ResponseHandler<T>): Promise<T>;
+  /**
+   * Make a DELETE request
+   */
+  protected delete<T>(endpoint: string, responseHandler?: ResponseHandler<T>): Promise<T>;
+  /**
+   * Handle HTTP response with error checking and parsing
+   */
+  protected handleResponse<T>(response: Response, customHandler?: ResponseHandler<T>): Promise<T>;
+  /**
+   * Handle error responses with consistent error throwing
+   */
+  protected handleErrorResponse(response: Response): Promise<never>;
+  /**
+   * Create a streaming response handler for Server-Sent Events
+   */
+  protected handleStreamResponse(response: Response): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Utility method to log successful operations
+   */
+  protected logSuccess(operation: string, details?: string): void;
+  /**
+   * Utility method to log errors intelligently
+   * Only logs unexpected errors (5xx), not expected errors (4xx)
+   *
+   * - 4xx errors (validation, not found, conflicts): Don't log (expected client errors)
+   * - 5xx errors (server failures, internal errors): DO log (unexpected server errors)
+   */
+  protected logError(operation: string, error: unknown): void;
+  /**
+   * Check if response indicates a retryable container error
+   * Uses fail-safe strategy: only retry known transient errors
+   *
+   * TODO: This relies on string matching error messages, which is brittle.
+   * Ideally, the container API should return structured errors with a
+   * `retryable: boolean` field to avoid coupling to error message format.
+   *
+   * @param response - HTTP response to check
+   * @returns true if error is retryable container error, false otherwise
+   */
+  private isRetryableContainerError;
+  private executeFetch;
+}
+//#endregion
+//#region src/clients/command-client.d.ts
+/**
+ * Response interface for command execution
+ */
+interface ExecuteResponse extends BaseApiResponse {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  command: string;
+}
+/**
+ * Client for command execution operations
+ */
+declare class CommandClient extends BaseHttpClient {
+  /**
+   * Execute a command and return the complete result
+   * @param command - The command to execute
+   * @param sessionId - The session ID for this command execution
+   * @param timeoutMs - Optional timeout in milliseconds (unlimited by default)
+   * @param env - Optional environment variables for this command
+   * @param cwd - Optional working directory for this command
+   */
+  execute(command: string, sessionId: string, options?: {
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+  }): Promise<ExecuteResponse>;
+  /**
+   * Execute a command and return a stream of events
+   * @param command - The command to execute
+   * @param sessionId - The session ID for this command execution
+   * @param options - Optional per-command execution settings
+   */
+  executeStream(command: string, sessionId: string, options?: {
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+  }): Promise<ReadableStream<Uint8Array>>;
+}
+//#endregion
+//#region src/clients/file-client.d.ts
+/**
+ * Request interface for creating directories
+ */
+interface MkdirRequest extends SessionRequest {
+  path: string;
+  recursive?: boolean;
+}
+/**
+ * Request interface for writing files
+ */
+interface WriteFileRequest extends SessionRequest {
+  path: string;
+  content: string;
+  encoding?: string;
+}
+/**
+ * Request interface for reading files
+ */
+interface ReadFileRequest extends SessionRequest {
+  path: string;
+  encoding?: string;
+}
+/**
+ * Request interface for file operations (delete, rename, move)
+ */
+interface FileOperationRequest extends SessionRequest {
+  path: string;
+  newPath?: string;
+}
+/**
+ * Client for file system operations
+ */
+declare class FileClient extends BaseHttpClient {
+  /**
+   * Create a directory
+   * @param path - Directory path to create
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (recursive)
+   */
+  mkdir(path: string, sessionId: string, options?: {
+    recursive?: boolean;
+  }): Promise<MkdirResult>;
+  /**
+   * Write content to a file
+   * @param path - File path to write to
+   * @param content - Content to write
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (encoding)
+   */
+  writeFile(path: string, content: string, sessionId: string, options?: {
+    encoding?: string;
+  }): Promise<WriteFileResult>;
+  /**
+   * Read content from a file
+   * @param path - File path to read from
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (encoding)
+   */
+  readFile(path: string, sessionId: string, options?: {
+    encoding?: string;
+  }): Promise<ReadFileResult>;
+  /**
+   * Stream a file using Server-Sent Events
+   * Returns a ReadableStream of SSE events containing metadata, chunks, and completion
+   * @param path - File path to stream
+   * @param sessionId - The session ID for this operation
+   */
+  readFileStream(path: string, sessionId: string): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Delete a file
+   * @param path - File path to delete
+   * @param sessionId - The session ID for this operation
+   */
+  deleteFile(path: string, sessionId: string): Promise<DeleteFileResult>;
+  /**
+   * Rename a file
+   * @param path - Current file path
+   * @param newPath - New file path
+   * @param sessionId - The session ID for this operation
+   */
+  renameFile(path: string, newPath: string, sessionId: string): Promise<RenameFileResult>;
+  /**
+   * Move a file
+   * @param path - Current file path
+   * @param newPath - Destination file path
+   * @param sessionId - The session ID for this operation
+   */
+  moveFile(path: string, newPath: string, sessionId: string): Promise<MoveFileResult>;
+  /**
+   * List files in a directory
+   * @param path - Directory path to list
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (recursive, includeHidden)
+   */
+  listFiles(path: string, sessionId: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  /**
+   * Check if a file or directory exists
+   * @param path - Path to check
+   * @param sessionId - The session ID for this operation
+   */
+  exists(path: string, sessionId: string): Promise<FileExistsResult>;
+}
+//#endregion
+//#region src/clients/git-client.d.ts
+/**
+ * Request interface for Git checkout operations
+ */
+interface GitCheckoutRequest extends SessionRequest {
+  repoUrl: string;
+  branch?: string;
+  targetDir?: string;
+}
+/**
+ * Client for Git repository operations
+ */
+declare class GitClient extends BaseHttpClient {
+  constructor(options?: HttpClientOptions);
+  /**
+   * Clone a Git repository
+   * @param repoUrl - URL of the Git repository to clone
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (branch, targetDir)
+   */
+  checkout(repoUrl: string, sessionId: string, options?: {
+    branch?: string;
+    targetDir?: string;
+  }): Promise<GitCheckoutResult>;
+  /**
+   * Extract repository name from URL for default directory name
+   */
+  private extractRepoName;
+}
+//#endregion
+//#region src/clients/interpreter-client.d.ts
+interface ExecutionCallbacks {
+  onStdout?: (output: OutputMessage) => void | Promise<void>;
+  onStderr?: (output: OutputMessage) => void | Promise<void>;
+  onResult?: (result: Result) => void | Promise<void>;
+  onError?: (error: ExecutionError) => void | Promise<void>;
+}
+declare class InterpreterClient extends BaseHttpClient {
+  private readonly maxRetries;
+  private readonly retryDelayMs;
+  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  runCodeStream(contextId: string | undefined, code: string, language: string | undefined, callbacks: ExecutionCallbacks, timeoutMs?: number): Promise<void>;
+  listCodeContexts(): Promise<CodeContext[]>;
+  deleteCodeContext(contextId: string): Promise<void>;
+  /**
+   * Execute an operation with automatic retry for transient errors
+   */
+  private executeWithRetry;
+  private isRetryableError;
+  private parseErrorResponse;
+  private readLines;
+  private parseExecutionResult;
+}
+//#endregion
+//#region src/clients/port-client.d.ts
+/**
+ * Request interface for exposing ports
+ */
+interface ExposePortRequest {
+  port: number;
+  name?: string;
+}
+/**
+ * Request interface for unexposing ports
+ */
+interface UnexposePortRequest {
+  port: number;
+}
+/**
+ * Client for port management and preview URL operations
+ */
+declare class PortClient extends BaseHttpClient {
+  /**
+   * Expose a port and get a preview URL
+   * @param port - Port number to expose
+   * @param sessionId - The session ID for this operation
+   * @param name - Optional name for the port
+   */
+  exposePort(port: number, sessionId: string, name?: string): Promise<PortExposeResult>;
+  /**
+   * Unexpose a port and remove its preview URL
+   * @param port - Port number to unexpose
+   * @param sessionId - The session ID for this operation
+   */
+  unexposePort(port: number, sessionId: string): Promise<PortCloseResult>;
+  /**
+   * Get all currently exposed ports
+   * @param sessionId - The session ID for this operation
+   */
+  getExposedPorts(sessionId: string): Promise<PortListResult>;
+}
+//#endregion
+//#region src/clients/process-client.d.ts
+/**
+ * Client for background process management
+ */
+declare class ProcessClient extends BaseHttpClient {
+  /**
+   * Start a background process
+   * @param command - Command to execute as a background process
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (processId)
+   */
+  startProcess(command: string, sessionId: string, options?: {
+    processId?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    cwd?: string;
+    encoding?: string;
+    autoCleanup?: boolean;
+  }): Promise<ProcessStartResult>;
+  /**
+   * List all processes (sandbox-scoped, not session-scoped)
+   */
+  listProcesses(): Promise<ProcessListResult>;
+  /**
+   * Get information about a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to retrieve
+   */
+  getProcess(processId: string): Promise<ProcessInfoResult>;
+  /**
+   * Kill a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to kill
+   */
+  killProcess(processId: string): Promise<ProcessKillResult>;
+  /**
+   * Kill all running processes (sandbox-scoped, not session-scoped)
+   */
+  killAllProcesses(): Promise<ProcessCleanupResult>;
+  /**
+   * Get logs from a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to get logs from
+   */
+  getProcessLogs(processId: string): Promise<ProcessLogsResult>;
+  /**
+   * Stream logs from a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to stream logs from
+   */
+  streamProcessLogs(processId: string): Promise<ReadableStream<Uint8Array>>;
+}
+//#endregion
+//#region src/clients/utility-client.d.ts
+/**
+ * Response interface for ping operations
+ */
+interface PingResponse extends BaseApiResponse {
+  message: string;
+  uptime?: number;
+}
+/**
+ * Response interface for getting available commands
+ */
+interface CommandsResponse extends BaseApiResponse {
+  availableCommands: string[];
+  count: number;
+}
+/**
+ * Request interface for creating sessions
+ */
+interface CreateSessionRequest {
+  id: string;
+  env?: Record<string, string>;
+  cwd?: string;
+}
+/**
+ * Response interface for creating sessions
+ */
+interface CreateSessionResponse extends BaseApiResponse {
+  id: string;
+  message: string;
+}
+/**
+ * Request interface for deleting sessions
+ */
+interface DeleteSessionRequest {
+  sessionId: string;
+}
+/**
+ * Response interface for deleting sessions
+ */
+interface DeleteSessionResponse extends BaseApiResponse {
+  sessionId: string;
+}
+/**
+ * Client for health checks and utility operations
+ */
+declare class UtilityClient extends BaseHttpClient {
+  /**
+   * Ping the sandbox to check if it's responsive
+   */
+  ping(): Promise<string>;
+  /**
+   * Get list of available commands in the sandbox environment
+   */
+  getCommands(): Promise<string[]>;
+  /**
+   * Create a new execution session
+   * @param options - Session configuration (id, env, cwd)
+   */
+  createSession(options: CreateSessionRequest): Promise<CreateSessionResponse>;
+  /**
+   * Delete an execution session
+   * @param sessionId - Session ID to delete
+   */
+  deleteSession(sessionId: string): Promise<DeleteSessionResponse>;
+  /**
+   * Get the container version
+   * Returns the version embedded in the Docker image during build
+   */
+  getVersion(): Promise<string>;
+}
+//#endregion
+//#region src/clients/sandbox-client.d.ts
+/**
+ * Main sandbox client that composes all domain-specific clients
+ * Provides organized access to all sandbox functionality
+ */
+declare class SandboxClient {
+  readonly commands: CommandClient;
+  readonly files: FileClient;
+  readonly processes: ProcessClient;
+  readonly ports: PortClient;
+  readonly git: GitClient;
+  readonly interpreter: InterpreterClient;
+  readonly utils: UtilityClient;
+  constructor(options: HttpClientOptions);
+}
+//#endregion
+//#region src/sandbox.d.ts
+declare function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string, options?: SandboxOptions): Sandbox;
+declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
+  defaultPort: number;
+  sleepAfter: string | number;
+  client: SandboxClient;
+  private codeInterpreter;
+  private sandboxName;
+  private normalizeId;
+  private baseUrl;
+  private portTokens;
+  private defaultSession;
+  envVars: Record<string, string>;
+  private logger;
+  private keepAliveEnabled;
+  private activeMounts;
+  /**
+   * Default container startup timeouts (conservative for production)
+   * Based on Cloudflare docs: "Containers take several minutes to provision"
+   */
+  private readonly DEFAULT_CONTAINER_TIMEOUTS;
+  /**
+   * Active container timeout configuration
+   * Can be set via options, env vars, or defaults
+   */
+  private containerTimeouts;
+  constructor(ctx: DurableObjectState<{}>, env: Env);
+  setSandboxName(name: string, normalizeId?: boolean): Promise<void>;
+  setBaseUrl(baseUrl: string): Promise<void>;
+  setSleepAfter(sleepAfter: string | number): Promise<void>;
+  setKeepAlive(keepAlive: boolean): Promise<void>;
+  setEnvVars(envVars: Record<string, string>): Promise<void>;
+  /**
+   * RPC method to configure container startup timeouts
+   */
+  setContainerTimeouts(timeouts: NonNullable<SandboxOptions['containerTimeouts']>): Promise<void>;
+  /**
+   * Validate a timeout value is within acceptable range
+   * Throws error if invalid - used for user-provided values
+   */
+  private validateTimeout;
+  /**
+   * Get default timeouts with env var fallbacks and validation
+   * Precedence: SDK defaults < Env vars < User config
+   */
+  private getDefaultTimeouts;
+  mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+  /**
+   * Manually unmount a bucket filesystem
+   *
+   * @param mountPath - Absolute path where the bucket is mounted
+   * @throws InvalidMountConfigError if mount path doesn't exist or isn't mounted
+   */
+  unmountBucket(mountPath: string): Promise<void>;
+  /**
+   * Validate mount options
+   */
+  private validateMountOptions;
+  /**
+   * Generate unique password file path for s3fs credentials
+   */
+  private generatePasswordFilePath;
+  /**
+   * Create password file with s3fs credentials
+   * Format: bucket:accessKeyId:secretAccessKey
+   */
+  private createPasswordFile;
+  /**
+   * Delete password file
+   */
+  private deletePasswordFile;
+  /**
+   * Execute S3FS mount command
+   */
+  private executeS3FSMount;
+  /**
+   * Cleanup and destroy the sandbox container
+   */
+  destroy(): Promise<void>;
+  onStart(): void;
+  /**
+   * Check if the container version matches the SDK version
+   * Logs a warning if there's a mismatch
+   */
+  private checkVersionCompatibility;
+  onStop(): Promise<void>;
+  onError(error: unknown): void;
+  /**
+   * Override Container.containerFetch to use production-friendly timeouts
+   * Automatically starts container with longer timeouts if not running
+   */
+  containerFetch(requestOrUrl: Request | string | URL, portOrInit?: number | RequestInit, portParam?: number): Promise<Response>;
+  /**
+   * Helper: Check if error is "no container instance available"
+   */
+  private isNoInstanceError;
+  /**
+   * Helper: Parse containerFetch arguments (supports multiple signatures)
+   */
+  private parseContainerFetchArgs;
+  /**
+   * Override onActivityExpired to prevent automatic shutdown when keepAlive is enabled
+   * When keepAlive is disabled, calls parent implementation which stops the container
+   */
+  onActivityExpired(): Promise<void>;
+  fetch(request: Request): Promise<Response>;
+  wsConnect(request: Request, port: number): Promise<Response>;
+  private determinePort;
+  /**
+   * Ensure default session exists - lazy initialization
+   * This is called automatically by all public methods that need a session
+   *
+   * The session is persisted to Durable Object storage to survive hot reloads
+   * during development. If a session already exists in the container after reload,
+   * we reuse it instead of trying to create a new one.
+   */
+  private ensureDefaultSession;
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  /**
+   * Internal session-aware exec implementation
+   * Used by both public exec() and session wrappers
+   */
+  private execWithSession;
+  private executeWithStreaming;
+  private mapExecuteResponseToExecResult;
+  /**
+   * Create a Process domain object from HTTP client DTO
+   * Centralizes process object creation with bound methods
+   * This eliminates duplication across startProcess, listProcesses, getProcess, and session wrappers
+   */
+  private createProcessFromDTO;
+  startProcess(command: string, options?: ProcessOptions, sessionId?: string): Promise<Process>;
+  listProcesses(sessionId?: string): Promise<Process[]>;
+  getProcess(id: string, sessionId?: string): Promise<Process | null>;
+  killProcess(id: string, signal?: string, sessionId?: string): Promise<void>;
+  killAllProcesses(sessionId?: string): Promise<number>;
+  cleanupCompletedProcesses(sessionId?: string): Promise<number>;
+  getProcessLogs(id: string, sessionId?: string): Promise<{
+    stdout: string;
+    stderr: string;
+    processId: string;
+  }>;
+  execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Internal session-aware execStream implementation
+   */
+  private execStreamWithSession;
+  /**
+   * Stream logs from a background process as a ReadableStream.
+   */
+  streamProcessLogs(processId: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<ReadableStream<Uint8Array>>;
+  gitCheckout(repoUrl: string, options: {
+    branch?: string;
+    targetDir?: string;
+    sessionId?: string;
+  }): Promise<GitCheckoutResult>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+    sessionId?: string;
+  }): Promise<MkdirResult>;
+  writeFile(path: string, content: string, options?: {
+    encoding?: string;
+    sessionId?: string;
+  }): Promise<WriteFileResult>;
+  deleteFile(path: string, sessionId?: string): Promise<DeleteFileResult>;
+  renameFile(oldPath: string, newPath: string, sessionId?: string): Promise<RenameFileResult>;
+  moveFile(sourcePath: string, destinationPath: string, sessionId?: string): Promise<MoveFileResult>;
+  readFile(path: string, options?: {
+    encoding?: string;
+    sessionId?: string;
+  }): Promise<ReadFileResult>;
+  /**
+   * Stream a file from the sandbox using Server-Sent Events
+   * Returns a ReadableStream that can be consumed with streamFile() or collectFile() utilities
+   * @param path - Path to the file to stream
+   * @param options - Optional session ID
+   */
+  readFileStream(path: string, options?: {
+    sessionId?: string;
+  }): Promise<ReadableStream<Uint8Array>>;
+  listFiles(path: string, options?: {
+    recursive?: boolean;
+    includeHidden?: boolean;
+  }): Promise<ListFilesResult>;
+  exists(path: string, sessionId?: string): Promise<FileExistsResult>;
+  exposePort(port: number, options: {
+    name?: string;
+    hostname: string;
+  }): Promise<{
+    url: string;
+    port: number;
+    name: string | undefined;
+  }>;
+  unexposePort(port: number): Promise<void>;
+  getExposedPorts(hostname: string): Promise<{
+    url: string;
+    port: number;
+    status: "active" | "inactive";
+  }[]>;
+  isPortExposed(port: number): Promise<boolean>;
+  validatePortToken(port: number, token: string): Promise<boolean>;
+  private generatePortToken;
+  private persistPortTokens;
+  private constructPreviewUrl;
+  /**
+   * Create isolated execution session for advanced use cases
+   * Returns ExecutionSession with full sandbox API bound to specific session
+   */
+  createSession(options?: SessionOptions): Promise<ExecutionSession>;
+  /**
+   * Get an existing session by ID
+   * Returns ExecutionSession wrapper bound to the specified session
+   *
+   * This is useful for retrieving sessions across different requests/contexts
+   * without storing the ExecutionSession object (which has RPC lifecycle limitations)
+   *
+   * @param sessionId - The ID of an existing session
+   * @returns ExecutionSession wrapper bound to the session
+   */
+  getSession(sessionId: string): Promise<ExecutionSession>;
+  /**
+   * Delete an execution session
+   * Cleans up session resources and removes it from the container
+   * Note: Cannot delete the default session. To reset the default session,
+   * use sandbox.destroy() to terminate the entire sandbox.
+   *
+   * @param sessionId - The ID of the session to delete
+   * @returns Result with success status, sessionId, and timestamp
+   * @throws Error if attempting to delete the default session
+   */
+  deleteSession(sessionId: string): Promise<SessionDeleteResult>;
+  /**
+   * Internal helper to create ExecutionSession wrapper for a given sessionId
+   * Used by both createSession and getSession
+   */
+  private getSessionWrapper;
+  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
+  runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
+  listCodeContexts(): Promise<CodeContext[]>;
+  deleteCodeContext(contextId: string): Promise<void>;
+}
+//#endregion
+export { ProcessInfoResult as $, RequestConfig as A, FileChunk as B, WriteFileRequest as C, ContainerStub as D, BaseApiResponse as E, BucketProvider as F, ListFilesOptions as G, FileStreamEvent as H, ExecEvent as I, PortCloseResult as J, LogEvent as K, ExecOptions as L, SessionRequest as M, BaseExecOptions as N, ErrorResponse as O, BucketCredentials as P, ProcessCleanupResult as Q, ExecResult as R, ReadFileRequest as S, ExecuteResponse as T, GitCheckoutResult as U, FileMetadata as V, ISandbox as W, PortListResult as X, PortExposeResult as Y, Process as Z, GitCheckoutRequest as _, CreateSessionRequest as a, ProcessStatus as at, FileOperationRequest as b, DeleteSessionResponse as c, StreamOptions as ct, ProcessClient as d, isProcessStatus as dt, ProcessKillResult as et, ExposePortRequest as f, CodeContext as ft, InterpreterClient as g, RunCodeOptions as gt, ExecutionCallbacks as h, ExecutionResult as ht, CommandsResponse as i, ProcessStartResult as it, ResponseHandler as j, HttpClientOptions as k, PingResponse as l, isExecResult as lt, UnexposePortRequest as m, Execution as mt, getSandbox as n, ProcessLogsResult as nt, CreateSessionResponse as o, SandboxOptions as ot, PortClient as p, CreateContextOptions as pt, MountBucketOptions as q, SandboxClient as r, ProcessOptions as rt, DeleteSessionRequest as s, SessionOptions as st, Sandbox as t, ProcessListResult as tt, UtilityClient as u, isProcess as ut, GitClient as v, CommandClient as w, MkdirRequest as x, FileClient as y, ExecutionSession as z };
+//# sourceMappingURL=sandbox-HQazw9bn.d.ts.map