@loxia-labs/loxia-autopilot-one 1.0.1

package/src/tools/fileSystemTool.js

@@ -0,0 +1,1107 @@
+/**
+ * FileSystemTool - Handle file system operations safely
+ * 
+ * Purpose:
+ * - Read, write, and manipulate files
+ * - Directory operations
+ * - File metadata and permissions
+ * - Safe file operations with validation
+ */
+
+import { BaseTool } from './baseTool.js';
+import TagParser from '../utilities/tagParser.js';
+import DirectoryAccessManager from '../utilities/directoryAccessManager.js';
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+import {
+  TOOL_STATUS,
+  FILE_EXTENSIONS,
+  SYSTEM_DEFAULTS
+} from '../utilities/constants.js';
+
+class FileSystemTool extends BaseTool {
+  constructor(config = {}, logger = null) {
+    super(config, logger);
+    
+    // Tool metadata
+    this.requiresProject = true;
+    this.isAsync = false; // Most file operations are quick
+    this.timeout = config.timeout || 30000; // 30 seconds
+    this.maxConcurrentOperations = config.maxConcurrentOperations || 5;
+    
+    // Security settings
+    this.maxFileSize = config.maxFileSize || SYSTEM_DEFAULTS.MAX_FILE_SIZE;
+    this.allowedExtensions = config.allowedExtensions || null; // null = all allowed
+    this.blockedExtensions = config.blockedExtensions || ['.exe', '.bat', '.cmd', '.scr', '.com'];
+    this.allowedDirectories = config.allowedDirectories || null; // null = project dir only
+    
+    // File operation history
+    this.operationHistory = [];
+    
+    // Directory access manager
+    this.directoryAccessManager = new DirectoryAccessManager(config, logger);
+  }
+
+  /**
+   * Get tool description for LLM consumption
+   * @returns {string} Tool description
+   */
+  getDescription() {
+    return `
+File System Tool: Perform file and directory operations safely within the project scope.
+
+CRITICAL: Both XML and JSON formats are fully supported. When using XML format, commands are automatically converted to the appropriate structure internally - you don't need to manually wrap them in an actions array.
+
+USAGE - TWO FORMATS SUPPORTED:
+
+FORMAT 1 - XML STYLE (Recommended):
+[tool id="filesystem"]
+<read file-path="src/index.js" />
+<write output-path="src/components/Button.js">
+const Button = () => {
+  return <button>Click me</button>;
+};
+export default Button;
+</write>
+[/tool]
+
+FORMAT 2 - JSON STYLE:
+\`\`\`json
+{
+  "toolId": "filesystem", 
+  "actions": [
+    {
+      "type": "read",
+      "filePath": "src/index.js"
+    },
+    {
+      "type": "write", 
+      "outputPath": "src/components/Button.js",
+      "content": "const Button = () => { return <button>Click me</button>; };"
+    }
+  ]
+}
+\`\`\`
+
+IMPORTANT: 
+- Use either format consistently. Do NOT mix formats in a single command.
+- XML format is recommended for single operations and better readability
+- JSON format is recommended for complex multi-action operations
+- Both formats work equally well and produce the same results
+
+SUPPORTED ACTIONS:
+- read: Read file contents
+- write: Write content to file
+- append: Append content to existing file
+- delete: Delete a file
+- copy: Copy file from source to destination
+- move: Move/rename file
+- create-dir: Create directory
+- list: List directory contents
+- exists: Check if file/directory exists
+- stats: Get file/directory metadata
+
+PARAMETERS:
+- file-path: Path to file to read
+- output-path: Path where to write/create file
+- source-path: Source path for copy/move operations
+- dest-path: Destination path for copy/move operations
+- directory: Directory path for directory operations
+- content: Content to write/append
+- encoding: File encoding (default: utf8)
+- create-dirs: Create parent directories if they don't exist (true/false)
+
+EXAMPLES:
+
+SIMPLE FILE CREATION (XML format - recommended):
+[tool id="filesystem"]
+<write output-path="hello.c">
+#include <stdio.h>
+
+int main() {
+    printf("Hello, World!\\n");
+    return 0;
+}
+</write>
+[/tool]
+
+READING FILES (XML format):
+[tool id="filesystem"]
+<read file-path="package.json" />
+[/tool]
+
+MULTIPLE OPERATIONS (JSON format recommended):
+\`\`\`json
+{
+  "toolId": "filesystem",
+  "actions": [
+    {
+      "type": "read",
+      "filePath": "src/index.js"
+    },
+    {
+      "type": "write",
+      "outputPath": "src/backup.js",
+      "content": "// Backup file\\nconsole.log('backup');"
+    }
+  ]
+}
+\`\`\`
+
+OTHER XML EXAMPLES:
+[tool id="filesystem"]
+<copy source-path="template.js" dest-path="src/component.js" />
+<create-dir directory="src/components/ui" />
+<list directory="src" />
+[/tool]
+
+SECURITY:
+- Operations restricted to project directory
+- File size limits enforced (max ${Math.round(this.maxFileSize / 1024 / 1024)}MB)
+- Dangerous file types blocked
+- Path traversal protection
+- Backup created for destructive operations
+
+ENCODING SUPPORT:
+- utf8 (default)
+- ascii
+- base64
+- binary
+- hex
+    `;
+  }
+
+  /**
+   * Parse parameters from tool command content
+   * @param {string} content - Raw tool command content
+   * @returns {Object} Parsed parameters
+   */
+  parseParameters(content) {
+    try {
+      const params = {};
+      const actions = [];
+      
+      this.logger?.debug('FileSystem tool parsing parameters', {
+        contentLength: content.length,
+        contentPreview: content.substring(0, 200)
+      });
+      
+      // Extract self-closing tags (read, delete, copy, etc.)
+      const selfClosingTags = [
+        'read', 'delete', 'copy', 'move', 'create-dir', 
+        'list', 'exists', 'stats', 'append'
+      ];
+      
+      for (const tagName of selfClosingTags) {
+        const tags = TagParser.extractTagsWithAttributes(content, tagName);
+        for (const tag of tags) {
+          const action = {
+            type: tagName,
+            ...tag.attributes
+          };
+          
+          // Normalize common attribute names
+          if (action['file-path']) {
+            action.filePath = action['file-path'];
+            delete action['file-path'];
+          }
+          if (action['output-path']) {
+            action.outputPath = action['output-path'];
+            delete action['output-path'];
+          }
+          if (action['source-path']) {
+            action.sourcePath = action['source-path'];
+            delete action['source-path'];
+          }
+          if (action['dest-path']) {
+            action.destPath = action['dest-path'];
+            delete action['dest-path'];
+          }
+          if (action['create-dirs']) {
+            action.createDirs = action['create-dirs'] === 'true';
+            delete action['create-dirs'];
+          }
+          
+          actions.push(action);
+        }
+      }
+      
+      // Extract write and append tags with content
+      const writeMatches = content.matchAll(/<write\s+([^>]*)>(.*?)<\/write>/gs);
+      for (const match of writeMatches) {
+        const parser = new TagParser();
+        const attributes = parser.parseAttributes(match[1]);
+        const writeContent = match[2].trim();
+        
+        const action = {
+          type: 'write',
+          content: writeContent,
+          ...attributes
+        };
+        
+        // Normalize attribute names
+        if (action['output-path']) {
+          action.outputPath = action['output-path'];
+          delete action['output-path'];
+        }
+        if (action['create-dirs']) {
+          action.createDirs = action['create-dirs'] === 'true';
+          delete action['create-dirs'];
+        }
+        
+        actions.push(action);
+      }
+      
+      const appendMatches = content.matchAll(/<append\s+([^>]*)>(.*?)<\/append>/gs);
+      for (const match of appendMatches) {
+        const parser = new TagParser();
+        const attributes = parser.parseAttributes(match[1]);
+        const appendContent = match[2].trim();
+        
+        const action = {
+          type: 'append',
+          content: appendContent,
+          ...attributes
+        };
+        
+        // Normalize attribute names
+        if (action['file-path']) {
+          action.filePath = action['file-path'];
+          delete action['file-path'];
+        }
+        
+        actions.push(action);
+      }
+      
+      params.actions = actions;
+      params.rawContent = content.trim();
+      
+      this.logger?.debug('Parsed FileSystem tool parameters', {
+        totalActions: actions.length,
+        actionTypes: actions.map(a => a.type),
+        actions: actions.map(a => ({ 
+          type: a.type, 
+          filePath: a.filePath, 
+          outputPath: a.outputPath,
+          hasContent: !!a.content 
+        }))
+      });
+      
+      return params;
+      
+    } catch (error) {
+      throw new Error(`Failed to parse filesystem parameters: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get required parameters
+   * @returns {Array<string>} Array of required parameter names
+   */
+  getRequiredParameters() {
+    return ['actions'];
+  }
+
+  /**
+   * Custom parameter validation
+   * @param {Object} params - Parameters to validate
+   * @returns {Object} Validation result
+   */
+  customValidateParameters(params) {
+    const errors = [];
+    
+    if (!params.actions || !Array.isArray(params.actions) || params.actions.length === 0) {
+      errors.push('At least one action is required');
+    } else {
+      // Validate each action
+      for (const [index, action] of params.actions.entries()) {
+        if (!action.type) {
+          errors.push(`Action ${index + 1}: type is required`);
+          continue;
+        }
+        
+        switch (action.type) {
+          case 'read':
+          case 'delete':
+          case 'exists':
+          case 'stats':
+            if (!action.filePath) {
+              errors.push(`Action ${index + 1}: file-path is required for ${action.type}`);
+            }
+            break;
+            
+          case 'write':
+            if (!action.outputPath) {
+              errors.push(`Action ${index + 1}: output-path is required for write`);
+            }
+            if (!action.content && action.content !== '') {
+              errors.push(`Action ${index + 1}: content is required for write`);
+            }
+            break;
+            
+          case 'append':
+            if (!action.filePath) {
+              errors.push(`Action ${index + 1}: file-path is required for append`);
+            }
+            if (!action.content && action.content !== '') {
+              errors.push(`Action ${index + 1}: content is required for append`);
+            }
+            break;
+            
+          case 'copy':
+          case 'move':
+            if (!action.sourcePath) {
+              errors.push(`Action ${index + 1}: source-path is required for ${action.type}`);
+            }
+            if (!action.destPath) {
+              errors.push(`Action ${index + 1}: dest-path is required for ${action.type}`);
+            }
+            break;
+            
+          case 'create-dir':
+          case 'list':
+            if (!action.directory) {
+              errors.push(`Action ${index + 1}: directory is required for ${action.type}`);
+            }
+            break;
+            
+          default:
+            errors.push(`Action ${index + 1}: unknown action type: ${action.type}`);
+        }
+        
+        // Validate file extensions if specified
+        if (action.filePath && !this.isAllowedFileExtension(action.filePath)) {
+          errors.push(`Action ${index + 1}: file type not allowed: ${path.extname(action.filePath)}`);
+        }
+        if (action.outputPath && !this.isAllowedFileExtension(action.outputPath)) {
+          errors.push(`Action ${index + 1}: file type not allowed: ${path.extname(action.outputPath)}`);
+        }
+      }
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+
+  /**
+   * Execute tool with parsed parameters
+   * @param {Object} params - Parsed parameters
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(params, context) {
+    // Validate params structure
+    if (!params || typeof params !== 'object') {
+      throw new Error('Invalid parameters: params must be an object');
+    }
+
+    const { actions } = params;
+
+    // Validate actions array
+    if (!actions) {
+      throw new Error('Invalid parameters: actions is required. Received params: ' + JSON.stringify(Object.keys(params)));
+    }
+
+    if (!Array.isArray(actions)) {
+      throw new Error('Invalid parameters: actions must be an array. Received type: ' + typeof actions);
+    }
+
+    if (actions.length === 0) {
+      throw new Error('Invalid parameters: actions array is empty');
+    }
+
+    const { projectDir, agentId, directoryAccess } = context;
+
+    // Get directory access configuration from agent or create default
+    const accessConfig = directoryAccess ||
+      this.directoryAccessManager.createDirectoryAccess({
+        workingDirectory: projectDir || process.cwd(),
+        writeEnabledDirectories: [projectDir || process.cwd()],
+        restrictToProject: true
+      });
+    
+    // IMPORTANT: If the agent has directoryAccess configured, use its workingDirectory
+    // This ensures UI-configured project directories are respected
+    if (directoryAccess && directoryAccess.workingDirectory) {
+      // Agent has explicitly configured working directory from UI - use it
+      console.log('FileSystem DEBUG: Using agent configured working directory:', directoryAccess.workingDirectory);
+      console.log('FileSystem DEBUG: Full directoryAccess object:', JSON.stringify(directoryAccess, null, 2));
+    } else {
+      // Using fallback to projectDir or process.cwd()
+      console.log('FileSystem DEBUG: Using fallback working directory:', projectDir || process.cwd());
+      console.log('FileSystem DEBUG: directoryAccess is:', directoryAccess);
+      console.log('FileSystem DEBUG: projectDir is:', projectDir);
+    }
+    
+    const results = [];
+    
+    for (const action of actions) {
+      try {
+        let result;
+        
+        switch (action.type) {
+          case 'read':
+            result = await this.readFile(action.filePath, accessConfig, action.encoding);
+            break;
+            
+          case 'write':
+            result = await this.writeFile(action.outputPath, action.content, accessConfig, {
+              encoding: action.encoding,
+              createDirs: action.createDirs
+            });
+            break;
+            
+          case 'append':
+            result = await this.appendToFile(action.filePath, action.content, accessConfig, action.encoding);
+            break;
+            
+          case 'delete':
+            result = await this.deleteFile(action.filePath, accessConfig);
+            break;
+            
+          case 'copy':
+            result = await this.copyFile(action.sourcePath, action.destPath, accessConfig);
+            break;
+            
+          case 'move':
+            result = await this.moveFile(action.sourcePath, action.destPath, accessConfig);
+            break;
+            
+          case 'create-dir':
+            result = await this.createDirectory(action.directory, accessConfig);
+            break;
+            
+          case 'list':
+            result = await this.listDirectory(action.directory, accessConfig);
+            break;
+            
+          case 'exists':
+            result = await this.checkExists(action.filePath, accessConfig);
+            break;
+            
+          case 'stats':
+            result = await this.getFileStats(action.filePath, accessConfig);
+            break;
+            
+          default:
+            throw new Error(`Unknown action type: ${action.type}`);
+        }
+        
+        results.push(result);
+        this.addToHistory(action, result, context.agentId);
+        
+      } catch (error) {
+        const errorResult = {
+          success: false,
+          action: action.type,
+          error: error.message,
+          filePath: action.filePath || action.outputPath || action.directory
+        };
+        
+        results.push(errorResult);
+        this.addToHistory(action, errorResult, context.agentId);
+      }
+    }
+    
+    return {
+      success: true,
+      actions: results,
+      executedActions: actions.length,
+      toolUsed: 'filesys'
+    };
+  }
+
+  /**
+   * Read file contents
+   * @private
+   */
+  async readFile(filePath, accessConfig, encoding = 'utf8') {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(filePath, workingDir);
+    
+    // Validate read access using DirectoryAccessManager
+    const accessResult = this.directoryAccessManager.validateReadAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Read access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+    
+    try {
+      const stats = await fs.stat(fullPath);
+      
+      if (stats.size > this.maxFileSize) {
+        throw new Error(`File too large: ${stats.size} bytes (max ${this.maxFileSize})`);
+      }
+      
+      const content = await fs.readFile(fullPath, encoding);
+      
+      return {
+        success: true,
+        action: 'read',
+        filePath: this.directoryAccessManager.createRelativePath(fullPath, accessConfig),
+        content,
+        size: stats.size,
+        encoding,
+        lastModified: stats.mtime.toISOString(),
+        message: `Read ${stats.size} bytes from ${filePath}`
+      };
+      
+    } catch (error) {
+      throw new Error(`Failed to read file ${filePath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Write content to file
+   * @private
+   */
+  async writeFile(outputPath, content, accessConfig, options = {}) {
+    const { encoding = 'utf8', createDirs = true } = options;
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(outputPath, workingDir);
+    
+    // Validate write access using DirectoryAccessManager
+    const accessResult = this.directoryAccessManager.validateWriteAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Write access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+    
+    try {
+      // Check content size
+      const contentSize = Buffer.byteLength(content, encoding);
+      if (contentSize > this.maxFileSize) {
+        throw new Error(`Content too large: ${contentSize} bytes (max ${this.maxFileSize})`);
+      }
+      
+      // Create parent directories if requested
+      if (createDirs) {
+        const dirPath = path.dirname(fullPath);
+        await fs.mkdir(dirPath, { recursive: true });
+      }
+      
+      // Create backup if file exists
+      let backupPath = null;
+      try {
+        await fs.access(fullPath);
+        backupPath = `${fullPath}.backup-${Date.now()}`;
+        await fs.copyFile(fullPath, backupPath);
+      } catch {
+        // File doesn't exist, no backup needed
+      }
+      
+      await fs.writeFile(fullPath, content, encoding);
+      
+      const stats = await fs.stat(fullPath);
+      
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+      
+      return {
+        success: true,
+        action: 'write',
+        outputPath: relativePath,
+        fullPath: fullPath,
+        size: stats.size,
+        encoding,
+        backupPath: backupPath ? this.directoryAccessManager.createRelativePath(backupPath, accessConfig) : null,
+        backupFullPath: backupPath || null,
+        message: `Wrote ${stats.size} bytes to ${fullPath}`
+      };
+      
+    } catch (error) {
+      throw new Error(`Failed to write file ${fullPath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Append content to file
+   * @private
+   */
+  async appendToFile(filePath, content, accessConfig, encoding = 'utf8') {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(filePath, workingDir);
+    
+    // Validate write access using DirectoryAccessManager
+    const accessResult = this.directoryAccessManager.validateWriteAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Write access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+    
+    try {
+      // Check if file exists and get current size
+      let currentSize = 0;
+      try {
+        const stats = await fs.stat(fullPath);
+        currentSize = stats.size;
+      } catch {
+        // File doesn't exist, will be created
+      }
+      
+      const contentSize = Buffer.byteLength(content, encoding);
+      if (currentSize + contentSize > this.maxFileSize) {
+        throw new Error(`File would become too large: ${currentSize + contentSize} bytes (max ${this.maxFileSize})`);
+      }
+      
+      await fs.appendFile(fullPath, content, encoding);
+      
+      const stats = await fs.stat(fullPath);
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+      
+      return {
+        success: true,
+        action: 'append',
+        filePath: relativePath,
+        fullPath: fullPath,
+        appendedBytes: contentSize,
+        totalSize: stats.size,
+        encoding,
+        message: `Appended ${contentSize} bytes to ${fullPath}`
+      };
+      
+    } catch (error) {
+      throw new Error(`Failed to append to file ${fullPath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Delete file
+   * @private
+   */
+  async deleteFile(filePath, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(filePath, workingDir);
+    
+    // Validate write access for deletion
+    const accessResult = this.directoryAccessManager.validateWriteAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Delete access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+    
+    try {
+      const stats = await fs.stat(fullPath);
+      
+      // Create backup before deletion
+      const backupPath = `${fullPath}.deleted-backup-${Date.now()}`;
+      await fs.copyFile(fullPath, backupPath);
+      
+      await fs.unlink(fullPath);
+      
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+      const backupRelativePath = this.directoryAccessManager.createRelativePath(backupPath, accessConfig);
+      
+      return {
+        success: true,
+        action: 'delete',
+        filePath: relativePath,
+        fullPath: fullPath,
+        size: stats.size,
+        backupPath: backupRelativePath,
+        backupFullPath: backupPath,
+        message: `Deleted ${fullPath} (backup created)`
+      };
+      
+    } catch (error) {
+      throw new Error(`Failed to delete file ${fullPath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Copy file
+   * @private
+   */
+  async copyFile(sourcePath, destPath, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullSourcePath = this.resolvePath(sourcePath, workingDir);
+    const fullDestPath = this.resolvePath(destPath, workingDir);
+    
+    // Validate read access for source
+    const sourceAccessResult = this.directoryAccessManager.validateReadAccess(fullSourcePath, accessConfig);
+    if (!sourceAccessResult.allowed) {
+      throw new Error(`Source read access denied: ${sourceAccessResult.reason} (${sourceAccessResult.path})`);
+    }
+    
+    // Validate write access for destination
+    const destAccessResult = this.directoryAccessManager.validateWriteAccess(fullDestPath, accessConfig);
+    if (!destAccessResult.allowed) {
+      throw new Error(`Destination write access denied: ${destAccessResult.reason} (${destAccessResult.path})`);
+    }
+    
+    try {
+      const sourceStats = await fs.stat(fullSourcePath);
+      
+      if (sourceStats.size > this.maxFileSize) {
+        throw new Error(`Source file too large: ${sourceStats.size} bytes`);
+      }
+      
+      // Create destination directory if needed
+      const destDir = path.dirname(fullDestPath);
+      await fs.mkdir(destDir, { recursive: true });
+      
+      await fs.copyFile(fullSourcePath, fullDestPath);
+      
+      const sourceRelativePath = this.directoryAccessManager.createRelativePath(fullSourcePath, accessConfig);
+      const destRelativePath = this.directoryAccessManager.createRelativePath(fullDestPath, accessConfig);
+      
+      return {
+        success: true,
+        action: 'copy',
+        sourcePath: sourceRelativePath,
+        destPath: destRelativePath,
+        sourceFullPath: fullSourcePath,
+        destFullPath: fullDestPath,
+        size: sourceStats.size,
+        message: `Copied ${fullSourcePath} to ${fullDestPath}`
+      };
+      
+    } catch (error) {
+      throw new Error(`Failed to copy ${fullSourcePath} to ${fullDestPath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Move/rename file
+   * @private
+   */
+  async moveFile(sourcePath, destPath, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullSourcePath = this.resolvePath(sourcePath, workingDir);
+    const fullDestPath = this.resolvePath(destPath, workingDir);
+
+    // Validate read access for source
+    const readResult = this.directoryAccessManager.validateReadAccess(fullSourcePath, accessConfig);
+    if (!readResult.allowed) {
+      throw new Error(`Read access denied for source: ${readResult.reason} (${readResult.path})`);
+    }
+
+    // Validate write access for destination
+    const writeResult = this.directoryAccessManager.validateWriteAccess(fullDestPath, accessConfig);
+    if (!writeResult.allowed) {
+      throw new Error(`Write access denied for destination: ${writeResult.reason} (${writeResult.path})`);
+    }
+
+    try {
+      const sourceStats = await fs.stat(fullSourcePath);
+
+      // Create destination directory if needed
+      const destDir = path.dirname(fullDestPath);
+      await fs.mkdir(destDir, { recursive: true });
+
+      await fs.rename(fullSourcePath, fullDestPath);
+
+      const relativeSource = this.directoryAccessManager.createRelativePath(fullSourcePath, accessConfig);
+      const relativeDest = this.directoryAccessManager.createRelativePath(fullDestPath, accessConfig);
+
+      return {
+        success: true,
+        action: 'move',
+        sourcePath: relativeSource,
+        destPath: relativeDest,
+        fullSourcePath: fullSourcePath,
+        fullDestPath: fullDestPath,
+        size: sourceStats.size,
+        message: `Moved ${sourcePath} to ${destPath}`
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to move ${sourcePath} to ${destPath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Create directory
+   * @private
+   */
+  async createDirectory(directory, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(directory, workingDir);
+
+    // Validate write access using DirectoryAccessManager
+    const accessResult = this.directoryAccessManager.validateWriteAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Write access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+
+    try {
+      await fs.mkdir(fullPath, { recursive: true });
+
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+
+      return {
+        success: true,
+        action: 'create-dir',
+        directory: relativePath,
+        fullPath: fullPath,
+        message: `Created directory ${directory}`
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to create directory ${directory}: ${error.message}`);
+    }
+  }
+
+  /**
+   * List directory contents
+   * @private
+   */
+  async listDirectory(directory, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(directory, workingDir);
+
+    // Validate read access using DirectoryAccessManager
+    const accessResult = this.directoryAccessManager.validateReadAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Read access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+
+    try {
+      const entries = await fs.readdir(fullPath, { withFileTypes: true });
+
+      const contents = [];
+      for (const entry of entries) {
+        const entryPath = path.join(fullPath, entry.name);
+        const stats = await fs.stat(entryPath);
+
+        contents.push({
+          name: entry.name,
+          type: entry.isDirectory() ? 'directory' : 'file',
+          size: entry.isFile() ? stats.size : undefined,
+          lastModified: stats.mtime.toISOString(),
+          permissions: stats.mode,
+          isSymlink: entry.isSymbolicLink()
+        });
+      }
+
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+
+      return {
+        success: true,
+        action: 'list',
+        directory: relativePath,
+        fullPath: fullPath,
+        contents,
+        totalItems: contents.length,
+        directories: contents.filter(item => item.type === 'directory').length,
+        files: contents.filter(item => item.type === 'file').length,
+        message: `Listed ${contents.length} items in ${directory}`
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to list directory ${directory}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check if file/directory exists
+   * @private
+   */
+  async checkExists(filePath, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(filePath, workingDir);
+
+    // Validate read access
+    const accessResult = this.directoryAccessManager.validateReadAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Read access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+
+    try {
+      const stats = await fs.stat(fullPath);
+
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+
+      return {
+        success: true,
+        action: 'exists',
+        filePath: relativePath,
+        fullPath: fullPath,
+        exists: true,
+        type: stats.isDirectory() ? 'directory' : 'file',
+        message: `${filePath} exists as ${stats.isDirectory() ? 'directory' : 'file'}`
+      };
+
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+        return {
+          success: true,
+          action: 'exists',
+          filePath: relativePath,
+          fullPath: fullPath,
+          exists: false,
+          message: `${filePath} does not exist`
+        };
+      }
+
+      throw new Error(`Failed to check existence of ${filePath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get file statistics
+   * @private
+   */
+  async getFileStats(filePath, accessConfig) {
+    const workingDir = this.directoryAccessManager.getWorkingDirectory(accessConfig);
+    const fullPath = this.resolvePath(filePath, workingDir);
+
+    // Validate read access
+    const accessResult = this.directoryAccessManager.validateReadAccess(fullPath, accessConfig);
+    if (!accessResult.allowed) {
+      throw new Error(`Read access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+
+    try {
+      const stats = await fs.stat(fullPath);
+
+      const relativePath = this.directoryAccessManager.createRelativePath(fullPath, accessConfig);
+
+      return {
+        success: true,
+        action: 'stats',
+        filePath: relativePath,
+        fullPath: fullPath,
+        stats: {
+          size: stats.size,
+          type: stats.isDirectory() ? 'directory' : 'file',
+          lastModified: stats.mtime.toISOString(),
+          lastAccessed: stats.atime.toISOString(),
+          created: stats.birthtime.toISOString(),
+          permissions: stats.mode,
+          isSymlink: stats.isSymbolicLink()
+        },
+        message: `Retrieved stats for ${filePath}`
+      };
+
+    } catch (error) {
+      throw new Error(`Failed to get stats for ${filePath}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Resolve file path safely (legacy method for compatibility)
+   * @private
+   */
+  resolvePath(filePath, workingDir) {
+    if (path.isAbsolute(filePath)) {
+      return path.normalize(filePath);
+    }
+    return path.resolve(workingDir, filePath);
+  }
+
+  /**
+   * Validate path access using DirectoryAccessManager
+   * @private
+   */
+  validatePathAccess(fullPath, accessConfig, operation = 'read') {
+    const accessResult = operation === 'write' 
+      ? this.directoryAccessManager.validateWriteAccess(fullPath, accessConfig)
+      : this.directoryAccessManager.validateReadAccess(fullPath, accessConfig);
+      
+    if (!accessResult.allowed) {
+      throw new Error(`${operation} access denied: ${accessResult.reason} (${accessResult.path})`);
+    }
+    
+    return accessResult;
+  }
+
+  /**
+   * Check if file extension is allowed
+   * @private
+   */
+  isAllowedFileExtension(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    
+    if (this.blockedExtensions.includes(ext)) {
+      return false;
+    }
+    
+    if (this.allowedExtensions && !this.allowedExtensions.includes(ext)) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Add operation to history
+   * @private
+   */
+  addToHistory(action, result, agentId) {
+    const historyEntry = {
+      timestamp: new Date().toISOString(),
+      agentId,
+      action: action.type,
+      filePath: action.filePath || action.outputPath || action.directory,
+      success: result.success,
+      size: result.size
+    };
+    
+    this.operationHistory.push(historyEntry);
+    
+    // Keep only last 200 entries
+    if (this.operationHistory.length > 200) {
+      this.operationHistory = this.operationHistory.slice(-200);
+    }
+  }
+
+  /**
+   * Get supported actions for this tool
+   * @returns {Array<string>} Array of supported action names
+   */
+  getSupportedActions() {
+    return [
+      'read', 'write', 'append', 'delete', 'copy', 'move', 
+      'create-dir', 'list', 'exists', 'stats'
+    ];
+  }
+
+  /**
+   * Get parameter schema for validation
+   * @returns {Object} Parameter schema
+   */
+  getParameterSchema() {
+    return {
+      type: 'object',
+      properties: {
+        actions: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: this.getSupportedActions()
+              },
+              filePath: { type: 'string' },
+              outputPath: { type: 'string' },
+              sourcePath: { type: 'string' },
+              destPath: { type: 'string' },
+              directory: { type: 'string' },
+              content: { type: 'string' },
+              encoding: { type: 'string' },
+              createDirs: { type: 'boolean' }
+            },
+            required: ['type']
+          }
+        }
+      },
+      required: ['actions']
+    };
+  }
+
+  /**
+   * Get operation history for debugging
+   * @returns {Array} Operation history
+   */
+  getOperationHistory(agentId = null) {
+    if (agentId) {
+      return this.operationHistory.filter(entry => entry.agentId === agentId);
+    }
+    return [...this.operationHistory];
+  }
+}
+
+export default FileSystemTool;