illuma-agents 1.0.26 → 1.0.27

package/dist/cjs/tools/BrowserTools.cjs

@@ -62,25 +62,79 @@ const BrowserBackSchema = zod.z.object({});
 const BrowserScreenshotSchema = zod.z.object({});
 const BrowserGetPageStateSchema = zod.z.object({});
 /**
- * Create placeholder browser tools that signal to the extension to execute locally
- * The server creates these tools to give the LLM the schema, but actual execution
- * happens in the browser extension which intercepts tool calls
+ * Format browser action result for LLM consumption
+ */
+function formatResultForLLM(result, action) {
+    if (!result.success && result.error) {
+        return `Browser action "${action}" failed: ${result.error}`;
+    }
+    const parts = [];
+    if (result.url) {
+        parts.push(`**Current URL:** ${result.url}`);
+    }
+    if (result.title) {
+        parts.push(`**Page Title:** ${result.title}`);
+    }
+    if (result.elementList) {
+        parts.push(`\n**Interactive Elements:**\n${result.elementList}`);
+    }
+    if (result.screenshot) {
+        parts.push(`\n[Screenshot captured and displayed to user]`);
+    }
+    if (parts.length === 0) {
+        return `Browser action "${action}" completed successfully.`;
+    }
+    return parts.join('\n');
+}
+/**
+ * Create browser tools with optional callback for waiting on results
+ *
+ * When waitForResult callback is provided:
+ * 1. Tool returns marker that triggers extension
+ * 2. Tool then awaits callback to get actual results
+ * 3. Returns real page state to LLM
+ *
+ * When no callback:
+ * 1. Tool returns marker only (for non-server contexts)
  *
  * NOTE: These tools use TEXT-BASED element lists, NOT screenshots
  * Screenshots would be 100K+ tokens each - element lists are ~100 tokens
  */
