@browserbasehq/orca 3.0.9-alpha-3 → 3.1.0-headers

package/dist/cjs/lib/v3/agent/tools/fillFormVision.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fillFormVisionTool = void 0;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const coordinateNormalization_js_1 = require("../utils/coordinateNormalization.js");
+const xpath_js_1 = require("../utils/xpath.js");
+const screenshotHandler_js_1 = require("../utils/screenshotHandler.js");
+const variables_js_1 = require("../utils/variables.js");
+const fillFormVisionTool = (v3, provider, variables) => {
+    const hasVariables = variables && Object.keys(variables).length > 0;
+    const valueDescription = hasVariables
+        ? `Text to type into the target field. Use %variableName% to substitute a variable value. Available: ${Object.keys(variables).join(", ")}`
+        : "Text to type into the target field";
+    return (0, ai_1.tool)({
+        description: `FORM FILL - SPECIALIZED MULTI-FIELD INPUT TOOL
+
+CRITICAL: Use this for ANY form with 2+ input fields (text inputs, textareas, etc.)
+IMPORTANT: Ensure the fields are visible within the current viewport
+
+WHY THIS TOOL EXISTS:
+- Forms are the #1 use case for multi-field input
+- Optimized specifically for input/textarea elements
+- 4-6x faster than individual typing actions
+
+Use fillFormVision: Pure form filling (inputs, textareas only)
+MANDATORY USE CASES (always use fillFormVision for these):
+- Registration forms: name, email, password fields
+- Contact forms: name, email, message fields
+- Checkout forms: address, payment info fields
+- Profile updates: multiple user data fields
+- Search filters: multiple criteria inputs`,
+        inputSchema: zod_1.z.object({
+            fields: zod_1.z
+                .array(zod_1.z.object({
+                action: zod_1.z
+                    .string()
+                    .describe("Description of the typing action, e.g. 'type foo into the bar field'"),
+                value: zod_1.z.string().describe(valueDescription),
+                coordinates: zod_1.z
+                    .object({
+                    x: zod_1.z.number(),
+                    y: zod_1.z.number(),
+                })
+                    .describe("Coordinates of the target field"),
+            }))
+                .min(2, "Provide at least two fields to fill"),
+        }),
+        execute: async ({ fields }) => {
+            try {
+                const page = await v3.context.awaitActivePage();
+                // Process coordinates and substitute variables for each field
+                // Keep original values (with %tokens%) for logging/caching, substituted values for typing
+                const processedFields = fields.map((field) => {
+                    const processed = (0, coordinateNormalization_js_1.processCoordinates)(field.coordinates.x, field.coordinates.y, provider, v3);
+                    return {
+                        ...field,
+                        originalValue: field.value, // Keep original with %tokens% for cache
+                        value: (0, variables_js_1.substituteVariables)(field.value, variables),
+                        coordinates: { x: processed.x, y: processed.y },
+                    };
+                });
+                v3.logger({
+                    category: "agent",
+                    message: `Agent calling tool: fillFormVision`,
+                    level: 1,
+                    auxiliary: {
+                        arguments: {
+                            value: JSON.stringify({ fields }), // Don't log substituted values
+                            type: "object",
+                        },
+                    },
+                });
+                // Only request XPath when caching is enabled to avoid unnecessary computation
+                const shouldCollectXpath = v3.isAgentReplayActive();
+                const actions = [];
+                for (const field of processedFields) {
+                    // Click the field, only requesting XPath when caching is enabled
+                    const xpath = await page.click(field.coordinates.x, field.coordinates.y, {
+                        returnXpath: shouldCollectXpath,
+                    });
+                    await page.type(field.value);
+                    // Build Action with XPath for deterministic replay (only when caching)
+                    // Use originalValue (with %tokens%) so cache stores references, not sensitive values
+                    if (shouldCollectXpath) {
+                        const normalizedXpath = (0, xpath_js_1.ensureXPath)(xpath);
+                        if (normalizedXpath) {
+                            actions.push({
+                                selector: normalizedXpath,
+                                description: field.action,
+                                method: "type",
+                                arguments: [field.originalValue],
+                            });
+                        }
+                    }
+                    // Small delay between fields
+                    await new Promise((resolve) => setTimeout(resolve, 100));
+                }
+                const screenshotBase64 = await (0, screenshotHandler_js_1.waitAndCaptureScreenshot)(page, 100);
+                // Record as "act" step with proper Actions for deterministic replay (only when caching)
+                if (shouldCollectXpath && actions.length > 0) {
+                    v3.recordAgentReplayStep({
+                        type: "act",
+                        instruction: `Fill ${fields.length} form fields`,
+                        actions,
+                        actionDescription: `Fill ${fields.length} form fields`,
+                    });
+                }
+                return {
+                    success: true,
+                    playwrightArguments: processedFields,
+                    screenshotBase64,
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: `Error filling form: ${error.message}`,
+                };
+            }
+        },
+        toModelOutput: (result) => {
+            if (result.success === false || result.error !== undefined) {
+                return {
+                    type: "content",
+                    value: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: result.success,
+                                error: result.error,
+                            }),
+                        },
+                    ],
+                };
+            }
+            const content = [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: result.success,
+                        fieldsCount: result.playwrightArguments?.length ?? 0,
+                    }),
+                },
+            ];
+            if (result.screenshotBase64) {
+                content.push({
+                    type: "media",
+                    mediaType: "image/png",
+                    data: result.screenshotBase64,
+                });
+            }
+            return { type: "content", value: content };
+        },
+    });
+};
+exports.fillFormVisionTool = fillFormVisionTool;
+//# sourceMappingURL=fillFormVision.js.map

