@browserbasehq/orca 3.0.0-preview.5 → 3.0.0-preview.7

package/dist/index.d.ts

@@ -1,17 +1,17 @@
-import { ZodType, z, ZodError, ZodTypeAny } from 'zod/v3';
+import z, { ZodType, z as z$1, ZodError, ZodTypeAny } from 'zod/v3';
 import { ClientOptions as ClientOptions$2 } from '@anthropic-ai/sdk';
 import { LanguageModelV2 } from '@ai-sdk/provider';
 import { ClientOptions as ClientOptions$1 } from 'openai';
 import { generateObject, generateText, streamText, streamObject, experimental_generateImage, embed, embedMany, experimental_transcribe, experimental_generateSpeech, ToolSet } from 'ai';
-import { Protocol } from 'devtools-protocol';
-import { Buffer as Buffer$1 } from 'buffer';
+import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
 import { Page as Page$1 } from 'playwright-core';
 export { Page as PlaywrightPage } from 'playwright-core';
-import { Page as Page$3 } from 'patchright-core';
-export { Page as PatchrightPage } from 'patchright-core';
 import { Page as Page$2 } from 'puppeteer-core';
 export { Page as PuppeteerPage } from 'puppeteer-core';
-import { Client, ClientOptions as ClientOptions$3 } from '@modelcontextprotocol/sdk/client/index.js';
+import { Page as Page$3 } from 'patchright-core';
+export { Page as PatchrightPage } from 'patchright-core';
+import { Protocol } from 'devtools-protocol';
+import { Buffer as Buffer$1 } from 'buffer';
 import Browserbase from '@browserbasehq/sdk';
 import { ToolSet as ToolSet$1 } from 'ai/dist';
 import { Schema } from '@google/genai';
