@compilr-dev/agents 0.0.1

package/dist/tools/builtin/read-file.js

@@ -0,0 +1,184 @@
+/**
+ * Read File Tool - Read contents of a file from the filesystem
+ */
+import { readFile as fsReadFile, stat } from 'node:fs/promises';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { isNodeError, isExtensionAllowed } from './utils.js';
+/**
+ * Default maximum file size (10MB)
+ */
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+/**
+ * Default maximum content size returned to agent (100KB)
+ * Files larger than this are truncated to prevent memory bloat
+ */
+const DEFAULT_MAX_CONTENT_SIZE = 100 * 1024;
+/**
+ * Read file tool definition
+ */
+export const readFileTool = defineTool({
+    name: 'read_file',
+    description: 'Read the contents of a file. Returns the file content as text. ' +
+        'Use maxLines and startLine to read specific portions of large files.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute or relative path to the file',
+            },
+            encoding: {
+                type: 'string',
+                description: 'File encoding (default: utf-8)',
+            },
+            maxLines: {
+                type: 'number',
+                description: 'Maximum number of lines to read',
+            },
+            startLine: {
+                type: 'number',
+                description: 'Line number to start reading from (1-indexed)',
+            },
+        },
+        required: ['path'],
+    },
+    execute: executeReadFile,
+});
+/**
+ * Execute the read_file tool
+ */
+async function executeReadFile(input, options) {
+    const maxFileSize = options?.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+    const maxContentSize = options?.maxContentSize ?? DEFAULT_MAX_CONTENT_SIZE;
+    const truncateIfLarge = options?.truncateIfLarge ?? true;
+    try {
+        // Pre-check: Get file size before reading
+        const stats = await stat(input.path);
+        const fileSize = stats.size;
+        // Check if file is too large to read at all
+        if (fileSize > maxFileSize) {
+            return createErrorResult(`File too large to read: ${formatSize(fileSize)} (max: ${formatSize(maxFileSize)}). ` +
+                `Consider using maxLines/startLine to read portions.`);
+        }
+        const encoding = input.encoding ?? 'utf-8';
+        let content = await fsReadFile(input.path, { encoding });
+        let truncated = false;
+        let totalLines;
+        let linesReturned;
+        // Handle line-based reading
+        if (input.maxLines !== undefined || input.startLine !== undefined) {
+            const lines = content.split('\n');
+            totalLines = lines.length;
+            // Validate and convert startLine to 0-indexed (minimum 1)
+            const startLine = Math.max(1, input.startLine ?? 1);
+            const startIdx = startLine - 1;
+            const endIdx = input.maxLines !== undefined ? startIdx + input.maxLines : lines.length;
+            content = lines.slice(startIdx, endIdx).join('\n');
+            linesReturned = Math.min(endIdx, lines.length) - startIdx;
+        }
+        // Truncate content if too large for agent context
+        if (content.length > maxContentSize) {
+            if (truncateIfLarge) {
+                truncated = true;
+                const lines = content.split('\n');
+                totalLines = totalLines ?? lines.length;
+                // Keep first and last portions
+                const headSize = Math.floor(maxContentSize * 0.7);
+                const tailSize = Math.floor(maxContentSize * 0.2);
+                const head = content.slice(0, headSize);
+                const tail = content.slice(-tailSize);
+                const omitted = content.length - headSize - tailSize;
+                content = `${head}\n\n... [${formatSize(omitted)} truncated] ...\n\n${tail}`;
+            }
+            else {
+                return createErrorResult(`File content too large: ${formatSize(content.length)} (max: ${formatSize(maxContentSize)}). ` +
+                    `Use maxLines/startLine to read portions.`);
+            }
+        }
+        // Return result with metadata
+        return createSuccessResult({
+            content,
+            path: input.path,
+            size: fileSize,
+            truncated,
+            ...(totalLines !== undefined && { totalLines }),
+            ...(linesReturned !== undefined && { linesReturned }),
+        });
+    }
+    catch (error) {
+        if (isNodeError(error)) {
+            switch (error.code) {
+                case 'ENOENT':
+                    return createErrorResult(`File not found: ${input.path}`);
+                case 'EACCES':
+                    return createErrorResult(`Permission denied: ${input.path}`);
+                case 'EISDIR':
+                    return createErrorResult(`Path is a directory: ${input.path}`);
+                default:
+                    return createErrorResult(`Failed to read file: ${error.message}`);
+            }
+        }
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Format byte size for human readability
+ */
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${String(bytes)} bytes`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Factory function to create a read_file tool with custom options
+ */
+export function createReadFileTool(options) {
+    return defineTool({
+        name: 'read_file',
+        description: 'Read the contents of a file. Returns the file content as text. ' +
+            'Use maxLines and startLine to read specific portions of large files.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute or relative path to the file',
+                },
+                encoding: {
+                    type: 'string',
+                    description: 'File encoding (default: utf-8)',
+                },
+                maxLines: {
+                    type: 'number',
+                    description: 'Maximum number of lines to read',
+                },
+                startLine: {
+                    type: 'number',
+                    description: 'Line number to start reading from (1-indexed)',
+                },
+            },
+            required: ['path'],
+        },
+        execute: async (input) => {
+            const { baseDir, allowedExtensions, maxFileSize, maxContentSize, truncateIfLarge } = options ?? {};
+            let filePath = input.path;
+            // Resolve relative paths
+            if (baseDir && !filePath.startsWith('/')) {
+                filePath = `${baseDir}/${filePath}`;
+            }
+            // Check extension if restricted
+            if (allowedExtensions && allowedExtensions.length > 0) {
+                if (!isExtensionAllowed(filePath, allowedExtensions)) {
+                    return createErrorResult(`File extension not allowed. Allowed: ${allowedExtensions.join(', ')}`);
+                }
+            }
+            return executeReadFile({ ...input, path: filePath }, {
+                maxFileSize,
+                maxContentSize,
+                truncateIfLarge,
+            });
+        },
+    });
+}

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

@@ -0,0 +1,176 @@
+/**
+ * Shell Manager - Track and manage background shell processes
+ */
+/**
+ * Status of a background shell
+ */
+export type ShellStatus = 'running' | 'completed' | 'failed' | 'killed';
+/**
+ * Information about a background shell
+ */
+export interface BackgroundShell {
+    /**
+     * Unique identifier for this shell
+     */
+    id: string;
+    /**
+     * The command being executed
+     */
+    command: string;
+    /**
+     * Current status
+     */
+    status: ShellStatus;
+    /**
+     * When the shell was started
+     */
+    startTime: Date;
+    /**
+     * When the shell finished (if completed/failed/killed)
+     */
+    endTime?: Date;
+    /**
+     * Exit code (if completed or failed)
+     */
+    exitCode?: number;
+    /**
+     * Working directory
+     */
+    cwd?: string;
+}
+/**
+ * Output from a background shell
+ */
+export interface ShellOutput {
+    /**
+     * Shell ID
+     */
+    id: string;
+    /**
+     * Current status
+     */
+    status: ShellStatus;
+    /**
+     * Standard output (new since last read)
+     */
+    stdout: string;
+    /**
+     * Standard error (new since last read)
+     */
+    stderr: string;
+    /**
+     * Whether there is more output buffered
+     */
+    hasMore: boolean;
+    /**
+     * Exit code (if completed)
+     */
+    exitCode?: number;
+}
+/**
+ * Options for ShellManager
+ */
+export interface ShellManagerOptions {
+    /**
+     * Maximum buffer size per stream in bytes
+     */
+    maxBufferSize?: number;
+    /**
+     * Maximum number of concurrent shells
+     */
+    maxShells?: number;
+    /**
+     * Shell to use (default: /bin/bash)
+     */
+    shell?: string;
+    /**
+     * Auto-cleanup completed shells after this many milliseconds
+     * Set to 0 to disable auto-cleanup
+     */
+    autoCleanupMs?: number;
+}
+/**
+ * Manages background shell processes
+ */
+export declare class ShellManager {
+    private readonly shells;
+    private readonly maxBufferSize;
+    private readonly maxShells;
+    private readonly shell;
+    private readonly autoCleanupMs;
+    private readonly cleanupTimers;
+    constructor(options?: ShellManagerOptions);
+    /**
+     * Spawn a new background shell
+     */
+    spawn(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+    }): string;
+    /**
+     * Get output from a shell (only new output since last read)
+     */
+    getOutput(id: string, filter?: RegExp): ShellOutput | null;
+    /**
+     * Get all output from a shell (including previously read)
+     */
+    getAllOutput(id: string): ShellOutput | null;
+    /**
+     * Kill a background shell
+     */
+    kill(id: string): boolean;
+    /**
+     * Verify and sync shell status with actual process state.
+     * Call this to ensure status reflects reality after potential race conditions.
+     */
+    verifyStatus(id: string): ShellStatus | null;
+    /**
+     * Verify all shells and sync their status.
+     * Returns number of shells whose status was corrected.
+     */
+    verifyAllStatus(): number;
+    /**
+     * List all shells
+     */
+    list(): BackgroundShell[];
+    /**
+     * List running shells only
+     */
+    listRunning(): BackgroundShell[];
+    /**
+     * Get shell info
+     */
+    get(id: string): BackgroundShell | null;
+    /**
+     * Remove a shell from tracking (only if not running)
+     */
+    remove(id: string): boolean;
+    /**
+     * Clear all completed/failed/killed shells
+     */
+    clearCompleted(): number;
+    /**
+     * Kill all running shells
+     */
+    killAll(): number;
+    /**
+     * Cleanup - kill all shells and clear state
+     */
+    dispose(): void;
+    /**
+     * Append data to buffer with size limit
+     */
+    private appendToBuffer;
+    /**
+     * Schedule auto-cleanup for a completed shell
+     */
+    private scheduleCleanup;
+}
+/**
+ * Get or create the default shell manager
+ */
+export declare function getDefaultShellManager(): ShellManager;
+/**
+ * Set a custom default shell manager
+ */
+export declare function setDefaultShellManager(manager: ShellManager): void;

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

@@ -0,0 +1,337 @@
+/**
+ * Shell Manager - Track and manage background shell processes
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+/**
+ * Default maximum buffer size per stream (100KB)
+ */
+const DEFAULT_MAX_BUFFER_SIZE = 100 * 1024;
+/**
+ * Default maximum number of concurrent shells
+ */
+const DEFAULT_MAX_SHELLS = 10;
+/**
+ * Manages background shell processes
+ */
+export class ShellManager {
+    shells = new Map();
+    maxBufferSize;
+    maxShells;
+    shell;
+    autoCleanupMs;
+    cleanupTimers = new Map();
+    constructor(options) {
+        this.maxBufferSize = options?.maxBufferSize ?? DEFAULT_MAX_BUFFER_SIZE;
+        this.maxShells = options?.maxShells ?? DEFAULT_MAX_SHELLS;
+        this.shell = options?.shell ?? '/bin/bash';
+        this.autoCleanupMs = options?.autoCleanupMs ?? 5 * 60 * 1000; // 5 minutes default
+    }
+    /**
+     * Spawn a new background shell
+     */
+    spawn(command, options) {
+        // Check limit
+        const runningCount = Array.from(this.shells.values()).filter((s) => s.info.status === 'running').length;
+        if (runningCount >= this.maxShells) {
+            throw new Error(`Maximum concurrent shells (${String(this.maxShells)}) reached. ` +
+                `Kill some shells before starting new ones.`);
+        }
+        const id = randomUUID().slice(0, 8);
+        const { cwd, env } = options ?? {};
+        const childProcess = spawn(command, [], {
+            cwd,
+            shell: this.shell,
+            env: env ? { ...globalThis.process.env, ...env } : undefined,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const state = {
+            info: {
+                id,
+                command,
+                status: 'running',
+                startTime: new Date(),
+                cwd,
+            },
+            process: childProcess,
+            stdoutBuffer: [],
+            stderrBuffer: [],
+            readIndex: { stdout: 0, stderr: 0 },
+        };
+        // Collect stdout (guaranteed non-null due to stdio: ['ignore', 'pipe', 'pipe'])
+        childProcess.stdout.on('data', (chunk) => {
+            this.appendToBuffer(state.stdoutBuffer, chunk.toString());
+        });
+        // Collect stderr (guaranteed non-null due to stdio: ['ignore', 'pipe', 'pipe'])
+        childProcess.stderr.on('data', (chunk) => {
+            this.appendToBuffer(state.stderrBuffer, chunk.toString());
+        });
+        // Handle completion
+        childProcess.on('close', (code) => {
+            state.info.status = code === 0 ? 'completed' : 'failed';
+            state.info.exitCode = code ?? undefined;
+            state.info.endTime = new Date();
+            this.scheduleCleanup(id);
+        });
+        childProcess.on('error', (error) => {
+            state.info.status = 'failed';
+            state.info.endTime = new Date();
+            state.stderrBuffer.push(`Process error: ${error.message}`);
+            this.scheduleCleanup(id);
+        });
+        this.shells.set(id, state);
+        return id;
+    }
+    /**
+     * Get output from a shell (only new output since last read)
+     */
+    getOutput(id, filter) {
+        const state = this.shells.get(id);
+        if (!state) {
+            return null;
+        }
+        // Get new output since last read
+        const newStdout = state.stdoutBuffer.slice(state.readIndex.stdout);
+        const newStderr = state.stderrBuffer.slice(state.readIndex.stderr);
+        // Update read index
+        state.readIndex.stdout = state.stdoutBuffer.length;
+        state.readIndex.stderr = state.stderrBuffer.length;
+        // Apply filter if provided
+        let stdout = newStdout.join('');
+        let stderr = newStderr.join('');
+        if (filter) {
+            stdout = stdout
+                .split('\n')
+                .filter((line) => filter.test(line))
+                .join('\n');
+            stderr = stderr
+                .split('\n')
+                .filter((line) => filter.test(line))
+                .join('\n');
+        }
+        return {
+            id,
+            status: state.info.status,
+            stdout,
+            stderr,
+            hasMore: state.info.status === 'running',
+            exitCode: state.info.exitCode,
+        };
+    }
+    /**
+     * Get all output from a shell (including previously read)
+     */
+    getAllOutput(id) {
+        const state = this.shells.get(id);
+        if (!state) {
+            return null;
+        }
+        return {
+            id,
+            status: state.info.status,
+            stdout: state.stdoutBuffer.join(''),
+            stderr: state.stderrBuffer.join(''),
+            hasMore: state.info.status === 'running',
+            exitCode: state.info.exitCode,
+        };
+    }
+    /**
+     * Kill a background shell
+     */
+    kill(id) {
+        const state = this.shells.get(id);
+        if (!state) {
+            return false;
+        }
+        if (state.info.status === 'running') {
+            // Immediately update status to prevent race conditions
+            state.info.status = 'killed';
+            state.info.endTime = new Date();
+            // Send SIGTERM
+            try {
+                state.process.kill('SIGTERM');
+            }
+            catch {
+                // Process may already be dead
+            }
+            // Force kill after 5 seconds if process still exists
+            const forceKillTimer = setTimeout(() => {
+                try {
+                    // Check if process is still alive by sending signal 0
+                    state.process.kill(0);
+                    // If we get here, process is still alive - force kill
+                    state.process.kill('SIGKILL');
+                }
+                catch {
+                    // Process is already dead - good
+                }
+            }, 5000);
+            // Don't let the timer prevent process exit
+            if (typeof forceKillTimer.unref === 'function') {
+                forceKillTimer.unref();
+            }
+            // Schedule cleanup
+            this.scheduleCleanup(id);
+        }
+        return true;
+    }
+    /**
+     * Verify and sync shell status with actual process state.
+     * Call this to ensure status reflects reality after potential race conditions.
+     */
+    verifyStatus(id) {
+        const state = this.shells.get(id);
+        if (!state) {
+            return null;
+        }
+        // If marked as running, verify process is actually alive
+        if (state.info.status === 'running') {
+            try {
+                // signal 0 checks if process exists without sending actual signal
+                state.process.kill(0);
+                // Process is alive
+            }
+            catch {
+                // Process is dead but we thought it was running - update status
+                state.info.status = 'completed';
+                state.info.endTime = new Date();
+                this.scheduleCleanup(id);
+            }
+        }
+        return state.info.status;
+    }
+    /**
+     * Verify all shells and sync their status.
+     * Returns number of shells whose status was corrected.
+     */
+    verifyAllStatus() {
+        let corrected = 0;
+        for (const [id, state] of this.shells) {
+            if (state.info.status === 'running') {
+                const verified = this.verifyStatus(id);
+                if (verified !== 'running') {
+                    corrected++;
+                }
+            }
+        }
+        return corrected;
+    }
+    /**
+     * List all shells
+     */
+    list() {
+        return Array.from(this.shells.values()).map((s) => ({ ...s.info }));
+    }
+    /**
+     * List running shells only
+     */
+    listRunning() {
+        return this.list().filter((s) => s.status === 'running');
+    }
+    /**
+     * Get shell info
+     */
+    get(id) {
+        const state = this.shells.get(id);
+        return state ? { ...state.info } : null;
+    }
+    /**
+     * Remove a shell from tracking (only if not running)
+     */
+    remove(id) {
+        const state = this.shells.get(id);
+        if (!state || state.info.status === 'running') {
+            return false;
+        }
+        // Clear cleanup timer if exists
+        const timer = this.cleanupTimers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.cleanupTimers.delete(id);
+        }
+        return this.shells.delete(id);
+    }
+    /**
+     * Clear all completed/failed/killed shells
+     */
+    clearCompleted() {
+        let count = 0;
+        for (const [id, state] of this.shells) {
+            if (state.info.status !== 'running') {
+                this.remove(id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Kill all running shells
+     */
+    killAll() {
+        let count = 0;
+        for (const state of this.shells.values()) {
+            if (state.info.status === 'running') {
+                this.kill(state.info.id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Cleanup - kill all shells and clear state
+     */
+    dispose() {
+        this.killAll();
+        for (const timer of this.cleanupTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.cleanupTimers.clear();
+        this.shells.clear();
+    }
+    /**
+     * Append data to buffer with size limit
+     */
+    appendToBuffer(buffer, data) {
+        buffer.push(data);
+        // Trim buffer if too large
+        let totalSize = buffer.reduce((sum, s) => sum + s.length, 0);
+        while (totalSize > this.maxBufferSize && buffer.length > 1) {
+            const removed = buffer.shift();
+            if (removed) {
+                totalSize -= removed.length;
+            }
+        }
+    }
+    /**
+     * Schedule auto-cleanup for a completed shell
+     */
+    scheduleCleanup(id) {
+        if (this.autoCleanupMs <= 0) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.remove(id);
+            this.cleanupTimers.delete(id);
+        }, this.autoCleanupMs);
+        this.cleanupTimers.set(id, timer);
+    }
+}
+/**
+ * Default global shell manager instance
+ */
+let defaultManager = null;
+/**
+ * Get or create the default shell manager
+ */
+export function getDefaultShellManager() {
+    if (!defaultManager) {
+        defaultManager = new ShellManager();
+    }
+    return defaultManager;
+}
+/**
+ * Set a custom default shell manager
+ */
+export function setDefaultShellManager(manager) {
+    defaultManager = manager;
+}