feat: make file operations browser-compatible

- Update fileUpload to accept string/Blob/File instead of file paths
- Update fileDownload to return content instead of writing to disk
- Add convenience methods for common browser use cases
- Remove Node.js fs and path dependencies
- Add FileDownloadResult interface
- Update examples to remove Node.js-specific code
- Add comprehensive browser compatibility documentation

Fixes file operations to work natively in browser environments without
Node.js polyfills or dependencies.

Co-authored-by: openhands <openhands@all-hands.dev>

Author: openhands-agent

BROWSER_COMPATIBILITY.md

@@ -0,0 +1,158 @@
+# Browser Compatibility Guide
+
+This document outlines the browser-compatible file operations API in the OpenHands TypeScript Client.
+
+## Overview
+
+The TypeScript client has been updated to work natively in browser environments without Node.js dependencies. The main changes involve file upload and download operations that now work with browser-native data types like `Blob`, `File`, and strings instead of file system paths.
+
+## File Upload API
+
+### `fileUpload(content, destinationPath, fileName?)`
+
+Upload content to the remote workspace.
+
+**Parameters:**
+- `content: string | Blob | File` - The content to upload
+- `destinationPath: string` - Where to save the file on the remote workspace
+- `fileName?: string` - Optional filename (auto-detected for File objects)
+
+**Examples:**
+
+```typescript
+const workspace = new RemoteWorkspace({
+  host: 'http://localhost:3000',
+  workingDir: '/tmp',
+  apiKey: 'your-api-key'
+});
+
+// Upload text content
+await workspace.fileUpload('Hello, World!', '/tmp/hello.txt', 'hello.txt');
+
+// Upload a File object (from file input)
+const fileInput = document.getElementById('fileInput') as HTMLInputElement;
+const file = fileInput.files[0];
+await workspace.fileUpload(file, '/tmp/uploads/');
+
+// Upload a Blob
+const blob = new Blob(['Some data'], { type: 'text/plain' });
+await workspace.fileUpload(blob, '/tmp/data.txt', 'data.txt');
+```
+
+### Convenience Methods
+
+#### `uploadText(text, destinationPath, fileName?)`
+Shorthand for uploading text content.
+
+```typescript
+await workspace.uploadText('Hello, World!', '/tmp/hello.txt');
+```
+
+#### `uploadFileObject(file, destinationPath)`
+Shorthand for uploading File objects.
+
+```typescript
+const file = fileInput.files[0];
+await workspace.uploadFileObject(file, '/tmp/uploads/');
+```
+
+## File Download API
+
+### `fileDownload(sourcePath)`
+
+Download a file from the remote workspace. Returns content as string or Blob.
+
+**Parameters:**
+- `sourcePath: string` - Path to the file on the remote workspace
+
+**Returns:** `Promise<FileDownloadResult>`
+
+```typescript
+interface FileDownloadResult {
+  success: boolean;
+  source_path: string;
+  content: string | Blob;
+  file_size?: number;
+  error?: string;
+}
+```
+
+**Example:**
+
+```typescript
+const result = await workspace.fileDownload('/tmp/data.txt');
+if (result.success) {
+  console.log('File content:', result.content);
+}
+```
+
+### Convenience Methods
+
+#### `downloadAsText(sourcePath)`
+Download file content as a string.
+
+```typescript
+const text = await workspace.downloadAsText('/tmp/hello.txt');
+console.log(text); // "Hello, World!"
+```
+
+#### `downloadAsBlob(sourcePath)`
+Download file content as a Blob.
+
+```typescript
+const blob = await workspace.downloadAsBlob('/tmp/image.png');
+// Use blob for further processing
+```
+
+#### `downloadAndSave(sourcePath, saveAsFileName?)`
+Download a file and trigger browser download dialog.
+
+```typescript
+// This will prompt the user to save the file
+await workspace.downloadAndSave('/tmp/report.pdf', 'my-report.pdf');
+```
+
+## Migration from Node.js API
+
+### Before (Node.js only)
+```typescript
+// Old API - required file system paths
+await workspace.fileUpload('/local/path/file.txt', '/remote/path/file.txt');
+await workspace.fileDownload('/remote/path/file.txt', '/local/path/file.txt');
+```
+
+### After (Browser compatible)
+```typescript
+// New API - works with browser data types
+const fileInput = document.getElementById('file') as HTMLInputElement;
+const file = fileInput.files[0];
+await workspace.fileUpload(file, '/remote/path/file.txt');
+
+const result = await workspace.fileDownload('/remote/path/file.txt');
+if (result.success) {
+  // Use result.content (string or Blob)
+  console.log(result.content);
+}
+```
+
+## Browser Testing
+
+A test file `test-browser.html` is included to verify browser compatibility. Open it in a browser after building the project to test the API without a running server.
+
+## Node.js Compatibility
+
+The new API is also compatible with Node.js environments. You can still use the client in Node.js applications by providing appropriate data types:
+
+```typescript
+import fs from 'fs';
+
+// Read file content and upload
+const content = await fs.promises.readFile('/local/file.txt', 'utf8');
+await workspace.fileUpload(content, '/remote/file.txt', 'file.txt');
+
+// Download and save
+const result = await workspace.fileDownload('/remote/file.txt');
+if (result.success && typeof result.content === 'string') {
+  await fs.promises.writeFile('/local/downloaded.txt', result.content);
+}
+```

