@browserbasehq/orca 3.0.0-preview.0

package/dist/lib/api.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod/v3";
+import { StagehandAPIConstructorParams, StartSessionParams, StartSessionResult } from "./v3/types/api";
+import { GotoOptions } from "./v3/types/playwright";
+import { ActOptions, ActResult, AgentConfig, ExtractOptions, ExtractResult, ObserveOptions, Action } from "./v3/types/stagehand";
+import { AgentExecuteOptions, AgentResult } from "@/lib/v3/types/agent";
+export declare class StagehandAPI {
+    private apiKey;
+    private projectId;
+    private sessionId?;
+    private modelApiKey;
+    private logger;
+    private fetchWithCookies;
+    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
+    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, debugDom, systemPrompt, selfHeal, waitForCaptchaSolves, actionTimeoutMs, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
+    act(options: ActOptions | Action): Promise<ActResult>;
+    extract<T extends z.AnyZodObject>(options: ExtractOptions<T>): Promise<ExtractResult<T>>;
+    observe(options?: ObserveOptions): Promise<Action[]>;
+    goto(url: string, options?: GotoOptions): Promise<void>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions): Promise<AgentResult>;
+    end(): Promise<Response>;
+    private execute;
+    private request;
+}

package/dist/lib/dom/build/scriptContent.d.ts

