@cloudflare/sandbox 0.10.1 → 0.10.3

package/dist/{sandbox-uC1vzWtG.js → sandbox-B-MUmsli.js}

@@ -1,9 +1,10 @@
 import { _ as GitLogger, b as getEnvString, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as DEFAULT_GIT_CLONE_TIMEOUT_MS, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, p as logCanonicalEvent, r as isWSResponse, t as generateRequestId, u as createLogger, v as extractRepoName, x as partitionEnvVars, y as filterEnvVars } from "./dist-B_eXrP83.js";
-import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-CBi-O-pF.js";
+import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-8Hvune8K.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
-import { RpcSession } from "capnweb";
+import { RpcSession, RpcTarget } from "capnweb";
 import path from "node:path/posix";
+import { RpcTarget as RpcTarget$1 } from "cloudflare:workers";
 
 //#region src/errors/classes.ts
 /**
@@ -1784,6 +1785,17 @@ var CommandClient = class extends BaseHttpClient {
 //#endregion
 //#region src/clients/desktop-client.ts
 /**
+* Decode a base64-encoded screenshot payload into a Uint8Array.
+* Shared with the RPC client wrapper, which receives base64 over the
+* wire and needs the same `format: 'bytes'` convenience.
+*/
+function base64ToBytes(data) {
+	const binaryString = atob(data);
+	const bytes = new Uint8Array(binaryString.length);
+	for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+	return bytes;
+}
+/**
 * Client for desktop environment lifecycle, input, and screen operations
 */
 var DesktopClient = class extends BaseHttpClient {
@@ -1828,15 +1840,10 @@ var DesktopClient = class extends BaseHttpClient {
 			...options?.showCursor !== void 0 && { showCursor: options.showCursor }
 		};
 		const response = await this.post("/api/desktop/screenshot", data);
-		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
-			};
-		}
+		if (wantsBytes) return {
+			...response,
+			data: base64ToBytes(response.data)
+		};
 		return response;
 	}
 	async screenshotRegion(region, options) {
@@ -1849,15 +1856,10 @@ var DesktopClient = class extends BaseHttpClient {
 			...options?.showCursor !== void 0 && { showCursor: options.showCursor }
 		};
 		const response = await this.post("/api/desktop/screenshot/region", data);
-		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
-			};
-		}
+		if (wantsBytes) return {
+			...response,
+			data: base64ToBytes(response.data)
+		};
 		return response;
 	}
 	/**
@@ -2010,7 +2012,7 @@ var DesktopClient = class extends BaseHttpClient {
 	* Get health status for a specific desktop process.
 	*/
 	async getProcessStatus(name) {
-		return await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
+		return this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
 	}
 };
 
@@ -2523,6 +2525,9 @@ var UtilityClient = class extends BaseHttpClient {
 			return "unknown";
 		}
 	}
+	listSessions() {
+		throw new Error("listSessions requires the RPC transport. Set SANDBOX_TRANSPORT=rpc.");
+	}
 };
 
 //#endregion
