@browserbasehq/stagehand 3.0.7-alpha-b48c9c68e97f6370e2c01ba0232b951915142abd → 3.0.7-alpha-05f5580937c3c157550e3c25ae6671f44f562211

package/dist/index.d.ts

@@ -947,6 +947,7 @@ declare class StagehandAPIClient {
     private projectId;
     private sessionId?;
     private modelApiKey;
+    private modelProvider?;
     private logger;
     private fetchWithCookies;
     constructor({ apiKey, projectId, logger }: StagehandAPIConstructorParams);
@@ -960,6 +961,14 @@ declare class StagehandAPIClient {
     agentExecute(agentConfig: AgentConfig, executeOptions: AgentExecuteOptions | string, frameId?: string): Promise<AgentResult>;
     end(): Promise<Response>;
     getReplayMetrics(): Promise<StagehandMetrics>;
+    /**
+     * Prepares a model configuration for the API payload by ensuring
+     * the apiKey is included. If the model is passed as a string,
+     * it converts it to an object with modelName and apiKey.
+     * The apiKey is loaded from environment variables only if the provider
+     * differs from the one used during init.
+     */
+    private prepareModelConfig;
     private execute;
     private request;
 }
@@ -1091,7 +1100,7 @@ declare class V3Context {
     awaitActivePage(timeoutMs?: number): Promise<Page>;
 }
 
-type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | {
+type AgentReplayStep = AgentReplayActStep | AgentReplayFillFormStep | AgentReplayGotoStep | AgentReplayScrollStep | AgentReplayWaitStep | AgentReplayNavBackStep | AgentReplayKeysStep | {
     type: string;
     [key: string]: unknown;
 };
@@ -1134,6 +1143,16 @@ interface AgentReplayNavBackStep {
     type: "navback";
     waitUntil?: LoadState;
 }
+interface AgentReplayKeysStep {
+    type: "keys";
+    instruction?: string;
+    playwrightArguments: {
+        method: "type" | "press";
+        text?: string;
+        keys?: string;
+        times?: number;
+    };
+}
 
 /**
  * Response

package/dist/index.js

@@ -179,7 +179,7 @@ var __forAwait = (obj, it, method) => (it = obj[__knownSymbol("asyncIterator")])
 var STAGEHAND_VERSION;
 var init_version = __esm({
   "lib/version.ts"() {
-    STAGEHAND_VERSION = "3.0.7-alpha-b48c9c68e97f6370e2c01ba0232b951915142abd";
+    STAGEHAND_VERSION = "3.0.7-alpha-05f5580937c3c157550e3c25ae6671f44f562211";
   }
 });
 
@@ -28811,6 +28811,9 @@ var AgentCache = class {
         case "navback":
           yield this.replayAgentNavBackStep(step, ctx);
           return;
+        case "keys":
+          yield this.replayAgentKeysStep(step, ctx);
+          return;
         case "close":
         case "extract":
         case "screenshot":
@@ -28900,6 +28903,22 @@ var AgentCache = class {
       yield page.goBack({ waitUntil: (_a4 = step.waitUntil) != null ? _a4 : "domcontentloaded" });
     });
   }
+  replayAgentKeysStep(step, ctx) {
+    return __async(this, null, function* () {
+      const page = yield ctx.awaitActivePage();
+      const { method, text, keys, times } = step.playwrightArguments;
+      const repeatCount = Math.max(1, times != null ? times : 1);
+      if (method === "type" && text) {
+        for (let i2 = 0; i2 < repeatCount; i2++) {
+          yield page.type(text, { delay: 100 });
+        }
+      } else if (method === "press" && keys) {
+        for (let i2 = 0; i2 < repeatCount; i2++) {
+          yield page.keyPress(keys, { delay: 100 });
+        }
+      }
+    });
+  }
 };
 
 // lib/v3/cache/CacheStorage.ts
@@ -31323,6 +31342,16 @@ var extractTool = (v3, executionModel, logger) => (0, import_ai10.tool)({
 // lib/v3/agent/tools/click.ts
 var import_ai11 = require("ai");
 var import_zod15 = require("zod");
+
+// lib/v3/agent/utils/xpath.ts
+function ensureXPath(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.startsWith("xpath=") ? trimmed : `xpath=${trimmed}`;
+}
+
+// lib/v3/agent/tools/click.ts
 function waitForTimeout(ms) {
   return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
@@ -31353,15 +31382,27 @@ var clickTool = (v3, provider) => (0, import_ai11.tool)({
           }
         }
       });
-      yield page.click(processed.x, processed.y);
+      const xpath = yield page.click(processed.x, processed.y, {
+        returnXpath: true
+      });
       if (isGoogleProvider(provider)) {
         yield waitForTimeout(1e3);
       }
-      v3.recordAgentReplayStep({
-        type: "click",
-        instruction: describe,
-        playwrightArguments: { coordinates: [processed.x, processed.y] }
-      });
+      const normalizedXpath = ensureXPath(xpath);
+      if (normalizedXpath) {
+        const action = {
+          selector: normalizedXpath,
+          description: describe,
+          method: "click",
+          arguments: []
+        };
+        v3.recordAgentReplayStep({
+          type: "act",
+          instruction: describe,
+          actions: [action],
+          actionDescription: describe
+        });
+      }
       return {
         success: true,
         describe,
@@ -31410,19 +31451,28 @@ var typeTool = (v3, provider) => (0, import_ai12.tool)({
           }
         }
       });
-      yield page.click(processed.x, processed.y);
+      const xpath = yield page.click(processed.x, processed.y, {
+        returnXpath: true
+      });
       if (isGoogleProvider(provider)) {
         yield waitForTimeout2(1e3);
       }
       yield page.type(text);
-      v3.recordAgentReplayStep({
-        type: "type",
-        instruction: describe,
-        playwrightArguments: {
-          coordinates: [processed.x, processed.y],
-          text
-        }
-      });
+      const normalizedXpath = ensureXPath(xpath);
+      if (normalizedXpath) {
+        const action = {
+          selector: normalizedXpath,
+          description: describe,
+          method: "type",
+          arguments: [text]
+        };
+        v3.recordAgentReplayStep({
+          type: "act",
+          instruction: describe,
+          actions: [action],
+          actionDescription: describe
+        });
+      }
       return { success: true, describe, text };
     } catch (error) {
       return {
@@ -31473,20 +31523,29 @@ var dragAndDropTool = (v3, provider) => (0, import_ai13.tool)({
           }
         }
       });
-      yield page.dragAndDrop(
+      const [fromXpath, toXpath] = yield page.dragAndDrop(
         processedStart.x,
         processedStart.y,
         processedEnd.x,
-        processedEnd.y
+        processedEnd.y,
+        { returnXpath: true }
       );
-      v3.recordAgentReplayStep({
-        type: "dragAndDrop",
-        instruction: describe,
-        playwrightArguments: {
-          startCoordinates: [processedStart.x, processedStart.y],
-          endCoordinates: [processedEnd.x, processedEnd.y]
-        }
-      });
+      const normalizedFrom = ensureXPath(fromXpath);
+      const normalizedTo = ensureXPath(toXpath);
+      if (normalizedFrom && normalizedTo) {
+        const action = {
+          selector: normalizedFrom,
+          description: describe,
+          method: "dragAndDrop",
+          arguments: [normalizedTo]
+        };
+        v3.recordAgentReplayStep({
+          type: "act",
+          instruction: describe,
+          actions: [action],
+          actionDescription: describe
+        });
+      }
       return { success: true, describe };
     } catch (error) {
       return {
@@ -31533,21 +31592,28 @@ var clickAndHoldTool = (v3, provider) => (0, import_ai14.tool)({
           }
         }
       });
-      yield page.dragAndDrop(
+      const [xpath] = yield page.dragAndDrop(
         processed.x,
         processed.y,
         processed.x,
         processed.y,
-        { delay: duration }
+        { delay: duration, returnXpath: true }
       );
-      v3.recordAgentReplayStep({
-        type: "clickAndHold",
-        instruction: describe,
-        playwrightArguments: {
-          coordinates: [processed.x, processed.y],
-          duration
-        }
-      });
+      const normalizedXpath = ensureXPath(xpath);
+      if (normalizedXpath) {
+        const action = {
+          selector: normalizedXpath,
+          description: describe,
+          method: "clickAndHold",
+          arguments: [String(duration)]
+        };
+        v3.recordAgentReplayStep({
+          type: "act",
+          instruction: describe,
+          actions: [action],
+          actionDescription: describe
+        });
+      }
       return { success: true, describe };
     } catch (error) {
       return {
@@ -31677,16 +31743,35 @@ MANDATORY USE CASES (always use fillFormVision for these):
           }
         }
       });
+      const actions = [];
       for (const field of processedFields) {
-        yield page.click(field.coordinates.x, field.coordinates.y);
+        const xpath = yield page.click(
+          field.coordinates.x,
+          field.coordinates.y,
+          {
+            returnXpath: true
+          }
+        );
         yield page.type(field.value);
+        const normalizedXpath = ensureXPath(xpath);
+        if (normalizedXpath) {
+          actions.push({
+            selector: normalizedXpath,
+            description: field.action,
+            method: "type",
+            arguments: [field.value]
+          });
+        }
         yield new Promise((resolve3) => setTimeout(resolve3, 100));
       }
-      v3.recordAgentReplayStep({
-        type: "fillFormVision",
-        instruction: `Fill ${fields.length} form fields`,
-        playwrightArguments: processedFields
-      });
+      if (actions.length > 0) {
+        v3.recordAgentReplayStep({
+          type: "act",
+          instruction: `Fill ${fields.length} form fields`,
+          actions,
+          actionDescription: `Fill ${fields.length} form fields`
+        });
+      }
       return {
         success: true,
         playwrightArguments: processedFields
@@ -35680,7 +35765,7 @@ var V3CuaAgentHandler = class {
               clickCount: clickCount != null ? clickCount : 1,
               returnXpath: true
             });
-            const normalized = this.ensureXPath(xpath);
+            const normalized = ensureXPath(xpath);
             if (normalized) {
               const stagehandAction = {
                 selector: normalized,
@@ -35711,7 +35796,7 @@ var V3CuaAgentHandler = class {
               clickCount: 2,
               returnXpath: true
             });
-            const normalized = this.ensureXPath(xpath);
+            const normalized = ensureXPath(xpath);
             if (normalized) {
               const stagehandAction = {
                 selector: normalized,
@@ -35741,7 +35826,7 @@ var V3CuaAgentHandler = class {
               clickCount: 3,
               returnXpath: true
             });
-            const normalized = this.ensureXPath(xpath);
+            const normalized = ensureXPath(xpath);
             if (normalized) {
               const stagehandAction = {
                 selector: normalized,
@@ -35767,7 +35852,7 @@ var V3CuaAgentHandler = class {
           yield page.type(String(text != null ? text : ""));
           if (recording) {
             const xpath = yield computeActiveElementXpath(page);
-            const normalized = this.ensureXPath(xpath);
+            const normalized = ensureXPath(xpath);
             if (normalized) {
               const stagehandAction = {
                 selector: normalized,
@@ -35837,8 +35922,8 @@ var V3CuaAgentHandler = class {
                 returnXpath: true
               });
               const [fromXpath, toXpath] = xps || ["", ""];
-              const from = this.ensureXPath(fromXpath);
-              const to = this.ensureXPath(toXpath);
+              const from = ensureXPath(fromXpath);
+              const to = ensureXPath(toXpath);
               if (from && to) {
                 const stagehandAction = {
                   selector: from,
@@ -35927,12 +36012,6 @@ var V3CuaAgentHandler = class {
   computePointerTarget(action) {
     return typeof action.x === "number" && typeof action.y === "number" ? `(${action.x}, ${action.y})` : typeof action.selector === "string" ? action.selector : typeof action.input === "string" ? action.input : typeof action.description === "string" ? action.description : void 0;
   }
-  ensureXPath(value) {
-    if (typeof value !== "string") return null;
-    const trimmed = value.trim();
-    if (!trimmed) return null;
-    return trimmed.startsWith("xpath=") ? trimmed : `xpath=${trimmed}`;
-  }
   describePointerAction(kind, x2, y) {
     const nx = Number(x2);
     const ny = Number(y);
@@ -65014,6 +65093,7 @@ var StagehandAPIClient = class {
         throw new StagehandAPIError("modelApiKey is required");
       }
       this.modelApiKey = modelApiKey;
+      this.modelProvider = (modelName == null ? void 0 : modelName.includes("/")) ? modelName.split("/")[0] : void 0;
       const region = browserbaseSessionCreateParams == null ? void 0 : browserbaseSessionCreateParams.region;
       if (region && region !== "us-west-2") {
         return { sessionId: browserbaseSessionID != null ? browserbaseSessionID : null, available: false };
@@ -65068,6 +65148,9 @@ var StagehandAPIClient = class {
       if (options) {
         const _a4 = options, { page: _ } = _a4, restOptions = __objRest(_a4, ["page"]);
         if (Object.keys(restOptions).length > 0) {
+          if (restOptions.model) {
+            restOptions.model = this.prepareModelConfig(restOptions.model);
+          }
           args.options = restOptions;
         }
       }
@@ -65093,6 +65176,9 @@ var StagehandAPIClient = class {
       if (options) {
         const _a4 = options, { page: _ } = _a4, restOptions = __objRest(_a4, ["page"]);
         if (Object.keys(restOptions).length > 0) {
+          if (restOptions.model) {
+            restOptions.model = this.prepareModelConfig(restOptions.model);
+          }
           args.options = restOptions;
         }
       }
@@ -65115,6 +65201,9 @@ var StagehandAPIClient = class {
       if (options) {
         const _a4 = options, { page: _ } = _a4, restOptions = __objRest(_a4, ["page"]);
         if (Object.keys(restOptions).length > 0) {
+          if (restOptions.model) {
+            restOptions.model = this.prepareModelConfig(restOptions.model);
+          }
           args.options = restOptions;
         }
       }
@@ -65259,6 +65348,32 @@ var StagehandAPIClient = class {
       return metrics;
     });
   }
+  /**
+   * Prepares a model configuration for the API payload by ensuring
+   * the apiKey is included. If the model is passed as a string,
+   * it converts it to an object with modelName and apiKey.
+   * The apiKey is loaded from environment variables only if the provider
+   * differs from the one used during init.
+   */
+  prepareModelConfig(model) {
+    var _a4, _b, _c;
+    if (typeof model === "string") {
+      const provider = model.includes("/") ? model.split("/")[0] : void 0;
+      const apiKey = provider && provider !== this.modelProvider ? (_a4 = loadApiKeyFromEnv(provider, this.logger)) != null ? _a4 : this.modelApiKey : this.modelApiKey;
+      return {
+        modelName: model,
+        apiKey
+      };
+    }
+    if (!model.apiKey) {
+      const provider = ((_b = model.modelName) == null ? void 0 : _b.includes("/")) ? model.modelName.split("/")[0] : void 0;
+      const apiKey = provider && provider !== this.modelProvider ? (_c = loadApiKeyFromEnv(provider, this.logger)) != null ? _c : this.modelApiKey : this.modelApiKey;
+      return __spreadProps(__spreadValues({}, model), {
+        apiKey
+      });
+    }
+    return model;
+  }
   execute(_0) {
     return __async(this, arguments, function* ({
       method,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/stagehand",
-  "version": "3.0.7-alpha-b48c9c68e97f6370e2c01ba0232b951915142abd",
+  "version": "3.0.7-alpha-05f5580937c3c157550e3c25ae6671f44f562211",
   "description": "An AI web browsing framework focused on simplicity and extensibility.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",