@browserbasehq/stagehand 2.5.5 → 2.5.7

package/dist/index.d.ts

@@ -314,6 +314,9 @@ interface ObserveOptions {
      * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
      */
     onlyVisible?: boolean;
+    /**
+     * @deprecated The `drawOverlay` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
     drawOverlay?: boolean;
     iframes?: boolean;
     frameId?: string;

package/dist/index.js

@@ -494,7 +494,7 @@ var StagehandFunctionName = /* @__PURE__ */ ((StagehandFunctionName2) => {
 })(StagehandFunctionName || {});
 
 // lib/version.ts
-var STAGEHAND_VERSION = "2.5.5";
+var STAGEHAND_VERSION = "2.5.7";
 
 // types/stagehandErrors.ts
 var StagehandError = class extends Error {
@@ -2161,57 +2161,6 @@ function validateZodSchema(schema, data) {
   }
   throw new ZodSchemaValidationError(data, result.error.format());
 }
-function drawObserveOverlay(page, results) {
-  return __async(this, null, function* () {
-    const xpathList = results.map((result) => result.selector);
-    const validXpaths = xpathList.filter((xpath) => xpath !== "xpath=");
-    yield page.evaluate((selectors2) => {
-      selectors2.forEach((selector) => {
-        let element;
-        if (selector.startsWith("xpath=")) {
-          const xpath = selector.substring(6);
-          element = document.evaluate(
-            xpath,
-            document,
-            null,
-            XPathResult.FIRST_ORDERED_NODE_TYPE,
-            null
-          ).singleNodeValue;
-        } else {
-          element = document.querySelector(selector);
-        }
-        if (element instanceof HTMLElement) {
-          const overlay = document.createElement("div");
-          overlay.setAttribute("stagehandObserve", "true");
-          const rect = element.getBoundingClientRect();
-          overlay.style.position = "absolute";
-          overlay.style.left = rect.left + "px";
-          overlay.style.top = rect.top + "px";
-          overlay.style.width = rect.width + "px";
-          overlay.style.height = rect.height + "px";
-          overlay.style.backgroundColor = "rgba(255, 255, 0, 0.3)";
-          overlay.style.pointerEvents = "none";
-          overlay.style.zIndex = "10000";
-          document.body.appendChild(overlay);
-        }
-      });
-    }, validXpaths);
-  });
-}
-function clearOverlays(page) {
-  return __async(this, null, function* () {
-    yield page.evaluate(() => {
-      const elements = document.querySelectorAll('[stagehandObserve="true"]');
-      elements.forEach((el) => {
-        const parent = el.parentNode;
-        while (el.firstChild) {
-          parent == null ? void 0 : parent.insertBefore(el.firstChild, el);
-        }
-        parent == null ? void 0 : parent.removeChild(el);
-      });
-    });
-  });
-}
 function isRunningInBun() {
   return typeof process !== "undefined" && typeof process.versions !== "undefined" && "bun" in process.versions;
 }
@@ -3709,6 +3658,13 @@ var StagehandObserveHandler = class {
           level: 1
         });
       }
+      if (drawOverlay !== void 0) {
+        this.logger({
+          category: "observation",
+          message: "Warning: the drawOverlay parameter has been deprecated and this parameter is now a no-op.",
+          level: 1
+        });
+      }
       yield this.stagehandPage._waitForSettledDom();
       this.logger({
         category: "observation",
@@ -3836,9 +3792,6 @@ var StagehandObserveHandler = class {
           }
         }
       });
-      if (drawOverlay) {
-        yield drawObserveOverlay(this.stagehandPage.page, elementsWithSelectors);
-      }
       return elementsWithSelectors;
     });
   }