@@ -0,0 +1 @@
+export declare const scriptContent = "(() => {\n  // lib/dom/elementCheckUtils.ts\n  function isElementNode(node) {\n    return node.nodeType === Node.ELEMENT_NODE;\n  }\n  function isTextNode(node) {\n    return node.nodeType === Node.TEXT_NODE && Boolean(node.textContent?.trim());\n  }\n\n  // lib/dom/xpathUtils.ts\n  function getParentElement(node) {\n    return isElementNode(node) ? node.parentElement : node.parentNode;\n  }\n  function getCombinations(attributes, size) {\n    const results = [];\n    function helper(start, combo) {\n      if (combo.length === size) {\n        results.push([...combo]);\n        return;\n      }\n      for (let i = start; i < attributes.length; i++) {\n        combo.push(attributes[i]);\n        helper(i + 1, combo);\n        combo.pop();\n      }\n    }\n    helper(0, []);\n    return results;\n  }\n  function isXPathFirstResultElement(xpath, target) {\n    try {\n      const result = document.evaluate(\n        xpath,\n        document.documentElement,\n        null,\n        XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n        null\n      );\n      return result.snapshotItem(0) === target;\n    } catch (error) {\n      console.warn(`Invalid XPath expression: ${xpath}`, error);\n      return false;\n    }\n  }\n  function escapeXPathString(value) {\n    if (value.includes(\"'\")) {\n      if (value.includes('\"')) {\n        return \"concat(\" + value.split(/('+)/).map((part) => {\n          if (part === \"'\") {\n            return `\"'\"`;\n          } else if (part.startsWith(\"'\") && part.endsWith(\"'\")) {\n            return `\"${part}\"`;\n          } else {\n            return `'${part}'`;\n          }\n        }).join(\",\") + \")\";\n      } else {\n        return `\"${value}\"`;\n      }\n    } else {\n      return `'${value}'`;\n    }\n  }\n  async function generateXPathsForElement(element) {\n    if (!element) return [];\n    const [complexXPath, standardXPath, idBasedXPath] = await Promise.all([\n      generateComplexXPath(element),\n      generateStandardXPath(element),\n      generatedIdBasedXPath(element)\n    ]);\n    return [standardXPath, ...idBasedXPath ? [idBasedXPath] : [], complexXPath];\n  }\n  async function generateComplexXPath(element) {\n    const parts = [];\n    let currentElement = element;\n    while (currentElement && (isTextNode(currentElement) || isElementNode(currentElement))) {\n      if (isElementNode(currentElement)) {\n        const el = currentElement;\n        let selector = el.tagName.toLowerCase();\n        const attributePriority = [\n          \"data-qa\",\n          \"data-component\",\n          \"data-role\",\n          \"role\",\n          \"aria-role\",\n          \"type\",\n          \"name\",\n          \"aria-label\",\n          \"placeholder\",\n          \"title\",\n          \"alt\"\n        ];\n        const attributes = attributePriority.map((attr) => {\n          let value = el.getAttribute(attr);\n          if (attr === \"href-full\" && value) {\n            value = el.getAttribute(\"href\");\n          }\n          return value ? { attr: attr === \"href-full\" ? \"href\" : attr, value } : null;\n        }).filter((attr) => attr !== null);\n        let uniqueSelector = \"\";\n        for (let i = 1; i <= attributes.length; i++) {\n          const combinations = getCombinations(attributes, i);\n          for (const combo of combinations) {\n            const conditions = combo.map((a) => `@${a.attr}=${escapeXPathString(a.value)}`).join(\" and \");\n            const xpath2 = `//${selector}[${conditions}]`;\n            if (isXPathFirstResultElement(xpath2, el)) {\n              uniqueSelector = xpath2;\n              break;\n            }\n          }\n          if (uniqueSelector) break;\n        }\n        if (uniqueSelector) {\n          parts.unshift(uniqueSelector.replace(\"//\", \"\"));\n          break;\n        } else {\n          const parent = getParentElement(el);\n          if (parent) {\n            const siblings = Array.from(parent.children).filter(\n              (sibling) => sibling.tagName === el.tagName\n            );\n            const index = siblings.indexOf(el) + 1;\n            selector += siblings.length > 1 ? `[${index}]` : \"\";\n          }\n          parts.unshift(selector);\n        }\n      }\n      currentElement = getParentElement(currentElement);\n    }\n    const xpath = \"//\" + parts.join(\"/\");\n    return xpath;\n  }\n  async function generateStandardXPath(element) {\n    const parts = [];\n    while (element && (isTextNode(element) || isElementNode(element))) {\n      let index = 0;\n      let hasSameTypeSiblings = false;\n      const siblings = element.parentElement ? Array.from(element.parentElement.childNodes) : [];\n      for (let i = 0; i < siblings.length; i++) {\n        const sibling = siblings[i];\n        if (sibling.nodeType === element.nodeType && sibling.nodeName === element.nodeName) {\n          index = index + 1;\n          hasSameTypeSiblings = true;\n          if (sibling.isSameNode(element)) {\n            break;\n          }\n        }\n      }\n      if (element.nodeName !== \"#text\") {\n        const tagName = element.nodeName.toLowerCase();\n        const pathIndex = hasSameTypeSiblings ? `[${index}]` : \"\";\n        parts.unshift(`${tagName}${pathIndex}`);\n      }\n      element = element.parentElement;\n    }\n    return parts.length ? `/${parts.join(\"/\")}` : \"\";\n  }\n  async function generatedIdBasedXPath(element) {\n    if (isElementNode(element) && element.id) {\n      return `//*[@id='${element.id}']`;\n    }\n    return null;\n  }\n\n  // types/stagehandErrors.ts\n  var StagehandError = class extends Error {\n    constructor(message) {\n      super(message);\n      this.name = this.constructor.name;\n    }\n  };\n  var StagehandDomProcessError = class extends StagehandError {\n    constructor(message) {\n      super(`Error Processing Dom: ${message}`);\n    }\n  };\n\n  // lib/dom/utils.ts\n  function canElementScroll(elem) {\n    if (typeof elem.scrollTo !== \"function\") {\n      console.warn(\"canElementScroll: .scrollTo is not a function.\");\n      return false;\n    }\n    try {\n      const originalTop = elem.scrollTop;\n      elem.scrollTo({\n        top: originalTop + 100,\n        left: 0,\n        behavior: \"instant\"\n      });\n      if (elem.scrollTop === originalTop) {\n        throw new StagehandDomProcessError(\"scrollTop did not change\");\n      }\n      elem.scrollTo({\n        top: originalTop,\n        left: 0,\n        behavior: \"instant\"\n      });\n      return true;\n    } catch (error) {\n      console.warn(\"canElementScroll error:\", error.message || error);\n      return false;\n    }\n  }\n  function getNodeFromXpath(xpath) {\n    return document.evaluate(\n      xpath,\n      document.documentElement,\n      null,\n      XPathResult.FIRST_ORDERED_NODE_TYPE,\n      null\n    ).singleNodeValue;\n  }\n  function waitForElementScrollEnd(element, idleMs = 100) {\n    return new Promise((resolve) => {\n      let scrollEndTimer;\n      const handleScroll = () => {\n        clearTimeout(scrollEndTimer);\n        scrollEndTimer = window.setTimeout(() => {\n          element.removeEventListener(\"scroll\", handleScroll);\n          resolve();\n        }, idleMs);\n      };\n      element.addEventListener(\"scroll\", handleScroll, { passive: true });\n      handleScroll();\n    });\n  }\n\n  // lib/dom/process.ts\n  function getScrollableElements(topN) {\n    const docEl = document.documentElement;\n    const scrollableElements = [docEl];\n    const allElements = document.querySelectorAll(\"*\");\n    for (const elem of allElements) {\n      const style = window.getComputedStyle(elem);\n      const overflowY = style.overflowY;\n      const isPotentiallyScrollable = overflowY === \"auto\" || overflowY === \"scroll\" || overflowY === \"overlay\";\n      if (isPotentiallyScrollable) {\n        const candidateScrollDiff = elem.scrollHeight - elem.clientHeight;\n        if (candidateScrollDiff > 0 && canElementScroll(elem)) {\n          scrollableElements.push(elem);\n        }\n      }\n    }\n    scrollableElements.sort((a, b) => b.scrollHeight - a.scrollHeight);\n    if (topN !== void 0) {\n      return scrollableElements.slice(0, topN);\n    }\n    return scrollableElements;\n  }\n  async function getScrollableElementXpaths(topN) {\n    const scrollableElems = getScrollableElements(topN);\n    const xpaths = [];\n    for (const elem of scrollableElems) {\n      const allXPaths = await generateXPathsForElement(elem);\n      const firstXPath = allXPaths?.[0] || \"\";\n      xpaths.push(firstXPath);\n    }\n    return xpaths;\n  }\n  (() => {\n    const closedRoots = /* @__PURE__ */ new WeakMap();\n    const nativeAttachShadow = Element.prototype.attachShadow;\n    Element.prototype.attachShadow = function(init) {\n      const root = nativeAttachShadow.call(this, init);\n      if (init.mode === \"closed\") closedRoots.set(this, root);\n      return root;\n    };\n    const backdoor = {\n      getClosedRoot: (host) => closedRoots.get(host),\n      queryClosed: (host, selector) => {\n        const root = closedRoots.get(host);\n        return root ? Array.from(root.querySelectorAll(selector)) : [];\n      },\n      xpathClosed: (host, xp) => {\n        const root = closedRoots.get(host);\n        if (!root) return [];\n        const it = document.evaluate(\n          xp,\n          root,\n          null,\n          XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,\n          null\n        );\n        const out = [];\n        for (let i = 0; i < it.snapshotLength; ++i) {\n          const n = it.snapshotItem(i);\n          if (n) out.push(n);\n        }\n        return out;\n      }\n    };\n    if (!(\"__stagehand__\" in window)) {\n      Object.defineProperty(window, \"__stagehand__\", {\n        value: backdoor,\n        enumerable: false,\n        writable: false,\n        configurable: false\n      });\n    }\n  })();\n  window.getScrollableElementXpaths = getScrollableElementXpaths;\n  window.getNodeFromXpath = getNodeFromXpath;\n  window.waitForElementScrollEnd = waitForElementScrollEnd;\n})();\n";

