wait for captcha solve after navigation (#504)

* add waitforcaptcha method

* add waitForCaptcha method

* add env warning

* dont expose wait function & parameterize

* handle captchas on `act()` navigation

* changeset

Author: sameelarif

Diff for: .changeset/polite-rivers-sip.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Enabled support for Browserbase captcha solving after page navigations. This can be enabled with the new constructor parameter: `waitForCaptchaSolves`.

Diff for: lib/StagehandPage.ts

@@ -40,6 +40,7 @@ export class StagehandPage {
   private cdpClient: CDPSession | null = null;
   private api: StagehandAPI;
   private userProvidedInstructions?: string;
+  private waitForCaptchaSolves: boolean;
 
   constructor(
     page: PlaywrightPage,
@@ -48,6 +49,7 @@ export class StagehandPage {
     llmClient: LLMClient,
     userProvidedInstructions?: string,
     api?: StagehandAPI,
+    waitForCaptchaSolves?: boolean,
   ) {
     this.intPage = Object.assign(page, {
       act: () => {
@@ -71,11 +73,14 @@ export class StagehandPage {
         );
       },
     });
+
     this.stagehand = stagehand;
     this.intContext = context;
     this.llmClient = llmClient;
     this.api = api;
     this.userProvidedInstructions = userProvidedInstructions;
+    this.waitForCaptchaSolves = waitForCaptchaSolves ?? false;
+
     if (this.llmClient) {
       this.actHandler = new StagehandActHandler({
         verbose: this.stagehand.verbose,
@@ -87,6 +92,7 @@ export class StagehandPage {
         llmClient: llmClient,
         userProvidedInstructions,
         selfHeal: this.stagehand.selfHeal,
+        waitForCaptchaSolves: this.waitForCaptchaSolves,
       });
       this.extractHandler = new StagehandExtractHandler({
         stagehand: this.stagehand,
@@ -146,17 +152,79 @@ export class StagehandPage {
     await this._waitForSettledDom();
   }
 
+  /**
+   * Waits for a captcha to be solved when using Browserbase environment.
+   *
+   * @param timeoutMs - Optional timeout in milliseconds. If provided, the promise will reject if the captcha solving hasn't started within the given time.
+   * @throws Error if called in a LOCAL environment
+   * @throws Error if the timeout is reached before captcha solving starts
+   * @returns Promise that resolves when the captcha is solved
+   */
+  public async waitForCaptchaSolve(timeoutMs?: number) {
+    if (this.stagehand.env === "LOCAL") {
+      throw new Error(
+        "The waitForCaptcha method may only be used when using the Browserbase environment.",
+      );
+    }
+
+    this.stagehand.log({
+      category: "captcha",
+      message: "Waiting for captcha",
+      level: 1,
+    });
+
+    return new Promise<void>((resolve, reject) => {
+      let started = false;
+      let timeoutId: NodeJS.Timeout;
+
+      if (timeoutMs) {
+        timeoutId = setTimeout(() => {
+          if (!started) {
+            reject(new Error("Captcha timeout"));
+          }
+        }, timeoutMs);
+      }
+
+      this.intPage.on("console", (msg) => {
+        if (msg.text() === "browserbase-solving-finished") {
+          this.stagehand.log({
+            category: "captcha",
+            message: "Captcha solving finished",
+            level: 1,
+          });
+          if (timeoutId) clearTimeout(timeoutId);
+          resolve();
+        } else if (msg.text() === "browserbase-solving-started") {
+          started = true;
+          this.stagehand.log({
+            category: "captcha",
+            message: "Captcha solving started",
+            level: 1,
+          });
+        }
+      });
+    });
+  }
+
   async init(): Promise<StagehandPage> {
     const page = this.intPage;
     const stagehand = this.stagehand;
     this.intPage = new Proxy(page, {
       get: (target, prop) => {
-        if (prop === "goto")
+        if (prop === "goto") {
           return async (url: string, options: GotoOptions) => {
             const result = this.api
               ? await this.api.goto(url, options)
               : await page.goto(url, options);
 
+            if (this.waitForCaptchaSolves) {
+              try {
+                await this.waitForCaptchaSolve(1000);
+              } catch {
+                // ignore
+              }
+            }
+
             if (this.api) {
               await this._refreshPageFromAPI();
             } else {
@@ -171,8 +239,7 @@ export class StagehandPage {
             }
             return result;
           };
-
-        if (this.llmClient) {
+        } else if (this.llmClient) {
           if (prop === "act") {
             return async (options: ActOptions) => {
               return this.act(options);

Diff for: lib/handlers/actHandler.ts

@@ -30,6 +30,7 @@ export class StagehandActHandler {
   };
   private readonly userProvidedInstructions?: string;
   private readonly selfHeal: boolean;
+  private readonly waitForCaptchaSolves: boolean;
 
   constructor({
     verbose,
@@ -39,6 +40,7 @@ export class StagehandActHandler {
     stagehandPage,
     userProvidedInstructions,
     selfHeal,
+    waitForCaptchaSolves,
   }: {
     verbose: 0 | 1 | 2;
     llmProvider: LLMProvider;
@@ -49,6 +51,7 @@ export class StagehandActHandler {
     stagehandContext: StagehandContext;
     userProvidedInstructions?: string;
     selfHeal: boolean;
+    waitForCaptchaSolves: boolean;
   }) {
     this.verbose = verbose;
     this.llmProvider = llmProvider;
@@ -59,6 +62,7 @@ export class StagehandActHandler {
     this.stagehandPage = stagehandPage;
     this.userProvidedInstructions = userProvidedInstructions;
     this.selfHeal = selfHeal;
+    this.waitForCaptchaSolves = waitForCaptchaSolves;
   }
 
   /**
@@ -1379,6 +1383,14 @@ export class StagehandActHandler {
 
         if (this.stagehandPage.page.url() !== initialUrl) {
           steps += `  Result (Important): Page URL changed from ${initialUrl} to ${this.stagehandPage.page.url()}\n\n`;
+
+          if (this.waitForCaptchaSolves) {
+            try {
+              await this.stagehandPage.waitForCaptchaSolve(1000);
+            } catch {
+              // ignore
+            }
+          }
         }
 
         const actionCompleted = await this._verifyActionCompletion({

Diff for: lib/index.ts

@@ -373,6 +373,7 @@ export class Stagehand {
   private usingAPI: boolean;
   private modelName: AvailableModel;
   private apiClient: StagehandAPI | undefined;
+  private waitForCaptchaSolves: boolean;
   private localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
   public readonly selfHeal: boolean;
 
@@ -397,6 +398,7 @@ export class Stagehand {
       useAPI,
       localBrowserLaunchOptions,
       selfHeal = true,
+      waitForCaptchaSolves = false,
     }: ConstructorParams = {
       env: "BROWSERBASE",
     },
@@ -442,6 +444,8 @@ export class Stagehand {
       );
     }
 
+    this.waitForCaptchaSolves = waitForCaptchaSolves;
+
     this.selfHeal = selfHeal;
     this.localBrowserLaunchOptions = localBrowserLaunchOptions;
   }
@@ -543,6 +547,7 @@ export class Stagehand {
       this.llmClient,
       this.userProvidedInstructions,
       this.apiClient,
+      this.waitForCaptchaSolves,
     ).init();
 
     // Set the browser to headless mode if specified

Diff for: types/stagehand.ts

@@ -33,6 +33,12 @@ export interface ConstructorParams {
    */
   useAPI?: boolean;
   selfHeal?: boolean;
+  /**
+   * Wait for captchas to be solved after navigation when using Browserbase environment.
+   *
+   * @default false
+   */
+  waitForCaptchaSolves?: boolean;
   localBrowserLaunchOptions?: LocalBrowserLaunchOptions;
 }