@browserbasehq/orca 3.1.0-patch.3 → 3.2.0-middleware.1

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

@@ -0,0 +1,344 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActHandler = void 0;
+// lib/v3/handlers/actHandler.ts
+const inference_js_1 = require("../../inference.js");
+const prompt_js_1 = require("../../prompt.js");
+const utils_js_1 = require("../../utils.js");
+const logger_js_1 = require("../logger.js");
+const methods_js_1 = require("../types/public/methods.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+const index_js_1 = require("../understudy/a11y/snapshot/index.js");
+const index_js_2 = require("../types/private/index.js");
+const actHandlerUtils_js_1 = require("./handlerUtils/actHandlerUtils.js");
+const timeoutGuard_js_1 = require("./handlerUtils/timeoutGuard.js");
+const variables_js_1 = require("../agent/utils/variables.js");
+class ActHandler {
+    llmClient;
+    defaultModelName;
+    defaultClientOptions;
+    resolveLlmClient;
+    systemPrompt;
+    logInferenceToFile;
+    selfHeal;
+    onMetrics;
+    defaultDomSettleTimeoutMs;
+    constructor(llmClient, defaultModelName, defaultClientOptions, resolveLlmClient, systemPrompt, logInferenceToFile, selfHeal, onMetrics, defaultDomSettleTimeoutMs) {
+        this.llmClient = llmClient;
+        this.defaultModelName = defaultModelName;
+        this.defaultClientOptions = defaultClientOptions;
+        this.resolveLlmClient = resolveLlmClient;
+        this.systemPrompt = systemPrompt ?? "";
+        this.logInferenceToFile = logInferenceToFile ?? false;
+        this.selfHeal = !!selfHeal;
+        this.onMetrics = onMetrics;
+        this.defaultDomSettleTimeoutMs = defaultDomSettleTimeoutMs;
+    }
+    recordActMetrics(response) {
+        this.onMetrics?.(methods_js_1.V3FunctionName.ACT, response.prompt_tokens ?? 0, response.completion_tokens ?? 0, response.reasoning_tokens ?? 0, response.cached_input_tokens ?? 0, response.inference_time_ms ?? 0);
+    }
+    async getActionFromLLM({ instruction, domElements, xpathMap, llmClient, requireMethodAndArguments = true, }) {
+        const response = await (0, inference_js_1.act)({
+            instruction,
+            domElements,
+            llmClient,
+            userProvidedInstructions: this.systemPrompt,
+            logger: logger_js_1.v3Logger,
+            logInferenceToFile: this.logInferenceToFile,
+        });
+        this.recordActMetrics(response);
+        const normalized = normalizeActInferenceElement(response.element, xpathMap, requireMethodAndArguments);
+        if (!normalized) {
+            return { response };
+        }
+        return {
+            action: { ...normalized },
+            response,
+        };
+    }
+    async act(params) {
+        const { instruction, page, variables, timeout, model } = params;
+        const llmClient = this.resolveLlmClient(model);
+        const ensureTimeRemaining = (0, timeoutGuard_js_1.createTimeoutGuard)(timeout, (ms) => new sdkErrors_js_1.ActTimeoutError(ms));
+        ensureTimeRemaining();
+        await (0, actHandlerUtils_js_1.waitForDomNetworkQuiet)(page.mainFrame(), this.defaultDomSettleTimeoutMs);
+        ensureTimeRemaining();
+        const { combinedTree, combinedXpathMap } = await (0, index_js_1.captureHybridSnapshot)(page, { experimental: true });
+        const actInstruction = (0, prompt_js_1.buildActPrompt)(instruction, Object.values(index_js_2.SupportedUnderstudyAction), variables);
+        ensureTimeRemaining();
+        const { action: firstAction, response: actInferenceResponse } = await this.getActionFromLLM({
+            instruction: actInstruction,
+            domElements: combinedTree,
+            xpathMap: combinedXpathMap,
+            llmClient,
+        });
+        if (!firstAction) {
+            (0, logger_js_1.v3Logger)({
+                category: "action",
+                message: "no actionable element returned by LLM",
+                level: 1,
+            });
+            return {
+                success: false,
+                message: "Failed to perform act: No action found",
+                actionDescription: instruction,
+                actions: [],
+            };
+        }
+        // First action (self-heal aware path)
+        ensureTimeRemaining();
+        const firstResult = await this.takeDeterministicAction(firstAction, page, this.defaultDomSettleTimeoutMs, llmClient, ensureTimeRemaining, variables);
+        // If not two-step, return the first action result
+        if (actInferenceResponse?.twoStep !== true) {
+            return firstResult;
+        }
+        // Take a new focused snapshot and observe again
+        ensureTimeRemaining();
+        const { combinedTree: combinedTree2, combinedXpathMap: combinedXpathMap2 } = await (0, index_js_1.captureHybridSnapshot)(page, {
+            experimental: true,
+        });
+        let diffedTree = (0, index_js_1.diffCombinedTrees)(combinedTree, combinedTree2);
+        if (!diffedTree.trim()) {
+            // Fallback: if no diff detected, use the fresh tree to avoid empty context
+            diffedTree = combinedTree2;
+        }
+        const previousAction = `method: ${firstAction.method}, description: ${firstAction.description}, arguments: ${firstAction.arguments}`;
+        const stepTwoInstructions = (0, prompt_js_1.buildStepTwoPrompt)(instruction, previousAction, Object.values(index_js_2.SupportedUnderstudyAction).filter((action) => action !== index_js_2.SupportedUnderstudyAction.SELECT_OPTION_FROM_DROPDOWN), variables);
+        ensureTimeRemaining();
+        const { action: secondAction } = await this.getActionFromLLM({
+            instruction: stepTwoInstructions,
+            domElements: diffedTree,
+            xpathMap: combinedXpathMap2,
+            llmClient,
+        });
+        if (!secondAction) {
+            // No second action found — return first result as-is
+            return firstResult;
+        }
+        ensureTimeRemaining();
+        const secondResult = await this.takeDeterministicAction(secondAction, page, this.defaultDomSettleTimeoutMs, llmClient, ensureTimeRemaining, variables);
+        // Combine results
+        return {
+            success: firstResult.success && secondResult.success,
+            message: secondResult.success
+                ? `${firstResult.message} → ${secondResult.message}`
+                : `${firstResult.message} → ${secondResult.message}`,
+            actionDescription: firstResult.actionDescription,
+            actions: [
+                ...(firstResult.actions || []),
+                ...(secondResult.actions || []),
+            ],
+        };
+    }
+    async takeDeterministicAction(action, page, domSettleTimeoutMs, llmClientOverride, ensureTimeRemaining, variables) {
+        ensureTimeRemaining?.();
+        const settleTimeout = domSettleTimeoutMs ?? this.defaultDomSettleTimeoutMs;
+        const effectiveClient = llmClientOverride ?? this.llmClient;
+        const method = action.method?.trim();
+        if (!method || method === "not-supported") {
+            (0, logger_js_1.v3Logger)({
+                category: "action",
+                message: "action has no supported method",
+                level: 0,
+                auxiliary: {
+                    act: { value: JSON.stringify(action), type: "object" },
+                },
+            });
+            return {
+                success: false,
+                message: `Unable to perform action: The method '${method ?? ""}' is not supported in Action. Please use a supported Playwright locator method.`,
+                actionDescription: action.description || `Action (${method ?? "unknown"})`,
+                actions: [],
+            };
+        }
+        const placeholderArgs = Array.isArray(action.arguments)
+            ? [...action.arguments]
+            : [];
+        const resolvedArgs = substituteVariablesInArguments(action.arguments, variables) ?? [];
+        try {
+            ensureTimeRemaining?.();
+            await (0, actHandlerUtils_js_1.performUnderstudyMethod)(page, page.mainFrame(), method, action.selector, resolvedArgs, settleTimeout);
+            return {
+                success: true,
+                message: `Action [${method}] performed successfully on selector: ${action.selector}`,
+                actionDescription: action.description || `action (${method})`,
+                actions: [
+                    {
+                        selector: action.selector,
+                        description: action.description || `action (${method})`,
+                        method,
+                        arguments: placeholderArgs,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            if (err instanceof sdkErrors_js_1.ActTimeoutError) {
+                throw err;
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            // Attempt self-heal: rerun actInference and retry with updated selector
+            if (this.selfHeal) {
+                (0, logger_js_1.v3Logger)({
+                    category: "action",
+                    message: "Error performing action. Reprocessing the page and trying again",
+                    level: 1,
+                    auxiliary: {
+                        error: { value: msg, type: "string" },
+                        action: {
+                            value: JSON.stringify(action),
+                            type: "object",
+                        },
+                    },
+                });
+                try {
+                    // Build an instruction combining method + description, avoiding duplication
+                    const actCommand = action.description
+                        ? action.description.toLowerCase().startsWith(method.toLowerCase())
+                            ? action.description
+                            : `${method} ${action.description}`
+                        : method;
+                    // Take a fresh snapshot and ask for a new actionable element
+                    ensureTimeRemaining?.();
+                    const { combinedTree, combinedXpathMap } = await (0, index_js_1.captureHybridSnapshot)(page, {
+                        experimental: true,
+                    });
+                    const instruction = (0, prompt_js_1.buildActPrompt)(actCommand, Object.values(index_js_2.SupportedUnderstudyAction), {});
+                    ensureTimeRemaining?.();
+                    const { action: fallbackAction, response: fallbackResponse } = await this.getActionFromLLM({
+                        instruction,
+                        domElements: combinedTree,
+                        xpathMap: combinedXpathMap,
+                        llmClient: effectiveClient,
+                        requireMethodAndArguments: false,
+                    });
+                    const fallbackElement = fallbackResponse.element;
+                    if (!fallbackElement) {
+                        return {
+                            success: false,
+                            message: "Failed to self-heal act: No observe results found for action",
+                            actionDescription: actCommand,
+                            actions: [],
+                        };
+                    }
+                    // Retry with original method/args but new selector from fallback
+                    let newSelector = action.selector;
+                    if (fallbackAction?.selector) {
+                        newSelector = fallbackAction.selector;
+                    }
+                    ensureTimeRemaining?.();
+                    await (0, actHandlerUtils_js_1.performUnderstudyMethod)(page, page.mainFrame(), method, newSelector, resolvedArgs, settleTimeout);
+                    return {
+                        success: true,
+                        message: `Action [${method}] performed successfully on selector: ${newSelector}`,
+                        actionDescription: action.description || `action (${method})`,
+                        actions: [
+                            {
+                                selector: newSelector,
+                                description: action.description || `action (${method})`,
+                                method,
+                                arguments: placeholderArgs,
+                            },
+                        ],
+                    };
+                }
+                catch (retryErr) {
+                    if (retryErr instanceof sdkErrors_js_1.ActTimeoutError) {
+                        throw retryErr;
+                    }
+                    const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+                    return {
+                        success: false,
+                        message: `Failed to perform act after self-heal: ${retryMsg}`,
+                        actionDescription: action.description || `action (${method})`,
+                        actions: [],
+                    };
+                }
+            }
+            return {
+                success: false,
+                message: `Failed to perform act: ${msg}`,
+                actionDescription: action.description || `action (${method})`,
+                actions: [],
+            };
+        }
+    }
+}
+exports.ActHandler = ActHandler;
+function normalizeActInferenceElement(element, xpathMap, requireMethodAndArguments = true) {
+    if (!element) {
+        return undefined;
+    }
+    const { elementId, description, method, arguments: args } = element;
+    const hasArgs = Array.isArray(args);
+    if (requireMethodAndArguments &&
+        (!method || method === "not-supported" || !hasArgs)) {
+        return undefined;
+    }
+    if (typeof elementId !== "string" || !elementId.includes("-")) {
+        return undefined;
+    }
+    const xp = xpathMap[elementId];
+    const trimmed = (0, utils_js_1.trimTrailingTextNode)(xp);
+    if (!trimmed) {
+        return undefined;
+    }
+    // For dragAndDrop, convert element ID in arguments to xpath (target element)
+    let resolvedArgs = hasArgs ? args : undefined;
+    if (method === "dragAndDrop" && hasArgs && args.length > 0) {
+        const targetArg = args[0];
+        // Check if argument looks like an element ID (e.g., "1-67")
+        if (typeof targetArg === "string" && /^\d+-\d+$/.test(targetArg)) {
+            const argXpath = xpathMap[targetArg];
+            const trimmedArgXpath = (0, utils_js_1.trimTrailingTextNode)(argXpath);
+            if (trimmedArgXpath) {
+                resolvedArgs = [`xpath=${trimmedArgXpath}`, ...args.slice(1)];
+            }
+            else {
+                // Target element lookup failed, filter out this action
+                (0, logger_js_1.v3Logger)({
+                    category: "action",
+                    message: "dragAndDrop target element lookup failed",
+                    level: 1,
+                    auxiliary: {
+                        targetElementId: { value: targetArg, type: "string" },
+                        sourceElementId: { value: elementId, type: "string" },
+                    },
+                });
+                return undefined;
+            }
+        }
+        else {
+            (0, logger_js_1.v3Logger)({
+                category: "action",
+                message: "dragAndDrop target element invalid ID format",
+                level: 0,
+                auxiliary: {
+                    targetElementId: { value: String(targetArg), type: "string" },
+                    sourceElementId: { value: elementId, type: "string" },
+                },
+            });
+            return undefined;
+        }
+    }
+    return {
+        description,
+        method,
+        arguments: resolvedArgs,
+        selector: `xpath=${trimmed}`,
+    };
+}
+function substituteVariablesInArguments(args, variables) {
+    if (!variables || !Array.isArray(args)) {
+        return args;
+    }
+    return args.map((arg) => {
+        let out = arg;
+        for (const [key, v] of Object.entries(variables)) {
+            const token = `%${key}%`;
+            out = out.split(token).join((0, variables_js_1.resolveVariableValue)(v));
+        }
+        return out;
+    });
+}
+//# sourceMappingURL=actHandler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actHandler.js","sourceRoot":"","sources":["../../../../../lib/v3/handlers/actHandler.ts"],"names":[],"mappings":"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","sourcesContent":["// lib/v3/handlers/actHandler.ts\nimport { act as actInference } from \"../../inference.js\";\nimport { buildActPrompt, buildStepTwoPrompt } from \"../../prompt.js\";\nimport { trimTrailingTextNode } from \"../../utils.js\";\nimport { v3Logger } from \"../logger.js\";\nimport { ActHandlerParams } from \"../types/private/handlers.js\";\nimport { ActResult, Action, V3FunctionName } from \"../types/public/methods.js\";\nimport { ActTimeoutError } from \"../types/public/sdkErrors.js\";\nimport {\n  captureHybridSnapshot,\n  diffCombinedTrees,\n} from \"../understudy/a11y/snapshot/index.js\";\nimport { LLMClient } from \"../llm/LLMClient.js\";\nimport { SupportedUnderstudyAction } from \"../types/private/index.js\";\nimport { EncodedId } from \"../types/private/internal.js\";\nimport {\n  AvailableModel,\n  ClientOptions,\n  ModelConfiguration,\n} from \"../types/public/model.js\";\nimport type { Variables } from \"../types/public/agent.js\";\nimport type { Page } from \"../understudy/page.js\";\nimport {\n  performUnderstudyMethod,\n  waitForDomNetworkQuiet,\n} from \"./handlerUtils/actHandlerUtils.js\";\nimport { createTimeoutGuard } from \"./handlerUtils/timeoutGuard.js\";\nimport { resolveVariableValue } from \"../agent/utils/variables.js\";\n\ntype ActInferenceElement = {\n  elementId?: string;\n  description: string;\n  method?: string;\n  arguments?: string[];\n};\n\ntype ActInferenceResponse = Awaited<ReturnType<typeof actInference>>;\n\nexport class ActHandler {\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 selfHeal: 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  private readonly defaultDomSettleTimeoutMs?: number;\n\n  constructor(\n    llmClient: LLMClient,\n    defaultModelName: AvailableModel,\n    defaultClientOptions: ClientOptions,\n    resolveLlmClient: (model?: ModelConfiguration) => LLMClient,\n    systemPrompt?: string,\n    logInferenceToFile?: boolean,\n    selfHeal?: boolean,\n    onMetrics?: (\n      functionName: V3FunctionName,\n      promptTokens: number,\n      completionTokens: number,\n      reasoningTokens: number,\n      cachedInputTokens: number,\n      inferenceTimeMs: number,\n    ) => void,\n    defaultDomSettleTimeoutMs?: number,\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.selfHeal = !!selfHeal;\n    this.onMetrics = onMetrics;\n    this.defaultDomSettleTimeoutMs = defaultDomSettleTimeoutMs;\n  }\n\n  private recordActMetrics(response: ActInferenceResponse): void {\n    this.onMetrics?.(\n      V3FunctionName.ACT,\n      response.prompt_tokens ?? 0,\n      response.completion_tokens ?? 0,\n      response.reasoning_tokens ?? 0,\n      response.cached_input_tokens ?? 0,\n      response.inference_time_ms ?? 0,\n    );\n  }\n\n  private async getActionFromLLM({\n    instruction,\n    domElements,\n    xpathMap,\n    llmClient,\n    requireMethodAndArguments = true,\n  }: {\n    instruction: string;\n    domElements: string;\n    xpathMap: Record<string, string>;\n    llmClient: LLMClient;\n    requireMethodAndArguments?: boolean;\n  }): Promise<{ action?: Action; response: ActInferenceResponse }> {\n    const response = await actInference({\n      instruction,\n      domElements,\n      llmClient,\n      userProvidedInstructions: this.systemPrompt,\n      logger: v3Logger,\n      logInferenceToFile: this.logInferenceToFile,\n    });\n\n    this.recordActMetrics(response);\n\n    const normalized = normalizeActInferenceElement(\n      response.element as ActInferenceElement | undefined,\n      xpathMap,\n      requireMethodAndArguments,\n    );\n\n    if (!normalized) {\n      return { response };\n    }\n\n    return {\n      action: { ...normalized } as Action,\n      response,\n    };\n  }\n\n  async act(params: ActHandlerParams): Promise<ActResult> {\n    const { instruction, page, variables, timeout, model } = params;\n\n    const llmClient = this.resolveLlmClient(model);\n    const ensureTimeRemaining = createTimeoutGuard(\n      timeout,\n      (ms) => new ActTimeoutError(ms),\n    );\n\n    ensureTimeRemaining();\n    await waitForDomNetworkQuiet(\n      page.mainFrame(),\n      this.defaultDomSettleTimeoutMs,\n    );\n    ensureTimeRemaining();\n    const { combinedTree, combinedXpathMap } = await captureHybridSnapshot(\n      page,\n      { experimental: true },\n    );\n\n    const actInstruction = buildActPrompt(\n      instruction,\n      Object.values(SupportedUnderstudyAction),\n      variables,\n    );\n\n    ensureTimeRemaining();\n    const { action: firstAction, response: actInferenceResponse } =\n      await this.getActionFromLLM({\n        instruction: actInstruction,\n        domElements: combinedTree,\n        xpathMap: combinedXpathMap,\n        llmClient,\n      });\n\n    if (!firstAction) {\n      v3Logger({\n        category: \"action\",\n        message: \"no actionable element returned by LLM\",\n        level: 1,\n      });\n      return {\n        success: false,\n        message: \"Failed to perform act: No action found\",\n        actionDescription: instruction,\n        actions: [],\n      };\n    }\n\n    // First action (self-heal aware path)\n    ensureTimeRemaining();\n    const firstResult = await this.takeDeterministicAction(\n      firstAction,\n      page,\n      this.defaultDomSettleTimeoutMs,\n      llmClient,\n      ensureTimeRemaining,\n      variables,\n    );\n\n    // If not two-step, return the first action result\n    if (actInferenceResponse?.twoStep !== true) {\n      return firstResult;\n    }\n\n    // Take a new focused snapshot and observe again\n    ensureTimeRemaining();\n    const { combinedTree: combinedTree2, combinedXpathMap: combinedXpathMap2 } =\n      await captureHybridSnapshot(page, {\n        experimental: true,\n      });\n\n    let diffedTree = diffCombinedTrees(combinedTree, combinedTree2);\n    if (!diffedTree.trim()) {\n      // Fallback: if no diff detected, use the fresh tree to avoid empty context\n      diffedTree = combinedTree2;\n    }\n\n    const previousAction = `method: ${firstAction.method}, description: ${firstAction.description}, arguments: ${firstAction.arguments}`;\n\n    const stepTwoInstructions = buildStepTwoPrompt(\n      instruction,\n      previousAction,\n      Object.values(SupportedUnderstudyAction).filter(\n        (\n          action,\n        ): action is Exclude<\n          SupportedUnderstudyAction,\n          SupportedUnderstudyAction.SELECT_OPTION_FROM_DROPDOWN\n        > => action !== SupportedUnderstudyAction.SELECT_OPTION_FROM_DROPDOWN,\n      ),\n      variables,\n    );\n\n    ensureTimeRemaining();\n    const { action: secondAction } = await this.getActionFromLLM({\n      instruction: stepTwoInstructions,\n      domElements: diffedTree,\n      xpathMap: combinedXpathMap2,\n      llmClient,\n    });\n\n    if (!secondAction) {\n      // No second action found — return first result as-is\n      return firstResult;\n    }\n\n    ensureTimeRemaining();\n    const secondResult = await this.takeDeterministicAction(\n      secondAction,\n      page,\n      this.defaultDomSettleTimeoutMs,\n      llmClient,\n      ensureTimeRemaining,\n      variables,\n    );\n\n    // Combine results\n    return {\n      success: firstResult.success && secondResult.success,\n      message: secondResult.success\n        ? `${firstResult.message} → ${secondResult.message}`\n        : `${firstResult.message} → ${secondResult.message}`,\n      actionDescription: firstResult.actionDescription,\n      actions: [\n        ...(firstResult.actions || []),\n        ...(secondResult.actions || []),\n      ],\n    };\n  }\n\n  async takeDeterministicAction(\n    action: Action,\n    page: Page,\n    domSettleTimeoutMs?: number,\n    llmClientOverride?: LLMClient,\n    ensureTimeRemaining?: () => void,\n    variables?: Variables,\n  ): Promise<ActResult> {\n    ensureTimeRemaining?.();\n    const settleTimeout = domSettleTimeoutMs ?? this.defaultDomSettleTimeoutMs;\n    const effectiveClient = llmClientOverride ?? this.llmClient;\n    const method = action.method?.trim();\n    if (!method || method === \"not-supported\") {\n      v3Logger({\n        category: \"action\",\n        message: \"action has no supported method\",\n        level: 0,\n        auxiliary: {\n          act: { value: JSON.stringify(action), type: \"object\" },\n        },\n      });\n      return {\n        success: false,\n        message: `Unable to perform action: The method '${method ?? \"\"}' is not supported in Action. Please use a supported Playwright locator method.`,\n        actionDescription:\n          action.description || `Action (${method ?? \"unknown\"})`,\n        actions: [],\n      };\n    }\n\n    const placeholderArgs = Array.isArray(action.arguments)\n      ? [...action.arguments]\n      : [];\n    const resolvedArgs =\n      substituteVariablesInArguments(action.arguments, variables) ?? [];\n\n    try {\n      ensureTimeRemaining?.();\n      await performUnderstudyMethod(\n        page,\n        page.mainFrame(),\n        method,\n        action.selector,\n        resolvedArgs,\n        settleTimeout,\n      );\n      return {\n        success: true,\n        message: `Action [${method}] performed successfully on selector: ${action.selector}`,\n        actionDescription: action.description || `action (${method})`,\n        actions: [\n          {\n            selector: action.selector,\n            description: action.description || `action (${method})`,\n            method,\n            arguments: placeholderArgs,\n          },\n        ],\n      };\n    } catch (err) {\n      if (err instanceof ActTimeoutError) {\n        throw err;\n      }\n      const msg = err instanceof Error ? err.message : String(err);\n\n      // Attempt self-heal: rerun actInference and retry with updated selector\n      if (this.selfHeal) {\n        v3Logger({\n          category: \"action\",\n          message:\n            \"Error performing action. Reprocessing the page and trying again\",\n          level: 1,\n          auxiliary: {\n            error: { value: msg, type: \"string\" },\n            action: {\n              value: JSON.stringify(action),\n              type: \"object\",\n            },\n          },\n        });\n\n        try {\n          // Build an instruction combining method + description, avoiding duplication\n          const actCommand = action.description\n            ? action.description.toLowerCase().startsWith(method.toLowerCase())\n              ? action.description\n              : `${method} ${action.description}`\n            : method;\n\n          // Take a fresh snapshot and ask for a new actionable element\n          ensureTimeRemaining?.();\n          const { combinedTree, combinedXpathMap } =\n            await captureHybridSnapshot(page, {\n              experimental: true,\n            });\n\n          const instruction = buildActPrompt(\n            actCommand,\n            Object.values(SupportedUnderstudyAction),\n            {},\n          );\n\n          ensureTimeRemaining?.();\n          const { action: fallbackAction, response: fallbackResponse } =\n            await this.getActionFromLLM({\n              instruction,\n              domElements: combinedTree,\n              xpathMap: combinedXpathMap,\n              llmClient: effectiveClient,\n              requireMethodAndArguments: false,\n            });\n\n          const fallbackElement = fallbackResponse.element;\n          if (!fallbackElement) {\n            return {\n              success: false,\n              message:\n                \"Failed to self-heal act: No observe results found for action\",\n              actionDescription: actCommand,\n              actions: [],\n            };\n          }\n\n          // Retry with original method/args but new selector from fallback\n          let newSelector = action.selector;\n          if (fallbackAction?.selector) {\n            newSelector = fallbackAction.selector;\n          }\n\n          ensureTimeRemaining?.();\n          await performUnderstudyMethod(\n            page,\n            page.mainFrame(),\n            method,\n            newSelector,\n            resolvedArgs,\n            settleTimeout,\n          );\n\n          return {\n            success: true,\n            message: `Action [${method}] performed successfully on selector: ${newSelector}`,\n            actionDescription: action.description || `action (${method})`,\n            actions: [\n              {\n                selector: newSelector,\n                description: action.description || `action (${method})`,\n                method,\n                arguments: placeholderArgs,\n              },\n            ],\n          };\n        } catch (retryErr) {\n          if (retryErr instanceof ActTimeoutError) {\n            throw retryErr;\n          }\n          const retryMsg =\n            retryErr instanceof Error ? retryErr.message : String(retryErr);\n          return {\n            success: false,\n            message: `Failed to perform act after self-heal: ${retryMsg}`,\n            actionDescription: action.description || `action (${method})`,\n            actions: [],\n          };\n        }\n      }\n\n      return {\n        success: false,\n        message: `Failed to perform act: ${msg}`,\n        actionDescription: action.description || `action (${method})`,\n        actions: [],\n      };\n    }\n  }\n}\n\nfunction normalizeActInferenceElement(\n  element: ActInferenceElement | undefined,\n  xpathMap: Record<string, string>,\n  requireMethodAndArguments = true,\n): Action | undefined {\n  if (!element) {\n    return undefined;\n  }\n  const { elementId, description, method, arguments: args } = element;\n  const hasArgs = Array.isArray(args);\n\n  if (\n    requireMethodAndArguments &&\n    (!method || method === \"not-supported\" || !hasArgs)\n  ) {\n    return undefined;\n  }\n\n  if (typeof elementId !== \"string\" || !elementId.includes(\"-\")) {\n    return undefined;\n  }\n\n  const xp = xpathMap[elementId as EncodedId];\n  const trimmed = trimTrailingTextNode(xp);\n  if (!trimmed) {\n    return undefined;\n  }\n\n  // For dragAndDrop, convert element ID in arguments to xpath (target element)\n  let resolvedArgs = hasArgs ? args : undefined;\n  if (method === \"dragAndDrop\" && hasArgs && args.length > 0) {\n    const targetArg = args[0];\n    // Check if argument looks like an element ID (e.g., \"1-67\")\n    if (typeof targetArg === \"string\" && /^\\d+-\\d+$/.test(targetArg)) {\n      const argXpath = xpathMap[targetArg as EncodedId];\n      const trimmedArgXpath = trimTrailingTextNode(argXpath);\n      if (trimmedArgXpath) {\n        resolvedArgs = [`xpath=${trimmedArgXpath}`, ...args.slice(1)];\n      } else {\n        // Target element lookup failed, filter out this action\n        v3Logger({\n          category: \"action\",\n          message: \"dragAndDrop target element lookup failed\",\n          level: 1,\n          auxiliary: {\n            targetElementId: { value: targetArg, type: \"string\" },\n            sourceElementId: { value: elementId, type: \"string\" },\n          },\n        });\n        return undefined;\n      }\n    } else {\n      v3Logger({\n        category: \"action\",\n        message: \"dragAndDrop target element invalid ID format\",\n        level: 0,\n        auxiliary: {\n          targetElementId: { value: String(targetArg), type: \"string\" },\n          sourceElementId: { value: elementId, type: \"string\" },\n        },\n      });\n      return undefined;\n    }\n  }\n\n  return {\n    description,\n    method,\n    arguments: resolvedArgs,\n    selector: `xpath=${trimmed}`,\n  } as Action;\n}\n\nfunction substituteVariablesInArguments(\n  args: string[] | undefined,\n  variables?: Variables,\n): string[] | undefined {\n  if (!variables || !Array.isArray(args)) {\n    return args;\n  }\n\n  return args.map((arg: string) => {\n    let out = arg;\n    for (const [key, v] of Object.entries(variables)) {\n      const token = `%${key}%`;\n      out = out.split(token).join(resolveVariableValue(v));\n    }\n    return out;\n  });\n}\n"]}

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

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractHandler = void 0;
+exports.transformUrlStringsToNumericIds = transformUrlStringsToNumericIds;
+// lib/v3/handlers/extractHandler.ts
+const inference_js_1 = require("../../inference.js");
+const utils_js_1 = require("../../utils.js");
+const logger_js_1 = require("../logger.js");
+const methods_js_1 = require("../types/public/methods.js");
+const index_js_1 = require("../understudy/a11y/snapshot/index.js");
+const methods_js_2 = require("../types/public/methods.js");
+const sdkErrors_js_1 = require("../types/public/sdkErrors.js");
+const timeoutGuard_js_1 = require("./handlerUtils/timeoutGuard.js");
+/**
+ * Scans the provided Zod schema for any `z.string().url()` fields and
+ * replaces them with `z.number()`.
+ *
+ * @param schema - The Zod object schema to transform.
+ * @returns A tuple containing:
+ *   1. The transformed schema (or the original schema if no changes were needed).
+ *   2. An array of {@link ZodPathSegments} objects representing all the replaced URL fields,
+ *      with each path segment showing where in the schema the replacement occurred.
+ */
+function transformUrlStringsToNumericIds(schema) {
+    const [finalSchema, urlPaths] = (0, utils_js_1.transformSchema)(schema, []);
+    return [finalSchema, urlPaths];
+}
+class ExtractHandler {
+    llmClient;
+    defaultModelName;
+    defaultClientOptions;
+    resolveLlmClient;
+    systemPrompt;
+    logInferenceToFile;
+    experimental;
+    onMetrics;
+    constructor(llmClient, defaultModelName, defaultClientOptions, resolveLlmClient, systemPrompt, logInferenceToFile, experimental, onMetrics) {
+        this.llmClient = llmClient;
+        this.defaultModelName = defaultModelName;
+        this.defaultClientOptions = defaultClientOptions;
+        this.resolveLlmClient = resolveLlmClient;
+        this.systemPrompt = systemPrompt ?? "";
+        this.logInferenceToFile = logInferenceToFile ?? false;
+        this.experimental = experimental ?? false;
+        this.onMetrics = onMetrics;
+    }
+    async extract(params) {
+        const { instruction, schema, page, selector, timeout, model } = 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)
+        const noArgs = !instruction && !schema;
+        if (noArgs) {
+            const focusSelector = selector?.replace(/^xpath=/i, "") ?? "";
+            ensureTimeRemaining();
+            const snap = await (0, index_js_1.captureHybridSnapshot)(page, {
+                experimental: this.experimental,
+                focusSelector: focusSelector || undefined,
+            });
+            ensureTimeRemaining();
+            const result = { pageText: snap.combinedTree };
+            // Validate via the same schema used in v2
+            return methods_js_2.pageTextSchema.parse(result);
+        }
+        if (!instruction && schema) {
+            throw new sdkErrors_js_1.StagehandInvalidArgumentError("extract() requires an instruction when a schema is provided.");
+        }
+        const focusSelector = selector?.replace(/^xpath=/, "") ?? "";
+        // Build the hybrid snapshot (includes combinedTree; combinedUrlMap optional)
+        ensureTimeRemaining();
+        const { combinedTree, combinedUrlMap } = await (0, index_js_1.captureHybridSnapshot)(page, {
+            experimental: this.experimental,
+            focusSelector: focusSelector,
+        });
+        (0, logger_js_1.v3Logger)({
+            category: "extraction",
+            message: "Starting extraction using a11y snapshot",
+            level: 1,
+            auxiliary: instruction
+                ? { instruction: { value: instruction, type: "string" } }
+                : undefined,
+        });
+        // Normalize schema: if instruction provided without schema, use defaultExtractSchema
+        const baseSchema = (schema ??
+            methods_js_2.defaultExtractSchema);
+        // Ensure we pass an object schema into inference; wrap non-object schemas
+        const isObjectSchema = (0, utils_js_1.getZodType)(baseSchema) === "object";
+        const WRAP_KEY = "value";
+        const factory = (0, utils_js_1.getZFactory)(baseSchema);
+        const objectSchema = isObjectSchema
+            ? baseSchema
+            : factory.object({
+                [WRAP_KEY]: baseSchema,
+            });
+        const [transformedSchema, urlFieldPaths] = transformUrlStringsToNumericIds(objectSchema);
+        ensureTimeRemaining();
+        const extractionResponse = await (0, inference_js_1.extract)({
+            instruction,
+            domElements: combinedTree,
+            schema: transformedSchema,
+            llmClient,
+            userProvidedInstructions: this.systemPrompt,
+            logger: logger_js_1.v3Logger,
+            logInferenceToFile: this.logInferenceToFile,
+        });
+        const { metadata: { completed }, prompt_tokens, completion_tokens, reasoning_tokens = 0, cached_input_tokens = 0, inference_time_ms, ...rest } = extractionResponse;
+        let output = rest;
+        // Update EXTRACT metrics from the LLM calls
+        this.onMetrics?.(methods_js_1.V3FunctionName.EXTRACT, prompt_tokens, completion_tokens, reasoning_tokens, cached_input_tokens, inference_time_ms);
+        // Re-inject URLs for any url() fields we temporarily converted to number()
+        const idToUrl = (combinedUrlMap ?? {});
+        for (const { segments } of urlFieldPaths) {
+            (0, utils_js_1.injectUrls)(output, segments, idToUrl);
+        }
+        // If we wrapped a non-object schema, unwrap the value
+        if (!isObjectSchema && output && typeof output === "object") {
+            output = output[WRAP_KEY];
+        }
+        const resultPreviewLength = 200;
+        const resultString = JSON.stringify(output) ?? "undefined";
+        const resultPreview = resultString.length > resultPreviewLength
+            ? resultString.slice(0, resultPreviewLength) + "..."
+            : resultString;
+        (0, logger_js_1.v3Logger)({
+            category: "extraction",
+            message: completed
+                ? "Extraction completed successfully"
+                : "Extraction incomplete after processing all data",
+            level: 1,
+            auxiliary: {
+                prompt_tokens: { value: String(prompt_tokens), type: "string" },
+                completion_tokens: { value: String(completion_tokens), type: "string" },
+                inference_time_ms: {
+                    value: String(inference_time_ms),
+                    type: "string",
+                },
+                result: { value: resultPreview, type: "string" },
+            },
+        });
+        return output;
+    }
+}
+exports.ExtractHandler = ExtractHandler;
+//# sourceMappingURL=extractHandler.js.map

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

@@ -0,0 +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 { instruction, schema, page, selector, timeout, model } = 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      });\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    });\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"]}