add optional granular timeout; (#173)

* add optional granular timeout;

* readme update

* reduce default timeout to 30s

Author: filip-michalsky

README.md

@@ -137,7 +137,7 @@ This constructor is used to create an instance of Stagehand.
     - `1`: SDK-level logging
     - `2`: LLM-client level logging (most granular)
   - `debugDom`: a `boolean` that draws bounding boxes around elements presented to the LLM during automation.
-  - `domSettleTimeoutMs`: an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. Defaults to 30000 (30 seconds).
+  - `domSettleTimeoutMs`: an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. It can be overriden in individual function calls if needed. Defaults to 30000 (30 seconds).
   - `enableCaching`: a `boolean` that enables caching of LLM responses. When set to `true`, the LLM requests will be cached on disk and reused for identical requests. Defaults to `false`.
 
 - **Returns:**
@@ -179,6 +179,7 @@ This constructor is used to create an instance of Stagehand.
   - `action`: a `string` describing the action to perform, e.g., `"search for 'x'"`.
   - `modelName`: (optional) an `AvailableModel` string to specify the model to use.
   - `useVision`: (optional) a `boolean` or `"fallback"` to determine if vision-based processing should be used. Defaults to `"fallback"`.
+  - `domSettleTimeoutMs`: (optional) an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. If not set, defaults to the timeout value specified during initialization.
 
 - **Returns:**
 
@@ -201,6 +202,7 @@ This constructor is used to create an instance of Stagehand.
   - `instruction`: a `string` providing instructions for extraction.
   - `schema`: a `z.AnyZodObject` defining the structure of the data to extract.
   - `modelName`: (optional) an `AvailableModel` string to specify the model to use.
+  - `domSettleTimeoutMs`: (optional) an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. If not set, defaults to the timeout value specified during initialization.
 
 - **Returns:**
 
@@ -229,6 +231,7 @@ If you are looking for a specific element, you can also pass in an instruction t
 
   - `instruction`: a `string` providing instructions for the observation.
   - `useVision`: (optional) a `boolean` or `"fallback"` to determine if vision-based processing should be used. Defaults to `"fallback"`.
+  - `domSettleTimeoutMs`: (optional) an `integer` that specifies the timeout in milliseconds for waiting for the DOM to settle. If not set, defaults to the timeout value specified during initialization.
 
 - **Returns:**
 

evals/index.eval.ts

@@ -321,7 +321,9 @@ const homedepot = async () => {
 
   logger.init(stagehand);
 
-  const { debugUrl, sessionUrl } = await stagehand.init();
+  const { debugUrl, sessionUrl } = await stagehand.init({
+    domSettleTimeoutMs: 60_000,
+  });
 
   try {
     await stagehand.page.goto("https://www.homedepot.com/");

lib/index.ts

@@ -296,7 +296,7 @@ export class Stagehand {
     this.verbose = verbose ?? 0;
     this.debugDom = debugDom ?? false;
     this.defaultModelName = "gpt-4o";
-    this.domSettleTimeoutMs = domSettleTimeoutMs ?? 60_000;
+    this.domSettleTimeoutMs = domSettleTimeoutMs ?? 30_000;
     this.headless = headless ?? false;
     this.browserBaseSessionCreateParams = browserBaseSessionCreateParams;
     this.browserbaseResumeSessionID = browserbaseResumeSessionID;
@@ -592,6 +592,7 @@ export class Stagehand {
     chunksSeen = [],
     modelName,
     requestId,
+    domSettleTimeoutMs,
   }: {
     instruction: string;
     schema: T;
@@ -600,14 +601,15 @@ export class Stagehand {
     chunksSeen?: Array<number>;
     modelName?: AvailableModel;
     requestId?: string;
+    domSettleTimeoutMs?: number;
   }): Promise<z.infer<T>> {
     this.log({
       category: "extraction",
       message: `starting extraction '${instruction}'`,
       level: 1,
     });
 
-    await this._waitForSettledDom();
+    await this._waitForSettledDom(domSettleTimeoutMs);
     await this.startDomDebug();
     const { outputString, chunk, chunks } = await this.page.evaluate(
       (chunksSeen?: number[]) => window.processDom(chunksSeen ?? []),
@@ -661,14 +663,15 @@ export class Stagehand {
         message: `continuing extraction, progress: '${newProgress}'`,
         level: 1,
       });
-      await this._waitForSettledDom();
+      await this._waitForSettledDom(domSettleTimeoutMs);
       return this._extract({
         instruction,
         schema,
         progress: newProgress,
         content: output,
         chunksSeen,
         modelName,
+        domSettleTimeoutMs,
       });
     }
   }
@@ -679,12 +682,14 @@ export class Stagehand {
     fullPage,
     modelName,
     requestId,
+    domSettleTimeoutMs,
   }: {
     instruction: string;
     useVision: boolean;
     fullPage: boolean;
     modelName?: AvailableModel;
     requestId?: string;
+    domSettleTimeoutMs?: number;
   }): Promise<{ selector: string; description: string }[]> {
     if (!instruction) {
       instruction = `Find elements that can be used for any future actions in the page. These may be navigation links, related pages, section/subsection links, buttons, or other interactive elements. Be comprehensive: if there are multiple elements that may be relevant for future actions, return all of them.`;
@@ -698,7 +703,7 @@ export class Stagehand {
       level: 1,
     });
 
-    await this._waitForSettledDom();
+    await this._waitForSettledDom(domSettleTimeoutMs);
     await this.startDomDebug();
     let { outputString, selectorMap } = await this.page.evaluate(
       (fullPage: boolean) =>
@@ -770,6 +775,7 @@ export class Stagehand {
     verifierUseVision,
     retries = 0,
     requestId,
+    domSettleTimeoutMs,
   }: {
     action: string;
     steps?: string;
@@ -779,6 +785,7 @@ export class Stagehand {
     verifierUseVision: boolean;
     retries?: number;
     requestId?: string;
+    domSettleTimeoutMs?: number;
   }): Promise<{ success: boolean; message: string; action: string }> {
     const model = modelName ?? this.defaultModelName;
 
@@ -801,7 +808,7 @@ export class Stagehand {
       level: 2,
     });
 
-    await this._waitForSettledDom();
+    await this._waitForSettledDom(domSettleTimeoutMs);
 
     await this.startDomDebug();
 
@@ -889,6 +896,7 @@ export class Stagehand {
           useVision,
           verifierUseVision,
           requestId,
+          domSettleTimeoutMs,
         });
       } else if (useVision === "fallback") {
         this.log({
@@ -905,6 +913,7 @@ export class Stagehand {
           useVision: true,
           verifierUseVision,
           requestId,
+          domSettleTimeoutMs,
         });
       } else {
         if (this.enableCaching) {
@@ -980,6 +989,7 @@ export class Stagehand {
               retries: retries + 1,
               chunksSeen,
               requestId,
+              domSettleTimeoutMs,
             });
           }
         }
@@ -1010,6 +1020,7 @@ export class Stagehand {
               retries: retries + 1,
               chunksSeen,
               requestId,
+              domSettleTimeoutMs,
             });
           }
         }
