@cloudflare/sandbox 0.5.1 → 0.5.3

package/src/openai/index.ts

@@ -0,0 +1,465 @@
+/**
+ * OpenAI Agents adapters for executing shell commands and file operations
+ * inside a Cloudflare Sandbox.
+ */
+import {
+  type ApplyPatchOperation,
+  type ApplyPatchResult,
+  applyDiff,
+  type Editor as OpenAIEeditor,
+  type Shell as OpenAIShell,
+  type ShellAction,
+  type ShellOutputResult,
+  type ShellResult
+} from '@openai/agents';
+
+// Command result for API responses
+export interface CommandResult {
+  command: string;
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  timestamp: number;
+}
+
+// File operation result for API responses
+export interface FileOperationResult {
+  operation: 'create' | 'update' | 'delete';
+  path: string;
+  status: 'completed' | 'failed';
+  output: string;
+  error?: string;
+  timestamp: number;
+}
+
+import { createLogger, type Logger } from '@repo/shared';
+import type { Sandbox } from '../sandbox';
+
+// Helper functions for error handling
+function isErrorWithProperties(error: unknown): error is {
+  message?: string;
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+  status?: number;
+  stack?: string;
+} {
+  return typeof error === 'object' && error !== null;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (isErrorWithProperties(error) && typeof error.message === 'string') {
+    return error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Convert unknown values to Error instances when possible so downstream
+ * loggers can include stack traces without losing type safety.
+ */
+function toError(error: unknown): Error | undefined {
+  return error instanceof Error ? error : undefined;
+}
+
+/**
+ * Shell implementation that adapts Cloudflare Sandbox exec calls to the
+ * OpenAI Agents `Shell` contract, including structured result collection.
+ */
+export class Shell implements OpenAIShell {
+  private cwd: string = '/workspace';
+  public results: CommandResult[] = [];
+  private readonly logger: Logger;
+
+  constructor(private readonly sandbox: Sandbox) {
+    this.logger = createLogger({
+      component: 'sandbox-do',
+      operation: 'openai-shell'
+    });
+  }
+
+  async run(action: ShellAction): Promise<ShellResult> {
+    this.logger.debug('SandboxShell.run called', {
+      commands: action.commands,
+      timeout: action.timeoutMs
+    });
+    const output: ShellResult['output'] = [];
+
+    for (const command of action.commands) {
+      this.logger.debug('Executing command', { command, cwd: this.cwd });
+      let stdout = '';
+      let stderr = '';
+      let exitCode: number | null = 0;
+      let outcome: ShellOutputResult['outcome'] = {
+        type: 'exit',
+        exitCode: 0
+      };
+      try {
+        const result = await this.sandbox.exec(command, {
+          timeout: action.timeoutMs,
+          cwd: this.cwd
+        });
+        stdout = result.stdout;
+        stderr = result.stderr;
+        exitCode = result.exitCode;
+        // exec returns a result even for failed commands, so check success field
+        // Timeout would be indicated by a specific error or exit code
+        outcome = { type: 'exit', exitCode };
+
+        this.logger.debug('Command executed successfully', {
+          command,
+          exitCode,
+          stdoutLength: stdout.length,
+          stderrLength: stderr.length
+        });
+
+        // Log warnings for non-zero exit codes or stderr output
+        if (exitCode !== 0) {
+          this.logger.warn(`Command failed with exit code ${exitCode}`, {
+            command,
+            stderr
+          });
+        } else if (stderr) {
+          this.logger.warn(`Command produced stderr output`, {
+            command,
+            stderr
+          });
+        } else {
+          this.logger.info(`Command completed successfully`, { command });
+        }
+      } catch (error: unknown) {
+        // Handle network/HTTP errors or timeout errors
+        const errorObj = isErrorWithProperties(error) ? error : {};
+        exitCode =
+          typeof errorObj.exitCode === 'number' ? errorObj.exitCode : null;
+        stdout = typeof errorObj.stdout === 'string' ? errorObj.stdout : '';
+        stderr = typeof errorObj.stderr === 'string' ? errorObj.stderr : '';
+
+        // Check if it's a timeout error
+        const errorMessage = getErrorMessage(error);
+        if (
+          errorMessage.includes('timeout') ||
+          errorMessage.includes('Timeout') ||
+          errorMessage.includes('timed out')
+        ) {
+          this.logger.error(`Command timed out`, undefined, {
+            command,
+            timeout: action.timeoutMs
+          });
+          outcome = { type: 'timeout' };
+        } else {
+          this.logger.error(`Error executing command`, toError(error), {
+            command,
+            error: errorMessage || error,
+            exitCode
+          });
+          outcome = { type: 'exit', exitCode: exitCode ?? 1 };
+        }
+      }
+      output.push({
+        command,
+        stdout,
+        stderr,
+        outcome
+      });
+
+      // Collect results for API responses
+      const collectedExitCode =
+        outcome.type === 'exit' ? outcome.exitCode : null;
+      const timestamp = Date.now();
+      this.results.push({
+        command: String(command),
+        stdout: String(stdout),
+        stderr: String(stderr),
+        exitCode: collectedExitCode,
+        timestamp
+      });
+      this.logger.debug('Result collected', {
+        command,
+        exitCode: collectedExitCode,
+        timestamp
+      });
+
+      if (outcome.type === 'timeout') {
+        this.logger.warn('Breaking command loop due to timeout');
+        break;
+      }
+    }
+
+    this.logger.debug('SandboxShell.run completed', {
+      totalCommands: action.commands.length,
+      resultsCount: this.results.length
+    });
+    return {
+      output,
+      providerData: {
+        working_directory: this.cwd
+      }
+    };
+  }
+}
+
+/**
+ * Editor implementation that projects applyPatch operations from Agents
+ * into calls against the sandbox filesystem APIs.
+ */
+export class Editor implements OpenAIEeditor {
+  public results: FileOperationResult[] = [];
+  private readonly logger: Logger;
+
+  constructor(
+    private readonly sandbox: Sandbox,
+    private readonly root: string = '/workspace'
+  ) {
+    this.logger = createLogger({
+      component: 'sandbox-do',
+      operation: 'openai-editor'
+    });
+  }
+
+  /**
+   * Create a new file inside the sandbox by applying the provided diff.
+   */
+  async createFile(
+    operation: Extract<ApplyPatchOperation, { type: 'create_file' }>
+  ): Promise<ApplyPatchResult | undefined> {
+    const targetPath = this.resolve(operation.path);
+    this.logger.debug('WorkspaceEditor.createFile called', {
+      path: operation.path,
+      targetPath
+    });
+
+    try {
+      // Create parent directory if needed
+      const dirPath = this.getDirname(targetPath);
+      if (dirPath !== this.root && dirPath !== '/') {
+        this.logger.debug('Creating parent directory', { dirPath });
+        await this.sandbox.mkdir(dirPath, { recursive: true });
+      }
+
+      const content = applyDiff('', operation.diff, 'create');
+      this.logger.debug('Writing file content', {
+        path: targetPath,
+        contentLength: content.length
+      });
+      await this.sandbox.writeFile(targetPath, content, { encoding: 'utf-8' });
+      const timestamp = Date.now();
+      const result: FileOperationResult = {
+        operation: 'create',
+        path: operation.path,
+        status: 'completed',
+        output: `Created ${operation.path}`,
+        timestamp
+      };
+      this.results.push(result);
+      this.logger.info('File created successfully', {
+        path: operation.path,
+        timestamp
+      });
+      return { status: 'completed', output: `Created ${operation.path}` };
+    } catch (error: unknown) {
+      const timestamp = Date.now();
+      const errorMessage = getErrorMessage(error);
+      const result: FileOperationResult = {
+        operation: 'create',
+        path: operation.path,
+        status: 'failed',
+        output: `Failed to create ${operation.path}`,
+        error: errorMessage,
+        timestamp
+      };
+      this.results.push(result);
+      this.logger.error('Failed to create file', toError(error), {
+        path: operation.path,
+        error: errorMessage
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Update an existing file by reading its content, applying a diff, and
+   * writing the patched output back to the sandbox.
+   */
+  async updateFile(
+    operation: Extract<ApplyPatchOperation, { type: 'update_file' }>
+  ): Promise<ApplyPatchResult | undefined> {
+    const targetPath = this.resolve(operation.path);
+    this.logger.debug('WorkspaceEditor.updateFile called', {
+      path: operation.path,
+      targetPath
+    });
+
+    try {
+      let original: string;
+      try {
+        this.logger.debug('Reading original file', { path: targetPath });
+        const fileInfo = await this.sandbox.readFile(targetPath, {
+          encoding: 'utf-8'
+        });
+        original = fileInfo.content;
+        this.logger.debug('Original file read', {
+          path: targetPath,
+          originalLength: original.length
+        });
+      } catch (error: unknown) {
+        // Sandbox API may throw errors for missing files
+        const errorObj = isErrorWithProperties(error) ? error : {};
+        const errorMessage = getErrorMessage(error);
+        if (
+          errorMessage.includes('not found') ||
+          errorMessage.includes('ENOENT') ||
+          errorObj.status === 404
+        ) {
+          this.logger.error('Cannot update missing file', undefined, {
+            path: operation.path
+          });
+          throw new Error(`Cannot update missing file: ${operation.path}`);
+        }
+        this.logger.error('Error reading file', toError(error), {
+          path: operation.path,
+          error: errorMessage
+        });
+        throw error;
+      }
+
+      const patched = applyDiff(original, operation.diff);
+      this.logger.debug('Applied diff', {
+        path: targetPath,
+        originalLength: original.length,
+        patchedLength: patched.length
+      });
+      await this.sandbox.writeFile(targetPath, patched, { encoding: 'utf-8' });
+      const timestamp = Date.now();
+      const result: FileOperationResult = {
+        operation: 'update',
+        path: operation.path,
+        status: 'completed',
+        output: `Updated ${operation.path}`,
+        timestamp
+      };
+      this.results.push(result);
+      this.logger.info('File updated successfully', {
+        path: operation.path,
+        timestamp
+      });
+      return { status: 'completed', output: `Updated ${operation.path}` };
+    } catch (error: unknown) {
+      const timestamp = Date.now();
+      const errorMessage = getErrorMessage(error);
+      const result: FileOperationResult = {
+        operation: 'update',
+        path: operation.path,
+        status: 'failed',
+        output: `Failed to update ${operation.path}`,
+        error: errorMessage,
+        timestamp
+      };
+      this.results.push(result);
+      this.logger.error('Failed to update file', toError(error), {
+        path: operation.path,
+        error: errorMessage
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Delete a file that was previously created through applyPatch calls.
+   */
+  async deleteFile(
+    operation: Extract<ApplyPatchOperation, { type: 'delete_file' }>
+  ): Promise<ApplyPatchResult | undefined> {
+    const targetPath = this.resolve(operation.path);
+    this.logger.debug('WorkspaceEditor.deleteFile called', {
+      path: operation.path,
+      targetPath
+    });
+
+    try {
+      await this.sandbox.deleteFile(targetPath);
+      const timestamp = Date.now();
+      const result: FileOperationResult = {
+        operation: 'delete',
+        path: operation.path,
+        status: 'completed',
+        output: `Deleted ${operation.path}`,
+        timestamp
+      };
+      this.results.push(result);
+      this.logger.info('File deleted successfully', {
+        path: operation.path,
+        timestamp
+      });
+      return { status: 'completed', output: `Deleted ${operation.path}` };
+    } catch (error: unknown) {
+      const timestamp = Date.now();
+      const errorMessage = getErrorMessage(error);
+      const result: FileOperationResult = {
+        operation: 'delete',
+        path: operation.path,
+        status: 'failed',
+        output: `Failed to delete ${operation.path}`,
+        error: errorMessage,
+        timestamp
+      };
+      this.results.push(result);
+      this.logger.error('Failed to delete file', toError(error), {
+        path: operation.path,
+        error: errorMessage
+      });
+      throw error;
+    }
+  }
+
+  private resolve(relativePath: string): string {
+    // If the path already starts with the root, strip it to get the relative part
+    let pathToProcess = relativePath;
+    if (relativePath.startsWith(this.root)) {
+      pathToProcess = relativePath.slice(this.root.length);
+      // Remove leading slash if present after stripping root
+      pathToProcess = pathToProcess.replace(/^\//, '');
+    }
+
+    // Remove leading ./ or / if present, then join with root
+    const normalized = pathToProcess.replace(/^\.\//, '').replace(/^\//, '');
+    const resolved = normalized ? `${this.root}/${normalized}` : this.root;
+
+    // Normalize path separators first
+    const pathWithNormalizedSeparators = resolved.replace(/\/+/g, '/');
+
+    // Normalize .. segments by processing path segments
+    const segments = pathWithNormalizedSeparators
+      .split('/')
+      .filter((s) => s && s !== '.');
+    const stack: string[] = [];
+
+    for (const segment of segments) {
+      if (segment === '..') {
+        if (stack.length === 0) {
+          throw new Error(`Operation outside workspace: ${relativePath}`);
+        }
+        stack.pop();
+      } else {
+        stack.push(segment);
+      }
+    }
+
+    const normalizedPath = `/${stack.join('/')}`;
+
+    // Ensure the resolved path is within the workspace
+    if (!normalizedPath.startsWith(this.root)) {
+      throw new Error(`Operation outside workspace: ${relativePath}`);
+    }
+
+    return normalizedPath;
+  }
+
+  private getDirname(filePath: string): string {
+    const lastSlash = filePath.lastIndexOf('/');
+    if (lastSlash === -1) {
+      return '/';
+    }
+    return filePath.substring(0, lastSlash) || '/';
+  }
+}

package/src/sandbox.ts

@@ -22,7 +22,6 @@ import type {
 import {
   createLogger,
   getEnvString,
-  runWithLogger,
   type SessionDeleteResult,
   shellEscape,
   TraceContext
@@ -757,8 +756,20 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     }
   }
 
-  override onStop() {
+  override async onStop() {
     this.logger.debug('Sandbox stopped');
+
+    // Clear in-memory state that references the old container
+    // This prevents stale references after container restarts
+    this.portTokens.clear();
+    this.defaultSession = null;
+    this.activeMounts.clear();
+
+    // Persist cleanup to storage so state is clean on next container start
+    await Promise.all([
+      this.ctx.storage.delete('portTokens'),
+      this.ctx.storage.delete('defaultSession')
+    ]);
   }
 
   override onError(error: unknown) {
@@ -905,48 +916,46 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     // Create request-specific logger with trace ID
     const requestLogger = this.logger.child({ traceId, operation: 'fetch' });
 
-    return await runWithLogger(requestLogger, async () => {
-      const url = new URL(request.url);
+    const url = new URL(request.url);
 
-      // Capture and store the sandbox name from the header if present
-      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);
-      }
+    // Capture and store the sandbox name from the header if present
+    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);
+    }
 
-      // Detect WebSocket upgrade request (RFC 6455 compliant)
-      const upgradeHeader = request.headers.get('Upgrade');
-      const connectionHeader = request.headers.get('Connection');
-      const isWebSocket =
-        upgradeHeader?.toLowerCase() === 'websocket' &&
-        connectionHeader?.toLowerCase().includes('upgrade');
+    // Detect WebSocket upgrade request (RFC 6455 compliant)
+    const upgradeHeader = request.headers.get('Upgrade');
+    const connectionHeader = request.headers.get('Connection');
+    const isWebSocket =
+      upgradeHeader?.toLowerCase() === 'websocket' &&
+      connectionHeader?.toLowerCase().includes('upgrade');
 
-      if (isWebSocket) {
-        // WebSocket path: Let parent Container class handle WebSocket proxying
-        // This bypasses containerFetch() which uses JSRPC and cannot handle WebSocket upgrades
-        try {
-          requestLogger.debug('WebSocket upgrade requested', {
-            path: url.pathname,
-            port: this.determinePort(url)
-          });
-          return await super.fetch(request);
-        } catch (error) {
-          requestLogger.error(
-            'WebSocket connection failed',
-            error instanceof Error ? error : new Error(String(error)),
-            { path: url.pathname }
-          );
-          throw error;
-        }
+    if (isWebSocket) {
+      // WebSocket path: Let parent Container class handle WebSocket proxying
+      // This bypasses containerFetch() which uses JSRPC and cannot handle WebSocket upgrades
+      try {
+        requestLogger.debug('WebSocket upgrade requested', {
+          path: url.pathname,
+          port: this.determinePort(url)
+        });
+        return await super.fetch(request);
+      } catch (error) {
+        requestLogger.error(
+          'WebSocket connection failed',
+          error instanceof Error ? error : new Error(String(error)),
+          { path: url.pathname }
+        );
+        throw error;
       }
+    }
 
-      // Non-WebSocket: Use existing port determination and HTTP routing logic
-      const port = this.determinePort(url);
+    // Non-WebSocket: Use existing port determination and HTTP routing logic
+    const port = this.determinePort(url);
 
-      // Route to the appropriate port
-      return await this.containerFetch(request, port);
-    });
+    // Route to the appropriate port
+    return await this.containerFetch(request, port);
   }
 
   wsConnect(request: Request, port: number): Promise<Response> {
@@ -1051,7 +1060,23 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
         );
       } else {
         // Regular execution with session
-        const response = await this.client.commands.execute(command, sessionId);
+        const commandOptions =
+          options &&
+          (options.timeout !== undefined ||
+            options.env !== undefined ||
+            options.cwd !== undefined)
+            ? {
+                timeoutMs: options.timeout,
+                env: options.env,
+                cwd: options.cwd
+              }
+            : undefined;
+
+        const response = await this.client.commands.execute(
+          command,
+          sessionId,
+          commandOptions
+        );
 
         const duration = Date.now() - startTime;
         result = this.mapExecuteResponseToExecResult(
@@ -1092,7 +1117,12 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     try {
       const stream = await this.client.commands.executeStream(
         command,
-        sessionId
+        sessionId,
+        {
+          timeoutMs: options.timeout,
+          env: options.env,
+          cwd: options.cwd
+        }
       );
 
       for await (const event of parseSSEStream<ExecEvent>(stream)) {
@@ -1222,12 +1252,23 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     // Use the new HttpClient method to start the process
     try {
       const session = sessionId ?? (await this.ensureDefaultSession());
+      const requestOptions = {
+        ...(options?.processId !== undefined && {
+          processId: options.processId
+        }),
+        ...(options?.timeout !== undefined && { timeoutMs: options.timeout }),
+        ...(options?.env !== undefined && { env: options.env }),
+        ...(options?.cwd !== undefined && { cwd: options.cwd }),
+        ...(options?.encoding !== undefined && { encoding: options.encoding }),
+        ...(options?.autoCleanup !== undefined && {
+          autoCleanup: options.autoCleanup
+        })
+      };
+
       const response = await this.client.processes.startProcess(
         command,
         session,
-        {
-          processId: options?.processId
-        }
+        requestOptions
       );
 
       const processObj = this.createProcessFromDTO(
@@ -1347,7 +1388,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
 
     const session = await this.ensureDefaultSession();
     // Get the stream from CommandClient
-    return this.client.commands.executeStream(command, session);
+    return this.client.commands.executeStream(command, session, {
+      timeoutMs: options?.timeout,
+      env: options?.env,
+      cwd: options?.cwd
+    });
   }
 
   /**
@@ -1363,7 +1408,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       throw new Error('Operation was aborted');
     }
 
-    return this.client.commands.executeStream(command, sessionId);
+    return this.client.commands.executeStream(command, sessionId, {
+      timeoutMs: options?.timeout,
+      env: options?.env,
+      cwd: options?.cwd
+    });
   }
 
   /**
@@ -1697,11 +1746,18 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
   async createSession(options?: SessionOptions): Promise<ExecutionSession> {
     const sessionId = options?.id || `session-${Date.now()}`;
 
+    const mergedEnv = {
+      ...this.envVars,
+      ...(options?.env ?? {})
+    };
+    const envPayload =
+      Object.keys(mergedEnv).length > 0 ? mergedEnv : undefined;
+
     // Create session in container
     await this.client.utils.createSession({
       id: sessionId,
-      env: options?.env,
-      cwd: options?.cwd
+      ...(envPayload && { env: envPayload }),
+      ...(options?.cwd && { cwd: options.cwd })
     });
 
     // Return wrapper that binds sessionId to all operations

package/src/version.ts

@@ -3,4 +3,4 @@
  * This file is auto-updated by .github/changeset-version.ts during releases
  * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
  */
-export const SDK_VERSION = '0.5.1';
+export const SDK_VERSION = '0.5.3';