@oagi/oagi 0.1.3

package/dist/index.d.cts

@@ -0,0 +1,567 @@
+import * as z from 'zod';
+import { ChatCompletionMessageParam, CompletionUsage } from 'openai/resources.js';
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+declare const ActionSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        click: "click";
+        left_double: "left_double";
+        left_triple: "left_triple";
+        right_single: "right_single";
+        drag: "drag";
+        hotkey: "hotkey";
+        type: "type";
+        scroll: "scroll";
+        finish: "finish";
+        wait: "wait";
+        call_user: "call_user";
+    }>;
+    argument: z.ZodString;
+    count: z.ZodDefault<z.ZodInt>;
+}, z.core.$strip>;
+type Action = z.infer<typeof ActionSchema>;
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+interface Step {
+    reason?: string;
+    actions: Action[];
+    stop: boolean;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+/**
+ * A single todo item in the task workflow.
+ */
+interface Todo {
+    /**
+     * Todo index in the list
+     */
+    index: number;
+    /**
+     * Todo description
+     */
+    description: string;
+    /**
+     * Current status of the todo
+     */
+    status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+    /**
+     * Summary of execution for this todo
+     */
+    execution_summary?: string;
+}
+interface HistoryItem {
+    /**
+     * Index of the todo that was executed
+     */
+    todo_index: number;
+    /**
+     * Description of the todo
+     */
+    todo_description: string;
+    /**
+     * Number of actions taken
+     */
+    action_count: number;
+    /**
+     * Execution summary
+     */
+    summary?: string;
+    /**
+     * Whether the todo was completed
+     */
+    completed: boolean;
+}
+interface GenerateOption {
+    /**
+     * One of "oagi_first", "oagi_follow", "oagi_task_summary"
+     */
+    workerId: string;
+    /**
+     * Current todo description
+     */
+    overallTodo: string;
+    /**
+     * Overall task description
+     */
+    taskDescription?: string;
+    /**
+     * List of todo dicts with index, description, status, execution_summary
+     */
+    todos: Todo[];
+    /**
+     * List of history dicts with todo_index, todo_description, action_count, summary, completed
+     */
+    history?: HistoryItem[];
+    /**
+     * Index of current todo being executed
+     */
+    currentTodoIndex?: number;
+    /**
+     * Summary of overall task execution
+     */
+    taskExecutionSummary?: string;
+    /**
+     * Uploaded file UUID for screenshot (oagi_first)
+     */
+    currentScreenshot?: string;
+    /**
+     * Subtask instruction (oagi_follow)
+     */
+    currentSubtaskInstruction?: string;
+    /**
+     * Action steps list (oagi_follow)
+     */
+    windowSteps?: Step[];
+    /**
+     * Uploaded file UUIDs list (oagi_follow)
+     */
+    windowScreenshots?: string[];
+    /**
+     * Uploaded file UUID for result screenshot (oagi_follow)
+     */
+    resultScreenshot?: string;
+    /**
+     * Execution notes (oagi_follow)
+     */
+    priorNotes?: string;
+    /**
+     * Latest summary (oagi_task_summary)
+     */
+    latestTodoSummary?: string;
+    /**
+     * API version header
+     */
+    apiVersion?: string;
+}
+declare const ErrorDetailSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Detailed error information.
+ */
+type ErrorDetail = z.infer<typeof ErrorDetailSchema>;
+declare const ErrorResponseSchema: z.ZodObject<{
+    error: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Standard error response format.
+ */
+type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+declare const UploadFileResponseSchema: z.ZodObject<{
+    url: z.ZodString;
+    uuid: z.ZodString;
+    expires_at: z.ZodInt;
+    file_expires_at: z.ZodInt;
+    download_url: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Response from S3 presigned URL upload.
+ */
+type UploadFileResponse = z.infer<typeof UploadFileResponseSchema>;
+declare const GenerateResponseSchema: z.ZodObject<{
+    response: z.ZodString;
+    prompt_tokens: z.ZodInt;
+    completion_tokens: z.ZodInt;
+    cost: z.ZodOptional<z.ZodNullable<z.ZodFloat64>>;
+    request_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Response from /v1/generate endpoint.
+ */
+type GenerateResponse = z.infer<typeof GenerateResponseSchema>;
+
+declare const ImageConfigSchema: z.ZodPipe<z.ZodObject<{
+    format: z.ZodDefault<z.ZodEnum<{
+        PNG: "PNG";
+        JPEG: "JPEG";
+    }>>;
+    quality: z.ZodDefault<z.ZodInt>;
+    width: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodInt>>>;
+    height: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodInt>>>;
+    optimize: z.ZodDefault<z.ZodBoolean>;
+    resample: z.ZodDefault<z.ZodEnum<{
+        NEAREST: "NEAREST";
+        BILINEAR: "BILINEAR";
+        BICUBIC: "BICUBIC";
+        LANCZOS: "LANCZOS";
+    }>>;
+}, z.core.$strip>, z.ZodTransform<{
+    format: "PNG" | "JPEG";
+    quality: number;
+    width: number | null;
+    height: number | null;
+    optimize: boolean;
+    resample: "NEAREST" | "BILINEAR" | "BICUBIC" | "LANCZOS";
+}, {
+    format: "PNG" | "JPEG";
+    quality: number;
+    width: number | null;
+    height: number | null;
+    optimize: boolean;
+    resample: "NEAREST" | "BILINEAR" | "BICUBIC" | "LANCZOS";
+}>>;
+type ImageConfig = z.infer<typeof ImageConfigSchema>;
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+declare const ImageEventSchema: z.ZodObject<{
+    timestamp: z.ZodDefault<z.ZodDate>;
+    type: z.ZodLiteral<"image">;
+    step_num: z.ZodNumber;
+    image: z.ZodString;
+}, z.core.$strip>;
+type ImageEvent = z.infer<typeof ImageEventSchema>;
+declare const StepEventSchema: z.ZodObject<{
+    timestamp: z.ZodDefault<z.ZodDate>;
+    type: z.ZodLiteral<"step">;
+    step_num: z.ZodNumber;
+    image: z.ZodCustom<ArrayBuffer, ArrayBuffer>;
+    step: z.ZodCustom<Step, Step>;
+    task_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type StepEvent = z.infer<typeof StepEventSchema>;
+declare const ActionEventSchema: z.ZodObject<{
+    timestamp: z.ZodDefault<z.ZodDate>;
+    type: z.ZodLiteral<"action">;
+    step_num: z.ZodNumber;
+    actions: z.ZodArray<z.ZodCustom<{
+        type: "click" | "left_double" | "left_triple" | "right_single" | "drag" | "hotkey" | "type" | "scroll" | "finish" | "wait" | "call_user";
+        argument: string;
+        count: number;
+    }, {
+        type: "click" | "left_double" | "left_triple" | "right_single" | "drag" | "hotkey" | "type" | "scroll" | "finish" | "wait" | "call_user";
+        argument: string;
+        count: number;
+    }>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ActionEvent = z.infer<typeof ActionEventSchema>;
+declare const LogEventSchema: z.ZodObject<{
+    timestamp: z.ZodDefault<z.ZodDate>;
+    type: z.ZodLiteral<"log">;
+    message: z.ZodString;
+}, z.core.$strip>;
+type LogEvent = z.infer<typeof LogEventSchema>;
+declare const SplitEventSchema: z.ZodObject<{
+    timestamp: z.ZodDefault<z.ZodDate>;
+    type: z.ZodLiteral<"split">;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SplitEvent = z.infer<typeof SplitEventSchema>;
+declare const PlanEventSchema: z.ZodObject<{
+    timestamp: z.ZodDefault<z.ZodDate>;
+    type: z.ZodLiteral<"plan">;
+    phase: z.ZodEnum<{
+        initial: "initial";
+        reflection: "reflection";
+        summary: "summary";
+    }>;
+    image: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodCustom<ArrayBuffer, ArrayBuffer>]>>;
+    reasoning: z.ZodString;
+    result: z.ZodOptional<z.ZodString>;
+    request_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PlanEvent = z.infer<typeof PlanEventSchema>;
+type ObserverEvent = ImageEvent | StepEvent | ActionEvent | LogEvent | SplitEvent | PlanEvent;
+declare abstract class StepObserver {
+    abstract onEvent(event: ObserverEvent): Promise<void>;
+    chain(observer?: StepObserver | null): StepObserver;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+interface ActionHandler {
+    handle(actions: Action[]): Promise<void>;
+}
+interface ImageProvider {
+    provide(): Promise<ArrayBuffer>;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+/**
+ * Base class for task automation with the OAGI API.
+ */
+declare class Actor {
+    private model;
+    private temperature?;
+    /**
+     * Client-side generated UUID
+     */
+    private taskId;
+    private taskDescription;
+    /**
+     * OpenAI-compatible message history
+     */
+    private messageHistory;
+    private maxSteps;
+    /**
+     * Current step counter
+     */
+    private currentStep;
+    private client;
+    constructor(apiKey?: string, baseUrl?: string, model?: string, temperature?: number | undefined);
+    private validateAndIncrementStep;
+    /**
+     * Get screenshot URL, uploading to S3 if needed (async version).
+     * @param screenshot Screenshot as URL string, or raw bytes
+     * @returns Screenshot URL (either direct or from S3 upload)
+     */
+    private ensureScreenshotUrl;
+    /**
+     * Add user message with screenshot to message history.
+     *
+     * @param screenshot URL of the screenshot
+     * @param prompt Optional prompt text (for first message only)
+     */
+    private addUserMessageToHistory;
+    /**
+     * Build prompt for first message only.
+     */
+    private buildStepPrompt;
+    /**
+     * Initialize a new task with the given description.
+     *
+     * @param taskDescription Task description
+     * @param maxSteps Maximum number of steps allowed
+     */
+    initTask(taskDescription: string, maxSteps?: number): void;
+    /**
+     * Send screenshot to the server and get the next actions.
+     *
+     * @param screenshot Screenshot as URL string, or raw bytes
+     * @param instruction Optional additional instruction for this step (currently unused)
+     * @param temperature Sampling temperature for this step (overrides task default if provided)
+     */
+    step(screenshot: string | ArrayBuffer, _instruction?: string, temperature?: number): Promise<Step>;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+declare class DefaultAgent implements Agent {
+    /** Default asynchronous agent implementation using OAGI client. */
+    private api_key?;
+    private base_url?;
+    private model;
+    private max_steps;
+    private temperature?;
+    private step_observer?;
+    private step_delay;
+    constructor(api_key?: string, base_url?: string, model?: string, max_steps?: number, temperature?: number | undefined, step_observer?: StepObserver, step_delay?: number);
+    execute(instruction: string, action_handler: ActionHandler, image_provider: ImageProvider): Promise<boolean>;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+interface Agent {
+    /**
+     * Protocol for synchronous task execution agents.
+     */
+    execute(instruction: string, action_handler: ActionHandler, image_provider: ImageProvider): Promise<boolean>;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+
+/**
+ * HTTP client for the OAGI API.
+ */
+declare class Client {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private client;
+    constructor(baseUrl?: string, apiKey?: string | null, maxRetries?: number);
+    private fetch;
+    private buildHeaders;
+    private handleResponseError;
+    private handleHttpErrors;
+    private static getErrorClass;
+    /**
+     * Call OpenAI-compatible /v1/chat/completions endpoint.
+     *
+     * @param model Model to use for inference
+     * @param messages Full message history (OpenAI-compatible format)
+     * @param temperature Sampling temperature (0.0-2.0)
+     * @param taskId Optional task ID for multi-turn conversations
+     * @returns Tuple of (Step, raw_output, Usage)
+     *   - Step: Parsed actions and reasoning
+     *   - raw_output: Raw model output string (for message history)
+     *   - Usage: Token usage statistics (or None if not available)
+     */
+    chatCompletions(model: string, messages: ChatCompletionMessageParam[], temperature?: number, taskId?: string): Promise<[Step, rawOutput: string, CompletionUsage | undefined]>;
+    /**
+     * Call the /v1/file/upload endpoint to get a S3 presigned URL
+     *
+     * @param apiVersion API version header
+     * @returns {Promise<UploadFileResponse>} The response from /v1/file/upload with uuid and presigned S3 URL
+     */
+    getS3PresignedUrl(apiVersion?: string): Promise<UploadFileResponse>;
+    /**
+     * Upload image bytes to S3 using presigned URL
+     *
+     * @param url S3 presigned URL
+     * @param content Image bytes to upload
+     * @throws {APIError} If upload fails
+     */
+    uploadToS3(url: string, content: ArrayBuffer): Promise<void>;
+    /**
+     * Get S3 presigned URL and upload image (convenience method)
+     *
+     * @param screenshot Screenshot image bytes
+     * @param apiVersion API version header
+     * @returns {UploadFileResponse} The response from /v1/file/upload with uuid and presigned S3 URL
+     */
+    putS3PresignedUrl(screenshot: ArrayBuffer, apiVersion?: string): Promise<{
+        url: string;
+        uuid: string;
+        expires_at: number;
+        file_expires_at: number;
+        download_url: string;
+    }>;
+    /**
+     * Call the /v1/generate endpoint for OAGI worker processing.
+     *
+     * @returns {Promise<GenerateResponse>} The response from the API
+     * @throws {ValueError} If workerId is invalid
+     * @throws {APIError} If API returns error
+     */
+    callWorker({ workerId, overallTodo, taskDescription, todos, history, currentTodoIndex, taskExecutionSummary, currentScreenshot, currentSubtaskInstruction, windowSteps, windowScreenshots, resultScreenshot, priorNotes, latestTodoSummary, apiVersion, }: GenerateOption): Promise<GenerateResponse>;
+}
+
+/**
+ * -----------------------------------------------------------------------------
+ *  Copyright (c) OpenAGI Foundation
+ *  All rights reserved.
+ *
+ *  This file is part of the official API project.
+ *  Licensed under the MIT License.
+ * -----------------------------------------------------------------------------
+ */
+declare class OAGIError extends Error {
+}
+declare class APIError extends OAGIError {
+    response: Response;
+    constructor(response: Response, message?: string);
+    toString(): string;
+}
+declare class AuthenticationError extends APIError {
+}
+declare class RateLimitError extends APIError {
+}
+declare class ValidationError extends APIError {
+}
+declare class NotFoundError extends APIError {
+}
+declare class ServerError extends APIError {
+}
+declare class ConfigurationError extends OAGIError {
+}
+declare class NetworkError extends OAGIError {
+    originalError: Error;
+    constructor(message: string, originalError: Error);
+}
+declare class RequestTimeoutError extends NetworkError {
+}
+
+type DesktopAutomationConfig = {
+    dragDurationMs?: number;
+    scrollAmount?: number;
+    waitDurationMs?: number;
+    hotkeyDelayMs?: number;
+    macosCtrlToCmd?: boolean;
+    capslockMode?: 'session' | 'system';
+};
+declare class ScreenshotMaker implements ImageProvider {
+    #private;
+    constructor(cfg?: Partial<ImageConfig>);
+    static toArrayBuffer(buffer: Buffer): ArrayBuffer;
+    provide(): Promise<ArrayBuffer>;
+}
+declare class DefaultActionHandler implements ActionHandler {
+    #private;
+    constructor(cfg?: DesktopAutomationConfig);
+    reset(): void;
+    handle(actions: Action[]): Promise<void>;
+}
+
+export { APIError, Actor, type Agent, AuthenticationError, Client, ConfigurationError, DefaultActionHandler, DefaultAgent, type ErrorDetail, type ErrorResponse, type GenerateResponse, NetworkError, NotFoundError, OAGIError, RateLimitError, RequestTimeoutError, ScreenshotMaker, ServerError, type UploadFileResponse, ValidationError };