@cloudflare/sandbox 0.3.1 → 0.3.2

package/src/errors.ts

@@ -23,17 +23,17 @@ export class SandboxError extends Error {
 }
 
 /**
- * Error thrown when Jupyter functionality is requested but the service is still initializing.
+ * Error thrown when interpreter functionality is requested but the service is still initializing.
  *
- * Note: With the current implementation, requests wait for Jupyter to be ready.
+ * Note: With the current implementation, requests wait for interpreter to be ready.
  * This error is only thrown when:
- * 1. The request times out waiting for Jupyter (default: 30 seconds)
- * 2. Jupyter initialization actually fails
+ * 1. The request times out waiting for interpreter (default: 30 seconds)
+ * 2. interpreter initialization actually fails
  *
  * Most requests will succeed after a delay, not throw this error.
  */
-export class JupyterNotReadyError extends SandboxError {
-  public readonly code = "JUPYTER_NOT_READY";
+export class InterpreterNotReadyError extends SandboxError {
+  public readonly code = "INTERPRETER_NOT_READY";
   public readonly retryAfter: number;
   public readonly progress?: number;
 
@@ -42,7 +42,8 @@ export class JupyterNotReadyError extends SandboxError {
     options?: { retryAfter?: number; progress?: number }
   ) {
     super(
-      message || "Jupyter is still initializing. Please retry in a few seconds."
+      message ||
+        "Interpreter is still initializing. Please retry in a few seconds."
     );
     this.retryAfter = options?.retryAfter || 5;
     this.progress = options?.progress;
@@ -123,12 +124,12 @@ export class ServiceUnavailableError extends SandboxError {
 }
 
 /**
- * Type guard to check if an error is a JupyterNotReadyError
+ * Type guard to check if an error is a InterpreterNotReadyError
  */
-export function isJupyterNotReadyError(
+export function isInterpreterNotReadyError(
   error: unknown
-): error is JupyterNotReadyError {
-  return error instanceof JupyterNotReadyError;
+): error is InterpreterNotReadyError {
+  return error instanceof InterpreterNotReadyError;
 }
 
 /**
@@ -143,7 +144,7 @@ export function isSandboxError(error: unknown): error is SandboxError {
  */
 export function isRetryableError(error: unknown): boolean {
   if (
-    error instanceof JupyterNotReadyError ||
+    error instanceof InterpreterNotReadyError ||
     error instanceof ContainerNotReadyError ||
     error instanceof ServiceUnavailableError
   ) {
@@ -189,9 +190,9 @@ export async function parseErrorResponse(
       );
     }
 
-    // Jupyter initialization error
+    // Interpreter initialization error
     if (data.status === "initializing") {
-      return new JupyterNotReadyError(data.error, {
+      return new InterpreterNotReadyError(data.error, {
         retryAfter: parseInt(response.headers.get("Retry-After") || "5"),
         progress: data.progress,
       });

package/src/index.ts

@@ -1,20 +1,31 @@
-// Export API response types
+// biome-ignore-start assist/source/organizeImports: Need separate exports for deprecation warnings to work properly
+/**
+ * @deprecated Use `InterpreterNotReadyError` instead. Will be removed in a future version.
+ */
+export { InterpreterNotReadyError as JupyterNotReadyError } from "./errors";
+
+/**
+ * @deprecated Use `isInterpreterNotReadyError` instead. Will be removed in a future version.
+ */
+export { isInterpreterNotReadyError as isJupyterNotReadyError } from "./errors";
+// biome-ignore-end assist/source/organizeImports: Need separate exports for deprecation warnings to work properly
 
-// Export errors
+// Export API response types
 export {
   CodeExecutionError,
   ContainerNotReadyError,
   ContextNotFoundError,
-  isJupyterNotReadyError,
+  InterpreterNotReadyError,
+  isInterpreterNotReadyError,
   isRetryableError,
   isSandboxError,
-  JupyterNotReadyError,
   parseErrorResponse,
   SandboxError,
   type SandboxErrorResponse,
   SandboxNetworkError,
   ServiceUnavailableError,
 } from "./errors";
+
 // Export code interpreter types
 export type {
   ChartData,
@@ -60,5 +71,5 @@ export type {
   ReadFileResponse,
   RenameFileResponse,
   StreamOptions,
-  WriteFileResponse
+  WriteFileResponse,
 } from "./types";

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

@@ -62,7 +62,7 @@ export interface ExecutionCallbacks {
   onError?: (error: ExecutionError) => void | Promise<void>;
 }
 
-export class JupyterClient extends HttpClient {
+export class InterpreterClient extends HttpClient {
   private readonly maxRetries = 3;
   private readonly retryDelayMs = 1000;
 
@@ -239,7 +239,10 @@ export class JupyterClient extends HttpClient {
           break;
       }
     } catch (error) {
-      console.error("[JupyterClient] Error parsing execution result:", error);
+      console.error(
+        "[InterpreterClient] Error parsing execution result:",
+        error
+      );
     }
   }
 
@@ -295,7 +298,7 @@ export class JupyterClient extends HttpClient {
       } catch (error) {
         lastError = error as Error;
 
-        // Check if it's a retryable error (circuit breaker or Jupyter not ready)
+        // 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) {

package/src/interpreter-types.ts

@@ -4,19 +4,19 @@ export interface CreateContextOptions {
    * Programming language for the context
    * @default 'python'
    */
-  language?: 'python' | 'javascript' | 'typescript';
-  
+  language?: "python" | "javascript" | "typescript";
+
   /**
    * Working directory for the context
    * @default '/workspace'
    */
   cwd?: string;
-  
+
   /**
    * Environment variables for the context
    */
   envVars?: Record<string, string>;
-  
+
   /**
    * Request timeout in milliseconds
    * @default 30000
@@ -29,22 +29,22 @@ export interface CodeContext {
    * Unique identifier for the context
    */
   readonly id: string;
-  
+
   /**
    * Programming language of the context
    */
   readonly language: string;
-  
+
   /**
    * Current working directory
    */
   readonly cwd: string;
-  
+
   /**
    * When the context was created
    */
   readonly createdAt: Date;
-  
+
   /**
    * When the context was last used
    */
@@ -57,44 +57,44 @@ export interface RunCodeOptions {
    * Context to run the code in. If not provided, uses default context for the language
    */
   context?: CodeContext;
-  
+
   /**
    * Language to use if context is not provided
    * @default 'python'
    */
-  language?: 'python' | 'javascript' | 'typescript';
-  
+  language?: "python" | "javascript" | "typescript";
+
   /**
    * Environment variables for this execution
    */
   envVars?: Record<string, string>;
-  
+
   /**
    * Execution timeout in milliseconds
    * @default 60000
    */
   timeout?: number;
-  
+
   /**
    * AbortSignal for cancelling execution
    */
   signal?: AbortSignal;
-  
+
   /**
    * Callback for stdout output
    */
   onStdout?: (output: OutputMessage) => void | Promise<void>;
-  
+
   /**
    * Callback for stderr output
    */
   onStderr?: (output: OutputMessage) => void | Promise<void>;
-  
+
   /**
    * Callback for execution results (charts, tables, etc)
    */
   onResult?: (result: Result) => void | Promise<void>;
-  
+
   /**
    * Callback for execution errors
    */
@@ -107,7 +107,7 @@ export interface OutputMessage {
    * The output text
    */
   text: string;
-  
+
   /**
    * Timestamp of the output
    */
@@ -120,57 +120,57 @@ export interface Result {
    * Plain text representation
    */
   text?: string;
-  
+
   /**
    * HTML representation (tables, formatted output)
    */
   html?: string;
-  
+
   /**
    * PNG image data (base64 encoded)
    */
   png?: string;
-  
+
   /**
    * JPEG image data (base64 encoded)
    */
   jpeg?: string;
-  
+
   /**
    * SVG image data
    */
   svg?: string;
-  
+
   /**
    * LaTeX representation
    */
   latex?: string;
-  
+
   /**
    * Markdown representation
    */
   markdown?: string;
-  
+
   /**
    * JavaScript code to execute
    */
   javascript?: string;
-  
+
   /**
    * JSON data
    */
   json?: any;
-  
+
   /**
    * Chart data if the result is a visualization
    */
   chart?: ChartData;
-  
+
   /**
    * Raw data object
    */
   data?: any;
-  
+
   /**
    * Available output formats
    */
@@ -182,33 +182,40 @@ export interface ChartData {
   /**
    * Type of chart
    */
-  type: 'line' | 'bar' | 'scatter' | 'pie' | 'histogram' | 'heatmap' | 'unknown';
-  
+  type:
+    | "line"
+    | "bar"
+    | "scatter"
+    | "pie"
+    | "histogram"
+    | "heatmap"
+    | "unknown";
+
   /**
    * Chart title
    */
   title?: string;
-  
+
   /**
    * Chart data (format depends on library)
    */
   data: any;
-  
+
   /**
    * Chart layout/configuration
    */
   layout?: any;
-  
+
   /**
    * Additional configuration
    */
   config?: any;
-  
+
   /**
    * Library that generated the chart
    */
-  library?: 'matplotlib' | 'plotly' | 'altair' | 'seaborn' | 'unknown';
-  
+  library?: "matplotlib" | "plotly" | "altair" | "seaborn" | "unknown";
+
   /**
    * Base64 encoded image if available
    */
@@ -221,17 +228,17 @@ export interface ExecutionError {
    * Error name/type (e.g., 'NameError', 'SyntaxError')
    */
   name: string;
-  
+
   /**
    * Error message
    */
   value: string;
-  
+
   /**
    * Stack trace
    */
   traceback: string[];
-  
+
   /**
    * Line number where error occurred
    */
@@ -268,30 +275,30 @@ export class Execution {
    * All results from the execution
    */
   public results: Result[] = [];
-  
+
   /**
    * Accumulated stdout and stderr
    */
   public logs = {
     stdout: [] as string[],
-    stderr: [] as string[]
+    stderr: [] as string[],
   };
-  
+
   /**
    * Execution error if any
    */
   public error?: ExecutionError;
-  
+
   /**
-   * Execution count (for Jupyter)
+   * Execution count (for interpreter)
    */
   public executionCount?: number;
-  
+
   constructor(
     public readonly code: string,
     public readonly context: CodeContext
   ) {}
-  
+
   /**
    * Convert to a plain object for serialization
    */
@@ -301,7 +308,7 @@ export class Execution {
       logs: this.logs,
       error: this.error,
       executionCount: this.executionCount,
-      results: this.results.map(result => ({
+      results: this.results.map((result) => ({
         text: result.text,
         html: result.html,
         png: result.png,
@@ -312,8 +319,8 @@ export class Execution {
         javascript: result.javascript,
         json: result.json,
         chart: result.chart,
-        data: result.data
-      }))
+        data: result.data,
+      })),
     };
   }
 }
@@ -321,63 +328,63 @@ export class Execution {
 // Implementation of Result
 export class ResultImpl implements Result {
   constructor(private raw: any) {}
-  
-  get text(): string | undefined { 
-    return this.raw.text || this.raw.data?.['text/plain']; 
+
+  get text(): string | undefined {
+    return this.raw.text || this.raw.data?.["text/plain"];
   }
-  
-  get html(): string | undefined { 
-    return this.raw.html || this.raw.data?.['text/html']; 
+
+  get html(): string | undefined {
+    return this.raw.html || this.raw.data?.["text/html"];
   }
-  
-  get png(): string | undefined { 
-    return this.raw.png || this.raw.data?.['image/png']; 
+
+  get png(): string | undefined {
+    return this.raw.png || this.raw.data?.["image/png"];
   }
-  
-  get jpeg(): string | undefined { 
-    return this.raw.jpeg || this.raw.data?.['image/jpeg']; 
+
+  get jpeg(): string | undefined {
+    return this.raw.jpeg || this.raw.data?.["image/jpeg"];
   }
-  
-  get svg(): string | undefined { 
-    return this.raw.svg || this.raw.data?.['image/svg+xml']; 
+
+  get svg(): string | undefined {
+    return this.raw.svg || this.raw.data?.["image/svg+xml"];
   }
-  
-  get latex(): string | undefined { 
-    return this.raw.latex || this.raw.data?.['text/latex']; 
+
+  get latex(): string | undefined {
+    return this.raw.latex || this.raw.data?.["text/latex"];
   }
-  
-  get markdown(): string | undefined { 
-    return this.raw.markdown || this.raw.data?.['text/markdown']; 
+
+  get markdown(): string | undefined {
+    return this.raw.markdown || this.raw.data?.["text/markdown"];
   }
-  
-  get javascript(): string | undefined { 
-    return this.raw.javascript || this.raw.data?.['application/javascript']; 
+
+  get javascript(): string | undefined {
+    return this.raw.javascript || this.raw.data?.["application/javascript"];
   }
-  
-  get json(): any { 
-    return this.raw.json || this.raw.data?.['application/json']; 
+
+  get json(): any {
+    return this.raw.json || this.raw.data?.["application/json"];
   }
-  
-  get chart(): ChartData | undefined { 
-    return this.raw.chart; 
+
+  get chart(): ChartData | undefined {
+    return this.raw.chart;
   }
-  
-  get data(): any { 
-    return this.raw.data; 
+
+  get data(): any {
+    return this.raw.data;
   }
-  
+
   formats(): string[] {
     const formats: string[] = [];
-    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');
+    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;
   }
-}
+}

package/src/interpreter.ts

@@ -1,3 +1,4 @@
+import type { InterpreterClient } from "./interpreter-client.js";
 import {
   type CodeContext,
   type CreateContextOptions,
@@ -5,15 +6,14 @@ import {
   ResultImpl,
   type RunCodeOptions,
 } from "./interpreter-types.js";
-import type { JupyterClient } from "./jupyter-client.js";
 import type { Sandbox } from "./sandbox.js";
 
 export class CodeInterpreter {
-  private jupyterClient: JupyterClient;
+  private interpreterClient: InterpreterClient;
   private contexts = new Map<string, CodeContext>();
 
   constructor(sandbox: Sandbox) {
-    this.jupyterClient = sandbox.client as JupyterClient;
+    this.interpreterClient = sandbox.client as InterpreterClient;
   }
 
   /**
@@ -22,7 +22,7 @@ export class CodeInterpreter {
   async createCodeContext(
     options: CreateContextOptions = {}
   ): Promise<CodeContext> {
-    const context = await this.jupyterClient.createCodeContext(options);
+    const context = await this.interpreterClient.createCodeContext(options);
     this.contexts.set(context.id, context);
     return context;
   }
@@ -46,7 +46,7 @@ export class CodeInterpreter {
     const execution = new Execution(code, context);
 
     // Stream execution
-    await this.jupyterClient.runCodeStream(context.id, code, options.language, {
+    await this.interpreterClient.runCodeStream(context.id, code, options.language, {
       onStdout: (output) => {
         execution.logs.stdout.push(output.text);
         if (options.onStdout) return options.onStdout(output);
@@ -83,7 +83,7 @@ export class CodeInterpreter {
     }
 
     // Create streaming response
-    const response = await this.jupyterClient.doFetch("/api/execute/code", {
+    const response = await this.interpreterClient.doFetch("/api/execute/code", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -116,7 +116,7 @@ export class CodeInterpreter {
    * List all code contexts
    */
   async listCodeContexts(): Promise<CodeContext[]> {
-    const contexts = await this.jupyterClient.listCodeContexts();
+    const contexts = await this.interpreterClient.listCodeContexts();
 
     // Update local cache
     for (const context of contexts) {
@@ -130,7 +130,7 @@ export class CodeInterpreter {
    * Delete a code context
    */
   async deleteCodeContext(contextId: string): Promise<void> {
-    await this.jupyterClient.deleteCodeContext(contextId);
+    await this.interpreterClient.deleteCodeContext(contextId);
     this.contexts.delete(contextId);
   }
 

package/src/sandbox.ts

@@ -1,12 +1,12 @@
 import { Container, getContainer } from "@cloudflare/containers";
 import { CodeInterpreter } from "./interpreter";
+import { InterpreterClient } from "./interpreter-client";
 import type {
   CodeContext,
   CreateContextOptions,
   ExecutionResult,
   RunCodeOptions,
 } from "./interpreter-types";
-import { JupyterClient } from "./jupyter-client";
 import { isLocalhostPattern } from "./request-handler";
 import {
   logSecurityEvent,
@@ -41,14 +41,14 @@ export function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string) {
 export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
   defaultPort = 3000; // Default port for the container's Bun server
   sleepAfter = "20m"; // Keep container warm for 20 minutes to avoid cold starts
-  client: JupyterClient;
+  client: InterpreterClient;
   private sandboxName: string | null = null;
   private codeInterpreter: CodeInterpreter;
   private defaultSession: ExecutionSession | null = null;
 
   constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);
-    this.client = new JupyterClient({
+    this.client = new InterpreterClient({
       onCommandComplete: (success, exitCode, _stdout, _stderr, command) => {
         console.log(
           `[Container] Command completed: ${command}, Success: ${success}, Exit code: ${exitCode}`