package/dist/cjs/lib/v3/agent/tools/fillFormVision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fillFormVision.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/fillFormVision.ts"],"names":[],"mappings":"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","sourcesContent":["import { tool } from \"ai\";\nimport { z } from \"zod\";\nimport type { V3 } from \"../../v3.js\";\nimport type { Action } from \"../../types/public/methods.js\";\nimport type {\n  FillFormVisionToolResult,\n  ModelOutputContentItem,\n  Variables,\n} from \"../../types/public/agent.js\";\nimport { processCoordinates } from \"../utils/coordinateNormalization.js\";\nimport { ensureXPath } from \"../utils/xpath.js\";\nimport { waitAndCaptureScreenshot } from \"../utils/screenshotHandler.js\";\nimport { substituteVariables } from \"../utils/variables.js\";\n\nexport const fillFormVisionTool = (\n  v3: V3,\n  provider?: string,\n  variables?: Variables,\n) => {\n  const hasVariables = variables && Object.keys(variables).length > 0;\n  const valueDescription = hasVariables\n    ? `Text to type into the target field. Use %variableName% to substitute a variable value. Available: ${Object.keys(variables).join(\", \")}`\n    : \"Text to type into the target field\";\n\n  return tool({\n    description: `FORM FILL - SPECIALIZED MULTI-FIELD INPUT TOOL\n\nCRITICAL: Use this for ANY form with 2+ input fields (text inputs, textareas, etc.)\nIMPORTANT: Ensure the fields are visible within the current viewport\n\nWHY THIS TOOL EXISTS:\n- Forms are the #1 use case for multi-field input\n- Optimized specifically for input/textarea elements\n- 4-6x faster than individual typing actions\n\nUse fillFormVision: Pure form filling (inputs, textareas only)\nMANDATORY USE CASES (always use fillFormVision for these):\n- Registration forms: name, email, password fields\n- Contact forms: name, email, message fields\n- Checkout forms: address, payment info fields\n- Profile updates: multiple user data fields\n- Search filters: multiple criteria inputs`,\n    inputSchema: z.object({\n      fields: z\n        .array(\n          z.object({\n            action: z\n              .string()\n              .describe(\n                \"Description of the typing action, e.g. 'type foo into the bar field'\",\n              ),\n            value: z.string().describe(valueDescription),\n            coordinates: z\n              .object({\n                x: z.number(),\n                y: z.number(),\n              })\n              .describe(\"Coordinates of the target field\"),\n          }),\n        )\n        .min(2, \"Provide at least two fields to fill\"),\n    }),\n    execute: async ({ fields }): Promise<FillFormVisionToolResult> => {\n      try {\n        const page = await v3.context.awaitActivePage();\n\n        // Process coordinates and substitute variables for each field\n        // Keep original values (with %tokens%) for logging/caching, substituted values for typing\n        const processedFields = fields.map((field) => {\n          const processed = processCoordinates(\n            field.coordinates.x,\n            field.coordinates.y,\n            provider,\n            v3,\n          );\n          return {\n            ...field,\n            originalValue: field.value, // Keep original with %tokens% for cache\n            value: substituteVariables(field.value, variables),\n            coordinates: { x: processed.x, y: processed.y },\n          };\n        });\n\n        v3.logger({\n          category: \"agent\",\n          message: `Agent calling tool: fillFormVision`,\n          level: 1,\n          auxiliary: {\n            arguments: {\n              value: JSON.stringify({ fields }), // Don't log substituted values\n              type: \"object\",\n            },\n          },\n        });\n\n        // Only request XPath when caching is enabled to avoid unnecessary computation\n        const shouldCollectXpath = v3.isAgentReplayActive();\n        const actions: Action[] = [];\n\n        for (const field of processedFields) {\n          // Click the field, only requesting XPath when caching is enabled\n          const xpath = await page.click(\n            field.coordinates.x,\n            field.coordinates.y,\n            {\n              returnXpath: shouldCollectXpath,\n            },\n          );\n          await page.type(field.value);\n\n          // Build Action with XPath for deterministic replay (only when caching)\n          // Use originalValue (with %tokens%) so cache stores references, not sensitive values\n          if (shouldCollectXpath) {\n            const normalizedXpath = ensureXPath(xpath);\n            if (normalizedXpath) {\n              actions.push({\n                selector: normalizedXpath,\n                description: field.action,\n                method: \"type\",\n                arguments: [field.originalValue],\n              });\n            }\n          }\n\n          // Small delay between fields\n          await new Promise((resolve) => setTimeout(resolve, 100));\n        }\n\n        const screenshotBase64 = await waitAndCaptureScreenshot(page, 100);\n\n        // Record as \"act\" step with proper Actions for deterministic replay (only when caching)\n        if (shouldCollectXpath && actions.length > 0) {\n          v3.recordAgentReplayStep({\n            type: \"act\",\n            instruction: `Fill ${fields.length} form fields`,\n            actions,\n            actionDescription: `Fill ${fields.length} form fields`,\n          });\n        }\n\n        return {\n          success: true,\n          playwrightArguments: processedFields,\n          screenshotBase64,\n        };\n      } catch (error) {\n        return {\n          success: false,\n          error: `Error filling form: ${(error as Error).message}`,\n        };\n      }\n    },\n    toModelOutput: (result) => {\n      if (result.success === false || result.error !== undefined) {\n        return {\n          type: \"content\",\n          value: [\n            {\n              type: \"text\",\n              text: JSON.stringify({\n                success: result.success,\n                error: result.error,\n              }),\n            },\n          ],\n        };\n      }\n\n      const content: ModelOutputContentItem[] = [\n        {\n          type: \"text\",\n          text: JSON.stringify({\n            success: result.success,\n            fieldsCount: result.playwrightArguments?.length ?? 0,\n          }),\n        },\n      ];\n      if (result.screenshotBase64) {\n        content.push({\n          type: \"media\",\n          mediaType: \"image/png\",\n          data: result.screenshotBase64,\n        });\n      }\n      return { type: \"content\", value: content };\n    },\n  });\n};\n"]}

