@cloudflare/sandbox 0.9.0 → 0.9.2

package/dist/{sandbox-Chr1Ebo-.d.ts → sandbox-YMrVC62F.d.ts}

@@ -1,7 +1,65 @@
 import { Container } from "@cloudflare/containers";
+import "capnweb";
 
-//#region ../shared/dist/logger/types.d.ts
+//#region ../shared/dist/desktop-types.d.ts
 
+interface DesktopStartResult {
+  success: boolean;
+  resolution: [number, number];
+  dpi: number;
+}
+interface DesktopStopResult {
+  success: boolean;
+}
+interface DesktopStatusResult {
+  success: boolean;
+  status: 'active' | 'partial' | 'inactive';
+  processes: Record<string, DesktopProcessHealth>;
+  resolution: [number, number] | null;
+  dpi: number | null;
+}
+interface DesktopProcessHealth {
+  running: boolean;
+  pid?: number;
+  uptime?: number;
+}
+type DesktopImageFormat = 'png' | 'jpeg' | 'webp';
+interface DesktopScreenshotRequest {
+  format?: 'base64';
+  imageFormat?: DesktopImageFormat;
+  quality?: number;
+  showCursor?: boolean;
+}
+interface DesktopScreenshotRegionRequest extends DesktopScreenshotRequest {
+  region: DesktopScreenshotRegion;
+}
+interface DesktopScreenshotRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface DesktopScreenshotResult {
+  success: boolean;
+  data: string;
+  imageFormat: DesktopImageFormat;
+  width: number;
+  height: number;
+}
+type DesktopMouseButton = 'left' | 'right' | 'middle';
+type DesktopScrollDirection = 'up' | 'down' | 'left' | 'right';
+interface DesktopCursorPosition {
+  success: boolean;
+  x: number;
+  y: number;
+}
+interface DesktopScreenSize {
+  success: boolean;
+  width: number;
+  height: number;
+}
+//#endregion
+//#region ../shared/dist/logger/types.d.ts
 type LogComponent = 'container' | 'sandbox-do' | 'executor';
 /**
  * Context metadata included in every log entry
@@ -826,6 +884,8 @@ interface SandboxOptions {
    * - `"http"` (default): Standard HTTP request/response. Works everywhere.
    * - `"websocket"`: Multiplexes requests over a single WebSocket connection,
    *   avoiding sub-request limits in Workers and Durable Objects.
+   * - `"capnweb"`: Direct RPC over a single WebSocket using the capnweb protocol.
+   *   Lowest latency; automatically disconnects when idle to respect `sleepAfter`.
    *
    * When set via `getSandbox()` options, this overrides the `SANDBOX_TRANSPORT` env var.
    *
@@ -836,7 +896,7 @@ interface SandboxOptions {
    *
    * @default "http"
    */
-  transport?: 'http' | 'websocket';
+  transport?: 'http' | 'websocket' | 'rpc';
 }
 /**
  * Execution session - isolated execution context within a sandbox
@@ -1166,7 +1226,7 @@ interface ExecutionSession {
   streamProcessLogs(processId: string, options?: {
     signal?: AbortSignal;
   }): Promise<ReadableStream<Uint8Array>>;
-  writeFile(path: string, content: string, options?: {
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
     encoding?: string;
   }): Promise<WriteFileResult>;
   readFile(path: string, options?: {
@@ -1371,7 +1431,7 @@ interface ISandbox {
     stderr: string;
     processId: string;
   }>;
-  writeFile(path: string, content: string, options?: {
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
     encoding?: string;
   }): Promise<WriteFileResult>;
   readFile(path: string, options?: {
@@ -1402,6 +1462,13 @@ interface ISandbox {
   unmountBucket(mountPath: string): Promise<void>;
   createSession(options?: SessionOptions): Promise<ExecutionSession>;
   deleteSession(sessionId: string): Promise<SessionDeleteResult>;
+  /**
+   * Returns the Cloudflare placement ID observed during the most recent
+   * session-create handshake with the container. `null` when the container
+   * does not expose `CLOUDFLARE_PLACEMENT_ID` (local development). `undefined`
+   * when no handshake has been observed yet on this sandbox.
+   */
+  getContainerPlacementId(): Promise<string | null | undefined>;
   createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
   runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
   runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
