@browserbasehq/orca 3.0.0-preview.0

package/dist/lib/v3/understudy/page.d.ts

@@ -0,0 +1,241 @@
+import { Protocol } from "devtools-protocol";
+import type { CDPSessionLike } from "./cdp";
+import { CdpConnection } from "./cdp";
+import { Frame } from "./frame";
+import { FrameLocator } from "./frameLocator";
+import { LoadState } from "../types";
+export declare class Page {
+    private readonly conn;
+    private readonly mainSession;
+    private readonly _targetId;
+    /** Every CDP child session this page owns (top-level + adopted OOPIF sessions). */
+    private readonly sessions;
+    /** Unified truth for frame topology + ownership. */
+    private readonly registry;
+    /** A convenience wrapper bound to the current main frame id (top-level session). */
+    private mainFrameWrapper;
+    /** Compact ordinal per frameId (used by snapshot encoding). */
+    private frameOrdinals;
+    private nextOrdinal;
+    /** cache Frames per frameId so everyone uses the same one */
+    private readonly frameCache;
+    /** Stable id for Frames created by this Page (use top-level TargetId). */
+    private readonly pageId;
+    private constructor();
+    private cursorEnabled;
+    private ensureCursorScript;
+    enableCursorOverlay(): Promise<void>;
+    private updateCursor;
+    /**
+     * 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>;
+    /**
+     * Parent/child session emitted a `frameAttached`.
+     * Topology update + ownership stamped to **emitting session**.
+     */
+    onFrameAttached(frameId: string, parentId: string | null, session: CDPSessionLike): void;
+    /**
+     * Parent/child session emitted a `frameDetached`.
+     */
+    onFrameDetached(frameId: string, reason?: "remove" | "swap" | string): void;
+    /**
+     * Parent/child session emitted a `frameNavigated`.
+     * Topology + ownership update. Handles root swaps.
+     */
+    onFrameNavigated(frame: Protocol.Page.Frame, session: CDPSessionLike): void;
+    /**
+     * An OOPIF child session whose **main** frame id equals the parent iframe’s frameId
+     * has been attached; adopt the session into this Page and seed ownership for its subtree.
+     */
+    adoptOopifSession(childSession: CDPSessionLike, childMainFrameId: string): void;
+    /** Detach an adopted child session and prune its subtree */
+    detachOopifSession(sessionId: string): void;
+    /** Return the owning CDP session for a frameId (falls back to main session) */
+    getSessionForFrame(frameId: string): CDPSessionLike;
+    /** Always returns a Frame bound to the owning session */
+    frameForId(frameId: string): Frame;
+    /** Expose a session by id (used by snapshot to resolve session id -> session) */
+    getSessionById(id: string): CDPSessionLike | undefined;
+    targetId(): string;
+    mainFrameId(): string;
+    mainFrame(): Frame;
+    /**
+     * Close this top-level page (tab). Best-effort via Target.closeTarget.
+     */
+    close(): Promise<void>;
+    getFullFrameTree(): Protocol.Page.FrameTree;
+    asProtocolFrameTree(rootMainFrameId: string): Protocol.Page.FrameTree;
+    private ensureOrdinal;
+    /** Public getter for snapshot code / handlers. */
+    getOrdinal(frameId: string): number;
+    listAllFrameIds(): string[];
+    /**
+     * Navigate the page; optionally wait for a lifecycle state.
+     * Waits on the **current** main frame and follows root swaps during navigation.
+     */
+    goto(url: string, options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Reload the page; optionally wait for a lifecycle state.
+     */
+    reload(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+        ignoreCache?: boolean;
+    }): Promise<void>;
+    /**
+     * Navigate back in history if possible; optionally wait for a lifecycle state.
+     */
+    goBack(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Navigate forward in history if possible; optionally wait for a lifecycle state.
+     */
+    goForward(options?: {
+        waitUntil?: LoadState;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Return the current page URL (from navigation history).
+     */
+    url(): Promise<string>;
+    /**
+     * Return the current page title.
+     * Prefers reading from the active document via Runtime.evaluate to reflect dynamic changes.
+     * Falls back to navigation history title if evaluation is unavailable.
+     */
+    title(): Promise<string>;
+    /**
+     * Capture a screenshot (delegated to the current main frame).
+     */
+    screenshot(options?: {
+        fullPage?: boolean;
+    }): Promise<string>;
+    /**
+     * Create a locator bound to the current main frame.
+     */
+    locator(selector: string): ReturnType<Frame["locator"]>;
+    /**
+     * Deep locator that supports cross-iframe traversal.
+     * - Recognizes '>>' hop notation to enter iframe contexts.
+     * - Supports deep XPath that includes iframe steps (e.g., '/html/body/iframe[2]//div').
+     * Returns a Locator scoped to the appropriate frame.
+     */
+    deepLocator(selector: string): import("./deepLocator").DeepLocatorDelegate;
+    /**
+     * Frame locator similar to Playwright: targets iframe elements and scopes
+     * subsequent locators to that frame. Supports chaining.
+     */
+    frameLocator(selector: string): FrameLocator;
+    /**
+     * List all frames belonging to this page as Frame objects bound to their owning sessions.
+     * The list is ordered by a stable ordinal assigned during the page lifetime.
+     */
+    frames(): Frame[];
+    /**
+     * Wait until the page reaches a lifecycle state on the current main frame.
+     * Mirrors Playwright's API signatures.
+     */
+    waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>;
+    /**
+     * Evaluate a function or expression in the current main frame's isolated world.
+     * - If a string is provided, it is treated as a JS expression.
+     * - If a function is provided, it is stringified and invoked with the optional argument.
+     * - The return value should be JSON-serializable. Non-serializable objects will
+     *   best-effort serialize via JSON.stringify inside the page context.
+     */
+    evaluate<R = unknown, Arg = unknown>(pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>), arg?: Arg): Promise<R>;
+    /**
+     * Force the page viewport to an exact CSS size and device scale factor.
+     * Ensures screenshots match width x height pixels when deviceScaleFactor = 1.
+     */
+    setViewportSize(width: number, height: number, options?: {
+        deviceScaleFactor?: number;
+    }): Promise<void>;
+    /**
+     * Click at absolute page coordinates (CSS pixels).
+     * Dispatches mouseMoved → mousePressed → mouseReleased via CDP Input domain
+     * on the top-level page target's session. Coordinates are relative to the
+     * viewport origin (top-left). Does not scroll.
+     */
+    click(x: number, y: number, options: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath: true;
+    }): Promise<string>;
+    click(x: number, y: number, options?: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath?: false;
+    }): Promise<void>;
+    click(x: number, y: number, options: {
+        button?: "left" | "right" | "middle";
+        clickCount?: number;
+        returnXpath: boolean;
+    }): Promise<void | string>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
+        returnXpath: true;
+    }): Promise<string>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options?: {
+        returnXpath?: false;
+    }): Promise<void>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number, options: {
+        returnXpath: boolean;
+    }): Promise<void | string>;
+    /**
+     * Drag from (fromX, fromY) to (toX, toY) using mouse events.
+     * Sends mouseMoved → mousePressed → mouseMoved (steps) → mouseReleased.
+     */
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath: true;
+    }): Promise<[string, string]>;
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options?: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath?: false;
+    }): Promise<void>;
+    dragAndDrop(fromX: number, fromY: number, toX: number, toY: number, options: {
+        button?: "left" | "right" | "middle";
+        steps?: number;
+        delay?: number;
+        returnXpath: boolean;
+    }): Promise<void | [string, string]>;
+    /**
+     * Type a string by dispatching keyDown/keyUp events per character.
+     * Focus must already be on the desired element. Uses CDP Input.dispatchKeyEvent
+     * and never falls back to Input.insertText. Optional delay applies between
+     * successive characters.
+     */
+    type(text: string, options?: {
+        delay?: number;
+        withMistakes?: boolean;
+    }): Promise<void>;
+    /**
+     * Press a single key (keyDown then keyUp). For printable characters,
+     * uses the text path on keyDown; for named keys, sets key/code/VK.
+     */
+    keyPress(key: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Create an isolated world for the **current** main frame and return its context id.
+     */
+    private createIsolatedWorldForCurrentMain;
+    /**
+     * Wait until the **current** main frame reaches a lifecycle state.
+     * - Fast path via `document.readyState`.
+     * - Event path listens at the session level and compares incoming `frameId`
+     *   to `mainFrameId()` **at event time** to follow root swaps.
+     */
+    private waitForMainLoadState;
+}