README.md

@@ -14,6 +14,12 @@
 A TypeScript client library for the OpenHands Agent Server API. Mirrors the structure and functionality of the Python [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk),
 but only supports remote conversations.
 
+## ✨ Browser Compatible
+
+This client is **fully browser-compatible** and works without Node.js dependencies. File operations use browser-native APIs like `Blob`, `File`, and `FormData` instead of file system operations. Perfect for web applications, React apps, and other browser-based projects.
+
+See [BROWSER_COMPATIBILITY.md](./BROWSER_COMPATIBILITY.md) for detailed usage examples.
+
 ## Installation
 
 This package is published to GitHub Packages. You have two installation options:

examples/basic-usage.ts

@@ -6,10 +6,11 @@ import { Conversation, Agent, Workspace, AgentExecutionStatus } from '../src/ind
 
 async function main() {
   // Define the agent configuration
+  // Note: In a browser environment, you would get these values from your app's configuration
   const agent = new Agent({
     llm: {
       model: 'gpt-4',
-      api_key: process.env.OPENAI_API_KEY || 'your-openai-api-key',
+      api_key: 'your-openai-api-key', // Replace with your actual API key
     },
   });
 
@@ -18,7 +19,7 @@ async function main() {
     const workspace = new Workspace({
       host: 'http://localhost:3000',
       workingDir: '/tmp',
-      apiKey: process.env.SESSION_API_KEY || 'your-session-api-key',
+      apiKey: 'your-session-api-key', // Replace with your actual session API key
     });
 
     // Create a new conversation
@@ -87,7 +88,7 @@ async function loadExistingConversation() {
   const agent = new Agent({
     llm: {
       model: 'gpt-4',
-      api_key: process.env.OPENAI_API_KEY || 'your-openai-api-key',
+      api_key: 'your-openai-api-key', // Replace with your actual API key
     },
   });
 
@@ -96,7 +97,7 @@ async function loadExistingConversation() {
     const workspace = new Workspace({
       host: 'http://localhost:3000',
       workingDir: '/tmp',
-      apiKey: process.env.SESSION_API_KEY || 'your-session-api-key',
+      apiKey: 'your-session-api-key', // Replace with your actual session API key
     });
 
     const conversation = new Conversation(agent, workspace, {
@@ -120,6 +121,6 @@ async function loadExistingConversation() {
 }
 
 // Run the example
-if (require.main === module) {
-  main().catch(console.error);
-}
+// Note: In a browser environment, you would call main() directly or from an event handler
+// For Node.js environments, you can use import.meta.main (ES modules) or check if this is the main module
+main().catch(console.error);

package-lock.json

@@ -55,7 +55,7 @@ export type { AgentOptions } from './agent/agent';
 export { EventSortOrder, AgentExecutionStatus } from './types/base';
 
 // Workspace models
-export type { CommandResult, FileOperationResult, GitChange, GitDiff } from './models/workspace';
+export type { CommandResult, FileOperationResult, FileDownloadResult, GitChange, GitDiff } from './models/workspace';
 
 // Conversation models
 export type {

src/index.ts

@@ -18,6 +18,14 @@ export interface FileOperationResult {
   error?: string;
 }
 
+export interface FileDownloadResult {
+  success: boolean;
+  source_path: string;
+  content: string | Blob;
+  file_size?: number;
+  error?: string;
+}
+
 export interface GitChange {
   path: string;
   status: 'added' | 'modified' | 'deleted' | 'renamed';