@@ -2646,6 +2651,13 @@ var SandboxClient = class {
 	utils;
 	desktop;
 	watch;
+	/**
+	* Tunnels are RPC-only — the route-based transport does not implement them.
+	* This getter exists so the `PublicKeys<SandboxClient> satisfies
+	* PublicKeys<SandboxAPI>` compile-time check holds. Calling any method on
+	* the returned proxy throws a clear `RPC transport required` error.
+	*/
+	tunnels = createTunnelsNotImplemented();
 	transport = null;
 	constructor(options) {
 		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
@@ -2723,6 +2735,14 @@ var SandboxClient = class {
 		if (this.transport) this.transport.disconnect();
 	}
 };
+function createTunnelsNotImplemented() {
+	const message = "sandbox.tunnels.* requires the RPC transport. Enable it with transport: \"rpc\" in sandbox options.";
+	return new Proxy({}, { get() {
+		return () => {
+			throw new Error(message);
+		};
+	} });
+}
 
 //#endregion
 //#region ../shared/src/backup.ts
@@ -2745,6 +2765,10 @@ function normalizeBackupExcludePattern(pattern) {
 	return normalized;
 }
 
+//#endregion
+//#region ../shared/src/internal.ts
+const DISABLE_SESSION_TOKEN = "__DISABLE_SESSION__";
+
 //#endregion
 //#region src/container-control/connection.ts
 const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
@@ -2769,13 +2793,15 @@ var ContainerControlConnection = class {
 	port;
 	logger;
 	retryTimeoutMs;
+	onClose;
 	constructor(options) {
 		this.containerStub = options.stub;
 		this.port = options.port ?? 3e3;
 		this.logger = options.logger ?? createNoOpLogger();
 		this.retryTimeoutMs = options.retryTimeoutMs ?? DEFAULT_RETRY_TIMEOUT_MS;
+		this.onClose = options.onClose;
 		this.transport = new DeferredTransport();
-		this.session = new RpcSession(this.transport);
+		this.session = new RpcSession(this.transport, options.localMain);
 		this.stub = this.session.getRemoteMain();
 	}
 	/**
@@ -2815,6 +2841,8 @@ var ContainerControlConnection = class {
 			this.stub[Symbol.dispose]?.();
 		} catch {}
 		if (this.ws) {
+			this.ws.removeEventListener("close", this.onWebSocketClose);
+			this.ws.removeEventListener("error", this.onWebSocketError);
 			try {
 				this.ws.close();
 			} catch {}
@@ -2831,6 +2859,42 @@ var ContainerControlConnection = class {
 	setRetryTimeoutMs(ms) {
 		this.retryTimeoutMs = ms;
 	}
+	/**
+	* Run the owner-provided `onClose` callback exactly once per call,
+	* swallowing any errors so a buggy listener can't keep the connection
+	* object in a half-torn-down state.
+	*/
+	fireOnClose() {
+		if (!this.onClose) return;
+		try {
+			this.onClose();
+		} catch (err) {
+			this.logger.warn("ContainerControlConnection onClose handler threw", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	/**
+	* WebSocket `close` listener. Defined as a bound arrow field so the
+	* same reference can be passed to both `addEventListener` and
+	* `removeEventListener` — a fresh anonymous lambda would silently
+	* fail to unbind.
+	*/
+	onWebSocketClose = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		this.logger.debug("ContainerControlConnection WebSocket closed");
+		if (wasConnected) this.fireOnClose();
+	};
+	/**
+	* WebSocket `error` listener. Same field-form rationale as
+	* {@link onWebSocketClose}.
+	*/
+	onWebSocketError = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		if (wasConnected) this.fireOnClose();
+	};
 	async doConnect() {
 		try {
 			const response = await this.fetchUpgradeWithRetry();
@@ -2838,15 +2902,8 @@ var ContainerControlConnection = class {
 			const ws = response.webSocket;
 			if (!ws) throw new Error("No WebSocket in upgrade response");
 			ws.accept();
-			ws.addEventListener("close", () => {
-				this.connected = false;
-				this.ws = null;
-				this.logger.debug("ContainerControlConnection WebSocket closed");
-			});
-			ws.addEventListener("error", () => {
-				this.connected = false;
-				this.ws = null;
-			});
+			ws.addEventListener("close", this.onWebSocketClose);
+			ws.addEventListener("error", this.onWebSocketError);
 			this.ws = ws;
 			this.transport.activate(ws);
 			this.connected = true;
@@ -3004,12 +3061,33 @@ const IDLE_EXPORT_THRESHOLD = 1;
 /**
 * Translate a capnweb-propagated error into a typed SandboxError.
 *
-* capnweb only preserves `error.name` and `error.message` across the wire.
-* The container encodes the full error as a JSON object in the message
-* string: `{"code":"...","message":"...","context":{...}}`.
+* Two wire formats are supported for backward compatibility with older
+* container images:
+*
+*  1. Propagated error properties (capnweb >= 0.8.0). The container throws a
+*     `ServiceError`-shaped object with own enumerable `code` and `details`
+*     properties. capnweb walks `Object.keys()` and reconstructs those fields
+*     on the SDK side.
+*  2. Legacy JSON-encoded message. Older containers encoded the structured
+*     payload as a JSON string in `error.message`.
+*
+* The JSON-fallback branch can be removed once all older container images are
+* no longer in service.
 */
 function translateRPCError(error) {
 	if (error instanceof Error) {
+		const propagated = error;
+		if (typeof propagated.code === "string" && Object.hasOwn(ErrorCode, propagated.code)) {
+			const code = propagated.code;
+			const context = propagated.details && typeof propagated.details === "object" ? propagated.details : {};
+			throw createErrorFromResponse({
+				code,
+				message: error.message,
+				context,
+				httpStatus: getHttpStatus(code),
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
 		let payload;
 		try {
 			payload = JSON.parse(error.message);
@@ -3126,19 +3204,16 @@ var ContainerControlClient = class {
 	busyPollTimer = null;
 	/** Tracks whether we currently believe the session is busy. */
 	busy = false;
-	/**
-	* Set the first time the poller observes `conn.isConnected() === true`,
-	* cleared in `destroyConnection()`. Lets us distinguish "the WebSocket
-	* upgrade is still in progress" (don't tear down) from "we were
-	* connected and the peer went away" (do tear down).
-	*/
-	wasEverConnected = false;
 	constructor(options) {
 		this.connOptions = {
 			stub: options.stub,
 			port: options.port,
+			localMain: options.localMain,
 			logger: options.logger,
-			retryTimeoutMs: options.retryTimeoutMs
+			retryTimeoutMs: options.retryTimeoutMs,
+			onClose: () => {
+				if (this.conn) this.destroyConnection();
+			}
 		};
 		this.idleDisconnectMs = options.idleDisconnectMs ?? DEFAULT_IDLE_DISCONNECT_MS;
 		this.busyPollIntervalMs = options.busyPollIntervalMs ?? BUSY_POLL_INTERVAL_MS;
@@ -3180,11 +3255,7 @@ var ContainerControlClient = class {
 	pollBusyState = () => {
 		const conn = this.conn;
 		if (!conn) return;
-		if (!conn.isConnected()) {
-			if (this.wasEverConnected) this.destroyConnection();
-			return;
-		}
-		this.wasEverConnected = true;
+		if (!conn.isConnected()) return;
 		const { imports, exports } = conn.getStats();
 		if (imports > IDLE_IMPORT_THRESHOLD || exports > IDLE_EXPORT_THRESHOLD) {
 			if (!this.busy) {
@@ -3217,7 +3288,7 @@ var ContainerControlClient = class {
 			if (!conn || !conn.isConnected()) return;
 			const { imports, exports } = conn.getStats();
 			if (imports <= IDLE_IMPORT_THRESHOLD && exports <= IDLE_EXPORT_THRESHOLD) {
-				this.logger.debug("Disconnecting idle capnweb connection");
+				this.logger.debug("Disconnecting idle RPC connection");
 				this.destroyConnection();
 			}
 		}, this.idleDisconnectMs);
@@ -3239,7 +3310,6 @@ var ContainerControlClient = class {
 			this.conn.disconnect();
 			this.conn = null;
 		}
-		this.wasEverConnected = false;
 	}
 	get commands() {
 		return wrapStub(this.getConnection().rpc().commands, this.renewActivity);
@@ -3263,11 +3333,37 @@ var ContainerControlClient = class {
 		return wrapStub(this.getConnection().rpc().backup, this.renewActivity);
 	}
 	get desktop() {
-		return wrapStub(this.getConnection().rpc().desktop, this.renewActivity);
+		const stub = wrapStub(this.getConnection().rpc().desktop, this.renewActivity);
+		const wire = stub;
+		return new Proxy(stub, { get(target, prop, receiver) {
+			if (prop === "screenshot") return async (options) => {
+				const { format, ...rest } = options ?? {};
+				const result = await wire.screenshot(rest);
+				return format === "bytes" ? {
+					...result,
+					data: base64ToBytes(result.data)
+				} : result;
+			};
+			if (prop === "screenshotRegion") return async (region, options) => {
+				const { format, ...rest } = options ?? {};
+				const result = await wire.screenshotRegion({
+					region,
+					...rest
+				});
+				return format === "bytes" ? {
+					...result,
+					data: base64ToBytes(result.data)
+				} : result;
+			};
+			return Reflect.get(target, prop, receiver);
+		} });
 	}
 	get watch() {
 		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
 	}
+	get tunnels() {
+		return wrapStub(this.getConnection().rpc().tunnels, this.renewActivity);
+	}
 	get interpreter() {
 		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
 	}
@@ -3808,6 +3904,13 @@ function resolveS3fsOptions(provider, userOptions) {
 
 //#endregion
 //#region src/storage-mount/validation.ts
+/**
+* Type guard for R2Bucket binding.
+* Checks for the minimal R2Bucket interface methods we use.
+*/
+function isR2Bucket(value) {
+	return typeof value === "object" && value !== null && "put" in value && typeof value.put === "function" && "get" in value && typeof value.get === "function" && "head" in value && typeof value.head === "function" && "delete" in value && typeof value.delete === "function" && "list" in value && typeof value.list === "function";
+}
 function validatePrefix(prefix) {
 	if (!prefix.startsWith("/")) throw new InvalidMountConfigError(`Prefix must start with '/': "${prefix}"`);
 }
@@ -3818,6 +3921,13 @@ function validateBucketName(bucket, mountPath) {
 	}
 	if (!/^[a-z0-9]([a-z0-9.-]{0,61}[a-z0-9])?$/.test(bucket)) throw new InvalidMountConfigError(`Invalid bucket name: "${bucket}". Bucket names must be 3-63 characters, lowercase alphanumeric, dots, or hyphens, and cannot start/end with dots or hyphens.`);
 }
+function validateBucketBindingName(bucketBinding, mountPath) {
+	if (bucketBinding.includes(":")) {
+		const [bucketName, prefixPart] = bucketBinding.split(":");
+		throw new InvalidMountConfigError(`Bucket name cannot contain ':'. To mount a prefix, use the 'prefix' option:\n  mountBucket('${bucketName}', '${mountPath}', { ...options, prefix: '${prefixPart}' })`);
+	}
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(bucketBinding)) throw new InvalidMountConfigError(`Invalid R2 binding name: "${bucketBinding}". Binding names must start with a letter or underscore and contain only letters, numbers, or underscores.`);
+}
 /**
 * Builds the s3fs source string from bucket name and optional prefix.
 * Format: "bucket" or "bucket:/prefix/" for subdirectory mounts.
@@ -4142,7 +4252,7 @@ async function proxyTerminal(stub, sessionId, request, options) {
 
 //#endregion
 //#region src/request-handler.ts
-async function proxyToSandbox(request, env) {
+async function proxyToSandbox(request, env$1) {
 	const logger = createLogger({
 		component: "sandbox-do",
 		traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
@@ -4153,7 +4263,7 @@ async function proxyToSandbox(request, env) {
 		const routeInfo = extractSandboxRoute(url);
 		if (!routeInfo) return null;
 		const { sandboxId, port, path: path$1, token } = routeInfo;
-		const sandbox = getSandbox(env.Sandbox, sandboxId, { normalizeId: true });
+		const sandbox = getSandbox(env$1.Sandbox, sandboxId, { normalizeId: true });
 		if (port !== 3e3) {
 			if (!await sandbox.validatePortToken(port, token)) {
 				logger.warn("Invalid token access blocked", {
@@ -4239,6 +4349,513 @@ function isLocalhostPattern(hostname) {
 	return hostPart === "localhost" || hostPart === "127.0.0.1" || hostPart === "0.0.0.0";
 }
 
+//#endregion
+//#region src/storage-mount/r2-egress-handler.ts
+const XML_NS = "xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"";
+const XML_DECL = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
+function escapeXML(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function xmlResponse(body, status = 200) {
+	return new Response(XML_DECL + body, {
+		status,
+		headers: { "Content-Type": "application/xml" }
+	});
+}
+function normalizeObjectKey(value) {
+	return value.replace(/^\/+/, "");
+}
+function trimTrailingSlashes(s) {
+	let end = s.length;
+	while (end > 0 && s[end - 1] === "/") end--;
+	return s.slice(0, end);
+}
+function parsePath(pathname) {
+	const stripped = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	if (!stripped) return null;
+	const slash = stripped.indexOf("/");
+	if (slash === -1) return {
+		bucket: stripped,
+		key: ""
+	};
+	return {
+		bucket: stripped.slice(0, slash),
+		key: normalizeObjectKey(stripped.slice(slash + 1))
+	};
+}
+function resolveR2Bucket(env$1, name) {
+	if (typeof env$1 !== "object" || env$1 === null) return null;
+	const val = env$1[name];
+	return isR2Bucket(val) ? val : null;
+}
+function parseRange(header) {
+	if (!header) return void 0;
+	const m = header.match(/^bytes=(\d*)-(\d*)$/);
+	if (!m) return void 0;
+	const start = m[1] ? parseInt(m[1], 10) : void 0;
+	const end = m[2] ? parseInt(m[2], 10) : void 0;
+	if (start === void 0 && end !== void 0) return { suffix: end };
+	if (start !== void 0 && end !== void 0) return {
+		offset: start,
+		length: end - start + 1
+	};
+	if (start !== void 0) return { offset: start };
+}
+function buildListObjectsV2Xml(bucketName, prefix, delimiter, maxKeys, result) {
+	const contents = result.objects.map((obj) => `<Contents><Key>${escapeXML(obj.key)}</Key><LastModified>${obj.uploaded.toISOString()}</LastModified><ETag>${escapeXML(obj.httpEtag)}</ETag><Size>${obj.size}</Size><StorageClass>STANDARD</StorageClass></Contents>`).join("");
+	const commonPrefixes = result.delimitedPrefixes.map((p) => `<CommonPrefixes><Prefix>${escapeXML(p)}</Prefix></CommonPrefixes>`).join("");
+	const nextToken = result.truncated && result.cursor ? `<NextContinuationToken>${escapeXML(result.cursor)}</NextContinuationToken>` : "";
+	const keyCount = result.objects.length + result.delimitedPrefixes.length;
+	return `<ListBucketResult ${XML_NS}><Name>${escapeXML(bucketName)}</Name><Prefix>${escapeXML(prefix)}</Prefix><KeyCount>${keyCount}</KeyCount><MaxKeys>${maxKeys}</MaxKeys>` + (delimiter ? `<Delimiter>${escapeXML(delimiter)}</Delimiter>` : "") + `<IsTruncated>${result.truncated}</IsTruncated>` + nextToken + contents + commonPrefixes + `</ListBucketResult>`;
+}
+function buildLocationXml() {
+	return `<LocationConstraint ${XML_NS}/>`;
+}
+function buildInitiateMultipartUploadXml(bucketName, key, uploadId) {
+	return `<InitiateMultipartUploadResult ${XML_NS}><Bucket>${escapeXML(bucketName)}</Bucket><Key>${escapeXML(key)}</Key><UploadId>${escapeXML(uploadId)}</UploadId></InitiateMultipartUploadResult>`;
+}
+function buildCompleteMultipartUploadXml(bucketName, key, etag) {
+	return `<CompleteMultipartUploadResult ${XML_NS}><Location>http://r2.internal/${escapeXML(bucketName)}/${escapeXML(key)}</Location><Bucket>${escapeXML(bucketName)}</Bucket><Key>${escapeXML(key)}</Key><ETag>${escapeXML(etag)}</ETag></CompleteMultipartUploadResult>`;
+}
+function buildCopyObjectXml(etag, uploaded) {
+	return `<CopyObjectResult ${XML_NS}><LastModified>${uploaded.toISOString()}</LastModified><ETag>${escapeXML(etag)}</ETag></CopyObjectResult>`;
+}
+function extractXmlTagContent(segment, tagName) {
+	const openTag = `<${tagName}>`;
+	const closeTag = `</${tagName}>`;
+	const start = segment.indexOf(openTag);
+	if (start === -1) return null;
+	const contentStart = start + openTag.length;
+	const end = segment.indexOf(closeTag, contentStart);
+	if (end === -1) return null;
+	return segment.slice(contentStart, end);
+}
+function parseCompleteMultipartUploadBody(body) {
+	const parts = [];
+	let pos = 0;
+	while (pos < body.length) {
+		const start = body.indexOf("<Part>", pos);
+		if (start === -1) break;
+		const end = body.indexOf("</Part>", start + 6);
+		if (end === -1) break;
+		const segment = body.slice(start, end + 7);
+		pos = end + 7;
+		const partNumberText = extractXmlTagContent(segment, "PartNumber");
+		const etagText = extractXmlTagContent(segment, "ETag");
+		const partNumber = partNumberText ? parseInt(partNumberText, 10) : NaN;
+		if (Number.isFinite(partNumber) && etagText) parts.push({
+			partNumber,
+			etag: etagText.replace(/^"|"$/g, "")
+		});
+	}
+	return parts;
+}
+function buildResponseHeaders(obj) {
+	const headers = new Headers();
+	headers.set("ETag", obj.httpEtag);
+	headers.set("Content-Length", String(obj.size));
+	headers.set("Last-Modified", obj.uploaded.toUTCString());
+	headers.set("Accept-Ranges", "bytes");
+	if (obj.httpMetadata?.contentType) headers.set("Content-Type", obj.httpMetadata.contentType);
+	if (obj.httpMetadata?.contentDisposition) headers.set("Content-Disposition", obj.httpMetadata.contentDisposition);
+	if (obj.httpMetadata?.contentEncoding) headers.set("Content-Encoding", obj.httpMetadata.contentEncoding);
+	if (obj.httpMetadata?.contentLanguage) headers.set("Content-Language", obj.httpMetadata.contentLanguage);
+	if (obj.httpMetadata?.cacheControl) headers.set("Cache-Control", obj.httpMetadata.cacheControl);
+	return headers;
+}
+function buildContentRange(range, totalSize) {
+	if ("suffix" in range) return `bytes ${Math.max(0, totalSize - range.suffix)}-${totalSize - 1}/${totalSize}`;
+	const start = range.offset ?? 0;
+	return `bytes ${start}-${range.length !== void 0 ? start + range.length - 1 : totalSize - 1}/${totalSize}`;
+}
+function getRangeContentLength(range, totalSize) {
+	if ("suffix" in range) return Math.min(range.suffix, totalSize);
+	const start = range.offset ?? 0;
+	if (start >= totalSize) return 0;
+	const requestedLength = range.length !== void 0 ? range.length : totalSize - start;
+	return Math.min(requestedLength, totalSize - start);
+}
+function extractHttpMetadata(request) {
+	const meta = {};
+	const ct = request.headers.get("Content-Type");
+	if (ct) meta.contentType = ct;
+	const cd = request.headers.get("Content-Disposition");
+	if (cd) meta.contentDisposition = cd;
+	const ce = request.headers.get("Content-Encoding");
+	if (ce) meta.contentEncoding = ce;
+	const cl = request.headers.get("Content-Language");
+	if (cl) meta.contentLanguage = cl;
+	const cc = request.headers.get("Cache-Control");
+	if (cc) meta.cacheControl = cc;
+	return meta;
+}
+function parseCopySource(header) {
+	const sourcePath = header.split("?")[0] ?? "";
+	if (!sourcePath) return null;
+	const decoded = decodeURIComponent(sourcePath);
+	const parsed = parsePath(decoded.startsWith("/") ? decoded : `/${decoded}`);
+	return parsed ? {
+		bucket: parsed.bucket,
+		key: normalizeObjectKey(parsed.key)
+	} : null;
+}
+function normalizeStorageClass(storageClass) {
+	if (storageClass === "Standard" || storageClass === "InfrequentAccess") return storageClass;
+}
+async function putRequestBody(r2, key, request, options) {
+	const contentLength = request.headers.get("Content-Length");
+	const length = contentLength ? Number.parseInt(contentLength, 10) : NaN;
+	if (!Number.isFinite(length) || length < 0) return new Response("Bad Request: missing or invalid Content-Length", { status: 400 });
+	if (length === 0) return r2.put(key, new Uint8Array(0), options);
+	if (!request.body) return new Response("Bad Request: missing request body", { status: 400 });
+	const { readable, writable } = new FixedLengthStream(length);
+	const pipe = request.body.pipeTo(writable);
+	const result = await r2.put(key, readable, options);
+	await pipe;
+	return result;
+}
+async function handleListObjects(r2, bucketName, url, mountPrefix) {
+	const queryPrefix = normalizeObjectKey(url.searchParams.get("prefix") ?? "");
+	const delimiter = url.searchParams.get("delimiter") ?? "";
+	const maxKeys = Math.min(parseInt(url.searchParams.get("max-keys") ?? "1000", 10) || 1e3, 1e3);
+	const continuationToken = url.searchParams.get("continuation-token") ?? void 0;
+	const listOpts = {
+		prefix: (mountPrefix ? `${mountPrefix}/${queryPrefix}` : queryPrefix) || void 0,
+		delimiter: delimiter || void 0,
+		limit: maxKeys,
+		cursor: continuationToken
+	};
+	const result = await r2.list(listOpts);
+	const stripKey = mountPrefix ? (k) => k.startsWith(`${mountPrefix}/`) ? k.slice(mountPrefix.length + 1) : k : (k) => k;
+	return xmlResponse(buildListObjectsV2Xml(bucketName, queryPrefix, delimiter, maxKeys, {
+		objects: result.objects.map((obj) => ({
+			key: stripKey(obj.key),
+			uploaded: obj.uploaded,
+			httpEtag: obj.httpEtag,
+			size: obj.size
+		})),
+		delimitedPrefixes: result.delimitedPrefixes.map(stripKey),
+		truncated: result.truncated,
+		cursor: result.truncated ? result.cursor : void 0
+	}));
+}
+async function handleHeadObject(r2, key) {
+	const obj = await r2.head(key);
+	if (!obj) return new Response(null, { status: 404 });
+	return new Response(null, {
+		status: 200,
+		headers: buildResponseHeaders(obj)
+	});
+}
+async function handleGetObject(r2, key, request) {
+	const range = parseRange(request.headers.get("Range"));
+	if (!range) {
+		const obj = await r2.get(key);
+		if (!obj) return new Response(null, { status: 404 });
+		return new Response(obj.body, {
+			status: 200,
+			headers: buildResponseHeaders(obj)
+		});
+	}
+	const [headObj, rangeObj] = await Promise.all([r2.head(key), r2.get(key, { range })]);
+	if (!headObj || !rangeObj) return new Response(null, { status: 404 });
+	const headers = buildResponseHeaders(rangeObj);
+	headers.set("Content-Range", buildContentRange(range, headObj.size));
+	headers.set("Content-Length", String(getRangeContentLength(range, headObj.size)));
+	return new Response(rangeObj.body, {
+		status: 206,
+		headers
+	});
+}
+async function handlePutObject(r2, bucketName, key, request, env$1, permitted, mountPrefix) {
+	const copySourceHeader = request.headers.get("x-amz-copy-source");
+	if (copySourceHeader) {
+		const copySource = parseCopySource(copySourceHeader);
+		if (!copySource || !copySource.key) return new Response("Bad Request: invalid x-amz-copy-source", { status: 400 });
+		if (!permitted.has(copySource.bucket)) return new Response(`Access to R2 bucket "${copySource.bucket}" is not permitted. Call mountBucket() with this bucket before accessing it.`, { status: 403 });
+		const sourceBucket = copySource.bucket === bucketName ? r2 : resolveR2Bucket(env$1, copySource.bucket);
+		if (!sourceBucket) return new Response(`R2 binding "${copySource.bucket}" not found in Worker env. Ensure the binding name matches the bucket name passed to mountBucket().`, { status: 500 });
+		const sourceKey = mountPrefix && copySource.bucket === bucketName ? `${mountPrefix}/${copySource.key}` : copySource.key;
+		const sourceObject = await sourceBucket.get(sourceKey);
+		if (!sourceObject) return new Response(null, { status: 404 });
+		const httpMetadata = request.headers.get("x-amz-metadata-directive")?.toUpperCase() === "REPLACE" ? extractHttpMetadata(request) : sourceObject.httpMetadata;
+		const result$1 = await r2.put(key, sourceObject.body, {
+			httpMetadata,
+			customMetadata: sourceObject.customMetadata,
+			storageClass: normalizeStorageClass(sourceObject.storageClass)
+		});
+		return xmlResponse(buildCopyObjectXml(result$1.httpEtag, result$1.uploaded));
+	}
+	const result = await putRequestBody(r2, key, request, { httpMetadata: extractHttpMetadata(request) });
+	if (result instanceof Response) return result;
+	const headers = new Headers();
+	headers.set("ETag", result.httpEtag);
+	return new Response(null, {
+		status: 200,
+		headers
+	});
+}
+async function handleDeleteObject(r2, key) {
+	await r2.delete(key);
+	return new Response(null, { status: 204 });
+}
+async function handleCreateMultipartUpload(r2, bucketName, key, request) {
+	const httpMetadata = extractHttpMetadata(request);
+	return xmlResponse(buildInitiateMultipartUploadXml(bucketName, key, (await r2.createMultipartUpload(key, { httpMetadata })).uploadId));
+}
+async function handleUploadPart(r2, key, url, request) {
+	const uploadId = url.searchParams.get("uploadId") ?? "";
+	const partNumber = parseInt(url.searchParams.get("partNumber") ?? "0", 10);
+	if (!uploadId || !partNumber) return new Response("Bad Request: missing uploadId or partNumber", { status: 400 });
+	if (!request.body) return new Response("Bad Request: missing request body", { status: 400 });
+	const contentLength = request.headers.get("Content-Length");
+	const partLength = contentLength ? Number.parseInt(contentLength, 10) : NaN;
+	if (!Number.isFinite(partLength) || partLength < 0) return new Response("Bad Request: missing or invalid Content-Length", { status: 400 });
+	const upload = r2.resumeMultipartUpload(key, uploadId);
+	let part;
+	if (partLength === 0) part = await upload.uploadPart(partNumber, new Uint8Array(0));
+	else {
+		const { readable, writable } = new FixedLengthStream(partLength);
+		const pipe = request.body.pipeTo(writable);
+		part = await upload.uploadPart(partNumber, readable);
+		await pipe;
+	}
+	const headers = new Headers();
+	headers.set("ETag", `"${part.etag}"`);
+	return new Response(null, {
+		status: 200,
+		headers
+	});
+}
+async function handleCompleteMultipartUpload(r2, bucketName, key, url, request) {
+	const uploadId = url.searchParams.get("uploadId") ?? "";
+	if (!uploadId) return new Response("Bad Request: missing uploadId", { status: 400 });
+	const r2Parts = parseCompleteMultipartUploadBody(await request.text()).map((p) => ({
+		partNumber: p.partNumber,
+		etag: p.etag
+	}));
+	return xmlResponse(buildCompleteMultipartUploadXml(bucketName, key, (await r2.resumeMultipartUpload(key, uploadId).complete(r2Parts)).httpEtag));
+}
+async function handleAbortMultipartUpload(r2, key, url) {
+	const uploadId = url.searchParams.get("uploadId") ?? "";
+	if (!uploadId) return new Response("Bad Request: missing uploadId", { status: 400 });
+	await r2.resumeMultipartUpload(key, uploadId).abort();
+	return new Response(null, { status: 204 });
+}
+const r2EgressHandler = async (request, env$1, ctx) => {
+	const url = new URL(request.url);
+	const parsed = parsePath(url.pathname);
+	if (!parsed) return new Response("Bad Request: empty path", { status: 400 });
+	const { bucket: bucketName, key } = parsed;
+	if (!ctx.params?.buckets || !(bucketName in ctx.params.buckets)) return new Response(`Access to R2 bucket "${bucketName}" is not permitted. Call mountBucket() with this bucket before accessing it.`, { status: 403 });
+	const bucketParams = ctx.params.buckets[bucketName];
+	const rawPrefix = bucketParams.prefix;
+	const mountPrefix = rawPrefix ? trimTrailingSlashes(normalizeObjectKey(rawPrefix)) : void 0;
+	const readOnly = bucketParams.readOnly ?? false;
+	const r2 = resolveR2Bucket(env$1, bucketName);
+	if (!r2) return new Response(`R2 binding "${bucketName}" not found in Worker env. Ensure the binding name matches the bucket name passed to mountBucket().`, { status: 500 });
+	const { method } = request;
+	if (!key) {
+		if (method === "GET" && url.searchParams.has("location")) return xmlResponse(buildLocationXml());
+		if (method === "GET" && url.searchParams.get("list-type") === "2") return handleListObjects(r2, bucketName, url, mountPrefix);
+		if (method === "GET") return handleListObjects(r2, bucketName, url, mountPrefix);
+		return new Response("Method Not Allowed", { status: 405 });
+	}
+	const fullKey = mountPrefix ? `${mountPrefix}/${key}` : key;
+	const permitted = new Set(Object.keys(ctx.params.buckets));
+	if (readOnly && (method === "PUT" || method === "DELETE" || method === "POST" && (url.searchParams.has("uploads") || url.searchParams.has("uploadId")))) return new Response("Forbidden: bucket mount is read-only", { status: 403 });
+	if (method === "POST" && url.searchParams.has("uploads")) return handleCreateMultipartUpload(r2, bucketName, fullKey, request);
+	if (method === "POST" && url.searchParams.has("uploadId")) return handleCompleteMultipartUpload(r2, bucketName, fullKey, url, request);
+	if (method === "PUT" && url.searchParams.has("partNumber") && url.searchParams.has("uploadId")) return handleUploadPart(r2, fullKey, url, request);
+	if (method === "DELETE" && url.searchParams.has("uploadId")) return handleAbortMultipartUpload(r2, fullKey, url);
+	switch (method) {
+		case "HEAD": return handleHeadObject(r2, fullKey);
+		case "GET": return handleGetObject(r2, fullKey, request);
+		case "PUT": return handlePutObject(r2, bucketName, fullKey, request, env$1, permitted, mountPrefix);
+		case "DELETE": return handleDeleteObject(r2, fullKey);
+		default: return new Response("Method Not Allowed", { status: 405 });
+	}
+};
+
+//#endregion
+//#region src/tunnels/sandbox-control-callback.ts
+var SandboxControlCallbackImpl = class extends RpcTarget {
+	constructor(getHandler, logger) {
+		super();
+		this.getHandler = getHandler;
+		this.logger = logger;
+	}
+	async onTunnelExit(id, port, exitCode) {
+		const handler = this.getHandler();
+		if (!handler) {
+			this.logger.debug("onTunnelExit: no handler bound; ignoring", {
+				id,
+				port,
+				exitCode
+			});
+			return;
+		}
+		await handler(id, port, exitCode);
+	}
+};
+
+//#endregion
+//#region src/tunnels/tunnels-handler.ts
+/**
+* Tunnels namespace handler. Created once per Sandbox DO instance via
+* `createTunnelsHandler(host)` and exposed as `sandbox.tunnels`.
+*
+* Storage is the source of truth. The DO holds a `Record<portString, TunnelInfo>`
+* under the `tunnels` storage key. `Sandbox.onStart()` clears the key on every
+* container restart so any record in storage is by construction backed by a
+* running `cloudflared` process; the handler never needs to verify that
+* separately against the container.
+*/
+/** DO storage key for the `port → TunnelInfo` map. */
+const STORAGE_KEY = "tunnels";
+function validateTunnelPort(port) {
+	if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding reserved ports.`);
+}
+/** 8-char hex id derived from `crypto.getRandomValues`. Unique per sandbox. */
+function shortId() {
+	const buf = new Uint8Array(4);
+	crypto.getRandomValues(buf);
+	return Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isTunnelNotFoundError(error) {
+	return (error instanceof Error ? error.message : String(error)).includes("TUNNEL_NOT_FOUND");
+}
+async function readMap(storage) {
+	return await storage.get(STORAGE_KEY) ?? {};
+}
+/**
+* Concrete `TunnelsHandler` implementation. Extends `RpcTarget` so it
+* can cross the Workers RPC boundary: the Sandbox DO is reachable from
+* Workers via Workers RPC (`stub.tunnels.get(port)`), and only
+* `RpcTarget` instances are passed by reference across that boundary.
+*/
+var TunnelsRpcTarget = class extends RpcTarget$1 {
+	#host;
+	#withPortLock;
+	constructor(host, withPortLock) {
+		super();
+		this.#host = host;
+		this.#withPortLock = withPortLock;
+	}
+	async get(port) {
+		const startTime = Date.now();
+		let outcome = "error";
+		let cacheState = "miss";
+		let caughtError;
+		try {
+			validateTunnelPort(port);
+			const info = await this.#withPortLock(port, async () => {
+				const existing = (await readMap(this.#host.storage))[port.toString()];
+				if (existing) {
+					cacheState = "hit";
+					return existing;
+				}
+				const id = `quick-${shortId()}`;
+				const spawned = await this.#host.client.tunnels.runQuickTunnel(id, port);
+				await this.#host.storage.transaction(async (txn) => {
+					const nextMap = await readMap(txn);
+					nextMap[port.toString()] = spawned;
+					await txn.put(STORAGE_KEY, nextMap);
+				});
+				return spawned;
+			});
+			outcome = "success";
+			return info;
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.#host.logger, {
+				event: "tunnel.get",
+				outcome,
+				port,
+				cacheState,
+				durationMs: Date.now() - startTime,
+				error: caughtError
+			});
+		}
+	}
+	async destroy(portOrInfo) {
+		const port = typeof portOrInfo === "number" ? portOrInfo : portOrInfo.port;
+		const startTime = Date.now();
+		let outcome = "error";
+		let caughtError;
+		let tunnelId;
+		try {
+			await this.#withPortLock(port, async () => {
+				const existing = (await readMap(this.#host.storage))[port.toString()];
+				if (!existing) return;
+				tunnelId = existing.id;
+				await this.#host.storage.transaction(async (txn) => {
+					const current = await readMap(txn);
+					delete current[port.toString()];
+					await txn.put(STORAGE_KEY, current);
+				});
+				try {
+					await this.#host.client.tunnels.destroyTunnel(existing.id);
+				} catch (error) {
+					if (!isTunnelNotFoundError(error)) throw error;
+				}
+			});
+			outcome = "success";
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.#host.logger, {
+				event: "tunnel.destroy",
+				outcome,
+				port,
+				tunnelId,
+				durationMs: Date.now() - startTime,
+				error: caughtError
+			});
+		}
+	}
+	async list() {
+		const map = await readMap(this.#host.storage);
+		return Object.values(map);
+	}
+};
+function createTunnelsHandler(host) {
+	const portLocks = /* @__PURE__ */ new Map();
+	const withPortLock = (port, fn) => {
+		const next = (portLocks.get(port) ?? Promise.resolve()).then(fn, fn);
+		portLocks.set(port, next.catch(() => void 0));
+		return next;
+	};
+	const tunnels = new TunnelsRpcTarget(host, withPortLock);
+	const handleTunnelExit = async (id, port, exitCode) => {
+		const startTime = Date.now();
+		await withPortLock(port, async () => {
+			await host.storage.transaction(async (txn) => {
+				const map = await readMap(txn);
+				if (map[port.toString()]?.id === id) {
+					delete map[port.toString()];
+					await txn.put(STORAGE_KEY, map);
+				}
+			});
+			logCanonicalEvent(host.logger, {
+				event: "tunnel.exit",
+				outcome: "success",
+				port,
+				tunnelId: id,
+				exitCode: exitCode ?? void 0,
+				durationMs: Date.now() - startTime
+			});
+		});
+	};
+	return {
+		tunnels,
+		handleTunnelExit
+	};
+}
+
 //#endregion
 //#region src/version.ts
 /**
@@ -4246,11 +4863,23 @@ function isLocalhostPattern(hostname) {
 * 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.10.1";
+const SDK_VERSION = "0.10.3";
 
 //#endregion
 //#region src/sandbox.ts
+const R2_EGRESS_PROXY_TARGET_CLASS_NAME = "CloudflareSandboxR2EgressProxyTarget";
+var R2EgressProxyTarget = class extends Container {};
+Object.defineProperty(R2EgressProxyTarget, "name", { value: R2_EGRESS_PROXY_TARGET_CLASS_NAME });
+R2EgressProxyTarget.outboundHandlers = { r2EgressMount: r2EgressHandler };
+function isFetcher(value) {
+	return typeof value === "object" && value !== null && "fetch" in value && typeof value.fetch === "function";
+}
 const sandboxConfigurationCache = /* @__PURE__ */ new WeakMap();
+const R2_DEFAULT_S3FS_OPTIONS = {
+	stat_cache_expire: "60",
+	enable_noobj_cache: true,
+	multipart_size: "5"
+};
 const BACKUP_DEFAULT_TTL_SECONDS = 259200;
 const BACKUP_MAX_NAME_LENGTH = 256;
 const BACKUP_CONTAINER_DIR = "/var/backups";
@@ -4383,19 +5012,72 @@ function getSandbox(ns, id, options) {
 		});
 	}
 	const defaultSessionId = `sandbox-${effectiveId}`;
+	const useDefaultSession = options?.enableDefaultSession !== false;
 	const enhancedMethods = {
 		fetch: (request) => stub.fetch(request),
+		exec: (command, execOptions) => useDefaultSession ? stub.exec(command, execOptions) : stub.execWithSessionToken(command, DISABLE_SESSION_TOKEN, execOptions),
+		startProcess: (command, processOptions) => useDefaultSession || processOptions?.sessionId !== void 0 ? stub.startProcess(command, processOptions) : stub.startProcess(command, {
+			...processOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		listProcesses: (sessionId) => useDefaultSession || sessionId !== void 0 ? stub.listProcesses(sessionId) : stub.listProcesses(DISABLE_SESSION_TOKEN),
+		getProcess: (id$1, sessionId) => useDefaultSession || sessionId !== void 0 ? stub.getProcess(id$1, sessionId) : stub.getProcess(id$1, DISABLE_SESSION_TOKEN),
+		execStream: (command, streamOptions) => {
+			if (useDefaultSession || streamOptions?.sessionId !== void 0) return stub.execStream(command, streamOptions);
+			return stub.execStreamWithSessionToken(command, DISABLE_SESSION_TOKEN, streamOptions);
+		},
+		writeFile: (path$1, content, fileOptions = {}) => useDefaultSession || fileOptions.sessionId !== void 0 ? stub.writeFile(path$1, content, fileOptions) : stub.writeFile(path$1, content, {
+			...fileOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		readFile: (path$1, fileOptions = {}) => {
+			const options$1 = useDefaultSession || fileOptions.sessionId !== void 0 ? fileOptions : {
+				...fileOptions,
+				sessionId: DISABLE_SESSION_TOKEN
+			};
+			if (options$1.encoding === "none") return stub.readFile(path$1, options$1);
+			return stub.readFile(path$1, options$1);
+		},
+		readFileStream: (path$1, fileOptions = {}) => useDefaultSession || fileOptions.sessionId !== void 0 ? stub.readFileStream(path$1, fileOptions) : stub.readFileStream(path$1, { sessionId: DISABLE_SESSION_TOKEN }),
+		mkdir: (path$1, mkdirOptions = {}) => useDefaultSession || mkdirOptions.sessionId !== void 0 ? stub.mkdir(path$1, mkdirOptions) : stub.mkdir(path$1, {
+			...mkdirOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		deleteFile: (path$1) => useDefaultSession ? stub.deleteFile(path$1) : stub.deleteFile(path$1, DISABLE_SESSION_TOKEN),
+		renameFile: (oldPath, newPath) => useDefaultSession ? stub.renameFile(oldPath, newPath) : stub.renameFile(oldPath, newPath, DISABLE_SESSION_TOKEN),
+		moveFile: (sourcePath, destinationPath) => useDefaultSession ? stub.moveFile(sourcePath, destinationPath) : stub.moveFile(sourcePath, destinationPath, DISABLE_SESSION_TOKEN),
+		listFiles: (path$1, listOptions) => useDefaultSession || listOptions?.sessionId !== void 0 ? stub.listFiles(path$1, listOptions) : stub.listFiles(path$1, {
+			...listOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		exists: (path$1, sessionId) => useDefaultSession || sessionId !== void 0 ? stub.exists(path$1, sessionId) : stub.exists(path$1, DISABLE_SESSION_TOKEN),
+		gitCheckout: (repoUrl, gitOptions) => useDefaultSession || gitOptions?.sessionId !== void 0 ? stub.gitCheckout(repoUrl, gitOptions) : stub.gitCheckout(repoUrl, {
+			...gitOptions,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
 		createSession: async (opts) => {
 			return enhanceSession(stub, await stub.createSession(opts));
 		},
 		getSession: async (sessionId) => {
 			return enhanceSession(stub, await stub.getSession(sessionId));
 		},
+		watch: (path$1, options$1 = {}) => useDefaultSession || options$1.sessionId !== void 0 ? stub.watch(path$1, options$1) : stub.watch(path$1, {
+			...options$1,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
+		checkChanges: (path$1, options$1 = {}) => useDefaultSession || options$1.sessionId !== void 0 ? stub.checkChanges(path$1, options$1) : stub.checkChanges(path$1, {
+			...options$1,
+			sessionId: DISABLE_SESSION_TOKEN
+		}),
 		terminal: (request, opts) => proxyTerminal(stub, defaultSessionId, request, opts),
 		wsConnect: connect(stub),
 		desktop: new Proxy({}, { get(_, method) {
 			if (typeof method !== "string" || method === "then") return void 0;
 			return (...args) => stub.callDesktop(method, args);
+		} }),
+		tunnels: new Proxy({}, { get: (_, method) => {
+			if (typeof method !== "string" || method === "then") return void 0;
+			return (...args) => stub.callTunnels(method, args);
 		} })
 	};
 	return new Proxy(stub, { get(target, prop) {
@@ -4416,19 +5098,15 @@ function connect(stub) {
 		return await stub.fetch(portSwitchedRequest);
 	};
 }
-/**
-* Type guard for R2Bucket binding.
-* Checks for the minimal R2Bucket interface methods we use.
-*/
-function isR2Bucket(value) {
-	return typeof value === "object" && value !== null && "put" in value && typeof value.put === "function" && "get" in value && typeof value.get === "function" && "head" in value && typeof value.head === "function" && "delete" in value && typeof value.delete === "function";
-}
 var Sandbox = class Sandbox extends Container {
 	defaultPort = 3e3;
 	sleepAfter = "10m";
 	client;
 	codeInterpreter;
 	sandboxName = null;
+	tunnelsHandler = null;
+	tunnelExitHandler = null;
+	controlCallback;
 	normalizeId = false;
 	defaultSession = null;
 	containerGeneration = 0;
@@ -4527,13 +5205,30 @@ var Sandbox = class Sandbox extends Container {
 	* 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.
+	* through property getters which is broken when using vite-plugin.
 	*/
 	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}`);
+		if (typeof fn !== "function") throw new Error(`sandbox.desktop missing method: ${method}`);
+		return fn.apply(client, args);
+	}
+	/**
+	* Dispatch method for tunnel operations.
+	* Called by the client-side proxy created in getSandbox() to provide
+	* the `sandbox.tunnels` API without relying on RPC pipelining
+	* through property getters which is broken when using vite-plugin.
+	*/
+	async callTunnels(method, args) {
+		if (![
+			"get",
+			"list",
+			"destroy"
+		].includes(method)) throw new Error(`Unknown tunnels method: ${method}`);
+		const client = this.tunnels;
+		const fn = client[method];
+		if (typeof fn !== "function") throw new Error(`sandbox.tunnels missing method: ${method}`);
 		return fn.apply(client, args);
 	}
 	/**
@@ -4579,6 +5274,7 @@ var Sandbox = class Sandbox extends Container {
 				port: 3e3,
 				logger: this.logger,
 				retryTimeoutMs: this.computeRetryTimeoutMs(),
+				localMain: this.controlCallback,
 				onActivity: () => {
 					this.renewActivityTimeout();
 				},
@@ -4593,9 +5289,9 @@ var Sandbox = class Sandbox extends Container {
 		}
 		return this.createSandboxClient();
 	}
-	constructor(ctx, env) {
-		super(ctx, env);
-		const envObj = env;
+	constructor(ctx, env$1) {
+		super(ctx, env$1);
+		const envObj = env$1;
 		["SANDBOX_LOG_LEVEL", "SANDBOX_LOG_FORMAT"].forEach((key) => {
 			if (envObj?.[key]) this.envVars[key] = String(envObj[key]);
 		});
@@ -4618,6 +5314,7 @@ var Sandbox = class Sandbox extends Container {
 			accessKeyId: this.r2AccessKeyId,
 			secretAccessKey: this.r2SecretAccessKey
 		});
+		this.controlCallback = new SandboxControlCallbackImpl(() => this.tunnelExitHandler, this.logger);
 		this.client = this.createClientForTransport(this.transport);
 		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 		this.ctx.blockConcurrencyWhile(async () => {
@@ -4645,6 +5342,8 @@ var Sandbox = class Sandbox extends Container {
 				const previousClient = this.client;
 				this.client = this.createClientForTransport(storedTransport);
 				this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
+				this.tunnelsHandler = null;
+				this.tunnelExitHandler = null;
 				previousClient.disconnect();
 			}
 			if (storedTransport) this.hasStoredTransport = true;
@@ -4700,13 +5399,6 @@ var Sandbox = class Sandbox extends Container {
 			}
 		}
 	}
-	/**
-	* RPC method to configure container startup timeouts. Idempotent once
-	* the values have been persisted: re-applying the same timeout set is a
-	* no-op. The transport retry budget is recomputed only when at least
-	* one timeout actually changes. Storage is written before the in-memory
-	* mirror and derived state are updated.
-	*/
 	async setContainerTimeouts(timeouts) {
 		const validated = { ...this.containerTimeouts };
 		if (timeouts.instanceGetTimeoutMS !== void 0) validated.instanceGetTimeoutMS = this.validateTimeout(timeouts.instanceGetTimeoutMS, "instanceGetTimeoutMS", 5e3, 3e5);
@@ -4719,11 +5411,6 @@ var Sandbox = class Sandbox extends Container {
 		this.client.setRetryTimeoutMs(this.computeRetryTimeoutMs());
 		this.logger.debug("Container timeouts updated", this.containerTimeouts);
 	}
-	/**
-	* RPC method to set the transport protocol. Idempotent once the value
-	* has been persisted: re-applying the same transport is a no-op.
-	* Storage is written before the in-memory state and client are updated.
-	*/
 	async setTransport(transport) {
 		if (transport !== "http" && transport !== "websocket" && transport !== "rpc") {
 			this.logger.warn(`Invalid transport value: "${transport}". Must be "http", "websocket", or "rpc". Ignoring.`);
@@ -4736,24 +5423,18 @@ var Sandbox = class Sandbox extends Container {
 		this.hasStoredTransport = true;
 		this.client = this.createClientForTransport(transport);
 		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
+		this.tunnelsHandler = null;
+		this.tunnelExitHandler = null;
 		previousClient.disconnect();
 		this.renewActivityTimeout();
 		this.logger.debug("Transport updated", { transport });
 	}
-	/**
-	* Validate a timeout value is within acceptable range
-	* Throws error if invalid - used for user-provided values
-	*/
 	validateTimeout(value, name, min, max) {
 		if (typeof value !== "number" || Number.isNaN(value) || !Number.isFinite(value)) throw new Error(`${name} must be a valid finite number, got ${value}`);
 		if (value < min || value > max) throw new Error(`${name} must be between ${min}-${max}ms, got ${value}ms`);
 		return value;
 	}
-	/**
-	* Get default timeouts with env var fallbacks and validation
-	* Precedence: SDK defaults < Env vars < User config
-	*/
-	getDefaultTimeouts(env) {
+	getDefaultTimeouts(env$1) {
 		const parseAndValidate = (envVar, name, min, max) => {
 			const defaultValue = this.DEFAULT_CONTAINER_TIMEOUTS[name];
 			if (envVar === void 0) return defaultValue;
@@ -4769,9 +5450,9 @@ var Sandbox = class Sandbox extends Container {
 			return parsed;
 		};
 		return {
-			instanceGetTimeoutMS: parseAndValidate(getEnvString(env, "SANDBOX_INSTANCE_TIMEOUT_MS"), "instanceGetTimeoutMS", 5e3, 3e5),
-			portReadyTimeoutMS: parseAndValidate(getEnvString(env, "SANDBOX_PORT_TIMEOUT_MS"), "portReadyTimeoutMS", 1e4, 6e5),
-			waitIntervalMS: parseAndValidate(getEnvString(env, "SANDBOX_POLL_INTERVAL_MS"), "waitIntervalMS", 100, 5e3)
+			instanceGetTimeoutMS: parseAndValidate(getEnvString(env$1, "SANDBOX_INSTANCE_TIMEOUT_MS"), "instanceGetTimeoutMS", 5e3, 3e5),
+			portReadyTimeoutMS: parseAndValidate(getEnvString(env$1, "SANDBOX_PORT_TIMEOUT_MS"), "portReadyTimeoutMS", 1e4, 6e5),
+			waitIntervalMS: parseAndValidate(getEnvString(env$1, "SANDBOX_POLL_INTERVAL_MS"), "waitIntervalMS", 100, 5e3)
 		};
 	}
 	/**
@@ -4793,7 +5474,16 @@ var Sandbox = class Sandbox extends Container {
 			await this.mountBucketLocal(bucket, mountPath, options);
 			return;
 		}
-		await this.mountBucketFuse(bucket, mountPath, options);
+		const remoteOptions = options;
+		if (remoteOptions.endpoint === void 0) {
+			const binding = this.env[bucket];
+			if (isR2Bucket(binding)) {
+				await this.mountBucketR2Egress(bucket, mountPath, options);
+				return;
+			}
+			throw new InvalidMountConfigError(`R2 binding "${bucket}" not found in Worker env. Ensure the binding name matches the bucket binding configured in wrangler.jsonc.`);
+		}
+		await this.mountBucketFuse(bucket, mountPath, remoteOptions);
 	}
 	/**
 	* Local dev mount: bidirectional sync via R2 binding + file/watch APIs
@@ -4850,12 +5540,109 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
+	getR2EgressParams() {
+		const buckets = {};
+		for (const [, m] of this.activeMounts) if (m.mountType === "r2-egress") buckets[m.bucket] = {
+			prefix: m.prefix,
+			readOnly: m.readOnly
+		};
+		return { buckets };
+	}
+	validateR2EgressS3fsOptions(options) {
+		if (!options) return;
+		const protectedOptions = new Set(["passwd_file", "url"]);
+		for (const option of options) {
+			const [key] = option.split("=");
+			if (protectedOptions.has(key)) throw new InvalidMountConfigError(`s3fs option "${key}" cannot be overridden for R2 binding mounts`);
+		}
+	}
+	/**
+	* Credential-less R2 mount: egress interception routes s3fs requests to the
+	* R2 binding. No S3 credentials are needed in the container or Worker env.
+	*/
+	async mountBucketR2Egress(bucket, mountPath, options) {
+		const mountStartTime = Date.now();
+		const prefix = options.prefix;
+		let mountOutcome = "error";
+		let mountError;
+		try {
+			validateBucketBindingName(bucket, mountPath);
+			this.validateMountPath(mountPath);
+			this.validateR2EgressS3fsOptions(options.s3fsOptions);
+			for (const [existingMountPath, mountInfo$1] of this.activeMounts) {
+				if (mountInfo$1.mountType === "r2-egress" && mountInfo$1.bucket === bucket && mountInfo$1.prefix !== prefix) throw new InvalidMountConfigError(`R2 binding "${bucket}" is already mounted at ${existingMountPath} with a different prefix. Mount the same binding only once, or use the same prefix for additional mounts.`);
+				if (mountInfo$1.mountType === "r2-egress" && mountInfo$1.bucket === bucket && mountInfo$1.readOnly !== (options.readOnly ?? false)) throw new InvalidMountConfigError(`R2 binding "${bucket}" is already mounted at ${existingMountPath} with a different readOnly setting. Mount the same binding only once, or use the same readOnly value for additional mounts.`);
+			}
+			const passwordFilePath = this.generatePasswordFilePath();
+			await this.createPasswordFile(passwordFilePath, bucket, {
+				accessKeyId: "x",
+				secretAccessKey: "x"
+			});
+			const mountInfo = {
+				mountType: "r2-egress",
+				bucket,
+				mountPath,
+				passwordFilePath,
+				mounted: false,
+				prefix,
+				readOnly: options.readOnly ?? false
+			};
+			this.activeMounts.set(mountPath, mountInfo);
+			await this.configureR2EgressOutbound(this.getR2EgressParams());
+			await this.execInternal(`mkdir -p ${shellEscape(mountPath)}`);
+			const s3fsSource = bucket;
+			const optionsStr = shellEscape(serializeS3fsOptions({
+				passwd_file: passwordFilePath,
+				...R2_DEFAULT_S3FS_OPTIONS,
+				...parseS3fsOptions(resolveS3fsOptions("r2", options.s3fsOptions)),
+				use_path_request_style: true,
+				url: "http://r2.internal",
+				...options.readOnly ? { ro: true } : {}
+			}));
+			const mountCmd = `s3fs ${shellEscape(s3fsSource)} ${shellEscape(mountPath)} -o ${optionsStr}`;
+			this.logger.debug("r2-egress: running s3fs", { mountCmd });
+			const result = await this.execInternal(mountCmd);
+			this.logger.debug("r2-egress: s3fs exited", {
+				exitCode: result.exitCode,
+				stdout: result.stdout,
+				stderr: result.stderr
+			});
+			if (result.exitCode !== 0) throw new S3FSMountError(`S3FS mount failed: ${result.stderr || result.stdout || "Unknown error"}`);
+			const mountpointCheck = await this.execInternal(`mountpoint -q ${shellEscape(mountPath)} && echo 'FUSE_MOUNTED' || echo 'NOT_FUSE_MOUNTED'`);
+			this.logger.debug("r2-egress: mountpoint check", {
+				stdout: mountpointCheck.stdout.trim(),
+				exitCode: mountpointCheck.exitCode
+			});
+			if (mountpointCheck.stdout.trim() !== "FUSE_MOUNTED") throw new S3FSMountError(`s3fs exited 0 but mount was not established at ${mountPath}`);
+			mountInfo.mounted = true;
+			mountOutcome = "success";
+		} catch (error) {
+			mountError = error instanceof Error ? error : new Error(String(error));
+			const failedMount = this.activeMounts.get(mountPath);
+			this.activeMounts.delete(mountPath);
+			if (failedMount?.mountType === "r2-egress") await this.deletePasswordFile(failedMount.passwordFilePath).catch(() => {});
+			const remainingParams = this.getR2EgressParams();
+			await this.configureR2EgressOutbound(remainingParams).catch(() => {});
+			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "bucket.mount",
+				outcome: mountOutcome,
+				durationMs: Date.now() - mountStartTime,
+				bucket,
+				mountPath,
+				provider: "r2",
+				prefix,
+				error: mountError
+			});
+		}
+	}
 	/**
 	* Production mount: S3FS-FUSE inside the container
 	*/
 	async mountBucketFuse(bucket, mountPath, options) {
 		const mountStartTime = Date.now();
-		const prefix = options.prefix || void 0;
+		const prefix = options.prefix;
 		let mountOutcome = "error";
 		let mountError;
 		let passwordFilePath;
@@ -4946,6 +5733,7 @@ var Sandbox = class Sandbox extends Container {
 				}
 				mountInfo.mounted = false;
 				this.activeMounts.delete(mountPath);
+				if (mountInfo.mountType === "r2-egress") await this.configureR2EgressOutbound(this.getR2EgressParams());
 				try {
 					const cleanup = await this.execInternal(`mountpoint -q ${shellEscape(mountPath)} || rmdir ${shellEscape(mountPath)}`);
 					if (cleanup.exitCode !== 0) this.logger.warn("mount directory removal failed", {
@@ -4978,7 +5766,14 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	/**
-	* Validate mount options
+	* Shared validation for mount path (absolute, not already in use).
+	*/
+	validateMountPath(mountPath) {
+		if (!mountPath.startsWith("/")) throw new InvalidMountConfigError(`Mount path must be absolute (start with /): "${mountPath}"`);
+		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path "${mountPath}" is already in use by bucket "${this.activeMounts.get(mountPath)?.bucket}". Unmount the existing bucket first or use a different mount path.`);
+	}
+	/**
+	* Validate mount options for remote (FUSE) mounts
 	*/
 	validateMountOptions(bucket, mountPath, options) {
 		try {
@@ -4987,8 +5782,7 @@ var Sandbox = class Sandbox extends Container {
 			throw new InvalidMountConfigError(`Invalid endpoint URL: "${options.endpoint}". Must be a valid HTTP(S) URL.`);
 		}
 		validateBucketName(bucket, mountPath);
-		if (!mountPath.startsWith("/")) throw new InvalidMountConfigError(`Mount path must be absolute (start with /): "${mountPath}"`);
-		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path "${mountPath}" is already in use by bucket "${this.activeMounts.get(mountPath)?.bucket}". Unmount the existing bucket first or use a different mount path.`);
+		this.validateMountPath(mountPath);
 	}
 	/**
 	* Generate unique password file path for s3fs credentials
@@ -5002,7 +5796,7 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async createPasswordFile(passwordFilePath, bucket, credentials) {
 		const content = `${bucket}:${credentials.accessKeyId}:${credentials.secretAccessKey}`;
-		await this.writeFile(passwordFilePath, content);
+		await this.client.files.writeFile(passwordFilePath, content, DISABLE_SESSION_TOKEN);
 		await this.execInternal(`chmod 0600 ${shellEscape(passwordFilePath)}`);
 	}
 	/**
@@ -5048,6 +5842,13 @@ var Sandbox = class Sandbox extends Container {
 		if (result.exitCode === 2) throw new S3FSMountError(`S3FS mount failed: ${detail || "Unknown error"}`);
 		throw new S3FSMountError(`S3FS mount failed: FUSE filesystem never appeared at ${mountPath}. ${detail ? `s3fs log: ${detail}` : "No s3fs log output captured. The s3fs daemon may have exited before writing logs."}`);
 	}
+	async unmountTrackedFuseMount(mountPath, mountInfo) {
+		if (!mountInfo.mounted) return;
+		this.logger.debug(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
+		const result = await this.execInternal(`fusermount -u ${shellEscape(mountPath)}`);
+		if (result.exitCode !== 0) throw new Error(`fusermount -u failed (exit ${result.exitCode}): ${result.stderr || "unknown error"}`);
+		mountInfo.mounted = false;
+	}
 	/**
 	* In-flight `destroy()` promise. While set, concurrent callers coalesce
 	* onto the same teardown instead of triggering a second one. Cleared when
@@ -5109,10 +5910,8 @@ var Sandbox = class Sandbox extends Container {
 					this.logger.warn(`Failed to stop local sync for ${mountPath}: ${errorMsg}`);
 				}
 				else {
-					if (mountInfo.mounted) try {
-						this.logger.debug(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
-						await this.execInternal(`fusermount -u ${shellEscape(mountPath)}`);
-						mountInfo.mounted = false;
+					try {
+						await this.unmountTrackedFuseMount(mountPath, mountInfo);
 					} catch (error) {
 						mountFailures++;
 						const errorMsg = error instanceof Error ? error.message : String(error);
@@ -5122,6 +5921,7 @@ var Sandbox = class Sandbox extends Container {
 				}
 			}
 			await this.ctx.storage.delete("portTokens");
+			await this.ctx.storage.delete("tunnels");
 			this.client.disconnect();
 			outcome = "success";
 			await super.destroy();
@@ -5149,6 +5949,11 @@ var Sandbox = class Sandbox extends Container {
 		} catch (error) {
 			this.logger.error("Failed to restore exposed ports after container start", error instanceof Error ? error : new Error(String(error)));
 		}
+		try {
+			await this.ctx.storage.delete("tunnels");
+		} catch (error) {
+			this.logger.error("Failed to clear tunnel storage after container start", error instanceof Error ? error : new Error(String(error)));
+		}
 	}
 	/**
 	* Re-expose ports on the container runtime using tokens persisted in DO
@@ -5169,8 +5974,7 @@ var Sandbox = class Sandbox extends Container {
 		let restored = 0;
 		let skipped = 0;
 		let failed = 0;
-		const sessionId = await this.ensureDefaultSession();
-		const exposedSet = await this.client.ports.getExposedPorts(sessionId).then((response) => new Set(response.ports.map((p) => p.port))).catch((error) => {
+		const exposedSet = await this.client.ports.getExposedPorts(DISABLE_SESSION_TOKEN).then((response) => new Set(response.ports.map((p) => p.port))).catch((error) => {
 			this.logger.warn("Failed to fetch exposed ports for restore; assuming none exposed", { error: error instanceof Error ? error.message : String(error) });
 			return /* @__PURE__ */ new Set();
 		});
@@ -5186,7 +5990,7 @@ var Sandbox = class Sandbox extends Container {
 				continue;
 			}
 			try {
-				await this.client.ports.exposePort(port, sessionId, entry.name);
+				await this.client.ports.exposePort(port, DISABLE_SESSION_TOKEN, entry.name);
 				restored++;
 			} catch (error) {
 				failed++;
@@ -5251,7 +6055,10 @@ var Sandbox = class Sandbox extends Container {
 		this.defaultSession = null;
 		this.defaultSessionInit = null;
 		this.client.disconnect();
+		let hadR2EgressMount = false;
 		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
+		else if (m.mountType === "r2-egress") hadR2EgressMount = true;
+		if (hadR2EgressMount) await this.configureR2EgressOutbound({ buckets: {} }).catch(() => {});
 		this.activeMounts.clear();
 		await this.ctx.storage.delete("defaultSession");
 	}
@@ -5566,10 +6373,78 @@ var Sandbox = class Sandbox extends Container {
 		if (containerPlacementId === void 0) return;
 		await this.ctx.storage.put("containerPlacementId", containerPlacementId);
 	}
+	async resolveExecution(explicitSessionId) {
+		if (explicitSessionId !== void 0) {
+			this.validateExplicitSessionId(explicitSessionId);
+			if (explicitSessionId === DISABLE_SESSION_TOKEN) return { kind: "sessionless" };
+			return {
+				kind: "session",
+				sessionId: explicitSessionId
+			};
+		}
+		return {
+			kind: "session",
+			sessionId: await this.ensureDefaultSession()
+		};
+	}
+	validateExplicitSessionId(sessionId) {
+		if (sessionId.trim().length === 0) throw new Error("sessionId must not be empty or whitespace");
+	}
+	serializeExecutionContext(context) {
+		if (context.kind === "sessionless") return DISABLE_SESSION_TOKEN;
+		return context.sessionId;
+	}
+	getPublicExecutionSessionId(sessionId) {
+		return sessionId === DISABLE_SESSION_TOKEN ? void 0 : sessionId;
+	}
+	/**
+	* Resolves the session ID to annotate returned Process objects.
+	*
+	* Unlike `resolveExecution`, this is synchronous and never creates a
+	* session. When the default session hasn't been established yet, it returns
+	* `undefined` rather than triggering session creation. The resolved value is
+	* only used to populate `Process.sessionId` on the returned object — it is
+	* never sent to the container API.
+	*/
+	getProcessSessionBinding(explicitSessionId) {
+		if (explicitSessionId !== void 0) {
+			this.validateExplicitSessionId(explicitSessionId);
+			if (explicitSessionId === DISABLE_SESSION_TOKEN) return;
+			return explicitSessionId;
+		}
+		return this.defaultSession ?? void 0;
+	}
+	resolveExecutionEnv(sessionId, env$1) {
+		if (sessionId === DISABLE_SESSION_TOKEN) {
+			const mergedEnv = filterEnvVars({
+				...this.envVars,
+				...env$1 ?? {}
+			});
+			return Object.keys(mergedEnv).length > 0 ? mergedEnv : void 0;
+		}
+		if (env$1 === void 0) return;
+		const filteredEnv = filterEnvVars(env$1);
+		return Object.keys(filteredEnv).length > 0 ? filteredEnv : void 0;
+	}
+	buildExecutionRequestOptions(sessionId, options) {
+		const env$1 = this.resolveExecutionEnv(sessionId, options?.env);
+		if (options?.timeout === void 0 && env$1 === void 0 && options?.cwd === void 0 && options?.origin === void 0) return;
+		return {
+			...options?.timeout !== void 0 && { timeoutMs: options.timeout },
+			...env$1 !== void 0 && { env: env$1 },
+			...options?.cwd !== void 0 && { cwd: options.cwd },
+			...options?.origin !== void 0 && { origin: options.origin }
+		};
+	}
 	async exec(command, options) {
-		const session = await this.ensureDefaultSession();
+		const context = await this.resolveExecution();
+		const session = this.serializeExecutionContext(context);
 		return this.execWithSession(command, session, options);
 	}
+	async execWithSessionToken(command, sessionId, options) {
+		this.validateExplicitSessionId(sessionId);
+		return this.execWithSession(command, sessionId, options);
+	}
 	/**
 	* Execute an infrastructure command (backup, mount, env setup, etc.)
 	* tagged with origin: 'internal' so logging demotes it to debug level.
@@ -5592,15 +6467,11 @@ var Sandbox = class Sandbox extends Container {
 			let result;
 			if (options?.stream && options?.onOutput) result = await this.executeWithStreaming(command, sessionId, options, startTime, timestamp);
 			else {
-				const commandOptions = options && (options.timeout !== void 0 || options.env !== void 0 || options.cwd !== void 0 || options.origin !== void 0) ? {
-					timeoutMs: options.timeout,
-					env: options.env,
-					cwd: options.cwd,
-					origin: options.origin
-				} : void 0;
+				const commandOptions = this.buildExecutionRequestOptions(sessionId, options);
 				const response = await this.client.commands.execute(command, sessionId, commandOptions);
 				const duration = Date.now() - startTime;
-				result = this.mapExecuteResponseToExecResult(response, duration, sessionId);
+				const publicSessionId = this.getPublicExecutionSessionId(sessionId);
+				result = this.mapExecuteResponseToExecResult(response, duration, publicSessionId);
 			}
 			execOutcome = {
 				exitCode: result.exitCode,
@@ -5619,7 +6490,7 @@ var Sandbox = class Sandbox extends Container {
 				command,
 				exitCode: execOutcome?.exitCode,
 				durationMs: Date.now() - startTime,
-				sessionId,
+				sessionId: this.getPublicExecutionSessionId(sessionId),
 				origin: options?.origin ?? "user",
 				error: execError ?? void 0,
 				errorMessage: execError?.message
@@ -5630,12 +6501,8 @@ var Sandbox = class Sandbox extends Container {
 		let stdout = "";
 		let stderr = "";
 		try {
-			const stream = await this.client.commands.executeStream(command, sessionId, {
-				timeoutMs: options.timeout,
-				env: options.env,
-				cwd: options.cwd,
-				origin: options.origin
-			});
+			const commandOptions = this.buildExecutionRequestOptions(sessionId, options);
+			const stream = await this.client.commands.executeStream(command, sessionId, commandOptions);
 			for await (const event of parseSSEStream(stream)) {
 				if (options.signal?.aborted) throw new Error("Operation was aborted");
 				switch (event.type) {
@@ -5657,7 +6524,7 @@ var Sandbox = class Sandbox extends Container {
 							command,
 							duration,
 							timestamp,
-							sessionId
+							sessionId: this.getPublicExecutionSessionId(sessionId)
 						};
 					}
 					case "error": throw new Error(event.data || "Command execution failed");
@@ -5933,12 +6800,16 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async startProcess(command, options, sessionId) {
 		try {
-			const session = sessionId ?? await this.ensureDefaultSession();
+			const execution = await this.resolveExecution(sessionId);
+			const session = this.serializeExecutionContext(execution);
+			const processSession = this.getProcessSessionBinding(session);
 			const requestOptions = {
+				...this.buildExecutionRequestOptions(session, {
+					timeout: options?.timeout,
+					env: options?.env,
+					cwd: options?.cwd
+				}),
 				...options?.processId !== void 0 && { processId: options.processId },
-				...options?.timeout !== void 0 && { timeoutMs: options.timeout },
-				...options?.env !== void 0 && { env: filterEnvVars(options.env) },
-				...options?.cwd !== void 0 && { cwd: options.cwd },
 				...options?.encoding !== void 0 && { encoding: options.encoding },
 				...options?.autoCleanup !== void 0 && { autoCleanup: options.autoCleanup }
 			};
@@ -5951,7 +6822,7 @@ var Sandbox = class Sandbox extends Container {
 				startTime: /* @__PURE__ */ new Date(),
 				endTime: void 0,
 				exitCode: void 0
-			}, session);
+			}, processSession);
 			if (options?.onStart) options.onStart(processObj);
 			if (options?.onOutput || options?.onExit) this.startProcessCallbackStream(response.processId, options).catch(() => {});
 			return processObj;
@@ -5979,13 +6850,14 @@ var Sandbox = class Sandbox extends Container {
 					if (options.onExit) options.onExit(event.exitCode ?? null);
 					return;
 			}
+			throw new Error("Stream ended without completion event");
 		} catch (error) {
 			if (options.onError && error instanceof Error) options.onError(error);
 			this.logger.error("Background process streaming failed", error instanceof Error ? error : new Error(String(error)), { processId });
 		}
 	}
 	async listProcesses(sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const session = this.getProcessSessionBinding(sessionId);
 		return (await this.client.processes.listProcesses()).processes.map((processData) => this.createProcessFromDTO({
 			id: processData.id,
 			pid: processData.pid,
@@ -5997,19 +6869,24 @@ var Sandbox = class Sandbox extends Container {
 		}, session));
 	}
 	async getProcess(id, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
-		const response = await this.client.processes.getProcess(id);
-		if (!response.process) return null;
-		const processData = response.process;
-		return this.createProcessFromDTO({
-			id: processData.id,
-			pid: processData.pid,
-			command: processData.command,
-			status: processData.status,
-			startTime: processData.startTime,
-			endTime: processData.endTime,
-			exitCode: processData.exitCode
-		}, session);
+		const session = this.getProcessSessionBinding(sessionId);
+		try {
+			const response = await this.client.processes.getProcess(id);
+			if (!response.process) return null;
+			const processData = response.process;
+			return this.createProcessFromDTO({
+				id: processData.id,
+				pid: processData.pid,
+				command: processData.command,
+				status: processData.status,
+				startTime: processData.startTime,
+				endTime: processData.endTime,
+				exitCode: processData.exitCode
+			}, session);
+		} catch (error) {
+			if (error instanceof ProcessNotFoundError) return null;
+			throw error;
+		}
 	}
 	async killProcess(id, signal, sessionId) {
 		await this.client.processes.killProcess(id);
@@ -6030,23 +6907,29 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async execStream(command, options) {
 		if (options?.signal?.aborted) throw new Error("Operation was aborted");
-		const session = await this.ensureDefaultSession();
-		return this.client.commands.executeStream(command, session, {
-			timeoutMs: options?.timeout,
+		const context = await this.resolveExecution(options?.sessionId);
+		const session = this.serializeExecutionContext(context);
+		const executionOptions = this.buildExecutionRequestOptions(session, {
+			timeout: options?.timeout,
 			env: options?.env,
 			cwd: options?.cwd
 		});
+		return this.client.commands.executeStream(command, session, executionOptions);
+	}
+	async execStreamWithSessionToken(command, sessionId, options) {
+		this.validateExplicitSessionId(sessionId);
+		return this.execStreamWithSession(command, sessionId, options);
 	}
 	/**
 	* Internal session-aware execStream implementation
 	*/
 	async execStreamWithSession(command, sessionId, options) {
 		if (options?.signal?.aborted) throw new Error("Operation was aborted");
-		return this.client.commands.executeStream(command, sessionId, {
-			timeoutMs: options?.timeout,
+		return this.client.commands.executeStream(command, sessionId, this.buildExecutionRequestOptions(sessionId, {
+			timeout: options?.timeout,
 			env: options?.env,
 			cwd: options?.cwd
-		});
+		}));
 	}
 	/**
 	* Stream logs from a background process as a ReadableStream.
@@ -6056,7 +6939,8 @@ var Sandbox = class Sandbox extends Container {
 		return this.client.processes.streamProcessLogs(processId);
 	}
 	async gitCheckout(repoUrl, options) {
-		const session = options?.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options?.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.git.checkout(repoUrl, session, {
 			branch: options?.branch,
 			targetDir: options?.targetDir,
@@ -6065,28 +6949,34 @@ var Sandbox = class Sandbox extends Container {
 		});
 	}
 	async mkdir(path$1, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.mkdir(path$1, session, { recursive: options.recursive });
 	}
 	async writeFile(path$1, content, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		if (content instanceof ReadableStream) return this.client.files.writeFileStream(path$1, content, session);
 		return this.client.files.writeFile(path$1, content, session, { encoding: options.encoding });
 	}
 	async deleteFile(path$1, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.deleteFile(path$1, session);
 	}
 	async renameFile(oldPath, newPath, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.renameFile(oldPath, newPath, session);
 	}
 	async moveFile(sourcePath, destinationPath, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.moveFile(sourcePath, destinationPath, session);
 	}
 	async readFile(path$1, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		if (options.encoding === "none") return this.client.files.readFile(path$1, session, { encoding: "none" });
 		return this.client.files.readFile(path$1, session, { encoding: options.encoding });
 	}
@@ -6097,15 +6987,18 @@ var Sandbox = class Sandbox extends Container {
 	* @param options - Optional session ID
 	*/
 	async readFileStream(path$1, options = {}) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.readFileStream(path$1, session);
 	}
 	async listFiles(path$1, options) {
-		const session = await this.ensureDefaultSession();
+		const context = await this.resolveExecution(options?.sessionId);
+		const session = this.serializeExecutionContext(context);
 		return this.client.files.listFiles(path$1, session, options);
 	}
 	async exists(path$1, sessionId) {
-		const session = sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(sessionId);
+		const session = this.serializeExecutionContext(execution);
 		return this.client.files.exists(path$1, session);
 	}
 	/**
@@ -6156,7 +7049,8 @@ var Sandbox = class Sandbox extends Container {
 	* @param options - Watch options
 	*/
 	async watch(path$1, options = {}) {
-		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const sessionId = this.serializeExecutionContext(execution);
 		return this.client.watch.watch({
 			path: path$1,
 			recursive: options.recursive,
@@ -6176,7 +7070,8 @@ var Sandbox = class Sandbox extends Container {
 	* @param options - Change-check options
 	*/
 	async checkChanges(path$1, options = {}) {
-		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
+		const execution = await this.resolveExecution(options.sessionId);
+		const sessionId = this.serializeExecutionContext(execution);
 		return this.client.watch.checkChanges({
 			path: path$1,
 			recursive: options.recursive,
@@ -6238,7 +7133,7 @@ var Sandbox = class Sandbox extends Container {
 			const tokens = await this.readPortTokens();
 			const existingPort = Object.entries(tokens).find(([p, entry]) => entry.token === token && p !== port.toString());
 			if (existingPort) throw new SandboxSecurityError(`Token '${token}' is already in use by port ${existingPort[0]}. Please use a different token.`);
-			const sessionId = await this.ensureDefaultSession();
+			const sessionId = this.serializeExecutionContext(await this.resolveExecution());
 			await this.client.ports.exposePort(port, sessionId, options?.name);
 			tokens[port.toString()] = {
 				token,
@@ -6278,7 +7173,7 @@ var Sandbox = class Sandbox extends Container {
 				delete tokens[port.toString()];
 				await this.ctx.storage.put("portTokens", tokens);
 			}
-			const sessionId = await this.ensureDefaultSession();
+			const sessionId = this.serializeExecutionContext(await this.resolveExecution());
 			try {
 				await this.client.ports.unexposePort(port, sessionId);
 			} catch (error) {
@@ -6299,7 +7194,7 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	async getExposedPorts(hostname) {
-		const sessionId = await this.ensureDefaultSession();
+		const sessionId = this.serializeExecutionContext(await this.resolveExecution());
 		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.readPortTokens();
@@ -6316,9 +7211,48 @@ var Sandbox = class Sandbox extends Container {
 			}];
 		});
 	}
+	/**
+	* Namespaced tunnel API. Quick tunnels are zero-config preview URLs
+	* backed by Cloudflare's trycloudflare service.
+	*
+	* - `tunnels.get(port)` — idempotent. Returns the cached tunnel for
+	*   `port` if one exists in DO storage, otherwise spawns a fresh
+	*   cloudflared process and persists the record.
+	* - `tunnels.list()` — records currently known to this sandbox, from
+	*   DO storage.
+	* - `tunnels.destroy(portOrInfo)` — tear down by port number or by
+	*   the record returned from `get()`.
+	*
+	* Storage is cleared on container restart (`onStart`), so URLs do
+	* not survive a container restart — the next `get(port)` call will
+	* spawn a fresh tunnel with a new URL.
+	*
+	* Requires the RPC transport. Calling this on a route-based transport
+	* throws "RPC transport required".
+	*/
+	get tunnels() {
+		this.ensureTunnelsBuilt();
+		return this.tunnelsHandler;
+	}
+	/**
+	* Lazily construct both the public tunnels handler and its sibling
+	* exit-handler callback. Called from the `tunnels` getter on first
+	* access and on every access after a transport swap clears both
+	* fields.
+	*/
+	ensureTunnelsBuilt() {
+		if (this.tunnelsHandler) return;
+		const built = createTunnelsHandler({
+			client: this.client,
+			storage: this.ctx.storage,
+			logger: this.logger
+		});
+		this.tunnelsHandler = built.tunnels;
+		this.tunnelExitHandler = built.handleTunnelExit;
+	}
 	async isPortExposed(port) {
 		try {
-			const sessionId = await this.ensureDefaultSession();
+			const sessionId = this.serializeExecutionContext(await this.resolveExecution());
 			return (await this.client.ports.getExposedPorts(sessionId)).ports.some((exposedPort) => exposedPort.port === port);
 		} catch (error) {
 			this.logger.error("Error checking if port is exposed", error instanceof Error ? error : new Error(String(error)), { port });
@@ -6378,6 +7312,7 @@ var Sandbox = class Sandbox extends Container {
 	*/
 	async createSession(options) {
 		const sessionId = options?.id || `session-${Date.now()}`;
+		if (sessionId === DISABLE_SESSION_TOKEN) throw new Error(`Session ID '${DISABLE_SESSION_TOKEN}' is reserved for internal use`);
 		const filteredEnv = filterEnvVars({
 			...this.envVars,
 			...options?.env ?? {}
@@ -7585,8 +8520,24 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
+	async configureR2EgressOutbound(params) {
+		const ctx = this.ctx;
+		if (!ctx.container?.interceptOutboundHttp) throw new InvalidMountConfigError("R2 binding mounts require container outbound interception support");
+		if (!ctx.exports?.ContainerProxy) throw new InvalidMountConfigError("R2 binding mounts require exporting ContainerProxy from the Worker entrypoint");
+		const fetcher = ctx.exports.ContainerProxy({ props: {
+			enableInternet: this.enableInternet,
+			containerId: this.ctx.id.toString(),
+			className: R2_EGRESS_PROXY_TARGET_CLASS_NAME,
+			outboundByHostOverrides: { "r2.internal": {
+				method: "r2EgressMount",
+				params
+			} }
+		} });
+		if (!isFetcher(fetcher)) throw new InvalidMountConfigError("R2 binding mounts require ContainerProxy to return a valid Fetcher");
+		await ctx.container.interceptOutboundHttp("r2.internal", fetcher);
+	}
 };
 
 //#endregion
 export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, RPCTransportError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y, SessionTerminatedError as z };
-//# sourceMappingURL=sandbox-uC1vzWtG.js.map
+//# sourceMappingURL=sandbox-B-MUmsli.js.map