package/dist/lib/inference.d.ts

@@ -0,0 +1,71 @@
+import { z } from "zod/v3";
+import { LogLine } from "./v3/types/log";
+import { LLMClient } from "./v3/llm/LLMClient";
+/** Simple usage shape if your LLM returns usage tokens. */
+interface LLMUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/**
+ * For calls that use a schema: the LLMClient may return { data: T; usage?: LLMUsage }
+ */
+export interface LLMParsedResponse<T> {
+    data: T;
+    usage?: LLMUsage;
+}
+export declare function extract({ instruction, domElements, schema, llmClient, logger, userProvidedInstructions, logInferenceToFile, }: {
+    instruction: string;
+    domElements: string;
+    schema: z.ZodObject<z.ZodRawShape>;
+    llmClient: LLMClient;
+    userProvidedInstructions?: string;
+    logger: (message: LogLine) => void;
+    logInferenceToFile?: boolean;
+}): Promise<{
+    metadata: {
+        completed: boolean;
+        progress: string;
+    };
+    prompt_tokens: number;
+    completion_tokens: number;
+    inference_time_ms: number;
+}>;
+export declare function observe({ instruction, domElements, llmClient, userProvidedInstructions, logger, logInferenceToFile, }: {
+    instruction: string;
+    domElements: string;
+    llmClient: LLMClient;
+    userProvidedInstructions?: string;
+    logger: (message: LogLine) => void;
+    logInferenceToFile?: boolean;
+}): Promise<{
+    elements: {
+        elementId: string;
+        description: string;
+        method: string;
+        arguments: string[];
+    }[];
+    prompt_tokens: number;
+    completion_tokens: number;
+    inference_time_ms: number;
+}>;
+export declare function act({ instruction, domElements, llmClient, userProvidedInstructions, logger, logInferenceToFile, }: {
+    instruction: string;
+    domElements: string;
+    llmClient: LLMClient;
+    userProvidedInstructions?: string;
+    logger: (message: LogLine) => void;
+    logInferenceToFile?: boolean;
+}): Promise<{
+    element: {
+        elementId: string;
+        description: string;
+        method: string;
+        arguments: string[];
+    };
+    prompt_tokens: number;
+    completion_tokens: number;
+    inference_time_ms: number;
+    twoStep: boolean;
+}>;
+export {};

