computer-agents 1.0.3 → 1.1.0

package/README.md

@@ -1,511 +1,379 @@
 # Computer Agents SDK
 
-[![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)
-
-Build agents that write code, run tests, and modify files. Orchestrate unlimited agents in parallel with seamless local and cloud execution.
-
-## Why Computer Agents?
-
-Traditional agent frameworks limit you to single-agent workflows or rigid orchestration patterns. Computer Agents is designed for programmatic multi-agent orchestration at scale.
-
-**Unlimited Parallel Orchestration**
-Compose and run unlimited agents concurrently. Build custom multi-agent workflows programmatically—you control execution flow and agent communication. No framework constraints, just code.
-
-**Seamless Local ↔ Cloud Execution**
-Develop locally, scale to cloud by changing workspace configuration. Runtime abstraction handles the complexity while your code remains identical. Switch execution environments without rewriting workflows.
-
-**Two Powerful Agent Types**
-- **LLM agents** (OpenAI API) for planning, reasoning, and code review
-- **Computer agents** (Codex SDK) for code generation and file operations
-
-Mix agent types to build sophisticated workflows. Computer agents bypass LLM for tool selection, providing faster execution and lower costs.
-
-**Production-Ready Infrastructure**
-- Automatic session continuity across runs
-- Efficient workspace synchronization
-- Built on OpenAI Codex SDK
-- Type-safe TypeScript with comprehensive documentation
-
-**Use cases:** Parallel test generation, distributed code review, large-scale refactoring, automated debugging workflows, multi-repository updates.
+Official TypeScript/JavaScript SDK for the [Computer Agents Cloud API](https://api.computer-agents.com).
 
 ## Installation
 
 ```bash
 npm install computer-agents
+# or
+pnpm add computer-agents
+# or
+yarn add computer-agents
 ```
 
 ## Quick Start
 
-### Local Computer Agent
-
 ```typescript
-import { Agent, run } from 'computer-agents';
+import { ComputerAgentsClient } from 'computer-agents';
 
-const agent = new Agent({
-  agentType: "computer",
-  workspace: "./my-project",
-  instructions: "You are an expert developer."
+const client = new ComputerAgentsClient({
+  apiKey: process.env.COMPUTER_AGENTS_API_KEY
 });
 
-const result = await run(agent, "Create a Python script that calculates fibonacci numbers");
-console.log(result.finalOutput);
-```
-
-### LLM Agent
-
-```typescript
-import { Agent, run } from 'computer-agents';
-
-const agent = new Agent({
-  agentType: "llm",
-  model: "gpt-4o",
-  instructions: "You create detailed implementation plans."
+// Execute a task
+const result = await client.run('Create a REST API with Flask', {
+  environmentId: 'env_xxx',
+  onEvent: (event) => console.log(event.type)
 });
 
-const result = await run(agent, "Plan how to add user authentication");
-console.log(result.finalOutput);
+console.log(result.content);
 ```
 
-## Agent Types
+## Features
 
-The SDK supports two agent types:
+- Full TypeScript support with complete type definitions
+- SSE streaming for real-time execution progress
+- Simple, intuitive API that mirrors the REST API structure
+- Zero dependencies - uses native `fetch`
 
-| Type | Execution | Use Cases |
-|------|-----------|-----------|
-| `computer` | Codex SDK | Code generation, file operations, terminal commands |
-| `llm` | OpenAI API | Planning, reasoning, text generation |
-
-### Computer Agents
+## API Reference
 
-Computer agents execute code changes using the Codex SDK. They can create files, run commands, and modify codebases.
+### Creating a Client
 
 ```typescript
-const agent = new Agent({
-  agentType: "computer",
-  workspace: "./my-project",
-  instructions: "You are a Python developer."
+const client = new ComputerAgentsClient({
+  apiKey: 'tb_xxx',                              // Required
+  baseUrl: 'https://api.computer-agents.com',   // Optional (default)
+  timeout: 60000,                                // Optional (default: 60s)
+  debug: false                                   // Optional
 });
-
-await run(agent, "Add unit tests for the fibonacci module");
 ```
 
-### LLM Agents
+### Running Tasks
 
-LLM agents use the OpenAI API for text generation and reasoning tasks.
+The simplest way to execute a task:
 
 ```typescript
-const agent = new Agent({
-  agentType: "llm",
-  model: "gpt-4o",
-  instructions: "You review code for quality and security."
+// One-shot execution
+const result = await client.run('Fix the TypeScript errors', {
+  environmentId: 'env_xxx'
 });
 
-await run(agent, "Review the authentication implementation");
+// With streaming progress
+const result = await client.run('Build a REST API', {
+  environmentId: 'env_xxx',
+  onEvent: (event) => {
+    if (event.type === 'response.item.completed') {
+      console.log(event.item);
+    }
+  }
+});
+
+// Continue a conversation
+const followUp = await client.run('Add authentication', {
+  environmentId: 'env_xxx',
+  threadId: result.threadId
+});
 ```
 
-## Multi-Agent Workflows
+### Threads
 
-Compose multiple agents for complex tasks:
+For multi-turn conversations:
 
 ```typescript
-import { Agent, run } from 'computer-agents';
-
-// LLM creates plan
-const planner = new Agent({
-  agentType: 'llm',
-  model: 'gpt-4o',
-  instructions: 'Create implementation plans.'
+// Create a thread
+const thread = await client.threads.create({
+  environmentId: 'env_xxx'
 });
 
-// Computer agent executes
-const executor = new Agent({
-  agentType: 'computer',
-  workspace: './my-project',
-  instructions: 'Execute implementation plans.'
+// Send a message
+const result = await client.threads.sendMessage(thread.id, {
+  content: 'Create a REST API',
+  onEvent: (event) => console.log(event)
 });
 
-// LLM reviews result
-const reviewer = new Agent({
-  agentType: 'llm',
-  model: 'gpt-4o',
-  instructions: 'Review code quality.'
-});
+// List threads
+const threads = await client.threads.list();
 
-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}`);
+// Get a specific thread
+const thread = await client.threads.get('thread_xxx');
+
+// Delete a thread
+await client.threads.delete('thread_xxx');
 ```
 
-## Streaming Events
+### Environments
 
-Monitor agent execution in real-time:
+Manage isolated execution environments:
 
 ```typescript
-import { Agent, runStreamed } from 'computer-agents';
-
-const agent = new Agent({
-  agentType: "computer",
-  workspace: "./my-project"
+// Create an environment with custom configuration
+const env = await client.environments.create({
+  name: 'data-science',
+  description: 'Environment for data processing',
+  runtimes: { python: '3.12', nodejs: '20' },
+  packages: {
+    system: ['ffmpeg'],
+    python: ['pandas', 'numpy'],
+    node: ['typescript']
+  },
+  internetAccess: true
 });
 
-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;
-  }
-}
-```
+// List environments
+const environments = await client.environments.list();
 
-## Task Control
+// Get an environment
+const env = await client.environments.get('env_xxx');
 
-Control running agents with pause, resume, abort, and messaging capabilities:
+// Get default environment (creates one if doesn't exist)
+const defaultEnv = await client.environments.getDefault();
+
+// Update an environment
+await client.environments.update('env_xxx', {
+  description: 'Updated description'
+});
 
-### Local Control
+// Delete an environment
+await client.environments.delete('env_xxx');
+```
 
-Control agents running in the same process:
+#### Runtime Management
 
 ```typescript
-import { Agent, run } from 'computer-agents';
-
-const agent = new Agent({
-  agentType: 'computer',
-  workspace: './my-project'
+// List all available runtimes and versions
+const available = await client.environments.listAvailableRuntimes();
+// { python: ['3.9', '3.10', '3.11', '3.12', '3.13'], nodejs: ['18', '20', '22'], ... }
+
+// Get current runtimes for an environment
+const runtimes = await client.environments.getRuntimes('env_xxx');
+// { python: '3.12', nodejs: '20' }
+
+// Set runtime versions (triggers rebuild)
+await client.environments.setRuntimes('env_xxx', {
+  python: '3.12',
+  nodejs: '20',
+  go: '1.22'
 });
+```
 
-// Start a long-running task
-const taskPromise = run(agent, 'Analyze all TypeScript files');
+#### Package Management
 
-// Pause after 5 seconds
-setTimeout(async () => {
-  await agent.pause();
-  console.log('Agent paused');
+```typescript
+// List installed packages
+const packages = await client.environments.listPackages('env_xxx');
+// { system: ['ffmpeg'], python: ['pandas'], node: ['typescript'] }
 
-  // Resume later
-  await agent.resume();
-  await run(agent, 'Continue analysis');
-}, 5000);
+// Install packages (triggers rebuild)
+await client.environments.installPackages('env_xxx', 'python', ['requests', 'beautifulsoup4']);
+await client.environments.installPackages('env_xxx', 'system', ['imagemagick']);
+await client.environments.installPackages('env_xxx', 'node', ['tsx']);
 
-// Check status
-const status = agent.getStatus();
-console.log(status);
-// { status: 'running', threadId: 'thread-123', queuedMessages: 0 }
+// Uninstall a package (triggers rebuild)
+await client.environments.uninstallPackage('env_xxx', 'python', 'requests');
+```
 
-// Send messages
-await agent.sendMessage('Focus on performance issues');
+#### Dockerfile Customization
 
-// Abort permanently
-await agent.abort();
+```typescript
+// Get Dockerfile configuration
+const dockerfile = await client.environments.getDockerfile('env_xxx');
+// { baseImage: '...', dockerfileExtensions: '...', effectiveDockerfile: '...' }
+
+// Set Dockerfile extensions (triggers rebuild)
+await client.environments.setDockerfileExtensions('env_xxx',
+  'RUN pip install custom-package\nRUN apt-get install -y custom-tool'
+);
+
+// Validate Dockerfile syntax without building
+const validation = await client.environments.validateDockerfile('env_xxx',
+  'RUN pip install something'
+);
+// { valid: true, warnings: [], effectiveDockerfile: '...' }
 ```
 
-### Cloud Control API
+#### Build Management
 
-Control cloud agents remotely via HTTP endpoints:
-
-```bash
-# Get execution status
-curl -X GET https://api.testbase.ai/control/status/thread-abc-123 \
-  -H "X-API-Key: your-api-key"
-
-# Pause execution
-curl -X POST https://api.testbase.ai/control/pause/thread-abc-123 \
-  -H "X-API-Key: your-api-key"
-
-# Resume execution
-curl -X POST https://api.testbase.ai/control/resume/thread-abc-123 \
-  -H "X-API-Key: your-api-key"
-
-# Abort execution
-curl -X POST https://api.testbase.ai/control/abort/thread-abc-123 \
-  -H "X-API-Key: your-api-key"
-
-# Send message
-curl -X POST https://api.testbase.ai/control/message/thread-abc-123 \
-  -H "X-API-Key: your-api-key" \
-  -H "Content-Type: application/json" \
-  -d '{"message": "Focus on critical files only"}'
-
-# List all running executions
-curl -X GET https://api.testbase.ai/control/executions \
-  -H "X-API-Key: your-api-key"
-```
+```typescript
+// Trigger a build
+const build = await client.environments.triggerBuild('env_xxx');
+// { buildId: 'build_xxx', status: 'building', message: 'Build started' }
 
-### Control Methods
+// Force rebuild even if up to date
+await client.environments.triggerBuild('env_xxx', true);
 
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `agent.pause()` | Pause execution (can be resumed) | `Promise<void>` |
-| `agent.resume()` | Resume paused execution | `Promise<void>` |
-| `agent.abort()` | Stop permanently (cannot resume) | `Promise<void>` |
-| `agent.sendMessage(msg)` | Queue message for agent | `Promise<void>` |
-| `agent.getStatus()` | Get current status | `{ status, threadId, queuedMessages }` |
+// Get build status
+const status = await client.environments.getBuildStatus('env_xxx');
+// { buildStatus: 'ready', buildHash: '...', imageTag: '...', lastBuildAt: '...' }
 
-### Use Cases
+// Get build logs
+const logs = await client.environments.getBuildLogs('env_xxx');
+// { logs: '...', buildStatus: 'ready' }
 
-- **Long-running tasks**: Pause agents that exceed time limits
-- **User intervention**: Send messages to guide agent behavior
-- **Error recovery**: Abort stuck or misbehaving agents
-- **Resource management**: Control multiple cloud executions
-- **Interactive workflows**: Pause for user review, then resume
+// Test build (validates without caching)
+const test = await client.environments.testBuild('env_xxx');
+// { success: true, logs: '...', duration: 45000 }
+```
 
-## Session Continuity
+### Agents
 
-Agents automatically maintain context across multiple runs:
+Configure agent behavior:
 
 ```typescript
-const agent = new Agent({
-  agentType: 'computer',
-  workspace: './my-project'
+// Create an agent
+const agent = await client.agents.create({
+  name: 'Code Assistant',
+  model: 'gpt-4o',
+  instructions: 'You are a helpful coding assistant.'
 });
 
-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
+// List agents
+const agents = await client.agents.list();
 
-agent.resetSession();  // Start fresh
-await run(agent, 'New project');  // New session
+// Update an agent
+await client.agents.update('agent_xxx', {
+  instructions: 'Updated instructions'
+});
 ```
 
-## Cloud Execution (Coming Soon)
+### Files
 
-> **Note**: Cloud execution with `CloudClient` and `Project` management is currently in private beta. Public access coming soon.
->
-> Interested in early access? [Join the waitlist →](https://testbase.ai)
-
-Cloud execution will enable:
-- Run agents in isolated cloud environments
-- Project-based workspace management with bidirectional sync
-- Seamless transition from local to cloud with workspace configuration
-- Parallel execution at scale without local resource constraints
-
-Example (available in private beta):
+Manage files in environment workspaces:
 
 ```typescript
-import { Agent, run, CloudClient } from 'computer-agents';
-
-const client = new CloudClient({
-  apiKey: process.env.TESTBASE_API_KEY
+// List files in an environment
+const files = await client.files.listFiles('env_xxx');
+
+// Upload a file
+await client.files.uploadFile({
+  environmentId: 'env_xxx',
+  filename: 'app.py',
+  path: 'src',  // optional subdirectory
+  content: 'print("hello")'
 });
 
-// Create a cloud project
-const project = await client.createProject({ name: 'my-app' });
+// Download file content
+const content = await client.files.getFile('env_xxx', 'src/app.py');
 
-// Cloud agent
-const agent = new Agent({
-  agentType: "computer",
-  workspace: project,  // Use cloud project as workspace
-  instructions: "You are an expert developer."
+// Download as Buffer
+const buffer = await client.files.downloadFile('env_xxx', 'src/app.py');
+
+// Move/rename a file
+await client.files.moveFile({
+  environmentId: 'env_xxx',
+  sourcePath: 'old-name.py',
+  destPath: 'new-name.py'
 });
 
-const result = await run(agent, "Add error handling to the API");
-console.log(result.finalOutput);
+// Delete a file
+await client.files.deleteFile('env_xxx', 'src/app.py');
 ```
 
-## Configuration
+### Schedules
 
-### Agent Configuration
+Automate task execution:
 
 ```typescript
-const agent = new Agent({
-  name: "My Agent",                    // Optional, auto-generated if omitted
-  agentType: 'computer',               // 'llm' | 'computer'
-  workspace: './my-project',           // Required for computer agents
-  model: 'gpt-4o',                     // Required for LLM agents
-  instructions: "You are helpful.",    // System prompt
-  debug: false,                        // Show detailed logs
-  timeout: 600000,                     // 10 minutes (default)
-  mcpServers: [],                      // MCP server configurations
+// Create a schedule
+const schedule = await client.schedules.create({
+  name: 'Daily Report',
+  agentId: 'agent_xxx',
+  agentName: 'Reporter',
+  task: 'Generate daily report',
+  scheduleType: 'recurring',
+  cronExpression: '0 9 * * *'
 });
-```
-
-### Environment Variables
 
-```bash
-# Required for all agents
-OPENAI_API_KEY=your-openai-key
+// List schedules
+const schedules = await client.schedules.list();
 
-# Required for CloudClient (private beta)
-TESTBASE_API_KEY=your-testbase-key
+// Trigger a schedule manually
+await client.schedules.trigger('schedule_xxx');
 ```
 
-## MCP Server Integration
+### Billing
 
-Use Model Context Protocol servers with your agents:
+Track usage and manage budgets:
 
 ```typescript
-import type { McpServerConfig } from 'computer-agents';
-
-const mcpServers: McpServerConfig[] = [
-  {
-    type: 'stdio',
-    name: 'filesystem',
-    command: 'npx',
-    args: ['@modelcontextprotocol/server-filesystem', '/workspace']
-  },
-  {
-    type: 'http',
-    name: 'notion',
-    url: 'https://notion-mcp.example.com/mcp',
-    bearerToken: process.env.NOTION_TOKEN
-  }
-];
+// Get budget status
+const status = await client.budget.getStatus();
 
-const agent = new Agent({
-  agentType: 'computer',
-  workspace: './my-project',
-  mcpServers
-});
-```
-
-## API Reference
+// Check if can execute
+const canRun = await client.budget.canExecute();
 
-### Agent
+// Get billing records
+const records = await client.billing.listRecords({ limit: 10 });
 
-```typescript
-class Agent {
-  constructor(config: AgentConfiguration);
-
-  currentThreadId: string | undefined;
-  resetSession(): void;
-  workspace: string;
-  agentType: 'llm' | 'computer';
-
-  // Task control
-  async pause(): Promise<void>;
-  async resume(): Promise<void>;
-  async abort(): Promise<void>;
-  async sendMessage(message: string): Promise<void>;
-  getStatus(): { status: 'idle' | 'running' | 'paused' | 'aborted', threadId?: string, queuedMessages: number };
-}
+// Get usage stats
+const stats = await client.billing.getStats({ period: 'month' });
 ```
 
-### run()
+### Git Operations
 
-```typescript
-function run(
-  agent: Agent,
-  task: string,
-  options?: RunOptions
-): Promise<RunResult>;
-```
-
-### runStreamed()
+Manage version control:
 
 ```typescript
-function runStreamed(
-  agent: Agent,
-  task: string,
-  options?: RunOptions
-): AsyncGenerator<Event>;
-```
-
-### CloudClient (Coming Soon)
+// Get diff
+const diff = await client.git.diff('env_xxx');
 
-```typescript
-class CloudClient {
-  constructor(config?: CloudClientConfig);
+// Commit changes
+await client.git.commit('env_xxx', {
+  message: 'Add new feature'
+});
 
-  async createProject(config: CreateProjectConfig): Promise<Project>;
-  async listProjects(): Promise<Project[]>;
-  async getProject(id: string): Promise<Project>;
-  async deleteProject(id: string, hard?: boolean): Promise<void>;
-}
+// Push to remote
+await client.git.push('env_xxx');
 ```
 
-### Project (Coming Soon)
+## Error Handling
 
 ```typescript
-class Project {
-  readonly id: string;
-  readonly name: string;
-  readonly localPath: string | undefined;
-  readonly cloudPath: string;
-
-  async sync(options?: SyncOptions): Promise<SyncResult>;
-  async listFiles(pattern?: string): Promise<ProjectFile[]>;
-  async readFile(path: string): Promise<string>;
-  async writeFile(path: string, content: string): Promise<void>;
-  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>;
-
-  getWorkspacePath(): string;
+import { ComputerAgentsClient, ApiClientError } from 'computer-agents';
+
+try {
+  await client.run('Task', { environmentId: 'env_xxx' });
+} catch (error) {
+  if (error instanceof ApiClientError) {
+    console.error(`API Error: ${error.message}`);
+    console.error(`Status: ${error.status}`);
+    console.error(`Code: ${error.code}`);
+  }
 }
 ```
 
-## Examples
-
-```bash
-# Clone the repository
-git clone https://github.com/TestBase-ai/computer-agents.git
-cd computer-agents
-npm install
-npm run build
-
-# Run examples
-node examples/testbase/hello-world.mjs
-node examples/testbase/multi-agent-workflow.mjs
-node examples/testbase/streaming-progress.cjs
-```
-
-[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-...
-```
-
-### "Computer agents require a workspace"
+## Environment Variables
 
-Computer agents need a workspace parameter:
+| Variable | Description |
+|----------|-------------|
+| `COMPUTER_AGENTS_API_KEY` | API key for authentication |
 
-```typescript
-// Correct
-new Agent({ agentType: 'computer', workspace: './my-project' })
-
-// Missing workspace - Error
-new Agent({ agentType: 'computer' })
-```
+## TypeScript
 
-### Session continuity not working
-
-Use the same agent instance across runs:
+Full type definitions are included:
 
 ```typescript
-const agent = new Agent({ agentType: 'computer', workspace: './project' });
-await run(agent, 'Task 1');
-await run(agent, 'Task 2');  // Same instance = session continues
+import type {
+  // Core types
+  Thread,
+  Environment,
+  CloudAgent,
+  Schedule,
+  BudgetStatus,
+  MessageStreamEvent,
+
+  // Environment configuration
+  RuntimeConfig,
+  PackagesConfig,
+  AvailableRuntimes,
+  PackageType,
+  BuildStatus,
+  BuildStatusResult,
+  DockerfileResult,
+} from 'computer-agents';
 ```
 
 ## License
 
 MIT
-
-## Links
-
-- **GitHub**: [https://github.com/TestBase-ai/computer-agents](https://github.com/TestBase-ai/computer-agents)
-- **npm**: [https://www.npmjs.com/package/computer-agents](https://www.npmjs.com/package/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)