package/dist/lib/v3/understudy/piercer.d.ts

@@ -0,0 +1,4 @@
+import type { CDPSessionLike } from "./cdp";
+export declare function installV3PiercerIntoSession(session: CDPSessionLike): Promise<void>;
+/** (Optional) stream patch logs in your node console during bring-up */
+export declare function tapPiercerConsole(session: CDPSessionLike, label: string): void;

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

@@ -0,0 +1,156 @@
+import { V3Options, ActOptions, ObserveOptions, V3Metrics, V3FunctionName, ExtractOptions } from "@/lib/v3/types";
+import { V3Context } from "@/lib/v3/understudy/context";
+import { LLMClient } from "./llm/LLMClient";
+import { z } from "zod/v3";
+import type { ZodTypeAny } from "zod/v3";
+import { Action, ActResult, HistoryEntry, AgentConfig } from "./types/stagehand";
+import { AgentExecuteOptions, AgentResult } from "./types/agent";
+import { LogLine } from "./types/log";
+import { defaultExtractSchema, pageTextSchema } from "./types";
+import type { AgentReplayStep } from "./types/cache";
+/**
+ * V3
+ *
+ * Purpose:
+ * A high-level orchestrator for Stagehand V3. Abstracts away whether the browser
+ * runs **locally via Chrome** or remotely on **Browserbase**, and exposes simple
+ * entrypoints (`act`, `extract`, `observe`) that delegate to the corresponding
+ * handler classes.
+ *
+ * Responsibilities:
+ * - Bootstraps Chrome or Browserbase, ensures a working CDP WebSocket, and builds a `V3Context`.
+ * - Manages lifecycle: init, context access, cleanup.
+ * - Bridges external page objects (Playwright/Puppeteer) into internal frameIds for handlers.
+ * - Provides a stable API surface for downstream code regardless of runtime environment.
+ */
+export declare class V3 {
+    private readonly opts;
+    private state;
+    private actHandler;
+    private extractHandler;
+    private observeHandler;
+    private ctx;
+    llmClient: LLMClient;
+    private modelName;
+    private modelClientOptions;
+    private llmProvider;
+    private readonly domSettleTimeoutMs?;
+    private _isClosing;
+    private _onCdpClosed;
+    readonly experimental: boolean;
+    readonly logInferenceToFile: boolean;
+    private externalLogger?;
+    verbose: 0 | 1 | 2;
+    private _history;
+    private readonly instanceId;
+    private static _processGuardsInstalled;
+    private static _instances;
+    private cacheDir?;
+    private _agentReplayRecording;
+    v3Metrics: V3Metrics;
+    /**
+     * Async property for metrics so callers can `await v3.metrics`.
+     * Returning a Promise future-proofs async aggregation/storage.
+     */
+    get metrics(): Promise<V3Metrics>;
+    private cloneForCache;
+    private beginAgentReplayRecording;
+    private endAgentReplayRecording;
+    private discardAgentReplayRecording;
+    private isAgentReplayRecording;
+    isAgentReplayActive(): boolean;
+    recordAgentReplayStep(step: AgentReplayStep): void;
+    /**
+     * Async property for history so callers can `await v3.history`.
+     * Returns a frozen copy to avoid external mutation.
+     */
+    get history(): Promise<ReadonlyArray<HistoryEntry>>;
+    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;
+    /**
+     * Entrypoint: initializes handlers, launches Chrome or Browserbase,
+     * and sets up a CDP context.
+     */
+    init(): Promise<void>;
+    /** Apply post-connect local browser options that require CDP. */
+    private _applyPostConnectLocalOptions;
+    /**
+     * Run an "act" instruction through the ActHandler.
+     *
+     * New API:
+     * - act(instruction: string, options?: ActOptions)
+     * - act(action: Action, options?: ActOptions)
+     */
+    act(instruction: string, options?: ActOptions): Promise<ActResult>;
+    act(action: Action, options?: ActOptions): Promise<ActResult>;
+    /**
+     * Run an "extract" instruction through the ExtractHandler.
+     *
+     * Accepted forms:
+     * - extract() → pageText
+     * - extract(options) → pageText
+     * - extract(instruction) → defaultExtractSchema
+     * - 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>>;
+    /**
+     * Run an "observe" instruction through the ObserveHandler.
+     */
+    observe(): Promise<Action[]>;
+    observe(options: ObserveOptions): Promise<Action[]>;
+    observe(instruction: string, options?: ObserveOptions): Promise<Action[]>;
+    /** Return the browser-level CDP WebSocket endpoint. */
+    connectURL(): string;
+    /** Expose the current CDP-backed context. */
+    get context(): V3Context;
+    /** Best-effort cleanup of context and launched resources. */
+    close(opts?: {
+        force?: boolean;
+    }): Promise<void>;
+    /** Guard: ensure Browserbase credentials exist in options. */
+    private requireBrowserbaseCreds;
+    get logger(): (logLine: LogLine) => void;
+    /**
+     * Normalize a Playwright/Puppeteer page object into its top frame id,
+     * so handlers can resolve it to a `Page` within our V3Context.
+     */
+    private resolveTopFrameId;
+    private isPlaywrightPage;
+    private isPatchrightPage;
+    private isPuppeteerPage;
+    private normalizeToV3Page;
+    private buildActCacheKey;
+    private safeGetPageUrl;
+    private readActCacheEntry;
+    private writeActCacheEntry;
+    private sanitizeAgentExecuteOptions;
+    private buildAgentCacheSignature;
+    private buildAgentCacheKey;
+    private readAgentCacheEntry;
+    private writeAgentCacheEntry;
+    private replayAgentCacheEntry;
+    private executeAgentReplayStep;
+    private replayAgentActStep;
+    private replayAgentFillFormStep;
+    private replayAgentGotoStep;
+    private replayAgentScrollStep;
+    private replayAgentWaitStep;
+    private replayAgentNavBackStep;
+    private replayCachedActions;
+    private runWithActTimeout;
+    /**
+     * Create a v3 agent instance (AISDK tool-based) with execute().
+     * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
+     */
+    agent(options?: AgentConfig): {
+        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+    };
+}

