@cloudflare/sandbox 0.6.5 → 0.6.7

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as shellEscape, c as TraceContext, d as GitLogger, f as getEnvString, i as isTerminalStatus, l as Execution, n as isProcess, o as createLogger, r as isProcessStatus, s as createNoOpLogger, t as isExecResult, u as ResultImpl } from "./dist-2SF6oOaz.js";
+import { a as isExecResult, c as shellEscape, d as TraceContext, f as Execution, h as getEnvString, 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 } from "./dist-Dgwt0coR.js";
 import { t as ErrorCode } from "./errors-BCXUmJUn.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 
@@ -569,31 +569,37 @@ function createErrorFromResponse(errorResponse) {
 }
 
 //#endregion
-//#region src/clients/base-client.ts
+//#region src/clients/transport/base-transport.ts
+/**
+* Container startup retry configuration
+*/
 const TIMEOUT_MS = 12e4;
 const MIN_TIME_FOR_RETRY_MS = 15e3;
 /**
-* Abstract base class providing common HTTP functionality for all domain clients
+* Abstract base transport with shared retry logic
+*
+* Handles 503 retry for container startup - shared by all transports.
+* Subclasses implement the transport-specific fetch and stream logic.
 */
-var BaseHttpClient = class {
-	baseUrl;
-	options;
+var BaseTransport = class {
+	config;
 	logger;
-	constructor(options = {}) {
-		this.options = options;
-		this.logger = options.logger ?? createNoOpLogger();
-		this.baseUrl = this.options.baseUrl;
+	constructor(config) {
+		this.config = config;
+		this.logger = config.logger ?? createNoOpLogger();
 	}
 	/**
-	* Core HTTP request method with automatic retry for container startup delays
-	* Retries both 503 (provisioning) and 500 (startup failure) errors when they're container-related
+	* Fetch with automatic retry for 503 (container starting)
+	*
+	* This is the primary entry point for making requests. It wraps the
+	* transport-specific doFetch() with retry logic for container startup.
 	*/
-	async doFetch(path, options) {
+	async fetch(path, options) {
 		const startTime = Date.now();
 		let attempt = 0;
 		while (true) {
-			const response = await this.executeFetch(path, options);
-			if (await this.isRetryableContainerError(response)) {
+			const response = await this.doFetch(path, options);
+			if (response.status === 503) {
 				const elapsed = Date.now() - startTime;
 				const remaining = TIMEOUT_MS - elapsed;
 				if (remaining > MIN_TIME_FOR_RETRY_MS) {
@@ -602,19 +608,537 @@ var BaseHttpClient = class {
 						status: response.status,
 						attempt: attempt + 1,
 						delayMs: delay,
-						remainingSec: Math.floor(remaining / 1e3)
+						remainingSec: Math.floor(remaining / 1e3),
+						mode: this.getMode()
 					});
-					await new Promise((resolve) => setTimeout(resolve, delay));
+					await this.sleep(delay);
 					attempt++;
 					continue;
 				}
 				this.logger.error("Container failed to become ready", /* @__PURE__ */ new Error(`Failed after ${attempt + 1} attempts over ${Math.floor(elapsed / 1e3)}s`));
-				return response;
 			}
 			return response;
 		}
 	}
 	/**
+	* Sleep utility for retry delays
+	*/
+	sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+
+//#endregion
+//#region src/clients/transport/http-transport.ts
+/**
+* HTTP transport implementation
+*
+* Uses standard fetch API for communication with the container.
+* HTTP is stateless, so connect/disconnect are no-ops.
+*/
+var HttpTransport = class extends BaseTransport {
+	baseUrl;
+	constructor(config) {
+		super(config);
+		this.baseUrl = config.baseUrl ?? "http://localhost:3000";
+	}
+	getMode() {
+		return "http";
+	}
+	async connect() {}
+	disconnect() {}
+	isConnected() {
+		return true;
+	}
+	async doFetch(path, options) {
+		const url = this.buildUrl(path);
+		if (this.config.stub) return this.config.stub.containerFetch(url, options || {}, this.config.port);
+		return globalThis.fetch(url, options);
+	}
+	async fetchStream(path, body, method = "POST") {
+		const url = this.buildUrl(path);
+		const options = this.buildStreamOptions(body, method);
+		let response;
+		if (this.config.stub) response = await this.config.stub.containerFetch(url, options, this.config.port);
+		else response = await globalThis.fetch(url, options);
+		if (!response.ok) {
+			const errorBody = await response.text();
+			throw new Error(`HTTP error! status: ${response.status} - ${errorBody}`);
+		}
+		if (!response.body) throw new Error("No response body for streaming");
+		return response.body;
+	}
+	buildUrl(path) {
+		if (this.config.stub) return `http://localhost:${this.config.port}${path}`;
+		return `${this.baseUrl}${path}`;
+	}
+	buildStreamOptions(body, method) {
+		return {
+			method,
+			headers: body && method === "POST" ? { "Content-Type": "application/json" } : void 0,
+			body: body && method === "POST" ? JSON.stringify(body) : void 0
+		};
+	}
+};
+
+//#endregion
+//#region src/clients/transport/ws-transport.ts
+/**
+* WebSocket transport implementation
+*
+* Multiplexes HTTP-like requests over a single WebSocket connection.
+* Useful when running inside Workers/DO where sub-request limits apply.
+*/
+var WebSocketTransport = class extends BaseTransport {
+	ws = null;
+	state = "disconnected";
+	pendingRequests = /* @__PURE__ */ new Map();
+	connectPromise = null;
+	boundHandleMessage;
+	boundHandleClose;
+	constructor(config) {
+		super(config);
+		if (!config.wsUrl) throw new Error("wsUrl is required for WebSocket transport");
+		this.boundHandleMessage = this.handleMessage.bind(this);
+		this.boundHandleClose = this.handleClose.bind(this);
+	}
+	getMode() {
+		return "websocket";
+	}
+	/**
+	* Check if WebSocket is connected
+	*/
+	isConnected() {
+		return this.state === "connected" && this.ws?.readyState === WebSocket.OPEN;
+	}
+	/**
+	* Connect to the WebSocket server
+	*
+	* The connection promise is assigned synchronously so concurrent
+	* callers share the same connection attempt.
+	*/
+	async connect() {
+		if (this.isConnected()) return;
+		if (this.connectPromise) return this.connectPromise;
+		this.connectPromise = this.doConnect();
+		try {
+			await this.connectPromise;
+		} catch (error) {
+			this.connectPromise = null;
+			throw error;
+		}
+	}
+	/**
+	* Disconnect from the WebSocket server
+	*/
+	disconnect() {
+		this.cleanup();
+	}
+	/**
+	* Transport-specific fetch implementation
+	* Converts WebSocket response to standard Response object.
+	*/
+	async doFetch(path, options) {
+		await this.connect();
+		const method = options?.method || "GET";
+		const body = this.parseBody(options?.body);
+		const result = await this.request(method, path, body);
+		return new Response(JSON.stringify(result.body), {
+			status: result.status,
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	/**
+	* Streaming fetch implementation
+	*/
+	async fetchStream(path, body, method = "POST") {
+		return this.requestStream(method, path, body);
+	}
+	/**
+	* Parse request body from RequestInit
+	*/
+	parseBody(body) {
+		if (!body) return;
+		if (typeof body === "string") try {
+			return JSON.parse(body);
+		} catch (error) {
+			throw new Error(`Request body must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		throw new Error(`WebSocket transport only supports string bodies. Got: ${typeof body}`);
+	}
+	/**
+	* Internal connection logic
+	*/
+	async doConnect() {
+		this.state = "connecting";
+		if (this.config.stub) await this.connectViaFetch();
+		else await this.connectViaWebSocket();
+	}
+	/**
+	* Connect using fetch-based WebSocket (Cloudflare Workers style)
+	* This is required when running inside a Durable Object.
+	*
+	* Uses stub.fetch() which routes WebSocket upgrade requests through the
+	* parent Container class that supports the WebSocket protocol.
+	*/
+	async connectViaFetch() {
+		const timeoutMs = this.config.connectTimeoutMs ?? 3e4;
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const wsPath = new URL(this.config.wsUrl).pathname;
+			const httpUrl = `http://localhost:${this.config.port || 3e3}${wsPath}`;
+			const request = new Request(httpUrl, {
+				headers: {
+					Upgrade: "websocket",
+					Connection: "Upgrade"
+				},
+				signal: controller.signal
+			});
+			const response = await this.config.stub.fetch(request);
+			clearTimeout(timeout);
+			if (response.status !== 101) throw new Error(`WebSocket upgrade failed: ${response.status} ${response.statusText}`);
+			const ws = response.webSocket;
+			if (!ws) throw new Error("No WebSocket in upgrade response");
+			ws.accept();
+			this.ws = ws;
+			this.state = "connected";
+			this.ws.addEventListener("close", this.boundHandleClose);
+			this.ws.addEventListener("message", this.boundHandleMessage);
+			this.logger.debug("WebSocket connected via fetch", { url: this.config.wsUrl });
+		} catch (error) {
+			clearTimeout(timeout);
+			this.state = "error";
+			this.logger.error("WebSocket fetch connection failed", error instanceof Error ? error : new Error(String(error)));
+			throw error;
+		}
+	}
+	/**
+	* Connect using standard WebSocket API (browser/Node style)
+	*/
+	connectViaWebSocket() {
+		return new Promise((resolve, reject) => {
+			const timeoutMs = this.config.connectTimeoutMs ?? 3e4;
+			const timeout = setTimeout(() => {
+				this.cleanup();
+				reject(/* @__PURE__ */ new Error(`WebSocket connection timeout after ${timeoutMs}ms`));
+			}, timeoutMs);
+			try {
+				this.ws = new WebSocket(this.config.wsUrl);
+				const onOpen = () => {
+					clearTimeout(timeout);
+					this.ws?.removeEventListener("open", onOpen);
+					this.ws?.removeEventListener("error", onConnectError);
+					this.state = "connected";
+					this.logger.debug("WebSocket connected", { url: this.config.wsUrl });
+					resolve();
+				};
+				const onConnectError = () => {
+					clearTimeout(timeout);
+					this.ws?.removeEventListener("open", onOpen);
+					this.ws?.removeEventListener("error", onConnectError);
+					this.state = "error";
+					this.logger.error("WebSocket error", /* @__PURE__ */ new Error("WebSocket connection failed"));
+					reject(/* @__PURE__ */ new Error("WebSocket connection failed"));
+				};
+				this.ws.addEventListener("open", onOpen);
+				this.ws.addEventListener("error", onConnectError);
+				this.ws.addEventListener("close", this.boundHandleClose);
+				this.ws.addEventListener("message", this.boundHandleMessage);
+			} catch (error) {
+				clearTimeout(timeout);
+				this.state = "error";
+				reject(error);
+			}
+		});
+	}
+	/**
+	* Send a request and wait for response
+	*/
+	async request(method, path, body) {
+		await this.connect();
+		const id = generateRequestId();
+		const request = {
+			type: "request",
+			id,
+			method,
+			path,
+			body
+		};
+		return new Promise((resolve, reject) => {
+			const timeoutMs = this.config.requestTimeoutMs ?? 12e4;
+			const timeoutId = setTimeout(() => {
+				this.pendingRequests.delete(id);
+				reject(/* @__PURE__ */ new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path}`));
+			}, timeoutMs);
+			this.pendingRequests.set(id, {
+				resolve: (response) => {
+					clearTimeout(timeoutId);
+					this.pendingRequests.delete(id);
+					resolve({
+						status: response.status,
+						body: response.body
+					});
+				},
+				reject: (error) => {
+					clearTimeout(timeoutId);
+					this.pendingRequests.delete(id);
+					reject(error);
+				},
+				isStreaming: false,
+				timeoutId
+			});
+			try {
+				this.send(request);
+			} catch (error) {
+				clearTimeout(timeoutId);
+				this.pendingRequests.delete(id);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			}
+		});
+	}
+	/**
+	* Send a streaming request and return a ReadableStream
+	*
+	* The stream will receive data chunks as they arrive over the WebSocket.
+	* Format matches SSE for compatibility with existing streaming code.
+	*/
+	async requestStream(method, path, body) {
+		await this.connect();
+		const id = generateRequestId();
+		const request = {
+			type: "request",
+			id,
+			method,
+			path,
+			body
+		};
+		return new ReadableStream({
+			start: (controller) => {
+				const timeoutMs = this.config.requestTimeoutMs ?? 12e4;
+				const timeoutId = setTimeout(() => {
+					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) {
+					clearTimeout(timeoutId);
+					this.pendingRequests.delete(id);
+					controller.error(error instanceof Error ? error : new Error(String(error)));
+				}
+			},
+			cancel: () => {
+				const pending = this.pendingRequests.get(id);
+				if (pending?.timeoutId) clearTimeout(pending.timeoutId);
+				this.pendingRequests.delete(id);
+			}
+		});
+	}
+	/**
+	* Send a message over the WebSocket
+	*/
+	send(message) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) throw new Error("WebSocket not connected");
+		this.ws.send(JSON.stringify(message));
+		this.logger.debug("WebSocket sent", {
+			id: message.id,
+			method: message.method,
+			path: message.path
+		});
+	}
+	/**
+	* Handle incoming WebSocket messages
+	*/
+	handleMessage(event) {
+		try {
+			const message = JSON.parse(event.data);
+			if (isWSResponse(message)) this.handleResponse(message);
+			else if (isWSStreamChunk(message)) this.handleStreamChunk(message);
+			else if (isWSError(message)) this.handleError(message);
+			else this.logger.warn("Unknown WebSocket message type", { message });
+		} catch (error) {
+			this.logger.error("Failed to parse WebSocket message", error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+	/**
+	* Handle a response message
+	*/
+	handleResponse(response) {
+		const pending = this.pendingRequests.get(response.id);
+		if (!pending) {
+			this.logger.warn("Received response for unknown request", { id: response.id });
+			return;
+		}
+		this.logger.debug("WebSocket response", {
+			id: response.id,
+			status: response.status,
+			done: response.done
+		});
+		if (response.done) pending.resolve(response);
+	}
+	/**
+	* Handle a stream chunk message
+	*/
+	handleStreamChunk(chunk) {
+		const pending = this.pendingRequests.get(chunk.id);
+		if (!pending || !pending.streamController) {
+			this.logger.warn("Received stream chunk for unknown request", { id: chunk.id });
+			return;
+		}
+		const encoder = new TextEncoder();
+		let sseData;
+		if (chunk.event) sseData = `event: ${chunk.event}\ndata: ${chunk.data}\n\n`;
+		else sseData = `data: ${chunk.data}\n\n`;
+		try {
+			pending.streamController.enqueue(encoder.encode(sseData));
+		} catch (error) {
+			this.logger.debug("Failed to enqueue stream chunk, cleaning up", {
+				id: chunk.id,
+				error: error instanceof Error ? error.message : String(error)
+			});
+			if (pending.timeoutId) clearTimeout(pending.timeoutId);
+			this.pendingRequests.delete(chunk.id);
+		}
+	}
+	/**
+	* Handle an error message
+	*/
+	handleError(error) {
+		if (error.id) {
+			const pending = this.pendingRequests.get(error.id);
+			if (pending) {
+				pending.reject(/* @__PURE__ */ new Error(`${error.code}: ${error.message}`));
+				return;
+			}
+		}
+		this.logger.error("WebSocket error message", new Error(error.message), {
+			code: error.code,
+			status: error.status
+		});
+	}
+	/**
+	* Handle WebSocket close
+	*/
+	handleClose(event) {
+		this.state = "disconnected";
+		this.ws = null;
+		const closeError = /* @__PURE__ */ new Error(`WebSocket closed: ${event.code} ${event.reason || "No reason"}`);
+		for (const [, pending] of this.pendingRequests) {
+			if (pending.timeoutId) clearTimeout(pending.timeoutId);
+			if (pending.streamController) try {
+				pending.streamController.error(closeError);
+			} catch {}
+			pending.reject(closeError);
+		}
+		this.pendingRequests.clear();
+	}
+	/**
+	* Cleanup resources
+	*/
+	cleanup() {
+		if (this.ws) {
+			this.ws.removeEventListener("close", this.boundHandleClose);
+			this.ws.removeEventListener("message", this.boundHandleMessage);
+			this.ws.close();
+			this.ws = null;
+		}
+		this.state = "disconnected";
+		this.connectPromise = null;
+		for (const pending of this.pendingRequests.values()) if (pending.timeoutId) clearTimeout(pending.timeoutId);
+		this.pendingRequests.clear();
+	}
+};
+
+//#endregion
+//#region src/clients/transport/factory.ts
+/**
+* Create a transport instance based on mode
+*
+* This is the primary API for creating transports. It handles
+* the selection of HTTP or WebSocket transport based on the mode.
+*
+* @example
+* ```typescript
+* // HTTP transport (default)
+* const http = createTransport({
+*   mode: 'http',
+*   baseUrl: 'http://localhost:3000'
+* });
+*
+* // WebSocket transport
+* const ws = createTransport({
+*   mode: 'websocket',
+*   wsUrl: 'ws://localhost:3000/ws'
+* });
+* ```
+*/
+function createTransport(options) {
+	switch (options.mode) {
+		case "websocket": return new WebSocketTransport(options);
+		default: return new HttpTransport(options);
+	}
+}
+
+//#endregion
+//#region src/clients/base-client.ts
+/**
+* Abstract base class providing common HTTP/WebSocket functionality for all domain clients
+*
+* All requests go through the Transport abstraction layer, which handles:
+* - HTTP and WebSocket modes transparently
+* - Automatic retry for 503 errors (container starting)
+* - Streaming responses
+*
+* WebSocket mode is useful when running inside Workers/Durable Objects
+* where sub-request limits apply.
+*/
+var BaseHttpClient = class {
+	options;
+	logger;
+	transport;
+	constructor(options = {}) {
+		this.options = options;
+		this.logger = options.logger ?? createNoOpLogger();
+		if (options.transport) this.transport = options.transport;
+		else this.transport = createTransport({
+			mode: options.transportMode ?? "http",
+			baseUrl: options.baseUrl ?? "http://localhost:3000",
+			wsUrl: options.wsUrl,
+			logger: this.logger,
+			stub: options.stub,
+			port: options.port
+		});
+	}
+	/**
+	* Check if using WebSocket transport
+	*/
+	isWebSocketMode() {
+		return this.transport.getMode() === "websocket";
+	}
+	/**
+	* Core fetch method - delegates to Transport which handles retry logic
+	*/
+	async doFetch(path, options) {
+		return this.transport.fetch(path, options);
+	}
+	/**
 	* Make a POST request with JSON body
 	*/
 	async post(endpoint, data, responseHandler) {
@@ -686,6 +1210,30 @@ var BaseHttpClient = class {
 		return response.body;
 	}
 	/**
+	* Stream request handler
+	*
+	* For HTTP mode, uses doFetch + handleStreamResponse to get proper error typing.
+	* For WebSocket mode, uses Transport's streaming support.
+	*
+	* @param path - The API path to call
+	* @param body - Optional request body (for POST requests)
+	* @param method - HTTP method (default: POST, use GET for process logs)
+	*/
+	async doStreamFetch(path, body, method = "POST") {
+		if (this.transport.getMode() === "websocket") try {
+			return await this.transport.fetchStream(path, body, method);
+		} catch (error) {
+			this.logError(`stream ${method} ${path}`, error);
+			throw error;
+		}
+		const response = await this.doFetch(path, {
+			method,
+			headers: { "Content-Type": "application/json" },
+			body: body && method === "POST" ? JSON.stringify(body) : void 0
+		});
+		return this.handleStreamResponse(response);
+	}
+	/**
 	* Utility method to log successful operations
 	*/
 	logSuccess(operation, details) {
@@ -704,67 +1252,6 @@ var BaseHttpClient = class {
 			if (httpStatus >= 500) this.logger.error(`Unexpected error in ${operation}`, error instanceof Error ? error : new Error(String(error)), { httpStatus });
 		} else this.logger.error(`Error in ${operation}`, error instanceof Error ? error : new Error(String(error)));
 	}
-	/**
-	* Check if response indicates a retryable container error
-	* Uses fail-safe strategy: only retry known transient errors
-	*
-	* TODO: This relies on string matching error messages, which is brittle.
-	* Ideally, the container API should return structured errors with a
-	* `retryable: boolean` field to avoid coupling to error message format.
-	*
-	* @param response - HTTP response to check
-	* @returns true if error is retryable container error, false otherwise
-	*/
-	async isRetryableContainerError(response) {
-		if (response.status !== 500 && response.status !== 503) return false;
-		try {
-			const text = await response.clone().text();
-			const textLower = text.toLowerCase();
-			if ([
-				"no such image",
-				"container already exists",
-				"malformed containerinspect"
-			].some((err) => textLower.includes(err))) {
-				this.logger.debug("Detected permanent error, not retrying", { text });
-				return false;
-			}
-			const shouldRetry = [
-				"no container instance available",
-				"currently provisioning",
-				"container port not found",
-				"connection refused: container port",
-				"the container is not listening",
-				"failed to verify port",
-				"container did not start",
-				"network connection lost",
-				"container suddenly disconnected",
-				"monitor failed to find container",
-				"timed out",
-				"timeout"
-			].some((err) => textLower.includes(err));
-			if (!shouldRetry) this.logger.debug("Unknown error pattern, not retrying", {
-				status: response.status,
-				text: text.substring(0, 200)
-			});
-			return shouldRetry;
-		} catch (error) {
-			this.logger.error("Error checking if response is retryable", error instanceof Error ? error : new Error(String(error)));
-			return false;
-		}
-	}
-	async executeFetch(path, options) {
-		const url = this.options.stub ? `http://localhost:${this.options.port}${path}` : `${this.baseUrl}${path}`;
-		try {
-			if (this.options.stub) return await this.options.stub.containerFetch(url, options || {}, this.options.port);
-			else return await fetch(url, options);
-		} catch (error) {
-			this.logger.error("HTTP request error", error instanceof Error ? error : new Error(String(error)), {
-				method: options?.method || "GET",
-				url
-			});
-			throw error;
-		}
-	}
 };
 
 //#endregion
@@ -815,12 +1302,7 @@ var CommandClient = class extends BaseHttpClient {
 				...options?.env !== void 0 && { env: options.env },
 				...options?.cwd !== void 0 && { cwd: options.cwd }
 			};
-			const response = await this.doFetch("/api/execute/stream", {
-				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify(data)
-			});
-			const stream = await this.handleStreamResponse(response);
+			const stream = await this.doStreamFetch("/api/execute/stream", data);
 			this.logSuccess("Command stream started", command);
 			return stream;
 		} catch (error) {
@@ -914,12 +1396,7 @@ var FileClient = class extends BaseHttpClient {
 				path,
 				sessionId
 			};
-			const response = await this.doFetch("/api/read/stream", {
-				method: "POST",
-				headers: { "Content-Type": "application/json" },
-				body: JSON.stringify(data)
-			});
-			const stream = await this.handleStreamResponse(response);
+			const stream = await this.doStreamFetch("/api/read/stream", data);
 			this.logSuccess("File stream started", path);
 			return stream;
 		} catch (error) {
@@ -1108,22 +1585,13 @@ var InterpreterClient = class extends BaseHttpClient {
 	}
 	async runCodeStream(contextId, code, language, callbacks, timeoutMs) {
 		return this.executeWithRetry(async () => {
-			const response = await this.doFetch("/api/execute/code", {
-				method: "POST",
-				headers: {
-					"Content-Type": "application/json",
-					Accept: "text/event-stream"
-				},
-				body: JSON.stringify({
-					context_id: contextId,
-					code,
-					language,
-					...timeoutMs !== void 0 && { timeout_ms: timeoutMs }
-				})
+			const stream = await this.doStreamFetch("/api/execute/code", {
+				context_id: contextId,
+				code,
+				language,
+				...timeoutMs !== void 0 && { timeout_ms: timeoutMs }
 			});
-			if (!response.ok) throw await this.parseErrorResponse(response);
-			if (!response.body) throw new Error("No response body for streaming execution");
-			for await (const chunk of this.readLines(response.body)) await this.parseExecutionResult(chunk, callbacks);
+			for await (const chunk of this.readLines(stream)) await this.parseExecutionResult(chunk, callbacks);
 		});
 	}
 	async listCodeContexts() {
@@ -1154,6 +1622,17 @@ var InterpreterClient = class extends BaseHttpClient {
 		});
 	}
 	/**
+	* Get a raw stream for code execution.
+	* Used by CodeInterpreter.runCodeStreaming() for direct stream access.
+	*/
+	async streamCode(contextId, code, language) {
+		return this.doStreamFetch("/api/execute/code", {
+			context_id: contextId,
+			code,
+			language
+		});
+	}
+	/**
 	* Execute an operation with automatic retry for transient errors
 	*/
 	async executeWithRetry(operation) {
@@ -1314,17 +1793,18 @@ var PortClient = class extends BaseHttpClient {
 		}
 	}
 	/**
-	* Check if a port is ready to accept connections
-	* @param request - Port check configuration
+	* Watch a port for readiness via SSE stream
+	* @param request - Port watch configuration
+	* @returns SSE stream that emits PortWatchEvent objects
 	*/
-	async checkPortReady(request) {
+	async watchPort(request) {
 		try {
-			return await this.post("/api/port-check", request);
+			const stream = await this.doStreamFetch("/api/port-watch", request);
+			this.logSuccess("Port watch started", `port ${request.port}`);
+			return stream;
 		} catch (error) {
-			return {
-				ready: false,
-				error: error instanceof Error ? error.message : "Port check failed"
-			};
+			this.logError("watchPort", error);
+			throw error;
 		}
 	}
 };
@@ -1439,8 +1919,7 @@ var ProcessClient = class extends BaseHttpClient {
 	async streamProcessLogs(processId) {
 		try {
 			const url = `/api/process/${processId}/stream`;
-			const response = await this.doFetch(url, { method: "GET" });
-			const stream = await this.handleStreamResponse(response);
+			const stream = await this.doStreamFetch(url, void 0, "GET");
 			this.logSuccess("Process log stream started", `ID: ${processId}`);
 			return stream;
 		} catch (error) {
@@ -1531,6 +2010,12 @@ var UtilityClient = class extends BaseHttpClient {
 /**
 * 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.
 */
 var SandboxClient = class {
 	commands;
@@ -1540,10 +2025,20 @@ var SandboxClient = class {
 	git;
 	interpreter;
 	utils;
+	transport = null;
 	constructor(options) {
+		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
+			mode: "websocket",
+			wsUrl: options.wsUrl,
+			baseUrl: options.baseUrl,
+			logger: options.logger,
+			stub: options.stub,
+			port: options.port
+		});
 		const clientOptions = {
 			baseUrl: "http://localhost:3000",
-			...options
+			...options,
+			transport: this.transport ?? options.transport
 		};
 		this.commands = new CommandClient(clientOptions);
 		this.files = new FileClient(clientOptions);
@@ -1553,6 +2048,33 @@ var SandboxClient = class {
 		this.interpreter = new InterpreterClient(clientOptions);
 		this.utils = new UtilityClient(clientOptions);
 	}
+	/**
+	* Get the current transport mode
+	*/
+	getTransportMode() {
+		return this.transport?.getMode() ?? "http";
+	}
+	/**
+	* Check if WebSocket is connected (only relevant in WebSocket mode)
+	*/
+	isWebSocketConnected() {
+		return this.transport?.isConnected() ?? false;
+	}
+	/**
+	* Connect WebSocket transport (no-op in HTTP mode)
+	* Called automatically on first request, but can be called explicitly
+	* to establish connection upfront.
+	*/
+	async connect() {
+		if (this.transport) await this.transport.connect();
+	}
+	/**
+	* Disconnect WebSocket transport (no-op in HTTP mode)
+	* Should be called when the sandbox is destroyed.
+	*/
+	disconnect() {
+		if (this.transport) this.transport.disconnect();
+	}
 };
 
 //#endregion
@@ -1679,24 +2201,7 @@ var CodeInterpreter = class {
 			const language = options.language || "python";
 			context = await this.getOrCreateDefaultContext(language);
 		}
-		const response = await this.interpreterClient.doFetch("/api/execute/code", {
-			method: "POST",
-			headers: {
-				"Content-Type": "application/json",
-				Accept: "text/event-stream"
-			},
-			body: JSON.stringify({
-				context_id: context.id,
-				code,
-				language: options.language
-			})
-		});
-		if (!response.ok) {
-			const errorData = await response.json().catch(() => ({ error: "Unknown error" }));
-			throw new Error(errorData.error || `Failed to execute code: ${response.status}`);
-		}
-		if (!response.body) throw new Error("No response body for streaming execution");
-		return response.body;
+		return this.interpreterClient.streamCode(context.id, code, options.language);
 	}
 	/**
 	* List all code contexts
@@ -2019,7 +2524,7 @@ function resolveS3fsOptions(provider, userOptions) {
 * 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.6.5";
+const SDK_VERSION = "0.6.7";
 
 //#endregion
 //#region src/sandbox.ts
@@ -2051,12 +2556,12 @@ var Sandbox = class extends Container {
 	sandboxName = null;
 	normalizeId = false;
 	baseUrl = null;
-	portTokens = /* @__PURE__ */ new Map();
 	defaultSession = null;
 	envVars = {};
 	logger;
 	keepAliveEnabled = false;
 	activeMounts = /* @__PURE__ */ new Map();
+	transport = "http";
 	/**
 	* Default container startup timeouts (conservative for production)
 	* Based on Cloudflare docs: "Containers take several minutes to provision"
@@ -2071,6 +2576,20 @@ var Sandbox = class extends Container {
 	* Can be set via options, env vars, or defaults
 	*/
 	containerTimeouts = { ...this.DEFAULT_CONTAINER_TIMEOUTS };
+	/**
+	* Create a SandboxClient with current transport settings
+	*/
+	createSandboxClient() {
+		return new SandboxClient({
+			logger: this.logger,
+			port: 3e3,
+			stub: this,
+			...this.transport === "websocket" && {
+				transportMode: "websocket",
+				wsUrl: "ws://localhost:3000/ws"
+			}
+		});
+	}
 	constructor(ctx, env) {
 		super(ctx, env);
 		const envObj = env;
@@ -2082,19 +2601,15 @@ var Sandbox = class extends Container {
 			component: "sandbox-do",
 			sandboxId: this.ctx.id.toString()
 		});
-		this.client = new SandboxClient({
-			logger: this.logger,
-			port: 3e3,
-			stub: this
-		});
+		const transportEnv = envObj?.SANDBOX_TRANSPORT;
+		if (transportEnv === "websocket") this.transport = "websocket";
+		else if (transportEnv != null && transportEnv !== "http") this.logger.warn(`Invalid SANDBOX_TRANSPORT value: "${transportEnv}". Must be "http" or "websocket". Defaulting to "http".`);
+		this.client = this.createSandboxClient();
 		this.codeInterpreter = new CodeInterpreter(this);
 		this.ctx.blockConcurrencyWhile(async () => {
 			this.sandboxName = await this.ctx.storage.get("sandboxName") || null;
 			this.normalizeId = await this.ctx.storage.get("normalizeId") || false;
 			this.defaultSession = await this.ctx.storage.get("defaultSession") || null;
-			const storedTokens = await this.ctx.storage.get("portTokens") || {};
-			this.portTokens = /* @__PURE__ */ new Map();
-			for (const [portStr, token] of Object.entries(storedTokens)) this.portTokens.set(parseInt(portStr, 10), token);
 			const storedTimeouts = await this.ctx.storage.get("containerTimeouts");
 			if (storedTimeouts) this.containerTimeouts = {
 				...this.containerTimeouts,
@@ -2302,6 +2817,7 @@ var Sandbox = class extends Container {
 	*/
 	async destroy() {
 		this.logger.info("Destroying sandbox container");
+		this.client.disconnect();
 		for (const [mountPath, mountInfo] of this.activeMounts.entries()) {
 			if (mountInfo.mounted) try {
 				this.logger.info(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
@@ -2346,7 +2862,6 @@ var Sandbox = class extends Container {
 	}
 	async onStop() {
 		this.logger.debug("Sandbox stopped");
-		this.portTokens.clear();
 		this.defaultSession = null;
 		this.activeMounts.clear();
 		await Promise.all([this.ctx.storage.delete("portTokens"), this.ctx.storage.delete("defaultSession")]);
@@ -2379,18 +2894,57 @@ var Sandbox = class extends Container {
 				status: 503,
 				headers: { "Retry-After": "10" }
 			});
-			this.logger.error("Container startup failed", e instanceof Error ? e : new Error(String(e)));
+			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.", {
+					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 });
 		}
 		return await super.containerFetch(requestOrUrl, portOrInit, portParam);
 	}
 	/**
 	* Helper: Check if error is "no container instance available"
+	* This indicates the container VM is still being provisioned.
 	*/
 	isNoInstanceError(error) {
 		return error instanceof Error && error.message.toLowerCase().includes("no container instance");
 	}
 	/**
+	* 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
+	*/
+	isTransientStartupError(error) {
+		if (!(error instanceof Error)) return false;
+		const msg = error.message.toLowerCase();
+		return [
+			"container port not found",
+			"connection refused: container port",
+			"the container is not listening",
+			"failed to verify port",
+			"container did not start",
+			"network connection lost",
+			"container suddenly disconnected",
+			"monitor failed to find container",
+			"timed out",
+			"timeout",
+			"the operation was aborted"
+		].some((pattern) => msg.includes(pattern));
+	}
+	/**
 	* Helper: Parse containerFetch arguments (supports multiple signatures)
 	*/
 	parseContainerFetchArgs(requestOrUrl, portOrInit, portParam) {
@@ -2451,7 +3005,7 @@ var Sandbox = class extends Container {
 		return await this.containerFetch(request, port);
 	}
 	wsConnect(request, port) {
-		throw new Error("Not implemented here to avoid RPC serialization issues");
+		throw new Error("wsConnect must be called on the stub returned by getSandbox()");
 	}
 	determinePort(url) {
 		const proxyMatch = url.pathname.match(/^\/proxy\/(\d+)/);
@@ -2462,9 +3016,9 @@ var Sandbox = class extends Container {
 	* Ensure default session exists - lazy initialization
 	* This is called automatically by all public methods that need a session
 	*
-	* The session is persisted to Durable Object storage to survive hot reloads
-	* during development. If a session already exists in the container after reload,
-	* we reuse it instead of trying to create a new one.
+	* The session ID is persisted to DO storage. On container restart, if the
+	* container already has this session (from a previous instance), we sync
+	* our state rather than failing on duplicate creation.
 	*/
 	async ensureDefaultSession() {
 		const sessionId = `sandbox-${this.sandboxName || "default"}`;
@@ -2606,6 +3160,9 @@ var Sandbox = class extends Container {
 			},
 			waitForPort: async (port, options) => {
 				await this.waitForPortReady(data.id, data.command, port, options);
+			},
+			waitForExit: async (timeout) => {
+				return this.waitForProcessExit(data.id, data.command, timeout);
 			}
 		};
 	}
@@ -2699,35 +3256,65 @@ var Sandbox = class extends Container {
 			min: 200,
 			max: 399
 		}, timeout, interval = 500 } = options ?? {};
-		const startTime = Date.now();
 		const conditionStr = mode === "http" ? `port ${port} (HTTP ${path})` : `port ${port} (TCP)`;
-		const targetInterval = interval;
-		let checkCount = 0;
-		const checkRequest = {
+		const statusMin = typeof status === "number" ? status : status.min;
+		const statusMax = typeof status === "number" ? status : status.max;
+		const stream = await this.client.ports.watchPort({
 			port,
 			mode,
 			path,
-			statusMin: typeof status === "number" ? status : status.min,
-			statusMax: typeof status === "number" ? status : status.max
-		};
-		while (true) {
-			if (timeout !== void 0) {
-				if (timeout - (Date.now() - startTime) <= 0) throw this.createReadyTimeoutError(processId, command, conditionStr, timeout);
-			}
-			const iterationStart = Date.now();
-			if (checkCount % 3 === 0) {
-				const processInfo = await this.getProcess(processId);
-				if (!processInfo || isTerminalStatus(processInfo.status)) throw this.createExitedBeforeReadyError(processId, command, conditionStr, processInfo?.exitCode ?? 1);
-			}
+			statusMin,
+			statusMax,
+			processId,
+			interval
+		});
+		let timeoutId;
+		let timeoutPromise;
+		if (timeout !== void 0) timeoutPromise = new Promise((_, reject) => {
+			timeoutId = setTimeout(() => {
+				reject(this.createReadyTimeoutError(processId, command, conditionStr, timeout));
+			}, timeout);
+		});
+		try {
+			const streamProcessor = async () => {
+				for await (const event of parseSSEStream(stream)) switch (event.type) {
+					case "ready": return;
+					case "process_exited": throw this.createExitedBeforeReadyError(processId, command, conditionStr, event.exitCode ?? 1);
+					case "error": throw new Error(event.error || "Port watch failed");
+				}
+				throw new Error("Port watch stream ended unexpectedly");
+			};
+			if (timeoutPromise) await Promise.race([streamProcessor(), timeoutPromise]);
+			else await streamProcessor();
+		} finally {
+			if (timeoutId) clearTimeout(timeoutId);
 			try {
-				if ((await this.client.ports.checkPortReady(checkRequest)).ready) return;
+				await stream.cancel();
 			} catch {}
-			checkCount++;
-			const iterationDuration = Date.now() - iterationStart;
-			const sleepTime = Math.max(0, targetInterval - iterationDuration);
-			if (sleepTime > 0) {
-				if (timeout === void 0 || Date.now() - startTime + sleepTime < timeout) await new Promise((resolve) => setTimeout(resolve, sleepTime));
-			}
+		}
+	}
+	/**
+	* Wait for a process to exit
+	* Returns the exit code
+	*/
+	async waitForProcessExit(processId, command, timeout) {
+		const stream = await this.streamProcessLogs(processId);
+		let timeoutId;
+		let timeoutPromise;
+		if (timeout !== void 0) timeoutPromise = new Promise((_, reject) => {
+			timeoutId = setTimeout(() => {
+				reject(this.createReadyTimeoutError(processId, command, "process exit", timeout));
+			}, timeout);
+		});
+		try {
+			const streamProcessor = async () => {
+				for await (const event of parseSSEStream(stream)) if (event.type === "exit") return { exitCode: event.exitCode ?? 1 };
+				throw new Error(`Process ${processId} stream ended unexpectedly without exit event`);
+			};
+			if (timeoutPromise) return await Promise.race([streamProcessor(), timeoutPromise]);
+			return await streamProcessor();
+		} finally {
+			if (timeoutId) clearTimeout(timeoutId);
 		}
 	}
 	/**
@@ -2988,8 +3575,9 @@ var Sandbox = class extends Container {
 		await this.client.ports.exposePort(port, sessionId, options?.name);
 		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
 		const token = this.generatePortToken();
-		this.portTokens.set(port, token);
-		await this.persistPortTokens();
+		const tokens = await this.ctx.storage.get("portTokens") || {};
+		tokens[port.toString()] = token;
+		await this.ctx.storage.put("portTokens", tokens);
 		return {
 			url: this.constructPreviewUrl(port, this.sandboxName, options.hostname, token),
 			port,
@@ -3000,17 +3588,19 @@ var Sandbox = class extends Container {
 		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be between 1024-65535 and not reserved.`);
 		const sessionId = await this.ensureDefaultSession();
 		await this.client.ports.unexposePort(port, sessionId);
-		if (this.portTokens.has(port)) {
-			this.portTokens.delete(port);
-			await this.persistPortTokens();
+		const tokens = await this.ctx.storage.get("portTokens") || {};
+		if (tokens[port.toString()]) {
+			delete tokens[port.toString()];
+			await this.ctx.storage.put("portTokens", tokens);
 		}
 	}
 	async getExposedPorts(hostname) {
 		const sessionId = await this.ensureDefaultSession();
 		const response = await this.client.ports.getExposedPorts(sessionId);
 		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
+		const tokens = await this.ctx.storage.get("portTokens") || {};
 		return response.ports.map((port) => {
-			const token = this.portTokens.get(port.port);
+			const token = tokens[port.port.toString()];
 			if (!token) throw new Error(`Port ${port.port} is exposed but has no token. This should not happen.`);
 			return {
 				url: this.constructPreviewUrl(port.port, this.sandboxName, hostname, token),
@@ -3030,7 +3620,7 @@ var Sandbox = class extends Container {
 	}
 	async validatePortToken(port, token) {
 		if (!await this.isPortExposed(port)) return false;
-		const storedToken = this.portTokens.get(port);
+		const storedToken = (await this.ctx.storage.get("portTokens") || {})[port.toString()];
 		if (!storedToken) {
 			this.logger.error("Port is exposed but has no token - bug detected", void 0, { port });
 			return false;
@@ -3042,11 +3632,6 @@ var Sandbox = class extends Container {
 		crypto.getRandomValues(array);
 		return btoa(String.fromCharCode(...array)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "").toLowerCase();
 	}
-	async persistPortTokens() {
-		const tokensObj = {};
-		for (const [port, token] of this.portTokens.entries()) tokensObj[port.toString()] = token;
-		await this.ctx.storage.put("portTokens", tokensObj);
-	}
 	constructPreviewUrl(port, sandboxId, hostname, token) {
 		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be between 1024-65535 and not reserved.`);
 		const effectiveId = this.sandboxName || sandboxId;