agi 0.4.0 → 0.5.1

package/README.md

@@ -1,554 +1,98 @@
-<div align="center">
+# @agi_inc/cli
 
-<img src="https://cdn.prod.website-files.com/67be56277f6d514dcad939e2/67e48dd1cdab04c17a311669_logo-agi-white.png" alt="AGI" width="120"/>
+Terminal-based AI agent for desktop automation. Give it a task in plain English and watch it take control of your computer to get it done.
 
-<h1>AGI Node.js SDK</h1>
-
-<p>
-  <a href="https://www.npmjs.com/package/agi"><img src="https://img.shields.io/npm/v/agi?style=flat-square" alt="npm version"></a>
-  <a href="https://github.com/agi-inc/agi-node/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/agi-inc/agi-node/ci.yml?branch=main&style=flat-square" alt="Build Status"></a>
-  <a href="https://codecov.io/gh/agi-inc/agi-node"><img src="https://img.shields.io/codecov/c/github/agi-inc/agi-node?style=flat-square" alt="Coverage"></a>
-  <a href="https://github.com/agi-inc/agi-node/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/agi?style=flat-square" alt="License"></a>
-  <a href="https://www.npmjs.com/package/agi"><img src="https://img.shields.io/npm/dm/agi?style=flat-square" alt="Downloads"></a>
-</p>
-
-<p>
-  <a href="https://www.theagi.company/">Website</a> •
-  <a href="https://docs.agi.tech">Documentation</a> •
-  <a href="https://platform.agi.tech">Platform</a> •
-  <a href="https://theagi.company/blog">Blog</a>
-</p>
-
----
-
-**Universal Computer-Use AI**
-
-<br />
-
-</div>
-
-```typescript
-import { AGIClient } from 'agi';
-
-const client = new AGIClient({ apiKey: process.env.AGI_API_KEY });
-
-// Context manager with automatic cleanup
-await using session = client.session('agi-0');
-
-const result = await session.runTask(
-  'Find three nonstop flights from SFO to JFK next month under $450. ' +
-    'Return flight times, airlines, and booking links.'
-);
-
-console.log(result.data);
-console.log(`Duration: ${result.metadata.duration}s, Steps: ${result.metadata.steps}`);
-// Session automatically deleted
+```bash
+npx @agi_inc/cli "open calculator and compute 2+2"
 ```
 
-<br />
-
-> Powered by [AGI.tech](https://agi.tech) - the world's most capable computer agent. Trusted by [Visa](https://www.theagi.company/blog/agi-inc-visa) for agentic commerce. Evaluated with [REAL Bench](https://www.theagi.company/blog/introducing-real-bench).
-
-<br />
-
 ## Installation
 
-```bash
-npm install agi
-```
-
-Get your API key at [platform.agi.tech](https://platform.agi.tech/api-keys)
+**Zero-install** (recommended):
 
 ```bash
