@compilr-dev/agents 0.0.1

package/dist/tools/builtin/grep.js

@@ -0,0 +1,363 @@
+/**
+ * Grep Tool - Search for patterns in files using regex
+ */
+import { readFile } from 'node:fs/promises';
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { isNodeError, isExtensionAllowed } from './utils.js';
+/**
+ * Grep tool definition
+ */
+export const grepTool = defineTool({
+    name: 'grep',
+    description: 'Search for patterns in files using regular expressions. ' +
+        'Can search a single file or recursively through directories. ' +
+        'Returns matching lines with optional context.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            pattern: {
+                type: 'string',
+                description: 'Regular expression pattern to search for',
+            },
+            path: {
+                type: 'string',
+                description: 'Path to file or directory to search in',
+            },
+            ignoreCase: {
+                type: 'boolean',
+                description: 'Case insensitive search (default: false)',
+            },
+            lineNumbers: {
+                type: 'boolean',
+                description: 'Include line numbers in output (default: true)',
+            },
+            before: {
+                type: 'number',
+                description: 'Number of context lines before match',
+            },
+            after: {
+                type: 'number',
+                description: 'Number of context lines after match',
+            },
+            filesOnly: {
+                type: 'boolean',
+                description: 'Only return filenames with matches',
+            },
+            includeHidden: {
+                type: 'boolean',
+                description: 'Include hidden files/directories',
+            },
+            extensions: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'File extensions to include (e.g., [".ts", ".js"])',
+            },
+            maxMatches: {
+                type: 'number',
+                description: 'Maximum number of matches to return (default: 100)',
+            },
+            recursive: {
+                type: 'boolean',
+                description: 'Search recursively in directories (default: true)',
+            },
+        },
+        required: ['pattern', 'path'],
+    },
+    execute: executeGrep,
+});
+/**
+ * Test if a regex pattern is potentially dangerous (ReDoS)
+ * This is a heuristic check - not comprehensive but catches common cases
+ */
+function isPotentiallyDangerousRegex(pattern) {
+    // Check for nested quantifiers which are common ReDoS patterns
+    // e.g., (a+)+, (a*)*,  (a+)*,  .*.*
+    const dangerousPatterns = [
+        /\([^)]*[+*][^)]*\)[+*]/, // Nested quantifiers like (a+)+
+        /\([^)]*\|[^)]*\)[+*]/, // Alternation with quantifier like (a|b)+
+        /\.[*+].*\.[*+]/, // Multiple .* or .+ patterns
+    ];
+    for (const dangerous of dangerousPatterns) {
+        if (dangerous.test(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Safely test a regex against a string with input length protection.
+ * Note: True timeout-based protection would require worker threads.
+ */
+function safeRegexTest(regex, text) {
+    // For very long lines, truncate to prevent ReDoS on long input
+    const maxLineLength = 10000;
+    const truncatedText = text.length > maxLineLength ? text.substring(0, maxLineLength) : text;
+    // Reset lastIndex before testing
+    regex.lastIndex = 0;
+    return regex.test(truncatedText);
+}
+/**
+ * Execute the grep tool
+ */
+async function executeGrep(input) {
+    try {
+        const { pattern, path, ignoreCase = false, lineNumbers = true, before = 0, after = 0, filesOnly = false, includeHidden = false, extensions, maxMatches = 100, recursive = true, } = input;
+        // Check for potentially dangerous regex patterns
+        if (isPotentiallyDangerousRegex(pattern)) {
+            return createErrorResult(`Potentially dangerous regex pattern detected (ReDoS risk). ` +
+                `Avoid nested quantifiers like (a+)+ or multiple .* patterns.`);
+        }
+        // Compile regex
+        let regex;
+        try {
+            regex = new RegExp(pattern, ignoreCase ? 'gi' : 'g');
+        }
+        catch {
+            return createErrorResult(`Invalid regular expression: ${pattern}`);
+        }
+        // Determine if path is file or directory
+        const stats = await stat(path);
+        const files = [];
+        if (stats.isFile()) {
+            files.push(path);
+        }
+        else if (stats.isDirectory()) {
+            await collectFiles(path, files, {
+                recursive,
+                includeHidden,
+                extensions,
+            });
+        }
+        else {
+            return createErrorResult(`Path is neither a file nor directory: ${path}`);
+        }
+        // Search files
+        const matches = [];
+        const filesWithMatches = new Set();
+        let totalMatches = 0;
+        for (const file of files) {
+            if (totalMatches >= maxMatches)
+                break;
+            const fileMatches = await searchFile(file, regex, {
+                before,
+                after,
+                maxMatches: maxMatches - totalMatches,
+            });
+            if (fileMatches.length > 0) {
+                filesWithMatches.add(file);
+                if (!filesOnly) {
+                    matches.push(...fileMatches);
+                }
+                totalMatches += fileMatches.length;
+            }
+        }
+        // Format output
+        if (filesOnly) {
+            const relativePaths = Array.from(filesWithMatches).map((f) => f.startsWith(path) ? relative(path, f) || f : f);
+            return createSuccessResult({
+                files: relativePaths,
+                count: relativePaths.length,
+            });
+        }
+        // Format matches with line numbers and context
+        const output = formatMatches(matches, { lineNumbers, path });
+        return createSuccessResult({
+            matches: output,
+            count: matches.length,
+            filesSearched: files.length,
+            truncated: totalMatches >= maxMatches,
+        });
+    }
+    catch (error) {
+        if (isNodeError(error)) {
+            switch (error.code) {
+                case 'ENOENT':
+                    return createErrorResult(`Path not found: ${input.path}`);
+                case 'EACCES':
+                    return createErrorResult(`Permission denied: ${input.path}`);
+                default:
+                    return createErrorResult(`Grep failed: ${error.message}`);
+            }
+        }
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Recursively collect files from a directory
+ */
+async function collectFiles(dir, files, options) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Skip hidden files unless included
+        if (!options.includeHidden && entry.name.startsWith('.')) {
+            continue;
+        }
+        const fullPath = join(dir, entry.name);
+        if (entry.isFile()) {
+            // Check extension filter
+            if (options.extensions && options.extensions.length > 0) {
+                if (!isExtensionAllowed(entry.name, options.extensions)) {
+                    continue;
+                }
+            }
+            files.push(fullPath);
+        }
+        else if (entry.isDirectory() && options.recursive) {
+            await collectFiles(fullPath, files, options);
+        }
+    }
+}
+/**
+ * Search a single file for pattern matches
+ */
+async function searchFile(filePath, regex, options) {
+    const matches = [];
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        // Skip likely binary files (files with null bytes in first 8KB)
+        if (content.length > 0 && content.slice(0, 8000).includes('\0')) {
+            return matches;
+        }
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (matches.length >= options.maxMatches)
+                break;
+            // Use safe regex test with line length protection
+            if (safeRegexTest(regex, lines[i])) {
+                const match = {
+                    file: filePath,
+                    line: i + 1, // 1-indexed
+                    content: lines[i],
+                };
+                // Add context if requested
+                if (options.before > 0 || options.after > 0) {
+                    match.context = {
+                        before: lines.slice(Math.max(0, i - options.before), i),
+                        after: lines.slice(i + 1, i + 1 + options.after),
+                    };
+                }
+                matches.push(match);
+            }
+        }
+    }
+    catch {
+        // Skip files that can't be read (binary files, permission issues, etc.)
+    }
+    return matches;
+}
+/**
+ * Format matches for output
+ */
+function formatMatches(matches, options) {
+    return matches.map((match) => {
+        const relativePath = match.file.startsWith(options.path)
+            ? relative(options.path, match.file) || match.file
+            : match.file;
+        let output = '';
+        // Add context before
+        if (match.context?.before) {
+            for (let i = 0; i < match.context.before.length; i++) {
+                const lineNum = match.line - match.context.before.length + i;
+                output += options.lineNumbers
+                    ? `${relativePath}:${String(lineNum)}-${match.context.before[i]}\n`
+                    : `${relativePath}-${match.context.before[i]}\n`;
+            }
+        }
+        // Add the matching line
+        output += options.lineNumbers
+            ? `${relativePath}:${String(match.line)}:${match.content}`
+            : `${relativePath}:${match.content}`;
+        // Add context after
+        if (match.context?.after) {
+            for (let i = 0; i < match.context.after.length; i++) {
+                const lineNum = match.line + 1 + i;
+                output += options.lineNumbers
+                    ? `\n${relativePath}:${String(lineNum)}-${match.context.after[i]}`
+                    : `\n${relativePath}-${match.context.after[i]}`;
+            }
+        }
+        return output;
+    });
+}
+/**
+ * Factory function to create a grep tool with custom options
+ *
+ * TODO: Future enhancements could include:
+ * - maxFileSize: Skip files larger than specified size
+ * - excludeDirs: Exclude directories by name (e.g., node_modules, .git)
+ */
+export function createGrepTool(options) {
+    return defineTool({
+        name: 'grep',
+        description: 'Search for patterns in files using regular expressions. ' +
+            'Can search a single file or recursively through directories. ' +
+            'Returns matching lines with optional context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern: {
+                    type: 'string',
+                    description: 'Regular expression pattern to search for',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Path to file or directory to search in',
+                },
+                ignoreCase: {
+                    type: 'boolean',
+                    description: 'Case insensitive search (default: false)',
+                },
+                lineNumbers: {
+                    type: 'boolean',
+                    description: 'Include line numbers in output (default: true)',
+                },
+                before: {
+                    type: 'number',
+                    description: 'Number of context lines before match',
+                },
+                after: {
+                    type: 'number',
+                    description: 'Number of context lines after match',
+                },
+                filesOnly: {
+                    type: 'boolean',
+                    description: 'Only return filenames with matches',
+                },
+                includeHidden: {
+                    type: 'boolean',
+                    description: 'Include hidden files/directories',
+                },
+                extensions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'File extensions to include (e.g., [".ts", ".js"])',
+                },
+                maxMatches: {
+                    type: 'number',
+                    description: 'Maximum number of matches to return (default: 100)',
+                },
+                recursive: {
+                    type: 'boolean',
+                    description: 'Search recursively in directories (default: true)',
+                },
+            },
+            required: ['pattern', 'path'],
+        },
+        execute: async (input) => {
+            let searchPath = input.path;
+            // Resolve relative paths
+            if (options?.baseDir && !searchPath.startsWith('/')) {
+                searchPath = join(options.baseDir, searchPath);
+            }
+            // Apply default extensions if none specified
+            const extensions = input.extensions ?? options?.defaultExtensions;
+            return executeGrep({
+                ...input,
+                path: searchPath,
+                extensions,
+            });
+        },
+    });
+}

