@browserbasehq/stagehand 2.1.0 → 2.2.0-alpha-8814af9ece99fddc3dd9fb32671d0513a3a00c67

package/dist/evals/tasks/extract_jfk_links.d.ts

@@ -0,0 +1,2 @@
+import { EvalFunction } from "@/types/evals";
+export declare const extract_jfk_links: EvalFunction;

package/dist/evals/tasks/extract_single_link.d.ts

@@ -0,0 +1,2 @@
+import { EvalFunction } from "@/types/evals";
+export declare const extract_single_link: EvalFunction;

package/dist/index.d.ts

@@ -524,6 +524,23 @@ interface HistoryEntry {
     result: unknown;
     timestamp: string;
 }
+/**
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
+ *
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
+ */
+interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}
 
 declare const defaultExtractSchema: z.ZodObject<{
     extraction: z.ZodString;
@@ -849,4 +866,4 @@ declare class Stagehand {
     get history(): ReadonlyArray<HistoryEntry>;
 }
 
-export { type ActOptions, type ActResult, type ActionExecutionResult, type AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentOptions, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, type CreateChatCompletionOptions, CreateChatCompletionResponseError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, LLMClient, type LLMResponse, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult, type OperatorResponse, type OperatorSummary, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandDefaultError, StagehandDeprecationError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotImplementedError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, type ToolUseItem, UnsupportedModelError, UnsupportedModelProviderError, defaultExtractSchema, operatorResponseSchema, operatorSummarySchema, pageTextSchema };
+export { type ActOptions, type ActResult, type ActionExecutionResult, type AgentAction, type AgentClientOptions, type AgentConfig, type AgentExecuteOptions, type AgentExecuteParams, type AgentExecutionOptions, type AgentHandlerOptions, type AgentOptions, type AgentProviderType, type AgentResult, AgentScreenshotProviderError, type AgentType, AnnotatedScreenshotText, type AnthropicContentBlock, type AnthropicJsonSchemaObject, type AnthropicMessage, type AnthropicTextBlock, type AnthropicToolResult, type AvailableModel, AvailableModelSchema, type Browser, type BrowserContext, type BrowserResult, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, type ChatCompletionOptions, type ChatMessage, type ChatMessageContent, type ChatMessageImageContent, type ChatMessageTextContent, type ClientOptions, type ComputerCallItem, type ConstructorParams, type CreateChatCompletionOptions, CreateChatCompletionResponseError, type ExtractOptions, type ExtractResult, type FunctionCallItem, type GotoOptions, HandlerNotInitializedError, type HistoryEntry, type InitResult, LLMClient, type LLMResponse, LOG_LEVEL_NAMES, type LocalBrowserLaunchOptions, type LogLevel, type LogLine, type Logger, MissingEnvironmentVariableError, MissingLLMConfigurationError, type ModelProvider, type ObserveOptions, type ObserveResult, type OperatorResponse, type OperatorSummary, type Page, PlaywrightCommandException, PlaywrightCommandMethodNotSupportedException, type ResponseInputItem, type ResponseItem, Stagehand, StagehandAPIError, StagehandAPIUnauthorizedError, StagehandDefaultError, StagehandDeprecationError, StagehandDomProcessError, StagehandElementNotFoundError, StagehandEnvironmentError, StagehandError, StagehandEvalError, StagehandFunctionName, StagehandHttpError, StagehandInvalidArgumentError, type StagehandMetrics, StagehandMissingArgumentError, StagehandNotImplementedError, StagehandNotInitializedError, StagehandResponseBodyError, StagehandResponseParseError, StagehandServerError, type ToolUseItem, UnsupportedModelError, UnsupportedModelProviderError, type ZodPathSegments, defaultExtractSchema, operatorResponseSchema, operatorSummarySchema, pageTextSchema };

package/dist/index.js

@@ -188,7 +188,7 @@ Please keep the user's instructions in mind when performing actions. If the user
 User Instructions:
 ${userProvidedInstructions}`;
 }
-function buildExtractSystemPrompt(isUsingPrintExtractedDataTool = false, useTextExtract = true, userProvidedInstructions) {
+function buildExtractSystemPrompt(isUsingPrintExtractedDataTool = false, useTextExtract = false, userProvidedInstructions) {
   const baseContent = `You are extracting content on behalf of a user.
   If a user asks you to extract a 'list' of information, or 'all' information, 
   YOU MUST EXTRACT ALL OF THE INFORMATION THAT THE USER REQUESTS.
@@ -207,7 +207,7 @@ ONLY print the content using the print_extracted_data tool provided.
   `.trim() : "";
   const additionalInstructions = useTextExtract ? `Once you are given the text-rendered webpage, 
     you must thoroughly and meticulously analyze it. Be very careful to ensure that you
-    do not miss any important information.` : "";
+    do not miss any important information.` : "If a user is attempting to extract links or URLs, you MUST respond with ONLY the IDs of the link elements. \nDo not attempt to extract links directly from the text unless absolutely necessary. ";
   const userInstructions = buildUserInstructionsString(
     userProvidedInstructions
   );
@@ -261,7 +261,6 @@ Refined content:`
 }
 var metadataSystemPrompt = `You are an AI assistant tasked with evaluating the progress and completion status of an extraction task.
 Analyze the extraction response and determine if the task is completed or if more information is needed.
-
 Strictly abide by the following criteria:
 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:
@@ -1233,6 +1232,9 @@ var StagehandActHandler = class {
   }
 };
 