-export AGI_API_KEY="your-api-key"
-```
-
-## Quick Start
-
-### Simple Task (Recommended)
-
-```typescript
-import { AGIClient } from 'agi';
-
-const client = new AGIClient({ apiKey: process.env.AGI_API_KEY });
-
-// Context manager with automatic cleanup
-await using session = client.session('agi-0');
-
-const result = await session.runTask('Find the cheapest iPhone 15 on Amazon');
-
-console.log(result.data); // Task output
-console.log(result.metadata.duration); // Execution time in seconds
-console.log(result.metadata.steps); // Number of steps taken
-// Session automatically deleted when scope exits
-```
-
-### Real-Time Event Streaming
-
-```typescript
-await using session = client.session('agi-0');
-
-await session.sendMessage('Research the top 5 AI companies in 2025');
-
-for await (const event of session.streamEvents()) {
-  if (event.event === 'thought') {
-    console.log('💭 Agent:', event.data);
-  }
-  if (event.event === 'done') {
-    console.log('✅ Result:', event.data);
-    break;
-  }
-}
-// Session automatically deleted
-```
-
-### Polling Configuration
-
-Configure timeouts and polling intervals for different task types:
-
-```typescript
-await using session = client.session('agi-0');
-
-// Quick task (1 min timeout, 2s polling)
-const result1 = await session.runTask('What is 2+2?', {
-  timeout: 60000,
-  pollInterval: 2000,
-});
-
-// Complex task (15 min timeout, 5s polling)
-const result2 = await session.runTask('Research AI companies...', {
-  timeout: 900000,
-  pollInterval: 5000,
-});
-```
-
-### Manual Session Management
-
-For advanced use cases requiring fine-grained control:
-
-```typescript
-// Create session manually
-const response = await client.sessions.create('agi-0', {
-  webhookUrl: 'https://yourapp.com/webhook',
-  maxSteps: 200,
-});
-
-// Send message
-await client.sessions.sendMessage(response.sessionId, 'Find flights from SFO to JFK under $450');
-
-// Check status
-const status = await client.sessions.getStatus(response.sessionId);
-
-// Delete when done
-await client.sessions.delete(response.sessionId);
-```
-
-### Session Control
-
-```typescript
-await using session = client.session('agi-0');
-
-await session.sendMessage('Long research task...');
-
-// Control execution
-await session.pause(); // Pause the agent
-await session.resume(); // Resume later
-await session.cancel(); // Or cancel
-```
-
----
-
-## Core Concepts
-
-_Understanding the building blocks of agi_
-
-### Sessions: The Container for Tasks
-
-Every task runs inside a **session** - an isolated browser environment:
-
-```typescript
-// Recommended: Context manager (automatic cleanup)
-await using session = client.session('agi-0');
-await session.runTask('Find flights...');
-// Session automatically deleted
-
-// Alternative: Manual management
-const response = await client.sessions.create('agi-0');
-await client.sessions.delete(response.sessionId);
-```
-
-▸ Use context managers (`await using`) for automatic cleanup. Sessions consume resources and should be deleted when done.
-
-### Available Agents
-
-- **agi-0** - General purpose agent (recommended)
-- **agi-0-fast** - Faster agent for simple tasks
-- **agi-1** - Advanced agent with enhanced capabilities
-
-See [docs.agi.tech](https://docs.agi.tech) for the full list.
-
----
-
-## Features
-
-- **Natural Language** - Describe tasks in plain English, no selectors or scraping code
-- **Real-Time Streaming** - Watch agent execution live with Server-Sent Events
-- **Session Control** - Pause, resume, or cancel long-running tasks
-- **Browser Control** - Navigate and screenshot for visual debugging
-- **Type-Safe** - Full TypeScript support with comprehensive type definitions
-- **Production-Ready** - Built-in retries, automatic cleanup, comprehensive error handling
-
----
-
-## Common Use Cases
-
-### Price Monitoring
-
-Monitor product prices and availability across retailers.
-
-```typescript
-const session = await client.createSession('agi-0');
-
-try {
-  const result = await session.runTask(
-    'Go to amazon.com and search for "Sony WH-1000XM5". ' +
-      "Get the current price, check if it's in stock, and return the product rating. " +
-      'Return as JSON with fields: price, in_stock, rating, url.'
-  );
-  console.log(result);
-} finally {
-  await session.delete();
-}
-```
-
-### Lead Generation
-
-Extract structured data from public sources.
-
-```typescript
-const session = await client.createSession('agi-0');
-
-try {
-  const result = await session.runTask(
-    'Go to ycombinator.com/companies, find companies in the "AI" category ' +
-      'from the latest batch. For the first 10 companies, get their name, ' +
-      'description, and website. Return as a JSON array.'
-  );
-  console.log(result);
-} finally {
-  await session.delete();
-}
-```
-
-### Flight Booking Research
-
-```typescript
-const session = await client.createSession('agi-0');
-
-try {
-  const result = await session.runTask(
-    'Find three nonstop SFO→JFK flights next month under $450. ' +
-      'Compare prices on Google Flights, Kayak, and Expedia. ' +
-      'Return flight details and booking links.'
-  );
-  console.log(result);
-} finally {
-  await session.delete();
-}
-```
-
-<details>
-<summary><b>Browser Control</b> – Navigate and take screenshots for visual debugging</summary>
-
-<br />
-
-```typescript
-const session = await client.createSession('agi-0');
-
-try {
-  // Navigate to specific URL
-  await session.navigate('https://amazon.com');
-
-  // Get screenshot for debugging
-  const screenshot = await session.screenshot();
-  console.log(screenshot.url); // Current page URL
-  console.log(screenshot.title); // Page title
-  // screenshot.screenshot contains base64 JPEG data
-} finally {
-  await session.delete();
-}
-```
-
-</details>
-
-<details>
-<summary><b>Session Snapshots</b> – Preserve authentication and browser state</summary>
-
-<br />
-
-```typescript
-// Create session and save environment
-const session1 = await client.createSession('agi-0');
-// ... do some authentication work ...
-await session1.delete('filesystem');
-
-// Later, restore from saved environment
-const session2 = await client.createSession('agi-0', {
-  restoreFromEnvironmentId: session1.environmentId,
-});
-// Authentication state and cookies preserved!
-
-await session2.delete();
-```
-
-</details>
-
-<details>
-<summary><b>Advanced Session Management</b> – Full control over session lifecycle</summary>
-
-<br />
-
-```typescript
-// Create session with options
-const session = await client.createSession('agi-0-fast', {
-  webhookUrl: 'https://yourapp.com/webhook',
-  maxSteps: 200,
-});
-
-// Send message
-await session.sendMessage('Find flights from SFO to JFK under $450');
-
-// Check status
-const status = await session.getStatus();
-console.log(status.status); // "running", "finished", etc.
-
-// List all sessions
-const sessions = await client.listSessions();
-
-// Delete when done
-await session.delete();
-```
-
-</details>
-
-<details>
-<summary><b>Webhooks</b> – Get notified when tasks complete</summary>
-
-<br />
-
-```typescript
-const session = await client.createSession('agi-0', {
-  webhookUrl: 'https://yourapp.com/webhook',
-});
-
-// Your webhook will receive events:
-// POST https://yourapp.com/webhook
-// {
-//   "event": "done",
-//   "session_id": "sess_...",
-//   "data": {...}
-// }
+npx @agi_inc/cli "your task here"
 ```
 
-</details>
+**Global install**:
 
-<details>
-<summary><b>Client-Driven Sessions</b> – Run agents on desktop, mobile, or custom environments</summary>
-
-<br />
-
-> **Note:** Desktop mode is currently feature-gated. For enterprise access, contact [`partner@theagi.company`](mailto:partner@theagi.company).
-
-For scenarios where you control the execution environment (desktop automation, mobile apps, custom browsers), use client-driven sessions with `AgentLoop`:
-
-```typescript
-import { AGIClient, AgentLoop } from 'agi';
-
-const client = new AGIClient({ apiKey: process.env.AGI_API_KEY });
-
-// Create a client-driven session
-const session = await client.sessions.create('agi-2-claude', {
-  agentSessionType: 'desktop',
-  goal: 'Open calculator and compute 2+2',
-});
-
-// Create and run the loop
-const loop = new AgentLoop({
-  client,
-  agentUrl: session.agentUrl!,
-  captureScreenshot: async () => {
-    // Return base64-encoded screenshot from your environment
-    return '...';
-  },
-  executeActions: async (actions) => {
-    for (const action of actions) {
-      console.log(`Executing: ${action.type}`);
-      // Execute action in your environment
-    }
-  },
-  onThinking: (t) => console.log(`💭 ${t}`),
-});
-
-const result = await loop.start();
-console.log(`Finished: ${result.finished}`);
-```
-
-**Loop Control:**
-
-```typescript
-// Start without awaiting
-const promise = loop.start();
-
-// Pause/resume/stop
-loop.pause(); // Pause after current step
-loop.resume(); // Continue execution
-loop.stop(); // Stop the loop
-
-// Check state
-loop.state; // 'running', 'paused', 'stopped', 'finished'
-loop.currentStep; // Current step number
-loop.lastResult; // Last StepDesktopResponse
+```bash
+npm install -g @agi_inc/cli
+agi "your task here"
 ```
 
