@cloudflare/sandbox 0.0.0-7bccc85 → 0.0.0-7edbfa9

package/dist/index.d.ts

@@ -0,0 +1,1907 @@
+import { Container } from "@cloudflare/containers";
+import { DurableObject } from "cloudflare:workers";
+
+//#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;
+}
+declare class ResultImpl implements Result {
+  private raw;
+  constructor(raw: any);
+  get text(): string | undefined;
+  get html(): string | undefined;
+  get png(): string | undefined;
+  get jpeg(): string | undefined;
+  get svg(): string | undefined;
+  get latex(): string | undefined;
+  get markdown(): string | undefined;
+  get javascript(): string | undefined;
+  get json(): any;
+  get chart(): ChartData | undefined;
+  get data(): any;
+  formats(): string[];
+}
+//#endregion
+//#region ../shared/dist/logger/types.d.ts
+/**
+ * Logger types for Cloudflare Sandbox SDK
+ *
+ * Provides structured, trace-aware logging across Worker, Durable Object, and Container.
+ */
+/**
+ * Log levels (from most to least verbose)
+ */
+declare enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+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/logger/trace-context.d.ts
+/**
+ * Trace context utilities for request correlation
+ *
+ * Trace IDs enable correlating logs across distributed components:
+ * Worker → Durable Object → Container → back
+ *
+ * The trace ID is propagated via the X-Trace-Id HTTP header.
+ */
+/**
+ * Utility for managing trace context across distributed components
+ */
+declare class TraceContext {
+  /**
+   * HTTP header name for trace ID propagation
+   */
+  private static readonly TRACE_HEADER;
+  /**
+   * Generate a new trace ID
+   *
+   * Format: "tr_" + 16 random hex characters
+   * Example: "tr_7f3a9b2c4e5d6f1a"
+   *
+   * @returns Newly generated trace ID
+   */
+  static generate(): string;
+  /**
+   * Extract trace ID from HTTP request headers
+   *
+   * @param headers Request headers
+   * @returns Trace ID if present, null otherwise
+   */
+  static fromHeaders(headers: Headers): string | null;
+  /**
+   * Create headers object with trace ID for outgoing requests
+   *
+   * @param traceId Trace ID to include
+   * @returns Headers object with X-Trace-Id set
+   */
+  static toHeaders(traceId: string): Record<string, string>;
+  /**
+   * Get the header name used for trace ID propagation
+   *
+   * @returns Header name ("X-Trace-Id")
+   */
+  static getHeaderName(): string;
+}
+//#endregion
+//#region ../shared/dist/logger/index.d.ts
+/**
+ * Create a no-op logger for testing
+ *
+ * Returns a logger that implements the Logger interface but does nothing.
+ * Useful for tests that don't need actual logging output.
+ *
+ * @returns No-op logger instance
+ *
+ * @example
+ * ```typescript
+ * // In tests
+ * const client = new HttpClient({
+ *   baseUrl: 'http://test.com',
+ *   logger: createNoOpLogger() // Optional - tests can enable real logging if needed
+ * });
+ * ```
+ */
+declare function createNoOpLogger(): Logger;
+/**
+ * Get the current logger from AsyncLocalStorage
+ *
+ * @throws Error if no logger is initialized in the current async context
+ * @returns Current logger instance
+ *
+ * @example
+ * ```typescript
+ * function someHelperFunction() {
+ *   const logger = getLogger(); // Automatically has all context!
+ *   logger.info('Helper called');
+ * }
+ * ```
+ */
+declare function getLogger(): Logger;
+/**
+ * Run a function with a logger stored in AsyncLocalStorage
+ *
+ * The logger is available to all code within the function via getLogger().
+ * This is typically called at request entry points (fetch handler) and when
+ * creating child loggers with additional context.
+ *
+ * @param logger Logger instance to store in context
+ * @param fn Function to execute with logger context
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * // At request entry point
+ * async fetch(request: Request): Promise<Response> {
+ *   const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc' });
+ *   return runWithLogger(logger, async () => {
+ *     return await this.handleRequest(request);
+ *   });
+ * }
+ *
+ * // When adding operation context
+ * async exec(command: string) {
+ *   const logger = getLogger().child({ operation: 'exec', commandId: 'cmd-123' });
+ *   return runWithLogger(logger, async () => {
+ *     logger.info('Command started');
+ *     await this.executeCommand(command); // Nested calls get the child logger
+ *     logger.info('Command completed');
+ *   });
+ * }
+ * ```
+ */
+declare function runWithLogger<T>(logger: Logger, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Create a new logger instance
+ *
+ * @param context Base context for the logger. Must include 'component'.
+ *                TraceId will be auto-generated if not provided.
+ * @returns New logger instance
+ *
+ * @example
+ * ```typescript
+ * // In Durable Object
+ * const logger = createLogger({
+ *   component: 'sandbox-do',
+ *   traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
+ *   sandboxId: this.id
+ * });
+ *
+ * // In Container
+ * const logger = createLogger({
+ *   component: 'container',
+ *   traceId: TraceContext.fromHeaders(request.headers)!,
+ *   sessionId: this.id
+ * });
+ * ```
+ */
+declare function createLogger(context: Partial<LogContext> & {
+  component: LogComponent;
+}): Logger;
+//#endregion
+//#region ../shared/dist/request-types.d.ts
+/**
+ * Request to start a background process
+ * Uses flat structure consistent with other endpoints
+ */
+interface StartProcessRequest {
+  command: string;
+  sessionId?: string;
+  processId?: string;
+  timeoutMs?: number;
+  env?: Record<string, string>;
+  cwd?: string;
+  encoding?: string;
+  autoCleanup?: boolean;
+}
+/**
+ * Request to delete a file
+ */
+interface DeleteFileRequest {
+  path: string;
+  sessionId?: string;
+}
+/**
+ * Request to rename a file
+ */
+interface RenameFileRequest {
+  oldPath: string;
+  newPath: string;
+  sessionId?: string;
+}
+/**
+ * Request to move a file
+ */
+interface MoveFileRequest {
+  sourcePath: string;
+  destinationPath: string;
+  sessionId?: string;
+}
+/**
+ * Request to check if a file or directory exists
+ */
+interface FileExistsRequest {
+  path: string;
+  sessionId?: string;
+}
+/**
+ * Request to create a session
+ */
+interface SessionCreateRequest {
+  id?: string;
+  name?: string;
+  env?: Record<string, string>;
+  cwd?: string;
+}
+/**
+ * Request to delete a session
+ */
+interface SessionDeleteRequest {
+  sessionId: string;
+}
+//#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;
+}
+/**
+ * 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 SessionCreateResult {
+  success: boolean;
+  sessionId: string;
+  name?: string;
+  cwd?: string;
+  timestamp: string;
+}
+interface SessionDeleteResult {
+  success: boolean;
+  sessionId: string;
+  timestamp: string;
+}
+interface EnvSetResult {
+  success: boolean;
+  timestamp: string;
+}
+interface PortExposeResult {
+  success: boolean;
+  port: number;
+  url: string;
+  timestamp: string;
+}
+interface PortStatusResult {
+  success: boolean;
+  port: number;
+  status: 'active' | 'inactive';
+  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 InterpreterHealthResult {
+  success: boolean;
+  status: 'healthy' | 'unhealthy';
+  timestamp: string;
+}
+interface ContextCreateResult {
+  success: boolean;
+  contextId: string;
+  language: string;
+  cwd?: string;
+  timestamp: string;
+}
+interface ContextListResult {
+  success: boolean;
+  contexts: Array<{
+    id: string;
+    language: string;
+    cwd?: string;
+  }>;
+  timestamp: string;
+}
+interface ContextDeleteResult {
+  success: boolean;
+  contextId: string;
+  timestamp: string;
+}
+interface HealthCheckResult {
+  success: boolean;
+  status: 'healthy' | 'unhealthy';
+  timestamp: string;
+}
+interface ShutdownResult {
+  success: boolean;
+  message: string;
+  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>;
+}
+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>;
+  createSession(options?: SessionOptions): Promise<ExecutionSession>;
+  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>;
+}
+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 provisioning delays
+   */
+  protected doFetch(path: string, options?: RequestInit): Promise<Response>;
+  /**
+   * Make a POST request with JSON body
+   */
+  protected post<T>(endpoint: string, data: Record<string, any>, 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 503 response is from container provisioning (retryable)
+   * vs user application (not retryable)
+   */
+  private isContainerProvisioningError;
+  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 {
+  /**
+   * 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;
+}
+/**
+ * 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>;
+  /**
+   * 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;
+/**
+ * Connect an incoming WebSocket request to a specific port inside the container.
+ *
+ * Note: This is a standalone function (not a Sandbox method) because WebSocket
+ * connections cannot be serialized over Durable Object RPC.
+ *
+ * @param sandbox - The Sandbox instance to route the request through
+ * @param request - The incoming WebSocket upgrade request
+ * @param port - The port number to connect to (1024-65535)
+ * @returns The WebSocket upgrade response
+ * @throws {SecurityError} - If port is invalid or in restricted range
+ *
+ * @example
+ * const sandbox = getSandbox(env.Sandbox, 'sandbox-id');
+ * if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
+ *   return await connect(sandbox, request, 8080);
+ * }
+ */
+declare function connect(sandbox: Sandbox, request: Request, port: number): Promise<Response>;
+declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
+  defaultPort: number;
+  sleepAfter: string | number;
+  client: SandboxClient;
+  private codeInterpreter;
+  private sandboxName;
+  private baseUrl;
+  private portTokens;
+  private defaultSession;
+  envVars: Record<string, string>;
+  private logger;
+  private keepAliveEnabled;
+  constructor(ctx: DurableObject['ctx'], env: Env);
+  setSandboxName(name: string): 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>;
+  /**
+   * 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 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>;
+  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>;
+  /**
+   * 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
+ *
+ * @param stream - The ReadableStream from readFileStream()
+ * @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
+ *
+ * @example
+ * ```ts
+ * const stream = await sandbox.readFileStream('/path/to/file.png');
+ * for await (const chunk of streamFile(stream)) {
+ *   if (chunk instanceof Uint8Array) {
+ *     // Binary chunk
+ *     console.log('Binary chunk:', chunk.length, 'bytes');
+ *   } else {
+ *     // Text chunk
+ *     console.log('Text chunk:', chunk);
+ *   }
+ * }
+ * ```
+ */
+declare function streamFile(stream: ReadableStream<Uint8Array>): AsyncGenerator<FileChunk, FileMetadata>;
+/**
+ * Collect an entire file into memory from a stream
+ *
+ * @param stream - The ReadableStream from readFileStream()
+ * @returns Object containing the file content and metadata
+ *
+ * @example
+ * ```ts
+ * const stream = await sandbox.readFileStream('/path/to/file.txt');
+ * const { content, metadata } = await collectFile(stream);
+ * console.log('Content:', content);
+ * console.log('MIME type:', metadata.mimeType);
+ * ```
+ */
+declare function collectFile(stream: ReadableStream<Uint8Array>): Promise<{
+  content: string | Uint8Array;
+  metadata: FileMetadata;
+}>;
+//#endregion
+//#region src/interpreter.d.ts
+declare class CodeInterpreter {
+  private interpreterClient;
+  private contexts;
+  constructor(sandbox: Sandbox);
+  /**
+   * Create a new code execution context
+   */
+  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  /**
+   * Run code with optional context
+   */
+  runCode(code: string, options?: RunCodeOptions): Promise<Execution>;
+  /**
+   * Run code and return a streaming response
+   */
+  runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
+  /**
+   * List all code contexts
+   */
+  listCodeContexts(): Promise<CodeContext[]>;
+  /**
+   * Delete a code context
+   */
+  deleteCodeContext(contextId: string): Promise<void>;
+  private getOrCreateDefaultContext;
+}
+//#endregion
+//#region src/request-handler.d.ts
+interface SandboxEnv {
+  Sandbox: DurableObjectNamespace<Sandbox>;
+}
+interface RouteInfo {
+  port: number;
+  sandboxId: string;
+  path: string;
+  token: string;
+}
+declare function proxyToSandbox<E extends SandboxEnv>(request: Request, env: E): Promise<Response | null>;
+//#endregion
+//#region src/sse-parser.d.ts
+/**
+ * Server-Sent Events (SSE) parser for streaming responses
+ * Converts ReadableStream<Uint8Array> to typed AsyncIterable<T>
+ */
+/**
+ * Parse a ReadableStream of SSE events into typed AsyncIterable
+ * @param stream - The ReadableStream from fetch response
+ * @param signal - Optional AbortSignal for cancellation
+ */
+declare function parseSSEStream<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Helper to convert a Response with SSE stream directly to AsyncIterable
+ * @param response - Response object with SSE stream
+ * @param signal - Optional AbortSignal for cancellation
+ */
+declare function responseToAsyncIterable<T>(response: Response, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Create an SSE-formatted ReadableStream from an AsyncIterable
+ * (Useful for Worker endpoints that need to forward AsyncIterable as SSE)
+ * @param events - AsyncIterable of events
+ * @param options - Stream options
+ */
+declare function asyncIterableToSSEStream<T>(events: AsyncIterable<T>, options?: {
+  signal?: AbortSignal;
+  serialize?: (event: T) => string;
+}): ReadableStream<Uint8Array>;
+//#endregion
+export { type BaseApiResponse, type BaseExecOptions, type ChartData, type CodeContext, CodeInterpreter, CommandClient, type ExecuteResponse as CommandExecuteResponse, type CommandsResponse, type ContainerStub, ContextCreateResult, ContextDeleteResult, ContextListResult, type CreateContextOptions, DeleteFileRequest, DeleteFileResult, EnvSetResult, type ErrorResponse, type ExecEvent, type ExecOptions, type ExecResult, type ExecuteRequest, Execution, type ExecutionCallbacks, type ExecutionError, type ExecutionResult, ExecutionSession, type ExposePortRequest, type FileChunk, FileClient, FileExistsRequest, FileExistsResult, FileInfo, type FileMetadata, type FileOperationRequest, type FileStreamEvent, type GitCheckoutRequest, type GitCheckoutResult, GitClient, HealthCheckResult, type ISandbox, type InterpreterClient, InterpreterHealthResult, ListFilesOptions, ListFilesResult, type LogContext, type LogEvent, type LogLevel, LogLevel as LogLevelEnum, type Logger, type MkdirRequest, MkdirResult, MoveFileRequest, MoveFileResult, type OutputMessage, type PingResponse, PortClient, type PortCloseResult, type PortExposeResult, type PortListResult, PortStatusResult, type Process, type ProcessCleanupResult, ProcessClient, type ProcessInfoResult, type ProcessKillResult, type ProcessListResult, type ProcessLogsResult, type ProcessOptions, type ProcessStartResult, type ProcessStatus, type ReadFileRequest, ReadFileResult, RenameFileRequest, RenameFileResult, type RequestConfig, type ResponseHandler, type Result, ResultImpl, type RouteInfo, type RunCodeOptions, Sandbox, SandboxClient, type HttpClientOptions as SandboxClientOptions, type SandboxEnv, SandboxOptions, SessionCreateRequest, SessionCreateResult, SessionDeleteRequest, SessionDeleteResult, SessionOptions, type SessionRequest, ShutdownResult, type StartProcessRequest, type StreamOptions, TraceContext, type UnexposePortRequest, UtilityClient, type WriteFileRequest, WriteFileResult, asyncIterableToSSEStream, collectFile, connect, createLogger, createNoOpLogger, getLogger, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, runWithLogger, streamFile };
+//# sourceMappingURL=index.d.ts.map