@cloudflare/sandbox 0.3.6 → 0.4.1

package/dist/chunk-HGF554LH.js

@@ -0,0 +1,2236 @@
+import {
+  CodeInterpreter
+} from "./chunk-BCJ7SF3Q.js";
+import {
+  SecurityError,
+  sanitizeSandboxId,
+  validatePort
+} from "./chunk-Z532A7QC.js";
+import {
+  parseSSEStream
+} from "./chunk-EKSWCBCA.js";
+
+// src/request-handler.ts
+import { createLogger as createLogger2, TraceContext as TraceContext2 } from "@repo/shared";
+
+// src/sandbox.ts
+import { Container, getContainer } from "@cloudflare/containers";
+import { createLogger, runWithLogger, TraceContext } from "@repo/shared";
+
+// src/clients/base-client.ts
+import { createNoOpLogger } from "@repo/shared";
+
+// src/errors/index.ts
+import { ErrorCode as ErrorCode2, Operation } from "@repo/shared/errors";
+
+// src/errors/adapter.ts
+import { ErrorCode } from "@repo/shared/errors";
+
+// src/errors/classes.ts
+var SandboxError = class extends Error {
+  constructor(errorResponse) {
+    super(errorResponse.message);
+    this.errorResponse = errorResponse;
+    this.name = "SandboxError";
+  }
+  // Convenience accessors
+  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;
+  }
+  // Custom serialization for logging
+  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
+    };
+  }
+};
+var FileNotFoundError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "FileNotFoundError";
+  }
+  // Type-safe accessors
+  get path() {
+    return this.context.path;
+  }
+};
+var FileExistsError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "FileExistsError";
+  }
+  // Type-safe accessor
+  get path() {
+    return this.context.path;
+  }
+};
+var FileSystemError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "FileSystemError";
+  }
+  // Type-safe accessors
+  get path() {
+    return this.context.path;
+  }
+  get stderr() {
+    return this.context.stderr;
+  }
+  get exitCode() {
+    return this.context.exitCode;
+  }
+};
+var PermissionDeniedError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "PermissionDeniedError";
+  }
+  get path() {
+    return this.context.path;
+  }
+};
+var CommandNotFoundError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "CommandNotFoundError";
+  }
+  // Type-safe accessor
+  get command() {
+    return this.context.command;
+  }
+};
+var CommandError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "CommandError";
+  }
+  // Type-safe accessors
+  get command() {
+    return this.context.command;
+  }
+  get exitCode() {
+    return this.context.exitCode;
+  }
+  get stdout() {
+    return this.context.stdout;
+  }
+  get stderr() {
+    return this.context.stderr;
+  }
+};
+var ProcessNotFoundError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "ProcessNotFoundError";
+  }
+  // Type-safe accessor
+  get processId() {
+    return this.context.processId;
+  }
+};
+var ProcessError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "ProcessError";
+  }
+  // Type-safe accessors
+  get processId() {
+    return this.context.processId;
+  }
+  get pid() {
+    return this.context.pid;
+  }
+  get exitCode() {
+    return this.context.exitCode;
+  }
+  get stderr() {
+    return this.context.stderr;
+  }
+};
+var PortAlreadyExposedError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "PortAlreadyExposedError";
+  }
+  // Type-safe accessors
+  get port() {
+    return this.context.port;
+  }
+  get portName() {
+    return this.context.portName;
+  }
+};
+var PortNotExposedError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "PortNotExposedError";
+  }
+  // Type-safe accessor
+  get port() {
+    return this.context.port;
+  }
+};
+var InvalidPortError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "InvalidPortError";
+  }
+  // Type-safe accessors
+  get port() {
+    return this.context.port;
+  }
+  get reason() {
+    return this.context.reason;
+  }
+};
+var ServiceNotRespondingError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "ServiceNotRespondingError";
+  }
+  // Type-safe accessors
+  get port() {
+    return this.context.port;
+  }
+  get portName() {
+    return this.context.portName;
+  }
+};
+var PortInUseError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "PortInUseError";
+  }
+  // Type-safe accessor
+  get port() {
+    return this.context.port;
+  }
+};
+var PortError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "PortError";
+  }
+  // Type-safe accessors
+  get port() {
+    return this.context.port;
+  }
+  get portName() {
+    return this.context.portName;
+  }
+  get stderr() {
+    return this.context.stderr;
+  }
+};
+var CustomDomainRequiredError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "CustomDomainRequiredError";
+  }
+};
+var GitRepositoryNotFoundError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitRepositoryNotFoundError";
+  }
+  // Type-safe accessor
+  get repository() {
+    return this.context.repository;
+  }
+};
+var GitAuthenticationError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitAuthenticationError";
+  }
+  // Type-safe accessor
+  get repository() {
+    return this.context.repository;
+  }
+};
+var GitBranchNotFoundError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitBranchNotFoundError";
+  }
+  // Type-safe accessors
+  get branch() {
+    return this.context.branch;
+  }
+  get repository() {
+    return this.context.repository;
+  }
+};
+var GitNetworkError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitNetworkError";
+  }
+  // Type-safe accessors
+  get repository() {
+    return this.context.repository;
+  }
+  get branch() {
+    return this.context.branch;
+  }
+  get targetDir() {
+    return this.context.targetDir;
+  }
+};
+var GitCloneError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitCloneError";
+  }
+  // Type-safe accessors
+  get repository() {
+    return this.context.repository;
+  }
+  get targetDir() {
+    return this.context.targetDir;
+  }
+  get stderr() {
+    return this.context.stderr;
+  }
+  get exitCode() {
+    return this.context.exitCode;
+  }
+};
+var GitCheckoutError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitCheckoutError";
+  }
+  // Type-safe accessors
+  get branch() {
+    return this.context.branch;
+  }
+  get repository() {
+    return this.context.repository;
+  }
+  get stderr() {
+    return this.context.stderr;
+  }
+};
+var InvalidGitUrlError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "InvalidGitUrlError";
+  }
+  // Type-safe accessor
+  get validationErrors() {
+    return this.context.validationErrors;
+  }
+};
+var GitError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "GitError";
+  }
+  // Type-safe accessors
+  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;
+  }
+};
+var InterpreterNotReadyError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "InterpreterNotReadyError";
+  }
+  // Type-safe accessors
+  get retryAfter() {
+    return this.context.retryAfter;
+  }
+  get progress() {
+    return this.context.progress;
+  }
+};
+var ContextNotFoundError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "ContextNotFoundError";
+  }
+  // Type-safe accessor
+  get contextId() {
+    return this.context.contextId;
+  }
+};
+var CodeExecutionError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "CodeExecutionError";
+  }
+  // Type-safe accessors
+  get contextId() {
+    return this.context.contextId;
+  }
+  get ename() {
+    return this.context.ename;
+  }
+  get evalue() {
+    return this.context.evalue;
+  }
+  get traceback() {
+    return this.context.traceback;
+  }
+};
+var ValidationFailedError = class extends SandboxError {
+  constructor(errorResponse) {
+    super(errorResponse);
+    this.name = "ValidationFailedError";
+  }
+  // Type-safe accessor
+  get validationErrors() {
+    return this.context.validationErrors;
+  }
+};
+
+// src/errors/adapter.ts
+function createErrorFromResponse(errorResponse) {
+  switch (errorResponse.code) {
+    // File System Errors
+    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);
+    // Command Errors
+    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);
+    // Process Errors
+    case ErrorCode.PROCESS_NOT_FOUND:
+      return new ProcessNotFoundError(errorResponse);
+    case ErrorCode.PROCESS_PERMISSION_DENIED:
+    case ErrorCode.PROCESS_ERROR:
+      return new ProcessError(errorResponse);
+    // Port Errors
+    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);
+    // Git Errors
+    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);
+    // Code Interpreter Errors
+    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);
+    // Validation Errors
+    case ErrorCode.VALIDATION_FAILED:
+      return new ValidationFailedError(errorResponse);
+    // Generic Errors
+    case ErrorCode.INVALID_JSON_RESPONSE:
+    case ErrorCode.UNKNOWN_ERROR:
+    case ErrorCode.INTERNAL_ERROR:
+      return new SandboxError(errorResponse);
+    default:
+      return new SandboxError(errorResponse);
+  }
+}
+
+// src/clients/base-client.ts
+var TIMEOUT_MS = 6e4;
+var MIN_TIME_FOR_RETRY_MS = 1e4;
+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) {
+        const isContainerProvisioning = await this.isContainerProvisioningError(response);
+        if (isContainerProvisioning) {
+          const elapsed = Date.now() - startTime;
+          const remaining = TIMEOUT_MS - elapsed;
+          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", 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) {
+      const errorResponse = {
+        code: ErrorCode2.INVALID_JSON_RESPONSE,
+        message: `Invalid JSON response: ${error instanceof Error ? error.message : "Unknown parsing error"}`,
+        context: {},
+        httpStatus: response.status,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      throw createErrorFromResponse(errorResponse);
+    }
+  }
+  /**
+   * Handle error responses with consistent error throwing
+   */
+  async handleErrorResponse(response) {
+    let errorData;
+    try {
+      errorData = await response.json();
+    } catch {
+      errorData = {
+        code: ErrorCode2.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 {
+      const cloned = response.clone();
+      const text = await cloned.text();
+      return 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;
+    }
+  }
+};
+
+// src/clients/command-client.ts
+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;
+    }
+  }
+};
+
+// src/clients/file-client.ts
+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 ?? "utf8"
+      };
+      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 ?? "utf8"
+      };
+      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;
+    }
+  }
+};
+
+// src/clients/git-client.ts
+var GitClient = class extends BaseHttpClient {
+  /**
+   * 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) {
+        const repoName = this.extractRepoName(repoUrl);
+        targetDir = `/workspace/${repoName}`;
+      }
+      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 url = new URL(repoUrl);
+      const pathParts = url.pathname.split("/");
+      const repoName = pathParts[pathParts.length - 1];
+      return repoName.replace(/\.git$/, "");
+    } catch {
+      const parts = repoUrl.split("/");
+      const repoName = parts[parts.length - 1];
+      return repoName.replace(/\.git$/, "") || "repo";
+    }
+  }
+};
+
+// src/clients/interpreter-client.ts
+import {
+  ResultImpl
+} from "@repo/shared";
+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) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+      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) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+      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) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+      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) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+    });
+  }
+  /**
+   * 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 || 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 {
+      const errorData = await response.json();
+      return createErrorFromResponse(errorData);
+    } catch {
+      const errorResponse = {
+        code: ErrorCode2.INTERNAL_ERROR,
+        message: `HTTP ${response.status}: ${response.statusText}`,
+        context: {},
+        httpStatus: response.status,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      return createErrorFromResponse(errorResponse);
+    }
+  }
+  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);
+    }
+  }
+};
+
+// src/clients/port-client.ts
+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;
+    }
+  }
+};
+
+// src/clients/process-client.ts
+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 url = `/api/process/list`;
+      const response = await this.get(url);
+      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 url = `/api/process/kill-all`;
+      const response = await this.delete(url);
+      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;
+    }
+  }
+};
+
+// src/clients/utility-client.ts
+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;
+    }
+  }
+};
+
+// src/clients/sandbox-client.ts
+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);
+  }
+};
+
+// src/sandbox.ts
+function getSandbox(ns, id, options) {
+  const stub = getContainer(ns, id);
+  stub.setSandboxName?.(id);
+  if (options?.baseUrl) {
+    stub.setBaseUrl(options.baseUrl);
+  }
+  return stub;
+}
+var Sandbox = class extends Container {
+  defaultPort = 3e3;
+  // Default port for the container's Bun server
+  sleepAfter = "3m";
+  // Sleep the sandbox if no requests are made in this timeframe
+  client;
+  codeInterpreter;
+  sandboxName = null;
+  baseUrl = null;
+  portTokens = /* @__PURE__ */ new Map();
+  defaultSession = null;
+  envVars = {};
+  logger;
+  constructor(ctx, env) {
+    super(ctx, env);
+    const envObj = env;
+    const sandboxEnvKeys = ["SANDBOX_LOG_LEVEL", "SANDBOX_LOG_FORMAT"];
+    sandboxEnvKeys.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,
+      // Control plane port
+      stub: this
+    });
+    this.codeInterpreter = new CodeInterpreter(this);
+    this.ctx.blockConcurrencyWhile(async () => {
+      this.sandboxName = await this.ctx.storage.get("sandboxName") || 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);
+      }
+    });
+  }
+  // RPC method to set the sandbox name
+  async setSandboxName(name) {
+    if (!this.sandboxName) {
+      this.sandboxName = name;
+      await this.ctx.storage.put("sandboxName", name);
+    }
+  }
+  // RPC method to set the base URL
+  async setBaseUrl(baseUrl) {
+    if (!this.baseUrl) {
+      this.baseUrl = baseUrl;
+      await this.ctx.storage.put("baseUrl", baseUrl);
+      console.log(`[Sandbox] Stored base URL: ${baseUrl}`);
+    } else {
+      if (this.baseUrl !== baseUrl) {
+        throw new Error("Base URL already set and different from one previously provided");
+      }
+    }
+  }
+  // RPC method to set environment variables
+  async setEnvVars(envVars) {
+    this.envVars = { ...this.envVars, ...envVars };
+    if (this.defaultSession) {
+      for (const [key, value] of Object.entries(envVars)) {
+        const escapedValue = value.replace(/'/g, "'\\''");
+        const exportCommand = `export ${key}='${escapedValue}'`;
+        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");
+  }
+  onStop() {
+    this.logger.debug("Sandbox stopped");
+  }
+  onError(error) {
+    this.logger.error("Sandbox error", error instanceof Error ? error : new Error(String(error)));
+  }
+  // Override fetch to route internal container requests to appropriate ports
+  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 port = this.determinePort(url);
+      return await this.containerFetch(request, port);
+    });
+  }
+  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
+   */
+  async ensureDefaultSession() {
+    if (!this.defaultSession) {
+      const sessionId = `sandbox-${this.sandboxName || "default"}`;
+      await this.client.utils.createSession({
+        id: sessionId,
+        env: this.envVars || {},
+        cwd: "/workspace"
+      });
+      this.defaultSession = sessionId;
+      this.logger.debug("Default session initialized", { sessionId });
+    }
+    return this.defaultSession;
+  }
+  // Enhanced exec method - always returns ExecResult with optional streaming
+  // This replaces the old exec method to match ISandbox interface
+  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();
+    let timeoutId;
+    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;
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+  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 () => {
+        const current = await this.getProcess(data.id);
+        return current?.status || "error";
+      },
+      getLogs: async () => {
+        const logs = await this.getProcessLogs(data.id);
+        return { stdout: logs.stdout, stderr: logs.stderr };
+      }
+    };
+  }
+  // Background process management
+  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();
+    const response = await this.client.processes.listProcesses();
+    return response.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) {
+    const response = await this.client.processes.killAllProcesses();
+    return response.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
+    };
+  }
+  // Streaming methods - return ReadableStream for RPC compatibility
+  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);
+  }
+  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 exposePort(port, options) {
+    if (options.hostname.endsWith(".workers.dev")) {
+      const errorResponse = {
+        code: ErrorCode2.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()
+      };
+      throw new CustomDomainRequiredError(errorResponse);
+    }
+    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();
+    const url = this.constructPreviewUrl(port, this.sandboxName, options.hostname, token);
+    return {
+      url,
+      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();
+      const response = await this.client.ports.getExposedPorts(sessionId);
+      return response.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) {
+    const isExposed = await this.isPortExposed(port);
+    if (!isExposed) {
+      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);
+    const base64 = btoa(String.fromCharCode(...array));
+    return base64.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);
+    const isLocalhost = isLocalhostPattern(hostname);
+    if (isLocalhost) {
+      const [host, portStr] = hostname.split(":");
+      const mainPort = portStr || "80";
+      try {
+        const baseUrl = new URL(`http://${host}:${mainPort}`);
+        const subdomainHost = `${port}-${sanitizedSandboxId}-${token}.${host}`;
+        baseUrl.hostname = subdomainHost;
+        return baseUrl.toString();
+      } catch (error) {
+        throw new SecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+      }
+    }
+    try {
+      const protocol = "https";
+      const baseUrl = new URL(`${protocol}://${hostname}`);
+      const subdomainHost = `${port}-${sanitizedSandboxId}-${token}.${hostname}`;
+      baseUrl.hostname = subdomainHost;
+      return baseUrl.toString();
+    } catch (error) {
+      throw new SecurityError(`Failed to construct preview URL: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+  }
+  // ============================================================================
+  // Session Management - Advanced Use Cases
+  // ============================================================================
+  /**
+   * 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);
+  }
+  /**
+   * Internal helper to create ExecutionSession wrapper for a given sessionId
+   * Used by both createSession and getSession
+   */
+  getSessionWrapper(sessionId) {
+    return {
+      id: sessionId,
+      // Command execution - delegate to internal session-aware methods
+      exec: (command, options) => this.execWithSession(command, sessionId, options),
+      execStream: (command, options) => this.execStreamWithSession(command, sessionId, options),
+      // Process management
+      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),
+      // File operations - pass sessionId via options or parameter
+      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),
+      // Git operations
+      gitCheckout: (repoUrl, options) => this.gitCheckout(repoUrl, { ...options, sessionId }),
+      // Environment management - needs special handling
+      setEnvVars: async (envVars) => {
+        try {
+          for (const [key, value] of Object.entries(envVars)) {
+            const escapedValue = value.replace(/'/g, "'\\''");
+            const exportCommand = `export ${key}='${escapedValue}'`;
+            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;
+        }
+      },
+      // Code interpreter methods - delegate to sandbox's code interpreter
+      createCodeContext: (options) => this.codeInterpreter.createCodeContext(options),
+      runCode: async (code, options) => {
+        const execution = await this.codeInterpreter.runCode(code, options);
+        return execution.toJSON();
+      },
+      runCodeStream: (code, options) => this.codeInterpreter.runCodeStream(code, options),
+      listCodeContexts: () => this.codeInterpreter.listCodeContexts(),
+      deleteCodeContext: (contextId) => this.codeInterpreter.deleteCodeContext(contextId)
+    };
+  }
+  // ============================================================================
+  // Code interpreter methods - delegate to CodeInterpreter wrapper
+  // ============================================================================
+  async createCodeContext(options) {
+    return this.codeInterpreter.createCodeContext(options);
+  }
+  async runCode(code, options) {
+    const execution = await this.codeInterpreter.runCode(code, options);
+    return execution.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);
+  }
+};
+
+// src/request-handler.ts
+async function proxyToSandbox(request, env) {
+  const traceId = TraceContext2.fromHeaders(request.headers) || TraceContext2.generate();
+  const logger = createLogger2({
+    component: "sandbox-do",
+    traceId,
+    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) {
+      const isValidToken = await sandbox.validatePortToken(port, token);
+      if (!isValidToken) {
+        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"
+            }
+          }
+        );
+      }
+    }
+    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
+        // Pass the friendly name
+      },
+      body: request.body,
+      // @ts-expect-error - duplex required for body streaming in modern runtimes
+      duplex: "half"
+    });
+    return 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-zA-Z0-9_-]{12,20})\.(.+)$/);
+  if (!subdomainMatch) {
+    return null;
+  }
+  const portStr = subdomainMatch[1];
+  const sandboxId = subdomainMatch[2];
+  const token = subdomainMatch[3];
+  const domain = 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("]:")) {
+      const ipv6Part = hostname.substring(0, hostname.indexOf("]:") + 1);
+      return ipv6Part === "[::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";
+}
+
+export {
+  CommandClient,
+  FileClient,
+  GitClient,
+  PortClient,
+  ProcessClient,
+  UtilityClient,
+  SandboxClient,
+  proxyToSandbox,
+  isLocalhostPattern,
+  getSandbox,
+  Sandbox
+};
+//# sourceMappingURL=chunk-HGF554LH.js.map