@cloudflare/sandbox 0.0.0-46eb4e6 → 0.0.0-485cf61

package/src/{interpreter-client.ts → clients/interpreter-client.ts}

@@ -1,25 +1,17 @@
-import { HttpClient } from "./client.js";
-import { isRetryableError, parseErrorResponse } from "./errors.js";
-import type {
-  CodeContext,
-  CreateContextOptions,
-  ExecutionError,
-  OutputMessage,
-  Result,
-} from "./interpreter-types.js";
-
-// API Response types
-interface ContextResponse {
-  id: string;
-  language: string;
-  cwd: string;
-  createdAt: string; // ISO date string from JSON
-  lastUsed: string; // ISO date string from JSON
-}
-
-interface ContextListResponse {
-  contexts: ContextResponse[];
-}
+import {
+  type CodeContext,
+  type ContextCreateResult,
+  type ContextListResult,
+  type CreateContextOptions,
+  type ExecutionError,
+  type OutputMessage,
+  type Result,
+  ResultImpl,
+} from '@repo/shared';
+import type { ErrorResponse } from '../errors';
+import { createErrorFromResponse, ErrorCode, InterpreterNotReadyError } from '../errors';
+import { BaseHttpClient } from './base-client.js';
+import type { HttpClientOptions } from './types.js';
 
 // Streaming execution data from the server
 interface StreamingExecutionData {
@@ -62,10 +54,14 @@ export interface ExecutionCallbacks {
   onError?: (error: ExecutionError) => void | Promise<void>;
 }
 
-export class InterpreterClient extends HttpClient {
+export class InterpreterClient extends BaseHttpClient {
   private readonly maxRetries = 3;
   private readonly retryDelayMs = 1000;
 
+  constructor(options: HttpClientOptions = {}) {
+    super(options);
+  }
+
   async createCodeContext(
     options: CreateContextOptions = {}
   ): Promise<CodeContext> {
@@ -81,16 +77,21 @@ export class InterpreterClient extends HttpClient {
       });
 
       if (!response.ok) {
-        throw await parseErrorResponse(response);
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+
+      const data = (await response.json()) as ContextCreateResult;
+      if (!data.success) {
+        throw new Error(`Failed to create context: ${JSON.stringify(data)}`);
       }
 
-      const data = (await response.json()) as ContextResponse;
       return {
-        id: data.id,
+        id: data.contextId,
         language: data.language,
-        cwd: data.cwd,
-        createdAt: new Date(data.createdAt),
-        lastUsed: new Date(data.lastUsed),
+        cwd: data.cwd || '/workspace',
+        createdAt: new Date(data.timestamp),
+        lastUsed: new Date(data.timestamp),
       };
     });
   }
@@ -99,7 +100,8 @@ export class InterpreterClient extends HttpClient {
     contextId: string | undefined,
     code: string,
     language: string | undefined,
-    callbacks: ExecutionCallbacks
+    callbacks: ExecutionCallbacks,
+    timeoutMs?: number
   ): Promise<void> {
     return this.executeWithRetry(async () => {
       const response = await this.doFetch("/api/execute/code", {
@@ -112,11 +114,13 @@ export class InterpreterClient extends HttpClient {
           context_id: contextId,
           code,
           language,
+          ...(timeoutMs !== undefined && { timeout_ms: timeoutMs })
         }),
       });
 
       if (!response.ok) {
-        throw await parseErrorResponse(response);
+        const error = await this.parseErrorResponse(response);
+        throw error;
       }
 
       if (!response.body) {
@@ -130,6 +134,111 @@ export class InterpreterClient extends HttpClient {
     });
   }
 
+  async listCodeContexts(): Promise<CodeContext[]> {
+    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()) as ContextListResult;
+      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: string): Promise<void> {
+    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
+   */
+  private async executeWithRetry<T>(operation: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error as Error;
+
+        // Check if it's a retryable error (interpreter not ready)
+        if (this.isRetryableError(error)) {
+          // Don't retry on the last attempt
+          if (attempt < this.maxRetries - 1) {
+            // Exponential backoff with jitter
+            const delay =
+              this.retryDelayMs * 2 ** attempt + Math.random() * 1000;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+
+        // Not retryable or last attempt - throw the error
+        throw error;
+      }
+    }
+
+    throw lastError || new Error("Execution failed after retries");
+  }
+
+  private isRetryableError(error: unknown): boolean {
+    if (error instanceof InterpreterNotReadyError) {
+      return true;
+    }
+
+    if (error instanceof Error) {
+      return (
+        error.message.includes("not ready") ||
+        error.message.includes("initializing")
+      );
+    }
+
+    return false;
+  }
+
+  private async parseErrorResponse(response: Response): Promise<Error> {
+    try {
+      const errorData = await response.json() as ErrorResponse;
+      return createErrorFromResponse(errorData);
+    } catch {
+      // Fallback if response isn't JSON
+      const errorResponse: ErrorResponse = {
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `HTTP ${response.status}: ${response.statusText}`,
+        context: {},
+        httpStatus: response.status,
+        timestamp: new Date().toISOString()
+      };
+      return createErrorFromResponse(errorResponse);
+    }
+  }
+
   private async *readLines(
     stream: ReadableStream<Uint8Array>
   ): AsyncGenerator<string> {
@@ -167,8 +276,13 @@ export class InterpreterClient extends HttpClient {
   ) {
     if (!line.trim()) return;
 
+    // Skip lines that don't start with "data: " (SSE format)
+    if (!line.startsWith('data: ')) return;
+
     try {
-      const data = JSON.parse(line) as StreamingExecutionData;
+      // Strip "data: " prefix and parse JSON
+      const jsonData = line.substring(6); // "data: " is 6 characters
+      const data = JSON.parse(jsonData) as StreamingExecutionData;
 
       switch (data.type) {
         case "stdout":
@@ -191,34 +305,8 @@ export class InterpreterClient extends HttpClient {
 
         case "result":
           if (callbacks.onResult) {
-            // Convert raw result to Result interface
-            const result: Result = {
-              text: data.text,
-              html: data.html,
-              png: data.png,
-              jpeg: data.jpeg,
-              svg: data.svg,
-              latex: data.latex,
-              markdown: data.markdown,
-              javascript: data.javascript,
-              json: data.json,
-              chart: data.chart,
-              data: data.data,
-              formats: () => {
-                const formats: string[] = [];
-                if (data.text) formats.push("text");
-                if (data.html) formats.push("html");
-                if (data.png) formats.push("png");
-                if (data.jpeg) formats.push("jpeg");
-                if (data.svg) formats.push("svg");
-                if (data.latex) formats.push("latex");
-                if (data.markdown) formats.push("markdown");
-                if (data.javascript) formats.push("javascript");
-                if (data.json) formats.push("json");
-                if (data.chart) formats.push("chart");
-                return formats;
-              },
-            };
+            // Create a ResultImpl instance from the raw data
+            const result = new ResultImpl(data);
             await callbacks.onResult(result);
           }
           break;
@@ -227,126 +315,18 @@ export class InterpreterClient extends HttpClient {
           if (callbacks.onError) {
             await callbacks.onError({
               name: data.ename || "Error",
-              value: data.evalue || data.text || "Unknown error",
+              message: data.evalue || "Unknown error",
               traceback: data.traceback || [],
-              lineNumber: data.lineNumber,
             });
           }
           break;
 
         case "execution_complete":
-          // Execution completed successfully
+          // Signal completion - callbacks can handle cleanup if needed
           break;
       }
     } catch (error) {
-      console.error(
-        "[InterpreterClient] Error parsing execution result:",
-        error
-      );
-    }
-  }
-
-  async listCodeContexts(): Promise<CodeContext[]> {
-    return this.executeWithRetry(async () => {
-      const response = await this.doFetch("/api/contexts", {
-        method: "GET",
-        headers: { "Content-Type": "application/json" },
-      });
-
-      if (!response.ok) {
-        throw await parseErrorResponse(response);
-      }
-
-      const data = (await response.json()) as ContextListResponse;
-      return data.contexts.map((ctx) => ({
-        id: ctx.id,
-        language: ctx.language,
-        cwd: ctx.cwd,
-        createdAt: new Date(ctx.createdAt),
-        lastUsed: new Date(ctx.lastUsed),
-      }));
-    });
-  }
-
-  async deleteCodeContext(contextId: string): Promise<void> {
-    return this.executeWithRetry(async () => {
-      const response = await this.doFetch(`/api/contexts/${contextId}`, {
-        method: "DELETE",
-        headers: { "Content-Type": "application/json" },
-      });
-
-      if (!response.ok) {
-        throw await parseErrorResponse(response);
-      }
-    });
-  }
-
-  // Override parent doFetch to be public for this class
-  public async doFetch(path: string, options?: RequestInit): Promise<Response> {
-    return super.doFetch(path, options);
-  }
-
-  /**
-   * Execute an operation with automatic retry for transient errors
-   */
-  private async executeWithRetry<T>(operation: () => Promise<T>): Promise<T> {
-    let lastError: Error | undefined;
-
-    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
-      try {
-        return await operation();
-      } catch (error) {
-        lastError = error as Error;
-
-        // Check if it's a retryable error (circuit breaker or interpreter not ready)
-        if (this.isRetryableError(error)) {
-          // Don't retry on the last attempt
-          if (attempt < this.maxRetries - 1) {
-            // Exponential backoff with jitter
-            const delay =
-              this.retryDelayMs * 2 ** attempt + Math.random() * 1000;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-            continue;
-          }
-        }
-
-        // Non-retryable error or last attempt - throw immediately
-        throw error;
-      }
+      console.error("Failed to parse execution result:", error);
     }
-
-    // All retries exhausted - throw a clean error without implementation details
-    if (lastError?.message.includes("Code execution")) {
-      // If the error already has a clean message about code execution, use it
-      throw lastError;
-    }
-
-    // Otherwise, throw a generic but user-friendly error
-    throw new Error("Unable to execute code at this time");
-  }
-
-  /**
-   * Check if an error is retryable
-   */
-  private isRetryableError(error: unknown): boolean {
-    // Use the SDK's built-in retryable check
-    if (isRetryableError(error)) {
-      return true;
-    }
-
-    // Also check for circuit breaker specific errors
-    if (error instanceof Error) {
-      // Circuit breaker errors (from the container's response)
-      if (error.message.includes("Circuit breaker is open")) {
-        return true;
-      }
-
-      // Check if error has a status property
-      if ("status" in error && error.status === "circuit_open") {
-        return true;
-      }
-    }
-
-    return false;
   }
 }

package/src/clients/port-client.ts

@@ -0,0 +1,108 @@
+import type {
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+} from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions } from './types';
+
+// Re-export for convenience
+export type {
+  PortExposeResult,
+  PortCloseResult,
+  PortListResult,
+};
+
+/**
+ * Request interface for exposing ports
+ */
+export interface ExposePortRequest {
+  port: number;
+  name?: string;
+}
+
+/**
+ * Request interface for unexposing ports
+ */
+export interface UnexposePortRequest {
+  port: number;
+}
+
+/**
+ * Client for port management and preview URL operations
+ */
+export class PortClient extends BaseHttpClient {
+  constructor(options: HttpClientOptions = {}) {
+    super(options);
+  }
+
+  /**
+   * 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: number,
+    sessionId: string,
+    name?: string
+  ): Promise<PortExposeResult> {
+    try {
+      const data = { port, sessionId, name };
+
+      const response = await this.post<PortExposeResult>(
+        '/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: number, sessionId: string): Promise<PortCloseResult> {
+    try {
+      const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
+      const response = await this.delete<PortCloseResult>(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: string): Promise<PortListResult> {
+    try {
+      const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
+      const response = await this.get<PortListResult>(url);
+
+      this.logSuccess(
+        'Exposed ports retrieved',
+        `${response.ports.length} ports exposed`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('getExposedPorts', error);
+      throw error;
+    }
+  }
+}

package/src/clients/process-client.ts

@@ -0,0 +1,180 @@
+import type {
+  ProcessCleanupResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessListResult,
+  ProcessLogsResult,
+  ProcessStartResult,
+  StartProcessRequest,
+} from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions } from './types';
+
+// Re-export for convenience
+export type {
+  StartProcessRequest,
+  ProcessStartResult,
+  ProcessListResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessLogsResult,
+  ProcessCleanupResult,
+};
+
+
+/**
+ * Client for background process management
+ */
+export class ProcessClient extends BaseHttpClient {
+  constructor(options: HttpClientOptions = {}) {
+    super(options);
+  }
+
+  /**
+   * 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: string,
+    sessionId: string,
+    options?: { processId?: string }
+  ): Promise<ProcessStartResult> {
+    try {
+      const data: StartProcessRequest = {
+        command,
+        sessionId,
+        processId: options?.processId,
+      };
+
+      const response = await this.post<ProcessStartResult>(
+        '/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(): Promise<ProcessListResult> {
+    try {
+      const url = `/api/process/list`;
+      const response = await this.get<ProcessListResult>(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: string): Promise<ProcessInfoResult> {
+    try {
+      const url = `/api/process/${processId}`;
+      const response = await this.get<ProcessInfoResult>(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: string): Promise<ProcessKillResult> {
+    try {
+      const url = `/api/process/${processId}`;
+      const response = await this.delete<ProcessKillResult>(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(): Promise<ProcessCleanupResult> {
+    try {
+      const url = `/api/process/kill-all`;
+      const response = await this.delete<ProcessCleanupResult>(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: string): Promise<ProcessLogsResult> {
+    try {
+      const url = `/api/process/${processId}/logs`;
+      const response = await this.get<ProcessLogsResult>(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: string): Promise<ReadableStream<Uint8Array>> {
+    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;
+    }
+  }
+}