computer-agents 1.0.2 → 1.0.3

package/README.md

@@ -1,282 +1,511 @@
 # Computer Agents SDK
 
-Official TypeScript/JavaScript SDK for the [Computer Agents Cloud API](https://api.computer-agents.com).
+[![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.
 
 ## Installation
 
 ```bash
 npm install computer-agents
-# or
-pnpm add computer-agents
-# or
-yarn add computer-agents
 ```
 
 ## Quick Start
 
+### Local Computer Agent
+
 ```typescript
-import { ComputerAgentsClient } from 'computer-agents';
+import { Agent, run } from 'computer-agents';
 
-const client = new ComputerAgentsClient({
-  apiKey: process.env.COMPUTER_AGENTS_API_KEY
+const agent = new Agent({
+  agentType: "computer",
+  workspace: "./my-project",
+  instructions: "You are an expert developer."
 });
 
-// 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, "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."
 });
 
-console.log(result.content);
+const result = await run(agent, "Plan how to add user authentication");
+console.log(result.finalOutput);
 ```
 
-## Features
+## 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`
+The SDK supports two agent types:
 
-## API Reference
+| Type | Execution | Use Cases |
+|------|-----------|-----------|
+| `computer` | Codex SDK | Code generation, file operations, terminal commands |
+| `llm` | OpenAI API | Planning, reasoning, text generation |
+
+### Computer Agents
 
-### Creating a Client
+Computer agents execute code changes using the Codex SDK. They can create files, run commands, and modify codebases.
 
 ```typescript
-const client = new ComputerAgentsClient({
-  apiKey: 'tb_xxx',                              // Required
-  baseUrl: 'https://api.computer-agents.com',   // Optional
-  timeout: 60000,                                // Optional (default: 60s)
-  debug: false                                   // Optional
+const agent = new Agent({
+  agentType: "computer",
+  workspace: "./my-project",
+  instructions: "You are a Python developer."
 });
+
+await run(agent, "Add unit tests for the fibonacci module");
 ```
 
-### Running Tasks
+### LLM Agents
 
-The simplest way to execute a task:
+LLM agents use the OpenAI API for text generation and reasoning tasks.
 
 ```typescript
-// One-shot execution
-const result = await client.run('Fix the TypeScript errors', {
-  environmentId: 'env_xxx'
+const agent = new Agent({
+  agentType: "llm",
+  model: "gpt-4o",
+  instructions: "You review code for quality and security."
 });
 
-// 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);
-    }
-  }
+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.'
 });
 
-// Continue a conversation
-const followUp = await client.run('Add authentication', {
-  environmentId: 'env_xxx',
-  threadId: result.threadId
+// Computer agent executes
+const executor = new Agent({
+  agentType: 'computer',
+  workspace: './my-project',
+  instructions: 'Execute implementation plans.'
+});
+
+// LLM reviews result
+const reviewer = new Agent({
+  agentType: 'llm',
+  model: 'gpt-4o',
+  instructions: 'Review code quality.'
 });
+
+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}`);
 ```
 
-### Threads
+## Streaming Events
 
-For multi-turn conversations:
+Monitor agent execution in real-time:
 
 ```typescript
-// Create a thread
-const thread = await client.threads.create({
-  environmentId: 'env_xxx'
-});
+import { Agent, runStreamed } from 'computer-agents';
 
-// Send a message
-const result = await client.threads.sendMessage(thread.id, {
-  content: 'Create a REST API',
-  onEvent: (event) => console.log(event)
+const agent = new Agent({
+  agentType: "computer",
+  workspace: "./my-project"
 });
 
-// List threads
-const threads = await client.threads.list();
+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;
+  }
+}
+```
 
-// Get a specific thread
-const thread = await client.threads.get('thread_xxx');
+## Task Control
 
-// Delete a thread
-await client.threads.delete('thread_xxx');
-```
+Control running agents with pause, resume, abort, and messaging capabilities:
 
-### Environments
+### Local Control
 
-Manage isolated execution environments:
+Control agents running in the same process:
 
 ```typescript
-// Create an environment
-const env = await client.environments.create({
-  name: 'production',
-  internetAccess: true
+import { Agent, run } from 'computer-agents';
+
+const agent = new Agent({
+  agentType: 'computer',
+  workspace: './my-project'
 });
 
-// List environments
-const environments = await client.environments.list();
+// Start a long-running task
+const taskPromise = run(agent, 'Analyze all TypeScript files');
 
-// Get an environment
-const env = await client.environments.get('env_xxx');
+// Pause after 5 seconds
+setTimeout(async () => {
+  await agent.pause();
+  console.log('Agent paused');
 
-// Update an environment
-await client.environments.update('env_xxx', {
-  internetAccess: false
-});
+  // Resume later
+  await agent.resume();
+  await run(agent, 'Continue analysis');
+}, 5000);
+
+// Check status
+const status = agent.getStatus();
+console.log(status);
+// { status: 'running', threadId: 'thread-123', queuedMessages: 0 }
 
-// Delete an environment
-await client.environments.delete('env_xxx');
+// Send messages
+await agent.sendMessage('Focus on performance issues');
+
+// Abort permanently
+await agent.abort();
 ```
 
-### Agents
+### Cloud Control API
+
+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"
+```
+
+### 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
 
-Configure agent behavior:
+- **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:
 
 ```typescript
-// Create an agent
-const agent = await client.agents.create({
-  name: 'Code Assistant',
-  model: 'gpt-4o',
-  instructions: 'You are a helpful coding assistant.'
+const agent = new Agent({
+  agentType: 'computer',
+  workspace: './my-project'
 });
 
-// List agents
-const agents = await client.agents.list();
+await run(agent, 'Create app.py');
+await run(agent, 'Add error handling');  // Continues same session
+await run(agent, 'Add tests');  // Still same session
 
-// Update an agent
-await client.agents.update('agent_xxx', {
-  instructions: 'Updated instructions'
-});
+console.log(agent.currentThreadId);  // Thread ID maintained
+
+agent.resetSession();  // Start fresh
+await run(agent, 'New project');  // New session
 ```
 
-### Files
+## Cloud Execution (Coming Soon)
+
+> **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)
 
-Manage files in environment workspaces:
+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):
 
 ```typescript
-// 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")'
-});
+import { Agent, run, CloudClient } from 'computer-agents';
 
-// Download file content
-const content = await client.files.getFile('env_xxx', 'src/app.py');
+const client = new CloudClient({
+  apiKey: process.env.TESTBASE_API_KEY
+});
 
-// Download as Buffer
-const buffer = await client.files.downloadFile('env_xxx', 'src/app.py');
+// Create a cloud project
+const project = await client.createProject({ name: 'my-app' });
 
-// Move/rename a file
-await client.files.moveFile({
-  environmentId: 'env_xxx',
-  sourcePath: 'old-name.py',
-  destPath: 'new-name.py'
+// Cloud agent
+const agent = new Agent({
+  agentType: "computer",
+  workspace: project,  // Use cloud project as workspace
+  instructions: "You are an expert developer."
 });
 
-// Delete a file
-await client.files.deleteFile('env_xxx', 'src/app.py');
+const result = await run(agent, "Add error handling to the API");
+console.log(result.finalOutput);
 ```
 
-### Schedules
+## Configuration
 
-Automate task execution:
+### Agent Configuration
 
 ```typescript
-// 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 * * *'
+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
 });
+```
+
+### Environment Variables
 
-// List schedules
-const schedules = await client.schedules.list();
+```bash
+# Required for all agents
+OPENAI_API_KEY=your-openai-key
 
-// Trigger a schedule manually
-await client.schedules.trigger('schedule_xxx');
+# Required for CloudClient (private beta)
+TESTBASE_API_KEY=your-testbase-key
 ```
 
-### Billing
+## MCP Server Integration
 
-Track usage and manage budgets:
+Use Model Context Protocol servers with your agents:
 
 ```typescript
-// Get budget status
-const status = await client.budget.getStatus();
+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
+});
+```
 
-// Check if can execute
-const canRun = await client.budget.canExecute();
+## API Reference
 
-// Get billing records
-const records = await client.billing.listRecords({ limit: 10 });
+### Agent
 
-// Get usage stats
-const stats = await client.billing.getStats({ period: 'month' });
+```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 };
+}
 ```
 
-### Git Operations
+### run()
 
-Manage version control:
+```typescript
+function run(
+  agent: Agent,
+  task: string,
+  options?: RunOptions
+): Promise<RunResult>;
+```
+
+### runStreamed()
 
 ```typescript
