illuma-agents 1.0.23 → 1.0.25

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

@@ -1,282 +0,0 @@
-/**
- * Browser Automation Tools with LangGraph Interrupt Support
- *
- * These tools use LangGraph's interrupt() mechanism to pause execution
- * and wait for the browser extension to execute actions and return results.
- *
- * Flow:
- * 1. Agent calls browser tool (e.g., browser_navigate)
- * 2. Tool calls interrupt() with action details
- * 3. Graph pauses and returns interrupt to client
- * 4. Extension executes action in browser
- * 5. Extension sends resume Command with actual result
- * 6. Graph continues with real browser data
- *
- * This enables proper chain-of-thought with browser context because
- * the agent receives ACTUAL results (page elements, screenshots, etc.)
- * instead of placeholder acknowledgments.
- */
-import { z } from 'zod';
-import { DynamicStructuredTool } from '@langchain/core/tools';
-/**
- * Interrupt payload sent to the extension
- */
-export interface BrowserInterrupt {
-    /** Type of browser action to execute */
-    type: 'browser_interrupt';
-    /** The specific action to perform */
-    action: BrowserAction;
-    /** Unique ID for this interrupt (for matching resume) */
-    interruptId: string;
-}
-/**
- * Browser action types
- */
-export type BrowserAction = {
-    type: 'navigate';
-    url: string;
-    reason?: string;
-} | {
-    type: 'click';
-    index?: number;
-    coordinates?: {
-        x: number;
-        y: number;
-    };
-    reason?: string;
-} | {
-    type: 'type';
-    index: number;
-    text: string;
-    clear?: boolean;
-    pressEnter?: boolean;
-} | {
-    type: 'scroll';
-    direction: 'up' | 'down' | 'left' | 'right';
-    amount?: number;
-} | {
-    type: 'extract';
-    query?: string;
-    selector?: string;
-} | {
-    type: 'hover';
-    index: number;
-} | {
-    type: 'wait';
-    duration?: number;
-    reason?: string;
-} | {
-    type: 'back';
-    reason?: string;
-} | {
-    type: 'screenshot';
-    fullPage?: boolean;
-} | {
-    type: 'get_page_state';
-    reason?: string;
-};
-/**
- * Result returned from extension after executing action
- */
-export interface BrowserActionResult {
-    success: boolean;
-    error?: string;
-    /** Page state after action (for navigate, click, get_page_state) */
-    pageState?: {
-        url: string;
-        title: string;
-        /** Formatted element list for LLM */
-        elementList: string;
-        elementCount: number;
-        scrollPosition: number;
-        scrollHeight: number;
-        viewportHeight: number;
-    };
-    /** Screenshot data URL */
-    screenshot?: string;
-    /** Extracted content */
-    extractedContent?: string;
-    /** Any additional data */
-    data?: unknown;
-}
-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;
-    }>>;
-    reason: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    index?: number | undefined;
-    coordinates?: {
-        y: number;
-        x: number;
-    } | undefined;
-    reason?: string | undefined;
-}, {
-    index?: number | undefined;
-    coordinates?: {
-        y: number;
-        x: number;
-    } | 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>;
-}, "strip", z.ZodTypeAny, {
-    fullPage?: boolean | undefined;
-}, {
-    fullPage?: boolean | undefined;
-}>;
-declare const BrowserGetPageStateSchema: z.ZodObject<{
-    reason: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    reason?: string | undefined;
-}, {
-    reason?: string | undefined;
-}>;
-/**
- * Navigate tool - navigates to URL and returns page state
- */
-export declare function createBrowserNavigateInterruptTool(): DynamicStructuredTool<typeof BrowserNavigateSchema>;
-/**
- * Click tool - clicks element and returns updated state
- */
-export declare function createBrowserClickInterruptTool(): DynamicStructuredTool<typeof BrowserClickSchema>;
-/**
- * Type tool - types text into input field
- */
-export declare function createBrowserTypeInterruptTool(): DynamicStructuredTool<typeof BrowserTypeSchema>;
-/**
- * Get page state tool - captures current page elements
- */
-export declare function createBrowserGetPageStateInterruptTool(): DynamicStructuredTool<typeof BrowserGetPageStateSchema>;
-/**
- * Scroll tool
- */
-export declare function createBrowserScrollInterruptTool(): DynamicStructuredTool<typeof BrowserScrollSchema>;
-/**
- * Extract tool
- */
-export declare function createBrowserExtractInterruptTool(): DynamicStructuredTool<typeof BrowserExtractSchema>;
-/**
- * Hover tool
- */
-export declare function createBrowserHoverInterruptTool(): DynamicStructuredTool<typeof BrowserHoverSchema>;
-/**
- * Wait tool
- */
-export declare function createBrowserWaitInterruptTool(): DynamicStructuredTool<typeof BrowserWaitSchema>;
-/**
- * Go back tool
- */
-export declare function createBrowserGoBackInterruptTool(): DynamicStructuredTool<typeof BrowserGoBackSchema>;
-/**
- * Screenshot tool
- */
-export declare function createBrowserScreenshotInterruptTool(): DynamicStructuredTool<typeof BrowserScreenshotSchema>;
-export declare const EBrowserInterruptTools: {
-    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 declare const BROWSER_INTERRUPT_TOOL_NAMES: ("browser_navigate" | "browser_click" | "browser_type" | "browser_get_page_state" | "browser_scroll" | "browser_extract" | "browser_hover" | "browser_wait" | "browser_back" | "browser_screenshot")[];
-export type BrowserInterruptToolName = typeof BROWSER_INTERRUPT_TOOL_NAMES[number];
-export declare function isBrowserInterruptToolCall(toolName: string): toolName is BrowserInterruptToolName;
-/**
- * Create all interrupt-based browser tools
- *
- * Use these when the client is a browser extension that can:
- * 1. Detect browser_interrupt events in the stream
- * 2. Execute browser actions locally
- * 3. Send Command({ resume: result }) to continue the graph
- */
-export declare function createBrowserInterruptTools(): DynamicStructuredTool[];
-/**
- * Check if an interrupt is a browser interrupt
- */
-export declare function isBrowserInterrupt(value: unknown): value is BrowserInterrupt;
-export {};

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

@@ -1,259 +0,0 @@
-/**
- * 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;
-    reason?: string | undefined;
-    visualDescription?: string | undefined;
-}, {
-    index?: number | undefined;
-    coordinates?: {
-        y: number;
-        x: number;
-    } | undefined;
-    reason?: string | undefined;
-    visualDescription?: 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;
-}>;
-declare const BrowserGetPageStateSchema: z.ZodObject<{
-    reason: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    reason?: string | undefined;
-}, {
-    reason?: string | 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>;
-/**
- * Browser get page state tool - gets fresh page context after navigation or actions
- * CRITICAL: Use this after browser_navigate or any action that changes the page
- */
-export declare function createBrowserGetPageStateTool(): DynamicStructuredTool<typeof BrowserGetPageStateSchema>;
-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;
-    /** Enable get page state tool */
-    enableGetPageState?: 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";
-    readonly GET_PAGE_STATE: "browser_get_page_state";
-};
-/**
- * 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", "browser_get_page_state"];
-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 {};