@@ -4389,7 +4342,6 @@ var StagehandPage = class _StagehandPage {
         if (!this.actHandler) {
           throw new HandlerNotInitializedError("Act");
         }
-        yield clearOverlays(this.page);
         if (typeof actionOrOptions === "object" && actionOrOptions !== null) {
           if ("selector" in actionOrOptions && "method" in actionOrOptions) {
             const observeResult = actionOrOptions;
@@ -4468,7 +4420,6 @@ var StagehandPage = class _StagehandPage {
         if (!this.extractHandler) {
           throw new HandlerNotInitializedError("Extract");
         }
-        yield clearOverlays(this.page);
         if (!instructionOrOptions) {
           let result2;
           if (this.api) {
@@ -4571,7 +4522,6 @@ var StagehandPage = class _StagehandPage {
         if (!this.observeHandler) {
           throw new HandlerNotInitializedError("Observe");
         }
-        yield clearOverlays(this.page);
         const options = typeof instructionOrOptions === "string" ? { instruction: instructionOrOptions } : instructionOrOptions || {};
         const {
           instruction,
@@ -23502,51 +23452,74 @@ var createScrollTool = (stagehand) => (0, import_ai11.tool)({
 // lib/agent/tools/extract.ts
 var import_ai12 = require("ai");
 var import_v314 = require("zod/v3");
-function evaluateZodSchema(schemaStr, logger) {
-  try {
-    const schemaFunction = new Function("z", `return ${schemaStr}`);
-    return schemaFunction(import_v314.z);
-  } catch (error) {
-    logger == null ? void 0 : logger({
-      category: "extract",
-      message: `Failed to evaluate schema string, using z.any(): ${error}`,
-      level: 1,
-      auxiliary: {
-        error: {
-          value: error,
-          type: "string"
+function jsonSchemaToZod2(schema) {
+  switch (schema.type) {
+    case "object": {
+      const shape = {};
+      if (schema.properties) {
+        for (const [key, value] of Object.entries(schema.properties)) {
+          shape[key] = jsonSchemaToZod2(value);
         }
       }
-    });
-    return import_v314.z.any();
+      return import_v314.z.object(shape);
+    }
+    case "array":
+      return import_v314.z.array(schema.items ? jsonSchemaToZod2(schema.items) : import_v314.z.any());
+    case "string": {
+      let s = import_v314.z.string();
+      if (schema.format === "url") s = s.url();
+      if (schema.format === "email") s = s.email();
+      if (schema.format === "uuid") s = s.uuid();
+      if (schema.enum && schema.enum.length > 0)
+        return import_v314.z.enum(schema.enum);
+      return s;
+    }
+    case "number":
+    case "integer":
+      return import_v314.z.number();
+    case "boolean":
+      return import_v314.z.boolean();
+    case "null":
+      return import_v314.z.null();
+    default:
+      return import_v314.z.any();
   }
 }
-var createExtractTool = (stagehand, executionModel, logger) => (0, import_ai12.tool)({
+var createExtractTool = (stagehand, executionModel) => (0, import_ai12.tool)({
   description: `Extract structured data from the current page based on a provided schema.
     
     USAGE GUIDELINES:
     - Keep schemas MINIMAL - only include fields essential for the task
-    - IMPORANT: only use this if explicitly asked for structured output. In most scenarios, you should use the aria tree tool over this. 
-    - If you need to extract a link, make sure the type defintion follows the format of z.string().url()
+    - IMPORTANT: only use this if explicitly asked for structured output. In most scenarios, you should use the aria tree tool over this.
+    - For URL fields, use format: "url"
+    
     EXAMPLES:
     1. Extract a single value:
        instruction: "extract the product price"
-       schema: "z.object({ price: z.number()})"
+       schema: { type: "object", properties: { price: { type: "number" } } }
     
     2. Extract multiple fields:
        instruction: "extract product name and price"
-       schema: "z.object({ name: z.string(), price: z.number() })"
+       schema: { type: "object", properties: { name: { type: "string" }, price: { type: "number" } } }
     
     3. Extract arrays:
        instruction: "extract all product names and prices"
-       schema: "z.object({ products: z.array(z.object({ name: z.string(), price: z.number() })) })"`,
+       schema: { type: "object", properties: { products: { type: "array", items: { type: "object", properties: { name: { type: "string" }, price: { type: "number" } } } } } }
+    
+    4. Extract a URL:
+       instruction: "extract the link"
+       schema: { type: "object", properties: { url: { type: "string", format: "url" } } }`,
   parameters: import_v314.z.object({
     instruction: import_v314.z.string().describe(
       "Clear instruction describing what data to extract from the page"
     ),
-    schema: import_v314.z.string().describe(
-      'Zod schema as a string (e.g., "z.object({ price: z.number() })")'
-    )
+    schema: import_v314.z.object({
+      type: import_v314.z.string().optional(),
+      properties: import_v314.z.record(import_v314.z.string(), import_v314.z.unknown()).optional(),
+      items: import_v314.z.unknown().optional(),
+      enum: import_v314.z.array(import_v314.z.string()).optional(),
+      format: import_v314.z.enum(["url", "email", "uuid"]).optional()
+    }).passthrough().describe("JSON Schema object describing the structure to extract")
   }),
   execute: (_0) => __async(null, [_0], function* ({ instruction, schema }) {
     try {
@@ -23559,14 +23532,13 @@ var createExtractTool = (stagehand, executionModel, logger) => (0, import_ai12.t
             value: instruction,
             type: "string"
           },
-          // TODO: check if we want to log this
           schema: {
-            value: schema,
+            value: JSON.stringify(schema),
             type: "object"
           }
         }
       });
-      const zodSchema = evaluateZodSchema(schema, logger);
+      const zodSchema = jsonSchemaToZod2(schema);
       const schemaObject = zodSchema instanceof import_v314.z.ZodObject ? zodSchema : import_v314.z.object({ result: zodSchema });
       const result = yield stagehand.page.extract(__spreadValues({
         instruction,
@@ -23595,7 +23567,7 @@ function createAgentTools(stagehand, options) {
     act: createActTool(stagehand, executionModel),
     ariaTree: createAriaTreeTool(stagehand),
     close: createCloseTool(),
-    extract: createExtractTool(stagehand, executionModel, options == null ? void 0 : options.logger),
+    extract: createExtractTool(stagehand, executionModel),
     fillForm: createFillFormTool(stagehand, executionModel),
     goto: createGotoTool(stagehand),
     navback: createNavBackTool(stagehand),

package/dist/lib/agent/tools/extract.d.ts

@@ -1,14 +1,47 @@
 import { z } from "zod/v3";
 import { Stagehand } from "../../index";
-import { LogLine } from "@/types/log";
-export declare const createExtractTool: (stagehand: Stagehand, executionModel?: string, logger?: (message: LogLine) => void) => import("ai/dist").Tool<z.ZodObject<{
+export declare const createExtractTool: (stagehand: Stagehand, executionModel?: string) => import("ai/dist").Tool<z.ZodObject<{
     instruction: z.ZodString;
-    schema: z.ZodString;
+    schema: z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        items: z.ZodOptional<z.ZodUnknown>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        format: z.ZodOptional<z.ZodEnum<["url", "email", "uuid"]>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        type: z.ZodOptional<z.ZodString>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        items: z.ZodOptional<z.ZodUnknown>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        format: z.ZodOptional<z.ZodEnum<["url", "email", "uuid"]>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        type: z.ZodOptional<z.ZodString>;
+        properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        items: z.ZodOptional<z.ZodUnknown>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        format: z.ZodOptional<z.ZodEnum<["url", "email", "uuid"]>>;
+    }, z.ZodTypeAny, "passthrough">>;
 }, "strip", z.ZodTypeAny, {
-    schema?: string;
+    schema?: {
+        type?: string;
+        format?: "url" | "email" | "uuid";
+        properties?: Record<string, unknown>;
+        items?: unknown;
+        enum?: string[];
+    } & {
+        [k: string]: unknown;
+    };
     instruction?: string;
 }, {
-    schema?: string;
+    schema?: {
+        type?: string;
+        format?: "url" | "email" | "uuid";
+        properties?: Record<string, unknown>;
+        items?: unknown;
+        enum?: string[];
+    } & {
+        [k: string]: unknown;
+    };
     instruction?: string;
 }>, {
     success: boolean;
@@ -22,7 +55,15 @@ export declare const createExtractTool: (stagehand: Stagehand, executionModel?:
     data?: undefined;
 }> & {
     execute: (args: {
-        schema?: string;
+        schema?: {
+            type?: string;
+            format?: "url" | "email" | "uuid";
+            properties?: Record<string, unknown>;
+            items?: unknown;
+            enum?: string[];
+        } & {
+            [k: string]: unknown;
+        };
         instruction?: string;
     }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
         success: boolean;

package/dist/lib/agent/tools/index.d.ts

@@ -94,12 +94,46 @@ export declare function createAgentTools(stagehand: Stagehand, options?: AgentTo
     };
     extract: import("ai/dist").Tool<import("zod/v3").ZodObject<{
         instruction: import("zod/v3").ZodString;
-        schema: import("zod/v3").ZodString;
+        schema: import("zod/v3").ZodObject<{
+            type: import("zod/v3").ZodOptional<import("zod/v3").ZodString>;
+            properties: import("zod/v3").ZodOptional<import("zod/v3").ZodRecord<import("zod/v3").ZodString, import("zod/v3").ZodUnknown>>;
+            items: import("zod/v3").ZodOptional<import("zod/v3").ZodUnknown>;
+            enum: import("zod/v3").ZodOptional<import("zod/v3").ZodArray<import("zod/v3").ZodString, "many">>;
+            format: import("zod/v3").ZodOptional<import("zod/v3").ZodEnum<["url", "email", "uuid"]>>;
+        }, "passthrough", import("zod/v3").ZodTypeAny, import("zod/v3").objectOutputType<{
+            type: import("zod/v3").ZodOptional<import("zod/v3").ZodString>;
+            properties: import("zod/v3").ZodOptional<import("zod/v3").ZodRecord<import("zod/v3").ZodString, import("zod/v3").ZodUnknown>>;
+            items: import("zod/v3").ZodOptional<import("zod/v3").ZodUnknown>;
+            enum: import("zod/v3").ZodOptional<import("zod/v3").ZodArray<import("zod/v3").ZodString, "many">>;
+            format: import("zod/v3").ZodOptional<import("zod/v3").ZodEnum<["url", "email", "uuid"]>>;
+        }, import("zod/v3").ZodTypeAny, "passthrough">, import("zod/v3").objectInputType<{
+            type: import("zod/v3").ZodOptional<import("zod/v3").ZodString>;
+            properties: import("zod/v3").ZodOptional<import("zod/v3").ZodRecord<import("zod/v3").ZodString, import("zod/v3").ZodUnknown>>;
+            items: import("zod/v3").ZodOptional<import("zod/v3").ZodUnknown>;
+            enum: import("zod/v3").ZodOptional<import("zod/v3").ZodArray<import("zod/v3").ZodString, "many">>;
+            format: import("zod/v3").ZodOptional<import("zod/v3").ZodEnum<["url", "email", "uuid"]>>;
+        }, import("zod/v3").ZodTypeAny, "passthrough">>;
     }, "strip", import("zod/v3").ZodTypeAny, {
-        schema?: string;
+        schema?: {
+            type?: string;
+            format?: "url" | "email" | "uuid";
+            properties?: Record<string, unknown>;
+            items?: unknown;
+            enum?: string[];
+        } & {
+            [k: string]: unknown;
+        };
         instruction?: string;
     }, {
-        schema?: string;
+        schema?: {
+            type?: string;
+            format?: "url" | "email" | "uuid";
+            properties?: Record<string, unknown>;
+            items?: unknown;
+            enum?: string[];
+        } & {
+            [k: string]: unknown;
+        };
         instruction?: string;
     }>, {
         success: boolean;
@@ -113,7 +147,15 @@ export declare function createAgentTools(stagehand: Stagehand, options?: AgentTo
         data?: undefined;
     }> & {
         execute: (args: {
-            schema?: string;
+            schema?: {
+                type?: string;
+                format?: "url" | "email" | "uuid";
+                properties?: Record<string, unknown>;
+                items?: unknown;
+                enum?: string[];
+            } & {
+                [k: string]: unknown;
+            };
             instruction?: string;
         }, options: import("ai/dist").ToolExecutionOptions) => PromiseLike<{
             success: boolean;

package/dist/lib/handlers/observeHandler.d.ts

@@ -25,6 +25,9 @@ export declare class StagehandObserveHandler {
          * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
          */
         onlyVisible?: boolean;
+        /**
+         * @deprecated The `drawOverlay` parameter has no effect in this version of Stagehand and will be removed in later versions.
+         */
         drawOverlay?: boolean;
         fromAct?: boolean;
         iframes?: boolean;

package/dist/lib/utils.d.ts

@@ -1,12 +1,9 @@
 import { Schema } from "@google/genai";
 import { z, ZodTypeAny } from "zod/v3";
-import { ObserveResult, Page } from ".";
 import { LogLine } from "../types/log";
 import { ModelProvider } from "../types/model";
 import { ZodPathSegments } from "../types/stagehand";
 export declare function validateZodSchema(schema: z.ZodTypeAny, data: unknown): boolean;
-export declare function drawObserveOverlay(page: Page, results: ObserveResult[]): Promise<void>;
-export declare function clearOverlays(page: Page): Promise<void>;
 /**
  * Detects if the code is running in the Bun runtime environment.
  * @returns {boolean} True if running in Bun, false otherwise.

package/dist/lib/version.d.ts

@@ -2,4 +2,4 @@
  * AUTO-GENERATED — DO NOT EDIT BY HAND
  *  Run `pnpm run gen-version` to refresh.
  */
-export declare const STAGEHAND_VERSION: "2.5.5";
+export declare const STAGEHAND_VERSION: "2.5.7";

package/dist/types/stagehand.d.ts

@@ -150,6 +150,9 @@ export interface ObserveOptions {
      * @deprecated The `onlyVisible` parameter has no effect in this version of Stagehand and will be removed in later versions.
      */
     onlyVisible?: boolean;
+    /**
+     * @deprecated The `drawOverlay` parameter has no effect in this version of Stagehand and will be removed in later versions.
+     */
     drawOverlay?: boolean;
     iframes?: boolean;
     frameId?: string;

package/package.json

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