package/dist/tools/builtin/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Built-in tools for common operations
+ */
+export { readFileTool, createReadFileTool } from './read-file.js';
+export type { ReadFileInput } from './read-file.js';
+export { writeFileTool, createWriteFileTool } from './write-file.js';
+export type { WriteFileInput } from './write-file.js';
+export { bashTool, createBashTool, execStream, detectFifoUsage } from './bash.js';
+export type { BashInput, BashResult, FifoDetectionResult } from './bash.js';
+export { bashOutputTool, createBashOutputTool } from './bash-output.js';
+export type { BashOutputInput, BashOutputResult } from './bash-output.js';
+export { killShellTool, createKillShellTool } from './kill-shell.js';
+export type { KillShellInput, KillShellResult } from './kill-shell.js';
+export { ShellManager, getDefaultShellManager, setDefaultShellManager } from './shell-manager.js';
+export type { ShellStatus, BackgroundShell, ShellOutput, ShellManagerOptions, } from './shell-manager.js';
+export { grepTool, createGrepTool } from './grep.js';
+export type { GrepInput } from './grep.js';
+export { globTool, createGlobTool } from './glob.js';
+export type { GlobInput } from './glob.js';
+export { editTool, createEditTool } from './edit.js';
+export type { EditInput } from './edit.js';
+export { todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, } from './todo.js';
+export type { TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, } from './todo.js';
+export { createTaskTool, defaultAgentTypes } from './task.js';
+export type { TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, } from './task.js';
+export { webFetchTool, createWebFetchTool } from './web-fetch.js';
+export type { WebFetchInput, WebFetchResult, WebFetchOptions } from './web-fetch.js';
+export declare const builtinTools: {
+    readonly readFile: import("../types.js").Tool<import("./read-file.js").ReadFileInput>;
+    readonly writeFile: import("../types.js").Tool<import("./write-file.js").WriteFileInput>;
+    readonly bash: import("../types.js").Tool<import("./bash.js").BashInput>;
+    readonly bashOutput: import("../types.js").Tool<import("./bash-output.js").BashOutputInput>;
+    readonly killShell: import("../types.js").Tool<import("./kill-shell.js").KillShellInput>;
+    readonly grep: import("../types.js").Tool<import("./grep.js").GrepInput>;
+    readonly glob: import("../types.js").Tool<import("./glob.js").GlobInput>;
+    readonly edit: import("../types.js").Tool<import("./edit.js").EditInput>;
+    readonly todoWrite: import("../types.js").Tool<import("./todo.js").TodoWriteInput>;
+    readonly todoRead: import("../types.js").Tool<import("./todo.js").TodoReadInput>;
+    readonly webFetch: import("../types.js").Tool<import("./web-fetch.js").WebFetchInput>;
+};
+/**
+ * Array of all built-in tools
+ */
+export declare const allBuiltinTools: readonly [import("../types.js").Tool<import("./read-file.js").ReadFileInput>, import("../types.js").Tool<import("./write-file.js").WriteFileInput>, import("../types.js").Tool<import("./bash.js").BashInput>, import("../types.js").Tool<import("./bash-output.js").BashOutputInput>, import("../types.js").Tool<import("./kill-shell.js").KillShellInput>, import("../types.js").Tool<import("./grep.js").GrepInput>, import("../types.js").Tool<import("./glob.js").GlobInput>, import("../types.js").Tool<import("./edit.js").EditInput>, import("../types.js").Tool<import("./todo.js").TodoWriteInput>, import("../types.js").Tool<import("./todo.js").TodoReadInput>, import("../types.js").Tool<import("./web-fetch.js").WebFetchInput>];

