@cloudflare/sandbox 0.0.0-d86b60e → 0.0.0-d951819

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @cloudflare/sandbox
 
+## 0.3.6
+
+### Patch Changes
+
+- [#90](https://github.com/cloudflare/sandbox-sdk/pull/90) [`66cc85b`](https://github.com/cloudflare/sandbox-sdk/commit/66cc85b679b466b3ffb1f00fbd697670fc186f06) Thanks [@eastlondoner](https://github.com/eastlondoner)! - set bun idletimeout
+
+## 0.3.5
+
+### Patch Changes
+
+- [#88](https://github.com/cloudflare/sandbox-sdk/pull/88) [`46eb4e6`](https://github.com/cloudflare/sandbox-sdk/commit/46eb4e6b6c671b682fc74f83563ccf5f316011cb) Thanks [@ghostwriternr](https://github.com/ghostwriternr)! - Add binary file support with automatic MIME detection and streaming
+
 ## 0.3.4
 
 ### Patch Changes

package/Dockerfile

@@ -13,6 +13,7 @@ RUN apt-get update && apt-get install -y \
     git \
     unzip \
     zip \
+    file \
     # Process management
     procps \
     htop \
@@ -51,6 +52,12 @@ RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
 COPY --from=bun-source /usr/local/bin/bun /usr/local/bin/bun
 COPY --from=bun-source /usr/local/bin/bunx /usr/local/bin/bunx
 
+# Install development tools globally
+RUN npm install -g \
+    wrangler \
+    vite \
+    opencode-ai
+
 # Install essential Python packages for code execution
 RUN pip3 install --no-cache-dir \
     matplotlib \

package/README.md

@@ -50,10 +50,11 @@ The Cloudflare Sandbox SDK enables you to run isolated code environments directl
 - **🔒 Secure Isolation**: Each sandbox runs in its own container with full process isolation
 - **⚡ Edge-Native**: Runs on Cloudflare's global network for low latency worldwide
 - **📁 File System Access**: Read, write, and manage files within the sandbox
+- **🖼️ Binary File Support**: Automatic MIME type detection and base64 encoding for images, PDFs, and other binary files
 - **🔧 Command Execution**: Run any command or process inside the container
 - **🌐 Preview URLs**: Expose services running in your sandbox via public URLs
 - **🔄 Git Integration**: Clone repositories directly into sandboxes
-- **🚀 Streaming Support**: Real-time output streaming for long-running commands
+- **🚀 Streaming Support**: Real-time output streaming for long-running commands and file transfers
 - **🎮 Session Management**: Maintain state across multiple operations
 - **🧪 Code Interpreter**: Execute Python and JavaScript with rich outputs (charts, tables, formatted data)
 - **📊 Multi-Language Support**: Persistent execution contexts for Python and JavaScript/TypeScript
@@ -72,7 +73,7 @@ npm install @cloudflare/sandbox
 1. **Create a Dockerfile** (temporary requirement, will be removed in future releases):
 
 ```dockerfile
-FROM docker.io/cloudflare/sandbox:0.3.4
+FROM docker.io/cloudflare/sandbox:0.3.6
 
 # Expose the ports you want to expose
 EXPOSE 3000
@@ -189,11 +190,57 @@ await sandbox.writeFile("/workspace/app.js", "console.log('Hello!');");
 
 #### `readFile(path, options?)`
 
-Read a file from the sandbox.
+Read a file from the sandbox with automatic binary detection.
 
 ```typescript
+// Read text files
 const file = await sandbox.readFile("/package.json");
-console.log(file.content);
+console.log(file.content); // UTF-8 text content
+
+// Read binary files - automatically detected and base64 encoded
+const image = await sandbox.readFile("/workspace/chart.png");
+console.log(image.mimeType); // "image/png"
+console.log(image.isBinary); // true
+console.log(image.encoding); // "base64"
+console.log(image.size); // File size in bytes
+
+// Use the base64 content directly in data URLs
+const dataUrl = `data:${image.mimeType};base64,${image.content}`;
+```
+
+#### `readFileStream(path)`
+
+Stream large files efficiently with automatic chunking and encoding.
+
+```typescript
+import { streamFile, collectFile } from '@cloudflare/sandbox';
+
+// Stream a large file
+const stream = await sandbox.readFileStream("/large-video.mp4");
+
+// Option 1: Process chunks as they arrive
+for await (const chunk of streamFile(stream)) {
+  if (chunk instanceof Uint8Array) {
+    // Binary chunk - already decoded from base64
+    console.log(`Received ${chunk.byteLength} bytes`);
+    // Process binary data...
+  } else {
+    // Text chunk
+    console.log('Text:', chunk);
+  }
+}
+
+// Option 2: Collect entire file into memory
+const { content, metadata } = await collectFile(stream);
+console.log(`MIME: ${metadata.mimeType}, Size: ${metadata.size} bytes`);
+
+if (content instanceof Uint8Array) {
+  // Binary file - ready to save or process
+  await writeToStorage(content);
+} else {
+  // Text file
+  console.log('Content:', content);
+}
 ```
 
 #### `gitCheckout(repoUrl, options?)`
@@ -241,7 +288,8 @@ console.log(result.stdout); // "production"
 #### File System Methods
 
 - `writeFile(path, content, options?)` - Write content to a file
-- `readFile(path, options?)` - Read a file from the sandbox
+- `readFile(path, options?)` - Read a file with automatic binary detection and base64 encoding
+- `readFileStream(path)` - Stream large files efficiently with chunking
 - `mkdir(path, options?)` - Create a directory
 - `deleteFile(path)` - Delete a file
 - `renameFile(oldPath, newPath)` - Rename a file
@@ -665,10 +713,15 @@ for await (const event of parseSSEStream<ExecEvent>(stream)) {
 
 The SDK exports utilities for working with Server-Sent Event streams:
 
+**Command Execution:**
 - **`parseSSEStream<T>(stream)`** - Convert ReadableStream to typed AsyncIterable
 - **`responseToAsyncIterable<T>(response)`** - Convert SSE Response to AsyncIterable
 - **`asyncIterableToSSEStream<T>(iterable)`** - Convert AsyncIterable back to SSE stream
 
+**File Streaming:**
+- **`streamFile(stream, signal?)`** - Convert file SSE stream to AsyncIterable with automatic base64 decoding
+- **`collectFile(stream, signal?)`** - Collect entire file from stream into memory
+
 #### Advanced Streaming Examples
 
 **CI/CD Build System:**

package/container_src/handler/file.ts

@@ -204,6 +204,11 @@ export async function handleReadFileRequest(
                 path,
                 success: result.success,
                 timestamp: new Date().toISOString(),
+                // New metadata fields for binary file support
+                encoding: result.encoding,
+                isBinary: result.isBinary,
+                mimeType: result.mimeType,
+                size: result.size,
             }),
             {
                 headers: {
@@ -403,4 +408,50 @@ export async function handleListFilesRequest(
     } catch (error) {
         return createServerErrorResponse("handleListFilesRequest", error, corsHeaders);
     }
+}
+
+export async function handleReadFileStreamRequest(
+    req: Request,
+    corsHeaders: Record<string, string>,
+    sessionManager: SessionManager
+): Promise<Response> {
+    try {
+        const body = (await req.json()) as ReadFileRequest;
+        const { path, sessionId } = body;
+
+        // Validate path
+        const pathError = validatePath(path);
+        if (pathError) {
+            return createPathErrorResponse(pathError, corsHeaders);
+        }
+
+        console.log(`[Server] Streaming file: ${path}${sessionId ? ` in session: ${sessionId}` : ''}`);
+
+        // Get the appropriate session
+        const session = sessionId
+            ? sessionManager.getSession(sessionId)
+            : await sessionManager.getOrCreateDefaultSession();
+
+        if (!session) {
+            return createServerErrorResponse(
+                "handleReadFileStreamRequest",
+                new Error(`Session '${sessionId}' not found`),
+                corsHeaders
+            );
+        }
+
+        // Create SSE stream
+        const stream = await session.readFileStreamOperation(path);
+
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                ...corsHeaders,
+            },
+        });
+    } catch (error) {
+        return createServerErrorResponse("handleReadFileStreamRequest", error, corsHeaders);
+    }
 }

package/container_src/index.ts

@@ -9,6 +9,7 @@ import {
   handleMkdirRequest,
   handleMoveFileRequest,
   handleReadFileRequest,
+  handleReadFileStreamRequest,
   handleRenameFileRequest,
   handleWriteFileRequest,
 } from "./handler/file";
@@ -86,6 +87,7 @@ console.log("[Container] Interpreter service ready - no cold start!");
 console.log("[Container] All API endpoints available immediately");
 
 const server = serve({
+  idleTimeout: 255,
   async fetch(req: Request) {
     const url = new URL(req.url);
     const pathname = url.pathname;
@@ -190,6 +192,12 @@ const server = serve({
           }
           break;
 
+        case "/api/read/stream":
+          if (req.method === "POST") {
+            return handleReadFileStreamRequest(req, corsHeaders, sessionManager);
+          }
+          break;
+
         case "/api/delete":
           if (req.method === "POST") {
             return handleDeleteFileRequest(req, corsHeaders, sessionManager);
@@ -569,6 +577,7 @@ console.log(`   POST /api/git/checkout - Checkout a git repository`);
 console.log(`   POST /api/mkdir - Create a directory`);
 console.log(`   POST /api/write - Write a file`);
 console.log(`   POST /api/read - Read a file`);
+console.log(`   POST /api/read/stream - Stream a file (SSE)`);
 console.log(`   POST /api/delete - Delete a file`);
 console.log(`   POST /api/rename - Rename a file`);
 console.log(`   POST /api/move - Move a file`);

package/container_src/isolation.ts

@@ -446,16 +446,180 @@ SANDBOX_EOF`;
     };
   }
 
