@browserbasehq/stagehand 3.0.6-alpha-7a8e7055724fe68d36940e483ce84546c597f06d → 3.0.6-alpha-1ebc7e1be4d3129dbba48b0a05b5ac006d3387eb

package/README.md

@@ -20,7 +20,7 @@
       <img alt="MIT License" src="../../media/light_license.svg" />
     </picture>
   </a>
-  <a href="https://join.slack.com/t/stagehand-dev/shared_invite/zt-3hgv6bwqu-s7MXXgPd7_rD53aViGo1MQ">
+  <a href="https://join.slack.com/t/stagehand-dev/shared_invite/zt-3kg9piw3m-rxqCIzeuYQMXG315yHigPQ">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset="../../media/dark_slack.svg" />
       <img alt="Slack Community" src="../../media/light_slack.svg" />
@@ -137,9 +137,9 @@ In your project's `package.json` set:
 ## Contributing
 
 > [!NOTE]  
-> We highly value contributions to Stagehand! For questions or support, please join our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3hgv6bwqu-s7MXXgPd7_rD53aViGo1MQ).
+> We highly value contributions to Stagehand! For questions or support, please join our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3kg9piw3m-rxqCIzeuYQMXG315yHigPQ).
 
-At a high level, we're focused on improving reliability, extensibility, speed, and cost in that order of priority. If you're interested in contributing, **bug fixes and small improvements are the best way to get started**. For more involved features, we strongly recommend reaching out to [Miguel Gonzalez](https://x.com/miguel_gonzf) or [Paul Klein](https://x.com/pk_iv) in our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3hgv6bwqu-s7MXXgPd7_rD53aViGo1MQ) before starting to ensure that your contribution aligns with our goals.
+At a high level, we're focused on improving reliability, extensibility, speed, and cost in that order of priority. If you're interested in contributing, **bug fixes and small improvements are the best way to get started**. For more involved features, we strongly recommend reaching out to [Miguel Gonzalez](https://x.com/miguel_gonzf) or [Paul Klein](https://x.com/pk_iv) in our [Slack community](https://join.slack.com/t/stagehand-dev/shared_invite/zt-3kg9piw3m-rxqCIzeuYQMXG315yHigPQ) before starting to ensure that your contribution aligns with our goals.
 
 <!-- For more information, please see our [Contributing Guide](https://docs.stagehand.dev/examples/contributing). -->
 

package/dist/index.d.ts

@@ -778,6 +778,15 @@ declare class ResponseParseError extends StagehandError {
 declare class TimeoutError extends StagehandError {
     constructor(operation: string, timeoutMs: number);
 }
+declare class ActTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+declare class ExtractTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
+declare class ObserveTimeoutError extends TimeoutError {
+    constructor(timeoutMs: number);
+}
 declare class PageNotFoundError extends StagehandError {
     constructor(identifier: string);
 }
@@ -2400,4 +2409,4 @@ declare class V3Evaluator {
     private _evaluateWithMultipleScreenshots;
 }
 
-export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, type Action, type ActionExecutionResult, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentType, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };
+export { type AISDKCustomProvider, type AISDKProvider, AISdkClient, AVAILABLE_CUA_MODELS, type ActOptions, type ActResult, ActTimeoutError, type Action, type ActionExecutionResult, type AgentAction, type AgentCallbacks, type AgentConfig, type AgentContext, type AgentExecuteCallbacks, type AgentExecuteOptions, type AgentExecuteOptionsBase, type AgentExecutionOptions, type AgentHandlerOptions, type AgentInstance, type AgentModelConfig, AgentProvider, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentState, type AgentStreamCallbacks, type AgentStreamExecuteOptions, type AgentStreamResult, type AgentType, AnnotatedScreenshotText, type AnthropicClientOptions, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AnyPage, type AvailableCuaModel, type AvailableModel, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, ConnectionTimeoutError, type ConsoleListener, ConsoleMessage, ContentFrameNotFoundError, type CreateChatCompletionOptions, CreateChatCompletionResponseError, CuaModelRequiredError, ElementNotVisibleError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, type ExtractOptions, type ExtractResult, ExtractTimeoutError, type FunctionCallItem, type GoogleServiceAccountCredentials, type GoogleVertexProviderSettings, HandlerNotInitializedError, type HistoryEntry, type InferStagehandSchema, InvalidAISDKModelFormatError, type JsonSchema, type JsonSchemaDocument, type JsonSchemaProperty, LLMClient, type LLMParsedResponse, type LLMResponse, LLMResponseError, type LLMTool, type LLMUsage, LOG_LEVEL_NAMES, type LoadState, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MCPConnectionError, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelConfiguration, type ModelProvider, type NonStreamingAgentInstance, type ObserveOptions, ObserveTimeoutError, type OpenAIClientOptions, Page, PageNotFoundError, Response$1 as Response, ResponseBodyError, type ResponseInputItem, type ResponseItem, ResponseParseError, V3 as Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandClickError, StagehandDefaultError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandHttpError, StagehandIframeError, StagehandInitError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, type StagehandZodObject, type StagehandZodSchema, type StreamingAgentInstance, StreamingCallbacksInNonStreamingModeError, TimeoutError, type ToolUseItem, UnsupportedAISDKModelProviderError, UnsupportedModelError, UnsupportedModelProviderError, V3, type V3Env, V3Evaluator, V3FunctionName, type V3Options, XPathResolutionError, ZodSchemaValidationError, connectToMCPServer, defaultExtractSchema, getZodType, injectUrls, isRunningInBun, isZod3Schema, isZod4Schema, jsonSchemaToZod, loadApiKeyFromEnv, modelToAgentProviderMap, pageTextSchema, providerEnvVarMap, toGeminiSchema, toJsonSchema, transformSchema, trimTrailingTextNode, validateZodSchema };

package/dist/index.js

@@ -141,12 +141,12 @@ var __forAwait = (obj, it, method) => (it = obj[__knownSymbol("asyncIterator")])
 var STAGEHAND_VERSION;
 var init_version = __esm({
   "lib/version.ts"() {
-    STAGEHAND_VERSION = "3.0.6-alpha-7a8e7055724fe68d36940e483ce84546c597f06d";
+    STAGEHAND_VERSION = "3.0.6-alpha-1ebc7e1be4d3129dbba48b0a05b5ac006d3387eb";
   }
 });
 
 // lib/v3/types/public/sdkErrors.ts
-var StagehandError, StagehandDefaultError, StagehandEnvironmentError, MissingEnvironmentVariableError, UnsupportedModelError, UnsupportedModelProviderError, UnsupportedAISDKModelProviderError, InvalidAISDKModelFormatError, StagehandNotInitializedError, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, MissingLLMConfigurationError, HandlerNotInitializedError, StagehandInvalidArgumentError, StagehandElementNotFoundError, AgentScreenshotProviderError, StagehandMissingArgumentError, CreateChatCompletionResponseError, StagehandEvalError, StagehandDomProcessError, StagehandClickError, LLMResponseError, StagehandIframeError, ContentFrameNotFoundError, XPathResolutionError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, CuaModelRequiredError, ZodSchemaValidationError, StagehandInitError, MCPConnectionError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, ElementNotVisibleError, ResponseBodyError, ResponseParseError, TimeoutError, PageNotFoundError, ConnectionTimeoutError, StreamingCallbacksInNonStreamingModeError;
+var StagehandError, StagehandDefaultError, StagehandEnvironmentError, MissingEnvironmentVariableError, UnsupportedModelError, UnsupportedModelProviderError, UnsupportedAISDKModelProviderError, InvalidAISDKModelFormatError, StagehandNotInitializedError, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, MissingLLMConfigurationError, HandlerNotInitializedError, StagehandInvalidArgumentError, StagehandElementNotFoundError, AgentScreenshotProviderError, StagehandMissingArgumentError, CreateChatCompletionResponseError, StagehandEvalError, StagehandDomProcessError, StagehandClickError, LLMResponseError, StagehandIframeError, ContentFrameNotFoundError, XPathResolutionError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, CuaModelRequiredError, ZodSchemaValidationError, StagehandInitError, MCPConnectionError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, ElementNotVisibleError, ResponseBodyError, ResponseParseError, TimeoutError, ActTimeoutError, ExtractTimeoutError, ObserveTimeoutError, PageNotFoundError, ConnectionTimeoutError, StreamingCallbacksInNonStreamingModeError;
 var init_sdkErrors = __esm({
   "lib/v3/types/public/sdkErrors.ts"() {
     init_version();
@@ -396,6 +396,24 @@ ${JSON.stringify(issues, null, 2)}`);
         super(`${operation} timed out after ${timeoutMs}ms`);
       }
     };
+    ActTimeoutError = class extends TimeoutError {
+      constructor(timeoutMs) {
+        super("act()", timeoutMs);
+        this.name = "ActTimeoutError";
+      }
+    };
+    ExtractTimeoutError = class extends TimeoutError {
+      constructor(timeoutMs) {
+        super("extract()", timeoutMs);
+        this.name = "ExtractTimeoutError";
+      }
+    };
+    ObserveTimeoutError = class extends TimeoutError {
+      constructor(timeoutMs) {
+        super("observe()", timeoutMs);
+        this.name = "ObserveTimeoutError";
+      }
+    };
     PageNotFoundError = class extends StagehandError {
       constructor(identifier) {
         super(`No Page found for ${identifier}`);
@@ -25989,6 +26007,7 @@ var v3_exports = {};
 __export(v3_exports, {
   AISdkClient: () => AISdkClient2,
   AVAILABLE_CUA_MODELS: () => AVAILABLE_CUA_MODELS,
+  ActTimeoutError: () => ActTimeoutError,
   AgentProvider: () => AgentProvider,
   AgentScreenshotProviderError: () => AgentScreenshotProviderError,
   AnnotatedScreenshotText: () => AnnotatedScreenshotText,
@@ -26002,6 +26021,7 @@ __export(v3_exports, {
   ElementNotVisibleError: () => ElementNotVisibleError,
   ExperimentalApiConflictError: () => ExperimentalApiConflictError,
   ExperimentalNotConfiguredError: () => ExperimentalNotConfiguredError,
+  ExtractTimeoutError: () => ExtractTimeoutError,
   HandlerNotInitializedError: () => HandlerNotInitializedError,
   InvalidAISDKModelFormatError: () => InvalidAISDKModelFormatError,
   LLMClient: () => LLMClient,
@@ -26010,6 +26030,7 @@ __export(v3_exports, {
   MCPConnectionError: () => MCPConnectionError,
   MissingEnvironmentVariableError: () => MissingEnvironmentVariableError,
   MissingLLMConfigurationError: () => MissingLLMConfigurationError,
+  ObserveTimeoutError: () => ObserveTimeoutError,
   PageNotFoundError: () => PageNotFoundError,
   Response: () => Response2,
   ResponseBodyError: () => ResponseBodyError,
@@ -28490,6 +28511,7 @@ var V3FunctionName = /* @__PURE__ */ ((V3FunctionName2) => {
 })(V3FunctionName || {});
 
 // lib/v3/handlers/actHandler.ts
+init_sdkErrors();
 init_snapshot();
 
 // lib/v3/types/private/handlers.ts
@@ -29142,6 +29164,23 @@ function handlePossibleNavigation(actionDescription, xpath, initialUrl, frame) {
   });
 }
 
+// lib/v3/handlers/handlerUtils/timeoutGuard.ts
+init_sdkErrors();
+function createTimeoutGuard(timeoutMs, errorFactory) {
+  if (!timeoutMs || timeoutMs <= 0) {
+    return () => {
+    };
+  }
+  const startTime = Date.now();
+  return () => {
+    var _a4;
+    if (Date.now() - startTime >= timeoutMs) {
+      const err = (_a4 = errorFactory == null ? void 0 : errorFactory(timeoutMs)) != null ? _a4 : new TimeoutError("operation", timeoutMs);
+      throw err;
+    }
+  };
+}
+
 // lib/v3/handlers/actHandler.ts
 var ActHandler = class {
   constructor(llmClient, defaultModelName, defaultClientOptions, resolveLlmClient, systemPrompt, logInferenceToFile, selfHeal, onMetrics, defaultDomSettleTimeoutMs) {
@@ -29209,111 +29248,109 @@ var ActHandler = class {
     return __async(this, null, function* () {
       const { instruction, page, variables, timeout, model } = params;
       const llmClient = this.resolveLlmClient(model);
-      const doObserveAndAct = () => __async(this, null, function* () {
-        yield waitForDomNetworkQuiet(
-          page.mainFrame(),
-          this.defaultDomSettleTimeoutMs
-        );
-        const { combinedTree, combinedXpathMap } = yield captureHybridSnapshot(
-          page,
-          { experimental: true }
-        );
-        const actInstruction = buildActPrompt(
-          instruction,
-          Object.values(SupportedPlaywrightAction),
-          variables
-        );
-        const { action: firstAction, response: actInferenceResponse } = yield this.getActionFromLLM({
-          instruction: actInstruction,
-          domElements: combinedTree,
-          xpathMap: combinedXpathMap,
-          llmClient,
-          variables
-        });
-        if (!firstAction) {
-          v3Logger({
-            category: "action",
-            message: "no actionable element returned by LLM",
-            level: 1
-          });
-          return {
-            success: false,
-            message: "Failed to perform act: No action found",
-            actionDescription: instruction,
-            actions: []
-          };
-        }
-        const firstResult = yield this.takeDeterministicAction(
-          firstAction,
-          page,
-          this.defaultDomSettleTimeoutMs,
-          llmClient
-        );
-        if ((actInferenceResponse == null ? void 0 : actInferenceResponse.twoStep) !== true) {
-          return firstResult;
-        }
-        const {
-          combinedTree: combinedTree2,
-          combinedXpathMap: combinedXpathMap2
-        } = yield captureHybridSnapshot(page, {
-          experimental: true
-        });
-        let diffedTree = diffCombinedTrees(combinedTree, combinedTree2);
-        if (!diffedTree.trim()) {
-          diffedTree = combinedTree2;
-        }
-        const previousAction = `method: ${firstAction.method}, description: ${firstAction.description}, arguments: ${firstAction.arguments}`;
-        const stepTwoInstructions = buildStepTwoPrompt(
-          instruction,
-          previousAction,
-          Object.values(SupportedPlaywrightAction).filter(
-            (action) => action !== "selectOptionFromDropdown" /* SELECT_OPTION_FROM_DROPDOWN */
-          ),
-          variables
-        );
-        const { action: secondAction } = yield this.getActionFromLLM({
-          instruction: stepTwoInstructions,
-          domElements: diffedTree,
-          xpathMap: combinedXpathMap2,
-          llmClient,
-          variables
+      const effectiveTimeoutMs = typeof timeout === "number" && timeout > 0 ? timeout : void 0;
+      const ensureTimeRemaining = createTimeoutGuard(
+        effectiveTimeoutMs,
+        (ms) => new ActTimeoutError(ms)
+      );
+      ensureTimeRemaining();
+      yield waitForDomNetworkQuiet(
+        page.mainFrame(),
+        this.defaultDomSettleTimeoutMs
+      );
+      ensureTimeRemaining();
+      const { combinedTree, combinedXpathMap } = yield captureHybridSnapshot(
+        page,
+        { experimental: true }
+      );
+      const actInstruction = buildActPrompt(
+        instruction,
+        Object.values(SupportedPlaywrightAction),
+        variables
+      );
+      ensureTimeRemaining();
+      const { action: firstAction, response: actInferenceResponse } = yield this.getActionFromLLM({
+        instruction: actInstruction,
+        domElements: combinedTree,
+        xpathMap: combinedXpathMap,
+        llmClient,
+        variables
+      });
+      if (!firstAction) {
+        v3Logger({
+          category: "action",
+          message: "no actionable element returned by LLM",
+          level: 1
         });
-        if (!secondAction) {
-          return firstResult;
-        }
-        const secondResult = yield this.takeDeterministicAction(
-          secondAction,
-          page,
-          this.defaultDomSettleTimeoutMs,
-          llmClient
-        );
         return {
-          success: firstResult.success && secondResult.success,
-          message: secondResult.success ? `${firstResult.message} \u2192 ${secondResult.message}` : `${firstResult.message} \u2192 ${secondResult.message}`,
-          actionDescription: firstResult.actionDescription,
-          actions: [
-            ...firstResult.actions || [],
-            ...secondResult.actions || []
-          ]
+          success: false,
+          message: "Failed to perform act: No action found",
+          actionDescription: instruction,
+          actions: []
         };
+      }
+      ensureTimeRemaining();
+      const firstResult = yield this.takeDeterministicAction(
+        firstAction,
+        page,
+        this.defaultDomSettleTimeoutMs,
+        llmClient,
+        ensureTimeRemaining
+      );
+      if ((actInferenceResponse == null ? void 0 : actInferenceResponse.twoStep) !== true) {
+        return firstResult;
+      }
+      ensureTimeRemaining();
+      const { combinedTree: combinedTree2, combinedXpathMap: combinedXpathMap2 } = yield captureHybridSnapshot(page, {
+        experimental: true
       });
-      if (!timeout) {
-        return doObserveAndAct();
-      }
-      return yield Promise.race([
-        doObserveAndAct(),
-        new Promise((_, reject) => {
-          setTimeout(
-            () => reject(new Error(`act() timed out after ${timeout}ms`)),
-            timeout
-          );
-        })
-      ]);
+      let diffedTree = diffCombinedTrees(combinedTree, combinedTree2);
+      if (!diffedTree.trim()) {
+        diffedTree = combinedTree2;
+      }
+      const previousAction = `method: ${firstAction.method}, description: ${firstAction.description}, arguments: ${firstAction.arguments}`;
+      const stepTwoInstructions = buildStepTwoPrompt(
+        instruction,
+        previousAction,
+        Object.values(SupportedPlaywrightAction).filter(
+          (action) => action !== "selectOptionFromDropdown" /* SELECT_OPTION_FROM_DROPDOWN */
+        ),
+        variables
+      );
+      ensureTimeRemaining();
+      const { action: secondAction } = yield this.getActionFromLLM({
+        instruction: stepTwoInstructions,
+        domElements: diffedTree,
+        xpathMap: combinedXpathMap2,
+        llmClient,
+        variables
+      });
+      if (!secondAction) {
+        return firstResult;
+      }
+      ensureTimeRemaining();
+      const secondResult = yield this.takeDeterministicAction(
+        secondAction,
+        page,
+        this.defaultDomSettleTimeoutMs,
+        llmClient,
+        ensureTimeRemaining
+      );
+      return {
+        success: firstResult.success && secondResult.success,
+        message: secondResult.success ? `${firstResult.message} \u2192 ${secondResult.message}` : `${firstResult.message} \u2192 ${secondResult.message}`,
+        actionDescription: firstResult.actionDescription,
+        actions: [
+          ...firstResult.actions || [],
+          ...secondResult.actions || []
+        ]
+      };
     });
   }
-  takeDeterministicAction(action, page, domSettleTimeoutMs, llmClientOverride) {
+  takeDeterministicAction(action, page, domSettleTimeoutMs, llmClientOverride, ensureTimeRemaining) {
     return __async(this, null, function* () {
       var _a4;
+      ensureTimeRemaining == null ? void 0 : ensureTimeRemaining();
       const settleTimeout = domSettleTimeoutMs != null ? domSettleTimeoutMs : this.defaultDomSettleTimeoutMs;
       const effectiveClient = llmClientOverride != null ? llmClientOverride : this.llmClient;
       const method = (_a4 = action.method) == null ? void 0 : _a4.trim();
@@ -29335,6 +29372,7 @@ var ActHandler = class {
       }
       const args = Array.isArray(action.arguments) ? action.arguments : [];
       try {
+        ensureTimeRemaining == null ? void 0 : ensureTimeRemaining();
         yield performUnderstudyMethod(
           page,
           page.mainFrame(),
@@ -29357,6 +29395,9 @@ var ActHandler = class {
           ]
         };
       } catch (err) {
+        if (err instanceof ActTimeoutError) {
+          throw err;
+        }
         const msg = err instanceof Error ? err.message : String(err);
         if (this.selfHeal) {
           v3Logger({
@@ -29373,6 +29414,7 @@ var ActHandler = class {
           });
           try {
             const actCommand = action.description ? action.description.toLowerCase().startsWith(method.toLowerCase()) ? action.description : `${method} ${action.description}` : method;
+            ensureTimeRemaining == null ? void 0 : ensureTimeRemaining();
             const { combinedTree, combinedXpathMap } = yield captureHybridSnapshot(page, {
               experimental: true
             });
@@ -29381,6 +29423,7 @@ var ActHandler = class {
               Object.values(SupportedPlaywrightAction),
               {}
             );
+            ensureTimeRemaining == null ? void 0 : ensureTimeRemaining();
             const { action: fallbackAction, response: fallbackResponse } = yield this.getActionFromLLM({
               instruction,
               domElements: combinedTree,
@@ -29401,6 +29444,7 @@ var ActHandler = class {
             if (fallbackAction == null ? void 0 : fallbackAction.selector) {
               newSelector = fallbackAction.selector;
             }
+            ensureTimeRemaining == null ? void 0 : ensureTimeRemaining();
             yield performUnderstudyMethod(
               page,
               page.mainFrame(),
@@ -29423,6 +29467,9 @@ var ActHandler = class {
               ]
             };
           } catch (retryErr) {
+            if (retryErr instanceof ActTimeoutError) {
+              throw retryErr;
+            }
             const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
             return {
               success: false,
@@ -29501,122 +29548,110 @@ var ExtractHandler = class {
   }
   extract(params) {
     return __async(this, null, function* () {
+      var _a4, _b, _d2;
       const { instruction, schema, page, selector, timeout, model } = params;
       const llmClient = this.resolveLlmClient(model);
-      const doExtract = () => __async(this, null, function* () {
-        var _a4, _b, _d2;
-        const noArgs = !instruction && !schema;
-        if (noArgs) {
-          const focusSelector2 = (_a4 = selector == null ? void 0 : selector.replace(/^xpath=/i, "")) != null ? _a4 : "";
-          const snap = yield captureHybridSnapshot(page, {
-            experimental: this.experimental,
-            focusSelector: focusSelector2 || void 0
-          });
-          const result = { pageText: snap.combinedTree };
-          return pageTextSchema.parse(result);
-        }
-        if (!instruction && schema) {
-          throw new StagehandInvalidArgumentError(
-            "extract() requires an instruction when a schema is provided."
-          );
-        }
-        const focusSelector = (_b = selector == null ? void 0 : selector.replace(/^xpath=/, "")) != null ? _b : "";
-        const { combinedTree, combinedUrlMap } = yield captureHybridSnapshot(
-          page,
-          {
-            experimental: this.experimental,
-            focusSelector
-          }
-        );
-        v3Logger({
-          category: "extraction",
-          message: "Starting extraction using a11y snapshot",
-          level: 1,
-          auxiliary: instruction ? { instruction: { value: instruction, type: "string" } } : void 0
-        });
-        const baseSchema = schema != null ? schema : defaultExtractSchema;
-        const isObjectSchema = getZodType(baseSchema) === "object";
-        const WRAP_KEY = "value";
-        const factory6 = getZFactory(baseSchema);
-        const objectSchema = isObjectSchema ? baseSchema : factory6.object({
-          [WRAP_KEY]: baseSchema
-        });
-        const [transformedSchema, urlFieldPaths] = transformUrlStringsToNumericIds(objectSchema);
-        const extractionResponse = yield extract({
-          instruction,
-          domElements: combinedTree,
-          schema: transformedSchema,
-          llmClient,
-          userProvidedInstructions: this.systemPrompt,
-          logger: v3Logger,
-          logInferenceToFile: this.logInferenceToFile
-        });
-        const _c = extractionResponse, {
-          metadata: { completed },
-          prompt_tokens,
-          completion_tokens,
-          reasoning_tokens = 0,
-          cached_input_tokens = 0,
-          inference_time_ms
-        } = _c, rest = __objRest(_c, [
-          "metadata",
-          "prompt_tokens",
-          "completion_tokens",
-          "reasoning_tokens",
-          "cached_input_tokens",
-          "inference_time_ms"
-        ]);
-        let output = rest;
-        v3Logger({
-          category: "extraction",
-          message: completed ? "Extraction completed successfully" : "Extraction incomplete after processing all data",
-          level: 1,
-          auxiliary: {
-            prompt_tokens: { value: String(prompt_tokens), type: "string" },
-            completion_tokens: {
-              value: String(completion_tokens),
-              type: "string"
-            },
-            inference_time_ms: {
-              value: String(inference_time_ms),
-              type: "string"
-            }
-          }
+      const effectiveTimeoutMs = typeof timeout === "number" && timeout > 0 ? timeout : void 0;
+      const ensureTimeRemaining = createTimeoutGuard(
+        effectiveTimeoutMs,
+        (ms) => new ExtractTimeoutError(ms)
+      );
+      const noArgs = !instruction && !schema;
+      if (noArgs) {
+        const focusSelector2 = (_a4 = selector == null ? void 0 : selector.replace(/^xpath=/i, "")) != null ? _a4 : "";
+        ensureTimeRemaining();
+        const snap = yield captureHybridSnapshot(page, {
+          experimental: this.experimental,
+          focusSelector: focusSelector2 || void 0
         });
-        (_d2 = this.onMetrics) == null ? void 0 : _d2.call(
-          this,
-          "EXTRACT" /* EXTRACT */,
-          prompt_tokens,
-          completion_tokens,
-          reasoning_tokens,
-          cached_input_tokens,
-          inference_time_ms
+        const result = { pageText: snap.combinedTree };
+        return pageTextSchema.parse(result);
+      }
+      if (!instruction && schema) {
+        throw new StagehandInvalidArgumentError(
+          "extract() requires an instruction when a schema is provided."
         );
-        const idToUrl = combinedUrlMap != null ? combinedUrlMap : {};
-        for (const { segments } of urlFieldPaths) {
-          injectUrls(
-            output,
-            segments,
-            idToUrl
-          );
-        }
-        if (!isObjectSchema && output && typeof output === "object") {
-          output = output[WRAP_KEY];
-        }
-        return output;
+      }
+      const focusSelector = (_b = selector == null ? void 0 : selector.replace(/^xpath=/, "")) != null ? _b : "";
+      ensureTimeRemaining();
+      const { combinedTree, combinedUrlMap } = yield captureHybridSnapshot(page, {
+        experimental: this.experimental,
+        focusSelector
       });
-      if (!timeout) return doExtract();
-      return yield Promise.race([
-        doExtract(),
-        new Promise(
-          (_, reject) => {
-            setTimeout(
-              () => reject(new Error(`extract() timed out after ${timeout}ms`)),
-              timeout
-            );
-          }
-        )
+      v3Logger({
+        category: "extraction",
+        message: "Starting extraction using a11y snapshot",
+        level: 1,
+        auxiliary: instruction ? { instruction: { value: instruction, type: "string" } } : void 0
+      });
+      const baseSchema = schema != null ? schema : defaultExtractSchema;
+      const isObjectSchema = getZodType(baseSchema) === "object";
+      const WRAP_KEY = "value";
+      const factory6 = getZFactory(baseSchema);
+      const objectSchema = isObjectSchema ? baseSchema : factory6.object({
+        [WRAP_KEY]: baseSchema
+      });
+      const [transformedSchema, urlFieldPaths] = transformUrlStringsToNumericIds(objectSchema);
+      ensureTimeRemaining();
+      const extractionResponse = yield extract({
+        instruction,
+        domElements: combinedTree,
+        schema: transformedSchema,
+        llmClient,
+        userProvidedInstructions: this.systemPrompt,
+        logger: v3Logger,
+        logInferenceToFile: this.logInferenceToFile
+      });
+      const _c = extractionResponse, {
+        metadata: { completed },
+        prompt_tokens,
+        completion_tokens,
+        reasoning_tokens = 0,
+        cached_input_tokens = 0,
+        inference_time_ms
+      } = _c, rest = __objRest(_c, [
+        "metadata",
+        "prompt_tokens",
+        "completion_tokens",
+        "reasoning_tokens",
+        "cached_input_tokens",
+        "inference_time_ms"
       ]);
+      let output = rest;
+      v3Logger({
+        category: "extraction",
+        message: completed ? "Extraction completed successfully" : "Extraction incomplete after processing all data",
+        level: 1,
+        auxiliary: {
+          prompt_tokens: { value: String(prompt_tokens), type: "string" },
+          completion_tokens: { value: String(completion_tokens), type: "string" },
+          inference_time_ms: {
+            value: String(inference_time_ms),
+            type: "string"
+          }
+        }
+      });
+      (_d2 = this.onMetrics) == null ? void 0 : _d2.call(
+        this,
+        "EXTRACT" /* EXTRACT */,
+        prompt_tokens,
+        completion_tokens,
+        reasoning_tokens,
+        cached_input_tokens,
+        inference_time_ms
+      );
+      const idToUrl = combinedUrlMap != null ? combinedUrlMap : {};
+      for (const { segments } of urlFieldPaths) {
+        injectUrls(
+          output,
+          segments,
+          idToUrl
+        );
+      }
+      if (!isObjectSchema && output && typeof output === "object") {
+        output = output[WRAP_KEY];
+      }
+      return output;
     });
   }
 };
@@ -29624,6 +29659,7 @@ var ExtractHandler = class {
 // lib/v3/handlers/observeHandler.ts
 init_logger();
 init_snapshot();
+init_sdkErrors();
 var ObserveHandler = class {
   constructor(llmClient, defaultModelName, defaultClientOptions, resolveLlmClient, systemPrompt, logInferenceToFile, experimental, onMetrics) {
     this.llmClient = llmClient;
@@ -29637,102 +29673,96 @@ var ObserveHandler = class {
   }
   observe(params) {
     return __async(this, null, function* () {
+      var _a4, _b, _c;
       const { instruction, page, timeout, selector, model } = params;
       const llmClient = this.resolveLlmClient(model);
+      const effectiveTimeoutMs = typeof timeout === "number" && timeout > 0 ? timeout : void 0;
+      const ensureTimeRemaining = createTimeoutGuard(
+        effectiveTimeoutMs,
+        (ms) => new ObserveTimeoutError(ms)
+      );
       const effectiveInstruction = instruction != null ? 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.";
-      const doObserve = () => __async(this, null, function* () {
-        var _a4, _b, _c;
-        v3Logger({
-          category: "observation",
-          message: "starting observation",
-          level: 1,
-          auxiliary: {
-            instruction: {
-              value: effectiveInstruction,
-              type: "string"
-            }
+      v3Logger({
+        category: "observation",
+        message: "starting observation",
+        level: 1,
+        auxiliary: {
+          instruction: {
+            value: effectiveInstruction,
+            type: "string"
           }
-        });
-        const focusSelector = (_a4 = selector == null ? void 0 : selector.replace(/^xpath=/i, "")) != null ? _a4 : "";
-        const snapshot = yield captureHybridSnapshot(page, {
-          experimental: this.experimental,
-          focusSelector: focusSelector || void 0
-        });
-        const combinedTree = snapshot.combinedTree;
-        const combinedXpathMap = (_b = snapshot.combinedXpathMap) != null ? _b : {};
-        v3Logger({
-          category: "observation",
-          message: "Got accessibility tree data",
-          level: 1
-        });
-        const observationResponse = yield observe({
-          instruction: effectiveInstruction,
-          domElements: combinedTree,
-          llmClient,
-          userProvidedInstructions: this.systemPrompt,
-          logger: v3Logger,
-          logInferenceToFile: this.logInferenceToFile
-        });
-        const {
-          prompt_tokens = 0,
-          completion_tokens = 0,
-          reasoning_tokens = 0,
-          cached_input_tokens = 0,
-          inference_time_ms = 0
-        } = observationResponse;
-        (_c = this.onMetrics) == null ? void 0 : _c.call(
-          this,
-          "OBSERVE" /* OBSERVE */,
-          prompt_tokens,
-          completion_tokens,
-          reasoning_tokens,
-          cached_input_tokens,
-          inference_time_ms
-        );
-        const elementsWithSelectors = (yield Promise.all(
-          observationResponse.elements.map((element) => __async(this, null, function* () {
-            const _a5 = element, { elementId } = _a5, rest = __objRest(_a5, ["elementId"]);
-            if (typeof elementId === "string" && elementId.includes("-")) {
-              const lookUpIndex = elementId;
-              const xpath = combinedXpathMap[lookUpIndex];
-              const trimmedXpath = trimTrailingTextNode(xpath);
-              if (!trimmedXpath) return void 0;
-              return __spreadProps(__spreadValues({}, rest), {
-                // if method/arguments exist, they’re preserved; otherwise they’re absent
-                selector: `xpath=${trimmedXpath}`
-              });
-            }
-            return {
-              description: "an element inside a shadow DOM",
-              method: "not-supported",
-              arguments: [],
-              selector: "not-supported"
-            };
-          }))
-        )).filter((e2) => e2 !== void 0);
-        v3Logger({
-          category: "observation",
-          message: "found elements",
-          level: 1,
-          auxiliary: {
-            elements: {
-              value: JSON.stringify(elementsWithSelectors),
-              type: "object"
-            }
+        }
+      });
+      const focusSelector = (_a4 = selector == null ? void 0 : selector.replace(/^xpath=/i, "")) != null ? _a4 : "";
+      ensureTimeRemaining();
+      const snapshot = yield captureHybridSnapshot(page, {
+        experimental: this.experimental,
+        focusSelector: focusSelector || void 0
+      });
+      const combinedTree = snapshot.combinedTree;
+      const combinedXpathMap = (_b = snapshot.combinedXpathMap) != null ? _b : {};
+      v3Logger({
+        category: "observation",
+        message: "Got accessibility tree data",
+        level: 1
+      });
+      ensureTimeRemaining();
+      const observationResponse = yield observe({
+        instruction: effectiveInstruction,
+        domElements: combinedTree,
+        llmClient,
+        userProvidedInstructions: this.systemPrompt,
+        logger: v3Logger,
+        logInferenceToFile: this.logInferenceToFile
+      });
+      const {
+        prompt_tokens = 0,
+        completion_tokens = 0,
+        reasoning_tokens = 0,
+        cached_input_tokens = 0,
+        inference_time_ms = 0
+      } = observationResponse;
+      (_c = this.onMetrics) == null ? void 0 : _c.call(
+        this,
+        "OBSERVE" /* OBSERVE */,
+        prompt_tokens,
+        completion_tokens,
+        reasoning_tokens,
+        cached_input_tokens,
+        inference_time_ms
+      );
+      const elementsWithSelectors = (yield Promise.all(
+        observationResponse.elements.map((element) => __async(this, null, function* () {
+          const _a5 = element, { elementId } = _a5, rest = __objRest(_a5, ["elementId"]);
+          if (typeof elementId === "string" && elementId.includes("-")) {
+            const lookUpIndex = elementId;
+            const xpath = combinedXpathMap[lookUpIndex];
+            const trimmedXpath = trimTrailingTextNode(xpath);
+            if (!trimmedXpath) return void 0;
+            return __spreadProps(__spreadValues({}, rest), {
+              selector: `xpath=${trimmedXpath}`
+            });
           }
-        });
-        return elementsWithSelectors;
+          return {
+            description: "an element inside a shadow DOM",
+            method: "not-supported",
+            arguments: [],
+            selector: "not-supported"
+          };
+        }))
+      )).filter((e2) => e2 !== void 0);
+      v3Logger({
+        category: "observation",
+        message: "found elements",
+        level: 1,
+        auxiliary: {
+          elements: {
+            value: JSON.stringify(elementsWithSelectors),
+            type: "object"
+          }
+        }
       });
-      if (!timeout) return doObserve();
-      return yield Promise.race([
-        doObserve(),
-        new Promise((_, reject) => {
-          setTimeout(
-            () => reject(new Error(`observe() timed out after ${timeout}ms`)),
-            timeout
-          );
-        })
-      ]);
+      return elementsWithSelectors;
     });
   }
 };
@@ -63087,6 +63117,7 @@ var StagehandAPIClient = class {
 };
 
 // lib/v3/v3.ts
+init_sdkErrors();
 var DEFAULT_MODEL_NAME = "openai/gpt-4.1-mini";
 var DEFAULT_VIEWPORT = { width: 1288, height: 711 };
 function resolveModelConfiguration(model) {
@@ -63792,13 +63823,17 @@ var _V3 = class _V3 {
               frameId: v3Page.mainFrameId()
             });
           } else {
+            const effectiveTimeoutMs = typeof (options == null ? void 0 : options.timeout) === "number" && options.timeout > 0 ? options.timeout : void 0;
+            const ensureTimeRemaining = createTimeoutGuard(
+              effectiveTimeoutMs,
+              (ms) => new ActTimeoutError(ms)
+            );
             actResult = yield this.actHandler.takeDeterministicAction(
               __spreadProps(__spreadValues({}, input), { selector }),
-              // ObserveResult
               v3Page,
-              // V3 Page
               this.domSettleTimeoutMs,
-              this.resolveLlmClient(options == null ? void 0 : options.model)
+              this.resolveLlmClient(options == null ? void 0 : options.model),
+              ensureTimeRemaining
             );
           }
           this.addToHistory(
@@ -64659,6 +64694,7 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
 0 && (module.exports = {
   AISdkClient,
   AVAILABLE_CUA_MODELS,
+  ActTimeoutError,
   AgentProvider,
   AgentScreenshotProviderError,
   AnnotatedScreenshotText,
@@ -64672,6 +64708,7 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
   ElementNotVisibleError,
   ExperimentalApiConflictError,
   ExperimentalNotConfiguredError,
+  ExtractTimeoutError,
   HandlerNotInitializedError,
   InvalidAISDKModelFormatError,
   LLMClient,
@@ -64680,6 +64717,7 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
   MCPConnectionError,
   MissingEnvironmentVariableError,
   MissingLLMConfigurationError,
+  ObserveTimeoutError,
   PageNotFoundError,
   Response,
   ResponseBodyError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/stagehand",
-  "version": "3.0.6-alpha-7a8e7055724fe68d36940e483ce84546c597f06d",
+  "version": "3.0.6-alpha-1ebc7e1be4d3129dbba48b0a05b5ac006d3387eb",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -96,6 +96,6 @@
     "e2e:bb": "playwright test --config=lib/v3/tests/v3.bb.playwright.config.ts",
     "lint": "cd ../.. && prettier --check packages/core && cd packages/core && eslint .",
     "format": "prettier --write .",
-    "test:vitest": "pnpm run build-js && pnpm run typecheck && vitest run --config vitest.config.ts"
+    "test:vitest": "turbo run build && vitest run --config vitest.config.ts"
   }
 }