@cloudflare/sandbox 0.13.0-next.651.1 → 0.13.0-next.709.1

package/dist/index.d.ts

@@ -1,131 +1,14 @@
-import { n as Sandbox, r as getSandbox, t as ContainerProxy } from "./sandbox-D_MMqExx.js";
-import { A as ExecResult, B as ListFilesOptions, C as BucketProvider, D as DirectoryBackup, F as FileMetadata, G as MountBucketOptions, H as LocalMountBucketOptions, I as FileStreamEvent, J as ProcessOptions, L as FileWatchSSEEvent, M as FileChunk, O as ExecEvent, Q as RemoteMountBucketOptions, R as GitCheckoutResult, S as BucketCredentials, T as CheckChangesResult, U as LogEvent, Y as ProcessStatus, _t as RunCodeOptions, at as WaitForLogResult, b as BackupOptions, dt as isProcessStatus, et as RestoreBackupResult, f as SandboxInterpreterAPI, ft as PtyOptions, gt as ExecutionResult, ht as Execution, i as QuickTunnelInfo, it as StreamOptions, j as ExecutionSession, k as ExecOptions, lt as isExecResult, mt as CreateContextOptions, ot as WaitForPortOptions, pt as CodeContext, q as Process, r as NamedTunnelInfo, rt as SessionOptions, st as WatchOptions, tt as SandboxOptions, ut as isProcess, v as TunnelInfo, w as CheckChangesOptions, x as BaseExecOptions, y as TunnelOptions, z as ISandbox } from "./rpc-types-PBUY-xXM.js";
-import { a as ContainerUnavailableContext, c as ProcessExitedBeforeReadyContext, d as RPCTransportErrorKind, f as SessionTerminatedContext, h as ErrorCode, i as BackupRestoreContext, l as ProcessReadyTimeoutContext, m as OperationType, n as BackupExpiredContext, o as InvalidBackupConfigContext, p as ErrorResponse, r as BackupNotFoundContext, t as BackupCreateContext, u as RPCTransportContext } from "./contexts-BS0Bs6IU.js";
+import { H as RPCTransportErrorKind, V as RPCTransportContext, Z as ErrorCode } from "./contexts-1EsLHByO.js";
+import { c as WaitForLogResult, i as ProcessLogEvent, n as ProcessFailure, o as ProcessStatus, r as ProcessLogCursor, s as SandboxCommand, t as ProcessExit } from "./process-types-GStiZ8f8.js";
+import { A as CreateTerminalOptions, C as BucketCredentials, D as MountBucketOptions, E as LocalMountBucketOptions, F as TerminalOutputOptions, G as ProcessTextOutputOptions, H as ProcessLogsOptions, I as TerminalOutputSubscriptionAPI, J as WaitForExitOptions, K as SandboxOptions, L as TerminalSnapshot, M as Terminal, N as TerminalOutputCursor, O as RemoteMountBucketOptions, P as TerminalOutputEvent, R as ExecOptions, S as BackupOptions, T as DirectoryBackup, U as ProcessOutput, W as ProcessOutputOptions, X as WaitForPortOptions, Y as WaitForLogOptions, _ as RenameFileResult, a as FileChunk, b as WriteFileResult, c as FileMetadata, d as ListFilesOptions, f as ListFilesResult, g as ReadFileStreamResult, h as ReadFileResult, i as DeleteFileResult, k as RestoreBackupResult, l as FileStreamEvent, m as MoveFileResult, o as FileEncoding, p as MkdirResult, q as SandboxProcess, r as CheckChangesResult, s as FileExistsResult, t as CheckChangesOptions, u as FileWatchSSEEvent, v as WatchOptions, w as BucketProvider } from "./filesystem-BWAZCZER.js";
+import { t as ISandbox } from "./sandbox-BbAabq93.js";
+import { _ as QuickTunnelInfo, d as sandboxRuntimeCall, f as ProcessPullSubscriptionRPC, g as NamedTunnelInfo, n as ExtensionRuntimeCall, p as ProcessRPCDescriptor, s as HTTPAuthInterceptorParams, v as TunnelInfo, y as TunnelOptions } from "./index-Bs4bqXDR.js";
+import { $ as TerminalNotFoundError, G as ContainerUnavailableError, H as BackupExpiredError, J as InvalidTerminalCwdError, K as InvalidBackupConfigError, Q as TerminalControlError, U as BackupNotFoundError, V as BackupCreateError, W as BackupRestoreError, X as RPCTransportError, Y as OperationInterruptedError, Z as StaleTerminalHandleError, a as InvalidProcessCursorError, c as ProcessAbortedError, d as ProcessExitedBeforeReadyError, f as ProcessNotFoundError, g as StaleProcessHandleError, h as ProcessWaitTimeoutError, l as ProcessError, m as ProcessSpawnFailedError, n as RuntimeControlProtocolError, o as InvalidProcessCwdError, p as ProcessReadyTimeoutError, q as InvalidTerminalCursorError, s as InvalidProcessEnvironmentError, t as RuntimeIdentityInactiveError, u as ProcessExitedBeforeLogError } from "./index-HNYBk-az.js";
+import { Container, ContainerProxy as ContainerProxy$1, ContainerStartConfigOptions } from "@cloudflare/containers";
+import { RpcTarget, RpcTransport } from "capnweb";
 
