@cloudflare/sandbox 0.7.7 → 0.7.10

package/dist/openai/index.d.ts

@@ -1,4 +1,4 @@
-import { t as Sandbox } from "../sandbox-DGAjk7r3.js";
+import { t as Sandbox } from "../sandbox-BYNjxjyr.js";
 import { ApplyPatchOperation, ApplyPatchResult, Editor as Editor$1, Shell as Shell$1, ShellAction, ShellResult } from "@openai/agents";
 
 //#region src/openai/index.d.ts

package/dist/openai/index.js

@@ -1,4 +1,4 @@
-import { l as createLogger } from "../dist-D9B_6gn_.js";
+import { u as createLogger } from "../dist-CwUZf_TJ.js";
 import { applyDiff } from "@openai/agents";
 
 //#region src/openai/index.ts

package/dist/opencode/index.d.ts

@@ -1,5 +1,5 @@
-import { t as Sandbox } from "../sandbox-DGAjk7r3.js";
-import { o as OpencodeStartupContext } from "../contexts-B0qA8qmx.js";
+import { t as Sandbox } from "../sandbox-BYNjxjyr.js";
+import { c as OpencodeStartupContext } from "../contexts-C5xSPEYL.js";
 import { OpencodeClient } from "@opencode-ai/sdk/v2/client";
 import { Config } from "@opencode-ai/sdk/v2";
 

package/dist/opencode/index.js

@@ -1,5 +1,5 @@
-import { l as createLogger } from "../dist-D9B_6gn_.js";
-import { t as ErrorCode } from "../errors-CAZT-Gtg.js";
+import { u as createLogger } from "../dist-CwUZf_TJ.js";
+import { t as ErrorCode } from "../errors-8W0q5Gll.js";
 
 //#region src/opencode/types.ts
 /**

package/dist/{sandbox-DGAjk7r3.d.ts → sandbox-BYNjxjyr.d.ts}

@@ -941,6 +941,71 @@ interface FileMetadata {
  * File stream chunk - either string (text) or Uint8Array (binary, auto-decoded)
  */
 type FileChunk = string | Uint8Array;
+/**
+ * Options for watching a directory.
+ *
+ * `watch()` resolves only after the watcher is established on the filesystem.
+ * The returned SSE stream can be consumed with `parseSSEStream()`.
+ */
+interface WatchOptions {
+  /**
+   * Watch subdirectories recursively
+   * @default true
+   */
+  recursive?: boolean;
+  /**
+   * Glob patterns to include (e.g., '*.ts', '*.js').
+   * If not specified, all files are included.
+   * Cannot be used together with `exclude`.
+   */
+  include?: string[];
+  /**
+   * Glob patterns to exclude (e.g., 'node_modules', '.git').
+   * Cannot be used together with `include`.
+   * @default ['.git', 'node_modules', '.DS_Store']
+   */
+  exclude?: string[];
+  /**
+   * Session to run the watch in.
+   * If omitted, the default session is used.
+   */
+  sessionId?: string;
+}
+/**
+ * @internal SSE event types for container communication
+ */
+type FileWatchEventType = 'create' | 'modify' | 'delete' | 'move_from' | 'move_to' | 'attrib';
+/**
+ * @internal Request body for starting a file watch
+ */
+interface WatchRequest {
+  path: string;
+  recursive?: boolean;
+  events?: FileWatchEventType[];
+  include?: string[];
+  exclude?: string[];
+  sessionId?: string;
+}
+/**
+ * SSE events emitted by `sandbox.watch()`.
+ */
+type FileWatchSSEEvent = {
+  type: 'watching';
+  path: string;
+  watchId: string;
+} | {
+  type: 'event';
+  eventType: FileWatchEventType;
+  path: string;
+  isDirectory: boolean;
+  timestamp: string;
+} | {
+  type: 'error';
+  error: string;
+} | {
+  type: 'stopped';
+  reason: string;
+};
 interface ProcessStartResult {
   success: boolean;
   processId: string;
@@ -1043,6 +1108,7 @@ interface ExecutionSession {
     encoding?: string;
   }): Promise<ReadFileResult>;
   readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  watch(path: string, options?: Omit<WatchOptions, 'sessionId'>): Promise<ReadableStream<Uint8Array>>;
   mkdir(path: string, options?: {
     recursive?: boolean;
   }): Promise<MkdirResult>;