package/dist/cjs/lib/v3/agent/tools/fillform.d.ts

@@ -0,0 +1,19 @@
+import type { V3 } from "../../v3.js";
+import type { Action } from "../../types/public/methods.js";
+import type { AgentModelConfig, Variables } from "../../types/public/agent.js";
+export declare const fillFormTool: (v3: V3, executionModel?: string | AgentModelConfig, variables?: Variables, toolTimeout?: number) => import("ai").Tool<{
+    fields: {
+        action: string;
+        value: string;
+    }[];
+}, {
+    success: boolean;
+    actions: unknown[];
+    playwrightArguments: Action[];
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    actions?: undefined;
+    playwrightArguments?: undefined;
+}>;

package/dist/cjs/lib/v3/agent/tools/fillform.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fillFormTool = void 0;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const sdkErrors_js_1 = require("../../types/public/sdkErrors.js");
+const fillFormTool = (v3, executionModel, variables, toolTimeout) => {
+    const hasVariables = variables && Object.keys(variables).length > 0;
+    const valueDescription = hasVariables
+        ? `Text to type into the target. Use %variableName% to substitute a variable value. Available: ${Object.keys(variables).join(", ")}`
+        : "Text to type into the target";
+    return (0, ai_1.tool)({
+        description: `📝 FORM FILL - MULTI-FIELD INPUT TOOL\nFor any form with 2+ inputs/textareas. Faster than individual typing.`,
+        inputSchema: zod_1.z.object({
+            fields: zod_1.z
+                .array(zod_1.z.object({
+                action: zod_1.z
+                    .string()
+                    .describe('Description of typing action, e.g. "type foo into the email field"'),
+                value: zod_1.z.string().describe(valueDescription),
+            }))
+                .min(1, "Provide at least one field to fill"),
+        }),
+        execute: async ({ fields }) => {
+            try {
+                v3.logger({
+                    category: "agent",
+                    message: `Agent calling tool: fillForm`,
+                    level: 1,
+                    auxiliary: {
+                        arguments: {
+                            value: JSON.stringify(fields),
+                            type: "object",
+                        },
+                    },
+                });
+                const instruction = `Return observation results for the following actions: ${fields
+                    .map((f) => f.action)
+                    .join(", ")}`;
+                const observeOptions = executionModel
+                    ? { model: executionModel, timeout: toolTimeout }
+                    : { timeout: toolTimeout };
+                const observeResults = await v3.observe(instruction, observeOptions);
+                const completed = [];
+                const replayableActions = [];
+                for (const res of observeResults) {
+                    const actOptions = variables
+                        ? { variables, timeout: toolTimeout }
+                        : { timeout: toolTimeout };
+                    const actResult = await v3.act(res, actOptions);
+                    completed.push(actResult);
+                    if (Array.isArray(actResult.actions)) {
+                        replayableActions.push(...actResult.actions);
+                    }
+                }
+                v3.recordAgentReplayStep({
+                    type: "fillForm",
+                    fields,
+                    observeResults,
+                    actions: replayableActions,
+                });
+                return {
+                    success: true,
+                    actions: completed,
+                    playwrightArguments: replayableActions,
+                };
+            }
+            catch (error) {
+                if (error instanceof sdkErrors_js_1.TimeoutError) {
+                    const timeoutMessage = `TimeoutError while waiting for fillForm() to complete (it may continue executing in the background)`;
+                    v3.logger({
+                        category: "agent",
+                        message: timeoutMessage,
+                        level: 0,
+                    });
+                    return {
+                        success: false,
+                        error: `${timeoutMessage} — try filling fewer fields at once or use a different tool`,
+                    };
+                }
+                return {
+                    success: false,
+                    error: error?.message ?? String(error),
+                };
+            }
+        },
+    });
+};
+exports.fillFormTool = fillFormTool;
+//# sourceMappingURL=fillform.js.map

