illuma-agents 1.0.25 → 1.0.27

package/dist/cjs/main.cjs

@@ -15,6 +15,7 @@ var Graph = require('./graphs/Graph.cjs');
 var MultiAgentGraph = require('./graphs/MultiAgentGraph.cjs');
 var Calculator = require('./tools/Calculator.cjs');
 var CodeExecutor = require('./tools/CodeExecutor.cjs');
+var BrowserTools = require('./tools/BrowserTools.cjs');
 var ProgrammaticToolCalling = require('./tools/ProgrammaticToolCalling.cjs');
 var ToolSearchRegex = require('./tools/ToolSearchRegex.cjs');
 var handlers = require('./tools/handlers.cjs');
@@ -29,9 +30,6 @@ var tokens = require('./utils/tokens.cjs');
 var toonFormat = require('./utils/toonFormat.cjs');
 var contextAnalytics = require('./utils/contextAnalytics.cjs');
 var index = require('./llm/openai/index.cjs');
-var index$1 = require('./llm/anthropic/index.cjs');
-var index$2 = require('./llm/bedrock/index.cjs');
-var providers = require('./llm/providers.cjs');
 
 
 
@@ -83,6 +81,9 @@ exports.Calculator = Calculator.Calculator;
 exports.createCodeExecutionTool = CodeExecutor.createCodeExecutionTool;
 exports.getCodeBaseURL = CodeExecutor.getCodeBaseURL;
 exports.imageExtRegex = CodeExecutor.imageExtRegex;
+exports.EBrowserTools = BrowserTools.EBrowserTools;
+exports.createBrowserTools = BrowserTools.createBrowserTools;
+exports.hasBrowserCapability = BrowserTools.hasBrowserCapability;
 exports.createProgrammaticToolCallingTool = ProgrammaticToolCalling.createProgrammaticToolCallingTool;
 exports.executeTools = ProgrammaticToolCalling.executeTools;
 exports.extractUsedToolNames = ProgrammaticToolCalling.extractUsedToolNames;
@@ -174,14 +175,5 @@ exports.isToonFormat = toonFormat.isToonFormat;
 exports.jsonToToon = toonFormat.jsonToToon;
 exports.processToolOutput = toonFormat.processToolOutput;
 exports.buildContextAnalytics = contextAnalytics.buildContextAnalytics;
-exports.AzureChatOpenAI = index.AzureChatOpenAI;
-exports.ChatDeepSeek = index.ChatDeepSeek;
-exports.ChatOpenAI = index.ChatOpenAI;
-exports.ChatXAI = index.ChatXAI;
 exports.CustomOpenAIClient = index.CustomOpenAIClient;
-exports.CustomAnthropic = index$1.CustomAnthropic;
-exports.CustomChatBedrockConverse = index$2.CustomChatBedrockConverse;
-exports.getChatModelClass = providers.getChatModelClass;
-exports.llmProviders = providers.llmProviders;
-exports.manualToolStreamProviders = providers.manualToolStreamProviders;
 //# sourceMappingURL=main.cjs.map

