digital-workers 2.1.3 → 2.4.0

package/dist/browse.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Browser automation functionality for digital workers
+ *
+ * IMPORTANT: Worker Routing vs Direct Browser Calls
+ * -------------------------------------------------
+ * This module provides worker-routed browser automation, enabling AI-assisted
+ * browser control with human fallback capabilities.
+ *
+ * - `digital-workers.browse()` - Routes browser automation tasks to Workers
+ *   (AI Agents or Humans) based on capability matching and complexity.
+ *
+ * Use digital-workers.browse when you need:
+ * - AI-planned browser automation
+ * - Human-in-the-loop for complex interactions
+ * - Capability-based worker selection
+ * - Screenshot and data extraction with fallback
+ *
+ * @module
+ */
+/**
+ * Viewport dimensions for browser automation
+ */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/**
+ * Options for browser automation
+ */
+export interface BrowseOptions {
+    /** URL to navigate to */
+    url: string;
+    /** Task or goal to accomplish in the browser */
+    task: string;
+    /** Maximum time to wait for task completion (ms) */
+    timeout?: number;
+    /** Run browser in headless mode */
+    headless?: boolean;
+    /** Browser viewport dimensions */
+    viewport?: Viewport;
+    /** Additional context for the task */
+    context?: Record<string, unknown>;
+    /** Wait for specific selector before starting */
+    waitFor?: string;
+    /** Cookies to set before navigation */
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+    }>;
+    /** User agent string */
+    userAgent?: string;
+    /** Enable human fallback for complex interactions */
+    humanFallback?: boolean;
+    /** Worker to route to (defaults to automatic selection) */
+    worker?: string;
+}
+/**
+ * Browser action types
+ */
+export type BrowseActionType = 'navigate' | 'click' | 'type' | 'scroll' | 'wait' | 'screenshot' | 'extract';
+/**
+ * Individual browser action record
+ */
+export interface BrowseAction {
+    /** Type of action performed */
+    type: BrowseActionType;
+    /** Target selector or URL */
+    target?: string;
+    /** Value used in the action (text typed, scroll amount, etc.) */
+    value?: string;
+    /** Timestamp when action was performed */
+    timestamp?: Date;
+    /** Whether action succeeded */
+    success?: boolean;
+    /** Error message if action failed */
+    error?: string;
+}
+/**
+ * Result of browser automation
+ */
+export interface BrowseResult {
+    /** Whether the overall task succeeded */
+    success: boolean;
+    /** Extracted data or task result */
+    data?: unknown;
+    /** Screenshot as base64 string (if requested) */
+    screenshot?: string;
+    /** List of actions performed */
+    actions: BrowseAction[];
+    /** Error message if task failed */
+    error?: string;
+    /** Duration of task execution (ms) */
+    duration?: number;
+    /** Final URL after navigation */
+    finalUrl?: string;
+    /** Page title */
+    title?: string;
+    /** Worker that executed the task */
+    executedBy?: string;
+}
+/**
+ * Options for click action
+ */
+export interface ClickOptions {
+    /** Wait for navigation after click */
+    waitForNavigation?: boolean;
+    /** Click position offset from element center */
+    offset?: {
+        x: number;
+        y: number;
+    };
+    /** Number of clicks */
+    clickCount?: number;
+    /** Mouse button */
+    button?: 'left' | 'right' | 'middle';
+}
+/**
+ * Options for type action
+ */
+export interface TypeOptions {
+    /** Clear existing text before typing */
+    clear?: boolean;
+    /** Delay between keystrokes (ms) */
+    delay?: number;
+    /** Press Enter after typing */
+    pressEnter?: boolean;
+}
+/**
+ * Options for scroll action
+ */
+export interface ScrollOptions {
+    /** Scroll direction */
+    direction: 'up' | 'down' | 'left' | 'right';
+    /** Amount to scroll in pixels */
+    amount?: number;
+    /** Scroll to specific element */
+    toElement?: string;
+    /** Scroll smoothly */
+    smooth?: boolean;
+}
+/**
+ * Options for screenshot action
+ */
+export interface ScreenshotOptions {
+    /** Capture full page or viewport only */
+    fullPage?: boolean;
+    /** Specific element to capture */
+    selector?: string;
+    /** Image format */
+    format?: 'png' | 'jpeg' | 'webp';
+    /** Image quality (0-100) for jpeg/webp */
+    quality?: number;
+}
+/**
+ * Options for extract action
+ */
+export interface ExtractOptions {
+    /** Schema describing the data to extract */
+    schema?: Record<string, unknown>;
+    /** CSS selector to scope extraction */
+    selector?: string;
+    /** Extract multiple items */
+    multiple?: boolean;
+    /** Include raw HTML */
+    includeHtml?: boolean;
+}
+/**
+ * Execute browser automation by routing to an appropriate Worker (AI Agent or Human).
+ *
+ * This function uses AI to plan and execute browser actions to accomplish
+ * a given task. It supports human fallback for complex interactions that
+ * require human judgment.
+ *
+ * @param url - URL to navigate to
+ * @param task - Description of the task to accomplish
+ * @param options - Additional options for browser automation
+ * @returns Promise resolving to browse result with execution details
+ *
+ * @example
+ * ```ts
+ * // Simple navigation and extraction
+ * const result = await browse('https://example.com', 'Find the contact email')
+ *
+ * if (result.success) {
+ *   console.log('Email:', result.data)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Form submission
+ * const result = await browse('https://example.com/login', 'Log in with test credentials', {
+ *   context: {
+ *     username: 'testuser',
+ *     password: 'testpass123',
+ *   },
+ *   timeout: 30000,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Complex interaction with human fallback
+ * const result = await browse('https://example.com/checkout', 'Complete the purchase', {
+ *   humanFallback: true,
+ *   timeout: 60000,
+ * })
+ * ```
+ */
+export declare function browse(url: string, task: string, options?: Partial<BrowseOptions>): Promise<BrowseResult>;
+export declare namespace browse {
+    var click: (url: string, selector: string, options?: ClickOptions) => Promise<BrowseResult>;
+    var type: (url: string, selector: string, text: string, options?: TypeOptions) => Promise<BrowseResult>;
+    var scroll: (url: string, direction: "up" | "down" | "left" | "right", amount?: number, options?: Partial<ScrollOptions>) => Promise<BrowseResult>;
+    var screenshot: (url: string, options?: ScreenshotOptions) => Promise<BrowseResult>;
+    var extract: (url: string, schema: Record<string, unknown>, options?: ExtractOptions) => Promise<BrowseResult>;
+    var waitFor: (url: string, selector: string, timeout?: number) => Promise<BrowseResult>;
+    var fill: (url: string, formData: Record<string, string>, submitSelector?: string) => Promise<BrowseResult>;
+    var crawl: (urls: string[], taskPerPage: string) => Promise<BrowseResult[]>;
+}
+export default browse;
+//# sourceMappingURL=browse.d.ts.map

