@browserbasehq/stagehand 3.0.7-alpha-fea1700552af3319052f463685752501c8e71de3 → 3.0.7-alpha-e0e22e06bc752a8ffde30f3dbfa58d91e24e6c09

package/dist/index.d.ts

@@ -1100,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;
 };
@@ -1143,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
@@ -1983,6 +1993,7 @@ type AgentConfig = {
      * - 'dom' (default): Uses DOM-based tools (act, fillForm) for structured interactions
      * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)
      *             for visual/screenshot-based interactions
+     * @experimental hybrid mode requires `experimental: true` in Stagehand constructor
      */
     mode?: AgentToolMode;
 };

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-fea1700552af3319052f463685752501c8e71de3";
+    STAGEHAND_VERSION = "3.0.7-alpha-e0e22e06bc752a8ffde30f3dbfa58d91e24e6c09";
   }
 });
 
@@ -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);
@@ -65442,6 +65521,9 @@ function validateExperimentalFeatures(options) {
   if (hasIntegrations || hasTools) {
     features.push("MCP integrations and custom tools");
   }
+  if ((agentConfig == null ? void 0 : agentConfig.mode) === "hybrid") {
+    features.push("hybrid mode");
+  }
   if (!(agentConfig == null ? void 0 : agentConfig.cua) && (isStreaming || (agentConfig == null ? void 0 : agentConfig.stream))) {
     features.push("streaming");
   }

package/package.json

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