+// lib/handlers/extractHandler.ts
+var import_zod3 = require("zod");
+
 // lib/inference.ts
 var import_zod2 = require("zod");
 
@@ -2500,11 +2502,13 @@ var StagehandExtractHandler = class {
         level: 1
       });
       const outputString = tree.simplified;
+      const idToUrlMapping = tree.idToUrl;
+      const [transformedSchema, urlFieldPaths] = transformUrlStringsToNumericIds(schema);
       const extractionResponse = yield extract({
         instruction,
         previouslyExtractedContent: content,
         domElements: outputString,
-        schema,
+        schema: transformedSchema,
         chunksSeen: 1,
         chunksTotal: 1,
         llmClient,
@@ -2565,6 +2569,9 @@ var StagehandExtractHandler = class {
           }
         });
       }
+      for (const { segments } of urlFieldPaths) {
+        injectUrls(output, segments, idToUrlMapping);
+      }
       return output;
     });
   }
@@ -2679,6 +2686,172 @@ var StagehandExtractHandler = class {
     return deduplicated;
   }
 };
+function transformUrlStringsToNumericIds(schema) {
+  const shape = schema._def.shape();
+  const newShape = {};
+  const urlPaths = [];
+  let changed = false;
+  for (const [key, value] of Object.entries(shape)) {
+    const [childTransformed, childPaths] = transformSchema(value, [key]);
+    newShape[key] = childTransformed;
+    if (childTransformed !== value) {
+      changed = true;
+    }
+    if (childPaths.length > 0) {
+      childPaths.forEach((cp) => {
+        urlPaths.push({ segments: [key, ...cp.segments] });
+      });
+    }
+  }
+  const finalSchema = changed ? import_zod3.z.object(newShape) : schema;
+  return [finalSchema, urlPaths];
+}
+function transformSchema(schema, currentPath) {
+  var _a, _b;
+  if (schema instanceof import_zod3.z.ZodString) {
+    const hasUrlCheck = (_b = (_a = schema._def.checks) == null ? void 0 : _a.some((check) => check.kind === "url")) != null ? _b : false;
+    if (hasUrlCheck) {
+      return [
+        import_zod3.z.number().describe("ID of element that points to a URL"),
+        [{ segments: [] }]
+      ];
+    }
+    return [schema, []];
+  }
+  if (schema instanceof import_zod3.z.ZodObject) {
+    const shape = schema._def.shape();
+    const newShape = {};
+    const urlPaths = [];
+    let changed = false;
+    const shapeKeys = Object.keys(shape);
+    for (const key of shapeKeys) {
+      const child = shape[key];
+      const [transformedChild, childPaths] = transformSchema(child, [
+        ...currentPath,
+        key
+      ]);
+      if (transformedChild !== child) {
+        changed = true;
+      }
+      newShape[key] = transformedChild;
+      if (childPaths.length > 0) {
+        for (const cp of childPaths) {
+          urlPaths.push({ segments: [key, ...cp.segments] });
+        }
+      }
+    }
+    if (changed) {
+      return [import_zod3.z.object(newShape), urlPaths];
+    }
+    return [schema, urlPaths];
+  }
+  if (schema instanceof import_zod3.z.ZodArray) {
+    const itemType = schema._def.type;
+    const [transformedItem, childPaths] = transformSchema(itemType, [
+      ...currentPath,
+      "*"
+    ]);
+    const changed = transformedItem !== itemType;
+    const arrayPaths = childPaths.map((cp) => ({
+      segments: ["*", ...cp.segments]
+    }));
+    if (changed) {
+      return [import_zod3.z.array(transformedItem), arrayPaths];
+    }
+    return [schema, arrayPaths];
+  }
+  if (schema instanceof import_zod3.z.ZodUnion) {
+    const unionOptions = schema._def.options;
+    const newOptions = [];
+    let changed = false;
+    let allPaths = [];
+    unionOptions.forEach((option, idx) => {
+      const [newOption, childPaths] = transformSchema(option, [
+        ...currentPath,
+        `union_${idx}`
+      ]);
+      if (newOption !== option) {
+        changed = true;
+      }
+      newOptions.push(newOption);
+      allPaths = [...allPaths, ...childPaths];
+    });
+    if (changed) {
+      return [
+        import_zod3.z.union(newOptions),
+        allPaths
+      ];
+    }
+    return [schema, allPaths];
+  }
+  if (schema instanceof import_zod3.z.ZodIntersection) {
+    const leftType = schema._def.left;
+    const rightType = schema._def.right;
+    const [left, leftPaths] = transformSchema(leftType, [
+      ...currentPath,
+      "intersection_left"
+    ]);
+    const [right, rightPaths] = transformSchema(rightType, [
+      ...currentPath,
+      "intersection_right"
+    ]);
+    const changed = left !== leftType || right !== rightType;
+    const allPaths = [...leftPaths, ...rightPaths];
+    if (changed) {
+      return [import_zod3.z.intersection(left, right), allPaths];
+    }
+    return [schema, allPaths];
+  }
+  if (schema instanceof import_zod3.z.ZodOptional) {
+    const innerType = schema._def.innerType;
+    const [inner, innerPaths] = transformSchema(innerType, currentPath);
+    if (inner !== innerType) {
+      return [import_zod3.z.optional(inner), innerPaths];
+    }
+    return [schema, innerPaths];
+  }
+  if (schema instanceof import_zod3.z.ZodNullable) {
+    const innerType = schema._def.innerType;
+    const [inner, innerPaths] = transformSchema(innerType, currentPath);
+    if (inner !== innerType) {
+      return [import_zod3.z.nullable(inner), innerPaths];
+    }
+    return [schema, innerPaths];
+  }
+  if (schema instanceof import_zod3.z.ZodEffects) {
+    const baseSchema = schema._def.schema;
+    const [newBaseSchema, basePaths] = transformSchema(baseSchema, currentPath);
+    if (newBaseSchema !== baseSchema) {
+      return [import_zod3.z.effect(newBaseSchema, schema._def.effect), basePaths];
+    }
+    return [schema, basePaths];
+  }
+  return [schema, []];
+}
+function injectUrls(obj, path4, idToUrlMapping) {
+  if (path4.length === 0) return;
+  const [key, ...rest] = path4;
+  if (key === "*") {
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        injectUrls(item, rest, idToUrlMapping);
+      }
+    }
+    return;
+  }
+  if (obj && typeof obj === "object") {
+    const record = obj;
+    if (path4.length === 1) {
+      const fieldValue = record[key];
+      if (typeof fieldValue === "number") {
+        const mappedUrl = idToUrlMapping[String(fieldValue)];
+        record[key] = mappedUrl != null ? mappedUrl : ``;
+      }
+    } else {
+      injectUrls(record[key], rest, idToUrlMapping);
+    }
+  }
+}
 
 // lib/handlers/observeHandler.ts
 var StagehandObserveHandler = class {
@@ -5647,7 +5820,7 @@ var GroqClient = class extends LLMClient {
 
 // lib/llm/OpenAIClient.ts
 var import_openai3 = __toESM(require("openai"));
-var import_zod3 = require("openai/helpers/zod");
+var import_zod4 = require("openai/helpers/zod");
 var import_zod_to_json_schema6 = __toESM(require("zod-to-json-schema"));
 var OpenAIClient = class extends LLMClient {
   constructor({
@@ -5835,7 +6008,7 @@ ${parsedSchema}
             throw error;
           }
         } else {
-          responseFormat = (0, import_zod3.zodResponseFormat)(
+          responseFormat = (0, import_zod4.zodResponseFormat)(
             options.response_model.schema,
             options.response_model.name
           );
@@ -7697,12 +7870,12 @@ var StagehandAgentHandler = class {
 };
 
 // types/operator.ts
-var import_zod4 = require("zod");
-var operatorResponseSchema = import_zod4.z.object({
-  reasoning: import_zod4.z.string().describe(
+var import_zod5 = require("zod");
+var operatorResponseSchema = import_zod5.z.object({
+  reasoning: import_zod5.z.string().describe(
     "The reasoning for the step taken. If this step's method is `close`, the goal was to extract data, and the task was successful, state the data that was extracted."
   ),
-  method: import_zod4.z.enum([
+  method: import_zod5.z.enum([
     "act",
     "extract",
     "goto",
@@ -7718,7 +7891,7 @@ var operatorResponseSchema = import_zod4.z.object({
       wait: Wait for a period of time.
       navback: Navigate back to the previous page. Do not navigate back if you are already on the first page.
       refresh: Refresh the page.`),
-  parameters: import_zod4.z.string().describe(
+  parameters: import_zod5.z.string().describe(
     `The parameter for the action. Only pass in a parameter for the following methods:
         - act: The action to perform. e.g. "click on the submit button" or "type [email] into the email input field and press enter"
         - extract: The data to extract. e.g. "the title of the article". If you want to extract all of the text on the page, leave this undefined.
@@ -7726,12 +7899,12 @@ var operatorResponseSchema = import_zod4.z.object({
         - goto: The URL to navigate to. e.g. "https://www.google.com"
         The other methods do not require a parameter.`
   ).optional(),
-  taskComplete: import_zod4.z.boolean().describe(
+  taskComplete: import_zod5.z.boolean().describe(
     "Whether the task is complete. If true, the task is complete and no more steps are needed. If you chose to close the task because the goal is not achievable, set this to false."
   )
 });
-var operatorSummarySchema = import_zod4.z.object({
-  answer: import_zod4.z.string().describe("The final answer to the original instruction.")
+var operatorSummarySchema = import_zod5.z.object({
+  answer: import_zod5.z.string().describe("The final answer to the original instruction.")
 });
 
 // lib/handlers/operatorHandler.ts
@@ -8133,8 +8306,8 @@ var LOG_LEVEL_NAMES = {
 };
 
 // types/model.ts
-var import_zod5 = require("zod");
-var AvailableModelSchema = import_zod5.z.enum([
+var import_zod6 = require("zod");
+var AvailableModelSchema = import_zod6.z.enum([
   "gpt-4o",
   "gpt-4o-mini",
   "gpt-4o-2024-08-06",
@@ -8317,18 +8490,6 @@ function getBrowser(apiKey, projectId, env = "LOCAL", headless = false, logger,
           }
         }
       });
-      if (localBrowserLaunchOptions) {
-        logger({
-          category: "init",
-          message: "local browser launch options",
-          auxiliary: {
-            localLaunchOptions: {
-              value: JSON.stringify(localBrowserLaunchOptions),
-              type: "string"
-            }
-          }
-        });
-      }
       if (localBrowserLaunchOptions == null ? void 0 : localBrowserLaunchOptions.cdpUrl) {
         if (!localBrowserLaunchOptions.cdpUrl.includes("connect.connect")) {
           logger({

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

@@ -1,4 +1,5 @@
-import { z } from "zod";
+import { z, ZodTypeAny } from "zod";
+import { ZodPathSegments } from "../../types/stagehand";
 import { LLMClient } from "../llm/LLMClient";
 import { StagehandPage } from "../StagehandPage";
 import { Stagehand } from "../index";
@@ -97,3 +98,35 @@ export declare class StagehandExtractHandler {
      */
     private deduplicateAnnotations;
 }
+/**
+ * Scans the provided Zod schema for any `z.string().url()` fields and
+ * replaces them with `z.number()`.
+ *
+ * @param schema - The Zod object schema to transform.
+ * @returns A tuple containing:
+ *   1. The transformed schema (or the original schema if no changes were needed).
+ *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,
+ *      with each path segment showing where in the schema the replacement occurred.
+ */
+export declare function transformUrlStringsToNumericIds<T extends z.ZodObject<z.ZodRawShape>>(schema: T): [T, ZodPathSegments[]];
+/**
+ * Recursively traverses a given Zod schema, scanning for any fields of type `z.string().url()`.
+ * For each such field, it replaces the `z.string().url()` with `z.number()`.
+ *
+ * This function is used internally by higher-level utilities (e.g., transforming entire object schemas)
+ * and handles nested objects, arrays, unions, intersections, optionals.
+ *
+ * @param schema - The Zod schema to transform.
+ * @param currentPath - An array of string/number keys representing the current schema path (used internally for recursion).
+ * @returns A two-element tuple:
+ *   1. The updated Zod schema, with any `.url()` fields replaced by `z.number()`.
+ *   2. An array of {@link ZodPathSegments} objects representing each replaced field, including the path segments.
+ */
+export declare function transformSchema(schema: ZodTypeAny, currentPath: Array<string | number>): [ZodTypeAny, ZodPathSegments[]];
+/**
+ * Once we get the final extracted object that has numeric IDs in place of URLs,
+ * use `injectUrls` to walk the object and replace numeric IDs
+ * with the real URL strings from idToUrlMapping. The `path` may include `*`
+ * for array indices (indicating "all items in the array").
+ */
+export declare function injectUrls(obj: unknown, path: Array<string | number>, idToUrlMapping: Record<string, string>): void;

package/dist/types/stagehand.d.ts

@@ -269,3 +269,20 @@ export interface HistoryEntry {
     result: unknown;
     timestamp: string;
 }
+/**
+ * Represents a path through a Zod schema from the root object down to a
+ * particular field. The `segments` array describes the chain of keys/indices.
+ *
+ * - **String** segments indicate object property names.
+ * - **Number** segments indicate array indices.
+ *
+ * For example, `["users", 0, "homepage"]` might describe reaching
+ * the `homepage` field in `schema.users[0].homepage`.
+ */
+export interface ZodPathSegments {
+    /**
+     * The ordered list of keys/indices leading from the schema root
+     * to the targeted field.
+     */
+    segments: Array<string | number>;
+}

package/lib/handlers/extractHandler.ts

@@ -1,5 +1,6 @@
-import { z } from "zod";
+import { z, ZodTypeAny } from "zod";
 import { LogLine } from "../../types/log";
+import { ZodPathSegments } from "../../types/stagehand";
 import { TextAnnotation } from "../../types/textannotation";
 import { extract } from "../inference";
 import { LLMClient } from "../llm/LLMClient";
@@ -420,12 +421,18 @@ export class StagehandExtractHandler {
       level: 1,
     });
     const outputString = tree.simplified;
+    const idToUrlMapping = tree.idToUrl;
 
+    // Transform user defined schema to replace string().url() with .number()
+    const [transformedSchema, urlFieldPaths] =
+      transformUrlStringsToNumericIds(schema);
+
+    // call extract inference with transformed schema
     const extractionResponse = await extract({
       instruction,
       previouslyExtractedContent: content,
       domElements: outputString,
-      schema,
+      schema: transformedSchema,
       chunksSeen: 1,
       chunksTotal: 1,
       llmClient,
@@ -486,9 +493,14 @@ export class StagehandExtractHandler {
         },
       });
     }
-    return output;
-  }
 
+    // revert to original schema and populate with URLs
+    for (const { segments } of urlFieldPaths) {
+      injectUrls(output, segments, idToUrlMapping);
+    }
+
+    return output as z.infer<T>;
+  }
   /**
    * Get the width, height, and offsets of either the entire page or a specific element.
    * (Matches your existing getTargetDimensions logic, just adapted to accept a string | undefined.)
@@ -642,3 +654,243 @@ export class StagehandExtractHandler {
     return deduplicated;
   }
 }
+
+/**
+ * Scans the provided Zod schema for any `z.string().url()` fields and
+ * replaces them with `z.number()`.
+ *
+ * @param schema - The Zod object schema to transform.
+ * @returns A tuple containing:
+ *   1. The transformed schema (or the original schema if no changes were needed).
+ *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,
+ *      with each path segment showing where in the schema the replacement occurred.
+ */
+export function transformUrlStringsToNumericIds<
+  T extends z.ZodObject<z.ZodRawShape>,
+>(schema: T): [T, ZodPathSegments[]] {
+  const shape = schema._def.shape();
+  const newShape: Record<string, ZodTypeAny> = {};
+  const urlPaths: ZodPathSegments[] = [];
+  let changed = false;
+
+  for (const [key, value] of Object.entries(shape)) {
+    const [childTransformed, childPaths] = transformSchema(value, [key]);
+    newShape[key] = childTransformed;
+    if (childTransformed !== value) {
+      changed = true;
+    }
+    if (childPaths.length > 0) {
+      childPaths.forEach((cp) => {
+        urlPaths.push({ segments: [key, ...cp.segments] });
+      });
+    }
+  }
+
+  const finalSchema = changed ? z.object(newShape) : schema;
+  return [finalSchema as T, urlPaths];
+}
+
+/**
+ * Recursively traverses a given Zod schema, scanning for any fields of type `z.string().url()`.
+ * For each such field, it replaces the `z.string().url()` with `z.number()`.
+ *
+ * This function is used internally by higher-level utilities (e.g., transforming entire object schemas)
+ * and handles nested objects, arrays, unions, intersections, optionals.
+ *
+ * @param schema - The Zod schema to transform.
+ * @param currentPath - An array of string/number keys representing the current schema path (used internally for recursion).
+ * @returns A two-element tuple:
+ *   1. The updated Zod schema, with any `.url()` fields replaced by `z.number()`.
+ *   2. An array of {@link ZodPathSegments} objects representing each replaced field, including the path segments.
+ */
+export function transformSchema(
+  schema: ZodTypeAny,
+  currentPath: Array<string | number>,
+): [ZodTypeAny, ZodPathSegments[]] {
+  // 1) If it's a string with .url(), convert to z.number()
+  if (schema instanceof z.ZodString) {
+    const hasUrlCheck =
+      schema._def.checks?.some((check) => check.kind === "url") ?? false;
+    if (hasUrlCheck) {
+      return [
+        z.number().describe("ID of element that points to a URL"),
+        [{ segments: [] }],
+      ];
+    }
+    return [schema, []];
+  }
+
+  // 2) If it's an object, transform each field
+  if (schema instanceof z.ZodObject) {
+    // The shape is a raw object containing fields keyed by string (no symbols):
+    const shape = schema._def.shape() as Record<string, ZodTypeAny>;
+    const newShape: Record<string, ZodTypeAny> = {};
+    const urlPaths: ZodPathSegments[] = [];
+    let changed = false;
+
+    const shapeKeys = Object.keys(shape);
+
+    for (const key of shapeKeys) {
+      const child = shape[key];
+      const [transformedChild, childPaths] = transformSchema(child, [
+        ...currentPath,
+        key,
+      ]);
+
+      if (transformedChild !== child) {
+        changed = true;
+      }
+      newShape[key] = transformedChild;
+
+      if (childPaths.length > 0) {
+        for (const cp of childPaths) {
+          urlPaths.push({ segments: [key, ...cp.segments] });
+        }
+      }
+    }
+
+    if (changed) {
+      return [z.object(newShape), urlPaths];
+    }
+    return [schema, urlPaths];
+  }
+
+  // 3) If it's an array, transform its item type
+  if (schema instanceof z.ZodArray) {
+    const itemType = schema._def.type as ZodTypeAny;
+    const [transformedItem, childPaths] = transformSchema(itemType, [
+      ...currentPath,
+      "*",
+    ]);
+    const changed = transformedItem !== itemType;
+    const arrayPaths: ZodPathSegments[] = childPaths.map((cp) => ({
+      segments: ["*", ...cp.segments],
+    }));
+
+    if (changed) {
+      return [z.array(transformedItem), arrayPaths];
+    }
+    return [schema, arrayPaths];
+  }
+
+  // 4) If it's a union, transform each option
+  if (schema instanceof z.ZodUnion) {
+    // Cast the union’s options to an array of ZodTypeAny
+    const unionOptions = schema._def.options as ZodTypeAny[];
+    const newOptions: ZodTypeAny[] = [];
+    let changed = false;
+    let allPaths: ZodPathSegments[] = [];
+
+    unionOptions.forEach((option: ZodTypeAny, idx: number) => {
+      const [newOption, childPaths] = transformSchema(option, [
+        ...currentPath,
+        `union_${idx}`,
+      ]);
+      if (newOption !== option) {
+        changed = true;
+      }
+      newOptions.push(newOption);
+      allPaths = [...allPaths, ...childPaths];
+    });
+
+    if (changed) {
+      // We assume at least two options remain:
+      return [
+        z.union(newOptions as [ZodTypeAny, ZodTypeAny, ...ZodTypeAny[]]),
+        allPaths,
+      ];
+    }
+    return [schema, allPaths];
+  }
+
+  // 5) If it's an intersection, transform left and right
+  if (schema instanceof z.ZodIntersection) {
+    const leftType = schema._def.left as ZodTypeAny;
+    const rightType = schema._def.right as ZodTypeAny;
+
+    const [left, leftPaths] = transformSchema(leftType, [
+      ...currentPath,
+      "intersection_left",
+    ]);
+    const [right, rightPaths] = transformSchema(rightType, [
+      ...currentPath,
+      "intersection_right",
+    ]);
+    const changed = left !== leftType || right !== rightType;
+    const allPaths = [...leftPaths, ...rightPaths];
+    if (changed) {
+      return [z.intersection(left, right), allPaths];
+    }
+    return [schema, allPaths];
+  }
+
+  // 6) If it's optional, transform inner
+  if (schema instanceof z.ZodOptional) {
+    const innerType = schema._def.innerType as ZodTypeAny;
+    const [inner, innerPaths] = transformSchema(innerType, currentPath);
+    if (inner !== innerType) {
+      return [z.optional(inner), innerPaths];
+    }
+    return [schema, innerPaths];
+  }
+
+  // 7) If it's nullable, transform inner
+  if (schema instanceof z.ZodNullable) {
+    const innerType = schema._def.innerType as ZodTypeAny;
+    const [inner, innerPaths] = transformSchema(innerType, currentPath);
+    if (inner !== innerType) {
+      return [z.nullable(inner), innerPaths];
+    }
+    return [schema, innerPaths];
+  }
+
+  // 8) If it's an effect, transform base schema
+  if (schema instanceof z.ZodEffects) {
+    const baseSchema = schema._def.schema as ZodTypeAny;
+    const [newBaseSchema, basePaths] = transformSchema(baseSchema, currentPath);
+    if (newBaseSchema !== baseSchema) {
+      return [z.effect(newBaseSchema, schema._def.effect), basePaths];
+    }
+    return [schema, basePaths];
+  }
+
+  // 9) If none of the above, return as-is
+  return [schema, []];
+}
+
+/**
+ * Once we get the final extracted object that has numeric IDs in place of URLs,
+ * use `injectUrls` to walk the object and replace numeric IDs
+ * with the real URL strings from idToUrlMapping. The `path` may include `*`
+ * for array indices (indicating "all items in the array").
+ */
+export function injectUrls(
+  obj: unknown,
+  path: Array<string | number>,
+  idToUrlMapping: Record<string, string>,
+): void {
+  if (path.length === 0) return;
+  const [key, ...rest] = path;
+
+  if (key === "*") {
+    if (Array.isArray(obj)) {
+      for (const item of obj) {
+        injectUrls(item, rest, idToUrlMapping);
+      }
+    }
+    return;
+  }
+
+  if (obj && typeof obj === "object") {
+    const record = obj as Record<string | number, unknown>;
+    if (path.length === 1) {
+      const fieldValue = record[key];
+      if (typeof fieldValue === "number") {
+        const mappedUrl = idToUrlMapping[String(fieldValue)];
+        record[key] = mappedUrl ?? ``;
+      }
+    } else {
+      injectUrls(record[key], rest, idToUrlMapping);
+    }
+  }
+}

package/lib/index.ts

@@ -236,19 +236,6 @@ async function getBrowser(
       },
     });
 
-    if (localBrowserLaunchOptions) {
-      logger({
-        category: "init",
-        message: "local browser launch options",
-        auxiliary: {
-          localLaunchOptions: {
-            value: JSON.stringify(localBrowserLaunchOptions),
-            type: "string",
-          },
-        },
-      });
-    }
-
     if (localBrowserLaunchOptions?.cdpUrl) {
       if (!localBrowserLaunchOptions.cdpUrl.includes("connect.connect")) {
         logger({

package/lib/prompt.ts

@@ -18,7 +18,7 @@ ${userProvidedInstructions}`;
 // extract
 export function buildExtractSystemPrompt(
   isUsingPrintExtractedDataTool: boolean = false,
-  useTextExtract: boolean = true,
+  useTextExtract: boolean = false,
   userProvidedInstructions?: string,
 ): ChatMessage {
   const baseContent = `You are extracting content on behalf of a user.
@@ -51,7 +51,8 @@ ONLY print the content using the print_extracted_data tool provided.
     ? `Once you are given the text-rendered webpage, 
     you must thoroughly and meticulously analyze it. Be very careful to ensure that you
     do not miss any important information.`
-    : "";
+    : "If a user is attempting to extract links or URLs, you MUST respond with ONLY the IDs of the link elements. \n" +
+      "Do not attempt to extract links directly from the text unless absolutely necessary. ";
 
   const userInstructions = buildUserInstructionsString(
     userProvidedInstructions,
@@ -119,7 +120,6 @@ Refined content:`,
 
 const metadataSystemPrompt = `You are an AI assistant tasked with evaluating the progress and completion status of an extraction task.
 Analyze the extraction response and determine if the task is completed or if more information is needed.
-
 Strictly abide by the following criteria:
 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:

package/package.json

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