agi 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,824 @@
+/**
+ * Result types for task execution
+ */
+/**
+ * Task execution metadata and performance metrics
+ */
+interface TaskMetadata {
+    /** Unique task identifier */
+    taskId: string | number;
+    /** Session ID */
+    sessionId: string;
+    /** Execution time in seconds */
+    duration: number;
+    /** Task cost in USD (not yet provided by API) */
+    cost: number;
+    /** Task completion timestamp */
+    timestamp: Date;
+    /** Number of steps executed */
+    steps: number;
+    /** Whether task succeeded */
+    success: boolean;
+}
+/**
+ * Result of task execution
+ *
+ * @example
+ * ```typescript
+ * const result = await session.runTask("Find flights...");
+ * console.log(result.data);
+ * console.log(`Duration: ${result.metadata.duration}s`);
+ * console.log(`Steps: ${result.metadata.steps}`);
+ * ```
+ */
+interface TaskResult<T = unknown> {
+    /** Task output data */
+    data: T;
+    /** Execution metadata */
+    metadata: TaskMetadata;
+}
+
+/**
+ * Screenshot handling with image data and metadata
+ */
+/**
+ * Browser screenshot with decoded image data and metadata
+ *
+ * @example
+ * ```typescript
+ * const screenshot = await session.screenshot();
+ * await screenshot.save("page.png");
+ * console.log(`Size: ${screenshot.width}x${screenshot.height}`);
+ * console.log(`URL: ${screenshot.url}`);
+ * ```
+ */
+declare class Screenshot {
+    readonly data: Buffer;
+    readonly format: 'png' | 'jpg';
+    readonly timestamp: Date;
+    readonly width: number;
+    readonly height: number;
+    readonly url: string;
+    readonly title: string;
+    constructor(data: Buffer, format: 'png' | 'jpg', timestamp: Date, width: number, height: number, url: string, title: string);
+    /**
+     * Save screenshot to file
+     *
+     * @param path - File path to save to (e.g., "screenshot.png")
+     *
+     * @example
+     * ```typescript
+     * const screenshot = await session.screenshot();
+     * await screenshot.save("amazon.png");
+     * ```
+     */
+    save(path: string): Promise<void>;
+    /**
+     * Create Screenshot from base64 data URL
+     *
+     * @param base64Data - Base64-encoded data URL (e.g., "data:image/jpeg;base64,...")
+     * @param url - Current page URL
+     * @param title - Current page title
+     * @param timestamp - Screenshot timestamp (defaults to now)
+     * @returns Screenshot instance with decoded image data
+     */
+    static fromBase64(base64Data: string, url: string, title: string, timestamp?: Date): Screenshot;
+    /**
+     * Extract width and height from image data
+     *
+     * @param data - Raw image bytes
+     * @param format - Image format (png, jpg)
+     * @returns Tuple of (width, height)
+     */
+    private static getImageDimensions;
+}
+
+/**
+ * Type definitions for AGI SDK
+ */
+
+type SnapshotMode = 'none' | 'memory' | 'filesystem';
+type SessionStatus = 'ready' | 'running' | 'waiting_for_input' | 'paused' | 'finished' | 'error';
+type EventType = 'step' | 'thought' | 'question' | 'done' | 'error' | 'log' | 'paused' | 'resumed' | 'heartbeat' | 'user';
+type MessageType = 'THOUGHT' | 'QUESTION' | 'USER' | 'DONE' | 'ERROR' | 'LOG';
+interface AGIClientOptions {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for API (default: https://api.agi.tech) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+    /** Maximum number of retries (default: 3) */
+    maxRetries?: number;
+}
+interface CreateSessionOptions {
+    /** Webhook URL for session event notifications */
+    webhookUrl?: string;
+    /** Task goal (optional, can be set later via sendMessage) */
+    goal?: string;
+    /** Maximum number of agent steps (default: 100) */
+    maxSteps?: number;
+    /** Environment UUID to restore from */
+    restoreFromEnvironmentId?: string;
+}
+interface SessionResponse {
+    /** Session UUID */
+    sessionId: string;
+    /** VNC URL for browser access */
+    vncUrl?: string;
+    /** Agent service URL (desktop mode) */
+    agentUrl?: string;
+    /** Agent name */
+    agentName: string;
+    /** Session status */
+    status: SessionStatus;
+    /** Session creation timestamp */
+    createdAt: string;
+    /** Environment UUID for restore */
+    environmentId?: string;
+    /** Task goal */
+    goal?: string;
+}
+interface ExecuteStatusResponse {
+    /** Current execution status */
+    status: SessionStatus;
+}
+interface MessageResponse {
+    /** Message ID */
+    id: number;
+    /** Message type */
+    type: MessageType;
+    /** Message content */
+    content: string | Record<string, unknown> | Array<Record<string, unknown>>;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+interface MessagesResponse {
+    /** List of messages */
+    messages: MessageResponse[];
+    /** Current execution status */
+    status: string;
+    /** Whether agent is connected */
+    hasAgent: boolean;
+}
+interface SSEEvent {
+    /** Event ID */
+    id?: string;
+    /** Event type */
+    event: EventType;
+    /** Event data */
+    data: Record<string, unknown>;
+}
+interface NavigateResponse {
+    /** Current URL after navigation */
+    currentUrl: string;
+}
+interface ScreenshotResponse {
+    /** Base64-encoded JPEG data URL */
+    screenshot: string;
+    /** Current page URL */
+    url: string;
+    /** Current page title */
+    title: string;
+}
+interface SuccessResponse {
+    /** Operation success */
+    success: boolean;
+    /** Success message */
+    message: string;
+}
+interface DeleteResponse {
+    /** Operation success */
+    success: boolean;
+    /** Whether resource was deleted */
+    deleted: boolean;
+    /** Response message */
+    message: string;
+}
+interface MessageOptions {
+    /** Optional starting URL */
+    startUrl?: string;
+    /** Optional configuration updates */
+    configUpdates?: Record<string, unknown>;
+}
+interface RunTaskOptions {
+    /** Optional starting URL */
+    startUrl?: string;
+    /** Optional configuration updates */
+    configUpdates?: Record<string, unknown>;
+    /** Maximum time to wait for task completion in milliseconds (default: 600000 = 10 min) */
+    timeout?: number;
+    /** Polling interval in milliseconds (default: 3000 = 3s) */
+    pollInterval?: number;
+}
+interface StreamOptions {
+    /** Event types to filter */
+    eventTypes?: EventType[];
+    /** Sanitize event data */
+    sanitize?: boolean;
+    /** Include historical events */
+    includeHistory?: boolean;
+}
+
+/**
+ * Session context manager for high-level API
+ */
+
+/**
+ * High-level session context manager with automatic cleanup
+ *
+ * Use with `await using` for automatic session deletion:
+ *
+ * @example
+ * ```typescript
+ * await using session = client.session('agi-0');
+ * const result = await session.runTask('Find flights...');
+ * // Session automatically deleted
+ * ```
+ */
+declare class SessionContext {
+    private readonly client;
+    private readonly agentName;
+    private readonly createOptions?;
+    sessionId?: string;
+    vncUrl?: string;
+    agentUrl?: string;
+    constructor(client: AGIClient, agentName?: string, createOptions?: {
+        webhookUrl?: string;
+        goal?: string;
+        maxSteps?: number;
+        restoreFromEnvironmentId?: string;
+    } | undefined);
+    /**
+     * Automatic cleanup via explicit resource management
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Ensure session is created
+     */
+    private ensureSession;
+    /**
+     * Run a task and wait for completion using HTTP polling
+     *
+     * This method uses HTTP polling instead of SSE streaming for better reliability
+     * with long-running tasks and network instability.
+     *
+     * @param task - Natural language task description
+     * @param options - Task execution options
+     * @returns TaskResult with data and execution metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await session.runTask(
+     *   'Find cheapest iPhone 15 Pro',
+     *   { timeout: 300000, pollInterval: 2000 } // 5 min timeout, 2s polling
+     * );
+     * console.log(result.data);
+     * console.log(`Took ${result.metadata.duration}s, ${result.metadata.steps} steps`);
+     * ```
+     */
+    runTask(task: string, options?: {
+        startUrl?: string;
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<TaskResult>;
+    /**
+     * Send a message to the agent
+     *
+     * @param message - Message content
+     * @param options - Message options
+     * @returns SuccessResponse confirming message was sent
+     *
+     * @example
+     * ```typescript
+     * await session.sendMessage('Find flights from SFO to JFK under $450');
+     * ```
+     */
+    sendMessage(message: string, options?: {
+        startUrl?: string;
+        configUpdates?: Record<string, unknown>;
+    }): Promise<SuccessResponse>;
+    /**
+     * Get current execution status
+     *
+     * @returns ExecuteStatusResponse with status
+     *
+     * @example
+     * ```typescript
+     * const status = await session.getStatus();
+     * console.log(status.status);
+     * ```
+     */
+    getStatus(): Promise<ExecuteStatusResponse>;
+    /**
+     * Get messages from the session
+     *
+     * @param afterId - Return messages with ID > afterId (for polling)
+     * @param sanitize - Filter out system messages, prompts, and images
+     * @returns MessagesResponse with messages list and status
+     *
+     * @example
+     * ```typescript
+     * const messages = await session.getMessages(0);
+     * for (const msg of messages.messages) {
+     *   console.log(`[${msg.type}] ${msg.content}`);
+     * }
+     * ```
+     */
+    getMessages(afterId?: number, sanitize?: boolean): Promise<MessagesResponse>;
+    /**
+     * Stream real-time events from the session via Server-Sent Events
+     *
+     * @param options - Stream options
+     * @yields SSEEvent objects
+     *
+     * @example
+     * ```typescript
+     * 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;
+     *   }
+     * }
+     * ```
+     */
+    streamEvents(options?: {
+        eventTypes?: string[];
+        sanitize?: boolean;
+        includeHistory?: boolean;
+    }): AsyncGenerator<SSEEvent>;
+    /**
+     * Pause task execution
+     *
+     * @returns SuccessResponse confirming pause
+     *
+     * @example
+     * ```typescript
+     * await session.pause();
+     * ```
+     */
+    pause(): Promise<SuccessResponse>;
+    /**
+     * Resume paused task
+     *
+     * @returns SuccessResponse confirming resume
+     *
+     * @example
+     * ```typescript
+     * await session.resume();
+     * ```
+     */
+    resume(): Promise<SuccessResponse>;
+    /**
+     * Cancel task execution
+     *
+     * @returns SuccessResponse confirming cancellation
+     *
+     * @example
+     * ```typescript
+     * await session.cancel();
+     * ```
+     */
+    cancel(): Promise<SuccessResponse>;
+    /**
+     * Navigate browser to URL
+     *
+     * @param url - URL to navigate to
+     * @returns NavigateResponse with current URL
+     *
+     * @example
+     * ```typescript
+     * await session.navigate('https://amazon.com');
+     * ```
+     */
+    navigate(url: string): Promise<NavigateResponse>;
+    /**
+     * Get browser screenshot
+     *
+     * @returns Screenshot with decoded image data and save() method
+     *
+     * @example
+     * ```typescript
+     * const screenshot = await session.screenshot();
+     * await screenshot.save('page.png');
+     * console.log(`Size: ${screenshot.width}x${screenshot.height}`);
+     * ```
+     */
+    screenshot(): Promise<Screenshot>;
+}
+
+/**
+ * HTTP client for AGI API with fetch and SSE support
+ */
+
+interface RequestOptions {
+    json?: unknown;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+}
+declare class HTTPClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(options: AGIClientOptions);
+    /**
+     * Make an HTTP request with retries and error handling
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Stream Server-Sent Events from an endpoint
+     */
+    streamEvents(path: string, query?: Record<string, string>): AsyncGenerator<SSEEvent>;
+    private pendingEvents;
+    private buildUrl;
+    private buildHeaders;
+    private handleErrorResponse;
+    private sleep;
+}
+
+/**
+ * Sessions API resource
+ */
+
+/**
+ * Sessions API resource providing all session-related operations
+ */
+declare class SessionsResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    /**
+     * Create a new agent session
+     *
+     * @param agentName - Agent model to use (e.g., "agi-0", "agi-0-fast", "agi-1")
+     * @param options - Session creation options
+     * @returns SessionResponse with session_id, vnc_url, status, etc.
+     *
+     * @example
+     * ```typescript
+     * const session = await client.sessions.create('agi-0', {
+     *   webhookUrl: 'https://yourapp.com/webhook',
+     *   maxSteps: 200
+     * });
+     * ```
+     */
+    create(agentName?: string, options?: {
+        webhookUrl?: string;
+        goal?: string;
+        maxSteps?: number;
+        restoreFromEnvironmentId?: string;
+    }): Promise<SessionResponse>;
+    /**
+     * List all sessions for the authenticated user
+     *
+     * @returns Array of SessionResponse objects
+     *
+     * @example
+     * ```typescript
+     * const sessions = await client.sessions.list();
+     * for (const session of sessions) {
+     *   console.log(`${session.sessionId}: ${session.status}`);
+     * }
+     * ```
+     */
+    list(): Promise<SessionResponse[]>;
+    /**
+     * Get details for a specific session
+     *
+     * @param sessionId - Session UUID
+     * @returns SessionResponse with session details
+     *
+     * @example
+     * ```typescript
+     * const session = await client.sessions.get('session-uuid');
+     * console.log(session.status);
+     * ```
+     */
+    get(sessionId: string): Promise<SessionResponse>;
+    /**
+     * Delete a session and cleanup its resources
+     *
+     * @param sessionId - Session UUID
+     * @param saveSnapshotMode - Snapshot mode: "none", "memory", or "filesystem"
+     * @returns DeleteResponse confirming deletion
+     *
+     * @example
+     * ```typescript
+     * await client.sessions.delete('session-uuid', 'filesystem');
+     * ```
+     */
+    delete(sessionId: string, saveSnapshotMode?: SnapshotMode): Promise<DeleteResponse>;
+    /**
+     * Delete all sessions for the authenticated user
+     *
+     * @returns DeleteResponse with count of deleted sessions
+     *
+     * @example
+     * ```typescript
+     * const result = await client.sessions.deleteAll();
+     * console.log(result.message);
+     * ```
+     */
+    deleteAll(): Promise<DeleteResponse>;
+    /**
+     * Send a message to the agent to start a task or respond to questions
+     *
+     * @param sessionId - Session UUID
+     * @param message - Message content (task instruction or response)
+     * @param options - Message options
+     * @returns SuccessResponse confirming message was sent
+     *
+     * @example
+     * ```typescript
+     * await client.sessions.sendMessage(
+     *   'session-uuid',
+     *   'Find flights from SFO to JFK under $450'
+     * );
+     * ```
+     */
+    sendMessage(sessionId: string, message: string, options?: {
+        startUrl?: string;
+        configUpdates?: Record<string, unknown>;
+    }): Promise<SuccessResponse>;
+    /**
+     * Get the current execution status of a session
+     *
+     * @param sessionId - Session UUID
+     * @returns ExecuteStatusResponse with status
+     *
+     * @example
+     * ```typescript
+     * const status = await client.sessions.getStatus('session-uuid');
+     * if (status.status === 'finished') {
+     *   console.log('Task completed!');
+     * }
+     * ```
+     */
+    getStatus(sessionId: string): Promise<ExecuteStatusResponse>;
+    /**
+     * Poll for messages and updates from the agent
+     *
+     * @param sessionId - Session UUID
+     * @param afterId - Return messages with ID > afterId (for polling)
+     * @param sanitize - Filter out system messages, prompts, and images
+     * @returns MessagesResponse with messages list and status
+     *
+     * @example
+     * ```typescript
+     * const messages = await client.sessions.getMessages('session-uuid', 0);
+     * for (const msg of messages.messages) {
+     *   console.log(`[${msg.type}] ${msg.content}`);
+     * }
+     * ```
+     */
+    getMessages(sessionId: string, afterId?: number, sanitize?: boolean): Promise<MessagesResponse>;
+    /**
+     * Stream real-time events from the session via Server-Sent Events
+     *
+     * @param sessionId - Session UUID
+     * @param options - Stream options
+     * @yields SSEEvent objects
+     *
+     * @example
+     * ```typescript
+     * for await (const event of client.sessions.streamEvents('session-uuid')) {
+     *   if (event.event === 'thought') {
+     *     console.log('Agent:', event.data);
+     *   }
+     *   if (event.event === 'done') {
+     *     console.log('Result:', event.data);
+     *     break;
+     *   }
+     * }
+     * ```
+     */
+    streamEvents(sessionId: string, options?: {
+        eventTypes?: string[];
+        sanitize?: boolean;
+        includeHistory?: boolean;
+    }): AsyncGenerator<SSEEvent>;
+    /**
+     * Temporarily pause task execution
+     *
+     * @param sessionId - Session UUID
+     * @returns SuccessResponse confirming pause
+     *
+     * @example
+     * ```typescript
+     * await client.sessions.pause('session-uuid');
+     * ```
+     */
+    pause(sessionId: string): Promise<SuccessResponse>;
+    /**
+     * Resume a paused task
+     *
+     * @param sessionId - Session UUID
+     * @returns SuccessResponse confirming resume
+     *
+     * @example
+     * ```typescript
+     * await client.sessions.resume('session-uuid');
+     * ```
+     */
+    resume(sessionId: string): Promise<SuccessResponse>;
+    /**
+     * Cancel task execution
+     *
+     * @param sessionId - Session UUID
+     * @returns SuccessResponse confirming cancellation
+     *
+     * @example
+     * ```typescript
+     * await client.sessions.cancel('session-uuid');
+     * ```
+     */
+    cancel(sessionId: string): Promise<SuccessResponse>;
+    /**
+     * Navigate the browser to a specific URL
+     *
+     * @param sessionId - Session UUID
+     * @param url - URL to navigate to
+     * @returns NavigateResponse with current URL
+     *
+     * @example
+     * ```typescript
+     * await client.sessions.navigate('session-uuid', 'https://amazon.com');
+     * ```
+     */
+    navigate(sessionId: string, url: string): Promise<NavigateResponse>;
+    /**
+     * Get a screenshot of the browser
+     *
+     * @param sessionId - Session UUID
+     * @returns ScreenshotResponse with base64-encoded image, URL, and title
+     *
+     * @example
+     * ```typescript
+     * const screenshot = await client.sessions.screenshot('session-uuid');
+     * console.log(screenshot.url);
+     * ```
+     */
+    screenshot(sessionId: string): Promise<ScreenshotResponse>;
+}
+
+/**
+ * Main AGI API client
+ */
+
+/**
+ * Official TypeScript/JavaScript client for the AGI.tech API
+ *
+ * The AGIClient provides access to the AGI API for creating and managing
+ * AI agent sessions that can perform complex web tasks.
+ *
+ * @example
+ * Simple usage with context manager (recommended):
+ * ```typescript
+ * import { AGIClient } from 'agi-sdk';
+ *
+ * const client = new AGIClient({ apiKey: 'your_api_key' });
+ *
+ * await using session = client.session('agi-0');
+ * const result = await session.runTask('Find cheapest iPhone 15 on Amazon');
+ * console.log(result.data);
+ * console.log(`Duration: ${result.metadata.duration}s`);
+ * ```
+ *
+ * @example
+ * Advanced usage with low-level API:
+ * ```typescript
+ * const session = await client.sessions.create('agi-0', {
+ *   webhookUrl: 'https://yourapp.com/webhook'
+ * });
+ *
+ * await client.sessions.sendMessage(session.sessionId, 'Find flights...');
+ *
+ * for await (const event of client.sessions.streamEvents(session.sessionId)) {
+ *   if (event.event === 'thought') {
+ *     console.log('Agent:', event.data);
+ *   }
+ *   if (event.event === 'done') {
+ *     break;
+ *   }
+ * }
+ *
+ * await client.sessions.delete(session.sessionId);
+ * ```
+ */
+declare class AGIClient {
+    private readonly http;
+    /** Sessions resource for low-level API access */
+    readonly sessions: SessionsResource;
+    /**
+     * Create a new AGI client
+     *
+     * @param options - Client configuration options
+     *
+     * @example
+     * ```typescript
+     * // With explicit API key
+     * const client = new AGIClient({ apiKey: 'your_api_key' });
+     *
+     * // With custom base URL
+     * const client = new AGIClient({
+     *   apiKey: 'your_api_key',
+     *   baseUrl: 'https://custom-api.example.com',
+     *   timeout: 120000,
+     * });
+     * ```
+     */
+    constructor(options: AGIClientOptions);
+    /**
+     * Create a session context manager for easy session lifecycle management (recommended)
+     *
+     * This is the recommended way to use the SDK. The context manager automatically
+     * creates and deletes the session using `await using` syntax.
+     *
+     * @param agentName - Agent model to use (e.g., "agi-0", "agi-0-fast", "agi-1")
+     * @param options - Session creation options
+     * @returns SessionContext manager
+     *
+     * @example
+     * ```typescript
+     * // Simple usage
+     * await using session = client.session('agi-0');
+     * const result = await session.runTask('Find flights SFO→JFK under $450');
+     * console.log(result.data);
+     * // Session automatically deleted
+     *
+     * // With options
+     * await using session = client.session('agi-0', {
+     *   webhookUrl: 'https://yourapp.com/webhook',
+     *   maxSteps: 200
+     * });
+     * const result = await session.runTask('Research company XYZ');
+     * ```
+     */
+    session(agentName?: string, options?: {
+        webhookUrl?: string;
+        goal?: string;
+        maxSteps?: number;
+        restoreFromEnvironmentId?: string;
+    }): SessionContext;
+}
+
+/**
+ * Error classes for AGI SDK
+ */
+/**
+ * Base error class for all AGI API errors
+ */
+declare class AGIError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+/**
+ * Authentication error (401)
+ */
+declare class AuthenticationError extends AGIError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * Not found error (404)
+ */
+declare class NotFoundError extends AGIError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * Rate limit error (429)
+ */
+declare class RateLimitError extends AGIError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * Agent execution error (task failed)
+ */
+declare class AgentExecutionError extends AGIError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * Validation error (422)
+ */
+declare class ValidationError extends AGIError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * Permission error (403)
+ */
+declare class PermissionError extends AGIError {
+    constructor(message: string, response?: unknown);
+}
+/**
+ * API error (5xx server errors)
+ */
+declare class APIError extends AGIError {
+    constructor(message: string, statusCode?: number, response?: unknown);
+}
+
+export { AGIClient, type AGIClientOptions, AGIError, APIError, AgentExecutionError, AuthenticationError, type CreateSessionOptions, type DeleteResponse, type EventType, type ExecuteStatusResponse, type MessageOptions, type MessageResponse, type MessageType, type MessagesResponse, type NavigateResponse, NotFoundError, PermissionError, RateLimitError, type RunTaskOptions, type SSEEvent, Screenshot, type ScreenshotResponse, SessionContext, type SessionResponse, type SessionStatus, SessionsResource, type SnapshotMode, type StreamOptions, type SuccessResponse, type TaskMetadata, type TaskResult, ValidationError };