-//#region src/errors/classes.d.ts
-
-/**
- * Base SDK error that wraps ErrorResponse
- * Preserves all error information from container
- */
-declare class SandboxError<TContext = Record<string, unknown>> extends Error {
-  readonly errorResponse: ErrorResponse<TContext>;
-  constructor(errorResponse: ErrorResponse<TContext>, options?: {
-    cause?: unknown;
-  });
-  get code(): ErrorCode;
-  get context(): TContext;
-  get httpStatus(): number;
-  get operation(): OperationType | undefined;
-  get suggestion(): string | undefined;
-  get timestamp(): string;
-  get documentation(): string | undefined;
-  toJSON(): {
-    name: string;
-    message: string;
-    code: ErrorCode;
-    context: TContext;
-    httpStatus: number;
-    operation: OperationType | undefined;
-    suggestion: string | undefined;
-    timestamp: string;
-    documentation: string | undefined;
-    stack: string | undefined;
-  };
-}
-/**
- * Error thrown when a session's underlying shell exited without an explicit
- * `destroy()` call (user ran `exit`, the shell crashed, or a child process
- * took the shell down). The session-local state is gone, but the next call
- * with the same sessionId will transparently start a fresh session.
- */
-declare class SessionTerminatedError extends SandboxError<SessionTerminatedContext> {
-  constructor(errorResponse: ErrorResponse<SessionTerminatedContext>);
-  get sessionId(): string;
-  get exitCode(): number | null;
-}
-/**
- * Error thrown when a process does not become ready within the timeout period
- */
-declare class ProcessReadyTimeoutError extends SandboxError<ProcessReadyTimeoutContext> {
-  constructor(errorResponse: ErrorResponse<ProcessReadyTimeoutContext>);
-  get processId(): string;
-  get command(): string;
-  get condition(): string;
-  get timeout(): number;
-}
-/**
- * Error thrown when a process exits before becoming ready
- */
-declare class ProcessExitedBeforeReadyError extends SandboxError<ProcessExitedBeforeReadyContext> {
-  constructor(errorResponse: ErrorResponse<ProcessExitedBeforeReadyContext>);
-  get processId(): string;
-  get command(): string;
-  get condition(): string;
-  get exitCode(): number;
-}
-/**
- * Error thrown when a backup is not found in R2
- */
-declare class BackupNotFoundError extends SandboxError<BackupNotFoundContext> {
-  constructor(errorResponse: ErrorResponse<BackupNotFoundContext>);
-  get backupId(): string;
-}
-/**
- * Error thrown when a backup has expired (past its TTL)
- */
-declare class BackupExpiredError extends SandboxError<BackupExpiredContext> {
-  constructor(errorResponse: ErrorResponse<BackupExpiredContext>);
-  get backupId(): string;
-  get expiredAt(): string | undefined;
-}
-/**
- * Error thrown when backup configuration or inputs are invalid
- */
-declare class InvalidBackupConfigError extends SandboxError<InvalidBackupConfigContext> {
-  constructor(errorResponse: ErrorResponse<InvalidBackupConfigContext>);
-  get reason(): string;
-}
-/**
- * Error thrown when backup creation fails
- */
-declare class BackupCreateError extends SandboxError<BackupCreateContext> {
-  constructor(errorResponse: ErrorResponse<BackupCreateContext>);
-  get dir(): string;
-  get backupId(): string | undefined;
-}
-/**
- * Error thrown when backup restoration fails
- */
-declare class BackupRestoreError extends SandboxError<BackupRestoreContext> {
-  constructor(errorResponse: ErrorResponse<BackupRestoreContext>);
-  get dir(): string;
-  get backupId(): string;
-}
-declare class ContainerUnavailableError extends SandboxError<ContainerUnavailableContext> {
-  constructor(errorResponse: ErrorResponse<ContainerUnavailableContext>);
-}
-/**
- * Raised when the capnweb WebSocket session itself fails on the SDK side.
- * Unlike the rest of the SandboxError tree, the container never produces
- * this error — it is synthesised by `translateRPCError` from the plain
- * Errors capnweb / DeferredTransport raise when the connection dies.
- *
- * `kind` distinguishes the failure mode (peer close, upgrade failed, etc.)
- * so callers can branch on a structured code instead of substring-matching
- * on the message.
- *
- * Always retryable: the SDK opens a fresh connection on the next call.
- */
-declare class RPCTransportError extends SandboxError<RPCTransportContext> {
-  constructor(errorResponse: ErrorResponse<RPCTransportContext>, options?: {
-    cause?: unknown;
-  });
-  get kind(): RPCTransportErrorKind;
-  get originalMessage(): string;
-}
-//#endregion
 //#region src/file-stream.d.ts
