onbuzz 3.3.0

package/src/tools/visualEditorTool.js

@@ -0,0 +1,1175 @@
+/**
+ * @file tools/visualEditorTool.js
+ * @description Tool for visual editor integration - allows agents to interact
+ * with user's web application visually and receive element selections with
+ * source code locations.
+ *
+ * Phase 1: Basic actions (get-context, set-app-url, get-status)
+ * Phase 5: Full actions (highlight, scroll-to, get-source, reload, set-mode)
+ */
+
+import { BaseTool } from './baseTool.js';
+import { getVisualEditorBridge, InstanceStatus } from '../services/visualEditorBridge.js';
+import { getVisualEditorServer, getVisualEditorPort, getVisualEditorBaseUrl } from '../services/visualEditorServer.js';
+import { getPortTracker } from '../services/portTracker.js';
+import { getProjectDetector, PROJECT_TYPES } from '../services/projectDetector.js';
+
+/**
+ * Supported actions for the Visual Editor Tool
+ */
+const ACTIONS = {
+  GET_CONTEXT: 'get-context',
+  SET_APP_URL: 'set-app-url',
+  GET_STATUS: 'get-status',
+  CLEAR_CONTEXT: 'clear-context',
+  // Server management actions
+  START_SERVER: 'start-server',      // Start dev server for project
+  SERVE_STATIC: 'serve-static',      // Serve static files directly
+  DETECT_PROJECT: 'detect-project',  // Detect project type
+  // UI control actions
+  OPEN_EDITOR: 'open-editor',        // Open visual editor in UI with specified URL
+  // Phase 5 actions
+  HIGHLIGHT: 'highlight',
+  SCROLL_TO: 'scroll-to',
+  GET_SOURCE: 'get-source',
+  RELOAD: 'reload',
+  SET_MODE: 'set-mode'
+};
+
+/**
+ * VisualEditorTool - Interact with user's web application visually
+ */
+export class VisualEditorTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+
+    // Override tool ID
+    this.id = 'visual-editor';
+
+    // Tool properties
+    this.isAsync = false;
+    this.requiresProject = false;
+
+    // Bridge instance (lazy loaded)
+    this._bridge = null;
+  }
+
+  /**
+   * Get bridge instance (lazy load)
+   * @private
+   */
+  _getBridge() {
+    if (!this._bridge) {
+      this._bridge = getVisualEditorBridge();
+    }
+    return this._bridge;
+  }
+
+  /**
+   * Get tool description for agent system prompt
+   * @returns {string} Formatted tool description
+   */
+  getDescription() {
+    return `Tool: Visual Editor - Interact with the user's web application visually.
+
+**PURPOSE:** Allow users to visually select elements in their app preview.
+You receive context about selected elements including source code location.
+
+**COMPLETE WORKFLOW - When user wants to visually edit their app:**
+
+1. **If app is NOT running yet:**
+   - Use \`detect-project\` to identify project type
+   - Use \`serve-static\` (for HTML) or start dev server via Terminal tool
+
+2. **Open the Visual Editor UI:**
+   - Use \`open-editor\` with the app URL to show the visual editor to the user
+   - This opens the preview panel in the UI automatically
+
+3. **User clicks elements in the preview**
+   - You automatically receive element context in messages
+
+**ACTIONS:**
+
+**open-editor** - Open visual editor UI with app URL (RECOMMENDED after starting server)
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "open-editor",
+  "parameters": {
+    "url": "http://localhost:3000"
+  }
+}
+\`\`\`
+This opens the visual editor panel in the user's UI and loads your app for visual selection.
+
+**detect-project** - Detect project type and get server suggestions
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "detect-project"
+}
+\`\`\`
+Returns: projectType, framework, serverCommand, defaultPort
+
+**serve-static** - Serve static HTML files directly (no external server needed)
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "serve-static",
+  "parameters": {
+    "directory": "public"  // Optional: subdirectory to serve, defaults to project root
+  }
+}
+\`\`\`
+Returns: url (e.g., http://localhost:4000/)
+
+**set-app-url** - Configure the app URL for visual editing
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "set-app-url",
+  "parameters": {
+    "url": "http://localhost:3000"
+  }
+}
+\`\`\`
+
+**get-context** - Get current visual selection (if any)
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "get-context"
+}
+\`\`\`
+
+**get-status** - Get visual editor instance status
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "get-status"
+}
+\`\`\`
+
+**clear-context** - Clear the current visual selection
+\`\`\`json
+{
+  "toolId": "visual-editor",
+  "action": "clear-context"
+}
+\`\`\`
+
+**AUTOMATIC CONTEXT INJECTION:**
+When user selects an element, you receive visual context automatically:
+\`\`\`
+[VISUAL CONTEXT - User selected element]
+Element: <button class="btn-primary">
+Source: src/components/Form.tsx:42 (Component: SubmitButton)
+Code:
+  41│  return (
+► 42│    <button className="btn-primary">Submit</button>
+  43│  );
+\`\`\`
+
+**WORKFLOW EXAMPLE:**
+1. User: "Let me visually edit the app"
+2. Agent: detect-project → React (Vite)
+3. Agent: Terminal → npm run dev (starts on port 5173)
+4. Agent: open-editor → url: http://localhost:5173 (opens UI panel)
+5. Agent: "Visual editor ready! Click any element to select it."
+6. User clicks element → context injected automatically
+7. Agent: Uses filesystem tool to edit the source file
+
+**TIPS:**
+- For static HTML: Use \`serve-static\` then \`open-editor\`
+- For React/Vue/Next.js: Start dev server via Terminal, then \`open-editor\`
+- Always use \`open-editor\` to show the preview UI to the user
+- Always acknowledge visual context when user selects element
+- Use source location (file:line) to make targeted code changes`;
+  }
+
+  /**
+   * Get supported actions
+   * @returns {Array<string>} Supported action names
+   */
+  getSupportedActions() {
+    return Object.values(ACTIONS);
+  }
+
+  /**
+   * Get required parameters
+   * @returns {Array<string>} Required parameter names
+   */
+  getRequiredParameters() {
+    return ['action'];
+  }
+
+  /**
+   * Parse parameters from tool command content
+   * @param {string|Object} content - Raw content or parsed object
+   * @returns {Object} Parsed parameters
+   */
+  parseParameters(content) {
+    // Handle JSON format
+    if (typeof content === 'object' && content !== null) {
+      return this._parseJSONParams(content);
+    }
+
+    // Handle string format
+    if (typeof content === 'string') {
+      const trimmed = content.trim();
+
+      // Try to parse as JSON
+      if (trimmed.startsWith('{')) {
+        try {
+          const parsed = JSON.parse(trimmed);
+          return this._parseJSONParams(parsed);
+        } catch (err) {
+          // Fall through to XML parsing
+        }
+      }
+
+      // Parse as XML
+      return this._parseXMLParams(content);
+    }
+
+    throw new Error('Invalid parameter format');
+  }
+
+  /**
+   * Parse JSON parameters
+   * @private
+   */
+  _parseJSONParams(obj) {
+    // Handle parameters wrapper
+    if (obj.parameters) {
+      return {
+        action: obj.action || ACTIONS.GET_CONTEXT,
+        ...obj.parameters
+      };
+    }
+
+    return {
+      action: obj.action || ACTIONS.GET_CONTEXT,
+      url: obj.url,
+      selector: obj.selector,
+      mode: obj.mode,
+      projectRoot: obj.projectRoot
+    };
+  }
+
+  /**
+   * Parse XML parameters
+   * @private
+   */
+  _parseXMLParams(content) {
+    const extractTag = (tag) => {
+      const regex = new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'i');
+      const match = regex.exec(content);
+      return match ? match[1].trim() : null;
+    };
+
+    return {
+      action: extractTag('action') || ACTIONS.GET_CONTEXT,
+      url: extractTag('url'),
+      selector: extractTag('selector'),
+      mode: extractTag('mode'),
+      projectRoot: extractTag('project-root') || extractTag('projectRoot')
+    };
+  }
+
+  /**
+   * Validate parameters
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} Validation result
+   */
+  customValidateParameters(params) {
+    // Validate action
+    if (!Object.values(ACTIONS).includes(params.action)) {
+      return {
+        valid: false,
+        error: `Invalid action: ${params.action}. Valid actions: ${Object.values(ACTIONS).join(', ')}`
+      };
+    }
+
+    // Validate action-specific parameters
+    if (params.action === ACTIONS.SET_APP_URL && !params.url) {
+      return {
+        valid: false,
+        error: 'URL is required for set-app-url action'
+      };
+    }
+
+    // Phase 5 actions validation (placeholder)
+    if ([ACTIONS.HIGHLIGHT, ACTIONS.SCROLL_TO, ACTIONS.GET_SOURCE].includes(params.action)) {
+      if (!params.selector) {
+        return {
+          valid: false,
+          error: `Selector is required for ${params.action} action`
+        };
+      }
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Execute tool with parsed parameters
+   * @param {Object|string} params - Parsed parameters or raw content
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(params, context = {}) {
+    try {
+      const { agentId } = context;
+
+      // Auto-parse if string
+      if (typeof params === 'string') {
+        params = this.parseParameters(params);
+      } else if (typeof params === 'object' && params !== null && !params.action) {
+        params = this.parseParameters(params);
+      }
+
+      // Get bridge
+      const bridge = this._getBridge();
+
+      // Check if bridge is enabled
+      if (!bridge.isEnabled()) {
+        return {
+          success: false,
+          error: 'Visual editor is disabled. Enable it in configuration.'
+        };
+      }
+
+      // Validate
+      const validation = this.customValidateParameters(params);
+      if (!validation.valid) {
+        return {
+          success: false,
+          error: validation.error
+        };
+      }
+
+      // Route to action handler
+      switch (params.action) {
+        case ACTIONS.GET_CONTEXT:
+          return this._handleGetContext(bridge, agentId);
+
+        case ACTIONS.SET_APP_URL:
+          return this._handleSetAppUrl(bridge, agentId, params);
+
+        case ACTIONS.GET_STATUS:
+          return this._handleGetStatus(bridge, agentId);
+
+        case ACTIONS.CLEAR_CONTEXT:
+          return this._handleClearContext(bridge, agentId);
+
+        // Server management actions
+        case ACTIONS.DETECT_PROJECT:
+          return this._handleDetectProject(context);
+
+        case ACTIONS.SERVE_STATIC:
+          return this._handleServeStatic(bridge, agentId, params, context);
+
+        case ACTIONS.START_SERVER:
+          return this._handleStartServer(bridge, agentId, params, context);
+
+        // UI control actions
+        case ACTIONS.OPEN_EDITOR:
+          return this._handleOpenEditor(bridge, agentId, params, context);
+
+        // Phase 5 actions - full editor control
+        case ACTIONS.HIGHLIGHT:
+          return this._handleHighlight(bridge, agentId, params);
+
+        case ACTIONS.SCROLL_TO:
+          return this._handleScrollTo(bridge, agentId, params);
+
+        case ACTIONS.GET_SOURCE:
+          return this._handleGetSource(bridge, agentId, params);
+
+        case ACTIONS.RELOAD:
+          return this._handleReload(bridge, agentId);
+
+        case ACTIONS.SET_MODE:
+          return this._handleSetMode(bridge, agentId, params);
+
+        default:
+          return {
+            success: false,
+            error: `Unknown action: ${params.action}`
+          };
+      }
+
+    } catch (error) {
+      this.logger?.error('Visual editor tool error:', error);
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+
+  /**
+   * Handle get-context action
+   * @private
+   */
+  _handleGetContext(bridge, agentId) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required to get visual context'
+      };
+    }
+
+    const context = bridge.getVisualContext(agentId);
+
+    if (!context) {
+      return {
+        success: true,
+        hasContext: false,
+        message: 'No visual selection. User can select an element in Visual Mode.'
+      };
+    }
+
+    // Format context for agent consumption
+    return {
+      success: true,
+      hasContext: true,
+      context: {
+        selector: context.selector,
+        tagName: context.tagName,
+        text: context.text,
+        attributes: context.attributes,
+        sourceHint: context.sourceHint,
+        receivedAt: context.receivedAt
+      },
+      formatted: this._formatContextForAgent(context)
+    };
+  }
+
+  /**
+   * Handle set-app-url action
+   * @private
+   */
+  async _handleSetAppUrl(bridge, agentId, params) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required to set app URL'
+      };
+    }
+
+    // Validate URL format
+    try {
+      new URL(params.url);
+    } catch {
+      return {
+        success: false,
+        error: `Invalid URL format: ${params.url}`
+      };
+    }
+
+    // Get or create instance
+    const instance = await bridge.getInstance(agentId, {
+      appUrl: params.url,
+      projectRoot: params.projectRoot
+    });
+
+    return {
+      success: true,
+      message: `App URL configured: ${params.url}`,
+      instance: {
+        agentId: instance.agentId,
+        appUrl: instance.appUrl,
+        projectRoot: instance.projectRoot,
+        status: instance.status
+      }
+    };
+  }
+
+  /**
+   * Handle get-status action
+   * @private
+   */
+  _handleGetStatus(bridge, agentId) {
+    if (!agentId) {
+      // Return global status
+      const instances = bridge.listInstances();
+      return {
+        success: true,
+        instanceCount: instances.length,
+        maxInstances: bridge.maxInstances,
+        instances: instances.map(inst => ({
+          agentId: inst.agentId,
+          status: inst.status,
+          appUrl: inst.appUrl,
+          hasContext: inst.hasContext,
+          idleMs: inst.idleMs
+        }))
+      };
+    }
+
+    const status = bridge.getStatus(agentId);
+
+    if (!status.exists) {
+      return {
+        success: true,
+        exists: false,
+        message: 'No visual editor instance for this agent. Use set-app-url to configure.'
+      };
+    }
+
+    return {
+      success: true,
+      exists: true,
+      status: status.status,
+      appUrl: status.appUrl,
+      projectRoot: status.projectRoot,
+      editorUrl: status.editorUrl,
+      hasVisualContext: status.hasVisualContext,
+      subscriberCount: status.subscriberCount,
+      idleMs: status.idleMs,
+      error: status.error
+    };
+  }
+
+  /**
+   * Handle clear-context action
+   * @private
+   */
+  _handleClearContext(bridge, agentId) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required to clear visual context'
+      };
+    }
+
+    const cleared = bridge.clearVisualContext(agentId);
+
+    return {
+      success: true,
+      cleared,
+      message: cleared
+        ? 'Visual context cleared'
+        : 'No visual context to clear'
+    };
+  }
+
+  // === Server Management Action Handlers ===
+
+  /**
+   * Handle detect-project action
+   * @private
+   */
+  async _handleDetectProject(context) {
+    const projectRoot = context.projectRoot || context.workingDirectory;
+
+    if (!projectRoot) {
+      return {
+        success: false,
+        error: 'No project directory available. Set projectRoot in context.'
+      };
+    }
+
+    const detector = getProjectDetector();
+    const detection = await detector.detect(projectRoot);
+
+    if (detection.error) {
+      return {
+        success: false,
+        error: detection.error
+      };
+    }
+
+    const serverInfo = detector.getSuggestedServerCommand(detection);
+
+    return {
+      success: true,
+      projectDir: projectRoot,
+      projectType: detection.projectType,
+      framework: detection.framework,
+      isStatic: detection.isStatic,
+      entryPoints: detection.entryPoints,
+      serverCommand: serverInfo.command,
+      defaultPort: serverInfo.port,
+      availableScripts: detection.availableScripts,
+      confidence: detection.confidence,
+      message: detection.isStatic
+        ? `Static HTML project detected. Use 'serve-static' action to preview.`
+        : `${detection.framework || detection.projectType} project detected. Run "${serverInfo.command}" to start server.`
+    };
+  }
+
+  /**
+   * Handle serve-static action - serve static files via Visual Editor Server
+   * @private
+   */
+  async _handleServeStatic(bridge, agentId, params, context) {
+    const projectRoot = context.projectRoot || context.workingDirectory;
+
+    if (!projectRoot) {
+      return {
+        success: false,
+        error: 'No project directory available'
+      };
+    }
+
+    // Get Visual Editor Server
+    const server = getVisualEditorServer();
+
+    // Start server if not running
+    if (!server.isRunning) {
+      await server.start();
+    }
+
+    // Determine directory to serve
+    const directory = params.directory || '';
+    const fullPath = directory ? `${projectRoot}/${directory}` : projectRoot;
+
+    // Register static directory with the server
+    server.registerStaticDir(agentId, fullPath);
+
+    // Generate URL for static files using configurable port
+    const baseUrl = getVisualEditorBaseUrl();
+    const staticUrl = `${baseUrl}/static/${agentId}/`;
+
+    // Also set as app URL for the visual editor
+    if (agentId) {
+      const instance = await bridge.getInstance(agentId, {
+        appUrl: staticUrl,
+        projectRoot
+      });
+
+      bridge.updateStatus(agentId, instance.status, {
+        editorUrl: `${baseUrl}?agentId=${agentId}&appUrl=${encodeURIComponent(staticUrl)}`
+      });
+    }
+
+    return {
+      success: true,
+      url: staticUrl,
+      directory: fullPath,
+      message: `Static files served at ${staticUrl}. Visual Mode ready.`,
+      editorUrl: `${baseUrl}?agentId=${agentId}&appUrl=${encodeURIComponent(staticUrl)}`
+    };
+  }
+
+  /**
+   * Handle start-server action - provides server command info
+   * (Actual server start should be done via Terminal tool)
+   * @private
+   */
+  async _handleStartServer(bridge, agentId, params, context) {
+    const projectRoot = context.projectRoot || context.workingDirectory;
+
+    if (!projectRoot) {
+      return {
+        success: false,
+        error: 'No project directory available'
+      };
+    }
+
+    // Detect project
+    const detector = getProjectDetector();
+    const detection = await detector.detect(projectRoot);
+
+    // Get port tracker
+    const portTracker = getPortTracker();
+    const preferredPort = params.port || detection.defaultPort;
+
+    // Find available port
+    const availablePort = await portTracker.findAvailablePort(
+      preferredPort,
+      preferredPort + 100
+    );
+
+    if (!availablePort) {
+      return {
+        success: false,
+        error: `No available ports in range ${preferredPort}-${preferredPort + 100}`
+      };
+    }
+
+    // Get command with port
+    const serverInfo = detector.getSuggestedServerCommand(detection, availablePort);
+
+    return {
+      success: true,
+      projectType: detection.projectType,
+      framework: detection.framework,
+      command: serverInfo.command,
+      port: availablePort,
+      expectedUrl: `http://localhost:${availablePort}`,
+      instructions: `
+To start the server:
+1. Use Terminal tool: ${serverInfo.command}
+2. Wait for server to start
+3. Use set-app-url with: http://localhost:${availablePort}
+
+Or for static HTML, use 'serve-static' action instead.
+      `.trim()
+    };
+  }
+
+  // === UI Control Action Handlers ===
+
+  /**
+   * Handle open-editor action - opens visual editor UI with specified app URL
+   * Broadcasts a message to the web-ui to enable visual editor mode
+   * @private
+   */
+  async _handleOpenEditor(bridge, agentId, params, context) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required to open visual editor'
+      };
+    }
+
+    // Validate URL format
+    const appUrl = params.url;
+    if (!appUrl) {
+      return {
+        success: false,
+        error: 'URL parameter is required. Provide the URL of your running app (e.g., http://localhost:3000)'
+      };
+    }
+
+    try {
+      new URL(appUrl);
+    } catch {
+      return {
+        success: false,
+        error: `Invalid URL format: ${appUrl}`
+      };
+    }
+
+    // Verify the target app is reachable and scan for errors
+    let pageWarnings = [];
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 5000);
+      const response = await fetch(appUrl, {
+        method: 'GET',
+        signal: controller.signal,
+        redirect: 'follow'
+      });
+      clearTimeout(timeoutId);
+
+      if (!response.ok && response.status >= 500) {
+        return {
+          success: false,
+          error: `Target app returned HTTP ${response.status} at ${appUrl}. Make sure the app is running and accessible.`
+        };
+      }
+
+      // Scan response body for common error patterns
+      const contentType = response.headers.get('content-type') || '';
+      if (contentType.includes('text/html') || contentType.includes('text/plain')) {
+        const body = await response.text();
+        const bodyLower = body.toLowerCase();
+        const bodySnippet = body.slice(0, 4000); // Limit scan size
+
+        // Common build/runtime error patterns
+        const errorPatterns = [
+          { pattern: /Module not found|Cannot find module/i, msg: 'Module not found error detected' },
+          { pattern: /SyntaxError|Unexpected token/i, msg: 'JavaScript syntax error detected' },
+          { pattern: /TypeError|ReferenceError|RangeError/i, msg: 'JavaScript runtime error detected' },
+          { pattern: /ENOENT|EACCES|EADDRINUSE/i, msg: 'Node.js filesystem/port error detected' },
+          { pattern: /Cannot GET|Cannot POST|Not Found/i, msg: 'Route not found (404-like page)' },
+          { pattern: /Compilation failed|Build failed|Failed to compile/i, msg: 'Build/compilation error detected' },
+          { pattern: /Error: |ERROR |error occurred/i, msg: 'Error message found in page content' },
+          { pattern: /<pre class="error">/i, msg: 'Error overlay detected (dev server error page)' },
+          { pattern: /vite-error-overlay|react-error-overlay|nextjs-portal/i, msg: 'Framework error overlay detected' },
+        ];
+
+        for (const { pattern, msg } of errorPatterns) {
+          const match = bodySnippet.match(pattern);
+          if (match) {
+            // Extract surrounding context (up to 150 chars around the match)
+            const idx = bodySnippet.indexOf(match[0]);
+            const start = Math.max(0, idx - 50);
+            const end = Math.min(bodySnippet.length, idx + match[0].length + 100);
+            const context = bodySnippet.slice(start, end)
+              .replace(/<[^>]+>/g, ' ')  // Strip HTML tags
+              .replace(/\s+/g, ' ')      // Collapse whitespace
+              .trim();
+            pageWarnings.push(`${msg}: ...${context}...`);
+          }
+        }
+
+        // Check if page is essentially empty (broken build output)
+        const textContent = body.replace(/<[^>]+>/g, '').trim();
+        if (textContent.length < 10 && !body.includes('<script')) {
+          pageWarnings.push('Page appears empty (no content or scripts). The app may not have built correctly.');
+        }
+      }
+    } catch (fetchErr) {
+      const isAbort = fetchErr.name === 'AbortError';
+      return {
+        success: false,
+        error: isAbort
+          ? `Target app at ${appUrl} did not respond within 5 seconds. Make sure the dev server is running.`
+          : `Cannot reach ${appUrl}: ${fetchErr.message}. Start the dev server first, then retry open-editor.`
+      };
+    }
+
+    // Ensure visual editor server is running (no-op if already started at boot)
+    const server = getVisualEditorServer();
+    if (!server.isRunning) {
+      await server.start();
+    }
+
+    // Get or create instance
+    const instance = await bridge.getInstance(agentId, {
+      appUrl,
+      projectRoot: context.projectRoot || context.workingDirectory
+    });
+
+    // Generate editor URL using configurable port
+    const baseUrl = getVisualEditorBaseUrl();
+    const editorUrl = `${baseUrl}?agentId=${agentId}&appUrl=${encodeURIComponent(appUrl)}`;
+
+    // Update instance status
+    bridge.updateStatus(agentId, instance.status, {
+      editorUrl
+    });
+
+    // Broadcast to web-ui to open visual editor
+    this._broadcastOpenEditor(context, {
+      agentId,
+      appUrl,
+      editorUrl,
+      sessionId: context.sessionId
+    });
+
+    const result = {
+      success: true,
+      message: `Visual Editor opening with ${appUrl}. The preview panel will appear in the UI.`,
+      appUrl,
+      editorUrl,
+      instructions: 'Click elements in the preview to select them. You will receive context automatically.'
+    };
+
+    if (pageWarnings.length > 0) {
+      result.warnings = pageWarnings;
+      result.message += `\n\nWarnings detected on page:\n${pageWarnings.map(w => `  - ${w}`).join('\n')}`;
+    }
+
+    return result;
+  }
+
+  /**
+   * Broadcast open-editor command to web-ui
+   * @private
+   */
+  _broadcastOpenEditor(context, data) {
+    const message = {
+      type: 'visual_editor_open',
+      data: {
+        agentId: data.agentId,
+        appUrl: data.appUrl,
+        editorUrl: data.editorUrl
+      }
+    };
+
+    // Method 1: Through agentPool messageProcessor
+    if (context.agentPool?.messageProcessor?.orchestrator?.webServer) {
+      context.agentPool.messageProcessor.orchestrator.webServer.broadcastToSession(
+        context.sessionId || 'web-session',
+        message
+      );
+      return;
+    }
+
+    // Method 2: Direct orchestrator access
+    if (context.orchestrator?.webServer) {
+      context.orchestrator.webServer.broadcastToSession(
+        context.sessionId || 'web-session',
+        message
+      );
+      return;
+    }
+
+    // Method 3: Global reference fallback
+    if (global.loxiaWebServer) {
+      global.loxiaWebServer.broadcastToSession(
+        context.sessionId || 'web-session',
+        message
+      );
+      return;
+    }
+
+    this.logger?.warn('[VisualEditorTool] Could not broadcast open-editor command - no webServer access');
+  }
+
+  // === Phase 5 Action Handlers ===
+
+  /**
+   * Handle highlight action - highlight element in preview
+   * @private
+   */
+  _handleHighlight(bridge, agentId, params) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required for highlight action'
+      };
+    }
+
+    // Check if connected
+    if (!bridge.isConnected(agentId)) {
+      return {
+        success: false,
+        error: 'Not connected to visual editor. Start the editor first.',
+        hint: 'Use set-app-url to configure and connect to the visual editor'
+      };
+    }
+
+    const duration = params.duration || 2000;
+    const sent = bridge.highlightElement(agentId, params.selector, duration);
+
+    return {
+      success: sent,
+      message: sent
+        ? `Highlighting "${params.selector}" for ${duration}ms`
+        : 'Failed to send highlight command',
+      selector: params.selector,
+      duration
+    };
+  }
+
+  /**
+   * Handle scroll-to action - scroll to element in preview
+   * @private
+   */
+  _handleScrollTo(bridge, agentId, params) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required for scroll-to action'
+      };
+    }
+
+    if (!bridge.isConnected(agentId)) {
+      return {
+        success: false,
+        error: 'Not connected to visual editor. Start the editor first.'
+      };
+    }
+
+    const sent = bridge.scrollToElement(agentId, params.selector);
+
+    return {
+      success: sent,
+      message: sent
+        ? `Scrolling to "${params.selector}"`
+        : 'Failed to send scroll command',
+      selector: params.selector
+    };
+  }
+
+  /**
+   * Handle get-source action - get source code for selector
+   * @private
+   */
+  async _handleGetSource(bridge, agentId, params) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required for get-source action'
+      };
+    }
+
+    // Get visual context for the selector
+    const context = bridge.getVisualContext(agentId);
+
+    // If we have context with source hint, return it
+    if (context && context.sourceHint) {
+      const { file, line, component, codeSnippet, confidence } = context.sourceHint;
+
+      return {
+        success: true,
+        selector: params.selector,
+        source: {
+          file,
+          line,
+          component,
+          codeSnippet,
+          confidence
+        },
+        message: file
+          ? `Source: ${file}:${line}${component ? ` (${component})` : ''}`
+          : 'Source location available in context'
+      };
+    }
+
+    // No source hint available
+    return {
+      success: true,
+      selector: params.selector,
+      source: null,
+      message: 'No source information available for this selector. Try selecting the element in Visual Mode first.'
+    };
+  }
+
+  /**
+   * Handle reload action - reload the preview
+   * @private
+   */
+  _handleReload(bridge, agentId) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required for reload action'
+      };
+    }
+
+    if (!bridge.isConnected(agentId)) {
+      return {
+        success: false,
+        error: 'Not connected to visual editor. Start the editor first.'
+      };
+    }
+
+    const sent = bridge.reloadPreview(agentId);
+
+    return {
+      success: sent,
+      message: sent
+        ? 'Preview reload requested'
+        : 'Failed to send reload command'
+    };
+  }
+
+  /**
+   * Handle set-mode action - switch editor mode
+   * @private
+   */
+  _handleSetMode(bridge, agentId, params) {
+    if (!agentId) {
+      return {
+        success: false,
+        error: 'Agent ID is required for set-mode action'
+      };
+    }
+
+    if (!bridge.isConnected(agentId)) {
+      return {
+        success: false,
+        error: 'Not connected to visual editor. Start the editor first.'
+      };
+    }
+
+    const mode = params.mode;
+    if (!['edit', 'preview'].includes(mode)) {
+      return {
+        success: false,
+        error: `Invalid mode: ${mode}. Must be 'edit' or 'preview'`
+      };
+    }
+
+    const sent = bridge.setEditorMode(agentId, mode);
+
+    return {
+      success: sent,
+      message: sent
+        ? `Editor mode set to '${mode}'`
+        : 'Failed to send mode command',
+      mode
+    };
+  }
+
+  /**
+   * Format visual context for agent consumption
+   * @private
+   */
+  _formatContextForAgent(context) {
+    let formatted = `[VISUAL CONTEXT - User selected element]\n`;
+    formatted += `Element: <${context.tagName}`;
+
+    // Add key attributes
+    if (context.attributes?.class) {
+      formatted += ` class="${context.attributes.class}"`;
+    }
+    if (context.attributes?.id) {
+      formatted += ` id="${context.attributes.id}"`;
+    }
+    formatted += '>\n';
+
+    // Add CSS selector for precise targeting
+    if (context.selector) {
+      formatted += `Selector: ${context.selector}\n`;
+    }
+
+    // Add text content if available
+    if (context.text) {
+      const truncated = context.text.length > 50
+        ? context.text.substring(0, 50) + '...'
+        : context.text;
+      formatted += `Text: "${truncated}"\n`;
+    }
+
+    // Add source hint if available
+    if (context.sourceHint) {
+      const { file, fullPath, line, component, confidence } = context.sourceHint;
+
+      // Use file path if available, fallback to fullPath
+      const filePath = file || fullPath;
+
+      if (filePath) {
+        formatted += `Source: ${filePath}`;
+        if (line) {
+          formatted += `:${line}`;
+        }
+        if (component) {
+          formatted += ` (Component: ${component})`;
+        }
+        if (confidence === 'low') {
+          formatted += ' [VERIFY - low confidence]';
+        }
+        formatted += '\n';
+      } else if (component) {
+        // Even without file path, component name is useful
+        formatted += `Component: ${component}`;
+        if (confidence === 'low') {
+          formatted += ' [source file unknown]';
+        }
+        formatted += '\n';
+      }
+
+      // Add code snippet if available
+      if (context.sourceHint.codeSnippet) {
+        formatted += 'Code:\n';
+        formatted += context.sourceHint.codeSnippet;
+        formatted += '\n';
+      }
+    } else {
+      // No React source info - indicate this is likely vanilla HTML/CSS
+      formatted += `Note: No React source mapping available (plain HTML element)\n`;
+    }
+
+    return formatted;
+  }
+
+  /**
+   * Inject visual context into user message
+   * Called by messageProcessor when visual context exists
+   * @param {string} userMessage - Original user message
+   * @param {Object} context - Visual context
+   * @returns {string} Enhanced message with visual context
+   */
+  static injectContextIntoMessage(userMessage, visualContext) {
+    if (!visualContext) {
+      return userMessage;
+    }
+
+    const tool = new VisualEditorTool();
+    const formatted = tool._formatContextForAgent(visualContext);
+
+    return `${formatted}\n[USER MESSAGE]\n${userMessage}`;
+  }
+}
+
+export default VisualEditorTool;