@loxia-labs/loxia-autopilot-one 1.0.1

package/src/tools/webTool.js

@@ -0,0 +1,1430 @@
+/**
+ * WebTool - Web browsing and automation with Puppeteer
+ *
+ * Purpose:
+ * - Search the web using known search engines
+ * - Fetch web content in various formats
+ * - Interactive browser automation with command chaining
+ * - Tab management with agent isolation
+ * - Screenshot capture and AI-powered analysis
+ * - Mouse and keyboard event simulation
+ */
+
+import { BaseTool } from './baseTool.js';
+import TagParser from '../utilities/tagParser.js';
+import puppeteer from 'puppeteer';
+import path from 'path';
+import fs from 'fs/promises';
+import os from 'os';
+
+import {
+  TOOL_STATUS,
+  SYSTEM_DEFAULTS
+} from '../utilities/constants.js';
+
+class WebTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+
+    // Tool metadata
+    this.requiresProject = false;
+    this.isAsync = true;
+
+    // Browser instance (singleton per system)
+    this.browser = null;
+    this.browserInitializing = false;
+
+    // Tab tracking: Map<agentId, Map<tabName, tabInfo>>
+    this.agentTabs = new Map();
+
+    // Known search engines
+    this.searchEngines = [
+      {
+        name: 'google',
+        url: 'https://www.google.com/search?q=',
+        searchSelector: 'input[name="q"]',
+        submitSelector: 'input[type="submit"], button[type="submit"]',
+        resultsSelector: '#search .g a, #search a[href]',
+        waitSelector: '#search'
+      },
+      {
+        name: 'bing',
+        url: 'https://www.bing.com/search?q=',
+        searchSelector: 'input[name="q"]',
+        submitSelector: 'input[type="submit"]',
+        resultsSelector: '.b_algo a',
+        waitSelector: '#b_results'
+      },
+      {
+        name: 'duckduckgo',
+        url: 'https://duckduckgo.com/?q=',
+        searchSelector: 'input[name="q"]',
+        submitSelector: 'button[type="submit"]',
+        resultsSelector: '.result__a, a[data-testid="result-title-a"]',
+        waitSelector: '#links, [data-testid="mainline"]'
+      }
+    ];
+
+    // Configuration
+    this.TAB_IDLE_TIMEOUT = config.tabIdleTimeout || 60 * 60 * 1000; // 1 hour
+    this.CLEANUP_INTERVAL = config.cleanupInterval || 5 * 60 * 1000; // 5 minutes
+    this.DEFAULT_TIMEOUT = config.defaultTimeout || 60000; // 60 seconds
+    this.TEMP_DIR = config.tempDir || path.join(os.tmpdir(), 'webtool-screenshots');
+
+    // Start cleanup timer
+    this.cleanupTimer = null;
+    this.startCleanupTimer();
+
+    // Ensure temp directory exists
+    this.ensureTempDir();
+  }
+
+  /**
+   * Get tool description for LLM consumption
+   * @returns {string} Tool description
+   */
+  getDescription() {
+    return `
+Web Tool: Browse, search, and automate web interactions using a real browser (Puppeteer).
+
+IMPORTANT: This tool supports command chaining - nest multiple actions together to execute them sequentially without waiting for responses between each action.
+
+USAGE:
+[tool id="web"]
+<operation>search|fetch|interactive</operation>
+<!-- Operation-specific content -->
+[/tool]
+
+ALTERNATIVE JSON FORMAT:
+\`\`\`json
+{
+  "toolId": "web",
+  "operation": "search|fetch|interactive",
+  "parameters": { ... }
+}
+\`\`\`
+
+═══════════════════════════════════════════════════════════════
+OPERATION 1: SEARCH THE WEB
+═══════════════════════════════════════════════════════════════
+
+Search using real browsers on known search engines (Google, Bing, DuckDuckGo).
+
+XML SYNTAX:
+[tool id="web"]
+<operation>search</operation>
+<query>puppeteer web scraping tutorial</query>
+<engine>google</engine> <!-- Optional: google|bing|duckduckgo, default: google -->
+<max-results>10</max-results> <!-- Optional, default: 10 -->
+[/tool]
+
+JSON SYNTAX:
+\`\`\`json
+{
+  "toolId": "web",
+  "operation": "search",
+  "query": "puppeteer web scraping tutorial",
+  "engine": "google",
+  "maxResults": 10
+}
+\`\`\`
+
+OUTPUT: List of URLs with titles and descriptions
+
+═══════════════════════════════════════════════════════════════
+OPERATION 2: FETCH WEB CONTENT
+═══════════════════════════════════════════════════════════════
+
+Fetch content from a URL in various formats.
+
+XML SYNTAX:
+[tool id="web"]
+<operation>fetch</operation>
+<url>https://example.com</url>
+<format>title,text,links</format> <!-- Options: title|text|links|html|console -->
+[/tool]
+
+JSON SYNTAX:
+\`\`\`json
+{
+  "toolId": "web",
+  "operation": "fetch",
+  "url": "https://example.com",
+  "formats": ["title", "text", "links", "html", "console"]
+}
+\`\`\`
+
+FORMAT OPTIONS:
+- title: Page title
+- text: Plain text content (no HTML)
+- links: All links on page
+- html: Full HTML source
+- console: Browser console messages
+
+OUTPUT: Object with requested content formats
+
+═══════════════════════════════════════════════════════════════
+OPERATION 3: INTERACTIVE BROWSER AUTOMATION
+═══════════════════════════════════════════════════════════════
+
+Control a real browser with command chaining for complex workflows.
+
+XML SYNTAX (RECOMMENDED FOR CHAINING):
+[tool id="web"]
+<operation>interactive</operation>
+<headless>true</headless> <!-- true|false, default: true -->
+<actions>
+  <open-tab name="search">
+    <navigate>https://github.com/trending</navigate>
+    <wait-for selector=".Box-row" timeout="5000" />
+    <click selector=".Box-row:first-child a" />
+    <wait-for selector="#readme" />
+    <screenshot format="file" path="readme.png" />
+    <analyze-screenshot>What is the main topic of this README?</analyze-screenshot>
+    <extract-text selector="#readme" />
+    <get-source />
+  </open-tab>
+  <open-tab name="docs">
+    <navigate>https://docs.example.com</navigate>
+    <type selector="input.search" text="installation" />
+    <press key="Enter" />
+    <extract-links selector="a.doc-link" />
+  </open-tab>
+  <list-tabs />
+  <close-tab name="search" />
+</actions>
+[/tool]
+
+JSON SYNTAX (ALTERNATIVE):
+\`\`\`json
+{
+  "toolId": "web",
+  "operation": "interactive",
+  "headless": true,
+  "actions": [
+    {
+      "type": "open-tab",
+      "name": "search",
+      "url": "https://github.com/trending",
+      "nestedActions": [
+        {"type": "wait-for", "selector": ".Box-row", "timeout": 5000},
+        {"type": "click", "selector": ".Box-row:first-child a"},
+        {"type": "screenshot", "format": "base64"},
+        {"type": "extract-text", "selector": "#readme"}
+      ]
+    },
+    {"type": "list-tabs"},
+    {"type": "close-tab", "name": "search"}
+  ]
+}
+\`\`\`
+
+SUPPORTED ACTIONS:
+- open-tab: Open new tab with nested actions
+- close-tab: Close specific tab
+- switch-tab: Switch to existing tab
+- list-tabs: List all active tabs for this agent
+- navigate: Go to URL
+- click: Click element (left|right|middle)
+- type: Type text into element
+- press: Press keyboard key
+- wait-for: Wait for element to appear
+- screenshot: Capture screenshot (file|base64)
+- analyze-screenshot: AI analysis of current page
+- extract-text: Extract text from selector
+- extract-links: Extract all links
+- get-source: Get HTML source
+- get-console: Get console messages
+- scroll: Scroll page
+- hover: Hover over element
+
+MOUSE EVENTS:
+<click selector=".button" button="left" /> <!-- left|right|middle -->
+<hover selector=".menu" />
+<mouse-move selector=".element" />
+
+KEYBOARD EVENTS:
+<type selector="input" text="Hello World" />
+<press key="Enter" />
+<press key="Control+C" /> <!-- Supports modifier keys -->
+
+SCREENSHOT OPTIONS:
+<screenshot format="file" path="screenshot.png" /> <!-- Save to project dir -->
+<screenshot format="file" /> <!-- Save to temp dir -->
+<screenshot format="base64" /> <!-- Return as base64 string -->
+
+AI SCREENSHOT ANALYSIS:
+<analyze-screenshot>What products are visible on this page?</analyze-screenshot>
+<analyze-screenshot model="gpt-4-vision">Describe the layout</analyze-screenshot>
+
+TAB MANAGEMENT:
+- Tabs are agent-isolated (each agent has its own tabs)
+- Tabs auto-close after 1 hour of inactivity
+- Tab names must be unique per agent
+- Use descriptive names for easy identification
+
+═══════════════════════════════════════════════════════════════
+COMMAND CHAINING BENEFITS
+═══════════════════════════════════════════════════════════════
+
+Instead of:
+1. Open tab → wait for response
+2. Navigate → wait for response
+3. Click → wait for response
+4. Screenshot → wait for response
+
+Do this (ONE REQUEST):
+<open-tab name="task">
+  <navigate>URL</navigate>
+  <click selector=".button" />
+  <screenshot />
+</open-tab>
+
+All actions execute sequentially in one operation!
+
+═══════════════════════════════════════════════════════════════
+EXAMPLES
+═══════════════════════════════════════════════════════════════
+
+EXAMPLE 1: Search and analyze results
+[tool id="web"]
+<operation>interactive</operation>
+<headless>true</headless>
+<actions>
+  <open-tab name="search">
+    <navigate>https://google.com</navigate>
+    <type selector="input[name=q]">best web scraping tools 2025</type>
+    <press key="Enter" />
+    <wait-for selector="#search" />
+    <screenshot format="file" path="search-results.png" />
+    <analyze-screenshot>List the top 3 tools mentioned</analyze-screenshot>
+    <extract-links selector="#search .g a" />
+  </open-tab>
+</actions>
+[/tool]
+
+EXAMPLE 2: Multi-tab workflow
+[tool id="web"]
+<operation>interactive</operation>
+<actions>
+  <open-tab name="github">
+    <navigate>https://github.com/trending</navigate>
+    <extract-links selector=".Box-row a" />
+  </open-tab>
+  <open-tab name="npm">
+    <navigate>https://npmjs.com/package/puppeteer</navigate>
+    <extract-text selector=".package-description" />
+  </open-tab>
+  <list-tabs />
+</actions>
+[/tool]
+
+EXAMPLE 3: Form interaction
+[tool id="web"]
+<operation>interactive</operation>
+<headless>false</headless> <!-- Visible browser for debugging -->
+<actions>
+  <open-tab name="form">
+    <navigate>https://example.com/contact</navigate>
+    <type selector="#name" text="John Doe" />
+    <type selector="#email" text="john@example.com" />
+    <type selector="#message" text="Hello!" />
+    <click selector="#submit" />
+    <wait-for selector=".success-message" />
+    <screenshot format="base64" />
+  </open-tab>
+</actions>
+[/tool]
+
+EXAMPLE 4: Simple fetch
+[tool id="web"]
+<operation>fetch</operation>
+<url>https://example.com</url>
+<format>title,text,links</format>
+[/tool]
+
+EXAMPLE 5: Quick search
+[tool id="web"]
+<operation>search</operation>
+<query>openai gpt-4 api documentation</query>
+<engine>google</engine>
+<max-results>5</max-results>
+[/tool]
+
+SECURITY NOTES:
+- Browser runs in isolated context per agent
+- Tabs auto-close after 1 hour of inactivity
+- Screenshots stored in temp directory with auto-cleanup
+- No access to local file system beyond allowed directories
+
+BEST PRACTICES:
+- Use command chaining to minimize round-trips
+- Use descriptive tab names
+- Close tabs when done to free resources
+- Use headless mode for better performance
+- Use visible mode only for debugging
+    `;
+  }
+
+  /**
+   * Parse parameters from tool command content
+   * @param {string} content - Raw tool command content
+   * @returns {Object} Parsed parameters
+   */
+  parseParameters(content) {
+    try {
+      // Try JSON first
+      if (content.trim().startsWith('{')) {
+        return JSON.parse(content);
+      }
+
+      // Parse XML-style tags
+      const params = {};
+
+      // Extract operation
+      const operationMatches = TagParser.extractContent(content, 'operation');
+      if (operationMatches.length > 0) {
+        params.operation = operationMatches[0].trim();
+      }
+
+      // Extract based on operation
+      switch (params.operation) {
+        case 'search':
+          params.query = TagParser.extractContent(content, 'query')[0]?.trim();
+          params.engine = TagParser.extractContent(content, 'engine')[0]?.trim() || 'google';
+          const maxResults = TagParser.extractContent(content, 'max-results')[0]?.trim();
+          params.maxResults = maxResults ? parseInt(maxResults, 10) : 10;
+          break;
+
+        case 'fetch':
+          params.url = TagParser.extractContent(content, 'url')[0]?.trim();
+          const formatStr = TagParser.extractContent(content, 'format')[0]?.trim();
+          params.formats = formatStr ? formatStr.split(',').map(f => f.trim()) : ['title', 'text'];
+          break;
+
+        case 'interactive':
+          const headlessStr = TagParser.extractContent(content, 'headless')[0]?.trim();
+          params.headless = headlessStr !== 'false'; // Default true
+
+          // Extract actions block
+          const actionsContent = TagParser.extractContent(content, 'actions')[0];
+          if (actionsContent) {
+            params.actions = this.parseActions(actionsContent);
+          }
+          break;
+      }
+
+      params.rawContent = content.trim();
+      return params;
+
+    } catch (error) {
+      throw new Error(`Failed to parse web tool parameters: ${error.message}`);
+    }
+  }
+
+  /**
+   * Parse actions from XML content
+   * @param {string} content - Actions XML content
+   * @returns {Array} Parsed actions
+   * @private
+   */
+  parseActions(content) {
+    const actions = [];
+
+    // Parse open-tab actions
+    const openTabRegex = /<open-tab[^>]*name="([^"]+)"[^>]*>([\s\S]*?)<\/open-tab>/g;
+    let match;
+
+    while ((match = openTabRegex.exec(content)) !== null) {
+      const [, name, nestedContent] = match;
+      const url = TagParser.extractContent(nestedContent, 'navigate')[0]?.trim();
+
+      actions.push({
+        type: 'open-tab',
+        name,
+        url,
+        nestedActions: this.parseNestedActions(nestedContent)
+      });
+    }
+
+    // Parse other actions (close-tab, switch-tab, list-tabs, etc.)
+    const simpleActions = [
+      'close-tab', 'switch-tab', 'list-tabs', 'navigate',
+      'click', 'type', 'press', 'wait-for', 'screenshot',
+      'analyze-screenshot', 'extract-text', 'extract-links',
+      'get-source', 'get-console', 'scroll', 'hover', 'mouse-move'
+    ];
+
+    for (const actionType of simpleActions) {
+      const regex = new RegExp(`<${actionType}([^>]*)>([^<]*)<\/${actionType}>`, 'g');
+      let actionMatch;
+
+      while ((actionMatch = regex.exec(content)) !== null) {
+        const [, attrs, value] = actionMatch;
+        const action = { type: actionType };
+
+        // Parse attributes
+        const attrRegex = /(\w+(?:-\w+)*)="([^"]*)"/g;
+        let attrMatch;
+        while ((attrMatch = attrRegex.exec(attrs)) !== null) {
+          action[attrMatch[1]] = attrMatch[2];
+        }
+
+        // Add value if present
+        if (value && value.trim()) {
+          action.value = value.trim();
+        }
+
+        actions.push(action);
+      }
+    }
+
+    return actions;
+  }
+
+  /**
+   * Parse nested actions within a tab
+   * @param {string} content - Nested actions content
+   * @returns {Array} Parsed nested actions
+   * @private
+   */
+  parseNestedActions(content) {
+    const actions = [];
+
+    const actionTypes = [
+      'navigate', 'click', 'type', 'press', 'wait-for', 'screenshot',
+      'analyze-screenshot', 'extract-text', 'extract-links',
+      'get-source', 'get-console', 'scroll', 'hover', 'mouse-move'
+    ];
+
+    for (const actionType of actionTypes) {
+      const regex = new RegExp(`<${actionType}([^>]*)>([^<]*)<\/${actionType}>|<${actionType}([^>]*)\/>`, 'g');
+      let match;
+
+      while ((match = regex.exec(content)) !== null) {
+        const [, attrs1, value, attrs2] = match;
+        const attrs = attrs1 || attrs2 || '';
+        const action = { type: actionType };
+
+        // Parse attributes
+        const attrRegex = /(\w+(?:-\w+)*)="([^"]*)"/g;
+        let attrMatch;
+        while ((attrMatch = attrRegex.exec(attrs)) !== null) {
+          action[attrMatch[1]] = attrMatch[2];
+        }
+
+        // Add value if present
+        if (value && value.trim()) {
+          action.value = value.trim();
+        }
+
+        actions.push(action);
+      }
+    }
+
+    return actions;
+  }
+
+  /**
+   * Get required parameters based on operation
+   * @returns {Array<string>} Array of required parameter names
+   */
+  getRequiredParameters() {
+    return ['operation'];
+  }
+
+  /**
+   * Custom parameter validation
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} Validation result
+   */
+  customValidateParameters(params) {
+    const errors = [];
+
+    if (!['search', 'fetch', 'interactive'].includes(params.operation)) {
+      errors.push('operation must be one of: search, fetch, interactive');
+      return { valid: false, errors };
+    }
+
+    switch (params.operation) {
+      case 'search':
+        if (!params.query) {
+          errors.push('query is required for search operation');
+        }
+        break;
+
+      case 'fetch':
+        if (!params.url) {
+          errors.push('url is required for fetch operation');
+        }
+        break;
+
+      case 'interactive':
+        if (!params.actions || !Array.isArray(params.actions) || params.actions.length === 0) {
+          errors.push('actions array is required for interactive operation');
+        }
+        break;
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Execute tool with parsed parameters
+   * @param {Object} params - Parsed parameters
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(params, context) {
+    const { operation } = params;
+    const { agentId } = context;
+
+    try {
+      // Ensure browser is initialized
+      await this.ensureBrowser();
+
+      let result;
+
+      switch (operation) {
+        case 'search':
+          result = await this.search(params.query, {
+            engine: params.engine || 'google',
+            maxResults: params.maxResults || 10,
+            agentId
+          });
+          break;
+
+        case 'fetch':
+          result = await this.fetch(params.url, {
+            formats: params.formats || ['title', 'text'],
+            agentId
+          });
+          break;
+
+        case 'interactive':
+          result = await this.interactive(params.actions, {
+            headless: params.headless !== false, // Default true
+            agentId,
+            context
+          });
+          break;
+
+        default:
+          throw new Error(`Unknown operation: ${operation}`);
+      }
+
+      return {
+        success: true,
+        operation,
+        result,
+        toolUsed: 'web'
+      };
+
+    } catch (error) {
+      this.logger?.error('Web tool execution failed', {
+        operation,
+        error: error.message,
+        agentId
+      });
+
+      return {
+        success: false,
+        operation,
+        error: error.message,
+        toolUsed: 'web'
+      };
+    }
+  }
+
+  /**
+   * Ensure browser is initialized
+   * @private
+   */
+  async ensureBrowser() {
+    if (this.browser && this.browser.isConnected()) {
+      return;
+    }
+
+    if (this.browserInitializing) {
+      // Wait for browser to finish initializing
+      while (this.browserInitializing) {
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+      return;
+    }
+
+    this.browserInitializing = true;
+
+    try {
+      this.logger?.info('Initializing Puppeteer browser');
+
+      this.browser = await puppeteer.launch({
+        headless: 'new', // Use new headless mode
+        args: [
+          '--no-sandbox',
+          '--disable-setuid-sandbox',
+          '--disable-dev-shm-usage',
+          '--disable-accelerated-2d-canvas',
+          '--disable-gpu',
+          '--disable-blink-features=AutomationControlled',
+          '--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+        ]
+      });
+
+      this.logger?.info('Puppeteer browser initialized successfully');
+
+    } catch (error) {
+      this.logger?.error('Failed to initialize browser', { error: error.message });
+      throw new Error(`Browser initialization failed: ${error.message}`);
+    } finally {
+      this.browserInitializing = false;
+    }
+  }
+
+  /**
+   * Search the web using a known search engine
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<Object>} Search results
+   */
+  async search(query, options = {}) {
+    const { engine = 'google', maxResults = 10, agentId } = options;
+
+    // Validate query
+    if (!query || typeof query !== 'string' || query.trim().length === 0) {
+      throw new Error('Search query is required and must be a non-empty string');
+    }
+
+    const searchEngine = this.searchEngines.find(e => e.name === engine);
+    if (!searchEngine) {
+      throw new Error(`Unknown search engine: ${engine}. Available: ${this.searchEngines.map(e => e.name).join(', ')}`);
+    }
+
+    // Ensure browser is initialized
+    await this.ensureBrowser();
+
+    this.logger?.info('Performing web search', { query, engine, agentId });
+
+    // Create temporary page for search
+    const page = await this.browser.newPage();
+
+    try {
+      // Navigate to search engine
+      const searchUrl = `${searchEngine.url}${encodeURIComponent(query)}`;
+      await page.goto(searchUrl, { waitUntil: 'networkidle2', timeout: this.DEFAULT_TIMEOUT });
+
+      // Wait for results
+      await page.waitForSelector(searchEngine.waitSelector, { timeout: this.DEFAULT_TIMEOUT });
+
+      // Extract results
+      const results = await page.evaluate((selector, max) => {
+        const links = Array.from(document.querySelectorAll(selector));
+        return links.slice(0, max).map(link => ({
+          url: link.href,
+          title: link.textContent.trim(),
+          description: link.closest('.g, .b_algo, .result')?.textContent.trim() || ''
+        })).filter(result => result.url && result.url.startsWith('http'));
+      }, searchEngine.resultsSelector, maxResults);
+
+      this.logger?.info('Search completed', { resultsCount: results.length, agentId });
+
+      return {
+        success: true,
+        query,
+        engine,
+        resultsCount: results.length,
+        results
+      };
+
+    } finally {
+      await page.close();
+    }
+  }
+
+  /**
+   * Fetch web content in various formats
+   * @param {string} url - URL to fetch
+   * @param {Object} options - Fetch options
+   * @returns {Promise<Object>} Fetched content
+   */
+  async fetch(url, options = {}) {
+    const { formats = ['title', 'text'], agentId } = options;
+
+    // Ensure browser is initialized
+    await this.ensureBrowser();
+
+    this.logger?.info('Fetching web content', { url, formats, agentId });
+
+    // Create temporary page
+    const page = await this.browser.newPage();
+
+    try {
+      // Listen for console messages if requested
+      const consoleMessages = [];
+      if (formats.includes('console')) {
+        page.on('console', msg => {
+          consoleMessages.push({
+            type: msg.type(),
+            text: msg.text()
+          });
+        });
+      }
+
+      // Navigate to URL
+      await page.goto(url, { waitUntil: 'networkidle2', timeout: this.DEFAULT_TIMEOUT });
+
+      const result = { url };
+
+      // Extract requested formats
+      for (const format of formats) {
+        switch (format) {
+          case 'title':
+            result.title = await page.title();
+            break;
+
+          case 'text':
+            result.text = await page.evaluate(() => document.body.innerText);
+            break;
+
+          case 'links':
+            result.links = await page.evaluate(() => {
+              return Array.from(document.querySelectorAll('a[href]')).map(a => ({
+                href: a.href,
+                text: a.textContent.trim()
+              }));
+            });
+            break;
+
+          case 'html':
+            result.html = await page.content();
+            break;
+
+          case 'console':
+            result.consoleMessages = consoleMessages;
+            break;
+        }
+      }
+
+      this.logger?.info('Fetch completed', { url, formats, agentId });
+
+      return {
+        success: true,
+        ...result
+      };
+
+    } finally {
+      await page.close();
+    }
+  }
+
+  /**
+   * Interactive browser automation with command chaining
+   * @param {Array} actions - Array of actions to execute
+   * @param {Object} options - Options
+   * @returns {Promise<Object>} Results of all actions
+   */
+  async interactive(actions, options = {}) {
+    const { headless = true, agentId, context } = options;
+
+    // Ensure browser is initialized
+    await this.ensureBrowser();
+
+    this.logger?.info('Starting interactive session', {
+      actionsCount: actions.length,
+      headless,
+      agentId
+    });
+
+    const results = [];
+
+    // Initialize agent tabs if not exists
+    if (!this.agentTabs.has(agentId)) {
+      this.agentTabs.set(agentId, new Map());
+    }
+
+    const agentTabsMap = this.agentTabs.get(agentId);
+
+    for (const action of actions) {
+      try {
+        let actionResult;
+
+        switch (action.type) {
+          case 'open-tab':
+            actionResult = await this.openTab(agentId, action.name, action.url, headless, action.nestedActions, context);
+            break;
+
+          case 'close-tab':
+            actionResult = await this.closeTab(agentId, action.name);
+            break;
+
+          case 'switch-tab':
+            actionResult = await this.switchTab(agentId, action.name);
+            break;
+
+          case 'list-tabs':
+            actionResult = await this.listTabs(agentId);
+            break;
+
+          default:
+            // For actions that need a tab context, we need to specify which tab
+            // For now, we'll skip these at the top level
+            actionResult = {
+              success: false,
+              error: `Action ${action.type} must be executed within a tab context (use open-tab with nestedActions)`
+            };
+        }
+
+        results.push({
+          action: action.type,
+          ...actionResult
+        });
+
+      } catch (error) {
+        this.logger?.error('Action failed', {
+          action: action.type,
+          error: error.message,
+          agentId
+        });
+
+        results.push({
+          action: action.type,
+          success: false,
+          error: error.message
+        });
+      }
+    }
+
+    return {
+      success: results.every(r => r.success !== false),
+      actionsExecuted: results.length,
+      results
+    };
+  }
+
+  /**
+   * Open a new tab with nested actions
+   * @param {string} agentId - Agent identifier
+   * @param {string} tabName - Unique tab name
+   * @param {string} url - Initial URL
+   * @param {boolean} headless - Headless mode
+   * @param {Array} nestedActions - Actions to execute in this tab
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Result
+   */
+  async openTab(agentId, tabName, url, headless, nestedActions = [], context = {}) {
+    // Initialize agent tabs if not exists
+    if (!this.agentTabs.has(agentId)) {
+      this.agentTabs.set(agentId, new Map());
+    }
+
+    const agentTabsMap = this.agentTabs.get(agentId);
+
+    // Check if tab already exists
+    if (agentTabsMap.has(tabName)) {
+      throw new Error(`Tab '${tabName}' already exists for agent ${agentId}`);
+    }
+
+    this.logger?.info('Opening tab', { agentId, tabName, url, headless });
+
+    // Create new page
+    const page = await this.browser.newPage();
+
+    // Set viewport
+    await page.setViewport({ width: 1280, height: 720 });
+
+    // Track console messages
+    const consoleMessages = [];
+    page.on('console', msg => {
+      consoleMessages.push({
+        type: msg.type(),
+        text: msg.text(),
+        timestamp: Date.now()
+      });
+    });
+
+    // Store tab info
+    const tabInfo = {
+      page,
+      url,
+      lastActivity: Date.now(),
+      headless,
+      consoleMessages,
+      name: tabName
+    };
+
+    agentTabsMap.set(tabName, tabInfo);
+
+    const results = [];
+
+    try {
+      // Navigate to initial URL if provided
+      if (url) {
+        await page.goto(url, { waitUntil: 'networkidle2', timeout: this.DEFAULT_TIMEOUT });
+        tabInfo.url = url;
+        tabInfo.lastActivity = Date.now();
+      }
+
+      // Execute nested actions
+      for (const action of nestedActions) {
+        const actionResult = await this.executeTabAction(page, action, tabInfo, context);
+        results.push({
+          action: action.type,
+          ...actionResult
+        });
+        tabInfo.lastActivity = Date.now();
+      }
+
+      return {
+        success: true,
+        tabName,
+        url: tabInfo.url,
+        actionsExecuted: results.length,
+        results
+      };
+
+    } catch (error) {
+      this.logger?.error('Failed to open tab', {
+        agentId,
+        tabName,
+        error: error.message
+      });
+
+      // Clean up on error
+      await page.close();
+      agentTabsMap.delete(tabName);
+
+      throw error;
+    }
+  }
+
+  /**
+   * Execute an action in a tab context
+   * @param {Page} page - Puppeteer page
+   * @param {Object} action - Action to execute
+   * @param {Object} tabInfo - Tab information
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Action result
+   * @private
+   */
+  async executeTabAction(page, action, tabInfo, context) {
+    switch (action.type) {
+      case 'navigate':
+        await page.goto(action.value || action.url, {
+          waitUntil: 'networkidle2',
+          timeout: this.DEFAULT_TIMEOUT
+        });
+        tabInfo.url = page.url();
+        return { success: true, url: tabInfo.url };
+
+      case 'click':
+        await page.click(action.selector, {
+          button: action.button || 'left'
+        });
+        return { success: true, selector: action.selector };
+
+      case 'type':
+        await page.type(action.selector, action.text || action.value);
+        return { success: true, selector: action.selector, text: action.text };
+
+      case 'press':
+        await page.keyboard.press(action.key || action.value);
+        return { success: true, key: action.key };
+
+      case 'wait-for':
+        const timeout = action.timeout ? parseInt(action.timeout, 10) : this.DEFAULT_TIMEOUT;
+        await page.waitForSelector(action.selector, { timeout });
+        return { success: true, selector: action.selector };
+
+      case 'screenshot':
+        return await this.takeScreenshot(page, action, context);
+
+      case 'analyze-screenshot':
+        return await this.analyzeScreenshot(page, action.value, context);
+
+      case 'extract-text':
+        const text = await page.evaluate((sel) => {
+          const element = document.querySelector(sel);
+          return element ? element.innerText : null;
+        }, action.selector);
+        return { success: true, selector: action.selector, text };
+
+      case 'extract-links':
+        const links = await page.evaluate((sel) => {
+          const elements = document.querySelectorAll(sel);
+          return Array.from(elements).map(a => ({
+            href: a.href,
+            text: a.textContent.trim()
+          }));
+        }, action.selector);
+        return { success: true, selector: action.selector, links };
+
+      case 'get-source':
+        const html = await page.content();
+        return { success: true, html };
+
+      case 'get-console':
+        return {
+          success: true,
+          consoleMessages: [...tabInfo.consoleMessages]
+        };
+
+      case 'scroll':
+        await page.evaluate((sel) => {
+          if (sel) {
+            document.querySelector(sel)?.scrollIntoView();
+          } else {
+            window.scrollTo(0, document.body.scrollHeight);
+          }
+        }, action.selector);
+        return { success: true };
+
+      case 'hover':
+        await page.hover(action.selector);
+        return { success: true, selector: action.selector };
+
+      case 'mouse-move':
+        await page.hover(action.selector);
+        return { success: true, selector: action.selector };
+
+      default:
+        throw new Error(`Unknown action type: ${action.type}`);
+    }
+  }
+
+  /**
+   * Take screenshot of page
+   * @param {Page} page - Puppeteer page
+   * @param {Object} options - Screenshot options
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Screenshot result
+   * @private
+   */
+  async takeScreenshot(page, options, context) {
+    const format = options.format || 'file';
+    const screenshotPath = options.path;
+
+    if (format === 'base64') {
+      const screenshot = await page.screenshot({ encoding: 'base64' });
+      return {
+        success: true,
+        format: 'base64',
+        screenshot
+      };
+    }
+
+    // File format
+    let filePath;
+
+    if (screenshotPath) {
+      // Save to project directory if path is provided
+      const projectDir = context.directoryAccess?.workingDirectory || context.projectDir || process.cwd();
+      filePath = path.isAbsolute(screenshotPath)
+        ? screenshotPath
+        : path.join(projectDir, screenshotPath);
+    } else {
+      // Save to temp directory
+      const filename = `screenshot-${Date.now()}.png`;
+      filePath = path.join(this.TEMP_DIR, filename);
+    }
+
+    await page.screenshot({ path: filePath });
+
+    return {
+      success: true,
+      format: 'file',
+      path: filePath
+    };
+  }
+
+  /**
+   * Analyze screenshot using AI vision model
+   * @param {Page} page - Puppeteer page
+   * @param {string} question - Question for AI
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Analysis result
+   * @private
+   */
+  async analyzeScreenshot(page, question, context) {
+    // Take screenshot as base64
+    const screenshot = await page.screenshot({ encoding: 'base64' });
+
+    // Get AI service from context
+    const aiService = context.aiService;
+    if (!aiService) {
+      throw new Error('AI service not available for screenshot analysis');
+    }
+
+    this.logger?.info('Analyzing screenshot with AI', {
+      question: question.substring(0, 100),
+      agentId: context.agentId
+    });
+
+    try {
+      // Use vision model (prefer o3 if available, fallback to gpt-4-vision)
+      const model = 'o3'; // Will be mapped by AI service
+
+      // Create message with image
+      const response = await aiService.sendMessage(
+        model,
+        question,
+        {
+          agentId: context.agentId,
+          images: [`data:image/png;base64,${screenshot}`],
+          apiKey: context.apiKey,
+          customApiKeys: context.customApiKeys,
+          platformProvided: context.platformProvided
+        }
+      );
+
+      return {
+        success: true,
+        question,
+        analysis: response.content,
+        model: response.model || model
+      };
+
+    } catch (error) {
+      this.logger?.error('Screenshot analysis failed', {
+        error: error.message,
+        agentId: context.agentId
+      });
+
+      throw new Error(`Screenshot analysis failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Close a tab
+   * @param {string} agentId - Agent identifier
+   * @param {string} tabName - Tab name to close
+   * @returns {Promise<Object>} Result
+   */
+  async closeTab(agentId, tabName) {
+    const agentTabsMap = this.agentTabs.get(agentId);
+    if (!agentTabsMap || !agentTabsMap.has(tabName)) {
+      throw new Error(`Tab '${tabName}' not found for agent ${agentId}`);
+    }
+
+    const tabInfo = agentTabsMap.get(tabName);
+
+    this.logger?.info('Closing tab', { agentId, tabName });
+
+    await tabInfo.page.close();
+    agentTabsMap.delete(tabName);
+
+    return {
+      success: true,
+      tabName,
+      message: `Tab '${tabName}' closed`
+    };
+  }
+
+  /**
+   * Switch to an existing tab
+   * @param {string} agentId - Agent identifier
+   * @param {string} tabName - Tab name to switch to
+   * @returns {Promise<Object>} Result
+   */
+  async switchTab(agentId, tabName) {
+    const agentTabsMap = this.agentTabs.get(agentId);
+    if (!agentTabsMap || !agentTabsMap.has(tabName)) {
+      throw new Error(`Tab '${tabName}' not found for agent ${agentId}`);
+    }
+
+    const tabInfo = agentTabsMap.get(tabName);
+    tabInfo.lastActivity = Date.now();
+
+    return {
+      success: true,
+      tabName,
+      url: tabInfo.url,
+      message: `Switched to tab '${tabName}'`
+    };
+  }
+
+  /**
+   * List all active tabs for an agent
+   * @param {string} agentId - Agent identifier
+   * @returns {Promise<Object>} List of tabs
+   */
+  async listTabs(agentId) {
+    const agentTabsMap = this.agentTabs.get(agentId);
+
+    if (!agentTabsMap || agentTabsMap.size === 0) {
+      return {
+        success: true,
+        tabCount: 0,
+        tabs: [],
+        message: 'No active tabs'
+      };
+    }
+
+    const tabs = [];
+    for (const [name, info] of agentTabsMap.entries()) {
+      tabs.push({
+        name,
+        url: info.url,
+        idleTime: Date.now() - info.lastActivity,
+        headless: info.headless
+      });
+    }
+
+    return {
+      success: true,
+      tabCount: tabs.length,
+      tabs
+    };
+  }
+
+  /**
+   * Start cleanup timer for idle tabs
+   * @private
+   */
+  startCleanupTimer() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+
+    this.cleanupTimer = setInterval(() => {
+      this.cleanupIdleTabs();
+    }, this.CLEANUP_INTERVAL);
+  }
+
+  /**
+   * Cleanup idle tabs (1-hour timeout)
+   * @private
+   */
+  async cleanupIdleTabs() {
+    const now = Date.now();
+    const tabsToClose = [];
+
+    for (const [agentId, agentTabsMap] of this.agentTabs.entries()) {
+      for (const [tabName, tabInfo] of agentTabsMap.entries()) {
+        const idleTime = now - tabInfo.lastActivity;
+
+        if (idleTime > this.TAB_IDLE_TIMEOUT) {
+          tabsToClose.push({ agentId, tabName, tabInfo });
+        }
+      }
+    }
+
+    if (tabsToClose.length > 0) {
+      this.logger?.info('Cleaning up idle tabs', {
+        count: tabsToClose.length
+      });
+
+      for (const { agentId, tabName, tabInfo } of tabsToClose) {
+        try {
+          await tabInfo.page.close();
+          this.agentTabs.get(agentId).delete(tabName);
+          this.logger?.debug('Closed idle tab', { agentId, tabName });
+        } catch (error) {
+          this.logger?.error('Failed to close idle tab', {
+            agentId,
+            tabName,
+            error: error.message
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Cleanup all tabs for an agent (called when agent is deleted)
+   * @param {string} agentId - Agent identifier
+   * @returns {Promise<Object>} Cleanup result
+   */
+  async cleanupAgent(agentId) {
+    const agentTabsMap = this.agentTabs.get(agentId);
+
+    if (!agentTabsMap) {
+      return {
+        success: true,
+        agentId,
+        closedTabs: 0,
+        message: 'No tabs to clean up'
+      };
+    }
+
+    this.logger?.info('Cleaning up agent tabs', {
+      agentId,
+      tabCount: agentTabsMap.size
+    });
+
+    let closedCount = 0;
+
+    for (const [tabName, tabInfo] of agentTabsMap.entries()) {
+      try {
+        await tabInfo.page.close();
+        closedCount++;
+      } catch (error) {
+        this.logger?.error('Failed to close tab during cleanup', {
+          agentId,
+          tabName,
+          error: error.message
+        });
+      }
+    }
+
+    this.agentTabs.delete(agentId);
+
+    return {
+      success: true,
+      agentId,
+      closedTabs: closedCount,
+      message: `Closed ${closedCount} tabs for agent ${agentId}`
+    };
+  }
+
+  /**
+   * Ensure temp directory exists
+   * @private
+   */
+  async ensureTempDir() {
+    try {
+      await fs.mkdir(this.TEMP_DIR, { recursive: true });
+    } catch (error) {
+      this.logger?.warn('Failed to create temp directory', {
+        path: this.TEMP_DIR,
+        error: error.message
+      });
+    }
+  }
+
+  /**
+   * Cleanup resources
+   */
+  async cleanup() {
+    // Stop cleanup timer
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+
+    // Close all tabs
+    for (const [agentId] of this.agentTabs.entries()) {
+      await this.cleanupAgent(agentId);
+    }
+
+    // Close browser
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+
+    // Clean temp directory
+    try {
+      await fs.rm(this.TEMP_DIR, { recursive: true, force: true });
+    } catch (error) {
+      this.logger?.warn('Failed to clean temp directory', {
+        path: this.TEMP_DIR,
+        error: error.message
+      });
+    }
+  }
+}
+
+export default WebTool;