-**Manual Step Control:**
+**Homebrew** (macOS/Linux):
 
-```typescript
-// Or manage the loop yourself
-let finished = false;
-while (!finished) {
-  const screenshot = await captureScreenshot();
-  const result = await client.sessions.step(session.agentUrl!, screenshot);
-  await executeActions(result.actions);
-  finished = result.finished;
-}
+```bash
+brew install agi-inc/tap/agi
+agi "your task here"
 ```
 
-</details>
-
----
-
-## Error Handling
-
-<details>
-<summary><b>Robust error handling with detailed debugging</b></summary>
+## Configuration
 
-<br />
+Set your API key before running:
 
-```typescript
-import {
-  AGIClient,
-  AuthenticationError,
-  NotFoundError,
-  RateLimitError,
-  AgentExecutionError,
-  AGIError,
-} from 'agi';
-
-const client = new AGIClient({ apiKey: process.env.AGI_API_KEY });
-
-try {
-  const session = await client.createSession('agi-0');
-  try {
-    const result = await session.runTask('Find flights...');
-    console.log(result);
-  } finally {
-    await session.delete();
-  }
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Invalid API key');
-  } else if (error instanceof NotFoundError) {
-    console.error('Session not found');
-  } else if (error instanceof RateLimitError) {
-    console.error('Rate limit exceeded - please retry');
-  } else if (error instanceof AgentExecutionError) {
-    console.error('Task failed:', error.message);
-    // Debug at VNC URL if available
-  } else if (error instanceof AGIError) {
-    console.error('API error:', error.message);
-  }
-}
+```bash
+export AGI_API_KEY=your_api_key
+# or
+export ANTHROPIC_API_KEY=your_api_key
 ```
 
