illuma-agents 1.0.29 → 1.0.31

package/dist/cjs/tools/BrowserTools.cjs

@@ -111,26 +111,29 @@ const BrowserKeypressSchema = zod.z.object({
 /**
  * Format browser action result for LLM consumption
  */
-function formatResultForLLM(result, action) {
+function formatResultForLLM(result, action, actionArgs) {
     if (!result.success && result.error) {
-        return `Browser action "${action}" failed: ${result.error}`;
+        const errorType = result.errorType ? `[${result.errorType}] ` : '';
+        return `${errorType}Action "${action}" failed: ${result.error}`;
     }
     const parts = [];
-    if (result.url != null && result.url !== '') {
-        parts.push(`**Current URL:** ${result.url}`);
-    }
-    if (result.title != null && result.title !== '') {
-        parts.push(`**Page Title:** ${result.title}`);
-    }
-    if (result.elementList != null && result.elementList !== '') {
-        parts.push(`\n**Interactive Elements:**\n${result.elementList}`);
-    }
-    if (result.screenshot != null && result.screenshot !== '') {
-        parts.push('\n[Screenshot captured and displayed to user]');
-    }
-    if (parts.length === 0) {
-        return `Browser action "${action}" completed successfully.`;
+    // Verification result (Skyvern pattern)
+    if (result.verification) {
+        const v = result.verification;
+        if (v.dialogClosed || v.formGone || v.urlChanged) {
+            parts.push(`✓ ${v.changeDescription}`);
+        }
+        else if (!v.significantChange) {
+            parts.push(`⚠ No change detected`);
+        }
     }
+    // Page state
+    if (result.url)
+        parts.push(`URL: ${result.url}`);
+    if (result.title)
+        parts.push(`Title: ${result.title}`);
+    if (result.elementList)
+        parts.push(`\nElements:\n${result.elementList}`);
     return parts.join('\n');
 }
 /**
@@ -173,45 +176,65 @@ function createBrowserTools(options) {
             // The marker is still returned initially via SSE, but we wait for the callback
             try {
                 const result = await waitForResult(action, args, toolCallId);
-                return formatResultForLLM(result, action);
+                return formatResultForLLM(result, action, args);
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                return `Browser action "${action}" failed: ${errorMessage}`;
+                return `❌ **ACTION FAILED**: Browser action "${action}" failed: ${errorMessage}
+
+**REQUIRED**: Analyze why the action failed and try an alternative approach.`;
             }
         };
     };
-    // browser_click
+    // browser_click - PRIMARY action for buttons and links
     tools$1.push(tools.tool(createToolFunction('click'), {
         name: EBrowserTools.CLICK,
-        description: `Click an element on the current web page by its index number.
-The element list shows clickable items like: [0]<button>Submit</button> [1]<a href="/home">Home</a>
-Use the index number in brackets to click that element.
-After clicking, you receive an updated element list showing the new page state.`,
+        description: `Click an element by its [index] from the element list.
+
+**WHEN TO USE (prioritize this over keypress):**
+- Buttons labeled "Send", "Submit", "Save", "OK", "Confirm" → CLICK them
+- Links (a tags) to navigate
+- Checkboxes, radio buttons to select
+- Any clickable element that performs an action
+
+**SEMANTIC ELEMENT IDENTIFICATION:**
+- Look for aria-label="Send", aria-label="Submit" for action buttons
+- Look for type="submit" for form submission
+- Look for button text like "Send", "Submit", "Save"
+- For email compose: Find the Send button, DON'T use keyboard shortcuts
+
+Returns verification: dialog closed, form submitted, URL changed, or NO CHANGE (action may have failed).`,
         schema: BrowserClickSchema,
     }));
     // browser_type
     tools$1.push(tools.tool(createToolFunction('type'), {
         name: EBrowserTools.TYPE,
-        description: `Type text into an input element on the page.
-Find the input element in the list by its index (e.g., [5]<input placeholder="Search">).
-Set pressEnter: true to submit forms after typing.
-After typing, you receive an updated element list.`,
+        description: `Type text into an input/textarea element by [index].
+
+**WHEN TO USE:**
+- Input fields (fieldType="email", "search", "phone", etc.)
+- Textareas for longer content
+- Contenteditable divs (like Gmail compose body)
+
+**OPTIONS:**
+- pressEnter: true → Press Enter after typing (for search forms)
+- pressEnter: false → Just type without submitting
+
+**DO NOT use pressEnter to send emails** - find and CLICK the Send button instead.
+
+Returns verification showing if text was entered or form was submitted.`,
         schema: BrowserTypeSchema,
     }));
     // browser_navigate
     tools$1.push(tools.tool(createToolFunction('navigate'), {
         name: EBrowserTools.NAVIGATE,
-        description: `Navigate to a URL. Always include the full URL with https://.
-After navigation, you receive the new page's element list.`,
+        description: `Navigate to a URL (include https://). Returns new page's element list.`,
         schema: BrowserNavigateSchema,
     }));
     // browser_scroll
     tools$1.push(tools.tool(createToolFunction('scroll'), {
         name: EBrowserTools.SCROLL,
-        description: `Scroll the page to reveal more content.
-Use 'down' to scroll down, 'up' to scroll up.
-After scrolling, you receive an updated element list with newly visible elements.`,
+        description: `Scroll the page. Returns updated element list with newly visible elements.`,
         schema: BrowserScrollSchema,
     }));
     // browser_extract
@@ -246,27 +269,19 @@ After going back, you receive the previous page's element list.`,
     // browser_screenshot
     tools$1.push(tools.tool(createToolFunction('screenshot'), {
         name: EBrowserTools.SCREENSHOT,
-        description: `Capture a screenshot of the current page.
-Returns the page state with a note that screenshot was displayed to the user.
-Use browser_get_page_state to get the element list for automation.`,
+        description: `Capture a screenshot. Use browser_get_page_state for element list.`,
         schema: BrowserScreenshotSchema,
     }));
     // browser_get_page_state
     tools$1.push(tools.tool(createToolFunction('get_page_state'), {
         name: EBrowserTools.GET_PAGE_STATE,
-        description: `Get the current page state including URL, title, and all interactive elements.
-Use this at the start of a task to see what elements are available.
-Returns a text list of elements with their index numbers for interaction.`,
+        description: `Get current page URL, title, and interactive elements list with index numbers.`,
         schema: BrowserGetPageStateSchema,
     }));
-    // browser_select_option - Skyvern-inspired for robust dropdown handling
+    // browser_select_option
     tools$1.push(tools.tool(createToolFunction('select_option'), {
         name: EBrowserTools.SELECT_OPTION,
-        description: `Select an option from a dropdown or select element.
-For native <select> elements: finds and selects the option by value/label.
-For custom dropdowns: clicks to open, then clicks the matching option.
-Use this instead of click for dropdowns - it handles both native and custom selects.
-After selection, you receive an updated element list.`,
+        description: `Select an option from a dropdown. Handles both native <select> and custom dropdowns.`,
         schema: BrowserSelectOptionSchema,
     }));
     // browser_upload_file - Skyvern-inspired for file input handling
@@ -278,14 +293,26 @@ The system will download the file and attach it to the input.
 After upload, you receive an updated element list.`,
         schema: BrowserUploadFileSchema,
     }));
-    // browser_keypress - For keyboard shortcuts and special keys
+    // browser_keypress - LAST RESORT for keyboard shortcuts
     tools$1.push(tools.tool(createToolFunction('keypress'), {
         name: EBrowserTools.KEYPRESS,
-        description: `Press keyboard key(s) on the page.
-Single keys: "Enter", "Escape", "Tab", "ArrowDown", "ArrowUp", "Backspace", "Delete"
-Key combos: "Control+A" (select all), "Control+C" (copy), "Shift+Enter" (newline)
-Use this for form submission, closing modals, navigating dropdowns.
-After keypress, you receive an updated element list.`,
+        description: `Press keyboard key(s) - USE ONLY AS LAST RESORT after clicking fails.
+
+**PREFER browser_click OVER keypress:**
+- To send email → Find and CLICK the Send button
+- To submit form → CLICK the Submit button
+- To close modal → CLICK the X or Cancel button
+
+**WHEN TO USE keypress:**
+- Navigation: "Tab", "ArrowDown", "ArrowUp" in dropdowns
+- Escape to close popups if no X button exists
+- Control+A, Control+C for select/copy operations
+- ONLY use Enter to submit if there's NO visible submit button
+
+Single keys: "Enter", "Escape", "Tab", "ArrowDown"
+Key combos: "Control+A", "Shift+Enter"
+
+Returns verification showing if page state changed.`,
         schema: BrowserKeypressSchema,
     }));
     return tools$1;

package/dist/cjs/tools/BrowserTools.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"BrowserTools.cjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as _t from '@/types';\n\n/**\n * Browser tool names - keep in sync with ranger-browser extension\n * These tools execute locally in the browser extension, NOT on the server\n */\nexport const EBrowserTools = {\n  CLICK: 'browser_click',\n  TYPE: 'browser_type',\n  NAVIGATE: 'browser_navigate',\n  SCROLL: 'browser_scroll',\n  EXTRACT: 'browser_extract',\n  HOVER: 'browser_hover',\n  WAIT: 'browser_wait',\n  BACK: 'browser_back',\n  SCREENSHOT: 'browser_screenshot',\n  GET_PAGE_STATE: 'browser_get_page_state',\n  // Skyvern-inspired additions for robust form handling\n  SELECT_OPTION: 'browser_select_option',\n  UPLOAD_FILE: 'browser_upload_file',\n  KEYPRESS: 'browser_keypress',\n} as const;\n\nexport type BrowserToolName =\n  (typeof EBrowserTools)[keyof typeof EBrowserTools];\n\n/**\n * Callback function type for waiting on browser action results\n * This allows the server (Ranger) to provide a callback that waits for the extension\n * to POST results back to the server before returning to the LLM.\n *\n * @param action - The browser action (click, type, navigate, etc.)\n * @param args - Arguments for the action\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\n * @returns Promise that resolves with the actual browser result (page state, etc.)\n */\nexport type BrowserToolCallback = (\n  action: string,\n  args: Record<string, unknown>,\n  toolCallId: string\n) => Promise<BrowserActionResult>;\n\n/**\n * Result returned from browser action execution\n */\nexport interface BrowserActionResult {\n  success: boolean;\n  url?: string;\n  title?: string;\n  elementList?: string; // Text-based element list\n  error?: string;\n  screenshot?: string; // Base64 screenshot (if requested)\n}\n\n/**\n * Check if browser capability is available based on request headers or context\n * The browser extension sets these headers when connected:\n * - X-Ranger-Browser-Extension: true\n * - X-Ranger-Browser-Capable: true\n */\nexport function hasBrowserCapability(req?: {\n  headers?: Record<string, string | string[] | undefined>;\n}): boolean {\n  if (!req?.headers) {\n    return false;\n  }\n\n  const browserExtension = req.headers['x-ranger-browser-extension'];\n  const browserCapable = req.headers['x-ranger-browser-capable'];\n\n  return browserExtension === 'true' || browserCapable === 'true';\n}\n\n// Tool schemas\nconst BrowserClickSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The index number [0], [1], etc. of the element to click from the page state element list'\n    ),\n});\n\nconst BrowserTypeSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the input element to type into'),\n  text: z.string().describe('The text to type into the element'),\n  pressEnter: z\n    .boolean()\n    .optional()\n    .describe('Whether to press Enter after typing (useful for search forms)'),\n});\n\nconst BrowserNavigateSchema = z.object({\n  url: z\n    .string()\n    .describe('The full URL to navigate to (must include https://)'),\n});\n\nconst BrowserScrollSchema = z.object({\n  direction: z\n    .enum(['up', 'down', 'left', 'right'])\n    .describe('Direction to scroll'),\n  amount: z\n    .number()\n    .optional()\n    .describe('Pixels to scroll (default: one viewport height)'),\n});\n\nconst BrowserExtractSchema = z.object({\n  query: z\n    .string()\n    .optional()\n    .describe('Optional: specific content to extract from the page'),\n});\n\nconst BrowserHoverSchema = z.object({\n  index: z.number().describe('The index number of the element to hover over'),\n});\n\nconst BrowserWaitSchema = z.object({\n  duration: z\n    .number()\n    .optional()\n    .describe('Milliseconds to wait (default: 1000)'),\n});\n\nconst BrowserBackSchema = z.object({});\n\nconst BrowserScreenshotSchema = z.object({});\n\nconst BrowserGetPageStateSchema = z.object({});\n\n// Skyvern-inspired schemas for robust form handling\nconst BrowserSelectOptionSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the select/dropdown element'),\n  value: z\n    .string()\n    .optional()\n    .describe('The value or label of the option to select. For native <select>, use the option text. For custom dropdowns, this is the option label to click.'),\n});\n\nconst BrowserUploadFileSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the file input element'),\n  fileUrl: z\n    .string()\n    .describe('URL of the file to upload (the system will download and upload it)'),\n});\n\nconst BrowserKeypressSchema = z.object({\n  keys: z\n    .string()\n    .describe('Key(s) to press. Single key: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\". Combo: \"Control+A\", \"Shift+Enter\"'),\n});\n\n/**\n * Browser tool response interface\n * This is what the extension returns after executing the action\n */\nexport interface BrowserToolResponse {\n  requiresBrowserExecution: true;\n  action: string;\n  args: Record<string, unknown>;\n  toolCallId?: string; // Added to help extension correlate with callback\n}\n\n/**\n * Options for creating browser tools\n */\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Optional callback that waits for browser action results.\n   * When provided, tools will await this callback to get actual results from the extension.\n   * When not provided, tools return markers immediately (for non-server contexts).\n   */\n  waitForResult?: BrowserToolCallback;\n}\n\n/**\n * Format browser action result for LLM consumption\n */\nfunction formatResultForLLM(\n  result: BrowserActionResult,\n  action: string\n): string {\n  if (!result.success && result.error) {\n    return `Browser action \"${action}\" failed: ${result.error}`;\n  }\n\n  const parts: string[] = [];\n\n  if (result.url != null && result.url !== '') {\n    parts.push(`**Current URL:** ${result.url}`);\n  }\n  if (result.title != null && result.title !== '') {\n    parts.push(`**Page Title:** ${result.title}`);\n  }\n  if (result.elementList != null && result.elementList !== '') {\n    parts.push(`\\n**Interactive Elements:**\\n${result.elementList}`);\n  }\n  if (result.screenshot != null && result.screenshot !== '') {\n    parts.push('\\n[Screenshot captured and displayed to user]');\n  }\n\n  if (parts.length === 0) {\n    return `Browser action \"${action}\" completed successfully.`;\n  }\n\n  return parts.join('\\n');\n}\n\n/**\n * Create browser tools with optional callback for waiting on results\n *\n * When waitForResult callback is provided:\n * 1. Tool returns marker that triggers extension\n * 2. Tool then awaits callback to get actual results\n * 3. Returns real page state to LLM\n *\n * When no callback:\n * 1. Tool returns marker only (for non-server contexts)\n *\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\n */\nexport function createBrowserTools(\n  options?: CreateBrowserToolsOptions\n): DynamicStructuredTool[] {\n  const { waitForResult } = options || {};\n  const tools: DynamicStructuredTool[] = [];\n\n  /**\n   * Helper to create tool function that optionally waits for results\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\n   */\n  const createToolFunction = (action: string) => {\n    return async (\n      args: Record<string, unknown>,\n      config?: { toolCall?: { id?: string } }\n    ): Promise<string> => {\n      const toolCallId =\n        config?.toolCall?.id ??\n        `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n      // Create marker for extension\n      const marker: BrowserToolResponse = {\n        requiresBrowserExecution: true,\n        action,\n        args,\n        toolCallId,\n      };\n\n      // If no callback, return marker immediately (extension handles via SSE interception)\n      if (!waitForResult) {\n        return JSON.stringify(marker);\n      }\n\n      // With callback: wait for actual results from extension\n      // The marker is still returned initially via SSE, but we wait for the callback\n      try {\n        const result = await waitForResult(action, args, toolCallId);\n        return formatResultForLLM(result, action);\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return `Browser action \"${action}\" failed: ${errorMessage}`;\n      }\n    };\n  };\n\n  // browser_click\n  tools.push(\n    tool(createToolFunction('click'), {\n      name: EBrowserTools.CLICK,\n      description: `Click an element on the current web page by its index number.\nThe element list shows clickable items like: [0]<button>Submit</button> [1]<a href=\"/home\">Home</a>\nUse the index number in brackets to click that element.\nAfter clicking, you receive an updated element list showing the new page state.`,\n      schema: BrowserClickSchema,\n    })\n  );\n\n  // browser_type\n  tools.push(\n    tool(createToolFunction('type'), {\n      name: EBrowserTools.TYPE,\n      description: `Type text into an input element on the page.\nFind the input element in the list by its index (e.g., [5]<input placeholder=\"Search\">).\nSet pressEnter: true to submit forms after typing.\nAfter typing, you receive an updated element list.`,\n      schema: BrowserTypeSchema,\n    })\n  );\n\n  // browser_navigate\n  tools.push(\n    tool(createToolFunction('navigate'), {\n      name: EBrowserTools.NAVIGATE,\n      description: `Navigate to a URL. Always include the full URL with https://.\nAfter navigation, you receive the new page's element list.`,\n      schema: BrowserNavigateSchema,\n    })\n  );\n\n  // browser_scroll\n  tools.push(\n    tool(createToolFunction('scroll'), {\n      name: EBrowserTools.SCROLL,\n      description: `Scroll the page to reveal more content.\nUse 'down' to scroll down, 'up' to scroll up.\nAfter scrolling, you receive an updated element list with newly visible elements.`,\n      schema: BrowserScrollSchema,\n    })\n  );\n\n  // browser_extract\n  tools.push(\n    tool(createToolFunction('extract'), {\n      name: EBrowserTools.EXTRACT,\n      description: `Extract content from the current page.\nReturns page URL, title, and element list.`,\n      schema: BrowserExtractSchema,\n    })\n  );\n\n  // browser_hover\n  tools.push(\n    tool(createToolFunction('hover'), {\n      name: EBrowserTools.HOVER,\n      description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\n      schema: BrowserHoverSchema,\n    })\n  );\n\n  // browser_wait\n  tools.push(\n    tool(createToolFunction('wait'), {\n      name: EBrowserTools.WAIT,\n      description: `Wait for a specified duration for page content to load.\nUse this after actions that trigger async content loading.\nAfter waiting, you receive an updated element list.`,\n      schema: BrowserWaitSchema,\n    })\n  );\n\n  // browser_back\n  tools.push(\n    tool(createToolFunction('back'), {\n      name: EBrowserTools.BACK,\n      description: `Go back to the previous page in browser history.\nAfter going back, you receive the previous page's element list.`,\n      schema: BrowserBackSchema,\n    })\n  );\n\n  // browser_screenshot\n  tools.push(\n    tool(createToolFunction('screenshot'), {\n      name: EBrowserTools.SCREENSHOT,\n      description: `Capture a screenshot of the current page.\nReturns the page state with a note that screenshot was displayed to the user.\nUse browser_get_page_state to get the element list for automation.`,\n      schema: BrowserScreenshotSchema,\n    })\n  );\n\n  // browser_get_page_state\n  tools.push(\n    tool(createToolFunction('get_page_state'), {\n      name: EBrowserTools.GET_PAGE_STATE,\n      description: `Get the current page state including URL, title, and all interactive elements.\nUse this at the start of a task to see what elements are available.\nReturns a text list of elements with their index numbers for interaction.`,\n      schema: BrowserGetPageStateSchema,\n    })\n  );\n\n  // browser_select_option - Skyvern-inspired for robust dropdown handling\n  tools.push(\n    tool(createToolFunction('select_option'), {\n      name: EBrowserTools.SELECT_OPTION,\n      description: `Select an option from a dropdown or select element.\nFor native <select> elements: finds and selects the option by value/label.\nFor custom dropdowns: clicks to open, then clicks the matching option.\nUse this instead of click for dropdowns - it handles both native and custom selects.\nAfter selection, you receive an updated element list.`,\n      schema: BrowserSelectOptionSchema,\n    })\n  );\n\n  // browser_upload_file - Skyvern-inspired for file input handling\n  tools.push(\n    tool(createToolFunction('upload_file'), {\n      name: EBrowserTools.UPLOAD_FILE,\n      description: `Upload a file to a file input element.\nProvide the index of the file input and the URL of the file to upload.\nThe system will download the file and attach it to the input.\nAfter upload, you receive an updated element list.`,\n      schema: BrowserUploadFileSchema,\n    })\n  );\n\n  // browser_keypress - For keyboard shortcuts and special keys\n  tools.push(\n    tool(createToolFunction('keypress'), {\n      name: EBrowserTools.KEYPRESS,\n      description: `Press keyboard key(s) on the page.\nSingle keys: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\", \"ArrowUp\", \"Backspace\", \"Delete\"\nKey combos: \"Control+A\" (select all), \"Control+C\" (copy), \"Shift+Enter\" (newline)\nUse this for form submission, closing modals, navigating dropdowns.\nAfter keypress, you receive an updated element list.`,\n      schema: BrowserKeypressSchema,\n    })\n  );\n\n  return tools;\n}\n"],"names":["z","tools","tool"],"mappings":"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"}
+{"version":3,"file":"BrowserTools.cjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as _t from '@/types';\n\n/**\n * Browser tool names - keep in sync with ranger-browser extension\n * These tools execute locally in the browser extension, NOT on the server\n */\nexport const EBrowserTools = {\n  CLICK: 'browser_click',\n  TYPE: 'browser_type',\n  NAVIGATE: 'browser_navigate',\n  SCROLL: 'browser_scroll',\n  EXTRACT: 'browser_extract',\n  HOVER: 'browser_hover',\n  WAIT: 'browser_wait',\n  BACK: 'browser_back',\n  SCREENSHOT: 'browser_screenshot',\n  GET_PAGE_STATE: 'browser_get_page_state',\n  // Skyvern-inspired additions for robust form handling\n  SELECT_OPTION: 'browser_select_option',\n  UPLOAD_FILE: 'browser_upload_file',\n  KEYPRESS: 'browser_keypress',\n} as const;\n\nexport type BrowserToolName =\n  (typeof EBrowserTools)[keyof typeof EBrowserTools];\n\n/**\n * Callback function type for waiting on browser action results\n * This allows the server (Ranger) to provide a callback that waits for the extension\n * to POST results back to the server before returning to the LLM.\n *\n * @param action - The browser action (click, type, navigate, etc.)\n * @param args - Arguments for the action\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\n * @returns Promise that resolves with the actual browser result (page state, etc.)\n */\nexport type BrowserToolCallback = (\n  action: string,\n  args: Record<string, unknown>,\n  toolCallId: string\n) => Promise<BrowserActionResult>;\n\n/**\n * Action status - matches Skyvern's ActionStatus\n */\nexport type ActionStatus = 'pending' | 'completed' | 'failed' | 'skipped';\n\n/**\n * Verification status - matches Skyvern's VerificationStatus\n * - complete: Goal achieved\n * - terminate: Goal cannot be achieved, stop\n * - continue: Goal not yet achieved, keep going\n */\nexport type VerificationStatus = 'complete' | 'terminate' | 'continue';\n\n/**\n * Result returned from browser action execution\n */\nexport interface BrowserActionResult {\n  success: boolean;\n  status?: ActionStatus;\n  url?: string;\n  title?: string;\n  elementList?: string;\n  error?: string;\n  errorType?: string; // Typed error classification\n  screenshot?: string;\n  elementDescription?: string;\n  // State verification (before/after comparison)\n  verification?: {\n    urlChanged: boolean;\n    titleChanged: boolean;\n    elementCountDelta: number;\n    significantChange: boolean;\n    dialogClosed: boolean;\n    formGone: boolean;\n    changeDescription: string;\n  };\n}\n\n/**\n * Check if browser capability is available based on request headers or context\n * The browser extension sets these headers when connected:\n * - X-Ranger-Browser-Extension: true\n * - X-Ranger-Browser-Capable: true\n */\nexport function hasBrowserCapability(req?: {\n  headers?: Record<string, string | string[] | undefined>;\n}): boolean {\n  if (!req?.headers) {\n    return false;\n  }\n\n  const browserExtension = req.headers['x-ranger-browser-extension'];\n  const browserCapable = req.headers['x-ranger-browser-capable'];\n\n  return browserExtension === 'true' || browserCapable === 'true';\n}\n\n// Tool schemas\nconst BrowserClickSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The index number [0], [1], etc. of the element to click from the page state element list'\n    ),\n});\n\nconst BrowserTypeSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the input element to type into'),\n  text: z.string().describe('The text to type into the element'),\n  pressEnter: z\n    .boolean()\n    .optional()\n    .describe('Whether to press Enter after typing (useful for search forms)'),\n});\n\nconst BrowserNavigateSchema = z.object({\n  url: z\n    .string()\n    .describe('The full URL to navigate to (must include https://)'),\n});\n\nconst BrowserScrollSchema = z.object({\n  direction: z\n    .enum(['up', 'down', 'left', 'right'])\n    .describe('Direction to scroll'),\n  amount: z\n    .number()\n    .optional()\n    .describe('Pixels to scroll (default: one viewport height)'),\n});\n\nconst BrowserExtractSchema = z.object({\n  query: z\n    .string()\n    .optional()\n    .describe('Optional: specific content to extract from the page'),\n});\n\nconst BrowserHoverSchema = z.object({\n  index: z.number().describe('The index number of the element to hover over'),\n});\n\nconst BrowserWaitSchema = z.object({\n  duration: z\n    .number()\n    .optional()\n    .describe('Milliseconds to wait (default: 1000)'),\n});\n\nconst BrowserBackSchema = z.object({});\n\nconst BrowserScreenshotSchema = z.object({});\n\nconst BrowserGetPageStateSchema = z.object({});\n\n// Skyvern-inspired schemas for robust form handling\nconst BrowserSelectOptionSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the select/dropdown element'),\n  value: z\n    .string()\n    .optional()\n    .describe('The value or label of the option to select. For native <select>, use the option text. For custom dropdowns, this is the option label to click.'),\n});\n\nconst BrowserUploadFileSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the file input element'),\n  fileUrl: z\n    .string()\n    .describe('URL of the file to upload (the system will download and upload it)'),\n});\n\nconst BrowserKeypressSchema = z.object({\n  keys: z\n    .string()\n    .describe('Key(s) to press. Single key: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\". Combo: \"Control+A\", \"Shift+Enter\"'),\n});\n\n/**\n * Browser tool response interface\n * This is what the extension returns after executing the action\n */\nexport interface BrowserToolResponse {\n  requiresBrowserExecution: true;\n  action: string;\n  args: Record<string, unknown>;\n  toolCallId?: string; // Added to help extension correlate with callback\n}\n\n/**\n * Options for creating browser tools\n */\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Optional callback that waits for browser action results.\n   * When provided, tools will await this callback to get actual results from the extension.\n   * When not provided, tools return markers immediately (for non-server contexts).\n   */\n  waitForResult?: BrowserToolCallback;\n}\n\n/**\n * Format browser action result for LLM consumption\n */\nfunction formatResultForLLM(\n  result: BrowserActionResult,\n  action: string,\n  actionArgs?: Record<string, unknown>\n): string {\n  if (!result.success && result.error) {\n    const errorType = result.errorType ? `[${result.errorType}] ` : '';\n    return `${errorType}Action \"${action}\" failed: ${result.error}`;\n  }\n\n  const parts: string[] = [];\n\n  // Verification result (Skyvern pattern)\n  if (result.verification) {\n    const v = result.verification;\n    if (v.dialogClosed || v.formGone || v.urlChanged) {\n      parts.push(`✓ ${v.changeDescription}`);\n    } else if (!v.significantChange) {\n      parts.push(`⚠ No change detected`);\n    }\n  }\n\n  // Page state\n  if (result.url) parts.push(`URL: ${result.url}`);\n  if (result.title) parts.push(`Title: ${result.title}`);\n  if (result.elementList) parts.push(`\\nElements:\\n${result.elementList}`);\n\n  return parts.join('\\n');\n}\n\n/**\n * Create browser tools with optional callback for waiting on results\n *\n * When waitForResult callback is provided:\n * 1. Tool returns marker that triggers extension\n * 2. Tool then awaits callback to get actual results\n * 3. Returns real page state to LLM\n *\n * When no callback:\n * 1. Tool returns marker only (for non-server contexts)\n *\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\n */\nexport function createBrowserTools(\n  options?: CreateBrowserToolsOptions\n): DynamicStructuredTool[] {\n  const { waitForResult } = options || {};\n  const tools: DynamicStructuredTool[] = [];\n\n  /**\n   * Helper to create tool function that optionally waits for results\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\n   */\n  const createToolFunction = (action: string) => {\n    return async (\n      args: Record<string, unknown>,\n      config?: { toolCall?: { id?: string } }\n    ): Promise<string> => {\n      const toolCallId =\n        config?.toolCall?.id ??\n        `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n      // Create marker for extension\n      const marker: BrowserToolResponse = {\n        requiresBrowserExecution: true,\n        action,\n        args,\n        toolCallId,\n      };\n\n      // If no callback, return marker immediately (extension handles via SSE interception)\n      if (!waitForResult) {\n        return JSON.stringify(marker);\n      }\n\n      // With callback: wait for actual results from extension\n      // The marker is still returned initially via SSE, but we wait for the callback\n      try {\n        const result = await waitForResult(action, args, toolCallId);\n        return formatResultForLLM(result, action, args);\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return `❌ **ACTION FAILED**: Browser action \"${action}\" failed: ${errorMessage}\n\n**REQUIRED**: Analyze why the action failed and try an alternative approach.`;\n      }\n    };\n  };\n\n  // browser_click - PRIMARY action for buttons and links\n  tools.push(\n    tool(createToolFunction('click'), {\n      name: EBrowserTools.CLICK,\n      description: `Click an element by its [index] from the element list.\n\n**WHEN TO USE (prioritize this over keypress):**\n- Buttons labeled \"Send\", \"Submit\", \"Save\", \"OK\", \"Confirm\" → CLICK them\n- Links (a tags) to navigate\n- Checkboxes, radio buttons to select\n- Any clickable element that performs an action\n\n**SEMANTIC ELEMENT IDENTIFICATION:**\n- Look for aria-label=\"Send\", aria-label=\"Submit\" for action buttons\n- Look for type=\"submit\" for form submission\n- Look for button text like \"Send\", \"Submit\", \"Save\"\n- For email compose: Find the Send button, DON'T use keyboard shortcuts\n\nReturns verification: dialog closed, form submitted, URL changed, or NO CHANGE (action may have failed).`,\n      schema: BrowserClickSchema,\n    })\n  );\n\n  // browser_type\n  tools.push(\n    tool(createToolFunction('type'), {\n      name: EBrowserTools.TYPE,\n      description: `Type text into an input/textarea element by [index].\n\n**WHEN TO USE:**\n- Input fields (fieldType=\"email\", \"search\", \"phone\", etc.)\n- Textareas for longer content\n- Contenteditable divs (like Gmail compose body)\n\n**OPTIONS:**\n- pressEnter: true → Press Enter after typing (for search forms)\n- pressEnter: false → Just type without submitting\n\n**DO NOT use pressEnter to send emails** - find and CLICK the Send button instead.\n\nReturns verification showing if text was entered or form was submitted.`,\n      schema: BrowserTypeSchema,\n    })\n  );\n\n  // browser_navigate\n  tools.push(\n    tool(createToolFunction('navigate'), {\n      name: EBrowserTools.NAVIGATE,\n      description: `Navigate to a URL (include https://). Returns new page's element list.`,\n      schema: BrowserNavigateSchema,\n    })\n  );\n\n  // browser_scroll\n  tools.push(\n    tool(createToolFunction('scroll'), {\n      name: EBrowserTools.SCROLL,\n      description: `Scroll the page. Returns updated element list with newly visible elements.`,\n      schema: BrowserScrollSchema,\n    })\n  );\n\n  // browser_extract\n  tools.push(\n    tool(createToolFunction('extract'), {\n      name: EBrowserTools.EXTRACT,\n      description: `Extract content from the current page.\nReturns page URL, title, and element list.`,\n      schema: BrowserExtractSchema,\n    })\n  );\n\n  // browser_hover\n  tools.push(\n    tool(createToolFunction('hover'), {\n      name: EBrowserTools.HOVER,\n      description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\n      schema: BrowserHoverSchema,\n    })\n  );\n\n  // browser_wait\n  tools.push(\n    tool(createToolFunction('wait'), {\n      name: EBrowserTools.WAIT,\n      description: `Wait for a specified duration for page content to load.\nUse this after actions that trigger async content loading.\nAfter waiting, you receive an updated element list.`,\n      schema: BrowserWaitSchema,\n    })\n  );\n\n  // browser_back\n  tools.push(\n    tool(createToolFunction('back'), {\n      name: EBrowserTools.BACK,\n      description: `Go back to the previous page in browser history.\nAfter going back, you receive the previous page's element list.`,\n      schema: BrowserBackSchema,\n    })\n  );\n\n  // browser_screenshot\n  tools.push(\n    tool(createToolFunction('screenshot'), {\n      name: EBrowserTools.SCREENSHOT,\n      description: `Capture a screenshot. Use browser_get_page_state for element list.`,\n      schema: BrowserScreenshotSchema,\n    })\n  );\n\n  // browser_get_page_state\n  tools.push(\n    tool(createToolFunction('get_page_state'), {\n      name: EBrowserTools.GET_PAGE_STATE,\n      description: `Get current page URL, title, and interactive elements list with index numbers.`,\n      schema: BrowserGetPageStateSchema,\n    })\n  );\n\n  // browser_select_option\n  tools.push(\n    tool(createToolFunction('select_option'), {\n      name: EBrowserTools.SELECT_OPTION,\n      description: `Select an option from a dropdown. Handles both native <select> and custom dropdowns.`,\n      schema: BrowserSelectOptionSchema,\n    })\n  );\n\n  // browser_upload_file - Skyvern-inspired for file input handling\n  tools.push(\n    tool(createToolFunction('upload_file'), {\n      name: EBrowserTools.UPLOAD_FILE,\n      description: `Upload a file to a file input element.\nProvide the index of the file input and the URL of the file to upload.\nThe system will download the file and attach it to the input.\nAfter upload, you receive an updated element list.`,\n      schema: BrowserUploadFileSchema,\n    })\n  );\n\n  // browser_keypress - LAST RESORT for keyboard shortcuts\n  tools.push(\n    tool(createToolFunction('keypress'), {\n      name: EBrowserTools.KEYPRESS,\n      description: `Press keyboard key(s) - USE ONLY AS LAST RESORT after clicking fails.\n\n**PREFER browser_click OVER keypress:**\n- To send email → Find and CLICK the Send button\n- To submit form → CLICK the Submit button\n- To close modal → CLICK the X or Cancel button\n\n**WHEN TO USE keypress:**\n- Navigation: \"Tab\", \"ArrowDown\", \"ArrowUp\" in dropdowns\n- Escape to close popups if no X button exists\n- Control+A, Control+C for select/copy operations\n- ONLY use Enter to submit if there's NO visible submit button\n\nSingle keys: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\"\nKey combos: \"Control+A\", \"Shift+Enter\"\n\nReturns verification showing if page state changed.`,\n      schema: BrowserKeypressSchema,\n    })\n  );\n\n  return tools;\n}\n"],"names":["z","tools","tool"],"mappings":"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"}

package/dist/esm/tools/BrowserTools.mjs

@@ -109,26 +109,29 @@ const BrowserKeypressSchema = z.object({
 /**
  * Format browser action result for LLM consumption
  */
-function formatResultForLLM(result, action) {
+function formatResultForLLM(result, action, actionArgs) {
     if (!result.success && result.error) {
-        return `Browser action "${action}" failed: ${result.error}`;
+        const errorType = result.errorType ? `[${result.errorType}] ` : '';
+        return `${errorType}Action "${action}" failed: ${result.error}`;
     }
     const parts = [];
-    if (result.url != null && result.url !== '') {
-        parts.push(`**Current URL:** ${result.url}`);
-    }
-    if (result.title != null && result.title !== '') {
-        parts.push(`**Page Title:** ${result.title}`);
-    }
-    if (result.elementList != null && result.elementList !== '') {
-        parts.push(`\n**Interactive Elements:**\n${result.elementList}`);
-    }
-    if (result.screenshot != null && result.screenshot !== '') {
-        parts.push('\n[Screenshot captured and displayed to user]');
-    }
-    if (parts.length === 0) {
-        return `Browser action "${action}" completed successfully.`;
+    // Verification result (Skyvern pattern)
+    if (result.verification) {
+        const v = result.verification;
+        if (v.dialogClosed || v.formGone || v.urlChanged) {
+            parts.push(`✓ ${v.changeDescription}`);
+        }
+        else if (!v.significantChange) {
+            parts.push(`⚠ No change detected`);
+        }
     }
+    // Page state
+    if (result.url)
+        parts.push(`URL: ${result.url}`);
+    if (result.title)
+        parts.push(`Title: ${result.title}`);
+    if (result.elementList)
+        parts.push(`\nElements:\n${result.elementList}`);
     return parts.join('\n');
 }
 /**
@@ -171,45 +174,65 @@ function createBrowserTools(options) {
             // The marker is still returned initially via SSE, but we wait for the callback
             try {
                 const result = await waitForResult(action, args, toolCallId);
-                return formatResultForLLM(result, action);
+                return formatResultForLLM(result, action, args);
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                return `Browser action "${action}" failed: ${errorMessage}`;
+                return `❌ **ACTION FAILED**: Browser action "${action}" failed: ${errorMessage}
+
+**REQUIRED**: Analyze why the action failed and try an alternative approach.`;
             }
         };
     };
-    // browser_click
+    // browser_click - PRIMARY action for buttons and links
     tools.push(tool(createToolFunction('click'), {
         name: EBrowserTools.CLICK,
-        description: `Click an element on the current web page by its index number.
-The element list shows clickable items like: [0]<button>Submit</button> [1]<a href="/home">Home</a>
-Use the index number in brackets to click that element.
-After clicking, you receive an updated element list showing the new page state.`,
+        description: `Click an element by its [index] from the element list.
+
+**WHEN TO USE (prioritize this over keypress):**
+- Buttons labeled "Send", "Submit", "Save", "OK", "Confirm" → CLICK them
+- Links (a tags) to navigate
+- Checkboxes, radio buttons to select
+- Any clickable element that performs an action
+
+**SEMANTIC ELEMENT IDENTIFICATION:**
+- Look for aria-label="Send", aria-label="Submit" for action buttons
+- Look for type="submit" for form submission
+- Look for button text like "Send", "Submit", "Save"
+- For email compose: Find the Send button, DON'T use keyboard shortcuts
+
+Returns verification: dialog closed, form submitted, URL changed, or NO CHANGE (action may have failed).`,
         schema: BrowserClickSchema,
     }));
     // browser_type
     tools.push(tool(createToolFunction('type'), {
         name: EBrowserTools.TYPE,
-        description: `Type text into an input element on the page.
-Find the input element in the list by its index (e.g., [5]<input placeholder="Search">).
-Set pressEnter: true to submit forms after typing.
-After typing, you receive an updated element list.`,
+        description: `Type text into an input/textarea element by [index].
+
+**WHEN TO USE:**
+- Input fields (fieldType="email", "search", "phone", etc.)
+- Textareas for longer content
+- Contenteditable divs (like Gmail compose body)
+
+**OPTIONS:**
+- pressEnter: true → Press Enter after typing (for search forms)
+- pressEnter: false → Just type without submitting
+
+**DO NOT use pressEnter to send emails** - find and CLICK the Send button instead.
+
+Returns verification showing if text was entered or form was submitted.`,
         schema: BrowserTypeSchema,
     }));
     // browser_navigate
     tools.push(tool(createToolFunction('navigate'), {
         name: EBrowserTools.NAVIGATE,
-        description: `Navigate to a URL. Always include the full URL with https://.
-After navigation, you receive the new page's element list.`,
+        description: `Navigate to a URL (include https://). Returns new page's element list.`,
         schema: BrowserNavigateSchema,
     }));
     // browser_scroll
     tools.push(tool(createToolFunction('scroll'), {
         name: EBrowserTools.SCROLL,
-        description: `Scroll the page to reveal more content.
-Use 'down' to scroll down, 'up' to scroll up.
-After scrolling, you receive an updated element list with newly visible elements.`,
+        description: `Scroll the page. Returns updated element list with newly visible elements.`,
         schema: BrowserScrollSchema,
     }));
     // browser_extract
@@ -244,27 +267,19 @@ After going back, you receive the previous page's element list.`,
     // browser_screenshot
     tools.push(tool(createToolFunction('screenshot'), {
         name: EBrowserTools.SCREENSHOT,
-        description: `Capture a screenshot of the current page.
-Returns the page state with a note that screenshot was displayed to the user.
-Use browser_get_page_state to get the element list for automation.`,
+        description: `Capture a screenshot. Use browser_get_page_state for element list.`,
         schema: BrowserScreenshotSchema,
     }));
     // browser_get_page_state
     tools.push(tool(createToolFunction('get_page_state'), {
         name: EBrowserTools.GET_PAGE_STATE,
-        description: `Get the current page state including URL, title, and all interactive elements.
-Use this at the start of a task to see what elements are available.
-Returns a text list of elements with their index numbers for interaction.`,
+        description: `Get current page URL, title, and interactive elements list with index numbers.`,
         schema: BrowserGetPageStateSchema,
     }));
-    // browser_select_option - Skyvern-inspired for robust dropdown handling
+    // browser_select_option
     tools.push(tool(createToolFunction('select_option'), {
         name: EBrowserTools.SELECT_OPTION,
-        description: `Select an option from a dropdown or select element.
-For native <select> elements: finds and selects the option by value/label.
-For custom dropdowns: clicks to open, then clicks the matching option.
-Use this instead of click for dropdowns - it handles both native and custom selects.
-After selection, you receive an updated element list.`,
+        description: `Select an option from a dropdown. Handles both native <select> and custom dropdowns.`,
         schema: BrowserSelectOptionSchema,
     }));
     // browser_upload_file - Skyvern-inspired for file input handling
@@ -276,14 +291,26 @@ The system will download the file and attach it to the input.
 After upload, you receive an updated element list.`,
         schema: BrowserUploadFileSchema,
     }));
-    // browser_keypress - For keyboard shortcuts and special keys
+    // browser_keypress - LAST RESORT for keyboard shortcuts
     tools.push(tool(createToolFunction('keypress'), {
         name: EBrowserTools.KEYPRESS,
-        description: `Press keyboard key(s) on the page.
-Single keys: "Enter", "Escape", "Tab", "ArrowDown", "ArrowUp", "Backspace", "Delete"
-Key combos: "Control+A" (select all), "Control+C" (copy), "Shift+Enter" (newline)
-Use this for form submission, closing modals, navigating dropdowns.
-After keypress, you receive an updated element list.`,
+        description: `Press keyboard key(s) - USE ONLY AS LAST RESORT after clicking fails.
+
+**PREFER browser_click OVER keypress:**
+- To send email → Find and CLICK the Send button
+- To submit form → CLICK the Submit button
+- To close modal → CLICK the X or Cancel button
+
+**WHEN TO USE keypress:**
+- Navigation: "Tab", "ArrowDown", "ArrowUp" in dropdowns
+- Escape to close popups if no X button exists
+- Control+A, Control+C for select/copy operations
+- ONLY use Enter to submit if there's NO visible submit button
+
+Single keys: "Enter", "Escape", "Tab", "ArrowDown"
+Key combos: "Control+A", "Shift+Enter"
+
+Returns verification showing if page state changed.`,
         schema: BrowserKeypressSchema,
     }));
     return tools;

package/dist/esm/tools/BrowserTools.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"BrowserTools.mjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as _t from '@/types';\n\n/**\n * Browser tool names - keep in sync with ranger-browser extension\n * These tools execute locally in the browser extension, NOT on the server\n */\nexport const EBrowserTools = {\n  CLICK: 'browser_click',\n  TYPE: 'browser_type',\n  NAVIGATE: 'browser_navigate',\n  SCROLL: 'browser_scroll',\n  EXTRACT: 'browser_extract',\n  HOVER: 'browser_hover',\n  WAIT: 'browser_wait',\n  BACK: 'browser_back',\n  SCREENSHOT: 'browser_screenshot',\n  GET_PAGE_STATE: 'browser_get_page_state',\n  // Skyvern-inspired additions for robust form handling\n  SELECT_OPTION: 'browser_select_option',\n  UPLOAD_FILE: 'browser_upload_file',\n  KEYPRESS: 'browser_keypress',\n} as const;\n\nexport type BrowserToolName =\n  (typeof EBrowserTools)[keyof typeof EBrowserTools];\n\n/**\n * Callback function type for waiting on browser action results\n * This allows the server (Ranger) to provide a callback that waits for the extension\n * to POST results back to the server before returning to the LLM.\n *\n * @param action - The browser action (click, type, navigate, etc.)\n * @param args - Arguments for the action\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\n * @returns Promise that resolves with the actual browser result (page state, etc.)\n */\nexport type BrowserToolCallback = (\n  action: string,\n  args: Record<string, unknown>,\n  toolCallId: string\n) => Promise<BrowserActionResult>;\n\n/**\n * Result returned from browser action execution\n */\nexport interface BrowserActionResult {\n  success: boolean;\n  url?: string;\n  title?: string;\n  elementList?: string; // Text-based element list\n  error?: string;\n  screenshot?: string; // Base64 screenshot (if requested)\n}\n\n/**\n * Check if browser capability is available based on request headers or context\n * The browser extension sets these headers when connected:\n * - X-Ranger-Browser-Extension: true\n * - X-Ranger-Browser-Capable: true\n */\nexport function hasBrowserCapability(req?: {\n  headers?: Record<string, string | string[] | undefined>;\n}): boolean {\n  if (!req?.headers) {\n    return false;\n  }\n\n  const browserExtension = req.headers['x-ranger-browser-extension'];\n  const browserCapable = req.headers['x-ranger-browser-capable'];\n\n  return browserExtension === 'true' || browserCapable === 'true';\n}\n\n// Tool schemas\nconst BrowserClickSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The index number [0], [1], etc. of the element to click from the page state element list'\n    ),\n});\n\nconst BrowserTypeSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the input element to type into'),\n  text: z.string().describe('The text to type into the element'),\n  pressEnter: z\n    .boolean()\n    .optional()\n    .describe('Whether to press Enter after typing (useful for search forms)'),\n});\n\nconst BrowserNavigateSchema = z.object({\n  url: z\n    .string()\n    .describe('The full URL to navigate to (must include https://)'),\n});\n\nconst BrowserScrollSchema = z.object({\n  direction: z\n    .enum(['up', 'down', 'left', 'right'])\n    .describe('Direction to scroll'),\n  amount: z\n    .number()\n    .optional()\n    .describe('Pixels to scroll (default: one viewport height)'),\n});\n\nconst BrowserExtractSchema = z.object({\n  query: z\n    .string()\n    .optional()\n    .describe('Optional: specific content to extract from the page'),\n});\n\nconst BrowserHoverSchema = z.object({\n  index: z.number().describe('The index number of the element to hover over'),\n});\n\nconst BrowserWaitSchema = z.object({\n  duration: z\n    .number()\n    .optional()\n    .describe('Milliseconds to wait (default: 1000)'),\n});\n\nconst BrowserBackSchema = z.object({});\n\nconst BrowserScreenshotSchema = z.object({});\n\nconst BrowserGetPageStateSchema = z.object({});\n\n// Skyvern-inspired schemas for robust form handling\nconst BrowserSelectOptionSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the select/dropdown element'),\n  value: z\n    .string()\n    .optional()\n    .describe('The value or label of the option to select. For native <select>, use the option text. For custom dropdowns, this is the option label to click.'),\n});\n\nconst BrowserUploadFileSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the file input element'),\n  fileUrl: z\n    .string()\n    .describe('URL of the file to upload (the system will download and upload it)'),\n});\n\nconst BrowserKeypressSchema = z.object({\n  keys: z\n    .string()\n    .describe('Key(s) to press. Single key: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\". Combo: \"Control+A\", \"Shift+Enter\"'),\n});\n\n/**\n * Browser tool response interface\n * This is what the extension returns after executing the action\n */\nexport interface BrowserToolResponse {\n  requiresBrowserExecution: true;\n  action: string;\n  args: Record<string, unknown>;\n  toolCallId?: string; // Added to help extension correlate with callback\n}\n\n/**\n * Options for creating browser tools\n */\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Optional callback that waits for browser action results.\n   * When provided, tools will await this callback to get actual results from the extension.\n   * When not provided, tools return markers immediately (for non-server contexts).\n   */\n  waitForResult?: BrowserToolCallback;\n}\n\n/**\n * Format browser action result for LLM consumption\n */\nfunction formatResultForLLM(\n  result: BrowserActionResult,\n  action: string\n): string {\n  if (!result.success && result.error) {\n    return `Browser action \"${action}\" failed: ${result.error}`;\n  }\n\n  const parts: string[] = [];\n\n  if (result.url != null && result.url !== '') {\n    parts.push(`**Current URL:** ${result.url}`);\n  }\n  if (result.title != null && result.title !== '') {\n    parts.push(`**Page Title:** ${result.title}`);\n  }\n  if (result.elementList != null && result.elementList !== '') {\n    parts.push(`\\n**Interactive Elements:**\\n${result.elementList}`);\n  }\n  if (result.screenshot != null && result.screenshot !== '') {\n    parts.push('\\n[Screenshot captured and displayed to user]');\n  }\n\n  if (parts.length === 0) {\n    return `Browser action \"${action}\" completed successfully.`;\n  }\n\n  return parts.join('\\n');\n}\n\n/**\n * Create browser tools with optional callback for waiting on results\n *\n * When waitForResult callback is provided:\n * 1. Tool returns marker that triggers extension\n * 2. Tool then awaits callback to get actual results\n * 3. Returns real page state to LLM\n *\n * When no callback:\n * 1. Tool returns marker only (for non-server contexts)\n *\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\n */\nexport function createBrowserTools(\n  options?: CreateBrowserToolsOptions\n): DynamicStructuredTool[] {\n  const { waitForResult } = options || {};\n  const tools: DynamicStructuredTool[] = [];\n\n  /**\n   * Helper to create tool function that optionally waits for results\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\n   */\n  const createToolFunction = (action: string) => {\n    return async (\n      args: Record<string, unknown>,\n      config?: { toolCall?: { id?: string } }\n    ): Promise<string> => {\n      const toolCallId =\n        config?.toolCall?.id ??\n        `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n      // Create marker for extension\n      const marker: BrowserToolResponse = {\n        requiresBrowserExecution: true,\n        action,\n        args,\n        toolCallId,\n      };\n\n      // If no callback, return marker immediately (extension handles via SSE interception)\n      if (!waitForResult) {\n        return JSON.stringify(marker);\n      }\n\n      // With callback: wait for actual results from extension\n      // The marker is still returned initially via SSE, but we wait for the callback\n      try {\n        const result = await waitForResult(action, args, toolCallId);\n        return formatResultForLLM(result, action);\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return `Browser action \"${action}\" failed: ${errorMessage}`;\n      }\n    };\n  };\n\n  // browser_click\n  tools.push(\n    tool(createToolFunction('click'), {\n      name: EBrowserTools.CLICK,\n      description: `Click an element on the current web page by its index number.\nThe element list shows clickable items like: [0]<button>Submit</button> [1]<a href=\"/home\">Home</a>\nUse the index number in brackets to click that element.\nAfter clicking, you receive an updated element list showing the new page state.`,\n      schema: BrowserClickSchema,\n    })\n  );\n\n  // browser_type\n  tools.push(\n    tool(createToolFunction('type'), {\n      name: EBrowserTools.TYPE,\n      description: `Type text into an input element on the page.\nFind the input element in the list by its index (e.g., [5]<input placeholder=\"Search\">).\nSet pressEnter: true to submit forms after typing.\nAfter typing, you receive an updated element list.`,\n      schema: BrowserTypeSchema,\n    })\n  );\n\n  // browser_navigate\n  tools.push(\n    tool(createToolFunction('navigate'), {\n      name: EBrowserTools.NAVIGATE,\n      description: `Navigate to a URL. Always include the full URL with https://.\nAfter navigation, you receive the new page's element list.`,\n      schema: BrowserNavigateSchema,\n    })\n  );\n\n  // browser_scroll\n  tools.push(\n    tool(createToolFunction('scroll'), {\n      name: EBrowserTools.SCROLL,\n      description: `Scroll the page to reveal more content.\nUse 'down' to scroll down, 'up' to scroll up.\nAfter scrolling, you receive an updated element list with newly visible elements.`,\n      schema: BrowserScrollSchema,\n    })\n  );\n\n  // browser_extract\n  tools.push(\n    tool(createToolFunction('extract'), {\n      name: EBrowserTools.EXTRACT,\n      description: `Extract content from the current page.\nReturns page URL, title, and element list.`,\n      schema: BrowserExtractSchema,\n    })\n  );\n\n  // browser_hover\n  tools.push(\n    tool(createToolFunction('hover'), {\n      name: EBrowserTools.HOVER,\n      description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\n      schema: BrowserHoverSchema,\n    })\n  );\n\n  // browser_wait\n  tools.push(\n    tool(createToolFunction('wait'), {\n      name: EBrowserTools.WAIT,\n      description: `Wait for a specified duration for page content to load.\nUse this after actions that trigger async content loading.\nAfter waiting, you receive an updated element list.`,\n      schema: BrowserWaitSchema,\n    })\n  );\n\n  // browser_back\n  tools.push(\n    tool(createToolFunction('back'), {\n      name: EBrowserTools.BACK,\n      description: `Go back to the previous page in browser history.\nAfter going back, you receive the previous page's element list.`,\n      schema: BrowserBackSchema,\n    })\n  );\n\n  // browser_screenshot\n  tools.push(\n    tool(createToolFunction('screenshot'), {\n      name: EBrowserTools.SCREENSHOT,\n      description: `Capture a screenshot of the current page.\nReturns the page state with a note that screenshot was displayed to the user.\nUse browser_get_page_state to get the element list for automation.`,\n      schema: BrowserScreenshotSchema,\n    })\n  );\n\n  // browser_get_page_state\n  tools.push(\n    tool(createToolFunction('get_page_state'), {\n      name: EBrowserTools.GET_PAGE_STATE,\n      description: `Get the current page state including URL, title, and all interactive elements.\nUse this at the start of a task to see what elements are available.\nReturns a text list of elements with their index numbers for interaction.`,\n      schema: BrowserGetPageStateSchema,\n    })\n  );\n\n  // browser_select_option - Skyvern-inspired for robust dropdown handling\n  tools.push(\n    tool(createToolFunction('select_option'), {\n      name: EBrowserTools.SELECT_OPTION,\n      description: `Select an option from a dropdown or select element.\nFor native <select> elements: finds and selects the option by value/label.\nFor custom dropdowns: clicks to open, then clicks the matching option.\nUse this instead of click for dropdowns - it handles both native and custom selects.\nAfter selection, you receive an updated element list.`,\n      schema: BrowserSelectOptionSchema,\n    })\n  );\n\n  // browser_upload_file - Skyvern-inspired for file input handling\n  tools.push(\n    tool(createToolFunction('upload_file'), {\n      name: EBrowserTools.UPLOAD_FILE,\n      description: `Upload a file to a file input element.\nProvide the index of the file input and the URL of the file to upload.\nThe system will download the file and attach it to the input.\nAfter upload, you receive an updated element list.`,\n      schema: BrowserUploadFileSchema,\n    })\n  );\n\n  // browser_keypress - For keyboard shortcuts and special keys\n  tools.push(\n    tool(createToolFunction('keypress'), {\n      name: EBrowserTools.KEYPRESS,\n      description: `Press keyboard key(s) on the page.\nSingle keys: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\", \"ArrowUp\", \"Backspace\", \"Delete\"\nKey combos: \"Control+A\" (select all), \"Control+C\" (copy), \"Shift+Enter\" (newline)\nUse this for form submission, closing modals, navigating dropdowns.\nAfter keypress, you receive an updated element list.`,\n      schema: BrowserKeypressSchema,\n    })\n  );\n\n  return tools;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"BrowserTools.mjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport type * as _t from '@/types';\n\n/**\n * Browser tool names - keep in sync with ranger-browser extension\n * These tools execute locally in the browser extension, NOT on the server\n */\nexport const EBrowserTools = {\n  CLICK: 'browser_click',\n  TYPE: 'browser_type',\n  NAVIGATE: 'browser_navigate',\n  SCROLL: 'browser_scroll',\n  EXTRACT: 'browser_extract',\n  HOVER: 'browser_hover',\n  WAIT: 'browser_wait',\n  BACK: 'browser_back',\n  SCREENSHOT: 'browser_screenshot',\n  GET_PAGE_STATE: 'browser_get_page_state',\n  // Skyvern-inspired additions for robust form handling\n  SELECT_OPTION: 'browser_select_option',\n  UPLOAD_FILE: 'browser_upload_file',\n  KEYPRESS: 'browser_keypress',\n} as const;\n\nexport type BrowserToolName =\n  (typeof EBrowserTools)[keyof typeof EBrowserTools];\n\n/**\n * Callback function type for waiting on browser action results\n * This allows the server (Ranger) to provide a callback that waits for the extension\n * to POST results back to the server before returning to the LLM.\n *\n * @param action - The browser action (click, type, navigate, etc.)\n * @param args - Arguments for the action\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\n * @returns Promise that resolves with the actual browser result (page state, etc.)\n */\nexport type BrowserToolCallback = (\n  action: string,\n  args: Record<string, unknown>,\n  toolCallId: string\n) => Promise<BrowserActionResult>;\n\n/**\n * Action status - matches Skyvern's ActionStatus\n */\nexport type ActionStatus = 'pending' | 'completed' | 'failed' | 'skipped';\n\n/**\n * Verification status - matches Skyvern's VerificationStatus\n * - complete: Goal achieved\n * - terminate: Goal cannot be achieved, stop\n * - continue: Goal not yet achieved, keep going\n */\nexport type VerificationStatus = 'complete' | 'terminate' | 'continue';\n\n/**\n * Result returned from browser action execution\n */\nexport interface BrowserActionResult {\n  success: boolean;\n  status?: ActionStatus;\n  url?: string;\n  title?: string;\n  elementList?: string;\n  error?: string;\n  errorType?: string; // Typed error classification\n  screenshot?: string;\n  elementDescription?: string;\n  // State verification (before/after comparison)\n  verification?: {\n    urlChanged: boolean;\n    titleChanged: boolean;\n    elementCountDelta: number;\n    significantChange: boolean;\n    dialogClosed: boolean;\n    formGone: boolean;\n    changeDescription: string;\n  };\n}\n\n/**\n * Check if browser capability is available based on request headers or context\n * The browser extension sets these headers when connected:\n * - X-Ranger-Browser-Extension: true\n * - X-Ranger-Browser-Capable: true\n */\nexport function hasBrowserCapability(req?: {\n  headers?: Record<string, string | string[] | undefined>;\n}): boolean {\n  if (!req?.headers) {\n    return false;\n  }\n\n  const browserExtension = req.headers['x-ranger-browser-extension'];\n  const browserCapable = req.headers['x-ranger-browser-capable'];\n\n  return browserExtension === 'true' || browserCapable === 'true';\n}\n\n// Tool schemas\nconst BrowserClickSchema = z.object({\n  index: z\n    .number()\n    .describe(\n      'The index number [0], [1], etc. of the element to click from the page state element list'\n    ),\n});\n\nconst BrowserTypeSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the input element to type into'),\n  text: z.string().describe('The text to type into the element'),\n  pressEnter: z\n    .boolean()\n    .optional()\n    .describe('Whether to press Enter after typing (useful for search forms)'),\n});\n\nconst BrowserNavigateSchema = z.object({\n  url: z\n    .string()\n    .describe('The full URL to navigate to (must include https://)'),\n});\n\nconst BrowserScrollSchema = z.object({\n  direction: z\n    .enum(['up', 'down', 'left', 'right'])\n    .describe('Direction to scroll'),\n  amount: z\n    .number()\n    .optional()\n    .describe('Pixels to scroll (default: one viewport height)'),\n});\n\nconst BrowserExtractSchema = z.object({\n  query: z\n    .string()\n    .optional()\n    .describe('Optional: specific content to extract from the page'),\n});\n\nconst BrowserHoverSchema = z.object({\n  index: z.number().describe('The index number of the element to hover over'),\n});\n\nconst BrowserWaitSchema = z.object({\n  duration: z\n    .number()\n    .optional()\n    .describe('Milliseconds to wait (default: 1000)'),\n});\n\nconst BrowserBackSchema = z.object({});\n\nconst BrowserScreenshotSchema = z.object({});\n\nconst BrowserGetPageStateSchema = z.object({});\n\n// Skyvern-inspired schemas for robust form handling\nconst BrowserSelectOptionSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the select/dropdown element'),\n  value: z\n    .string()\n    .optional()\n    .describe('The value or label of the option to select. For native <select>, use the option text. For custom dropdowns, this is the option label to click.'),\n});\n\nconst BrowserUploadFileSchema = z.object({\n  index: z\n    .number()\n    .describe('The index number of the file input element'),\n  fileUrl: z\n    .string()\n    .describe('URL of the file to upload (the system will download and upload it)'),\n});\n\nconst BrowserKeypressSchema = z.object({\n  keys: z\n    .string()\n    .describe('Key(s) to press. Single key: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\". Combo: \"Control+A\", \"Shift+Enter\"'),\n});\n\n/**\n * Browser tool response interface\n * This is what the extension returns after executing the action\n */\nexport interface BrowserToolResponse {\n  requiresBrowserExecution: true;\n  action: string;\n  args: Record<string, unknown>;\n  toolCallId?: string; // Added to help extension correlate with callback\n}\n\n/**\n * Options for creating browser tools\n */\nexport interface CreateBrowserToolsOptions {\n  /**\n   * Optional callback that waits for browser action results.\n   * When provided, tools will await this callback to get actual results from the extension.\n   * When not provided, tools return markers immediately (for non-server contexts).\n   */\n  waitForResult?: BrowserToolCallback;\n}\n\n/**\n * Format browser action result for LLM consumption\n */\nfunction formatResultForLLM(\n  result: BrowserActionResult,\n  action: string,\n  actionArgs?: Record<string, unknown>\n): string {\n  if (!result.success && result.error) {\n    const errorType = result.errorType ? `[${result.errorType}] ` : '';\n    return `${errorType}Action \"${action}\" failed: ${result.error}`;\n  }\n\n  const parts: string[] = [];\n\n  // Verification result (Skyvern pattern)\n  if (result.verification) {\n    const v = result.verification;\n    if (v.dialogClosed || v.formGone || v.urlChanged) {\n      parts.push(`✓ ${v.changeDescription}`);\n    } else if (!v.significantChange) {\n      parts.push(`⚠ No change detected`);\n    }\n  }\n\n  // Page state\n  if (result.url) parts.push(`URL: ${result.url}`);\n  if (result.title) parts.push(`Title: ${result.title}`);\n  if (result.elementList) parts.push(`\\nElements:\\n${result.elementList}`);\n\n  return parts.join('\\n');\n}\n\n/**\n * Create browser tools with optional callback for waiting on results\n *\n * When waitForResult callback is provided:\n * 1. Tool returns marker that triggers extension\n * 2. Tool then awaits callback to get actual results\n * 3. Returns real page state to LLM\n *\n * When no callback:\n * 1. Tool returns marker only (for non-server contexts)\n *\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\n */\nexport function createBrowserTools(\n  options?: CreateBrowserToolsOptions\n): DynamicStructuredTool[] {\n  const { waitForResult } = options || {};\n  const tools: DynamicStructuredTool[] = [];\n\n  /**\n   * Helper to create tool function that optionally waits for results\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\n   */\n  const createToolFunction = (action: string) => {\n    return async (\n      args: Record<string, unknown>,\n      config?: { toolCall?: { id?: string } }\n    ): Promise<string> => {\n      const toolCallId =\n        config?.toolCall?.id ??\n        `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n      // Create marker for extension\n      const marker: BrowserToolResponse = {\n        requiresBrowserExecution: true,\n        action,\n        args,\n        toolCallId,\n      };\n\n      // If no callback, return marker immediately (extension handles via SSE interception)\n      if (!waitForResult) {\n        return JSON.stringify(marker);\n      }\n\n      // With callback: wait for actual results from extension\n      // The marker is still returned initially via SSE, but we wait for the callback\n      try {\n        const result = await waitForResult(action, args, toolCallId);\n        return formatResultForLLM(result, action, args);\n      } catch (error) {\n        const errorMessage =\n          error instanceof Error ? error.message : String(error);\n        return `❌ **ACTION FAILED**: Browser action \"${action}\" failed: ${errorMessage}\n\n**REQUIRED**: Analyze why the action failed and try an alternative approach.`;\n      }\n    };\n  };\n\n  // browser_click - PRIMARY action for buttons and links\n  tools.push(\n    tool(createToolFunction('click'), {\n      name: EBrowserTools.CLICK,\n      description: `Click an element by its [index] from the element list.\n\n**WHEN TO USE (prioritize this over keypress):**\n- Buttons labeled \"Send\", \"Submit\", \"Save\", \"OK\", \"Confirm\" → CLICK them\n- Links (a tags) to navigate\n- Checkboxes, radio buttons to select\n- Any clickable element that performs an action\n\n**SEMANTIC ELEMENT IDENTIFICATION:**\n- Look for aria-label=\"Send\", aria-label=\"Submit\" for action buttons\n- Look for type=\"submit\" for form submission\n- Look for button text like \"Send\", \"Submit\", \"Save\"\n- For email compose: Find the Send button, DON'T use keyboard shortcuts\n\nReturns verification: dialog closed, form submitted, URL changed, or NO CHANGE (action may have failed).`,\n      schema: BrowserClickSchema,\n    })\n  );\n\n  // browser_type\n  tools.push(\n    tool(createToolFunction('type'), {\n      name: EBrowserTools.TYPE,\n      description: `Type text into an input/textarea element by [index].\n\n**WHEN TO USE:**\n- Input fields (fieldType=\"email\", \"search\", \"phone\", etc.)\n- Textareas for longer content\n- Contenteditable divs (like Gmail compose body)\n\n**OPTIONS:**\n- pressEnter: true → Press Enter after typing (for search forms)\n- pressEnter: false → Just type without submitting\n\n**DO NOT use pressEnter to send emails** - find and CLICK the Send button instead.\n\nReturns verification showing if text was entered or form was submitted.`,\n      schema: BrowserTypeSchema,\n    })\n  );\n\n  // browser_navigate\n  tools.push(\n    tool(createToolFunction('navigate'), {\n      name: EBrowserTools.NAVIGATE,\n      description: `Navigate to a URL (include https://). Returns new page's element list.`,\n      schema: BrowserNavigateSchema,\n    })\n  );\n\n  // browser_scroll\n  tools.push(\n    tool(createToolFunction('scroll'), {\n      name: EBrowserTools.SCROLL,\n      description: `Scroll the page. Returns updated element list with newly visible elements.`,\n      schema: BrowserScrollSchema,\n    })\n  );\n\n  // browser_extract\n  tools.push(\n    tool(createToolFunction('extract'), {\n      name: EBrowserTools.EXTRACT,\n      description: `Extract content from the current page.\nReturns page URL, title, and element list.`,\n      schema: BrowserExtractSchema,\n    })\n  );\n\n  // browser_hover\n  tools.push(\n    tool(createToolFunction('hover'), {\n      name: EBrowserTools.HOVER,\n      description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\n      schema: BrowserHoverSchema,\n    })\n  );\n\n  // browser_wait\n  tools.push(\n    tool(createToolFunction('wait'), {\n      name: EBrowserTools.WAIT,\n      description: `Wait for a specified duration for page content to load.\nUse this after actions that trigger async content loading.\nAfter waiting, you receive an updated element list.`,\n      schema: BrowserWaitSchema,\n    })\n  );\n\n  // browser_back\n  tools.push(\n    tool(createToolFunction('back'), {\n      name: EBrowserTools.BACK,\n      description: `Go back to the previous page in browser history.\nAfter going back, you receive the previous page's element list.`,\n      schema: BrowserBackSchema,\n    })\n  );\n\n  // browser_screenshot\n  tools.push(\n    tool(createToolFunction('screenshot'), {\n      name: EBrowserTools.SCREENSHOT,\n      description: `Capture a screenshot. Use browser_get_page_state for element list.`,\n      schema: BrowserScreenshotSchema,\n    })\n  );\n\n  // browser_get_page_state\n  tools.push(\n    tool(createToolFunction('get_page_state'), {\n      name: EBrowserTools.GET_PAGE_STATE,\n      description: `Get current page URL, title, and interactive elements list with index numbers.`,\n      schema: BrowserGetPageStateSchema,\n    })\n  );\n\n  // browser_select_option\n  tools.push(\n    tool(createToolFunction('select_option'), {\n      name: EBrowserTools.SELECT_OPTION,\n      description: `Select an option from a dropdown. Handles both native <select> and custom dropdowns.`,\n      schema: BrowserSelectOptionSchema,\n    })\n  );\n\n  // browser_upload_file - Skyvern-inspired for file input handling\n  tools.push(\n    tool(createToolFunction('upload_file'), {\n      name: EBrowserTools.UPLOAD_FILE,\n      description: `Upload a file to a file input element.\nProvide the index of the file input and the URL of the file to upload.\nThe system will download the file and attach it to the input.\nAfter upload, you receive an updated element list.`,\n      schema: BrowserUploadFileSchema,\n    })\n  );\n\n  // browser_keypress - LAST RESORT for keyboard shortcuts\n  tools.push(\n    tool(createToolFunction('keypress'), {\n      name: EBrowserTools.KEYPRESS,\n      description: `Press keyboard key(s) - USE ONLY AS LAST RESORT after clicking fails.\n\n**PREFER browser_click OVER keypress:**\n- To send email → Find and CLICK the Send button\n- To submit form → CLICK the Submit button\n- To close modal → CLICK the X or Cancel button\n\n**WHEN TO USE keypress:**\n- Navigation: \"Tab\", \"ArrowDown\", \"ArrowUp\" in dropdowns\n- Escape to close popups if no X button exists\n- Control+A, Control+C for select/copy operations\n- ONLY use Enter to submit if there's NO visible submit button\n\nSingle keys: \"Enter\", \"Escape\", \"Tab\", \"ArrowDown\"\nKey combos: \"Control+A\", \"Shift+Enter\"\n\nReturns verification showing if page state changed.`,\n      schema: BrowserKeypressSchema,\n    })\n  );\n\n  return tools;\n}\n"],"names":[],"mappings":";;;AAIA;;;AAGG;AACU,MAAA,aAAa,GAAG;AAC3B,IAAA,KAAK,EAAE,eAAe;AACtB,IAAA,IAAI,EAAE,cAAc;AACpB,IAAA,QAAQ,EAAE,kBAAkB;AAC5B,IAAA,MAAM,EAAE,gBAAgB;AACxB,IAAA,OAAO,EAAE,iBAAiB;AAC1B,IAAA,KAAK,EAAE,eAAe;AACtB,IAAA,IAAI,EAAE,cAAc;AACpB,IAAA,IAAI,EAAE,cAAc;AACpB,IAAA,UAAU,EAAE,oBAAoB;AAChC,IAAA,cAAc,EAAE,wBAAwB;;AAExC,IAAA,aAAa,EAAE,uBAAuB;AACtC,IAAA,WAAW,EAAE,qBAAqB;AAClC,IAAA,QAAQ,EAAE,kBAAkB;;AA4D9B;;;;;AAKG;AACG,SAAU,oBAAoB,CAAC,GAEpC,EAAA;AACC,IAAA,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE;AACjB,QAAA,OAAO,KAAK;;IAGd,MAAM,gBAAgB,GAAG,GAAG,CAAC,OAAO,CAAC,4BAA4B,CAAC;IAClE,MAAM,cAAc,GAAG,GAAG,CAAC,OAAO,CAAC,0BAA0B,CAAC;AAE9D,IAAA,OAAO,gBAAgB,KAAK,MAAM,IAAI,cAAc,KAAK,MAAM;AACjE;AAEA;AACA,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;AAClC,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;SACN,QAAQ,CACP,0FAA0F,CAC3F;AACJ,CAAA,CAAC;AAEF,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;AACjC,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;SACN,QAAQ,CAAC,oDAAoD,CAAC;IACjE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;AAC9D,IAAA,UAAU,EAAE;AACT,SAAA,OAAO;AACP,SAAA,QAAQ;SACR,QAAQ,CAAC,+DAA+D,CAAC;AAC7E,CAAA,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;AACrC,IAAA,GAAG,EAAE;AACF,SAAA,MAAM;SACN,QAAQ,CAAC,qDAAqD,CAAC;AACnE,CAAA,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;AACnC,IAAA,SAAS,EAAE;SACR,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;SACpC,QAAQ,CAAC,qBAAqB,CAAC;AAClC,IAAA,MAAM,EAAE;AACL,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,iDAAiD,CAAC;AAC/D,CAAA,CAAC;AAEF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;AACpC,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,qDAAqD,CAAC;AACnE,CAAA,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;AAC5E,CAAA,CAAC;AAEF,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;AACjC,IAAA,QAAQ,EAAE;AACP,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,sCAAsC,CAAC;AACpD,CAAA,CAAC;AAEF,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;AAEtC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;AAE5C,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;AAE9C;AACA,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;AACzC,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;SACN,QAAQ,CAAC,iDAAiD,CAAC;AAC9D,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,gJAAgJ,CAAC;AAC9J,CAAA,CAAC;AAEF,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;AACvC,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;SACN,QAAQ,CAAC,4CAA4C,CAAC;AACzD,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;SACN,QAAQ,CAAC,oEAAoE,CAAC;AAClF,CAAA,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;AACrC,IAAA,IAAI,EAAE;AACH,SAAA,MAAM;SACN,QAAQ,CAAC,uGAAuG,CAAC;AACrH,CAAA,CAAC;AAyBF;;AAEG;AACH,SAAS,kBAAkB,CACzB,MAA2B,EAC3B,MAAc,EACd,UAAoC,EAAA;IAEpC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,EAAE;AACnC,QAAA,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,GAAG,CAAI,CAAA,EAAA,MAAM,CAAC,SAAS,CAAA,EAAA,CAAI,GAAG,EAAE;QAClE,OAAO,CAAA,EAAG,SAAS,CAAW,QAAA,EAAA,MAAM,aAAa,MAAM,CAAC,KAAK,CAAA,CAAE;;IAGjE,MAAM,KAAK,GAAa,EAAE;;AAG1B,IAAA,IAAI,MAAM,CAAC,YAAY,EAAE;AACvB,QAAA,MAAM,CAAC,GAAG,MAAM,CAAC,YAAY;AAC7B,QAAA,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,UAAU,EAAE;YAChD,KAAK,CAAC,IAAI,CAAC,CAAA,EAAA,EAAK,CAAC,CAAC,iBAAiB,CAAE,CAAA,CAAC;;AACjC,aAAA,IAAI,CAAC,CAAC,CAAC,iBAAiB,EAAE;AAC/B,YAAA,KAAK,CAAC,IAAI,CAAC,CAAA,oBAAA,CAAsB,CAAC;;;;IAKtC,IAAI,MAAM,CAAC,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,CAAA,KAAA,EAAQ,MAAM,CAAC,GAAG,CAAE,CAAA,CAAC;IAChD,IAAI,MAAM,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,CAAA,OAAA,EAAU,MAAM,CAAC,KAAK,CAAE,CAAA,CAAC;IACtD,IAAI,MAAM,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,CAAA,aAAA,EAAgB,MAAM,CAAC,WAAW,CAAE,CAAA,CAAC;AAExE,IAAA,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;AACzB;AAEA;;;;;;;;;;;;;AAaG;AACG,SAAU,kBAAkB,CAChC,OAAmC,EAAA;AAEnC,IAAA,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,IAAI,EAAE;IACvC,MAAM,KAAK,GAA4B,EAAE;AAEzC;;;AAGG;AACH,IAAA,MAAM,kBAAkB,GAAG,CAAC,MAAc,KAAI;AAC5C,QAAA,OAAO,OACL,IAA6B,EAC7B,MAAuC,KACpB;AACnB,YAAA,MAAM,UAAU,GACd,MAAM,EAAE,QAAQ,EAAE,EAAE;gBACpB,CAAQ,KAAA,EAAA,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;;AAG7D,YAAA,MAAM,MAAM,GAAwB;AAClC,gBAAA,wBAAwB,EAAE,IAAI;gBAC9B,MAAM;gBACN,IAAI;gBACJ,UAAU;aACX;;YAGD,IAAI,CAAC,aAAa,EAAE;AAClB,gBAAA,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;;;;AAK/B,YAAA,IAAI;gBACF,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,CAAC;gBAC5D,OAAO,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC;;YAC/C,OAAO,KAAK,EAAE;AACd,gBAAA,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC;gBACxD,OAAO,CAAA,qCAAA,EAAwC,MAAM,CAAA,UAAA,EAAa,YAAY;;6EAET;;AAEzE,SAAC;AACH,KAAC;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAChC,IAAI,EAAE,aAAa,CAAC,KAAK;AACzB,QAAA,WAAW,EAAE,CAAA;;;;;;;;;;;;;;AAcsF,wGAAA,CAAA;AACnG,QAAA,MAAM,EAAE,kBAAkB;AAC3B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE;QAC/B,IAAI,EAAE,aAAa,CAAC,IAAI;AACxB,QAAA,WAAW,EAAE,CAAA;;;;;;;;;;;;;AAaqD,uEAAA,CAAA;AAClE,QAAA,MAAM,EAAE,iBAAiB;AAC1B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE;QACnC,IAAI,EAAE,aAAa,CAAC,QAAQ;AAC5B,QAAA,WAAW,EAAE,CAAwE,sEAAA,CAAA;AACrF,QAAA,MAAM,EAAE,qBAAqB;AAC9B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE;QACjC,IAAI,EAAE,aAAa,CAAC,MAAM;AAC1B,QAAA,WAAW,EAAE,CAA4E,0EAAA,CAAA;AACzF,QAAA,MAAM,EAAE,mBAAmB;AAC5B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,EAAE;QAClC,IAAI,EAAE,aAAa,CAAC,OAAO;AAC3B,QAAA,WAAW,EAAE,CAAA;AACwB,0CAAA,CAAA;AACrC,QAAA,MAAM,EAAE,oBAAoB;AAC7B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE;QAChC,IAAI,EAAE,aAAa,CAAC,KAAK;AACzB,QAAA,WAAW,EAAE,CAAA;AACmE,qFAAA,CAAA;AAChF,QAAA,MAAM,EAAE,kBAAkB;AAC3B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE;QAC/B,IAAI,EAAE,aAAa,CAAC,IAAI;AACxB,QAAA,WAAW,EAAE,CAAA;;AAEiC,mDAAA,CAAA;AAC9C,QAAA,MAAM,EAAE,iBAAiB;AAC1B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE;QAC/B,IAAI,EAAE,aAAa,CAAC,IAAI;AACxB,QAAA,WAAW,EAAE,CAAA;AAC6C,+DAAA,CAAA;AAC1D,QAAA,MAAM,EAAE,iBAAiB;AAC1B,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE;QACrC,IAAI,EAAE,aAAa,CAAC,UAAU;AAC9B,QAAA,WAAW,EAAE,CAAoE,kEAAA,CAAA;AACjF,QAAA,MAAM,EAAE,uBAAuB;AAChC,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,EAAE;QACzC,IAAI,EAAE,aAAa,CAAC,cAAc;AAClC,QAAA,WAAW,EAAE,CAAgF,8EAAA,CAAA;AAC7F,QAAA,MAAM,EAAE,yBAAyB;AAClC,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,eAAe,CAAC,EAAE;QACxC,IAAI,EAAE,aAAa,CAAC,aAAa;AACjC,QAAA,WAAW,EAAE,CAAsF,oFAAA,CAAA;AACnG,QAAA,MAAM,EAAE,yBAAyB;AAClC,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,aAAa,CAAC,EAAE;QACtC,IAAI,EAAE,aAAa,CAAC,WAAW;AAC/B,QAAA,WAAW,EAAE,CAAA;;;AAGgC,kDAAA,CAAA;AAC7C,QAAA,MAAM,EAAE,uBAAuB;AAChC,KAAA,CAAC,CACH;;IAGD,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE;QACnC,IAAI,EAAE,aAAa,CAAC,QAAQ;AAC5B,QAAA,WAAW,EAAE,CAAA;;;;;;;;;;;;;;;;AAgBiC,mDAAA,CAAA;AAC9C,QAAA,MAAM,EAAE,qBAAqB;AAC9B,KAAA,CAAC,CACH;AAED,IAAA,OAAO,KAAK;AACd;;;;"}

package/dist/types/tools/BrowserTools.d.ts

@@ -30,16 +30,39 @@ export type BrowserToolName = (typeof EBrowserTools)[keyof typeof EBrowserTools]
  * @returns Promise that resolves with the actual browser result (page state, etc.)
  */
 export type BrowserToolCallback = (action: string, args: Record<string, unknown>, toolCallId: string) => Promise<BrowserActionResult>;
+/**
+ * Action status - matches Skyvern's ActionStatus
+ */
+export type ActionStatus = 'pending' | 'completed' | 'failed' | 'skipped';
+/**
+ * Verification status - matches Skyvern's VerificationStatus
+ * - complete: Goal achieved
+ * - terminate: Goal cannot be achieved, stop
+ * - continue: Goal not yet achieved, keep going
+ */
+export type VerificationStatus = 'complete' | 'terminate' | 'continue';
 /**
  * Result returned from browser action execution
  */
 export interface BrowserActionResult {
     success: boolean;
+    status?: ActionStatus;
     url?: string;
     title?: string;
     elementList?: string;
     error?: string;
+    errorType?: string;
     screenshot?: string;
+    elementDescription?: string;
+    verification?: {
+        urlChanged: boolean;
+        titleChanged: boolean;
+        elementCountDelta: number;
+        significantChange: boolean;
+        dialogClosed: boolean;
+        formGone: boolean;
+        changeDescription: string;
+    };
 }
 /**
  * Check if browser capability is available based on request headers or context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/tools/BrowserTools.ts

@@ -42,16 +42,42 @@ export type BrowserToolCallback = (
   toolCallId: string
 ) => Promise<BrowserActionResult>;
 
+/**
+ * Action status - matches Skyvern's ActionStatus
+ */
+export type ActionStatus = 'pending' | 'completed' | 'failed' | 'skipped';
+
+/**
+ * Verification status - matches Skyvern's VerificationStatus
+ * - complete: Goal achieved
+ * - terminate: Goal cannot be achieved, stop
+ * - continue: Goal not yet achieved, keep going
+ */
+export type VerificationStatus = 'complete' | 'terminate' | 'continue';
+
 /**
  * Result returned from browser action execution
  */
 export interface BrowserActionResult {
   success: boolean;
+  status?: ActionStatus;
   url?: string;
   title?: string;
-  elementList?: string; // Text-based element list
+  elementList?: string;
   error?: string;
-  screenshot?: string; // Base64 screenshot (if requested)
+  errorType?: string; // Typed error classification
+  screenshot?: string;
+  elementDescription?: string;
+  // State verification (before/after comparison)
+  verification?: {
+    urlChanged: boolean;
+    titleChanged: boolean;
+    elementCountDelta: number;
+    significantChange: boolean;
+    dialogClosed: boolean;
+    formGone: boolean;
+    changeDescription: string;
+  };
 }
 
 /**
@@ -187,30 +213,30 @@ export interface CreateBrowserToolsOptions {
  */
 function formatResultForLLM(
   result: BrowserActionResult,
-  action: string
+  action: string,
+  actionArgs?: Record<string, unknown>
 ): string {
   if (!result.success && result.error) {
-    return `Browser action "${action}" failed: ${result.error}`;
+    const errorType = result.errorType ? `[${result.errorType}] ` : '';
+    return `${errorType}Action "${action}" failed: ${result.error}`;
   }
 
   const parts: string[] = [];
 
-  if (result.url != null && result.url !== '') {
-    parts.push(`**Current URL:** ${result.url}`);
-  }
-  if (result.title != null && result.title !== '') {
-    parts.push(`**Page Title:** ${result.title}`);
-  }
-  if (result.elementList != null && result.elementList !== '') {
-    parts.push(`\n**Interactive Elements:**\n${result.elementList}`);
-  }
-  if (result.screenshot != null && result.screenshot !== '') {
-    parts.push('\n[Screenshot captured and displayed to user]');
+  // Verification result (Skyvern pattern)
+  if (result.verification) {
+    const v = result.verification;
+    if (v.dialogClosed || v.formGone || v.urlChanged) {
+      parts.push(`✓ ${v.changeDescription}`);
+    } else if (!v.significantChange) {
+      parts.push(`⚠ No change detected`);
+    }
   }
 
-  if (parts.length === 0) {
-    return `Browser action "${action}" completed successfully.`;
-  }
+  // Page state
+  if (result.url) parts.push(`URL: ${result.url}`);
+  if (result.title) parts.push(`Title: ${result.title}`);
+  if (result.elementList) parts.push(`\nElements:\n${result.elementList}`);
 
   return parts.join('\n');
 }
@@ -265,23 +291,36 @@ export function createBrowserTools(
       // The marker is still returned initially via SSE, but we wait for the callback
       try {
         const result = await waitForResult(action, args, toolCallId);
-        return formatResultForLLM(result, action);
+        return formatResultForLLM(result, action, args);
       } catch (error) {
         const errorMessage =
           error instanceof Error ? error.message : String(error);
-        return `Browser action "${action}" failed: ${errorMessage}`;
+        return `❌ **ACTION FAILED**: Browser action "${action}" failed: ${errorMessage}
+
+**REQUIRED**: Analyze why the action failed and try an alternative approach.`;
       }
     };
   };
 
-  // browser_click
+  // browser_click - PRIMARY action for buttons and links
   tools.push(
     tool(createToolFunction('click'), {
       name: EBrowserTools.CLICK,
-      description: `Click an element on the current web page by its index number.
-The element list shows clickable items like: [0]<button>Submit</button> [1]<a href="/home">Home</a>
-Use the index number in brackets to click that element.
-After clicking, you receive an updated element list showing the new page state.`,
+      description: `Click an element by its [index] from the element list.
+
+**WHEN TO USE (prioritize this over keypress):**
+- Buttons labeled "Send", "Submit", "Save", "OK", "Confirm" → CLICK them
+- Links (a tags) to navigate
+- Checkboxes, radio buttons to select
+- Any clickable element that performs an action
+
+**SEMANTIC ELEMENT IDENTIFICATION:**
+- Look for aria-label="Send", aria-label="Submit" for action buttons
+- Look for type="submit" for form submission
+- Look for button text like "Send", "Submit", "Save"
+- For email compose: Find the Send button, DON'T use keyboard shortcuts
+
+Returns verification: dialog closed, form submitted, URL changed, or NO CHANGE (action may have failed).`,
       schema: BrowserClickSchema,
     })
   );
@@ -290,10 +329,20 @@ After clicking, you receive an updated element list showing the new page state.`
   tools.push(
     tool(createToolFunction('type'), {
       name: EBrowserTools.TYPE,
-      description: `Type text into an input element on the page.
-Find the input element in the list by its index (e.g., [5]<input placeholder="Search">).
-Set pressEnter: true to submit forms after typing.
-After typing, you receive an updated element list.`,
+      description: `Type text into an input/textarea element by [index].
+
+**WHEN TO USE:**
+- Input fields (fieldType="email", "search", "phone", etc.)
+- Textareas for longer content
+- Contenteditable divs (like Gmail compose body)
+
+**OPTIONS:**
+- pressEnter: true → Press Enter after typing (for search forms)
+- pressEnter: false → Just type without submitting
+
+**DO NOT use pressEnter to send emails** - find and CLICK the Send button instead.
+
+Returns verification showing if text was entered or form was submitted.`,
       schema: BrowserTypeSchema,
     })
   );
@@ -302,8 +351,7 @@ After typing, you receive an updated element list.`,
   tools.push(
     tool(createToolFunction('navigate'), {
       name: EBrowserTools.NAVIGATE,
-      description: `Navigate to a URL. Always include the full URL with https://.
-After navigation, you receive the new page's element list.`,
+      description: `Navigate to a URL (include https://). Returns new page's element list.`,
       schema: BrowserNavigateSchema,
     })
   );
@@ -312,9 +360,7 @@ After navigation, you receive the new page's element list.`,
   tools.push(
     tool(createToolFunction('scroll'), {
       name: EBrowserTools.SCROLL,
-      description: `Scroll the page to reveal more content.
-Use 'down' to scroll down, 'up' to scroll up.
-After scrolling, you receive an updated element list with newly visible elements.`,
+      description: `Scroll the page. Returns updated element list with newly visible elements.`,
       schema: BrowserScrollSchema,
     })
   );
@@ -364,9 +410,7 @@ After going back, you receive the previous page's element list.`,
   tools.push(
     tool(createToolFunction('screenshot'), {
       name: EBrowserTools.SCREENSHOT,
-      description: `Capture a screenshot of the current page.
-Returns the page state with a note that screenshot was displayed to the user.
-Use browser_get_page_state to get the element list for automation.`,
+      description: `Capture a screenshot. Use browser_get_page_state for element list.`,
       schema: BrowserScreenshotSchema,
     })
   );
@@ -375,22 +419,16 @@ Use browser_get_page_state to get the element list for automation.`,
   tools.push(
     tool(createToolFunction('get_page_state'), {
       name: EBrowserTools.GET_PAGE_STATE,
-      description: `Get the current page state including URL, title, and all interactive elements.
-Use this at the start of a task to see what elements are available.
-Returns a text list of elements with their index numbers for interaction.`,
+      description: `Get current page URL, title, and interactive elements list with index numbers.`,
       schema: BrowserGetPageStateSchema,
     })
   );
 
-  // browser_select_option - Skyvern-inspired for robust dropdown handling
+  // browser_select_option
   tools.push(
     tool(createToolFunction('select_option'), {
       name: EBrowserTools.SELECT_OPTION,
-      description: `Select an option from a dropdown or select element.
-For native <select> elements: finds and selects the option by value/label.
-For custom dropdowns: clicks to open, then clicks the matching option.
-Use this instead of click for dropdowns - it handles both native and custom selects.
-After selection, you receive an updated element list.`,
+      description: `Select an option from a dropdown. Handles both native <select> and custom dropdowns.`,
       schema: BrowserSelectOptionSchema,
     })
   );
@@ -407,15 +445,27 @@ After upload, you receive an updated element list.`,
     })
   );
 
-  // browser_keypress - For keyboard shortcuts and special keys
+  // browser_keypress - LAST RESORT for keyboard shortcuts
   tools.push(
     tool(createToolFunction('keypress'), {
       name: EBrowserTools.KEYPRESS,
-      description: `Press keyboard key(s) on the page.
-Single keys: "Enter", "Escape", "Tab", "ArrowDown", "ArrowUp", "Backspace", "Delete"
-Key combos: "Control+A" (select all), "Control+C" (copy), "Shift+Enter" (newline)
-Use this for form submission, closing modals, navigating dropdowns.
-After keypress, you receive an updated element list.`,
+      description: `Press keyboard key(s) - USE ONLY AS LAST RESORT after clicking fails.
+
+**PREFER browser_click OVER keypress:**
+- To send email → Find and CLICK the Send button
+- To submit form → CLICK the Submit button
+- To close modal → CLICK the X or Cancel button
+
+**WHEN TO USE keypress:**
+- Navigation: "Tab", "ArrowDown", "ArrowUp" in dropdowns
+- Escape to close popups if no X button exists
+- Control+A, Control+C for select/copy operations
+- ONLY use Enter to submit if there's NO visible submit button
+
+Single keys: "Enter", "Escape", "Tab", "ArrowDown"
+Key combos: "Control+A", "Shift+Enter"
+
+Returns verification showing if page state changed.`,
       schema: BrowserKeypressSchema,
     })
   );