package/dist/lib/inferenceLogUtils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Appends a new entry to the act_summary.json file, then writes the file back out.
+ */
+export declare function appendSummary<T>(inferenceType: string, entry: T): void;
+/**
+ * Writes `data` as JSON into a file in `directory`, using a prefix plus timestamp.
+ * Returns both the file name and the timestamp used, so you can log them.
+ */
+export declare function writeTimestampedTxtFile(directory: string, prefix: string, data: unknown): {
+    fileName: string;
+    timestamp: string;
+};

package/dist/lib/logger.d.ts

@@ -0,0 +1,54 @@
+import pino from "pino";
+import { LogLine } from "./v3/types/log";
+export interface LoggerOptions {
+    pretty?: boolean;
+    level?: pino.Level;
+    destination?: pino.DestinationStream;
+    usePino?: boolean;
+}
+/**
+ * Creates a configured Pino logger instance
+ */
+export declare function createLogger(options?: LoggerOptions): import("pino/pino").Logger<never, boolean>;
+/**
+ * StagehandLogger class that wraps Pino for our specific needs
+ */
+export declare class StagehandLogger {
+    /**
+     * We maintain a single shared Pino instance when `usePino` is enabled.
+     * This prevents spawning a new worker thread for every Stagehand instance
+     * (which happens when `pino-pretty` transport is used), eliminating the
+     * memory/RSS growth observed when many Stagehand objects are created and
+     * disposed within the same process (e.g. a request-per-instance API).
+     */
+    private static sharedPinoLogger;
+    private logger?;
+    private verbose;
+    private externalLogger?;
+    private usePino;
+    private isTest;
+    constructor(options?: LoggerOptions, externalLogger?: (logLine: LogLine) => void);
+    /**
+     * Set the verbosity level
+     */
+    setVerbosity(level: 0 | 1 | 2): void;
+    /**
+     * Log a message using our LogLine format
+     */
+    log(logLine: LogLine): void;
+    /**
+     * Helper to format auxiliary data for structured logging
+     */
+    private formatAuxiliaryData;
+    /**
+     * Convenience methods for different log levels
+     */
+    error(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    /**
+     * Convert a plain object to our auxiliary format
+     */
+    private convertToAuxiliary;
+}

package/dist/lib/prompt.d.ts

@@ -0,0 +1,12 @@
+import { ChatMessage } from "./v3/llm/LLMClient";
+export declare function buildUserInstructionsString(userProvidedInstructions?: string): string;
+export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, userProvidedInstructions?: string): ChatMessage;
+export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean): ChatMessage;
+export declare function buildMetadataSystemPrompt(): ChatMessage;
+export declare function buildMetadataPrompt(instruction: string, extractionResponse: object): ChatMessage;
+export declare function buildObserveSystemPrompt(userProvidedInstructions?: string): ChatMessage;
+export declare function buildObserveUserMessage(instruction: string, domElements: string): ChatMessage;
+export declare function buildActSystemPrompt(userProvidedInstructions?: string): ChatMessage;
+export declare function buildActPrompt(action: string, supportedActions: string[], variables?: Record<string, string>): string;
+export declare function buildStepTwoPrompt(originalUserAction: string, previousAction: string, supportedActions: string[], variables?: Record<string, string>): string;
+export declare function buildOperatorSystemPrompt(goal: string): ChatMessage;

