@cloudflare/sandbox 0.7.7 → 0.7.10

package/dist/index.js

@@ -1,5 +1,5 @@
-import { _ as getEnvString, a as isExecResult, c as shellEscape, d as TraceContext, f as Execution, g as filterEnvVars, h as extractRepoName, i as isWSStreamChunk, l as createLogger, m as GitLogger, n as isWSError, o as isProcess, p as ResultImpl, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createNoOpLogger, v as partitionEnvVars } from "./dist-D9B_6gn_.js";
-import { t as ErrorCode } from "./errors-CAZT-Gtg.js";
+import { _ as filterEnvVars, a as isExecResult, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as extractRepoName, h as GitLogger, i as isWSStreamChunk, l as shellEscape, m as ResultImpl, n as isWSError, o as isProcess, p as Execution, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createLogger, v as getEnvString, y as partitionEnvVars } from "./dist-CwUZf_TJ.js";
+import { t as ErrorCode } from "./errors-8W0q5Gll.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
 
@@ -593,6 +593,42 @@ var BackupRestoreError = class extends SandboxError {
 		return this.context.backupId;
 	}
 };
+var DesktopNotStartedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "DesktopNotStartedError";
+	}
+};
+var DesktopStartFailedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "DesktopStartFailedError";
+	}
+};
+var DesktopUnavailableError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "DesktopUnavailableError";
+	}
+};
+var DesktopProcessCrashedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "DesktopProcessCrashedError";
+	}
+};
+var DesktopInvalidOptionsError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "DesktopInvalidOptionsError";
+	}
+};
+var DesktopInvalidCoordinatesError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "DesktopInvalidCoordinatesError";
+	}
+};
 
 //#endregion
 //#region src/errors/adapter.ts