+
 /**
  * Stream a file from the sandbox with automatic base64 decoding for binary files
  *
@@ -166,39 +49,495 @@ declare function collectFile(stream: ReadableStream<Uint8Array>): Promise<{
   metadata: FileMetadata;
 }>;
 //#endregion
-//#region src/interpreter.d.ts
-declare class CodeInterpreter {
-  private getInterpreterClient;
-  private contexts;
-  constructor(interpreterClient: SandboxInterpreterAPI | (() => SandboxInterpreterAPI));
+//#region src/platform-errors.d.ts
+/**
+ * Whether an error was raised because the current Durable Object isolate was
+ * superseded by a deploy/code update. In-process retries are futile for this
+ * class because the invocation keeps running on the old isolate; callers
+ * should return control to the platform or retry from a fresh request.
+ */
+declare function isDurableObjectCodeUpdateReset(error: unknown): boolean;
+/**
+ * Whether an error represents a transient platform lifecycle/storage failure,
+ * not an application-level sandbox failure.
+ */
+declare function isPlatformTransientError(error: unknown): boolean;
+//#endregion
+//#region src/pty/rpc-types.d.ts
+interface TerminalCapabilityRPC {
+  getSnapshot(): Promise<TerminalSnapshot | null>;
+  openOutput(options?: Omit<TerminalOutputOptions, 'signal'>): Promise<ProcessPullSubscriptionRPC<TerminalOutputEvent>>;
+  write(data: Uint8Array): Promise<void>;
+  resize(cols: number, rows: number): Promise<void>;
+  interrupt(): Promise<void>;
+  terminate(): Promise<void>;
+  authorizeConnection(): Promise<string>;
+}
+interface TerminalRPCDescriptor {
+  snapshot: TerminalSnapshot;
+  runtimeIncarnationID: string;
+  capability: TerminalCapabilityRPC;
+}
+//#endregion
+//#region src/pty/proxy.d.ts
+interface TerminalHandleStub {
+  get(id: string): Promise<TerminalSnapshot | null>;
+  output(id: string, options?: Omit<TerminalOutputOptions, 'signal'>): Promise<TerminalOutputSubscriptionAPI | ProcessPullSubscriptionRPC<TerminalOutputEvent>>;
+  write(id: string, data: Uint8Array): Promise<void>;
+  resize(id: string, cols: number, rows: number): Promise<void>;
+  interrupt(id: string): Promise<void>;
+  terminate(id: string): Promise<void>;
+  fetch(request: Request): Promise<Response>;
+}
+declare function proxyTerminal(stub: Pick<TerminalHandleStub, 'fetch'>, terminalId: string, request: Request, options: {
+  cursor?: TerminalOutputCursor;
+  cols?: number;
+  rows?: number;
+  runtimeIncarnationID: string;
+}): Promise<Response>;
+//#endregion
+//#region src/backup/restore-fault-injection.d.ts
+type BackupRestoreFaultPhase = 'after_archive_ready';
+type BackupRestoreTestFault = {
+  phase: BackupRestoreFaultPhase;
+  mode: 'transport_disposed';
+  times: number;
+};
+//#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 fusermount -u fails to unmount a FUSE filesystem
+ */
+declare class BucketUnmountError 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
+//#region src/storage-mount/outbound/container-proxy.d.ts
+declare class ContainerProxy extends ContainerProxy$1 {
+  fetch(request: Request): Promise<Response>;
+}
+//#endregion
+//#region src/tunnels/tunnel-service.d.ts
+interface TunnelsHandler {
+  get(port: number, options?: TunnelOptions): Promise<TunnelInfo>;
+  list(): Promise<TunnelInfo[]>;
+  destroy(portOrInfo: number | TunnelInfo): Promise<void>;
+}
+//#endregion
+//#region src/sandbox.d.ts
+type SandboxConfiguration = {
+  sandboxName?: {
+    name: string;
+    normalizeId?: boolean;
+  };
+  sleepAfter?: string | number;
+  keepAlive?: boolean;
+  containerTimeouts?: NonNullable<SandboxOptions['containerTimeouts']>;
+};
+type InternalSandboxRPCMethod = 'authorizePortRequest';
+type SandboxClient<T> = Omit<T, keyof ISandbox | InternalSandboxRPCMethod> & ISandbox;
+type CancellationOptions = {
+  abort?: AbortSignal;
+  instanceGetTimeoutMS?: number;
+  portReadyTimeoutMS?: number;
+  waitInterval?: number;
+};
+type StartAndWaitForPortsOptions = {
+  startOptions?: ContainerStartConfigOptions;
+  ports?: number | number[];
+  cancellationOptions?: CancellationOptions;
+};
+declare function getSandbox<T extends Sandbox<any>>(ns: DurableObjectNamespace<T>, id: string, options?: SandboxOptions): SandboxClient<T>;
+declare class Sandbox<Env = unknown> extends Container<Env> {
+  #private;
+  defaultPort: number;
+  sleepAfter: string | number;
+  private runtimeSessions;
+  private runtimeLifecycle;
+  private runtimeRunner;
+  private sandboxName;
+  private tunnelServiceHandle;
+  private tunnelsHandler;
+  private tunnelExitHandler;
+  private readonly controlCallback;
+  private normalizeId;
+  envVars: Record<string, string>;
+  private readonly portRequestTokens;
+  private logger;
+  private keepAliveEnabled;
+  private bucketMounts;
+  private currentLifetime;
+  private backupService;
+  private previewService;
+  private resourceActivityGate;
+  private r2AccessKeyId;
+  private r2SecretAccessKey;
+  private namedTunnelConfigResolver;
+  /**
+   * 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;
+  /**
+   * True once containerTimeouts has been written to storage at least once
+   * (either via setContainerTimeouts or restored on cold start). Gates the
+   * idempotency check in setContainerTimeouts so a first explicit call
+   * persists even when the requested values already equal the in-memory
+   * defaults, distinguishing "user intent recorded" from "running on
+   * env/SDK defaults".
+   */
+  private hasStoredContainerTimeouts;
+  /**
+   * Dispatch method for tunnel operations.
+   * Called by the client-side proxy created in getSandbox() to provide
+   * the `sandbox.tunnels` API without relying on RPC pipelining through
+   * property getters, which vite-plugin does not currently support. This
+   * local method dispatch uses standard function application, so new
+   * Workers RPC pipelining traits on `TunnelsRpcTarget` also need an
+   * explicit path here before the proxy can expose them.
+   */
+  callTunnels(method: string, args: unknown[]): Promise<unknown>;
+  callExtension(extensionName: string, method: string, args: unknown[]): Promise<unknown>;
+  private renewActivityTimeoutIfAvailable;
+  private getRuntimePortStub;
+  constructor(ctx: DurableObjectState<{}>, env: Env);
+  setSandboxName(name: string, normalizeId?: boolean): Promise<void>;
+  configure(configuration: SandboxConfiguration): Promise<void>;
+  setSleepAfter(sleepAfter: string | number): Promise<void>;
+  setKeepAlive(keepAlive: boolean): Promise<void>;
+  setEnvVars(envVars: Record<string, string | undefined>): Promise<void>;
+  setContainerTimeouts(timeouts: NonNullable<SandboxOptions['containerTimeouts']>): Promise<void>;
+  private validateTimeout;
+  private getDefaultTimeouts;
+  /**
+   * Mount an S3-compatible bucket as a local directory.
+   */
+  mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+  /**
+   * Manually unmount a bucket filesystem.
+   */
+  unmountBucket(mountPath: string): Promise<void>;
+  /**
+   * In-flight `destroy()` promise. While set, concurrent callers coalesce
+   * onto the same teardown instead of triggering a second one. Cleared when
+   * the underlying work settles, so a later call that genuinely needs to
+   * recreate a destroyed sandbox still runs.
+   *
+   * If the underlying teardown hangs (e.g. `super.destroy()` never resolves
+   * because the Containers control plane is unresponsive), every coalesced
+   * caller hangs on the same promise until the Durable Object is evicted.
+   * This is deliberate: a second concurrent teardown would not make a stuck
+   * control plane unstuck, and spawning one would defeat the point of
+   * coalescing. Callers that need bounded waits must apply their own
+   * timeout around `destroy()`.
+   */
+  private inflightDestroy;
+  /**
+   * Cleanup and destroy the sandbox container.
+   *
+   * Concurrent calls coalesce: if a previous `destroy()` is still in flight,
+   * subsequent calls await the same underlying work instead of starting a
+   * second teardown. A canonical `sandbox.destroy.coalesced` event is logged
+   * per coalesced call so repeated destroy traffic is observable.
+   */
+  destroy(): Promise<void>;
+  private doDestroy;
+  private performRuntimeStop;
+  private runBoundedDestroyRuntimeCleanup;
+  private cleanupRuntimeBeforeDestroy;
+  private createTeardownTunnelsHandle;
+  private createDurableDestroyTunnelsHandle;
+  private createDestroyTunnelsHandle;
+  onStart(): Promise<void>;
+  start(options?: Parameters<Container<Env>['start']>[0]): Promise<void>;
+  startAndWaitForPorts(args: StartAndWaitForPortsOptions): Promise<void>;
+  startAndWaitForPorts(portsOrArgs?: number | number[] | StartAndWaitForPortsOptions, cancellationOptions?: CancellationOptions, startOptions?: ContainerStartConfigOptions): Promise<void>;
+  stop(signal?: Parameters<Container<Env>['stop']>[0]): Promise<void>;
+  onStop(): Promise<void>;
+  onError(error: unknown): void;
+  /**
+   * Override Container.containerFetch to route direct forwarding through runtime admission.
+   */
+  containerFetch(requestOrUrl: Request | string | URL, portOrInit?: number | RequestInit, portParam?: number): Promise<Response>;
+  private containerStartupErrorResponse;
+  /**
+   * Helper: Check if error is "no container instance available"
+   * This indicates the container VM is still being provisioned.
+   */
+  private isNoInstanceError;
+  /**
+   * Helper: Check if error is a transient startup error that should trigger retry
+   *
+   * These errors occur during normal container startup and are recoverable:
+   * - Port not yet mapped (container starting, app not listening yet)
+   * - Connection refused (port mapped but app not ready)
+   * - Timeouts during startup (recoverable with retry)
+   * - Network transients (temporary connectivity issues)
+   *
+   * Errors NOT included (permanent failures):
+   * - "no such image" - missing Docker image
+   * - "container already exists" - name collision
+   * - Configuration errors
+   */
+  private isTransientStartupError;
+  /**
+   * Helper: Check if error is a permanent startup failure that will never recover
+   *
+   * These errors indicate resource exhaustion, misconfiguration, or missing images.
+   * Retrying will never succeed, so the SDK should fail fast with HTTP 500.
+   *
+   * Error sources (traced from platform internals):
+   *   - Container runtime: OOM, PID limit
+   *   - Scheduling/provisioning: no matching app, no namespace configured
+   *   - workerd container-client.c++: no such image
+   *   - @cloudflare/containers: did not call start
+   */
+  private isPermanentStartupError;
+  /**
+   * Helper: Parse containerFetch arguments (supports multiple signatures)
+   */
+  private parseContainerFetchArgs;
+  onActivityExpired(): Promise<void>;
+  private getPreviewForwardingContainer;
+  fetch(request: Request): Promise<Response>;
+  wsConnect(request: Request, port: number): Promise<Response>;
+  authorizePortRequest(port: number, path: string): Promise<string>;
+  private connectWebSocket;
+  createTerminal(options: CreateTerminalOptions): Promise<TerminalRPCDescriptor>;
+  getTerminal(id: string): Promise<TerminalRPCDescriptor | null>;
+  listTerminals(): Promise<TerminalRPCDescriptor[]>;
+  private terminalDescriptor;
+  private terminalStub;
+  private determinePort;
+  exec(command: SandboxCommand, options?: ExecOptions): Promise<ProcessRPCDescriptor>;
+  private processDescriptor;
+  private processCapabilityLifecycle;
+  /** Internal bridge liveness read that neither starts nor renews a runtime. */
+  isRuntimeActive(): Promise<boolean>;
+  getProcess(id: string): Promise<ProcessRPCDescriptor | null>;
+  listProcesses(): Promise<ProcessStatus[]>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+  }): Promise<MkdirResult>;
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+    encoding?: string;
+  }): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  } | WriteFileResult>;
+  deleteFile(path: string): Promise<DeleteFileResult>;
+  renameFile(oldPath: string, newPath: string): Promise<RenameFileResult>;
+  moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
+  /**
+   * Read a file from the sandbox.
+   *
+   * @param encoding - How to encode the returned content:
+   *   - `undefined` (default): auto-detect from MIME type (text → UTF-8 string, binary → base64 string)
+   *   - `'utf-8'` / `'utf8'`: always return as UTF-8 string
+   *   - `'base64'`: always return as base64-encoded string
+   *   - `'none'`: return a result whose `content` is a raw binary `ReadableStream<Uint8Array>`
+   *              with no encoding overhead.
+   */
+  readFile(path: string, options: {
+    encoding: 'none';
+  }): Promise<ReadFileStreamResult>;
+  readFile(path: string, options?: {
+    encoding?: Exclude<FileEncoding, 'none'>;
+  }): 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
+   */
+  createWorkspaceArchive(options?: {
+    root: string;
+    excludes?: readonly string[];
+  }): Promise<string>;
+  extractWorkspaceArchive(options: {
+    root: string;
+    archivePath: string;
+  }): Promise<void>;
+  cleanupWorkspaceArchive(archivePath: string): Promise<void>;
+  cleanupMountDirectory(mountPath: string): Promise<void>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  listFiles(path: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string): Promise<FileExistsResult>;
+  /**
+   * Watch a directory for file system changes using native inotify.
+   *
+   * The returned promise resolves only after the watcher is established on the
+   * filesystem, so callers can immediately perform actions that depend on the
+   * watch being active. The returned stream contains the full event sequence
+   * starting with the `watching` event.
+   *
+   * Consume the stream with `parseSSEStream<FileWatchSSEEvent>(stream)`.
+   *
+   * @param path - Path to watch (absolute or relative to /workspace)
+   * @param options - Watch options
+   */
+  watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Check whether a path changed while this caller was disconnected.
+   *
+   * Pass the `version` returned from a prior call in `options.since` to learn
+   * whether the path is unchanged, changed, or needs a full resync because the
+   * retained change state was reset.
+   *
+   * @param path - Path to check (absolute or relative to /workspace)
+   * @param options - Change-check options
+   */
+  checkChanges(path: string, options?: CheckChangesOptions): Promise<CheckChangesResult>;
+  /**
+   * Expose a port and get a preview URL for accessing services running in the sandbox
+   *
+   * Preview URL authorization survives transient container restarts, but
+   * forwarding is active only for the runtime where `exposePort()` was last
+   * called. Call `exposePort()` again after a restart to reactivate an
+   * existing URL for the current runtime.
+   *
+   * @param port - Port number to expose (1024-65535)
+   * @param options - Configuration options
+   * @param options.hostname - Your Worker's domain name (required for preview URL construction)
+   * @param options.name - Optional friendly name for the port
+   * @param options.token - Optional custom token for the preview URL (1-16 characters: lowercase letters, numbers, underscores)
+   *                       If not provided, a random 16-character token will be generated automatically
+   * @returns Preview URL information including the full URL, port number, and optional name
+   *
+   * @example
+   * // With auto-generated token
+   * const { url } = await sandbox.exposePort(8080, { hostname: 'example.com' });
+   * // url: https://8080-sandbox-id-abc123random4567.example.com
+   *
+   * @example
+   * // With custom token for stable URLs across deployments
+   * const { url } = await sandbox.exposePort(8080, {
+   *   hostname: 'example.com',
+   *   token: 'my_token_v1'
+   * });
+   * // url: https://8080-sandbox-id-my_token_v1.example.com
+   */
+  private runWakingComposite;
+  [sandboxRuntimeCall]: ExtensionRuntimeCall;
+  exposePort(port: number, options: {
+    name?: string;
+    hostname: string;
+    token?: string;
+  }): Promise<{
+    url: string;
+    port: number;
+    name?: string;
+  }>;
+  /**
+   * Revoke preview URL authorization and current-runtime activation for a port.
+   *
+   * Revocation is idempotent: calling this for a port with no preview state is
+   * still successful. The operation clears Durable Object-owned preview state
+   * only and does not contact, probe, wake, or clean up the container runtime.
+   */
+  unexposePort(port: number): Promise<void>;
   /**
-   * Create a new code execution context
+   * Returns preview URLs that are currently forwardable in the active runtime.
+   * Durable authorization without current-runtime activation is omitted.
    */
