@compass-ai/nova 1.0.73 → 1.0.74

package/dist/tools/file-tools.js

@@ -0,0 +1,954 @@
+/**
+ * File operation tools
+ *
+ * Tools for reading, writing, and manipulating files and directories.
+ * Extracted from the monolithic built-in-tools.ts for better maintainability.
+ */
+import { getFileService } from '../services/file-service.js';
+import { ActionType } from '../services/action-logger.js';
+import { pathExists } from '../utils/file-system.js';
+import { trackFileHash, updateFileHash, validateFileIntegrity, untrackFile, FileModifiedExternallyError, } from '../services/file-hash-tracker.js';
+import { MAX_FILE_READ_TOKENS, MAX_FILE_TOKENS_REJECT_THRESHOLD } from '../constants/defaults.js';
+import { estimateTokens } from '../utils/token-counter.js';
+import { isBlocklistedFile, truncateToolResult, formatBytes, findSimilarText, } from './shared-utils.js';
+import { replaceWithStrategies } from './edit-replacers.js';
+import { generateCompactEditResponse } from '../utils/diff.js';
+import path from 'path';
+import { logger } from '../utils/logger.js';
+import { getGlobalCompassDir, getProjectCompassDir } from '../utils/path.js';
+const turnFileCache = new Map();
+const TURN_CACHE_TTL_MS = 60000; // 60 seconds - covers typical LLM turn duration
+/**
+ * Gets a cached file entry if it exists and hasn't expired
+ */
+function getCachedFile(filePath) {
+    const entry = turnFileCache.get(filePath);
+    if (entry && Date.now() - entry.timestamp < TURN_CACHE_TTL_MS) {
+        return entry;
+    }
+    // Expired or not found - clean up if expired
+    if (entry) {
+        turnFileCache.delete(filePath);
+    }
+    return undefined;
+}
+/**
+ * Caches a file read result
+ * @param fullContentReturned - Whether the full file content was returned to the LLM
+ */
+function cacheFileRead(filePath, content, totalLines, fullContentReturned) {
+    // Limit cache size to prevent memory bloat
+    if (turnFileCache.size >= 50) {
+        // Evict oldest entries
+        const now = Date.now();
+        for (const [key, entry] of turnFileCache) {
+            if (now - entry.timestamp > TURN_CACHE_TTL_MS / 2) {
+                turnFileCache.delete(key);
+            }
+        }
+    }
+    const existing = turnFileCache.get(filePath);
+    turnFileCache.set(filePath, {
+        content,
+        timestamp: Date.now(),
+        size: content.length,
+        totalLines,
+        // Once full content has been returned, keep it flagged
+        fullContentReturned: fullContentReturned || (existing?.fullContentReturned ?? false),
+    });
+}
+/**
+ * Invalidates a cached file (call after writes/edits)
+ */
+function invalidateCachedFile(filePath) {
+    turnFileCache.delete(filePath);
+}
+/**
+ * Clears the entire turn cache (call on new conversation turns if needed)
+ */
+export function clearTurnFileCache() {
+    turnFileCache.clear();
+}
+export function registerFileTools(registry) {
+    registry.registerTool('read_file', `Reads the contents of a file from the project.
+
+IMPORTANT: To minimize token usage and context bloat:
+- For large files (>200 lines), ALWAYS use offset/limit to read specific sections
+- First read a small portion (limit: 50) to understand structure, then target specific areas
+- Use grep_search to find relevant line numbers before reading
+- Full file reads are truncated at ~8000 tokens and rejected entirely above ~40000 tokens
+
+Parameters:
+- path: File path to read
+- offset: Starting line number (0-indexed). Use to skip to relevant sections.
+- limit: Max lines to read. Use 50-100 for targeted reads.`, {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Relative or absolute path to the file to read',
+            },
+            offset: {
+                type: 'number',
+                description: 'Line number to start reading from (0-indexed). Defaults to 0 (start of file).',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum number of lines to read. If not specified, reads to end of file.',
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fileService = getFileService();
+        const filePath = path.resolve(context.projectRoot, input.path);
+        // Check if file is blocklisted (large/generated files that would bloat context)
+        const blocklistCheck = isBlocklistedFile(input.path);
+        if (blocklistCheck.blocked) {
+            logger.warn(`Blocked read of file: ${input.path}`, { reason: blocklistCheck.reason });
+            return {
+                path: input.path,
+                content: '',
+                size: 0,
+                totalLines: 0,
+                linesReturned: 0,
+                blocked: true,
+                blockReason: blocklistCheck.reason,
+                suggestion: 'If you need specific information from this file, please describe what you\'re looking for and I can help find an alternative approach.',
+            };
+        }
+        const exists = await pathExists(filePath);
+        if (!exists) {
+            throw new Error(`File not found: ${input.path}`);
+        }
+        // Check turn cache first to avoid redundant disk reads
+        const hasPartialRead = input.offset !== undefined || input.limit !== undefined;
+        const cachedEntry = getCachedFile(filePath);
+        let content;
+        let fromCache = false;
+        if (cachedEntry && !hasPartialRead && cachedEntry.fullContentReturned) {
+            // Full file read with cache hit AND full content was already shown to LLM
+            // DON'T return full content again - this prevents context bloat
+            logger.debug(`Turn cache hit for ${input.path} (${cachedEntry.size} bytes) - returning stub (already read)`);
+            return {
+                path: input.path,
+                content: '', // Empty content to save tokens
+                size: cachedEntry.size,
+                totalLines: cachedEntry.totalLines,
+                linesReturned: 0,
+                fromCache: true,
+                alreadyRead: true,
+                note: `This file (${cachedEntry.totalLines} lines) was already read in this conversation. Use the previously read content instead of re-reading. If you need a specific section, use offset/limit parameters.`,
+            };
+        }
+        else if (cachedEntry && !hasPartialRead && !cachedEntry.fullContentReturned) {
+            // Full file read, file is cached but only partial content was shown before
+            // Return full content from cache and mark as fully returned
+            content = cachedEntry.content;
+            fromCache = true;
+            // Update cache to mark full content as returned
+            cacheFileRead(filePath, content, cachedEntry.totalLines, true);
+            logger.debug(`Turn cache hit for ${input.path} - returning full content (first full read)`);
+        }
+        else if (cachedEntry && hasPartialRead) {
+            // Partial read but we have the full file cached - slice from cache
+            content = cachedEntry.content;
+            fromCache = true;
+            logger.debug(`Turn cache hit (partial read) for ${input.path}`);
+        }
+        else {
+            // Cache miss - read from disk
+            content = await fileService.readFile(filePath) || '';
+            // Cache full file content for future reads in this turn
+            // Mark fullContentReturned based on whether this is a full read or partial
+            const lines = content.split('\n');
+            cacheFileRead(filePath, content, lines.length, !hasPartialRead);
+            logger.debug(`Turn cache miss for ${input.path}, cached ${content.length} bytes`);
+        }
+        // Track the full file content hash for integrity checking on future edits
+        // Only track if reading the full file (no offset/limit)
+        const fullContent = content;
+        if (!hasPartialRead) {
+            trackFileHash(filePath, fullContent);
+            // Check if full file read would exceed token threshold
+            const estimatedTokenCount = estimateTokens(content);
+            if (estimatedTokenCount > MAX_FILE_TOKENS_REJECT_THRESHOLD) {
+                throw new Error(`File content (${estimatedTokenCount} tokens) exceeds maximum allowed tokens (${MAX_FILE_TOKENS_REJECT_THRESHOLD}). ` +
+                    `Please use offset and limit parameters to read specific portions of the file, ` +
+                    `or use the GrepTool to search for specific content.`);
+            }
+        }
+        let lines = content.split('\n');
+        const totalLines = lines.length;
+        let truncated = false;
+        let tokenTruncated = false;
+        let originalTokens;
+        // Apply offset (start line)
+        const startLine = input.offset !== undefined && input.offset > 0 ? Math.min(input.offset, totalLines) : 0;
+        // Apply limit (number of lines to read)
+        let endLine = totalLines;
+        if (input.limit !== undefined && input.limit > 0) {
+            endLine = Math.min(startLine + input.limit, totalLines);
+        }
+        // Slice the lines if we have offset or limit
+        if (startLine > 0 || endLine < totalLines) {
+            lines = lines.slice(startLine, endLine);
+            truncated = startLine > 0 || endLine < totalLines;
+            content = lines.join('\n');
+        }
+        // Apply token-based truncation to prevent context bloat
+        const truncationResult = truncateToolResult(content, MAX_FILE_READ_TOKENS, 'File content');
+        if (truncationResult.wasTruncated) {
+            content = truncationResult.content;
+            tokenTruncated = true;
+            originalTokens = truncationResult.originalTokens;
+            logger.info(`Truncated file read for ${input.path}: ${truncationResult.originalTokens} -> ${truncationResult.truncatedTokens} tokens`);
+        }
+        return {
+            path: input.path,
+            content,
+            size: content.length,
+            totalLines,
+            linesReturned: lines.length,
+            truncated: truncated || tokenTruncated,
+            tokenTruncated,
+            originalTokens,
+            startLine: startLine > 0 ? startLine : undefined,
+            fromCache,
+            // Hint to LLM: if fromCache is true, this file was already read recently
+            ...(fromCache && { note: 'This file was read recently in this conversation. Content served from cache.' }),
+        };
+    }, {
+        actionType: ActionType.FILE_READ,
+        requiresApproval: false,
+        category: 'file_operations',
+        tags: ['io', 'read'],
+        displayName: 'Read',
+    });
+    registry.registerTool('write_file', `Writes content to a file. Creates the file if it doesn't exist, or overwrites if it does.
+
+When to use:
+- Creating NEW files
+- Complete file rewrites (replacing all content)
+- When you have the full file content ready
+
+Use edit_file instead for: targeted changes to specific parts of existing files.`, {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Relative or absolute path to the file to write',
+            },
+            content: {
+                type: 'string',
+                description: 'Content to write to the file',
+            },
+            description: {
+                type: 'string',
+                description: 'Human-readable description of why this file is being written',
+            },
+        },
+        required: ['path', 'content'],
+    }, async (input, context) => {
+        const fileService = getFileService();
+        const filePath = path.resolve(context.projectRoot, input.path);
+        // If file exists, validate it hasn't been modified externally since last read
+        const fileExists = await pathExists(filePath);
+        if (fileExists) {
+            try {
+                await validateFileIntegrity(filePath);
+            }
+            catch (error) {
+                if (error instanceof FileModifiedExternallyError) {
+                    // Invalidate stale caches so next read_file hits disk and re-tracks
+                    invalidateCachedFile(filePath);
+                    untrackFile(filePath);
+                    return error.toToolResponse();
+                }
+                throw error;
+            }
+        }
+        // Auto-approve writes to internal CLI directories (memory, config, etc.)
+        const isCompassPath = filePath.startsWith(getGlobalCompassDir())
+            || filePath.startsWith(getProjectCompassDir(context.projectRoot));
+        const result = await fileService.writeFile(filePath, input.content, {
+            description: input.description || `Write file: ${input.path}`,
+            requireApproval: !isCompassPath,
+            createBackup: !isCompassPath,
+        });
+        // Update the tracked hash after successful write
+        if (result.success) {
+            updateFileHash(filePath, input.content);
+            // Invalidate turn cache so next read gets fresh content
+            invalidateCachedFile(filePath);
+        }
+        return {
+            path: input.path,
+            success: result.success,
+            operation: result.operation,
+            backupCreated: !!result.backup,
+            error: result.error, // Pass through error for rejection detection
+            lineCount: input.content.split('\n').length,
+            byteSize: Buffer.byteLength(input.content, 'utf-8'),
+        };
+    }, {
+        actionType: ActionType.FILE_WRITE,
+        requiresApproval: true,
+        category: 'file_operations',
+        tags: ['io', 'write', 'modify'],
+        displayName: 'Write',
+    });
+    registry.registerTool('delete_file', 'Deletes a file from the filesystem. A backup will be created automatically before deletion.', {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Relative or absolute path to the file to delete',
+            },
+            description: {
+                type: 'string',
+                description: 'Reason for deleting this file',
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fileService = getFileService();
+        const filePath = path.resolve(context.projectRoot, input.path);
+        const result = await fileService.deleteFile(filePath, {
+            description: input.description || `Delete file: ${input.path}`,
+            requireApproval: true,
+        });
+        // Invalidate turn cache for deleted file
+        if (result.success) {
+            invalidateCachedFile(filePath);
+        }
+        return {
+            path: input.path,
+            success: result.success,
+            backupCreated: !!result.backup,
+            error: result.error, // Pass through error for rejection detection
+        };
+    }, {
+        actionType: ActionType.FILE_DELETE,
+        requiresApproval: true,
+        category: 'file_operations',
+        tags: ['io', 'delete', 'remove'],
+        displayName: 'Delete',
+    });
+    registry.registerTool('list_files', 'Lists files in a directory with optional glob pattern filtering. Always provide the "directory" parameter — use "." for the project root. To search recursively, set "recursive" to true. Example: directory="src", pattern="*.tsx", recursive=true.', {
+        type: 'object',
+        properties: {
+            directory: {
+                type: 'string',
+                description: 'Directory to list files from (relative or absolute). Use "." for the project root. This parameter is required.',
+            },
+            pattern: {
+                type: 'string',
+                description: 'Glob pattern to filter file names (e.g., "*.ts", "*.{png,jpg,svg}"). Only matches file names, not paths. Defaults to "*" (all files).',
+            },
+            recursive: {
+                type: 'boolean',
+                description: 'Whether to list files recursively in subdirectories. Set to true when searching the whole tree.',
+                default: false,
+            },
+            excludePatterns: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Glob patterns to exclude (e.g., ["**/test/**", "**/*.spec.ts"]). Defaults to node_modules, .git, dist, build.',
+            },
+        },
+        required: ['directory'],
+    }, async (input, context) => {
+        const { glob } = await import('glob');
+        const directory = input.directory || '.';
+        const dirPath = path.resolve(context.projectRoot, directory);
+        const exists = await pathExists(dirPath);
+        if (!exists) {
+            throw new Error(`Directory not found: ${directory}`);
+        }
+        const pattern = input.pattern || '*';
+        // Convert to forward slashes for glob compatibility on Windows
+        const globPattern = (input.recursive
+            ? path.join(dirPath, '**', pattern)
+            : path.join(dirPath, pattern)).replace(/\\/g, '/');
+        const defaultExcludes = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'];
+        let excludePatterns = input.excludePatterns || defaultExcludes;
+        // CLI data directories (.compass/, .claude/) should always be accessible —
+        // strip any exclude patterns that would block them when explicitly targeted
+        const normalizedDir = directory.replace(/\\/g, '/').toLowerCase();
+        const isCliDataDir = normalizedDir === '.compass' || normalizedDir.startsWith('.compass/') ||
+            normalizedDir === '.claude' || normalizedDir.startsWith('.claude/');
+        if (isCliDataDir) {
+            excludePatterns = excludePatterns.filter((p) => {
+                const lp = p.toLowerCase();
+                return !lp.includes('.compass') && !lp.includes('.claude');
+            });
+        }
+        const files = await glob(globPattern, {
+            nodir: true,
+            dot: true,
+            ignore: excludePatterns,
+        });
+        return {
+            directory,
+            pattern: input.pattern,
+            excludePatterns,
+            files: files.map((f) => path.relative(context.projectRoot, f)),
+            count: files.length,
+        };
+    }, {
+        actionType: ActionType.SEARCH,
+        requiresApproval: false,
+        category: 'file_operations',
+        tags: ['io', 'search', 'explore'],
+        displayName: 'Glob',
+    });
+    registry.registerTool('read_media_file', 'Reads an image or audio file and returns it as base64 data with MIME type. Use for processing media files.', {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path to the image or audio file to read',
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fs = await import('fs/promises');
+        const filePath = path.resolve(context.projectRoot, input.path);
+        const exists = await pathExists(filePath);
+        if (!exists) {
+            throw new Error(`File not found: ${input.path}`);
+        }
+        const ext = path.extname(filePath).toLowerCase();
+        // Map extensions to MIME types
+        const mimeTypes = {
+            // Images
+            '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg',
+            '.png': 'image/png',
+            '.gif': 'image/gif',
+            '.webp': 'image/webp',
+            '.bmp': 'image/bmp',
+            '.svg': 'image/svg+xml',
+            '.ico': 'image/x-icon',
+            '.tiff': 'image/tiff',
+            '.tif': 'image/tiff',
+            // Audio
+            '.mp3': 'audio/mpeg',
+            '.wav': 'audio/wav',
+            '.ogg': 'audio/ogg',
+            '.m4a': 'audio/mp4',
+            '.flac': 'audio/flac',
+            '.aac': 'audio/aac',
+            '.wma': 'audio/x-ms-wma',
+            '.webm': 'audio/webm',
+        };
+        const mimeType = mimeTypes[ext];
+        if (!mimeType) {
+            throw new Error(`Unsupported media file type: ${ext}. Supported: ${Object.keys(mimeTypes).join(', ')}`);
+        }
+        const buffer = await fs.readFile(filePath);
+        const base64 = buffer.toString('base64');
+        const stats = await fs.stat(filePath);
+        return {
+            path: input.path,
+            mimeType,
+            base64,
+            size: stats.size,
+            sizeHuman: formatBytes(stats.size),
+        };
+    }, {
+        actionType: ActionType.FILE_READ,
+        requiresApproval: false,
+        category: 'file_operations',
+        tags: ['io', 'read', 'media', 'image', 'audio'],
+        displayName: 'Read Media',
+    });
+    registry.registerTool('create_directory', 'Creates a new directory. Creates parent directories if needed. Succeeds silently if directory already exists.', {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path of the directory to create (relative or absolute)',
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fs = await import('fs/promises');
+        const dirPath = path.resolve(context.projectRoot, input.path);
+        await fs.mkdir(dirPath, { recursive: true });
+        return {
+            path: input.path,
+            success: true,
+            message: `Directory created: ${input.path}`,
+        };
+    }, {
+        actionType: ActionType.FILE_WRITE,
+        requiresApproval: true,
+        category: 'file_operations',
+        tags: ['io', 'write', 'directory', 'mkdir'],
+        displayName: 'Create Directory',
+    });
+    registry.registerTool('list_directory', 'Lists directory contents with [FILE] or [DIR] prefixes for each entry.', {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Directory path to list (relative or absolute)',
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fs = await import('fs/promises');
+        const dirPath = path.resolve(context.projectRoot, input.path);
+        const exists = await pathExists(dirPath);
+        if (!exists) {
+            throw new Error(`Directory not found: ${input.path}`);
+        }
+        const stats = await fs.stat(dirPath);
+        if (!stats.isDirectory()) {
+            throw new Error(`Path is not a directory: ${input.path}`);
+        }
+        const entries = await fs.readdir(dirPath, { withFileTypes: true });
+        const listing = entries.map((entry) => {
+            const prefix = entry.isDirectory() ? '[DIR]' : '[FILE]';
+            return `${prefix} ${entry.name}`;
+        });
+        return {
+            path: input.path,
+            entries: listing,
+            totalFiles: entries.filter((e) => e.isFile()).length,
+            totalDirectories: entries.filter((e) => e.isDirectory()).length,
+            total: entries.length,
+        };
+    }, {
+        actionType: ActionType.SEARCH,
+        requiresApproval: false,
+        category: 'file_operations',
+        tags: ['io', 'read', 'directory', 'ls'],
+        displayName: 'List',
+    });
+    registry.registerTool('list_directory_with_sizes', 'Lists directory contents with file sizes, sorted by name or size.', {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Directory path to list (relative or absolute)',
+            },
+            sortBy: {
+                type: 'string',
+                enum: ['name', 'size'],
+                description: 'Sort entries by name or size (default: name)',
+                default: 'name',
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fs = await import('fs/promises');
+        const dirPath = path.resolve(context.projectRoot, input.path);
+        const exists = await pathExists(dirPath);
+        if (!exists) {
+            throw new Error(`Directory not found: ${input.path}`);
+        }
+        const stats = await fs.stat(dirPath);
+        if (!stats.isDirectory()) {
+            throw new Error(`Path is not a directory: ${input.path}`);
+        }
+        const dirEntries = await fs.readdir(dirPath, { withFileTypes: true });
+        const entries = await Promise.all(dirEntries.map(async (entry) => {
+            const entryPath = path.join(dirPath, entry.name);
+            const entryStats = await fs.stat(entryPath);
+            return {
+                name: entry.name,
+                type: entry.isDirectory() ? 'directory' : 'file',
+                size: entryStats.size,
+                sizeHuman: formatBytes(entryStats.size),
+            };
+        }));
+        // Sort entries
+        if (input.sortBy === 'size') {
+            entries.sort((a, b) => b.size - a.size);
+        }
+        else {
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+        }
+        const totalSize = entries.reduce((sum, e) => sum + e.size, 0);
+        const fileCount = entries.filter((e) => e.type === 'file').length;
+        const dirCount = entries.filter((e) => e.type === 'directory').length;
+        const listing = entries.map((e) => {
+            const prefix = e.type === 'directory' ? '[DIR]' : '[FILE]';
+            const sizeStr = e.type === 'file' ? ` (${e.sizeHuman})` : '';
+            return `${prefix} ${e.name}${sizeStr}`;
+        });
+        return {
+            path: input.path,
+            sortBy: input.sortBy || 'name',
+            entries: listing,
+            details: entries,
+            summary: {
+                totalFiles: fileCount,
+                totalDirectories: dirCount,
+                totalEntries: entries.length,
+                totalSize,
+                totalSizeHuman: formatBytes(totalSize),
+            },
+        };
+    }, {
+        actionType: ActionType.SEARCH,
+        requiresApproval: false,
+        category: 'file_operations',
+        tags: ['io', 'read', 'directory', 'ls', 'size'],
+        displayName: 'List',
+    });
+    registry.registerTool('move_file', 'Moves or renames a file or directory. Fails if destination already exists.', {
+        type: 'object',
+        properties: {
+            source: {
+                type: 'string',
+                description: 'Source path (relative or absolute)',
+            },
+            destination: {
+                type: 'string',
+                description: 'Destination path (relative or absolute)',
+            },
+        },
+        required: ['source', 'destination'],
+    }, async (input, context) => {
+        const fs = await import('fs/promises');
+        const sourcePath = path.resolve(context.projectRoot, input.source);
+        const destPath = path.resolve(context.projectRoot, input.destination);
+        const sourceExists = await pathExists(sourcePath);
+        if (!sourceExists) {
+            throw new Error(`Source not found: ${input.source}`);
+        }
+        const destExists = await pathExists(destPath);
+        if (destExists) {
+            throw new Error(`Destination already exists: ${input.destination}`);
+        }
+        // Ensure destination directory exists
+        const destDir = path.dirname(destPath);
+        await fs.mkdir(destDir, { recursive: true });
+        await fs.rename(sourcePath, destPath);
+        return {
+            source: input.source,
+            destination: input.destination,
+            success: true,
+            message: `Moved ${input.source} to ${input.destination}`,
+        };
+    }, {
+        actionType: ActionType.FILE_WRITE,
+        requiresApproval: true,
+        category: 'file_operations',
+        tags: ['io', 'write', 'move', 'rename'],
+        displayName: 'Move',
+    });
+    registry.registerTool('directory_tree', 'Gets a recursive JSON tree structure of directory contents.', {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Starting directory path (relative or absolute)',
+            },
+            excludePatterns: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Glob patterns to exclude (e.g., ["node_modules", ".git"]). Defaults to node_modules, .git, dist, build.',
+            },
+            maxDepth: {
+                type: 'number',
+                description: 'Maximum depth to traverse (default: 10)',
+                default: 10,
+            },
+        },
+        required: ['path'],
+    }, async (input, context) => {
+        const fs = await import('fs/promises');
+        const dirPath = path.resolve(context.projectRoot, input.path);
+        const exists = await pathExists(dirPath);
+        if (!exists) {
+            throw new Error(`Directory not found: ${input.path}`);
+        }
+        const defaultExcludes = ['node_modules', '.git', 'dist', 'build'];
+        const excludePatterns = input.excludePatterns || defaultExcludes;
+        const maxDepth = input.maxDepth || 10;
+        // Simple glob matching for exclude patterns
+        const matchesPattern = (name, pattern) => {
+            // Handle exact match
+            if (pattern === name)
+                return true;
+            // Handle wildcard patterns like *.js or .*
+            if (pattern.includes('*')) {
+                const regexPattern = pattern
+                    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+                    .replace(/\*/g, '.*')
+                    .replace(/\?/g, '.');
+                return new RegExp(`^${regexPattern}$`).test(name);
+            }
+            return false;
+        };
+        const shouldExclude = (name) => {
+            return excludePatterns.some((pattern) => matchesPattern(name, pattern));
+        };
+        const buildTree = async (currentPath, depth) => {
+            if (depth > maxDepth) {
+                return [];
+            }
+            const entries = await fs.readdir(currentPath, { withFileTypes: true });
+            const nodes = [];
+            for (const entry of entries) {
+                if (shouldExclude(entry.name)) {
+                    continue;
+                }
+                const node = {
+                    name: entry.name,
+                    type: entry.isDirectory() ? 'directory' : 'file',
+                };
+                if (entry.isDirectory()) {
+                    const childPath = path.join(currentPath, entry.name);
+                    node.children = await buildTree(childPath, depth + 1);
+                }
+                nodes.push(node);
+            }
+            // Sort: directories first, then files, both alphabetically
+            nodes.sort((a, b) => {
+                if (a.type !== b.type) {
+                    return a.type === 'directory' ? -1 : 1;
+                }
+                return a.name.localeCompare(b.name);
+            });
+            return nodes;
+        };
+        const tree = await buildTree(dirPath, 1);
+        return {
+            path: input.path,
+            excludePatterns,
+            maxDepth,
+            tree,
+        };
+    }, {
+        actionType: ActionType.SEARCH,
+        requiresApproval: false,
+        category: 'file_operations',
+        tags: ['io', 'read', 'directory', 'tree', 'structure'],
+        displayName: 'Dir Tree',
+    });
+    // ============================================================
+    // EDIT FILE
+    // ============================================================
+    registry.registerTool('edit_file', `Edits a file by replacing specific strings with new content.
+
+When to use:
+- Making targeted changes to EXISTING files
+- Modifying specific functions, classes, or sections
+- Small to medium changes where you don't need to rewrite the whole file
+
+Use write_file instead for: new files or complete rewrites.
+
+Features: multiple simultaneous edits, dry run preview mode.
+
+CRITICAL — Rules for reliable edits:
+1. ALWAYS read the file first (read_file) before attempting any edit. Never edit a file you haven't read in the current conversation.
+2. Copy oldText EXACTLY from the read_file output — including whitespace, indentation, and line breaks. Do NOT retype or paraphrase from memory.
+3. Include enough surrounding context in oldText to make it unique (at least 3-5 lines). If the text appears multiple times, expand oldText until it is unambiguous.
+4. NEVER truncate or abbreviate oldText with "..." or comments. The full literal text must be provided.
+5. If an edit fails with "Text not found" or "Text is not unique", re-read the file and retry with the exact text from the fresh read. Do NOT guess or retry with the same text.`, {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path to the file to edit',
+            },
+            edits: {
+                type: 'array',
+                description: 'List of edit operations to perform',
+                items: {
+                    type: 'object',
+                    properties: {
+                        oldText: {
+                            type: 'string',
+                            description: 'The text to search for (can be substring)',
+                        },
+                        newText: {
+                            type: 'string',
+                            description: 'The text to replace with. MUST be different from oldText',
+                        },
+                    },
+                    required: ['oldText', 'newText'],
+                },
+            },
+            dryRun: {
+                type: 'boolean',
+                description: 'Preview changes without applying them (default: false)',
+                default: false,
+            },
+            description: {
+                type: 'string',
+                description: 'Description of what this edit does',
+            },
+        },
+        required: ['path', 'edits'],
+    }, async (input, context) => {
+        const fileService = getFileService();
+        const filePath = path.resolve(context.projectRoot, input.path);
+        const exists = await pathExists(filePath);
+        if (!exists) {
+            throw new Error(`File not found: ${input.path}`);
+        }
+        // Validate file integrity - check if file was modified externally since last read
+        try {
+            await validateFileIntegrity(filePath);
+        }
+        catch (error) {
+            if (error instanceof FileModifiedExternallyError) {
+                // Invalidate stale caches so next read_file hits disk and re-tracks
+                invalidateCachedFile(filePath);
+                untrackFile(filePath);
+                return error.toToolResponse();
+            }
+            throw error;
+        }
+        const content = await fileService.readFile(filePath);
+        if (content === null) {
+            throw new Error(`Could not read file: ${input.path}`);
+        }
+        // Track the file content hash for future integrity checks
+        trackFileHash(filePath, content);
+        const edits = input.edits;
+        if (!edits || edits.length === 0) {
+            throw new Error('No edits provided');
+        }
+        // Validate each edit has required properties with informative error messages
+        // Note: Error messages are designed to be clear that oldText/newText are PROPERTIES, not tools
+        for (let i = 0; i < edits.length; i++) {
+            const edit = edits[i];
+            if (typeof edit?.oldText !== 'string') {
+                throw new Error(`edit_file validation error: Item ${i + 1} in the "edits" array is missing a valid "oldText" string property. ` +
+                    `Each edit must be an object like: { "oldText": "text to find", "newText": "replacement" }. ` +
+                    `Received ${edit?.oldText === undefined ? 'undefined' : typeof edit?.oldText} instead of string.`);
+            }
+            if (typeof edit?.newText !== 'string') {
+                throw new Error(`edit_file validation error: Item ${i + 1} in the "edits" array is missing a valid "newText" string property. ` +
+                    `Each edit must be an object like: { "oldText": "text to find", "newText": "replacement" }. ` +
+                    `Received ${edit?.newText === undefined ? 'undefined' : typeof edit?.newText} instead of string.`);
+            }
+        }
+        // Track edit results for reporting
+        const editResults = [];
+        let workingContent = content;
+        for (const edit of edits) {
+            try {
+                // Use the chain of replacer strategies to find and replace the text
+                const result = replaceWithStrategies(workingContent, edit.oldText, edit.newText, false // Don't replace all, handle uniqueness per edit
+                );
+                // Find line number of the matched text for reporting
+                let lineNumber;
+                const matchIndex = workingContent.indexOf(result.matchedText);
+                if (matchIndex !== -1) {
+                    // Count newlines before the match to get line number
+                    const textBeforeMatch = workingContent.substring(0, matchIndex);
+                    lineNumber = (textBeforeMatch.match(/\n/g) || []).length + 1;
+                }
+                editResults.push({
+                    oldText: edit.oldText,
+                    newText: edit.newText,
+                    actualOldText: result.matchedText,
+                    lineNumber,
+                    strategy: result.strategy,
+                });
+                // Update working content with the result
+                workingContent = result.content;
+            }
+            catch (error) {
+                // Provide helpful error with suggestions when text is not found
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (errorMessage.includes('not found')) {
+                    const suggestions = findSimilarText(workingContent, edit.oldText);
+                    let errorMsg = `Text not found in file: "${edit.oldText.slice(0, 80)}${edit.oldText.length > 80 ? '...' : ''}"`;
+                    if (suggestions.length > 0) {
+                        errorMsg += `\n\nDid you mean one of these? (similar content found):`;
+                        for (const suggestion of suggestions) {
+                            errorMsg += `\n  Line ${suggestion.lineNumber}: "${suggestion.preview}"`;
+                        }
+                    }
+                    // Add hint about potential whitespace issues
+                    if (edit.oldText.includes('\r') || edit.oldText.match(/[ \t]$/m)) {
+                        errorMsg += `\n\nNote: The search text may have trailing whitespace or CRLF line endings that don't match the file.`;
+                    }
+                    throw new Error(errorMsg);
+                }
+                else if (errorMessage.includes('multiple matches')) {
+                    throw new Error(`Text is not unique: "${edit.oldText.slice(0, 50)}${edit.oldText.length > 50 ? '...' : ''}". Please provide more context to make it unique.`);
+                }
+                else if (errorMessage.includes('identical')) {
+                    // oldText and newText are the same - no change needed
+                    throw new Error(`No change needed: oldText and newText are identical. If you intended to make a change, check that newText differs from oldText. Preview of text: "${edit.oldText.slice(0, 80)}${edit.oldText.length > 80 ? '...' : ''}"`);
+                }
+                throw error;
+            }
+        }
+        // If dry run, return preview without applying using compact format
+        if (input.dryRun) {
+            const compactPreview = generateCompactEditResponse(content, workingContent, input.path, 2 // Context lines
+            );
+            return {
+                path: input.path,
+                dryRun: true,
+                success: true,
+                editsCount: edits.length,
+                // Echo edits (truncated) - helps LLM learn expected input format
+                editsApplied: edits.map((e) => ({
+                    oldText: e.oldText.slice(0, 60) + (e.oldText.length > 60 ? '...' : ''),
+                    newText: e.newText.slice(0, 60) + (e.newText.length > 60 ? '...' : ''),
+                })),
+                context: compactPreview.context,
+                changes: compactPreview.changes,
+                additions: compactPreview.additions,
+                deletions: compactPreview.deletions,
+                message: 'Dry run complete. No changes applied.',
+            };
+        }
+        // Apply the edits
+        const isCompassPath = filePath.startsWith(getGlobalCompassDir())
+            || filePath.startsWith(getProjectCompassDir(context.projectRoot));
+        const result = await fileService.writeFile(filePath, workingContent, {
+            description: input.description || `Edit file: ${input.path} (${edits.length} edit${edits.length > 1 ? 's' : ''})`,
+            requireApproval: !isCompassPath,
+            createBackup: !isCompassPath,
+        });
+        // Update the tracked hash after successful write
+        if (result.success) {
+            updateFileHash(filePath, workingContent);
+            // Invalidate turn cache so next read gets fresh content
+            invalidateCachedFile(filePath);
+        }
+        // Generate compact edit response for token efficiency
+        // This reduces response size from ~8K to ~500 chars on average
+        const compactResponse = generateCompactEditResponse(content, workingContent, input.path, 2 // Context lines before/after changes
+        );
+        return {
+            path: input.path,
+            dryRun: false,
+            success: result.success,
+            operation: 'edit',
+            editsCount: edits.length,
+            backupCreated: !!result.backup,
+            error: result.error,
+            // Echo applied edits (truncated) - helps LLM learn expected input format
+            editsApplied: edits.map((e) => ({
+                oldText: e.oldText.slice(0, 60) + (e.oldText.length > 60 ? '...' : ''),
+                newText: e.newText.slice(0, 60) + (e.newText.length > 60 ? '...' : ''),
+            })),
+            // Compact diff format for token efficiency
+            context: compactResponse.context,
+            changes: compactResponse.changes,
+            additions: compactResponse.additions,
+            deletions: compactResponse.deletions,
+        };
+    }, {
+        actionType: ActionType.FILE_WRITE,
+        requiresApproval: true,
+        category: 'file_operations',
+        tags: ['io', 'write', 'edit', 'modify'],
+        displayName: 'Edit',
+    });
+}
+//# sourceMappingURL=file-tools.js.map