illuma-agents 1.0.18 → 1.0.19

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

@@ -0,0 +1,244 @@
+/**
+ * Browser Automation Tools for Ranger Browser Extension
+ *
+ * These tools allow the LLM to interact with the browser through the
+ * ranger-browser extension. They generate structured actions that are
+ * sent to the extension via SSE streaming for execution.
+ *
+ * The extension handles:
+ * - DOM extraction with element indexing
+ * - Click, type, hover, scroll actions
+ * - Navigation and page context
+ * - Visual element highlighting
+ */
+import { z } from 'zod';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+/**
+ * Enhanced click schema that supports both index-based and coordinate-based clicking
+ */
+declare const BrowserClickSchema: z.ZodObject<{
+    index: z.ZodOptional<z.ZodNumber>;
+    coordinates: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        y: number;
+        x: number;
+    }, {
+        y: number;
+        x: number;
+    }>>;
+    visualDescription: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    index?: number | undefined;
+    coordinates?: {
+        y: number;
+        x: number;
+    } | undefined;
+    visualDescription?: string | undefined;
+    reason?: string | undefined;
+}, {
+    index?: number | undefined;
+    coordinates?: {
+        y: number;
+        x: number;
+    } | undefined;
+    visualDescription?: string | undefined;
+    reason?: string | undefined;
+}>;
+declare const BrowserTypeSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    text: z.ZodString;
+    clear: z.ZodOptional<z.ZodBoolean>;
+    pressEnter: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    index: number;
+    clear?: boolean | undefined;
+    pressEnter?: boolean | undefined;
+}, {
+    text: string;
+    index: number;
+    clear?: boolean | undefined;
+    pressEnter?: boolean | undefined;
+}>;
+declare const BrowserNavigateSchema: z.ZodObject<{
+    url: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    reason?: string | undefined;
+}, {
+    url: string;
+    reason?: string | undefined;
+}>;
+declare const BrowserScrollSchema: z.ZodObject<{
+    direction: z.ZodEnum<["up", "down", "left", "right"]>;
+    amount: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    direction: "up" | "down" | "left" | "right";
+    amount?: number | undefined;
+}, {
+    direction: "up" | "down" | "left" | "right";
+    amount?: number | undefined;
+}>;
+declare const BrowserExtractSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    query?: string | undefined;
+    selector?: string | undefined;
+}, {
+    query?: string | undefined;
+    selector?: string | undefined;
+}>;
+declare const BrowserHoverSchema: z.ZodObject<{
+    index: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    index: number;
+}, {
+    index: number;
+}>;
+declare const BrowserWaitSchema: z.ZodObject<{
+    duration: z.ZodOptional<z.ZodNumber>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    duration?: number | undefined;
+    reason?: string | undefined;
+}, {
+    duration?: number | undefined;
+    reason?: string | undefined;
+}>;
+declare const BrowserGoBackSchema: z.ZodObject<{
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    reason?: string | undefined;
+}, {
+    reason?: string | undefined;
+}>;
+declare const BrowserScreenshotSchema: z.ZodObject<{
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    reason?: string | undefined;
+    fullPage?: boolean | undefined;
+}, {
+    reason?: string | undefined;
+    fullPage?: boolean | undefined;
+}>;
+/**
+ * Browser click tool - clicks an element by index or coordinates
+ * Supports both semantic (index-based) and vision (coordinate-based) clicking
+ */
+export declare function createBrowserClickTool(): DynamicStructuredTool<typeof BrowserClickSchema>;
+/**
+ * Browser type tool - types text into an input field
+ */
+export declare function createBrowserTypeTool(): DynamicStructuredTool<typeof BrowserTypeSchema>;
+/**
+ * Browser navigate tool - navigates to a URL
+ */
+export declare function createBrowserNavigateTool(): DynamicStructuredTool<typeof BrowserNavigateSchema>;
+/**
+ * Browser scroll tool - scrolls the page
+ */
+export declare function createBrowserScrollTool(): DynamicStructuredTool<typeof BrowserScrollSchema>;
+/**
+ * Browser extract tool - extracts content from the page
+ */
+export declare function createBrowserExtractTool(): DynamicStructuredTool<typeof BrowserExtractSchema>;
+/**
+ * Browser hover tool - hovers over an element
+ */
+export declare function createBrowserHoverTool(): DynamicStructuredTool<typeof BrowserHoverSchema>;
+/**
+ * Browser wait tool - waits for a specified duration
+ */
+export declare function createBrowserWaitTool(): DynamicStructuredTool<typeof BrowserWaitSchema>;
+/**
+ * Browser go back tool - navigates back in history
+ */
+export declare function createBrowserGoBackTool(): DynamicStructuredTool<typeof BrowserGoBackSchema>;
+/**
+ * Browser screenshot tool - captures a screenshot
+ */
+export declare function createBrowserScreenshotTool(): DynamicStructuredTool<typeof BrowserScreenshotSchema>;
+export type BrowserToolsConfig = {
+    /** Enable click tool */
+    enableClick?: boolean;
+    /** Enable type tool */
+    enableType?: boolean;
+    /** Enable navigate tool */
+    enableNavigate?: boolean;
+    /** Enable scroll tool */
+    enableScroll?: boolean;
+    /** Enable extract tool */
+    enableExtract?: boolean;
+    /** Enable hover tool */
+    enableHover?: boolean;
+    /** Enable wait tool */
+    enableWait?: boolean;
+    /** Enable back tool */
+    enableBack?: boolean;
+    /** Enable screenshot tool */
+    enableScreenshot?: boolean;
+};
+/**
+ * Create all browser automation tools
+ *
+ * IMPORTANT: These tools should ONLY be registered when:
+ * 1. The request comes from a browser extension that can execute them
+ * 2. The client has indicated browser capability (e.g., via header or parameter)
+ *
+ * DO NOT register these for normal web UI users - they cannot execute browser actions.
+ *
+ * Detection in Ranger API:
+ * - Check for `X-Ranger-Browser-Extension: true` header
+ * - Or check for `browserCapable: true` in request body
+ * - Or check user agent for extension identifier
+ *
+ * @example
+ * // In Ranger API endpoint:
+ * const hasBrowserExtension = req.headers['x-ranger-browser-extension'] === 'true';
+ * const tools = hasBrowserExtension
+ *   ? [...normalTools, ...createBrowserTools()]
+ *   : normalTools;
+ */
+export declare function createBrowserTools(config?: BrowserToolsConfig): DynamicStructuredTool[];
+/**
+ * Browser tool name constants
+ * Use these instead of magic strings
+ */
+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";
+};
+/**
+ * Get browser tool names for filtering/identification
+ */
+export declare const BROWSER_TOOL_NAMES: readonly ["browser_click", "browser_type", "browser_navigate", "browser_scroll", "browser_extract", "browser_hover", "browser_wait", "browser_back", "browser_screenshot"];
+export type BrowserToolName = typeof BROWSER_TOOL_NAMES[number];
+/**
+ * Check if a tool call is a browser action
+ */
+export declare function isBrowserToolCall(toolName: string): toolName is BrowserToolName;
+/**
+ * Check if request indicates browser extension capability
+ * Use this to conditionally register browser tools
+ *
+ * @example
+ * // In Express middleware or endpoint:
+ * if (hasBrowserCapability(req.headers)) {
+ *   tools.push(...createBrowserTools());
+ * }
+ */
+export declare function hasBrowserCapability(headers: Record<string, string | string[] | undefined>): boolean;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "illuma-agents",
-  "version": "1.0.18",
+  "version": "1.0.19",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -13,6 +13,10 @@
   },
   "type": "module",
   "description": "Illuma AI Agents Library",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codevakure/agents"
+  },
   "author": "Illuma Team",
   "license": "MIT",
   "packageManager": "npm@10.5.2",

package/src/index.ts

@@ -13,6 +13,7 @@ export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearchRegex';
+export * from './tools/BrowserTools';
 export * from './tools/handlers';
 export * from './tools/search';