agi 0.2.2 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGI Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,55 @@
-# AGI Browser
+<div align="center">
 
-AGI - Your intelligent browser worker
+<img src="https://cdn.prod.website-files.com/67be56277f6d514dcad939e2/67e48dd1cdab04c17a311669_logo-agi-white.png" alt="AGI" width="120"/>
+
+<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
+```
+
+<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
 
@@ -8,25 +57,498 @@ AGI - Your intelligent browser worker
 npm install agi
 ```
 
-**Note:** This package is currently only supported on macOS (darwin).
+Get your API key at [platform.agi.tech](https://platform.agi.tech/api-keys)
 
-## What it does
+```bash
+export AGI_API_KEY="your-api-key"
+```
 
-The AGI app provides an intelligent browser automation assistant that can help you navigate and interact with web pages.
+## Quick Start
 
-## Requirements
+### Simple Task (Recommended)
 
-- macOS (darwin)
-- Node.js >= 14.0.0
+```typescript
+import { AGIClient } from 'agi';
 
-## Post-install
+const client = new AGIClient({ apiKey: process.env.AGI_API_KEY });
 
-Install the AGI app
+// Context manager with automatic cleanup
+await using session = client.session('agi-0');
 
-## License
+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();
+}
+```
 
-MIT
+</details>
 
-## Author
+<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": {...}
+// }
+```
+
+</details>
+
+<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
+```
+
+**Manual Step Control:**
+
+```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;
+}
+```
+
+</details>
+
+---
+
+## Error Handling
+
+<details>
+<summary><b>Robust error handling with detailed debugging</b></summary>
+
+<br />
+
+```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);
+  }
+}
+```
+
+</details>
+
+---
+
+## Examples
+
+**Real-world, production-ready examples** → See [examples/](./examples)
+
+### Quick Start
+
+```bash
+# 5-line hello world
+npx tsx examples/hello-world.ts
+
+# Price tracking
+npx tsx examples/ecommerce/price-tracker.ts \
+  --product "Sony WH-1000XM5" --max-price 350
+
+# Flight search
+npx tsx examples/travel/flight-finder.ts \
+  --from SFO --to JFK --date "2026-02-15" --max-price 450
+
+# 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"
+```
+
+### 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
+
+**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)
+
+---
+
+## Documentation & Resources
+
+**Learn More**
+
+- [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
+
+**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;
+```
+
+---
+
+## Requirements
+
+- Node.js 20.4 or higher (required for `await using` syntax)
+- TypeScript 5.0+ (for TypeScript users)
+
+---
+
+## License
 
-AGI, Inc.
+MIT License - see [LICENSE](LICENSE) for details.