agi 0.2.2 → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,1427 @@
+import { EventEmitter } from 'events';
+
+/**
+ * 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 AgentSessionType = 'managed-cdp' | 'external-cdp' | 'desktop';
+type SessionStatus = 'ready' | 'running' | 'waiting_for_input' | 'paused' | 'finished' | 'error';
+type EventType$1 = '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;
+    /** Agent session type */
+    agentSessionType?: AgentSessionType;
+    /** External CDP WebSocket URL (required for external-cdp session type) */
+    cdpUrl?: 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;
+    /** Agent session type */
+    agentSessionType?: 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$1;
+    /** 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$1[];
+    /** Sanitize event data */
+    sanitize?: boolean;
+    /** Include historical events */
+    includeHistory?: boolean;
+}
+type DesktopActionType = 'click' | 'double_click' | 'triple_click' | 'right_click' | 'hover' | 'type' | 'key' | 'scroll' | 'drag' | 'wait' | 'finish' | 'fail' | 'confirm' | 'ask_question';
+interface DesktopAction {
+    /** Action type */
+    type: DesktopActionType | string;
+    /** X coordinate (for click, hover, scroll) */
+    x?: number;
+    /** Y coordinate (for click, hover, scroll) */
+    y?: number;
+    /** Text to type (for type action) */
+    text?: string;
+    /** Content to type (alias for text) */
+    content?: string;
+    /** Key or key combination (for key action) */
+    key?: string;
+    /** Scroll direction (for scroll action) */
+    direction?: 'up' | 'down' | 'left' | 'right';
+    /** Scroll amount in lines (for scroll action) */
+    amount?: number;
+    /** Wait duration in seconds (for wait action) */
+    duration?: number;
+    /** Start X coordinate (for drag action) */
+    start_x?: number;
+    /** Start Y coordinate (for drag action) */
+    start_y?: number;
+    /** End X coordinate (for drag action) */
+    end_x?: number;
+    /** End Y coordinate (for drag action) */
+    end_y?: number;
+    /** Summary message (for finish action) */
+    summary?: string;
+    /** Reason message (for fail action) */
+    reason?: string;
+    /** Question to ask (for ask_question action) */
+    question?: string;
+    /** Additional action properties */
+    [key: string]: unknown;
+}
+interface StepDesktopRequest {
+    /** Base64-encoded screenshot (full resolution). Viewport dimensions are extracted from the image. */
+    screenshot: string;
+    /** Optional user message (e.g., initial goal or follow-up instruction) */
+    message?: string;
+}
+interface StepDesktopResponse {
+    /** Actions to execute (flat format) */
+    actions: DesktopAction[];
+    /** Model reasoning */
+    thinking?: string;
+    /** Whether the task is complete */
+    finished: boolean;
+    /** Question for user, if any */
+    askUser?: string;
+    /** Current step number */
+    step: number;
+}
+interface ModelsResponse {
+    /** Available agent models */
+    models: string[];
+}
+
+/**
+ * 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>;
+    /**
+     * Make an HTTP request to an absolute URL with retries and error handling
+     */
+    requestUrl<T>(method: string, url: 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-2-claude")
+     * @param options - Session creation options
+     * @returns SessionResponse with sessionId, vncUrl, agentUrl, status, etc.
+     *
+     * @example
+     * ```typescript
+     * // Standard browser session
+     * const session = await client.sessions.create('agi-0', {
+     *   webhookUrl: 'https://yourapp.com/webhook',
+     *   maxSteps: 200
+     * });
+     *
+     * // Desktop session (client-managed)
+     * const session = await client.sessions.create('agi-2-claude', {
+     *   agentSessionType: 'desktop',
+     *   goal: 'Open calculator and compute 2+2'
+     * });
+     * console.log(session.agentUrl); // Use with client.desktop.step()
+     * ```
+     */
+    create(agentName?: string, options?: {
+        webhookUrl?: string;
+        goal?: string;
+        maxSteps?: number;
+        restoreFromEnvironmentId?: string;
+        agentSessionType?: string;
+        cdpUrl?: 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>;
+    /**
+     * Execute a single step for client-driven sessions (desktop mode).
+     *
+     * In desktop mode (agentSessionType="desktop"), the client manages the
+     * execution loop. This method sends a screenshot to the agent and receives
+     * actions to execute locally.
+     *
+     * @param agentUrl - Agent service URL from session.agentUrl
+     * @param sessionId - Session ID (required for routing in shared sandbox)
+     * @param screenshot - Base64-encoded screenshot (full resolution, JPEG or PNG)
+     * @param message - Optional user message (goal on first call, or follow-up instruction)
+     * @returns StepDesktopResponse with actions, thinking, finished, askUser, and step
+     *
+     * @example
+     * ```typescript
+     * // Create a desktop session
+     * const session = await client.sessions.create('agi-2-claude', {
+     *   agentSessionType: 'desktop',
+     *   goal: 'Open calculator and compute 2+2'
+     * });
+     *
+     * // Client-managed loop
+     * let finished = false;
+     * while (!finished) {
+     *   const screenshot = captureScreenshot(); // Client captures
+     *   const result = await client.sessions.step(
+     *     session.agentUrl!,
+     *     session.sessionId,
+     *     screenshot
+     *   );
+     *   executeActions(result.actions); // Client executes
+     *   finished = result.finished;
+     *   if (result.askUser) {
+     *     const answer = await promptUser(result.askUser);
+     *     // Send answer in next step
+     *   }
+     * }
+     * ```
+     */
+    step(agentUrl: string, sessionId: string, screenshot: string, message?: string): Promise<StepDesktopResponse>;
+    /**
+     * List available agent models.
+     *
+     * @param filter - Optional filter: "cdp" for browser agents, "desktop" for
+     *                 desktop agents
+     * @returns ModelsResponse with list of available model names
+     *
+     * @example
+     * ```typescript
+     * // List all models
+     * const models = await client.sessions.listModels();
+     * console.log(models.models);
+     *
+     * // List only desktop-compatible models
+     * const desktopModels = await client.sessions.listModels('desktop');
+     * console.log(desktopModels.models);
+     * // ['agi-2-claude', 'agi-2-qwen']
+     * ```
+     */
+    listModels(filter?: string): Promise<ModelsResponse>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Async event loop manager for client-driven sessions.
+ */
+
+/**
+ * State of the agent execution loop.
+ */
+type LoopState = 'idle' | 'running' | 'paused' | 'stopped' | 'finished';
+/**
+ * Callback type for capturing screenshots.
+ * Should return a base64-encoded screenshot.
+ */
+type CaptureScreenshotFn = () => Promise<string>;
+/**
+ * Callback type for executing actions.
+ */
+type ExecuteActionsFn = (actions: DesktopAction[]) => Promise<void>;
+/**
+ * Callback type for handling thinking output.
+ */
+type OnThinkingFn = (thinking: string) => void;
+/**
+ * Callback type for handling user questions.
+ * Should return the user's answer.
+ */
+type OnAskUserFn = (question: string) => Promise<string>;
+/**
+ * Callback type for step completion.
+ */
+type OnStepFn = (step: number, response: StepDesktopResponse) => void;
+/**
+ * Options for creating an AgentLoop.
+ */
+interface AgentLoopOptions {
+    /** AGIClient instance */
+    client: AGIClient;
+    /** Agent service URL from session.agentUrl */
+    agentUrl: string;
+    /** Session ID (required for routing in shared sandbox) */
+    sessionId: string;
+    /** Async callback that returns base64-encoded screenshot */
+    captureScreenshot: CaptureScreenshotFn;
+    /** Async callback that executes a list of actions */
+    executeActions: ExecuteActionsFn;
+    /** Optional callback for agent thinking/reasoning output */
+    onThinking?: OnThinkingFn;
+    /** Optional async callback to handle user questions. If not provided and agent asks a question, the loop will stop. */
+    onAskUser?: OnAskUserFn;
+    /** Optional callback called after each step with step number and full response */
+    onStep?: OnStepFn;
+    /** Optional delay in milliseconds between steps (default: 0) */
+    stepDelay?: number;
+}
+/**
+ * Async event loop manager for client-driven sessions.
+ *
+ * This class manages the execution loop for agent sessions where the client
+ * is responsible for capturing screenshots and executing actions (e.g., desktop,
+ * mobile, or any client-driven session type). It provides start/pause/resume/stop
+ * control over the loop.
+ *
+ * The loop:
+ * 1. Captures a screenshot using the provided callback
+ * 2. Sends it to the agent via step()
+ * 3. Executes returned actions using the provided callback
+ * 4. Repeats until finished or stopped
+ *
+ * @example
+ * ```typescript
+ * import { AGIClient, AgentLoop } from 'agi-sdk';
+ *
+ * const client = new AGIClient({ apiKey: '...' });
+ *
+ * // Create client-driven session
+ * const session = await client.sessions.create('agi-2-claude', {
+ *   agentSessionType: 'desktop',
+ *   goal: 'Open calculator and compute 2+2'
+ * });
+ *
+ * // Create and run loop
+ * const loop = new AgentLoop({
+ *   client,
+ *   agentUrl: session.agentUrl!,
+ *   captureScreenshot: async () => {
+ *     // Return base64-encoded screenshot
+ *     return '...';
+ *   },
+ *   executeActions: async (actions) => {
+ *     for (const action of actions) {
+ *       console.log('Executing:', action);
+ *     }
+ *   },
+ *   onThinking: (t) => console.log('Thinking:', t),
+ * });
+ *
+ * const result = await loop.start();
+ * console.log('Finished:', result.finished);
+ * ```
+ *
+ * @example Pause/resume control
+ * ```typescript
+ * // Start loop without awaiting
+ * const promise = loop.start();
+ *
+ * // Pause after 5 seconds
+ * setTimeout(() => loop.pause(), 5000);
+ *
+ * // Resume after user input
+ * process.stdin.once('data', () => loop.resume());
+ *
+ * // Wait for completion
+ * const result = await promise;
+ * ```
+ */
+declare class AgentLoop {
+    private readonly client;
+    private readonly agentUrl;
+    private readonly sessionId;
+    private readonly captureScreenshot;
+    private readonly executeActions;
+    private readonly onThinking?;
+    private readonly onAskUser?;
+    private readonly onStep?;
+    private readonly stepDelay;
+    private _state;
+    private _lastResult;
+    private _currentStep;
+    private pauseResolve;
+    private pausePromise;
+    constructor(options: AgentLoopOptions);
+    /** Current state of the loop. */
+    get state(): LoopState;
+    /** Current step number. */
+    get currentStep(): number;
+    /** Last step result, if any. */
+    get lastResult(): StepDesktopResponse | null;
+    /**
+     * Start the execution loop.
+     *
+     * Runs the loop until the task is finished, stopped, or an unhandled
+     * ask_user question is encountered.
+     *
+     * @param message - Optional initial message (goal or instruction).
+     *   Usually not needed if goal was set during session creation.
+     * @returns The final StepDesktopResponse
+     * @throws Error if loop is already running
+     */
+    start(message?: string): Promise<StepDesktopResponse>;
+    /**
+     * Pause the execution loop.
+     *
+     * The loop will complete the current step before pausing.
+     * Call resume() to continue.
+     */
+    pause(): void;
+    /**
+     * Resume a paused loop.
+     */
+    resume(): void;
+    /**
+     * Stop the execution loop.
+     *
+     * The loop will complete the current step before stopping.
+     */
+    stop(): void;
+    /** Check if the loop is currently running. */
+    isRunning(): boolean;
+    /** Check if the loop is currently paused. */
+    isPaused(): boolean;
+    /** Check if the loop has finished successfully. */
+    isFinished(): boolean;
+}
+
+/**
+ * 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);
+}
+
+/**
+ * Protocol types for driver communication.
+ *
+ * The driver communicates via JSON lines:
+ * - Events are emitted on stdout (driver -> SDK)
+ * - Commands are sent on stdin (SDK -> driver)
+ */
+type EventType = 'ready' | 'state_change' | 'thinking' | 'action' | 'confirm' | 'ask_question' | 'finished' | 'error' | 'screenshot_captured';
+type CommandType = 'start' | 'screenshot' | 'pause' | 'resume' | 'stop' | 'confirm' | 'answer';
+type DriverState = 'idle' | 'running' | 'paused' | 'waiting_confirmation' | 'waiting_answer' | 'finished' | 'stopped' | 'error';
+interface BaseEvent {
+    event: EventType;
+    step: number;
+}
+interface ReadyEvent extends BaseEvent {
+    event: 'ready';
+    version: string;
+    protocol: string;
+}
+interface StateChangeEvent extends BaseEvent {
+    event: 'state_change';
+    state: DriverState;
+}
+interface ThinkingEvent extends BaseEvent {
+    event: 'thinking';
+    text: string;
+}
+interface ActionEvent extends BaseEvent {
+    event: 'action';
+    action: DriverAction;
+}
+interface ConfirmEvent extends BaseEvent {
+    event: 'confirm';
+    action: DriverAction;
+    reason: string;
+}
+interface AskQuestionEvent extends BaseEvent {
+    event: 'ask_question';
+    question: string;
+    question_id: string;
+}
+interface FinishedEvent extends BaseEvent {
+    event: 'finished';
+    reason: string;
+    summary: string;
+    success: boolean;
+}
+interface ErrorEvent extends BaseEvent {
+    event: 'error';
+    message: string;
+    code: string;
+    recoverable: boolean;
+}
+/**
+ * Emitted in local mode when the driver captures a screenshot.
+ * Lightweight notification (no image data).
+ */
+interface ScreenshotCapturedEvent extends BaseEvent {
+    event: 'screenshot_captured';
+    width: number;
+    height: number;
+}
+type DriverEvent = ReadyEvent | StateChangeEvent | ThinkingEvent | ActionEvent | ConfirmEvent | AskQuestionEvent | FinishedEvent | ErrorEvent | ScreenshotCapturedEvent;
+interface DriverAction {
+    type: string;
+    x?: number;
+    y?: number;
+    [key: string]: unknown;
+}
+interface BaseCommand {
+    command: CommandType;
+}
+interface StartCommand extends BaseCommand {
+    command: 'start';
+    session_id: string;
+    goal: string;
+    screenshot: string;
+    screen_width: number;
+    screen_height: number;
+    platform: 'desktop' | 'android';
+    model: string;
+    /** "local" for autonomous mode, "" for legacy SDK-driven mode */
+    mode?: string;
+}
+interface ScreenshotCommand extends BaseCommand {
+    command: 'screenshot';
+    data: string;
+    screen_width: number;
+    screen_height: number;
+}
+interface PauseCommand extends BaseCommand {
+    command: 'pause';
+}
+interface ResumeCommand extends BaseCommand {
+    command: 'resume';
+}
+interface StopCommand extends BaseCommand {
+    command: 'stop';
+    reason?: string;
+}
+interface ConfirmResponseCommand extends BaseCommand {
+    command: 'confirm';
+    approved: boolean;
+    message?: string;
+}
+interface AnswerCommand extends BaseCommand {
+    command: 'answer';
+    text: string;
+    question_id?: string;
+}
+type DriverCommand = StartCommand | ScreenshotCommand | PauseCommand | ResumeCommand | StopCommand | ConfirmResponseCommand | AnswerCommand;
+
+/**
+ * AgentDriver - Spawns and manages the agi-driver binary.
+ *
+ * The driver communicates via JSON lines over stdin/stdout and provides
+ * an event-based interface for agent control.
+ */
+
+/**
+ * Options for creating an AgentDriver.
+ */
+interface DriverOptions {
+    /** Path to the agi-driver binary. If not provided, will be auto-detected. */
+    binaryPath?: string;
+    /** Model to use (default: 'claude-sonnet') */
+    model?: string;
+    /** Platform type (default: 'desktop') */
+    platform?: 'desktop' | 'android';
+    /** "local" for autonomous mode, "" for legacy SDK-driven mode */
+    mode?: string;
+    /** Environment variables to pass to the driver process */
+    env?: Record<string, string>;
+}
+/**
+ * Result from running the driver.
+ */
+interface DriverResult {
+    /** Whether the task completed successfully */
+    success: boolean;
+    /** Reason for completion */
+    reason: string;
+    /** Summary of what was accomplished */
+    summary: string;
+    /** Final step number */
+    step: number;
+}
+/**
+ * AgentDriver manages the lifecycle of the agi-driver binary.
+ *
+ * @example
+ * ```typescript
+ * const driver = new AgentDriver();
+ *
+ * driver.on('action', async (action) => {
+ *   // Execute the action on the local machine
+ *   await executeAction(action);
+ *   // Send next screenshot
+ *   driver.sendScreenshot(captureScreenshot());
+ * });
+ *
+ * driver.on('thinking', (text) => {
+ *   console.log('Agent thinking:', text);
+ * });
+ *
+ * driver.on('confirm', async (reason) => {
+ *   // Ask user for confirmation
+ *   return await askUser(reason);
+ * });
+ *
+ * const result = await driver.start('Open calculator and compute 2+2');
+ * console.log('Done:', result.summary);
+ * ```
+ */
+declare class AgentDriver extends EventEmitter {
+    private readonly binaryPath;
+    private readonly pythonFallback;
+    private readonly model;
+    private readonly platform;
+    private readonly mode;
+    private readonly env;
+    private process;
+    private readline;
+    private state;
+    private step;
+    private sessionId;
+    private screenWidth;
+    private screenHeight;
+    private resolveStart;
+    private rejectStart;
+    private pendingConfirm;
+    private pendingAnswer;
+    constructor(options?: DriverOptions);
+    /**
+     * Get the current state of the driver.
+     */
+    get currentState(): DriverState;
+    /**
+     * Get the current step number.
+     */
+    get currentStep(): number;
+    /**
+     * Check if the driver is running.
+     */
+    get isRunning(): boolean;
+    /**
+     * Check if the driver is waiting for user input.
+     */
+    get isWaiting(): boolean;
+    /**
+     * Start the agent with a goal.
+     *
+     * @param goal - The task for the agent to accomplish
+     * @param screenshot - Initial screenshot (base64-encoded). Not needed in local mode.
+     * @param screenWidth - Screen width in pixels. Not needed in local mode.
+     * @param screenHeight - Screen height in pixels. Not needed in local mode.
+     * @param mode - Override the mode set in DriverOptions.
+     * @returns Promise that resolves when the agent finishes
+     */
+    start(goal: string, screenshot?: string, screenWidth?: number, screenHeight?: number, mode?: string): Promise<DriverResult>;
+    /**
+     * Send a new screenshot to the driver.
+     *
+     * @param screenshot - Base64-encoded screenshot
+     * @param screenWidth - Screen width in pixels
+     * @param screenHeight - Screen height in pixels
+     */
+    sendScreenshot(screenshot: string, screenWidth?: number, screenHeight?: number): void;
+    /**
+     * Pause the driver.
+     */
+    pause(): void;
+    /**
+     * Resume the driver.
+     */
+    resume(): void;
+    /**
+     * Stop the driver.
+     *
+     * @param reason - Reason for stopping
+     */
+    stop(reason?: string): Promise<void>;
+    /**
+     * Respond to a confirmation request.
+     *
+     * @param approved - Whether the action is approved
+     * @param message - Optional message to send with the response
+     */
+    respondConfirm(approved: boolean, message?: string): void;
+    /**
+     * Respond to a question.
+     *
+     * @param text - The answer text
+     * @param questionId - Optional question ID
+     */
+    respondAnswer(text: string, questionId?: string): void;
+    private sendCommand;
+    private handleLine;
+    private handleFinished;
+    private handleError;
+    private cleanup;
+}
+
+/**
+ * Binary locator for the agi-driver.
+ *
+ * Finds the platform-specific binary bundled with the package
+ * or falls back to a global installation.
+ */
+/**
+ * Platform identifier for binary selection.
+ */
+type PlatformId = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'win32-x64';
+/**
+ * Get the current platform identifier.
+ */
+declare function getPlatformId(): PlatformId;
+/**
+ * Find the agi-driver binary path.
+ *
+ * @throws Error if the binary cannot be found
+ */
+declare function findBinaryPath(): string;
+/**
+ * Check if the binary is available.
+ */
+declare function isBinaryAvailable(): boolean;
+
+export { AGIClient, type AGIClientOptions, AGIError, APIError, AgentDriver, AgentExecutionError, AgentLoop, type AgentLoopOptions, type AgentSessionType, AuthenticationError, type CaptureScreenshotFn, type CreateSessionOptions, type DeleteResponse, type DesktopAction, type DesktopActionType, type DriverAction, type DriverCommand, type DriverEvent, type DriverOptions, type DriverResult, type DriverState, type EventType$1 as EventType, type ExecuteActionsFn, type ExecuteStatusResponse, type LoopState, type MessageOptions, type MessageResponse, type MessageType, type MessagesResponse, type ModelsResponse, type NavigateResponse, NotFoundError, type OnAskUserFn, type OnStepFn, type OnThinkingFn, PermissionError, type PlatformId, RateLimitError, type RunTaskOptions, type SSEEvent, Screenshot, type ScreenshotResponse, SessionContext, type SessionResponse, type SessionStatus, SessionsResource, type SnapshotMode, type StepDesktopRequest, type StepDesktopResponse, type StreamOptions, type SuccessResponse, type TaskMetadata, type TaskResult, ValidationError, findBinaryPath, getPlatformId, isBinaryAvailable };