@cloudflare/sandbox 0.0.0-aa00a75 → 0.0.0-aeba44f

package/dist/index.js

@@ -1,55 +1,3280 @@
-import {
-  collectFile,
-  streamFile
-} from "./chunk-BFVUNTP4.js";
-import {
-  CommandClient,
-  FileClient,
-  GitClient,
-  PortClient,
-  ProcessClient,
-  Sandbox,
-  SandboxClient,
-  UtilityClient,
-  getSandbox,
-  proxyToSandbox
-} from "./chunk-HGF554LH.js";
-import {
-  CodeInterpreter
-} from "./chunk-BCJ7SF3Q.js";
-import "./chunk-Z532A7QC.js";
-import {
-  asyncIterableToSSEStream,
-  parseSSEStream,
-  responseToAsyncIterable
-} from "./chunk-EKSWCBCA.js";
-
-// src/index.ts
-export * from "@repo/shared";
-import {
-  isExecResult,
-  isProcess,
-  isProcessStatus
-} from "@repo/shared";
-export {
-  CodeInterpreter,
-  CommandClient,
-  FileClient,
-  GitClient,
-  PortClient,
-  ProcessClient,
-  Sandbox,
-  SandboxClient,
-  UtilityClient,
-  asyncIterableToSSEStream,
-  collectFile,
-  getSandbox,
-  isExecResult,
-  isProcess,
-  isProcessStatus,
-  parseSSEStream,
-  proxyToSandbox,
-  responseToAsyncIterable,
-  streamFile
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Container, getContainer, switchPort } from "@cloudflare/containers";
+
+//#region ../shared/dist/git.js
+/**
+* Redact credentials from URLs for secure logging
+*
+* Replaces any credentials (username:password, tokens, etc.) embedded
+* in URLs with ****** to prevent sensitive data exposure in logs.
+* Works with URLs embedded in text (e.g., "Error: https://token@github.com/repo.git failed")
+*
+* @param text - String that may contain URLs with credentials
+* @returns String with credentials redacted from any URLs
+*/
+function redactCredentials(text) {
+	let result = text;
+	let pos = 0;
+	while (pos < result.length) {
+		const httpPos = result.indexOf("http://", pos);
+		const httpsPos = result.indexOf("https://", pos);
+		let protocolPos = -1;
+		let protocolLen = 0;
+		if (httpPos === -1 && httpsPos === -1) break;
+		if (httpPos !== -1 && (httpsPos === -1 || httpPos < httpsPos)) {
+			protocolPos = httpPos;
+			protocolLen = 7;
+		} else {
+			protocolPos = httpsPos;
+			protocolLen = 8;
+		}
+		const searchStart = protocolPos + protocolLen;
+		const atPos = result.indexOf("@", searchStart);
+		let urlEnd = searchStart;
+		while (urlEnd < result.length) {
+			const char = result[urlEnd];
+			if (/[\s"'`<>,;{}[\]]/.test(char)) break;
+			urlEnd++;
+		}
+		if (atPos !== -1 && atPos < urlEnd) {
+			result = `${result.substring(0, searchStart)}******${result.substring(atPos)}`;
+			pos = searchStart + 6;
+		} else pos = protocolPos + protocolLen;
+	}
+	return result;
+}
+/**
+* Sanitize data by redacting credentials from any strings
+* Recursively processes objects and arrays to ensure credentials are never leaked
+*/
+function sanitizeGitData(data) {
+	if (typeof data === "string") return redactCredentials(data);
+	if (data === null || data === void 0) return data;
+	if (Array.isArray(data)) return data.map((item) => sanitizeGitData(item));
+	if (typeof data === "object") {
+		const result = {};
+		for (const [key, value] of Object.entries(data)) result[key] = sanitizeGitData(value);
+		return result;
+	}
+	return data;
+}
+/**
+* Logger wrapper that automatically sanitizes git credentials
+*/
+var GitLogger = class GitLogger {
+	baseLogger;
+	constructor(baseLogger) {
+		this.baseLogger = baseLogger;
+	}
+	sanitizeContext(context) {
+		return context ? sanitizeGitData(context) : context;
+	}
+	sanitizeError(error) {
+		if (!error) return error;
+		const sanitized = new Error(redactCredentials(error.message));
+		sanitized.name = error.name;
+		if (error.stack) sanitized.stack = redactCredentials(error.stack);
+		const sanitizedRecord = sanitized;
+		const errorRecord = error;
+		for (const key of Object.keys(error)) if (key !== "message" && key !== "stack" && key !== "name") sanitizedRecord[key] = sanitizeGitData(errorRecord[key]);
+		return sanitized;
+	}
+	debug(message, context) {
+		this.baseLogger.debug(message, this.sanitizeContext(context));
+	}
+	info(message, context) {
+		this.baseLogger.info(message, this.sanitizeContext(context));
+	}
+	warn(message, context) {
+		this.baseLogger.warn(message, this.sanitizeContext(context));
+	}
+	error(message, error, context) {
+		this.baseLogger.error(message, this.sanitizeError(error), this.sanitizeContext(context));
+	}
+	child(context) {
+		const sanitized = sanitizeGitData(context);
+		return new GitLogger(this.baseLogger.child(sanitized));
+	}
+};
+
+//#endregion
+//#region ../shared/dist/interpreter-types.js
+var Execution = class {
+	code;
+	context;
+	/**
+	* All results from the execution
+	*/
+	results = [];
+	/**
+	* Accumulated stdout and stderr
+	*/
+	logs = {
+		stdout: [],
+		stderr: []
+	};
+	/**
+	* Execution error if any
+	*/
+	error;
+	/**
+	* Execution count (for interpreter)
+	*/
+	executionCount;
+	constructor(code, context) {
+		this.code = code;
+		this.context = context;
+	}
+	/**
+	* Convert to a plain object for serialization
+	*/
+	toJSON() {
+		return {
+			code: this.code,
+			logs: this.logs,
+			error: this.error,
+			executionCount: this.executionCount,
+			results: this.results.map((result) => ({
+				text: result.text,
+				html: result.html,
+				png: result.png,
+				jpeg: result.jpeg,
+				svg: result.svg,
+				latex: result.latex,
+				markdown: result.markdown,
+				javascript: result.javascript,
+				json: result.json,
+				chart: result.chart,
+				data: result.data
+			}))
+		};
+	}
+};
+var ResultImpl = class {
+	raw;
+	constructor(raw) {
+		this.raw = raw;
+	}
+	get text() {
+		return this.raw.text || this.raw.data?.["text/plain"];
+	}
+	get html() {
+		return this.raw.html || this.raw.data?.["text/html"];
+	}
+	get png() {
+		return this.raw.png || this.raw.data?.["image/png"];
+	}
+	get jpeg() {
+		return this.raw.jpeg || this.raw.data?.["image/jpeg"];
+	}
+	get svg() {
+		return this.raw.svg || this.raw.data?.["image/svg+xml"];
+	}
+	get latex() {
+		return this.raw.latex || this.raw.data?.["text/latex"];
+	}
+	get markdown() {
+		return this.raw.markdown || this.raw.data?.["text/markdown"];
+	}
+	get javascript() {
+		return this.raw.javascript || this.raw.data?.["application/javascript"];
+	}
+	get json() {
+		return this.raw.json || this.raw.data?.["application/json"];
+	}
+	get chart() {
+		return this.raw.chart;
+	}
+	get data() {
+		return this.raw.data;
+	}
+	formats() {
+		const formats = [];
+		if (this.text) formats.push("text");
+		if (this.html) formats.push("html");
+		if (this.png) formats.push("png");
+		if (this.jpeg) formats.push("jpeg");
+		if (this.svg) formats.push("svg");
+		if (this.latex) formats.push("latex");
+		if (this.markdown) formats.push("markdown");
+		if (this.javascript) formats.push("javascript");
+		if (this.json) formats.push("json");
+		if (this.chart) formats.push("chart");
+		return formats;
+	}
+};
+
+//#endregion
+//#region ../shared/dist/logger/types.js
+/**
+* Logger types for Cloudflare Sandbox SDK
+*
+* Provides structured, trace-aware logging across Worker, Durable Object, and Container.
+*/
+/**
+* Log levels (from most to least verbose)
+*/
+var LogLevel;
+(function(LogLevel$1) {
+	LogLevel$1[LogLevel$1["DEBUG"] = 0] = "DEBUG";
+	LogLevel$1[LogLevel$1["INFO"] = 1] = "INFO";
+	LogLevel$1[LogLevel$1["WARN"] = 2] = "WARN";
+	LogLevel$1[LogLevel$1["ERROR"] = 3] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+
+//#endregion
+//#region ../shared/dist/logger/logger.js
+/**
+* ANSI color codes for terminal output
+*/
+const COLORS = {
+	reset: "\x1B[0m",
+	debug: "\x1B[36m",
+	info: "\x1B[32m",
+	warn: "\x1B[33m",
+	error: "\x1B[31m",
+	dim: "\x1B[2m"
+};
+/**
+* CloudflareLogger implements structured logging with support for
+* both JSON output (production) and pretty printing (development).
+*/
+var CloudflareLogger = class CloudflareLogger {
+	baseContext;
+	minLevel;
+	pretty;
+	/**
+	* Create a new CloudflareLogger
+	*
+	* @param baseContext Base context included in all log entries
+	* @param minLevel Minimum log level to output (default: INFO)
+	* @param pretty Enable pretty printing for human-readable output (default: false)
+	*/
+	constructor(baseContext, minLevel = LogLevel.INFO, pretty = false) {
+		this.baseContext = baseContext;
+		this.minLevel = minLevel;
+		this.pretty = pretty;
+	}
+	/**
+	* Log debug-level message
+	*/
+	debug(message, context) {
+		if (this.shouldLog(LogLevel.DEBUG)) {
+			const logData = this.buildLogData("debug", message, context);
+			this.output(console.log, logData);
+		}
+	}
+	/**
+	* Log info-level message
+	*/
+	info(message, context) {
+		if (this.shouldLog(LogLevel.INFO)) {
+			const logData = this.buildLogData("info", message, context);
+			this.output(console.log, logData);
+		}
+	}
+	/**
+	* Log warning-level message
+	*/
+	warn(message, context) {
+		if (this.shouldLog(LogLevel.WARN)) {
+			const logData = this.buildLogData("warn", message, context);
+			this.output(console.warn, logData);
+		}
+	}
+	/**
+	* Log error-level message
+	*/
+	error(message, error, context) {
+		if (this.shouldLog(LogLevel.ERROR)) {
+			const logData = this.buildLogData("error", message, context, error);
+			this.output(console.error, logData);
+		}
+	}
+	/**
+	* Create a child logger with additional context
+	*/
+	child(context) {
+		return new CloudflareLogger({
+			...this.baseContext,
+			...context
+		}, this.minLevel, this.pretty);
+	}
+	/**
+	* Check if a log level should be output
+	*/
+	shouldLog(level) {
+		return level >= this.minLevel;
+	}
+	/**
+	* Build log data object
+	*/
+	buildLogData(level, message, context, error) {
+		const logData = {
+			level,
+			msg: message,
+			...this.baseContext,
+			...context,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		if (error) logData.error = {
+			message: error.message,
+			stack: error.stack,
+			name: error.name
+		};
+		return logData;
+	}
+	/**
+	* Output log data to console (pretty or JSON)
+	*/
+	output(consoleFn, data) {
+		if (this.pretty) this.outputPretty(consoleFn, data);
+		else this.outputJson(consoleFn, data);
+	}
+	/**
+	* Output as JSON (production)
+	*/
+	outputJson(consoleFn, data) {
+		consoleFn(JSON.stringify(data));
+	}
+	/**
+	* Output as pretty-printed, colored text (development)
+	*
+	* Format: LEVEL [component] message (trace: tr_...) {context}
+	* Example: INFO [sandbox-do] Command started (trace: tr_7f3a9b2c) {commandId: "cmd-123"}
+	*/
+	outputPretty(consoleFn, data) {
+		const { level, msg, timestamp, traceId, component, sandboxId, sessionId, processId, commandId, operation, duration, error,...rest } = data;
+		const levelStr = String(level || "INFO").toUpperCase();
+		const levelColor = this.getLevelColor(levelStr);
+		const componentBadge = component ? `[${component}]` : "";
+		const traceIdShort = traceId ? String(traceId).substring(0, 12) : "";
+		let logLine = `${levelColor}${levelStr.padEnd(5)}${COLORS.reset} ${componentBadge} ${msg}`;
+		if (traceIdShort) logLine += ` ${COLORS.dim}(trace: ${traceIdShort})${COLORS.reset}`;
+		const contextFields = [];
+		if (operation) contextFields.push(`operation: ${operation}`);
+		if (commandId) contextFields.push(`commandId: ${String(commandId).substring(0, 12)}`);
+		if (sandboxId) contextFields.push(`sandboxId: ${sandboxId}`);
+		if (sessionId) contextFields.push(`sessionId: ${String(sessionId).substring(0, 12)}`);
+		if (processId) contextFields.push(`processId: ${processId}`);
+		if (duration !== void 0) contextFields.push(`duration: ${duration}ms`);
+		if (contextFields.length > 0) logLine += ` ${COLORS.dim}{${contextFields.join(", ")}}${COLORS.reset}`;
+		consoleFn(logLine);
+		if (error && typeof error === "object") {
+			const errorObj = error;
+			if (errorObj.message) consoleFn(`  ${COLORS.error}Error: ${errorObj.message}${COLORS.reset}`);
+			if (errorObj.stack) consoleFn(`  ${COLORS.dim}${errorObj.stack}${COLORS.reset}`);
+		}
+		if (Object.keys(rest).length > 0) consoleFn(`  ${COLORS.dim}${JSON.stringify(rest, null, 2)}${COLORS.reset}`);
+	}
+	/**
+	* Get ANSI color code for log level
+	*/
+	getLevelColor(level) {
+		switch (level.toLowerCase()) {
+			case "debug": return COLORS.debug;
+			case "info": return COLORS.info;
+			case "warn": return COLORS.warn;
+			case "error": return COLORS.error;
+			default: return COLORS.reset;
+		}
+	}
+};
+
+//#endregion
+//#region ../shared/dist/logger/trace-context.js
+/**
+* Trace context utilities for request correlation
+*
+* Trace IDs enable correlating logs across distributed components:
+* Worker → Durable Object → Container → back
+*
+* The trace ID is propagated via the X-Trace-Id HTTP header.
+*/
+/**
+* Utility for managing trace context across distributed components
+*/
+var TraceContext = class TraceContext {
+	/**
+	* HTTP header name for trace ID propagation
+	*/
+	static TRACE_HEADER = "X-Trace-Id";
+	/**
+	* Generate a new trace ID
+	*
+	* Format: "tr_" + 16 random hex characters
+	* Example: "tr_7f3a9b2c4e5d6f1a"
+	*
+	* @returns Newly generated trace ID
+	*/
+	static generate() {
+		return `tr_${crypto.randomUUID().replace(/-/g, "").substring(0, 16)}`;
+	}
+	/**
+	* Extract trace ID from HTTP request headers
+	*
+	* @param headers Request headers
+	* @returns Trace ID if present, null otherwise
+	*/
+	static fromHeaders(headers) {
+		return headers.get(TraceContext.TRACE_HEADER);
+	}
+	/**
+	* Create headers object with trace ID for outgoing requests
+	*
+	* @param traceId Trace ID to include
+	* @returns Headers object with X-Trace-Id set
+	*/
+	static toHeaders(traceId) {
+		return { [TraceContext.TRACE_HEADER]: traceId };
+	}
+	/**
+	* Get the header name used for trace ID propagation
+	*
+	* @returns Header name ("X-Trace-Id")
+	*/
+	static getHeaderName() {
+		return TraceContext.TRACE_HEADER;
+	}
+};
+
+//#endregion
+//#region ../shared/dist/logger/index.js
+/**
+* Create a no-op logger for testing
+*
+* Returns a logger that implements the Logger interface but does nothing.
+* Useful for tests that don't need actual logging output.
+*
+* @returns No-op logger instance
+*
+* @example
+* ```typescript
+* // In tests
+* const client = new HttpClient({
+*   baseUrl: 'http://test.com',
+*   logger: createNoOpLogger() // Optional - tests can enable real logging if needed
+* });
+* ```
+*/
+function createNoOpLogger() {
+	return {
+		debug: () => {},
+		info: () => {},
+		warn: () => {},
+		error: () => {},
+		child: () => createNoOpLogger()
+	};
+}
+/**
+* AsyncLocalStorage for logger context
+*
+* Enables implicit logger propagation throughout the call stack without
+* explicit parameter passing. The logger is stored per async context.
+*/
+const loggerStorage = new AsyncLocalStorage();
+/**
+* Get the current logger from AsyncLocalStorage
+*
+* @throws Error if no logger is initialized in the current async context
+* @returns Current logger instance
+*
+* @example
+* ```typescript
+* function someHelperFunction() {
+*   const logger = getLogger(); // Automatically has all context!
+*   logger.info('Helper called');
+* }
+* ```
+*/
+function getLogger() {
+	const logger = loggerStorage.getStore();
+	if (!logger) throw new Error("Logger not initialized in async context. Ensure runWithLogger() is called at the entry point (e.g., fetch handler).");
+	return logger;
+}
+/**
+* Run a function with a logger stored in AsyncLocalStorage
+*
+* The logger is available to all code within the function via getLogger().
+* This is typically called at request entry points (fetch handler) and when
+* creating child loggers with additional context.
+*
+* @param logger Logger instance to store in context
+* @param fn Function to execute with logger context
+* @returns Result of the function
+*
+* @example
+* ```typescript
+* // At request entry point
+* async fetch(request: Request): Promise<Response> {
+*   const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc' });
+*   return runWithLogger(logger, async () => {
+*     return await this.handleRequest(request);
+*   });
+* }
+*
+* // When adding operation context
+* async exec(command: string) {
+*   const logger = getLogger().child({ operation: 'exec', commandId: 'cmd-123' });
+*   return runWithLogger(logger, async () => {
+*     logger.info('Command started');
+*     await this.executeCommand(command); // Nested calls get the child logger
+*     logger.info('Command completed');
+*   });
+* }
+* ```
+*/
+function runWithLogger(logger, fn) {
+	return loggerStorage.run(logger, fn);
+}
+/**
+* Create a new logger instance
+*
+* @param context Base context for the logger. Must include 'component'.
+*                TraceId will be auto-generated if not provided.
+* @returns New logger instance
+*
+* @example
+* ```typescript
+* // In Durable Object
+* const logger = createLogger({
+*   component: 'sandbox-do',
+*   traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
+*   sandboxId: this.id
+* });
+*
+* // In Container
+* const logger = createLogger({
+*   component: 'container',
+*   traceId: TraceContext.fromHeaders(request.headers)!,
+*   sessionId: this.id
+* });
+* ```
+*/
+function createLogger(context) {
+	const minLevel = getLogLevelFromEnv();
+	const pretty = isPrettyPrintEnabled();
+	return new CloudflareLogger({
+		...context,
+		traceId: context.traceId || TraceContext.generate(),
+		component: context.component
+	}, minLevel, pretty);
+}
+/**
+* Get log level from environment variable
+*
+* Checks SANDBOX_LOG_LEVEL env var, falls back to default based on environment.
+* Default: 'debug' for development, 'info' for production
+*/
+function getLogLevelFromEnv() {
+	switch ((getEnvVar("SANDBOX_LOG_LEVEL") || "info").toLowerCase()) {
+		case "debug": return LogLevel.DEBUG;
+		case "info": return LogLevel.INFO;
+		case "warn": return LogLevel.WARN;
+		case "error": return LogLevel.ERROR;
+		default: return LogLevel.INFO;
+	}
+}
+/**
+* Check if pretty printing should be enabled
+*
+* Checks SANDBOX_LOG_FORMAT env var, falls back to auto-detection:
+* - Local development: pretty (colored, human-readable)
+* - Production: json (structured)
+*/
+function isPrettyPrintEnabled() {
+	const format = getEnvVar("SANDBOX_LOG_FORMAT");
+	if (format) return format.toLowerCase() === "pretty";
+	return false;
+}
+/**
+* Get environment variable value
+*
+* Supports both Node.js (process.env) and Bun (Bun.env)
+*/
+function getEnvVar(name) {
+	if (typeof process !== "undefined" && process.env) return process.env[name];
+	if (typeof Bun !== "undefined") {
+		const bunEnv = Bun.env;
+		if (bunEnv) return bunEnv[name];
+	}
+}
+
+//#endregion
+//#region ../shared/dist/types.js
+function isExecResult(value) {
+	return value && typeof value.success === "boolean" && typeof value.exitCode === "number" && typeof value.stdout === "string" && typeof value.stderr === "string";
+}
+function isProcess(value) {
+	return value && typeof value.id === "string" && typeof value.command === "string" && typeof value.status === "string";
+}
+function isProcessStatus(value) {
+	return [
+		"starting",
+		"running",
+		"completed",
+		"failed",
+		"killed",
+		"error"
+	].includes(value);
+}
+
+//#endregion
+//#region ../shared/dist/errors/codes.js
+/**
+* Centralized error code registry
+* Each code maps to a specific error type with consistent semantics
+*/
+const ErrorCode = {
+	FILE_NOT_FOUND: "FILE_NOT_FOUND",
+	PERMISSION_DENIED: "PERMISSION_DENIED",
+	FILE_EXISTS: "FILE_EXISTS",
+	IS_DIRECTORY: "IS_DIRECTORY",
+	NOT_DIRECTORY: "NOT_DIRECTORY",
+	NO_SPACE: "NO_SPACE",
+	TOO_MANY_FILES: "TOO_MANY_FILES",
+	RESOURCE_BUSY: "RESOURCE_BUSY",
+	READ_ONLY: "READ_ONLY",
+	NAME_TOO_LONG: "NAME_TOO_LONG",
+	TOO_MANY_LINKS: "TOO_MANY_LINKS",
+	FILESYSTEM_ERROR: "FILESYSTEM_ERROR",
+	COMMAND_NOT_FOUND: "COMMAND_NOT_FOUND",
+	COMMAND_PERMISSION_DENIED: "COMMAND_PERMISSION_DENIED",
+	INVALID_COMMAND: "INVALID_COMMAND",
+	COMMAND_EXECUTION_ERROR: "COMMAND_EXECUTION_ERROR",
+	STREAM_START_ERROR: "STREAM_START_ERROR",
+	PROCESS_NOT_FOUND: "PROCESS_NOT_FOUND",
+	PROCESS_PERMISSION_DENIED: "PROCESS_PERMISSION_DENIED",
+	PROCESS_ERROR: "PROCESS_ERROR",
+	PORT_ALREADY_EXPOSED: "PORT_ALREADY_EXPOSED",
+	PORT_IN_USE: "PORT_IN_USE",
+	PORT_NOT_EXPOSED: "PORT_NOT_EXPOSED",
+	INVALID_PORT_NUMBER: "INVALID_PORT_NUMBER",
+	INVALID_PORT: "INVALID_PORT",
+	SERVICE_NOT_RESPONDING: "SERVICE_NOT_RESPONDING",
+	PORT_OPERATION_ERROR: "PORT_OPERATION_ERROR",
+	CUSTOM_DOMAIN_REQUIRED: "CUSTOM_DOMAIN_REQUIRED",
+	GIT_REPOSITORY_NOT_FOUND: "GIT_REPOSITORY_NOT_FOUND",
+	GIT_BRANCH_NOT_FOUND: "GIT_BRANCH_NOT_FOUND",
+	GIT_AUTH_FAILED: "GIT_AUTH_FAILED",
+	GIT_NETWORK_ERROR: "GIT_NETWORK_ERROR",
+	INVALID_GIT_URL: "INVALID_GIT_URL",
+	GIT_CLONE_FAILED: "GIT_CLONE_FAILED",
+	GIT_CHECKOUT_FAILED: "GIT_CHECKOUT_FAILED",
+	GIT_OPERATION_FAILED: "GIT_OPERATION_FAILED",
+	INTERPRETER_NOT_READY: "INTERPRETER_NOT_READY",
+	CONTEXT_NOT_FOUND: "CONTEXT_NOT_FOUND",
+	CODE_EXECUTION_ERROR: "CODE_EXECUTION_ERROR",
+	VALIDATION_FAILED: "VALIDATION_FAILED",
+	INVALID_JSON_RESPONSE: "INVALID_JSON_RESPONSE",
+	UNKNOWN_ERROR: "UNKNOWN_ERROR",
+	INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+
+//#endregion
+//#region ../shared/dist/errors/status-map.js
+/**
+* Maps error codes to HTTP status codes
+* Centralized mapping ensures consistency across SDK
+*/
+const ERROR_STATUS_MAP = {
+	[ErrorCode.FILE_NOT_FOUND]: 404,
+	[ErrorCode.COMMAND_NOT_FOUND]: 404,
+	[ErrorCode.PROCESS_NOT_FOUND]: 404,
+	[ErrorCode.PORT_NOT_EXPOSED]: 404,
+	[ErrorCode.GIT_REPOSITORY_NOT_FOUND]: 404,
+	[ErrorCode.GIT_BRANCH_NOT_FOUND]: 404,
+	[ErrorCode.CONTEXT_NOT_FOUND]: 404,
+	[ErrorCode.IS_DIRECTORY]: 400,
+	[ErrorCode.NOT_DIRECTORY]: 400,
+	[ErrorCode.INVALID_COMMAND]: 400,
+	[ErrorCode.INVALID_PORT_NUMBER]: 400,
+	[ErrorCode.INVALID_PORT]: 400,
+	[ErrorCode.INVALID_GIT_URL]: 400,
+	[ErrorCode.CUSTOM_DOMAIN_REQUIRED]: 400,
+	[ErrorCode.INVALID_JSON_RESPONSE]: 400,
+	[ErrorCode.NAME_TOO_LONG]: 400,
+	[ErrorCode.VALIDATION_FAILED]: 400,
+	[ErrorCode.GIT_AUTH_FAILED]: 401,
+	[ErrorCode.PERMISSION_DENIED]: 403,
+	[ErrorCode.COMMAND_PERMISSION_DENIED]: 403,
+	[ErrorCode.PROCESS_PERMISSION_DENIED]: 403,
+	[ErrorCode.READ_ONLY]: 403,
+	[ErrorCode.FILE_EXISTS]: 409,
+	[ErrorCode.PORT_ALREADY_EXPOSED]: 409,
+	[ErrorCode.PORT_IN_USE]: 409,
+	[ErrorCode.RESOURCE_BUSY]: 409,
+	[ErrorCode.SERVICE_NOT_RESPONDING]: 502,
+	[ErrorCode.GIT_NETWORK_ERROR]: 502,
+	[ErrorCode.INTERPRETER_NOT_READY]: 503,
+	[ErrorCode.NO_SPACE]: 500,
+	[ErrorCode.TOO_MANY_FILES]: 500,
+	[ErrorCode.TOO_MANY_LINKS]: 500,
+	[ErrorCode.FILESYSTEM_ERROR]: 500,
+	[ErrorCode.COMMAND_EXECUTION_ERROR]: 500,
+	[ErrorCode.STREAM_START_ERROR]: 500,
+	[ErrorCode.PROCESS_ERROR]: 500,
+	[ErrorCode.PORT_OPERATION_ERROR]: 500,
+	[ErrorCode.GIT_CLONE_FAILED]: 500,
+	[ErrorCode.GIT_CHECKOUT_FAILED]: 500,
+	[ErrorCode.GIT_OPERATION_FAILED]: 500,
+	[ErrorCode.CODE_EXECUTION_ERROR]: 500,
+	[ErrorCode.UNKNOWN_ERROR]: 500,
+	[ErrorCode.INTERNAL_ERROR]: 500
+};
+
+//#endregion
+//#region src/errors/classes.ts
+/**
+* Base SDK error that wraps ErrorResponse
+* Preserves all error information from container
+*/
+var SandboxError = class extends Error {
+	constructor(errorResponse) {
+		super(errorResponse.message);
+		this.errorResponse = errorResponse;
+		this.name = "SandboxError";
+	}
+	get code() {
+		return this.errorResponse.code;
+	}
+	get context() {
+		return this.errorResponse.context;
+	}
+	get httpStatus() {
+		return this.errorResponse.httpStatus;
+	}
+	get operation() {
+		return this.errorResponse.operation;
+	}
+	get suggestion() {
+		return this.errorResponse.suggestion;
+	}
+	get timestamp() {
+		return this.errorResponse.timestamp;
+	}
+	get documentation() {
+		return this.errorResponse.documentation;
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			context: this.context,
+			httpStatus: this.httpStatus,
+			operation: this.operation,
+			suggestion: this.suggestion,
+			timestamp: this.timestamp,
+			documentation: this.documentation,
+			stack: this.stack
+		};
+	}
+};
+/**
+* Error thrown when a file or directory is not found
+*/
+var FileNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "FileNotFoundError";
+	}
+	get path() {
+		return this.context.path;
+	}
+};
+/**
+* Error thrown when a file already exists
+*/
+var FileExistsError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "FileExistsError";
+	}
+	get path() {
+		return this.context.path;
+	}
+};
+/**
+* Generic file system error (permissions, disk full, etc.)
+*/
+var FileSystemError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "FileSystemError";
+	}
+	get path() {
+		return this.context.path;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
+};
+/**
+* Error thrown when permission is denied
+*/
+var PermissionDeniedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "PermissionDeniedError";
+	}
+	get path() {
+		return this.context.path;
+	}
+};
+/**
+* Error thrown when a command is not found
+*/
+var CommandNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "CommandNotFoundError";
+	}
+	get command() {
+		return this.context.command;
+	}
+};
+/**
+* Generic command execution error
+*/
+var CommandError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "CommandError";
+	}
+	get command() {
+		return this.context.command;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
+	get stdout() {
+		return this.context.stdout;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+};
+/**
+* Error thrown when a process is not found
+*/
+var ProcessNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ProcessNotFoundError";
+	}
+	get processId() {
+		return this.context.processId;
+	}
+};
+/**
+* Generic process error
+*/
+var ProcessError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ProcessError";
+	}
+	get processId() {
+		return this.context.processId;
+	}
+	get pid() {
+		return this.context.pid;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+};
+/**
+* Error thrown when a port is already exposed
+*/
+var PortAlreadyExposedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "PortAlreadyExposedError";
+	}
+	get port() {
+		return this.context.port;
+	}
+	get portName() {
+		return this.context.portName;
+	}
+};
+/**
+* Error thrown when a port is not exposed
+*/
+var PortNotExposedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "PortNotExposedError";
+	}
+	get port() {
+		return this.context.port;
+	}
+};
+/**
+* Error thrown when a port number is invalid
+*/
+var InvalidPortError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "InvalidPortError";
+	}
+	get port() {
+		return this.context.port;
+	}
+	get reason() {
+		return this.context.reason;
+	}
+};
+/**
+* Error thrown when a service on a port is not responding
+*/
+var ServiceNotRespondingError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ServiceNotRespondingError";
+	}
+	get port() {
+		return this.context.port;
+	}
+	get portName() {
+		return this.context.portName;
+	}
+};
+/**
+* Error thrown when a port is already in use
+*/
+var PortInUseError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "PortInUseError";
+	}
+	get port() {
+		return this.context.port;
+	}
+};
+/**
+* Generic port operation error
+*/
+var PortError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "PortError";
+	}
+	get port() {
+		return this.context.port;
+	}
+	get portName() {
+		return this.context.portName;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+};
+/**
+* Error thrown when port exposure requires a custom domain
+*/
+var CustomDomainRequiredError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "CustomDomainRequiredError";
+	}
+};
+/**
+* Error thrown when a git repository is not found
+*/
+var GitRepositoryNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitRepositoryNotFoundError";
+	}
+	get repository() {
+		return this.context.repository;
+	}
+};
+/**
+* Error thrown when git authentication fails
+*/
+var GitAuthenticationError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitAuthenticationError";
+	}
+	get repository() {
+		return this.context.repository;
+	}
+};
+/**
+* Error thrown when a git branch is not found
+*/
+var GitBranchNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitBranchNotFoundError";
+	}
+	get branch() {
+		return this.context.branch;
+	}
+	get repository() {
+		return this.context.repository;
+	}
+};
+/**
+* Error thrown when a git network operation fails
+*/
+var GitNetworkError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitNetworkError";
+	}
+	get repository() {
+		return this.context.repository;
+	}
+	get branch() {
+		return this.context.branch;
+	}
+	get targetDir() {
+		return this.context.targetDir;
+	}
+};
+/**
+* Error thrown when git clone fails
+*/
+var GitCloneError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitCloneError";
+	}
+	get repository() {
+		return this.context.repository;
+	}
+	get targetDir() {
+		return this.context.targetDir;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
 };