-  async readFileOperation(path: string, encoding: string = 'utf-8'): Promise<{ success: boolean; exitCode: number; content: string; path: string }> {
-    const command = `cat "${path}"`;
-    const result = await this.exec(command);
-    
+  async readFileOperation(path: string, encoding: string = 'utf-8'): Promise<{
+    success: boolean;
+    exitCode: number;
+    content: string;
+    path: string;
+    encoding?: 'utf-8' | 'base64';
+    isBinary?: boolean;
+    mimeType?: string;
+    size?: number;
+  }> {
+    // Step 1: Check if file exists and get metadata
+    const statCommand = `stat -c '%s' "${path}" 2>/dev/null || echo "FILE_NOT_FOUND"`;
+    const statResult = await this.exec(statCommand);
+
+    if (statResult.stdout.trim() === 'FILE_NOT_FOUND') {
+      // File doesn't exist - return error
+      return {
+        success: false,
+        exitCode: 1,
+        content: '',
+        path
+      };
+    }
+
+    const fileSize = parseInt(statResult.stdout.trim(), 10);
+
+    // Step 2: Detect MIME type using file command
+    const mimeCommand = `file --mime-type -b "${path}"`;
+    const mimeResult = await this.exec(mimeCommand);
+    const mimeType = mimeResult.stdout.trim();
+
+    // Step 3: Determine if file is binary based on MIME type
+    // Text MIME types: text/*, application/json, application/xml, application/javascript, etc.
+    const isBinary = !mimeType.startsWith('text/') &&
+                     !mimeType.includes('json') &&
+                     !mimeType.includes('xml') &&
+                     !mimeType.includes('javascript') &&
+                     !mimeType.includes('x-empty');
+
+    // Step 4: Read file with appropriate encoding
+    let content: string;
+    let actualEncoding: 'utf-8' | 'base64';
+
+    if (isBinary) {
+      // Use base64 for binary files
+      const base64Command = `base64 -w 0 "${path}"`;
+      const base64Result = await this.exec(base64Command);
+      content = base64Result.stdout;
+      actualEncoding = 'base64';
+    } else {
+      // Use cat for text files
+      const catCommand = `cat "${path}"`;
+      const catResult = await this.exec(catCommand);
+      content = catResult.stdout;
+      actualEncoding = 'utf-8';
+    }
+
     return {
-      success: result.exitCode === 0,
-      exitCode: result.exitCode,
-      content: result.stdout,
-      path
+      success: true,
+      exitCode: 0,
+      content,
+      path,
+      encoding: actualEncoding,
+      isBinary,
+      mimeType,
+      size: fileSize
+    };
+  }
+
+  async readFileStreamOperation(path: string): Promise<ReadableStream<Uint8Array>> {
+    const encoder = new TextEncoder();
+
+    // Helper to send SSE event
+    const sseEvent = (event: any): Uint8Array => {
+      return encoder.encode(`data: ${JSON.stringify(event)}\n\n`);
     };
+
+    // Create streaming response
+    return new ReadableStream({
+      start: async (controller) => {
+        try {
+          // Step 1: Get file metadata (same logic as readFileOperation)
+          const statCommand = `stat -c '%s' "${path}" 2>/dev/null || echo "FILE_NOT_FOUND"`;
+          const statResult = await this.exec(statCommand);
+
+          if (statResult.stdout.trim() === 'FILE_NOT_FOUND') {
+            // File doesn't exist - send error event
+            controller.enqueue(sseEvent({
+              type: 'error',
+              error: `File not found: ${path}`
+            }));
+            controller.close();
+            return;
+          }
+
+          const fileSize = parseInt(statResult.stdout.trim(), 10);
+
+          // Step 2: Detect MIME type
+          const mimeCommand = `file --mime-type -b "${path}"`;
+          const mimeResult = await this.exec(mimeCommand);
+          const mimeType = mimeResult.stdout.trim();
+
+          // Step 3: Determine if binary
+          const isBinary = !mimeType.startsWith('text/') &&
+                           !mimeType.includes('json') &&
+                           !mimeType.includes('xml') &&
+                           !mimeType.includes('javascript') &&
+                           !mimeType.includes('x-empty');
+
+          const encoding: 'utf-8' | 'base64' = isBinary ? 'base64' : 'utf-8';
+
+          // Step 4: Send metadata event
+          controller.enqueue(sseEvent({
+            type: 'metadata',
+            mimeType,
+            size: fileSize,
+            isBinary,
+            encoding
+          }));
+
+          // Step 5: Stream file in chunks
+          // IMPORTANT: Chunk size MUST be divisible by 3 for base64 encoding!
+          // Base64 encodes 3 bytes at a time. If chunks aren't aligned,
+          // concatenating separately-encoded base64 strings corrupts the data.
+          const CHUNK_SIZE = 65535;
+          let bytesRead = 0;
+
+          while (bytesRead < fileSize) {
+            const remainingBytes = fileSize - bytesRead;
+            const chunkSize = Math.min(CHUNK_SIZE, remainingBytes);
+
+            // Use dd to read chunk at specific offset
+            // bs=1 means 1 byte block size, skip=offset, count=chunkSize
+            let chunkCommand: string;
+            if (isBinary) {
+              // For binary, read and encode as base64
+              chunkCommand = `dd if="${path}" bs=1 skip=${bytesRead} count=${chunkSize} 2>/dev/null | base64 -w 0`;
+            } else {
+              // For text, just read
+              chunkCommand = `dd if="${path}" bs=1 skip=${bytesRead} count=${chunkSize} 2>/dev/null`;
+            }
+
+            const chunkResult = await this.exec(chunkCommand);
+
+            // Send chunk event
+            controller.enqueue(sseEvent({
+              type: 'chunk',
+              data: chunkResult.stdout
+            }));
+
+            bytesRead += chunkSize;
+          }
+
+          // Step 6: Send complete event
+          controller.enqueue(sseEvent({
+            type: 'complete',
+            bytesRead
+          }));
+
+          controller.close();
+        } catch (error) {
+          // Send error event
+          controller.enqueue(sseEvent({
+            type: 'error',
+            error: error instanceof Error ? error.message : String(error)
+          }));
+          controller.close();
+        }
+      },
+
+      cancel() {
+        console.log(`[Session] File stream cancelled for: ${path}`);
+      }
+    });
   }
 
   async mkdirOperation(path: string, recursive: boolean = false): Promise<{ success: boolean; exitCode: number; path: string; recursive: boolean }> {
@@ -1010,7 +1174,7 @@ export class SessionManager {
     return defaultSession.writeFileOperation(path, content, encoding);
   }
 
-  async readFile(path: string, encoding?: string): Promise<{ success: boolean; exitCode: number; content: string; path: string }> {
+  async readFile(path: string, encoding?: string): Promise<{ success: boolean; exitCode: number; content: string; path: string; encoding?: 'utf-8' | 'base64'; isBinary?: boolean; mimeType?: string; size?: number }> {
     const defaultSession = await this.getOrCreateDefaultSession();
     return defaultSession.readFileOperation(path, encoding);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "0.0.0-d86b60e",
+  "version": "0.0.0-d951819",
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/sandbox-sdk"

package/src/client.ts

@@ -481,6 +481,45 @@ export class HttpClient {
     }
   }
 
+  async readFileStream(
+    path: string,
+    sessionId: string
+  ): Promise<ReadableStream<Uint8Array>> {
+    try {
+      const response = await this.doFetch(`/api/read/stream`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          path,
+          sessionId,
+        } as ReadFileRequest),
+      });
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({}))) as {
+          error?: string;
+        };
+        throw new Error(
+          errorData.error || `HTTP error! status: ${response.status}`
+        );
+      }
+
+      if (!response.body) {
+        throw new Error("No response body for file streaming");
+      }
+
+      console.log(
+        `[HTTP Client] Started streaming file: ${path}${sessionId ? ` in session: ${sessionId}` : ''}`
+      );
+      return response.body;
+    } catch (error) {
+      console.error("[HTTP Client] Error streaming file:", error);
+      throw error;
+    }
+  }
+
   async deleteFile(
     path: string,
     sessionId: string

package/src/file-stream.ts

@@ -0,0 +1,162 @@
+/**
+ * File streaming utilities for reading binary and text files
+ * Provides simple AsyncIterable API over SSE stream with automatic base64 decoding
+ */
+
+import { parseSSEStream } from './sse-parser';
+import type { FileChunk, FileMetadata, FileStreamEvent } from './types';
+
+/**
+ * Convert ReadableStream of SSE file events to AsyncIterable of file chunks
+ * Automatically decodes base64 for binary files and provides metadata
+ *
+ * @param stream - The SSE ReadableStream from readFileStream()
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns AsyncIterable that yields file chunks (string for text, Uint8Array for binary)
+ *
+ * @example
+ * ```typescript
+ * const stream = await sandbox.readFileStream('/path/to/file.png');
+ *
+ * for await (const chunk of streamFile(stream)) {
+ *   if (chunk instanceof Uint8Array) {
+ *     // Binary chunk - already decoded from base64
+ *     console.log('Binary chunk:', chunk.byteLength, 'bytes');
+ *   } else {
+ *     // Text chunk
+ *     console.log('Text chunk:', chunk);
+ *   }
+ * }
+ *
+ * // Access metadata
+ * const iter = streamFile(stream);
+ * for await (const chunk of iter) {
+ *   console.log('MIME type:', iter.metadata?.mimeType);
+ *   // process chunk...
+ * }
+ * ```
+ */
+export async function* streamFile(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): AsyncGenerator<FileChunk, void, undefined> {
+  let metadata: FileMetadata | undefined;
+
+  try {
+    for await (const event of parseSSEStream<FileStreamEvent>(stream, signal)) {
+      switch (event.type) {
+        case 'metadata':
+          // Store metadata for access via iterator
+          metadata = {
+            mimeType: event.mimeType,
+            size: event.size,
+            isBinary: event.isBinary,
+            encoding: event.encoding,
+          };
+          // Store on generator function for external access
+          (streamFile as any).metadata = metadata;
+          break;
+
+        case 'chunk':
+          // Auto-decode base64 for binary files
+          if (metadata?.isBinary && metadata?.encoding === 'base64') {
+            // Decode base64 to Uint8Array
+            const binaryString = atob(event.data);
+            const bytes = new Uint8Array(binaryString.length);
+            for (let i = 0; i < binaryString.length; i++) {
+              bytes[i] = binaryString.charCodeAt(i);
+            }
+            yield bytes;
+          } else {
+            // Text file - yield as-is
+            yield event.data;
+          }
+          break;
+
+        case 'complete':
+          // Stream completed successfully
+          console.log(`[streamFile] File streaming complete: ${event.bytesRead} bytes read`);
+          return;
+
+        case 'error':
+          // Stream error
+          throw new Error(`File streaming error: ${event.error}`);
+      }
+    }
+  } catch (error) {
+    console.error('[streamFile] Error streaming file:', error);
+    throw error;
+  }
+}
+
+/**
+ * Helper to collect entire file from stream into memory
+ * Useful for smaller files where you want the complete content at once
+ *
+ * @param stream - The SSE ReadableStream from readFileStream()
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Object with content (string or Uint8Array) and metadata
+ *
+ * @example
+ * ```typescript
+ * const stream = await sandbox.readFileStream('/path/to/image.png');
+ * const { content, metadata } = await collectFile(stream);
+ *
+ * if (content instanceof Uint8Array) {
+ *   console.log('Binary file:', metadata.mimeType, content.byteLength, 'bytes');
+ * } else {
+ *   console.log('Text file:', metadata.mimeType, content.length, 'chars');
+ * }
+ * ```
+ */
+export async function collectFile(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): Promise<{ content: string | Uint8Array; metadata: FileMetadata }> {
+  let metadata: FileMetadata | undefined;
+  const chunks: FileChunk[] = [];
+
+  for await (const chunk of streamFile(stream, signal)) {
+    chunks.push(chunk);
+    // Capture metadata from first iteration
+    if (!metadata && (streamFile as any).metadata) {
+      metadata = (streamFile as any).metadata;
+    }
+  }
+
+  if (!metadata) {
+    throw new Error('No metadata received from file stream');
+  }
+
+  // Combine chunks based on type
+  if (chunks.length === 0) {
+    // Empty file
+    return {
+      content: metadata.isBinary ? new Uint8Array(0) : '',
+      metadata,
+    };
+  }
+
+  // Check if binary or text based on first chunk
+  if (chunks[0] instanceof Uint8Array) {
+    // Binary file - concatenate Uint8Arrays
+    const totalLength = chunks.reduce((sum, chunk) => {
+      return sum + (chunk as Uint8Array).byteLength;
+    }, 0);
+
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk as Uint8Array, offset);
+      offset += (chunk as Uint8Array).byteLength;
+    }
+
+    return { content: result, metadata };
+  } else {
+    // Text file - concatenate strings
+    return {
+      content: chunks.join(''),
+      metadata,
+    };
+  }
+}

