@browserbasehq/orca 3.4.0-preview-5 → 3.5.0-preview.0

package/dist/cjs/lib/inference.d.ts

@@ -3,7 +3,7 @@ import { LLMClient } from "./v3/llm/LLMClient.js";
 import type { InferStagehandSchema, StagehandZodObject } from "./v3/zodCompat.js";
 import type { Variables } from "./v3/types/public/agent.js";
 export type { LLMParsedResponse, LLMUsage } from "./v3/llm/LLMClient.js";
-export declare function extract<T extends StagehandZodObject>({ instruction, domElements, schema, llmClient, logger, userProvidedInstructions, logInferenceToFile, }: {
+export declare function extract<T extends StagehandZodObject>({ instruction, domElements, schema, llmClient, logger, userProvidedInstructions, logInferenceToFile, screenshot, }: {
     instruction: string;
     domElements: string;
     schema: T;
@@ -11,6 +11,7 @@ export declare function extract<T extends StagehandZodObject>({ instruction, dom
     userProvidedInstructions?: string;
     logger: (message: LogLine) => void;
     logInferenceToFile?: boolean;
+    screenshot?: Buffer;
 }): Promise<InferStagehandSchema<T> & {
     metadata: {
         completed: boolean;

package/dist/cjs/lib/inference.js

@@ -8,10 +8,11 @@ const timeoutConfig_js_1 = require("./v3/timeoutConfig.js");
 const prompt_js_1 = require("./prompt.js");
 const inferenceLogUtils_js_1 = require("./inferenceLogUtils.js");
 const handlers_js_1 = require("./v3/types/private/handlers.js");
+const sdkErrors_js_1 = require("./v3/types/public/sdkErrors.js");
 function withLlmTimeout(promise, operation) {
     return (0, timeoutConfig_js_1.withTimeout)(promise, (0, timeoutConfig_js_1.getEnvTimeoutMs)("LLM_MAX_MS"), `LLM ${operation}`);
 }
-async function extract({ instruction, domElements, schema, llmClient, logger, userProvidedInstructions, logInferenceToFile = false, }) {
+async function extract({ instruction, domElements, schema, llmClient, logger, userProvidedInstructions, logInferenceToFile = false, screenshot, }) {
     const metadataSchema = zod_1.z.object({
         progress: zod_1.z
             .string()
@@ -21,9 +22,15 @@ async function extract({ instruction, domElements, schema, llmClient, logger, us
             .describe("true if the goal is now accomplished. Use this conservatively, only when sure that the goal has been completed."),
     });
     const isUsingAnthropic = llmClient.type === "anthropic";
+    if (screenshot && llmClient.type !== "aisdk") {
+        throw new sdkErrors_js_1.StagehandInvalidArgumentError("extract({ screenshot: true }) is only supported with AI SDK clients.");
+    }
+    const screenshotDataUrl = screenshot
+        ? `data:image/png;base64,${screenshot.toString("base64")}`
+        : undefined;
     const extractCallMessages = [
-        (0, prompt_js_1.buildExtractSystemPrompt)(isUsingAnthropic, userProvidedInstructions),
-        (0, prompt_js_1.buildExtractUserPrompt)(instruction, domElements, isUsingAnthropic),
+        (0, prompt_js_1.buildExtractSystemPrompt)(isUsingAnthropic, userProvidedInstructions, Boolean(screenshotDataUrl)),
+        (0, prompt_js_1.buildExtractUserPrompt)(instruction, domElements, isUsingAnthropic, screenshotDataUrl),
     ];
     let extractCallFile = "";
     let extractCallTimestamp = "";

package/dist/cjs/lib/inference.js.map

@@ -1 +1 @@
-{"version":3,"file":"inference.js","sourceRoot":"","sources":["../../../lib/inference.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport { LogLine } from \"./v3/types/public/logs.js\";\nimport { ChatMessage, LLMClient } from \"./v3/llm/LLMClient.js\";\nimport { getEnvTimeoutMs, withTimeout } from \"./v3/timeoutConfig.js\";\nimport {\n  buildActSystemPrompt,\n  buildExtractSystemPrompt,\n  buildExtractUserPrompt,\n  buildMetadataPrompt,\n  buildMetadataSystemPrompt,\n  buildObserveSystemPrompt,\n  buildObserveUserMessage,\n} from \"./prompt.js\";\nimport { appendSummary, writeTimestampedTxtFile } from \"./inferenceLogUtils.js\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodObject,\n} from \"./v3/zodCompat.js\";\nimport { SupportedUnderstudyAction } from \"./v3/types/private/handlers.js\";\nimport type { Variables } from \"./v3/types/public/agent.js\";\n\n// Re-export for backward compatibility\nexport type { LLMParsedResponse, LLMUsage } from \"./v3/llm/LLMClient.js\";\n\nfunction withLlmTimeout<T>(promise: Promise<T>, operation: string): Promise<T> {\n  return withTimeout(\n    promise,\n    getEnvTimeoutMs(\"LLM_MAX_MS\"),\n    `LLM ${operation}`,\n  );\n}\n\nexport async function extract<T extends StagehandZodObject>({\n  instruction,\n  domElements,\n  schema,\n  llmClient,\n  logger,\n  userProvidedInstructions,\n  logInferenceToFile = false,\n}: {\n  instruction: string;\n  domElements: string;\n  schema: T;\n  llmClient: LLMClient;\n  userProvidedInstructions?: string;\n  logger: (message: LogLine) => void;\n  logInferenceToFile?: boolean;\n}) {\n  const metadataSchema = z.object({\n    progress: z\n      .string()\n      .describe(\n        \"progress of what has been extracted so far, as concise as possible\",\n      ),\n    completed: z\n      .boolean()\n      .describe(\n        \"true if the goal is now accomplished. Use this conservatively, only when sure that the goal has been completed.\",\n      ),\n  });\n\n  type ExtractionResponse = InferStagehandSchema<T>;\n  type MetadataResponse = z.infer<typeof metadataSchema>;\n\n  const isUsingAnthropic = llmClient.type === \"anthropic\";\n\n  const extractCallMessages: ChatMessage[] = [\n    buildExtractSystemPrompt(isUsingAnthropic, userProvidedInstructions),\n    buildExtractUserPrompt(instruction, domElements, isUsingAnthropic),\n  ];\n\n  let extractCallFile = \"\";\n  let extractCallTimestamp = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"extract_call\",\n      {\n        modelCall: \"extract\",\n        messages: extractCallMessages,\n      },\n    );\n    extractCallFile = fileName;\n    extractCallTimestamp = timestamp;\n  }\n\n  const extractStartTime = Date.now();\n  const extractionResponse = await withLlmTimeout(\n    llmClient.createChatCompletion<ExtractionResponse>({\n      options: {\n        messages: extractCallMessages,\n        response_model: {\n          schema,\n          name: \"Extraction\",\n        },\n        top_p: 1,\n        frequency_penalty: 0,\n        presence_penalty: 0,\n      },\n      logger,\n    }),\n    \"extract\",\n  );\n  const extractEndTime = Date.now();\n\n  const { data: extractedData, usage: extractUsage } = extractionResponse;\n\n  let extractResponseFile: string;\n  if (logInferenceToFile) {\n    const { fileName } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"extract_response\",\n      {\n        modelResponse: \"extract\",\n        rawResponse: extractedData,\n      },\n    );\n    extractResponseFile = fileName;\n\n    appendSummary(\"extract\", {\n      extract_inference_type: \"extract\",\n      timestamp: extractCallTimestamp,\n      LLM_input_file: extractCallFile,\n      LLM_output_file: extractResponseFile,\n      prompt_tokens: extractUsage?.prompt_tokens ?? 0,\n      completion_tokens: extractUsage?.completion_tokens ?? 0,\n      reasoning_tokens: extractUsage?.reasoning_tokens ?? 0,\n      cached_input_tokens: extractUsage?.cached_input_tokens ?? 0,\n      inference_time_ms: extractEndTime - extractStartTime,\n    });\n  }\n\n  const metadataCallMessages: ChatMessage[] = [\n    buildMetadataSystemPrompt(),\n    buildMetadataPrompt(instruction, extractedData),\n  ];\n\n  let metadataCallFile = \"\";\n  let metadataCallTimestamp = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"metadata_call\",\n      {\n        modelCall: \"metadata\",\n        messages: metadataCallMessages,\n      },\n    );\n    metadataCallFile = fileName;\n    metadataCallTimestamp = timestamp;\n  }\n\n  const metadataStartTime = Date.now();\n  const metadataResponse = await withLlmTimeout(\n    llmClient.createChatCompletion<MetadataResponse>({\n      options: {\n        messages: metadataCallMessages,\n        response_model: {\n          name: \"Metadata\",\n          schema: metadataSchema,\n        },\n        top_p: 1,\n        frequency_penalty: 0,\n        presence_penalty: 0,\n      },\n      logger,\n    }),\n    \"extract metadata\",\n  );\n  const metadataEndTime = Date.now();\n\n  const {\n    data: {\n      completed: metadataResponseCompleted,\n      progress: metadataResponseProgress,\n    },\n    usage: metadataResponseUsage,\n  } = metadataResponse;\n\n  let metadataResponseFile: string;\n  if (logInferenceToFile) {\n    const { fileName } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"metadata_response\",\n      {\n        modelResponse: \"metadata\",\n        completed: metadataResponseCompleted,\n        progress: metadataResponseProgress,\n      },\n    );\n    metadataResponseFile = fileName;\n\n    appendSummary(\"extract\", {\n      extract_inference_type: \"metadata\",\n      timestamp: metadataCallTimestamp,\n      LLM_input_file: metadataCallFile,\n      LLM_output_file: metadataResponseFile,\n      prompt_tokens: metadataResponseUsage?.prompt_tokens ?? 0,\n      completion_tokens: metadataResponseUsage?.completion_tokens ?? 0,\n      reasoning_tokens: metadataResponseUsage?.reasoning_tokens ?? 0,\n      cached_input_tokens: metadataResponseUsage?.cached_input_tokens ?? 0,\n      inference_time_ms: metadataEndTime - metadataStartTime,\n    });\n  }\n\n  const totalPromptTokens =\n    (extractUsage?.prompt_tokens ?? 0) +\n    (metadataResponseUsage?.prompt_tokens ?? 0);\n\n  const totalCompletionTokens =\n    (extractUsage?.completion_tokens ?? 0) +\n    (metadataResponseUsage?.completion_tokens ?? 0);\n\n  const totalInferenceTimeMs =\n    extractEndTime - extractStartTime + (metadataEndTime - metadataStartTime);\n  const totalReasoningTokens =\n    (extractUsage?.reasoning_tokens ?? 0) +\n    (metadataResponseUsage?.reasoning_tokens ?? 0);\n  const totalCachedInputTokens =\n    (extractUsage?.cached_input_tokens ?? 0) +\n    (metadataResponseUsage?.cached_input_tokens ?? 0);\n\n  return {\n    ...extractedData,\n    metadata: {\n      completed: metadataResponseCompleted,\n      progress: metadataResponseProgress,\n    },\n    prompt_tokens: totalPromptTokens,\n    completion_tokens: totalCompletionTokens,\n    reasoning_tokens: totalReasoningTokens,\n    cached_input_tokens: totalCachedInputTokens,\n    inference_time_ms: totalInferenceTimeMs,\n  };\n}\n\nexport async function observe({\n  instruction,\n  domElements,\n  llmClient,\n  userProvidedInstructions,\n  logger,\n  logInferenceToFile = false,\n  supportedActions,\n  variables,\n}: {\n  instruction: string;\n  domElements: string;\n  llmClient: LLMClient;\n  userProvidedInstructions?: string;\n  logger: (message: LogLine) => void;\n  logInferenceToFile?: boolean;\n  supportedActions?: string[];\n  variables?: Variables;\n}) {\n  const observeSchema = z.object({\n    elements: z\n      .array(\n        z.object({\n          elementId: z\n            .string()\n            .regex(/^\\d+-\\d+$/)\n            .describe(\n              \"the exact ID string associated with the element. Never include surrounding square brackets. This field must follow the format of 'number-number'. For example, if the accessibility tree shows [0-18372], return '0-18372', not '18372'.\",\n            ),\n          description: z\n            .string()\n            .describe(\n              \"a description of the accessible element and its purpose\",\n            ),\n          method: z\n            .enum(\n              // Use Object.values() for Zod v3 compatibility - z.enum() in v3 doesn't accept TypeScript enums directly\n              Object.values(SupportedUnderstudyAction) as unknown as readonly [\n                string,\n                ...string[],\n              ],\n            )\n            .describe(\n              `the candidate method/action to interact with the element. Select one of the available Understudy interaction methods.`,\n            ),\n          arguments: z.array(\n            z\n              .string()\n              .describe(\n                \"the arguments to pass to the method. For example, for a click, the arguments are empty, but for a fill, the arguments are the value to fill in.\",\n              ),\n          ),\n        }),\n      )\n      .describe(\"an array of accessible elements that match the instruction\"),\n  });\n\n  type ObserveResponse = z.infer<typeof observeSchema>;\n\n  const messages: ChatMessage[] = [\n    buildObserveSystemPrompt(\n      userProvidedInstructions,\n      supportedActions,\n      variables,\n    ),\n    buildObserveUserMessage(instruction, domElements),\n  ];\n\n  let callTimestamp = \"\";\n  let callFile = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      `observe_summary`,\n      `observe_call`,\n      {\n        modelCall: \"observe\",\n        messages,\n      },\n    );\n    callFile = fileName;\n    callTimestamp = timestamp;\n  }\n\n  const start = Date.now();\n  const rawResponse = await llmClient.createChatCompletion<ObserveResponse>({\n    options: {\n      messages,\n      response_model: {\n        schema: observeSchema,\n        name: \"Observation\",\n      },\n      top_p: 1,\n      frequency_penalty: 0,\n      presence_penalty: 0,\n    },\n    logger,\n  });\n  const end = Date.now();\n  const usageTimeMs = end - start;\n\n  const { data: observeData, usage: observeUsage } = rawResponse;\n  const promptTokens = observeUsage?.prompt_tokens ?? 0;\n  const completionTokens = observeUsage?.completion_tokens ?? 0;\n  const reasoningTokens = observeUsage?.reasoning_tokens ?? 0;\n  const cachedInputTokens = observeUsage?.cached_input_tokens ?? 0;\n\n  let responseFile: string;\n  if (logInferenceToFile) {\n    const { fileName: responseFileName } = writeTimestampedTxtFile(\n      `observe_summary`,\n      `observe_response`,\n      {\n        modelResponse: \"observe\",\n        rawResponse: observeData,\n      },\n    );\n    responseFile = responseFileName;\n\n    appendSummary(\"observe\", {\n      [`observe_inference_type`]: \"observe\",\n      timestamp: callTimestamp,\n      LLM_input_file: callFile,\n      LLM_output_file: responseFile,\n      prompt_tokens: promptTokens,\n      completion_tokens: completionTokens,\n      reasoning_tokens: reasoningTokens,\n      cached_input_tokens: cachedInputTokens,\n      inference_time_ms: usageTimeMs,\n    });\n  }\n\n  const parsedElements =\n    observeData.elements?.map((el) => {\n      const base = {\n        elementId: el.elementId,\n        description: String(el.description),\n        method: String(el.method),\n        arguments: el.arguments,\n      };\n      return base;\n    }) ?? [];\n\n  return {\n    elements: parsedElements,\n    prompt_tokens: promptTokens,\n    completion_tokens: completionTokens,\n    reasoning_tokens: reasoningTokens,\n    cached_input_tokens: cachedInputTokens,\n    inference_time_ms: usageTimeMs,\n  };\n}\n\nexport async function act({\n  instruction,\n  domElements,\n  llmClient,\n  userProvidedInstructions,\n  logger,\n  logInferenceToFile = false,\n}: {\n  instruction: string;\n  domElements: string;\n  llmClient: LLMClient;\n  userProvidedInstructions?: string;\n  logger: (message: LogLine) => void;\n  logInferenceToFile?: boolean;\n}) {\n  const actSchema = z.object({\n    action: z\n      .object({\n        elementId: z\n          .string()\n          .regex(/^\\d+-\\d+$/)\n          .describe(\n            \"the ID string associated with the element. Never include surrounding square brackets. This field must follow the format of 'number-number'. for example, '0-76' or '16-21'\",\n          ),\n        description: z\n          .string()\n          .describe(\"a description of the accessible element and its purpose\"),\n        method: z\n          .enum(\n            // Use Object.values() for Zod v3 compatibility - z.enum() in v3 doesn't accept TypeScript enums directly\n            Object.values(SupportedUnderstudyAction) as unknown as readonly [\n              string,\n              ...string[],\n            ],\n          )\n          .describe(\n            \"the candidate method/action to interact with the element. Select one of the available Understudy interaction methods.\",\n          ),\n        arguments: z.array(\n          z\n            .string()\n            .describe(\n              \"the arguments to pass to the method. For example, for a click, the arguments are empty, but for a fill, the arguments are the value to fill in.\",\n            ),\n        ),\n      })\n      .nullable()\n      .describe(\n        \"The element to act on. Return null if no element on the page matches the instruction — do NOT fabricate or guess an element, and never emit empty strings or placeholder values.\",\n      ),\n    twoStep: z.boolean(),\n  });\n\n  type ActResponse = z.infer<typeof actSchema>;\n\n  const messages: ChatMessage[] = [\n    buildActSystemPrompt(userProvidedInstructions),\n    buildObserveUserMessage(instruction, domElements),\n  ];\n\n  let callTimestamp = \"\";\n  let callFile = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      `act_summary`,\n      `act_call`,\n      {\n        modelCall: \"act\",\n        messages,\n      },\n    );\n    callFile = fileName;\n    callTimestamp = timestamp;\n  }\n\n  const start = Date.now();\n  const rawResponse = await llmClient.createChatCompletion<ActResponse>({\n    options: {\n      messages,\n      response_model: {\n        schema: actSchema,\n        name: \"act\",\n      },\n      top_p: 1,\n      frequency_penalty: 0,\n      presence_penalty: 0,\n    },\n    logger,\n  });\n  const end = Date.now();\n  const usageTimeMs = end - start;\n\n  const { data: actData, usage: actUsage } = rawResponse;\n  const promptTokens = actUsage?.prompt_tokens ?? 0;\n  const completionTokens = actUsage?.completion_tokens ?? 0;\n  const reasoningTokens = actUsage?.reasoning_tokens ?? 0;\n  const cachedInputTokens = actUsage?.cached_input_tokens ?? 0;\n\n  let responseFile: string;\n  if (logInferenceToFile) {\n    const { fileName: responseFileName } = writeTimestampedTxtFile(\n      `act_summary`,\n      `act_response`,\n      {\n        modelResponse: \"act\",\n        rawResponse: actData,\n      },\n    );\n    responseFile = responseFileName;\n\n    appendSummary(\"act\", {\n      [`act_inference_type`]: \"act\",\n      timestamp: callTimestamp,\n      LLM_input_file: callFile,\n      LLM_output_file: responseFile,\n      prompt_tokens: promptTokens,\n      completion_tokens: completionTokens,\n      reasoning_tokens: reasoningTokens,\n      cached_input_tokens: cachedInputTokens,\n      inference_time_ms: usageTimeMs,\n    });\n  }\n\n  const parsedElement = actData.action\n    ? {\n        elementId: actData.action.elementId,\n        description: String(actData.action.description),\n        method: String(actData.action.method),\n        arguments: actData.action.arguments,\n      }\n    : undefined;\n\n  return {\n    element: parsedElement,\n    prompt_tokens: promptTokens,\n    completion_tokens: completionTokens,\n    reasoning_tokens: reasoningTokens,\n    cached_input_tokens: cachedInputTokens,\n    inference_time_ms: usageTimeMs,\n    twoStep: actData.twoStep,\n  };\n}\n"]}
+{"version":3,"file":"inference.js","sourceRoot":"","sources":["../../../lib/inference.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport { LogLine } from \"./v3/types/public/logs.js\";\nimport { ChatMessage, LLMClient } from \"./v3/llm/LLMClient.js\";\nimport { getEnvTimeoutMs, withTimeout } from \"./v3/timeoutConfig.js\";\nimport {\n  buildActSystemPrompt,\n  buildExtractSystemPrompt,\n  buildExtractUserPrompt,\n  buildMetadataPrompt,\n  buildMetadataSystemPrompt,\n  buildObserveSystemPrompt,\n  buildObserveUserMessage,\n} from \"./prompt.js\";\nimport { appendSummary, writeTimestampedTxtFile } from \"./inferenceLogUtils.js\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodObject,\n} from \"./v3/zodCompat.js\";\nimport { SupportedUnderstudyAction } from \"./v3/types/private/handlers.js\";\nimport type { Variables } from \"./v3/types/public/agent.js\";\nimport { StagehandInvalidArgumentError } from \"./v3/types/public/sdkErrors.js\";\n\n// Re-export for backward compatibility\nexport type { LLMParsedResponse, LLMUsage } from \"./v3/llm/LLMClient.js\";\n\nfunction withLlmTimeout<T>(promise: Promise<T>, operation: string): Promise<T> {\n  return withTimeout(\n    promise,\n    getEnvTimeoutMs(\"LLM_MAX_MS\"),\n    `LLM ${operation}`,\n  );\n}\n\nexport async function extract<T extends StagehandZodObject>({\n  instruction,\n  domElements,\n  schema,\n  llmClient,\n  logger,\n  userProvidedInstructions,\n  logInferenceToFile = false,\n  screenshot,\n}: {\n  instruction: string;\n  domElements: string;\n  schema: T;\n  llmClient: LLMClient;\n  userProvidedInstructions?: string;\n  logger: (message: LogLine) => void;\n  logInferenceToFile?: boolean;\n  screenshot?: Buffer;\n}) {\n  const metadataSchema = z.object({\n    progress: z\n      .string()\n      .describe(\n        \"progress of what has been extracted so far, as concise as possible\",\n      ),\n    completed: z\n      .boolean()\n      .describe(\n        \"true if the goal is now accomplished. Use this conservatively, only when sure that the goal has been completed.\",\n      ),\n  });\n\n  type ExtractionResponse = InferStagehandSchema<T>;\n  type MetadataResponse = z.infer<typeof metadataSchema>;\n\n  const isUsingAnthropic = llmClient.type === \"anthropic\";\n  if (screenshot && llmClient.type !== \"aisdk\") {\n    throw new StagehandInvalidArgumentError(\n      \"extract({ screenshot: true }) is only supported with AI SDK clients.\",\n    );\n  }\n  const screenshotDataUrl = screenshot\n    ? `data:image/png;base64,${screenshot.toString(\"base64\")}`\n    : undefined;\n\n  const extractCallMessages: ChatMessage[] = [\n    buildExtractSystemPrompt(\n      isUsingAnthropic,\n      userProvidedInstructions,\n      Boolean(screenshotDataUrl),\n    ),\n    buildExtractUserPrompt(\n      instruction,\n      domElements,\n      isUsingAnthropic,\n      screenshotDataUrl,\n    ),\n  ];\n\n  let extractCallFile = \"\";\n  let extractCallTimestamp = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"extract_call\",\n      {\n        modelCall: \"extract\",\n        messages: extractCallMessages,\n      },\n    );\n    extractCallFile = fileName;\n    extractCallTimestamp = timestamp;\n  }\n\n  const extractStartTime = Date.now();\n  const extractionResponse = await withLlmTimeout(\n    llmClient.createChatCompletion<ExtractionResponse>({\n      options: {\n        messages: extractCallMessages,\n        response_model: {\n          schema,\n          name: \"Extraction\",\n        },\n        top_p: 1,\n        frequency_penalty: 0,\n        presence_penalty: 0,\n      },\n      logger,\n    }),\n    \"extract\",\n  );\n  const extractEndTime = Date.now();\n\n  const { data: extractedData, usage: extractUsage } = extractionResponse;\n\n  let extractResponseFile: string;\n  if (logInferenceToFile) {\n    const { fileName } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"extract_response\",\n      {\n        modelResponse: \"extract\",\n        rawResponse: extractedData,\n      },\n    );\n    extractResponseFile = fileName;\n\n    appendSummary(\"extract\", {\n      extract_inference_type: \"extract\",\n      timestamp: extractCallTimestamp,\n      LLM_input_file: extractCallFile,\n      LLM_output_file: extractResponseFile,\n      prompt_tokens: extractUsage?.prompt_tokens ?? 0,\n      completion_tokens: extractUsage?.completion_tokens ?? 0,\n      reasoning_tokens: extractUsage?.reasoning_tokens ?? 0,\n      cached_input_tokens: extractUsage?.cached_input_tokens ?? 0,\n      inference_time_ms: extractEndTime - extractStartTime,\n    });\n  }\n\n  const metadataCallMessages: ChatMessage[] = [\n    buildMetadataSystemPrompt(),\n    buildMetadataPrompt(instruction, extractedData),\n  ];\n\n  let metadataCallFile = \"\";\n  let metadataCallTimestamp = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"metadata_call\",\n      {\n        modelCall: \"metadata\",\n        messages: metadataCallMessages,\n      },\n    );\n    metadataCallFile = fileName;\n    metadataCallTimestamp = timestamp;\n  }\n\n  const metadataStartTime = Date.now();\n  const metadataResponse = await withLlmTimeout(\n    llmClient.createChatCompletion<MetadataResponse>({\n      options: {\n        messages: metadataCallMessages,\n        response_model: {\n          name: \"Metadata\",\n          schema: metadataSchema,\n        },\n        top_p: 1,\n        frequency_penalty: 0,\n        presence_penalty: 0,\n      },\n      logger,\n    }),\n    \"extract metadata\",\n  );\n  const metadataEndTime = Date.now();\n\n  const {\n    data: {\n      completed: metadataResponseCompleted,\n      progress: metadataResponseProgress,\n    },\n    usage: metadataResponseUsage,\n  } = metadataResponse;\n\n  let metadataResponseFile: string;\n  if (logInferenceToFile) {\n    const { fileName } = writeTimestampedTxtFile(\n      \"extract_summary\",\n      \"metadata_response\",\n      {\n        modelResponse: \"metadata\",\n        completed: metadataResponseCompleted,\n        progress: metadataResponseProgress,\n      },\n    );\n    metadataResponseFile = fileName;\n\n    appendSummary(\"extract\", {\n      extract_inference_type: \"metadata\",\n      timestamp: metadataCallTimestamp,\n      LLM_input_file: metadataCallFile,\n      LLM_output_file: metadataResponseFile,\n      prompt_tokens: metadataResponseUsage?.prompt_tokens ?? 0,\n      completion_tokens: metadataResponseUsage?.completion_tokens ?? 0,\n      reasoning_tokens: metadataResponseUsage?.reasoning_tokens ?? 0,\n      cached_input_tokens: metadataResponseUsage?.cached_input_tokens ?? 0,\n      inference_time_ms: metadataEndTime - metadataStartTime,\n    });\n  }\n\n  const totalPromptTokens =\n    (extractUsage?.prompt_tokens ?? 0) +\n    (metadataResponseUsage?.prompt_tokens ?? 0);\n\n  const totalCompletionTokens =\n    (extractUsage?.completion_tokens ?? 0) +\n    (metadataResponseUsage?.completion_tokens ?? 0);\n\n  const totalInferenceTimeMs =\n    extractEndTime - extractStartTime + (metadataEndTime - metadataStartTime);\n  const totalReasoningTokens =\n    (extractUsage?.reasoning_tokens ?? 0) +\n    (metadataResponseUsage?.reasoning_tokens ?? 0);\n  const totalCachedInputTokens =\n    (extractUsage?.cached_input_tokens ?? 0) +\n    (metadataResponseUsage?.cached_input_tokens ?? 0);\n\n  return {\n    ...extractedData,\n    metadata: {\n      completed: metadataResponseCompleted,\n      progress: metadataResponseProgress,\n    },\n    prompt_tokens: totalPromptTokens,\n    completion_tokens: totalCompletionTokens,\n    reasoning_tokens: totalReasoningTokens,\n    cached_input_tokens: totalCachedInputTokens,\n    inference_time_ms: totalInferenceTimeMs,\n  };\n}\n\nexport async function observe({\n  instruction,\n  domElements,\n  llmClient,\n  userProvidedInstructions,\n  logger,\n  logInferenceToFile = false,\n  supportedActions,\n  variables,\n}: {\n  instruction: string;\n  domElements: string;\n  llmClient: LLMClient;\n  userProvidedInstructions?: string;\n  logger: (message: LogLine) => void;\n  logInferenceToFile?: boolean;\n  supportedActions?: string[];\n  variables?: Variables;\n}) {\n  const observeSchema = z.object({\n    elements: z\n      .array(\n        z.object({\n          elementId: z\n            .string()\n            .regex(/^\\d+-\\d+$/)\n            .describe(\n              \"the exact ID string associated with the element. Never include surrounding square brackets. This field must follow the format of 'number-number'. For example, if the accessibility tree shows [0-18372], return '0-18372', not '18372'.\",\n            ),\n          description: z\n            .string()\n            .describe(\n              \"a description of the accessible element and its purpose\",\n            ),\n          method: z\n            .enum(\n              // Use Object.values() for Zod v3 compatibility - z.enum() in v3 doesn't accept TypeScript enums directly\n              Object.values(SupportedUnderstudyAction) as unknown as readonly [\n                string,\n                ...string[],\n              ],\n            )\n            .describe(\n              `the candidate method/action to interact with the element. Select one of the available Understudy interaction methods.`,\n            ),\n          arguments: z.array(\n            z\n              .string()\n              .describe(\n                \"the arguments to pass to the method. For example, for a click, the arguments are empty, but for a fill, the arguments are the value to fill in.\",\n              ),\n          ),\n        }),\n      )\n      .describe(\"an array of accessible elements that match the instruction\"),\n  });\n\n  type ObserveResponse = z.infer<typeof observeSchema>;\n\n  const messages: ChatMessage[] = [\n    buildObserveSystemPrompt(\n      userProvidedInstructions,\n      supportedActions,\n      variables,\n    ),\n    buildObserveUserMessage(instruction, domElements),\n  ];\n\n  let callTimestamp = \"\";\n  let callFile = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      `observe_summary`,\n      `observe_call`,\n      {\n        modelCall: \"observe\",\n        messages,\n      },\n    );\n    callFile = fileName;\n    callTimestamp = timestamp;\n  }\n\n  const start = Date.now();\n  const rawResponse = await llmClient.createChatCompletion<ObserveResponse>({\n    options: {\n      messages,\n      response_model: {\n        schema: observeSchema,\n        name: \"Observation\",\n      },\n      top_p: 1,\n      frequency_penalty: 0,\n      presence_penalty: 0,\n    },\n    logger,\n  });\n  const end = Date.now();\n  const usageTimeMs = end - start;\n\n  const { data: observeData, usage: observeUsage } = rawResponse;\n  const promptTokens = observeUsage?.prompt_tokens ?? 0;\n  const completionTokens = observeUsage?.completion_tokens ?? 0;\n  const reasoningTokens = observeUsage?.reasoning_tokens ?? 0;\n  const cachedInputTokens = observeUsage?.cached_input_tokens ?? 0;\n\n  let responseFile: string;\n  if (logInferenceToFile) {\n    const { fileName: responseFileName } = writeTimestampedTxtFile(\n      `observe_summary`,\n      `observe_response`,\n      {\n        modelResponse: \"observe\",\n        rawResponse: observeData,\n      },\n    );\n    responseFile = responseFileName;\n\n    appendSummary(\"observe\", {\n      [`observe_inference_type`]: \"observe\",\n      timestamp: callTimestamp,\n      LLM_input_file: callFile,\n      LLM_output_file: responseFile,\n      prompt_tokens: promptTokens,\n      completion_tokens: completionTokens,\n      reasoning_tokens: reasoningTokens,\n      cached_input_tokens: cachedInputTokens,\n      inference_time_ms: usageTimeMs,\n    });\n  }\n\n  const parsedElements =\n    observeData.elements?.map((el) => {\n      const base = {\n        elementId: el.elementId,\n        description: String(el.description),\n        method: String(el.method),\n        arguments: el.arguments,\n      };\n      return base;\n    }) ?? [];\n\n  return {\n    elements: parsedElements,\n    prompt_tokens: promptTokens,\n    completion_tokens: completionTokens,\n    reasoning_tokens: reasoningTokens,\n    cached_input_tokens: cachedInputTokens,\n    inference_time_ms: usageTimeMs,\n  };\n}\n\nexport async function act({\n  instruction,\n  domElements,\n  llmClient,\n  userProvidedInstructions,\n  logger,\n  logInferenceToFile = false,\n}: {\n  instruction: string;\n  domElements: string;\n  llmClient: LLMClient;\n  userProvidedInstructions?: string;\n  logger: (message: LogLine) => void;\n  logInferenceToFile?: boolean;\n}) {\n  const actSchema = z.object({\n    action: z\n      .object({\n        elementId: z\n          .string()\n          .regex(/^\\d+-\\d+$/)\n          .describe(\n            \"the ID string associated with the element. Never include surrounding square brackets. This field must follow the format of 'number-number'. for example, '0-76' or '16-21'\",\n          ),\n        description: z\n          .string()\n          .describe(\"a description of the accessible element and its purpose\"),\n        method: z\n          .enum(\n            // Use Object.values() for Zod v3 compatibility - z.enum() in v3 doesn't accept TypeScript enums directly\n            Object.values(SupportedUnderstudyAction) as unknown as readonly [\n              string,\n              ...string[],\n            ],\n          )\n          .describe(\n            \"the candidate method/action to interact with the element. Select one of the available Understudy interaction methods.\",\n          ),\n        arguments: z.array(\n          z\n            .string()\n            .describe(\n              \"the arguments to pass to the method. For example, for a click, the arguments are empty, but for a fill, the arguments are the value to fill in.\",\n            ),\n        ),\n      })\n      .nullable()\n      .describe(\n        \"The element to act on. Return null if no element on the page matches the instruction — do NOT fabricate or guess an element, and never emit empty strings or placeholder values.\",\n      ),\n    twoStep: z.boolean(),\n  });\n\n  type ActResponse = z.infer<typeof actSchema>;\n\n  const messages: ChatMessage[] = [\n    buildActSystemPrompt(userProvidedInstructions),\n    buildObserveUserMessage(instruction, domElements),\n  ];\n\n  let callTimestamp = \"\";\n  let callFile = \"\";\n  if (logInferenceToFile) {\n    const { fileName, timestamp } = writeTimestampedTxtFile(\n      `act_summary`,\n      `act_call`,\n      {\n        modelCall: \"act\",\n        messages,\n      },\n    );\n    callFile = fileName;\n    callTimestamp = timestamp;\n  }\n\n  const start = Date.now();\n  const rawResponse = await llmClient.createChatCompletion<ActResponse>({\n    options: {\n      messages,\n      response_model: {\n        schema: actSchema,\n        name: \"act\",\n      },\n      top_p: 1,\n      frequency_penalty: 0,\n      presence_penalty: 0,\n    },\n    logger,\n  });\n  const end = Date.now();\n  const usageTimeMs = end - start;\n\n  const { data: actData, usage: actUsage } = rawResponse;\n  const promptTokens = actUsage?.prompt_tokens ?? 0;\n  const completionTokens = actUsage?.completion_tokens ?? 0;\n  const reasoningTokens = actUsage?.reasoning_tokens ?? 0;\n  const cachedInputTokens = actUsage?.cached_input_tokens ?? 0;\n\n  let responseFile: string;\n  if (logInferenceToFile) {\n    const { fileName: responseFileName } = writeTimestampedTxtFile(\n      `act_summary`,\n      `act_response`,\n      {\n        modelResponse: \"act\",\n        rawResponse: actData,\n      },\n    );\n    responseFile = responseFileName;\n\n    appendSummary(\"act\", {\n      [`act_inference_type`]: \"act\",\n      timestamp: callTimestamp,\n      LLM_input_file: callFile,\n      LLM_output_file: responseFile,\n      prompt_tokens: promptTokens,\n      completion_tokens: completionTokens,\n      reasoning_tokens: reasoningTokens,\n      cached_input_tokens: cachedInputTokens,\n      inference_time_ms: usageTimeMs,\n    });\n  }\n\n  const parsedElement = actData.action\n    ? {\n        elementId: actData.action.elementId,\n        description: String(actData.action.description),\n        method: String(actData.action.method),\n        arguments: actData.action.arguments,\n      }\n    : undefined;\n\n  return {\n    element: parsedElement,\n    prompt_tokens: promptTokens,\n    completion_tokens: completionTokens,\n    reasoning_tokens: reasoningTokens,\n    cached_input_tokens: cachedInputTokens,\n    inference_time_ms: usageTimeMs,\n    twoStep: actData.twoStep,\n  };\n}\n"]}

package/dist/cjs/lib/prompt.d.ts

@@ -1,8 +1,8 @@
 import { ChatMessage } from "./v3/llm/LLMClient.js";
 import type { Variables } from "./v3/types/public/agent.js";
 export declare function buildUserInstructionsString(userProvidedInstructions?: string): string;
-export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, userProvidedInstructions?: string): ChatMessage;
-export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean): ChatMessage;
+export declare function buildExtractSystemPrompt(isUsingPrintExtractedDataTool?: boolean, userProvidedInstructions?: string, includeScreenshot?: boolean): ChatMessage;
+export declare function buildExtractUserPrompt(instruction: string, domElements: string, isUsingPrintExtractedDataTool?: boolean, screenshotDataUrl?: string): ChatMessage;
 export declare function buildMetadataSystemPrompt(): ChatMessage;
 export declare function buildMetadataPrompt(instruction: string, extractionResponse: object): ChatMessage;
 export declare function buildObserveSystemPrompt(userProvidedInstructions?: string, supportedActions?: string[], variables?: Variables): ChatMessage;

package/dist/cjs/lib/prompt.js

@@ -26,7 +26,7 @@ User Instructions:
 ${userProvidedInstructions}`;
 }
 // extract
-function buildExtractSystemPrompt(isUsingPrintExtractedDataTool = false, userProvidedInstructions) {
+function buildExtractSystemPrompt(isUsingPrintExtractedDataTool = false, userProvidedInstructions, includeScreenshot = false) {
     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.
@@ -34,7 +34,9 @@ function buildExtractSystemPrompt(isUsingPrintExtractedDataTool = false, userPro
   You will be given:
 1. An instruction
 2. `;
-    const contentDetail = `A list of DOM elements to extract from.`;
+    const contentDetail = includeScreenshot
+        ? `A list of DOM elements to extract from and a screenshot of the current viewport to extract from. Use them together to extract content from the page.`
+        : `A list of DOM elements to extract from.`;
     const instructions = `
 Print the exact text from the DOM elements with all symbols, characters, and endlines as is.
 Print null or an empty string if no new information is found.
@@ -54,14 +56,27 @@ ONLY print the content using the print_extracted_data tool provided.
         content,
     };
 }
-function buildExtractUserPrompt(instruction, domElements, isUsingPrintExtractedDataTool = false) {
-    let content = `Instruction: ${instruction}
+function buildExtractUserPrompt(instruction, domElements, isUsingPrintExtractedDataTool = false, screenshotDataUrl) {
+    let content = screenshotDataUrl
+        ? `Instruction: ${instruction}
+DOM: ${domElements}
+Use the screenshot of the current viewport together with the accessibility tree to extract content from the page.`
+        : `Instruction: ${instruction}
 DOM: ${domElements}`;
     if (isUsingPrintExtractedDataTool) {
         content += `
 ONLY print the content using the print_extracted_data tool provided.
 ONLY print the content using the print_extracted_data tool provided.`;
     }
+    if (screenshotDataUrl) {
+        return {
+            role: "user",
+            content: [
+                { type: "text", text: content },
+                { type: "image_url", image_url: { url: screenshotDataUrl } },
+            ],
+        };
+    }
     return {
         role: "user",
         content,

package/dist/cjs/lib/prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../lib/prompt.ts"],"names":[],"mappings":"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","sourcesContent":["import { ChatMessage } from \"./v3/llm/LLMClient.js\";\nimport type { Variables } from \"./v3/types/public/agent.js\";\nimport { getVariablePromptEntries } from \"./v3/agent/utils/variables.js\";\n\nexport function buildUserInstructionsString(\n  userProvidedInstructions?: string,\n): string {\n  if (!userProvidedInstructions) {\n    return \"\";\n  }\n\n  return `\\n\\n# Custom Instructions Provided by the User\n    \nPlease keep the user's instructions in mind when performing actions. If the user's instructions are not relevant to the current task, ignore them.\n\nUser Instructions:\n${userProvidedInstructions}`;\n}\n\n// extract\nexport function buildExtractSystemPrompt(\n  isUsingPrintExtractedDataTool: boolean = false,\n  userProvidedInstructions?: string,\n): ChatMessage {\n  const baseContent = `You are extracting content on behalf of a user.\n  If a user asks you to extract a 'list' of information, or 'all' information, \n  YOU MUST EXTRACT ALL OF THE INFORMATION THAT THE USER REQUESTS.\n   \n  You will be given:\n1. An instruction\n2. `;\n\n  const contentDetail = `A list of DOM elements to extract from.`;\n\n  const instructions = `\nPrint the exact text from the DOM elements with all symbols, characters, and endlines as is.\nPrint null or an empty string if no new information is found.\n  `.trim();\n\n  const toolInstructions = isUsingPrintExtractedDataTool\n    ? `\nONLY print the content using the print_extracted_data tool provided.\nONLY print the content using the print_extracted_data tool provided.\n  `.trim()\n    : \"\";\n\n  const additionalInstructions =\n    \"If a user is attempting to extract links or URLs, you MUST respond with ONLY the IDs of the link elements. \\n\" +\n    \"Do not attempt to extract links directly from the text unless absolutely necessary. \";\n\n  const userInstructions = buildUserInstructionsString(\n    userProvidedInstructions,\n  );\n\n  const content =\n    `${baseContent}${contentDetail}\\n\\n${instructions}\\n${toolInstructions}${\n      additionalInstructions ? `\\n\\n${additionalInstructions}` : \"\"\n    }${userInstructions ? `\\n\\n${userInstructions}` : \"\"}`.replace(/\\s+/g, \" \");\n\n  return {\n    role: \"system\",\n    content,\n  };\n}\n\nexport function buildExtractUserPrompt(\n  instruction: string,\n  domElements: string,\n  isUsingPrintExtractedDataTool: boolean = false,\n): ChatMessage {\n  let content = `Instruction: ${instruction}\nDOM: ${domElements}`;\n\n  if (isUsingPrintExtractedDataTool) {\n    content += `\nONLY print the content using the print_extracted_data tool provided.\nONLY print the content using the print_extracted_data tool provided.`;\n  }\n\n  return {\n    role: \"user\",\n    content,\n  };\n}\n\nconst metadataSystemPrompt = `You are an AI assistant tasked with evaluating the progress and completion status of an extraction task.\nAnalyze the extraction response and determine if the task is completed or if more information is needed.\nStrictly abide by the following criteria:\n1. Once the instruction has been satisfied by the current extraction response, ALWAYS set completion status to true and stop processing, regardless of remaining chunks.\n2. Only set completion status to false if BOTH of these conditions are true:\n   - The instruction has not been satisfied yet\n   - There are still chunks left to process (chunksTotal > chunksSeen)`;\n\nexport function buildMetadataSystemPrompt(): ChatMessage {\n  return {\n    role: \"system\",\n    content: metadataSystemPrompt,\n  };\n}\n\nexport function buildMetadataPrompt(\n  instruction: string,\n  extractionResponse: object,\n): ChatMessage {\n  return {\n    role: \"user\",\n    content: `Instruction: ${instruction}\nExtracted content: ${JSON.stringify(extractionResponse, null, 2)}`,\n  };\n}\n\n// observe\nexport function buildObserveSystemPrompt(\n  userProvidedInstructions?: string,\n  supportedActions?: string[],\n  variables?: Variables,\n): ChatMessage {\n  const actionsString = supportedActions?.length\n    ? `\\n\\nSupported actions: ${supportedActions.join(\", \")}`\n    : \"\";\n  const variableEntries = getVariablePromptEntries(variables);\n  const variablesString = variableEntries.length\n    ? `\\n\\nAvailable variables: ${variableEntries\n        .map(({ name, description }) => {\n          return description ? `%${name}% (${description})` : `%${name}%`;\n        })\n        .join(\n          \", \",\n        )}. When an action needs a dynamic or sensitive value, return the matching %variableName% placeholder in the action arguments instead of a literal value`\n    : \"\";\n\n  const observeSystemPrompt = `\nYou are helping the user automate the browser by finding elements based on what the user wants to observe in the page.\n\nYou will be given:\n1. a instruction of elements to observe\n2. a hierarchical accessibility tree showing the semantic structure of the page. The tree is a hybrid of the DOM and the accessibility tree.\n\nReturn an array of elements that match the instruction if they exist, otherwise return an empty array.\nWhen returning elements, include the appropriate method from the supported actions list.${actionsString}${variablesString}. When choosing non-left click actions, provide right or middle as the argument.\n\nEach element in the accessibility tree has an ID in square brackets, like [0-18372]. The ID has two parts: frame ordinal and backend node ID. Always copy the complete ID exactly as shown inside the brackets into elementId, including the frame ordinal and hyphen. For example, if the tree shows [0-18372], return elementId \"0-18372\"; never return only \"18372\".`;\n  const content = observeSystemPrompt.replace(/\\s+/g, \" \");\n\n  return {\n    role: \"system\",\n    content: [content, buildUserInstructionsString(userProvidedInstructions)]\n      .filter(Boolean)\n      .join(\"\\n\\n\"),\n  };\n}\n\nexport function buildObserveUserMessage(\n  instruction: string,\n  domElements: string,\n): ChatMessage {\n  return {\n    role: \"user\",\n    content: `instruction: ${instruction}\nAccessibility Tree: \\n${domElements}\\n`,\n  };\n}\n\nexport function buildActSystemPrompt(\n  userProvidedInstructions?: string,\n): ChatMessage {\n  const actSystemPrompt = `\nYou are helping the user automate the browser by finding elements based on what action the user wants to take on the page\n\nYou will be given:\n1. a user defined instruction about what action to take\n2. a hierarchical accessibility tree showing the semantic structure of the page. The tree is a hybrid of the DOM and the accessibility tree.\n\nReturn the element that matches the instruction if it exists. If no element on the page matches the instruction, set \\`action\\` to null. Do not fabricate or guess an element — empty strings or placeholder values for elementId/description/method are not acceptable.`;\n  const content = actSystemPrompt.replace(/\\s+/g, \" \");\n\n  return {\n    role: \"system\",\n    content: [content, buildUserInstructionsString(userProvidedInstructions)]\n      .filter(Boolean)\n      .join(\"\\n\\n\"),\n  };\n}\n\nfunction buildActVariablesPrompt(variables?: Variables): string {\n  if (!variables || Object.keys(variables).length === 0) {\n    return \"\";\n  }\n\n  const variableNames = Object.keys(variables)\n    .map((key) => `%${key}%`)\n    .join(\", \");\n\n  return ` The user has provided the following variables to be used in the action: ${variableNames} \\n\n    Note that these are the variable names/keys, and not the actual variable values. \\n\n    To use the variables in the action, you must respond with the variable name inside the 'arguments' array. The variable name must be wrapped in percentage signs (eg, %variableNameHere%) so that it can be replaced with the actual variable value before the action is taken. \\n`;\n}\n\nexport function buildActPrompt(\n  action: string,\n  supportedActions: string[],\n  variables?: Variables,\n): string {\n  // Base instruction\n  let instruction = `Find the most relevant element to perform an action on given the following action: ${action}.  \n  IF AND ONLY IF the action EXPLICITLY includes the word 'dropdown' and implies choosing/selecting an option from a dropdown, ignore the 'General Instructions' section, and follow the 'Dropdown Specific Instructions' section carefully.\n  \n  General Instructions: \n    Provide an action for this element such as ${supportedActions.join(\", \")}. Remember that to users, buttons and links look the same in most cases.\n    When choosing non-left click actions, provide right or middle as the argument\n    If the action is completely unrelated to a potential action to be taken on the page, or no matching element exists, set \\`action\\` to null. Do not fabricate or guess an element.\n    ONLY return one action. If multiple actions are relevant, return the most relevant one.\n    If the user is asking to scroll to a position on the page, e.g., 'halfway' or 0.75, etc, you must return the argument formatted as the correct percentage, e.g., '50%' or '75%', etc.\n    If the user is asking to scroll to the next chunk/previous chunk, choose the nextChunk/prevChunk method. No arguments are required here.\n    If the action implies a key press, e.g., 'press enter', 'press a', 'press space', etc., always choose the press method with the appropriate key as argument — e.g. 'a', 'Enter', 'Space'. Do not choose a click action on an on-screen keyboard. Capitalize the first character like 'Enter', 'Tab', 'Escape' only for special keys. \n  \n  Dropdown Specific Instructions:\n    For interacting with dropdowns, there are two specific cases that you need to handle. \n    \n    CASE 1: the element is a 'select' element. \n      - choose the selectOptionFromDropdown method,\n      - set the argument to the exact text of the option that should be selected,\n      - set twoStep to false.\n    CASE 2: the element is NOT a 'select' element:\n      - do not attempt to directly choose the element from the dropdown. You will need to click to expand the dropdown first. You will achieve this by following these instructions:\n        - choose the node that most closely corresponds to the given instruction EVEN if it is a 'StaticText' element, or otherwise does not appear to be interactable.  \n        - choose the 'click' method\n        - set twoStep to true.\n  `;\n\n  instruction += buildActVariablesPrompt(variables);\n\n  return instruction;\n}\n\nexport function buildStepTwoPrompt(\n  originalUserAction: string,\n  previousAction: string,\n  supportedActions: string[],\n  variables?: Variables,\n): string {\n  // Base instruction\n  let instruction = `\n  The original user action was: ${originalUserAction}.\n  You have just taken the following action which completed step 1 of 2: ${previousAction}.\n  \n  Now, you must find the most relevant element to perform an action on in order to complete step 2 of 2. \n  \n  General Instructions: \n  Provide an action for this element such as ${supportedActions.join(\", \")}. Remember that to users, buttons and links look the same in most cases.\n  If the action is completely unrelated to a potential action to be taken on the page, or no matching element exists, set \\`action\\` to null. Do not fabricate or guess an element.\n  ONLY return one action. If multiple actions are relevant, return the most relevant one.\n  If the user is asking to scroll to a position on the page, e.g., 'halfway' or 0.75, etc, you must return the argument formatted as the correct percentage, e.g., '50%' or '75%', etc.\n  If the user is asking to scroll to the next chunk/previous chunk, choose the nextChunk/prevChunk method. No arguments are required here.\n  If the action implies a key press, e.g., 'press enter', 'press a', 'press space', etc., always choose the press method with the appropriate key as argument — e.g. 'a', 'Enter', 'Space'. Do not choose a click action on an on-screen keyboard. Capitalize the first character like 'Enter', 'Tab', 'Escape' only for special keys. \n  `;\n\n  instruction += buildActVariablesPrompt(variables);\n\n  return instruction;\n}\n\nexport function buildOperatorSystemPrompt(goal: string): ChatMessage {\n  return {\n    role: \"system\",\n    content: `You are a general-purpose agent whose job is to accomplish the user's goal across multiple model calls by running actions on the page.\n\nYou will be given a goal and a list of steps that have been taken so far. Your job is to determine if either the user's goal has been completed or if there are still steps that need to be taken.\n\n# Your current goal\n${goal}\n\n# CRITICAL: You MUST use the provided tools to take actions. Do not just describe what you want to do - actually call the appropriate tools.\n\n# Available tools and when to use them:\n- \\`act\\`: Use this to interact with the page (click, type, navigate, etc.)\n- \\`extract\\`: Use this to get information from the page\n- \\`goto\\`: Use this to navigate to a specific URL\n- \\`wait\\`: Use this to wait for a period of time\n- \\`navback\\`: Use this to go back to the previous page\n- \\`refresh\\`: Use this to refresh the current page\n- \\`close\\`: Use this ONLY when the task is complete or cannot be achieved\n- External tools: Use any additional tools (like search tools) as needed for your goal\n\n# Important guidelines\n1. ALWAYS use tools - never just provide text responses about what you plan to do\n2. Break down complex actions into individual atomic steps\n3. For \\`act\\` commands, use only one action at a time, such as:\n   - Single click on a specific element\n   - Type into a single input field\n   - Select a single option\n4. Avoid combining multiple actions in one instruction\n5. If multiple actions are needed, they should be separate steps\n6. Only use \\`close\\` when the task is genuinely complete or impossible to achieve`,\n  };\n}\n\nexport function buildCuaDefaultSystemPrompt(): string {\n  return `You are a helpful assistant that can use a web browser.\\nDo not ask follow up questions, the user will trust your judgement. Today's date is ${new Date().toISOString().split(\"T\")[0]}.`;\n}\n\nexport function buildGoogleCUASystemPrompt(): ChatMessage {\n  return {\n    role: \"system\",\n    content: `You are a general-purpose browser agent whose job is to accomplish the user's goal.\nToday's date is ${new Date().toISOString().split(\"T\")[0]}.\nYou have access to a search tool; however, in most cases you should operate within the page/url the user has provided. ONLY use the search tool if you're stuck or the task is impossible to complete within the current page.\nYou will be given a goal and a list of steps that have been taken so far. Avoid requesting the user for input as much as possible. Good luck!\n`,\n  };\n}\n"]}
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../lib/prompt.ts"],"names":[],"mappings":"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","sourcesContent":["import { ChatMessage } from \"./v3/llm/LLMClient.js\";\nimport type { Variables } from \"./v3/types/public/agent.js\";\nimport { getVariablePromptEntries } from \"./v3/agent/utils/variables.js\";\n\nexport function buildUserInstructionsString(\n  userProvidedInstructions?: string,\n): string {\n  if (!userProvidedInstructions) {\n    return \"\";\n  }\n\n  return `\\n\\n# Custom Instructions Provided by the User\n    \nPlease keep the user's instructions in mind when performing actions. If the user's instructions are not relevant to the current task, ignore them.\n\nUser Instructions:\n${userProvidedInstructions}`;\n}\n\n// extract\nexport function buildExtractSystemPrompt(\n  isUsingPrintExtractedDataTool: boolean = false,\n  userProvidedInstructions?: string,\n  includeScreenshot: boolean = false,\n): ChatMessage {\n  const baseContent = `You are extracting content on behalf of a user.\n  If a user asks you to extract a 'list' of information, or 'all' information, \n  YOU MUST EXTRACT ALL OF THE INFORMATION THAT THE USER REQUESTS.\n   \n  You will be given:\n1. An instruction\n2. `;\n\n  const contentDetail = includeScreenshot\n    ? `A list of DOM elements to extract from and a screenshot of the current viewport to extract from. Use them together to extract content from the page.`\n    : `A list of DOM elements to extract from.`;\n\n  const instructions = `\nPrint the exact text from the DOM elements with all symbols, characters, and endlines as is.\nPrint null or an empty string if no new information is found.\n  `.trim();\n\n  const toolInstructions = isUsingPrintExtractedDataTool\n    ? `\nONLY print the content using the print_extracted_data tool provided.\nONLY print the content using the print_extracted_data tool provided.\n  `.trim()\n    : \"\";\n\n  const additionalInstructions =\n    \"If a user is attempting to extract links or URLs, you MUST respond with ONLY the IDs of the link elements. \\n\" +\n    \"Do not attempt to extract links directly from the text unless absolutely necessary. \";\n\n  const userInstructions = buildUserInstructionsString(\n    userProvidedInstructions,\n  );\n\n  const content =\n    `${baseContent}${contentDetail}\\n\\n${instructions}\\n${toolInstructions}${\n      additionalInstructions ? `\\n\\n${additionalInstructions}` : \"\"\n    }${userInstructions ? `\\n\\n${userInstructions}` : \"\"}`.replace(/\\s+/g, \" \");\n\n  return {\n    role: \"system\",\n    content,\n  };\n}\n\nexport function buildExtractUserPrompt(\n  instruction: string,\n  domElements: string,\n  isUsingPrintExtractedDataTool: boolean = false,\n  screenshotDataUrl?: string,\n): ChatMessage {\n  let content = screenshotDataUrl\n    ? `Instruction: ${instruction}\nDOM: ${domElements}\nUse the screenshot of the current viewport together with the accessibility tree to extract content from the page.`\n    : `Instruction: ${instruction}\nDOM: ${domElements}`;\n\n  if (isUsingPrintExtractedDataTool) {\n    content += `\nONLY print the content using the print_extracted_data tool provided.\nONLY print the content using the print_extracted_data tool provided.`;\n  }\n\n  if (screenshotDataUrl) {\n    return {\n      role: \"user\",\n      content: [\n        { type: \"text\", text: content },\n        { type: \"image_url\", image_url: { url: screenshotDataUrl } },\n      ],\n    };\n  }\n\n  return {\n    role: \"user\",\n    content,\n  };\n}\n\nconst metadataSystemPrompt = `You are an AI assistant tasked with evaluating the progress and completion status of an extraction task.\nAnalyze the extraction response and determine if the task is completed or if more information is needed.\nStrictly abide by the following criteria:\n1. Once the instruction has been satisfied by the current extraction response, ALWAYS set completion status to true and stop processing, regardless of remaining chunks.\n2. Only set completion status to false if BOTH of these conditions are true:\n   - The instruction has not been satisfied yet\n   - There are still chunks left to process (chunksTotal > chunksSeen)`;\n\nexport function buildMetadataSystemPrompt(): ChatMessage {\n  return {\n    role: \"system\",\n    content: metadataSystemPrompt,\n  };\n}\n\nexport function buildMetadataPrompt(\n  instruction: string,\n  extractionResponse: object,\n): ChatMessage {\n  return {\n    role: \"user\",\n    content: `Instruction: ${instruction}\nExtracted content: ${JSON.stringify(extractionResponse, null, 2)}`,\n  };\n}\n\n// observe\nexport function buildObserveSystemPrompt(\n  userProvidedInstructions?: string,\n  supportedActions?: string[],\n  variables?: Variables,\n): ChatMessage {\n  const actionsString = supportedActions?.length\n    ? `\\n\\nSupported actions: ${supportedActions.join(\", \")}`\n    : \"\";\n  const variableEntries = getVariablePromptEntries(variables);\n  const variablesString = variableEntries.length\n    ? `\\n\\nAvailable variables: ${variableEntries\n        .map(({ name, description }) => {\n          return description ? `%${name}% (${description})` : `%${name}%`;\n        })\n        .join(\n          \", \",\n        )}. When an action needs a dynamic or sensitive value, return the matching %variableName% placeholder in the action arguments instead of a literal value`\n    : \"\";\n\n  const observeSystemPrompt = `\nYou are helping the user automate the browser by finding elements based on what the user wants to observe in the page.\n\nYou will be given:\n1. a instruction of elements to observe\n2. a hierarchical accessibility tree showing the semantic structure of the page. The tree is a hybrid of the DOM and the accessibility tree.\n\nReturn an array of elements that match the instruction if they exist, otherwise return an empty array.\nWhen returning elements, include the appropriate method from the supported actions list.${actionsString}${variablesString}. When choosing non-left click actions, provide right or middle as the argument.\n\nEach element in the accessibility tree has an ID in square brackets, like [0-18372]. The ID has two parts: frame ordinal and backend node ID. Always copy the complete ID exactly as shown inside the brackets into elementId, including the frame ordinal and hyphen. For example, if the tree shows [0-18372], return elementId \"0-18372\"; never return only \"18372\".`;\n  const content = observeSystemPrompt.replace(/\\s+/g, \" \");\n\n  return {\n    role: \"system\",\n    content: [content, buildUserInstructionsString(userProvidedInstructions)]\n      .filter(Boolean)\n      .join(\"\\n\\n\"),\n  };\n}\n\nexport function buildObserveUserMessage(\n  instruction: string,\n  domElements: string,\n): ChatMessage {\n  return {\n    role: \"user\",\n    content: `instruction: ${instruction}\nAccessibility Tree: \\n${domElements}\\n`,\n  };\n}\n\nexport function buildActSystemPrompt(\n  userProvidedInstructions?: string,\n): ChatMessage {\n  const actSystemPrompt = `\nYou are helping the user automate the browser by finding elements based on what action the user wants to take on the page\n\nYou will be given:\n1. a user defined instruction about what action to take\n2. a hierarchical accessibility tree showing the semantic structure of the page. The tree is a hybrid of the DOM and the accessibility tree.\n\nReturn the element that matches the instruction if it exists. If no element on the page matches the instruction, set \\`action\\` to null. Do not fabricate or guess an element — empty strings or placeholder values for elementId/description/method are not acceptable.`;\n  const content = actSystemPrompt.replace(/\\s+/g, \" \");\n\n  return {\n    role: \"system\",\n    content: [content, buildUserInstructionsString(userProvidedInstructions)]\n      .filter(Boolean)\n      .join(\"\\n\\n\"),\n  };\n}\n\nfunction buildActVariablesPrompt(variables?: Variables): string {\n  if (!variables || Object.keys(variables).length === 0) {\n    return \"\";\n  }\n\n  const variableNames = Object.keys(variables)\n    .map((key) => `%${key}%`)\n    .join(\", \");\n\n  return ` The user has provided the following variables to be used in the action: ${variableNames} \\n\n    Note that these are the variable names/keys, and not the actual variable values. \\n\n    To use the variables in the action, you must respond with the variable name inside the 'arguments' array. The variable name must be wrapped in percentage signs (eg, %variableNameHere%) so that it can be replaced with the actual variable value before the action is taken. \\n`;\n}\n\nexport function buildActPrompt(\n  action: string,\n  supportedActions: string[],\n  variables?: Variables,\n): string {\n  // Base instruction\n  let instruction = `Find the most relevant element to perform an action on given the following action: ${action}.  \n  IF AND ONLY IF the action EXPLICITLY includes the word 'dropdown' and implies choosing/selecting an option from a dropdown, ignore the 'General Instructions' section, and follow the 'Dropdown Specific Instructions' section carefully.\n  \n  General Instructions: \n    Provide an action for this element such as ${supportedActions.join(\", \")}. Remember that to users, buttons and links look the same in most cases.\n    When choosing non-left click actions, provide right or middle as the argument\n    If the action is completely unrelated to a potential action to be taken on the page, or no matching element exists, set \\`action\\` to null. Do not fabricate or guess an element.\n    ONLY return one action. If multiple actions are relevant, return the most relevant one.\n    If the user is asking to scroll to a position on the page, e.g., 'halfway' or 0.75, etc, you must return the argument formatted as the correct percentage, e.g., '50%' or '75%', etc.\n    If the user is asking to scroll to the next chunk/previous chunk, choose the nextChunk/prevChunk method. No arguments are required here.\n    If the action implies a key press, e.g., 'press enter', 'press a', 'press space', etc., always choose the press method with the appropriate key as argument — e.g. 'a', 'Enter', 'Space'. Do not choose a click action on an on-screen keyboard. Capitalize the first character like 'Enter', 'Tab', 'Escape' only for special keys. \n  \n  Dropdown Specific Instructions:\n    For interacting with dropdowns, there are two specific cases that you need to handle. \n    \n    CASE 1: the element is a 'select' element. \n      - choose the selectOptionFromDropdown method,\n      - set the argument to the exact text of the option that should be selected,\n      - set twoStep to false.\n    CASE 2: the element is NOT a 'select' element:\n      - do not attempt to directly choose the element from the dropdown. You will need to click to expand the dropdown first. You will achieve this by following these instructions:\n        - choose the node that most closely corresponds to the given instruction EVEN if it is a 'StaticText' element, or otherwise does not appear to be interactable.  \n        - choose the 'click' method\n        - set twoStep to true.\n  `;\n\n  instruction += buildActVariablesPrompt(variables);\n\n  return instruction;\n}\n\nexport function buildStepTwoPrompt(\n  originalUserAction: string,\n  previousAction: string,\n  supportedActions: string[],\n  variables?: Variables,\n): string {\n  // Base instruction\n  let instruction = `\n  The original user action was: ${originalUserAction}.\n  You have just taken the following action which completed step 1 of 2: ${previousAction}.\n  \n  Now, you must find the most relevant element to perform an action on in order to complete step 2 of 2. \n  \n  General Instructions: \n  Provide an action for this element such as ${supportedActions.join(\", \")}. Remember that to users, buttons and links look the same in most cases.\n  If the action is completely unrelated to a potential action to be taken on the page, or no matching element exists, set \\`action\\` to null. Do not fabricate or guess an element.\n  ONLY return one action. If multiple actions are relevant, return the most relevant one.\n  If the user is asking to scroll to a position on the page, e.g., 'halfway' or 0.75, etc, you must return the argument formatted as the correct percentage, e.g., '50%' or '75%', etc.\n  If the user is asking to scroll to the next chunk/previous chunk, choose the nextChunk/prevChunk method. No arguments are required here.\n  If the action implies a key press, e.g., 'press enter', 'press a', 'press space', etc., always choose the press method with the appropriate key as argument — e.g. 'a', 'Enter', 'Space'. Do not choose a click action on an on-screen keyboard. Capitalize the first character like 'Enter', 'Tab', 'Escape' only for special keys. \n  `;\n\n  instruction += buildActVariablesPrompt(variables);\n\n  return instruction;\n}\n\nexport function buildOperatorSystemPrompt(goal: string): ChatMessage {\n  return {\n    role: \"system\",\n    content: `You are a general-purpose agent whose job is to accomplish the user's goal across multiple model calls by running actions on the page.\n\nYou will be given a goal and a list of steps that have been taken so far. Your job is to determine if either the user's goal has been completed or if there are still steps that need to be taken.\n\n# Your current goal\n${goal}\n\n# CRITICAL: You MUST use the provided tools to take actions. Do not just describe what you want to do - actually call the appropriate tools.\n\n# Available tools and when to use them:\n- \\`act\\`: Use this to interact with the page (click, type, navigate, etc.)\n- \\`extract\\`: Use this to get information from the page\n- \\`goto\\`: Use this to navigate to a specific URL\n- \\`wait\\`: Use this to wait for a period of time\n- \\`navback\\`: Use this to go back to the previous page\n- \\`refresh\\`: Use this to refresh the current page\n- \\`close\\`: Use this ONLY when the task is complete or cannot be achieved\n- External tools: Use any additional tools (like search tools) as needed for your goal\n\n# Important guidelines\n1. ALWAYS use tools - never just provide text responses about what you plan to do\n2. Break down complex actions into individual atomic steps\n3. For \\`act\\` commands, use only one action at a time, such as:\n   - Single click on a specific element\n   - Type into a single input field\n   - Select a single option\n4. Avoid combining multiple actions in one instruction\n5. If multiple actions are needed, they should be separate steps\n6. Only use \\`close\\` when the task is genuinely complete or impossible to achieve`,\n  };\n}\n\nexport function buildCuaDefaultSystemPrompt(): string {\n  return `You are a helpful assistant that can use a web browser.\\nDo not ask follow up questions, the user will trust your judgement. Today's date is ${new Date().toISOString().split(\"T\")[0]}.`;\n}\n\nexport function buildGoogleCUASystemPrompt(): ChatMessage {\n  return {\n    role: \"system\",\n    content: `You are a general-purpose browser agent whose job is to accomplish the user's goal.\nToday's date is ${new Date().toISOString().split(\"T\")[0]}.\nYou have access to a search tool; however, in most cases you should operate within the page/url the user has provided. ONLY use the search tool if you're stuck or the task is impossible to complete within the current page.\nYou will be given a goal and a list of steps that have been taken so far. Avoid requesting the user for input as much as possible. Good luck!\n`,\n  };\n}\n"]}

package/dist/cjs/lib/v3/handlers/extractHandler.js

@@ -45,7 +45,7 @@ class ExtractHandler {
         this.onMetrics = onMetrics;
     }
     async extract(params) {
-        const { instruction, schema, page, selector, ignoreSelectors, timeout, model, } = params;
+        const { instruction, schema, page, selector, ignoreSelectors, timeout, model, screenshot, } = params;
         const llmClient = this.resolveLlmClient(model);
         const ensureTimeRemaining = (0, timeoutGuard_js_1.createTimeoutGuard)(timeout, (ms) => new sdkErrors_js_1.ExtractTimeoutError(ms));
         // No-args → page text (parity with v2)
@@ -66,6 +66,9 @@ class ExtractHandler {
         if (!instruction && schema) {
             throw new sdkErrors_js_1.StagehandInvalidArgumentError("extract() requires an instruction when a schema is provided.");
         }
+        if (screenshot && llmClient.type !== "aisdk") {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("extract({ screenshot: true }) is only supported with AI SDK clients.");
+        }
         const focusSelector = selector?.replace(/^xpath=/, "") ?? "";
         // Build the hybrid snapshot (includes combinedTree; combinedUrlMap optional)
         ensureTimeRemaining();
@@ -74,9 +77,22 @@ class ExtractHandler {
             focusSelector: focusSelector,
             ignoreSelectors,
         });
+        const screenshotBuffer = screenshot
+            ? await (async () => {
+                ensureTimeRemaining();
+                const buffer = await page.screenshot({
+                    fullPage: false,
+                    type: "png",
+                });
+                ensureTimeRemaining();
+                return buffer;
+            })()
+            : undefined;
         (0, logger_js_1.v3Logger)({
             category: "extraction",
-            message: "Starting extraction using a11y snapshot",
+            message: screenshot
+                ? "Starting extraction using a11y snapshot and viewport screenshot"
+                : "Starting extraction using a11y snapshot",
             level: 1,
             auxiliary: instruction
                 ? { instruction: { value: instruction, type: "string" } }
@@ -104,6 +120,7 @@ class ExtractHandler {
             userProvidedInstructions: this.systemPrompt,
             logger: logger_js_1.v3Logger,
             logInferenceToFile: this.logInferenceToFile,
+            screenshot: screenshotBuffer,
         });
         const { metadata: { completed }, prompt_tokens, completion_tokens, reasoning_tokens = 0, cached_input_tokens = 0, inference_time_ms, ...rest } = extractionResponse;
         let output = rest;

package/dist/cjs/lib/v3/handlers/extractHandler.js.map

@@ -1 +1 @@
-{"version":3,"file":"extractHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/extractHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/handlers/extractHandler.ts\nimport { extract as runExtract } from \"../../inference.js\";\nimport {\n  getZFactory,\n  getZodType,\n  injectUrls,\n  transformSchema,\n} from \"../../utils.js\";\nimport { v3Logger } from \"../logger.js\";\nimport { V3FunctionName } from \"../types/public/methods.js\";\nimport { captureHybridSnapshot } from \"../understudy/a11y/snapshot/index.js\";\nimport type { ZodTypeAny } from \"zod\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport { ExtractHandlerParams } from \"../types/private/handlers.js\";\nimport { EncodedId, ZodPathSegments } from \"../types/private/internal.js\";\nimport {\n  defaultExtractSchema,\n  pageTextSchema,\n} from \"../types/public/methods.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelConfiguration,\n} from \"../types/public/model.js\";\nimport {\n  StagehandInvalidArgumentError,\n  ExtractTimeoutError,\n} from \"../types/public/sdkErrors.js\";\nimport { createTimeoutGuard } from \"./handlerUtils/timeoutGuard.js\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodObject,\n  StagehandZodSchema,\n} from \"../zodCompat.js\";\n\n/**\n * Scans the provided Zod schema for any `z.string().url()` fields and\n * replaces them with `z.number()`.\n *\n * @param schema - The Zod object schema to transform.\n * @returns A tuple containing:\n *   1. The transformed schema (or the original schema if no changes were needed).\n *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,\n *      with each path segment showing where in the schema the replacement occurred.\n */\nexport function transformUrlStringsToNumericIds<T extends StagehandZodSchema>(\n  schema: T,\n): [StagehandZodSchema, ZodPathSegments[]] {\n  const [finalSchema, urlPaths] = transformSchema(schema, []);\n  return [finalSchema, urlPaths];\n}\n\ninterface ExtractionResponseBase {\n  metadata: { completed: boolean };\n  prompt_tokens: number;\n  completion_tokens: number;\n  reasoning_tokens: number;\n  cached_input_tokens?: number;\n  inference_time_ms: number;\n}\n\ntype ExtractionResponse<T extends StagehandZodObject> = ExtractionResponseBase &\n  InferStagehandSchema<T>;\n\nexport class ExtractHandler {\n  private readonly llmClient: LLMClient;\n  private readonly defaultModelName: AvailableModel;\n  private readonly defaultClientOptions: ClientOptions;\n  private readonly resolveLlmClient: (model?: ModelConfiguration) => LLMClient;\n  private readonly systemPrompt: string;\n  private readonly logInferenceToFile: boolean;\n  private readonly experimental: boolean;\n  private readonly onMetrics?: (\n    functionName: V3FunctionName,\n    promptTokens: number,\n    completionTokens: number,\n    reasoningTokens: number,\n    cachedInputTokens: number,\n    inferenceTimeMs: number,\n  ) => void;\n\n  constructor(\n    llmClient: LLMClient,\n    defaultModelName: AvailableModel,\n    defaultClientOptions: ClientOptions,\n    resolveLlmClient: (model?: ModelConfiguration) => LLMClient,\n    systemPrompt?: string,\n    logInferenceToFile?: boolean,\n    experimental?: boolean,\n    onMetrics?: (\n      functionName: V3FunctionName,\n      promptTokens: number,\n      completionTokens: number,\n      reasoningTokens: number,\n      cachedInputTokens: number,\n      inferenceTimeMs: number,\n    ) => void,\n  ) {\n    this.llmClient = llmClient;\n    this.defaultModelName = defaultModelName;\n    this.defaultClientOptions = defaultClientOptions;\n    this.resolveLlmClient = resolveLlmClient;\n    this.systemPrompt = systemPrompt ?? \"\";\n    this.logInferenceToFile = logInferenceToFile ?? false;\n    this.experimental = experimental ?? false;\n    this.onMetrics = onMetrics;\n  }\n\n  async extract<T extends StagehandZodSchema>(\n    params: ExtractHandlerParams<T>,\n  ): Promise<InferStagehandSchema<T> | { pageText: string }> {\n    const {\n      instruction,\n      schema,\n      page,\n      selector,\n      ignoreSelectors,\n      timeout,\n      model,\n    } = params;\n\n    const llmClient = this.resolveLlmClient(model);\n\n    const ensureTimeRemaining = createTimeoutGuard(\n      timeout,\n      (ms) => new ExtractTimeoutError(ms),\n    );\n\n    // No-args → page text (parity with v2)\n    const noArgs = !instruction && !schema;\n    if (noArgs) {\n      const focusSelector = selector?.replace(/^xpath=/i, \"\") ?? \"\";\n      ensureTimeRemaining();\n      const snap = await captureHybridSnapshot(page, {\n        experimental: this.experimental,\n        focusSelector: focusSelector || undefined,\n        ignoreSelectors,\n      });\n      ensureTimeRemaining();\n\n      const result = { pageText: snap.combinedTree };\n      // Validate via the same schema used in v2\n      return pageTextSchema.parse(result);\n    }\n\n    if (!instruction && schema) {\n      throw new StagehandInvalidArgumentError(\n        \"extract() requires an instruction when a schema is provided.\",\n      );\n    }\n\n    const focusSelector = selector?.replace(/^xpath=/, \"\") ?? \"\";\n\n    // Build the hybrid snapshot (includes combinedTree; combinedUrlMap optional)\n    ensureTimeRemaining();\n    const { combinedTree, combinedUrlMap } = await captureHybridSnapshot(page, {\n      experimental: this.experimental,\n      focusSelector: focusSelector,\n      ignoreSelectors,\n    });\n\n    v3Logger({\n      category: \"extraction\",\n      message: \"Starting extraction using a11y snapshot\",\n      level: 1,\n      auxiliary: instruction\n        ? { instruction: { value: instruction, type: \"string\" } }\n        : undefined,\n    });\n\n    // Normalize schema: if instruction provided without schema, use defaultExtractSchema\n    const baseSchema: StagehandZodSchema = (schema ??\n      defaultExtractSchema) as StagehandZodSchema;\n    // Ensure we pass an object schema into inference; wrap non-object schemas\n    const isObjectSchema = getZodType(baseSchema) === \"object\";\n    const WRAP_KEY = \"value\" as const;\n    const factory = getZFactory(baseSchema);\n    const objectSchema: StagehandZodObject = isObjectSchema\n      ? (baseSchema as StagehandZodObject)\n      : (factory.object({\n          [WRAP_KEY]: baseSchema as ZodTypeAny,\n        }) as StagehandZodObject);\n\n    const [transformedSchema, urlFieldPaths] =\n      transformUrlStringsToNumericIds(objectSchema);\n\n    ensureTimeRemaining();\n    const extractionResponse: ExtractionResponse<StagehandZodObject> =\n      await runExtract<StagehandZodObject>({\n        instruction,\n        domElements: combinedTree,\n        schema: transformedSchema as StagehandZodObject,\n        llmClient,\n        userProvidedInstructions: this.systemPrompt,\n        logger: v3Logger,\n        logInferenceToFile: this.logInferenceToFile,\n      });\n\n    const {\n      metadata: { completed },\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens = 0,\n      cached_input_tokens = 0,\n      inference_time_ms,\n      ...rest\n    } = extractionResponse;\n    let output = rest as InferStagehandSchema<StagehandZodObject>;\n\n    // Update EXTRACT metrics from the LLM calls\n    this.onMetrics?.(\n      V3FunctionName.EXTRACT,\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens,\n      cached_input_tokens,\n      inference_time_ms,\n    );\n\n    // Re-inject URLs for any url() fields we temporarily converted to number()\n    const idToUrl: Record<EncodedId, string> = (combinedUrlMap ?? {}) as Record<\n      EncodedId,\n      string\n    >;\n    for (const { segments } of urlFieldPaths) {\n      injectUrls(\n        output as Record<string, unknown>,\n        segments,\n        idToUrl as unknown as Record<string, string>,\n      );\n    }\n    // If we wrapped a non-object schema, unwrap the value\n    if (!isObjectSchema && output && typeof output === \"object\") {\n      output = (output as Record<string, unknown>)[WRAP_KEY];\n    }\n\n    const resultPreviewLength = 200;\n    const resultString = JSON.stringify(output) ?? \"undefined\";\n    const resultPreview =\n      resultString.length > resultPreviewLength\n        ? resultString.slice(0, resultPreviewLength) + \"...\"\n        : resultString;\n\n    v3Logger({\n      category: \"extraction\",\n      message: completed\n        ? \"Extraction completed successfully\"\n        : \"Extraction incomplete after processing all data\",\n      level: 1,\n      auxiliary: {\n        prompt_tokens: { value: String(prompt_tokens), type: \"string\" },\n        completion_tokens: { value: String(completion_tokens), type: \"string\" },\n        inference_time_ms: {\n          value: String(inference_time_ms),\n          type: \"string\",\n        },\n        result: { value: resultPreview, type: \"string\" },\n      },\n    });\n\n    return output as InferStagehandSchema<T>;\n  }\n}\n"]}
+{"version":3,"file":"extractHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/extractHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/handlers/extractHandler.ts\nimport { extract as runExtract } from \"../../inference.js\";\nimport {\n  getZFactory,\n  getZodType,\n  injectUrls,\n  transformSchema,\n} from \"../../utils.js\";\nimport { v3Logger } from \"../logger.js\";\nimport { V3FunctionName } from \"../types/public/methods.js\";\nimport { captureHybridSnapshot } from \"../understudy/a11y/snapshot/index.js\";\nimport type { ZodTypeAny } from \"zod\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport { ExtractHandlerParams } from \"../types/private/handlers.js\";\nimport { EncodedId, ZodPathSegments } from \"../types/private/internal.js\";\nimport {\n  defaultExtractSchema,\n  pageTextSchema,\n} from \"../types/public/methods.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelConfiguration,\n} from \"../types/public/model.js\";\nimport {\n  StagehandInvalidArgumentError,\n  ExtractTimeoutError,\n} from \"../types/public/sdkErrors.js\";\nimport { createTimeoutGuard } from \"./handlerUtils/timeoutGuard.js\";\nimport type {\n  InferStagehandSchema,\n  StagehandZodObject,\n  StagehandZodSchema,\n} from \"../zodCompat.js\";\n\n/**\n * Scans the provided Zod schema for any `z.string().url()` fields and\n * replaces them with `z.number()`.\n *\n * @param schema - The Zod object schema to transform.\n * @returns A tuple containing:\n *   1. The transformed schema (or the original schema if no changes were needed).\n *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,\n *      with each path segment showing where in the schema the replacement occurred.\n */\nexport function transformUrlStringsToNumericIds<T extends StagehandZodSchema>(\n  schema: T,\n): [StagehandZodSchema, ZodPathSegments[]] {\n  const [finalSchema, urlPaths] = transformSchema(schema, []);\n  return [finalSchema, urlPaths];\n}\n\ninterface ExtractionResponseBase {\n  metadata: { completed: boolean };\n  prompt_tokens: number;\n  completion_tokens: number;\n  reasoning_tokens: number;\n  cached_input_tokens?: number;\n  inference_time_ms: number;\n}\n\ntype ExtractionResponse<T extends StagehandZodObject> = ExtractionResponseBase &\n  InferStagehandSchema<T>;\n\nexport class ExtractHandler {\n  private readonly llmClient: LLMClient;\n  private readonly defaultModelName: AvailableModel;\n  private readonly defaultClientOptions: ClientOptions;\n  private readonly resolveLlmClient: (model?: ModelConfiguration) => LLMClient;\n  private readonly systemPrompt: string;\n  private readonly logInferenceToFile: boolean;\n  private readonly experimental: boolean;\n  private readonly onMetrics?: (\n    functionName: V3FunctionName,\n    promptTokens: number,\n    completionTokens: number,\n    reasoningTokens: number,\n    cachedInputTokens: number,\n    inferenceTimeMs: number,\n  ) => void;\n\n  constructor(\n    llmClient: LLMClient,\n    defaultModelName: AvailableModel,\n    defaultClientOptions: ClientOptions,\n    resolveLlmClient: (model?: ModelConfiguration) => LLMClient,\n    systemPrompt?: string,\n    logInferenceToFile?: boolean,\n    experimental?: boolean,\n    onMetrics?: (\n      functionName: V3FunctionName,\n      promptTokens: number,\n      completionTokens: number,\n      reasoningTokens: number,\n      cachedInputTokens: number,\n      inferenceTimeMs: number,\n    ) => void,\n  ) {\n    this.llmClient = llmClient;\n    this.defaultModelName = defaultModelName;\n    this.defaultClientOptions = defaultClientOptions;\n    this.resolveLlmClient = resolveLlmClient;\n    this.systemPrompt = systemPrompt ?? \"\";\n    this.logInferenceToFile = logInferenceToFile ?? false;\n    this.experimental = experimental ?? false;\n    this.onMetrics = onMetrics;\n  }\n\n  async extract<T extends StagehandZodSchema>(\n    params: ExtractHandlerParams<T>,\n  ): Promise<InferStagehandSchema<T> | { pageText: string }> {\n    const {\n      instruction,\n      schema,\n      page,\n      selector,\n      ignoreSelectors,\n      timeout,\n      model,\n      screenshot,\n    } = params;\n\n    const llmClient = this.resolveLlmClient(model);\n\n    const ensureTimeRemaining = createTimeoutGuard(\n      timeout,\n      (ms) => new ExtractTimeoutError(ms),\n    );\n\n    // No-args → page text (parity with v2)\n    const noArgs = !instruction && !schema;\n    if (noArgs) {\n      const focusSelector = selector?.replace(/^xpath=/i, \"\") ?? \"\";\n      ensureTimeRemaining();\n      const snap = await captureHybridSnapshot(page, {\n        experimental: this.experimental,\n        focusSelector: focusSelector || undefined,\n        ignoreSelectors,\n      });\n      ensureTimeRemaining();\n\n      const result = { pageText: snap.combinedTree };\n      // Validate via the same schema used in v2\n      return pageTextSchema.parse(result);\n    }\n\n    if (!instruction && schema) {\n      throw new StagehandInvalidArgumentError(\n        \"extract() requires an instruction when a schema is provided.\",\n      );\n    }\n\n    if (screenshot && llmClient.type !== \"aisdk\") {\n      throw new StagehandInvalidArgumentError(\n        \"extract({ screenshot: true }) is only supported with AI SDK clients.\",\n      );\n    }\n\n    const focusSelector = selector?.replace(/^xpath=/, \"\") ?? \"\";\n\n    // Build the hybrid snapshot (includes combinedTree; combinedUrlMap optional)\n    ensureTimeRemaining();\n    const { combinedTree, combinedUrlMap } = await captureHybridSnapshot(page, {\n      experimental: this.experimental,\n      focusSelector: focusSelector,\n      ignoreSelectors,\n    });\n\n    const screenshotBuffer = screenshot\n      ? await (async () => {\n          ensureTimeRemaining();\n          const buffer = await page.screenshot({\n            fullPage: false,\n            type: \"png\",\n          });\n          ensureTimeRemaining();\n          return buffer;\n        })()\n      : undefined;\n\n    v3Logger({\n      category: \"extraction\",\n      message: screenshot\n        ? \"Starting extraction using a11y snapshot and viewport screenshot\"\n        : \"Starting extraction using a11y snapshot\",\n      level: 1,\n      auxiliary: instruction\n        ? { instruction: { value: instruction, type: \"string\" } }\n        : undefined,\n    });\n\n    // Normalize schema: if instruction provided without schema, use defaultExtractSchema\n    const baseSchema: StagehandZodSchema = (schema ??\n      defaultExtractSchema) as StagehandZodSchema;\n    // Ensure we pass an object schema into inference; wrap non-object schemas\n    const isObjectSchema = getZodType(baseSchema) === \"object\";\n    const WRAP_KEY = \"value\" as const;\n    const factory = getZFactory(baseSchema);\n    const objectSchema: StagehandZodObject = isObjectSchema\n      ? (baseSchema as StagehandZodObject)\n      : (factory.object({\n          [WRAP_KEY]: baseSchema as ZodTypeAny,\n        }) as StagehandZodObject);\n\n    const [transformedSchema, urlFieldPaths] =\n      transformUrlStringsToNumericIds(objectSchema);\n\n    ensureTimeRemaining();\n    const extractionResponse: ExtractionResponse<StagehandZodObject> =\n      await runExtract<StagehandZodObject>({\n        instruction,\n        domElements: combinedTree,\n        schema: transformedSchema as StagehandZodObject,\n        llmClient,\n        userProvidedInstructions: this.systemPrompt,\n        logger: v3Logger,\n        logInferenceToFile: this.logInferenceToFile,\n        screenshot: screenshotBuffer,\n      });\n\n    const {\n      metadata: { completed },\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens = 0,\n      cached_input_tokens = 0,\n      inference_time_ms,\n      ...rest\n    } = extractionResponse;\n    let output = rest as InferStagehandSchema<StagehandZodObject>;\n\n    // Update EXTRACT metrics from the LLM calls\n    this.onMetrics?.(\n      V3FunctionName.EXTRACT,\n      prompt_tokens,\n      completion_tokens,\n      reasoning_tokens,\n      cached_input_tokens,\n      inference_time_ms,\n    );\n\n    // Re-inject URLs for any url() fields we temporarily converted to number()\n    const idToUrl: Record<EncodedId, string> = (combinedUrlMap ?? {}) as Record<\n      EncodedId,\n      string\n    >;\n    for (const { segments } of urlFieldPaths) {\n      injectUrls(\n        output as Record<string, unknown>,\n        segments,\n        idToUrl as unknown as Record<string, string>,\n      );\n    }\n    // If we wrapped a non-object schema, unwrap the value\n    if (!isObjectSchema && output && typeof output === \"object\") {\n      output = (output as Record<string, unknown>)[WRAP_KEY];\n    }\n\n    const resultPreviewLength = 200;\n    const resultString = JSON.stringify(output) ?? \"undefined\";\n    const resultPreview =\n      resultString.length > resultPreviewLength\n        ? resultString.slice(0, resultPreviewLength) + \"...\"\n        : resultString;\n\n    v3Logger({\n      category: \"extraction\",\n      message: completed\n        ? \"Extraction completed successfully\"\n        : \"Extraction incomplete after processing all data\",\n      level: 1,\n      auxiliary: {\n        prompt_tokens: { value: String(prompt_tokens), type: \"string\" },\n        completion_tokens: { value: String(completion_tokens), type: \"string\" },\n        inference_time_ms: {\n          value: String(inference_time_ms),\n          type: \"string\",\n        },\n        result: { value: resultPreview, type: \"string\" },\n      },\n    });\n\n    return output as InferStagehandSchema<T>;\n  }\n}\n"]}

package/dist/cjs/lib/v3/index.d.ts

@@ -18,6 +18,7 @@ export { validateZodSchema, isRunningInBun, toGeminiSchema, getZodType, transfor
 export { isZod4Schema, isZod3Schema, toJsonSchema } from "./zodCompat.js";
 export { connectToMCPServer } from "./mcp/connection.js";
 export { V3Evaluator } from "../v3Evaluator.js";
+export type { V3EvaluatorBackend, V3EvaluatorConstructorOptions, V3EvaluatorOptions, } from "../v3Evaluator.js";
 export { tool } from "ai";
 export { getAISDKLanguageModel } from "./llm/LLMProvider.js";
 export { __internalCreateInMemoryAgentCacheHandle } from "./cache/serverAgentCache.js";

package/dist/cjs/lib/v3/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../lib/v3/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,mEAAqD;AACrD,mCAA6B;AAC7B,qDAAwE;AACxE,+DAGkC;AAClC,0CAWqB;AACrB,iDAA0E;AAC1E,uDAAyD;AACzD,sDAAgD;AAChD,2BAA0B;AAC1B,yDAA6D;AAC7D,qEAAuF;AACvF,4DAA8E;AAE9E,iCAA6B;AAApB,2FAAA,EAAE,OAAA;AACX,iCAA0C;AAAjC,kGAAA,EAAE,OAAa;AAExB,0DAAwC;AACxC,mDAAwE;AAA/D,uHAAA,uBAAuB,OAAA;AAAE,yGAAA,SAAS,OAAA;AAE3C,6DAGkC;AAFhC,iHAAA,aAAa,OAAA;AACb,2HAAA,uBAAuB,OAAA;AAUzB,wCAWqB;AAVnB,6GAAA,iBAAiB,OAAA;AACjB,0GAAA,cAAc,OAAA;AACd,0GAAA,cAAc,OAAA;AACd,sGAAA,UAAU,OAAA;AACV,2GAAA,eAAe,OAAA;AACf,sGAAA,UAAU,OAAA;AACV,6GAAA,iBAAiB,OAAA;AACjB,6GAAA,iBAAiB,OAAA;AACjB,gHAAA,oBAAoB,OAAA;AACpB,2GAAA,eAAe,OAAA;AAEjB,+CAA0E;AAAjE,4GAAA,YAAY,OAAA;AAAE,4GAAA,YAAY,OAAA;AAAE,4GAAA,YAAY,OAAA;AAEjD,qDAAyD;AAAhD,mHAAA,kBAAkB,OAAA;AAC3B,oDAAgD;AAAvC,6GAAA,WAAW,OAAA;AACpB,yBAA0B;AAAjB,0FAAA,IAAI,OAAA;AACb,uDAA6D;AAApD,uHAAA,qBAAqB,OAAA;AAC9B,mEAAuF;AAA9E,+IAAA,wCAAwC,OAAA;AACjD,0DAA8H;AAArH,6IAAA,kCAAkC,OAAgD;AAwB3F,MAAM,gBAAgB,GAAG;IACvB,GAAG,SAAS;IACZ,EAAE,EAAF,UAAE;IACF,SAAS,EAAE,UAAE;IACb,uBAAuB,EAAvB,sCAAuB;IACvB,SAAS,EAAT,wBAAS;IACT,aAAa,EAAb,gCAAa;IACb,uBAAuB,EAAvB,0CAAuB;IACvB,iBAAiB,EAAjB,4BAAiB;IACjB,cAAc,EAAd,yBAAc;IACd,cAAc,EAAd,yBAAc;IACd,UAAU,EAAV,qBAAU;IACV,eAAe,EAAf,0BAAe;IACf,UAAU,EAAV,qBAAU;IACV,iBAAiB,EAAjB,4BAAiB;IACjB,iBAAiB,EAAjB,4BAAiB;IACjB,oBAAoB,EAApB,+BAAoB;IACpB,eAAe,EAAf,0BAAe;IACf,YAAY,EAAZ,2BAAY;IACZ,YAAY,EAAZ,2BAAY;IACZ,YAAY,EAAZ,2BAAY;IACZ,kBAAkB,EAAlB,kCAAkB;IAClB,WAAW,EAAX,4BAAW;IACX,IAAI,EAAJ,SAAI;IACJ,qBAAqB,EAArB,sCAAqB;IACrB,wCAAwC,EAAxC,8DAAwC;IACxC,4CAA4C,EAC1C,kDAAkC;CACrC,CAAC;AAEF,kBAAe,gBAAgB,CAAC","sourcesContent":["import * as PublicApi from \"./types/public/index.js\";\nimport { V3 } from \"./v3.js\";\nimport { AnnotatedScreenshotText, LLMClient } from \"./llm/LLMClient.js\";\nimport {\n  AgentProvider,\n  modelToAgentProviderMap,\n} from \"./agent/AgentProvider.js\";\nimport {\n  validateZodSchema,\n  isRunningInBun,\n  toGeminiSchema,\n  getZodType,\n  transformSchema,\n  injectUrls,\n  providerEnvVarMap,\n  loadApiKeyFromEnv,\n  trimTrailingTextNode,\n  jsonSchemaToZod,\n} from \"../utils.js\";\nimport { isZod4Schema, isZod3Schema, toJsonSchema } from \"./zodCompat.js\";\nimport { connectToMCPServer } from \"./mcp/connection.js\";\nimport { V3Evaluator } from \"../v3Evaluator.js\";\nimport { tool } from \"ai\";\nimport { getAISDKLanguageModel } from \"./llm/LLMProvider.js\";\nimport { __internalCreateInMemoryAgentCacheHandle } from \"./cache/serverAgentCache.js\";\nimport { maybeRunShutdownSupervisorFromArgv } from \"./shutdown/supervisor.js\";\n\nexport { V3 } from \"./v3.js\";\nexport { V3 as Stagehand } from \"./v3.js\";\n\nexport * from \"./types/public/index.js\";\nexport { AnnotatedScreenshotText, LLMClient } from \"./llm/LLMClient.js\";\n\nexport {\n  AgentProvider,\n  modelToAgentProviderMap,\n} from \"./agent/AgentProvider.js\";\nexport type {\n  AgentTools,\n  AgentToolTypesMap,\n  AgentUITools,\n  AgentToolCall,\n  AgentToolResult,\n} from \"./agent/tools/index.js\";\n\nexport {\n  validateZodSchema,\n  isRunningInBun,\n  toGeminiSchema,\n  getZodType,\n  transformSchema,\n  injectUrls,\n  providerEnvVarMap,\n  loadApiKeyFromEnv,\n  trimTrailingTextNode,\n  jsonSchemaToZod,\n} from \"../utils.js\";\nexport { isZod4Schema, isZod3Schema, toJsonSchema } from \"./zodCompat.js\";\n\nexport { connectToMCPServer } from \"./mcp/connection.js\";\nexport { V3Evaluator } from \"../v3Evaluator.js\";\nexport { tool } from \"ai\";\nexport { getAISDKLanguageModel } from \"./llm/LLMProvider.js\";\nexport { __internalCreateInMemoryAgentCacheHandle } from \"./cache/serverAgentCache.js\";\nexport { maybeRunShutdownSupervisorFromArgv as __internalMaybeRunShutdownSupervisorFromArgv } from \"./shutdown/supervisor.js\";\nexport type { ServerAgentCacheHandle } from \"./cache/serverAgentCache.js\";\n\nexport type {\n  ChatMessage,\n  ChatMessageContent,\n  ChatMessageImageContent,\n  ChatMessageTextContent,\n  ChatCompletionOptions,\n  LLMResponse,\n  CreateChatCompletionOptions,\n  LLMUsage,\n  LLMParsedResponse,\n} from \"./llm/LLMClient.js\";\n\nexport type {\n  StagehandZodSchema,\n  StagehandZodObject,\n  InferStagehandSchema,\n  JsonSchemaDocument,\n} from \"./zodCompat.js\";\n\nexport type { JsonSchema, JsonSchemaProperty } from \"../utils.js\";\n\nconst StagehandDefault = {\n  ...PublicApi,\n  V3,\n  Stagehand: V3,\n  AnnotatedScreenshotText,\n  LLMClient,\n  AgentProvider,\n  modelToAgentProviderMap,\n  validateZodSchema,\n  isRunningInBun,\n  toGeminiSchema,\n  getZodType,\n  transformSchema,\n  injectUrls,\n  providerEnvVarMap,\n  loadApiKeyFromEnv,\n  trimTrailingTextNode,\n  jsonSchemaToZod,\n  isZod4Schema,\n  isZod3Schema,\n  toJsonSchema,\n  connectToMCPServer,\n  V3Evaluator,\n  tool,\n  getAISDKLanguageModel,\n  __internalCreateInMemoryAgentCacheHandle,\n  __internalMaybeRunShutdownSupervisorFromArgv:\n    maybeRunShutdownSupervisorFromArgv,\n};\n\nexport default StagehandDefault;\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../lib/v3/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,mEAAqD;AACrD,mCAA6B;AAC7B,qDAAwE;AACxE,+DAGkC;AAClC,0CAWqB;AACrB,iDAA0E;AAC1E,uDAAyD;AACzD,sDAAgD;AAChD,2BAA0B;AAC1B,yDAA6D;AAC7D,qEAAuF;AACvF,4DAA8E;AAE9E,iCAA6B;AAApB,2FAAA,EAAE,OAAA;AACX,iCAA0C;AAAjC,kGAAA,EAAE,OAAa;AAExB,0DAAwC;AACxC,mDAAwE;AAA/D,uHAAA,uBAAuB,OAAA;AAAE,yGAAA,SAAS,OAAA;AAE3C,6DAGkC;AAFhC,iHAAA,aAAa,OAAA;AACb,2HAAA,uBAAuB,OAAA;AAUzB,wCAWqB;AAVnB,6GAAA,iBAAiB,OAAA;AACjB,0GAAA,cAAc,OAAA;AACd,0GAAA,cAAc,OAAA;AACd,sGAAA,UAAU,OAAA;AACV,2GAAA,eAAe,OAAA;AACf,sGAAA,UAAU,OAAA;AACV,6GAAA,iBAAiB,OAAA;AACjB,6GAAA,iBAAiB,OAAA;AACjB,gHAAA,oBAAoB,OAAA;AACpB,2GAAA,eAAe,OAAA;AAEjB,+CAA0E;AAAjE,4GAAA,YAAY,OAAA;AAAE,4GAAA,YAAY,OAAA;AAAE,4GAAA,YAAY,OAAA;AAEjD,qDAAyD;AAAhD,mHAAA,kBAAkB,OAAA;AAC3B,oDAAgD;AAAvC,6GAAA,WAAW,OAAA;AAMpB,yBAA0B;AAAjB,0FAAA,IAAI,OAAA;AACb,uDAA6D;AAApD,uHAAA,qBAAqB,OAAA;AAC9B,mEAAuF;AAA9E,+IAAA,wCAAwC,OAAA;AACjD,0DAA8H;AAArH,6IAAA,kCAAkC,OAAgD;AAwB3F,MAAM,gBAAgB,GAAG;IACvB,GAAG,SAAS;IACZ,EAAE,EAAF,UAAE;IACF,SAAS,EAAE,UAAE;IACb,uBAAuB,EAAvB,sCAAuB;IACvB,SAAS,EAAT,wBAAS;IACT,aAAa,EAAb,gCAAa;IACb,uBAAuB,EAAvB,0CAAuB;IACvB,iBAAiB,EAAjB,4BAAiB;IACjB,cAAc,EAAd,yBAAc;IACd,cAAc,EAAd,yBAAc;IACd,UAAU,EAAV,qBAAU;IACV,eAAe,EAAf,0BAAe;IACf,UAAU,EAAV,qBAAU;IACV,iBAAiB,EAAjB,4BAAiB;IACjB,iBAAiB,EAAjB,4BAAiB;IACjB,oBAAoB,EAApB,+BAAoB;IACpB,eAAe,EAAf,0BAAe;IACf,YAAY,EAAZ,2BAAY;IACZ,YAAY,EAAZ,2BAAY;IACZ,YAAY,EAAZ,2BAAY;IACZ,kBAAkB,EAAlB,kCAAkB;IAClB,WAAW,EAAX,4BAAW;IACX,IAAI,EAAJ,SAAI;IACJ,qBAAqB,EAArB,sCAAqB;IACrB,wCAAwC,EAAxC,8DAAwC;IACxC,4CAA4C,EAC1C,kDAAkC;CACrC,CAAC;AAEF,kBAAe,gBAAgB,CAAC","sourcesContent":["import * as PublicApi from \"./types/public/index.js\";\nimport { V3 } from \"./v3.js\";\nimport { AnnotatedScreenshotText, LLMClient } from \"./llm/LLMClient.js\";\nimport {\n  AgentProvider,\n  modelToAgentProviderMap,\n} from \"./agent/AgentProvider.js\";\nimport {\n  validateZodSchema,\n  isRunningInBun,\n  toGeminiSchema,\n  getZodType,\n  transformSchema,\n  injectUrls,\n  providerEnvVarMap,\n  loadApiKeyFromEnv,\n  trimTrailingTextNode,\n  jsonSchemaToZod,\n} from \"../utils.js\";\nimport { isZod4Schema, isZod3Schema, toJsonSchema } from \"./zodCompat.js\";\nimport { connectToMCPServer } from \"./mcp/connection.js\";\nimport { V3Evaluator } from \"../v3Evaluator.js\";\nimport { tool } from \"ai\";\nimport { getAISDKLanguageModel } from \"./llm/LLMProvider.js\";\nimport { __internalCreateInMemoryAgentCacheHandle } from \"./cache/serverAgentCache.js\";\nimport { maybeRunShutdownSupervisorFromArgv } from \"./shutdown/supervisor.js\";\n\nexport { V3 } from \"./v3.js\";\nexport { V3 as Stagehand } from \"./v3.js\";\n\nexport * from \"./types/public/index.js\";\nexport { AnnotatedScreenshotText, LLMClient } from \"./llm/LLMClient.js\";\n\nexport {\n  AgentProvider,\n  modelToAgentProviderMap,\n} from \"./agent/AgentProvider.js\";\nexport type {\n  AgentTools,\n  AgentToolTypesMap,\n  AgentUITools,\n  AgentToolCall,\n  AgentToolResult,\n} from \"./agent/tools/index.js\";\n\nexport {\n  validateZodSchema,\n  isRunningInBun,\n  toGeminiSchema,\n  getZodType,\n  transformSchema,\n  injectUrls,\n  providerEnvVarMap,\n  loadApiKeyFromEnv,\n  trimTrailingTextNode,\n  jsonSchemaToZod,\n} from \"../utils.js\";\nexport { isZod4Schema, isZod3Schema, toJsonSchema } from \"./zodCompat.js\";\n\nexport { connectToMCPServer } from \"./mcp/connection.js\";\nexport { V3Evaluator } from \"../v3Evaluator.js\";\nexport type {\n  V3EvaluatorBackend,\n  V3EvaluatorConstructorOptions,\n  V3EvaluatorOptions,\n} from \"../v3Evaluator.js\";\nexport { tool } from \"ai\";\nexport { getAISDKLanguageModel } from \"./llm/LLMProvider.js\";\nexport { __internalCreateInMemoryAgentCacheHandle } from \"./cache/serverAgentCache.js\";\nexport { maybeRunShutdownSupervisorFromArgv as __internalMaybeRunShutdownSupervisorFromArgv } from \"./shutdown/supervisor.js\";\nexport type { ServerAgentCacheHandle } from \"./cache/serverAgentCache.js\";\n\nexport type {\n  ChatMessage,\n  ChatMessageContent,\n  ChatMessageImageContent,\n  ChatMessageTextContent,\n  ChatCompletionOptions,\n  LLMResponse,\n  CreateChatCompletionOptions,\n  LLMUsage,\n  LLMParsedResponse,\n} from \"./llm/LLMClient.js\";\n\nexport type {\n  StagehandZodSchema,\n  StagehandZodObject,\n  InferStagehandSchema,\n  JsonSchemaDocument,\n} from \"./zodCompat.js\";\n\nexport type { JsonSchema, JsonSchemaProperty } from \"../utils.js\";\n\nconst StagehandDefault = {\n  ...PublicApi,\n  V3,\n  Stagehand: V3,\n  AnnotatedScreenshotText,\n  LLMClient,\n  AgentProvider,\n  modelToAgentProviderMap,\n  validateZodSchema,\n  isRunningInBun,\n  toGeminiSchema,\n  getZodType,\n  transformSchema,\n  injectUrls,\n  providerEnvVarMap,\n  loadApiKeyFromEnv,\n  trimTrailingTextNode,\n  jsonSchemaToZod,\n  isZod4Schema,\n  isZod3Schema,\n  toJsonSchema,\n  connectToMCPServer,\n  V3Evaluator,\n  tool,\n  getAISDKLanguageModel,\n  __internalCreateInMemoryAgentCacheHandle,\n  __internalMaybeRunShutdownSupervisorFromArgv:\n    maybeRunShutdownSupervisorFromArgv,\n};\n\nexport default StagehandDefault;\n"]}

package/dist/cjs/lib/v3/types/private/handlers.d.ts

@@ -16,6 +16,7 @@ export interface ExtractHandlerParams<T extends StagehandZodSchema> {
     timeout?: number;
     selector?: string;
     ignoreSelectors?: string[];
+    screenshot?: boolean;
     page: Page;
 }
 export interface ObserveHandlerParams {

package/dist/cjs/lib/v3/types/private/handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/handlers.ts"],"names":[],"mappings":";;;AAiCA,gFAAgF;AAChF,IAAY,yBAYX;AAZD,WAAY,yBAAyB;IACnC,4CAAe,CAAA;IACf,0CAAa,CAAA;IACb,0CAAa,CAAA;IACb,4CAAe,CAAA;IACf,gDAAmB,CAAA;IACnB,qDAAwB,CAAA;IACxB,qDAAwB,CAAA;IACxB,qFAAwD,CAAA;IACxD,4CAAe,CAAA;IACf,yDAA4B,CAAA;IAC5B,0DAA6B,CAAA;AAC/B,CAAC,EAZW,yBAAyB,yCAAzB,yBAAyB,QAYpC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { StagehandZodSchema } from \"../../zodCompat.js\";\nimport type { Variables } from \"../public/agent.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  page: Page;\n}\n\nexport interface ExtractHandlerParams<T extends StagehandZodSchema> {\n  instruction?: string;\n  schema?: T;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  ignoreSelectors?: string[];\n  page: Page;\n}\n\nexport interface ObserveHandlerParams {\n  instruction?: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  selector?: string;\n  ignoreSelectors?: string[];\n  page: Page;\n}\n\n// We can use this enum to list the actions supported in performUnderstudyMethod\nexport enum SupportedUnderstudyAction {\n  CLICK = \"click\",\n  FILL = \"fill\",\n  TYPE = \"type\",\n  PRESS = \"press\",\n  SCROLL = \"scrollTo\",\n  NEXT_CHUNK = \"nextChunk\",\n  PREV_CHUNK = \"prevChunk\",\n  SELECT_OPTION_FROM_DROPDOWN = \"selectOptionFromDropdown\",\n  HOVER = \"hover\",\n  DOUBLE_CLICK = \"doubleClick\",\n  DRAG_AND_DROP = \"dragAndDrop\",\n}\n"]}
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../../../../../lib/v3/types/private/handlers.ts"],"names":[],"mappings":";;;AAkCA,gFAAgF;AAChF,IAAY,yBAYX;AAZD,WAAY,yBAAyB;IACnC,4CAAe,CAAA;IACf,0CAAa,CAAA;IACb,0CAAa,CAAA;IACb,4CAAe,CAAA;IACf,gDAAmB,CAAA;IACnB,qDAAwB,CAAA;IACxB,qDAAwB,CAAA;IACxB,qFAAwD,CAAA;IACxD,4CAAe,CAAA;IACf,yDAA4B,CAAA;IAC5B,0DAA6B,CAAA;AAC/B,CAAC,EAZW,yBAAyB,yCAAzB,yBAAyB,QAYpC","sourcesContent":["import { Page } from \"../../understudy/page.js\";\nimport { ModelConfiguration } from \"../public/model.js\";\nimport type { StagehandZodSchema } from \"../../zodCompat.js\";\nimport type { Variables } from \"../public/agent.js\";\n\nexport interface ActHandlerParams {\n  instruction: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  page: Page;\n}\n\nexport interface ExtractHandlerParams<T extends StagehandZodSchema> {\n  instruction?: string;\n  schema?: T;\n  model?: ModelConfiguration;\n  timeout?: number;\n  selector?: string;\n  ignoreSelectors?: string[];\n  screenshot?: boolean;\n  page: Page;\n}\n\nexport interface ObserveHandlerParams {\n  instruction?: string;\n  model?: ModelConfiguration;\n  variables?: Variables;\n  timeout?: number;\n  selector?: string;\n  ignoreSelectors?: string[];\n  page: Page;\n}\n\n// We can use this enum to list the actions supported in performUnderstudyMethod\nexport enum SupportedUnderstudyAction {\n  CLICK = \"click\",\n  FILL = \"fill\",\n  TYPE = \"type\",\n  PRESS = \"press\",\n  SCROLL = \"scrollTo\",\n  NEXT_CHUNK = \"nextChunk\",\n  PREV_CHUNK = \"prevChunk\",\n  SELECT_OPTION_FROM_DROPDOWN = \"selectOptionFromDropdown\",\n  HOVER = \"hover\",\n  DOUBLE_CLICK = \"doubleClick\",\n  DRAG_AND_DROP = \"dragAndDrop\",\n}\n"]}

package/dist/cjs/lib/v3/types/public/api.d.ts

@@ -765,6 +765,7 @@ export declare const ExtractOptionsSchema: z.ZodOptional<z.ZodObject<{
     timeout: z.ZodOptional<z.ZodNumber>;
     selector: z.ZodOptional<z.ZodString>;
     ignoreSelectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    screenshot: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>>;
 export declare const ExtractRequestSchema: z.ZodObject<{
     instruction: z.ZodOptional<z.ZodString>;
@@ -807,6 +808,7 @@ export declare const ExtractRequestSchema: z.ZodObject<{
         timeout: z.ZodOptional<z.ZodNumber>;
         selector: z.ZodOptional<z.ZodString>;
         ignoreSelectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        screenshot: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
     frameId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     streamResponse: z.ZodOptional<z.ZodBoolean>;

package/dist/cjs/lib/v3/types/public/api.js

@@ -511,6 +511,10 @@ exports.ExtractOptionsSchema = v4_1.z
         description: "Selectors for elements and subtrees that should be excluded from extraction",
         example: ["nav", ".cookie-banner", "#sidebar-ads"],
     }),
+    screenshot: v4_1.z.boolean().optional().meta({
+        description: "When true, include a screenshot of the current viewport in the extraction LLM call. Defaults to false.",
+        example: false,
+    }),
 })
     .optional()
     .meta({ id: "ExtractOptions" });