package/dist/lib/utils.d.ts

@@ -0,0 +1,65 @@
+import { Schema } from "@google/genai";
+import { z, ZodTypeAny } from "zod/v3";
+import { LogLine } from "./v3/types/log";
+import { ModelProvider } from "./v3/types/model";
+import { ZodPathSegments } from "./v3/types/stagehand";
+export declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
+/**
+ * Detects if the code is running in the Bun runtime environment.
+ * @returns {boolean} True if running in Bun, false otherwise.
+ */
+export declare function isRunningInBun(): boolean;
+export declare function toGeminiSchema(zodSchema: z.ZodTypeAny): Schema;
+export declare function getZodType(schema: z.ZodTypeAny): string;
+/**
+ * Recursively traverses a given Zod schema, scanning for any fields of type `z.string().url()`.
+ * For each such field, it replaces the `z.string().url()` with `z.number()`.
+ *
+ * This function is used internally by higher-level utilities (e.g., transforming entire object schemas)
+ * and handles nested objects, arrays, unions, intersections, optionals.
+ *
+ * @param schema - The Zod schema to transform.
+ * @param currentPath - An array of string/number keys representing the current schema path (used internally for recursion).
+ * @returns A two-element tuple:
+ *   1. The updated Zod schema, with any `.url()` fields replaced by `z.number()`.
+ *   2. An array of {@link ZodPathSegments} objects representing each replaced field, including the path segments.
+ */
+export declare function transformSchema(schema: z.ZodTypeAny, currentPath: Array<string | number>): [z.ZodTypeAny, ZodPathSegments[]];
+/**
+ * Once we get the final extracted object that has numeric IDs in place of URLs,
+ * use `injectUrls` to walk the object and replace numeric IDs
+ * with the real URL strings from idToUrlMapping. The `path` may include `*`
+ * for array indices (indicating "all items in the array").
+ */
+export declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlMapping: Record<string, string>): void;
+/**
+ * Mapping from LLM provider names to their corresponding environment variable names for API keys.
+ */
+export declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string>>;
+/**
+ * Loads an API key for a provider, checking environment variables.
+ * @param provider The name of the provider (e.g., 'openai', 'anthropic')
+ * @param logger Optional logger for info/error messages
+ * @returns The API key if found, undefined otherwise
+ */
+export declare function loadApiKeyFromEnv(provider: string | undefined, logger: (logLine: LogLine) => void): string | undefined;
+export declare function trimTrailingTextNode(path: string | undefined): string | undefined;
+export interface JsonSchemaProperty {
+    type: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    minimum?: number;
+    maximum?: number;
+    description?: string;
+}
+export interface JsonSchema extends JsonSchemaProperty {
+    type: string;
+}
+/**
+ * Converts a JSON Schema object to a Zod schema
+ * @param schema The JSON Schema object to convert
+ * @returns A Zod schema equivalent to the input JSON Schema
+ */
+export declare function jsonSchemaToZod(schema: JsonSchema): ZodTypeAny;

package/dist/lib/v3/agent/AgentClient.d.ts