@@ -648,6 +684,12 @@ function createErrorFromResponse(errorResponse) {
 		case ErrorCode.INTERPRETER_NOT_READY: return new InterpreterNotReadyError(errorResponse);
 		case ErrorCode.CONTEXT_NOT_FOUND: return new ContextNotFoundError(errorResponse);
 		case ErrorCode.CODE_EXECUTION_ERROR: return new CodeExecutionError(errorResponse);
+		case ErrorCode.DESKTOP_NOT_STARTED: return new DesktopNotStartedError(errorResponse);
+		case ErrorCode.DESKTOP_START_FAILED: return new DesktopStartFailedError(errorResponse);
+		case ErrorCode.DESKTOP_UNAVAILABLE: return new DesktopUnavailableError(errorResponse);
+		case ErrorCode.DESKTOP_PROCESS_CRASHED: return new DesktopProcessCrashedError(errorResponse);
+		case ErrorCode.DESKTOP_INVALID_OPTIONS: return new DesktopInvalidOptionsError(errorResponse);
+		case ErrorCode.DESKTOP_INVALID_COORDINATES: return new DesktopInvalidCoordinatesError(errorResponse);
 		case ErrorCode.VALIDATION_FAILED: return new ValidationFailedError(errorResponse);
 		case ErrorCode.INVALID_JSON_RESPONSE:
 		case ErrorCode.UNKNOWN_ERROR:
@@ -990,6 +1032,10 @@ var WebSocketTransport = class extends BaseTransport {
 	*
 	* The stream will receive data chunks as they arrive over the WebSocket.
 	* Format matches SSE for compatibility with existing streaming code.
+	*
+	* This method waits for the first message before returning. If the server
+	* responds with an error (non-streaming response), it throws immediately
+	* rather than returning a stream that will error later.
 	*/
 	async requestStream(method, path, body) {
 		await this.connect();
@@ -1001,41 +1047,75 @@ var WebSocketTransport = class extends BaseTransport {
 			path,
 			body
 		};
-		return new ReadableStream({
-			start: (controller) => {
-				const timeoutMs = this.config.requestTimeoutMs ?? 12e4;
-				const timeoutId = setTimeout(() => {
+		return new Promise((resolveStream, rejectStream) => {
+			let streamController;
+			let firstMessageReceived = false;
+			const timeoutMs = this.config.requestTimeoutMs ?? 12e4;
+			const timeoutId = setTimeout(() => {
+				this.pendingRequests.delete(id);
+				const error = /* @__PURE__ */ new Error(`Stream timeout after ${timeoutMs}ms: ${method} ${path}`);
+				if (firstMessageReceived) streamController?.error(error);
+				else rejectStream(error);
+			}, timeoutMs);
+			const stream = new ReadableStream({
+				start: (controller) => {
+					streamController = controller;
+				},
+				cancel: () => {
+					const pending = this.pendingRequests.get(id);
+					if (pending?.timeoutId) clearTimeout(pending.timeoutId);
+					try {
+						this.send({
+							type: "cancel",
+							id
+						});
+					} catch (error) {
+						this.logger.debug("Failed to send stream cancel message", {
+							id,
+							error: error instanceof Error ? error.message : String(error)
+						});
+					}
 					this.pendingRequests.delete(id);
-					controller.error(/* @__PURE__ */ new Error(`Stream timeout after ${timeoutMs}ms: ${method} ${path}`));
-				}, timeoutMs);
-				this.pendingRequests.set(id, {
-					resolve: (response) => {
-						clearTimeout(timeoutId);
-						this.pendingRequests.delete(id);
-						if (response.status >= 400) controller.error(/* @__PURE__ */ new Error(`Stream error: ${response.status} - ${JSON.stringify(response.body)}`));
-						else controller.close();
-					},
-					reject: (error) => {
-						clearTimeout(timeoutId);
-						this.pendingRequests.delete(id);
-						controller.error(error);
-					},
-					streamController: controller,
-					isStreaming: true,
-					timeoutId
-				});
-				try {
-					this.send(request);
-				} catch (error) {
+				}
+			});
+			this.pendingRequests.set(id, {
+				resolve: (response) => {
+					clearTimeout(timeoutId);
+					this.pendingRequests.delete(id);
+					if (!firstMessageReceived) {
+						firstMessageReceived = true;
+						if (response.status >= 400) rejectStream(/* @__PURE__ */ new Error(`Stream error: ${response.status} - ${JSON.stringify(response.body)}`));
+						else {
+							streamController?.close();
+							resolveStream(stream);
+						}
+					} else if (response.status >= 400) streamController?.error(/* @__PURE__ */ new Error(`Stream error: ${response.status} - ${JSON.stringify(response.body)}`));
+					else streamController?.close();
+				},
+				reject: (error) => {
 					clearTimeout(timeoutId);
 					this.pendingRequests.delete(id);
-					controller.error(error instanceof Error ? error : new Error(String(error)));
+					if (firstMessageReceived) streamController?.error(error);
+					else rejectStream(error);
+				},
+				streamController: void 0,
+				isStreaming: true,
+				timeoutId,
+				onFirstChunk: () => {
+					if (!firstMessageReceived) {
+						firstMessageReceived = true;
+						const pending = this.pendingRequests.get(id);
+						if (pending) pending.streamController = streamController;
+						resolveStream(stream);
+					}
 				}
-			},
-			cancel: () => {
-				const pending = this.pendingRequests.get(id);
-				if (pending?.timeoutId) clearTimeout(pending.timeoutId);
+			});
+			try {
+				this.send(request);
+			} catch (error) {
+				clearTimeout(timeoutId);
 				this.pendingRequests.delete(id);
+				rejectStream(error instanceof Error ? error : new Error(String(error)));
 			}
 		});
 	}
@@ -1047,8 +1127,9 @@ var WebSocketTransport = class extends BaseTransport {
 		this.ws.send(JSON.stringify(message));
 		this.logger.debug("WebSocket sent", {
 			id: message.id,
-			method: message.method,
-			path: message.path
+			type: message.type,
+			method: message.type === "request" ? message.method : void 0,
+			path: message.type === "request" ? message.path : void 0
 		});
 	}
 	/**
@@ -1086,10 +1167,18 @@ var WebSocketTransport = class extends BaseTransport {
 	*/
 	handleStreamChunk(chunk) {
 		const pending = this.pendingRequests.get(chunk.id);
-		if (!pending || !pending.streamController) {
+		if (!pending) {
 			this.logger.warn("Received stream chunk for unknown request", { id: chunk.id });
 			return;
 		}
+		if (pending.onFirstChunk) {
+			pending.onFirstChunk();
+			pending.onFirstChunk = void 0;
+		}
+		if (!pending.streamController) {
+			this.logger.warn("Stream chunk received but controller not ready", { id: chunk.id });
+			return;
+		}
 		const encoder = new TextEncoder();
 		let sseData;
 		if (chunk.event) sseData = `event: ${chunk.event}\ndata: ${chunk.data}\n\n`;
@@ -1455,6 +1544,369 @@ var CommandClient = class extends BaseHttpClient {
 	}
 };
 
+//#endregion
+//#region src/clients/desktop-client.ts
+/**
+* Client for desktop environment lifecycle, input, and screen operations
+*/
+var DesktopClient = class extends BaseHttpClient {
+	/**
+	* Start the desktop environment with optional resolution and DPI.
+	*/
+	async start(options) {
+		try {
+			const data = {
+				...options?.resolution !== void 0 && { resolution: options.resolution },
+				...options?.dpi !== void 0 && { dpi: options.dpi }
+			};
+			const response = await this.post("/api/desktop/start", data);
+			this.logSuccess("Desktop started", `${response.resolution[0]}x${response.resolution[1]}`);
+			return response;
+		} catch (error) {
+			this.logError("desktop.start", error);
+			this.options.onError?.(error instanceof Error ? error.message : String(error));
+			throw error;
+		}
+	}
+	/**
+	* Stop the desktop environment and all related processes.
+	*/
+	async stop() {
+		try {
+			const response = await this.post("/api/desktop/stop", {});
+			this.logSuccess("Desktop stopped");
+			return response;
+		} catch (error) {
+			this.logError("desktop.stop", error);
+			this.options.onError?.(error instanceof Error ? error.message : String(error));
+			throw error;
+		}
+	}
+	/**
+	* Get desktop lifecycle and process health status.
+	*/
+	async status() {
+		try {
+			const response = await this.get("/api/desktop/status");
+			this.logSuccess("Desktop status retrieved", response.status);
+			return response;
+		} catch (error) {
+			this.logError("desktop.status", error);
+			throw error;
+		}
+	}
+	async screenshot(options) {
+		try {
+			const wantsBytes = options?.format === "bytes";
+			const data = {
+				format: "base64",
+				...options?.imageFormat !== void 0 && { imageFormat: options.imageFormat },
+				...options?.quality !== void 0 && { quality: options.quality },
+				...options?.showCursor !== void 0 && { showCursor: options.showCursor }
+			};
+			const response = await this.post("/api/desktop/screenshot", data);
+			this.logSuccess("Screenshot captured", `${response.width}x${response.height}`);
+			if (wantsBytes) {
+				const binaryString = atob(response.data);
+				const bytes = new Uint8Array(binaryString.length);
+				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+				return {
+					...response,
+					data: bytes
+				};
+			}
+			return response;
+		} catch (error) {
+			this.logError("desktop.screenshot", error);
+			throw error;
+		}
+	}
+	async screenshotRegion(region, options) {
+		try {
+			const wantsBytes = options?.format === "bytes";
+			const data = {
+				region,
+				format: "base64",
+				...options?.imageFormat !== void 0 && { imageFormat: options.imageFormat },
+				...options?.quality !== void 0 && { quality: options.quality },
+				...options?.showCursor !== void 0 && { showCursor: options.showCursor }
+			};
+			const response = await this.post("/api/desktop/screenshot/region", data);
+			this.logSuccess("Region screenshot captured", `${region.width}x${region.height}`);
+			if (wantsBytes) {
+				const binaryString = atob(response.data);
+				const bytes = new Uint8Array(binaryString.length);
+				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+				return {
+					...response,
+					data: bytes
+				};
+			}
+			return response;
+		} catch (error) {
+			this.logError("desktop.screenshotRegion", error);
+			throw error;
+		}
+	}
+	/**
+	* Single-click at the given coordinates.
+	*/
+	async click(x, y, options) {
+		try {
+			await this.post("/api/desktop/mouse/click", {
+				x,
+				y,
+				button: options?.button ?? "left",
+				clickCount: 1
+			});
+			this.logSuccess("Mouse click", `(${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.click", error);
+			throw error;
+		}
+	}
+	/**
+	* Double-click at the given coordinates.
+	*/
+	async doubleClick(x, y, options) {
+		try {
+			await this.post("/api/desktop/mouse/click", {
+				x,
+				y,
+				button: options?.button ?? "left",
+				clickCount: 2
+			});
+			this.logSuccess("Mouse double click", `(${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.doubleClick", error);
+			throw error;
+		}
+	}
+	/**
+	* Triple-click at the given coordinates.
+	*/
+	async tripleClick(x, y, options) {
+		try {
+			await this.post("/api/desktop/mouse/click", {
+				x,
+				y,
+				button: options?.button ?? "left",
+				clickCount: 3
+			});
+			this.logSuccess("Mouse triple click", `(${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.tripleClick", error);
+			throw error;
+		}
+	}
+	/**
+	* Right-click at the given coordinates.
+	*/
+	async rightClick(x, y) {
+		try {
+			await this.post("/api/desktop/mouse/click", {
+				x,
+				y,
+				button: "right",
+				clickCount: 1
+			});
+			this.logSuccess("Mouse right click", `(${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.rightClick", error);
+			throw error;
+		}
+	}
+	/**
+	* Middle-click at the given coordinates.
+	*/
+	async middleClick(x, y) {
+		try {
+			await this.post("/api/desktop/mouse/click", {
+				x,
+				y,
+				button: "middle",
+				clickCount: 1
+			});
+			this.logSuccess("Mouse middle click", `(${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.middleClick", error);
+			throw error;
+		}
+	}
+	/**
+	* Press and hold a mouse button.
+	*/
+	async mouseDown(x, y, options) {
+		try {
+			await this.post("/api/desktop/mouse/down", {
+				...x !== void 0 && { x },
+				...y !== void 0 && { y },
+				button: options?.button ?? "left"
+			});
+			this.logSuccess("Mouse down", x !== void 0 ? `(${x}, ${y})` : "current position");
+		} catch (error) {
+			this.logError("desktop.mouseDown", error);
+			throw error;
+		}
+	}
+	/**
+	* Release a held mouse button.
+	*/
+	async mouseUp(x, y, options) {
+		try {
+			await this.post("/api/desktop/mouse/up", {
+				...x !== void 0 && { x },
+				...y !== void 0 && { y },
+				button: options?.button ?? "left"
+			});
+			this.logSuccess("Mouse up", x !== void 0 ? `(${x}, ${y})` : "current position");
+		} catch (error) {
+			this.logError("desktop.mouseUp", error);
+			throw error;
+		}
+	}
+	/**
+	* Move the mouse cursor to coordinates.
+	*/
+	async moveMouse(x, y) {
+		try {
+			await this.post("/api/desktop/mouse/move", {
+				x,
+				y
+			});
+			this.logSuccess("Mouse move", `(${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.moveMouse", error);
+			throw error;
+		}
+	}
+	/**
+	* Drag from start coordinates to end coordinates.
+	*/
+	async drag(startX, startY, endX, endY, options) {
+		try {
+			await this.post("/api/desktop/mouse/drag", {
+				startX,
+				startY,
+				endX,
+				endY,
+				button: options?.button ?? "left"
+			});
+			this.logSuccess("Mouse drag", `(${startX},${startY}) -> (${endX},${endY})`);
+		} catch (error) {
+			this.logError("desktop.drag", error);
+			throw error;
+		}
+	}
+	/**
+	* Scroll at coordinates in the specified direction.
+	*/
+	async scroll(x, y, direction, amount = 3) {
+		try {
+			await this.post("/api/desktop/mouse/scroll", {
+				x,
+				y,
+				direction,
+				amount
+			});
+			this.logSuccess("Mouse scroll", `${direction} ${amount} at (${x}, ${y})`);
+		} catch (error) {
+			this.logError("desktop.scroll", error);
+			throw error;
+		}
+	}
+	/**
+	* Get the current cursor coordinates.
+	*/
+	async getCursorPosition() {
+		try {
+			const response = await this.get("/api/desktop/mouse/position");
+			this.logSuccess("Cursor position retrieved", `(${response.x}, ${response.y})`);
+			return response;
+		} catch (error) {
+			this.logError("desktop.getCursorPosition", error);
+			throw error;
+		}
+	}
+	/**
+	* Type text into the focused element.
+	*/
+	async type(text, options) {
+		try {
+			await this.post("/api/desktop/keyboard/type", {
+				text,
+				...options?.delayMs !== void 0 && { delayMs: options.delayMs }
+			});
+			this.logSuccess("Keyboard type", `${text.length} chars`);
+		} catch (error) {
+			this.logError("desktop.type", error);
+			throw error;
+		}
+	}
+	/**
+	* Press and release a key or key combination.
+	*/
+	async press(key) {
+		try {
+			await this.post("/api/desktop/keyboard/press", { key });
+			this.logSuccess("Key press", key);
+		} catch (error) {
+			this.logError("desktop.press", error);
+			throw error;
+		}
+	}
+	/**
+	* Press and hold a key.
+	*/
+	async keyDown(key) {
+		try {
+			await this.post("/api/desktop/keyboard/down", { key });
+			this.logSuccess("Key down", key);
+		} catch (error) {
+			this.logError("desktop.keyDown", error);
+			throw error;
+		}
+	}
+	/**
+	* Release a held key.
+	*/
+	async keyUp(key) {
+		try {
+			await this.post("/api/desktop/keyboard/up", { key });
+			this.logSuccess("Key up", key);
+		} catch (error) {
+			this.logError("desktop.keyUp", error);
+			throw error;
+		}
+	}
+	/**
+	* Get the active desktop screen size.
+	*/
+	async getScreenSize() {
+		try {
+			const response = await this.get("/api/desktop/screen/size");
+			this.logSuccess("Screen size retrieved", `${response.width}x${response.height}`);
+			return response;
+		} catch (error) {
+			this.logError("desktop.getScreenSize", error);
+			throw error;
+		}
+	}
+	/**
+	* Get health status for a specific desktop process.
+	*/
+	async getProcessStatus(name) {
+		try {
+			const response = await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
+			this.logSuccess("Desktop process status retrieved", name);
+			return response;
+		} catch (error) {
+			this.logError("desktop.getProcessStatus", error);
+			throw error;
+		}
+	}
+};
+
 //#endregion
 //#region src/clients/file-client.ts
 /**
@@ -2139,6 +2591,106 @@ var UtilityClient = class extends BaseHttpClient {
 	}
 };
 
+//#endregion
+//#region src/clients/watch-client.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.
+*/
+var WatchClient = class 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
+	*/
+	async watch(request) {
+		try {
+			const stream = await this.doStreamFetch("/api/watch", request);
+			const readyStream = await this.waitForReadiness(stream);
+			this.logSuccess("File watch started", request.path);
+			return readyStream;
+		} catch (error) {
+			this.logError("watch", error);
+			throw error;
+		}
+	}
+	/**
+	* 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.
+	*/
+	async waitForReadiness(stream) {
+		const reader = stream.getReader();
+		const bufferedChunks = [];
+		const decoder = new TextDecoder();
+		let buffer = "";
+		let currentEvent = { data: [] };
+		let watcherReady = false;
+		const processEventData = (eventData) => {
+			let event;
+			try {
+				event = JSON.parse(eventData);
+			} catch {
+				return;
+			}
+			if (event.type === "watching") watcherReady = true;
+			if (event.type === "error") throw new Error(event.error || "Watch failed to establish");
+		};
+		try {
+			while (!watcherReady) {
+				const { done, value } = await reader.read();
+				if (done) {
+					const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
+					for (const frame of finalParsed.events) {
+						processEventData(frame.data);
+						if (watcherReady) break;
+					}
+					if (watcherReady) break;
+					throw new Error("Watch stream ended before watcher was established");
+				}
+				bufferedChunks.push(value);
+				buffer += decoder.decode(value, { stream: true });
+				const parsed = parseSSEFrames(buffer, currentEvent);
+				buffer = parsed.remaining;
+				currentEvent = parsed.currentEvent;
+				for (const frame of parsed.events) {
+					processEventData(frame.data);
+					if (watcherReady) break;
+				}
+			}
+		} catch (error) {
+			reader.cancel().catch(() => {});
+			throw error;
+		}
+		let replayIndex = 0;
+		return new ReadableStream({
+			pull(controller) {
+				if (replayIndex < bufferedChunks.length) {
+					controller.enqueue(bufferedChunks[replayIndex++]);
+					return;
+				}
+				return reader.read().then(({ done: d, value: v }) => {
+					if (d) {
+						controller.close();
+						return;
+					}
+					controller.enqueue(v);
+				});
+			},
+			cancel() {
+				return reader.cancel();
+			}
+		});
+	}
+};
+
 //#endregion
 //#region src/clients/sandbox-client.ts
 /**
@@ -2160,6 +2712,8 @@ var SandboxClient = class {
 	git;
 	interpreter;
 	utils;
+	desktop;
+	watch;
 	transport = null;
 	constructor(options) {
 		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
@@ -2183,6 +2737,8 @@ var SandboxClient = class {
 		this.git = new GitClient(clientOptions);
 		this.interpreter = new InterpreterClient(clientOptions);
 		this.utils = new UtilityClient(clientOptions);
+		this.desktop = new DesktopClient(clientOptions);
+		this.watch = new WatchClient(clientOptions);
 	}
 	/**
 	* Get the current transport mode
@@ -2490,32 +3046,44 @@ async function* parseSSEStream(stream, signal) {
 	const reader = stream.getReader();
 	const decoder = new TextDecoder();
 	let buffer = "";
+	let currentEvent = { data: [] };
+	let isAborted = signal?.aborted ?? false;
+	const emitEvent = (data) => {
+		if (data === "[DONE]" || data.trim() === "") return;
+		try {
+			return JSON.parse(data);
+		} catch {
+			return;
+		}
+	};
+	const onAbort = () => {
+		isAborted = true;
+		reader.cancel().catch(() => {});
+	};
+	if (signal && !signal.aborted) signal.addEventListener("abort", onAbort);
 	try {
 		while (true) {
-			if (signal?.aborted) throw new Error("Operation was aborted");
+			if (isAborted) throw new Error("Operation was aborted");
 			const { done, value } = await reader.read();
+			if (isAborted) throw new Error("Operation was aborted");
 			if (done) break;
 			buffer += decoder.decode(value, { stream: true });
-			const lines = buffer.split("\n");
-			buffer = lines.pop() || "";
-			for (const line of lines) {
-				if (line.trim() === "") continue;
-				if (line.startsWith("data: ")) {
-					const data = line.substring(6);
-					if (data === "[DONE]" || data.trim() === "") continue;
-					try {
-						yield JSON.parse(data);
-					} catch {}
-				}
+			const parsed = parseSSEFrames(buffer, currentEvent);
+			buffer = parsed.remaining;
+			currentEvent = parsed.currentEvent;
+			for (const frame of parsed.events) {
+				const event = emitEvent(frame.data);
+				if (event !== void 0) yield event;
 			}
 		}
-		if (buffer.trim() && buffer.startsWith("data: ")) {
-			const data = buffer.substring(6);
-			if (data !== "[DONE]" && data.trim()) try {
-				yield JSON.parse(data);
-			} catch {}
+		if (isAborted) throw new Error("Operation was aborted");
+		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
+		for (const frame of finalParsed.events) {
+			const event = emitEvent(frame.data);
+			if (event !== void 0) yield event;
 		}
 	} finally {
+		if (signal) signal.removeEventListener("abort", onAbort);
 		try {
 			await reader.cancel();
 		} catch {}
@@ -2712,7 +3280,7 @@ function buildS3fsSource(bucket, prefix) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.7.7";
+const SDK_VERSION = "0.7.10";
 
 //#endregion
 //#region src/sandbox.ts
@@ -2737,7 +3305,11 @@ function getSandbox(ns, id, options) {
 			return enhanceSession(stub, await stub.getSession(sessionId));
 		},
 		terminal: (request, opts) => proxyTerminal(stub, defaultSessionId, request, opts),
-		wsConnect: connect(stub)
+		wsConnect: connect(stub),
+		desktop: new Proxy({}, { get(_, method) {
+			if (typeof method !== "string" || method === "then") return void 0;
+			return (...args) => stub.callDesktop(method, args);
+		} })
 	};
 	return new Proxy(stub, { get(target, prop) {
 		if (typeof prop === "string" && prop in enhancedMethods) return enhancedMethods[prop];
@@ -2811,6 +3383,56 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	containerTimeouts = { ...this.DEFAULT_CONTAINER_TIMEOUTS };
 	/**
+	* 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() {
+		return this.client.desktop;
+	}
+	/**
+	* Allowed desktop methods — derived from the Desktop interface.
+	* Restricts callDesktop() to a known set of operations.
+	*/
+	static DESKTOP_METHODS = new Set([
+		"start",
+		"stop",
+		"status",
+		"screenshot",
+		"screenshotRegion",
+		"click",
+		"doubleClick",
+		"tripleClick",
+		"rightClick",
+		"middleClick",
+		"mouseDown",
+		"mouseUp",
+		"moveMouse",
+		"drag",
+		"scroll",
+		"getCursorPosition",
+		"type",
+		"press",
+		"keyDown",
+		"keyUp",
+		"getScreenSize",
+		"getProcessStatus"
+	]);
+	/**
+	* 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.
+	*/
+	async callDesktop(method, args) {
+		if (!Sandbox.DESKTOP_METHODS.has(method)) throw new Error(`Unknown desktop method: ${method}`);
+		const client = this.client.desktop;
+		const fn = client[method];
+		if (typeof fn !== "function") throw new Error(`Unknown desktop method: ${method}`);
+		return fn.apply(client, args);
+	}
+	/**
 	* Create a SandboxClient with current transport settings
 	*/
 	createSandboxClient() {
@@ -3080,6 +3702,9 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async destroy() {
 		this.logger.info("Destroying sandbox container");
+		if (this.ctx.container?.running) try {
+			await this.client.desktop.stop();
+		} catch {}
 		this.client.disconnect();
 		for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
 			if (mountInfo.mounted) try {
@@ -3138,34 +3763,43 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async containerFetch(requestOrUrl, portOrInit, portParam) {
 		const { request, port } = this.parseContainerFetchArgs(requestOrUrl, portOrInit, portParam);
-		if ((await this.getState()).status !== "healthy") try {
-			this.logger.debug("Starting container with configured timeouts", {
-				instanceTimeout: this.containerTimeouts.instanceGetTimeoutMS,
-				portTimeout: this.containerTimeouts.portReadyTimeoutMS
-			});
-			await this.startAndWaitForPorts({
-				ports: port,
-				cancellationOptions: {
-					instanceGetTimeoutMS: this.containerTimeouts.instanceGetTimeoutMS,
-					portReadyTimeoutMS: this.containerTimeouts.portReadyTimeoutMS,
-					waitInterval: this.containerTimeouts.waitIntervalMS,
-					abort: request.signal
-				}
-			});
-		} catch (e) {
-			if (this.isNoInstanceError(e)) return new Response("Container is currently provisioning. This can take several minutes on first deployment. Please retry in a moment.", {
-				status: 503,
-				headers: { "Retry-After": "10" }
-			});
-			if (this.isTransientStartupError(e)) {
-				this.logger.debug("Transient container startup error, returning 503", { error: e instanceof Error ? e.message : String(e) });
-				return new Response("Container is starting. Please retry in a moment.", {
+		const state = await this.getState();
+		const containerRunning = this.ctx.container?.running;
+		const staleStateDetected = state.status === "healthy" && containerRunning === false;
+		if (state.status !== "healthy" || containerRunning === false) {
+			if (staleStateDetected) this.logger.debug("Stale container state detected: persisted state is healthy but container is not running");
+			try {
+				this.logger.debug("Starting container with configured timeouts", {
+					instanceTimeout: this.containerTimeouts.instanceGetTimeoutMS,
+					portTimeout: this.containerTimeouts.portReadyTimeoutMS
+				});
+				await this.startAndWaitForPorts({
+					ports: port,
+					cancellationOptions: {
+						instanceGetTimeoutMS: this.containerTimeouts.instanceGetTimeoutMS,
+						portReadyTimeoutMS: this.containerTimeouts.portReadyTimeoutMS,
+						waitInterval: this.containerTimeouts.waitIntervalMS,
+						abort: request.signal
+					}
+				});
+			} catch (e) {
+				if (this.isNoInstanceError(e)) return new Response("Container is currently provisioning. This can take several minutes on first deployment. Please retry in a moment.", {
 					status: 503,
-					headers: { "Retry-After": "3" }
+					headers: { "Retry-After": "10" }
 				});
+				if (this.isTransientStartupError(e)) {
+					if (staleStateDetected) {
+						this.logger.warn("Container startup failed after stale state detection, aborting DO for recovery", { error: e instanceof Error ? e.message : String(e) });
+						this.ctx.abort();
+					} else this.logger.debug("Transient container startup error, returning 503", { error: e instanceof Error ? e.message : String(e) });
+					return new Response("Container is starting. Please retry in a moment.", {
+						status: 503,
+						headers: { "Retry-After": "3" }
+					});
+				}
+				this.logger.error("Container startup failed with permanent error", e instanceof Error ? e : new Error(String(e)));
+				return new Response(`Failed to start container: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
 			}
-			this.logger.error("Container startup failed with permanent error", e instanceof Error ? e : new Error(String(e)));
-			return new Response(`Failed to start container: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
 		}
 		return await super.containerFetch(requestOrUrl, portOrInit, portParam);
 	}
@@ -3202,6 +3836,8 @@ var Sandbox = class Sandbox extends Container {
 			"network connection lost",
 			"container suddenly disconnected",
 			"monitor failed to find container",
+			"container exited with unexpected exit code",
+			"container exited before we could determine",
 			"timed out",
 			"timeout",
 			"the operation was aborted"
@@ -3828,6 +4464,63 @@ var Sandbox = class Sandbox extends Container {
 		return this.client.files.exists(path, session);
 	}
 	/**
+	* 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
+	*/
+	async getDesktopStreamUrl(hostname, options) {
+		if ((await this.client.desktop.status()).status === "inactive") throw new Error("Desktop is not running. Call sandbox.desktop.start() first.");
+		let url;
+		try {
+			url = (await this.exposePort(6080, {
+				hostname,
+				token: options?.token
+			})).url;
+		} catch {
+			const existingToken = (await this.ctx.storage.get("portTokens") || {})["6080"];
+			if (existingToken && this.sandboxName) url = this.constructPreviewUrl(6080, this.sandboxName, hostname, existingToken);
+			else throw new Error("Failed to get desktop stream URL: port 6080 could not be exposed and no existing token found.");
+		}
+		try {
+			await this.waitForPort({
+				portToCheck: 6080,
+				retries: 30,
+				waitInterval: 500
+			});
+		} catch {}
+		return { url };
+	}
+	/**
+	* 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
+	*/
+	async watch(path, options = {}) {
+		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.watch.watch({
+			path,
+			recursive: options.recursive,
+			include: options.include,
+			exclude: options.exclude,
+			sessionId
+		});
+	}
+	/**
 	* Expose a port and get a preview URL for accessing services running in the sandbox
 	*
 	* @param port - Port number to expose (1024-65535)
@@ -4037,6 +4730,10 @@ var Sandbox = class Sandbox extends Container {
 				sessionId
 			}),
 			readFileStream: (path) => this.readFileStream(path, { sessionId }),
+			watch: (path, options) => this.watch(path, {
+				...options,
+				sessionId
+			}),
 			mkdir: (path, options) => this.mkdir(path, {
 				...options,
 				sessionId
@@ -4575,20 +5272,23 @@ async function* parseSSE(stream) {
 	const reader = stream.getReader();
 	const decoder = new TextDecoder();
 	let buffer = "";
+	let currentEvent = { data: [] };
 	try {
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) break;
 			buffer += decoder.decode(value, { stream: true });
-			const lines = buffer.split("\n");
-			buffer = lines.pop() || "";
-			for (const line of lines) if (line.startsWith("data: ")) {
-				const data = line.slice(6);
-				try {
-					yield JSON.parse(data);
-				} catch {}
-			}
+			const parsed = parseSSEFrames(buffer, currentEvent);
+			buffer = parsed.remaining;
+			currentEvent = parsed.currentEvent;
+			for (const frame of parsed.events) try {
+				yield JSON.parse(frame.data);
+			} catch {}
 		}
+		const finalParsed = parseSSEFrames(`${buffer}\n\n`, currentEvent);
+		for (const frame of finalParsed.events) try {
+			yield JSON.parse(frame.data);
+		} catch {}
 	} finally {
 		try {
 			await reader.cancel();
@@ -4686,5 +5386,5 @@ async function collectFile(stream) {
 }
 
 //#endregion
-export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, BackupRestoreError, BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidBackupConfigError, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, BackupRestoreError, BucketMountError, CodeInterpreter, CommandClient, DesktopClient, DesktopInvalidCoordinatesError, DesktopInvalidOptionsError, DesktopNotStartedError, DesktopProcessCrashedError, DesktopStartFailedError, DesktopUnavailableError, FileClient, GitClient, InvalidBackupConfigError, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.js.map