@browserbasehq/stagehand 1.0.3-alpha.2 → 1.1.0

package/README.md

@@ -101,6 +101,7 @@ import { z } from "zod";
 
 const stagehand = new Stagehand({
   env: "BROWSERBASE",
+  enableCaching: true,
 });
 ```
 
@@ -137,6 +138,7 @@ This constructor is used to create an instance of Stagehand.
     - `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).
+  - `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:**
 
@@ -278,7 +280,6 @@ Stagehand currently supports the following models from OpenAI and Anthropic:
 
 These models can be specified when initializing the `Stagehand` instance or when calling methods like `act()` and `extract()`.
 
-
 ## How It Works
 
 The SDK has two major phases:
@@ -342,12 +343,14 @@ const productInfo = await stagehand.extract({
 - **Break down complex tasks into smaller, atomic steps**
 
 Instead of combining actions:
+
 ```javascript
 // Avoid this
 await stagehand.act({ action: "log in and purchase the first item" });
 ```
 
 Split them into individual steps:
+
 ```javascript
 await stagehand.act({ action: "click the login button" });
 // ...additional steps to log in...
@@ -385,11 +388,10 @@ await stagehand.act({ action: "fill out the form and submit it" });
 await stagehand.act({ action: "book the cheapest flight available" });
 ```
 
-By following these guidelines, you'll increase the reliability and effectiveness of your web automations with Stagehand. Remember, Stagehand excels at executing precise, well-defined actions so keeping your instructions atomic will lead to the best outcomes. 
+By following these guidelines, you'll increase the reliability and effectiveness of your web automations with Stagehand. Remember, Stagehand excels at executing precise, well-defined actions so keeping your instructions atomic will lead to the best outcomes.
 
 We leave the agentic behaviour to higher-level agentic systems which can use Stagehand as a tool.
 
-
 ## Roadmap
 
 At a high level, we're focused on improving reliability, speed, and cost in that order of priority.
@@ -464,7 +466,7 @@ Stagehand uses [tsup](https://github.com/egoist/tsup) to build the SDK and vanil
 
 ## Acknowledgements
 
-This project heavily relies on [Playwright](https://playwright.dev/) as a resilient backbone to automate the web. It also would not be possible without the awesome techniques and discoveries made by [tarsier](https://github.com/reworkd/tarsier), and [fuji-web](https://github.com/fuji-web).
+This project heavily relies on [Playwright](https://playwright.dev/) as a resilient backbone to automate the web. It also would not be possible without the awesome techniques and discoveries made by [tarsier](https://github.com/reworkd/tarsier), and [fuji-web](https://github.com/normal-computing/fuji-web).
 
 [Jeremy Press](https://x.com/jeremypress) wrote the original MVP of Stagehand and continues to be a major ally to the project.
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Page, BrowserContext } from '@playwright/test';
 import { z } from 'zod';
+import { Browserbase } from '@browserbasehq/sdk';
 
 interface ChatMessage {
     role: "system" | "user" | "assistant";
@@ -40,21 +41,25 @@ type AvailableModel = "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-08-06" | "claude-3
 declare class LLMProvider {
     private modelToProviderMap;
     private logger;
+    private enableCaching;
+    private cache;
     constructor(logger: (message: {
         category?: string;
         message: string;
-    }) => void);
-    getClient(modelName: AvailableModel): LLMClient;
+    }) => void, enableCaching: boolean);
+    cleanRequestCache(requestId: string): void;
+    getClient(modelName: AvailableModel, requestId: string): LLMClient;
 }
 
 declare class Stagehand {
     private llmProvider;
     private observations;
     private actions;
-    private id;
     page: Page;
     context: BrowserContext;
     private env;
+    private apiKey;
+    private projectId;
     private verbose;
     private debugDom;
     private defaultModelName;
@@ -62,8 +67,13 @@ declare class Stagehand {
     private logger;
     private externalLogger?;
     private domSettleTimeoutMs;
-    constructor({ env, verbose, debugDom, llmProvider, headless, logger, domSettleTimeoutMs, }?: {
+    private browserBaseSessionCreateParams?;
+    private enableCaching;
+    private browserbaseResumeSessionID?;
+    constructor({ env, apiKey, projectId, verbose, debugDom, llmProvider, headless, logger, browserBaseSessionCreateParams, domSettleTimeoutMs, enableCaching, browserbaseResumeSessionID, }?: {
         env: "LOCAL" | "BROWSERBASE";
+        apiKey?: string;
+        projectId?: string;
         verbose?: 0 | 1 | 2;
         debugDom?: boolean;
         llmProvider?: LLMProvider;
@@ -74,6 +84,9 @@ declare class Stagehand {
             level?: 0 | 1 | 2;
         }) => void;
         domSettleTimeoutMs?: number;
+        browserBaseSessionCreateParams?: Browserbase.Sessions.SessionCreateParams;
+        enableCaching?: boolean;
+        browserbaseResumeSessionID?: string;
     });
     init({ modelName, }?: {
         modelName?: AvailableModel;
@@ -81,6 +94,9 @@ declare class Stagehand {
         debugUrl: string;
         sessionUrl: string;
     }>;
+    initFromPage(page: Page, modelName?: AvailableModel): Promise<{
+        context: BrowserContext;
+    }>;
     private pending_logs_to_send_to_browserbase;
     private is_processing_browserbase_logs;
     log({ message, category, level, }: {

package/dist/index.js

@@ -84,6 +84,7 @@ module.exports = __toCommonJS(lib_exports);
 var import_test = require("@playwright/test");
 var import_crypto = __toESM(require("crypto"));
 var import_fs2 = __toESM(require("fs"));
+var import_sdk2 = require("@browserbasehq/sdk");
 
 // lib/prompt.ts
 var actSystemPrompt = `
@@ -283,8 +284,10 @@ var metadataSystemPrompt = `You are an AI assistant tasked with evaluating the p
 Analyze the extraction response and determine if the task is completed or if more information is needed.
 
 Strictly abide by the following criteria:
-1. If you are certain that the instruction is completed, set the completion status to true, even if there are still chunks left.
-2. If there could still be more information to extract and there are still chunks left, set the completion status to false.`;
+1. Once the instruction has been satisfied by the current extraction response, ALWAYS set completion status to true and stop processing, regardless of remaining chunks.
+2. Only set completion status to false if BOTH of these conditions are true:
+   - The instruction has not been satisfied yet
+   - There are still chunks left to process (chunksTotal > chunksSeen)`;
 function buildMetadataSystemPrompt() {
   return {
     role: "system",
@@ -296,8 +299,8 @@ function buildMetadataPrompt(instruction, extractionResponse, chunksSeen, chunks
     role: "user",
     content: `Instruction: ${instruction}
 Extracted content: ${JSON.stringify(extractionResponse, null, 2)}