package/dist/cjs/lib/v3/agent/tools/fillform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fillform.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/fillform.ts"],"names":[],"mappings":"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","sourcesContent":["import { tool } from \"ai\";\nimport { z } from \"zod\";\nimport type { V3 } from \"../../v3.js\";\nimport type { Action } from \"../../types/public/methods.js\";\nimport type { AgentModelConfig, Variables } from \"../../types/public/agent.js\";\nimport { TimeoutError } from \"../../types/public/sdkErrors.js\";\n\nexport const fillFormTool = (\n  v3: V3,\n  executionModel?: string | AgentModelConfig,\n  variables?: Variables,\n  toolTimeout?: number,\n) => {\n  const hasVariables = variables && Object.keys(variables).length > 0;\n  const valueDescription = hasVariables\n    ? `Text to type into the target. Use %variableName% to substitute a variable value. Available: ${Object.keys(variables).join(\", \")}`\n    : \"Text to type into the target\";\n\n  return tool({\n    description: `📝 FORM FILL - MULTI-FIELD INPUT TOOL\\nFor any form with 2+ inputs/textareas. Faster than individual typing.`,\n    inputSchema: z.object({\n      fields: z\n        .array(\n          z.object({\n            action: z\n              .string()\n              .describe(\n                'Description of typing action, e.g. \"type foo into the email field\"',\n              ),\n            value: z.string().describe(valueDescription),\n          }),\n        )\n        .min(1, \"Provide at least one field to fill\"),\n    }),\n    execute: async ({ fields }) => {\n      try {\n        v3.logger({\n          category: \"agent\",\n          message: `Agent calling tool: fillForm`,\n          level: 1,\n          auxiliary: {\n            arguments: {\n              value: JSON.stringify(fields),\n              type: \"object\",\n            },\n          },\n        });\n        const instruction = `Return observation results for the following actions: ${fields\n          .map((f) => f.action)\n          .join(\", \")}`;\n\n        const observeOptions = executionModel\n          ? { model: executionModel, timeout: toolTimeout }\n          : { timeout: toolTimeout };\n        const observeResults = await v3.observe(instruction, observeOptions);\n\n        const completed = [] as unknown[];\n        const replayableActions: Action[] = [];\n        for (const res of observeResults) {\n          const actOptions = variables\n            ? { variables, timeout: toolTimeout }\n            : { timeout: toolTimeout };\n          const actResult = await v3.act(res, actOptions);\n          completed.push(actResult);\n          if (Array.isArray(actResult.actions)) {\n            replayableActions.push(...(actResult.actions as Action[]));\n          }\n        }\n        v3.recordAgentReplayStep({\n          type: \"fillForm\",\n          fields,\n          observeResults,\n          actions: replayableActions,\n        });\n        return {\n          success: true,\n          actions: completed,\n          playwrightArguments: replayableActions,\n        };\n      } catch (error) {\n        if (error instanceof TimeoutError) {\n          const timeoutMessage = `TimeoutError while waiting for fillForm() to complete (it may continue executing in the background)`;\n          v3.logger({\n            category: \"agent\",\n            message: timeoutMessage,\n            level: 0,\n          });\n          return {\n            success: false,\n            error: `${timeoutMessage} — try filling fewer fields at once or use a different tool`,\n          };\n        }\n        return {\n          success: false,\n          error: error?.message ?? String(error),\n        };\n      }\n    },\n  });\n};\n"]}

package/dist/cjs/lib/v3/agent/tools/goto.d.ts

@@ -0,0 +1,12 @@
+import type { V3 } from "../../v3.js";
+export declare const gotoTool: (v3: V3) => import("ai").Tool<{
+    url: string;
+}, {
+    success: boolean;
+    url: string;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: any;
+    url?: undefined;
+}>;

package/dist/cjs/lib/v3/agent/tools/goto.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gotoTool = void 0;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const gotoTool = (v3) => (0, ai_1.tool)({
+    description: "Navigate to a specific URL",
+    inputSchema: zod_1.z.object({
+        url: zod_1.z.string().describe("The URL to navigate to"),
+    }),
+    execute: async ({ url }) => {
+        try {
+            v3.logger({
+                category: "agent",
+                message: `Agent calling tool: goto`,
+                level: 1,
+                auxiliary: {
+                    arguments: {
+                        value: url,
+                        type: "string",
+                    },
+                },
+            });
+            const page = await v3.context.awaitActivePage();
+            await page.goto(url, { waitUntil: "load" });
+            v3.recordAgentReplayStep({ type: "goto", url, waitUntil: "load" });
+            return { success: true, url };
+        }
+        catch (error) {
+            return { success: false, error: error?.message ?? String(error) };
+        }
+    },
+});
+exports.gotoTool = gotoTool;
+//# sourceMappingURL=goto.js.map

