@loxia-labs/loxia-autopilot-one 1.0.1

package/src/tools/baseTool.js

@@ -0,0 +1,800 @@
+/**
+ * BaseTool - Abstract base class for all tools in the Loxia AI Agents System
+ * 
+ * Purpose:
+ * - Define standardized tool interface
+ * - Provide common tool functionality
+ * - Handle parameter validation
+ * - Manage tool execution lifecycle
+ * - Support both sync and async operations
+ */
+
+import {
+  TOOL_STATUS,
+  OPERATION_STATUS,
+  ERROR_TYPES,
+  SYSTEM_DEFAULTS
+} from '../utilities/constants.js';
+
+class BaseTool {
+  constructor(config = {}, logger = null) {
+    this.id = this.constructor.name.toLowerCase().replace('tool', '');
+    this.config = config;
+    this.logger = logger;
+    
+    // Tool capabilities
+    this.requiresProject = false;
+    this.isAsync = false;
+    this.timeout = config.timeout || SYSTEM_DEFAULTS.MAX_TOOL_EXECUTION_TIME;
+    this.maxConcurrentOperations = config.maxConcurrentOperations || 1;
+    
+    // Operation tracking
+    this.activeOperations = new Map();
+    this.operationHistory = [];
+    
+    // Tool state
+    this.isEnabled = config.enabled !== false;
+    this.lastUsed = null;
+    this.usageCount = 0;
+  }
+
+  /**
+   * Get tool description for LLM consumption
+   * Must be implemented by subclasses
+   * @returns {string} Tool description
+   */
+  getDescription() {
+    throw new Error(`Tool ${this.id} must implement getDescription()`);
+  }
+
+  /**
+   * Parse parameters from tool command content
+   * Must be implemented by subclasses
+   * @param {string} content - Raw tool command content
+   * @returns {Object} Parsed parameters object
+   */
+  parseParameters(content) {
+    throw new Error(`Tool ${this.id} must implement parseParameters()`);
+  }
+
+  /**
+   * Execute tool with parsed parameters
+   * Must be implemented by subclasses
+   * @param {Object} params - Parsed parameters
+   * @param {Object} context - Execution context
+   * @returns {Promise<*>} Execution result
+   */
+  async execute(params, context) {
+    throw new Error(`Tool ${this.id} must implement execute()`);
+  }
+
+  /**
+   * Get tool capabilities metadata
+   * @returns {Object} Capabilities object
+   */
+  getCapabilities() {
+    return {
+      id: this.id,
+      async: this.isAsync,
+      requiresProject: this.requiresProject,
+      timeout: this.timeout,
+      maxConcurrentOperations: this.maxConcurrentOperations,
+      enabled: this.isEnabled,
+      supportedActions: this.getSupportedActions(),
+      parameterSchema: this.getParameterSchema()
+    };
+  }
+
+  /**
+   * Validate tool parameters
+   * Can be overridden by subclasses for custom validation
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} Validation result with valid flag and error message
+   */
+  validateParameters(params) {
+    try {
+      if (!params || typeof params !== 'object') {
+        return {
+          valid: false,
+          error: 'Parameters must be an object'
+        };
+      }
+      
+      // Check required parameters
+      const requiredParams = this.getRequiredParameters();
+      for (const required of requiredParams) {
+        if (!(required in params)) {
+          return {
+            valid: false,
+            error: `Missing required parameter: ${required}`
+          };
+        }
+      }
+      
+      // Validate parameter types
+      const typeValidation = this.validateParameterTypes(params);
+      if (!typeValidation.valid) {
+        return typeValidation;
+      }
+      
+      // Custom validation
+      const customValidation = this.customValidateParameters(params);
+      if (!customValidation.valid) {
+        return customValidation;
+      }
+      
+      return { valid: true };
+      
+    } catch (error) {
+      return {
+        valid: false,
+        error: `Parameter validation failed: ${error.message}`
+      };
+    }
+  }
+
+  /**
+   * Execute tool with full lifecycle management
+   * @param {Object} params - Tool parameters
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Execution result with metadata
+   */
+  async executeWithLifecycle(params, context) {
+    const operationId = this.generateOperationId();
+    const startTime = Date.now();
+    
+    // Check if tool is enabled
+    if (!this.isEnabled) {
+      throw new Error(`Tool ${this.id} is disabled`);
+    }
+    
+    // Check concurrent operation limits
+    if (this.activeOperations.size >= this.maxConcurrentOperations) {
+      throw new Error(`Tool ${this.id} has reached maximum concurrent operations limit`);
+    }
+    
+    // Validate parameters
+    const validation = this.validateParameters(params);
+    if (!validation.valid) {
+      throw new Error(`Parameter validation failed: ${validation.error}`);
+    }
+    
+    // Create operation record
+    const operation = {
+      id: operationId,
+      toolId: this.id,
+      status: TOOL_STATUS.EXECUTING,
+      startTime: new Date().toISOString(),
+      params,
+      context: this.sanitizeContext(context)
+    };
+    
+    this.activeOperations.set(operationId, operation);
+    
+    try {
+      this.logger?.info(`Tool execution started: ${this.id}`, {
+        operationId,
+        toolId: this.id,
+        context: operation.context
+      });
+      
+      // Execute with timeout
+      const result = await this.executeWithTimeout(params, context);
+      
+      // Update operation status
+      operation.status = TOOL_STATUS.COMPLETED;
+      operation.result = result;
+      operation.endTime = new Date().toISOString();
+      operation.executionTime = Date.now() - startTime;
+      
+      // Update tool statistics
+      this.lastUsed = new Date().toISOString();
+      this.usageCount++;
+      
+      this.logger?.info(`Tool execution completed: ${this.id}`, {
+        operationId,
+        executionTime: operation.executionTime,
+        success: true
+      });
+      
+      return {
+        success: true,
+        operationId,
+        result,
+        executionTime: operation.executionTime,
+        toolId: this.id
+      };
+      
+    } catch (error) {
+      // Update operation status
+      operation.status = TOOL_STATUS.FAILED;
+      operation.error = error.message;
+      operation.endTime = new Date().toISOString();
+      operation.executionTime = Date.now() - startTime;
+      
+      this.logger?.error(`Tool execution failed: ${this.id}`, {
+        operationId,
+        error: error.message,
+        executionTime: operation.executionTime
+      });
+      
+      throw error;
+      
+    } finally {
+      // Move to history and cleanup
+      this.operationHistory.push({ ...operation });
+      this.activeOperations.delete(operationId);
+      
+      // Cleanup old history entries
+      this.cleanupHistory();
+      
+      // Perform tool-specific cleanup
+      await this.cleanup(operationId);
+    }
+  }
+
+  /**
+   * Get status of async operation
+   * @param {string} operationId - Operation identifier
+   * @returns {Promise<Object>} Operation status
+   */
+  async getStatus(operationId) {
+    const operation = this.activeOperations.get(operationId);
+    
+    if (!operation) {
+      // Check history
+      const historyEntry = this.operationHistory.find(op => op.id === operationId);
+      if (historyEntry) {
+        return {
+          operationId,
+          status: historyEntry.status,
+          result: historyEntry.result,
+          error: historyEntry.error,
+          executionTime: historyEntry.executionTime
+        };
+      }
+      
+      return {
+        operationId,
+        status: OPERATION_STATUS.NOT_FOUND,
+        error: 'Operation not found'
+      };
+    }
+    
+    return {
+      operationId,
+      status: operation.status,
+      startTime: operation.startTime,
+      executionTime: operation.endTime ? 
+        new Date(operation.endTime).getTime() - new Date(operation.startTime).getTime() :
+        Date.now() - new Date(operation.startTime).getTime()
+    };
+  }
+
+  /**
+   * Resource cleanup after tool execution
+   * Can be overridden by subclasses
+   * @param {string} operationId - Operation identifier
+   * @returns {Promise<void>}
+   */
+  async cleanup(operationId) {
+    // Default implementation - no cleanup needed
+  }
+
+  /**
+   * Get supported actions for this tool
+   * Can be overridden by subclasses
+   * @returns {Array<string>} Array of supported action names
+   */
+  getSupportedActions() {
+    return ['execute'];
+  }
+
+  /**
+   * Get parameter schema for validation
+   * Can be overridden by subclasses
+   * @returns {Object} Parameter schema
+   */
+  getParameterSchema() {
+    return {
+      type: 'object',
+      properties: {},
+      required: []
+    };
+  }
+
+  /**
+   * Get required parameters
+   * Can be overridden by subclasses
+   * @returns {Array<string>} Array of required parameter names
+   */
+  getRequiredParameters() {
+    return [];
+  }
+
+  /**
+   * Validate parameter types
+   * Can be overridden by subclasses
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} Validation result
+   */
+  validateParameterTypes(params) {
+    // Default implementation - all parameters are valid
+    return { valid: true };
+  }
+
+  /**
+   * Custom parameter validation
+   * Can be overridden by subclasses
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} Validation result
+   */
+  customValidateParameters(params) {
+    // Default implementation - no custom validation
+    return { valid: true };
+  }
+
+  /**
+   * Execute tool with timeout protection
+   * @private
+   */
+  async executeWithTimeout(params, context) {
+    return new Promise(async (resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        reject(new Error(`Tool execution timed out after ${this.timeout}ms`));
+      }, this.timeout);
+      
+      try {
+        const result = await this.execute(params, context);
+        clearTimeout(timeoutId);
+        resolve(result);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Generate unique operation ID
+   * @private
+   */
+  generateOperationId() {
+    return `${this.id}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Sanitize context for logging
+   * @private
+   */
+  sanitizeContext(context) {
+    const sanitized = { ...context };
+    
+    // Remove sensitive information
+    delete sanitized.apiKeys;
+    delete sanitized.secrets;
+    delete sanitized.passwords;
+    
+    // Truncate large content
+    if (sanitized.content && sanitized.content.length > 500) {
+      sanitized.content = sanitized.content.substring(0, 500) + '... [truncated]';
+    }
+    
+    return sanitized;
+  }
+
+  /**
+   * Cleanup old history entries
+   * @private
+   */
+  cleanupHistory() {
+    const maxHistoryEntries = 100;
+    if (this.operationHistory.length > maxHistoryEntries) {
+      this.operationHistory = this.operationHistory.slice(-maxHistoryEntries);
+    }
+  }
+
+  /**
+   * Get tool usage statistics
+   * @returns {Object} Usage statistics
+   */
+  getUsageStats() {
+    return {
+      toolId: this.id,
+      usageCount: this.usageCount,
+      lastUsed: this.lastUsed,
+      activeOperations: this.activeOperations.size,
+      totalOperations: this.operationHistory.length,
+      averageExecutionTime: this.calculateAverageExecutionTime(),
+      successRate: this.calculateSuccessRate(),
+      isEnabled: this.isEnabled
+    };
+  }
+
+  /**
+   * Calculate average execution time
+   * @private
+   */
+  calculateAverageExecutionTime() {
+    const completedOps = this.operationHistory.filter(op => 
+      op.status === TOOL_STATUS.COMPLETED && op.executionTime
+    );
+    
+    if (completedOps.length === 0) return 0;
+    
+    const totalTime = completedOps.reduce((sum, op) => sum + op.executionTime, 0);
+    return Math.round(totalTime / completedOps.length);
+  }
+
+  /**
+   * Calculate success rate
+   * @private
+   */
+  calculateSuccessRate() {
+    if (this.operationHistory.length === 0) return 0;
+    
+    const successfulOps = this.operationHistory.filter(op => 
+      op.status === TOOL_STATUS.COMPLETED
+    );
+    
+    return (successfulOps.length / this.operationHistory.length) * 100;
+  }
+
+  /**
+   * Enable tool
+   */
+  enable() {
+    this.isEnabled = true;
+    this.logger?.info(`Tool enabled: ${this.id}`);
+  }
+
+  /**
+   * Disable tool
+   */
+  disable() {
+    this.isEnabled = false;
+    this.logger?.info(`Tool disabled: ${this.id}`);
+  }
+
+  /**
+   * Reset tool statistics
+   */
+  resetStats() {
+    this.usageCount = 0;
+    this.lastUsed = null;
+    this.operationHistory = [];
+    this.logger?.info(`Tool statistics reset: ${this.id}`);
+  }
+}
+
+/**
+ * ToolsRegistry - Manages registration and discovery of tools
+ */
+class ToolsRegistry {
+  constructor(logger = null) {
+    this.logger = logger;
+    this.tools = new Map();
+    this.toolDescriptions = new Map();
+    this.toolCapabilities = new Map();
+    this.asyncOperations = new Map();
+  }
+
+  /**
+   * Register a tool class
+   * @param {Class} toolClass - Tool class to register
+   * @returns {Promise<void>}
+   */
+  async registerTool(toolClass) {
+    try {
+      const tool = new toolClass();
+      
+      if (!(tool instanceof BaseTool)) {
+        throw new Error(`Tool ${toolClass.name} must extend BaseTool`);
+      }
+      
+      const capabilities = tool.getCapabilities();
+      
+      // Validate tool implementation
+      await this.validateTool(tool);
+      
+      this.tools.set(tool.id, tool);
+      this.toolDescriptions.set(tool.id, tool.getDescription());
+      this.toolCapabilities.set(tool.id, capabilities);
+      
+      this.logger?.info(`Tool registered: ${tool.id}`, {
+        capabilities: capabilities.supportedActions,
+        async: capabilities.async,
+        requiresProject: capabilities.requiresProject
+      });
+      
+    } catch (error) {
+      this.logger?.error(`Tool registration failed: ${error.message}`, {
+        toolClass: toolClass.name
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Auto-discover tools in directory
+   * @param {string} directory - Directory path to scan
+   * @returns {Promise<number>} Number of tools discovered
+   */
+  async discoverTools(directory) {
+    // Implementation would scan directory for tool files
+    // For now, return 0
+    return 0;
+  }
+
+  /**
+   * Validate tool implementation
+   * @param {BaseTool} tool - Tool instance to validate
+   * @returns {Promise<void>}
+   */
+  async validateTool(tool) {
+    // Check required methods
+    const requiredMethods = ['getDescription', 'parseParameters', 'execute'];
+    
+    for (const method of requiredMethods) {
+      if (typeof tool[method] !== 'function') {
+        throw new Error(`Tool ${tool.id} missing required method: ${method}`);
+      }
+    }
+    
+    // Test parameter parsing
+    try {
+      const testParams = tool.parseParameters('test content');
+      if (typeof testParams !== 'object') {
+        throw new Error(`Tool ${tool.id} parseParameters must return an object`);
+      }
+    } catch (error) {
+      // Parsing may fail for test content, that's okay
+    }
+    
+    // Validate capabilities
+    const capabilities = tool.getCapabilities();
+    if (!capabilities || typeof capabilities !== 'object') {
+      throw new Error(`Tool ${tool.id} getCapabilities must return an object`);
+    }
+  }
+
+  /**
+   * Get tool by ID
+   * @param {string} toolId - Tool identifier
+   * @returns {BaseTool|null} Tool instance or null
+   */
+  getTool(toolId) {
+    return this.tools.get(toolId) || null;
+  }
+
+  /**
+   * Get all tool capabilities for LLM consumption
+   * @returns {Object} All tool capabilities
+   */
+  getToolCapabilities() {
+    const capabilities = {};
+    
+    for (const [toolId, tool] of this.tools.entries()) {
+      if (tool.isEnabled) {
+        capabilities[toolId] = {
+          description: this.toolDescriptions.get(toolId),
+          capabilities: this.toolCapabilities.get(toolId),
+          usageStats: tool.getUsageStats()
+        };
+      }
+    }
+    
+    return capabilities;
+  }
+
+  /**
+   * Execute tool securely with validation
+   * @param {string} toolId - Tool identifier
+   * @param {Object} params - Tool parameters
+   * @param {Object} context - Execution context
+   * @returns {Promise<*>} Execution result
+   */
+  async executeToolSecurely(toolId, params, context) {
+    const tool = this.getTool(toolId);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolId}`);
+    }
+    
+    if (!tool.isEnabled) {
+      throw new Error(`Tool is disabled: ${toolId}`);
+    }
+    
+    return await tool.executeWithLifecycle(params, context);
+  }
+
+  /**
+   * List all registered tools
+   * @returns {Array<string>} Array of tool IDs
+   */
+  listTools() {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Generate comprehensive tool descriptions for agent system prompts
+   * @param {Array<string>} capabilities - Specific tool IDs to include (empty = all)
+   * @param {Object} options - Generation options
+   * @returns {string} Formatted tool descriptions section
+   */
+  generateToolDescriptionsForPrompt(capabilities = [], options = {}) {
+    const {
+      includeExamples = true,
+      includeUsageGuidelines = true,
+      includeSecurityNotes = true,
+      compact = false
+    } = options;
+
+    // Get tools to include
+    const toolIds = capabilities.length > 0 
+      ? capabilities.filter(cap => this.tools.has(cap))
+      : Array.from(this.tools.keys());
+
+    if (toolIds.length === 0) {
+      return '';
+    }
+
+    let description = '\n## AVAILABLE TOOLS\n\n';
+    description += 'You have access to the following tools to perform operations and tasks:\n\n';
+
+    // Add individual tool descriptions
+    for (const toolId of toolIds) {
+      const tool = this.tools.get(toolId);
+      if (!tool || !tool.isEnabled) continue;
+
+      try {
+        if (compact) {
+          // Compact format - just tool name and brief description
+          const capabilities = tool.getCapabilities();
+          const actions = capabilities.supportedActions || ['execute'];
+          description += `**${toolId}**: ${actions.join(', ')}\n`;
+        } else {
+          // Full format - complete tool description
+          description += `### ${toolId.toUpperCase()} TOOL\n\n`;
+          description += tool.getDescription();
+          description += '\n\n---\n\n';
+        }
+      } catch (error) {
+        this.logger?.warn(`Failed to get description for tool: ${toolId}`, {
+          error: error.message
+        });
+      }
+    }
+
+    if (compact) {
+      description += '\nUse [tool id="tool-name"]<parameters>[/tool] or JSON format to invoke tools.\n\n';
+    }
+    
+    // Add comprehensive tool invocation instructions
+    description += '## TOOL INVOCATION SYNTAX\n\n';
+    description += '**IMPORTANT**: You MUST use one of these exact formats to invoke tools:\n\n';
+    description += '### Format 1: Bracket Notation\n';
+    description += '```\n';
+    description += '[tool id="toolname"]\n';
+    description += '<parameters here>\n';
+    description += '[/tool]\n';
+    description += '```\n\n';
+    description += '### Format 2: JSON in Markdown Code Block (REQUIRED for JSON)\n';
+    description += '```\n';
+    description += '```json\n';
+    description += '{\n';
+    description += '  "toolId": "toolname",\n';
+    description += '  "parameters": { ... } or "actions": [ ... ]\n';
+    description += '}\n';
+    description += '```\n';
+    description += '```\n\n';
+    description += '**WARNING**: Plain JSON without markdown code blocks (```json) will NOT be executed!\n';
+    description += 'Always wrap JSON tool commands in ```json ... ``` blocks.\n\n';
+    description += '### Format 3: XML Format\n';
+    description += '```xml\n';
+    description += '<tool-command>\n';
+    description += '  <tool id="toolname">\n';
+    description += '    <parameter>value</parameter>\n';
+    description += '  </tool>\n';
+    description += '</tool-command>\n';
+    description += '```\n\n';
+    description += 'After invoking a tool, WAIT for the actual response. Do NOT generate imaginary responses.\n';
+
+    return description;
+  }
+
+  /**
+   * Enhance existing system prompt with tool descriptions
+   * @param {string} existingPrompt - Current system prompt
+   * @param {Array<string>} capabilities - Agent capabilities
+   * @param {Object} options - Enhancement options
+   * @returns {string} Enhanced system prompt
+   */
+  enhanceSystemPrompt(existingPrompt, capabilities = [], options = {}) {
+    const toolSection = this.generateToolDescriptionsForPrompt(capabilities, options);
+
+    if (!toolSection.trim()) {
+      return existingPrompt || '';
+    }
+
+    const prompt = existingPrompt || '';
+    
+    // If prompt already contains tool section, replace it
+    if (prompt.includes('## AVAILABLE TOOLS')) {
+      return prompt.replace(
+        /## AVAILABLE TOOLS[\s\S]*?(?=##|$)/,
+        toolSection + '\n'
+      );
+    }
+
+    const orientationParagraph = `IMPORTANT: when asked to perform an action or operation, use each response to invoke a tool if needed, and update the user on the progress (same message).`;
+
+    // Otherwise, append to the end
+    return prompt + (prompt.endsWith('\n') ? '' : '\n') + toolSection + orientationParagraph + '\n';
+  }
+
+  /**
+   * Get available tools with metadata for web UI
+   * @returns {Array} Array of tool information objects
+   */
+  getAvailableToolsForUI() {
+    const tools = [];
+    
+    for (const [toolId, tool] of this.tools.entries()) {
+      const capabilities = tool.getCapabilities();
+      
+      // Extract tool name and description from the tool's description
+      const fullDescription = tool.getDescription();
+      const firstLine = fullDescription.split('\n').find(line => line.trim().length > 0) || '';
+      const toolName = firstLine.replace(/^.*Tool:\s*/i, '').replace(/\s*-.*$/, '').trim();
+      
+      tools.push({
+        id: toolId, // This is the correct ID to use in capabilities
+        name: toolName || toolId.charAt(0).toUpperCase() + toolId.slice(1),
+        description: firstLine,
+        category: this._getToolCategory(toolId),
+        enabled: capabilities.enabled,
+        async: capabilities.async,
+        requiresProject: capabilities.requiresProject,
+        className: tool.constructor.name
+      });
+    }
+    
+    return tools.sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Get tool category for organization
+   * @param {string} toolId - Tool identifier
+   * @returns {string} Tool category
+   * @private
+   */
+  _getToolCategory(toolId) {
+    const categories = {
+      'terminal': 'System',
+      'filesystem': 'File Operations', 
+      'browser': 'Automation',
+      'agentdelay': 'Utility'
+    };
+    
+    return categories[toolId] || 'Other';
+  }
+
+  /**
+   * Get registry statistics
+   * @returns {Object} Registry statistics
+   */
+  getRegistryStats() {
+    const enabledTools = Array.from(this.tools.values()).filter(tool => tool.isEnabled);
+    const totalOperations = Array.from(this.tools.values())
+      .reduce((sum, tool) => sum + tool.usageCount, 0);
+    
+    return {
+      totalTools: this.tools.size,
+      enabledTools: enabledTools.length,
+      totalOperations,
+      activeOperations: this.asyncOperations.size
+    };
+  }
+}
+
+export { BaseTool, ToolsRegistry };