@@ -0,0 +1,18 @@
+import { AgentAction, AgentResult, AgentType, AgentExecutionOptions } from "../types/agent";
+/**
+ * Abstract base class for agent clients
+ * This provides a common interface for all agent implementations
+ */
+export declare abstract class AgentClient {
+    type: AgentType;
+    modelName: string;
+    clientOptions: Record<string, unknown>;
+    userProvidedInstructions?: string;
+    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string);
+    abstract execute(options: AgentExecutionOptions): Promise<AgentResult>;
+    abstract captureScreenshot(options?: Record<string, unknown>): Promise<unknown>;
+    abstract setViewport(width: number, height: number): void;
+    abstract setCurrentUrl(url: string): void;
+    abstract setScreenshotProvider(provider: () => Promise<string>): void;
+    abstract setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
+}

package/dist/lib/v3/agent/AgentProvider.d.ts

@@ -0,0 +1,18 @@
+import { AgentType } from "../types/agent";
+import { LogLine } from "../types/log";
+import { ToolSet } from "ai/dist";
+import { AgentClient } from "./AgentClient";
+/**
+ * Provider for agent clients
+ * This class is responsible for creating the appropriate agent client
+ * based on the provider type
+ */
+export declare class AgentProvider {
+    private logger;
+    /**
+     * Create a new agent provider
+     */
+    constructor(logger: (message: LogLine) => void);
+    getClient(modelName: string, clientOptions?: Record<string, unknown>, userProvidedInstructions?: string, tools?: ToolSet): AgentClient;
+    static getAgentProvider(modelName: string): AgentType;
+}

package/dist/lib/v3/agent/AnthropicCUAClient.d.ts

@@ -0,0 +1,55 @@
+import { AgentAction, AgentExecutionOptions, AgentResult, AgentType, AnthropicContentBlock, AnthropicMessage, AnthropicToolResult, ToolUseItem } from "../types/agent";
+import { LogLine } from "../types/log";
+import { ToolSet } from "ai";
+import { AgentClient } from "./AgentClient";
+export type ResponseInputItem = AnthropicMessage | AnthropicToolResult;
+/**
+ * Client for Anthropic's Computer Use API
+ * This implementation uses the official Anthropic Messages API for Computer Use
+ */
+export declare class AnthropicCUAClient extends AgentClient {
+    private apiKey;
+    private baseURL?;
+    private client;
+    lastMessageId?: string;
+    private currentViewport;
+    private currentUrl?;
+    private screenshotProvider?;
+    private actionHandler?;
+    private thinkingBudget;
+    private tools?;
+    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string, clientOptions?: Record<string, unknown>, tools?: ToolSet);
+    setViewport(width: number, height: number): void;
+    setCurrentUrl(url: string): void;
+    setScreenshotProvider(provider: () => Promise<string>): void;
+    setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
+    /**
+     * Execute a task with the Anthropic CUA
+     * This is the main entry point for the agent
+     * @implements AgentClient.execute
+     */
+    execute(executionOptions: AgentExecutionOptions): Promise<AgentResult>;
+    executeStep(inputItems: ResponseInputItem[], logger: (message: LogLine) => void): Promise<{
+        actions: AgentAction[];
+        message: string;
+        completed: boolean;
+        nextInputItems: ResponseInputItem[];
+        usage: {
+            input_tokens: number;
+            output_tokens: number;
+            inference_time_ms: number;
+        };
+    }>;
+    private createInitialInputItems;
+    getAction(inputItems: ResponseInputItem[]): Promise<{
+        content: AnthropicContentBlock[];
+        id: string;
+        usage: Record<string, number>;
+    }>;
+    takeAction(toolUseItems: ToolUseItem[], logger: (message: LogLine) => void): Promise<AnthropicToolResult[]>;
+    private convertToolUseToAction;
+    captureScreenshot(options?: {
+        base64Image?: string;
+        currentUrl?: string;
+    }): Promise<string>;
+}

package/dist/lib/v3/agent/OpenAICUAClient.d.ts