package/dist/cjs/lib/v3/agent/tools/goto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"goto.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/goto.ts"],"names":[],"mappings":";;;AAAA,2BAA0B;AAC1B,6BAAwB;AAGjB,MAAM,QAAQ,GAAG,CAAC,EAAM,EAAE,EAAE,CACjC,IAAA,SAAI,EAAC;IACH,WAAW,EAAE,4BAA4B;IACzC,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC;QACpB,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;KACnD,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE;QACzB,IAAI,CAAC;YACH,EAAE,CAAC,MAAM,CAAC;gBACR,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,0BAA0B;gBACnC,KAAK,EAAE,CAAC;gBACR,SAAS,EAAE;oBACT,SAAS,EAAE;wBACT,KAAK,EAAE,GAAG;wBACV,IAAI,EAAE,QAAQ;qBACf;iBACF;aACF,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YAChD,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;YAC5C,EAAE,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;YACnE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAChC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QACpE,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AA3BQ,QAAA,QAAQ,YA2BhB","sourcesContent":["import { tool } from \"ai\";\nimport { z } from \"zod\";\nimport type { V3 } from \"../../v3.js\";\n\nexport const gotoTool = (v3: V3) =>\n  tool({\n    description: \"Navigate to a specific URL\",\n    inputSchema: z.object({\n      url: z.string().describe(\"The URL to navigate to\"),\n    }),\n    execute: async ({ url }) => {\n      try {\n        v3.logger({\n          category: \"agent\",\n          message: `Agent calling tool: goto`,\n          level: 1,\n          auxiliary: {\n            arguments: {\n              value: url,\n              type: \"string\",\n            },\n          },\n        });\n        const page = await v3.context.awaitActivePage();\n        await page.goto(url, { waitUntil: \"load\" });\n        v3.recordAgentReplayStep({ type: \"goto\", url, waitUntil: \"load\" });\n        return { success: true, url };\n      } catch (error) {\n        return { success: false, error: error?.message ?? String(error) };\n      }\n    },\n  });\n"]}

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

@@ -0,0 +1,102 @@
+import { gotoTool } from "./goto.js";
+import { actTool } from "./act.js";
+import { screenshotTool } from "./screenshot.js";
+import { waitTool } from "./wait.js";
+import { navBackTool } from "./navback.js";
+import { ariaTreeTool } from "./ariaTree.js";
+import { fillFormTool } from "./fillform.js";
+import { scrollTool, scrollVisionTool } from "./scroll.js";
+import { extractTool } from "./extract.js";
+import { clickTool } from "./click.js";
+import { typeTool } from "./type.js";
+import { dragAndDropTool } from "./dragAndDrop.js";
+import { clickAndHoldTool } from "./clickAndHold.js";
+import { keysTool } from "./keys.js";
+import { fillFormVisionTool } from "./fillFormVision.js";
+import { thinkTool } from "./think.js";
+import { searchTool } from "./search.js";
+import type { ToolSet, InferUITools } from "ai";
+import type { V3 } from "../../v3.js";
+import type { LogLine } from "../../types/public/logs.js";
+import type { AgentToolMode, AgentModelConfig, Variables } from "../../types/public/agent.js";
+export interface V3AgentToolOptions {
+    executionModel?: string | AgentModelConfig;
+    logger?: (message: LogLine) => void;
+    /**
+     * Tool mode determines which set of tools are available.
+     * - 'dom' (default): Uses DOM-based tools (act, fillForm) - removes coordinate-based tools
+     * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - removes fillForm
+     */
+    mode?: AgentToolMode;
+    /**
+     * The model provider. Used for model-specific coordinate handling
+     */
+    provider?: string;
+    /**
+     * Tools to exclude from the available toolset.
+     * These tools will be filtered out after mode-based filtering.
+     */
+    excludeTools?: string[];
+    /**
+     * Variables available to the agent for use in act/type tools.
+     * When provided, these tools will have an optional useVariable field.
+     */
+    variables?: Variables;
+    /**
+     * Timeout in milliseconds for tool calls that invoke v3 methods (act, extract, fillForm, ariaTree).
+     * Forwarded to the underlying v3 call's `timeout` option.
+     */
+    toolTimeout?: number;
+}
+export declare function createAgentTools(v3: V3, options?: V3AgentToolOptions): ToolSet;
+export type AgentTools = ReturnType<typeof createAgentTools>;
+/**
+ * Type map of all agent tools for strong typing of tool calls and results.
+ * Note: `search` is optional as it's only available when BRAVE_API_KEY is configured.
+ */
+export type AgentToolTypesMap = {
+    act: ReturnType<typeof actTool>;
+    ariaTree: ReturnType<typeof ariaTreeTool>;
+    click: ReturnType<typeof clickTool>;
+    clickAndHold: ReturnType<typeof clickAndHoldTool>;
+    dragAndDrop: ReturnType<typeof dragAndDropTool>;
+    extract: ReturnType<typeof extractTool>;
+    fillForm: ReturnType<typeof fillFormTool>;
+    fillFormVision: ReturnType<typeof fillFormVisionTool>;
+    goto: ReturnType<typeof gotoTool>;
+    keys: ReturnType<typeof keysTool>;
+    navback: ReturnType<typeof navBackTool>;
+    screenshot: ReturnType<typeof screenshotTool>;
+    scroll: ReturnType<typeof scrollTool> | ReturnType<typeof scrollVisionTool>;
+    search?: ReturnType<typeof searchTool>;
+    think: ReturnType<typeof thinkTool>;
+    type: ReturnType<typeof typeTool>;
+    wait: ReturnType<typeof waitTool>;
+};
+/**
+ * Inferred UI tools type for type-safe tool inputs and outputs.
+ * Use with UIMessage for full type safety in UI contexts.
+ */
+export type AgentUITools = InferUITools<AgentToolTypesMap>;
+/**
+ * Union type for all possible agent tool calls.
+ * Provides type-safe access to tool call arguments.
+ */
+export type AgentToolCall = {
+    [K in keyof AgentToolTypesMap]: {
+        toolName: K;
+        toolCallId: string;
+        args: AgentUITools[K]["input"];
+    };
+}[keyof AgentToolTypesMap];
+/**
+ * Union type for all possible agent tool results.
+ * Provides type-safe access to tool result values.
+ */
+export type AgentToolResult = {
+    [K in keyof AgentToolTypesMap]: {
+        toolName: K;
+        toolCallId: string;
+        result: AgentUITools[K]["output"];
+    };
+}[keyof AgentToolTypesMap];

