@compilr-dev/agents 0.0.1

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

@@ -0,0 +1,150 @@
+/**
+ * Bash Tool - Execute shell commands
+ */
+import type { Tool } from '../types.js';
+import { type ShellManager } from './shell-manager.js';
+/**
+ * Input parameters for bash tool
+ */
+export interface BashInput {
+    /**
+     * Command to execute
+     */
+    command: string;
+    /**
+     * Working directory for the command
+     */
+    cwd?: string;
+    /**
+     * Timeout in milliseconds (default: 60000 = 1 minute)
+     * Ignored when run_in_background is true
+     */
+    timeout?: number;
+    /**
+     * Environment variables to set
+     */
+    env?: Record<string, string>;
+    /**
+     * Run command in background and return immediately with a shell ID.
+     * Use bash_output tool to retrieve output later.
+     */
+    run_in_background?: boolean;
+    /**
+     * Description of what this command does (for display purposes)
+     */
+    description?: string;
+}
+/**
+ * Result of bash command execution
+ */
+export interface BashResult {
+    /**
+     * Standard output
+     */
+    stdout: string;
+    /**
+     * Standard error
+     */
+    stderr: string;
+    /**
+     * Exit code (0 = success)
+     */
+    exitCode: number;
+}
+/**
+ * FIFO detection result
+ */
+export interface FifoDetectionResult {
+    /**
+     * Whether potential FIFO/pipe usage was detected
+     */
+    detected: boolean;
+    /**
+     * Patterns that matched
+     */
+    patterns: string[];
+    /**
+     * Warning message to display
+     */
+    warning?: string;
+}
+/**
+ * Detect potential FIFO/named pipe usage in a command
+ * Commands that read from FIFOs can hang indefinitely if no writer is available
+ */
+export declare function detectFifoUsage(command: string): FifoDetectionResult;
+/**
+ * Bash tool definition
+ */
+export declare const bashTool: Tool<BashInput>;
+/**
+ * Factory function to create a bash tool with custom options
+ *
+ * SECURITY NOTE: The blockedCommands and allowedCommands options provide
+ * ADVISORY filtering only. They are NOT a security boundary. Shell commands
+ * can be obfuscated in many ways (quotes, escape sequences, command substitution,
+ * environment variables, etc.) that bypass simple string matching.
+ *
+ * For actual security isolation, use:
+ * - Container/sandbox environments
+ * - seccomp/AppArmor profiles
+ * - Dedicated restricted shells (rbash)
+ * - User namespace isolation
+ */
+export declare function createBashTool(options?: {
+    /**
+     * Default working directory
+     */
+    cwd?: string;
+    /**
+     * Default timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Maximum output size returned to agent (default: 50KB).
+     * Larger outputs are truncated to prevent memory bloat.
+     */
+    maxOutputSize?: number;
+    /**
+     * Commands or patterns that are not allowed (ADVISORY ONLY - see security note)
+     */
+    blockedCommands?: string[];
+    /**
+     * If true, only allow commands in allowedCommands list (ADVISORY ONLY)
+     */
+    restrictToAllowed?: boolean;
+    /**
+     * List of allowed commands - must match exactly (only used if restrictToAllowed is true)
+     */
+    allowedCommands?: string[];
+    /**
+     * Shell to use (default: /bin/bash)
+     */
+    shell?: string;
+    /**
+     * Custom shell manager for background processes
+     */
+    shellManager?: ShellManager;
+    /**
+     * How to handle FIFO/named pipe usage detection
+     * - 'warn': Add warning to result (default)
+     * - 'block': Return error if FIFO usage detected
+     * - 'allow': Ignore FIFO detection
+     */
+    fifoMode?: 'warn' | 'block' | 'allow';
+}): Tool<BashInput>;
+/**
+ * Execute a command with streaming output (for long-running commands)
+ *
+ * Note: This is a lower-level function for cases where you need
+ * to stream output as it arrives.
+ */
+export declare function execStream(command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    shell?: string;
+}): {
+    stdout: AsyncIterable<string>;
+    stderr: AsyncIterable<string>;
+    promise: Promise<number>;
+};

package/dist/tools/builtin/bash.js