+/**
+* Error thrown when git checkout fails
+*/
+var GitCheckoutError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitCheckoutError";
+	}
+	get branch() {
+		return this.context.branch;
+	}
+	get repository() {
+		return this.context.repository;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+};
+/**
+* Error thrown when a git URL is invalid
+*/
+var InvalidGitUrlError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "InvalidGitUrlError";
+	}
+	get validationErrors() {
+		return this.context.validationErrors;
+	}
+};
+/**
+* Generic git operation error
+*/
+var GitError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "GitError";
+	}
+	get repository() {
+		return this.context.repository;
+	}
+	get branch() {
+		return this.context.branch;
+	}
+	get targetDir() {
+		return this.context.targetDir;
+	}
+	get stderr() {
+		return this.context.stderr;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
+};
+/**
+* Error thrown when interpreter is not ready
+*/
+var InterpreterNotReadyError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "InterpreterNotReadyError";
+	}
+	get retryAfter() {
+		return this.context.retryAfter;
+	}
+	get progress() {
+		return this.context.progress;
+	}
+};
+/**
+* Error thrown when a context is not found
+*/
+var ContextNotFoundError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ContextNotFoundError";
+	}
+	get contextId() {
+		return this.context.contextId;
+	}
+};
+/**
+* Error thrown when code execution fails
+*/
+var CodeExecutionError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "CodeExecutionError";
+	}
+	get contextId() {
+		return this.context.contextId;
+	}
+	get ename() {
+		return this.context.ename;
+	}
+	get evalue() {
+		return this.context.evalue;
+	}
+	get traceback() {
+		return this.context.traceback;
+	}
+};
+/**
+* Error thrown when validation fails
+*/
+var ValidationFailedError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ValidationFailedError";
+	}
+	get validationErrors() {
+		return this.context.validationErrors;
+	}
+};
+
+//#endregion
+//#region src/errors/adapter.ts
+/**
+* Convert ErrorResponse to appropriate Error class
+* Simple switch statement - we trust the container sends correct context
+*/
+function createErrorFromResponse(errorResponse) {
+	switch (errorResponse.code) {
+		case ErrorCode.FILE_NOT_FOUND: return new FileNotFoundError(errorResponse);
+		case ErrorCode.FILE_EXISTS: return new FileExistsError(errorResponse);
+		case ErrorCode.PERMISSION_DENIED: return new PermissionDeniedError(errorResponse);
+		case ErrorCode.IS_DIRECTORY:
+		case ErrorCode.NOT_DIRECTORY:
+		case ErrorCode.NO_SPACE:
+		case ErrorCode.TOO_MANY_FILES:
+		case ErrorCode.RESOURCE_BUSY:
+		case ErrorCode.READ_ONLY:
+		case ErrorCode.NAME_TOO_LONG:
+		case ErrorCode.TOO_MANY_LINKS:
+		case ErrorCode.FILESYSTEM_ERROR: return new FileSystemError(errorResponse);
+		case ErrorCode.COMMAND_NOT_FOUND: return new CommandNotFoundError(errorResponse);
+		case ErrorCode.COMMAND_PERMISSION_DENIED:
+		case ErrorCode.COMMAND_EXECUTION_ERROR:
+		case ErrorCode.INVALID_COMMAND:
+		case ErrorCode.STREAM_START_ERROR: return new CommandError(errorResponse);
+		case ErrorCode.PROCESS_NOT_FOUND: return new ProcessNotFoundError(errorResponse);
+		case ErrorCode.PROCESS_PERMISSION_DENIED:
+		case ErrorCode.PROCESS_ERROR: return new ProcessError(errorResponse);
+		case ErrorCode.PORT_ALREADY_EXPOSED: return new PortAlreadyExposedError(errorResponse);
+		case ErrorCode.PORT_NOT_EXPOSED: return new PortNotExposedError(errorResponse);
+		case ErrorCode.INVALID_PORT_NUMBER:
+		case ErrorCode.INVALID_PORT: return new InvalidPortError(errorResponse);
+		case ErrorCode.SERVICE_NOT_RESPONDING: return new ServiceNotRespondingError(errorResponse);
+		case ErrorCode.PORT_IN_USE: return new PortInUseError(errorResponse);
+		case ErrorCode.PORT_OPERATION_ERROR: return new PortError(errorResponse);
+		case ErrorCode.CUSTOM_DOMAIN_REQUIRED: return new CustomDomainRequiredError(errorResponse);
+		case ErrorCode.GIT_REPOSITORY_NOT_FOUND: return new GitRepositoryNotFoundError(errorResponse);
+		case ErrorCode.GIT_AUTH_FAILED: return new GitAuthenticationError(errorResponse);
+		case ErrorCode.GIT_BRANCH_NOT_FOUND: return new GitBranchNotFoundError(errorResponse);
+		case ErrorCode.GIT_NETWORK_ERROR: return new GitNetworkError(errorResponse);
+		case ErrorCode.GIT_CLONE_FAILED: return new GitCloneError(errorResponse);
+		case ErrorCode.GIT_CHECKOUT_FAILED: return new GitCheckoutError(errorResponse);
+		case ErrorCode.INVALID_GIT_URL: return new InvalidGitUrlError(errorResponse);
+		case ErrorCode.GIT_OPERATION_FAILED: return new GitError(errorResponse);
+		case ErrorCode.INTERPRETER_NOT_READY: return new InterpreterNotReadyError(errorResponse);
+		case ErrorCode.CONTEXT_NOT_FOUND: return new ContextNotFoundError(errorResponse);
+		case ErrorCode.CODE_EXECUTION_ERROR: return new CodeExecutionError(errorResponse);
+		case ErrorCode.VALIDATION_FAILED: return new ValidationFailedError(errorResponse);
+		case ErrorCode.INVALID_JSON_RESPONSE:
+		case ErrorCode.UNKNOWN_ERROR:
+		case ErrorCode.INTERNAL_ERROR: return new SandboxError(errorResponse);
+		default: return new SandboxError(errorResponse);
+	}
+}
+
+//#endregion
+//#region src/clients/base-client.ts
+const TIMEOUT_MS = 6e4;
+const MIN_TIME_FOR_RETRY_MS = 1e4;
+/**
+* Abstract base class providing common HTTP functionality for all domain clients
+*/
+var BaseHttpClient = class {
+	baseUrl;
+	options;
+	logger;
+	constructor(options = {}) {
+		this.options = options;
+		this.logger = options.logger ?? createNoOpLogger();
+		this.baseUrl = this.options.baseUrl;
+	}
+	/**
+	* Core HTTP request method with automatic retry for container provisioning delays
+	*/
+	async doFetch(path, options) {
+		const startTime = Date.now();
+		let attempt = 0;
+		while (true) {
+			const response = await this.executeFetch(path, options);
+			if (response.status === 503) {
+				if (await this.isContainerProvisioningError(response)) {
+					const remaining = TIMEOUT_MS - (Date.now() - startTime);
+					if (remaining > MIN_TIME_FOR_RETRY_MS) {
+						const delay = Math.min(2e3 * 2 ** attempt, 16e3);
+						this.logger.info("Container provisioning in progress, retrying", {
+							attempt: attempt + 1,
+							delayMs: delay,
+							remainingSec: Math.floor(remaining / 1e3)
+						});
+						await new Promise((resolve) => setTimeout(resolve, delay));
+						attempt++;
+						continue;
+					} else {
+						this.logger.error("Container failed to provision after multiple attempts", /* @__PURE__ */ new Error(`Failed after ${attempt + 1} attempts over 60s`));
+						return response;
+					}
+				}
+			}
+			return response;
+		}
+	}
+	/**
+	* Make a POST request with JSON body
+	*/
+	async post(endpoint, data, responseHandler) {
+		const response = await this.doFetch(endpoint, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(data)
+		});
+		return this.handleResponse(response, responseHandler);
+	}
+	/**
+	* Make a GET request
+	*/
+	async get(endpoint, responseHandler) {
+		const response = await this.doFetch(endpoint, { method: "GET" });
+		return this.handleResponse(response, responseHandler);
+	}
+	/**
+	* Make a DELETE request
+	*/
+	async delete(endpoint, responseHandler) {
+		const response = await this.doFetch(endpoint, { method: "DELETE" });
+		return this.handleResponse(response, responseHandler);
+	}
+	/**
+	* Handle HTTP response with error checking and parsing
+	*/
+	async handleResponse(response, customHandler) {
+		if (!response.ok) await this.handleErrorResponse(response);
+		if (customHandler) return customHandler(response);
+		try {
+			return await response.json();
+		} catch (error) {
+			throw createErrorFromResponse({
+				code: ErrorCode.INVALID_JSON_RESPONSE,
+				message: `Invalid JSON response: ${error instanceof Error ? error.message : "Unknown parsing error"}`,
+				context: {},
+				httpStatus: response.status,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	}
+	/**
+	* Handle error responses with consistent error throwing
+	*/
+	async handleErrorResponse(response) {
+		let errorData;
+		try {
+			errorData = await response.json();
+		} catch {
+			errorData = {
+				code: ErrorCode.INTERNAL_ERROR,
+				message: `HTTP error! status: ${response.status}`,
+				context: { statusText: response.statusText },
+				httpStatus: response.status,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			};
+		}
+		const error = createErrorFromResponse(errorData);
+		this.options.onError?.(errorData.message, void 0);
+		throw error;
+	}
+	/**
+	* Create a streaming response handler for Server-Sent Events
+	*/
+	async handleStreamResponse(response) {
+		if (!response.ok) await this.handleErrorResponse(response);
+		if (!response.body) throw new Error("No response body for streaming");
+		return response.body;
+	}
+	/**
+	* Utility method to log successful operations
+	*/
+	logSuccess(operation, details) {
+		this.logger.info(`${operation} completed successfully`, details ? { details } : void 0);
+	}
+	/**
+	* Utility method to log errors intelligently
+	* Only logs unexpected errors (5xx), not expected errors (4xx)
+	*
+	* - 4xx errors (validation, not found, conflicts): Don't log (expected client errors)
+	* - 5xx errors (server failures, internal errors): DO log (unexpected server errors)
+	*/
+	logError(operation, error) {
+		if (error && typeof error === "object" && "httpStatus" in error) {
+			const httpStatus = error.httpStatus;
+			if (httpStatus >= 500) this.logger.error(`Unexpected error in ${operation}`, error instanceof Error ? error : new Error(String(error)), { httpStatus });
+		} else this.logger.error(`Error in ${operation}`, error instanceof Error ? error : new Error(String(error)));
+	}
+	/**
+	* Check if 503 response is from container provisioning (retryable)
+	* vs user application (not retryable)
+	*/
+	async isContainerProvisioningError(response) {
+		try {
+			return (await response.clone().text()).includes("There is no Container instance available");
+		} catch (error) {
+			this.logger.error("Error checking response body", error instanceof Error ? error : new Error(String(error)));
+			return false;
+		}
+	}
+	async executeFetch(path, options) {
+		const url = this.options.stub ? `http://localhost:${this.options.port}${path}` : `${this.baseUrl}${path}`;
+		try {
+			if (this.options.stub) return await this.options.stub.containerFetch(url, options || {}, this.options.port);
+			else return await fetch(url, options);
+		} catch (error) {
+			this.logger.error("HTTP request error", error instanceof Error ? error : new Error(String(error)), {
+				method: options?.method || "GET",
+				url
+			});
+			throw error;
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/command-client.ts
+/**
+* Client for command execution operations
+*/
+var CommandClient = class extends BaseHttpClient {
+	/**
+	* Execute a command and return the complete result
+	* @param command - The command to execute
+	* @param sessionId - The session ID for this command execution
+	* @param timeoutMs - Optional timeout in milliseconds (unlimited by default)
+	*/
+	async execute(command, sessionId, timeoutMs) {
+		try {
+			const data = {
+				command,
+				sessionId,
+				...timeoutMs !== void 0 && { timeoutMs }
+			};
+			const response = await this.post("/api/execute", data);
+			this.logSuccess("Command executed", `${command}, Success: ${response.success}`);
+			this.options.onCommandComplete?.(response.success, response.exitCode, response.stdout, response.stderr, response.command);
+			return response;
+		} catch (error) {
+			this.logError("execute", error);
+			this.options.onError?.(error instanceof Error ? error.message : String(error), command);
+			throw error;
+		}
+	}
+	/**
+	* Execute a command and return a stream of events
+	* @param command - The command to execute
+	* @param sessionId - The session ID for this command execution
+	*/
+	async executeStream(command, sessionId) {
+		try {
+			const data = {
+				command,
+				sessionId
+			};
+			const response = await this.doFetch("/api/execute/stream", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(data)
+			});
+			const stream = await this.handleStreamResponse(response);
+			this.logSuccess("Command stream started", command);
+			return stream;
+		} catch (error) {
+			this.logError("executeStream", error);
+			this.options.onError?.(error instanceof Error ? error.message : String(error), command);
+			throw error;
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/file-client.ts
+/**
+* Client for file system operations
+*/
+var FileClient = class extends BaseHttpClient {
+	/**
+	* Create a directory
+	* @param path - Directory path to create
+	* @param sessionId - The session ID for this operation
+	* @param options - Optional settings (recursive)
+	*/
+	async mkdir(path, sessionId, options) {
+		try {
+			const data = {
+				path,
+				sessionId,
+				recursive: options?.recursive ?? false
+			};
+			const response = await this.post("/api/mkdir", data);
+			this.logSuccess("Directory created", `${path} (recursive: ${data.recursive})`);
+			return response;
+		} catch (error) {
+			this.logError("mkdir", error);
+			throw error;
+		}
+	}
+	/**
+	* Write content to a file
+	* @param path - File path to write to
+	* @param content - Content to write
+	* @param sessionId - The session ID for this operation
+	* @param options - Optional settings (encoding)
+	*/
+	async writeFile(path, content, sessionId, options) {
+		try {
+			const data = {
+				path,
+				content,
+				sessionId,
+				encoding: options?.encoding
+			};
+			const response = await this.post("/api/write", data);
+			this.logSuccess("File written", `${path} (${content.length} chars)`);
+			return response;
+		} catch (error) {
+			this.logError("writeFile", error);
+			throw error;
+		}
+	}
+	/**
+	* Read content from a file
+	* @param path - File path to read from
+	* @param sessionId - The session ID for this operation
+	* @param options - Optional settings (encoding)
+	*/
+	async readFile(path, sessionId, options) {
+		try {
+			const data = {
+				path,
+				sessionId,
+				encoding: options?.encoding
+			};
+			const response = await this.post("/api/read", data);
+			this.logSuccess("File read", `${path} (${response.content.length} chars)`);
+			return response;
+		} catch (error) {
+			this.logError("readFile", error);
+			throw error;
+		}
+	}
+	/**
+	* Stream a file using Server-Sent Events
+	* Returns a ReadableStream of SSE events containing metadata, chunks, and completion
+	* @param path - File path to stream
+	* @param sessionId - The session ID for this operation
+	*/
+	async readFileStream(path, sessionId) {
+		try {
+			const data = {
+				path,
+				sessionId
+			};
+			const response = await this.doFetch("/api/read/stream", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(data)
+			});
+			const stream = await this.handleStreamResponse(response);
+			this.logSuccess("File stream started", path);
+			return stream;
+		} catch (error) {
+			this.logError("readFileStream", error);
+			throw error;
+		}
+	}
+	/**
+	* Delete a file
+	* @param path - File path to delete
+	* @param sessionId - The session ID for this operation
+	*/
+	async deleteFile(path, sessionId) {
+		try {
+			const data = {
+				path,
+				sessionId
+			};
+			const response = await this.post("/api/delete", data);
+			this.logSuccess("File deleted", path);
+			return response;
+		} catch (error) {
+			this.logError("deleteFile", error);
+			throw error;
+		}
+	}
+	/**
+	* Rename a file
+	* @param path - Current file path
+	* @param newPath - New file path
+	* @param sessionId - The session ID for this operation
+	*/
+	async renameFile(path, newPath, sessionId) {
+		try {
+			const data = {
+				oldPath: path,
+				newPath,
+				sessionId
+			};
+			const response = await this.post("/api/rename", data);
+			this.logSuccess("File renamed", `${path} -> ${newPath}`);
+			return response;
+		} catch (error) {
+			this.logError("renameFile", error);
+			throw error;
+		}
+	}
+	/**
+	* Move a file
+	* @param path - Current file path
+	* @param newPath - Destination file path
+	* @param sessionId - The session ID for this operation
+	*/
+	async moveFile(path, newPath, sessionId) {
+		try {
+			const data = {
+				sourcePath: path,
+				destinationPath: newPath,
+				sessionId
+			};
+			const response = await this.post("/api/move", data);
+			this.logSuccess("File moved", `${path} -> ${newPath}`);
+			return response;
+		} catch (error) {
+			this.logError("moveFile", error);
+			throw error;
+		}
+	}
+	/**
+	* List files in a directory
+	* @param path - Directory path to list
+	* @param sessionId - The session ID for this operation
+	* @param options - Optional settings (recursive, includeHidden)
+	*/
+	async listFiles(path, sessionId, options) {
+		try {
+			const data = {
+				path,
+				sessionId,
+				options: options || {}
+			};
+			const response = await this.post("/api/list-files", data);
+			this.logSuccess("Files listed", `${path} (${response.count} files)`);
+			return response;
+		} catch (error) {
+			this.logError("listFiles", error);
+			throw error;
+		}
+	}
+	/**
+	* Check if a file or directory exists
+	* @param path - Path to check
+	* @param sessionId - The session ID for this operation
+	*/
+	async exists(path, sessionId) {
+		try {
+			const data = {
+				path,
+				sessionId
+			};
+			const response = await this.post("/api/exists", data);
+			this.logSuccess("Path existence checked", `${path} (exists: ${response.exists})`);
+			return response;
+		} catch (error) {
+			this.logError("exists", error);
+			throw error;
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/git-client.ts
+/**
+* Client for Git repository operations
+*/
+var GitClient = class extends BaseHttpClient {
+	constructor(options = {}) {
+		super(options);
+		this.logger = new GitLogger(this.logger);
+	}
+	/**
+	* Clone a Git repository
+	* @param repoUrl - URL of the Git repository to clone
+	* @param sessionId - The session ID for this operation
+	* @param options - Optional settings (branch, targetDir)
+	*/
+	async checkout(repoUrl, sessionId, options) {
+		try {
+			let targetDir = options?.targetDir;
+			if (!targetDir) targetDir = `/workspace/${this.extractRepoName(repoUrl)}`;
+			const data = {
+				repoUrl,
+				sessionId,
+				targetDir
+			};
+			if (options?.branch) data.branch = options.branch;
+			const response = await this.post("/api/git/checkout", data);
+			this.logSuccess("Repository cloned", `${repoUrl} (branch: ${response.branch}) -> ${response.targetDir}`);
+			return response;
+		} catch (error) {
+			this.logError("checkout", error);
+			throw error;
+		}
+	}
+	/**
+	* Extract repository name from URL for default directory name
+	*/
+	extractRepoName(repoUrl) {
+		try {
+			const pathParts = new URL(repoUrl).pathname.split("/");
+			return pathParts[pathParts.length - 1].replace(/\.git$/, "");
+		} catch {
+			const parts = repoUrl.split("/");
+			return parts[parts.length - 1].replace(/\.git$/, "") || "repo";
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/interpreter-client.ts
+var InterpreterClient = class extends BaseHttpClient {
+	maxRetries = 3;
+	retryDelayMs = 1e3;
+	async createCodeContext(options = {}) {
+		return this.executeWithRetry(async () => {
+			const response = await this.doFetch("/api/contexts", {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({
+					language: options.language || "python",
+					cwd: options.cwd || "/workspace",
+					env_vars: options.envVars
+				})
+			});
+			if (!response.ok) throw await this.parseErrorResponse(response);
+			const data = await response.json();
+			if (!data.success) throw new Error(`Failed to create context: ${JSON.stringify(data)}`);
+			return {
+				id: data.contextId,
+				language: data.language,
+				cwd: data.cwd || "/workspace",
+				createdAt: new Date(data.timestamp),
+				lastUsed: new Date(data.timestamp)
+			};
+		});
+	}
+	async runCodeStream(contextId, code, language, callbacks, timeoutMs) {
+		return this.executeWithRetry(async () => {
+			const response = await this.doFetch("/api/execute/code", {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Accept: "text/event-stream"
+				},
+				body: JSON.stringify({
+					context_id: contextId,
+					code,
+					language,
+					...timeoutMs !== void 0 && { timeout_ms: timeoutMs }
+				})
+			});
+			if (!response.ok) throw await this.parseErrorResponse(response);
+			if (!response.body) throw new Error("No response body for streaming execution");
+			for await (const chunk of this.readLines(response.body)) await this.parseExecutionResult(chunk, callbacks);
+		});
+	}
+	async listCodeContexts() {
+		return this.executeWithRetry(async () => {
+			const response = await this.doFetch("/api/contexts", {
+				method: "GET",
+				headers: { "Content-Type": "application/json" }
+			});
+			if (!response.ok) throw await this.parseErrorResponse(response);
+			const data = await response.json();
+			if (!data.success) throw new Error(`Failed to list contexts: ${JSON.stringify(data)}`);
+			return data.contexts.map((ctx) => ({
+				id: ctx.id,
+				language: ctx.language,
+				cwd: ctx.cwd || "/workspace",
+				createdAt: new Date(data.timestamp),
+				lastUsed: new Date(data.timestamp)
+			}));
+		});
+	}
+	async deleteCodeContext(contextId) {
+		return this.executeWithRetry(async () => {
+			const response = await this.doFetch(`/api/contexts/${contextId}`, {
+				method: "DELETE",
+				headers: { "Content-Type": "application/json" }
+			});
+			if (!response.ok) throw await this.parseErrorResponse(response);
+		});
+	}
+	/**
+	* Execute an operation with automatic retry for transient errors
+	*/
+	async executeWithRetry(operation) {
+		let lastError;
+		for (let attempt = 0; attempt < this.maxRetries; attempt++) try {
+			return await operation();
+		} catch (error) {
+			this.logError("executeWithRetry", error);
+			lastError = error;
+			if (this.isRetryableError(error)) {
+				if (attempt < this.maxRetries - 1) {
+					const delay = this.retryDelayMs * 2 ** attempt + Math.random() * 1e3;
+					await new Promise((resolve) => setTimeout(resolve, delay));
+					continue;
+				}
+			}
+			throw error;
+		}
+		throw lastError || /* @__PURE__ */ new Error("Execution failed after retries");
+	}
+	isRetryableError(error) {
+		if (error instanceof InterpreterNotReadyError) return true;
+		if (error instanceof Error) return error.message.includes("not ready") || error.message.includes("initializing");
+		return false;
+	}
+	async parseErrorResponse(response) {
+		try {
+			return createErrorFromResponse(await response.json());
+		} catch {
+			return createErrorFromResponse({
+				code: ErrorCode.INTERNAL_ERROR,
+				message: `HTTP ${response.status}: ${response.statusText}`,
+				context: {},
+				httpStatus: response.status,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString()
+			});
+		}
+	}
+	async *readLines(stream) {
+		const reader = stream.getReader();
+		let buffer = "";
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (value) buffer += new TextDecoder().decode(value);
+				if (done) break;
+				let newlineIdx = buffer.indexOf("\n");
+				while (newlineIdx !== -1) {
+					yield buffer.slice(0, newlineIdx);
+					buffer = buffer.slice(newlineIdx + 1);
+					newlineIdx = buffer.indexOf("\n");
+				}
+			}
+			if (buffer.length > 0) yield buffer;
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	async parseExecutionResult(line, callbacks) {
+		if (!line.trim()) return;
+		if (!line.startsWith("data: ")) return;
+		try {
+			const jsonData = line.substring(6);
+			const data = JSON.parse(jsonData);
+			switch (data.type) {
+				case "stdout":
+					if (callbacks.onStdout && data.text) await callbacks.onStdout({
+						text: data.text,
+						timestamp: data.timestamp || Date.now()
+					});
+					break;
+				case "stderr":
+					if (callbacks.onStderr && data.text) await callbacks.onStderr({
+						text: data.text,
+						timestamp: data.timestamp || Date.now()
+					});
+					break;
+				case "result":
+					if (callbacks.onResult) {
+						const result = new ResultImpl(data);
+						await callbacks.onResult(result);
+					}
+					break;
+				case "error":
+					if (callbacks.onError) await callbacks.onError({
+						name: data.ename || "Error",
+						message: data.evalue || "Unknown error",
+						traceback: data.traceback || []
+					});
+					break;
+				case "execution_complete": break;
+			}
+		} catch (error) {
+			this.logError("parseExecutionResult", error);
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/port-client.ts
+/**
+* Client for port management and preview URL operations
+*/
+var PortClient = class extends BaseHttpClient {
+	/**
+	* Expose a port and get a preview URL
+	* @param port - Port number to expose
+	* @param sessionId - The session ID for this operation
+	* @param name - Optional name for the port
+	*/
+	async exposePort(port, sessionId, name) {
+		try {
+			const data = {
+				port,
+				sessionId,
+				name
+			};
+			const response = await this.post("/api/expose-port", data);
+			this.logSuccess("Port exposed", `${port} exposed at ${response.url}${name ? ` (${name})` : ""}`);
+			return response;
+		} catch (error) {
+			this.logError("exposePort", error);
+			throw error;
+		}
+	}
+	/**
+	* Unexpose a port and remove its preview URL
+	* @param port - Port number to unexpose
+	* @param sessionId - The session ID for this operation
+	*/
+	async unexposePort(port, sessionId) {
+		try {
+			const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
+			const response = await this.delete(url);
+			this.logSuccess("Port unexposed", `${port}`);
+			return response;
+		} catch (error) {
+			this.logError("unexposePort", error);
+			throw error;
+		}
+	}
+	/**
+	* Get all currently exposed ports
+	* @param sessionId - The session ID for this operation
+	*/
+	async getExposedPorts(sessionId) {
+		try {
+			const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
+			const response = await this.get(url);
+			this.logSuccess("Exposed ports retrieved", `${response.ports.length} ports exposed`);
+			return response;
+		} catch (error) {
+			this.logError("getExposedPorts", error);
+			throw error;
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/process-client.ts
+/**
+* Client for background process management
+*/
+var ProcessClient = class extends BaseHttpClient {
+	/**
+	* Start a background process
+	* @param command - Command to execute as a background process
+	* @param sessionId - The session ID for this operation
+	* @param options - Optional settings (processId)
+	*/
+	async startProcess(command, sessionId, options) {
+		try {
+			const data = {
+				command,
+				sessionId,
+				processId: options?.processId
+			};
+			const response = await this.post("/api/process/start", data);
+			this.logSuccess("Process started", `${command} (ID: ${response.processId})`);
+			return response;
+		} catch (error) {
+			this.logError("startProcess", error);
+			throw error;
+		}
+	}
+	/**
+	* List all processes (sandbox-scoped, not session-scoped)
+	*/
+	async listProcesses() {
+		try {
+			const response = await this.get(`/api/process/list`);
+			this.logSuccess("Processes listed", `${response.processes.length} processes`);
+			return response;
+		} catch (error) {
+			this.logError("listProcesses", error);
+			throw error;
+		}
+	}
+	/**
+	* Get information about a specific process (sandbox-scoped, not session-scoped)
+	* @param processId - ID of the process to retrieve
+	*/
+	async getProcess(processId) {
+		try {
+			const url = `/api/process/${processId}`;
+			const response = await this.get(url);
+			this.logSuccess("Process retrieved", `ID: ${processId}`);
+			return response;
+		} catch (error) {
+			this.logError("getProcess", error);
+			throw error;
+		}
+	}
+	/**
+	* Kill a specific process (sandbox-scoped, not session-scoped)
+	* @param processId - ID of the process to kill
+	*/
+	async killProcess(processId) {
+		try {
+			const url = `/api/process/${processId}`;
+			const response = await this.delete(url);
+			this.logSuccess("Process killed", `ID: ${processId}`);
+			return response;
+		} catch (error) {
+			this.logError("killProcess", error);
+			throw error;
+		}
+	}
+	/**
+	* Kill all running processes (sandbox-scoped, not session-scoped)
+	*/
+	async killAllProcesses() {
+		try {
+			const response = await this.delete(`/api/process/kill-all`);
+			this.logSuccess("All processes killed", `${response.cleanedCount} processes terminated`);
+			return response;
+		} catch (error) {
+			this.logError("killAllProcesses", error);
+			throw error;
+		}
+	}
+	/**
+	* Get logs from a specific process (sandbox-scoped, not session-scoped)
+	* @param processId - ID of the process to get logs from
+	*/
+	async getProcessLogs(processId) {
+		try {
+			const url = `/api/process/${processId}/logs`;
+			const response = await this.get(url);
+			this.logSuccess("Process logs retrieved", `ID: ${processId}, stdout: ${response.stdout.length} chars, stderr: ${response.stderr.length} chars`);
+			return response;
+		} catch (error) {
+			this.logError("getProcessLogs", error);
+			throw error;
+		}
+	}
+	/**
+	* Stream logs from a specific process (sandbox-scoped, not session-scoped)
+	* @param processId - ID of the process to stream logs from
+	*/
+	async streamProcessLogs(processId) {
+		try {
+			const url = `/api/process/${processId}/stream`;
+			const response = await this.doFetch(url, { method: "GET" });
+			const stream = await this.handleStreamResponse(response);
+			this.logSuccess("Process log stream started", `ID: ${processId}`);
+			return stream;
+		} catch (error) {
+			this.logError("streamProcessLogs", error);
+			throw error;
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/utility-client.ts
+/**
+* Client for health checks and utility operations
+*/
+var UtilityClient = class extends BaseHttpClient {
+	/**
+	* Ping the sandbox to check if it's responsive
+	*/
+	async ping() {
+		try {
+			const response = await this.get("/api/ping");
+			this.logSuccess("Ping successful", response.message);
+			return response.message;
+		} catch (error) {
+			this.logError("ping", error);
+			throw error;
+		}
+	}
+	/**
+	* Get list of available commands in the sandbox environment
+	*/
+	async getCommands() {
+		try {
+			const response = await this.get("/api/commands");
+			this.logSuccess("Commands retrieved", `${response.count} commands available`);
+			return response.availableCommands;
+		} catch (error) {
+			this.logError("getCommands", error);
+			throw error;
+		}
+	}
+	/**
+	* Create a new execution session
+	* @param options - Session configuration (id, env, cwd)
+	*/
+	async createSession(options) {
+		try {
+			const response = await this.post("/api/session/create", options);
+			this.logSuccess("Session created", `ID: ${options.id}`);
+			return response;
+		} catch (error) {
+			this.logError("createSession", error);
+			throw error;
+		}
+	}
+	/**
+	* Delete an execution session
+	* @param sessionId - Session ID to delete
+	*/
+	async deleteSession(sessionId) {
+		try {
+			const response = await this.post("/api/session/delete", { sessionId });
+			this.logSuccess("Session deleted", `ID: ${sessionId}`);
+			return response;
+		} catch (error) {
+			this.logError("deleteSession", error);
+			throw error;
+		}
+	}
+	/**
+	* Get the container version
+	* Returns the version embedded in the Docker image during build
+	*/
+	async getVersion() {
+		try {
+			const response = await this.get("/api/version");
+			this.logSuccess("Version retrieved", response.version);
+			return response.version;
+		} catch (error) {
+			this.logger.debug("Failed to get container version (may be old container)", { error });
+			return "unknown";
+		}
+	}
+};
+
+//#endregion
+//#region src/clients/sandbox-client.ts
+/**
+* Main sandbox client that composes all domain-specific clients
+* Provides organized access to all sandbox functionality
+*/
+var SandboxClient = class {
+	commands;
+	files;
+	processes;
+	ports;
+	git;
+	interpreter;
+	utils;
+	constructor(options) {
+		const clientOptions = {
+			baseUrl: "http://localhost:3000",
+			...options
+		};
+		this.commands = new CommandClient(clientOptions);
+		this.files = new FileClient(clientOptions);
+		this.processes = new ProcessClient(clientOptions);
+		this.ports = new PortClient(clientOptions);
+		this.git = new GitClient(clientOptions);
+		this.interpreter = new InterpreterClient(clientOptions);
+		this.utils = new UtilityClient(clientOptions);
+	}
+};
+
+//#endregion
+//#region src/security.ts
+/**
+* Security utilities for URL construction and input validation
+*
+* This module contains critical security functions to prevent:
+* - URL injection attacks
+* - SSRF (Server-Side Request Forgery) attacks
+* - DNS rebinding attacks
+* - Host header injection
+* - Open redirect vulnerabilities
+*/
+var SecurityError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "SecurityError";
+	}
+};
+/**
+* Validates port numbers for sandbox services
+* Only allows non-system ports to prevent conflicts and security issues
+*/
+function validatePort(port) {
+	if (!Number.isInteger(port)) return false;
+	if (port < 1024 || port > 65535) return false;
+	if ([3e3, 8787].includes(port)) return false;
+	return true;
+}
+/**
+* Sanitizes and validates sandbox IDs for DNS compliance and security
+* Only enforces critical requirements - allows maximum developer flexibility
+*/
+function sanitizeSandboxId(id) {
+	if (!id || id.length > 63) throw new SecurityError("Sandbox ID must be 1-63 characters long.", "INVALID_SANDBOX_ID_LENGTH");
+	if (id.startsWith("-") || id.endsWith("-")) throw new SecurityError("Sandbox ID cannot start or end with hyphens (DNS requirement).", "INVALID_SANDBOX_ID_HYPHENS");
+	const reservedNames = [
+		"www",
+		"api",
+		"admin",
+		"root",
+		"system",
+		"cloudflare",
+		"workers"
+	];
+	const lowerCaseId = id.toLowerCase();
+	if (reservedNames.includes(lowerCaseId)) throw new SecurityError(`Reserved sandbox ID '${id}' is not allowed.`, "RESERVED_SANDBOX_ID");
+	return id;
+}
+/**
+* Validates language for code interpreter
+* Only allows supported languages
+*/
+function validateLanguage(language) {
+	if (!language) return;
+	const supportedLanguages = [
+		"python",
+		"python3",
+		"javascript",
+		"js",
+		"node",
+		"typescript",
+		"ts"
+	];
+	const normalized = language.toLowerCase();
+	if (!supportedLanguages.includes(normalized)) throw new SecurityError(`Unsupported language '${language}'. Supported languages: python, javascript, typescript`, "INVALID_LANGUAGE");
+}
+
+//#endregion
+//#region src/interpreter.ts
+var CodeInterpreter = class {
+	interpreterClient;
+	contexts = /* @__PURE__ */ new Map();
+	constructor(sandbox) {
+		this.interpreterClient = sandbox.client.interpreter;
+	}
+	/**
+	* Create a new code execution context
+	*/
+	async createCodeContext(options = {}) {
+		validateLanguage(options.language);
+		const context = await this.interpreterClient.createCodeContext(options);
+		this.contexts.set(context.id, context);
+		return context;
+	}
+	/**
+	* Run code with optional context
+	*/
+	async runCode(code, options = {}) {
+		let context = options.context;
+		if (!context) {
+			const language = options.language || "python";
+			context = await this.getOrCreateDefaultContext(language);
+		}
+		const execution = new Execution(code, context);
+		await this.interpreterClient.runCodeStream(context.id, code, options.language, {
+			onStdout: (output) => {
+				execution.logs.stdout.push(output.text);
+				if (options.onStdout) return options.onStdout(output);
+			},
+			onStderr: (output) => {
+				execution.logs.stderr.push(output.text);
+				if (options.onStderr) return options.onStderr(output);
+			},
+			onResult: async (result) => {
+				execution.results.push(new ResultImpl(result));
+				if (options.onResult) return options.onResult(result);
+			},
+			onError: (error) => {
+				execution.error = error;
+				if (options.onError) return options.onError(error);
+			}
+		});
+		return execution;
+	}
+	/**
+	* Run code and return a streaming response
+	*/
+	async runCodeStream(code, options = {}) {
+		let context = options.context;
+		if (!context) {
+			const language = options.language || "python";
+			context = await this.getOrCreateDefaultContext(language);
+		}
+		const response = await this.interpreterClient.doFetch("/api/execute/code", {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: "text/event-stream"
+			},
+			body: JSON.stringify({
+				context_id: context.id,
+				code,
+				language: options.language
+			})
+		});
+		if (!response.ok) {
+			const errorData = await response.json().catch(() => ({ error: "Unknown error" }));
+			throw new Error(errorData.error || `Failed to execute code: ${response.status}`);
+		}
+		if (!response.body) throw new Error("No response body for streaming execution");
+		return response.body;
+	}
+	/**
+	* List all code contexts
+	*/
+	async listCodeContexts() {
+		const contexts = await this.interpreterClient.listCodeContexts();
+		for (const context of contexts) this.contexts.set(context.id, context);
+		return contexts;
+	}
+	/**
+	* Delete a code context
+	*/
+	async deleteCodeContext(contextId) {
+		await this.interpreterClient.deleteCodeContext(contextId);
+		this.contexts.delete(contextId);
+	}
+	async getOrCreateDefaultContext(language) {
+		for (const context of this.contexts.values()) if (context.language === language) return context;
+		return this.createCodeContext({ language });
+	}
+};
+
+//#endregion
+//#region src/request-handler.ts
+async function proxyToSandbox(request, env) {
+	const logger = createLogger({
+		component: "sandbox-do",
+		traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
+		operation: "proxy"
+	});
+	try {
+		const url = new URL(request.url);
+		const routeInfo = extractSandboxRoute(url);
+		if (!routeInfo) return null;
+		const { sandboxId, port, path, token } = routeInfo;
+		const sandbox = getSandbox(env.Sandbox, sandboxId);
+		if (port !== 3e3) {
+			if (!await sandbox.validatePortToken(port, token)) {
+				logger.warn("Invalid token access blocked", {
+					port,
+					sandboxId,
+					path,
+					hostname: url.hostname,
+					url: request.url,
+					method: request.method,
+					userAgent: request.headers.get("User-Agent") || "unknown"
+				});
+				return new Response(JSON.stringify({
+					error: `Access denied: Invalid token or port not exposed`,
+					code: "INVALID_TOKEN"
+				}), {
+					status: 404,
+					headers: { "Content-Type": "application/json" }
+				});
+			}
+		}
+		if (request.headers.get("Upgrade")?.toLowerCase() === "websocket") return await sandbox.fetch(switchPort(request, port));
+		let proxyUrl;
+		if (port !== 3e3) proxyUrl = `http://localhost:${port}${path}${url.search}`;
+		else proxyUrl = `http://localhost:3000${path}${url.search}`;
+		const proxyRequest = new Request(proxyUrl, {
+			method: request.method,
+			headers: {
+				...Object.fromEntries(request.headers),
+				"X-Original-URL": request.url,
+				"X-Forwarded-Host": url.hostname,
+				"X-Forwarded-Proto": url.protocol.replace(":", ""),
+				"X-Sandbox-Name": sandboxId
+			},
+			body: request.body,
+			duplex: "half"
+		});
+		return await sandbox.containerFetch(proxyRequest, port);
+	} catch (error) {
+		logger.error("Proxy routing error", error instanceof Error ? error : new Error(String(error)));
+		return new Response("Proxy routing error", { status: 500 });
+	}
+}
+function extractSandboxRoute(url) {
+	const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*?[^.-]|[^.-])-([a-z0-9_-]{16})\.(.+)$/);
+	if (!subdomainMatch) return null;
+	const portStr = subdomainMatch[1];
+	const sandboxId = subdomainMatch[2];
+	const token = subdomainMatch[3];
+	subdomainMatch[4];
+	const port = parseInt(portStr, 10);
+	if (!validatePort(port)) return null;
+	let sanitizedSandboxId;
+	try {
+		sanitizedSandboxId = sanitizeSandboxId(sandboxId);
+	} catch (error) {
+		return null;
+	}
+	if (sandboxId.length > 63) return null;
+	return {
+		port,
+		sandboxId: sanitizedSandboxId,
+		path: url.pathname || "/",
+		token
+	};
+}
+function isLocalhostPattern(hostname) {
+	if (hostname.startsWith("[")) if (hostname.includes("]:")) return hostname.substring(0, hostname.indexOf("]:") + 1) === "[::1]";
+	else return hostname === "[::1]";
+	if (hostname === "::1") return true;
+	const hostPart = hostname.split(":")[0];
+	return hostPart === "localhost" || hostPart === "127.0.0.1" || hostPart === "0.0.0.0";
+}
+
+//#endregion
+//#region src/sse-parser.ts
+/**
+* Server-Sent Events (SSE) parser for streaming responses
+* Converts ReadableStream<Uint8Array> to typed AsyncIterable<T>
+*/
+/**
+* Parse a ReadableStream of SSE events into typed AsyncIterable
+* @param stream - The ReadableStream from fetch response
+* @param signal - Optional AbortSignal for cancellation
+*/
+async function* parseSSEStream(stream, signal) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			if (signal?.aborted) throw new Error("Operation was aborted");
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+			for (const line of lines) {
+				if (line.trim() === "") continue;
+				if (line.startsWith("data: ")) {
+					const data = line.substring(6);
+					if (data === "[DONE]" || data.trim() === "") continue;
+					try {
+						yield JSON.parse(data);
+					} catch {}
+				}
+			}
+		}
+		if (buffer.trim() && buffer.startsWith("data: ")) {
+			const data = buffer.substring(6);
+			if (data !== "[DONE]" && data.trim()) try {
+				yield JSON.parse(data);
+			} catch {}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+/**
+* Helper to convert a Response with SSE stream directly to AsyncIterable
+* @param response - Response object with SSE stream
+* @param signal - Optional AbortSignal for cancellation
+*/
+async function* responseToAsyncIterable(response, signal) {
+	if (!response.ok) throw new Error(`Response not ok: ${response.status} ${response.statusText}`);
+	if (!response.body) throw new Error("No response body");
+	yield* parseSSEStream(response.body, signal);
+}
+/**
+* Create an SSE-formatted ReadableStream from an AsyncIterable
+* (Useful for Worker endpoints that need to forward AsyncIterable as SSE)
+* @param events - AsyncIterable of events
+* @param options - Stream options
+*/
+function asyncIterableToSSEStream(events, options) {
+	const encoder = new TextEncoder();
+	const serialize = options?.serialize || JSON.stringify;
+	return new ReadableStream({
+		async start(controller) {
+			try {
+				for await (const event of events) {
+					if (options?.signal?.aborted) {
+						controller.error(/* @__PURE__ */ new Error("Operation was aborted"));
+						break;
+					}
+					const sseEvent = `data: ${serialize(event)}\n\n`;
+					controller.enqueue(encoder.encode(sseEvent));
+				}
+				controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+			} catch (error) {
+				controller.error(error);
+			} finally {
+				controller.close();
+			}
+		},
+		cancel() {}
+	});
+}
+
+//#endregion
+//#region src/version.ts
+/**
+* SDK version - automatically synchronized with package.json by Changesets
+* 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.4.19";
+
+//#endregion
+//#region src/sandbox.ts
+function getSandbox(ns, id, options) {
+	const stub = getContainer(ns, id);
+	stub.setSandboxName?.(id);
+	if (options?.baseUrl) stub.setBaseUrl(options.baseUrl);
+	if (options?.sleepAfter !== void 0) stub.setSleepAfter(options.sleepAfter);
+	if (options?.keepAlive !== void 0) stub.setKeepAlive(options.keepAlive);
+	return Object.assign(stub, { wsConnect: connect(stub) });
+}
+function connect(stub) {
+	return async (request, port) => {
+		if (!validatePort(port)) throw new SecurityError(`Invalid or restricted port: ${port}. Ports must be in range 1024-65535 and not reserved.`);
+		const portSwitchedRequest = switchPort(request, port);
+		return await stub.fetch(portSwitchedRequest);
+	};
+}
+var Sandbox = class extends Container {
+	defaultPort = 3e3;
+	sleepAfter = "10m";
+	client;
+	codeInterpreter;
+	sandboxName = null;
+	baseUrl = null;
+	portTokens = /* @__PURE__ */ new Map();
+	defaultSession = null;
+	envVars = {};
+	logger;
+	keepAliveEnabled = false;
+	constructor(ctx, env) {
+		super(ctx, env);
+		const envObj = env;
+		["SANDBOX_LOG_LEVEL", "SANDBOX_LOG_FORMAT"].forEach((key) => {
+			if (envObj?.[key]) this.envVars[key] = envObj[key];
+		});
+		this.logger = createLogger({
+			component: "sandbox-do",
+			sandboxId: this.ctx.id.toString()
+		});
+		this.client = new SandboxClient({
+			logger: this.logger,
+			port: 3e3,
+			stub: this
+		});
+		this.codeInterpreter = new CodeInterpreter(this);
+		this.ctx.blockConcurrencyWhile(async () => {
+			this.sandboxName = await this.ctx.storage.get("sandboxName") || null;
+			this.defaultSession = await this.ctx.storage.get("defaultSession") || null;
+			const storedTokens = await this.ctx.storage.get("portTokens") || {};
+			this.portTokens = /* @__PURE__ */ new Map();
+			for (const [portStr, token] of Object.entries(storedTokens)) this.portTokens.set(parseInt(portStr, 10), token);
+		});
+	}
+	async setSandboxName(name) {
+		if (!this.sandboxName) {
+			this.sandboxName = name;
+			await this.ctx.storage.put("sandboxName", name);
+		}
+	}
+	async setBaseUrl(baseUrl) {
+		if (!this.baseUrl) {
+			this.baseUrl = baseUrl;
+			await this.ctx.storage.put("baseUrl", baseUrl);
+		} else if (this.baseUrl !== baseUrl) throw new Error("Base URL already set and different from one previously provided");
+	}
+	async setSleepAfter(sleepAfter) {
+		this.sleepAfter = sleepAfter;
+	}
+	async setKeepAlive(keepAlive) {
+		this.keepAliveEnabled = keepAlive;
+		if (keepAlive) this.logger.info("KeepAlive mode enabled - container will stay alive until explicitly destroyed");
+		else this.logger.info("KeepAlive mode disabled - container will timeout normally");
+	}
+	async setEnvVars(envVars) {
+		this.envVars = {
+			...this.envVars,
+			...envVars
+		};
+		if (this.defaultSession) for (const [key, value] of Object.entries(envVars)) {
+			const exportCommand = `export ${key}='${value.replace(/'/g, "'\\''")}'`;
+			const result = await this.client.commands.execute(exportCommand, this.defaultSession);
+			if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
+		}
+	}
+	/**
+	* Cleanup and destroy the sandbox container
+	*/
+	async destroy() {
+		this.logger.info("Destroying sandbox container");
+		await super.destroy();
+	}
+	onStart() {
+		this.logger.debug("Sandbox started");
+		this.checkVersionCompatibility().catch((error) => {
+			this.logger.error("Version compatibility check failed", error instanceof Error ? error : new Error(String(error)));
+		});
+	}
+	/**
+	* Check if the container version matches the SDK version
+	* Logs a warning if there's a mismatch
+	*/
+	async checkVersionCompatibility() {
+		try {
+			const sdkVersion = SDK_VERSION;
+			const containerVersion = await this.client.utils.getVersion();
+			if (containerVersion === "unknown") {
+				this.logger.warn("Container version check: Container version could not be determined. This may indicate an outdated container image. Please update your container to match SDK version " + sdkVersion);
+				return;
+			}
+			if (containerVersion !== sdkVersion) {
+				const message = `Version mismatch detected! SDK version (${sdkVersion}) does not match container version (${containerVersion}). This may cause compatibility issues. Please update your container image to version ${sdkVersion}`;
+				this.logger.warn(message);
+			} else this.logger.debug("Version check passed", {
+				sdkVersion,
+				containerVersion
+			});
+		} catch (error) {
+			this.logger.debug("Version compatibility check encountered an error", { error: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	onStop() {
+		this.logger.debug("Sandbox stopped");
+	}
+	onError(error) {
+		this.logger.error("Sandbox error", error instanceof Error ? error : new Error(String(error)));
+	}
+	/**
+	* Override onActivityExpired to prevent automatic shutdown when keepAlive is enabled
+	* When keepAlive is disabled, calls parent implementation which stops the container
+	*/
+	async onActivityExpired() {
+		if (this.keepAliveEnabled) this.logger.debug("Activity expired but keepAlive is enabled - container will stay alive");
+		else {
+			this.logger.debug("Activity expired - stopping container");
+			await super.onActivityExpired();
+		}
+	}
+	async fetch(request) {
+		const traceId = TraceContext.fromHeaders(request.headers) || TraceContext.generate();
+		const requestLogger = this.logger.child({
+			traceId,
+			operation: "fetch"
+		});
+		return await runWithLogger(requestLogger, async () => {
+			const url = new URL(request.url);
+			if (!this.sandboxName && request.headers.has("X-Sandbox-Name")) {
+				const name = request.headers.get("X-Sandbox-Name");
+				this.sandboxName = name;
+				await this.ctx.storage.put("sandboxName", name);
+			}
+			const upgradeHeader = request.headers.get("Upgrade");
+			const connectionHeader = request.headers.get("Connection");
+			if (upgradeHeader?.toLowerCase() === "websocket" && connectionHeader?.toLowerCase().includes("upgrade")) try {
+				requestLogger.debug("WebSocket upgrade requested", {
+					path: url.pathname,
+					port: this.determinePort(url)
+				});
+				return await super.fetch(request);
+			} catch (error) {
+				requestLogger.error("WebSocket connection failed", error instanceof Error ? error : new Error(String(error)), { path: url.pathname });
+				throw error;
+			}
+			const port = this.determinePort(url);
+			return await this.containerFetch(request, port);
+		});
+	}
+	wsConnect(request, port) {
+		throw new Error("Not implemented here to avoid RPC serialization issues");
+	}
+	determinePort(url) {
+		const proxyMatch = url.pathname.match(/^\/proxy\/(\d+)/);
+		if (proxyMatch) return parseInt(proxyMatch[1], 10);
+		return 3e3;
+	}
+	/**
+	* Ensure default session exists - lazy initialization
+	* This is called automatically by all public methods that need a session
+	*
+	* The session is persisted to Durable Object storage to survive hot reloads
+	* during development. If a session already exists in the container after reload,
+	* we reuse it instead of trying to create a new one.
+	*/
+	async ensureDefaultSession() {
+		if (!this.defaultSession) {
+			const sessionId = `sandbox-${this.sandboxName || "default"}`;
+			try {
+				await this.client.utils.createSession({
+					id: sessionId,
+					env: this.envVars || {},
+					cwd: "/workspace"
+				});
+				this.defaultSession = sessionId;
+				await this.ctx.storage.put("defaultSession", sessionId);
+				this.logger.debug("Default session initialized", { sessionId });
+			} catch (error) {
+				if (error?.message?.includes("already exists")) {
+					this.logger.debug("Reusing existing session after reload", { sessionId });
+					this.defaultSession = sessionId;
+					await this.ctx.storage.put("defaultSession", sessionId);
+				} else throw error;
+			}
+		}
+		return this.defaultSession;
+	}
+	async exec(command, options) {
+		const session = await this.ensureDefaultSession();
+		return this.execWithSession(command, session, options);
+	}
+	/**
+	* Internal session-aware exec implementation
+	* Used by both public exec() and session wrappers
+	*/
+	async execWithSession(command, sessionId, options) {
+		const startTime = Date.now();
+		const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+		try {
+			if (options?.signal?.aborted) throw new Error("Operation was aborted");
+			let result;
+			if (options?.stream && options?.onOutput) result = await this.executeWithStreaming(command, sessionId, options, startTime, timestamp);
+			else {
+				const response = await this.client.commands.execute(command, sessionId);
+				const duration = Date.now() - startTime;
+				result = this.mapExecuteResponseToExecResult(response, duration, sessionId);
+			}
+			if (options?.onComplete) options.onComplete(result);
+			return result;
+		} catch (error) {
+			if (options?.onError && error instanceof Error) options.onError(error);
+			throw error;
+		}
+	}
+	async executeWithStreaming(command, sessionId, options, startTime, timestamp) {
+		let stdout = "";
+		let stderr = "";
+		try {
+			const stream = await this.client.commands.executeStream(command, sessionId);
+			for await (const event of parseSSEStream(stream)) {
+				if (options.signal?.aborted) throw new Error("Operation was aborted");
+				switch (event.type) {
+					case "stdout":
+					case "stderr":
+						if (event.data) {
+							if (event.type === "stdout") stdout += event.data;
+							if (event.type === "stderr") stderr += event.data;
+							if (options.onOutput) options.onOutput(event.type, event.data);
+						}
+						break;
+					case "complete": {
+						const duration = Date.now() - startTime;
+						return {
+							success: (event.exitCode ?? 0) === 0,
+							exitCode: event.exitCode ?? 0,
+							stdout,
+							stderr,
+							command,
+							duration,
+							timestamp,
+							sessionId
+						};
+					}
+					case "error": throw new Error(event.data || "Command execution failed");
+				}
+			}
+			throw new Error("Stream ended without completion event");
+		} catch (error) {
+			if (options.signal?.aborted) throw new Error("Operation was aborted");
+			throw error;
+		}
+	}
+	mapExecuteResponseToExecResult(response, duration, sessionId) {
+		return {
+			success: response.success,
+			exitCode: response.exitCode,
+			stdout: response.stdout,
+			stderr: response.stderr,
+			command: response.command,
+			duration,
+			timestamp: response.timestamp,
+			sessionId
+		};
+	}
+	/**
+	* Create a Process domain object from HTTP client DTO
+	* Centralizes process object creation with bound methods
+	* This eliminates duplication across startProcess, listProcesses, getProcess, and session wrappers
+	*/
+	createProcessFromDTO(data, sessionId) {
+		return {
+			id: data.id,
+			pid: data.pid,
+			command: data.command,
+			status: data.status,
+			startTime: typeof data.startTime === "string" ? new Date(data.startTime) : data.startTime,
+			endTime: data.endTime ? typeof data.endTime === "string" ? new Date(data.endTime) : data.endTime : void 0,
+			exitCode: data.exitCode,
+			sessionId,
+			kill: async (signal) => {
+				await this.killProcess(data.id, signal);
+			},
+			getStatus: async () => {
+				return (await this.getProcess(data.id))?.status || "error";
+			},
+			getLogs: async () => {
+				const logs = await this.getProcessLogs(data.id);
+				return {
+					stdout: logs.stdout,
+					stderr: logs.stderr
+				};
+			}
+		};
+	}
+	async startProcess(command, options, sessionId) {
+		try {
+			const session = sessionId ?? await this.ensureDefaultSession();
+			const response = await this.client.processes.startProcess(command, session, { processId: options?.processId });
+			const processObj = this.createProcessFromDTO({
+				id: response.processId,
+				pid: response.pid,
+				command: response.command,
+				status: "running",
+				startTime: /* @__PURE__ */ new Date(),
+				endTime: void 0,
+				exitCode: void 0
+			}, session);
+			if (options?.onStart) options.onStart(processObj);
+			return processObj;
+		} catch (error) {
+			if (options?.onError && error instanceof Error) options.onError(error);
+			throw error;
+		}
+	}
+	async listProcesses(sessionId) {
+		const session = sessionId ?? await this.ensureDefaultSession();
+		return (await this.client.processes.listProcesses()).processes.map((processData) => this.createProcessFromDTO({
+			id: processData.id,
+			pid: processData.pid,
+			command: processData.command,
+			status: processData.status,
+			startTime: processData.startTime,
+			endTime: processData.endTime,
+			exitCode: processData.exitCode
+		}, 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);
+	}
+	async killProcess(id, signal, sessionId) {
+		await this.client.processes.killProcess(id);
+	}
+	async killAllProcesses(sessionId) {
+		return (await this.client.processes.killAllProcesses()).cleanedCount;
+	}
+	async cleanupCompletedProcesses(sessionId) {
+		return 0;
+	}
+	async getProcessLogs(id, sessionId) {
+		const response = await this.client.processes.getProcessLogs(id);
+		return {
+			stdout: response.stdout,
+			stderr: response.stderr,
+			processId: response.processId
+		};
+	}
+	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);
+	}
+	/**
+	* 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);
+	}
+	/**
+	* Stream logs from a background process as a ReadableStream.
+	*/
+	async streamProcessLogs(processId, options) {
+		if (options?.signal?.aborted) throw new Error("Operation was aborted");
+		return this.client.processes.streamProcessLogs(processId);
+	}
+	async gitCheckout(repoUrl, options) {
+		const session = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.git.checkout(repoUrl, session, {
+			branch: options.branch,
+			targetDir: options.targetDir
+		});
+	}
+	async mkdir(path, options = {}) {
+		const session = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.mkdir(path, session, { recursive: options.recursive });
+	}
+	async writeFile(path, content, options = {}) {
+		const session = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.writeFile(path, content, session, { encoding: options.encoding });
+	}
+	async deleteFile(path, sessionId) {
+		const session = sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.deleteFile(path, session);
+	}
+	async renameFile(oldPath, newPath, sessionId) {
+		const session = sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.renameFile(oldPath, newPath, session);
+	}
+	async moveFile(sourcePath, destinationPath, sessionId) {
+		const session = sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.moveFile(sourcePath, destinationPath, session);
+	}
+	async readFile(path, options = {}) {
+		const session = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.readFile(path, session, { encoding: options.encoding });
+	}
+	/**
+	* Stream a file from the sandbox using Server-Sent Events
+	* Returns a ReadableStream that can be consumed with streamFile() or collectFile() utilities
+	* @param path - Path to the file to stream
+	* @param options - Optional session ID
+	*/
+	async readFileStream(path, options = {}) {
+		const session = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.readFileStream(path, session);
+	}
+	async listFiles(path, options) {
+		const session = await this.ensureDefaultSession();
+		return this.client.files.listFiles(path, session, options);
+	}
+	async exists(path, sessionId) {
+		const session = sessionId ?? await this.ensureDefaultSession();
+		return this.client.files.exists(path, session);
+	}
+	async exposePort(port, options) {
+		if (options.hostname.endsWith(".workers.dev")) throw new CustomDomainRequiredError({
+			code: ErrorCode.CUSTOM_DOMAIN_REQUIRED,
+			message: `Port exposure requires a custom domain. .workers.dev domains do not support wildcard subdomains required for port proxying.`,
+			context: { originalError: options.hostname },
+			httpStatus: 400,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const sessionId = await this.ensureDefaultSession();
+		await this.client.ports.exposePort(port, sessionId, options?.name);
+		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
+		const token = this.generatePortToken();
+		this.portTokens.set(port, token);
+		await this.persistPortTokens();
+		return {
+			url: this.constructPreviewUrl(port, this.sandboxName, options.hostname, token),
+			port,
+			name: options?.name
+		};
+	}
+	async unexposePort(port) {
+		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be between 1024-65535 and not reserved.`);
+		const sessionId = await this.ensureDefaultSession();
+		await this.client.ports.unexposePort(port, sessionId);
+		if (this.portTokens.has(port)) {
+			this.portTokens.delete(port);
+			await this.persistPortTokens();
+		}
+	}
+	async getExposedPorts(hostname) {
+		const sessionId = await this.ensureDefaultSession();
+		const response = await this.client.ports.getExposedPorts(sessionId);
+		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
+		return response.ports.map((port) => {
+			const token = this.portTokens.get(port.port);
+			if (!token) throw new Error(`Port ${port.port} is exposed but has no token. This should not happen.`);
+			return {
+				url: this.constructPreviewUrl(port.port, this.sandboxName, hostname, token),
+				port: port.port,
+				status: port.status
+			};
+		});
+	}
+	async isPortExposed(port) {
+		try {
+			const sessionId = await this.ensureDefaultSession();
+			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 });
+			return false;
+		}
+	}
+	async validatePortToken(port, token) {
+		if (!await this.isPortExposed(port)) return false;
+		const storedToken = this.portTokens.get(port);
+		if (!storedToken) {
+			this.logger.error("Port is exposed but has no token - bug detected", void 0, { port });
+			return false;
+		}
+		return storedToken === token;
+	}
+	generatePortToken() {
+		const array = new Uint8Array(12);
+		crypto.getRandomValues(array);
+		return btoa(String.fromCharCode(...array)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "").toLowerCase();
+	}
+	async persistPortTokens() {
+		const tokensObj = {};
+		for (const [port, token] of this.portTokens.entries()) tokensObj[port.toString()] = token;
+		await this.ctx.storage.put("portTokens", tokensObj);
+	}
+	constructPreviewUrl(port, sandboxId, hostname, token) {
+		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be between 1024-65535 and not reserved.`);
+		const sanitizedSandboxId = sanitizeSandboxId(sandboxId);
+		if (isLocalhostPattern(hostname)) {
+			const [host, portStr] = hostname.split(":");
+			const mainPort = portStr || "80";
+			try {
+				const baseUrl = new URL(`http://${host}:${mainPort}`);
+				baseUrl.hostname = `${port}-${sanitizedSandboxId}-${token}.${host}`;
+				return baseUrl.toString();
+			} catch (error) {
+				throw new SecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
+		}
+		try {
+			const baseUrl = new URL(`https://${hostname}`);
+			baseUrl.hostname = `${port}-${sanitizedSandboxId}-${token}.${hostname}`;
+			return baseUrl.toString();
+		} catch (error) {
+			throw new SecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+		}
+	}
+	/**
+	* Create isolated execution session for advanced use cases
+	* Returns ExecutionSession with full sandbox API bound to specific session
+	*/
+	async createSession(options) {
+		const sessionId = options?.id || `session-${Date.now()}`;
+		await this.client.utils.createSession({
+			id: sessionId,
+			env: options?.env,
+			cwd: options?.cwd
+		});
+		return this.getSessionWrapper(sessionId);
+	}
+	/**
+	* Get an existing session by ID
+	* Returns ExecutionSession wrapper bound to the specified session
+	*
+	* This is useful for retrieving sessions across different requests/contexts
+	* without storing the ExecutionSession object (which has RPC lifecycle limitations)
+	*
+	* @param sessionId - The ID of an existing session
+	* @returns ExecutionSession wrapper bound to the session
+	*/
+	async getSession(sessionId) {
+		return this.getSessionWrapper(sessionId);
+	}
+	/**
+	* Delete an execution session
+	* Cleans up session resources and removes it from the container
+	* Note: Cannot delete the default session. To reset the default session,
+	* use sandbox.destroy() to terminate the entire sandbox.
+	*
+	* @param sessionId - The ID of the session to delete
+	* @returns Result with success status, sessionId, and timestamp
+	* @throws Error if attempting to delete the default session
+	*/
+	async deleteSession(sessionId) {
+		if (this.defaultSession && sessionId === this.defaultSession) throw new Error(`Cannot delete default session '${sessionId}'. Use sandbox.destroy() to terminate the sandbox.`);
+		const response = await this.client.utils.deleteSession(sessionId);
+		return {
+			success: response.success,
+			sessionId: response.sessionId,
+			timestamp: response.timestamp
+		};
+	}
+	/**
+	* Internal helper to create ExecutionSession wrapper for a given sessionId
+	* Used by both createSession and getSession
+	*/
+	getSessionWrapper(sessionId) {
+		return {
+			id: sessionId,
+			exec: (command, options) => this.execWithSession(command, sessionId, options),
+			execStream: (command, options) => this.execStreamWithSession(command, sessionId, options),
+			startProcess: (command, options) => this.startProcess(command, options, sessionId),
+			listProcesses: () => this.listProcesses(sessionId),
+			getProcess: (id) => this.getProcess(id, sessionId),
+			killProcess: (id, signal) => this.killProcess(id, signal),
+			killAllProcesses: () => this.killAllProcesses(),
+			cleanupCompletedProcesses: () => this.cleanupCompletedProcesses(),
+			getProcessLogs: (id) => this.getProcessLogs(id),
+			streamProcessLogs: (processId, options) => this.streamProcessLogs(processId, options),
+			writeFile: (path, content, options) => this.writeFile(path, content, {
+				...options,
+				sessionId
+			}),
+			readFile: (path, options) => this.readFile(path, {
+				...options,
+				sessionId
+			}),
+			readFileStream: (path) => this.readFileStream(path, { sessionId }),
+			mkdir: (path, options) => this.mkdir(path, {
+				...options,
+				sessionId
+			}),
+			deleteFile: (path) => this.deleteFile(path, sessionId),
+			renameFile: (oldPath, newPath) => this.renameFile(oldPath, newPath, sessionId),
+			moveFile: (sourcePath, destPath) => this.moveFile(sourcePath, destPath, sessionId),
+			listFiles: (path, options) => this.client.files.listFiles(path, sessionId, options),
+			exists: (path) => this.exists(path, sessionId),
+			gitCheckout: (repoUrl, options) => this.gitCheckout(repoUrl, {
+				...options,
+				sessionId
+			}),
+			setEnvVars: async (envVars) => {
+				try {
+					for (const [key, value] of Object.entries(envVars)) {
+						const exportCommand = `export ${key}='${value.replace(/'/g, "'\\''")}'`;
+						const result = await this.client.commands.execute(exportCommand, sessionId);
+						if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
+					}
+				} catch (error) {
+					this.logger.error("Failed to set environment variables", error instanceof Error ? error : new Error(String(error)), { sessionId });
+					throw error;
+				}
+			},
+			createCodeContext: (options) => this.codeInterpreter.createCodeContext(options),
+			runCode: async (code, options) => {
+				return (await this.codeInterpreter.runCode(code, options)).toJSON();
+			},
+			runCodeStream: (code, options) => this.codeInterpreter.runCodeStream(code, options),
+			listCodeContexts: () => this.codeInterpreter.listCodeContexts(),
+			deleteCodeContext: (contextId) => this.codeInterpreter.deleteCodeContext(contextId)
+		};
+	}
+	async createCodeContext(options) {
+		return this.codeInterpreter.createCodeContext(options);
+	}
+	async runCode(code, options) {
+		return (await this.codeInterpreter.runCode(code, options)).toJSON();
+	}
+	async runCodeStream(code, options) {
+		return this.codeInterpreter.runCodeStream(code, options);
+	}
+	async listCodeContexts() {
+		return this.codeInterpreter.listCodeContexts();
+	}
+	async deleteCodeContext(contextId) {
+		return this.codeInterpreter.deleteCodeContext(contextId);
+	}
+};
+
+//#endregion
+//#region src/file-stream.ts
+/**
+* Parse SSE (Server-Sent Events) lines from a stream
+*/
+async function* parseSSE(stream) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split("\n");
+			buffer = lines.pop() || "";
+			for (const line of lines) if (line.startsWith("data: ")) {
+				const data = line.slice(6);
+				try {
+					yield JSON.parse(data);
+				} catch {}
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+/**
+* Stream a file from the sandbox with automatic base64 decoding for binary files
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
+*
+* @example
+* ```ts
+* const stream = await sandbox.readFileStream('/path/to/file.png');
+* for await (const chunk of streamFile(stream)) {
+*   if (chunk instanceof Uint8Array) {
+*     // Binary chunk
+*     console.log('Binary chunk:', chunk.length, 'bytes');
+*   } else {
+*     // Text chunk
+*     console.log('Text chunk:', chunk);
+*   }
+* }
+* ```
+*/
+async function* streamFile(stream) {
+	let metadata = null;
+	for await (const event of parseSSE(stream)) switch (event.type) {
+		case "metadata":
+			metadata = {
+				mimeType: event.mimeType,
+				size: event.size,
+				isBinary: event.isBinary,
+				encoding: event.encoding
+			};
+			break;
+		case "chunk":
+			if (!metadata) throw new Error("Received chunk before metadata");
+			if (metadata.isBinary && metadata.encoding === "base64") {
+				const binaryString = atob(event.data);
+				const bytes = new Uint8Array(binaryString.length);
+				for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+				yield bytes;
+			} else yield event.data;
+			break;
+		case "complete":
+			if (!metadata) throw new Error("Stream completed without metadata");
+			return metadata;
+		case "error": throw new Error(`File streaming error: ${event.error}`);
+	}
+	throw new Error("Stream ended unexpectedly");
+}
+/**
+* Collect an entire file into memory from a stream
+*
+* @param stream - The ReadableStream from readFileStream()
+* @returns Object containing the file content and metadata
+*
+* @example
+* ```ts
+* const stream = await sandbox.readFileStream('/path/to/file.txt');
+* const { content, metadata } = await collectFile(stream);
+* console.log('Content:', content);
+* console.log('MIME type:', metadata.mimeType);
+* ```
+*/
+async function collectFile(stream) {
+	const chunks = [];
+	const generator = streamFile(stream);
+	let result = await generator.next();
+	while (!result.done) {
+		chunks.push(result.value);
+		result = await generator.next();
+	}
+	const metadata = result.value;
+	if (!metadata) throw new Error("Failed to get file metadata");
+	if (metadata.isBinary) {
+		const totalLength = chunks.reduce((sum, chunk) => sum + (chunk instanceof Uint8Array ? chunk.length : 0), 0);
+		const combined = new Uint8Array(totalLength);
+		let offset = 0;
+		for (const chunk of chunks) if (chunk instanceof Uint8Array) {
+			combined.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return {
+			content: combined,
+			metadata
+		};
+	} else return {
+		content: chunks.filter((c) => typeof c === "string").join(""),
+		metadata
+	};
+}
+
+//#endregion
+export { CodeInterpreter, CommandClient, Execution, FileClient, GitClient, GitLogger, LogLevel as LogLevelEnum, PortClient, ProcessClient, ResultImpl, Sandbox, SandboxClient, TraceContext, UtilityClient, asyncIterableToSSEStream, collectFile, createLogger, createNoOpLogger, getLogger, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, redactCredentials, responseToAsyncIterable, runWithLogger, sanitizeGitData, streamFile };
 //# sourceMappingURL=index.js.map