@@ -1193,6 +1259,7 @@ interface ISandbox {
     encoding?: string;
   }): Promise<ReadFileResult>;
   readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
+  watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
   mkdir(path: string, options?: {
     recursive?: boolean;
   }): Promise<MkdirResult>;
@@ -1476,6 +1543,225 @@ declare class CommandClient extends BaseHttpClient {
   }): Promise<ReadableStream<Uint8Array>>;
 }
 //#endregion
+//#region src/clients/desktop-client.d.ts
+interface DesktopStartOptions {
+  resolution?: [number, number];
+  dpi?: number;
+}
+interface ScreenshotOptions {
+  format?: 'base64' | 'bytes';
+  imageFormat?: 'png' | 'jpeg' | 'webp';
+  quality?: number;
+  showCursor?: boolean;
+}
+interface ScreenshotRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface ClickOptions {
+  button?: 'left' | 'right' | 'middle';
+}
+type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+type KeyInput = string;
+interface TypeOptions {
+  delayMs?: number;
+}
+interface DesktopStartResponse extends BaseApiResponse {
+  resolution: [number, number];
+  dpi: number;
+}
+interface DesktopStopResponse extends BaseApiResponse {}
+interface DesktopStatusResponse extends BaseApiResponse {
+  status: 'active' | 'partial' | 'inactive';
+  processes: Record<string, {
+    running: boolean;
+    pid?: number;
+    uptime?: number;
+  }>;
+  resolution: [number, number] | null;
+  dpi: number | null;
+}
+interface ScreenshotResponse extends BaseApiResponse {
+  data: string;
+  imageFormat: 'png' | 'jpeg' | 'webp';
+  width: number;
+  height: number;
+}
+interface ScreenshotBytesResponse extends BaseApiResponse {
+  data: Uint8Array;
+  imageFormat: 'png' | 'jpeg' | 'webp';
+  width: number;
+  height: number;
+}
+interface CursorPositionResponse extends BaseApiResponse {
+  x: number;
+  y: number;
+}
+interface ScreenSizeResponse extends BaseApiResponse {
+  width: number;
+  height: number;
+}
+/**
+ * Public interface for desktop operations.
+ * Returned by `sandbox.desktop` via an RpcTarget wrapper so that pipelined
+ * method calls work across the Durable Object RPC boundary.
+ */
+interface Desktop {
+  start(options?: DesktopStartOptions): Promise<DesktopStartResponse>;
+  stop(): Promise<DesktopStopResponse>;
+  status(): Promise<DesktopStatusResponse>;
+  screenshot(options?: ScreenshotOptions & {
+    format?: 'base64';
+  }): Promise<ScreenshotResponse>;
+  screenshot(options: ScreenshotOptions & {
+    format: 'bytes';
+  }): Promise<ScreenshotBytesResponse>;
+  screenshot(options?: ScreenshotOptions): Promise<ScreenshotResponse | ScreenshotBytesResponse>;
+  screenshotRegion(region: ScreenshotRegion, options?: ScreenshotOptions & {
+    format?: 'base64';
+  }): Promise<ScreenshotResponse>;
+  screenshotRegion(region: ScreenshotRegion, options: ScreenshotOptions & {
+    format: 'bytes';
+  }): Promise<ScreenshotBytesResponse>;
+  screenshotRegion(region: ScreenshotRegion, options?: ScreenshotOptions): Promise<ScreenshotResponse | ScreenshotBytesResponse>;
+  click(x: number, y: number, options?: ClickOptions): Promise<void>;
+  doubleClick(x: number, y: number, options?: ClickOptions): Promise<void>;
+  tripleClick(x: number, y: number, options?: ClickOptions): Promise<void>;
+  rightClick(x: number, y: number): Promise<void>;
+  middleClick(x: number, y: number): Promise<void>;
+  mouseDown(x?: number, y?: number, options?: ClickOptions): Promise<void>;
+  mouseUp(x?: number, y?: number, options?: ClickOptions): Promise<void>;
+  moveMouse(x: number, y: number): Promise<void>;
+  drag(startX: number, startY: number, endX: number, endY: number, options?: ClickOptions): Promise<void>;
+  scroll(x: number, y: number, direction: ScrollDirection, amount?: number): Promise<void>;
+  getCursorPosition(): Promise<CursorPositionResponse>;
+  type(text: string, options?: TypeOptions): Promise<void>;
+  press(key: KeyInput): Promise<void>;
+  keyDown(key: KeyInput): Promise<void>;
+  keyUp(key: KeyInput): Promise<void>;
+  getScreenSize(): Promise<ScreenSizeResponse>;
+  getProcessStatus(name: string): Promise<BaseApiResponse & {
+    running: boolean;
+    pid?: number;
+    uptime?: number;
+  }>;
+}
+/**
+ * Client for desktop environment lifecycle, input, and screen operations
+ */
+declare class DesktopClient extends BaseHttpClient {
+  /**
+   * Start the desktop environment with optional resolution and DPI.
+   */
+  start(options?: DesktopStartOptions): Promise<DesktopStartResponse>;
+  /**
+   * Stop the desktop environment and all related processes.
+   */
+  stop(): Promise<DesktopStopResponse>;
+  /**
+   * Get desktop lifecycle and process health status.
+   */
+  status(): Promise<DesktopStatusResponse>;
+  /**
+   * Capture a full-screen screenshot as base64 (default).
+   */
+  screenshot(options?: ScreenshotOptions & {
+    format?: 'base64';
+  }): Promise<ScreenshotResponse>;
+  /**
+   * Capture a full-screen screenshot as bytes.
+   */
+  screenshot(options: ScreenshotOptions & {
+    format: 'bytes';
+  }): Promise<ScreenshotBytesResponse>;
+  /**
+   * Capture a region screenshot as base64 (default).
+   */
+  screenshotRegion(region: ScreenshotRegion, options?: ScreenshotOptions & {
+    format?: 'base64';
+  }): Promise<ScreenshotResponse>;
+  /**
+   * Capture a region screenshot as bytes.
+   */
+  screenshotRegion(region: ScreenshotRegion, options: ScreenshotOptions & {
+    format: 'bytes';
+  }): Promise<ScreenshotBytesResponse>;
+  /**
+   * Single-click at the given coordinates.
+   */
+  click(x: number, y: number, options?: ClickOptions): Promise<void>;
+  /**
+   * Double-click at the given coordinates.
+   */
+  doubleClick(x: number, y: number, options?: ClickOptions): Promise<void>;
+  /**
+   * Triple-click at the given coordinates.
+   */
+  tripleClick(x: number, y: number, options?: ClickOptions): Promise<void>;
+  /**
+   * Right-click at the given coordinates.
+   */
+  rightClick(x: number, y: number): Promise<void>;
+  /**
+   * Middle-click at the given coordinates.
+   */
+  middleClick(x: number, y: number): Promise<void>;
+  /**
+   * Press and hold a mouse button.
+   */
+  mouseDown(x?: number, y?: number, options?: ClickOptions): Promise<void>;
+  /**
+   * Release a held mouse button.
+   */
+  mouseUp(x?: number, y?: number, options?: ClickOptions): Promise<void>;
+  /**
+   * Move the mouse cursor to coordinates.
+   */
+  moveMouse(x: number, y: number): Promise<void>;
+  /**
+   * Drag from start coordinates to end coordinates.
+   */
+  drag(startX: number, startY: number, endX: number, endY: number, options?: ClickOptions): Promise<void>;
+  /**
+   * Scroll at coordinates in the specified direction.
+   */
+  scroll(x: number, y: number, direction: ScrollDirection, amount?: number): Promise<void>;
+  /**
+   * Get the current cursor coordinates.
+   */
+  getCursorPosition(): Promise<CursorPositionResponse>;
+  /**
+   * Type text into the focused element.
+   */
+  type(text: string, options?: TypeOptions): Promise<void>;
+  /**
+   * Press and release a key or key combination.
+   */
+  press(key: KeyInput): Promise<void>;
+  /**
+   * Press and hold a key.
+   */
+  keyDown(key: KeyInput): Promise<void>;
+  /**
+   * Release a held key.
+   */
+  keyUp(key: KeyInput): Promise<void>;
+  /**
+   * Get the active desktop screen size.
+   */
+  getScreenSize(): Promise<ScreenSizeResponse>;
+  /**
+   * Get health status for a specific desktop process.
+   */
+  getProcessStatus(name: string): Promise<BaseApiResponse & {
+    running: boolean;
+    pid?: number;
+    uptime?: number;
+  }>;
+}
+//#endregion
 //#region src/clients/file-client.d.ts
 /**
  * Request interface for creating directories
@@ -1796,6 +2082,33 @@ declare class UtilityClient extends BaseHttpClient {
   getVersion(): Promise<string>;
 }
 //#endregion
+//#region src/clients/watch-client.d.ts
+/**
+ * Client for file watch operations
+ * Uses inotify under the hood for native filesystem event notifications
+ *
+ * @internal This client is used internally by the SDK.
+ * Users should use `sandbox.watch()` instead.
+ */
+declare class WatchClient extends BaseHttpClient {
+  /**
+   * Start watching a directory for changes.
+   * The returned promise resolves only after the watcher is established
+   * on the filesystem (i.e. the `watching` SSE event has been received).
+   * The returned stream still contains the `watching` event so consumers
+   * using `parseSSEStream` will see the full event sequence.
+   *
+   * @param request - Watch request with path and options
+   */
+  watch(request: WatchRequest): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Read SSE chunks until the `watching` event appears, then return a
+   * wrapper stream that replays the buffered chunks followed by the
+   * remaining original stream data.
+   */
+  private waitForReadiness;
+}
+//#endregion
 //#region src/clients/sandbox-client.d.ts
 /**
  * Main sandbox client that composes all domain-specific clients
@@ -1816,6 +2129,8 @@ declare class SandboxClient {
   readonly git: GitClient;
   readonly interpreter: InterpreterClient;
   readonly utils: UtilityClient;
+  readonly desktop: DesktopClient;
+  readonly watch: WatchClient;
   private transport;
   constructor(options: HttpClientOptions);
   /**
@@ -1883,6 +2198,25 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * Can be set via options, env vars, or defaults
    */
   private containerTimeouts;
