@cloudflare/sandbox 0.10.2 → 0.10.3

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

@@ -2765,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;
@@ -3057,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);
@@ -4838,7 +4863,7 @@ function createTunnelsHandler(host) {
 * 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.2";
+const SDK_VERSION = "0.10.3";
 
 //#endregion
 //#region src/sandbox.ts
@@ -4987,14 +5012,63 @@ 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) {
@@ -5325,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);
@@ -5344,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.`);
@@ -5367,19 +5429,11 @@ var Sandbox = class Sandbox extends Container {
 		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$1) {
 		const parseAndValidate = (envVar, name, min, max) => {
 			const defaultValue = this.DEFAULT_CONTAINER_TIMEOUTS[name];
@@ -5742,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)}`);
 	}
 	/**
@@ -5920,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();
 		});
@@ -5937,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++;
@@ -6320,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.
@@ -6346,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,
@@ -6373,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
@@ -6384,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) {
@@ -6411,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");
@@ -6687,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 }
 			};
@@ -6705,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;
@@ -6733,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,
@@ -6751,22 +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).catch((e) => {
-			if (e instanceof ProcessNotFoundError) return null;
-			throw e;
-		});
-		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);
@@ -6787,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.
@@ -6813,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,
@@ -6822,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 });
 	}
@@ -6854,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);
 	}
 	/**
@@ -6913,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,
@@ -6933,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,
@@ -6995,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,
@@ -7035,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) {
@@ -7056,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();
@@ -7114,7 +7252,7 @@ var Sandbox = class Sandbox extends Container {
 	}
 	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 });
@@ -7174,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 ?? {}
@@ -8401,4 +8540,4 @@ var Sandbox = class Sandbox extends Container {
 
 //#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-BcEq4aUF.js.map
+//# sourceMappingURL=sandbox-B-MUmsli.js.map