package/dist/tools/builtin/index.js

@@ -0,0 +1,69 @@
+/**
+ * Built-in tools for common operations
+ */
+// Read file tool
+export { readFileTool, createReadFileTool } from './read-file.js';
+// Write file tool
+export { writeFileTool, createWriteFileTool } from './write-file.js';
+// Bash tool
+export { bashTool, createBashTool, execStream, detectFifoUsage } from './bash.js';
+// Bash output tool (background shell monitoring)
+export { bashOutputTool, createBashOutputTool } from './bash-output.js';
+// Kill shell tool
+export { killShellTool, createKillShellTool } from './kill-shell.js';
+// Shell manager (for background processes)
+export { ShellManager, getDefaultShellManager, setDefaultShellManager } from './shell-manager.js';
+// Grep tool
+export { grepTool, createGrepTool } from './grep.js';
+// Glob tool
+export { globTool, createGlobTool } from './glob.js';
+// Edit tool
+export { editTool, createEditTool } from './edit.js';
+// Todo tools
+export { todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, } from './todo.js';
+// Task tool (sub-agent spawning)
+export { createTaskTool, defaultAgentTypes } from './task.js';
+// WebFetch tool
+export { webFetchTool, createWebFetchTool } from './web-fetch.js';
+/**
+ * Collection of all built-in tools for easy registration
+ */
+import { readFileTool } from './read-file.js';
+import { writeFileTool } from './write-file.js';
+import { bashTool } from './bash.js';
+import { bashOutputTool } from './bash-output.js';
+import { killShellTool } from './kill-shell.js';
+import { grepTool } from './grep.js';
+import { globTool } from './glob.js';
+import { editTool } from './edit.js';
+import { todoWriteTool, todoReadTool } from './todo.js';
+import { webFetchTool } from './web-fetch.js';
+export const builtinTools = {
+    readFile: readFileTool,
+    writeFile: writeFileTool,
+    bash: bashTool,
+    bashOutput: bashOutputTool,
+    killShell: killShellTool,
+    grep: grepTool,
+    glob: globTool,
+    edit: editTool,
+    todoWrite: todoWriteTool,
+    todoRead: todoReadTool,
+    webFetch: webFetchTool,
+};
+/**
+ * Array of all built-in tools
+ */
+export const allBuiltinTools = [
+    readFileTool,
+    writeFileTool,
+    bashTool,
+    bashOutputTool,
+    killShellTool,
+    grepTool,
+    globTool,
+    editTool,
+    todoWriteTool,
+    todoReadTool,
+    webFetchTool,
+];