+  /**
+   * Desktop environment operations.
+   * Within the DO, this getter provides direct access to DesktopClient.
+   * Over RPC, the getSandbox() proxy intercepts this property and routes
+   * calls through callDesktop() instead.
+   */
+  get desktop(): Desktop;
+  /**
+   * Allowed desktop methods — derived from the Desktop interface.
+   * Restricts callDesktop() to a known set of operations.
+   */
+  private static readonly DESKTOP_METHODS;
+  /**
+   * Dispatch method for desktop operations.
+   * Called by the client-side proxy created in getSandbox() to provide
+   * the `sandbox.desktop.status()` API without relying on RPC pipelining
+   * through property getters.
+   */
+  callDesktop(method: string, args: unknown[]): Promise<unknown>;
   /**
    * Create a SandboxClient with current transport settings
    */
@@ -2100,6 +2434,37 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     includeHidden?: boolean;
   }): Promise<ListFilesResult>;
   exists(path: string, sessionId?: string): Promise<FileExistsResult>;
+  /**
+   * Get the noVNC preview URL for browser-based desktop viewing.
+   * Confirms desktop is active, then uses exposePort() to generate
+   * a token-authenticated preview URL for the noVNC port (6080).
+   *
+   * @param hostname - The custom domain hostname for preview URLs
+   *   (e.g., 'preview.example.com'). Required because preview URLs
+   *   use subdomain patterns that .workers.dev doesn't support.
+   * @param options - Optional settings
+   * @param options.token - Reuse an existing token instead of generating a new one
+   * @returns The authenticated noVNC preview URL
+   */
+  getDesktopStreamUrl(hostname: string, options?: {
+    token?: string;
+  }): Promise<{
+    url: string;
+  }>;
+  /**
+   * 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>>;
   /**
    * Expose a port and get a preview URL for accessing services running in the sandbox
    *
@@ -2283,5 +2648,5 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   private doRestoreBackup;
 }
 //#endregion
-export { Process as $, RequestConfig as A, ExecResult as B, CommandClient as C, Execution as Ct, ContainerStub as D, BaseApiResponse as E, BucketCredentials as F, GitCheckoutResult as G, FileChunk as H, BucketProvider as I, LogEvent as J, ISandbox as K, DirectoryBackup as L, SessionRequest as M, BackupOptions as N, ErrorResponse as O, BaseExecOptions as P, PortListResult as Q, ExecEvent as R, WriteFileRequest as S, CreateContextOptions as St, BackupClient as T, RunCodeOptions as Tt, FileMetadata as U, ExecutionSession as V, FileStreamEvent as W, PortCloseResult as X, MountBucketOptions as Y, PortExposeResult as Z, GitClient as _, ExecuteRequest as _t, CreateSessionRequest as a, ProcessOptions as at, MkdirRequest as b, PtyOptions as bt, DeleteSessionResponse as c, RestoreBackupResult as ct, ProcessClient as d, StreamOptions as dt, ProcessCleanupResult as et, PortClient as f, WaitForLogResult as ft, GitCheckoutRequest as g, isProcessStatus as gt, InterpreterClient as h, isProcess as ht, CommandsResponse as i, ProcessLogsResult as it, ResponseHandler as j, HttpClientOptions as k, PingResponse as l, SandboxOptions as lt, ExecutionCallbacks as m, isExecResult as mt, getSandbox as n, ProcessKillResult as nt, CreateSessionResponse as o, ProcessStartResult as ot, UnexposePortRequest as p, WaitForPortOptions as pt, ListFilesOptions as q, SandboxClient as r, ProcessListResult as rt, DeleteSessionRequest as s, ProcessStatus as st, Sandbox as t, ProcessInfoResult as tt, UtilityClient as u, SessionOptions as ut, FileClient as v, ExposePortRequest as vt, ExecuteResponse as w, ExecutionResult as wt, ReadFileRequest as x, CodeContext as xt, FileOperationRequest as y, StartProcessRequest as yt, ExecOptions as z };
-//# sourceMappingURL=sandbox-DGAjk7r3.d.ts.map
+export { DirectoryBackup as $, DesktopStopResponse as A, WaitForPortOptions as At, ExecuteResponse as B, CreateContextOptions as Bt, ClickOptions as C, ProcessStartResult as Ct, DesktopStartOptions as D, SessionOptions as Dt, DesktopClient as E, SandboxOptions as Et, ScreenshotRegion as F, ExecuteRequest as Ft, HttpClientOptions as G, BaseApiResponse as H, ExecutionResult as Ht, ScreenshotResponse as I, ExposePortRequest as It, SessionRequest as J, RequestConfig as K, ScrollDirection as L, StartProcessRequest as Lt, ScreenSizeResponse as M, isExecResult as Mt, ScreenshotBytesResponse as N, isProcess as Nt, DesktopStartResponse as O, StreamOptions as Ot, ScreenshotOptions as P, isProcessStatus as Pt, BucketProvider as Q, TypeOptions as R, PtyOptions as Rt, WriteFileRequest as S, ProcessOptions as St, Desktop as T, RestoreBackupResult as Tt, ContainerStub as U, RunCodeOptions as Ut, BackupClient as V, Execution as Vt, ErrorResponse as W, BaseExecOptions as X, BackupOptions as Y, BucketCredentials as Z, GitClient as _, ProcessCleanupResult as _t, CreateSessionRequest as a, FileMetadata as at, MkdirRequest as b, ProcessListResult as bt, DeleteSessionResponse as c, GitCheckoutResult as ct, ProcessClient as d, LogEvent as dt, ExecEvent as et, PortClient as f, MountBucketOptions as ft, GitCheckoutRequest as g, Process as gt, InterpreterClient as h, PortListResult as ht, CommandsResponse as i, FileChunk as it, KeyInput as j, WatchOptions as jt, DesktopStatusResponse as k, WaitForLogResult as kt, PingResponse as l, ISandbox as lt, ExecutionCallbacks as m, PortExposeResult as mt, getSandbox as n, ExecResult as nt, CreateSessionResponse as o, FileStreamEvent as ot, UnexposePortRequest as p, PortCloseResult as pt, ResponseHandler as q, SandboxClient as r, ExecutionSession as rt, DeleteSessionRequest as s, FileWatchSSEEvent as st, Sandbox as t, ExecOptions as tt, UtilityClient as u, ListFilesOptions as ut, FileClient as v, ProcessInfoResult as vt, CursorPositionResponse as w, ProcessStatus as wt, ReadFileRequest as x, ProcessLogsResult as xt, FileOperationRequest as y, ProcessKillResult as yt, CommandClient as z, CodeContext as zt };
+//# sourceMappingURL=sandbox-BYNjxjyr.d.ts.map