@@ -1415,6 +1482,162 @@ 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 ../shared/dist/rpc-types.d.ts
+interface SandboxCommandsAPI {
+  execute(command: string, sessionId: string, options?: {
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+  }): Promise<{
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string;
+    timestamp: string;
+  }>;
+  executeStream(command: string, sessionId: string, options?: {
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+  }): Promise<ReadableStream<Uint8Array>>;
+}
+interface SandboxFilesAPI {
+  readFile(path: string, sessionId: string, options?: {
+    encoding?: string;
+  }): Promise<ReadFileResult>;
+  readFileStream(path: string, sessionId: string): Promise<ReadableStream<Uint8Array>>;
+  writeFile(path: string, content: string, sessionId: string, options?: {
+    encoding?: string;
+    permissions?: string;
+  }): Promise<WriteFileResult>;
+  writeFileStream(path: string, stream: ReadableStream<Uint8Array>, sessionId: string): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  }>;
+  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>;
+  mkdir(path: string, sessionId: string, options?: {
+    recursive?: boolean;
+  }): Promise<MkdirResult>;
+  listFiles(path: string, sessionId: string, options?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string, sessionId: string): Promise<FileExistsResult>;
+}
+interface SandboxProcessesAPI {
+  startProcess(command: string, sessionId: string, options?: {
+    processId?: string;
+    timeoutMs?: number;
+  }): Promise<ProcessStartResult>;
+  listProcesses(): Promise<ProcessListResult>;
+  getProcess(id: string): Promise<ProcessInfoResult>;
+  killProcess(id: string): Promise<ProcessKillResult>;
+  killAllProcesses(): Promise<ProcessCleanupResult>;
+  getProcessLogs(id: string): Promise<ProcessLogsResult>;
+  streamProcessLogs(id: string): Promise<ReadableStream<Uint8Array>>;
+}
+interface SandboxPortsAPI {
+  exposePort(port: number, sessionId: string, name?: string): Promise<PortExposeResult>;
+  getExposedPorts(sessionId: string): Promise<PortListResult>;
+  unexposePort(port: number, sessionId: string): Promise<PortCloseResult>;
+  watchPort(request: PortWatchRequest): Promise<ReadableStream<Uint8Array>>;
+}
+interface SandboxGitAPI {
+  checkout(repoUrl: string, sessionId: string, options?: {
+    branch?: string;
+    targetDir?: string;
+    depth?: number;
+    timeoutMs?: number;
+  }): Promise<GitCheckoutResult>;
+}
+interface SandboxInterpreterAPI {
+  createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
+  streamCode(contextId: string, code: string, language?: string): Promise<ReadableStream<Uint8Array>>;
+  runCodeStream(contextId: string | undefined, code: string, language: string | undefined, callbacks: {
+    onStdout?: (output: OutputMessage) => void | Promise<void>;
+    onStderr?: (output: OutputMessage) => void | Promise<void>;
+    onResult?: (result: Result) => void | Promise<void>;
+    onError?: (error: ExecutionError) => void | Promise<void>;
+  }, timeoutMs?: number): Promise<void>;
+  listCodeContexts(): Promise<CodeContext[]>;
+  deleteCodeContext(contextId: string): Promise<void>;
+}
+interface SandboxUtilsAPI {
+  ping(): Promise<string>;
+  getVersion(): Promise<string>;
+  getCommands(): Promise<string[]>;
+  createSession(options: {
+    id: string;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+  }): Promise<{
+    success: boolean;
+    id: string;
+    message: string;
+    timestamp: string;
+    containerPlacementId?: string | null;
+  }>;
+  deleteSession(sessionId: string): Promise<{
+    success: boolean;
+    sessionId: string;
+    timestamp: string;
+  }>;
+  listSessions(): Promise<{
+    sessions: string[];
+  }>;
+}
+interface SandboxBackupAPI {
+  createArchive(dir: string, archivePath: string, sessionId: string, options?: {
+    excludes?: string[];
+    gitignore?: boolean;
+  }): Promise<CreateBackupResponse>;
+  restoreArchive(dir: string, archivePath: string, sessionId: string): Promise<RestoreBackupResponse>;
+}
+interface SandboxDesktopAPI {
+  start(options?: {
+    resolution?: [number, number];
+    dpi?: number;
+  }): Promise<DesktopStartResult>;
+  stop(): Promise<DesktopStopResult>;
+  status(): Promise<DesktopStatusResult>;
+  screenshot(options?: DesktopScreenshotRequest): Promise<DesktopScreenshotResult>;
+  screenshotRegion(request: DesktopScreenshotRegionRequest): Promise<DesktopScreenshotResult>;
+  click(x: number, y: number, options?: {
+    button?: DesktopMouseButton;
+    clickCount?: number;
+  }): Promise<void>;
+  doubleClick(x: number, y: number): Promise<void>;
+  tripleClick(x: number, y: number): Promise<void>;
+  rightClick(x: number, y: number): Promise<void>;
+  middleClick(x: number, y: number): Promise<void>;
+  mouseDown(x?: number, y?: number, options?: {
+    button?: DesktopMouseButton;
+  }): Promise<void>;
+  mouseUp(x?: number, y?: number, options?: {
+    button?: DesktopMouseButton;
+  }): Promise<void>;
+  moveMouse(x: number, y: number): Promise<void>;
+  drag(startX: number, startY: number, endX: number, endY: number, options?: {
+    button?: DesktopMouseButton;
+  }): Promise<void>;
+  scroll(x: number, y: number, direction: DesktopScrollDirection, amount?: number): Promise<void>;
+  getCursorPosition(): Promise<DesktopCursorPosition>;
+  type(text: string, options?: {
+    delay?: number;
+  }): Promise<void>;
+  press(key: string): Promise<void>;
+  keyDown(key: string): Promise<void>;
+  keyUp(key: string): Promise<void>;
+  getScreenSize(): Promise<DesktopScreenSize>;
+  getProcessStatus(name: string): Promise<DesktopStatusResult>;
+}
+interface SandboxWatchAPI {
+  watch(request: WatchRequest): Promise<ReadableStream<Uint8Array>>;
+  checkChanges(request: CheckChangesRequest): Promise<CheckChangesResult>;
+}
+//#endregion
 //#region src/clients/types.d.ts
 /**
  * Minimal interface for container fetch functionality
@@ -1502,7 +1725,7 @@ interface SessionRequest {
 /**
  * Transport mode for SDK communication
  */