package/dist/tools/builtin/kill-shell.d.ts

@@ -0,0 +1,44 @@
+/**
+ * KillShell Tool - Terminate background shell processes
+ */
+import type { Tool } from '../types.js';
+import { type ShellManager } from './shell-manager.js';
+/**
+ * Input parameters for killShell tool
+ */
+export interface KillShellInput {
+    /**
+     * The ID of the background shell to kill
+     */
+    shell_id: string;
+}
+/**
+ * Result of killShell tool
+ */
+export interface KillShellResult {
+    /**
+     * Whether the shell was successfully killed
+     */
+    success: boolean;
+    /**
+     * Shell ID
+     */
+    id: string;
+    /**
+     * Message describing the result
+     */
+    message: string;
+}
+/**
+ * KillShell tool definition
+ */
+export declare const killShellTool: Tool<KillShellInput>;
+/**
+ * Factory function to create a killShell tool with custom shell manager
+ */
+export declare function createKillShellTool(options?: {
+    /**
+     * Custom shell manager to use
+     */
+    shellManager?: ShellManager;
+}): Tool<KillShellInput>;

package/dist/tools/builtin/kill-shell.js

@@ -0,0 +1,80 @@
+/**
+ * KillShell Tool - Terminate background shell processes
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { getDefaultShellManager } from './shell-manager.js';
+/**
+ * KillShell tool definition
+ */
+export const killShellTool = defineTool({
+    name: 'kill_shell',
+    description: 'Kill a running background bash shell by its ID. ' +
+        'Use this to terminate long-running commands that are no longer needed.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            shell_id: {
+                type: 'string',
+                description: 'The ID of the background shell to kill',
+            },
+        },
+        required: ['shell_id'],
+    },
+    execute: (input) => {
+        const manager = getDefaultShellManager();
+        return Promise.resolve(executeKillShell(input, manager));
+    },
+});
+/**
+ * Execute the killShell tool
+ */
+function executeKillShell(input, manager) {
+    const { shell_id } = input;
+    // Check if shell exists
+    const shell = manager.get(shell_id);
+    if (!shell) {
+        return createErrorResult(`Shell '${shell_id}' not found. It may have been cleaned up or never existed.`);
+    }
+    // Check if already completed
+    if (shell.status !== 'running') {
+        return createSuccessResult({
+            success: false,
+            id: shell_id,
+            message: `Shell '${shell_id}' is already ${shell.status} (exit code: ${String(shell.exitCode ?? 'N/A')})`,
+        });
+    }
+    // Kill the shell
+    const killed = manager.kill(shell_id);
+    if (killed) {
+        return createSuccessResult({
+            success: true,
+            id: shell_id,
+            message: `Shell '${shell_id}' has been terminated`,
+        });
+    }
+    else {
+        return createErrorResult(`Failed to kill shell '${shell_id}'`);
+    }
+}
+/**
+ * Factory function to create a killShell tool with custom shell manager
+ */
+export function createKillShellTool(options) {
+    const manager = options?.shellManager ?? getDefaultShellManager();
+    return defineTool({
+        name: 'kill_shell',
+        description: 'Kill a running background bash shell by its ID. ' +
+            'Use this to terminate long-running commands that are no longer needed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                shell_id: {
+                    type: 'string',
+                    description: 'The ID of the background shell to kill',
+                },
+            },
+            required: ['shell_id'],
+        },
+        execute: (input) => Promise.resolve(executeKillShell(input, manager)),
+    });
+}

