computer-agents 0.7.1 → 1.0.0

package/README.md

@@ -1,511 +1,269 @@
 # 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
+  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");
-```
-
-## Multi-Agent Workflows
-
-Compose multiple agents for complex tasks:
-
-```typescript
-import { Agent, run } from 'computer-agents';
-
-// LLM creates plan
-const planner = new Agent({
-  agentType: 'llm',
-  model: 'gpt-4o',
-  instructions: 'Create implementation plans.'
-});
-
-// Computer agent executes
-const executor = new Agent({
-  agentType: 'computer',
-  workspace: './my-project',
-  instructions: 'Execute implementation plans.'
+// 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);
+    }
+  }
 });
 
-// LLM reviews result
-const reviewer = new Agent({
-  agentType: 'llm',
-  model: 'gpt-4o',
-  instructions: 'Review code quality.'
+// Continue a conversation
+const followUp = await client.run('Add authentication', {
+  environmentId: 'env_xxx',
+  threadId: result.threadId
 });
-
-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}`);
 ```
 
-## Streaming Events
+### Threads
 
-Monitor agent execution in real-time:
+For multi-turn conversations:
 
 ```typescript
-import { Agent, runStreamed } from 'computer-agents';
-
-const agent = new Agent({
-  agentType: "computer",
-  workspace: "./my-project"
+// Create a thread
+const thread = await client.threads.create({
+  environmentId: 'env_xxx'
 });
 
-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;
-  }
-}
-```
-
-## Task Control
-
-Control running agents with pause, resume, abort, and messaging capabilities:
-
-### Local Control
-
-Control agents running in the same process:
-
-```typescript
-import { Agent, run } from 'computer-agents';
-
-const agent = new Agent({
-  agentType: 'computer',
-  workspace: './my-project'
+// Send a message
+const result = await client.threads.sendMessage(thread.id, {
+  content: 'Create a REST API',
+  onEvent: (event) => console.log(event)
 });
 
-// Start a long-running task
-const taskPromise = run(agent, 'Analyze all TypeScript files');
-
-// Pause after 5 seconds
-setTimeout(async () => {
-  await agent.pause();
-  console.log('Agent paused');
+// List threads
+const threads = await client.threads.list();
 
-  // Resume later
-  await agent.resume();
-  await run(agent, 'Continue analysis');
-}, 5000);
+// Get a specific thread
+const thread = await client.threads.get('thread_xxx');
 
-// Check status
-const status = agent.getStatus();
-console.log(status);
-// { status: 'running', threadId: 'thread-123', queuedMessages: 0 }
-
-// Send messages
-await agent.sendMessage('Focus on performance issues');
-
-// Abort permanently
-await agent.abort();
+// Delete a thread
+await client.threads.delete('thread_xxx');
 ```
 
-### Cloud Control API
-
-Control cloud agents remotely via HTTP endpoints:
+### Environments
 
-```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"
-```
-
-### Control Methods
-
-| 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 }` |
-
-### Use Cases
-
-- **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
-
-## Session Continuity
-
-Agents automatically maintain context across multiple runs:
+Manage isolated execution environments:
 
 ```typescript
