@browserbasehq/stagehand 1.0.3 → 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;

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 = `
@@ -334,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.";
@@ -347,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)
@@ -398,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)
@@ -437,7 +441,8 @@ function act(_0) {
         llmProvider,
         modelName,
         retries: retries + 1,
-        logger
+        logger,
+        requestId
       });
     }
   });
@@ -452,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: [
@@ -527,7 +533,8 @@ function observe(_0) {
     domElements,
     llmProvider,
     modelName,
-    image
+    image,
+    requestId
   }) {
     const observeSchema = import_zod.z.object({
       elements: import_zod.z.array(
@@ -539,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: [
@@ -567,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",
@@ -602,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;
     });
   }
@@ -613,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"
@@ -724,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",
@@ -753,17 +1098,36 @@ 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}`);
     }
@@ -773,55 +1137,6 @@ var LLMProvider = class {
 // lib/index.ts
 var import_path2 = __toESM(require("path"));
 
-// 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/vision.ts
 var import_fs = __toESM(require("fs"));
 var import_path = __toESM(require("path"));
@@ -1004,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}
 
@@ -1124,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"
   }) {
@@ -1138,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 };
@@ -1271,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`,
@@ -1284,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"
@@ -1301,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",
@@ -1374,7 +1746,8 @@ Trace: ${e.stack}`,
       progress = "",
       content = {},
       chunksSeen = [],
-      modelName
+      modelName,
+      requestId
     }) {
       this.log({
         category: "extraction",
@@ -1401,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 }
@@ -1445,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.`;
@@ -1485,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) => {
@@ -1514,7 +1890,8 @@ Trace: ${e.stack}`,
       modelName,
       useVision,
       verifierUseVision,
-      retries = 0
+      retries = 0,
+      requestId
     }) {
       var _a;
       const model = modelName != null ? modelName : this.defaultModelName;
@@ -1574,7 +1951,8 @@ Trace: ${e.stack}`,
         llmProvider: this.llmProvider,
         modelName: model,
         screenshot: annotatedScreenshot,
-        logger: this.logger
+        logger: this.logger,
+        requestId
       });
       this.log({
         category: "action",
@@ -1596,7 +1974,8 @@ Trace: ${e.stack}`,
             chunksSeen,
             modelName,
             useVision,
-            verifierUseVision
+            verifierUseVision,
+            requestId
           });
         } else if (useVision === "fallback") {
           this.log({
@@ -1611,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.`,
@@ -1670,7 +2053,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1699,7 +2083,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1722,7 +2107,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1751,7 +2137,8 @@ Trace: ${e.stack}`,
                 useVision,
                 verifierUseVision,
                 retries: retries + 1,
-                chunksSeen
+                chunksSeen,
+                requestId
               });
             }
           }
@@ -1820,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`,
@@ -1889,7 +2280,8 @@ Trace: ${e.stack}`,
             modelName: model,
             screenshot: fullpageScreenshot,
             domElements,
-            logger: this.logger
+            logger: this.logger,
+            requestId
           });
           this.log({
             category: "action",
@@ -1909,7 +2301,8 @@ Trace: ${e.stack}`,
             modelName,
             chunksSeen,
             useVision,
-            verifierUseVision
+            verifierUseVision,
+            requestId
           });
         } else {
           this.log({
@@ -1939,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}`,
@@ -1958,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
+        };
       });
     });
   }
@@ -1973,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",
+  "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",

package/dist/dom/build/types.js

@@ -1,2 +0,0 @@
-(() => {
-})();