package/dist/cjs/main.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/tools/BrowserTools.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+var zod = require('zod');
+var tools = require('@langchain/core/tools');
+
+/**
+ * Browser tool names - keep in sync with ranger-browser extension
+ * These tools execute locally in the browser extension, NOT on the server
+ */
+const EBrowserTools = {
+    CLICK: 'browser_click',
+    TYPE: 'browser_type',
+    NAVIGATE: 'browser_navigate',
+    SCROLL: 'browser_scroll',
+    EXTRACT: 'browser_extract',
+    HOVER: 'browser_hover',
+    WAIT: 'browser_wait',
+    BACK: 'browser_back',
+    SCREENSHOT: 'browser_screenshot',
+    GET_PAGE_STATE: 'browser_get_page_state',
+};
+/**
+ * Check if browser capability is available based on request headers or context
+ * The browser extension sets these headers when connected:
+ * - X-Ranger-Browser-Extension: true
+ * - X-Ranger-Browser-Capable: true
+ */
+function hasBrowserCapability(req) {
+    if (!req?.headers) {
+        return false;
+    }
+    const browserExtension = req.headers['x-ranger-browser-extension'];
+    const browserCapable = req.headers['x-ranger-browser-capable'];
+    return browserExtension === 'true' || browserCapable === 'true';
+}
+// Tool schemas
+const BrowserClickSchema = zod.z.object({
+    index: zod.z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),
+});
+const BrowserTypeSchema = zod.z.object({
+    index: zod.z.number().describe('The index number of the input element to type into'),
+    text: zod.z.string().describe('The text to type into the element'),
+    pressEnter: zod.z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),
+});
+const BrowserNavigateSchema = zod.z.object({
+    url: zod.z.string().describe('The full URL to navigate to (must include https://)'),
+});
+const BrowserScrollSchema = zod.z.object({
+    direction: zod.z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),
+    amount: zod.z.number().optional().describe('Pixels to scroll (default: one viewport height)'),
+});
+const BrowserExtractSchema = zod.z.object({
+    query: zod.z.string().optional().describe('Optional: specific content to extract from the page'),
+});
+const BrowserHoverSchema = zod.z.object({
+    index: zod.z.number().describe('The index number of the element to hover over'),
+});
+const BrowserWaitSchema = zod.z.object({
+    duration: zod.z.number().optional().describe('Milliseconds to wait (default: 1000)'),
+});
+const BrowserBackSchema = zod.z.object({});
+const BrowserScreenshotSchema = zod.z.object({});
+const BrowserGetPageStateSchema = zod.z.object({});
+/**
+ * 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(options) {
+    const { waitForResult } = options || {};
+    const tools$1 = [];
+    /**
+     * 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}`;
+            }
+        };
+    };
+    // 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>
+Use the index number in brackets to click that element.
+After clicking, you receive an updated element list showing the new page state.`,
+        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.`,
+        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.`,
+        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.`,
+        schema: BrowserScrollSchema,
+    }));
+    // browser_extract
+    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(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(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.
+After waiting, you receive an updated element list.`,
+        schema: BrowserWaitSchema,
+    }));
+    // browser_back
+    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(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.`,
+        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.`,
+        schema: BrowserGetPageStateSchema,
+    }));
+    return tools$1;
+}
+
+exports.EBrowserTools = EBrowserTools;
+exports.createBrowserTools = createBrowserTools;
+exports.hasBrowserCapability = hasBrowserCapability;
+//# sourceMappingURL=BrowserTools.cjs.map

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

@@ -0,0 +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 * 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/main.mjs

@@ -13,6 +13,7 @@ export { Graph, StandardGraph } from './graphs/Graph.mjs';
 export { MultiAgentGraph } from './graphs/MultiAgentGraph.mjs';
 export { Calculator } from './tools/Calculator.mjs';
 export { createCodeExecutionTool, getCodeBaseURL, imageExtRegex } from './tools/CodeExecutor.mjs';
+export { EBrowserTools, createBrowserTools, hasBrowserCapability } from './tools/BrowserTools.mjs';
 export { createProgrammaticToolCallingTool, executeTools, extractUsedToolNames, fetchSessionFiles, filterToolsByUsage, formatCompletedResponse, makeRequest, normalizeToPythonIdentifier, unwrapToolResponse } from './tools/ProgrammaticToolCalling.mjs';
 export { countNestedGroups, createToolSearchRegexTool, escapeRegexSpecialChars, hasNestedQuantifiers, isDangerousPattern, sanitizeRegex } from './tools/ToolSearchRegex.mjs';
 export { handleServerToolResult, handleToolCallChunks, handleToolCalls, toolResultTypes } from './tools/handlers.mjs';
@@ -26,8 +27,5 @@ export { RunnableCallable, sleep } from './utils/run.mjs';
 export { TokenEncoderManager, createTokenCounter, getTokenCountForMessage } from './utils/tokens.mjs';
 export { ensureToonLoaded, extractFirstJson, isToonAvailable, isToonFormat, jsonToToon, processToolOutput } from './utils/toonFormat.mjs';
 export { buildContextAnalytics } from './utils/contextAnalytics.mjs';
-export { AzureChatOpenAI, ChatDeepSeek, ChatOpenAI, ChatXAI, CustomOpenAIClient } from './llm/openai/index.mjs';
-export { CustomAnthropic } from './llm/anthropic/index.mjs';
-export { CustomChatBedrockConverse } from './llm/bedrock/index.mjs';
-export { getChatModelClass, llmProviders, manualToolStreamProviders } from './llm/providers.mjs';
+export { CustomOpenAIClient } from './llm/openai/index.mjs';
 //# sourceMappingURL=main.mjs.map

package/dist/esm/main.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/tools/BrowserTools.mjs

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { tool } from '@langchain/core/tools';
+
+/**
+ * Browser tool names - keep in sync with ranger-browser extension
+ * These tools execute locally in the browser extension, NOT on the server
+ */
+const EBrowserTools = {
+    CLICK: 'browser_click',
+    TYPE: 'browser_type',
+    NAVIGATE: 'browser_navigate',
+    SCROLL: 'browser_scroll',
+    EXTRACT: 'browser_extract',
+    HOVER: 'browser_hover',
+    WAIT: 'browser_wait',
+    BACK: 'browser_back',
+    SCREENSHOT: 'browser_screenshot',
+    GET_PAGE_STATE: 'browser_get_page_state',
+};
+/**
+ * Check if browser capability is available based on request headers or context
+ * The browser extension sets these headers when connected:
+ * - X-Ranger-Browser-Extension: true
+ * - X-Ranger-Browser-Capable: true
+ */
+function hasBrowserCapability(req) {
+    if (!req?.headers) {
+        return false;
+    }
+    const browserExtension = req.headers['x-ranger-browser-extension'];
+    const browserCapable = req.headers['x-ranger-browser-capable'];
+    return browserExtension === 'true' || browserCapable === 'true';
+}
+// Tool schemas
+const BrowserClickSchema = z.object({
+    index: z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),
+});
+const BrowserTypeSchema = z.object({
+    index: z.number().describe('The index number of the input element to type into'),
+    text: z.string().describe('The text to type into the element'),
+    pressEnter: z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),
+});
+const BrowserNavigateSchema = z.object({
+    url: z.string().describe('The full URL to navigate to (must include https://)'),
+});
+const BrowserScrollSchema = z.object({
+    direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),
+    amount: z.number().optional().describe('Pixels to scroll (default: one viewport height)'),
+});
+const BrowserExtractSchema = z.object({
+    query: z.string().optional().describe('Optional: specific content to extract from the page'),
+});
+const BrowserHoverSchema = z.object({
+    index: z.number().describe('The index number of the element to hover over'),
+});
+const BrowserWaitSchema = z.object({
+    duration: z.number().optional().describe('Milliseconds to wait (default: 1000)'),
+});
+const BrowserBackSchema = z.object({});
+const BrowserScreenshotSchema = z.object({});
+const BrowserGetPageStateSchema = z.object({});
+/**
+ * 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(options) {
+    const { waitForResult } = options || {};
+    const tools = [];
+    /**
+     * 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}`;
+            }
+        };
+    };
+    // 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>
+Use the index number in brackets to click that element.
+After clicking, you receive an updated element list showing the new page state.`,
+        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.`,
+        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.`,
+        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.`,
+        schema: BrowserScrollSchema,
+    }));
+    // browser_extract
+    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(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(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.
+After waiting, you receive an updated element list.`,
+        schema: BrowserWaitSchema,
+    }));
+    // browser_back
+    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(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.`,
+        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.`,
+        schema: BrowserGetPageStateSchema,
+    }));
+    return tools;
+}
+
+export { EBrowserTools, createBrowserTools, hasBrowserCapability };
+//# sourceMappingURL=BrowserTools.mjs.map

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

@@ -0,0 +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 * 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/index.d.ts

@@ -6,6 +6,7 @@ export * from './messages';
 export * from './graphs';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BrowserTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearchRegex';
 export * from './tools/handlers';
@@ -13,7 +14,4 @@ export * from './tools/search';
 export * from './common';
 export * from './utils';
 export type * from './types';
-export { CustomOpenAIClient, ChatOpenAI, ChatDeepSeek, ChatXAI, AzureChatOpenAI } from './llm/openai';
-export { CustomAnthropic } from './llm/anthropic';
-export { CustomChatBedrockConverse } from './llm/bedrock';
-export { llmProviders, getChatModelClass, manualToolStreamProviders } from './llm/providers';
+export { CustomOpenAIClient } from './llm/openai';

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

@@ -0,0 +1,85 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+/**
+ * Browser tool names - keep in sync with ranger-browser extension
+ * These tools execute locally in the browser extension, NOT on the server
+ */
+export declare const EBrowserTools: {
+    readonly CLICK: "browser_click";
+    readonly TYPE: "browser_type";
+    readonly NAVIGATE: "browser_navigate";
+    readonly SCROLL: "browser_scroll";
+    readonly EXTRACT: "browser_extract";
+    readonly HOVER: "browser_hover";
+    readonly WAIT: "browser_wait";
+    readonly BACK: "browser_back";
+    readonly SCREENSHOT: "browser_screenshot";
+    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:
+ * - X-Ranger-Browser-Extension: true
+ * - X-Ranger-Browser-Capable: true
+ */
+export declare function hasBrowserCapability(req?: {
+    headers?: Record<string, string | string[] | undefined>;
+}): boolean;
+/**
+ * Browser tool response interface
+ * This is what the extension returns after executing the action
+ */
+export interface BrowserToolResponse {
+    requiresBrowserExecution: true;
+    action: string;
+    args: Record<string, unknown>;
+    toolCallId?: string;
+}
+/**
+ * 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(options?: CreateBrowserToolsOptions): DynamicStructuredTool[];

package/package.json

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

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './graphs';
 /* Tools */
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BrowserTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearchRegex';
 export * from './tools/handlers';
@@ -23,8 +24,5 @@ export * from './utils';
 /* Types */
 export type * from './types';
 
-/* LLM Providers */
-export { CustomOpenAIClient, ChatOpenAI, ChatDeepSeek, ChatXAI, AzureChatOpenAI } from './llm/openai';
-export { CustomAnthropic } from './llm/anthropic';
-export { CustomChatBedrockConverse } from './llm/bedrock';
-export { llmProviders, getChatModelClass, manualToolStreamProviders } from './llm/providers';
+/* LLM */
+export { CustomOpenAIClient } from './llm/openai';

package/src/tools/BrowserTools.ts

@@ -0,0 +1,350 @@
+import { z } from 'zod';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+
+/**
+ * Browser tool names - keep in sync with ranger-browser extension
+ * These tools execute locally in the browser extension, NOT on the server
+ */
+export const EBrowserTools = {
+  CLICK: 'browser_click',
+  TYPE: 'browser_type',
+  NAVIGATE: 'browser_navigate',
+  SCROLL: 'browser_scroll',
+  EXTRACT: 'browser_extract',
+  HOVER: 'browser_hover',
+  WAIT: 'browser_wait',
+  BACK: 'browser_back',
+  SCREENSHOT: 'browser_screenshot',
+  GET_PAGE_STATE: 'browser_get_page_state',
+} as const;
+
+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:
+ * - X-Ranger-Browser-Extension: true
+ * - X-Ranger-Browser-Capable: true
+ */
+export function hasBrowserCapability(req?: { headers?: Record<string, string | string[] | undefined> }): boolean {
+  if (!req?.headers) {
+    return false;
+  }
+  
+  const browserExtension = req.headers['x-ranger-browser-extension'];
+  const browserCapable = req.headers['x-ranger-browser-capable'];
+  
+  return browserExtension === 'true' || browserCapable === 'true';
+}
+
+// Tool schemas
+const BrowserClickSchema = z.object({
+  index: z.number().describe('The index number [0], [1], etc. of the element to click from the page state element list'),
+});
+
+const BrowserTypeSchema = z.object({
+  index: z.number().describe('The index number of the input element to type into'),
+  text: z.string().describe('The text to type into the element'),
+  pressEnter: z.boolean().optional().describe('Whether to press Enter after typing (useful for search forms)'),
+});
+
+const BrowserNavigateSchema = z.object({
+  url: z.string().describe('The full URL to navigate to (must include https://)'),
+});
+
+const BrowserScrollSchema = z.object({
+  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll'),
+  amount: z.number().optional().describe('Pixels to scroll (default: one viewport height)'),
+});
+
+const BrowserExtractSchema = z.object({
+  query: z.string().optional().describe('Optional: specific content to extract from the page'),
+});
+
+const BrowserHoverSchema = z.object({
+  index: z.number().describe('The index number of the element to hover over'),
+});
+
+const BrowserWaitSchema = z.object({
+  duration: z.number().optional().describe('Milliseconds to wait (default: 1000)'),
+});
+
+const BrowserBackSchema = z.object({});
+
+const BrowserScreenshotSchema = z.object({});
+
+const BrowserGetPageStateSchema = z.object({});
+
+/**
+ * Browser tool response interface
+ * This is what the extension returns after executing the action
+ */
+export interface BrowserToolResponse {
+  requiresBrowserExecution: true;
+  action: string;
+  args: Record<string, unknown>;
+  toolCallId?: string;  // Added to help extension correlate with callback
+}
+
+/**
+ * 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(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(
+      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.`,
+        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.`,
+        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.`,
+        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.`,
+        schema: BrowserScrollSchema,
+      }
+    )
+  );
+
+  // browser_extract
+  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(
+      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(
+      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.
+After waiting, you receive an updated element list.`,
+        schema: BrowserWaitSchema,
+      }
+    )
+  );
+
+  // browser_back
+  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(
+      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.`,
+        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.`,
+        schema: BrowserGetPageStateSchema,
+      }
+    )
+  );
+
+  return tools;
+}

package/src/tools/__tests__/BrowserTools.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals';
+import {
+  createBrowserTools,
+  hasBrowserCapability,
+  EBrowserTools,
+  type BrowserToolResponse,
+} from '../BrowserTools';
+
+describe('BrowserTools', () => {
+  describe('EBrowserTools enum', () => {
+    it('should have all expected browser tool names', () => {
+      expect(EBrowserTools.CLICK).toBe('browser_click');
+      expect(EBrowserTools.TYPE).toBe('browser_type');
+      expect(EBrowserTools.NAVIGATE).toBe('browser_navigate');
+      expect(EBrowserTools.SCROLL).toBe('browser_scroll');
+      expect(EBrowserTools.EXTRACT).toBe('browser_extract');
+      expect(EBrowserTools.HOVER).toBe('browser_hover');
+      expect(EBrowserTools.WAIT).toBe('browser_wait');
+      expect(EBrowserTools.BACK).toBe('browser_back');
+      expect(EBrowserTools.SCREENSHOT).toBe('browser_screenshot');
+      expect(EBrowserTools.GET_PAGE_STATE).toBe('browser_get_page_state');
+    });
+
+    it('should have exactly 10 browser tools', () => {
+      expect(Object.keys(EBrowserTools).length).toBe(10);
+    });
+  });
+
+  describe('hasBrowserCapability', () => {
+    it('should return false when no request is provided', () => {
+      expect(hasBrowserCapability()).toBe(false);
+      expect(hasBrowserCapability(undefined)).toBe(false);
+    });
+
+    it('should return false when request has no headers', () => {
+      expect(hasBrowserCapability({})).toBe(false);
+      expect(hasBrowserCapability({ headers: undefined })).toBe(false);
+    });
+
+    it('should return true when X-Ranger-Browser-Extension header is true', () => {
+      const req = {
+        headers: {
+          'x-ranger-browser-extension': 'true',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(true);
+    });
+
+    it('should return true when X-Ranger-Browser-Capable header is true', () => {
+      const req = {
+        headers: {
+          'x-ranger-browser-capable': 'true',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(true);
+    });
+
+    it('should return false when browser headers are not true', () => {
+      const req = {
+        headers: {
+          'x-ranger-browser-extension': 'false',
+          'x-ranger-browser-capable': 'false',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(false);
+    });
+
+    it('should return false when browser headers are missing', () => {
+      const req = {
+        headers: {
+          'content-type': 'application/json',
+        },
+      };
+      expect(hasBrowserCapability(req)).toBe(false);
+    });
+  });
+
+  describe('createBrowserTools', () => {
+    let tools: ReturnType<typeof createBrowserTools>;
+
+    beforeEach(() => {
+      tools = createBrowserTools();
+    });
+
+    it('should create exactly 10 browser tools', () => {
+      expect(tools.length).toBe(10);
+    });
+
+    it('should create tools with correct names', () => {
+      const toolNames = tools.map(t => t.name);
+      expect(toolNames).toContain('browser_click');
+      expect(toolNames).toContain('browser_type');
+      expect(toolNames).toContain('browser_navigate');
+      expect(toolNames).toContain('browser_scroll');
+      expect(toolNames).toContain('browser_extract');
+      expect(toolNames).toContain('browser_hover');
+      expect(toolNames).toContain('browser_wait');
+      expect(toolNames).toContain('browser_back');
+      expect(toolNames).toContain('browser_screenshot');
+      expect(toolNames).toContain('browser_get_page_state');
+    });
+
+    it('should have descriptions for all tools', () => {
+      for (const tool of tools) {
+        expect(tool.description).toBeDefined();
+        expect(tool.description.length).toBeGreaterThan(0);
+      }
+    });
+
+    describe('browser_click tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const clickTool = tools.find(t => t.name === 'browser_click');
+        expect(clickTool).toBeDefined();
+        
+        const result = await clickTool!.invoke({ index: 5 });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('click');
+        expect(parsed.args).toEqual({ index: 5 });
+      });
+    });
+
+    describe('browser_type tool', () => {
+      it('should return requiresBrowserExecution marker with all args', async () => {
+        const typeTool = tools.find(t => t.name === 'browser_type');
+        expect(typeTool).toBeDefined();
+        
+        const result = await typeTool!.invoke({ 
+          index: 3, 
+          text: 'Hello World',
+          pressEnter: true 
+        });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('type');
+        expect(parsed.args.index).toBe(3);
+        expect(parsed.args.text).toBe('Hello World');
+        expect(parsed.args.pressEnter).toBe(true);
+      });
+    });
+
+    describe('browser_navigate tool', () => {
+      it('should return requiresBrowserExecution marker with URL', async () => {
+        const navigateTool = tools.find(t => t.name === 'browser_navigate');
+        expect(navigateTool).toBeDefined();
+        
+        const result = await navigateTool!.invoke({ url: 'https://example.com' });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('navigate');
+        expect(parsed.args.url).toBe('https://example.com');
+      });
+    });
+
+    describe('browser_scroll tool', () => {
+      it('should return requiresBrowserExecution marker with direction', async () => {
+        const scrollTool = tools.find(t => t.name === 'browser_scroll');
+        expect(scrollTool).toBeDefined();
+        
+        const result = await scrollTool!.invoke({ 
+          direction: 'down',
+          amount: 500 
+        });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('scroll');
+        expect(parsed.args.direction).toBe('down');
+        expect(parsed.args.amount).toBe(500);
+      });
+    });
+
+    describe('browser_hover tool', () => {
+      it('should return requiresBrowserExecution marker with index', async () => {
+        const hoverTool = tools.find(t => t.name === 'browser_hover');
+        expect(hoverTool).toBeDefined();
+        
+        const result = await hoverTool!.invoke({ index: 2 });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('hover');
+        expect(parsed.args.index).toBe(2);
+      });
+    });
+
+    describe('browser_wait tool', () => {
+      it('should return requiresBrowserExecution marker with duration', async () => {
+        const waitTool = tools.find(t => t.name === 'browser_wait');
+        expect(waitTool).toBeDefined();
+        
+        const result = await waitTool!.invoke({ duration: 2000 });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('wait');
+        expect(parsed.args.duration).toBe(2000);
+      });
+    });
+
+    describe('browser_back tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const backTool = tools.find(t => t.name === 'browser_back');
+        expect(backTool).toBeDefined();
+        
+        const result = await backTool!.invoke({});
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('back');
+      });
+    });
+
+    describe('browser_screenshot tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const screenshotTool = tools.find(t => t.name === 'browser_screenshot');
+        expect(screenshotTool).toBeDefined();
+        
+        const result = await screenshotTool!.invoke({});
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('screenshot');
+      });
+    });
+
+    describe('browser_get_page_state tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const pageStateTool = tools.find(t => t.name === 'browser_get_page_state');
+        expect(pageStateTool).toBeDefined();
+        
+        const result = await pageStateTool!.invoke({});
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('get_page_state');
+      });
+    });
+
+    describe('browser_extract tool', () => {
+      it('should return requiresBrowserExecution marker', async () => {
+        const extractTool = tools.find(t => t.name === 'browser_extract');
+        expect(extractTool).toBeDefined();
+        
+        const result = await extractTool!.invoke({ query: 'main content' });
+        const parsed: BrowserToolResponse = JSON.parse(result);
+        
+        expect(parsed.requiresBrowserExecution).toBe(true);
+        expect(parsed.action).toBe('extract');
+        expect(parsed.args.query).toBe('main content');
+      });
+    });
+  });
+});