computer-agents 0.6.3 → 0.6.4

package/README.md

@@ -3,42 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/computer-agents.svg)](https://www.npmjs.com/package/computer-agents)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**The first orchestration framework for parallel computer-use agents.**
-
-Scale from 1 to 100+ agents. Run experiments in parallel. Test multiple approaches simultaneously. computer-agents enables agent workflows that were previously impossible.
-
-## What Makes This Different
-
-Traditional agent frameworks focus on chat-based LLM agents. computer-agents is built for **computer-use agents** that write code, run tests, and modify files—with native support for **parallel execution at scale**.
-
-### Before computer-agents
-
-- ❌ No parallel orchestration for computer-use agents
-- ❌ Single agent, single workspace, sequential execution
-- ❌ Hours to run experiments sequentially
-- ❌ Limited to local machine resources
-
-### With computer-agents
-
-- ✅ **Parallel Orchestration** - Run 10, 50, 100+ agents simultaneously
-- ✅ **Unified Interface** - Seamless local ↔ cloud execution with one config change
-- ✅ **Workspace Collaboration** - Multiple agents working on the same codebase
-- ✅ **Cloud Scalability** - Effortless scaling beyond local machine limits
-- ✅ **Session Continuity** - Automatic multi-turn conversations
-
-## Revolutionary Use Cases
-
-**🔬 Scientific Experiments**
-Run 20 experimental variations in parallel instead of sequentially. What took hours now takes minutes.
-
-**🧪 ML/AI Development**
-Test dozens of hyperparameter configurations simultaneously. Systematic exploration of model architectures at scale.
-
-**⚡️ Multi-Approach Problem Solving**
-Try 5 different implementation approaches in parallel. Let the agents find the best solution.
-
-**🚀 A/B Testing at Scale**
-Test multiple implementations, frameworks, or approaches concurrently. Data-driven decision making.
+Build agents that write code, run tests, and modify files. Supports both local and cloud execution with automatic session management.
 
 ## Installation
 
@@ -54,400 +19,246 @@ npm install computer-agents
 import { Agent, run } from 'computer-agents';
 
 const agent = new Agent({
-  type: "computer",
-  workspace: "./my-project",  // String path = automatic local execution
-  instructions: "You are an expert developer.",
-  debug: true  // Optional: show detailed logs
+  agentType: "computer",
+  workspace: "./my-project",
+  instructions: "You are an expert developer."
 });
 
 const result = await run(agent, "Create a Python script that calculates fibonacci numbers");
 console.log(result.finalOutput);
 ```
 
-### Cloud Computer Agent (Coming Soon)
-
-> **Note**: Cloud execution for remote execution is under development and will be available in an upcoming release. The infrastructure is production-ready, and we're finalizing API access for public use.
-
-When cloud execution becomes available, you'll use Projects for cloud workspaces:
+### LLM Agent
 
 ```typescript
-import { Agent, run, CloudClient } from 'computer-agents';
-
-// Cloud execution will be available soon
-const client = new CloudClient({ apiKey: process.env.TESTBASE_API_KEY });
-const project = await client.createProject({
-  name: 'my-project',
-  localPath: './my-project'  // Enable local sync
-});
+import { Agent, run } from 'computer-agents';
 
 const agent = new Agent({
-  type: "computer",
-  workspace: project,  // Project = automatic cloud execution
-  instructions: "You are an expert developer."
+  agentType: "llm",
+  model: "gpt-4o",
+  instructions: "You create detailed implementation plans."
 });
 
-const result = await run(agent, "Add unit tests to the fibonacci module");
+const result = await run(agent, "Plan how to add user authentication");
 console.log(result.finalOutput);
-// Files automatically synced from cloud to local workspace
 ```
 
-For now, use local execution (workspace as string) for all computer agent tasks.
+## Agent Types
+
+The SDK supports two agent types:
+
+| Type | Execution | Use Cases |
+|------|-----------|-----------|
+| `computer` | Codex SDK | Code generation, file operations, terminal commands |
+| `llm` | OpenAI API | Planning, reasoning, text generation |
 
-### Streaming Progress (Real-Time Visibility)
+### Computer Agents
 
-Track agent execution in real-time with `runStreamed()`:
+Computer agents execute code changes using the Codex SDK. They can create files, run commands, and modify codebases.
 
 ```typescript
-import { Agent, runStreamed } from 'computer-agents';
-
 const agent = new Agent({
-  type: "computer",
+  agentType: "computer",
   workspace: "./my-project",
+  instructions: "You are a Python developer."
 });
 
-// Stream events in real-time
-for await (const event of runStreamed(agent, 'Create a Python web scraper')) {
-  switch (event.type) {
-    case 'thread.started':
-      console.log(`🔗 Thread: ${event.thread_id}`);
-      break;
-    case 'turn.started':
-      console.log('🎬 Turn started');
-      break;
-    case 'item.completed':
-      if (event.item.type === 'file_change') {
-        const files = event.item.changes.map(c => `${c.kind} ${c.path}`).join(', ');
-        console.log(`✅ Files: ${files}`);
-      }
-      break;
-    case 'turn.completed':
-      console.log(`🎉 Completed (${event.usage.input_tokens + event.usage.output_tokens} tokens)`);
-      break;
-  }
-}
+await run(agent, "Add unit tests for the fibonacci module");
 ```
 
-**Event Types:**
-- `thread.started` - Session initialized with thread ID
-- `turn.started` - Agent begins processing
-- `item.started` - Tool call or action begins
-- `item.completed` - Tool call or action completes (includes file changes)
-- `turn.completed` - Processing finished (includes token usage)
-- `turn.failed` - Error occurred
-
-**Use Cases:**
-- Progress bars for long-running tasks
-- Real-time logging and debugging
-- Live UI updates in applications
-- Better UX for multi-step operations
+### LLM Agents
 
-**API Consistency:** `runStreamed()` mirrors `run()` - same signature, just with streaming!
+LLM agents use the OpenAI API for text generation and reasoning tasks.
 
 ```typescript
-// Standard execution
-const result = await run(agent, task);
+const agent = new Agent({
+  agentType: "llm",
+  model: "gpt-4o",
+  instructions: "You review code for quality and security."
+});
 
-// Streaming execution
-for await (const event of runStreamed(agent, task)) {
-  // Real-time progress
-}
+await run(agent, "Review the authentication implementation");
 ```
 
-### Project Management (Efficient Workspace Sync) - Coming Soon
+## Cloud Execution
 
-> **Note**: Project Management for cloud execution is under development and will be available in an upcoming release.
+### Cloud Agents
 
-When available, manage workspaces with the Project API - perfect for organizing code and syncing with cloud storage:
+Execute agents in cloud environments using the CloudClient:
 
 ```typescript
-import { CloudClient, Agent, run } from 'computer-agents';
-
-const client = new CloudClient({ apiKey: process.env.TESTBASE_API_KEY });
+import { Agent, run, CloudClient } from 'computer-agents';
 
-// Create a synced project (local ↔ cloud)
-const project = await client.createProject({
-  name: 'my-app',
-  localPath: './src'  // Enables bidirectional sync
+const client = new CloudClient({
+  apiKey: process.env.TESTBASE_API_KEY
 });
 
-// Incremental sync - only uploads changed files (10x faster!)
-await project.sync({ direction: 'up' });  // Upload changes
-await project.sync({ direction: 'down' }); // Download changes
-await project.sync({ direction: 'both' }); // Bi-directional sync
+// Create a cloud project
+const project = await client.createProject({ name: 'my-app' });
 
-// Agents automatically use project workspaces
+// Cloud agent
 const agent = new Agent({
-  type: 'computer',
-  workspace: project  // Project = cloud execution
+  agentType: "computer",
+  workspace: project,
+  instructions: "You are an expert developer."
 });
 
-await run(agent, 'Add user authentication');
-// Changes are tracked, next sync will be incremental!
-```
-
-**Key Benefits:**
-- **10x faster sync** - Only transfers changed files (SHA-256 hashing)
-- **Organized workspaces** - Manage multiple projects easily
-- **Automatic tracking** - Sync state persisted in `.testbase/sync-state.json`
-- **Flexible sync** - Choose `up`, `down`, or `both` directions
-
-**Example: Incremental Sync Performance**
-- Full workspace (500MB): ~35 seconds
-- Incremental (5MB changes): ~3 seconds
-
-```typescript
-// List all projects
-const projects = await client.listProjects();
-
-// Get existing project
-const project = await client.getProject('project-id');
-
-// Get sync statistics
-const stats = await project.getSyncStats();
-console.log(stats); // { lastSyncAt, fileCount, version }
-
-// Manual file operations
-await project.upload(['file1.txt', 'file2.txt']);
-await project.download(['file1.txt']);
-await project.readFile('config.json');
-await project.writeFile('config.json', '{ "new": "data" }');
-
-// Delete project
-await client.deleteProject(project.id);
+const result = await run(agent, "Add error handling to the API");
+console.log(result.finalOutput);
 ```
 
-### Parallel Execution
+### Project Management
 
-**Local Parallel Execution (Available Now):**
-
-You can run multiple agents in parallel for local development:
+Manage cloud workspaces with the Project API:
 
 ```typescript
-import { Agent, run } from 'computer-agents';
+import { CloudClient } from 'computer-agents';
 
-// Create 5 agents to test different approaches
-const frameworks = ['Express', 'Fastify', 'Koa', 'Hapi', 'Restify'];
-const agents = frameworks.map(framework => new Agent({
-  name: `${framework} Agent`,
-  type: 'computer',
-  workspace: `./test-${framework.toLowerCase()}`,
-  instructions: `You are an expert in ${framework}.`
-}));
-
-// Run all 5 in parallel!
-const results = await Promise.all(
-  agents.map((agent, i) => run(agent, `Create a REST API with ${frameworks[i]}`))
-);
-
-// All 5 implementations complete in the time it takes to run 1
-console.log('All 5 frameworks tested in parallel!');
-```
-
-**Cloud Parallel Execution (Coming Soon):**
-
-> **Note**: Large-scale parallel execution with cloud infrastructure is coming soon. When available, you'll be able to scale to 100+ concurrent agents using CloudClient and Projects.
-
-### LLM Agent (for planning and reasoning)
+const client = new CloudClient({ apiKey: process.env.TESTBASE_API_KEY });
 
-```typescript
-const planner = new Agent({
-  type: "llm",
-  model: "gpt-4o",
-  instructions: "You create detailed implementation plans."
+// Create project with local sync
+const project = await client.createProject({
+  name: 'my-app',
+  localPath: './src'  // Enables bidirectional sync
 });
 
-const plan = await run(planner, "Plan how to add user authentication");
-console.log(plan.finalOutput);
-```
-
-## Core Concepts
-
-computer-agents has just **2 core concepts**:
-
-1. **Agent** - Single unified interface for both LLM and computer-use agents
-2. **CloudClient** - Manage cloud projects and infrastructure (coming soon)
-
-### 1. Agent - Unified Interface
-
-```typescript
-type AgentType = 'llm' | 'computer';
-```
-
-| Type | Execution | Use Cases |
-|------|-----------|-----------|
-| `'llm'` | OpenAI API | Planning, reasoning, reviewing |
-| `'computer'` | Codex SDK | Code, tests, file operations, terminal commands |
+// Sync files
+await project.sync({ direction: 'both' });
 
-**Key insight:** Workspace type determines execution mode automatically:
+// File operations
+const files = await project.listFiles();
+const content = await project.readFile('config.json');
+await project.writeFile('settings.json', '{"debug": true}');
 
-```typescript
-// Local execution (workspace = string path)
-const localAgent = new Agent({
-  type: 'computer',
-  workspace: './my-project'  // String = local execution
-});
-
-// Cloud execution (workspace = Project) - Coming Soon
-const cloudAgent = new Agent({
-  type: 'computer',
-  workspace: project  // Project = cloud execution
-});
+// Sync statistics
+const stats = await project.getSyncStats();
+console.log(stats);  // { lastSyncAt, fileCount, version }
 ```
 
-### 2. CloudClient - Infrastructure Management (Coming Soon)
+### Streaming Events
 
-Single entry point for cloud operations:
+Monitor agent execution in real-time:
 
 ```typescript
-const client = new CloudClient({ apiKey: process.env.TESTBASE_API_KEY });
-
-// Project management
-const projects = await client.listProjects();
-const project = await client.createProject({ name: 'my-app' });
-await client.deleteProject(project.id);
-
-// Infrastructure (future)
-const containers = await client.listContainers();
-const stats = await client.getContainerStats(containerId);
-```
-
-### Session Continuity
-
-Agents automatically maintain context across multiple runs:
+import { Agent, runStreamed } from 'computer-agents';
 
-```typescript
 const agent = new Agent({
-  type: 'computer',
-  workspace: './my-project'
+  agentType: "computer",
+  workspace: "./my-project"
 });
 
-await run(agent, 'Create app.py');           // New session
-await run(agent, 'Add error handling');      // Continues same session!
-await run(agent, 'Add tests');               // Still same session!
-
-console.log(agent.currentThreadId);          // Thread ID maintained
-
-agent.resetSession();                         // Start fresh when needed
-await run(agent, 'New project');             // New session
-```
-
-## Examples
-
-Comprehensive examples demonstrating the power of computer-agents:
-
-```bash
-# Clone the repository
-git clone https://github.com/TestBase-ai/computer-agents.git
-cd computer-agents
-npm install
-npm run build
-
-# Streaming progress (real-time event visibility)
-node examples/testbase/streaming-progress.cjs
-
-# Workspace sync modes (default vs cloud-only)
-node examples/testbase/workspace-sync-modes.mjs
-
-# Parallel execution (the game changer!)
-node examples/testbase/parallel-execution.mjs
-
-# Scale experiments (ML hyperparameter tuning, algorithm comparison)
-node examples/testbase/scale-experiments.mjs
-
-# Multi-agent workflows (planner → executor → reviewer)
-node examples/testbase/multi-agent-workflow.mjs
-
-# Session continuity demonstration
-node examples/testbase/hello-world.mjs
+for await (const event of runStreamed(agent, 'Create a web scraper')) {
+  switch (event.type) {
+    case 'thread.started':
+      console.log(`Thread: ${event.thread_id}`);
+      break;
+    case 'item.completed':
+      if (event.item.type === 'file_change') {
+        const files = event.item.changes.map(c => `${c.kind} ${c.path}`).join(', ');
+        console.log(`Files: ${files}`);
+      }
+      break;
+    case 'turn.completed':
+      console.log(`Completed (${event.usage.input_tokens + event.usage.output_tokens} tokens)`);
+      break;
+  }
+}
 ```
 
-**[📂 View all examples →](https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase)**
-
 ## Multi-Agent Workflows
 
-Build custom workflows by composing agents:
+Compose multiple agents for complex tasks:
 
 ```typescript
 import { Agent, run } from 'computer-agents';
 
 // LLM creates plan
 const planner = new Agent({
-  type: 'llm',
+  agentType: 'llm',
   model: 'gpt-4o',
-  instructions: 'Create detailed implementation plans.'
+  instructions: 'Create implementation plans.'
 });
 
-// Computer agent executes plan
+// Computer agent executes
 const executor = new Agent({
-  type: 'computer',
+  agentType: 'computer',
   workspace: './my-project',
   instructions: 'Execute implementation plans.'
 });
 
 // LLM reviews result
 const reviewer = new Agent({
-  type: 'llm',
+  agentType: 'llm',
   model: 'gpt-4o',
-  instructions: 'Review implementations for quality.'
+  instructions: 'Review code quality.'
 });
 
-// Manual workflow composition - you control the flow
 const task = "Add user authentication";
 const plan = await run(planner, `Plan: ${task}`);
 const code = await run(executor, plan.finalOutput);
 const review = await run(reviewer, `Review: ${code.finalOutput}`);
 ```
 
-## Configuration
+## Session Continuity
 
-### Environment Variables
+Agents automatically maintain context across multiple runs:
 
-```bash
-# Required for LLM agents and computer agents (Codex SDK uses OpenAI)
-OPENAI_API_KEY=your-openai-key
+```typescript
+const agent = new Agent({
+  agentType: 'computer',
+  workspace: './my-project'
+});
 
-# Optional for CloudClient (when cloud execution becomes available)
-TESTBASE_API_KEY=your-testbase-key  # Get from testbase.ai
+await run(agent, 'Create app.py');
+await run(agent, 'Add error handling');  // Continues same session
+await run(agent, 'Add tests');  // Still same session
+
+console.log(agent.currentThreadId);  // Thread ID maintained
+
+agent.resetSession();  // Start fresh
+await run(agent, 'New project');  // New session
 ```
 
+## Configuration
+
 ### Agent Configuration
 
 ```typescript
 const agent = new Agent({
   name: "My Agent",                    // Optional, auto-generated if omitted
-  type: 'computer',                    // 'llm' | 'computer'
-
-  // Computer agent specific
+  agentType: 'computer',               // 'llm' | 'computer'
   workspace: './my-project',           // Required for computer agents
-                                       // String = local, Project = cloud
-
-  // LLM agent specific
   model: 'gpt-4o',                     // Required for LLM agents
-
-  // Execution settings (computer agents only)
-  debug: true,                         // Show detailed logs
-  timeout: 600000,                     // 10 minutes (default)
-  skipGitRepoCheck: true,              // Allow execution outside git repos (default: true)
-
-  // Shared
   instructions: "You are helpful.",    // System prompt
-  mcpServers: [...],                   // MCP server configurations (optional)
+  debug: false,                        // Show detailed logs
+  timeout: 600000,                     // 10 minutes (default)
+  mcpServers: [],                      // MCP server configurations
 });
 ```
 
-### CloudClient Configuration (Coming Soon)
+### CloudClient Configuration
 
 ```typescript
 const client = new CloudClient({
-  apiKey: process.env.TESTBASE_API_KEY,  // Required (or use env var)
-  debug: true,                            // Show detailed logs
+  apiKey: process.env.TESTBASE_API_KEY,  // Required
+  debug: false,                           // Show detailed logs
   timeout: 600000,                        // 10 minutes (default)
 });
 ```
 
+### Environment Variables
+
+```bash
+# Required for all agents
+OPENAI_API_KEY=your-openai-key
+
+# Required for CloudClient
+TESTBASE_API_KEY=your-testbase-key
+```
+
 ## MCP Server Integration
 
-Unified MCP configuration works for both agent types:
+Use Model Context Protocol servers with your agents:
 
 ```typescript
 import type { McpServerConfig } from 'computer-agents';
@@ -467,35 +278,13 @@ const mcpServers: McpServerConfig[] = [
   }
 ];
 
-// Works for both LLM and computer agents!
 const agent = new Agent({
-  type: 'computer',
+  agentType: 'computer',
   workspace: './my-project',
-  mcpServers  // Automatically converted to appropriate format
+  mcpServers
 });
 ```
 
-The SDK handles conversion automatically:
-- **LLM agents**: MCP servers → function tools
-- **Computer agents**: MCP servers → Codex SDK config
-
-## Performance
-
-### Local Execution (workspace = string path)
-- **Cold start**: <1 second
-- **Warm execution**: <100ms overhead
-- **Parallelization**: Limited by local CPU/memory
-
-### Cloud Execution (workspace = Project) - Coming Soon
-- **First execution**: 30-45 seconds (includes workspace sync)
-- **Subsequent runs**: ~5-10 seconds
-- **Parallelization**: Scale to 100+ agents
-
-### Cloud-Only Mode (no localPath in Project) - Coming Soon
-- **Execution**: Faster (no sync overhead)
-- **Parallelization**: Scale to 100+ agents
-- **Perfect for**: CI/CD, experiments, parallel tasks
-
 ## API Reference
 
 ### Agent
@@ -504,31 +293,10 @@ The SDK handles conversion automatically:
 class Agent {
   constructor(config: AgentConfiguration);
 
-  currentThreadId: string | undefined;  // Current session thread ID
-  resetSession(): void;                 // Start new session
-  workspace: string;                    // Workspace path
-  type: 'llm' | 'computer';            // Agent type
-}
-
-interface AgentConfiguration {
-  name?: string;                       // Optional, auto-generated if omitted
-  type: 'llm' | 'computer';           // Agent type
-
-  // Computer agent specific
-  workspace?: string | Project;        // Required for computer agents
-                                      // String = local, Project = cloud
-
-  // LLM agent specific
-  model?: string;                      // Required for LLM agents
-
-  // Execution settings (computer agents only)
-  debug?: boolean;                     // Show detailed logs
-  timeout?: number;                    // Execution timeout (default: 600000ms)
-  skipGitRepoCheck?: boolean;          // Allow execution outside git repos (default: true)
-
-  // Shared
-  instructions?: string;               // System prompt
-  mcpServers?: McpServerConfig[];      // MCP server configurations
+  currentThreadId: string | undefined;
+  resetSession(): void;
+  workspace: string;
+  agentType: 'llm' | 'computer';
 }
 ```
 
@@ -552,324 +320,97 @@ function runStreamed(
 ): AsyncGenerator<Event>;
 ```
 
-Stream real-time events during agent execution. Returns an async generator that yields:
-- `thread.started` - Session initialized
-- `turn.started` - Agent begins processing
-- `item.started` / `item.completed` - Tool calls and file changes
-- `turn.completed` - Processing finished with usage stats
-- `turn.failed` - Error occurred
-
-**Example:**
-```typescript
-for await (const event of runStreamed(agent, 'Create app.py')) {
-  console.log(event.type, event);
-}
-```
-
-### CloudClient (Coming Soon)
-
-> **Note**: CloudClient for cloud execution is under development and will be available in an upcoming release.
+### CloudClient
 
 ```typescript
 class CloudClient {
-  constructor(config?: {
-    apiKey?: string;              // Required (or env var TESTBASE_API_KEY)
-    debug?: boolean;
-    timeout?: number;             // default: 600000ms (10 min)
-  });
+  constructor(config?: CloudClientConfig);
 
-  // Project management
   async createProject(config: CreateProjectConfig): Promise<Project>;
   async listProjects(): Promise<Project[]>;
   async getProject(id: string): Promise<Project>;
   async deleteProject(id: string, hard?: boolean): Promise<void>;
-
-  // Infrastructure (future)
-  async listContainers(): Promise<Container[]>;
-  async getContainerStats(id: string): Promise<ContainerStats>;
 }
 ```
 
-### Project (Coming Soon)
-
-> **Note**: Project API for cloud execution is under development and will be available in an upcoming release.
+### Project
 
 ```typescript
 class Project {
-  // Properties
   readonly id: string;
   readonly name: string;
   readonly localPath: string | undefined;
   readonly cloudPath: string;
 
-  // Sync operations (when localPath provided)
   async sync(options?: SyncOptions): Promise<SyncResult>;
-  async upload(files: string[]): Promise<void>;
-  async download(files: string[]): Promise<void>;
-
-  // File operations
   async listFiles(pattern?: string): Promise<ProjectFile[]>;
   async readFile(path: string): Promise<string>;
   async writeFile(path: string, content: string): Promise<void>;
-
-  // Management
+  async upload(files: string[]): Promise<void>;
+  async download(files: string[]): Promise<void>;
   async delete(hard?: boolean): Promise<void>;
   async getStats(): Promise<ProjectStats>;
   async getSyncStats(): Promise<SyncStats>;
-  async resetSyncState(): Promise<void>;
 
-  // Workspace path for agents
   getWorkspacePath(): string;
 }
-
-// Create project via CloudClient
-const client = new CloudClient({ apiKey: process.env.TESTBASE_API_KEY });
-const project = await client.createProject({
-  name: 'my-app',
-  localPath: './src',       // Optional - enables sync if provided
-  description: 'My app',    // Optional
-  metadata: { ... },        // Optional
-});
-
-// Sync options (when localPath provided)
-await project.sync({
-  direction: 'both',        // 'up' | 'down' | 'both'
-  force: false,             // Force full sync (skip incremental)
-  pattern: '*.ts'          // Optional glob pattern
-});
-```
-
-### Runtime Classes (Internal Use)
-
-> **Note**: Runtime classes are used internally by the SDK. Most users should not need to interact with them directly. Use CloudClient for cloud operations instead.
-
-These classes are marked `@internal` and are primarily for advanced use cases:
-
-```typescript
-// For advanced use only - not needed for typical usage
-class LocalRuntime implements Runtime { ... }
-class CloudRuntime implements Runtime { ... }
-```
-
-## Architecture
-
-```
-computer-agents/
-├── packages/
-│   ├── agents-core/              # Core SDK
-│   │   ├── src/
-│   │   │   ├── agent.ts          # Agent class
-│   │   │   ├── run.ts            # Run loop
-│   │   │   ├── runtime/          # Runtime abstraction
-│   │   │   │   ├── LocalRuntime.ts
-│   │   │   │   ├── CloudRuntime.ts
-│   │   │   │   └── gcsWorkspace.ts
-│   │   │   ├── codex/            # Codex SDK integration
-│   │   │   ├── cloud/            # Cloud API client
-│   │   │   └── mcpConfig.ts      # Unified MCP types
-│   │   └── package.json
-│   │
-│   ├── agents/                   # Main package export
-│   ├── agents-openai/            # OpenAI provider
-│   └── cloud-infrastructure/     # GCE cloud execution server
-│
-└── examples/testbase/            # Working examples
-```
-
-## Best Practices
-
-### Choosing Local vs Cloud Execution
-
-**Use Local Execution (workspace = string) when:**
-- Development and rapid iteration
-- Working with local files/tools
-- No cloud infrastructure needed
-- Testing and debugging
-
-**Use Cloud Execution (workspace = Project) when:** *(Coming Soon)*
-- Parallel execution at scale
-- Production deployments
-- CI/CD pipelines
-- Need isolated execution environments
-- Experiments requiring multiple concurrent agents
-
-### Choosing Workspace Sync Mode
-
-**With localPath (bidirectional sync):** *(Coming Soon)*
-- You need results in your local filesystem
-- Continuing work locally after cloud execution
-- Interactive development workflows
-
-**Without localPath (cloud-only):** *(Coming Soon)*
-- CI/CD pipelines (no local filesystem)
-- Running experiments at scale
-- Parallel task execution
-- Faster execution (skip sync overhead)
-
-### Session Management
-
-Always use the **same agent instance** for session continuity:
-
-```typescript
-// ✅ Correct - same agent, continuous session
-const agent = new Agent({ type: 'computer', workspace: './project' });
-await run(agent, 'Task 1');
-await run(agent, 'Task 2');  // Continues session
-
-// ❌ Wrong - different agents, new sessions
-await run(new Agent({ type: 'computer', workspace: './project' }), 'Task 1');
-await run(new Agent({ type: 'computer', workspace: './project' }), 'Task 2');  // Different session!
 ```
 
-### Parallel Execution
-
-Use `Promise.all()` for parallel execution:
-
-```typescript
-const agents = [agent1, agent2, agent3];
-const tasks = ['Task 1', 'Task 2', 'Task 3'];
+## Examples
 
-// ✅ Parallel - all execute simultaneously
-const results = await Promise.all(
-  agents.map((agent, i) => run(agent, tasks[i]))
-);
+```bash
+# Clone the repository
+git clone https://github.com/TestBase-ai/computer-agents.git
+cd computer-agents
+npm install
+npm run build
 
-// ❌ Sequential - one at a time
-for (let i = 0; i < agents.length; i++) {
-  await run(agents[i], tasks[i]);  // Slower!
-}
+# Run examples
+node examples/testbase/hello-world.mjs
+node examples/testbase/multi-agent-workflow.mjs
+node examples/testbase/streaming-progress.cjs
 ```
 
-## Cloud Infrastructure
-
-> **Coming Soon**: Public access to cloud execution infrastructure is under development.
-
-computer-agents includes production-ready cloud infrastructure that will soon be available:
-
-- **GCS Bucket** - Workspace storage (`gs://testbase-workspaces`)
-- **GCE VM** - Codex SDK execution server
-- **Pay-per-token** - Credit-based billing system
-- **API Keys** - Database-backed authentication
-- **Budget Protection** - Daily/monthly spending limits
-- **Project Management** - Incremental sync with SHA-256 hashing
-
-The infrastructure is fully built and tested. We're finalizing API access for public use. Stay tuned for updates!
-
-For now, `LocalRuntime` provides full computer-use agent capabilities for local development.
-
-## Documentation
-
-- **[Examples](https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase)** - Comprehensive working examples
-- **[Cloud Infrastructure](./packages/cloud-infrastructure/README.md)** - Deployment and configuration
-- **[Architecture](../docs/ARCHITECTURE.md)** - System design and internals
+[View all examples →](https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase)
 
 ## Troubleshooting
 
 ### "OPENAI_API_KEY not set"
+
 ```bash
 export OPENAI_API_KEY=sk-...
 ```
 
-### "TESTBASE_API_KEY required" *(When using CloudClient)*
+### "TESTBASE_API_KEY required"
+
 ```bash
 export TESTBASE_API_KEY=your-key
 # Or provide in constructor:
 new CloudClient({ apiKey: 'your-key' })
 ```
 
-### Session continuity not working
-Ensure you're using the **same agent instance** across runs:
-```typescript
-const agent = new Agent({ type: 'computer', workspace: './project' });
-await run(agent, 'Task 1');
-await run(agent, 'Task 2');  // Same instance = session continues
-```
-
 ### "Computer agents require a workspace"
+
 Computer agents need a workspace parameter:
+
 ```typescript
-// ✅ Correct
-new Agent({ type: 'computer', workspace: './my-project' })
+// Correct
+new Agent({ agentType: 'computer', workspace: './my-project' })
 
-// ❌ Missing workspace
-new Agent({ type: 'computer' })  // Error!
+// Missing workspace - Error
+new Agent({ agentType: 'computer' })
 ```
 
-## What's New
-
-### v0.6.0 - Major UX Simplification
-
-**Breaking Changes:**
-- Runtime objects removed from public API - no more `LocalRuntime` or `CloudRuntime` in user code
-- Agent configuration simplified: `agentType` → `type`, workspace accepts `string | Project`
-- CloudClient introduced as single entry point for cloud operations
-- Execution settings moved from Runtime to Agent level
+### Session continuity not working
 
-**Benefits:**
-- 40-50% less code for typical use cases
-- Reduced core concepts from 5 to 2 (Agent + CloudClient)
-- More intuitive API with better TypeScript inference
-- Automatic runtime selection based on workspace type
+Use the same agent instance across runs:
 
-**Migration:**
 ```typescript
-// Before (v0.5.x)
-const agent = new Agent({
-  agentType: 'computer',
-  runtime: new LocalRuntime({ debug: true }),
-  workspace: './project'
-});
-
-// After (v0.6.0)
-const agent = new Agent({
-  type: 'computer',
-  workspace: './project',
-  debug: true
-});
+const agent = new Agent({ agentType: 'computer', workspace: './project' });
+await run(agent, 'Task 1');
+await run(agent, 'Task 2');  // Same instance = session continues
 ```
 
-See [MIGRATION_v0.5_to_v0.6.md](https://github.com/TestBase-ai/computer-agents/blob/main/MIGRATION_v0.5_to_v0.6.md) for complete migration guide.
-
-### v0.5.0
-- **Project Management System**: Organize and sync workspaces efficiently
-- Incremental sync with SHA-256 hashing - 10x faster than full sync
-- Track sync state automatically in `.testbase/sync-state.json`
-- Native Web API FormData for reliable file uploads
-- Seamless agent integration with project workspaces
-
-### v0.4.9
-- **Streaming Progress**: New `runStreamed()` function for real-time visibility
-- Stream events: thread.started, turn.started, item.completed, turn.completed
-- API consistency - mirrors `run()` signature for easy adoption
-- Perfect for progress bars, real-time logging, and better UX
-
-### v0.4.6
-- **Cloud-Only Mode**: `skipWorkspaceSync` option for CloudRuntime
-- Perfect for CI/CD and parallel experiments
-- Faster cloud execution (no sync overhead)
-
-### v0.4.5
-- Fixed maxBuffer overflow for large workspace syncs
-- Improved GCS operation stability
-
-### v0.4.0
-- Initial public release
-- Parallel computer-use agent orchestration
-- Unified local/cloud runtime abstraction
-- Session continuity
-
-## Differences from OpenAI Agents SDK
-
-computer-agents extends OpenAI's Agents SDK with:
-
-1. **Computer-use agent type** - Direct Codex SDK integration
-2. **Simplified API** - No runtime objects needed, workspace type determines execution
-3. **CloudClient** - Unified interface for cloud operations and project management
-4. **Parallel orchestration** - Native support for concurrent agents
-5. **Session continuity** - Automatic thread management
-6. **Cloud infrastructure** - Production-ready execution platform (coming soon for public access)
-7. **Unified MCP config** - Single configuration for all agent types
-
 ## License
 
 MIT
@@ -877,17 +418,10 @@ MIT
 ## Links
 
 - **GitHub**: [https://github.com/TestBase-ai/computer-agents](https://github.com/TestBase-ai/computer-agents)
-- **Examples**: [https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase](https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase)
 - **npm**: [https://www.npmjs.com/package/computer-agents](https://www.npmjs.com/package/computer-agents)
-- **Website**: [https://testbase.ai/computer-agents](https://testbase.ai/computer-agents)
+- **Documentation**: [https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase](https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase)
 
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/TestBase-ai/computer-agents/issues)
 - **Website**: [testbase.ai](https://testbase.ai)
-
----
-
-**Built with ❤️ by [TestBase](https://testbase.ai)**
-
-*Based on [OpenAI Agents SDK](https://github.com/openai/openai-agents-sdk) • Powered by [Codex SDK](https://github.com/anthropics/claude-code) • Cloud infrastructure on GCP*

package/dist/metadata.js

@@ -4,9 +4,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.METADATA = void 0;
 exports.METADATA = {
     "name": "computer-agents",
-    "version": "0.6.3",
+    "version": "0.6.4",
     "versions": {
-        "computer-agents": "0.6.3"
+        "computer-agents": "0.6.4"
     }
 };
 exports.default = exports.METADATA;

package/package.json

@@ -2,7 +2,7 @@
   "name": "computer-agents",
   "repository": "https://github.com/TestBase-ai/computer-agents",
   "homepage": "https://testbase.ai/computer-agents",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Build computer-use agents that write code, run tests, and deploy apps. Seamless local and cloud execution with automatic session continuity.",
   "author": "Testbase",
   "main": "dist/index.js",