@loxia-labs/loxia-autopilot-one 1.0.1

package/src/utilities/tagParser.js

@@ -0,0 +1,1246 @@
+/**
+ * TagParser - Utility for parsing XML-style tags and JSON tool commands
+ * 
+ * Purpose:
+ * - Parse XML-style tool commands from agent messages
+ * - Extract parameters from tag-based format
+ * - Support for nested tags and attributes
+ * - JSON tool command parsing
+ * - Agent redirect parsing
+ */
+
+import {
+  AGENT_REDIRECT_ATTRIBUTES
+} from './constants.js';
+import { 
+  TOOL_IDS,
+  COMMAND_FORMATS,
+  JSON_STRUCTURES,
+  identifyJsonStructure,
+  getToolIdFromAction,
+  isValidToolId
+} from './toolConstants.js';
+
+class TagParser {
+  constructor() {
+    // Tag parsing patterns
+    this.patterns = {
+      toolCommand: /<tool-command>(.*?)<\/tool-command>/gs,
+      tool: /<tool\s+([^>]*)>(.*?)<\/tool>/gs,
+      parameter: /<([^>\s]+)(?:\s+([^>]*))?>(((?!<\/\1>)[\s\S])*)<\/\1>/g,
+      attribute: /([\w-]+)=["']([^"']*)["']/g,
+      agentRedirect: /\[agent-redirect\s+([^\]]*)\](.*?)\[\/agent-redirect\]/gs,
+      jsonBlock: /```json\s*(\{[\s\S]*?\})\s*```/g,
+      // Also match plain JSON objects on their own line(s) as fallback
+      plainJson: /^(\{(?:[^{}]|(?:\{[^{}]*\}))*\})$/gm
+    };
+  }
+
+  /**
+   * Decode HTML entities that might be present in tool content
+   * @param {string} text - Text that might contain HTML entities
+   * @returns {string} Decoded text
+   */
+  decodeHtmlEntities(text) {
+    const entityMap = {
+      '&lt;': '<',
+      '&gt;': '>',
+      '&amp;': '&',
+      '&quot;': '"',
+      '&#x27;': "'",
+      '&#x2F;': '/',
+      '&#39;': "'",
+      '&#47;': '/'
+    };
+    
+    return text.replace(/&(?:lt|gt|amp|quot|#x27|#x2F|#39|#47);/g, match => entityMap[match] || match);
+  }
+
+  /**
+   * Extract tool commands from message content
+   * @param {string} content - Message content to parse
+   * @returns {Array} Array of parsed tool commands
+   */
+  extractToolCommands(content) {
+    const commands = [];
+
+    // Decode HTML entities that might be present in the content
+    const decodedContent = this.decodeHtmlEntities(content);
+
+    // PHASE 1: Extract explicit tool invocations (OUTER layer identification)
+    // These use explicit markers: <toolname>, [tool id=""], or ```json
+    const xmlCommands = this.extractXMLToolCommands(decodedContent);
+    commands.push(...xmlCommands);
+
+    // PHASE 2: Extract JSON code blocks (also OUTER layer, explicit)
+    // Extract these BEFORE sanitization so we don't lose them
+    const jsonCodeBlockCommands = this.extractJSONCodeBlocks(decodedContent);
+    commands.push(...jsonCodeBlockCommands);
+
+    // PHASE 3: Sanitize content by removing already-extracted invocations
+    // This prevents INNER payload from being misinterpreted as new tool invocations
+    const sanitizedContent = this.removeToolInvocationBlocks(decodedContent);
+
+    // PHASE 4: Extract plain JSON (fallback, only from sanitized content)
+    // This should rarely find anything if agents follow the ```json block convention
+    const plainJsonCommands = this.extractPlainJSON(sanitizedContent);
+    commands.push(...plainJsonCommands);
+
+    return commands;
+  }
+
+  /**
+   * Remove content inside tool invocation blocks to prevent false JSON detection
+   *
+   * ARCHITECTURAL PRINCIPLE (OUTER-INNER HIERARCHY):
+   * - OUTER layer (message level): Tool identification
+   * - INNER layer (payload level): Action/data for the tool
+   *
+   * Tool invocations appear at MESSAGE LEVEL using explicit markers:
+   * - XML: <toolname>...</toolname> or [tool id="..."]...[/tool]
+   * - JSON: ```json {"toolId": "..."} ```
+   *
+   * Content INSIDE these markers is PAYLOAD, not new tool invocations.
+   *
+   * This method removes:
+   * - Direct tool tags: <taskmanager>...</taskmanager>, <filesystem>...</filesystem>, etc.
+   * - Bracket notation: [tool id="filesystem"]...[/tool]
+   * - JSON code blocks: ```json ... ```
+   *
+   * This prevents:
+   * - File content like {"type": "image/png"} inside <write> tags from being detected
+   * - Duplicate extraction of the same JSON block
+   *
+   * @param {string} content - Content to sanitize
+   * @returns {string} Content with tool invocation blocks removed/replaced with placeholders
+   * @private
+   */
+  removeToolInvocationBlocks(content) {
+    let sanitized = content;
+
+    // Remove JSON code blocks first (to prevent duplicate extraction)
+    let jsonBlockPosition = 0;
+    while (jsonBlockPosition < sanitized.length) {
+      const startMarker = '```json';
+      const endMarker = '```';
+
+      const startIndex = sanitized.indexOf(startMarker, jsonBlockPosition);
+      if (startIndex === -1) break;
+
+      const contentStart = startIndex + startMarker.length;
+      const endIndex = sanitized.indexOf(endMarker, contentStart);
+      if (endIndex === -1) break;
+
+      // Replace JSON code block with placeholder
+      const before = sanitized.substring(0, startIndex);
+      const after = sanitized.substring(endIndex + endMarker.length);
+      sanitized = before + '[JSON_CODE_BLOCK_REMOVED]' + after;
+
+      jsonBlockPosition = startIndex + '[JSON_CODE_BLOCK_REMOVED]'.length;
+    }
+
+    // List of known tool names (matches extractDirectToolTags)
+    const toolNames = [
+      'taskmanager', 'filesystem', 'terminal', 'browser',
+      'agentcommunication', 'jobdone', 'agentdelay', 'image-gen'
+    ];
+
+    // Remove direct tool tags like <filesystem>...</filesystem>
+    for (const toolName of toolNames) {
+      const openTag = `<${toolName}>`;
+      const closeTag = `</${toolName}>`;
+
+      let position = 0;
+      while (position < sanitized.length) {
+        const openIndex = sanitized.indexOf(openTag, position);
+        if (openIndex === -1) break;
+
+        const closeIndex = sanitized.indexOf(closeTag, openIndex + openTag.length);
+        if (closeIndex === -1) break;
+
+        // Replace the entire tool block with a placeholder to preserve message structure
+        // This allows JSON outside tool blocks to still be detected
+        const before = sanitized.substring(0, openIndex);
+        const after = sanitized.substring(closeIndex + closeTag.length);
+        sanitized = before + `[XML_TOOL_REMOVED:${toolName}]` + after;
+
+        position = openIndex + `[XML_TOOL_REMOVED:${toolName}]`.length;
+      }
+    }
+
+    // Remove bracket notation tool blocks: [tool id="..."]...[/tool]
+    // Use a simple loop to avoid regex complexity
+    let bracketPosition = 0;
+    while (bracketPosition < sanitized.length) {
+      const openMarker = '[tool id="';
+      const openIndex = sanitized.indexOf(openMarker, bracketPosition);
+      if (openIndex === -1) break;
+
+      // Find the closing quote to extract tool ID
+      const quoteStart = openIndex + openMarker.length;
+      const quoteEnd = sanitized.indexOf('"', quoteStart);
+      if (quoteEnd === -1) break;
+
+      const toolId = sanitized.substring(quoteStart, quoteEnd);
+
+      // Find the closing ] of the opening tag
+      const openTagEnd = sanitized.indexOf(']', quoteEnd);
+      if (openTagEnd === -1) break;
+
+      // Find the closing [/tool]
+      const closeMarker = '[/tool]';
+      const closeIndex = sanitized.indexOf(closeMarker, openTagEnd);
+      if (closeIndex === -1) break;
+
+      // Replace the bracket tool block with placeholder
+      const before = sanitized.substring(0, openIndex);
+      const after = sanitized.substring(closeIndex + closeMarker.length);
+      sanitized = before + `[BRACKET_TOOL_REMOVED:${toolId}]` + after;
+
+      bracketPosition = openIndex + `[BRACKET_TOOL_REMOVED:${toolId}]`.length;
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * Extract XML-style tool commands
+   * @param {string} content - Content to parse
+   * @returns {Array} Array of parsed XML tool commands
+   */
+  extractXMLToolCommands(content) {
+    const commands = [];
+
+    // Find all tool-command blocks
+    const toolCommandBlocks = this.matchAll(content, this.patterns.toolCommand);
+
+    for (const block of toolCommandBlocks) {
+      const blockContent = block.groups[1];
+
+      // Extract individual tool elements within the block
+      const tools = this.matchAll(blockContent, this.patterns.tool);
+
+      for (const tool of tools) {
+        const attributes = this.parseAttributes(tool.groups[1]);
+        const toolContent = tool.groups[2];
+
+        const command = {
+          type: COMMAND_FORMATS.XML,
+          toolId: attributes.id,
+          attributes,
+          parameters: this.parseXMLParameters(toolContent),
+          rawContent: tool.match.trim(),
+          blockContent: block.match.trim()
+        };
+
+        commands.push(command);
+      }
+    }
+
+    // Extract direct tool tags (e.g., <taskmanager>, <filesystem>)
+    const directToolTags = this.extractDirectToolTags(content);
+    commands.push(...directToolTags);
+
+    // Extract bracket notation (e.g., [tool id="filesystem"]...[/tool])
+    const bracketNotationTools = this.extractBracketNotationTools(content);
+    commands.push(...bracketNotationTools);
+
+    return commands;
+  }
+  
+  /**
+   * Extract direct tool tags like <taskmanager>, <filesystem>, etc.
+   * @param {string} content - Content to parse
+   * @returns {Array} Array of parsed direct tool commands
+   */
+  extractDirectToolTags(content) {
+    const commands = [];
+    const toolNames = ['taskmanager', 'filesystem', 'terminal', 'browser', 'agentcommunication', 'jobdone', 'agentdelay', 'image-gen'];
+
+    for (const toolName of toolNames) {
+      const toolCommands = this.extractToolByName(content, toolName);
+      commands.push(...toolCommands);
+    }
+
+    return commands;
+  }
+
+  /**
+   * Extract bracket notation tool commands like [tool id="filesystem"]...[/tool]
+   * @param {string} content - Content to parse
+   * @returns {Array} Array of parsed bracket notation tool commands
+   */
+  extractBracketNotationTools(content) {
+    const commands = [];
+    const openMarker = '[tool id="';
+    const closeMarker = '[/tool]';
+
+    let position = 0;
+
+    while (position < content.length) {
+      // Find opening marker
+      const openIndex = content.indexOf(openMarker, position);
+      if (openIndex === -1) break;
+
+      // Find the closing quote to extract tool ID
+      const quoteStart = openIndex + openMarker.length;
+      const quoteEnd = content.indexOf('"', quoteStart);
+      if (quoteEnd === -1) break;
+
+      const toolId = content.substring(quoteStart, quoteEnd);
+
+      // Find the closing ] of the opening tag
+      const openTagEnd = content.indexOf(']', quoteEnd);
+      if (openTagEnd === -1) break;
+
+      // Find the closing [/tool]
+      const closeIndex = content.indexOf(closeMarker, openTagEnd);
+      if (closeIndex === -1) break;
+
+      // Extract tool content between the tags
+      const toolContent = content.substring(openTagEnd + 1, closeIndex);
+      const fullMatch = content.substring(openIndex, closeIndex + closeMarker.length);
+
+      console.log(`TagParser DEBUG: extractBracketNotationTools - found ${toolId} tool`);
+
+      const command = {
+        type: COMMAND_FORMATS.XML,
+        toolId: toolId,
+        attributes: {},
+        parameters: this.parseXMLParameters(toolContent),
+        rawContent: fullMatch.trim(),
+        blockContent: fullMatch.trim()
+      };
+
+      commands.push(command);
+      position = closeIndex + closeMarker.length;
+    }
+
+    return commands;
+  }
+  
+  /**
+   * Extract tool tags by name using string functions
+   * @param {string} content - Content to search
+   * @param {string} toolName - Tool name to extract (e.g., 'taskmanager')
+   * @returns {Array} Array of extracted tool commands
+   */
+  extractToolByName(content, toolName) {
+    const commands = [];
+    const openTag = `<${toolName}>`;
+    const closeTag = `</${toolName}>`;
+    
+    let position = 0;
+    
+    while (position < content.length) {
+      const openTagStart = content.indexOf(openTag, position);
+      if (openTagStart === -1) break;
+      
+      const openTagEnd = openTagStart + openTag.length;
+      const closeTagStart = content.indexOf(closeTag, openTagEnd);
+      
+      if (closeTagStart === -1) {
+        position = openTagEnd;
+        continue;
+      }
+      
+      const toolContent = content.substring(openTagEnd, closeTagStart);
+      const fullMatch = content.substring(openTagStart, closeTagStart + closeTag.length);
+      
+      console.log(`TagParser DEBUG: extractToolByName - found ${toolName} tool`);
+      
+      const command = {
+        type: COMMAND_FORMATS.XML,
+        toolId: toolName,
+        attributes: {},
+        parameters: this.parseXMLParameters(toolContent),
+        rawContent: fullMatch.trim(),
+        blockContent: fullMatch.trim()
+      };
+      
+      commands.push(command);
+      position = closeTagStart + closeTag.length;
+    }
+    
+    return commands;
+  }
+
+  /**
+   * Extract JSON-style tool commands
+   * @param {string} content - Content to parse
+   * @returns {Array} Array of parsed JSON tool commands
+   */
+  extractJSONToolCommands(content) {
+    const commands = [];
+    
+    // Method 1: Find JSON in markdown code blocks (preferred format)
+    commands.push(...this.extractJSONCodeBlocks(content));
+    
+    // Method 2: Find plain JSON objects (fallback for agents that don't use code blocks)
+    commands.push(...this.extractPlainJSON(content));
+    
+    return commands;
+  }
+  
+  /**
+   * Extract JSON from markdown code blocks using string functions
+   * @private
+   */
+  extractJSONCodeBlocks(content) {
+    const commands = [];
+    let searchIndex = 0;
+    
+    while (true) {
+      // Find opening marker
+      const startMarker = '```json';
+      const endMarker = '```';
+      
+      const startIndex = content.indexOf(startMarker, searchIndex);
+      if (startIndex === -1) break;
+      
+      // Find closing marker
+      const contentStart = startIndex + startMarker.length;
+      const endIndex = content.indexOf(endMarker, contentStart);
+      if (endIndex === -1) break;
+      
+      // Extract JSON content
+      const jsonString = content.substring(contentStart, endIndex).trim();
+      
+      try {
+        const jsonData = JSON.parse(jsonString);
+
+        if (this.isToolCommandJSON(jsonData)) {
+          // ARCHITECTURAL PRINCIPLE: Use OUTER layer (toolId) for tool identification
+          const toolId = jsonData.toolId || jsonData.tool;
+
+          // Skip if no explicit outer tool identifier
+          if (!toolId || toolId === 'unknown') {
+            console.log('TagParser DEBUG: Skipping JSON block - missing explicit toolId');
+            searchIndex = endIndex + endMarker.length;
+            continue;
+          }
+
+          const command = {
+            type: COMMAND_FORMATS.JSON,
+            toolId: toolId,
+            parameters: jsonData.parameters || jsonData.actions || {},
+            actions: jsonData.actions,
+            rawContent: content.substring(startIndex, endIndex + endMarker.length),
+            jsonData
+          };
+
+          commands.push(command);
+        }
+        
+        // Handle toolCommands array format
+        if (jsonData.toolCommands && Array.isArray(jsonData.toolCommands)) {
+          for (const toolCommand of jsonData.toolCommands) {
+            if (this.isToolCommandJSON(toolCommand)) {
+              // ARCHITECTURAL PRINCIPLE: Use OUTER layer (toolId) for tool identification
+              const toolId = toolCommand.toolId || toolCommand.tool;
+
+              // Skip if no explicit outer tool identifier
+              if (!toolId || toolId === 'unknown') {
+                console.log('TagParser DEBUG: Skipping toolCommand - missing explicit toolId');
+                continue;
+              }
+
+              const command = {
+                type: COMMAND_FORMATS.JSON,
+                toolId: toolId,
+                parameters: toolCommand.parameters || toolCommand.actions || {},
+                actions: toolCommand.actions,
+                rawContent: JSON.stringify(toolCommand, null, 2),
+                jsonData: toolCommand
+              };
+
+              commands.push(command);
+            }
+          }
+        }
+        
+      } catch (error) {
+        // Invalid JSON, skip this block
+      }
+      
+      searchIndex = endIndex + endMarker.length;
+    }
+    
+    return commands;
+  }
+  
+  /**
+   * Extract plain JSON objects using string functions
+   * @private
+   */
+  extractPlainJSON(content) {
+    const commands = [];
+    const lines = content.split('\n');
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      
+      // Skip if line doesn't start with {
+      if (!line.startsWith('{')) continue;
+      
+      // Try to find complete JSON object
+      let jsonString = '';
+      let braceCount = 0;
+      let foundComplete = false;
+      
+      // Start from current line and look for complete JSON
+      for (let j = i; j < lines.length; j++) {
+        const currentLine = lines[j].trim();
+        jsonString += (j > i ? '\n' : '') + currentLine;
+        
+        // Count braces to find complete object
+        for (const char of currentLine) {
+          if (char === '{') braceCount++;
+          if (char === '}') braceCount--;
+          if (braceCount === 0 && char === '}') {
+            foundComplete = true;
+            break;
+          }
+        }
+        
+        if (foundComplete) break;
+      }
+      
+      if (!foundComplete) continue;
+      
+      try {
+        const jsonData = JSON.parse(jsonString);
+
+        // ARCHITECTURAL PRINCIPLE: Use OUTER layer for tool identification
+        // Only parse INNER content (actions, type) if OUTER identifier missing
+        // This follows the layered invocation hierarchy:
+        //   OUTER (message level): Tool identification via "toolId"
+        //   INNER (payload level): Action specification via "type"
+
+        // Check if this JSON looks like a tool command
+        if (this.isToolCommandJSON(jsonData) ||
+            (jsonData.actions && Array.isArray(jsonData.actions)) ||
+            (jsonData.type && typeof jsonData.type === 'string')) {
+
+          // CRITICAL: Use OUTER identifier first, only infer from INNER as fallback
+          const toolId = jsonData.toolId || jsonData.tool || this.inferToolFromActions(jsonData);
+
+          // Skip if we couldn't determine a valid tool
+          if (!toolId || toolId === 'unknown') {
+            console.log('TagParser DEBUG: Skipping plain JSON - could not determine valid toolId');
+            continue;
+          }
+
+          const command = {
+            type: COMMAND_FORMATS.JSON_PLAIN,
+            toolId: toolId,
+            parameters: jsonData.parameters || jsonData,
+            actions: jsonData.actions,
+            rawContent: jsonString,
+            jsonData,
+            warning: 'Plain JSON detected - should use ```json blocks'
+          };
+
+          commands.push(command);
+        }
+        
+      } catch (error) {
+        // Invalid JSON, skip
+        continue;
+      }
+    }
+    
+    return commands;
+  }
+  
+  /**
+   * Infer tool ID from JSON structure
+   * Uses the constants-based approach for deterministic tool identification
+   * @private
+   */
+  inferToolFromActions(jsonData) {
+    const structure = identifyJsonStructure(jsonData);
+    
+    switch (structure) {
+      case JSON_STRUCTURES.STANDARD:
+        // Already has toolId
+        return jsonData.toolId || 'unknown';
+        
+      case JSON_STRUCTURES.ACTIONS_ARRAY:
+        // Get tool from first action type
+        if (jsonData.actions && jsonData.actions.length > 0) {
+          const firstAction = jsonData.actions[0];
+          const toolId = getToolIdFromAction(firstAction.type);
+          return toolId || 'unknown';
+        }
+        break;
+        
+      case JSON_STRUCTURES.DIRECT_ACTION:
+        // Get tool from type field
+        const toolId = getToolIdFromAction(jsonData.type);
+        return toolId || 'unknown';
+        
+      case JSON_STRUCTURES.TOOL_COMMANDS:
+        // Get from first command
+        if (jsonData.toolCommands && jsonData.toolCommands.length > 0) {
+          return this.inferToolFromActions(jsonData.toolCommands[0]);
+        }
+        break;
+    }
+    
+    return 'unknown';
+  }
+
+  /**
+   * Extract agent redirects from content
+   * @param {string} content - Content to parse
+   * @returns {Array} Array of parsed agent redirects
+   */
+  extractAgentRedirects(content) {
+    const redirects = [];
+    
+    const matches = this.matchAll(content, this.patterns.agentRedirect);
+    
+    for (const match of matches) {
+      const attributeString = match.groups[1];
+      const messageContent = match.groups[2].trim();
+      
+      const attributes = this.parseAttributes(attributeString);
+      
+      const redirect = {
+        to: attributes.to,
+        content: messageContent,
+        urgent: attributes[AGENT_REDIRECT_ATTRIBUTES.URGENT] === 'true',
+        requiresResponse: attributes[AGENT_REDIRECT_ATTRIBUTES.REQUIRES_RESPONSE] === 'true',
+        context: attributes[AGENT_REDIRECT_ATTRIBUTES.CONTEXT],
+        rawMatch: match.match
+      };
+      
+      // Add any additional attributes
+      for (const [key, value] of Object.entries(attributes)) {
+        if (!['to', AGENT_REDIRECT_ATTRIBUTES.URGENT, AGENT_REDIRECT_ATTRIBUTES.REQUIRES_RESPONSE, AGENT_REDIRECT_ATTRIBUTES.CONTEXT].includes(key)) {
+          redirect[key] = value;
+        }
+      }
+      
+      redirects.push(redirect);
+    }
+    
+    return redirects;
+  }
+
+  /**
+   * Parse XML parameters from tool content
+   * @param {string} content - Tool content to parse
+   * @returns {Object} Parsed parameters
+   */
+  parseXMLParameters(content) {
+    const parameters = {};
+    
+    console.log('TagParser DEBUG: parseXMLParameters - content length:', content.length);
+    
+    let position = 0;
+    let foundCount = 0;
+    
+    // Look for opening tags like <write>, <read>, etc.
+    while (position < content.length) {
+      const openTagStart = content.indexOf('<', position);
+      if (openTagStart === -1) break;
+      
+      const openTagEnd = content.indexOf('>', openTagStart);
+      if (openTagEnd === -1) break;
+      
+      // Extract the full opening tag
+      const openTag = content.substring(openTagStart, openTagEnd + 1);
+      
+      // Parse tag name and attributes from the opening tag
+      const spaceIndex = openTag.indexOf(' ');
+      const tagName = spaceIndex > 0 
+        ? openTag.substring(1, spaceIndex)
+        : openTag.substring(1, openTag.length - 1);
+      
+      const isValid = this.isValidXmlTagName(tagName);
+
+      // Skip malformed tags or content that looks like code
+      if (tagName.includes('/') || !tagName || !this.isValidXmlTagName(tagName)) {
+        position = openTagEnd + 1;
+        continue;
+      }
+
+      // Check if this is a self-closing tag (ends with />)
+      const isSelfClosing = openTag.endsWith('/>');
+
+      let tagContent = '';
+      let closingTagStart = openTagEnd;
+
+      if (isSelfClosing) {
+        // Self-closing tag has no content
+        tagContent = '';
+        closingTagStart = openTagEnd; // Position right after the self-closing tag
+      } else {
+        // Look for the closing tag
+        const closingTag = `</${tagName}>`;
+        closingTagStart = content.indexOf(closingTag, openTagEnd + 1);
+
+        if (closingTagStart === -1) {
+          position = openTagEnd + 1;
+          continue;
+        }
+
+        // Extract the content between tags
+        tagContent = content.substring(openTagEnd + 1, closingTagStart);
+      }
+      
+      // Extract attributes from the opening tag
+      let attributeString = spaceIndex > 0
+        ? openTag.substring(spaceIndex + 1, openTag.length - 1).trim()
+        : '';
+
+      // For self-closing tags, remove the trailing '/' from attributes
+      if (isSelfClosing && attributeString.endsWith('/')) {
+        attributeString = attributeString.substring(0, attributeString.length - 1).trim();
+      }
+
+      const attributes = this.parseAttributes(attributeString);
+      
+      console.log('TagParser DEBUG: parseXMLParameters - found match:', {
+        paramName: tagName,
+        attributeString,
+        valueLength: tagContent.length,
+        valuePreview: tagContent.substring(0, 50) + (tagContent.length > 50 ? '...' : '')
+      });
+
+      // CRITICAL FIX: Handle multiple tags with same name (e.g., multiple <write> tags)
+      // Convert to array if duplicate detected
+      const paramValue = {
+        value: tagContent.trim(),
+        attributes
+      };
+
+      if (parameters[tagName]) {
+        // Tag already exists - convert to array or append to existing array
+        if (Array.isArray(parameters[tagName])) {
+          // Already an array, append
+          parameters[tagName].push(paramValue);
+          console.log('TagParser DEBUG: appended to existing array for tag:', tagName, 'count:', parameters[tagName].length);
+        } else {
+          // First duplicate - convert to array
+          const existingValue = parameters[tagName];
+          parameters[tagName] = [existingValue, paramValue];
+          console.log('TagParser DEBUG: converted to array for duplicate tag:', tagName);
+        }
+      } else {
+        // First occurrence - store as single object
+        parameters[tagName] = paramValue;
+      }
+
+      // For convenience, also store direct access to value (deprecated, kept for backward compatibility)
+      // Only define if it doesn't exist (handles multiple tags with same name)
+      const valuePropertyName = tagName + '_value';
+      if (!Object.prototype.hasOwnProperty.call(parameters, valuePropertyName)) {
+        Object.defineProperty(parameters, valuePropertyName, {
+          value: tagContent.trim(),
+          enumerable: false
+        });
+      }
+
+      foundCount++;
+
+      // Update position based on whether it's self-closing or paired tags
+      if (isSelfClosing) {
+        position = openTagEnd + 1;
+      } else {
+        const closingTag = `</${tagName}>`;
+        position = closingTagStart + closingTag.length;
+      }
+    }
+    
+    console.log('TagParser DEBUG: parseXMLParameters - matches found:', foundCount);
+    console.log('TagParser DEBUG: parseXMLParameters - final parameters:', Object.keys(parameters));
+    return parameters;
+  }
+
+  /**
+   * Parse attributes from attribute string
+   * @param {string} attributeString - Attribute string to parse
+   * @returns {Object} Parsed attributes
+   */
+  parseAttributes(attributeString) {
+    const attributes = {};
+    
+    if (!attributeString) return attributes;
+    
+    const attrMatches = this.matchAll(attributeString, this.patterns.attribute);
+    
+    for (const match of attrMatches) {
+      const attrName = match.groups[0];
+      const attrValue = match.groups[1];
+      
+      attributes[attrName] = attrValue;
+    }
+    
+    return attributes;
+  }
+
+  /**
+   * Extract content from tags
+   * @param {string} content - Content to search
+   * @param {string} tagName - Tag name to extract
+   * @returns {Array} Array of extracted content strings
+   */
+  static extractContent(content, tagName) {
+    const pattern = new RegExp(`<${tagName}[^>]*>([^<]*)<\\/${tagName}>`, 'g');
+    const matches = [];
+    let match;
+    
+    while ((match = pattern.exec(content)) !== null) {
+      matches.push(match[1].trim());
+    }
+    
+    return matches;
+  }
+
+  /**
+   * Extract tag with attributes
+   * @param {string} content - Content to search
+   * @param {string} tagName - Tag name to extract
+   * @returns {Array} Array of extracted tag objects with content and attributes
+   */
+  static extractTagsWithAttributes(content, tagName) {
+    const pattern = new RegExp(`<${tagName}\\s*([^>]*)>([^<]*)<\\/${tagName}>`, 'g');
+    const tags = [];
+    let match;
+    
+    while ((match = pattern.exec(content)) !== null) {
+      const attributeString = match[1];
+      const tagContent = match[2].trim();
+      
+      const parser = new TagParser();
+      const attributes = parser.parseAttributes(attributeString);
+      
+      tags.push({
+        content: tagContent,
+        attributes,
+        rawMatch: match[0]
+      });
+    }
+    
+    return tags;
+  }
+
+  /**
+   * Check if JSON object represents a tool command
+   * @private
+   */
+  isToolCommandJSON(obj) {
+    return obj && 
+           typeof obj === 'object' && 
+           (obj.toolId || obj.tool) && 
+           (obj.parameters || obj.actions);
+  }
+
+  /**
+   * Match all occurrences of a pattern
+   * @private
+   */
+  matchAll(content, pattern) {
+    const matches = [];
+    let match;
+    
+    // Reset pattern lastIndex to ensure clean matching
+    pattern.lastIndex = 0;
+    
+    while ((match = pattern.exec(content)) !== null) {
+      matches.push({
+        match: match[0],
+        groups: match.slice(1),
+        index: match.index
+      });
+    }
+    
+    return matches;
+  }
+
+  /**
+   * Validate tool command structure
+   * @param {Object} command - Tool command to validate
+   * @returns {Object} Validation result
+   */
+  validateToolCommand(command) {
+    const errors = [];
+    
+    if (!command.toolId) {
+      errors.push('Missing toolId');
+    }
+    
+    if (!command.parameters && !command.actions) {
+      errors.push('Missing parameters or actions');
+    }
+    
+    if (command.type === 'xml') {
+      if (!command.rawContent) {
+        errors.push('Missing rawContent for XML command');
+      }
+      
+      // Validate XML parameter structure
+      if (command.parameters) {
+        for (const [paramName, paramData] of Object.entries(command.parameters)) {
+          if (typeof paramData !== 'object' || !('value' in paramData)) {
+            errors.push(`Invalid parameter structure for ${paramName}`);
+          }
+        }
+      }
+    }
+    
+    if (command.type === 'json') {
+      if (!command.jsonData) {
+        errors.push('Missing jsonData for JSON command');
+      }
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Normalize tool command to consistent format
+   * @param {Object} command - Tool command to normalize
+   * @returns {Object} Normalized command
+   */
+  normalizeToolCommand(command) {
+    const normalized = {
+      toolId: command.toolId,
+      type: command.type,
+      parameters: {},
+      rawContent: command.rawContent
+    };
+
+    if (command.type === COMMAND_FORMATS.XML) {
+      console.log('TagParser DEBUG: normalizing XML command with parameters:', Object.keys(command.parameters || {}));
+
+      // SPECIAL CASE: AgentDelay tool expects flat object {duration, reason}, not actions array
+      if (command.toolId === 'agentdelay') {
+        const params = command.parameters || {};
+
+        // Extract duration and reason
+        if (params['pause-duration']) {
+          const durationStr = params['pause-duration'].value;
+          normalized.parameters.duration = parseInt(durationStr, 10);
+        }
+        if (params['reason']) {
+          normalized.parameters.reason = params['reason'].value.trim();
+        }
+
+        console.log('TagParser DEBUG: delay tool - flat parameters:', normalized.parameters);
+        return normalized;
+      }
+
+      // SPECIAL CASE: ImageGen tool has its own XML parser, pass raw content directly
+      if (command.toolId === 'image-gen') {
+        const params = command.parameters || {};
+
+        // Extract the inner XML content (without the <image-gen> wrapper)
+        // ImageTool.parseParameters() expects just the inner tags
+        let xmlContent = '';
+        for (const [key, paramData] of Object.entries(params)) {
+          xmlContent += `<${key}>${paramData.value}</${key}>\n`;
+        }
+
+        // Store the raw XML for ImageTool to parse
+        normalized.parameters = xmlContent.trim();
+
+        console.log('TagParser DEBUG: image-gen tool - passing raw XML to ImageTool:', xmlContent.substring(0, 100) + '...');
+        return normalized;
+      }
+
+      // NORMAL CASE: Convert XML parameters to actions array format for most tools
+      const actions = [];
+
+      for (const [key, paramData] of Object.entries(command.parameters || {})) {
+        console.log('TagParser DEBUG: processing XML parameter:', key, 'with data:', paramData);
+
+        // CRITICAL FIX: Handle both single object and array of objects (for duplicate tags)
+        const paramDataArray = Array.isArray(paramData) ? paramData : [paramData];
+
+        for (const singleParamData of paramDataArray) {
+          // Convert XML tags to action objects
+          const action = {
+            type: key, // e.g., "write", "read", "delete", "run-command"
+            ...singleParamData.attributes // e.g., output-path, file-path, etc.
+          };
+
+          // Add content if it exists
+          if (singleParamData.value && singleParamData.value.trim()) {
+            action.content = singleParamData.value.trim();
+          }
+
+          console.log('TagParser DEBUG: created action before normalization:', action);
+
+        // Convert attribute names to camelCase for consistency
+        const normalizedAction = {};
+        for (const [attrKey, attrValue] of Object.entries(action)) {
+          const normalizedKey = this._toCamelCase(attrKey);
+          normalizedAction[normalizedKey] = attrValue;
+        }
+
+        // CRITICAL FIX: Map 'content' field to tool-specific field names based on action type
+        if (normalizedAction.content !== undefined) {
+          const contentFieldMapping = {
+            // Terminal tool mappings
+            'run-command': 'command',
+            'create-directory': 'directory',
+            'change-directory': 'directory',
+            'list-directory': 'directory',
+            'get-working-directory': null, // No content field needed
+
+            // FileSystem tool mappings
+            'write': null, // Uses content for file content (keep as-is)
+            'read': 'filePath',
+            'delete': 'filePath',
+            'copy': null, // Uses attributes (source, destination)
+            'move': null, // Uses attributes (source, destination)
+            'append': 'filePath',
+            'create-dir': 'directory',
+            'list': 'directory',
+            'exists': 'path',
+            'stats': 'path',
+
+            // TaskManager tool mappings
+            'action': null, // Keep as content
+            'title': null,
+            'description': null,
+            'priority': null,
+            'taskId': null,
+            'status': null
+          };
+
+          const mappedFieldName = contentFieldMapping[normalizedAction.type];
+
+          if (mappedFieldName) {
+            // Map content to the specific field name
+            normalizedAction[mappedFieldName] = normalizedAction.content;
+            delete normalizedAction.content;
+            console.log(`TagParser DEBUG: mapped 'content' to '${mappedFieldName}' for action type '${normalizedAction.type}'`);
+          } else if (mappedFieldName === null) {
+            // Explicitly keep as content or remove if not needed
+            console.log(`TagParser DEBUG: keeping action type '${normalizedAction.type}' as-is`);
+          }
+        }
+
+          console.log('TagParser DEBUG: final normalized action:', normalizedAction);
+          actions.push(normalizedAction);
+        } // End inner loop for paramDataArray
+
+        // Preserve original format for backward compatibility (use first value if array)
+        const backwardCompatValue = Array.isArray(paramData) ? paramData[0] : paramData;
+        normalized.parameters[key] = backwardCompatValue.value;
+        if (backwardCompatValue.attributes && Object.keys(backwardCompatValue.attributes).length > 0) {
+          normalized.parameters[`${key}_attributes`] = backwardCompatValue.attributes;
+        }
+      } // End outer loop for parameters
+
+      console.log('TagParser DEBUG: total actions created:', actions.length);
+
+      // Add actions array if we found any XML actions
+      if (actions.length > 0) {
+        normalized.parameters.actions = actions;
+        console.log('TagParser DEBUG: added actions array to parameters');
+      } else {
+        console.log('TagParser DEBUG: WARNING - no actions created, this will cause "actions is not iterable" error');
+      }
+    } else if (command.type === COMMAND_FORMATS.JSON || command.type === COMMAND_FORMATS.JSON_PLAIN) {
+      // JSON parameters are already in simple format
+      normalized.parameters = { ...command.parameters };
+
+      // Handle actions array format (common in agentcommunication tool)
+      if (command.actions && Array.isArray(command.actions)) {
+        normalized.parameters.actions = command.actions;
+
+        // For agentcommunication tool, extract the action from the first item
+        if (command.toolId === TOOL_IDS.AGENT_COMMUNICATION && command.actions.length > 0) {
+          const firstAction = command.actions[0];
+          normalized.parameters.action = firstAction.type || firstAction.action;
+          // Spread the rest of the action properties
+          Object.assign(normalized.parameters, firstAction);
+        }
+      }
+    }
+
+    return normalized;
+  }
+
+  /**
+   * Check if a string is a valid XML tag name for tool commands
+   * @param {string} tagName - Tag name to validate
+   * @returns {boolean} True if valid
+   * @private
+   */
+  isValidXmlTagName(tagName) {
+    // Valid tool command tag names: write, read, delete, copy, move, etc.
+    const validTagNames = [
+      'write', 'read', 'delete', 'copy', 'move', 'append',
+      'create-dir', 'list', 'exists', 'stats',
+      'run-command', 'cd', 'pwd',
+      // Terminal tool tags
+      'create-directory', 'change-directory', 'list-directory', 'get-working-directory',
+      // Agent delay tool tags
+      'pause-duration', 'reason',
+      // TaskManager tool tags
+      'action', 'title', 'description', 'priority', 'taskId', 'status',
+      'dependsOn', 'dependencyType', 'relatedTo', 'parentTaskId',
+      'timeframe', 'templateId', 'stage', 'milestone', 'notes',
+      // Browser tool tags
+      'url', 'selector', 'text', 'screenshot', 'element',
+      // Agent communication tags
+      'recipient', 'message', 'conversation-id',
+      // Image generation tool tags
+      'prompt', 'output-path', 'size', 'quality', 'model', 'batch', 'image',
+      // General parameter tags
+      'command', 'path', 'content', 'name', 'value', 'type', 'target'
+    ];
+
+    // Must be a known tag name and contain only letters, numbers, and hyphens
+    return validTagNames.includes(tagName) && this.containsOnlyValidChars(tagName);
+  }
+  
+  /**
+   * Check if tag name contains only valid characters (letters, numbers, hyphens)
+   * @param {string} tagName - Tag name to check
+   * @returns {boolean} True if valid
+   * @private
+   */
+  containsOnlyValidChars(tagName) {
+    if (!tagName || tagName.length === 0) return false;
+    
+    // First character must be a letter
+    const firstChar = tagName.charAt(0);
+    const firstIsLetter = (firstChar >= 'a' && firstChar <= 'z') || (firstChar >= 'A' && firstChar <= 'Z');
+    if (!firstIsLetter) {
+      return false;
+    }
+    
+    // Rest can be letters, numbers, or hyphens
+    for (let i = 1; i < tagName.length; i++) {
+      const char = tagName.charAt(i);
+      const isLetter = (char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z');
+      const isNumber = char >= '0' && char <= '9';
+      const isHyphen = char === '-';
+      
+      if (!isLetter && !isNumber && !isHyphen) {
+        return false;
+      }
+    }
+    
+    return true;
+  }
+
+  /**
+   * Check if tag name is in the valid tag list (for debugging)
+   * @param {string} tagName - Tag name to check
+   * @returns {boolean} True if in list
+   * @private
+   */
+  isTagInValidList(tagName) {
+    const validTagNames = [
+      'write', 'read', 'delete', 'copy', 'move', 'append',
+      'create-dir', 'list', 'exists', 'stats',
+      'run-command', 'cd', 'pwd',
+      // Terminal tool tags
+      'create-directory', 'change-directory', 'list-directory', 'get-working-directory',
+      // Agent delay tool tags
+      'pause-duration', 'reason',
+      // TaskManager tool tags
+      'action', 'title', 'description', 'priority', 'taskId', 'status',
+      'dependsOn', 'dependencyType', 'relatedTo', 'parentTaskId',
+      'timeframe', 'templateId', 'stage', 'milestone', 'notes',
+      // Browser tool tags
+      'url', 'selector', 'text', 'screenshot', 'element',
+      // Agent communication tags
+      'recipient', 'message', 'conversation-id',
+      // Image generation tool tags
+      'prompt', 'output-path', 'size', 'quality', 'model', 'batch', 'image',
+      // General parameter tags
+      'command', 'path', 'content', 'name', 'value', 'type', 'target'
+    ];
+    return validTagNames.includes(tagName);
+  }
+
+  /**
+   * Convert kebab-case or snake_case to camelCase
+   * @private
+   */
+  _toCamelCase(str) {
+    return str.replace(/[-_](.)/g, (_, char) => char.toUpperCase());
+  }
+
+  /**
+   * Extract all content between tags, including nested tags
+   * @param {string} content - Content to search
+   * @param {string} startTag - Opening tag
+   * @param {string} endTag - Closing tag
+   * @returns {Array} Array of extracted content blocks
+   */
+  static extractBetweenTags(content, startTag, endTag) {
+    const blocks = [];
+    let startIndex = 0;
+    
+    while (true) {
+      const start = content.indexOf(startTag, startIndex);
+      if (start === -1) break;
+      
+      const end = content.indexOf(endTag, start + startTag.length);
+      if (end === -1) break;
+      
+      const blockContent = content.substring(start + startTag.length, end);
+      blocks.push({
+        content: blockContent,
+        fullMatch: content.substring(start, end + endTag.length),
+        startIndex: start,
+        endIndex: end + endTag.length
+      });
+      
+      startIndex = end + endTag.length;
+    }
+    
+    return blocks;
+  }
+
+  /**
+   * Clean content by removing all tool commands and agent redirects
+   * @param {string} content - Content to clean
+   * @returns {string} Cleaned content
+   */
+  cleanContent(content) {
+    let cleaned = content;
+    
+    // Remove tool command blocks
+    cleaned = cleaned.replace(this.patterns.toolCommand, '');
+    
+    // Remove agent redirects
+    cleaned = cleaned.replace(this.patterns.agentRedirect, '');
+    
+    // Remove JSON tool command blocks
+    cleaned = cleaned.replace(this.patterns.jsonBlock, (match, jsonContent) => {
+      try {
+        const jsonData = JSON.parse(jsonContent);
+        if (this.isToolCommandJSON(jsonData) || 
+            (jsonData.toolCommands && Array.isArray(jsonData.toolCommands))) {
+          return '';
+        }
+      } catch {
+        // Not a tool command JSON block, keep it
+      }
+      return match;
+    });
+    
+    // Clean up excessive whitespace
+    cleaned = cleaned.replace(/\n\s*\n\s*\n/g, '\n\n');
+    cleaned = cleaned.trim();
+    
+    return cleaned;
+  }
+}
+
+export default TagParser;