@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.0

package/dist/esm/lib/v3/understudy/selectorResolver.js

@@ -0,0 +1,296 @@
+import { locatorScriptBootstrap, locatorScriptGlobalRefs, } from "../dom/build/locatorScripts.generated.js";
+import { v3Logger } from "../logger.js";
+import { executionContexts } from "./executionContextRegistry.js";
+export class FrameSelectorResolver {
+    frame;
+    constructor(frame) {
+        this.frame = frame;
+    }
+    static parseSelector(raw) {
+        const trimmed = raw.trim();
+        const isText = /^text=/i.test(trimmed);
+        const looksLikeXPath = /^xpath=/i.test(trimmed) ||
+            trimmed.startsWith("/") ||
+            trimmed.startsWith("(");
+        const isCssPrefixed = /^css=/i.test(trimmed);
+        if (isText) {
+            let value = trimmed.replace(/^text=/i, "").trim();
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            return { kind: "text", value };
+        }
+        if (looksLikeXPath) {
+            const value = trimmed.replace(/^xpath=/i, "");
+            return { kind: "xpath", value };
+        }
+        let selector = isCssPrefixed ? trimmed.replace(/^css=/i, "") : trimmed;
+        if (selector.includes(">>")) {
+            selector = selector
+                .split(">>")
+                .map((piece) => piece.trim())
+                .filter(Boolean)
+                .join(" ");
+        }
+        return { kind: "css", value: selector };
+    }
+    async resolveFirst(query) {
+        return this.resolveAtIndex(query, 0);
+    }
+    async resolveAll(query, { limit = Infinity } = {}) {
+        if (limit <= 0)
+            return [];
+        switch (query.kind) {
+            case "css":
+                return this.resolveCss(query.value, limit);
+            case "text":
+                return this.resolveText(query.value, limit);
+            case "xpath":
+                return this.resolveXPath(query.value, limit);
+            default:
+                return [];
+        }
+    }
+    async count(query) {
+        switch (query.kind) {
+            case "css":
+                return this.countCss(query.value);
+            case "text":
+                return this.countText(query.value);
+            case "xpath":
+                return this.countXPath(query.value);
+            default:
+                return 0;
+        }
+    }
+    async resolveAtIndex(query, index) {
+        if (index < 0 || !Number.isFinite(index))
+            return null;
+        const results = await this.resolveAll(query, { limit: index + 1 });
+        return results[index] ?? null;
+    }
+    buildLocatorInvocation(name, args) {
+        const call = `${locatorScriptGlobalRefs[name]}(${args.join(", ")})`;
+        return `(() => { ${locatorScriptBootstrap}; return ${call}; })()`;
+    }
+    async resolveCss(selector, limit) {
+        if (limit <= 0)
+            return [];
+        const session = this.frame.session;
+        const { executionContextId } = await session.send("Page.createIsolatedWorld", {
+            frameId: this.frame.frameId,
+            worldName: "v3-world",
+        });
+        const ctxId = await executionContexts.waitForMainWorld(session, this.frame.frameId, 1000);
+        const results = [];
+        let loggedFallback = false;
+        for (let index = 0; index < limit; index += 1) {
+            const primaryExpr = this.buildLocatorInvocation("resolveCssSelector", [
+                JSON.stringify(selector),
+                String(index),
+            ]);
+            const primary = await this.evaluateElement(primaryExpr, executionContextId);
+            if (primary) {
+                results.push(primary);
+                continue;
+            }
+            if (!loggedFallback) {
+                v3Logger({
+                    category: "locator",
+                    message: "css pierce-fallback",
+                    level: 2,
+                    auxiliary: {
+                        frameId: { value: String(this.frame.frameId), type: "string" },
+                        selector: { value: selector, type: "string" },
+                    },
+                });
+                loggedFallback = true;
+            }
+            const fallbackExpr = this.buildLocatorInvocation("resolveCssSelectorPierce", [JSON.stringify(selector), String(index)]);
+            const fallback = await this.evaluateElement(fallbackExpr, ctxId);
+            if (fallback) {
+                results.push(fallback);
+                continue;
+            }
+            break;
+        }
+        return results;
+    }
+    async resolveText(value, limit) {
+        if (limit <= 0)
+            return [];
+        const session = this.frame.session;
+        const ctxId = await executionContexts.waitForMainWorld(session, this.frame.frameId, 1000);
+        const results = [];
+        for (let index = 0; index < limit; index += 1) {
+            const expr = this.buildLocatorInvocation("resolveTextSelector", [
+                JSON.stringify(value),
+                String(index),
+            ]);
+            const resolved = await this.evaluateElement(expr, ctxId);
+            if (!resolved)
+                break;
+            results.push(resolved);
+        }
+        return results;
+    }
+    async resolveXPath(value, limit) {
+        if (limit <= 0)
+            return [];
+        const session = this.frame.session;
+        const ctxId = await executionContexts.waitForMainWorld(session, this.frame.frameId, 1000);
+        const results = [];
+        for (let index = 0; index < limit; index += 1) {
+            const expr = this.buildLocatorInvocation("resolveXPathMainWorld", [
+                JSON.stringify(value),
+                String(index),
+            ]);
+            const resolved = await this.evaluateElement(expr, ctxId);
+            if (!resolved)
+                break;
+            results.push(resolved);
+        }
+        return results;
+    }
+    async countCss(selector) {
+        const session = this.frame.session;
+        const { executionContextId } = await session.send("Page.createIsolatedWorld", {
+            frameId: this.frame.frameId,
+            worldName: "v3-world",
+        });
+        const primaryExpr = this.buildLocatorInvocation("countCssMatchesPrimary", [
+            JSON.stringify(selector),
+        ]);
+        const primary = await this.evaluateCount(primaryExpr, executionContextId);
+        const ctxId = await executionContexts.waitForMainWorld(session, this.frame.frameId, 1000);
+        const fallbackExpr = this.buildLocatorInvocation("countCssMatchesPierce", [
+            JSON.stringify(selector),
+        ]);
+        const fallback = await this.evaluateCount(fallbackExpr, ctxId);
+        return Math.max(primary, fallback);
+    }
+    async countText(value) {
+        const session = this.frame.session;
+        const ctxId = await executionContexts.waitForMainWorld(session, this.frame.frameId, 1000);
+        const expr = this.buildLocatorInvocation("countTextMatches", [
+            JSON.stringify(value),
+        ]);
+        try {
+            const evalRes = await session.send("Runtime.evaluate", {
+                expression: expr,
+                contextId: ctxId,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            if (evalRes.exceptionDetails) {
+                const details = evalRes.exceptionDetails;
+                v3Logger({
+                    category: "locator",
+                    message: "count text evaluate exception",
+                    level: 0,
+                    auxiliary: {
+                        frameId: { value: String(this.frame.frameId), type: "string" },
+                        selector: { value: value, type: "string" },
+                        exception: {
+                            value: details.text ??
+                                String(details.exception?.description ??
+                                    details.exception?.value ??
+                                    ""),
+                            type: "string",
+                        },
+                    },
+                });
+                return 0;
+            }
+            const data = (evalRes.result.value ?? {});
+            const num = typeof data.count === "number" ? data.count : Number(data.count);
+            if (!Number.isFinite(num))
+                return 0;
+            return Math.max(0, Math.floor(num));
+        }
+        catch {
+            return 0;
+        }
+    }
+    async countXPath(value) {
+        const session = this.frame.session;
+        const ctxId = await executionContexts.waitForMainWorld(session, this.frame.frameId, 1000);
+        const expr = this.buildLocatorInvocation("countXPathMatchesMainWorld", [
+            JSON.stringify(value),
+        ]);
+        try {
+            const evalRes = await session.send("Runtime.evaluate", {
+                expression: expr,
+                contextId: ctxId,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            if (evalRes.exceptionDetails) {
+                return 0;
+            }
+            const num = typeof evalRes.result.value === "number"
+                ? evalRes.result.value
+                : Number(evalRes.result.value);
+            if (!Number.isFinite(num))
+                return 0;
+            return Math.max(0, Math.floor(num));
+        }
+        catch {
+            return 0;
+        }
+    }
+    async resolveFromObjectId(objectId) {
+        const session = this.frame.session;
+        let nodeId = null;
+        try {
+            const rn = await session.send("DOM.requestNode", { objectId });
+            nodeId = rn.nodeId ?? null;
+        }
+        catch {
+            nodeId = null;
+        }
+        return { objectId, nodeId };
+    }
+    async evaluateCount(expression, contextId) {
+        const session = this.frame.session;
+        try {
+            const evalRes = await session.send("Runtime.evaluate", {
+                expression,
+                contextId,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            if (evalRes.exceptionDetails) {
+                return 0;
+            }
+            const value = evalRes.result.value;
+            const num = typeof value === "number" ? value : Number(value);
+            if (!Number.isFinite(num))
+                return 0;
+            return Math.max(0, Math.floor(num));
+        }
+        catch {
+            return 0;
+        }
+    }
+    async evaluateElement(expression, contextId) {
+        const session = this.frame.session;
+        try {
+            const evalRes = await session.send("Runtime.evaluate", {
+                expression,
+                contextId,
+                returnByValue: false,
+                awaitPromise: true,
+            });
+            if (evalRes.exceptionDetails || !evalRes.result.objectId) {
+                return null;
+            }
+            return this.resolveFromObjectId(evalRes.result.objectId);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=selectorResolver.js.map

package/dist/esm/lib/v3/understudy/selectorResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selectorResolver.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/selectorResolver.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Protocol } from \"devtools-protocol\";\nimport {\n  locatorScriptBootstrap,\n  locatorScriptGlobalRefs,\n  type LocatorScriptName,\n} from \"../dom/build/locatorScripts.generated.js\";\nimport { v3Logger } from \"../logger.js\";\nimport type { Frame } from \"./frame.js\";\nimport { executionContexts } from \"./executionContextRegistry.js\";\n\nexport type SelectorQuery =\n  | { kind: \"css\"; value: string }\n  | { kind: \"text\"; value: string }\n  | { kind: \"xpath\"; value: string };\n\nexport interface ResolvedNode {\n  objectId: Protocol.Runtime.RemoteObjectId;\n  nodeId: Protocol.DOM.NodeId | null;\n}\n\nexport interface ResolveManyOptions {\n  limit?: number;\n}\n\nexport class FrameSelectorResolver {\n  constructor(private readonly frame: Frame) {}\n\n  public static parseSelector(raw: string): SelectorQuery {\n    const trimmed = raw.trim();\n\n    const isText = /^text=/i.test(trimmed);\n    const looksLikeXPath =\n      /^xpath=/i.test(trimmed) ||\n      trimmed.startsWith(\"/\") ||\n      trimmed.startsWith(\"(\");\n    const isCssPrefixed = /^css=/i.test(trimmed);\n\n    if (isText) {\n      let value = trimmed.replace(/^text=/i, \"\").trim();\n      if (\n        (value.startsWith('\"') && value.endsWith('\"')) ||\n        (value.startsWith(\"'\") && value.endsWith(\"'\"))\n      ) {\n        value = value.slice(1, -1);\n      }\n      return { kind: \"text\", value };\n    }\n\n    if (looksLikeXPath) {\n      const value = trimmed.replace(/^xpath=/i, \"\");\n      return { kind: \"xpath\", value };\n    }\n\n    let selector = isCssPrefixed ? trimmed.replace(/^css=/i, \"\") : trimmed;\n    if (selector.includes(\">>\")) {\n      selector = selector\n        .split(\">>\")\n        .map((piece) => piece.trim())\n        .filter(Boolean)\n        .join(\" \");\n    }\n\n    return { kind: \"css\", value: selector };\n  }\n\n  public async resolveFirst(\n    query: SelectorQuery,\n  ): Promise<ResolvedNode | null> {\n    return this.resolveAtIndex(query, 0);\n  }\n\n  public async resolveAll(\n    query: SelectorQuery,\n    { limit = Infinity }: ResolveManyOptions = {},\n  ): Promise<ResolvedNode[]> {\n    if (limit <= 0) return [];\n    switch (query.kind) {\n      case \"css\":\n        return this.resolveCss(query.value, limit);\n      case \"text\":\n        return this.resolveText(query.value, limit);\n      case \"xpath\":\n        return this.resolveXPath(query.value, limit);\n      default:\n        return [];\n    }\n  }\n\n  public async count(query: SelectorQuery): Promise<number> {\n    switch (query.kind) {\n      case \"css\":\n        return this.countCss(query.value);\n      case \"text\":\n        return this.countText(query.value);\n      case \"xpath\":\n        return this.countXPath(query.value);\n      default:\n        return 0;\n    }\n  }\n\n  public async resolveAtIndex(\n    query: SelectorQuery,\n    index: number,\n  ): Promise<ResolvedNode | null> {\n    if (index < 0 || !Number.isFinite(index)) return null;\n    const results = await this.resolveAll(query, { limit: index + 1 });\n    return results[index] ?? null;\n  }\n\n  private buildLocatorInvocation(\n    name: LocatorScriptName,\n    args: string[],\n  ): string {\n    const call = `${locatorScriptGlobalRefs[name]}(${args.join(\", \")})`;\n    return `(() => { ${locatorScriptBootstrap}; return ${call}; })()`;\n  }\n\n  private async resolveCss(\n    selector: string,\n    limit: number,\n  ): Promise<ResolvedNode[]> {\n    if (limit <= 0) return [];\n\n    const session = this.frame.session;\n    const { executionContextId } = await session.send<{\n      executionContextId: Protocol.Runtime.ExecutionContextId;\n    }>(\"Page.createIsolatedWorld\", {\n      frameId: this.frame.frameId,\n      worldName: \"v3-world\",\n    });\n\n    const ctxId = await executionContexts.waitForMainWorld(\n      session,\n      this.frame.frameId,\n      1000,\n    );\n\n    const results: ResolvedNode[] = [];\n    let loggedFallback = false;\n\n    for (let index = 0; index < limit; index += 1) {\n      const primaryExpr = this.buildLocatorInvocation(\"resolveCssSelector\", [\n        JSON.stringify(selector),\n        String(index),\n      ]);\n      const primary = await this.evaluateElement(\n        primaryExpr,\n        executionContextId,\n      );\n      if (primary) {\n        results.push(primary);\n        continue;\n      }\n\n      if (!loggedFallback) {\n        v3Logger({\n          category: \"locator\",\n          message: \"css pierce-fallback\",\n          level: 2,\n          auxiliary: {\n            frameId: { value: String(this.frame.frameId), type: \"string\" },\n            selector: { value: selector, type: \"string\" },\n          },\n        });\n        loggedFallback = true;\n      }\n\n      const fallbackExpr = this.buildLocatorInvocation(\n        \"resolveCssSelectorPierce\",\n        [JSON.stringify(selector), String(index)],\n      );\n      const fallback = await this.evaluateElement(fallbackExpr, ctxId);\n      if (fallback) {\n        results.push(fallback);\n        continue;\n      }\n\n      break;\n    }\n\n    return results;\n  }\n\n  private async resolveText(\n    value: string,\n    limit: number,\n  ): Promise<ResolvedNode[]> {\n    if (limit <= 0) return [];\n\n    const session = this.frame.session;\n    const ctxId = await executionContexts.waitForMainWorld(\n      session,\n      this.frame.frameId,\n      1000,\n    );\n\n    const results: ResolvedNode[] = [];\n    for (let index = 0; index < limit; index += 1) {\n      const expr = this.buildLocatorInvocation(\"resolveTextSelector\", [\n        JSON.stringify(value),\n        String(index),\n      ]);\n      const resolved = await this.evaluateElement(expr, ctxId);\n      if (!resolved) break;\n      results.push(resolved);\n    }\n\n    return results;\n  }\n\n  private async resolveXPath(\n    value: string,\n    limit: number,\n  ): Promise<ResolvedNode[]> {\n    if (limit <= 0) return [];\n\n    const session = this.frame.session;\n    const ctxId = await executionContexts.waitForMainWorld(\n      session,\n      this.frame.frameId,\n      1000,\n    );\n\n    const results: ResolvedNode[] = [];\n    for (let index = 0; index < limit; index += 1) {\n      const expr = this.buildLocatorInvocation(\"resolveXPathMainWorld\", [\n        JSON.stringify(value),\n        String(index),\n      ]);\n      const resolved = await this.evaluateElement(expr, ctxId);\n      if (!resolved) break;\n      results.push(resolved);\n    }\n\n    return results;\n  }\n\n  private async countCss(selector: string): Promise<number> {\n    const session = this.frame.session;\n\n    const { executionContextId } = await session.send<{\n      executionContextId: Protocol.Runtime.ExecutionContextId;\n    }>(\"Page.createIsolatedWorld\", {\n      frameId: this.frame.frameId,\n      worldName: \"v3-world\",\n    });\n\n    const primaryExpr = this.buildLocatorInvocation(\"countCssMatchesPrimary\", [\n      JSON.stringify(selector),\n    ]);\n    const primary = await this.evaluateCount(primaryExpr, executionContextId);\n\n    const ctxId = await executionContexts.waitForMainWorld(\n      session,\n      this.frame.frameId,\n      1000,\n    );\n\n    const fallbackExpr = this.buildLocatorInvocation(\"countCssMatchesPierce\", [\n      JSON.stringify(selector),\n    ]);\n    const fallback = await this.evaluateCount(fallbackExpr, ctxId);\n\n    return Math.max(primary, fallback);\n  }\n\n  private async countText(value: string): Promise<number> {\n    const session = this.frame.session;\n    const ctxId = await executionContexts.waitForMainWorld(\n      session,\n      this.frame.frameId,\n      1000,\n    );\n\n    const expr = this.buildLocatorInvocation(\"countTextMatches\", [\n      JSON.stringify(value),\n    ]);\n\n    try {\n      const evalRes = await session.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        {\n          expression: expr,\n          contextId: ctxId,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n      );\n\n      if (evalRes.exceptionDetails) {\n        const details = evalRes.exceptionDetails;\n        v3Logger({\n          category: \"locator\",\n          message: \"count text evaluate exception\",\n          level: 0,\n          auxiliary: {\n            frameId: { value: String(this.frame.frameId), type: \"string\" },\n            selector: { value: value, type: \"string\" },\n            exception: {\n              value:\n                details.text ??\n                String(\n                  details.exception?.description ??\n                    details.exception?.value ??\n                    \"\",\n                ),\n              type: \"string\",\n            },\n          },\n        });\n        return 0;\n      }\n\n      const data = (evalRes.result.value ?? {}) as {\n        count?: unknown;\n      };\n\n      const num =\n        typeof data.count === \"number\" ? data.count : Number(data.count);\n      if (!Number.isFinite(num)) return 0;\n      return Math.max(0, Math.floor(num));\n    } catch {\n      return 0;\n    }\n  }\n\n  private async countXPath(value: string): Promise<number> {\n    const session = this.frame.session;\n\n    const ctxId = await executionContexts.waitForMainWorld(\n      session,\n      this.frame.frameId,\n      1000,\n    );\n\n    const expr = this.buildLocatorInvocation(\"countXPathMatchesMainWorld\", [\n      JSON.stringify(value),\n    ]);\n\n    try {\n      const evalRes = await session.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        {\n          expression: expr,\n          contextId: ctxId,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n      );\n\n      if (evalRes.exceptionDetails) {\n        return 0;\n      }\n\n      const num =\n        typeof evalRes.result.value === \"number\"\n          ? evalRes.result.value\n          : Number(evalRes.result.value);\n      if (!Number.isFinite(num)) return 0;\n      return Math.max(0, Math.floor(num));\n    } catch {\n      return 0;\n    }\n  }\n\n  private async resolveFromObjectId(\n    objectId: Protocol.Runtime.RemoteObjectId,\n  ): Promise<ResolvedNode | null> {\n    const session = this.frame.session;\n    let nodeId: Protocol.DOM.NodeId | null = null;\n    try {\n      const rn = await session.send<{ nodeId: Protocol.DOM.NodeId }>(\n        \"DOM.requestNode\",\n        { objectId },\n      );\n      nodeId = rn.nodeId ?? null;\n    } catch {\n      nodeId = null;\n    }\n\n    return { objectId, nodeId };\n  }\n\n  private async evaluateCount(\n    expression: string,\n    contextId: Protocol.Runtime.ExecutionContextId,\n  ): Promise<number> {\n    const session = this.frame.session;\n\n    try {\n      const evalRes = await session.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        {\n          expression,\n          contextId,\n          returnByValue: true,\n          awaitPromise: true,\n        },\n      );\n\n      if (evalRes.exceptionDetails) {\n        return 0;\n      }\n\n      const value = evalRes.result.value;\n      const num = typeof value === \"number\" ? value : Number(value);\n      if (!Number.isFinite(num)) return 0;\n      return Math.max(0, Math.floor(num));\n    } catch {\n      return 0;\n    }\n  }\n\n  private async evaluateElement(\n    expression: string,\n    contextId: Protocol.Runtime.ExecutionContextId,\n  ): Promise<ResolvedNode | null> {\n    const session = this.frame.session;\n\n    try {\n      const evalRes = await session.send<Protocol.Runtime.EvaluateResponse>(\n        \"Runtime.evaluate\",\n        {\n          expression,\n          contextId,\n          returnByValue: false,\n          awaitPromise: true,\n        },\n      );\n\n      if (evalRes.exceptionDetails || !evalRes.result.objectId) {\n        return null;\n      }\n\n      return this.resolveFromObjectId(evalRes.result.objectId);\n    } catch {\n      return null;\n    }\n  }\n}\n"]}

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

@@ -0,0 +1,191 @@
+import { EventEmitter } from "events";
+import { z } from "zod";
+import { InferStagehandSchema, StagehandZodSchema } from "./zodCompat.js";
+import { LLMClient } from "./llm/LLMClient.js";
+import { AgentReplayStep } from "./types/private/index.js";
+import { AgentConfig, AgentExecuteOptions, AgentStreamExecuteOptions, AgentResult, LogLine, StagehandMetrics, Action, ActOptions, ActResult, defaultExtractSchema, ExtractOptions, HistoryEntry, ObserveOptions, pageTextSchema, V3FunctionName, V3Options, AgentStreamResult } from "./types/public/index.js";
+import { V3Context } from "./understudy/context.js";
+/**
+ * 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;
+    /**
+     * Event bus for internal communication.
+     * Emits events like 'screenshot' when screenshots are captured during agent execution.
+     */
+    readonly bus: EventEmitter;
+    private modelName;
+    private modelClientOptions;
+    private llmProvider;
+    private overrideLlmClients;
+    private readonly domSettleTimeoutMs?;
+    private _isClosing;
+    browserbaseSessionId?: string;
+    private browserbaseSessionUrl?;
+    private browserbaseDebugUrl?;
+    get browserbaseSessionID(): string | undefined;
+    get browserbaseSessionURL(): string | undefined;
+    get browserbaseDebugURL(): string | undefined;
+    /**
+     * Returns true if the browser is running on Browserbase.
+     */
+    get isBrowserbase(): boolean;
+    /**
+     * Returns true if advancedStealth is enabled in Browserbase settings.
+     */
+    get isAdvancedStealth(): boolean;
+    /**
+     * Returns the configured viewport dimensions from launch options.
+     * Falls back to default 1288x711 if not configured.
+     */
+    get configuredViewport(): {
+        width: number;
+        height: number;
+    };
+    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;
+    private static _instances;
+    private cacheStorage;
+    private actCache;
+    private agentCache;
+    private apiClient;
+    private keepAlive?;
+    private shutdownSupervisor;
+    stagehandMetrics: StagehandMetrics;
+    constructor(opts: V3Options);
+    /**
+     * Async property for metrics so callers can `await v3.metrics`.
+     * When using API mode, fetches metrics from the API. Otherwise returns local metrics.
+     */
+    get metrics(): Promise<StagehandMetrics>;
+    private resolveLlmClient;
+    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, reasoningTokens: number, cachedInputTokens: number, inferenceTimeMs: number): void;
+    private updateTotalMetrics;
+    private _immediateShutdown;
+    /** Spawn a crash-only supervisor that cleans up when this process dies. */
+    private startShutdownSupervisor;
+    /** Stop the supervisor during a normal shutdown. */
+    private stopShutdownSupervisor;
+    /**
+     * 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;
+    private _ensureBrowserbaseDownloadsEnabled;
+    private resetBrowserbaseSessionMetadata;
+    /**
+     * 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 StagehandZodSchema>(instruction: string, schema: T, options?: ExtractOptions): Promise<InferStagehandSchema<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;
+    /** Resolve an external page reference or fall back to the active V3 page. */
+    private resolvePage;
+    private normalizeToV3Page;
+    private _logBrowserbaseSessionStatus;
+    /**
+     * Prepares shared context for agent execution (both execute and stream).
+     * Extracts duplicated setup logic into a single helper.
+     */
+    private prepareAgentExecution;
+    /**
+     * Create a v3 agent instance (AISDK tool-based) with execute().
+     * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
+     *
+     * @overload When stream: true, returns a streaming agent where execute() returns AgentStreamResult
+     * @overload When stream is false/undefined, returns a non-streaming agent where execute() returns AgentResult
+     */
+    agent(options: AgentConfig & {
+        stream: true;
+    }): {
+        execute: (instructionOrOptions: string | AgentStreamExecuteOptions) => Promise<AgentStreamResult>;
+    };
+    agent(options?: AgentConfig & {
+        stream?: false;
+    }): {
+        execute: (instructionOrOptions: string | AgentExecuteOptions) => Promise<AgentResult>;
+    };
+}