@cloudflare/sandbox 0.5.1 → 0.5.2

package/dist/index.d.ts

@@ -1,346 +1,7 @@
-import { Container } from "@cloudflare/containers";
+import { $ as ProcessCleanupResult, A as HttpClientOptions, B as ExecutionSession, C as WriteFileRequest, D as BaseApiResponse, E as ExecuteResponse, F as BucketCredentials, G as ISandbox, H as FileMetadata, I as BucketProvider, J as MountBucketOptions, K as ListFilesOptions, L as ExecEvent, M as ResponseHandler, N as SessionRequest, O as ContainerStub, P as BaseExecOptions, Q as Process, R as ExecOptions, S as ReadFileRequest, T as ExecuteRequest, U as FileStreamEvent, V as FileChunk, W as GitCheckoutResult, X as PortExposeResult, Y as PortCloseResult, Z as PortListResult, _ as GitCheckoutRequest, _t as RunCodeOptions, a as CreateSessionRequest, at as ProcessStartResult, b as FileOperationRequest, c as DeleteSessionResponse, ct as SessionOptions, d as ProcessClient, dt as isProcess, et as ProcessInfoResult, f as ExposePortRequest, ft as isProcessStatus, g as InterpreterClient, gt as ExecutionResult, h as ExecutionCallbacks, ht as Execution, i as CommandsResponse, it as ProcessOptions, j as RequestConfig, k as ErrorResponse, l as PingResponse, lt as StreamOptions, m as UnexposePortRequest, mt as CreateContextOptions, n as getSandbox, nt as ProcessListResult, o as CreateSessionResponse, ot as ProcessStatus, p as PortClient, pt as CodeContext, q as LogEvent, r as SandboxClient, rt as ProcessLogsResult, s as DeleteSessionRequest, st as SandboxOptions, t as Sandbox, tt as ProcessKillResult, u as UtilityClient, ut as isExecResult, v as GitClient, w as CommandClient, x as MkdirRequest, y as FileClient, z as ExecResult } from "./sandbox-B3vJ541e.js";
 
-//#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/request-types.d.ts
+
 /**
  * Request to start a background process
  * Uses flat structure consistent with other endpoints
@@ -356,1391 +17,6 @@ interface StartProcessRequest {
   autoCleanup?: boolean;
 }
 //#endregion
-//#region ../shared/dist/types.d.ts
-interface BaseExecOptions {
-  /**
-   * Maximum execution time in milliseconds
-   */
-  timeout?: number;
-  /**
-   * Environment variables for the command
-   */
-  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>;
-  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
-/**
- * Request interface for command execution
- */
-interface ExecuteRequest extends SessionRequest {
-  command: string;
-  timeoutMs?: number;
-}
-/**
- * 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)
-   */
-  execute(command: string, sessionId: string, timeoutMs?: number): 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
-   */
-  executeStream(command: string, sessionId: 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;
-  }): 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(): 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
 //#region src/file-stream.d.ts
 /**
  * Stream a file from the sandbox with automatic base64 decoding for binary files