@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-middleware.1

package/dist/cjs/lib/v3/agent/utils/actionMapping.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapToolResultToActions = mapToolResultToActions;
+/**
+ * Keys to exclude from tool outputs when mapping to actions.
+ * These are large data fields that shouldn't be included in the actions array.
+ * Users can access this data through result.messages if needed.
+ */
+const EXCLUDED_OUTPUT_KEYS = ["screenshotBase64"];
+/**
+ * Strips excluded keys (like screenshotBase64) from a tool output object.
+ */
+function stripExcludedKeys(output) {
+    const result = {};
+    for (const [key, value] of Object.entries(output)) {
+        if (!EXCLUDED_OUTPUT_KEYS.includes(key)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function mapToolResultToActions({ toolCallName, toolResult, args, reasoning, }) {
+    switch (toolCallName) {
+        case "act":
+            return mapActToolResult(toolResult, args, reasoning);
+        case "fillForm":
+            return mapFillFormToolResult(toolResult, args, reasoning);
+        default:
+            return [createStandardAction(toolCallName, toolResult, args, reasoning)];
+    }
+}
+function mapActToolResult(toolResult, args, reasoning) {
+    if (!toolResult || typeof toolResult !== "object") {
+        return [createStandardAction("act", toolResult, args, reasoning)];
+    }
+    const result = toolResult;
+    // AI SDK wraps the tool result in an output property
+    const output = result.output || result;
+    // Extract playwright arguments if they exist
+    const action = {
+        type: "act",
+        reasoning,
+        taskCompleted: false,
+        ...args,
+    };
+    if (output.playwrightArguments) {
+        action.playwrightArguments = output.playwrightArguments;
+    }
+    return [action];
+}
+function mapFillFormToolResult(toolResult, args, reasoning) {
+    if (!toolResult || typeof toolResult !== "object") {
+        return [createStandardAction("fillForm", toolResult, args, reasoning)];
+    }
+    const result = toolResult;
+    // AI SDK wraps the tool result in an output property
+    const output = result.output || result;
+    const observeResults = Array.isArray(output?.playwrightArguments)
+        ? output.playwrightArguments
+        : [];
+    const actions = [];
+    actions.push({
+        type: "fillForm",
+        reasoning,
+        taskCompleted: false,
+        ...args,
+    });
+    for (const observeResult of observeResults) {
+        actions.push({
+            type: "act",
+            reasoning: "acting from fillform tool",
+            taskCompleted: false,
+            playwrightArguments: observeResult,
+        });
+    }
+    return actions;
+}
+function createStandardAction(toolCallName, toolResult, args, reasoning) {
+    const action = {
+        type: toolCallName,
+        reasoning,
+        taskCompleted: toolCallName === "done" ? args?.taskComplete : false,
+        ...args,
+    };
+    // For screenshot tool, exclude base64 data and just indicate a screenshot was taken,
+    // if somebody really wants the base64 data, they can access it through messages
+    if (toolCallName === "screenshot") {
+        action.result = "screenshotTaken";
+        return action;
+    }
+    // Spread the output from the tool result if it exists
+    // Exclude ariaTree tool result as it is very large and unnecessary
+    if (toolCallName !== "ariaTree" && toolResult) {
+        const result = toolResult;
+        const output = result.output;
+        if (output && typeof output === "object" && !Array.isArray(output)) {
+            const cleanedOutput = stripExcludedKeys(output);
+            Object.assign(action, cleanedOutput);
+        }
+    }
+    return action;
+}
+//# sourceMappingURL=actionMapping.js.map

package/dist/cjs/lib/v3/agent/utils/actionMapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actionMapping.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/actionMapping.ts"],"names":[],"mappings":"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","sourcesContent":["import { AgentAction } from \"../../types/public/agent.js\";\nimport { ActionMappingOptions } from \"../../types/private/agent.js\";\n\n/**\n * Keys to exclude from tool outputs when mapping to actions.\n * These are large data fields that shouldn't be included in the actions array.\n * Users can access this data through result.messages if needed.\n */\nconst EXCLUDED_OUTPUT_KEYS = [\"screenshotBase64\"] as const;\n\n/**\n * Strips excluded keys (like screenshotBase64) from a tool output object.\n */\nfunction stripExcludedKeys(\n  output: Record<string, unknown>,\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(output)) {\n    if (\n      !EXCLUDED_OUTPUT_KEYS.includes(\n        key as (typeof EXCLUDED_OUTPUT_KEYS)[number],\n      )\n    ) {\n      result[key] = value;\n    }\n  }\n  return result;\n}\n\nexport function mapToolResultToActions({\n  toolCallName,\n  toolResult,\n  args,\n  reasoning,\n}: ActionMappingOptions): AgentAction[] {\n  switch (toolCallName) {\n    case \"act\":\n      return mapActToolResult(toolResult, args, reasoning);\n    case \"fillForm\":\n      return mapFillFormToolResult(toolResult, args, reasoning);\n    default:\n      return [createStandardAction(toolCallName, toolResult, args, reasoning)];\n  }\n}\n\nfunction mapActToolResult(\n  toolResult: unknown,\n  args: Record<string, unknown>,\n  reasoning?: string,\n): AgentAction[] {\n  if (!toolResult || typeof toolResult !== \"object\") {\n    return [createStandardAction(\"act\", toolResult, args, reasoning)];\n  }\n\n  const result = toolResult as Record<string, unknown>;\n\n  // AI SDK wraps the tool result in an output property\n  const output = (result.output as Record<string, unknown>) || result;\n\n  // Extract playwright arguments if they exist\n  const action: AgentAction = {\n    type: \"act\",\n    reasoning,\n    taskCompleted: false,\n    ...args,\n  };\n\n  if (output.playwrightArguments) {\n    action.playwrightArguments = output.playwrightArguments;\n  }\n\n  return [action];\n}\n\nfunction mapFillFormToolResult(\n  toolResult: unknown,\n  args: Record<string, unknown>,\n  reasoning?: string,\n): AgentAction[] {\n  if (!toolResult || typeof toolResult !== \"object\") {\n    return [createStandardAction(\"fillForm\", toolResult, args, reasoning)];\n  }\n\n  const result = toolResult as Record<string, unknown>;\n\n  // AI SDK wraps the tool result in an output property\n  const output = (result.output as Record<string, unknown>) || result;\n\n  const observeResults = Array.isArray(output?.playwrightArguments)\n    ? output.playwrightArguments\n    : [];\n\n  const actions: AgentAction[] = [];\n\n  actions.push({\n    type: \"fillForm\",\n    reasoning,\n    taskCompleted: false,\n    ...args,\n  });\n\n  for (const observeResult of observeResults) {\n    actions.push({\n      type: \"act\",\n      reasoning: \"acting from fillform tool\",\n      taskCompleted: false,\n      playwrightArguments: observeResult,\n    });\n  }\n\n  return actions;\n}\n\nfunction createStandardAction(\n  toolCallName: string,\n  toolResult: unknown,\n  args: Record<string, unknown>,\n  reasoning?: string,\n): AgentAction {\n  const action: AgentAction = {\n    type: toolCallName,\n    reasoning,\n    taskCompleted:\n      toolCallName === \"done\" ? (args?.taskComplete as boolean) : false,\n    ...args,\n  };\n\n  // For screenshot tool, exclude base64 data and just indicate a screenshot was taken,\n  // if somebody really wants the base64 data, they can access it through messages\n  if (toolCallName === \"screenshot\") {\n    action.result = \"screenshotTaken\";\n    return action;\n  }\n\n  // Spread the output from the tool result if it exists\n  // Exclude ariaTree tool result as it is very large and unnecessary\n  if (toolCallName !== \"ariaTree\" && toolResult) {\n    const result = toolResult as { output?: unknown };\n    const output = result.output;\n\n    if (output && typeof output === \"object\" && !Array.isArray(output)) {\n      const cleanedOutput = stripExcludedKeys(\n        output as Record<string, unknown>,\n      );\n      Object.assign(action, cleanedOutput);\n    }\n  }\n\n  return action;\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/captchaSolver.d.ts

@@ -0,0 +1,76 @@
+import type { Page } from "../../understudy/page.js";
+/** Injected into the agent message stream after a successful captcha solve. */
+export declare const CAPTCHA_SOLVED_MSG = "A captcha was automatically detected and solved \u2014 no further interaction with the captcha is needed, even if it does not visually appear solved. Do not click the captcha checkbox, widget, or challenge again. Continue with your task.";
+/** Injected into the agent message stream when the captcha solver fails. */
+export declare const CAPTCHA_ERRORED_MSG = "A captcha was detected but the automatic captcha solver failed to solve it. You may need to try a different approach or navigate around the captcha.";
+/** Appended to the system prompt (DOM/hybrid agents) when captchas auto-solve. */
+export declare const CAPTCHA_SYSTEM_PROMPT_NOTE = "Captchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself \u2014 they will be handled for you. Do not click the captcha checkbox, widget, or challenge again after it has been solved, even if it still looks unresolved. Continue with your task as if the captcha does not exist.";
+/** Appended to the CUA system prompt when captchas auto-solve. */
+export declare const CAPTCHA_CUA_SYSTEM_PROMPT_NOTE = "\n\nCaptchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself \u2014 they will be handled for you. Continue with your task as if the captcha does not exist.";
+/**
+ * Tracks Browserbase captcha solver state via console messages and provides
+ * a blocking `waitIfSolving()` that agents call before each step/action.
+ *
+ * Accepts a page-provider callback so the listener is automatically
+ * re-attached when the active page changes (e.g. popup / new tab).
+ *
+ * All concurrent callers of `waitIfSolving()` share the same underlying
+ * promise, so multiple waiters are safely resolved together.
+ */
+export declare class CaptchaSolver {
+    private solving;
+    private _solvedSinceLastConsume;
+    private _erroredSinceLastConsume;
+    private listener;
+    private attachedPage;
+    private pageProvider;
+    /** Shared promise that all concurrent waitIfSolving() callers await. */
+    private waitPromise;
+    /** Resolves the shared waitPromise. */
+    private resolveWait;
+    /** Timeout handle for the 90s deadline. */
+    private waitTimer;
+    /**
+     * Initialise with a callback that returns the current active page.
+     * The listener is lazily (re-)attached whenever the active page changes.
+     */
+    init(pageProvider: () => Promise<Page>): void;
+    /** Whether a captcha solve is currently in progress. */
+    isSolving(): boolean;
+    /**
+     * Ensure the console listener is attached to the current active page.
+     * If the active page has changed since the last call, the old listener
+     * is removed and a new one is installed.
+     */
+    ensureAttached(): Promise<void>;
+    /**
+     * Returns a promise that resolves immediately if no captcha is being
+     * solved, or blocks until the solver finishes, errors, or the 90s
+     * timeout is reached.
+     *
+     * Also re-attaches the listener to the current active page if it has
+     * changed since the last call.
+     *
+     * All concurrent callers share the same promise, so no waiter is
+     * orphaned.
+     */
+    waitIfSolving(): Promise<void>;
+    /**
+     * Returns and resets the solve event flags.
+     * Call after `waitIfSolving()` to check whether a captcha was solved
+     * (or errored) since the last consume.  This captures events even if
+     * the solve completed between two `waitIfSolving()` calls.
+     */
+    consumeSolveResult(): {
+        solved: boolean;
+        errored: boolean;
+    };
+    /**
+     * Remove the console listener and reset all state.
+     */
+    dispose(): void;
+    /** Remove the console listener from the currently attached page. */
+    private detachListener;
+    /** Resolve the shared wait promise and clear the timeout. */
+    private settle;
+}

package/dist/cjs/lib/v3/agent/utils/captchaSolver.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CaptchaSolver = exports.CAPTCHA_CUA_SYSTEM_PROMPT_NOTE = exports.CAPTCHA_SYSTEM_PROMPT_NOTE = exports.CAPTCHA_ERRORED_MSG = exports.CAPTCHA_SOLVED_MSG = void 0;
+const SOLVING_STARTED = "browserbase-solving-started";
+const SOLVING_FINISHED = "browserbase-solving-finished";
+const SOLVING_ERRORED = "browserbase-solving-errored";
+/** Maximum time (ms) to wait for the captcha solver before giving up. */
+const SOLVE_TIMEOUT_MS = 90_000;
+// ---------------------------------------------------------------------------
+// Shared captcha notification strings
+// ---------------------------------------------------------------------------
+/** Injected into the agent message stream after a successful captcha solve. */
+exports.CAPTCHA_SOLVED_MSG = "A captcha was automatically detected and solved — no further interaction with the captcha is needed, even if it does not visually appear solved. Do not click the captcha checkbox, widget, or challenge again. Continue with your task.";
+/** Injected into the agent message stream when the captcha solver fails. */
+exports.CAPTCHA_ERRORED_MSG = "A captcha was detected but the automatic captcha solver failed to solve it. You may need to try a different approach or navigate around the captcha.";
+/** Appended to the system prompt (DOM/hybrid agents) when captchas auto-solve. */
+exports.CAPTCHA_SYSTEM_PROMPT_NOTE = "Captchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Do not click the captcha checkbox, widget, or challenge again after it has been solved, even if it still looks unresolved. Continue with your task as if the captcha does not exist.";
+/** Appended to the CUA system prompt when captchas auto-solve. */
+exports.CAPTCHA_CUA_SYSTEM_PROMPT_NOTE = "\n\nCaptchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Continue with your task as if the captcha does not exist.";
+/**
+ * Tracks Browserbase captcha solver state via console messages and provides
+ * a blocking `waitIfSolving()` that agents call before each step/action.
+ *
+ * Accepts a page-provider callback so the listener is automatically
+ * re-attached when the active page changes (e.g. popup / new tab).
+ *
+ * All concurrent callers of `waitIfSolving()` share the same underlying
+ * promise, so multiple waiters are safely resolved together.
+ */
+class CaptchaSolver {
+    solving = false;
+    _solvedSinceLastConsume = false;
+    _erroredSinceLastConsume = false;
+    listener = null;
+    attachedPage = null;
+    pageProvider = null;
+    /** Shared promise that all concurrent waitIfSolving() callers await. */
+    waitPromise = null;
+    /** Resolves the shared waitPromise. */
+    resolveWait = null;
+    /** Timeout handle for the 90s deadline. */
+    waitTimer = null;
+    /**
+     * Initialise with a callback that returns the current active page.
+     * The listener is lazily (re-)attached whenever the active page changes.
+     */
+    init(pageProvider) {
+        this.pageProvider = pageProvider;
+    }
+    /** Whether a captcha solve is currently in progress. */
+    isSolving() {
+        return this.solving;
+    }
+    /**
+     * Ensure the console listener is attached to the current active page.
+     * If the active page has changed since the last call, the old listener
+     * is removed and a new one is installed.
+     */
+    async ensureAttached() {
+        if (!this.pageProvider)
+            return;
+        const page = await this.pageProvider();
+        if (page === this.attachedPage)
+            return;
+        // Detach from the old page
+        this.detachListener();
+        this.attachedPage = page;
+        this.listener = (msg) => {
+            const text = msg.text();
+            if (text === SOLVING_STARTED) {
+                this.solving = true;
+            }
+            else if (text === SOLVING_FINISHED) {
+                this.solving = false;
+                this._solvedSinceLastConsume = true;
+                this.settle();
+            }
+            else if (text === SOLVING_ERRORED) {
+                this.solving = false;
+                this._erroredSinceLastConsume = true;
+                this.settle();
+            }
+        };
+        page.on("console", this.listener);
+    }
+    /**
+     * Returns a promise that resolves immediately if no captcha is being
+     * solved, or blocks until the solver finishes, errors, or the 90s
+     * timeout is reached.
+     *
+     * Also re-attaches the listener to the current active page if it has
+     * changed since the last call.
+     *
+     * All concurrent callers share the same promise, so no waiter is
+     * orphaned.
+     */
+    async waitIfSolving() {
+        await this.ensureAttached();
+        if (!this.solving)
+            return;
+        // Return the existing shared promise if one is already pending
+        if (this.waitPromise)
+            return this.waitPromise;
+        this.waitPromise = new Promise((resolve) => {
+            this.resolveWait = resolve;
+            this.waitTimer = setTimeout(() => {
+                this.solving = false;
+                this._erroredSinceLastConsume = true;
+                this.settle();
+            }, SOLVE_TIMEOUT_MS);
+        });
+        return this.waitPromise;
+    }
+    /**
+     * Returns and resets the solve event flags.
+     * Call after `waitIfSolving()` to check whether a captcha was solved
+     * (or errored) since the last consume.  This captures events even if
+     * the solve completed between two `waitIfSolving()` calls.
+     */
+    consumeSolveResult() {
+        const result = {
+            solved: this._solvedSinceLastConsume,
+            errored: this._erroredSinceLastConsume,
+        };
+        this._solvedSinceLastConsume = false;
+        this._erroredSinceLastConsume = false;
+        return result;
+    }
+    /**
+     * Remove the console listener and reset all state.
+     */
+    dispose() {
+        this.detachListener();
+        this.attachedPage = null;
+        this.pageProvider = null;
+        this.solving = false;
+        this._solvedSinceLastConsume = false;
+        this._erroredSinceLastConsume = false;
+        this.settle();
+    }
+    // ------------------------------------------------------------------
+    // Internal helpers
+    // ------------------------------------------------------------------
+    /** Remove the console listener from the currently attached page. */
+    detachListener() {
+        if (this.attachedPage && this.listener) {
+            this.attachedPage.off("console", this.listener);
+        }
+        this.listener = null;
+        // If a solve was in progress, mark it as errored so consumers
+        // know it was interrupted (consistent with the timeout path).
+        if (this.solving) {
+            this._erroredSinceLastConsume = true;
+        }
+        // Reset solving state so waiters aren't stuck waiting for events
+        // that can never arrive from the detached page.
+        this.solving = false;
+        this.settle();
+    }
+    /** Resolve the shared wait promise and clear the timeout. */
+    settle() {
+        if (this.waitTimer) {
+            clearTimeout(this.waitTimer);
+            this.waitTimer = null;
+        }
+        if (this.resolveWait) {
+            const resolve = this.resolveWait;
+            this.resolveWait = null;
+            this.waitPromise = null;
+            resolve();
+        }
+    }
+}
+exports.CaptchaSolver = CaptchaSolver;
+//# sourceMappingURL=captchaSolver.js.map

package/dist/cjs/lib/v3/agent/utils/captchaSolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captchaSolver.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/captchaSolver.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from \"../../understudy/page.js\";\nimport type { ConsoleMessage } from \"../../understudy/consoleMessage.js\";\n\nconst SOLVING_STARTED = \"browserbase-solving-started\";\nconst SOLVING_FINISHED = \"browserbase-solving-finished\";\nconst SOLVING_ERRORED = \"browserbase-solving-errored\";\n\n/** Maximum time (ms) to wait for the captcha solver before giving up. */\nconst SOLVE_TIMEOUT_MS = 90_000;\n\n// ---------------------------------------------------------------------------\n// Shared captcha notification strings\n// ---------------------------------------------------------------------------\n\n/** Injected into the agent message stream after a successful captcha solve. */\nexport const CAPTCHA_SOLVED_MSG =\n  \"A captcha was automatically detected and solved — no further interaction with the captcha is needed, even if it does not visually appear solved. Do not click the captcha checkbox, widget, or challenge again. Continue with your task.\";\n\n/** Injected into the agent message stream when the captcha solver fails. */\nexport const CAPTCHA_ERRORED_MSG =\n  \"A captcha was detected but the automatic captcha solver failed to solve it. You may need to try a different approach or navigate around the captcha.\";\n\n/** Appended to the system prompt (DOM/hybrid agents) when captchas auto-solve. */\nexport const CAPTCHA_SYSTEM_PROMPT_NOTE =\n  \"Captchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Do not click the captcha checkbox, widget, or challenge again after it has been solved, even if it still looks unresolved. Continue with your task as if the captcha does not exist.\";\n\n/** Appended to the CUA system prompt when captchas auto-solve. */\nexport const CAPTCHA_CUA_SYSTEM_PROMPT_NOTE =\n  \"\\n\\nCaptchas on this page are automatically detected and solved by the browser environment. Do not interact with or attempt to solve any captchas yourself — they will be handled for you. Continue with your task as if the captcha does not exist.\";\n\n/**\n * Tracks Browserbase captcha solver state via console messages and provides\n * a blocking `waitIfSolving()` that agents call before each step/action.\n *\n * Accepts a page-provider callback so the listener is automatically\n * re-attached when the active page changes (e.g. popup / new tab).\n *\n * All concurrent callers of `waitIfSolving()` share the same underlying\n * promise, so multiple waiters are safely resolved together.\n */\nexport class CaptchaSolver {\n  private solving = false;\n  private _solvedSinceLastConsume = false;\n  private _erroredSinceLastConsume = false;\n  private listener: ((msg: ConsoleMessage) => void) | null = null;\n  private attachedPage: Page | null = null;\n  private pageProvider: (() => Promise<Page>) | null = null;\n\n  /** Shared promise that all concurrent waitIfSolving() callers await. */\n  private waitPromise: Promise<void> | null = null;\n  /** Resolves the shared waitPromise. */\n  private resolveWait: (() => void) | null = null;\n  /** Timeout handle for the 90s deadline. */\n  private waitTimer: ReturnType<typeof setTimeout> | null = null;\n\n  /**\n   * Initialise with a callback that returns the current active page.\n   * The listener is lazily (re-)attached whenever the active page changes.\n   */\n  init(pageProvider: () => Promise<Page>): void {\n    this.pageProvider = pageProvider;\n  }\n\n  /** Whether a captcha solve is currently in progress. */\n  isSolving(): boolean {\n    return this.solving;\n  }\n\n  /**\n   * Ensure the console listener is attached to the current active page.\n   * If the active page has changed since the last call, the old listener\n   * is removed and a new one is installed.\n   */\n  async ensureAttached(): Promise<void> {\n    if (!this.pageProvider) return;\n    const page = await this.pageProvider();\n    if (page === this.attachedPage) return;\n\n    // Detach from the old page\n    this.detachListener();\n\n    this.attachedPage = page;\n    this.listener = (msg: ConsoleMessage) => {\n      const text = msg.text();\n      if (text === SOLVING_STARTED) {\n        this.solving = true;\n      } else if (text === SOLVING_FINISHED) {\n        this.solving = false;\n        this._solvedSinceLastConsume = true;\n        this.settle();\n      } else if (text === SOLVING_ERRORED) {\n        this.solving = false;\n        this._erroredSinceLastConsume = true;\n        this.settle();\n      }\n    };\n    page.on(\"console\", this.listener);\n  }\n\n  /**\n   * Returns a promise that resolves immediately if no captcha is being\n   * solved, or blocks until the solver finishes, errors, or the 90s\n   * timeout is reached.\n   *\n   * Also re-attaches the listener to the current active page if it has\n   * changed since the last call.\n   *\n   * All concurrent callers share the same promise, so no waiter is\n   * orphaned.\n   */\n  async waitIfSolving(): Promise<void> {\n    await this.ensureAttached();\n\n    if (!this.solving) return;\n\n    // Return the existing shared promise if one is already pending\n    if (this.waitPromise) return this.waitPromise;\n\n    this.waitPromise = new Promise<void>((resolve) => {\n      this.resolveWait = resolve;\n      this.waitTimer = setTimeout(() => {\n        this.solving = false;\n        this._erroredSinceLastConsume = true;\n        this.settle();\n      }, SOLVE_TIMEOUT_MS);\n    });\n\n    return this.waitPromise;\n  }\n\n  /**\n   * Returns and resets the solve event flags.\n   * Call after `waitIfSolving()` to check whether a captcha was solved\n   * (or errored) since the last consume.  This captures events even if\n   * the solve completed between two `waitIfSolving()` calls.\n   */\n  consumeSolveResult(): { solved: boolean; errored: boolean } {\n    const result = {\n      solved: this._solvedSinceLastConsume,\n      errored: this._erroredSinceLastConsume,\n    };\n    this._solvedSinceLastConsume = false;\n    this._erroredSinceLastConsume = false;\n    return result;\n  }\n\n  /**\n   * Remove the console listener and reset all state.\n   */\n  dispose(): void {\n    this.detachListener();\n    this.attachedPage = null;\n    this.pageProvider = null;\n    this.solving = false;\n    this._solvedSinceLastConsume = false;\n    this._erroredSinceLastConsume = false;\n    this.settle();\n  }\n\n  // ------------------------------------------------------------------\n  // Internal helpers\n  // ------------------------------------------------------------------\n\n  /** Remove the console listener from the currently attached page. */\n  private detachListener(): void {\n    if (this.attachedPage && this.listener) {\n      this.attachedPage.off(\"console\", this.listener);\n    }\n    this.listener = null;\n    // If a solve was in progress, mark it as errored so consumers\n    // know it was interrupted (consistent with the timeout path).\n    if (this.solving) {\n      this._erroredSinceLastConsume = true;\n    }\n    // Reset solving state so waiters aren't stuck waiting for events\n    // that can never arrive from the detached page.\n    this.solving = false;\n    this.settle();\n  }\n\n  /** Resolve the shared wait promise and clear the timeout. */\n  private settle(): void {\n    if (this.waitTimer) {\n      clearTimeout(this.waitTimer);\n      this.waitTimer = null;\n    }\n    if (this.resolveWait) {\n      const resolve = this.resolveWait;\n      this.resolveWait = null;\n      this.waitPromise = null;\n      resolve();\n    }\n  }\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/coordinateNormalization.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGoogleProvider = isGoogleProvider;
+exports.normalizeGoogleCoordinates = normalizeGoogleCoordinates;
+exports.processCoordinates = processCoordinates;
+// Default viewport for advancedStealth mode
+const STEALTH_VIEWPORT = { width: 1288, height: 711 };
+function isGoogleProvider(provider) {
+    if (!provider)
+        return false;
+    return provider.toLowerCase().includes("google");
+}
+// Google returns coordinates in a 0-1000 range, we need to normalize
+// them to the viewport dimensions
+function normalizeGoogleCoordinates(x, y, viewport) {
+    const clampedX = Math.min(999, Math.max(0, x));
+    const clampedY = Math.min(999, Math.max(0, y));
+    return {
+        x: Math.floor((clampedX / 1000) * viewport.width),
+        y: Math.floor((clampedY / 1000) * viewport.height),
+    };
+}
+function processCoordinates(x, y, provider, v3) {
+    if (isGoogleProvider(provider) && v3) {
+        // advancedStealth uses fixed viewport, otherwise use configured viewport
+        const viewport = v3.isAdvancedStealth
+            ? STEALTH_VIEWPORT
+            : v3.configuredViewport;
+        return normalizeGoogleCoordinates(x, y, viewport);
+    }
+    return { x, y };
+}
+//# sourceMappingURL=coordinateNormalization.js.map

package/dist/cjs/lib/v3/agent/utils/coordinateNormalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinateNormalization.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/coordinateNormalization.ts"],"names":[],"mappings":";;AAKA,4CAGC;AAID,gEAWC;AAED,gDAcC;AArCD,4CAA4C;AAC5C,MAAM,gBAAgB,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAEtD,SAAgB,gBAAgB,CAAC,QAAiB;IAChD,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACnD,CAAC;AAED,qEAAqE;AACrE,kCAAkC;AAClC,SAAgB,0BAA0B,CACxC,CAAS,EACT,CAAS,EACT,QAA2C;IAE3C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/C,OAAO;QACL,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC;QACjD,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,SAAgB,kBAAkB,CAChC,CAAS,EACT,CAAS,EACT,QAAiB,EACjB,EAAO;IAEP,IAAI,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QACrC,yEAAyE;QACzE,MAAM,QAAQ,GAAG,EAAE,CAAC,iBAAiB;YACnC,CAAC,CAAC,gBAAgB;YAClB,CAAC,CAAC,EAAE,CAAC,kBAAkB,CAAC;QAC1B,OAAO,0BAA0B,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAClB,CAAC","sourcesContent":["import type { V3 } from \"../../v3.js\";\n\n// Default viewport for advancedStealth mode\nconst STEALTH_VIEWPORT = { width: 1288, height: 711 };\n\nexport function isGoogleProvider(provider?: string): boolean {\n  if (!provider) return false;\n  return provider.toLowerCase().includes(\"google\");\n}\n\n// Google returns coordinates in a 0-1000 range, we need to normalize\n// them to the viewport dimensions\nexport function normalizeGoogleCoordinates(\n  x: number,\n  y: number,\n  viewport: { width: number; height: number },\n): { x: number; y: number } {\n  const clampedX = Math.min(999, Math.max(0, x));\n  const clampedY = Math.min(999, Math.max(0, y));\n  return {\n    x: Math.floor((clampedX / 1000) * viewport.width),\n    y: Math.floor((clampedY / 1000) * viewport.height),\n  };\n}\n\nexport function processCoordinates(\n  x: number,\n  y: number,\n  provider?: string,\n  v3?: V3,\n): { x: number; y: number } {\n  if (isGoogleProvider(provider) && v3) {\n    // advancedStealth uses fixed viewport, otherwise use configured viewport\n    const viewport = v3.isAdvancedStealth\n      ? STEALTH_VIEWPORT\n      : v3.configuredViewport;\n    return normalizeGoogleCoordinates(x, y, viewport);\n  }\n  return { x, y };\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/cuaKeyMapping.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Universal key mapping utility for converting various key representations
+ * to Playwright-compatible key names. Used by all CUA clients and handlers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapKeyToPlaywright = mapKeyToPlaywright;
+/**
+ * map of key variations to Playwright key names
+ * This handles keys from both Anthropic and OpenAI CUA APIs
+ */
+const KEY_MAP = {
+    ENTER: "Enter",
+    RETURN: "Enter",
+    ESCAPE: "Escape",
+    ESC: "Escape",
+    BACKSPACE: "Backspace",
+    TAB: "Tab",
+    SPACE: " ",
+    DELETE: "Delete",
+    DEL: "Delete",
+    ARROWUP: "ArrowUp",
+    ARROWDOWN: "ArrowDown",
+    ARROWLEFT: "ArrowLeft",
+    ARROWRIGHT: "ArrowRight",
+    ARROW_UP: "ArrowUp",
+    ARROW_DOWN: "ArrowDown",
+    ARROW_LEFT: "ArrowLeft",
+    ARROW_RIGHT: "ArrowRight",
+    UP: "ArrowUp",
+    DOWN: "ArrowDown",
+    LEFT: "ArrowLeft",
+    RIGHT: "ArrowRight",
+    SHIFT: "Shift",
+    CONTROL: "Control",
+    CTRL: "Control",
+    ALT: "Alt",
+    OPTION: "Alt", // macOS alternative name
+    META: "Meta",
+    COMMAND: "Meta", // macOS
+    CMD: "Meta", // macOS shorthand
+    SUPER: "Meta", // Linux
+    WINDOWS: "Meta", // Windows
+    WIN: "Meta", // Windows shorthand
+    HOME: "Home",
+    END: "End",
+    PAGEUP: "PageUp",
+    PAGEDOWN: "PageDown",
+    PAGE_UP: "PageUp",
+    PAGE_DOWN: "PageDown",
+    PGUP: "PageUp",
+    PGDN: "PageDown",
+};
+/**
+ * Maps a key name from various formats to Playwright-compatible format
+ * @param key The key name in any supported format
+ * @returns The Playwright-compatible key name
+ */
+function mapKeyToPlaywright(key) {
+    if (!key)
+        return key;
+    const upperKey = key.toUpperCase();
+    return KEY_MAP[upperKey] || key;
+}
+//# sourceMappingURL=cuaKeyMapping.js.map

package/dist/cjs/lib/v3/agent/utils/cuaKeyMapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cuaKeyMapping.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/cuaKeyMapping.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAsDH,gDAIC;AAxDD;;;GAGG;AACH,MAAM,OAAO,GAA2B;IACtC,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,QAAQ;IACb,SAAS,EAAE,WAAW;IACtB,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,QAAQ;IAChB,GAAG,EAAE,QAAQ;IACb,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,SAAS,EAAE,WAAW;IACtB,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,SAAS;IACnB,UAAU,EAAE,WAAW;IACvB,UAAU,EAAE,WAAW;IACvB,WAAW,EAAE,YAAY;IACzB,EAAE,EAAE,SAAS;IACb,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,YAAY;IACnB,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,KAAK,EAAE,yBAAyB;IACxC,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,MAAM,EAAE,QAAQ;IACzB,GAAG,EAAE,MAAM,EAAE,kBAAkB;IAC/B,KAAK,EAAE,MAAM,EAAE,QAAQ;IACvB,OAAO,EAAE,MAAM,EAAE,UAAU;IAC3B,GAAG,EAAE,MAAM,EAAE,oBAAoB;IACjC,IAAI,EAAE,MAAM;IACZ,GAAG,EAAE,KAAK;IACV,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,OAAO,EAAE,QAAQ;IACjB,SAAS,EAAE,UAAU;IACrB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,UAAU;CACjB,CAAC;AAEF;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,IAAI,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC;IACrB,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,OAAO,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC;AAClC,CAAC","sourcesContent":["/**\n * Universal key mapping utility for converting various key representations\n * to Playwright-compatible key names. Used by all CUA clients and handlers.\n */\n\n/**\n * map of key variations to Playwright key names\n * This handles keys from both Anthropic and OpenAI CUA APIs\n */\nconst KEY_MAP: Record<string, string> = {\n  ENTER: \"Enter\",\n  RETURN: \"Enter\",\n  ESCAPE: \"Escape\",\n  ESC: \"Escape\",\n  BACKSPACE: \"Backspace\",\n  TAB: \"Tab\",\n  SPACE: \" \",\n  DELETE: \"Delete\",\n  DEL: \"Delete\",\n  ARROWUP: \"ArrowUp\",\n  ARROWDOWN: \"ArrowDown\",\n  ARROWLEFT: \"ArrowLeft\",\n  ARROWRIGHT: \"ArrowRight\",\n  ARROW_UP: \"ArrowUp\",\n  ARROW_DOWN: \"ArrowDown\",\n  ARROW_LEFT: \"ArrowLeft\",\n  ARROW_RIGHT: \"ArrowRight\",\n  UP: \"ArrowUp\",\n  DOWN: \"ArrowDown\",\n  LEFT: \"ArrowLeft\",\n  RIGHT: \"ArrowRight\",\n  SHIFT: \"Shift\",\n  CONTROL: \"Control\",\n  CTRL: \"Control\",\n  ALT: \"Alt\",\n  OPTION: \"Alt\", // macOS alternative name\n  META: \"Meta\",\n  COMMAND: \"Meta\", // macOS\n  CMD: \"Meta\", // macOS shorthand\n  SUPER: \"Meta\", // Linux\n  WINDOWS: \"Meta\", // Windows\n  WIN: \"Meta\", // Windows shorthand\n  HOME: \"Home\",\n  END: \"End\",\n  PAGEUP: \"PageUp\",\n  PAGEDOWN: \"PageDown\",\n  PAGE_UP: \"PageUp\",\n  PAGE_DOWN: \"PageDown\",\n  PGUP: \"PageUp\",\n  PGDN: \"PageDown\",\n};\n\n/**\n * Maps a key name from various formats to Playwright-compatible format\n * @param key The key name in any supported format\n * @returns The Playwright-compatible key name\n */\nexport function mapKeyToPlaywright(key: string): string {\n  if (!key) return key;\n  const upperKey = key.toUpperCase();\n  return KEY_MAP[upperKey] || key;\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/googleCustomToolHandler.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeGoogleCustomTool = executeGoogleCustomTool;
+exports.isCustomTool = isCustomTool;
+exports.convertToolSetToFunctionDeclarations = convertToolSetToFunctionDeclarations;
+const genai_1 = require("@google/genai");
+const zodCompat_js_1 = require("../../zodCompat.js");
+/**
+ * Execute a custom tool and format the response for Google's API
+ * This handles tool execution, result formatting, and error handling
+ * specific to Google's function response format
+ */
+async function executeGoogleCustomTool(toolName, toolArgs, tools, functionCall, logger) {
+    try {
+        logger({
+            category: "agent",
+            message: `Executing custom tool: ${toolName} with args: ${JSON.stringify(toolArgs)}`,
+            level: 1,
+        });
+        const tool = tools[toolName];
+        const toolResult = await tool.execute(toolArgs, {
+            toolCallId: `tool_${Date.now()}`,
+            messages: [],
+        });
+        logger({
+            category: "agent",
+            message: `Tool ${toolName} completed successfully. Result: ${JSON.stringify(toolResult)}`,
+            level: 1,
+        });
+        // Create function response with the result
+        const functionResponsePart = {
+            functionResponse: {
+                name: toolName,
+                response: {
+                    result: JSON.stringify(toolResult),
+                },
+            },
+        };
+        return {
+            functionResponse: functionResponsePart,
+            success: true,
+        };
+    }
+    catch (toolError) {
+        const errorMessage = toolError instanceof Error ? toolError.message : String(toolError);
+        logger({
+            category: "agent",
+            message: `Error executing custom tool ${toolName}: ${errorMessage}`,
+            level: 0,
+        });
+        // Create error function response
+        const functionResponsePart = {
+            functionResponse: {
+                name: toolName,
+                response: {
+                    error: errorMessage,
+                },
+            },
+        };
+        return {
+            functionResponse: functionResponsePart,
+            success: false,
+        };
+    }
+}
+/**
+ * Check if a function call is a custom tool
+ */
+function isCustomTool(functionCall, tools) {
+    return !!(tools && functionCall.name && functionCall.name in tools);
+}
+/**
+ * Convert ToolSet to Google's FunctionDeclaration array
+ * Handles the conversion of Zod schemas to Google's parameter format
+ */
+function convertToolSetToFunctionDeclarations(tools) {
+    const functionDeclarations = [];
+    for (const [name, tool] of Object.entries(tools)) {
+        const functionDeclaration = convertToolToFunctionDeclaration(name, tool);
+        if (functionDeclaration) {
+            functionDeclarations.push(functionDeclaration);
+        }
+    }
+    return functionDeclarations;
+}
+/**
+ * Convert a single ToolSet tool to Google's FunctionDeclaration format
+ */
+function convertToolToFunctionDeclaration(name, tool) {
+    try {
+        // Convert Zod schema to JSON schema
+        const schema = tool.inputSchema;
+        const jsonSchema = (0, zodCompat_js_1.toJsonSchema)(schema);
+        const parameters = convertJsonSchemaToGoogleParameters(jsonSchema);
+        return {
+            name,
+            description: tool.description || `Execute ${name}`,
+            parameters,
+        };
+    }
+    catch (error) {
+        console.error(`Error converting tool ${name} to function declaration:`, error);
+        return null;
+    }
+}
+/**
+ * Convert JSON schema to Google's parameter format
+ */
+function convertJsonSchemaToGoogleParameters(schema) {
+    const properties = {};
+    if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+            const propSchema = value;
+            properties[key] = {
+                type: mapJsonTypeToGoogleType(propSchema.type || "string"),
+                ...(propSchema.description
+                    ? { description: propSchema.description }
+                    : {}),
+            };
+        }
+    }
+    return {
+        type: genai_1.Type.OBJECT,
+        properties,
+        ...(schema.required && schema.required.length > 0
+            ? { required: schema.required }
+            : {}),
+    };
+}
+/**
+ * Map JSON schema types to Google's Type enum
+ */
+function mapJsonTypeToGoogleType(jsonType) {
+    switch (jsonType.toLowerCase()) {
+        case "string":
+            return genai_1.Type.STRING;
+        case "number":
+        case "integer":
+            return genai_1.Type.NUMBER;
+        case "boolean":
+            return genai_1.Type.BOOLEAN;
+        case "array":
+            return genai_1.Type.ARRAY;
+        case "object":
+            return genai_1.Type.OBJECT;
+        default:
+            return genai_1.Type.STRING;
+    }
+}
+//# sourceMappingURL=googleCustomToolHandler.js.map