package/dist/lib/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * AUTO-GENERATED — DO NOT EDIT BY HAND
+ *  Run `pnpm run gen-version` to refresh.
+ */
+export declare const STAGEHAND_VERSION: "3.0.0-preview.0";

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@browserbasehq/orca",
+  "version": "3.0.0-preview.0",
+  "description": "An AI web browsing framework focused on simplicity and extensibility.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "evals": "./dist/evals/cli.js"
+  },
+  "scripts": {
+    "example": "pnpm --filter @browserbasehq/stagehand-examples run start",
+    "format": "prettier --write .",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write .",
+    "eslint": "eslint .",
+    "cache:clear": "rm -rf .cache",
+    "docs": "pnpm --filter @browserbasehq/stagehand-docs run dev",
+    "evals": "tsx scripts/run-evals.ts",
+    "evals:legacy": "tsx scripts/run-evals.ts",
+    "e2e": "pnpm run build && cd evals/deterministic && playwright test --config=e2e.playwright.config.ts",
+    "e2e:bb": "pnpm run build && cd evals/deterministic && playwright test --config=bb.playwright.config.ts",
+    "e2e:local": "pnpm run build && cd evals/deterministic && playwright test --config=local.playwright.config.ts",
+    "build-v3-dom-scripts": "tsx lib/v3/dom/genDomScripts.ts",
+    "build-types": "tsc --emitDeclarationOnly --outDir dist",
+    "build-js": "tsup --entry.index lib/v3/index.ts --dts",
+    "build:cli": "tsup evals/cli.ts --outDir dist/evals --format cjs && cp evals/evals.config.json dist/evals/ && chmod +x dist/evals/cli.js && npm link",
+    "build": "pnpm run lint && pnpm run gen-version && pnpm run build-v3-dom-scripts && pnpm run build-js && pnpm run build-types",
+    "gen-version": "tsx scripts/gen-version.ts",
+    "prepare": "pnpm run build",
+    "lint": "pnpm run prettier:fix && pnpm run eslint",
+    "release": "pnpm run build && changeset publish",
+    "release-canary": "pnpm run build && changeset version --snapshot && changeset publish --tag alpha"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/lib",
+    "dist/types",
+    "dist/stagehand.config.d.ts"
+  ],
+  "keywords": [],
+  "author": "Browserbase",
+  "license": "MIT",
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.0",
+    "@changesets/cli": "^2.27.9",
+    "@eslint/js": "^9.16.0",
+    "@langchain/core": "^0.3.40",
+    "@langchain/openai": "^0.4.4",
+    "playwright-core": "^1.54.1",
+    "puppeteer-core": "^22.8.0",
+    "chrome-launcher": "^1.2.0",
+    "patchright-core": "^1.55.2",
+    "@playwright/test": "^1.42.1",
+    "@types/adm-zip": "^0.5.7",
+    "@types/cheerio": "^0.22.35",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.30",
+    "@types/ws": "^8.5.13",
+    "adm-zip": "^0.5.16",
+    "autoevals": "^0.0.64",
+    "braintrust": "^0.0.171",
+    "chalk": "^5.4.1",
+    "cheerio": "^1.0.0",
+    "chromium-bidi": "^0.10.0",
+    "esbuild": "^0.21.4",
+    "eslint": "^9.16.0",
+    "express": "^4.21.0",
+    "globals": "^15.13.0",
+    "multer": "^1.4.5-lts.1",
+    "prettier": "^3.2.5",
+    "string-comparison": "^1.3.0",
+    "tsup": "^8.2.1",
+    "tsx": "^4.10.5",
+    "typescript": "^5.2.2",
+    "typescript-eslint": "^8.17.0"
+  },
+  "peerDependencies": {
+    "deepmerge": "^4.3.1",
+    "dotenv": "^16.4.5",
+    "zod": "3.25.67"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.39.0",
+    "@browserbasehq/sdk": "^2.4.0",
+    "@google/genai": "^0.8.0",
+    "@modelcontextprotocol/sdk": "^1.17.2",
+    "ai": "^4.3.9",
+    "devtools-protocol": "^0.0.1464554",
+    "fetch-cookie": "^3.1.0",
+    "openai": "^4.87.1",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "playwright": "^1.52.0",
+    "ws": "^8.18.0",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "optionalDependencies": {
+    "@ai-sdk/anthropic": "^1.2.6",
+    "@ai-sdk/azure": "^1.3.19",
+    "@ai-sdk/cerebras": "^0.2.6",
+    "@ai-sdk/deepseek": "^0.2.13",
+    "@ai-sdk/google": "^1.2.6",
+    "@ai-sdk/groq": "^1.2.4",
+    "@ai-sdk/mistral": "^1.2.7",
+    "@ai-sdk/openai": "^1.0.14",
+    "@ai-sdk/perplexity": "^1.1.7",
+    "@ai-sdk/togetherai": "^0.2.6",
+    "@ai-sdk/xai": "^1.2.15",
+    "ollama-ai-provider": "^1.2.0"
+  },
+  "directories": {
+    "doc": "docs",
+    "example": "examples",
+    "lib": "lib"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/browserbase/stagehand.git"
+  },
+  "bugs": {
+    "url": "https://github.com/browserbase/stagehand/issues"
+  },
+  "homepage": "https://stagehand.dev",
+  "overrides": {
+    "whatwg-url": "^14.0.0"
+  },
+  "packageManager": "pnpm@9.15.0+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"
+}