@@ -0,0 +1,354 @@
+/**
+ * Bash Tool - Execute shell commands
+ */
+import { exec, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { getDefaultShellManager } from './shell-manager.js';
+const execAsync = promisify(exec);
+/**
+ * Default timeout for commands (1 minute)
+ */
+const DEFAULT_TIMEOUT = 60000;
+/**
+ * Maximum buffer size for exec (1MB)
+ */
+const MAX_BUFFER_SIZE = 1024 * 1024;
+/**
+ * Default maximum output size returned to agent (50KB)
+ * Larger outputs are truncated to prevent memory issues in long sessions
+ */
+const DEFAULT_MAX_OUTPUT_SIZE = 50 * 1024;
+/**
+ * Patterns that indicate potential FIFO/named pipe usage
+ * These can cause hangs if the pipe has no writer
+ */
+const FIFO_PATTERNS = [
+    /\bcat\s+[^\s|]*\s*<\s*\(/, // Process substitution: cat <(...)
+    /mkfifo\b/, // Creating named pipes
+    /\/dev\/fd\/\d+/, // File descriptor paths
+    /\|\s*tee\s+.*\s*>\s*\/dev\/null/, // tee to /dev/null pattern
+    /\bread\s+.*<\s*/, // Reading from redirection that could be a pipe
+    /<\s*\/proc\//, // Reading from /proc (can block)
+    /\bwatch\b/, // watch command (runs indefinitely)
+    /\btail\s+-f\b/, // tail -f (follows file indefinitely)
+];
+/**
+ * Detect potential FIFO/named pipe usage in a command
+ * Commands that read from FIFOs can hang indefinitely if no writer is available
+ */
+export function detectFifoUsage(command) {
+    const matchedPatterns = [];
+    for (const pattern of FIFO_PATTERNS) {
+        if (pattern.test(command)) {
+            matchedPatterns.push(pattern.source);
+        }
+    }
+    if (matchedPatterns.length === 0) {
+        return { detected: false, patterns: [] };
+    }
+    return {
+        detected: true,
+        patterns: matchedPatterns,
+        warning: 'This command may read from FIFOs/named pipes, which can hang indefinitely ' +
+            'if no writer is available. Consider using run_in_background=true or adding a timeout.',
+    };
+}
+/**
+ * Truncate output to prevent memory bloat in agent context.
+ * Returns truncated string with indicator if truncation occurred.
+ */
+function truncateOutput(output, maxSize) {
+    if (output.length <= maxSize) {
+        return { content: output, truncated: false };
+    }
+    // Keep first and last portions for context
+    const headSize = Math.floor(maxSize * 0.7);
+    const tailSize = Math.floor(maxSize * 0.2);
+    const head = output.slice(0, headSize);
+    const tail = output.slice(-tailSize);
+    const omitted = output.length - headSize - tailSize;
+    return {
+        content: `${head}\n\n... [${String(omitted)} characters truncated] ...\n\n${tail}`,
+        truncated: true,
+    };
+}
+/**
+ * Bash tool definition
+ */
+export const bashTool = defineTool({
+    name: 'bash',
+    description: 'Execute a shell command and return its output. ' +
+        'Commands run in bash shell. Use for system operations, git commands, npm, etc. ' +
+        'Set run_in_background=true for long-running commands, then use bash_output to monitor.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            command: {
+                type: 'string',
+                description: 'The shell command to execute',
+            },
+            cwd: {
+                type: 'string',
+                description: 'Working directory for the command',
+            },
+            timeout: {
+                type: 'number',
+                description: 'Timeout in milliseconds (default: 60000). Ignored for background commands.',
+            },
+            env: {
+                type: 'object',
+                description: 'Additional environment variables',
+            },
+            run_in_background: {
+                type: 'boolean',
+                description: 'Run command in background and return shell ID. Use bash_output to get results.',
+            },
+            description: {
+                type: 'string',
+                description: 'Brief description of what this command does',
+            },
+        },
+        required: ['command'],
+    },
+    execute: executeBash,
+});
+/**
+ * Execute the bash tool
+ */
+async function executeBash(input) {
+    const { command, cwd, timeout = DEFAULT_TIMEOUT, env, run_in_background } = input;
+    // Detect FIFO usage and add warning
+    const fifoCheck = detectFifoUsage(command);
+    // Handle background execution
+    if (run_in_background) {
+        return executeInBackground(command, { cwd, env });
+    }
+    try {
+        const result = await execAsync(command, {
+            cwd,
+            timeout,
+            maxBuffer: MAX_BUFFER_SIZE,
+            shell: '/bin/bash',
+            env: env ? { ...process.env, ...env } : undefined,
+        });
+        // Truncate output to prevent memory bloat in agent context
+        const stdout = truncateOutput(result.stdout, DEFAULT_MAX_OUTPUT_SIZE);
+        const stderr = truncateOutput(result.stderr, DEFAULT_MAX_OUTPUT_SIZE);
+        return createSuccessResult({
+            stdout: stdout.content,
+            stderr: stderr.content,
+            exitCode: 0,
+            truncated: stdout.truncated || stderr.truncated,
+            ...(fifoCheck.detected && { fifoWarning: fifoCheck.warning }),
+        });
+    }
+    catch (error) {
+        if (isExecError(error)) {
+            // Command failed but executed
+            if (error.killed) {
+                return createErrorResult(`Command timed out after ${String(timeout)}ms`);
+            }
+            // Truncate output even on error
+            const stdout = truncateOutput(error.stdout ?? '', DEFAULT_MAX_OUTPUT_SIZE);
+            const stderr = truncateOutput(error.stderr ?? '', DEFAULT_MAX_OUTPUT_SIZE);
+            // Return output even on non-zero exit
+            return createSuccessResult({
+                stdout: stdout.content,
+                stderr: stderr.content,
+                exitCode: error.code ?? 1,
+                truncated: stdout.truncated || stderr.truncated,
+                ...(fifoCheck.detected && { fifoWarning: fifoCheck.warning }),
+            });
+        }
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Execute command in background and return shell ID
+ */
+function executeInBackground(command, options) {
+    try {
+        const manager = getDefaultShellManager();
+        const shellId = manager.spawn(command, options);
+        return createSuccessResult({
+            shell_id: shellId,
+            message: `Command started in background. Use bash_output with shell_id '${shellId}' to retrieve output.`,
+            command,
+        });
+    }
+    catch (error) {
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+function isExecError(error) {
+    return error instanceof Error && ('code' in error || 'killed' in error);
+}
+/**
+ * Factory function to create a bash tool with custom options
+ *
+ * SECURITY NOTE: The blockedCommands and allowedCommands options provide
+ * ADVISORY filtering only. They are NOT a security boundary. Shell commands
+ * can be obfuscated in many ways (quotes, escape sequences, command substitution,
+ * environment variables, etc.) that bypass simple string matching.
+ *
+ * For actual security isolation, use:
+ * - Container/sandbox environments
+ * - seccomp/AppArmor profiles
+ * - Dedicated restricted shells (rbash)
+ * - User namespace isolation
+ */
+export function createBashTool(options) {
+    return defineTool({
+        name: 'bash',
+        description: 'Execute a shell command and return its output. ' +
+            'Commands run in bash shell. Use for system operations, git commands, npm, etc. ' +
+            'Set run_in_background=true for long-running commands, then use bash_output to monitor.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: {
+                    type: 'string',
+                    description: 'The shell command to execute',
+                },
+                cwd: {
+                    type: 'string',
+                    description: 'Working directory for the command',
+                },
+                timeout: {
+                    type: 'number',
+                    description: 'Timeout in milliseconds (default: 60000). Ignored for background commands.',
+                },
+                env: {
+                    type: 'object',
+                    description: 'Additional environment variables',
+                },
+                run_in_background: {
+                    type: 'boolean',
+                    description: 'Run command in background and return shell ID. Use bash_output to get results.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Brief description of what this command does',
+                },
+            },
+            required: ['command'],
+        },
+        execute: async (input) => {
+            const { cwd: defaultCwd, timeout: defaultTimeout = DEFAULT_TIMEOUT, maxOutputSize = DEFAULT_MAX_OUTPUT_SIZE, blockedCommands = [], restrictToAllowed = false, allowedCommands = [], shell = '/bin/bash', shellManager, fifoMode = 'warn', } = options ?? {};
+            const command = input.command.trim();
+            // Detect FIFO usage
+            const fifoCheck = detectFifoUsage(command);
+            if (fifoCheck.detected && fifoMode === 'block') {
+                return createErrorResult(`Command blocked: ${fifoCheck.warning ?? 'FIFO/pipe usage detected'} ` +
+                    `Matched patterns: ${fifoCheck.patterns.join(', ')}`);
+            }
+            // Check blocked commands
+            for (const blocked of blockedCommands) {
+                if (command.includes(blocked)) {
+                    return createErrorResult(`Command contains blocked pattern: ${blocked}`);
+                }
+            }
+            // Check allowed commands if restricted (exact match required)
+            if (restrictToAllowed) {
+                const firstWord = command.split(/\s+/)[0];
+                if (!firstWord || !allowedCommands.includes(firstWord)) {
+                    return createErrorResult(`Command not in allowed list. Allowed: ${allowedCommands.join(', ')}`);
+                }
+            }
+            // Handle background execution
+            if (input.run_in_background) {
+                try {
+                    const manager = shellManager ?? getDefaultShellManager();
+                    const shellId = manager.spawn(command, {
+                        cwd: input.cwd ?? defaultCwd,
+                        env: input.env,
+                    });
+                    return createSuccessResult({
+                        shell_id: shellId,
+                        message: `Command started in background. Use bash_output with shell_id '${shellId}' to retrieve output.`,
+                        command,
+                    });
+                }
+                catch (error) {
+                    return createErrorResult(error instanceof Error ? error.message : String(error));
+                }
+            }
+            // Execute with merged options
+            const mergedInput = {
+                ...input,
+                cwd: input.cwd ?? defaultCwd,
+                timeout: input.timeout ?? defaultTimeout,
+            };
+            try {
+                const result = await execAsync(mergedInput.command, {
+                    cwd: mergedInput.cwd,
+                    timeout: mergedInput.timeout,
+                    maxBuffer: MAX_BUFFER_SIZE,
+                    shell,
+                    env: mergedInput.env ? { ...process.env, ...mergedInput.env } : undefined,
+                });
+                // Truncate output to prevent memory bloat
+                const stdout = truncateOutput(result.stdout, maxOutputSize);
+                const stderr = truncateOutput(result.stderr, maxOutputSize);
+                return createSuccessResult({
+                    stdout: stdout.content,
+                    stderr: stderr.content,
+                    exitCode: 0,
+                    truncated: stdout.truncated || stderr.truncated,
+                    ...(fifoCheck.detected && fifoMode === 'warn' && { fifoWarning: fifoCheck.warning }),
+                });
+            }
+            catch (error) {
+                if (isExecError(error)) {
+                    if (error.killed) {
+                        return createErrorResult(`Command timed out after ${String(mergedInput.timeout ?? defaultTimeout)}ms`);
+                    }
+                    // Truncate output even on error
+                    const stdout = truncateOutput(error.stdout ?? '', maxOutputSize);
+                    const stderr = truncateOutput(error.stderr ?? '', maxOutputSize);
+                    return createSuccessResult({
+                        stdout: stdout.content,
+                        stderr: stderr.content,
+                        exitCode: error.code ?? 1,
+                        truncated: stdout.truncated || stderr.truncated,
+                        ...(fifoCheck.detected && fifoMode === 'warn' && { fifoWarning: fifoCheck.warning }),
+                    });
+                }
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}
+/**
+ * Execute a command with streaming output (for long-running commands)
+ *
+ * Note: This is a lower-level function for cases where you need
+ * to stream output as it arrives.
+ */
+export function execStream(command, options) {
+    const { cwd, env, shell = '/bin/bash' } = options ?? {};
+    const child = spawn(command, [], {
+        cwd,
+        shell,
+        env: env ? { ...process.env, ...env } : undefined,
+    });
+    async function* createStream(stream) {
+        if (!stream)
+            return;
+        for await (const chunk of stream) {
+            yield chunk.toString();
+        }
+    }
+    const promise = new Promise((resolve, reject) => {
+        child.on('close', (code) => {
+            resolve(code ?? 0);
+        });
+        child.on('error', reject);
+    });
+    return {
+        stdout: createStream(child.stdout),
+        stderr: createStream(child.stderr),
+        promise,
+    };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Edit Tool - Perform targeted string replacements in files
+ */
+import type { Tool } from '../types.js';
+/**
+ * Input parameters for edit tool
+ */
+export interface EditInput {
+    /**
+     * Path to the file to edit
+     */
+    filePath: string;
+    /**
+     * The text to search for (must be unique in the file)
+     */
+    oldString: string;
+    /**
+     * The replacement text
+     */
+    newString: string;
+    /**
+     * Replace all occurrences (default: false, requires unique match)
+     */
+    replaceAll?: boolean;
+    /**
+     * Create the file if it doesn't exist (default: false)
+     */
+    createIfMissing?: boolean;
+}
+/**
+ * Edit tool definition
+ */
+export declare const editTool: Tool<EditInput>;
+/**
+ * Factory function to create an edit tool with custom options
+ */
+export declare function createEditTool(options?: {
+    /**
+     * Base directory to resolve relative paths against
+     */
+    baseDir?: string;
+    /**
+     * Allowed file extensions (if specified, only these can be edited)
+     */
+    allowedExtensions?: string[];
+    /**
+     * Disallowed paths (files that cannot be edited)
+     */
+    disallowedPaths?: string[];
+}): Tool<EditInput>;