@@ -0,0 +1,64 @@
+import { LogLine } from "../types/log";
+import { AgentAction, AgentResult, AgentType, AgentExecutionOptions, ResponseInputItem, ResponseItem } from "../types/agent";
+import { AgentClient } from "./AgentClient";
+import { ToolSet } from "ai/dist";
+/**
+ * Client for OpenAI's Computer Use Assistant API
+ * This implementation uses the official OpenAI Responses API for Computer Use
+ */
+export declare class OpenAICUAClient extends AgentClient {
+    private apiKey;
+    private organization?;
+    private baseURL;
+    private client;
+    lastResponseId?: string;
+    private currentViewport;
+    private currentUrl?;
+    private screenshotProvider?;
+    private actionHandler?;
+    private reasoningItems;
+    private environment;
+    private tools?;
+    constructor(type: AgentType, modelName: string, userProvidedInstructions?: string, clientOptions?: Record<string, unknown>, tools?: ToolSet);
+    setViewport(width: number, height: number): void;
+    setCurrentUrl(url: string): void;
+    setScreenshotProvider(provider: () => Promise<string>): void;
+    setActionHandler(handler: (action: AgentAction) => Promise<void>): void;
+    /**
+     * Execute a task with the OpenAI CUA
+     * This is the main entry point for the agent
+     * @implements AgentClient.execute
+     */
+    execute(executionOptions: AgentExecutionOptions): Promise<AgentResult>;
+    /**
+     * Execute a single step of the agent
+     * This coordinates the flow: Request → Get Action → Execute Action
+     */
+    executeStep(inputItems: ResponseInputItem[], previousResponseId: string | undefined, logger: (message: LogLine) => void): Promise<{
+        actions: AgentAction[];
+        message: string;
+        completed: boolean;
+        nextInputItems: ResponseInputItem[];
+        responseId: string;
+        usage: {
+            input_tokens: number;
+            output_tokens: number;
+            inference_time_ms: number;
+        };
+    }>;
+    private isComputerCallItem;
+    private isFunctionCallItem;
+    private createInitialInputItems;
+    getAction(inputItems: ResponseInputItem[], previousResponseId?: string): Promise<{
+        output: ResponseItem[];
+        responseId: string;
+        usage: Record<string, number>;
+    }>;
+    takeAction(output: ResponseItem[], logger: (message: LogLine) => void): Promise<ResponseInputItem[]>;
+    private convertComputerCallToAction;
+    private convertFunctionCallToAction;
+    captureScreenshot(options?: {
+        base64Image?: string;
+        currentUrl?: string;
+    }): Promise<string>;
+}

package/dist/lib/v3/agent/StagehandAgent.d.ts

@@ -0,0 +1,15 @@
+import { LogLine } from "../types/log";
+import { AgentExecuteOptions, AgentResult } from "../types/agent";
+import { AgentClient } from "./AgentClient";
+/**
+ * Main interface for agent operations in Stagehand
+ * This class provides methods for executing tasks with an agent
+ */
+export declare class StagehandAgent {
+    private client;
+    private logger;
+    constructor(client: AgentClient, logger: (message: LogLine) => void);
+    execute(optionsOrInstruction: AgentExecuteOptions | string): Promise<AgentResult>;
+    getModelName(): string;
+    getAgentType(): string;
+}

package/dist/lib/v3/agent/tools/index.d.ts