-  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  getExposedPorts(hostname: string): Promise<{
+    url: string;
+    port: number;
+    status: "active";
+  }[]>;
   /**
-   * Run code with optional context
+   * Returns whether a port is currently preview-forwardable.
+   * This checks Durable Object-owned auth and runtime activation without
+   * contacting or waking the container.
    */
-  runCode(code: string, options?: RunCodeOptions): Promise<Execution>;
+  isPortExposed(port: number): Promise<boolean>;
   /**
-   * Run code and return a streaming response
+   * Checks durable preview URL authorization for a port/token pair.
+   *
+   * This does not check whether the port is activated for the current runtime
+   * and is not sufficient to decide whether preview traffic may forward.
    */
-  runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
+  validatePortToken(port: number, token: string): Promise<boolean>;
   /**
-   * List all code contexts
+   * Namespaced tunnel API. Quick tunnels are zero-config preview URLs
+   * backed by Cloudflare's trycloudflare service. Named tunnels bind a
+   * stable hostname under the configured Cloudflare zone.
+   *
+   * - `tunnels.get(port)` — idempotent. Returns the cached tunnel for
+   *   `port` if one exists in DO storage, otherwise spawns a fresh
+   *   cloudflared process and persists the record.
+   * - `tunnels.list()` — returns tunnels currently usable through this
+   *   sandbox runtime.
+   * - `tunnels.destroy(portOrInfo)` — tear down by port number or by
+   *   the record returned from `get()`.
+   *
+   * Container restarts drop quick-tunnel records because their
+   * `*.trycloudflare.com` URLs are tied to the dead cloudflared process.
+   * Named-tunnel records stay in storage and are marked for respawn so the
+   * next `get(port, { name })` call reuses the Cloudflare tunnel and DNS
+   * record while starting a fresh cloudflared process.
    */
