computer-agents 2.1.0 → 2.2.0

package/README.md

@@ -1,15 +1,14 @@
 # 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?color=success)](https://www.npmjs.com/package/computer-agents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Official TypeScript/JavaScript SDK for the [Computer Agents Cloud API](https://computer-agents.com). Execute Claude-powered AI agents in isolated cloud containers.
 
 ## Installation
 
 ```bash
 npm install computer-agents
-# or
-pnpm add computer-agents
-# or
-yarn add computer-agents
 ```
 
 ## Quick Start
@@ -23,7 +22,6 @@ const client = new ComputerAgentsClient({
 
 // Execute a task
 const result = await client.run('Create a REST API with Flask', {
-  environmentId: 'env_xxx',
   onEvent: (event) => console.log(event.type)
 });
 
@@ -32,54 +30,57 @@ console.log(result.content);
 
 ## Features
 
-- 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`
+- **Claude-powered** — agents run on Claude Opus 4.6, Sonnet 4.5, or Haiku 4.5
+- **Cloud execution** — isolated containers with persistent workspaces
+- **SSE streaming** — real-time execution progress and tool calls
+- **Session continuity** — multi-turn conversations via threads
+- **MCP integration** — extend capabilities with Model Context Protocol servers
+- **Skills** — web search, image generation, deep research
+- **Zero dependencies** — uses native `fetch`
+- **Full TypeScript support** — complete type definitions
+
+## Supported Models
+
+| Model | ID | Use Case |
+|-------|-----|----------|
+| Claude 4.6 Opus | `claude-opus-4-6` | Most capable, complex tasks |
+| Claude 4.5 Sonnet | `claude-sonnet-4-5` | Balanced (default) |
+| Claude 4.5 Haiku | `claude-haiku-4-5` | Fast, efficient |
 
 ## API Reference
 
-### Creating a Client
+### Client
 
 ```typescript
 const client = new ComputerAgentsClient({
-  apiKey: 'tb_xxx',                              // Required
-  baseUrl: 'https://api.computer-agents.com',   // Optional (default)
-  timeout: 60000,                                // Optional (default: 60s)
-  debug: false                                   // Optional
+  apiKey: 'your-api-key',                         // Required
+  baseUrl: 'https://api.computer-agents.com',     // Optional (default)
+  timeout: 60000,                                  // Optional (default: 60s)
+  debug: false                                     // Optional
 });
 ```
 
 ### Running Tasks
 
-The simplest way to execute a task:
-
 ```typescript
 // One-shot execution
 const result = await client.run('Fix the TypeScript errors', {
   environmentId: 'env_xxx'
 });
 
-// With streaming progress
+// With streaming
 const result = await client.run('Build a REST API', {
-  environmentId: 'env_xxx',
   onEvent: (event) => {
     if (event.type === 'response.item.completed') {
-      console.log(event.item);
+      console.log(event);
     }
   }
 });
-
-// Continue a conversation
-const followUp = await client.run('Add authentication', {
-  environmentId: 'env_xxx',
-  threadId: result.threadId
-});
 ```
 
 ### Threads
 
-For multi-turn conversations:
+Multi-turn conversations with persistent context:
 
 ```typescript
 // Create a thread
@@ -87,154 +88,103 @@ const thread = await client.threads.create({
   environmentId: 'env_xxx'
 });
 
-// Send a message
-const result = await client.threads.sendMessage(thread.id, {
-  content: 'Create a REST API',
+// Send messages — the agent remembers the full context
+await client.threads.sendMessage(thread.id, {
+  content: 'Create a Python web server',
   onEvent: (event) => console.log(event)
 });
 
-// List threads
-const threads = await client.threads.list();
-
-// Get a specific thread
-const thread = await client.threads.get('thread_xxx');
-
-// Delete a thread
-await client.threads.delete('thread_xxx');
-```
-
-### Environments
-
-Manage isolated execution environments:
-
-```typescript
-// 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
+await client.threads.sendMessage(thread.id, {
+  content: 'Add authentication to it',
+  onEvent: (event) => console.log(event)
 });
 
-// List environments
-const environments = await client.environments.list();
-
-// Get an environment
-const env = await client.environments.get('env_xxx');
-
-// 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'
+// Copy a thread to fork the conversation
+const copy = await client.threads.copy(thread.id, {
+  title: 'Experiment v2'
 });
 
-// Delete an environment
-await client.environments.delete('env_xxx');
-```
-
-#### Runtime Management
-
-```typescript
-// 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'
+// Search across threads
+const results = await client.threads.search({
+  query: 'REST API',
+  limit: 10
 });
-```
-
-#### Package Management
-
-```typescript
-// List installed packages
-const packages = await client.environments.listPackages('env_xxx');
-// { system: ['ffmpeg'], python: ['pandas'], node: ['typescript'] }
 
-// 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']);
+// Get execution logs
+const logs = await client.threads.getLogs(thread.id);
 
-// Uninstall a package (triggers rebuild)
-await client.environments.uninstallPackage('env_xxx', 'python', 'requests');
+// List, get, update, delete
+const threads = await client.threads.list();
+const t = await client.threads.get('thread_xxx');
+await client.threads.update('thread_xxx', { title: 'New title' });
+await client.threads.delete('thread_xxx');
 ```
 
-#### Dockerfile Customization
-
-```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: '...' }
-```
+### Agents
 
-#### Build Management
+Configure agent behavior with specific models and instructions:
 
 ```typescript
-// Trigger a build
-const build = await client.environments.triggerBuild('env_xxx');
-// { buildId: 'build_xxx', status: 'building', message: 'Build started' }
-
-// Force rebuild even if up to date
-await client.environments.triggerBuild('env_xxx', true);
-
-// Get build status
-const status = await client.environments.getBuildStatus('env_xxx');
-// { buildStatus: 'ready', buildHash: '...', imageTag: '...', lastBuildAt: '...' }
-
-// Get build logs
-const logs = await client.environments.getBuildLogs('env_xxx');
-// { logs: '...', buildStatus: 'ready' }
+const agent = await client.agents.create({
+  name: 'Senior Developer',
+  model: 'claude-sonnet-4-5',
+  instructions: 'You are a senior developer. Write clean, tested code.',
+  reasoningEffort: 'high'
+});
 
-// Test build (validates without caching)
-const test = await client.environments.testBuild('env_xxx');
-// { success: true, logs: '...', duration: 45000 }
+// Use the agent in a thread
+const thread = await client.threads.create({
+  environmentId: 'env_xxx',
+  agentId: agent.id
+});
 ```
 
-### Agents
+### Environments
 
-Configure agent behavior:
+Isolated containers with custom runtimes, packages, and configuration:
 
 ```typescript
-// Create an agent
-const agent = await client.agents.create({
-  name: 'Code Assistant',
-  model: 'gpt-4o',
-  instructions: 'You are a helpful coding assistant.'
+// Create an environment
+const env = await client.environments.create({
+  name: 'python-dev',
+  internetAccess: true
 });
 
-// List agents
-const agents = await client.agents.list();
+// Configure runtimes
+await client.environments.setRuntimes(env.id, {
+  python: '3.12',
+  nodejs: '20'
+});
+
+// Install packages
+await client.environments.installPackages(env.id, {
+  packages: [
+    { type: 'python', name: 'flask' },
+    { type: 'python', name: 'pytest' },
+    { type: 'system', name: 'curl' }
+  ]
+});
 
-// Update an agent
-await client.agents.update('agent_xxx', {
-  instructions: 'Updated instructions'
+// Add MCP servers
+await client.environments.update(env.id, {
+  mcpServers: [
+    {
+      type: 'stdio',
+      name: 'filesystem',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-filesystem', '/workspace']
+    },
+    {
+      type: 'http',
+      name: 'notion',
+      url: 'https://mcp.notion.com/mcp',
+      bearerToken: process.env.NOTION_TOKEN
+    }
+  ]
 });
+
+// Trigger a build
+await client.environments.build(env.id);
 ```
 
 ### Files
@@ -242,89 +192,92 @@ await client.agents.update('agent_xxx', {
 Manage files in environment workspaces:
 
 ```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
+  path: 'src/app.py',
   content: 'print("hello")'
 });
 
 // Download file content
 const content = await client.files.getFile('env_xxx', 'src/app.py');
 
-// 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'
-});
+// List files
+const files = await client.files.listFiles('env_xxx');
 
 // Delete a file
 await client.files.deleteFile('env_xxx', 'src/app.py');
 ```
 
+### Git
+
+Version control on workspaces:
+
+```typescript
+// View uncommitted changes
+const diff = await client.git.diff('env_xxx');
+
+// Commit and push
+await client.git.commit('env_xxx', { message: 'Add new feature' });
+await client.git.push('env_xxx');
+```
+
 ### Schedules
 
-Automate task execution:
+Automate recurring tasks:
 
 ```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 * * *'
+  name: 'Daily Code Review',
+  type: 'cron',
+  cronExpression: '0 9 * * *',
+  task: 'Review all uncommitted changes',
+  environmentId: 'env_xxx'
 });
 
-// List schedules
-const schedules = await client.schedules.list();
-
-// Trigger a schedule manually
-await client.schedules.trigger('schedule_xxx');
+// Trigger manually
+await client.schedules.trigger(schedule.id);
 ```
 
-### Billing
+### Budget
 
-Track usage and manage budgets:
+Monitor spending and control execution:
 
 ```typescript
-// Get budget status
 const status = await client.budget.getStatus();
+console.log(`Balance: $${(status.balance / 100).toFixed(2)}`);
 
-// Check if can execute
 const canRun = await client.budget.canExecute();
-
-// Get billing records
-const records = await client.billing.listRecords({ limit: 10 });
-
-// Get usage stats
-const stats = await client.billing.getStats({ period: 'month' });
+if (!canRun.canExecute) {
+  console.log('Budget exceeded:', canRun.reason);
+}
 ```
 
-### Git Operations
-
-Manage version control:
+## Streaming Events
 
 ```typescript
-// Get diff
-const diff = await client.git.diff('env_xxx');
-
-// Commit changes
-await client.git.commit('env_xxx', {
-  message: 'Add new feature'
+await client.threads.sendMessage(threadId, {
+  content: 'Build a REST API',
+  onEvent: (event) => {
+    switch (event.type) {
+      case 'response.started':
+        console.log('Execution started');
+        break;
+      case 'response.item.completed':
+        console.log('Item:', event);
+        break;
+      case 'response.completed':
+        console.log('Response finished');
+        break;
+      case 'stream.completed':
+        console.log('Done');
+        break;
+      case 'stream.error':
+        console.error('Error:', event);
+        break;
+    }
+  }
 });
-
-// Push to remote
-await client.git.push('env_xxx');
 ```
 
 ## Error Handling
@@ -333,7 +286,7 @@ await client.git.push('env_xxx');
 import { ComputerAgentsClient, ApiClientError } from 'computer-agents';
 
 try {
-  await client.run('Task', { environmentId: 'env_xxx' });
+  await client.run('Task');
 } catch (error) {
   if (error instanceof ApiClientError) {
     console.error(`API Error: ${error.message}`);
@@ -343,11 +296,31 @@ try {
 }
 ```
 
-## Environment Variables
+## Examples
+
+See the [`examples/`](./examples) directory for complete, runnable examples:
 
-| Variable | Description |
-|----------|-------------|
-| `COMPUTER_AGENTS_API_KEY` | API key for authentication |
+| Example | Description |
+|---------|-------------|
+| [Hello World](./examples/01-hello-world.ts) | Simplest possible usage |
+| [Multi-turn Conversation](./examples/02-multi-turn-conversation.ts) | Thread-based conversations |
+| [Streaming](./examples/03-streaming.ts) | Real-time SSE event handling |
+| [Custom Agent](./examples/04-custom-agent.ts) | Agent configuration with models and instructions |
+| [Environments](./examples/05-environments.ts) | Environment management |
+| [File Operations](./examples/06-file-operations.ts) | Upload, download, and manage files |
+| [Copy Thread](./examples/07-copy-thread.ts) | Fork conversations |
+| [Search Threads](./examples/08-search-threads.ts) | Full-text search across threads |
+| [MCP Servers](./examples/09-mcp-servers.ts) | Model Context Protocol integration |
+| [Git Operations](./examples/10-git-operations.ts) | Diffs, commits, and pushes |
+| [Budget Management](./examples/11-budget-management.ts) | Monitor spending |
+| [Schedules](./examples/12-schedules.ts) | Automate recurring tasks |
+| [Execution Logs](./examples/13-execution-logs.ts) | Logs and deep research sessions |
+
+Run any example:
+
+```bash
+COMPUTER_AGENTS_API_KEY=your-key npx tsx examples/01-hello-world.ts
+```
 
 ## TypeScript
 
@@ -355,25 +328,29 @@ Full type definitions are included:
 
 ```typescript
 import type {
-  // Core types
   Thread,
   Environment,
   CloudAgent,
   Schedule,
-  BudgetStatus,
+  Run,
+  AgentModel,
+  ReasoningEffort,
   MessageStreamEvent,
-
-  // Environment configuration
-  RuntimeConfig,
-  PackagesConfig,
-  AvailableRuntimes,
-  PackageType,
-  BuildStatus,
-  BuildStatusResult,
-  DockerfileResult,
+  McpServer,
+  BudgetStatus,
+  CopyThreadParams,
+  SearchThreadsResponse,
+  ThreadLogEntry,
+  ResearchSession,
 } from 'computer-agents';
 ```
 
 ## License
 
 MIT
+
+## Links
+
+- [Website](https://computer-agents.com)
+- [npm](https://www.npmjs.com/package/computer-agents)
+- [GitHub](https://github.com/computer-agents/computer-agents-sdk)

package/dist/cloud/resources/EnvironmentsResource.d.ts

@@ -157,11 +157,11 @@ export declare class EnvironmentsResource {
      */
     getStatus(environmentId: string): Promise<ContainerStatus>;
     /**
-     * Get the Codex configuration for an environment
+     * Get the agent configuration for an environment
      */
     getConfig(environmentId: string): Promise<string>;
     /**
-     * Update the Codex configuration for an environment
+     * Update the agent configuration for an environment
      */
     updateConfig(environmentId: string, config: string): Promise<void>;
 }

package/dist/cloud/resources/EnvironmentsResource.js

@@ -239,14 +239,14 @@ class EnvironmentsResource {
     // Configuration Management
     // =========================================================================
     /**
-     * Get the Codex configuration for an environment
+     * Get the agent configuration for an environment
      */
     async getConfig(environmentId) {
         const response = await this.client.get(`/environments/${environmentId}/config`);
         return response.config;
     }
     /**
-     * Update the Codex configuration for an environment
+     * Update the agent configuration for an environment
      */
     async updateConfig(environmentId, config) {
         await this.client.put(`/environments/${environmentId}/config`, { config });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "computer-agents",
-  "repository": "https://github.com/TestBase-ai/computer-agents",
+  "repository": "https://github.com/computer-agents/computer-agents-sdk",
   "homepage": "https://computer-agents.com",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Official SDK for the Computer Agents Cloud API. Execute Claude-powered AI agents in isolated cloud containers.",
   "author": "Computer Agents",
   "main": "dist/index.js",