-Chunks seen: ${chunksSeen}
-Chunks total: ${chunksTotal}`
+chunksSeen: ${chunksSeen}
+chunksTotal: ${chunksTotal}`
   };
 }
 var observeSystemPrompt = `
@@ -332,6 +335,7 @@ var modelsWithVision = [
   "gpt-4o-mini",
   "claude-3-5-sonnet-latest",
   "claude-3-5-sonnet-20240620",
+  "claude-3-5-sonnet-20241022",
   "gpt-4o-2024-08-06"
 ];
 var AnnotatedScreenshotText = "This is a screenshot of the current page state with the elements annotated on it. Each element id is annotated with a number to the top left of it. Duplicate annotations at the same location are under each other vertically.";
@@ -345,9 +349,10 @@ function verifyActCompletion(_0) {
     modelName,
     screenshot,
     domElements,
-    logger
+    logger,
+    requestId
   }) {
-    const llmClient = llmProvider.getClient(modelName);
+    const llmClient = llmProvider.getClient(modelName, requestId);
     const messages = [
       buildVerifyActCompletionSystemPrompt(),
       buildVerifyActCompletionUserPrompt(goal, steps, domElements)
@@ -396,9 +401,10 @@ function act(_0) {
     modelName,
     screenshot,
     retries = 0,
-    logger
+    logger,
+    requestId
   }) {
-    const llmClient = llmProvider.getClient(modelName);
+    const llmClient = llmProvider.getClient(modelName, requestId);
     const messages = [
       buildActSystemPrompt(),
       buildActUserPrompt(action, steps, domElements)
@@ -435,7 +441,8 @@ function act(_0) {
         llmProvider,
         modelName,
         retries: retries + 1,
-        logger
+        logger,
+        requestId
       });
     }
   });
@@ -450,9 +457,10 @@ function extract(_0) {
     llmProvider,
     modelName,
     chunksSeen,
-    chunksTotal
+    chunksTotal,
+    requestId
   }) {
-    const llmClient = llmProvider.getClient(modelName);
+    const llmClient = llmProvider.getClient(modelName, requestId);
     const extractionResponse = yield llmClient.createChatCompletion({
       model: modelName,
       messages: [
@@ -525,7 +533,8 @@ function observe(_0) {
     domElements,
     llmProvider,
     modelName,
-    image
+    image,
+    requestId
   }) {
     const observeSchema = import_zod.z.object({
       elements: import_zod.z.array(
@@ -537,7 +546,7 @@ function observe(_0) {
         })
       ).describe("an array of elements that match the instruction")
     });
-    const llmClient = llmProvider.getClient(modelName);
+    const llmClient = llmProvider.getClient(modelName, requestId);
     const observationResponse = yield llmClient.createChatCompletion({
       model: modelName,
       messages: [
@@ -565,12 +574,31 @@ function observe(_0) {
 var import_openai = __toESM(require("openai"));
 var import_zod2 = require("openai/helpers/zod");
 var OpenAIClient = class {
-  constructor(logger) {
+  constructor(logger, enableCaching = false, cache, requestId) {
     this.client = new import_openai.default();
     this.logger = logger;
+    this.requestId = requestId;
+    this.cache = cache;
+    this.enableCaching = enableCaching;
   }
   createChatCompletion(options) {
     return __async(this, null, function* () {
+      const cacheOptions = {
+        model: options.model,
+        messages: options.messages,
+        temperature: options.temperature,
+        top_p: options.top_p,
+        frequency_penalty: options.frequency_penalty,
+        presence_penalty: options.presence_penalty,
+        image: options.image,
+        response_model: options.response_model
+      };
+      if (this.enableCaching) {
+        const cachedResponse = yield this.cache.get(cacheOptions, this.requestId);
+        if (cachedResponse) {
+          return cachedResponse;
+        }
+      }
       if (options.image) {
         const screenshotMessage = {
           role: "user",
@@ -600,8 +628,18 @@ var OpenAIClient = class {
       if (response_model) {
         const extractedData = response.choices[0].message.content;
         const parsedData = JSON.parse(extractedData);
+        if (this.enableCaching) {
+          this.cache.set(
+            cacheOptions,
+            __spreadValues({}, parsedData),
+            this.requestId
+          );
+        }
         return __spreadValues({}, parsedData);
       }
+      if (this.enableCaching) {
+        this.cache.set(cacheOptions, response, this.requestId);
+      }
       return response;
     });
   }
@@ -611,16 +649,33 @@ var OpenAIClient = class {
 var import_sdk = __toESM(require("@anthropic-ai/sdk"));
 var import_zod_to_json_schema = require("zod-to-json-schema");
 var AnthropicClient = class {
-  constructor(logger) {
+  constructor(logger, enableCaching = false, cache, requestId) {
     this.client = new import_sdk.default({
       apiKey: process.env.ANTHROPIC_API_KEY
-      // Make sure to set this environment variable
     });
     this.logger = logger;
+    this.cache = cache;
+    this.enableCaching = enableCaching;
+    this.requestId = requestId;
   }
   createChatCompletion(options) {
     return __async(this, null, function* () {
       var _a, _b, _c, _d, _e, _f, _g;
+      const cacheOptions = {
+        model: options.model,
+        messages: options.messages,
+        temperature: options.temperature,
+        image: options.image,
+        response_model: options.response_model,
+        tools: options.tools,
+        retries: options.retries
+      };
+      if (this.enableCaching) {
+        const cachedResponse = yield this.cache.get(cacheOptions, this.requestId);
+        if (cachedResponse) {
+          return cachedResponse;
+        }
+      }
       const systemMessage = options.messages.find((msg) => msg.role === "system");
       const userMessages = options.messages.filter(
         (msg) => msg.role !== "system"
@@ -722,26 +777,318 @@ var AnthropicClient = class {
       if (options.response_model) {
         const toolUse = response.content.find((c) => c.type === "tool_use");
         if (toolUse && "input" in toolUse) {
-          return toolUse.input;
+          const result = toolUse.input;
+          if (this.enableCaching) {
+            this.cache.set(cacheOptions, result, this.requestId);
+          }
+          return result;
         } else {
-          if (!options.retries || options.retries < 2) {
+          if (!options.retries || options.retries < 5) {
             return this.createChatCompletion(__spreadProps(__spreadValues({}, options), {
               retries: ((_g = options.retries) != null ? _g : 0) + 1
             }));
           }
           throw new Error(
-            "Extraction failed: No tool use with input in response"
+            "Create Chat Completion Failed: No tool use with input in response"
           );
         }
       }
+      if (this.enableCaching) {
+        this.cache.set(cacheOptions, transformedResponse, this.requestId);
+      }
       return transformedResponse;
     });
   }
 };
 
+// lib/llm/LLMCache.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
+var LLMCache = class {
+  constructor(logger, cacheDir = path.join(process.cwd(), "tmp", ".cache"), cacheFile = "llm_calls.json") {
+    this.CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+    // 1 week in milliseconds
+    this.CLEANUP_PROBABILITY = 0.01;
+    // 1% chance
+    this.LOCK_TIMEOUT_MS = 1e3;
+    this.lock_acquired = false;
+    this.count_lock_acquire_failures = 0;
+    this.request_id_to_used_hashes = {};
+    this.logger = logger;
+    this.cacheDir = cacheDir;
+    this.cacheFile = path.join(cacheDir, cacheFile);
+    this.lockFile = path.join(cacheDir, "llm_cache.lock");
+    this.ensureCacheDirectory();
+    this.setupProcessHandlers();
+  }
+  setupProcessHandlers() {
+    const releaseLockAndExit = () => {
+      this.releaseLock();
+      process.exit();
+    };
+    process.on("exit", releaseLockAndExit);
+    process.on("SIGINT", releaseLockAndExit);
+    process.on("SIGTERM", releaseLockAndExit);
+    process.on("uncaughtException", (err) => {
+      this.logger({
+        category: "llm_cache",
+        message: `Uncaught exception: ${err}`,
+        level: 2
+      });
+      if (this.lock_acquired) {
+        releaseLockAndExit();
+      }
+    });
+  }
+  ensureCacheDirectory() {
+    if (!fs.existsSync(this.cacheDir)) {
+      fs.mkdirSync(this.cacheDir, { recursive: true });
+    }
+  }
+  createHash(data) {
+    const hash = crypto.createHash("sha256");
+    return hash.update(JSON.stringify(data)).digest("hex");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  acquireLock() {
+    return __async(this, null, function* () {
+      const startTime = Date.now();
+      while (Date.now() - startTime < this.LOCK_TIMEOUT_MS) {
+        try {
+          if (fs.existsSync(this.lockFile)) {
+            const lockAge = Date.now() - fs.statSync(this.lockFile).mtimeMs;
+            if (lockAge > this.LOCK_TIMEOUT_MS) {
+              fs.unlinkSync(this.lockFile);
+            }
+          }
+          fs.writeFileSync(this.lockFile, process.pid.toString(), { flag: "wx" });
+          this.count_lock_acquire_failures = 0;
+          this.lock_acquired = true;
+          return true;
+        } catch (error) {
+          yield this.sleep(5);
+        }
+      }
+      this.logger({
+        category: "llm_cache",
+        message: "Failed to acquire lock after timeout",
+        level: 2
+      });
+      this.count_lock_acquire_failures++;
+      if (this.count_lock_acquire_failures >= 3) {
+        this.logger({
+          category: "llm_cache",
+          message: "Failed to acquire lock 3 times in a row. Releasing lock manually.",
+          level: 1
+        });
+        this.releaseLock();
+      }
+      return false;
+    });
+  }
+  releaseLock() {
+    try {
+      if (fs.existsSync(this.lockFile)) {
+        fs.unlinkSync(this.lockFile);
+      }
+      this.lock_acquired = false;
+    } catch (error) {
+      this.logger({
+        category: "llm_cache",
+        message: `Error releasing lock: ${error}`,
+        level: 2
+      });
+    }
+  }
+  readCache() {
+    if (fs.existsSync(this.cacheFile)) {
+      return JSON.parse(fs.readFileSync(this.cacheFile, "utf-8"));
+    }
+    return {};
+  }
+  writeCache(cache) {
+    try {
+      if (Math.random() < this.CLEANUP_PROBABILITY) {
+        this.cleanupStaleEntries(cache);
+      }
+      fs.writeFileSync(this.cacheFile, JSON.stringify(cache, null, 2));
+    } finally {
+      this.releaseLock();
+    }
+  }
+  cleanupStaleEntries(cache) {
+    if (!this.acquireLock()) {
+      this.logger({
+        category: "llm_cache",
+        message: "Failed to acquire lock for cleaning up cache",
+        level: 2
+      });
+      return;
+    }
+    try {
+      const now = Date.now();
+      let entriesRemoved = 0;
+      for (const [hash, entry] of Object.entries(cache)) {
+        if (now - entry.timestamp > this.CACHE_MAX_AGE_MS) {
+          delete cache[hash];
+          entriesRemoved++;
+        }
+      }
+      if (entriesRemoved > 0) {
+        this.logger({
+          category: "llm_cache",
+          message: `Cleaned up ${entriesRemoved} stale cache entries`,
+          level: 1
+        });
+      }
+    } catch (error) {
+      this.logger({
+        category: "llm_cache",
+        message: `Error cleaning up stale cache entries: ${error}`,
+        level: 1
+      });
+    } finally {
+      this.releaseLock();
+    }
+  }
+  resetCache() {
+    if (!this.acquireLock()) {
+      this.logger({
+        category: "llm_cache",
+        message: "Failed to acquire lock for resetting cache",
+        level: 2
+      });
+      return;
+    }
+    try {
+      this.ensureCacheDirectory();
+      fs.writeFileSync(this.cacheFile, "{}");
+    } finally {
+      this.releaseLock();
+    }
+  }
+  get(options, requestId) {
+    return __async(this, null, function* () {
+      var _a, _b;
+      if (!(yield this.acquireLock())) {
+        this.logger({
+          category: "llm_cache",
+          message: "Failed to acquire lock for getting cache",
+          level: 2
+        });
+        return null;
+      }
+      try {
+        const hash = this.createHash(options);
+        const cache = this.readCache();
+        if (cache[hash]) {
+          this.logger({
+            category: "llm_cache",
+            message: "Cache hit",
+            level: 1
+          });
+          (_b = (_a = this.request_id_to_used_hashes)[requestId]) != null ? _b : _a[requestId] = [];
+          this.request_id_to_used_hashes[requestId].push(hash);
+          return cache[hash].response;
+        }
+        return null;
+      } catch (error) {
+        this.logger({
+          category: "llm_cache",
+          message: `Error getting cache: ${error}. Resetting cache.`,
+          level: 1
+        });
+        this.resetCache();
+        return null;
+      } finally {
+        this.releaseLock();
+      }
+    });
+  }
+  deleteCacheForRequestId(requestId) {
+    return __async(this, null, function* () {
+      var _a;
+      if (!(yield this.acquireLock())) {
+        this.logger({
+          category: "llm_cache",
+          message: "Failed to acquire lock for deleting cache",
+          level: 2
+        });
+        return;
+      }
+      try {
+        const cache = this.readCache();
+        let entriesRemoved = [];
+        for (const hash of (_a = this.request_id_to_used_hashes[requestId]) != null ? _a : []) {
+          if (cache[hash]) {
+            entriesRemoved.push(cache[hash]);
+            delete cache[hash];
+          }
+        }
+        this.logger({
+          category: "llm_cache",
+          message: `Deleted ${entriesRemoved.length} cache entries for requestId ${requestId}`,
+          level: 1
+        });
+        this.writeCache(cache);
+      } catch (exception) {
+        this.logger({
+          category: "llm_cache",
+          message: `Error deleting cache for requestId ${requestId}: ${exception}`,
+          level: 1
+        });
+      } finally {
+        this.releaseLock();
+      }
+    });
+  }
+  set(options, response, requestId) {
+    return __async(this, null, function* () {
+      var _a, _b;
+      if (!(yield this.acquireLock())) {
+        this.logger({
+          category: "llm_cache",
+          message: "Failed to acquire lock for setting cache",
+          level: 2
+        });
+        return;
+      }
+      try {
+        const hash = this.createHash(options);
+        const cache = this.readCache();
+        cache[hash] = {
+          response,
+          timestamp: Date.now(),
+          requestId
+        };
+        this.writeCache(cache);
+        (_b = (_a = this.request_id_to_used_hashes)[requestId]) != null ? _b : _a[requestId] = [];
+        this.request_id_to_used_hashes[requestId].push(hash);
+        this.logger({
+          category: "llm_cache",
+          message: "Cache miss - saved new response",
+          level: 1
+        });
+      } catch (error) {
+        this.logger({
+          category: "llm_cache",
+          message: `Error setting cache: ${error}. Resetting cache.`,
+          level: 1
+        });
+        this.resetCache();
+      } finally {
+        this.releaseLock();
+      }
+    });
+  }
+};
+
 // lib/llm/LLMProvider.ts
 var LLMProvider = class {
-  constructor(logger) {
+  constructor(logger, enableCaching) {
     this.modelToProviderMap = {
       "gpt-4o": "openai",
       "gpt-4o-mini": "openai",
@@ -751,71 +1098,44 @@ var LLMProvider = class {
       "claude-3-5-sonnet-20241022": "anthropic"
     };
     this.logger = logger;
+    this.enableCaching = enableCaching;
+    this.cache = new LLMCache(logger);
+  }
+  cleanRequestCache(requestId) {
+    this.logger({
+      category: "llm_cache",
+      message: `Cleaning up cache for requestId: ${requestId}`
+    });
+    this.cache.deleteCacheForRequestId(requestId);
   }
-  getClient(modelName) {
+  getClient(modelName, requestId) {
     const provider = this.modelToProviderMap[modelName];
     if (!provider) {
       throw new Error(`Unsupported model: ${modelName}`);
     }
     switch (provider) {
       case "openai":
-        return new OpenAIClient(this.logger);
+        return new OpenAIClient(
+          this.logger,
+          this.enableCaching,
+          this.cache,
+          requestId
+        );
       case "anthropic":
-        return new AnthropicClient(this.logger);
+        return new AnthropicClient(
+          this.logger,
+          this.enableCaching,
+          this.cache,
+          requestId
+        );
       default:
         throw new Error(`Unsupported provider: ${provider}`);
     }
   }
 };
 
-// lib/browserbase.ts
-var Browserbase = class {
-  createSession() {
-    return __async(this, null, function* () {
-      if (!process.env.BROWSERBASE_API_KEY || !process.env.BROWSERBASE_PROJECT_ID) {
-        throw new Error(
-          "BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID must be set"
-        );
-      }
-      const response = yield fetch(`https://www.browserbase.com/v1/sessions`, {
-        method: "POST",
-        headers: {
-          "x-bb-api-key": `${process.env.BROWSERBASE_API_KEY}`,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify({
-          projectId: process.env.BROWSERBASE_PROJECT_ID
-        })
-      });
-      const json = yield response.json();
-      if (json.error) {
-        throw new Error(json.error);
-      }
-      return {
-        sessionId: json.id,
-        connectUrl: json.connectUrl
-      };
-    });
-  }
-  retrieveDebugConnectionURL(sessionId) {
-    return __async(this, null, function* () {
-      if (!process.env.BROWSERBASE_API_KEY) {
-        throw new Error("BROWSERBASE_API_KEY must be set");
-      }
-      const response = yield fetch(
-        `https://www.browserbase.com/v1/sessions/${sessionId}/debug`,
-        {
-          method: "GET",
-          headers: {
-            "x-bb-api-key": `${process.env.BROWSERBASE_API_KEY}`
-          }
-        }
-      );
-      const json = yield response.json();
-      return json.debuggerFullscreenUrl;
-    });
-  }
-};
+// lib/index.ts
+var import_path2 = __toESM(require("path"));
 
 // lib/vision.ts
 var import_fs = __toESM(require("fs"));