-  listCodeContexts(): Promise<CodeContext[]>;
+  get tunnels(): TunnelsHandler;
   /**
-   * Delete a code context
+   * Lazily construct the tunnel subsystem handle. Called from the
+   * `tunnels` getter on first access and from sandbox lifecycle hooks
+   * when tunnel reconciliation or cleanup is needed.
    */
-  deleteCodeContext(contextId: string): Promise<void>;
-  private getOrCreateDefaultContext;
+  private ensureTunnelsBuilt;
+  /**
+   * Create a backup of a directory and upload it to R2.
+   *
+   * The returned DirectoryBackup handle is serializable. Store it anywhere
+   * (KV, D1, DO storage) and pass it to restoreBackup() later.
+   *
+   * Concurrent backup/restore calls on the same sandbox are serialized.
+   */
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  /**
+   * Restore a backup from R2 into a directory.
+   *
+   * Production restores use a FUSE overlay mount. Local-bucket restores stream
+   * the archive through the R2 binding and extract it with unsquashfs.
+   *
+   * Concurrent backup/restore calls on the same sandbox are serialized.
+   */
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
+  __setBackupRestoreFaultForTesting(fault: BackupRestoreTestFault | null): Promise<void>;
+  registerGitAuthInterceptor(params: HTTPAuthInterceptorParams): Promise<void>;
+  private getMountOutboundHost;
 }
 //#endregion
