@cloudflare/sandbox 0.4.17 → 0.5.1

package/dist/index.d.ts

@@ -2,20 +2,6 @@ import { Container } from "@cloudflare/containers";
 
 //#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
@@ -111,182 +97,6 @@ interface Logger {
   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/git.d.ts
-/**
- * Redact credentials from URLs for secure logging
- *
- * Replaces any credentials (username:password, tokens, etc.) embedded
- * in URLs with ****** to prevent sensitive data exposure in logs.
- * Works with URLs embedded in text (e.g., "Error: https://token@github.com/repo.git failed")
- *
- * @param text - String that may contain URLs with credentials
- * @returns String with credentials redacted from any URLs
- */
-declare function redactCredentials(text: string): string;
-/**
- * Sanitize data by redacting credentials from any strings
- * Recursively processes objects and arrays to ensure credentials are never leaked
- */
-declare function sanitizeGitData<T>(data: T): T;
-/**
- * Logger wrapper that automatically sanitizes git credentials
- */
-declare class GitLogger implements Logger {
-  private readonly baseLogger;
-  constructor(baseLogger: Logger);
-  private sanitizeContext;
-  private sanitizeError;
-  debug(message: string, context?: Partial<LogContext>): void;
-  info(message: string, context?: Partial<LogContext>): void;
-  warn(message: string, context?: Partial<LogContext>): void;
-  error(message: string, error?: Error, context?: Partial<LogContext>): void;
-  child(context: Partial<LogContext>): Logger;
-}
-//#endregion
 //#region ../shared/dist/interpreter-types.d.ts
 interface CreateContextOptions {
   /**
@@ -529,22 +339,6 @@ declare class Execution {
    */
   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/request-types.d.ts
 /**
@@ -561,51 +355,6 @@ interface StartProcessRequest {
   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 {
@@ -834,6 +583,72 @@ interface SandboxOptions {
    * 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
@@ -1019,35 +834,17 @@ interface ProcessCleanupResult {
   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<{
@@ -1062,42 +859,6 @@ interface PortCloseResult {
   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;
@@ -1142,6 +903,68 @@ interface ExecutionSession {
   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>;
@@ -1179,6 +1002,8 @@ interface ISandbox {
     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>;
@@ -1253,13 +1078,14 @@ declare abstract class BaseHttpClient {
   protected logger: Logger;
   constructor(options?: HttpClientOptions);
   /**
-   * Core HTTP request method with automatic retry for container provisioning delays
+   * 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: Record<string, any>, responseHandler?: ResponseHandler<T>): Promise<T>;
+  protected post<T>(endpoint: string, data: unknown, responseHandler?: ResponseHandler<T>): Promise<T>;
   /**
    * Make a GET request
    */
@@ -1293,10 +1119,17 @@ declare abstract class BaseHttpClient {
    */
   protected logError(operation: string, error: unknown): void;
   /**
-   * Check if 503 response is from container provisioning (retryable)
-   * vs user application (not retryable)
+   * 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 isContainerProvisioningError;
+  private isRetryableContainerError;
   private executeFetch;
 }
 //#endregion
@@ -1671,18 +1504,73 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   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): Promise<void>;
+  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
    */
@@ -1695,6 +1583,19 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   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
@@ -1949,5 +1850,88 @@ declare function asyncIterableToSSEStream<T>(events: AsyncIterable<T>, options?:
   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, type CreateSessionRequest, type CreateSessionResponse, DeleteFileRequest, DeleteFileResult, type DeleteSessionRequest, type DeleteSessionResponse, 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, GitLogger, 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, createLogger, createNoOpLogger, getLogger, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, redactCredentials, responseToAsyncIterable, runWithLogger, sanitizeGitData, streamFile };
+//#region ../shared/dist/errors/codes.d.ts
+/**
+ * Centralized error code registry
+ * Each code maps to a specific error type with consistent semantics
+ */
+declare const ErrorCode: {
+  readonly FILE_NOT_FOUND: "FILE_NOT_FOUND";
+  readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+  readonly FILE_EXISTS: "FILE_EXISTS";
+  readonly IS_DIRECTORY: "IS_DIRECTORY";
+  readonly NOT_DIRECTORY: "NOT_DIRECTORY";
+  readonly NO_SPACE: "NO_SPACE";
+  readonly TOO_MANY_FILES: "TOO_MANY_FILES";
+  readonly RESOURCE_BUSY: "RESOURCE_BUSY";
+  readonly READ_ONLY: "READ_ONLY";
+  readonly NAME_TOO_LONG: "NAME_TOO_LONG";
+  readonly TOO_MANY_LINKS: "TOO_MANY_LINKS";
+  readonly FILESYSTEM_ERROR: "FILESYSTEM_ERROR";
+  readonly COMMAND_NOT_FOUND: "COMMAND_NOT_FOUND";
+  readonly COMMAND_PERMISSION_DENIED: "COMMAND_PERMISSION_DENIED";
+  readonly INVALID_COMMAND: "INVALID_COMMAND";
+  readonly COMMAND_EXECUTION_ERROR: "COMMAND_EXECUTION_ERROR";
+  readonly STREAM_START_ERROR: "STREAM_START_ERROR";
+  readonly PROCESS_NOT_FOUND: "PROCESS_NOT_FOUND";
+  readonly PROCESS_PERMISSION_DENIED: "PROCESS_PERMISSION_DENIED";
+  readonly PROCESS_ERROR: "PROCESS_ERROR";
+  readonly PORT_ALREADY_EXPOSED: "PORT_ALREADY_EXPOSED";
+  readonly PORT_IN_USE: "PORT_IN_USE";
+  readonly PORT_NOT_EXPOSED: "PORT_NOT_EXPOSED";
+  readonly INVALID_PORT_NUMBER: "INVALID_PORT_NUMBER";
+  readonly INVALID_PORT: "INVALID_PORT";
+  readonly SERVICE_NOT_RESPONDING: "SERVICE_NOT_RESPONDING";
+  readonly PORT_OPERATION_ERROR: "PORT_OPERATION_ERROR";
+  readonly CUSTOM_DOMAIN_REQUIRED: "CUSTOM_DOMAIN_REQUIRED";
+  readonly GIT_REPOSITORY_NOT_FOUND: "GIT_REPOSITORY_NOT_FOUND";
+  readonly GIT_BRANCH_NOT_FOUND: "GIT_BRANCH_NOT_FOUND";
+  readonly GIT_AUTH_FAILED: "GIT_AUTH_FAILED";
+  readonly GIT_NETWORK_ERROR: "GIT_NETWORK_ERROR";
+  readonly INVALID_GIT_URL: "INVALID_GIT_URL";
+  readonly GIT_CLONE_FAILED: "GIT_CLONE_FAILED";
+  readonly GIT_CHECKOUT_FAILED: "GIT_CHECKOUT_FAILED";
+  readonly GIT_OPERATION_FAILED: "GIT_OPERATION_FAILED";
+  readonly BUCKET_MOUNT_ERROR: "BUCKET_MOUNT_ERROR";
+  readonly S3FS_MOUNT_ERROR: "S3FS_MOUNT_ERROR";
+  readonly MISSING_CREDENTIALS: "MISSING_CREDENTIALS";
+  readonly INVALID_MOUNT_CONFIG: "INVALID_MOUNT_CONFIG";
+  readonly INTERPRETER_NOT_READY: "INTERPRETER_NOT_READY";
+  readonly CONTEXT_NOT_FOUND: "CONTEXT_NOT_FOUND";
+  readonly CODE_EXECUTION_ERROR: "CODE_EXECUTION_ERROR";
+  readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+  readonly INVALID_JSON_RESPONSE: "INVALID_JSON_RESPONSE";
+  readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+  readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+//#endregion
+//#region src/storage-mount/errors.d.ts
+/**
+ * Base error for bucket mounting operations
+ */
+declare class BucketMountError extends Error {
+  readonly code: ErrorCode;
+  constructor(message: string, code?: ErrorCode);
+}
+/**
+ * Thrown when S3FS mount command fails
+ */
+declare class S3FSMountError extends BucketMountError {
+  constructor(message: string);
+}
+/**
+ * Thrown when no credentials found in environment
+ */
+declare class MissingCredentialsError extends BucketMountError {
+  constructor(message: string);
+}
+/**
+ * Thrown when bucket name, mount path, or options are invalid
+ */
+declare class InvalidMountConfigError extends BucketMountError {
+  constructor(message: string);
+}
+//#endregion
+export { type BaseApiResponse, type BaseExecOptions, type BucketCredentials, BucketMountError, type BucketProvider, type CodeContext, CodeInterpreter, CommandClient, type ExecuteResponse as CommandExecuteResponse, type CommandsResponse, type ContainerStub, type CreateContextOptions, type CreateSessionRequest, type CreateSessionResponse, type DeleteSessionRequest, type DeleteSessionResponse, type ErrorResponse, type ExecEvent, type ExecOptions, type ExecResult, type ExecuteRequest, type ExecutionCallbacks, type ExecutionResult, type ExecutionSession, type ExposePortRequest, type FileChunk, FileClient, type FileMetadata, type FileOperationRequest, type FileStreamEvent, type GitCheckoutRequest, type GitCheckoutResult, GitClient, type ISandbox, type InterpreterClient, InvalidMountConfigError, type ListFilesOptions, type LogEvent, MissingCredentialsError, type MkdirRequest, type MountBucketOptions, type PingResponse, PortClient, type PortCloseResult, type PortExposeResult, type PortListResult, type Process, type ProcessCleanupResult, ProcessClient, type ProcessInfoResult, type ProcessKillResult, type ProcessListResult, type ProcessLogsResult, type ProcessOptions, type ProcessStartResult, type ProcessStatus, type ReadFileRequest, type RequestConfig, type ResponseHandler, type RouteInfo, type RunCodeOptions, S3FSMountError, Sandbox, SandboxClient, type HttpClientOptions as SandboxClientOptions, type SandboxEnv, type SandboxOptions, type SessionOptions, type SessionRequest, type StartProcessRequest, type StreamOptions, type UnexposePortRequest, UtilityClient, type WriteFileRequest, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.d.ts.map