@@ -1034,6 +1045,7 @@ export class Stagehand {
               retries: retries + 1,
               chunksSeen,
               requestId,
+              domSettleTimeoutMs,
             });
           }
         }
@@ -1070,6 +1082,7 @@ export class Stagehand {
               retries: retries + 1,
               chunksSeen,
               requestId,
+              domSettleTimeoutMs,
             });
           }
         }
@@ -1107,7 +1120,7 @@ export class Stagehand {
             await newOpenedTab.close();
             await this.page.goto(newOpenedTab.url());
             await this.page.waitForLoadState("domcontentloaded");
-            await this._waitForSettledDom();
+            await this._waitForSettledDom(domSettleTimeoutMs);
           }
 
           // Wait for the network to be idle with timeout of 5s (will only wait if loading a new page)
@@ -1259,6 +1272,7 @@ export class Stagehand {
           useVision,
           verifierUseVision,
           requestId,
+          domSettleTimeoutMs,
         });
       } else {
         this.log({
@@ -1289,6 +1303,7 @@ export class Stagehand {
           retries: retries + 1,
           chunksSeen,
           requestId,
+          domSettleTimeoutMs,
         });
       }
 
@@ -1309,10 +1324,12 @@ export class Stagehand {
     action,
     modelName,
     useVision = "fallback",
+    domSettleTimeoutMs,
   }: {
     action: string;
     modelName?: AvailableModel;
     useVision?: "fallback" | boolean;
+    domSettleTimeoutMs?: number;
   }): Promise<{
     success: boolean;
     message: string;
@@ -1334,6 +1351,7 @@ export class Stagehand {
       useVision,
       verifierUseVision: useVision !== false,
       requestId,
+      domSettleTimeoutMs,
     }).catch((e) => {
       this.logger({
         category: "act",
@@ -1356,10 +1374,12 @@ export class Stagehand {
     instruction,
     schema,
     modelName,
+    domSettleTimeoutMs,
   }: {
     instruction: string;
     schema: T;
     modelName?: AvailableModel;
+    domSettleTimeoutMs?: number;
   }): Promise<z.infer<T>> {
     const requestId = Math.random().toString(36).substring(2);
 
@@ -1373,6 +1393,7 @@ export class Stagehand {
       schema,
       modelName,
       requestId,
+      domSettleTimeoutMs,
     }).catch((e) => {
       this.logger({
         category: "extract",
@@ -1391,6 +1412,7 @@ export class Stagehand {
     instruction?: string;
     modelName?: AvailableModel;
     useVision?: boolean;
+    domSettleTimeoutMs?: number;
   }): Promise<{ selector: string; description: string }[]> {
     const requestId = Math.random().toString(36).substring(2);
 
@@ -1407,6 +1429,7 @@ export class Stagehand {
       useVision: options?.useVision ?? false,
       fullPage: false,
       requestId,
+      domSettleTimeoutMs: options?.domSettleTimeoutMs,
     }).catch((e) => {
       this.logger({
         category: "observe",