-//#region src/pty/proxy.d.ts
-declare function proxyTerminal(stub: {
-  fetch: (request: Request) => Promise<Response>;
-}, sessionId: string, request: Request, options?: PtyOptions): Promise<Response>;
-//#endregion
 //#region src/request-handler.d.ts
 interface SandboxEnv<T extends Sandbox<any> = Sandbox<any>> {
   Sandbox: DurableObjectNamespace<T>;
@@ -233,38 +572,5 @@ declare function asyncIterableToSSEStream<T>(events: AsyncIterable<T>, options?:
   serialize?: (event: T) => string;
 }): ReadableStream<Uint8Array>;
 //#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 fusermount -u fails to unmount a FUSE filesystem
- */
-declare class BucketUnmountError 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 { BackupCreateError, BackupExpiredError, BackupNotFoundError, type BackupOptions, BackupRestoreError, type BaseExecOptions, type BucketCredentials, BucketMountError, type BucketProvider, BucketUnmountError, type CheckChangesOptions, type CheckChangesResult, type CodeContext, CodeInterpreter, ContainerProxy, ContainerUnavailableError, type CreateContextOptions, type DirectoryBackup, type ExecEvent, type ExecOptions, type ExecResult, type ExecutionResult, type ExecutionSession, type FileChunk, type FileMetadata, type FileStreamEvent, type FileWatchSSEEvent, type GitCheckoutResult, type ISandbox, InvalidBackupConfigError, InvalidMountConfigError, type ListFilesOptions, type LocalMountBucketOptions, type LogEvent, MissingCredentialsError, type MountBucketOptions, type NamedTunnelInfo, type Process, ProcessExitedBeforeReadyError, type ProcessOptions, ProcessReadyTimeoutError, type ProcessStatus, type PtyOptions, type QuickTunnelInfo, type RPCTransportContext, RPCTransportError, type RPCTransportErrorKind, type RemoteMountBucketOptions, type RestoreBackupResult, type RunCodeOptions, S3FSMountError, Sandbox, type SandboxEnv, type SandboxOptions, type SessionOptions, SessionTerminatedError, type StreamOptions, type TunnelInfo, type TunnelOptions, type WaitForLogResult, type WaitForPortOptions, type WatchOptions, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BackupCreateError, BackupExpiredError, BackupNotFoundError, type BackupOptions, BackupRestoreError, type BucketCredentials, BucketMountError, type BucketProvider, BucketUnmountError, type CheckChangesOptions, type CheckChangesResult, ContainerProxy, ContainerUnavailableError, type CreateTerminalOptions, type DirectoryBackup, type ExecOptions, type FileChunk, type FileMetadata, type FileStreamEvent, type FileWatchSSEEvent, type ISandbox, InvalidBackupConfigError, InvalidMountConfigError, InvalidProcessCursorError, InvalidProcessCwdError, InvalidProcessEnvironmentError, InvalidTerminalCursorError, InvalidTerminalCwdError, type ListFilesOptions, type LocalMountBucketOptions, MissingCredentialsError, type MountBucketOptions, type NamedTunnelInfo, OperationInterruptedError, ProcessAbortedError, ProcessError, type ProcessExit, ProcessExitedBeforeLogError, ProcessExitedBeforeReadyError, type ProcessFailure, type ProcessLogCursor, type ProcessLogEvent, type ProcessLogsOptions, ProcessNotFoundError, type ProcessOutput, type ProcessOutputOptions, ProcessReadyTimeoutError, ProcessSpawnFailedError, type ProcessStatus, type ProcessTextOutputOptions, ProcessWaitTimeoutError, type QuickTunnelInfo, type RPCTransportContext, RPCTransportError, type RPCTransportErrorKind, type RemoteMountBucketOptions, type RestoreBackupResult, RuntimeControlProtocolError, RuntimeIdentityInactiveError, S3FSMountError, Sandbox, type SandboxCommand, type SandboxEnv, type SandboxOptions, type SandboxProcess, StaleProcessHandleError, StaleTerminalHandleError, type Terminal, TerminalControlError, TerminalNotFoundError, type TerminalOutputCursor, type TerminalOutputEvent, type TerminalOutputOptions, type TerminalSnapshot, type TunnelInfo, type TunnelOptions, type WaitForExitOptions, type WaitForLogOptions, type WaitForLogResult, type WaitForPortOptions, type WatchOptions, asyncIterableToSSEStream, collectFile, getSandbox, isDurableObjectCodeUpdateReset, isPlatformTransientError, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.d.ts.map