package/src/index.ts

@@ -52,6 +52,8 @@ export {
   parseSSEStream,
   responseToAsyncIterable,
 } from "./sse-parser";
+// Export file streaming utilities
+export { streamFile, collectFile } from "./file-stream";
 export type {
   DeleteFileResponse,
   ExecEvent,
@@ -59,6 +61,10 @@ export type {
   ExecResult,
   ExecuteResponse,
   ExecutionSession,
+  FileChunk,
+  FileMetadata,
+  FileStream,
+  FileStreamEvent,
   GitCheckoutResponse,
   ISandbox,
   ListFilesResponse,

package/src/sandbox.ts

@@ -264,6 +264,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     return session.readFile(path, options);
   }
 
+  async readFileStream(path: string): Promise<ReadableStream<Uint8Array>> {
+    const session = await this.ensureDefaultSession();
+    return session.readFileStream(path);
+  }
+
   async listFiles(
     path: string,
     options: {
@@ -678,7 +683,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       readFile: async (path: string, options?: { encoding?: string }) => {
         return await this.client.readFile(path, options?.encoding, sessionId);
       },
-      
+
+      readFileStream: async (path: string) => {
+        return await this.client.readFileStream(path, sessionId);
+      },
+
       mkdir: async (path: string, options?: { recursive?: boolean }) => {
         return await this.client.mkdir(path, options?.recursive, sessionId);
       },

package/src/types.ts

@@ -215,6 +215,54 @@ export interface StreamOptions extends BaseExecOptions {
   signal?: AbortSignal;
 }
 
+// File Streaming Types
+
+/**
+ * SSE events for file streaming
+ */
+export type FileStreamEvent =
+  | {
+      type: 'metadata';
+      mimeType: string;
+      size: number;
+      isBinary: boolean;
+      encoding: 'utf-8' | 'base64';
+    }
+  | {
+      type: 'chunk';
+      data: string; // base64 for binary, UTF-8 for text
+    }
+  | {
+      type: 'complete';
+      bytesRead: number;
+    }
+  | {
+      type: 'error';
+      error: string;
+    };
+
+/**
+ * File metadata from streaming
+ */
+export interface FileMetadata {
+  mimeType: string;
+  size: number;
+  isBinary: boolean;
+  encoding: 'utf-8' | 'base64';
+}
+
+/**
+ * File stream chunk - either string (text) or Uint8Array (binary, auto-decoded)
+ */
+export type FileChunk = string | Uint8Array;
+
+/**
+ * AsyncIterable of file chunks with metadata
+ */
+export interface FileStream extends AsyncIterable<FileChunk> {
+  metadata?: FileMetadata;
+}
+
 // Error Types
 
 export class SandboxError extends Error {
@@ -359,6 +407,7 @@ export interface ISandbox {
   renameFile(oldPath: string, newPath: string): Promise<RenameFileResponse>;
   moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResponse>;
   readFile(path: string, options?: { encoding?: string }): Promise<ReadFileResponse>;
+  readFileStream(path: string): Promise<ReadableStream<Uint8Array>>;
   listFiles(path: string, options?: { recursive?: boolean; includeHidden?: boolean }): Promise<ListFilesResponse>;
 
   // Port management
@@ -434,6 +483,26 @@ export interface ReadFileResponse {
   path: string;
   content: string;
   timestamp: string;
+
+  /**
+   * Encoding used for content (utf-8 for text, base64 for binary)
+   */
+  encoding?: 'utf-8' | 'base64';
+
+  /**
+   * Whether the file is detected as binary
+   */
+  isBinary?: boolean;
+
+  /**
+   * MIME type of the file (e.g., 'image/png', 'text/plain')
+   */
+  mimeType?: string;
+
+  /**
+   * File size in bytes
+   */
+  size?: number;
 }
 
 export interface DeleteFileResponse {