@@ -573,6 +573,27 @@ declare class LocatorDelegate {
 type AnyPage = Page$1 | Page$2 | Page$3 | Page;
 type LoadState = "load" | "domcontentloaded" | "networkidle";
 
+declare class StagehandAPIClient {
+    private apiKey;
+    private projectId;
+    private sessionId?;
+    private modelApiKey;
+    private logger;
+    private fetchWithCookies;
+    constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
+    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: StartSessionParams): Promise<StartSessionResult>;
+    act({ input, options, frameId }: APIActParameters): Promise<ActResult>;
+    extract<T extends z.AnyZodObject>({ instruction, schema: zodSchema, options, frameId, }: APIExtractParameters): Promise<ExtractResult<T>>;
+    observe({ instruction, options, frameId, }: APIObserveParameters): Promise<Action[]>;
+    goto(url: string, options?: {
+        waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    }, frameId?: string): Promise<void>;
+    agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
+    end(): Promise<Response>;
+    private execute;
+    private request;
+}
+
 declare class Page {
     private readonly conn;
     private readonly mainSession;
@@ -592,7 +613,11 @@ declare class Page {
     private readonly pageId;
     /** Cached current URL for synchronous page.url() */
     private _currentUrl;
+    private navigationCommandSeq;
+    private latestNavigationCommandId;
     private readonly networkManager;
+    /** Optional API client for routing page operations to the API */
+    private readonly apiClient;
     private constructor();
     private cursorEnabled;
     private ensureCursorScript;
@@ -602,7 +627,7 @@ declare class Page {
      * Factory: create Page and seed registry with the shallow tree from Page.getFrameTree.
      * Assumes Page domain is already enabled on the session passed in.
      */
-    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string): Promise<Page>;
+    static create(conn: CdpConnection, session: CDPSessionLike, targetId: string, apiClient?: StagehandAPIClient | null, localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null): Promise<Page>;
     /**
      * Parent/child session emitted a `frameAttached`.
      * Topology update + ownership stamped to **emitting session**.
@@ -682,6 +707,8 @@ declare class Page {
      * Return the current page URL (synchronous, cached from navigation events).
      */
     url(): string;
+    private beginNavigationCommand;
+    isCurrentNavigationCommand(id: number): boolean;
     /**
      * Return the current page title.
      * Prefers reading from the active document via Runtime.evaluate to reflect dynamic changes.
@@ -840,65 +867,6 @@ declare class Page {
     waitForMainLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
 }
 
-/**
- * Represents a path through a Zod schema from the root object down to a
- * particular field. The `segments` array describes the chain of keys/indices.
- *
- * - **String** segments indicate object property names.
- * - **Number** segments indicate array indices.
- *
- * For example, `["users", 0, "homepage"]` might describe reaching
- * the `homepage` field in `schema.users[0].homepage`.
- */
-interface ZodPathSegments {
-    /**
-     * The ordered list of keys/indices leading from the schema root
-     * to the targeted field.
-     */
-    segments: Array<string | number>;
-}
-
-type EvaluateOptions = {
-    /** The question to ask about the task state */
-    question: string;
-    /** The answer to the question */
-    answer?: string;
-    /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */
-    screenshot?: boolean | Buffer[];
-    /** Custom system prompt for the evaluator */
-    systemPrompt?: string;
-    /** Delay in milliseconds before taking the screenshot @default 250 */
-    screenshotDelayMs?: number;
-    /** The agent's reasoning/thought process for completing the task */
-    agentReasoning?: string;
-};
-type BatchAskOptions = {
-    /** Array of questions with optional answers */
-    questions: Array<{
-        question: string;
-        answer?: string;
-    }>;
-    /** Whether to take a screenshot of the task state */
-    screenshot?: boolean;
-    /** Custom system prompt for the evaluator */
-    systemPrompt?: string;
-    /** Delay in milliseconds before taking the screenshot @default 1000 */
-    screenshotDelayMs?: number;
-};
-/**
- * Result of an evaluation
- */
-interface EvaluationResult {
-    /**
-     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
-     */
-    evaluation: "YES" | "NO" | "INVALID";
-    /**
-     * The reasoning behind the evaluation
-     */
-    reasoning: string;
-}
-
 interface AgentAction {
     type: string;
     reasoning?: string;
@@ -1084,7 +1052,7 @@ interface ActResult {
     actionDescription: string;
     actions: Action[];
 }
-type ExtractResult<T extends z.AnyZodObject> = z.infer<T>;
+type ExtractResult<T extends z$1.AnyZodObject> = z$1.infer<T>;
 interface Action {
     selector: string;
     description: string;
@@ -1092,7 +1060,7 @@ interface Action {
     arguments?: string[];
 }
 interface HistoryEntry {
-    method: "act" | "extract" | "observe" | "navigate";
+    method: "act" | "extract" | "observe" | "navigate" | "agent";
     parameters: unknown;
     result: unknown;
     timestamp: string;
@@ -1103,16 +1071,16 @@ interface ExtractOptions {
     selector?: string;
     page?: Page$1 | Page$2 | Page$3 | Page;
 }
-declare const defaultExtractSchema: z.ZodObject<{
-    extraction: z.ZodString;
-}, "strip", z.ZodTypeAny, {
+declare const defaultExtractSchema: z$1.ZodObject<{
+    extraction: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
     extraction?: string;
 }, {
     extraction?: string;
 }>;
-declare const pageTextSchema: z.ZodObject<{
-    pageText: z.ZodString;
-}, "strip", z.ZodTypeAny, {
+declare const pageTextSchema: z$1.ZodObject<{
+    pageText: z$1.ZodString;
+}, "strip", z$1.ZodTypeAny, {
     pageText?: string;
 }, {
     pageText?: string;
@@ -1207,6 +1175,7 @@ interface V3Options {
     /** Directory used to persist cached actions for act(). */
     cacheDir?: string;
     domSettleTimeout?: number;
+    disableAPI?: boolean;
 }
 
 declare class StagehandError extends Error {
@@ -1313,6 +1282,103 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
     constructor(segment: string, hint?: string);
 }
 
+interface StagehandAPIConstructorParams {
+    apiKey: string;
+    projectId: string;
+    logger: (message: LogLine) => void;
+}
+interface StartSessionParams {
+    modelName: string;
+    modelApiKey: string;
+    domSettleTimeoutMs: number;
+    verbose: number;
+    systemPrompt?: string;
+    browserbaseSessionCreateParams?: Omit<Browserbase.Sessions.SessionCreateParams, "projectId"> & {
+        projectId?: string;
+    };
+    selfHeal?: boolean;
+    browserbaseSessionID?: string;
+}
+interface StartSessionResult {
+    sessionId: string;
+    available?: boolean;
+}
+interface APIActParameters {
+    input: string | Action;
+    options?: ActOptions;
+    frameId?: string;
+}
+interface APIExtractParameters {
+    instruction?: string;
+    schema?: ZodTypeAny;
+    options?: ExtractOptions;
+    frameId?: string;
+}
+interface APIObserveParameters {
+    instruction?: string;
+    options?: ObserveOptions;
+    frameId?: string;
+}
+
+/**
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
+ *
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
+ */
+interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
+
+type EvaluateOptions = {
+    /** The question to ask about the task state */
+    question: string;
+    /** The answer to the question */
+    answer?: string;
+    /** Whether to take a screenshot of the task state, or array of screenshots to evaluate */
+    screenshot?: boolean | Buffer[];
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 250 */
+    screenshotDelayMs?: number;
+    /** The agent's reasoning/thought process for completing the task */
+    agentReasoning?: string;
+};
+type BatchAskOptions = {
+    /** Array of questions with optional answers */
+    questions: Array<{
+        question: string;
+        answer?: string;
+    }>;
+    /** Whether to take a screenshot of the task state */
+    screenshot?: boolean;
+    /** Custom system prompt for the evaluator */
+    systemPrompt?: string;
+    /** Delay in milliseconds before taking the screenshot @default 1000 */
+    screenshotDelayMs?: number;
+};
+/**
+ * Result of an evaluation
+ */
+interface EvaluationResult {
+    /**
+     * The evaluation result ('YES', 'NO', or 'INVALID' if parsing failed or value was unexpected)
+     */
+    evaluation: "YES" | "NO" | "INVALID";
+    /**
+     * The reasoning behind the evaluation
+     */
+    reasoning: string;
+}
+
 /**
  * V3Context
  *
@@ -1327,6 +1393,8 @@ declare class StagehandShadowSegmentNotFoundError extends StagehandError {
 declare class V3Context {
     readonly conn: CdpConnection;
     private readonly env;
+    private readonly apiClient;
+    private readonly localBrowserLaunchOptions;
     private constructor();
     private readonly _piercerInstalled;
     private _lastPopupSignalAt;
@@ -1346,6 +1414,8 @@ declare class V3Context {
      */
     static create(wsUrl: string, opts?: {
         env?: "LOCAL" | "BROWSERBASE";
+        apiClient?: StagehandAPIClient | null;
+        localBrowserLaunchOptions?: LocalBrowserLaunchOptions | null;
     }): Promise<V3Context>;
     /**
      * Wait until at least one top-level Page has been created and registered.
@@ -1509,8 +1579,10 @@ declare class V3 {
     private _onCdpClosed;
     readonly experimental: boolean;
     readonly logInferenceToFile: boolean;
+    readonly disableAPI: boolean;
     private externalLogger?;
     verbose: 0 | 1 | 2;
+    private stagehandLogger;
     private _history;
     private readonly instanceId;
     private static _processGuardsInstalled;
@@ -1518,7 +1590,9 @@ declare class V3 {
     private cacheStorage;
     private actCache;
     private agentCache;
+    private apiClient;
     v3Metrics: V3Metrics;
+    constructor(opts: V3Options);
     /**
      * Async property for metrics so callers can `await v3.metrics`.
      * Returning a Promise future-proofs async aggregation/storage.
@@ -1539,7 +1613,6 @@ declare class V3 {
     addToHistory(method: HistoryEntry["method"], parameters: unknown, result?: unknown): void;
     updateMetrics(functionName: V3FunctionName, promptTokens: number, completionTokens: number, inferenceTimeMs: number): void;
     private updateTotalMetrics;
-    constructor(opts: V3Options);
     private _immediateShutdown;
     private static _installProcessGuards;
     /**
@@ -1569,10 +1642,10 @@ declare class V3 {
      * - extract(instruction, schema) → schema-inferred
      * - extract(instruction, schema, options)
      */
-    extract(): Promise<z.infer<typeof pageTextSchema>>;
-    extract(options: ExtractOptions): Promise<z.infer<typeof pageTextSchema>>;
-    extract(instruction: string, options?: ExtractOptions): Promise<z.infer<typeof defaultExtractSchema>>;
-    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z.infer<T>>;
+    extract(): Promise<z$1.infer<typeof pageTextSchema>>;
+    extract(options: ExtractOptions): Promise<z$1.infer<typeof pageTextSchema>>;
+    extract(instruction: string, options?: ExtractOptions): Promise<z$1.infer<typeof defaultExtractSchema>>;
+    extract<T extends ZodTypeAny>(instruction: string, schema: T, options?: ExtractOptions): Promise<z$1.infer<T>>;
     /**
      * Run an "observe" instruction through the ObserveHandler.
      */
@@ -1644,14 +1717,14 @@ declare class AgentProvider {
     static getAgentProvider(modelName: string): AgentProviderType;
 }
 
-declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
+declare function validateZodSchema(schema: z$1.ZodTypeAny, data: unknown): boolean;
 /**
  * Detects if the code is running in the Bun runtime environment.
  * @returns {boolean} True if running in Bun, false otherwise.
  */
 declare function isRunningInBun(): boolean;
-declare function toGeminiSchema(zodSchema: z.ZodTypeAny): Schema;
-declare function getZodType(schema: z.ZodTypeAny): string;
+declare function toGeminiSchema(zodSchema: z$1.ZodTypeAny): Schema;
+declare function getZodType(schema: z$1.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()`.
@@ -1665,7 +1738,7 @@ declare function getZodType(schema: z.ZodTypeAny): string;
  *   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.
  */
-declare function transformSchema(schema: z.ZodTypeAny, currentPath: Array<string | number>): [z.ZodTypeAny, ZodPathSegments[]];
+declare function transformSchema(schema: z$1.ZodTypeAny, currentPath: Array<string | number>): [z$1.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
@@ -1676,7 +1749,7 @@ declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlM
 /**
  * Mapping from LLM provider names to their corresponding environment variable names for API keys.
  */
-declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string>>;
+declare const providerEnvVarMap: Partial<Record<ModelProvider | string, string | Array<string>>>;
 /**
  * Loads an API key for a provider, checking environment variables.
  * @param provider The name of the provider (e.g., 'openai', 'anthropic')