-</details>
-
----
-
-## Examples
-
-**Real-world, production-ready examples** → See [examples/](./examples)
-
-### Quick Start
+## Usage
 
 ```bash
-# 5-line hello world
-npx tsx examples/hello-world.ts
+# Basic usage
+agi "Open calculator and compute 2+2"
 
-# Price tracking
-npx tsx examples/ecommerce/price-tracker.ts \
-  --product "Sony WH-1000XM5" --max-price 350
+# Use a specific model
+agi "Find flights from SFO to JFK" --model claude-opus
 
-# Flight search
-npx tsx examples/travel/flight-finder.ts \
-  --from SFO --to JFK --date "2026-02-15" --max-price 450
+# Verbose output (shows agent thinking)
+agi "Install Node.js" --verbose
 
-# B2B lead generation
-npx tsx examples/sales-marketing/linkedin-scraper.ts \
-  --industry "SaaS" --location "San Francisco" --count 10
-
-# Competitor analysis
-npx tsx examples/research/competitor-analysis.ts \
-  --competitors "stripe.com,square.com,paypal.com"
+# Auto-approve confirmations
+agi "Delete old files" --no-confirm
 ```
 
-### Example Categories
-
-- **[Basic](./examples#-basic-examples-basic)** (⭐ Beginner) - Quickstart, error handling, streaming
-- **[E-Commerce](./examples#-e-commerce-ecommerce)** (⭐⭐ Intermediate) - Price tracking, product comparison
-- **[Travel](./examples#️-travel-travel)** (⭐⭐ Intermediate) - Flight search, booking research
-- **[Sales & Marketing](./examples#-sales--marketing-sales-marketing)** (⭐⭐ Intermediate) - Lead generation, LinkedIn scraping
-- **[Research](./examples#-research-research)** (⭐⭐ Intermediate) - Competitive analysis, market research
-- **[Production](./examples#-production-patterns-production)** (⭐⭐⭐ Advanced) - Batch processing, webhook servers
+## Options
 
-**Learning Path**: [hello-world.ts](./examples/hello-world.ts) → [basic/quickstart.ts](./examples/basic/quickstart.ts) → [Choose your domain](./examples#-examples-by-category) → [Production patterns](./examples#-production-patterns-production)
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--model` | `-m` | Model to use (`claude-sonnet`, `claude-opus`) | `claude-sonnet` |
+| `--verbose` | `-v` | Show agent thinking | `false` |
+| `--no-confirm` | | Auto-approve confirmations | `false` |
+| `--help` | `-h` | Show help | |
+| `--version` | `-V` | Show version | |
 
----
+## Keyboard Shortcuts
 
-## Documentation & Resources
+While the agent is running:
 
-**Learn More**
+| Key | Action |
+|-----|--------|
+| `Space` | Pause/Resume |
+| `Q` | Stop |
+| `Ctrl+C` | Cancel |
 
-- [API Reference](https://docs.agi.tech) – Complete API documentation
-- [Code Examples](./examples) – 15+ production-ready examples
-- [GitHub Issues](https://github.com/agi-inc/agi-node/issues) – Report bugs or request features
+## How It Works
 
-**Get Help**
-
-- [Platform](https://platform.agi.tech) – Manage API keys and monitor usage
-- [Documentation](https://docs.agi.tech) – Guides and tutorials
-
----
-
-## TypeScript Support
-
-This SDK is written in TypeScript and provides full type definitions:
-
-```typescript
-import type { Session, SessionStatus, SSEEvent, NavigateResponse } from 'agi';
-
-const session: Session = await client.createSession('agi-0');
-const status: SessionStatus = (await session.getStatus()).status;
-```
-
----
+1. Captures screenshots of your desktop
+2. Analyzes them using Claude
+3. Decides on and executes actions
+4. Repeats until the task is complete
 
 ## Requirements
 
-- Node.js 20.4 or higher (required for `await using` syntax)
-- TypeScript 5.0+ (for TypeScript users)
+- Node.js 20.4.0 or later
+- macOS, Linux, or Windows
+- AGI API key or Anthropic API key
+
+## SDKs
 
----
+- [agi-python](https://github.com/agi-inc/agi-python) — Python SDK
+- [agi-node](https://github.com/agi-inc/agi-node) — Node.js SDK
+- [agi-csharp](https://github.com/agi-inc/agi-csharp) — C# SDK
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT

package/bin/agi

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import('../dist/index.mjs');