@compilr-dev/agents 0.0.1

package/dist/tools/builtin/utils.js

@@ -0,0 +1,70 @@
+/**
+ * Shared utilities for builtin tools
+ */
+/**
+ * Type guard for Node.js errors with code property
+ */
+export function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+/**
+ * Get the file extension from a path, including the leading dot.
+ * Returns empty string if no extension found.
+ *
+ * @example
+ * getExtension('/path/to/file.ts') // returns '.ts'
+ * getExtension('/path/to/file') // returns ''
+ * getExtension('/path/to/.gitignore') // returns '' (dotfile, not extension)
+ */
+export function getExtension(filePath) {
+    const fileName = filePath.split('/').pop() ?? '';
+    const lastDot = fileName.lastIndexOf('.');
+    // No dot, or dot is at start (dotfile like .gitignore)
+    if (lastDot <= 0) {
+        return '';
+    }
+    return fileName.substring(lastDot).toLowerCase();
+}
+/**
+ * Check if a file extension is in the allowed list.
+ * Handles both formats: ['.ts', '.js'] or ['ts', 'js']
+ */
+export function isExtensionAllowed(filePath, allowedExtensions) {
+    const ext = getExtension(filePath);
+    // No extension - not allowed if there are restrictions
+    if (!ext) {
+        return false;
+    }
+    // Check both with and without the dot for flexibility
+    const extWithoutDot = ext.substring(1);
+    return allowedExtensions.some((allowed) => allowed === ext || allowed === extWithoutDot);
+}
+/**
+ * Write a file atomically by writing to a temp file first, then renaming.
+ * This prevents file corruption if the write is interrupted.
+ */
+export async function atomicWriteFile(filePath, content, encoding = 'utf-8') {
+    const fs = await import('node:fs/promises');
+    const path = await import('node:path');
+    const crypto = await import('node:crypto');
+    // Create temp file in same directory (ensures same filesystem for atomic rename)
+    const dir = path.dirname(filePath);
+    const tempName = `.${path.basename(filePath)}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    const tempPath = dir === '.' ? tempName : `${dir}/${tempName}`;
+    try {
+        // Write to temp file
+        await fs.writeFile(tempPath, content, { encoding });
+        // Atomic rename
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        // Clean up temp file on failure
+        try {
+            await fs.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}

package/dist/tools/builtin/web-fetch.d.ts

@@ -0,0 +1,96 @@
+/**
+ * WebFetch Tool - Fetch and process web content
+ *
+ * Fetches content from a URL and optionally processes it with an LLM.
+ */
+import type { Tool } from '../types.js';
+/**
+ * Input parameters for webFetch tool
+ */
+export interface WebFetchInput {
+    /**
+     * The URL to fetch content from
+     */
+    url: string;
+    /**
+     * Optional prompt to process the content with
+     * If provided, the content will be processed and summarized
+     */
+    prompt?: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Maximum content size to return in bytes (default: 100KB)
+     * Larger content will be truncated
+     */
+    maxSize?: number;
+}
+/**
+ * Result of webFetch tool
+ */
+export interface WebFetchResult {
+    /**
+     * The fetched content (or processed result if prompt provided)
+     */
+    content: string;
+    /**
+     * The URL that was fetched (may differ from input if redirected)
+     */
+    url: string;
+    /**
+     * HTTP status code
+     */
+    status: number;
+    /**
+     * Content type from response headers
+     */
+    contentType: string;
+    /**
+     * Whether the content was truncated
+     */
+    truncated: boolean;
+    /**
+     * Original content size in bytes
+     */
+    originalSize: number;
+}
+/**
+ * WebFetch tool definition
+ */
+export declare const webFetchTool: Tool<WebFetchInput>;
+/**
+ * Options for creating a webFetch tool
+ */
+export interface WebFetchOptions {
+    /**
+     * Default timeout for requests (default: 30000ms)
+     */
+    defaultTimeout?: number;
+    /**
+     * Default max content size (default: 100KB)
+     */
+    defaultMaxSize?: number;
+    /**
+     * Blocked domains (requests to these domains will fail)
+     */
+    blockedDomains?: string[];
+    /**
+     * Allowed domains (if set, only these domains are allowed)
+     */
+    allowedDomains?: string[];
+    /**
+     * Custom content processor function
+     * Can be used to integrate LLM processing
+     */
+    contentProcessor?: (content: string, prompt?: string) => Promise<string>;
+    /**
+     * Custom headers to include in all requests
+     */
+    customHeaders?: Record<string, string>;
+}
+/**
+ * Factory function to create a webFetch tool with custom options
+ */
+export declare function createWebFetchTool(options?: WebFetchOptions): Tool<WebFetchInput>;

package/dist/tools/builtin/web-fetch.js

@@ -0,0 +1,290 @@
+/**
+ * WebFetch Tool - Fetch and process web content
+ *
+ * Fetches content from a URL and optionally processes it with an LLM.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+/**
+ * Default timeout (30 seconds)
+ */
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * Default max content size (100KB)
+ */
+const DEFAULT_MAX_SIZE = 100 * 1024;
+/**
+ * WebFetch tool definition
+ */
+export const webFetchTool = defineTool({
+    name: 'web_fetch',
+    description: 'Fetch content from a URL. Returns the page content as text. ' +
+        'Use for retrieving documentation, API responses, or web pages. ' +
+        'HTTP URLs are automatically upgraded to HTTPS.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: {
+                type: 'string',
+                description: 'The URL to fetch content from',
+            },
+            prompt: {
+                type: 'string',
+                description: 'Optional prompt to describe what information to extract from the page. ' +
+                    'If not provided, returns the raw content.',
+            },
+            timeout: {
+                type: 'number',
+                description: 'Request timeout in milliseconds (default: 30000)',
+            },
+            maxSize: {
+                type: 'number',
+                description: 'Maximum content size to return in bytes (default: 102400)',
+            },
+        },
+        required: ['url'],
+    },
+    execute: async (input) => {
+        return executeWebFetch(input);
+    },
+});
+/**
+ * Execute the webFetch tool
+ */
+async function executeWebFetch(input, options) {
+    const { url: inputUrl, timeout = DEFAULT_TIMEOUT, maxSize = DEFAULT_MAX_SIZE } = input;
+    // Validate and normalize URL
+    let url;
+    try {
+        url = new URL(inputUrl);
+        // Upgrade HTTP to HTTPS
+        if (url.protocol === 'http:') {
+            url.protocol = 'https:';
+        }
+        // Only allow http(s) protocols
+        if (url.protocol !== 'https:') {
+            return createErrorResult(`Unsupported protocol: ${url.protocol}. Only HTTP(S) is supported.`);
+        }
+    }
+    catch {
+        return createErrorResult(`Invalid URL: ${inputUrl}`);
+    }
+    // Build fetch options
+    const fetchOptions = {
+        method: 'GET',
+        headers: {
+            'User-Agent': 'Mozilla/5.0 (compatible; AgentBot/1.0)',
+            Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.7',
+            'Accept-Language': 'en-US,en;q=0.5',
+        },
+        redirect: 'follow',
+        signal: AbortSignal.timeout(timeout),
+    };
+    try {
+        const response = await fetch(url.toString(), fetchOptions);
+        // Get content type
+        const contentType = response.headers.get('content-type') ?? 'text/plain';
+        // Check for redirect to different host
+        const finalUrl = response.url;
+        const finalUrlObj = new URL(finalUrl);
+        if (finalUrlObj.host !== url.host) {
+            return createSuccessResult({
+                content: `Redirected to different host. New URL: ${finalUrl}`,
+                url: finalUrl,
+                status: response.status,
+                contentType,
+                truncated: false,
+                originalSize: 0,
+                redirected: true,
+            });
+        }
+        // Read response body
+        let content = await response.text();
+        const originalSize = content.length;
+        let truncated = false;
+        // Truncate if too large
+        if (content.length > maxSize) {
+            content = content.slice(0, maxSize) + '\n\n... [Content truncated]';
+            truncated = true;
+        }
+        // Convert HTML to plain text (basic conversion)
+        if (contentType.includes('text/html')) {
+            content = htmlToText(content);
+        }
+        // Apply custom processor if provided
+        if (options?.contentProcessor) {
+            content = await options.contentProcessor(content, input.prompt);
+        }
+        return createSuccessResult({
+            content,
+            url: finalUrl,
+            status: response.status,
+            contentType,
+            truncated,
+            originalSize,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            if (error.name === 'TimeoutError' || error.name === 'AbortError') {
+                return createErrorResult(`Request timed out after ${String(timeout)}ms`);
+            }
+            return createErrorResult(`Fetch failed: ${error.message}`);
+        }
+        return createErrorResult(`Fetch failed: ${String(error)}`);
+    }
+}
+/**
+ * Basic HTML to text conversion
+ * Strips tags and normalizes whitespace
+ */
+function htmlToText(html) {
+    // Remove script and style elements
+    let text = html.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
+    text = text.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');
+    // Replace common block elements with newlines
+    text = text.replace(/<\/?(p|div|br|h[1-6]|li|tr|td|th|article|section|header|footer)[^>]*>/gi, '\n');
+    // Replace list items with bullets
+    text = text.replace(/<li[^>]*>/gi, '\n• ');
+    // Remove remaining tags
+    text = text.replace(/<[^>]+>/g, '');
+    // Decode common HTML entities
+    text = text.replace(/&nbsp;/g, ' ');
+    text = text.replace(/&amp;/g, '&');
+    text = text.replace(/&lt;/g, '<');
+    text = text.replace(/&gt;/g, '>');
+    text = text.replace(/&quot;/g, '"');
+    text = text.replace(/&#39;/g, "'");
+    text = text.replace(/&apos;/g, "'");
+    // Normalize whitespace
+    text = text.replace(/[ \t]+/g, ' ');
+    text = text.replace(/\n\s*\n/g, '\n\n');
+    text = text.trim();
+    return text;
+}
+/**
+ * Factory function to create a webFetch tool with custom options
+ */
+export function createWebFetchTool(options) {
+    const { defaultTimeout = DEFAULT_TIMEOUT, defaultMaxSize = DEFAULT_MAX_SIZE, blockedDomains = [], allowedDomains, customHeaders = {}, } = options ?? {};
+    return defineTool({
+        name: 'web_fetch',
+        description: 'Fetch content from a URL. Returns the page content as text. ' +
+            'Use for retrieving documentation, API responses, or web pages. ' +
+            'HTTP URLs are automatically upgraded to HTTPS.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'The URL to fetch content from',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Optional prompt to describe what information to extract from the page. ' +
+                        'If not provided, returns the raw content.',
+                },
+                timeout: {
+                    type: 'number',
+                    description: `Request timeout in milliseconds (default: ${String(defaultTimeout)})`,
+                },
+                maxSize: {
+                    type: 'number',
+                    description: `Maximum content size to return in bytes (default: ${String(defaultMaxSize)})`,
+                },
+            },
+            required: ['url'],
+        },
+        execute: async (input) => {
+            const timeout = input.timeout ?? defaultTimeout;
+            const maxSize = input.maxSize ?? defaultMaxSize;
+            // Validate URL
+            let url;
+            try {
+                url = new URL(input.url);
+                // Upgrade HTTP to HTTPS
+                if (url.protocol === 'http:') {
+                    url.protocol = 'https:';
+                }
+                // Only allow http(s) protocols
+                if (url.protocol !== 'https:') {
+                    return createErrorResult(`Unsupported protocol: ${url.protocol}. Only HTTP(S) is supported.`);
+                }
+            }
+            catch {
+                return createErrorResult(`Invalid URL: ${input.url}`);
+            }
+            // Check blocked domains
+            if (blockedDomains.some((d) => url.hostname.endsWith(d))) {
+                return createErrorResult(`Domain '${url.hostname}' is blocked.`);
+            }
+            // Check allowed domains
+            if (allowedDomains && !allowedDomains.some((d) => url.hostname.endsWith(d))) {
+                return createErrorResult(`Domain '${url.hostname}' is not in allowed list.`);
+            }
+            // Build fetch options
+            const fetchOptions = {
+                method: 'GET',
+                headers: {
+                    'User-Agent': 'Mozilla/5.0 (compatible; AgentBot/1.0)',
+                    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.7',
+                    'Accept-Language': 'en-US,en;q=0.5',
+                    ...customHeaders,
+                },
+                redirect: 'follow',
+                signal: AbortSignal.timeout(timeout),
+            };
+            try {
+                const response = await fetch(url.toString(), fetchOptions);
+                const contentType = response.headers.get('content-type') ?? 'text/plain';
+                // Check for redirect to different host
+                const finalUrl = response.url;
+                const finalUrlObj = new URL(finalUrl);
+                if (finalUrlObj.host !== url.host) {
+                    return createSuccessResult({
+                        content: `Redirected to different host. New URL: ${finalUrl}`,
+                        url: finalUrl,
+                        status: response.status,
+                        contentType,
+                        truncated: false,
+                        originalSize: 0,
+                        redirected: true,
+                    });
+                }
+                // Read response body
+                let content = await response.text();
+                const originalSize = content.length;
+                let truncated = false;
+                // Truncate if too large
+                if (content.length > maxSize) {
+                    content = content.slice(0, maxSize) + '\n\n... [Content truncated]';
+                    truncated = true;
+                }
+                // Convert HTML to plain text
+                if (contentType.includes('text/html')) {
+                    content = htmlToText(content);
+                }
+                // Apply custom processor if provided
+                if (options?.contentProcessor) {
+                    content = await options.contentProcessor(content, input.prompt);
+                }
+                return createSuccessResult({
+                    content,
+                    url: finalUrl,
+                    status: response.status,
+                    contentType,
+                    truncated,
+                    originalSize,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    if (error.name === 'TimeoutError' || error.name === 'AbortError') {
+                        return createErrorResult(`Request timed out after ${String(timeout)}ms`);
+                    }
+                    return createErrorResult(`Fetch failed: ${error.message}`);
+                }
+                return createErrorResult(`Fetch failed: ${String(error)}`);
+            }
+        },
+    });
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Write File Tool - Write or create files on the filesystem
+ */
+import type { Tool } from '../types.js';
+/**
+ * Input parameters for write_file tool
+ */
+export interface WriteFileInput {
+    /**
+     * Path to the file to write
+     */
+    path: string;
+    /**
+     * Content to write to the file
+     */
+    content: string;
+    /**
+     * Encoding to use (default: utf-8)
+     */
+    encoding?: BufferEncoding;
+    /**
+     * Create parent directories if they don't exist (default: true)
+     */
+    createDirs?: boolean;
+    /**
+     * Append to file instead of overwriting (default: false)
+     */
+    append?: boolean;
+}
+/**
+ * Write file tool definition
+ */
+export declare const writeFileTool: Tool<WriteFileInput>;
+/**
+ * Factory function to create a write_file tool with custom options
+ */
+export declare function createWriteFileTool(options?: {
+    /**
+     * Base directory to resolve relative paths against
+     */
+    baseDir?: string;
+    /**
+     * List of allowed file extensions (e.g., ['.ts', '.js', '.json'])
+     */
+    allowedExtensions?: string[];
+    /**
+     * Maximum content size in bytes (default: 10MB)
+     */
+    maxContentSize?: number;
+    /**
+     * Directories that cannot be written to
+     */
+    blockedPaths?: string[];
+}): Tool<WriteFileInput>;

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

@@ -0,0 +1,147 @@
+/**
+ * Write File Tool - Write or create files on the filesystem
+ */
+import { writeFile as fsWriteFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+import { isNodeError, isExtensionAllowed } from './utils.js';
+/**
+ * Write file tool definition
+ */
+export const writeFileTool = defineTool({
+    name: 'write_file',
+    description: 'Write content to a file. Creates the file if it does not exist. ' +
+        'Use append: true to add to existing content instead of overwriting.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute or relative path to the file',
+            },
+            content: {
+                type: 'string',
+                description: 'Content to write to the file',
+            },
+            encoding: {
+                type: 'string',
+                description: 'File encoding (default: utf-8)',
+            },
+            createDirs: {
+                type: 'boolean',
+                description: 'Create parent directories if needed (default: true)',
+            },
+            append: {
+                type: 'boolean',
+                description: 'Append to file instead of overwriting (default: false)',
+            },
+        },
+        required: ['path', 'content'],
+    },
+    execute: executeWriteFile,
+});
+/**
+ * Execute the write_file tool
+ */
+async function executeWriteFile(input) {
+    try {
+        const { path, content, encoding = 'utf-8', createDirs = true, append = false } = input;
+        // Create parent directories if needed
+        if (createDirs) {
+            const dir = dirname(path);
+            if (dir && dir !== '.') {
+                await mkdir(dir, { recursive: true });
+            }
+        }
+        // Write the file
+        const flag = append ? 'a' : 'w';
+        await fsWriteFile(path, content, { encoding, flag });
+        return createSuccessResult({
+            path,
+            bytesWritten: Buffer.byteLength(content, encoding),
+            mode: append ? 'appended' : 'written',
+        });
+    }
+    catch (error) {
+        if (isNodeError(error)) {
+            switch (error.code) {
+                case 'EACCES':
+                    return createErrorResult(`Permission denied: ${input.path}`);
+                case 'ENOENT':
+                    return createErrorResult(`Directory does not exist: ${dirname(input.path)}`);
+                case 'ENOSPC':
+                    return createErrorResult('No space left on device');
+                case 'EROFS':
+                    return createErrorResult('Read-only file system');
+                default:
+                    return createErrorResult(`Failed to write file: ${error.message}`);
+            }
+        }
+        return createErrorResult(error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * Factory function to create a write_file tool with custom options
+ */
+export function createWriteFileTool(options) {
+    return defineTool({
+        name: 'write_file',
+        description: 'Write content to a file. Creates the file if it does not exist. ' +
+            'Use append: true to add to existing content instead of overwriting.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Absolute or relative path to the file',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Content to write to the file',
+                },
+                encoding: {
+                    type: 'string',
+                    description: 'File encoding (default: utf-8)',
+                },
+                createDirs: {
+                    type: 'boolean',
+                    description: 'Create parent directories if needed (default: true)',
+                },
+                append: {
+                    type: 'boolean',
+                    description: 'Append to file instead of overwriting (default: false)',
+                },
+            },
+            required: ['path', 'content'],
+        },
+        execute: async (input) => {
+            const { baseDir, allowedExtensions, maxContentSize = 10 * 1024 * 1024, blockedPaths = [], } = options ?? {};
+            let filePath = input.path;
+            // Resolve relative paths and normalize to prevent path traversal
+            if (baseDir && !filePath.startsWith('/')) {
+                filePath = resolve(baseDir, filePath);
+            }
+            else {
+                filePath = resolve(filePath);
+            }
+            // Check blocked paths (compare resolved paths to prevent traversal bypass)
+            for (const blocked of blockedPaths) {
+                const resolvedBlocked = resolve(blocked);
+                if (filePath.startsWith(resolvedBlocked) || filePath === resolvedBlocked) {
+                    return createErrorResult(`Cannot write to blocked path: ${blocked}`);
+                }
+            }
+            // Check extension if restricted
+            if (allowedExtensions && allowedExtensions.length > 0) {
+                if (!isExtensionAllowed(filePath, allowedExtensions)) {
+                    return createErrorResult(`File extension not allowed. Allowed: ${allowedExtensions.join(', ')}`);
+                }
+            }
+            // Check content size
+            if (Buffer.byteLength(input.content, input.encoding ?? 'utf-8') > maxContentSize) {
+                return createErrorResult(`Content too large (max: ${String(maxContentSize)} bytes)`);
+            }
+            return executeWriteFile({ ...input, path: filePath });
+        },
+    });
+}