@@ -0,0 +1,229 @@
+import type { V3 } from "@/lib/v3/v3";
+import type { LogLine } from "../../types/log";
+export interface V3AgentToolOptions {
+    executionModel?: string;
+    logger?: (message: LogLine) => void;
+}
+export declare function createAgentTools(v3: V3, options?: V3AgentToolOptions): {
+    act: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        action: import("zod/v3").ZodString;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        action?: string;
+    }, {
+        action?: string;
+    }>, {
+        success: boolean;
+        action: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        action?: undefined;
+    }> & {
+        execute: (args: {
+            action?: string;
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            action: string;
+            error?: undefined;
+        } | {
+            success: boolean;
+            error: any;
+            action?: undefined;
+        }>;
+    };
+    ariaTree: import("ai/dist").Tool<import("zod/v3").ZodObject<{}, "strip", import("zod/v3").ZodTypeAny, {}, {}>, {
+        content: string;
+        pageUrl: string;
+    }> & {
+        execute: (args: {}, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            content: string;
+            pageUrl: string;
+        }>;
+    };
+    close: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        reasoning: import("zod/v3").ZodString;
+        taskComplete: import("zod/v3").ZodBoolean;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        reasoning?: string;
+        taskComplete?: boolean;
+    }, {
+        reasoning?: string;
+        taskComplete?: boolean;
+    }>, {
+        success: boolean;
+        reasoning: string;
+        taskComplete: boolean;
+    }> & {
+        execute: (args: {
+            reasoning?: string;
+            taskComplete?: boolean;
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            reasoning: string;
+            taskComplete: boolean;
+        }>;
+    };
+    extract: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        instruction: import("zod/v3").ZodOptional<import("zod/v3").ZodString>;
+        schema: import("zod/v3").ZodOptional<import("zod/v3").ZodString>;
+        selector: import("zod/v3").ZodOptional<import("zod/v3").ZodString>;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        instruction?: string;
+        selector?: string;
+        schema?: string;
+    }, {
+        instruction?: string;
+        selector?: string;
+        schema?: string;
+    }>, {
+        success: boolean;
+        result: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        result?: undefined;
+    }> & {
+        execute: (args: {
+            instruction?: string;
+            selector?: string;
+            schema?: string;
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            result: any;
+            error?: undefined;
+        } | {
+            success: boolean;
+            error: any;
+            result?: undefined;
+        }>;
+    };
+    fillForm: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        fields: import("zod/v3").ZodArray<import("zod/v3").ZodObject<{
+            action: import("zod/v3").ZodString;
+            value: import("zod/v3").ZodString;
+        }, "strip", import("zod/v3").ZodTypeAny, {
+            value?: string;
+            action?: string;
+        }, {
+            value?: string;
+            action?: string;
+        }>, "many">;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        fields?: {
+            value?: string;
+            action?: string;
+        }[];
+    }, {
+        fields?: {
+            value?: string;
+            action?: string;
+        }[];
+    }>, {
+        success: boolean;
+        actions: unknown[];
+    }> & {
+        execute: (args: {
+            fields?: {
+                value?: string;
+                action?: string;
+            }[];
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            actions: unknown[];
+        }>;
+    };
+    goto: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        url: import("zod/v3").ZodString;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        url?: string;
+    }, {
+        url?: string;
+    }>, {
+        success: boolean;
+        url: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: any;
+        url?: undefined;
+    }> & {
+        execute: (args: {
+            url?: string;
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            url: string;
+            error?: undefined;
+        } | {
+            success: boolean;
+            error: any;
+            url?: undefined;
+        }>;
+    };
+    navback: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        reasoning: import("zod/v3").ZodString;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        reasoning?: string;
+    }, {
+        reasoning?: string;
+    }>, {
+        success: boolean;
+    }> & {
+        execute: (args: {
+            reasoning?: string;
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+        }>;
+    };
+    screenshot: import("ai/dist").Tool<import("zod/v3").ZodObject<{}, "strip", import("zod/v3").ZodTypeAny, {}, {}>, {
+        base64: string;
+        timestamp: number;
+        pageUrl: string;
+    }> & {
+        execute: (args: {}, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            base64: string;
+            timestamp: number;
+            pageUrl: string;
+        }>;
+    };
+    scroll: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        pixels: import("zod/v3").ZodNumber;
+        direction: import("zod/v3").ZodEnum<["up", "down"]>;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        pixels?: number;
+        direction?: "up" | "down";
+    }, {
+        pixels?: number;
+        direction?: "up" | "down";
+    }>, {
+        success: boolean;
+        pixels: number;
+    }> & {
+        execute: (args: {
+            pixels?: number;
+            direction?: "up" | "down";
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            pixels: number;
+        }>;
+    };
+    wait: import("ai/dist").Tool<import("zod/v3").ZodObject<{
+        timeMs: import("zod/v3").ZodNumber;
+    }, "strip", import("zod/v3").ZodTypeAny, {
+        timeMs?: number;
+    }, {
+        timeMs?: number;
+    }>, {
+        success: boolean;
+        waited: number;
+    }> & {
+        execute: (args: {
+            timeMs?: number;
+        }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
+            success: boolean;
+            waited: number;
+        }>;
+    };
+};
+export type AgentTools = ReturnType<typeof createAgentTools>;