package/dist/tools/builtin/read-file.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Read File Tool - Read contents of a file from the filesystem
+ */
+import type { Tool } from '../types.js';
+/**
+ * Input parameters for read_file tool
+ */
+export interface ReadFileInput {
+    /**
+     * Path to the file to read
+     */
+    path: string;
+    /**
+     * Encoding to use (default: utf-8)
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Maximum number of lines to read (default: all)
+     */
+    maxLines?: number;
+    /**
+     * Line offset to start reading from (1-indexed, default: 1)
+     */
+    startLine?: number;
+}
+/**
+ * Read file tool definition
+ */
+export declare const readFileTool: Tool<ReadFileInput>;
+/**
+ * Factory function to create a read_file tool with custom options
+ */
+export declare function createReadFileTool(options?: {
+    /**
+     * Base directory to resolve relative paths against
+     */
+    baseDir?: string;
+    /**
+     * List of allowed file extensions (e.g., ['.ts', '.js', '.json'])
+     */
+    allowedExtensions?: string[];
+    /**
+     * Maximum file size to read in bytes (default: 10MB).
+     * Files larger than this are rejected entirely.
+     */
+    maxFileSize?: number;
+    /**
+     * Maximum content size returned to agent in bytes (default: 100KB).
+     * Content larger than this is truncated.
+     */
+    maxContentSize?: number;
+    /**
+     * Whether to truncate large content (true) or reject (false).
+     * Default: true
+     */
+    truncateIfLarge?: boolean;
+}): Tool<ReadFileInput>;