package/dist/cjs/lib/v3/agent/tools/index.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentTools = createAgentTools;
+const goto_js_1 = require("./goto.js");
+const act_js_1 = require("./act.js");
+const screenshot_js_1 = require("./screenshot.js");
+const wait_js_1 = require("./wait.js");
+const navback_js_1 = require("./navback.js");
+const ariaTree_js_1 = require("./ariaTree.js");
+const fillform_js_1 = require("./fillform.js");
+const scroll_js_1 = require("./scroll.js");
+const extract_js_1 = require("./extract.js");
+const click_js_1 = require("./click.js");
+const type_js_1 = require("./type.js");
+const dragAndDrop_js_1 = require("./dragAndDrop.js");
+const clickAndHold_js_1 = require("./clickAndHold.js");
+const keys_js_1 = require("./keys.js");
+const fillFormVision_js_1 = require("./fillFormVision.js");
+const think_js_1 = require("./think.js");
+const search_js_1 = require("./search.js");
+/**
+ * Filters tools based on mode and explicit exclusions.
+ * - 'dom' mode: Removes coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)
+ * - 'hybrid' mode: Removes DOM-based form tool (fillForm) in favor of coordinate-based fillFormVision
+ * - excludeTools: Additional tools to remove from the toolset
+ */
+function filterTools(tools, mode, excludeTools) {
+    const filtered = { ...tools };
+    // Mode-based filtering
+    if (mode === "hybrid") {
+        delete filtered.fillForm;
+    }
+    else {
+        // DOM mode (default)
+        delete filtered.click;
+        delete filtered.type;
+        delete filtered.dragAndDrop;
+        delete filtered.clickAndHold;
+        delete filtered.fillFormVision;
+    }
+    if (excludeTools) {
+        for (const toolName of excludeTools) {
+            delete filtered[toolName];
+        }
+    }
+    return filtered;
+}
+function createAgentTools(v3, options) {
+    const executionModel = options?.executionModel;
+    const mode = options?.mode ?? "dom";
+    const provider = options?.provider;
+    const excludeTools = options?.excludeTools;
+    const variables = options?.variables;
+    const toolTimeout = options?.toolTimeout;
+    const allTools = {
+        act: (0, act_js_1.actTool)(v3, executionModel, variables, toolTimeout),
+        ariaTree: (0, ariaTree_js_1.ariaTreeTool)(v3, toolTimeout),
+        click: (0, click_js_1.clickTool)(v3, provider),
+        clickAndHold: (0, clickAndHold_js_1.clickAndHoldTool)(v3, provider),
+        dragAndDrop: (0, dragAndDrop_js_1.dragAndDropTool)(v3, provider),
+        extract: (0, extract_js_1.extractTool)(v3, executionModel, toolTimeout),
+        fillForm: (0, fillform_js_1.fillFormTool)(v3, executionModel, variables, toolTimeout),
+        fillFormVision: (0, fillFormVision_js_1.fillFormVisionTool)(v3, provider, variables),
+        goto: (0, goto_js_1.gotoTool)(v3),
+        keys: (0, keys_js_1.keysTool)(v3),
+        navback: (0, navback_js_1.navBackTool)(v3),
+        screenshot: (0, screenshot_js_1.screenshotTool)(v3),
+        scroll: mode === "hybrid" ? (0, scroll_js_1.scrollVisionTool)(v3, provider) : (0, scroll_js_1.scrollTool)(v3),
+        think: (0, think_js_1.thinkTool)(),
+        type: (0, type_js_1.typeTool)(v3, provider, variables),
+        wait: (0, wait_js_1.waitTool)(v3, mode),
+    };
+    if (process.env.BRAVE_API_KEY) {
+        allTools.search = (0, search_js_1.searchTool)(v3);
+    }
+    return filterTools(allTools, mode, excludeTools);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/tools/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { gotoTool } from \"./goto.js\";\nimport { actTool } from \"./act.js\";\nimport { screenshotTool } from \"./screenshot.js\";\nimport { waitTool } from \"./wait.js\";\nimport { navBackTool } from \"./navback.js\";\nimport { ariaTreeTool } from \"./ariaTree.js\";\nimport { fillFormTool } from \"./fillform.js\";\nimport { scrollTool, scrollVisionTool } from \"./scroll.js\";\nimport { extractTool } from \"./extract.js\";\nimport { clickTool } from \"./click.js\";\nimport { typeTool } from \"./type.js\";\nimport { dragAndDropTool } from \"./dragAndDrop.js\";\nimport { clickAndHoldTool } from \"./clickAndHold.js\";\nimport { keysTool } from \"./keys.js\";\nimport { fillFormVisionTool } from \"./fillFormVision.js\";\nimport { thinkTool } from \"./think.js\";\nimport { searchTool } from \"./search.js\";\n\nimport type { ToolSet, InferUITools } from \"ai\";\nimport type { V3 } from \"../../v3.js\";\nimport type { LogLine } from \"../../types/public/logs.js\";\nimport type {\n  AgentToolMode,\n  AgentModelConfig,\n  Variables,\n} from \"../../types/public/agent.js\";\n\nexport interface V3AgentToolOptions {\n  executionModel?: string | AgentModelConfig;\n  logger?: (message: LogLine) => void;\n  /**\n   * Tool mode determines which set of tools are available.\n   * - 'dom' (default): Uses DOM-based tools (act, fillForm) - removes coordinate-based tools\n   * - 'hybrid': Uses coordinate-based tools (click, type, dragAndDrop, etc.) - removes fillForm\n   */\n  mode?: AgentToolMode;\n  /**\n   * The model provider. Used for model-specific coordinate handling\n   */\n  provider?: string;\n  /**\n   * Tools to exclude from the available toolset.\n   * These tools will be filtered out after mode-based filtering.\n   */\n  excludeTools?: string[];\n  /**\n   * Variables available to the agent for use in act/type tools.\n   * When provided, these tools will have an optional useVariable field.\n   */\n  variables?: Variables;\n  /**\n   * Timeout in milliseconds for tool calls that invoke v3 methods (act, extract, fillForm, ariaTree).\n   * Forwarded to the underlying v3 call's `timeout` option.\n   */\n  toolTimeout?: number;\n}\n\n/**\n * Filters tools based on mode and explicit exclusions.\n * - 'dom' mode: Removes coordinate-based tools (click, type, dragAndDrop, clickAndHold, fillFormVision)\n * - 'hybrid' mode: Removes DOM-based form tool (fillForm) in favor of coordinate-based fillFormVision\n * - excludeTools: Additional tools to remove from the toolset\n */\nfunction filterTools(\n  tools: ToolSet,\n  mode: AgentToolMode,\n  excludeTools?: string[],\n): ToolSet {\n  const filtered: ToolSet = { ...tools };\n\n  // Mode-based filtering\n  if (mode === \"hybrid\") {\n    delete filtered.fillForm;\n  } else {\n    // DOM mode (default)\n    delete filtered.click;\n    delete filtered.type;\n    delete filtered.dragAndDrop;\n    delete filtered.clickAndHold;\n    delete filtered.fillFormVision;\n  }\n\n  if (excludeTools) {\n    for (const toolName of excludeTools) {\n      delete filtered[toolName];\n    }\n  }\n\n  return filtered;\n}\n\nexport function createAgentTools(v3: V3, options?: V3AgentToolOptions) {\n  const executionModel = options?.executionModel;\n  const mode = options?.mode ?? \"dom\";\n  const provider = options?.provider;\n  const excludeTools = options?.excludeTools;\n  const variables = options?.variables;\n  const toolTimeout = options?.toolTimeout;\n\n  const allTools: ToolSet = {\n    act: actTool(v3, executionModel, variables, toolTimeout),\n    ariaTree: ariaTreeTool(v3, toolTimeout),\n    click: clickTool(v3, provider),\n    clickAndHold: clickAndHoldTool(v3, provider),\n    dragAndDrop: dragAndDropTool(v3, provider),\n    extract: extractTool(v3, executionModel, toolTimeout),\n    fillForm: fillFormTool(v3, executionModel, variables, toolTimeout),\n    fillFormVision: fillFormVisionTool(v3, provider, variables),\n    goto: gotoTool(v3),\n    keys: keysTool(v3),\n    navback: navBackTool(v3),\n    screenshot: screenshotTool(v3),\n    scroll: mode === \"hybrid\" ? scrollVisionTool(v3, provider) : scrollTool(v3),\n    think: thinkTool(),\n    type: typeTool(v3, provider, variables),\n    wait: waitTool(v3, mode),\n  };\n\n  if (process.env.BRAVE_API_KEY) {\n    allTools.search = searchTool(v3);\n  }\n\n  return filterTools(allTools, mode, excludeTools);\n}\n\nexport type AgentTools = ReturnType<typeof createAgentTools>;\n\n/**\n * Type map of all agent tools for strong typing of tool calls and results.\n * Note: `search` is optional as it's only available when BRAVE_API_KEY is configured.\n */\nexport type AgentToolTypesMap = {\n  act: ReturnType<typeof actTool>;\n  ariaTree: ReturnType<typeof ariaTreeTool>;\n  click: ReturnType<typeof clickTool>;\n  clickAndHold: ReturnType<typeof clickAndHoldTool>;\n  dragAndDrop: ReturnType<typeof dragAndDropTool>;\n  extract: ReturnType<typeof extractTool>;\n  fillForm: ReturnType<typeof fillFormTool>;\n  fillFormVision: ReturnType<typeof fillFormVisionTool>;\n  goto: ReturnType<typeof gotoTool>;\n  keys: ReturnType<typeof keysTool>;\n  navback: ReturnType<typeof navBackTool>;\n  screenshot: ReturnType<typeof screenshotTool>;\n  scroll: ReturnType<typeof scrollTool> | ReturnType<typeof scrollVisionTool>;\n  search?: ReturnType<typeof searchTool>;\n  think: ReturnType<typeof thinkTool>;\n  type: ReturnType<typeof typeTool>;\n  wait: ReturnType<typeof waitTool>;\n};\n\n/**\n * Inferred UI tools type for type-safe tool inputs and outputs.\n * Use with UIMessage for full type safety in UI contexts.\n */\nexport type AgentUITools = InferUITools<AgentToolTypesMap>;\n\n/**\n * Union type for all possible agent tool calls.\n * Provides type-safe access to tool call arguments.\n */\nexport type AgentToolCall = {\n  [K in keyof AgentToolTypesMap]: {\n    toolName: K;\n    toolCallId: string;\n    args: AgentUITools[K][\"input\"];\n  };\n}[keyof AgentToolTypesMap];\n\n/**\n * Union type for all possible agent tool results.\n * Provides type-safe access to tool result values.\n */\nexport type AgentToolResult = {\n  [K in keyof AgentToolTypesMap]: {\n    toolName: K;\n    toolCallId: string;\n    result: AgentUITools[K][\"output\"];\n  };\n}[keyof AgentToolTypesMap];\n"]}