@@ -999,40 +1319,85 @@ var ScreenshotService = class _ScreenshotService {
 
 // lib/index.ts
 require("dotenv").config({ path: ".env" });
-function getBrowser(env = "LOCAL", headless = false, logger) {
+function getBrowser(apiKey, projectId, env = "LOCAL", headless = false, logger, browserbaseSessionCreateParams, browserbaseResumeSessionID) {
   return __async(this, null, function* () {
-    if (env === "BROWSERBASE" && !process.env.BROWSERBASE_API_KEY) {
-      logger({
-        category: "Init",
-        message: "BROWSERBASE_API_KEY is required to use BROWSERBASE env. Defaulting to LOCAL.",
-        level: 0
-      });
-      env = "LOCAL";
-    }
-    if (env === "BROWSERBASE" && !process.env.BROWSERBASE_PROJECT_ID) {
-      logger({
-        category: "Init",
-        message: "BROWSERBASE_PROJECT_ID is required to use BROWSERBASE env. Defaulting to LOCAL.",
-        level: 0
-      });
-      env = "LOCAL";
+    if (env === "BROWSERBASE") {
+      if (!apiKey) {
+        logger({
+          category: "Init",
+          message: "BROWSERBASE_API_KEY is required to use BROWSERBASE env. Defaulting to LOCAL.",
+          level: 0
+        });
+        env = "LOCAL";
+      }
+      if (!projectId) {
+        logger({
+          category: "Init",
+          message: "BROWSERBASE_PROJECT_ID is required for some Browserbase features that may not work without it.",
+          level: 1
+        });
+      }
     }
     if (env === "BROWSERBASE") {
+      if (!apiKey) {
+        throw new Error("BROWSERBASE_API_KEY is required.");
+      }
       let debugUrl = void 0;
       let sessionUrl = void 0;
-      logger({
-        category: "Init",
-        message: "Connecting you to Browserbase...",
-        level: 0
+      let sessionId;
+      let connectUrl;
+      const browserbase = new import_sdk2.Browserbase({
+        apiKey
       });
-      const browserbase = new Browserbase();
-      const { sessionId, connectUrl } = yield browserbase.createSession();
+      if (browserbaseResumeSessionID) {
+        try {
+          const sessionStatus = yield browserbase.sessions.retrieve(
+            browserbaseResumeSessionID
+          );
+          if (sessionStatus.status !== "RUNNING") {
+            throw new Error(
+              `Session ${browserbaseResumeSessionID} is not running (status: ${sessionStatus.status})`
+            );
+          }
+          sessionId = browserbaseResumeSessionID;
+          connectUrl = `wss://connect.browserbase.com?apiKey=${apiKey}&sessionId=${sessionId}`;
+          logger({
+            category: "Init",
+            message: "Resuming existing Browserbase session...",
+            level: 0
+          });
+        } catch (error) {
+          logger({
+            category: "Init",
+            message: `Failed to resume session ${browserbaseResumeSessionID}: ${error.message}`,
+            level: 0
+          });
+          throw error;
+        }
+      } else {
+        logger({
+          category: "Init",
+          message: "Creating new Browserbase session...",
+          level: 0
+        });
+        if (!projectId) {
+          throw new Error(
+            "BROWSERBASE_PROJECT_ID is required for new Browserbase sessions."
+          );
+        }
+        const session = yield browserbase.sessions.create(__spreadValues({
+          projectId
+        }, browserbaseSessionCreateParams));
+        sessionId = session.id;
+        connectUrl = session.connectUrl;
+      }
       const browser = yield import_test.chromium.connectOverCDP(connectUrl);
-      debugUrl = yield browserbase.retrieveDebugConnectionURL(sessionId);
+      const { debuggerUrl } = yield browserbase.sessions.debug(sessionId);
+      debugUrl = debuggerUrl;
       sessionUrl = `https://www.browserbase.com/sessions/${sessionId}`;
       logger({
         category: "Init",
-        message: `Browserbase session started.
+        message: `Browserbase session ${browserbaseResumeSessionID ? "resumed" : "started"}.
 
 Session Url: ${sessionUrl}
 
@@ -1119,12 +1484,17 @@ function applyStealthScripts(context) {
 var Stagehand = class {
   constructor({
     env,
-    verbose = 0,
-    debugDom = false,
+    apiKey,
+    projectId,
+    verbose,
+    debugDom,
     llmProvider,
-    headless = false,
+    headless,
     logger,
-    domSettleTimeoutMs = 6e4
+    browserBaseSessionCreateParams,
+    domSettleTimeoutMs,
+    enableCaching,
+    browserbaseResumeSessionID
   } = {
     env: "BROWSERBASE"
   }) {
@@ -1133,24 +1503,33 @@ var Stagehand = class {
     this.is_processing_browserbase_logs = false;
     this.externalLogger = logger;
     this.logger = this.log.bind(this);
-    this.llmProvider = llmProvider || new LLMProvider(this.logger);
+    this.enableCaching = enableCaching != null ? enableCaching : false;
+    this.llmProvider = llmProvider || new LLMProvider(this.logger, this.enableCaching);
     this.env = env;
     this.observations = {};
+    this.apiKey = apiKey;
+    this.projectId = projectId;
     this.actions = {};
-    this.verbose = verbose;
-    this.debugDom = debugDom;
+    this.verbose = verbose != null ? verbose : 0;
+    this.debugDom = debugDom != null ? debugDom : false;
     this.defaultModelName = "gpt-4o";
-    this.headless = headless;
-    this.domSettleTimeoutMs = domSettleTimeoutMs;
+    this.domSettleTimeoutMs = domSettleTimeoutMs != null ? domSettleTimeoutMs : 6e4;
+    this.headless = headless != null ? headless : false;
+    this.browserBaseSessionCreateParams = browserBaseSessionCreateParams;
+    this.browserbaseResumeSessionID = browserbaseResumeSessionID;
   }
   init() {
     return __async(this, arguments, function* ({
       modelName = "gpt-4o"
     } = {}) {
       const { context, debugUrl, sessionUrl } = yield getBrowser(
+        this.apiKey,
+        this.projectId,
         this.env,
         this.headless,
-        this.logger
+        this.logger,
+        this.browserBaseSessionCreateParams,
+        this.browserbaseResumeSessionID
       ).catch((e) => {
         console.error("Error in init:", e);
         return { context: void 0, debugUrl: void 0, sessionUrl: void 0 };
@@ -1169,11 +1548,44 @@ var Stagehand = class {
         yield this.page.setViewportSize({ width: 1280, height: 720 });
       }
       yield this.page.addInitScript({
-        content: '(()=>{var B=Object.defineProperty;var M=Object.getOwnPropertySymbols;var I=Object.prototype.hasOwnProperty,V=Object.prototype.propertyIsEnumerable;var $=(e,t,o)=>t in e?B(e,t,{enumerable:!0,configurable:!0,writable:!0,value:o}):e[t]=o,x=(e,t)=>{for(var o in t||(t={}))I.call(t,o)&&$(e,o,t[o]);if(M)for(var o of M(t))V.call(t,o)&&$(e,o,t[o]);return e};var d=(e,t,o)=>new Promise((n,s)=>{var c=a=>{try{l(o.next(a))}catch(u){s(u)}},i=a=>{try{l(o.throw(a))}catch(u){s(u)}},l=a=>a.done?n(a.value):Promise.resolve(a.value).then(c,i);l((o=o.apply(e,t)).next())});function _(e){return d(this,null,function*(){let{chunk:t,chunksArray:o}=yield Q(e),{outputString:n,selectorMap:s}=yield C(t);return console.log(`Stagehand (Browser Process): Extracted dom elements:${n}`),{outputString:n,selectorMap:s,chunk:t,chunks:o}})}function F(){return d(this,null,function*(){console.log("Stagehand (Browser Process): Processing all of DOM");let e=window.innerHeight,t=document.documentElement.scrollHeight,o=Math.ceil(t/e),n=0,s=[];for(let l=0;l<o;l++){let a=yield C(l,!0,n);s.push(a),n+=Object.keys(a.selectorMap).length}yield k(0);let c=s.map(l=>l.outputString).join(""),i=s.reduce((l,a)=>x(x({},l),a.selectorMap),{});return console.log(`Stagehand (Browser Process): All dom elements: ${c}`),{outputString:c,selectorMap:i}})}function k(e){return d(this,null,function*(){window.scrollTo({top:e,left:0,behavior:"smooth"}),yield new Promise(t=>{let o,n=()=>{clearTimeout(o),o=window.setTimeout(()=>{window.removeEventListener("scroll",n),t()},200)};window.addEventListener("scroll",n,{passive:!0}),n()})})}function C(e,t=!0,o=0){return d(this,null,function*(){console.time("processElements:total");let s=window.innerHeight*e,c=document.documentElement.scrollHeight-window.innerHeight,i=Math.min(s,c);t&&(console.time("processElements:scroll"),yield k(i),console.timeEnd("processElements:scroll"));let l=[],a=[...document.body.childNodes],u=new Map;for(console.log("Stagehand (Browser Process): Generating candidate elements"),console.time("processElements:findCandidates");a.length>0;){let r=a.pop(),h=!1;if(r&&b(r)){let p=r.childNodes.length;for(let w=p-1;w>=0;w--){let E=r.childNodes[w];a.push(E)}J(r)&&D(r)&&H(r)&&(h=!0),K(r)&&D(r)&&H(r)&&(h=!0)}r&&y(r)&&G(r)&&(h=!0),h&&l.push(r)}console.timeEnd("processElements:findCandidates");let m={},g="";return console.log(`Stagehand (Browser Process): Processing candidate elements: ${l.length}`),console.time("processElements:processCandidates"),l.forEach((r,h)=>{var w,E;let p=u.get(r);if(p||(p=j(r),u.set(r,p)),y(r)){let f=(w=r.textContent)==null?void 0:w.trim();f&&(g+=`${h+o}:${f}`)}else if(b(r)){let f=r.tagName.toLowerCase(),A=X(r),L=`<${f}${A?" "+A:""}>`,P=`</${f}>`,O=((E=r.textContent)==null?void 0:E.trim())||"";g+=`${h+o}:${L}${O}${P}`}m[h+o]=p}),console.timeEnd("processElements:processCandidates"),console.timeEnd("processElements:total"),{outputString:g,selectorMap:m}})}function X(e){let o=["id","class","href","src","aria-label","aria-name","aria-role","aria-description","aria-expanded","aria-haspopup"].map(n=>{let s=e.getAttribute(n);return s?`${n}="${s}"`:""}).filter(n=>n!=="");return Array.from(e.attributes).forEach(n=>{n.name.startsWith("data-")&&o.push(`${n.name}="${n.value}"`)}),o.join(" ")}window.processDom=_;window.processAllOfDom=F;window.processElements=C;window.scrollToHeight=k;function j(e){if(b(e)&&e.id)return`//*[@id="${e.id}"]`;let t=[];for(;e&&(y(e)||b(e));){let o=0,n=!1,s=e.parentElement?Array.from(e.parentElement.childNodes):[];for(let c=0;c<s.length;c++){let i=s[c];if(i.nodeType===e.nodeType&&i.nodeName===e.nodeName&&(o=o+1,n=!0,i.isSameNode(e)))break}if(e.nodeName!=="#text"){let c=e.nodeName.toLowerCase(),i=n?`[${o}]`:"";t.unshift(`${c}${i}`)}e=e.parentElement}return t.length?`/${t.join("/")}`:""}var U=["SVG","IFRAME","SCRIPT","STYLE","LINK"],Y=["A","BUTTON","DETAILS","EMBED","INPUT","LABEL","MENU","MENUITEM","OBJECT","SELECT","TEXTAREA","SUMMARY"],z=["button","menu","menuitem","link","checkbox","radio","slider","tab","tabpanel","textbox","combobox","grid","listbox","option","progressbar","scrollbar","searchbox","switch","tree","treeitem","spinbutton","tooltip"],q=["menu","menuitem","button"];function b(e){return e.nodeType===Node.ELEMENT_NODE}function y(e){var o;let t=(o=e.textContent)==null?void 0:o.trim().replace(/s/g,"");return e.nodeType===Node.TEXT_NODE&&t!==""}var H=e=>{let t=e.getBoundingClientRect();return t.width===0||t.height===0||t.top<0||t.top>window.innerHeight||!R(e,t)?!1:e.checkVisibility({checkOpacity:!0,checkVisibilityCSS:!0})},G=e=>{let t=document.createRange();t.selectNodeContents(e);let o=t.getBoundingClientRect();if(o.width===0||o.height===0||o.top<0||o.top>window.innerHeight)return!1;let n=e.parentElement;return!n||!R(n,o)?!1:n.checkVisibility({checkOpacity:!0,checkVisibilityCSS:!0})};function R(e,t){return[{x:t.left+t.width*.25,y:t.top+t.height*.25},{x:t.left+t.width*.75,y:t.top+t.height*.25},{x:t.left+t.width*.25,y:t.top+t.height*.75},{x:t.left+t.width*.75,y:t.top+t.height*.75},{x:t.left+t.width/2,y:t.top+t.height/2}].some(n=>{let c=document.elementFromPoint(n.x,n.y);for(;c&&c!==document.body;){if(c.isSameNode(e))return!0;c=c.parentElement}return!1})}var D=e=>!(e.hasAttribute("disabled")||e.hasAttribute("hidden")||e.getAttribute("aria-disabled")==="true"),J=e=>{let t=e.tagName,o=e.getAttribute("role"),n=e.getAttribute("aria-role");return t&&Y.includes(t)||o&&z.includes(o)||n&&q.includes(n)},K=e=>e.textContent===""?!1:e.childNodes.length===0?!U.includes(e.tagName):!!(e.childNodes.length===1&&y(e.childNodes[0]));function Q(e){return d(this,null,function*(){let t=window.innerHeight,o=document.documentElement.scrollHeight,n=Math.ceil(o/t),s=Array.from({length:n},(u,m)=>m),c=s.filter(u=>!e.includes(u)),i=window.scrollY,a=c.reduce((u,m)=>{let g=t*m,r=t*u;return Math.abs(i-g)<Math.abs(i-r)?m:u},c[0]);if(a===void 0)throw new Error(`No chunks remaining to check: ${c}`);return{chunk:a,chunksArray:s}})}function W(){return d(this,null,function*(){return new Promise(e=>{let t=()=>setTimeout(()=>{e()},2e3),o=t();new MutationObserver(()=>{clearTimeout(o),o=t()}).observe(window.document.body,{childList:!0,subtree:!0})})})}window.waitForDomSettle=W;function Z(){return d(this,null,function*(){window.chunkNumber=0;let{selectorMap:e,outputString:t}=yield window.processElements(window.chunkNumber);T(e),S()})}function T(e){N(),Object.entries(e).forEach(([t,o])=>{let n=document.evaluate(o,document,null,XPathResult.FIRST_ORDERED_NODE_TYPE,null).singleNodeValue;if(n){let s;if(n.nodeType===Node.ELEMENT_NODE)s=n.getBoundingClientRect();else{let l=document.createRange();l.selectNodeContents(n),s=l.getBoundingClientRect()}let c="grey",i=document.createElement("div");i.style.position="absolute",i.style.left=`${s.left+window.scrollX}px`,i.style.top=`${s.top+window.scrollY}px`,i.style.padding="2px",i.style.width=`${s.width}px`,i.style.height=`${s.height}px`,i.style.backgroundColor=c,i.className="stagehand-marker",i.style.opacity="0.3",i.style.zIndex="1000000000",i.style.border="1px solid",i.style.pointerEvents="none",document.body.appendChild(i)}})}function ee(){return d(this,null,function*(){N(),v()})}function N(){document.querySelectorAll(".stagehand-marker").forEach(t=>{t.remove()})}function v(){document.querySelectorAll(".stagehand-nav").forEach(t=>{t.remove()})}function S(){let e=window.innerHeight,t=document.documentElement.scrollHeight,o=Math.ceil(t/e);if(window.chunkNumber>0){let n=document.createElement("button");n.className="stagehand-nav",n.textContent="Previous",n.style.marginLeft="50px",n.style.position="fixed",n.style.bottom="10px",n.style.left="50%",n.style.transform="translateX(-50%)",n.style.zIndex="1000000000",n.onclick=()=>d(this,null,function*(){N(),v(),window.chunkNumber-=1,window.scrollTo(0,window.chunkNumber*window.innerHeight),yield window.waitForDomSettle();let{selectorMap:s}=yield processElements(window.chunkNumber);T(s),S()}),document.body.appendChild(n)}if(o>window.chunkNumber){let n=document.createElement("button");n.className="stagehand-nav",n.textContent="Next",n.style.marginRight="50px",n.style.position="fixed",n.style.bottom="10px",n.style.right="50%",n.style.transform="translateX(50%)",n.style.zIndex="1000000000",n.onclick=()=>d(this,null,function*(){N(),v(),window.chunkNumber+=1,window.scrollTo(0,window.chunkNumber*window.innerHeight),yield window.waitForDomSettle();let{selectorMap:s}=yield processElements(window.chunkNumber);T(s),S()}),document.body.appendChild(n)}}window.debugDom=Z;window.cleanupDebug=ee;})();'
+        path: import_path2.default.join(__dirname, "..", "dist", "dom", "build", "process.js")
+      });
+      yield this.page.addInitScript({
+        path: import_path2.default.join(__dirname, "..", "dist", "dom", "build", "utils.js")
+      });
+      yield this.page.addInitScript({
+        path: import_path2.default.join(__dirname, "..", "dist", "dom", "build", "debug.js")
       });
       return { debugUrl, sessionUrl };
     });
   }
+  initFromPage(page, modelName) {
+    return __async(this, null, function* () {
+      this.page = page;
+      this.context = page.context();
+      this.defaultModelName = modelName || this.defaultModelName;
+      const originalGoto = this.page.goto.bind(this.page);
+      this.page.goto = (url, options) => __async(this, null, function* () {
+        const result = yield originalGoto(url, options);
+        yield this.page.waitForLoadState("domcontentloaded");
+        yield this._waitForSettledDom();
+        return result;
+      });
+      if (this.headless) {
+        yield this.page.setViewportSize({ width: 1280, height: 720 });
+      }
+      yield this.page.addInitScript({
+        path: import_path2.default.join(__dirname, "..", "dist", "dom", "build", "process.js")
+      });
+      yield this.page.addInitScript({
+        path: import_path2.default.join(__dirname, "..", "dist", "dom", "build", "utils.js")
+      });
+      yield this.page.addInitScript({
+        path: import_path2.default.join(__dirname, "..", "dist", "dom", "build", "debug.js")
+      });
+      return { context: this.context };
+    });
+  }
   log({
     message,
     category,
@@ -1233,11 +1645,9 @@ var Stagehand = class {
     return __async(this, null, function* () {
       try {
         const timeout = timeoutMs != null ? timeoutMs : this.domSettleTimeoutMs;
-        const timeoutPromise = new Promise((resolve) => {
-          setTimeout(() => {
-            console.warn(
-              `[stagehand:dom] DOM settle timeout of ${timeout}ms exceeded, continuing anyway`
-            );
+        let timeoutHandle;
+        const timeoutPromise = new Promise((resolve, reject) => {
+          timeoutHandle = setTimeout(() => {
             this.log({
               category: "dom",
               message: `DOM settle timeout of ${timeout}ms exceeded, continuing anyway`,
@@ -1246,16 +1656,12 @@ var Stagehand = class {
             resolve();
           }, timeout);
         });
-        yield Promise.race([
-          (() => __async(this, null, function* () {
-            yield this.page.waitForSelector("body");
-            yield this.page.waitForLoadState("domcontentloaded");
-            yield this.page.evaluate(() => {
+        try {
+          yield Promise.race([
+            this.page.evaluate(() => {
               return new Promise((resolve) => {
                 if (typeof window.waitForDomSettle === "function") {
-                  window.waitForDomSettle().then(() => {
-                    resolve();
-                  });
+                  window.waitForDomSettle().then(resolve);
                 } else {
                   console.warn(
                     "waitForDomSettle is not defined, considering DOM as settled"
@@ -1263,10 +1669,14 @@ var Stagehand = class {
                   resolve();
                 }
               });
-            });
-          }))(),
-          timeoutPromise
-        ]);
+            }),
+            this.page.waitForLoadState("domcontentloaded"),
+            this.page.waitForSelector("body"),
+            timeoutPromise
+          ]);
+        } finally {
+          clearTimeout(timeoutHandle);
+        }
       } catch (e) {
         this.log({
           category: "dom",
@@ -1336,7 +1746,8 @@ Trace: ${e.stack}`,
       progress = "",
       content = {},
       chunksSeen = [],
-      modelName
+      modelName,
+      requestId
     }) {
       this.log({
         category: "extraction",
@@ -1363,7 +1774,8 @@ Trace: ${e.stack}`,
         schema,
         modelName: modelName || this.defaultModelName,
         chunksSeen: chunksSeen.length,
-        chunksTotal: chunks.length
+        chunksTotal: chunks.length,
+        requestId
       });
       const _a = extractionResponse, {
         metadata: { progress: newProgress, completed }
@@ -1407,7 +1819,8 @@ Trace: ${e.stack}`,
       instruction,
       useVision,
       fullPage,
-      modelName
+      modelName,
+      requestId
     }) {
       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.`;
@@ -1447,7 +1860,8 @@ Trace: ${e.stack}`,
         domElements: outputString,
         llmProvider: this.llmProvider,
         modelName: modelName || this.defaultModelName,
-        image: annotatedScreenshot
+        image: annotatedScreenshot,
+        requestId
       });
       const elementsWithSelectors = observationResponse.elements.map(
         (element) => {
@@ -1476,7 +1890,8 @@ Trace: ${e.stack}`,
       modelName,
       useVision,
       verifierUseVision,
-      retries = 0
+      retries = 0,
+      requestId
     }) {
       var _a;
       const model = modelName != null ? modelName : this.defaultModelName;
@@ -1536,7 +1951,8 @@ Trace: ${e.stack}`,
         llmProvider: this.llmProvider,
         modelName: model,
         screenshot: annotatedScreenshot,
-        logger: this.logger
+        logger: this.logger,
+        requestId
       });
       this.log({
         category: "action",
@@ -1558,7 +1974,8 @@ Trace: ${e.stack}`,
             chunksSeen,
             modelName,
             useVision,
-            verifierUseVision
+            verifierUseVision,
+            requestId
           });
         } else if (useVision === "fallback") {
           this.log({
@@ -1573,9 +1990,13 @@ Trace: ${e.stack}`,
             chunksSeen,
             modelName,
             useVision: true,
-            verifierUseVision
+            verifierUseVision,
+            requestId
           });
         } else {
+          if (this.enableCaching) {
+            this.llmProvider.cleanRequestCache(requestId);
+          }
           return {
             success: false,
             message: `Action was not able to be completed.`,
@@ -1632,7 +2053,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1661,7 +2083,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1684,7 +2107,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1713,7 +2137,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1782,9 +2207,13 @@ Trace: ${e.stack}`,
               useVision,
               verifierUseVision,
               retries: retries + 1,
-              chunksSeen
+              chunksSeen,
+              requestId
             });
           } else {
+            if (this.enableCaching) {
+              this.llmProvider.cleanRequestCache(requestId);
+            }
             return {
               success: false,
               message: `Internal error: Chosen method ${method} is invalid`,
@@ -1851,7 +2280,8 @@ Trace: ${e.stack}`,
             modelName: model,
             screenshot: fullpageScreenshot,
             domElements,
-            logger: this.logger
+            logger: this.logger,
+            requestId
           });
           this.log({
             category: "action",
@@ -1871,7 +2301,8 @@ Trace: ${e.stack}`,
             modelName,
             chunksSeen,
             useVision,
-            verifierUseVision
+            verifierUseVision,
+            requestId
           });
         } else {
           this.log({
@@ -1901,10 +2332,14 @@ Trace: ${error.stack}`,
             useVision,
             verifierUseVision,
             retries: retries + 1,
-            chunksSeen
+            chunksSeen,
+            requestId
           });
         }
         yield this._recordAction(action, "");
+        if (this.enableCaching) {
+          this.llmProvider.cleanRequestCache(requestId);
+        }
         return {
           success: false,
           message: `Error performing action: ${error.message}`,
@@ -1920,12 +2355,32 @@ Trace: ${error.stack}`,
       useVision = "fallback"
     }) {
       useVision = useVision != null ? useVision : "fallback";
+      const requestId = Math.random().toString(36).substring(2);
+      this.logger({
+        category: "act",
+        message: `Running act with action: ${action}, requestId: ${requestId}`
+      });
       return this._act({
         action,
         modelName,
         chunksSeen: [],
         useVision,
-        verifierUseVision: useVision !== false
+        verifierUseVision: useVision !== false,
+        requestId
+      }).catch((e) => {
+        this.logger({
+          category: "act",
+          message: `Error acting: ${e.message}
+Trace: ${e.stack}`
+        });
+        if (this.enableCaching) {
+          this.llmProvider.cleanRequestCache(requestId);
+        }
+        return {
+          success: false,
+          message: `Internal error: Error acting: ${e.message}`,
+          action
+        };
       });
     });
   }
@@ -1935,21 +2390,53 @@ Trace: ${error.stack}`,
       schema,
       modelName
     }) {
+      const requestId = Math.random().toString(36).substring(2);
+      this.logger({
+        category: "extract",
+        message: `Running extract with instruction: ${instruction}, requestId: ${requestId}`
+      });
       return this._extract({
         instruction,
         schema,
-        modelName
+        modelName,
+        requestId
+      }).catch((e) => {
+        this.logger({
+          category: "extract",
+          message: `Internal error: Error extracting: ${e.message}
+Trace: ${e.stack}`
+        });
+        if (this.enableCaching) {
+          this.llmProvider.cleanRequestCache(requestId);
+        }
+        throw e;
       });
     });
   }
   observe(options) {
     return __async(this, null, function* () {
       var _a, _b;
+      const requestId = Math.random().toString(36).substring(2);
+      this.logger({
+        category: "observe",
+        message: `Running observe with instruction: ${options == null ? void 0 : options.instruction}, requestId: ${requestId}`
+      });
       return this._observe({
         instruction: (_a = options == null ? void 0 : options.instruction) != null ? _a : "Find actions that can be performed on this page.",
         modelName: options == null ? void 0 : options.modelName,
         useVision: (_b = options == null ? void 0 : options.useVision) != null ? _b : false,
-        fullPage: false
+        fullPage: false,
+        requestId
+      }).catch((e) => {
+        this.logger({
+          category: "observe",
+          message: `Error observing: ${e.message}
+Trace: ${e.stack}`
+        });
+        if (this.enableCaching) {
+          this.llmProvider.cleanRequestCache(requestId);
+        }
+        throw e;
       });
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/stagehand",
-  "version": "1.0.3-alpha.2",
+  "version": "1.1.0",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -50,6 +50,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.27.3",
+    "@browserbasehq/sdk": "^2.0.0",
     "anthropic": "^0.0.0",
     "anthropic-ai": "^0.0.10",
     "sharp": "^0.33.5",