-type TransportMode = 'http' | 'websocket';
+type TransportMode = 'http' | 'websocket' | 'rpc';
 interface TransportRequestInit extends RequestInit {
   /** Override the non-streaming request timeout for this single request. */
   requestTimeoutMs?: number;
@@ -1627,7 +1850,10 @@ declare class BackupClient extends BaseHttpClient {
    * @param archivePath - Where the container should write the archive
    * @param sessionId - Session context
    */
-  createArchive(dir: string, archivePath: string, sessionId: string, gitignore?: boolean, excludes?: string[]): Promise<CreateBackupResponse>;
+  createArchive(dir: string, archivePath: string, sessionId: string, options?: {
+    excludes?: string[];
+    gitignore?: boolean;
+  }): Promise<CreateBackupResponse>;
   /**
    * Tell the container to restore a squashfs archive into a directory.
    * @param dir - Target directory
@@ -2178,11 +2404,16 @@ interface CreateSessionRequest {
   commandTimeoutMs?: number;
 }
 /**
- * Response interface for creating sessions
+ * Response interface for creating sessions.
+ *
+ * `containerPlacementId` carries the container's `CLOUDFLARE_PLACEMENT_ID` at session
+ * creation time so the DO can capture it without a separate request. It is
+ * `null` when the environment variable is not set, such as in local dev.
  */
 interface CreateSessionResponse extends BaseApiResponse {
   id: string;
   message: string;
+  containerPlacementId?: string | null;
 }
 /**
  * Request interface for deleting sessions
@@ -2258,14 +2489,13 @@ declare class WatchClient extends BaseHttpClient {
 //#endregion
 //#region src/clients/sandbox-client.d.ts
 /**
- * Main sandbox client that composes all domain-specific clients
- * Provides organized access to all sandbox functionality
+ * Main sandbox client that composes all domain-specific clients.
+ * Provides organized access to all sandbox functionality.
  *
  * Supports two transport modes:
  * - HTTP (default): Each request is a separate HTTP call
- * - WebSocket: All requests multiplexed over a single connection
- *
- * WebSocket mode reduces sub-request count when running inside Workers/Durable Objects.
+ * - WebSocket: All requests multiplexed over a single connection,
+ *   reducing sub-request count inside Workers/Durable Objects
  */
 declare class SandboxClient {
   readonly backup: BackupClient;
@@ -2296,6 +2526,19 @@ declare class SandboxClient {
    * Check if WebSocket is connected (only relevant in WebSocket mode)
    */
   isWebSocketConnected(): boolean;
+  /**
+   * Stream a file directly to the container over a binary RPC channel.
+   *
+   * Requires the capnweb transport (`useWebSocket: 'rpc'`). Calling this
+   * method with the HTTP or WebSocket transports throws an error because those
+   * transports do not support binary streaming.
+   */
+  writeFileStream(_path: string, _content: ReadableStream<Uint8Array>, _sessionId: string): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  }>;
   /**
    * Connect WebSocket transport (no-op in HTTP mode)
    * Called automatically on first request, but can be called explicitly
@@ -2309,6 +2552,132 @@ declare class SandboxClient {
   disconnect(): void;
 }
 //#endregion
+//#region src/container-connection.d.ts
+/** Stub that can issue a WebSocket-upgrade fetch through the DO's Container base class. */
+interface ContainerFetchStub {
+  fetch(request: Request): Promise<Response>;
+}
+interface ContainerConnectionOptions {
+  stub: ContainerFetchStub;
+  port?: number;
+  logger?: Logger;
+}
+//#endregion
+//#region src/clients/rpc-sandbox-client.d.ts
+interface RPCSandboxClientOptions extends ContainerConnectionOptions {
+  /** Idle timeout before disconnecting the WebSocket (ms). Defaults to 1 000. */
+  idleDisconnectMs?: number;
+  /** Busy/idle poll interval (ms). Defaults to 1 000. */
+  busyPollIntervalMs?: number;
+  /**
+   * Renew the DO's activity timeout. Fires at the start of every RPC call
+   * and on every busy-poll tick while the session has work in flight.
+   * Mirrors what `containerFetch()` does at the top of each HTTP request.
+   */
+  onActivity?: () => void;
+  /**
+   * Fires once when the capnweb session transitions from idle to busy
+   * (an RPC call was started or a stream return is now in flight). The
+   * Sandbox DO wires this to `inflightRequests++`, which makes
+   * `isActivityExpired()` skip the sleepAfter comparison.
+   */
+  onSessionBusy?: () => void;
+  /**
+   * Fires once when the session transitions from busy back to idle
+   * (all RPC promises settled and all stream exports released). The
+   * Sandbox DO wires this to `inflightRequests = max(0, n-1)` and a
+   * final `renewActivityTimeout()`, matching containerFetch's finally
+   * block.
+   */
+  onSessionIdle?: () => void;
+}
+/**
+ * SandboxClient backed by direct capnweb RPC.
+ *
+ * Drop-in replacement for SandboxClient when the capnweb transport is active.
+ * All operations call the container's SandboxRPCAPI directly over capnweb,
+ * bypassing the HTTP handler/router layer entirely.
+ *
+ * Manages its own WebSocket lifecycle: a fresh `ContainerConnection` is
+ * created on demand and torn down after `idleDisconnectMs` of inactivity.
+ * Busy/idle detection relies on `RpcSession.getStats()` which tracks all
+ * in-flight RPC calls and stream exports — including long-lived streaming
+ * RPCs that would be invisible to a simple per-call request counter (see
+ * the file-level comment for the full rationale).
+ */
+declare class RPCSandboxClient {
+  private readonly connOptions;
+  private readonly idleDisconnectMs;
+  private readonly busyPollIntervalMs;
+  private readonly logger;
+  private readonly onActivity;
+  private readonly onSessionBusy;
+  private readonly onSessionIdle;
+  private conn;
+  private idleTimer;
+  private busyPollTimer;
+  /** Tracks whether we currently believe the session is busy. */
+  private busy;
+  /**
+   * Set the first time the poller observes `conn.isConnected() === true`,
+   * cleared in `destroyConnection()`. Lets us distinguish "the WebSocket
+   * upgrade is still in progress" (don't tear down) from "we were
+   * connected and the peer went away" (do tear down).
+   */
+  private wasEverConnected;
+  constructor(options: RPCSandboxClientOptions);
+  /**
+   * Return the current connection, creating a new one if none exists or the
+   * previous one was torn down by an idle disconnect. Starts the busy-poll
+   * timer the first time a connection is materialized.
+   */
+  private getConnection;
+  /**
+   * Called synchronously at the start of each RPC method invocation.
+   * Renews the DO activity timeout so the sleepAfter alarm is pushed
+   * forward before the container processes the call.
+   */
+  private renewActivity;
+  /**
+   * Sample `getStats()` and update busy/idle state. While busy, renews the
+   * activity timeout each tick so an in-flight stream keeps pushing the
+   * sleepAfter deadline forward. On the busy → idle edge, fires
+   * `onSessionIdle` and schedules the WebSocket disconnect.
+   *
+   * If the WebSocket has dropped underneath us (container crash, network
+   * blip) we tear the connection down here. `destroyConnection()` fires
+   * `onSessionIdle` if we were busy, so the DO's inflight counter doesn't
+   * stay pinned forever waiting for a peer that's never going to reply.
+   */
+  private pollBusyState;
+  private startBusyPoll;
+  private stopBusyPoll;
+  private scheduleIdleDisconnect;
+  private clearIdleTimer;
+  private destroyConnection;
+  get commands(): SandboxCommandsAPI;
+  get files(): SandboxFilesAPI;
+  get processes(): SandboxProcessesAPI;
+  get ports(): SandboxPortsAPI;
+  get git(): SandboxGitAPI;
+  get utils(): SandboxUtilsAPI;
+  get backup(): SandboxBackupAPI;
+  get desktop(): SandboxDesktopAPI;
+  get watch(): SandboxWatchAPI;
+  get interpreter(): SandboxInterpreterAPI;
+  setRetryTimeoutMs(_ms: number): void;
+  getTransportMode(): TransportMode;
+  isWebSocketConnected(): boolean;
+  connect(): Promise<void>;
+  disconnect(): void;
+  writeFileStream(path: string, stream: ReadableStream<Uint8Array>, sessionId: string): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  }>;
+}
+//#endregion
 //#region src/sandbox.d.ts
 type SandboxConfiguration = {
   sandboxName?: {
@@ -2318,13 +2687,13 @@ type SandboxConfiguration = {
   sleepAfter?: string | number;
   keepAlive?: boolean;
   containerTimeouts?: NonNullable<SandboxOptions['containerTimeouts']>;
-  transport?: 'http' | 'websocket';
+  transport?: 'http' | 'websocket' | 'rpc';
 };
 declare function getSandbox<T extends Sandbox<any>>(ns: DurableObjectNamespace<T>, id: string, options?: SandboxOptions): T;
 declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
   defaultPort: number;
   sleepAfter: string | number;
-  client: SandboxClient;
+  client: SandboxClient | RPCSandboxClient;
   private codeInterpreter;
   private sandboxName;
   private normalizeId;
@@ -2412,6 +2781,10 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * Create a SandboxClient with current transport settings
    */
   private createSandboxClient;
+  /**
+   * Create the appropriate client for a given transport protocol.
+   */
+  private createClientForTransport;
   constructor(ctx: DurableObjectState<{}>, env: Env);
   setSandboxName(name: string, normalizeId?: boolean): Promise<void>;
   configure(configuration: SandboxConfiguration): Promise<void>;
@@ -2431,7 +2804,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * has been persisted: re-applying the same transport is a no-op.
    * Storage is written before the in-memory state and client are updated.
    */
-  setTransport(transport: 'http' | 'websocket'): Promise<void>;
+  setTransport(transport: 'http' | 'websocket' | 'rpc'): Promise<void>;
   /**
    * Validate a timeout value is within acceptable range
    * Throws error if invalid - used for user-provided values
@@ -2493,9 +2866,30 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    */
   private executeS3FSMount;
   /**
-   * Cleanup and destroy the sandbox container
+   * 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;
   onStart(): Promise<void>;
   /**
    * Re-expose ports on the container runtime using tokens persisted in DO
@@ -2581,6 +2975,21 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    */
   private ensureDefaultSession;
   private initializeDefaultSession;
+  /**
+   * Persist the container's placement ID in DO storage.
+   *
+   * Called from the session-create handshake so subsequent reads via
+   * `getContainerPlacementId()` do not require a round-trip to the container. The value
+   * is overwritten on every handshake so that container replacements (which
+   * assign a new placement ID) are reflected on the next session-create.
+   *
+   * A value of `undefined` means the handshake response omitted the field
+   * (older container, unexpected error shape) and the stored value is left
+   * untouched. `null` means the env var is not set in the container and is
+   * stored as-is so callers can distinguish "observed and absent" from "not
+   * yet observed."
+   */
+  private capturePlacementId;
   exec(command: string, options?: ExecOptions): Promise<ExecResult>;
   /**
    * Execute an infrastructure command (backup, mount, env setup, etc.)
@@ -2669,10 +3078,15 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     recursive?: boolean;
     sessionId?: string;
   }): Promise<MkdirResult>;
-  writeFile(path: string, content: string, options?: {
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
     encoding?: string;
     sessionId?: string;
-  }): Promise<WriteFileResult>;
+  }): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  } | 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>;
@@ -2813,6 +3227,24 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * @throws Error if attempting to delete the default session
    */
   deleteSession(sessionId: string): Promise<SessionDeleteResult>;
+  /**
+   * Get the Cloudflare placement ID observed for the underlying container.
+   *
+   * The placement ID is captured during the first session-create handshake
+   * after a container start and stored in Durable Object storage, so this
+   * method returns the cached value without contacting the container. A new
+   * placement ID is captured on each subsequent session-create handshake,
+   * which occurs whenever the container has been replaced.
+   *
+   * Returns `null` when a handshake has completed but the container's
+   * `CLOUDFLARE_PLACEMENT_ID` environment variable is not set (for example,
+   * in local development).
+   *
+   * Returns `undefined` when no handshake has been observed yet on this
+   * sandbox. Call any method that triggers session creation (such as
+   * `exec()`) to populate the value.
+   */
+  getContainerPlacementId(): Promise<string | null | undefined>;
   private getSessionWrapper;
   createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
   runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
@@ -2830,6 +3262,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * Returns the R2 bucket or throws if backup is not configured.
    */
   private requireBackupBucket;
+  private normalizeBackupExcludes;
   private static readonly PRESIGNED_URL_EXPIRY_SECONDS;
   /**
    * Create a unique, dedicated session for a single backup operation.
@@ -2936,5 +3369,5 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   private doRestoreBackupLocal;
 }
 //#endregion
-export { CheckChangesOptions as $, DesktopStopResponse as A, SandboxOptions as At, ExecuteResponse as B, ExposePortRequest as Bt, ClickOptions as C, ProcessListResult as Ct, DesktopStartOptions as D, ProcessStatus as Dt, DesktopClient as E, ProcessStartResult as Et, ScreenshotRegion as F, WatchOptions as Ft, HttpClientOptions as G, Execution as Gt, BaseApiResponse as H, PtyOptions as Ht, ScreenshotResponse as I, isExecResult as It, SessionRequest as J, RequestConfig as K, ExecutionResult as Kt, ScrollDirection as L, isProcess as Lt, ScreenSizeResponse as M, StreamOptions as Mt, ScreenshotBytesResponse as N, WaitForLogResult as Nt, DesktopStartResponse as O, RemoteMountBucketOptions as Ot, ScreenshotOptions as P, WaitForPortOptions as Pt, BucketProvider as Q, TypeOptions as R, isProcessStatus as Rt, WriteFileRequest as S, ProcessKillResult as St, Desktop as T, ProcessOptions as Tt, ContainerStub as U, CodeContext as Ut, BackupClient as V, StartProcessRequest as Vt, ErrorResponse as W, CreateContextOptions as Wt, BaseExecOptions as X, BackupOptions as Y, BucketCredentials as Z, GitClient as _, PortExposeResult as _t, CreateSessionRequest as a, ExecutionSession as at, MkdirRequest as b, ProcessCleanupResult as bt, DeleteSessionResponse as c, FileStreamEvent as ct, ProcessClient as d, ISandbox as dt, CheckChangesResult as et, PortClient as f, ListFilesOptions as ft, GitCheckoutRequest as g, PortCloseResult as gt, InterpreterClient as h, MountBucketOptions as ht, CommandsResponse as i, ExecResult as it, KeyInput as j, SessionOptions as jt, DesktopStatusResponse as k, RestoreBackupResult as kt, PingResponse as l, FileWatchSSEEvent as lt, ExecutionCallbacks as m, LogEvent as mt, getSandbox as n, ExecEvent as nt, CreateSessionResponse as o, FileChunk as ot, UnexposePortRequest as p, LocalMountBucketOptions as pt, ResponseHandler as q, RunCodeOptions as qt, SandboxClient as r, ExecOptions as rt, DeleteSessionRequest as s, FileMetadata as st, Sandbox as t, DirectoryBackup as tt, UtilityClient as u, GitCheckoutResult as ut, FileClient as v, PortListResult as vt, CursorPositionResponse as w, ProcessLogsResult as wt, ReadFileRequest as x, ProcessInfoResult as xt, FileOperationRequest as y, Process as yt, CommandClient as z, ExecuteRequest as zt };
-//# sourceMappingURL=sandbox-Chr1Ebo-.d.ts.map
+export { BucketProvider as $, DesktopStopResponse as A, RestoreBackupResult as At, ExecuteResponse as B, ExecuteRequest as Bt, ClickOptions as C, ProcessKillResult as Ct, DesktopStartOptions as D, ProcessStartResult as Dt, DesktopClient as E, ProcessOptions as Et, ScreenshotRegion as F, WaitForPortOptions as Ft, HttpClientOptions as G, CreateContextOptions as Gt, BaseApiResponse as H, StartProcessRequest as Ht, ScreenshotResponse as I, WatchOptions as It, SessionRequest as J, RunCodeOptions as Jt, RequestConfig as K, Execution as Kt, ScrollDirection as L, isExecResult as Lt, ScreenSizeResponse as M, SessionOptions as Mt, ScreenshotBytesResponse as N, StreamOptions as Nt, DesktopStartResponse as O, ProcessStatus as Ot, ScreenshotOptions as P, WaitForLogResult as Pt, BucketCredentials as Q, TypeOptions as R, isProcess as Rt, WriteFileRequest as S, ProcessInfoResult as St, Desktop as T, ProcessLogsResult as Tt, ContainerStub as U, PtyOptions as Ut, BackupClient as V, ExposePortRequest as Vt, ErrorResponse as W, CodeContext as Wt, BackupOptions as X, SandboxInterpreterAPI as Y, BaseExecOptions as Z, GitClient as _, PortCloseResult as _t, CreateSessionRequest as a, ExecResult as at, MkdirRequest as b, Process as bt, DeleteSessionResponse as c, FileMetadata as ct, ProcessClient as d, GitCheckoutResult as dt, CheckChangesOptions as et, PortClient as f, ISandbox as ft, GitCheckoutRequest as g, MountBucketOptions as gt, InterpreterClient as h, LogEvent as ht, CommandsResponse as i, ExecOptions as it, KeyInput as j, SandboxOptions as jt, DesktopStatusResponse as k, RemoteMountBucketOptions as kt, PingResponse as l, FileStreamEvent as lt, ExecutionCallbacks as m, LocalMountBucketOptions as mt, getSandbox as n, DirectoryBackup as nt, CreateSessionResponse as o, ExecutionSession as ot, UnexposePortRequest as p, ListFilesOptions as pt, ResponseHandler as q, ExecutionResult as qt, SandboxClient as r, ExecEvent as rt, DeleteSessionRequest as s, FileChunk as st, Sandbox as t, CheckChangesResult as tt, UtilityClient as u, FileWatchSSEEvent as ut, FileClient as v, PortExposeResult as vt, CursorPositionResponse as w, ProcessListResult as wt, ReadFileRequest as x, ProcessCleanupResult as xt, FileOperationRequest as y, PortListResult as yt, CommandClient as z, isProcessStatus as zt };
+//# sourceMappingURL=sandbox-YMrVC62F.d.ts.map