package/dist/browse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.d.ts","sourceRoot":"","sources":["../src/browse.ts"],"names":[],"mappings":"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"}

package/dist/browse.js

@@ -0,0 +1,392 @@
+/**
+ * Browser automation functionality for digital workers
+ *
+ * IMPORTANT: Worker Routing vs Direct Browser Calls
+ * -------------------------------------------------
+ * This module provides worker-routed browser automation, enabling AI-assisted
+ * browser control with human fallback capabilities.
+ *
+ * - `digital-workers.browse()` - Routes browser automation tasks to Workers
+ *   (AI Agents or Humans) based on capability matching and complexity.
+ *
+ * Use digital-workers.browse when you need:
+ * - AI-planned browser automation
+ * - Human-in-the-loop for complex interactions
+ * - Capability-based worker selection
+ * - Screenshot and data extraction with fallback
+ *
+ * @module
+ */
+import { define } from 'ai-functions';
+// ============================================================================
+// Main Browse Function
+// ============================================================================
+/**
+ * Execute browser automation by routing to an appropriate Worker (AI Agent or Human).
+ *
+ * This function uses AI to plan and execute browser actions to accomplish
+ * a given task. It supports human fallback for complex interactions that
+ * require human judgment.
+ *
+ * @param url - URL to navigate to
+ * @param task - Description of the task to accomplish
+ * @param options - Additional options for browser automation
+ * @returns Promise resolving to browse result with execution details
+ *
+ * @example
+ * ```ts
+ * // Simple navigation and extraction
+ * const result = await browse('https://example.com', 'Find the contact email')
+ *
+ * if (result.success) {
+ *   console.log('Email:', result.data)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Form submission
+ * const result = await browse('https://example.com/login', 'Log in with test credentials', {
+ *   context: {
+ *     username: 'testuser',
+ *     password: 'testpass123',
+ *   },
+ *   timeout: 30000,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Complex interaction with human fallback
+ * const result = await browse('https://example.com/checkout', 'Complete the purchase', {
+ *   humanFallback: true,
+ *   timeout: 60000,
+ * })
+ * ```
+ */
+export async function browse(url, task, options = {}) {
+    const { timeout = 30000, headless = true, viewport = { width: 1280, height: 720 }, context, waitFor, humanFallback = false, } = options;
+    const startTime = Date.now();
+    const actions = [];
+    // Record initial navigation
+    actions.push({
+        type: 'navigate',
+        target: url,
+        timestamp: new Date(),
+        success: true,
+    });
+    // Use agentic function for browser automation planning
+    const browserFn = define.agentic({
+        name: 'browserAutomation',
+        description: 'Plan and execute browser actions to accomplish a task',
+        args: {
+            url: 'The URL to navigate to',
+            task: 'The task to accomplish',
+            contextInfo: 'Additional context and parameters',
+            viewportSize: 'Browser viewport dimensions',
+        },
+        returnType: {
+            success: 'Whether the task was completed successfully',
+            data: 'Extracted data or task result',
+            actions: ['List of browser actions taken'],
+            finalUrl: 'The final URL after all actions',
+            title: 'The page title',
+            error: 'Error message if task failed',
+        },
+        instructions: `You are a browser automation agent. Plan and execute browser actions to accomplish the task.
+
+URL: ${url}
+Task: ${task}
+Viewport: ${viewport.width}x${viewport.height}
+${context ? `Context: ${JSON.stringify(context, null, 2)}` : ''}
+${waitFor ? `Wait for selector: ${waitFor}` : ''}
+
+Available actions:
+- navigate(url): Go to a URL
+- click(selector): Click an element
+- type(selector, text): Type text into an input
+- scroll(direction, amount): Scroll the page
+- wait(ms): Wait for a duration
+- waitForSelector(selector): Wait for element to appear
+- screenshot(): Take a screenshot
+- extract(schema): Extract data from the page
+
+Plan your actions step by step to accomplish the task efficiently.`,
+        maxIterations: 10,
+        tools: [], // Browser tools would be provided by the execution environment
+    });
+    try {
+        const response = (await Promise.race([
+            browserFn.call({
+                url,
+                task,
+                contextInfo: context ? JSON.stringify(context) : '',
+                viewportSize: `${viewport.width}x${viewport.height}`,
+            }),
+            timeout
+                ? new Promise((_, reject) => setTimeout(() => reject(new Error('Browser automation timeout')), timeout))
+                : new Promise(() => { }),
+        ]));
+        // Record actions from response
+        if (response.actions) {
+            actions.push(...response.actions.map((action) => {
+                const browseAction = {
+                    type: action.type,
+                    timestamp: new Date(),
+                    success: true,
+                };
+                if (action.target !== undefined) {
+                    browseAction.target = action.target;
+                }
+                if (action.value !== undefined) {
+                    browseAction.value = action.value;
+                }
+                return browseAction;
+            }));
+        }
+        const duration = Date.now() - startTime;
+        const result = {
+            success: response.success,
+            actions,
+            duration,
+            finalUrl: response.finalUrl || url,
+        };
+        if (response.data !== undefined) {
+            result.data = response.data;
+        }
+        if (response.error !== undefined) {
+            result.error = response.error;
+        }
+        if (response.title !== undefined) {
+            result.title = response.title;
+        }
+        return result;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // If human fallback is enabled and AI fails, route to human
+        if (humanFallback) {
+            return {
+                success: false,
+                actions,
+                error: `AI automation failed, human fallback requested: ${errorMessage}`,
+                duration: Date.now() - startTime,
+                executedBy: 'pending-human-fallback',
+            };
+        }
+        return {
+            success: false,
+            actions,
+            error: errorMessage,
+            duration: Date.now() - startTime,
+        };
+    }
+}
+// ============================================================================
+// Helper Methods
+// ============================================================================
+/**
+ * Click an element on a page
+ *
+ * @param url - URL of the page
+ * @param selector - CSS selector of the element to click
+ * @param options - Click options
+ * @returns Promise resolving to browse result
+ *
+ * @example
+ * ```ts
+ * const result = await browse.click('https://example.com', '#submit-button')
+ * ```
+ */
+browse.click = async (url, selector, options = {}) => {
+    const { waitForNavigation = false, clickCount = 1 } = options;
+    return browse(url, `Click the element matching selector "${selector}"`, {
+        context: {
+            action: 'click',
+            selector,
+            waitForNavigation,
+            clickCount,
+        },
+    });
+};
+/**
+ * Type text into an input element
+ *
+ * @param url - URL of the page
+ * @param selector - CSS selector of the input element
+ * @param text - Text to type
+ * @param options - Type options
+ * @returns Promise resolving to browse result
+ *
+ * @example
+ * ```ts
+ * const result = await browse.type('https://example.com', '#search-input', 'hello world')
+ * ```
+ */
+browse.type = async (url, selector, text, options = {}) => {
+    const { clear = false, delay = 0, pressEnter = false } = options;
+    return browse(url, `Type "${text}" into the element matching selector "${selector}"`, {
+        context: {
+            action: 'type',
+            selector,
+            text,
+            clear,
+            delay,
+            pressEnter,
+        },
+    });
+};
+/**
+ * Scroll the page
+ *
+ * @param url - URL of the page
+ * @param direction - Scroll direction
+ * @param amount - Amount to scroll in pixels (default: 500)
+ * @param options - Additional scroll options
+ * @returns Promise resolving to browse result
+ *
+ * @example
+ * ```ts
+ * const result = await browse.scroll('https://example.com', 'down', 500)
+ * ```
+ */
+browse.scroll = async (url, direction, amount = 500, options = {}) => {
+    const { toElement, smooth = true } = options;
+    return browse(url, `Scroll ${direction} by ${amount} pixels`, {
+        context: {
+            action: 'scroll',
+            direction,
+            amount,
+            toElement,
+            smooth,
+        },
+    });
+};
+/**
+ * Take a screenshot of the page
+ *
+ * @param url - URL of the page
+ * @param options - Screenshot options
+ * @returns Promise resolving to browse result with screenshot
+ *
+ * @example
+ * ```ts
+ * const result = await browse.screenshot('https://example.com')
+ * if (result.screenshot) {
+ *   // Save or process the base64 screenshot
+ * }
+ * ```
+ */
+browse.screenshot = async (url, options = {}) => {
+    const { fullPage = false, selector, format = 'png', quality } = options;
+    return browse(url, 'Take a screenshot of the page', {
+        context: {
+            action: 'screenshot',
+            fullPage,
+            selector,
+            format,
+            quality,
+        },
+    });
+};
+/**
+ * Extract structured data from a page
+ *
+ * @param url - URL of the page
+ * @param schema - Schema describing the data to extract
+ * @param options - Extract options
+ * @returns Promise resolving to browse result with extracted data
+ *
+ * @example
+ * ```ts
+ * const result = await browse.extract('https://example.com/products', {
+ *   products: [{
+ *     name: 'Product name',
+ *     price: 'Product price as number',
+ *     description: 'Product description',
+ *   }],
+ * })
+ *
+ * if (result.success) {
+ *   console.log('Products:', result.data)
+ * }
+ * ```
+ */
+browse.extract = async (url, schema, options = {}) => {
+    const { selector, multiple = false, includeHtml = false } = options;
+    return browse(url, 'Extract structured data from the page according to the schema', {
+        context: {
+            action: 'extract',
+            schema,
+            selector,
+            multiple,
+            includeHtml,
+        },
+    });
+};
+/**
+ * Wait for an element to appear on the page
+ *
+ * @param url - URL of the page
+ * @param selector - CSS selector to wait for
+ * @param timeout - Maximum time to wait (ms)
+ * @returns Promise resolving to browse result
+ *
+ * @example
+ * ```ts
+ * const result = await browse.waitFor('https://example.com', '.loaded-content', 5000)
+ * ```
+ */
+browse.waitFor = async (url, selector, timeout = 30000) => {
+    return browse(url, `Wait for element matching selector "${selector}" to appear`, {
+        waitFor: selector,
+        timeout,
+    });
+};
+/**
+ * Fill out a form with multiple fields
+ *
+ * @param url - URL of the page with the form
+ * @param formData - Object mapping selectors to values
+ * @param submitSelector - Optional selector for the submit button
+ * @returns Promise resolving to browse result
+ *
+ * @example
+ * ```ts
+ * const result = await browse.fill('https://example.com/contact', {
+ *   '#name': 'John Doe',
+ *   '#email': 'john@example.com',
+ *   '#message': 'Hello!',
+ * }, '#submit')
+ * ```
+ */
+browse.fill = async (url, formData, submitSelector) => {
+    return browse(url, 'Fill out the form with the provided data and submit if requested', {
+        context: {
+            action: 'fill',
+            formData,
+            submitSelector,
+        },
+    });
+};
+/**
+ * Navigate through multiple pages
+ *
+ * @param urls - Array of URLs to visit
+ * @param taskPerPage - Task to perform on each page
+ * @returns Promise resolving to array of browse results
+ *
+ * @example
+ * ```ts
+ * const results = await browse.crawl(
+ *   ['https://example.com/page1', 'https://example.com/page2'],
+ *   'Extract the page title'
+ * )
+ * ```
+ */
+browse.crawl = async (urls, taskPerPage) => {
+    return Promise.all(urls.map((url) => browse(url, taskPerPage)));
+};
+// Export as default as well
+export default browse;
+//# sourceMappingURL=browse.js.map

package/dist/browse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse.js","sourceRoot":"","sources":["../src/browse.ts"],"names":[],"mappings":"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"}

package/dist/capability-tiers.js

@@ -281,8 +281,8 @@ export function createCapabilityProfile(input) {
         tier,
         complexityRating,
         tools,
-        description,
-        constraints,
+        ...(description !== undefined && { description }),
+        ...(constraints !== undefined && { constraints }),
     };
 }
 // ============================================================================
@@ -346,7 +346,7 @@ export class TierRegistry {
         const result = [];
         for (const profile of this.profiles.values()) {
             const profileTools = new Set(profile.tools);
-            const hasAllTools = requiredTools.every(tool => profileTools.has(tool));
+            const hasAllTools = requiredTools.every((tool) => profileTools.has(tool));
             if (hasAllTools) {
                 result.push(profile);
             }