-function createBrowserTools() {
+function createBrowserTools(options) {
+    const { waitForResult } = options || {};
     const tools$1 = [];
-    // browser_click
-    tools$1.push(tools.tool(async (args) => {
-        // This returns a marker that tells the extension to execute locally
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'click',
-            args,
+    /**
+     * Helper to create tool function that optionally waits for results
+     * The toolCallId is extracted from the RunnableConfig passed by LangChain
+     */
+    const createToolFunction = (action) => {
+        return async (args, config) => {
+            const toolCallId = config?.toolCall?.id || `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+            // Create marker for extension
+            const marker = {
+                requiresBrowserExecution: true,
+                action,
+                args,
+                toolCallId,
+            };
+            // If no callback, return marker immediately (extension handles via SSE interception)
+            if (!waitForResult) {
+                return JSON.stringify(marker);
+            }
+            // With callback: wait for actual results from extension
+            // 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);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return `Browser action "${action}" failed: ${errorMessage}`;
+            }
         };
-        return JSON.stringify(response);
-    }, {
+    };
+    // browser_click
+    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>
@@ -89,14 +143,7 @@ After clicking, you receive an updated element list showing the new page state.`
         schema: BrowserClickSchema,
     }));
     // browser_type
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'type',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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">).
@@ -105,28 +152,14 @@ After typing, you receive an updated element list.`,
         schema: BrowserTypeSchema,
     }));
     // browser_navigate
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'navigate',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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.`,
         schema: BrowserNavigateSchema,
     }));
     // browser_scroll
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'scroll',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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.
@@ -134,42 +167,21 @@ After scrolling, you receive an updated element list with newly visible elements
         schema: BrowserScrollSchema,
     }));
     // browser_extract
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'extract',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools$1.push(tools.tool(createToolFunction('extract'), {
         name: EBrowserTools.EXTRACT,
         description: `Extract content from the current page.
 Returns page URL, title, and element list.`,
         schema: BrowserExtractSchema,
     }));
     // browser_hover
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'hover',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools$1.push(tools.tool(createToolFunction('hover'), {
         name: EBrowserTools.HOVER,
         description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.
 After hovering, you receive an updated element list with any newly revealed elements.`,
         schema: BrowserHoverSchema,
     }));
     // browser_wait
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'wait',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools$1.push(tools.tool(createToolFunction('wait'), {
         name: EBrowserTools.WAIT,
         description: `Wait for a specified duration for page content to load.
 Use this after actions that trigger async content loading.
@@ -177,47 +189,26 @@ After waiting, you receive an updated element list.`,
         schema: BrowserWaitSchema,
     }));
     // browser_back
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'back',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools$1.push(tools.tool(createToolFunction('back'), {
         name: EBrowserTools.BACK,
         description: `Go back to the previous page in browser history.
 After going back, you receive the previous page's element list.`,
         schema: BrowserBackSchema,
     }));
     // browser_screenshot
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'screenshot',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools$1.push(tools.tool(createToolFunction('screenshot'), {
         name: EBrowserTools.SCREENSHOT,
         description: `Capture a screenshot of the current page.
-NOTE: Screenshot is displayed to the USER only, not returned to you.
-Use browser_get_page_state instead to get the element list.`,
+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.`,
         schema: BrowserScreenshotSchema,
     }));
     // browser_get_page_state
-    tools$1.push(tools.tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'get_page_state',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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.`,
+Returns a text list of elements with their index numbers for interaction.`,
         schema: BrowserGetPageStateSchema,
     }));
     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';\r\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\r\nimport type * as t from '@/types';\r\n\r\n/**\r\n * Browser tool names - keep in sync with ranger-browser extension\r\n * These tools execute locally in the browser extension, NOT on the server\r\n */\r\nexport const EBrowserTools = {\r\n  CLICK: 'browser_click',\r\n  TYPE: 'browser_type',\r\n  NAVIGATE: 'browser_navigate',\r\n  SCROLL: 'browser_scroll',\r\n  EXTRACT: 'browser_extract',\r\n  HOVER: 'browser_hover',\r\n  WAIT: 'browser_wait',\r\n  BACK: 'browser_back',\r\n  SCREENSHOT: 'browser_screenshot',\r\n  GET_PAGE_STATE: 'browser_get_page_state',\r\n} as const;\r\n\r\nexport type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];\r\n\r\n/**\r\n * Check if browser capability is available based on request headers or context\r\n * The browser extension sets these headers when connected:\r\n * - X-Ranger-Browser-Extension: true\r\n * - X-Ranger-Browser-Capable: true\r\n */\r\nexport function hasBrowserCapability(req?: { headers?: Record<string, string | string[] | undefined> }): boolean {\r\n  if (!req?.headers) {\r\n    return false;\r\n  }\r\n  \r\n  const browserExtension = req.headers['x-ranger-browser-extension'];\r\n  const browserCapable = req.headers['x-ranger-browser-capable'];\r\n  \r\n  return browserExtension === 'true' || browserCapable === 'true';\r\n}\r\n\r\n// Tool schemas\r\nconst BrowserClickSchema = z.object({\r\n  index: z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),\r\n});\r\n\r\nconst BrowserTypeSchema = z.object({\r\n  index: z.number().describe('The index number of the input element to type into'),\r\n  text: z.string().describe('The text to type into the element'),\r\n  pressEnter: z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),\r\n});\r\n\r\nconst BrowserNavigateSchema = z.object({\r\n  url: z.string().describe('The full URL to navigate to (must include https://)'),\r\n});\r\n\r\nconst BrowserScrollSchema = z.object({\r\n  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),\r\n  amount: z.number().optional().describe('Pixels to scroll (default: one viewport height)'),\r\n});\r\n\r\nconst BrowserExtractSchema = z.object({\r\n  query: z.string().optional().describe('Optional: specific content to extract from the page'),\r\n});\r\n\r\nconst BrowserHoverSchema = z.object({\r\n  index: z.number().describe('The index number of the element to hover over'),\r\n});\r\n\r\nconst BrowserWaitSchema = z.object({\r\n  duration: z.number().optional().describe('Milliseconds to wait (default: 1000)'),\r\n});\r\n\r\nconst BrowserBackSchema = z.object({});\r\n\r\nconst BrowserScreenshotSchema = z.object({});\r\n\r\nconst BrowserGetPageStateSchema = z.object({});\r\n\r\n/**\r\n * Browser tool response interface\r\n * This is what the extension returns after executing the action\r\n */\r\nexport interface BrowserToolResponse {\r\n  requiresBrowserExecution: true;\r\n  action: string;\r\n  args: Record<string, unknown>;\r\n}\r\n\r\n/**\r\n * Create placeholder browser tools that signal to the extension to execute locally\r\n * The server creates these tools to give the LLM the schema, but actual execution\r\n * happens in the browser extension which intercepts tool calls\r\n * \r\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\r\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\r\n */\r\nexport function createBrowserTools(): DynamicStructuredTool[] {\r\n  const tools: DynamicStructuredTool[] = [];\r\n\r\n  // browser_click\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        // This returns a marker that tells the extension to execute locally\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'click',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.CLICK,\r\n        description: `Click an element on the current web page by its index number.\r\nThe element list shows clickable items like: [0]<button>Submit</button> [1]<a href=\"/home\">Home</a>\r\nUse the index number in brackets to click that element.\r\nAfter clicking, you receive an updated element list showing the new page state.`,\r\n        schema: BrowserClickSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_type\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'type',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.TYPE,\r\n        description: `Type text into an input element on the page.\r\nFind the input element in the list by its index (e.g., [5]<input placeholder=\"Search\">).\r\nSet pressEnter: true to submit forms after typing.\r\nAfter typing, you receive an updated element list.`,\r\n        schema: BrowserTypeSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_navigate\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'navigate',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.NAVIGATE,\r\n        description: `Navigate to a URL. Always include the full URL with https://.\r\nAfter navigation, you receive the new page's element list.`,\r\n        schema: BrowserNavigateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_scroll\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'scroll',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.SCROLL,\r\n        description: `Scroll the page to reveal more content.\r\nUse 'down' to scroll down, 'up' to scroll up.\r\nAfter scrolling, you receive an updated element list with newly visible elements.`,\r\n        schema: BrowserScrollSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_extract\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'extract',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.EXTRACT,\r\n        description: `Extract content from the current page.\r\nReturns page URL, title, and element list.`,\r\n        schema: BrowserExtractSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_hover\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'hover',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.HOVER,\r\n        description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\r\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\r\n        schema: BrowserHoverSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_wait\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'wait',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.WAIT,\r\n        description: `Wait for a specified duration for page content to load.\r\nUse this after actions that trigger async content loading.\r\nAfter waiting, you receive an updated element list.`,\r\n        schema: BrowserWaitSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_back\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'back',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.BACK,\r\n        description: `Go back to the previous page in browser history.\r\nAfter going back, you receive the previous page's element list.`,\r\n        schema: BrowserBackSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_screenshot\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'screenshot',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.SCREENSHOT,\r\n        description: `Capture a screenshot of the current page.\r\nNOTE: Screenshot is displayed to the USER only, not returned to you.\r\nUse browser_get_page_state instead to get the element list.`,\r\n        schema: BrowserScreenshotSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_get_page_state\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'get_page_state',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.GET_PAGE_STATE,\r\n        description: `Get the current page state including URL, title, and all interactive elements.\r\nUse this at the start of a task to see what elements are available.\r\nReturns a text list of elements with their index numbers.`,\r\n        schema: BrowserGetPageStateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  return tools;\r\n}\r\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';\r\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\r\nimport type * as t from '@/types';\r\n\r\n/**\r\n * Browser tool names - keep in sync with ranger-browser extension\r\n * These tools execute locally in the browser extension, NOT on the server\r\n */\r\nexport const EBrowserTools = {\r\n  CLICK: 'browser_click',\r\n  TYPE: 'browser_type',\r\n  NAVIGATE: 'browser_navigate',\r\n  SCROLL: 'browser_scroll',\r\n  EXTRACT: 'browser_extract',\r\n  HOVER: 'browser_hover',\r\n  WAIT: 'browser_wait',\r\n  BACK: 'browser_back',\r\n  SCREENSHOT: 'browser_screenshot',\r\n  GET_PAGE_STATE: 'browser_get_page_state',\r\n} as const;\r\n\r\nexport type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];\r\n\r\n/**\r\n * Callback function type for waiting on browser action results\r\n * This allows the server (Ranger) to provide a callback that waits for the extension\r\n * to POST results back to the server before returning to the LLM.\r\n * \r\n * @param action - The browser action (click, type, navigate, etc.)\r\n * @param args - Arguments for the action\r\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\r\n * @returns Promise that resolves with the actual browser result (page state, etc.)\r\n */\r\nexport type BrowserToolCallback = (\r\n  action: string,\r\n  args: Record<string, unknown>,\r\n  toolCallId: string\r\n) => Promise<BrowserActionResult>;\r\n\r\n/**\r\n * Result returned from browser action execution\r\n */\r\nexport interface BrowserActionResult {\r\n  success: boolean;\r\n  url?: string;\r\n  title?: string;\r\n  elementList?: string;  // Text-based element list\r\n  error?: string;\r\n  screenshot?: string;   // Base64 screenshot (if requested)\r\n}\r\n\r\n/**\r\n * Check if browser capability is available based on request headers or context\r\n * The browser extension sets these headers when connected:\r\n * - X-Ranger-Browser-Extension: true\r\n * - X-Ranger-Browser-Capable: true\r\n */\r\nexport function hasBrowserCapability(req?: { headers?: Record<string, string | string[] | undefined> }): boolean {\r\n  if (!req?.headers) {\r\n    return false;\r\n  }\r\n  \r\n  const browserExtension = req.headers['x-ranger-browser-extension'];\r\n  const browserCapable = req.headers['x-ranger-browser-capable'];\r\n  \r\n  return browserExtension === 'true' || browserCapable === 'true';\r\n}\r\n\r\n// Tool schemas\r\nconst BrowserClickSchema = z.object({\r\n  index: z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),\r\n});\r\n\r\nconst BrowserTypeSchema = z.object({\r\n  index: z.number().describe('The index number of the input element to type into'),\r\n  text: z.string().describe('The text to type into the element'),\r\n  pressEnter: z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),\r\n});\r\n\r\nconst BrowserNavigateSchema = z.object({\r\n  url: z.string().describe('The full URL to navigate to (must include https://)'),\r\n});\r\n\r\nconst BrowserScrollSchema = z.object({\r\n  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),\r\n  amount: z.number().optional().describe('Pixels to scroll (default: one viewport height)'),\r\n});\r\n\r\nconst BrowserExtractSchema = z.object({\r\n  query: z.string().optional().describe('Optional: specific content to extract from the page'),\r\n});\r\n\r\nconst BrowserHoverSchema = z.object({\r\n  index: z.number().describe('The index number of the element to hover over'),\r\n});\r\n\r\nconst BrowserWaitSchema = z.object({\r\n  duration: z.number().optional().describe('Milliseconds to wait (default: 1000)'),\r\n});\r\n\r\nconst BrowserBackSchema = z.object({});\r\n\r\nconst BrowserScreenshotSchema = z.object({});\r\n\r\nconst BrowserGetPageStateSchema = z.object({});\r\n\r\n/**\r\n * Browser tool response interface\r\n * This is what the extension returns after executing the action\r\n */\r\nexport interface BrowserToolResponse {\r\n  requiresBrowserExecution: true;\r\n  action: string;\r\n  args: Record<string, unknown>;\r\n  toolCallId?: string;  // Added to help extension correlate with callback\r\n}\r\n\r\n/**\r\n * Options for creating browser tools\r\n */\r\nexport interface CreateBrowserToolsOptions {\r\n  /**\r\n   * Optional callback that waits for browser action results.\r\n   * When provided, tools will await this callback to get actual results from the extension.\r\n   * When not provided, tools return markers immediately (for non-server contexts).\r\n   */\r\n  waitForResult?: BrowserToolCallback;\r\n}\r\n\r\n/**\r\n * Format browser action result for LLM consumption\r\n */\r\nfunction formatResultForLLM(result: BrowserActionResult, action: string): string {\r\n  if (!result.success && result.error) {\r\n    return `Browser action \"${action}\" failed: ${result.error}`;\r\n  }\r\n\r\n  const parts: string[] = [];\r\n  \r\n  if (result.url) {\r\n    parts.push(`**Current URL:** ${result.url}`);\r\n  }\r\n  if (result.title) {\r\n    parts.push(`**Page Title:** ${result.title}`);\r\n  }\r\n  if (result.elementList) {\r\n    parts.push(`\\n**Interactive Elements:**\\n${result.elementList}`);\r\n  }\r\n  if (result.screenshot) {\r\n    parts.push(`\\n[Screenshot captured and displayed to user]`);\r\n  }\r\n  \r\n  if (parts.length === 0) {\r\n    return `Browser action \"${action}\" completed successfully.`;\r\n  }\r\n  \r\n  return parts.join('\\n');\r\n}\r\n\r\n/**\r\n * Create browser tools with optional callback for waiting on results\r\n * \r\n * When waitForResult callback is provided:\r\n * 1. Tool returns marker that triggers extension\r\n * 2. Tool then awaits callback to get actual results\r\n * 3. Returns real page state to LLM\r\n * \r\n * When no callback:\r\n * 1. Tool returns marker only (for non-server contexts)\r\n * \r\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\r\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\r\n */\r\nexport function createBrowserTools(options?: CreateBrowserToolsOptions): DynamicStructuredTool[] {\r\n  const { waitForResult } = options || {};\r\n  const tools: DynamicStructuredTool[] = [];\r\n\r\n  /**\r\n   * Helper to create tool function that optionally waits for results\r\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\r\n   */\r\n  const createToolFunction = (action: string) => {\r\n    return async (args: Record<string, unknown>, config?: { toolCall?: { id?: string } }): Promise<string> => {\r\n      const toolCallId = config?.toolCall?.id || `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\r\n      \r\n      // Create marker for extension\r\n      const marker: BrowserToolResponse = {\r\n        requiresBrowserExecution: true,\r\n        action,\r\n        args,\r\n        toolCallId,\r\n      };\r\n      \r\n      // If no callback, return marker immediately (extension handles via SSE interception)\r\n      if (!waitForResult) {\r\n        return JSON.stringify(marker);\r\n      }\r\n      \r\n      // With callback: wait for actual results from extension\r\n      // The marker is still returned initially via SSE, but we wait for the callback\r\n      try {\r\n        const result = await waitForResult(action, args, toolCallId);\r\n        return formatResultForLLM(result, action);\r\n      } catch (error) {\r\n        const errorMessage = error instanceof Error ? error.message : String(error);\r\n        return `Browser action \"${action}\" failed: ${errorMessage}`;\r\n      }\r\n    };\r\n  };\r\n\r\n  // browser_click\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('click'),\r\n      {\r\n        name: EBrowserTools.CLICK,\r\n        description: `Click an element on the current web page by its index number.\r\nThe element list shows clickable items like: [0]<button>Submit</button> [1]<a href=\"/home\">Home</a>\r\nUse the index number in brackets to click that element.\r\nAfter clicking, you receive an updated element list showing the new page state.`,\r\n        schema: BrowserClickSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_type\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('type'),\r\n      {\r\n        name: EBrowserTools.TYPE,\r\n        description: `Type text into an input element on the page.\r\nFind the input element in the list by its index (e.g., [5]<input placeholder=\"Search\">).\r\nSet pressEnter: true to submit forms after typing.\r\nAfter typing, you receive an updated element list.`,\r\n        schema: BrowserTypeSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_navigate\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('navigate'),\r\n      {\r\n        name: EBrowserTools.NAVIGATE,\r\n        description: `Navigate to a URL. Always include the full URL with https://.\r\nAfter navigation, you receive the new page's element list.`,\r\n        schema: BrowserNavigateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_scroll\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('scroll'),\r\n      {\r\n        name: EBrowserTools.SCROLL,\r\n        description: `Scroll the page to reveal more content.\r\nUse 'down' to scroll down, 'up' to scroll up.\r\nAfter scrolling, you receive an updated element list with newly visible elements.`,\r\n        schema: BrowserScrollSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_extract\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('extract'),\r\n      {\r\n        name: EBrowserTools.EXTRACT,\r\n        description: `Extract content from the current page.\r\nReturns page URL, title, and element list.`,\r\n        schema: BrowserExtractSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_hover\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('hover'),\r\n      {\r\n        name: EBrowserTools.HOVER,\r\n        description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\r\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\r\n        schema: BrowserHoverSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_wait\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('wait'),\r\n      {\r\n        name: EBrowserTools.WAIT,\r\n        description: `Wait for a specified duration for page content to load.\r\nUse this after actions that trigger async content loading.\r\nAfter waiting, you receive an updated element list.`,\r\n        schema: BrowserWaitSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_back\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('back'),\r\n      {\r\n        name: EBrowserTools.BACK,\r\n        description: `Go back to the previous page in browser history.\r\nAfter going back, you receive the previous page's element list.`,\r\n        schema: BrowserBackSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_screenshot\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('screenshot'),\r\n      {\r\n        name: EBrowserTools.SCREENSHOT,\r\n        description: `Capture a screenshot of the current page.\r\nReturns the page state with a note that screenshot was displayed to the user.\r\nUse browser_get_page_state to get the element list for automation.`,\r\n        schema: BrowserScreenshotSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_get_page_state\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('get_page_state'),\r\n      {\r\n        name: EBrowserTools.GET_PAGE_STATE,\r\n        description: `Get the current page state including URL, title, and all interactive elements.\r\nUse this at the start of a task to see what elements are available.\r\nReturns a text list of elements with their index numbers for interaction.`,\r\n        schema: BrowserGetPageStateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  return tools;\r\n}\r\n"],"names":["z","tools","tool"],"mappings":"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"}

package/dist/esm/tools/BrowserTools.mjs

@@ -60,25 +60,79 @@ const BrowserBackSchema = z.object({});
 const BrowserScreenshotSchema = z.object({});
 const BrowserGetPageStateSchema = z.object({});
 /**
- * Create placeholder browser tools that signal to the extension to execute locally
- * The server creates these tools to give the LLM the schema, but actual execution
- * happens in the browser extension which intercepts tool calls
+ * Format browser action result for LLM consumption
+ */
+function formatResultForLLM(result, action) {
+    if (!result.success && result.error) {
+        return `Browser action "${action}" failed: ${result.error}`;
+    }
+    const parts = [];
+    if (result.url) {
+        parts.push(`**Current URL:** ${result.url}`);
+    }
+    if (result.title) {
+        parts.push(`**Page Title:** ${result.title}`);
+    }
+    if (result.elementList) {
+        parts.push(`\n**Interactive Elements:**\n${result.elementList}`);
+    }
+    if (result.screenshot) {
+        parts.push(`\n[Screenshot captured and displayed to user]`);
+    }
+    if (parts.length === 0) {
+        return `Browser action "${action}" completed successfully.`;
+    }
+    return parts.join('\n');
+}
+/**
+ * Create browser tools with optional callback for waiting on results
+ *
+ * When waitForResult callback is provided:
+ * 1. Tool returns marker that triggers extension
+ * 2. Tool then awaits callback to get actual results
+ * 3. Returns real page state to LLM
+ *
+ * When no callback:
+ * 1. Tool returns marker only (for non-server contexts)
  *
  * NOTE: These tools use TEXT-BASED element lists, NOT screenshots
  * Screenshots would be 100K+ tokens each - element lists are ~100 tokens
  */
-function createBrowserTools() {
+function createBrowserTools(options) {
+    const { waitForResult } = options || {};
     const tools = [];
-    // browser_click
-    tools.push(tool(async (args) => {
-        // This returns a marker that tells the extension to execute locally
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'click',
-            args,
+    /**
+     * Helper to create tool function that optionally waits for results
+     * The toolCallId is extracted from the RunnableConfig passed by LangChain
+     */
+    const createToolFunction = (action) => {
+        return async (args, config) => {
+            const toolCallId = config?.toolCall?.id || `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+            // Create marker for extension
+            const marker = {
+                requiresBrowserExecution: true,
+                action,
+                args,
+                toolCallId,
+            };
+            // If no callback, return marker immediately (extension handles via SSE interception)
+            if (!waitForResult) {
+                return JSON.stringify(marker);
+            }
+            // With callback: wait for actual results from extension
+            // 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);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return `Browser action "${action}" failed: ${errorMessage}`;
+            }
         };
-        return JSON.stringify(response);
-    }, {
+    };
+    // browser_click
+    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>
@@ -87,14 +141,7 @@ After clicking, you receive an updated element list showing the new page state.`
         schema: BrowserClickSchema,
     }));
     // browser_type
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'type',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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">).
@@ -103,28 +150,14 @@ After typing, you receive an updated element list.`,
         schema: BrowserTypeSchema,
     }));
     // browser_navigate
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'navigate',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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.`,
         schema: BrowserNavigateSchema,
     }));
     // browser_scroll
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'scroll',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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.
@@ -132,42 +165,21 @@ After scrolling, you receive an updated element list with newly visible elements
         schema: BrowserScrollSchema,
     }));
     // browser_extract
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'extract',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools.push(tool(createToolFunction('extract'), {
         name: EBrowserTools.EXTRACT,
         description: `Extract content from the current page.
 Returns page URL, title, and element list.`,
         schema: BrowserExtractSchema,
     }));
     // browser_hover
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'hover',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools.push(tool(createToolFunction('hover'), {
         name: EBrowserTools.HOVER,
         description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.
 After hovering, you receive an updated element list with any newly revealed elements.`,
         schema: BrowserHoverSchema,
     }));
     // browser_wait
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'wait',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools.push(tool(createToolFunction('wait'), {
         name: EBrowserTools.WAIT,
         description: `Wait for a specified duration for page content to load.
 Use this after actions that trigger async content loading.
@@ -175,47 +187,26 @@ After waiting, you receive an updated element list.`,
         schema: BrowserWaitSchema,
     }));
     // browser_back
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'back',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools.push(tool(createToolFunction('back'), {
         name: EBrowserTools.BACK,
         description: `Go back to the previous page in browser history.
 After going back, you receive the previous page's element list.`,
         schema: BrowserBackSchema,
     }));
     // browser_screenshot
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'screenshot',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    tools.push(tool(createToolFunction('screenshot'), {
         name: EBrowserTools.SCREENSHOT,
         description: `Capture a screenshot of the current page.
-NOTE: Screenshot is displayed to the USER only, not returned to you.
-Use browser_get_page_state instead to get the element list.`,
+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.`,
         schema: BrowserScreenshotSchema,
     }));
     // browser_get_page_state
-    tools.push(tool(async (args) => {
-        const response = {
-            requiresBrowserExecution: true,
-            action: 'get_page_state',
-            args,
-        };
-        return JSON.stringify(response);
-    }, {
+    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.`,
+Returns a text list of elements with their index numbers for interaction.`,
         schema: BrowserGetPageStateSchema,
     }));
     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';\r\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\r\nimport type * as t from '@/types';\r\n\r\n/**\r\n * Browser tool names - keep in sync with ranger-browser extension\r\n * These tools execute locally in the browser extension, NOT on the server\r\n */\r\nexport const EBrowserTools = {\r\n  CLICK: 'browser_click',\r\n  TYPE: 'browser_type',\r\n  NAVIGATE: 'browser_navigate',\r\n  SCROLL: 'browser_scroll',\r\n  EXTRACT: 'browser_extract',\r\n  HOVER: 'browser_hover',\r\n  WAIT: 'browser_wait',\r\n  BACK: 'browser_back',\r\n  SCREENSHOT: 'browser_screenshot',\r\n  GET_PAGE_STATE: 'browser_get_page_state',\r\n} as const;\r\n\r\nexport type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];\r\n\r\n/**\r\n * Check if browser capability is available based on request headers or context\r\n * The browser extension sets these headers when connected:\r\n * - X-Ranger-Browser-Extension: true\r\n * - X-Ranger-Browser-Capable: true\r\n */\r\nexport function hasBrowserCapability(req?: { headers?: Record<string, string | string[] | undefined> }): boolean {\r\n  if (!req?.headers) {\r\n    return false;\r\n  }\r\n  \r\n  const browserExtension = req.headers['x-ranger-browser-extension'];\r\n  const browserCapable = req.headers['x-ranger-browser-capable'];\r\n  \r\n  return browserExtension === 'true' || browserCapable === 'true';\r\n}\r\n\r\n// Tool schemas\r\nconst BrowserClickSchema = z.object({\r\n  index: z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),\r\n});\r\n\r\nconst BrowserTypeSchema = z.object({\r\n  index: z.number().describe('The index number of the input element to type into'),\r\n  text: z.string().describe('The text to type into the element'),\r\n  pressEnter: z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),\r\n});\r\n\r\nconst BrowserNavigateSchema = z.object({\r\n  url: z.string().describe('The full URL to navigate to (must include https://)'),\r\n});\r\n\r\nconst BrowserScrollSchema = z.object({\r\n  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),\r\n  amount: z.number().optional().describe('Pixels to scroll (default: one viewport height)'),\r\n});\r\n\r\nconst BrowserExtractSchema = z.object({\r\n  query: z.string().optional().describe('Optional: specific content to extract from the page'),\r\n});\r\n\r\nconst BrowserHoverSchema = z.object({\r\n  index: z.number().describe('The index number of the element to hover over'),\r\n});\r\n\r\nconst BrowserWaitSchema = z.object({\r\n  duration: z.number().optional().describe('Milliseconds to wait (default: 1000)'),\r\n});\r\n\r\nconst BrowserBackSchema = z.object({});\r\n\r\nconst BrowserScreenshotSchema = z.object({});\r\n\r\nconst BrowserGetPageStateSchema = z.object({});\r\n\r\n/**\r\n * Browser tool response interface\r\n * This is what the extension returns after executing the action\r\n */\r\nexport interface BrowserToolResponse {\r\n  requiresBrowserExecution: true;\r\n  action: string;\r\n  args: Record<string, unknown>;\r\n}\r\n\r\n/**\r\n * Create placeholder browser tools that signal to the extension to execute locally\r\n * The server creates these tools to give the LLM the schema, but actual execution\r\n * happens in the browser extension which intercepts tool calls\r\n * \r\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\r\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\r\n */\r\nexport function createBrowserTools(): DynamicStructuredTool[] {\r\n  const tools: DynamicStructuredTool[] = [];\r\n\r\n  // browser_click\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        // This returns a marker that tells the extension to execute locally\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'click',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.CLICK,\r\n        description: `Click an element on the current web page by its index number.\r\nThe element list shows clickable items like: [0]<button>Submit</button> [1]<a href=\"/home\">Home</a>\r\nUse the index number in brackets to click that element.\r\nAfter clicking, you receive an updated element list showing the new page state.`,\r\n        schema: BrowserClickSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_type\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'type',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.TYPE,\r\n        description: `Type text into an input element on the page.\r\nFind the input element in the list by its index (e.g., [5]<input placeholder=\"Search\">).\r\nSet pressEnter: true to submit forms after typing.\r\nAfter typing, you receive an updated element list.`,\r\n        schema: BrowserTypeSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_navigate\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'navigate',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.NAVIGATE,\r\n        description: `Navigate to a URL. Always include the full URL with https://.\r\nAfter navigation, you receive the new page's element list.`,\r\n        schema: BrowserNavigateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_scroll\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'scroll',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.SCROLL,\r\n        description: `Scroll the page to reveal more content.\r\nUse 'down' to scroll down, 'up' to scroll up.\r\nAfter scrolling, you receive an updated element list with newly visible elements.`,\r\n        schema: BrowserScrollSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_extract\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'extract',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.EXTRACT,\r\n        description: `Extract content from the current page.\r\nReturns page URL, title, and element list.`,\r\n        schema: BrowserExtractSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_hover\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'hover',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.HOVER,\r\n        description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\r\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\r\n        schema: BrowserHoverSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_wait\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'wait',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.WAIT,\r\n        description: `Wait for a specified duration for page content to load.\r\nUse this after actions that trigger async content loading.\r\nAfter waiting, you receive an updated element list.`,\r\n        schema: BrowserWaitSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_back\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'back',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.BACK,\r\n        description: `Go back to the previous page in browser history.\r\nAfter going back, you receive the previous page's element list.`,\r\n        schema: BrowserBackSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_screenshot\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'screenshot',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.SCREENSHOT,\r\n        description: `Capture a screenshot of the current page.\r\nNOTE: Screenshot is displayed to the USER only, not returned to you.\r\nUse browser_get_page_state instead to get the element list.`,\r\n        schema: BrowserScreenshotSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_get_page_state\r\n  tools.push(\r\n    tool(\r\n      async (args): Promise<string> => {\r\n        const response: BrowserToolResponse = {\r\n          requiresBrowserExecution: true,\r\n          action: 'get_page_state',\r\n          args,\r\n        };\r\n        return JSON.stringify(response);\r\n      },\r\n      {\r\n        name: EBrowserTools.GET_PAGE_STATE,\r\n        description: `Get the current page state including URL, title, and all interactive elements.\r\nUse this at the start of a task to see what elements are available.\r\nReturns a text list of elements with their index numbers.`,\r\n        schema: BrowserGetPageStateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  return tools;\r\n}\r\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"BrowserTools.mjs","sources":["../../../src/tools/BrowserTools.ts"],"sourcesContent":["import { z } from 'zod';\r\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\r\nimport type * as t from '@/types';\r\n\r\n/**\r\n * Browser tool names - keep in sync with ranger-browser extension\r\n * These tools execute locally in the browser extension, NOT on the server\r\n */\r\nexport const EBrowserTools = {\r\n  CLICK: 'browser_click',\r\n  TYPE: 'browser_type',\r\n  NAVIGATE: 'browser_navigate',\r\n  SCROLL: 'browser_scroll',\r\n  EXTRACT: 'browser_extract',\r\n  HOVER: 'browser_hover',\r\n  WAIT: 'browser_wait',\r\n  BACK: 'browser_back',\r\n  SCREENSHOT: 'browser_screenshot',\r\n  GET_PAGE_STATE: 'browser_get_page_state',\r\n} as const;\r\n\r\nexport type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];\r\n\r\n/**\r\n * Callback function type for waiting on browser action results\r\n * This allows the server (Ranger) to provide a callback that waits for the extension\r\n * to POST results back to the server before returning to the LLM.\r\n * \r\n * @param action - The browser action (click, type, navigate, etc.)\r\n * @param args - Arguments for the action\r\n * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)\r\n * @returns Promise that resolves with the actual browser result (page state, etc.)\r\n */\r\nexport type BrowserToolCallback = (\r\n  action: string,\r\n  args: Record<string, unknown>,\r\n  toolCallId: string\r\n) => Promise<BrowserActionResult>;\r\n\r\n/**\r\n * Result returned from browser action execution\r\n */\r\nexport interface BrowserActionResult {\r\n  success: boolean;\r\n  url?: string;\r\n  title?: string;\r\n  elementList?: string;  // Text-based element list\r\n  error?: string;\r\n  screenshot?: string;   // Base64 screenshot (if requested)\r\n}\r\n\r\n/**\r\n * Check if browser capability is available based on request headers or context\r\n * The browser extension sets these headers when connected:\r\n * - X-Ranger-Browser-Extension: true\r\n * - X-Ranger-Browser-Capable: true\r\n */\r\nexport function hasBrowserCapability(req?: { headers?: Record<string, string | string[] | undefined> }): boolean {\r\n  if (!req?.headers) {\r\n    return false;\r\n  }\r\n  \r\n  const browserExtension = req.headers['x-ranger-browser-extension'];\r\n  const browserCapable = req.headers['x-ranger-browser-capable'];\r\n  \r\n  return browserExtension === 'true' || browserCapable === 'true';\r\n}\r\n\r\n// Tool schemas\r\nconst BrowserClickSchema = z.object({\r\n  index: z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),\r\n});\r\n\r\nconst BrowserTypeSchema = z.object({\r\n  index: z.number().describe('The index number of the input element to type into'),\r\n  text: z.string().describe('The text to type into the element'),\r\n  pressEnter: z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),\r\n});\r\n\r\nconst BrowserNavigateSchema = z.object({\r\n  url: z.string().describe('The full URL to navigate to (must include https://)'),\r\n});\r\n\r\nconst BrowserScrollSchema = z.object({\r\n  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),\r\n  amount: z.number().optional().describe('Pixels to scroll (default: one viewport height)'),\r\n});\r\n\r\nconst BrowserExtractSchema = z.object({\r\n  query: z.string().optional().describe('Optional: specific content to extract from the page'),\r\n});\r\n\r\nconst BrowserHoverSchema = z.object({\r\n  index: z.number().describe('The index number of the element to hover over'),\r\n});\r\n\r\nconst BrowserWaitSchema = z.object({\r\n  duration: z.number().optional().describe('Milliseconds to wait (default: 1000)'),\r\n});\r\n\r\nconst BrowserBackSchema = z.object({});\r\n\r\nconst BrowserScreenshotSchema = z.object({});\r\n\r\nconst BrowserGetPageStateSchema = z.object({});\r\n\r\n/**\r\n * Browser tool response interface\r\n * This is what the extension returns after executing the action\r\n */\r\nexport interface BrowserToolResponse {\r\n  requiresBrowserExecution: true;\r\n  action: string;\r\n  args: Record<string, unknown>;\r\n  toolCallId?: string;  // Added to help extension correlate with callback\r\n}\r\n\r\n/**\r\n * Options for creating browser tools\r\n */\r\nexport interface CreateBrowserToolsOptions {\r\n  /**\r\n   * Optional callback that waits for browser action results.\r\n   * When provided, tools will await this callback to get actual results from the extension.\r\n   * When not provided, tools return markers immediately (for non-server contexts).\r\n   */\r\n  waitForResult?: BrowserToolCallback;\r\n}\r\n\r\n/**\r\n * Format browser action result for LLM consumption\r\n */\r\nfunction formatResultForLLM(result: BrowserActionResult, action: string): string {\r\n  if (!result.success && result.error) {\r\n    return `Browser action \"${action}\" failed: ${result.error}`;\r\n  }\r\n\r\n  const parts: string[] = [];\r\n  \r\n  if (result.url) {\r\n    parts.push(`**Current URL:** ${result.url}`);\r\n  }\r\n  if (result.title) {\r\n    parts.push(`**Page Title:** ${result.title}`);\r\n  }\r\n  if (result.elementList) {\r\n    parts.push(`\\n**Interactive Elements:**\\n${result.elementList}`);\r\n  }\r\n  if (result.screenshot) {\r\n    parts.push(`\\n[Screenshot captured and displayed to user]`);\r\n  }\r\n  \r\n  if (parts.length === 0) {\r\n    return `Browser action \"${action}\" completed successfully.`;\r\n  }\r\n  \r\n  return parts.join('\\n');\r\n}\r\n\r\n/**\r\n * Create browser tools with optional callback for waiting on results\r\n * \r\n * When waitForResult callback is provided:\r\n * 1. Tool returns marker that triggers extension\r\n * 2. Tool then awaits callback to get actual results\r\n * 3. Returns real page state to LLM\r\n * \r\n * When no callback:\r\n * 1. Tool returns marker only (for non-server contexts)\r\n * \r\n * NOTE: These tools use TEXT-BASED element lists, NOT screenshots\r\n * Screenshots would be 100K+ tokens each - element lists are ~100 tokens\r\n */\r\nexport function createBrowserTools(options?: CreateBrowserToolsOptions): DynamicStructuredTool[] {\r\n  const { waitForResult } = options || {};\r\n  const tools: DynamicStructuredTool[] = [];\r\n\r\n  /**\r\n   * Helper to create tool function that optionally waits for results\r\n   * The toolCallId is extracted from the RunnableConfig passed by LangChain\r\n   */\r\n  const createToolFunction = (action: string) => {\r\n    return async (args: Record<string, unknown>, config?: { toolCall?: { id?: string } }): Promise<string> => {\r\n      const toolCallId = config?.toolCall?.id || `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;\r\n      \r\n      // Create marker for extension\r\n      const marker: BrowserToolResponse = {\r\n        requiresBrowserExecution: true,\r\n        action,\r\n        args,\r\n        toolCallId,\r\n      };\r\n      \r\n      // If no callback, return marker immediately (extension handles via SSE interception)\r\n      if (!waitForResult) {\r\n        return JSON.stringify(marker);\r\n      }\r\n      \r\n      // With callback: wait for actual results from extension\r\n      // The marker is still returned initially via SSE, but we wait for the callback\r\n      try {\r\n        const result = await waitForResult(action, args, toolCallId);\r\n        return formatResultForLLM(result, action);\r\n      } catch (error) {\r\n        const errorMessage = error instanceof Error ? error.message : String(error);\r\n        return `Browser action \"${action}\" failed: ${errorMessage}`;\r\n      }\r\n    };\r\n  };\r\n\r\n  // browser_click\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('click'),\r\n      {\r\n        name: EBrowserTools.CLICK,\r\n        description: `Click an element on the current web page by its index number.\r\nThe element list shows clickable items like: [0]<button>Submit</button> [1]<a href=\"/home\">Home</a>\r\nUse the index number in brackets to click that element.\r\nAfter clicking, you receive an updated element list showing the new page state.`,\r\n        schema: BrowserClickSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_type\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('type'),\r\n      {\r\n        name: EBrowserTools.TYPE,\r\n        description: `Type text into an input element on the page.\r\nFind the input element in the list by its index (e.g., [5]<input placeholder=\"Search\">).\r\nSet pressEnter: true to submit forms after typing.\r\nAfter typing, you receive an updated element list.`,\r\n        schema: BrowserTypeSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_navigate\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('navigate'),\r\n      {\r\n        name: EBrowserTools.NAVIGATE,\r\n        description: `Navigate to a URL. Always include the full URL with https://.\r\nAfter navigation, you receive the new page's element list.`,\r\n        schema: BrowserNavigateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_scroll\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('scroll'),\r\n      {\r\n        name: EBrowserTools.SCROLL,\r\n        description: `Scroll the page to reveal more content.\r\nUse 'down' to scroll down, 'up' to scroll up.\r\nAfter scrolling, you receive an updated element list with newly visible elements.`,\r\n        schema: BrowserScrollSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_extract\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('extract'),\r\n      {\r\n        name: EBrowserTools.EXTRACT,\r\n        description: `Extract content from the current page.\r\nReturns page URL, title, and element list.`,\r\n        schema: BrowserExtractSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_hover\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('hover'),\r\n      {\r\n        name: EBrowserTools.HOVER,\r\n        description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.\r\nAfter hovering, you receive an updated element list with any newly revealed elements.`,\r\n        schema: BrowserHoverSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_wait\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('wait'),\r\n      {\r\n        name: EBrowserTools.WAIT,\r\n        description: `Wait for a specified duration for page content to load.\r\nUse this after actions that trigger async content loading.\r\nAfter waiting, you receive an updated element list.`,\r\n        schema: BrowserWaitSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_back\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('back'),\r\n      {\r\n        name: EBrowserTools.BACK,\r\n        description: `Go back to the previous page in browser history.\r\nAfter going back, you receive the previous page's element list.`,\r\n        schema: BrowserBackSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_screenshot\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('screenshot'),\r\n      {\r\n        name: EBrowserTools.SCREENSHOT,\r\n        description: `Capture a screenshot of the current page.\r\nReturns the page state with a note that screenshot was displayed to the user.\r\nUse browser_get_page_state to get the element list for automation.`,\r\n        schema: BrowserScreenshotSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  // browser_get_page_state\r\n  tools.push(\r\n    tool(\r\n      createToolFunction('get_page_state'),\r\n      {\r\n        name: EBrowserTools.GET_PAGE_STATE,\r\n        description: `Get the current page state including URL, title, and all interactive elements.\r\nUse this at the start of a task to see what elements are available.\r\nReturns a text list of elements with their index numbers for interaction.`,\r\n        schema: BrowserGetPageStateSchema,\r\n      }\r\n    )\r\n  );\r\n\r\n  return tools;\r\n}\r\n"],"names":[],"mappings":"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"}

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

@@ -16,6 +16,28 @@ export declare const EBrowserTools: {
     readonly GET_PAGE_STATE: "browser_get_page_state";
 };
 export type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];
+/**
+ * Callback function type for waiting on browser action results
+ * This allows the server (Ranger) to provide a callback that waits for the extension
+ * to POST results back to the server before returning to the LLM.
+ *
+ * @param action - The browser action (click, type, navigate, etc.)
+ * @param args - Arguments for the action
+ * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)
+ * @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>;
+/**
+ * Result returned from browser action execution
+ */
+export interface BrowserActionResult {
+    success: boolean;
+    url?: string;
+    title?: string;
+    elementList?: string;
+    error?: string;
+    screenshot?: string;
+}
 /**
  * Check if browser capability is available based on request headers or context
  * The browser extension sets these headers when connected:
@@ -33,13 +55,31 @@ export interface BrowserToolResponse {
     requiresBrowserExecution: true;
     action: string;
     args: Record<string, unknown>;
+    toolCallId?: string;
 }
 /**
- * Create placeholder browser tools that signal to the extension to execute locally
- * The server creates these tools to give the LLM the schema, but actual execution
- * happens in the browser extension which intercepts tool calls
+ * Options for creating browser tools
+ */
+export interface CreateBrowserToolsOptions {
+    /**
+     * Optional callback that waits for browser action results.
+     * When provided, tools will await this callback to get actual results from the extension.
+     * When not provided, tools return markers immediately (for non-server contexts).
+     */
+    waitForResult?: BrowserToolCallback;
+}
+/**
+ * Create browser tools with optional callback for waiting on results
+ *
+ * When waitForResult callback is provided:
+ * 1. Tool returns marker that triggers extension
+ * 2. Tool then awaits callback to get actual results
+ * 3. Returns real page state to LLM
+ *
+ * When no callback:
+ * 1. Tool returns marker only (for non-server contexts)
  *
  * NOTE: These tools use TEXT-BASED element lists, NOT screenshots
  * Screenshots would be 100K+ tokens each - element lists are ~100 tokens
  */
-export declare function createBrowserTools(): DynamicStructuredTool[];
+export declare function createBrowserTools(options?: CreateBrowserToolsOptions): DynamicStructuredTool[];

package/package.json

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

package/src/tools/BrowserTools.ts

@@ -21,6 +21,34 @@ export const EBrowserTools = {
 
 export type BrowserToolName = typeof EBrowserTools[keyof typeof EBrowserTools];
 
+/**
+ * Callback function type for waiting on browser action results
+ * This allows the server (Ranger) to provide a callback that waits for the extension
+ * to POST results back to the server before returning to the LLM.
+ * 
+ * @param action - The browser action (click, type, navigate, etc.)
+ * @param args - Arguments for the action
+ * @param toolCallId - Unique ID for this tool call (from config.toolCall.id)
+ * @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>;
+
+/**
+ * Result returned from browser action execution
+ */
+export interface BrowserActionResult {
+  success: boolean;
+  url?: string;
+  title?: string;
+  elementList?: string;  // Text-based element list
+  error?: string;
+  screenshot?: string;   // Base64 screenshot (if requested)
+}
+
 /**
  * Check if browser capability is available based on request headers or context
  * The browser extension sets these headers when connected:
@@ -84,31 +112,106 @@ export interface BrowserToolResponse {
   requiresBrowserExecution: true;
   action: string;
   args: Record<string, unknown>;
+  toolCallId?: string;  // Added to help extension correlate with callback
 }
 
 /**
- * Create placeholder browser tools that signal to the extension to execute locally
- * The server creates these tools to give the LLM the schema, but actual execution
- * happens in the browser extension which intercepts tool calls
+ * Options for creating browser tools
+ */
+export interface CreateBrowserToolsOptions {
+  /**
+   * Optional callback that waits for browser action results.
+   * When provided, tools will await this callback to get actual results from the extension.
+   * When not provided, tools return markers immediately (for non-server contexts).
+   */
+  waitForResult?: BrowserToolCallback;
+}
+
+/**
+ * Format browser action result for LLM consumption
+ */
+function formatResultForLLM(result: BrowserActionResult, action: string): string {
+  if (!result.success && result.error) {
+    return `Browser action "${action}" failed: ${result.error}`;
+  }
+
+  const parts: string[] = [];
+  
+  if (result.url) {
+    parts.push(`**Current URL:** ${result.url}`);
+  }
+  if (result.title) {
+    parts.push(`**Page Title:** ${result.title}`);
+  }
+  if (result.elementList) {
+    parts.push(`\n**Interactive Elements:**\n${result.elementList}`);
+  }
+  if (result.screenshot) {
+    parts.push(`\n[Screenshot captured and displayed to user]`);
+  }
+  
+  if (parts.length === 0) {
+    return `Browser action "${action}" completed successfully.`;
+  }
+  
+  return parts.join('\n');
+}
+
+/**
+ * Create browser tools with optional callback for waiting on results
+ * 
+ * When waitForResult callback is provided:
+ * 1. Tool returns marker that triggers extension
+ * 2. Tool then awaits callback to get actual results
+ * 3. Returns real page state to LLM
+ * 
+ * When no callback:
+ * 1. Tool returns marker only (for non-server contexts)
  * 
  * NOTE: These tools use TEXT-BASED element lists, NOT screenshots
  * Screenshots would be 100K+ tokens each - element lists are ~100 tokens
  */
-export function createBrowserTools(): DynamicStructuredTool[] {
+export function createBrowserTools(options?: CreateBrowserToolsOptions): DynamicStructuredTool[] {
+  const { waitForResult } = options || {};
   const tools: DynamicStructuredTool[] = [];
 
+  /**
+   * Helper to create tool function that optionally waits for results
+   * The toolCallId is extracted from the RunnableConfig passed by LangChain
+   */
+  const createToolFunction = (action: string) => {
+    return async (args: Record<string, unknown>, config?: { toolCall?: { id?: string } }): Promise<string> => {
+      const toolCallId = config?.toolCall?.id || `tool_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      
+      // Create marker for extension
+      const marker: BrowserToolResponse = {
+        requiresBrowserExecution: true,
+        action,
+        args,
+        toolCallId,
+      };
+      
+      // If no callback, return marker immediately (extension handles via SSE interception)
+      if (!waitForResult) {
+        return JSON.stringify(marker);
+      }
+      
+      // With callback: wait for actual results from extension
+      // 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);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return `Browser action "${action}" failed: ${errorMessage}`;
+      }
+    };
+  };
+
   // browser_click
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        // This returns a marker that tells the extension to execute locally
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'click',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('click'),
       {
         name: EBrowserTools.CLICK,
         description: `Click an element on the current web page by its index number.
@@ -123,14 +226,7 @@ After clicking, you receive an updated element list showing the new page state.`
   // browser_type
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'type',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('type'),
       {
         name: EBrowserTools.TYPE,
         description: `Type text into an input element on the page.
@@ -145,14 +241,7 @@ After typing, you receive an updated element list.`,
   // browser_navigate
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'navigate',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('navigate'),
       {
         name: EBrowserTools.NAVIGATE,
         description: `Navigate to a URL. Always include the full URL with https://.
@@ -165,14 +254,7 @@ After navigation, you receive the new page's element list.`,
   // browser_scroll
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'scroll',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('scroll'),
       {
         name: EBrowserTools.SCROLL,
         description: `Scroll the page to reveal more content.
@@ -186,14 +268,7 @@ After scrolling, you receive an updated element list with newly visible elements
   // browser_extract
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'extract',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('extract'),
       {
         name: EBrowserTools.EXTRACT,
         description: `Extract content from the current page.
@@ -206,14 +281,7 @@ Returns page URL, title, and element list.`,
   // browser_hover
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'hover',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('hover'),
       {
         name: EBrowserTools.HOVER,
         description: `Hover over an element to reveal tooltips, dropdowns, or other hover-triggered content.
@@ -226,14 +294,7 @@ After hovering, you receive an updated element list with any newly revealed elem
   // browser_wait
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'wait',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('wait'),
       {
         name: EBrowserTools.WAIT,
         description: `Wait for a specified duration for page content to load.
@@ -247,14 +308,7 @@ After waiting, you receive an updated element list.`,
   // browser_back
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'back',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('back'),
       {
         name: EBrowserTools.BACK,
         description: `Go back to the previous page in browser history.
@@ -267,19 +321,12 @@ After going back, you receive the previous page's element list.`,
   // browser_screenshot
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'screenshot',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      createToolFunction('screenshot'),
       {
         name: EBrowserTools.SCREENSHOT,
         description: `Capture a screenshot of the current page.
-NOTE: Screenshot is displayed to the USER only, not returned to you.
-Use browser_get_page_state instead to get the element list.`,
+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.`,
         schema: BrowserScreenshotSchema,
       }
     )
@@ -288,19 +335,12 @@ Use browser_get_page_state instead to get the element list.`,
   // browser_get_page_state
   tools.push(
     tool(
-      async (args): Promise<string> => {
-        const response: BrowserToolResponse = {
-          requiresBrowserExecution: true,
-          action: 'get_page_state',
-          args,
-        };
-        return JSON.stringify(response);
-      },
+      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.`,
+Returns a text list of elements with their index numbers for interaction.`,
         schema: BrowserGetPageStateSchema,
       }
     )