package/dist/cjs/lib/v3/agent/tools/keys.d.ts

@@ -0,0 +1,24 @@
+import type { V3 } from "../../v3.js";
+export declare const keysTool: (v3: V3) => import("ai").Tool<{
+    method: "type" | "press";
+    value: string;
+    repeat?: number;
+}, {
+    success: boolean;
+    method: "type";
+    value: string;
+    times: number;
+    error?: undefined;
+} | {
+    success: boolean;
+    method: "press";
+    value: string;
+    times: number;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string;
+    method?: undefined;
+    value?: undefined;
+    times?: undefined;
+}>;

package/dist/cjs/lib/v3/agent/tools/keys.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keysTool = void 0;
+const ai_1 = require("ai");
+const zod_1 = require("zod");
+const keysTool = (v3) => (0, ai_1.tool)({
+    description: `Send keyboard input to the page without targeting a specific element. Unlike the type tool which clicks then types into coordinates, this sends keystrokes directly to wherever focus currently is.
+
+Use method="type" to enter text into the currently focused element. Preferred when: input is already focused, text needs to flow across multiple fields (e.g., verification codes)
+
+Use method="press" for navigation keys (Enter, Tab, Escape, Backspace, arrows) and keyboard shortcuts (Cmd+A, Ctrl+C, Shift+Tab).`,
+    inputSchema: zod_1.z.object({
+        method: zod_1.z.enum(["press", "type"]),
+        value: zod_1.z
+            .string()
+            .describe("The text to type, or the key/combo to press (Enter, Tab, Cmd+A)"),
+        repeat: zod_1.z.number().optional(),
+    }),
+    execute: async ({ method, value, repeat }) => {
+        try {
+            const page = await v3.context.awaitActivePage();
+            v3.logger({
+                category: "agent",
+                message: `Agent calling tool: keys`,
+                level: 1,
+                auxiliary: {
+                    arguments: {
+                        value: JSON.stringify({ method, value, repeat }),
+                        type: "object",
+                    },
+                },
+            });
+            const times = Math.max(1, repeat ?? 1);
+            if (method === "type") {
+                for (let i = 0; i < times; i++) {
+                    await page.type(value, { delay: 100 });
+                }
+                v3.recordAgentReplayStep({
+                    type: "keys",
+                    instruction: `type "${value}"`,
+                    playwrightArguments: { method, text: value, times },
+                });
+                return { success: true, method, value, times };
+            }
+            if (method === "press") {
+                for (let i = 0; i < times; i++) {
+                    await page.keyPress(value, { delay: 100 });
+                }
+                v3.recordAgentReplayStep({
+                    type: "keys",
+                    instruction: `press ${value}`,
+                    playwrightArguments: { method, keys: value, times },
+                });
+                return { success: true, method, value, times };
+            }
+            return { success: false, error: `Unsupported method: ${method}` };
+        }
+        catch (error) {
+            return { success: false, error: error.message };
+        }
+    },
+});
+exports.keysTool = keysTool;
+//# sourceMappingURL=keys.js.map