-const agent = new Agent({
-  agentType: 'computer',
-  workspace: './my-project'
+// Create an environment
+const env = await client.environments.create({
+  name: 'production',
+  internetAccess: true
 });
 
-await run(agent, 'Create app.py');
-await run(agent, 'Add error handling');  // Continues same session
-await run(agent, 'Add tests');  // Still same session
+// List environments
+const environments = await client.environments.list();
 
-console.log(agent.currentThreadId);  // Thread ID maintained
+// Get environment status
+const status = await client.environments.getStatus('env_xxx');
 
-agent.resetSession();  // Start fresh
-await run(agent, 'New project');  // New session
+// Start/stop environment
+await client.environments.start('env_xxx');
+await client.environments.stop('env_xxx');
 ```
 
-## Cloud Execution (Coming Soon)
+### Agents
 
-> **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):
+Configure agent behavior:
 
 ```typescript
-import { Agent, run, CloudClient } from 'computer-agents';
-
-const client = new CloudClient({
-  apiKey: process.env.TESTBASE_API_KEY
+// Create an agent
+const agent = await client.agents.create({
+  name: 'Code Assistant',
+  model: 'gpt-4o',
+  instructions: 'You are a helpful coding assistant.'
 });
 
-// Create a cloud project
-const project = await client.createProject({ name: 'my-app' });
+// List agents
+const agents = await client.agents.list();
 
-// Cloud agent
-const agent = new Agent({
-  agentType: "computer",
-  workspace: project,  // Use cloud project as workspace
-  instructions: "You are an expert developer."
+// Update an agent
+await client.agents.update('agent_xxx', {
+  instructions: 'Updated instructions'
 });
-
-const result = await run(agent, "Add error handling to the API");
-console.log(result.finalOutput);
 ```
 
-## Configuration
+### Files
 
-### Agent Configuration
+Manage files in environments:
 
 ```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
+// List files
+const files = await client.files.listFiles({
+  environmentId: 'env_xxx'
 });
-```
 
-### Environment Variables
+// Upload a file
+await client.files.uploadFile({
+  path: '/src/app.py',
+  content: 'print("hello")',
+  environmentId: 'env_xxx'
+});
 
-```bash
-# Required for all agents
-OPENAI_API_KEY=your-openai-key
+// Get file content
+const content = await client.files.getFile('/src/app.py', 'env_xxx');
 
-# Required for CloudClient (private beta)
-TESTBASE_API_KEY=your-testbase-key
+// Delete a file
+await client.files.deleteFile('/src/app.py');
 ```
 
-## MCP Server Integration
+### Schedules
 
-Use Model Context Protocol servers with your agents:
+Automate task execution:
 
 ```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
-  }
-];
-
-const agent = new Agent({
-  agentType: 'computer',
-  workspace: './my-project',
-  mcpServers
+// 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 * * *'
 });
-```
 
-## API Reference
+// List schedules
+const schedules = await client.schedules.list();
 
-### Agent
-
-```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 };
-}
+// Trigger a schedule manually
+await client.schedules.trigger('schedule_xxx');
 ```
 
-### run()
-
-```typescript
-function run(
-  agent: Agent,
-  task: string,
-  options?: RunOptions
-): Promise<RunResult>;
-```
+### Billing
 
-### runStreamed()
+Track usage and manage budgets:
 
 ```typescript
-function runStreamed(
-  agent: Agent,
-  task: string,
-  options?: RunOptions
-): AsyncGenerator<Event>;
-```
+// Get budget status
+const status = await client.budget.getStatus();
 
-### CloudClient (Coming Soon)
+// Check if can execute
+const canRun = await client.budget.canExecute();
 
-```typescript
-class CloudClient {
-  constructor(config?: CloudClientConfig);
+// Get billing records
+const records = await client.billing.listRecords({ limit: 10 });
 
-  async createProject(config: CreateProjectConfig): Promise<Project>;
-  async listProjects(): Promise<Project[]>;
-  async getProject(id: string): Promise<Project>;
-  async deleteProject(id: string, hard?: boolean): Promise<void>;
-}
+// Get usage stats
+const stats = await client.billing.getStats({ period: 'month' });
 ```
 
-### Project (Coming Soon)
+### Git Operations
+
+Manage version control:
 
 ```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;
-}
-```
+// Get diff
+const diff = await client.git.diff('env_xxx');
 
-## Examples
+// Commit changes
+await client.git.commit('env_xxx', {
+  message: 'Add new feature'
+});
 
-```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
+// Push to remote
+await client.git.push('env_xxx');
 ```
 
-[View all examples →](https://github.com/TestBase-ai/computer-agents/tree/main/examples/testbase)
+## Error Handling
 
-## Troubleshooting
-
-### "OPENAI_API_KEY not set"
-
-```bash
-export OPENAI_API_KEY=sk-...
+```typescript
+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}`);
+  }
+}
 ```
 
-### "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 {
+  Thread,
+  Environment,
+  CloudAgent,
+  Schedule,
+  BudgetStatus,
+  MessageStreamEvent,
+} 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)