-// Get diff
-const diff = await client.git.diff('env_xxx');
+function runStreamed(
+  agent: Agent,
+  task: string,
+  options?: RunOptions
+): AsyncGenerator<Event>;
+```
 
-// Commit changes
-await client.git.commit('env_xxx', {
-  message: 'Add new feature'
-});
+### CloudClient (Coming Soon)
+
+```typescript
+class CloudClient {
+  constructor(config?: CloudClientConfig);
 
-// Push to remote
-await client.git.push('env_xxx');
+  async createProject(config: CreateProjectConfig): Promise<Project>;
+  async listProjects(): Promise<Project[]>;
+  async getProject(id: string): Promise<Project>;
+  async deleteProject(id: string, hard?: boolean): Promise<void>;
+}
 ```
 
-## Error Handling
+### Project (Coming Soon)
 
 ```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}`);
-  }
+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;
 }
 ```
 
-## Environment Variables
+## 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)
 
-| Variable | Description |
-|----------|-------------|
-| `COMPUTER_AGENTS_API_KEY` | API key for authentication |
+## Troubleshooting
 
-## TypeScript
+### "OPENAI_API_KEY not set"
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
 
-Full type definitions are included:
+### "Computer agents require a workspace"
+
+Computer agents need a workspace parameter:
 
 ```typescript
-import type {
-  Thread,
-  Environment,
-  CloudAgent,
-  Schedule,
-  BudgetStatus,
-  MessageStreamEvent,
-} from 'computer-agents';
+// Correct
+new Agent({ agentType: 'computer', workspace: './my-project' })
+
+// Missing workspace - Error
+new Agent({ agentType: 'computer' })
+```
+
+### Session continuity not working
+
+Use the same agent instance across runs:
+
+```typescript
+const agent = new Agent({ agentType: 'computer', workspace: './project' });
+await run(agent, 'Task 1');
+await run(agent, 'Task 2');  // Same instance = session continues
 ```
 
 ## 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)