@compilr-dev/agents 0.0.1

package/dist/errors.js

@@ -0,0 +1,249 @@
+/**
+ * Error classes for @compilr-dev/agents
+ *
+ * Error hierarchy:
+ * - AgentError (base)
+ *   - ProviderError (LLM API errors)
+ *   - ToolError (tool execution errors)
+ *   - ValidationError (input validation errors)
+ */
+/**
+ * Base error class for all agent-related errors.
+ */
+export class AgentError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'AgentError';
+        // Maintains proper stack trace in V8 environments
+        if (typeof Error.captureStackTrace === 'function') {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+/**
+ * Error thrown when an LLM provider API call fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ProviderError(
+ *   'Rate limit exceeded. Retry after 60s',
+ *   'claude',
+ *   429
+ * );
+ * ```
+ */
+export class ProviderError extends AgentError {
+    provider;
+    statusCode;
+    constructor(message, provider, statusCode, cause) {
+        super(message, cause);
+        this.provider = provider;
+        this.statusCode = statusCode;
+        this.name = 'ProviderError';
+    }
+    /**
+     * Check if this is a rate limit error (HTTP 429)
+     */
+    isRateLimitError() {
+        return this.statusCode === 429;
+    }
+    /**
+     * Check if this is an authentication error (HTTP 401/403)
+     */
+    isAuthError() {
+        return this.statusCode === 401 || this.statusCode === 403;
+    }
+    /**
+     * Check if this is a server error (HTTP 5xx)
+     */
+    isServerError() {
+        return this.statusCode !== undefined && this.statusCode >= 500 && this.statusCode < 600;
+    }
+    /**
+     * Check if this error is retryable
+     */
+    isRetryable() {
+        return this.isRateLimitError() || this.isServerError();
+    }
+}
+/**
+ * Error thrown when a tool execution fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ToolError(
+ *   'File not found: /path/to/file.txt',
+ *   'read_file',
+ *   originalError
+ * );
+ * ```
+ */
+export class ToolError extends AgentError {
+    toolName;
+    constructor(message, toolName, cause) {
+        super(message, cause);
+        this.toolName = toolName;
+        this.name = 'ToolError';
+    }
+}
+/**
+ * Error thrown when a tool execution times out.
+ *
+ * @example
+ * ```typescript
+ * throw new ToolTimeoutError('read_file', 30000);
+ * ```
+ */
+export class ToolTimeoutError extends ToolError {
+    toolName;
+    timeoutMs;
+    constructor(toolName, timeoutMs) {
+        super(`Tool '${toolName}' timed out after ${String(timeoutMs)}ms`, toolName);
+        this.toolName = toolName;
+        this.timeoutMs = timeoutMs;
+        this.name = 'ToolTimeoutError';
+    }
+}
+/**
+ * Error thrown when input validation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError(
+ *   'maxTokens must be a positive number',
+ *   'maxTokens'
+ * );
+ * ```
+ */
+export class ValidationError extends AgentError {
+    field;
+    constructor(message, field) {
+        super(message);
+        this.field = field;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Error thrown when the agentic loop exceeds max iterations.
+ *
+ * @example
+ * ```typescript
+ * throw new MaxIterationsError(10);
+ * ```
+ */
+export class MaxIterationsError extends AgentError {
+    maxIterations;
+    constructor(maxIterations) {
+        super(`Agent exceeded maximum iterations (${String(maxIterations)})`);
+        this.maxIterations = maxIterations;
+        this.name = 'MaxIterationsError';
+    }
+}
+/**
+ * Error thrown when the agent is stuck in a tool call loop.
+ *
+ * This occurs when the same tool is called with identical input
+ * multiple times consecutively, indicating the agent is not
+ * processing the tool results properly.
+ *
+ * @example
+ * ```typescript
+ * throw new ToolLoopError('read_file', 3);
+ * ```
+ */
+export class ToolLoopError extends AgentError {
+    toolName;
+    consecutiveCalls;
+    input;
+    constructor(toolName, consecutiveCalls, input) {
+        super(`Agent stuck in tool loop: '${toolName}' called ${String(consecutiveCalls)} times ` +
+            `with identical input. The agent may not be processing tool results correctly.`);
+        this.toolName = toolName;
+        this.consecutiveCalls = consecutiveCalls;
+        this.input = input;
+        this.name = 'ToolLoopError';
+    }
+}
+/**
+ * Error thrown when a request is aborted via AbortSignal.
+ */
+export class AbortError extends AgentError {
+    constructor(message = 'Request was aborted') {
+        super(message);
+        this.name = 'AbortError';
+    }
+}
+/**
+ * Error thrown when context window cannot be reduced sufficiently.
+ *
+ * This occurs when:
+ * - Multiple summarization rounds fail to reduce context below target
+ * - Content is too large even after aggressive filtering
+ *
+ * @example
+ * ```typescript
+ * throw new ContextOverflowError(
+ *   'Unable to reduce context below 90% after 3 summarization rounds',
+ *   0.95,  // current utilization
+ *   3      // rounds attempted
+ * );
+ * ```
+ */
+export class ContextOverflowError extends AgentError {
+    utilization;
+    roundsAttempted;
+    constructor(message, utilization, roundsAttempted) {
+        super(message);
+        this.utilization = utilization;
+        this.roundsAttempted = roundsAttempted;
+        this.name = 'ContextOverflowError';
+    }
+}
+/**
+ * Type guard to check if an error is a ContextOverflowError
+ */
+export function isContextOverflowError(error) {
+    return error instanceof ContextOverflowError;
+}
+/**
+ * Type guard to check if an error is an AgentError
+ */
+export function isAgentError(error) {
+    return error instanceof AgentError;
+}
+/**
+ * Type guard to check if an error is a ProviderError
+ */
+export function isProviderError(error) {
+    return error instanceof ProviderError;
+}
+/**
+ * Type guard to check if an error is a ToolError
+ */
+export function isToolError(error) {
+    return error instanceof ToolError;
+}
+/**
+ * Type guard to check if an error is a ToolLoopError
+ */
+export function isToolLoopError(error) {
+    return error instanceof ToolLoopError;
+}
+/**
+ * Type guard to check if an error is a ToolTimeoutError
+ */
+export function isToolTimeoutError(error) {
+    return error instanceof ToolTimeoutError;
+}
+/**
+ * Wrap an unknown error into an AgentError
+ */
+export function wrapError(error, message) {
+    if (error instanceof AgentError) {
+        return error;
+    }
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return new AgentError(message ?? cause.message, cause);
+}

package/dist/guardrails/builtin.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Built-in guardrails for common dangerous operations
+ *
+ * These guardrails provide sensible safety defaults that can be disabled
+ * by setting includeDefaults: false in GuardrailManagerOptions.
+ */
+import type { Guardrail } from './types.js';
+/**
+ * Built-in guardrails for dangerous operations
+ */
+export declare const BUILTIN_GUARDRAILS: Guardrail[];
+/**
+ * Get a copy of the built-in guardrails
+ */
+export declare function getBuiltinGuardrails(): Guardrail[];
+/**
+ * Check if a guardrail is a built-in default
+ */
+export declare function isBuiltinGuardrail(guardrail: Guardrail): boolean;
+/**
+ * Get built-in guardrail IDs
+ */
+export declare function getBuiltinGuardrailIds(): string[];
+/**
+ * Get guardrails by tag
+ */
+export declare function getGuardrailsByTag(tag: string): Guardrail[];

package/dist/guardrails/builtin.js

@@ -0,0 +1,223 @@
+/**
+ * Built-in guardrails for common dangerous operations
+ *
+ * These guardrails provide sensible safety defaults that can be disabled
+ * by setting includeDefaults: false in GuardrailManagerOptions.
+ */
+/**
+ * Built-in guardrails for dangerous operations
+ */
+export const BUILTIN_GUARDRAILS = [
+    // ==========================================================================
+    // Git Destructive Operations
+    // ==========================================================================
+    {
+        id: 'git-reset-hard',
+        name: 'Git Hard Reset',
+        description: 'Detects git reset --hard which discards uncommitted changes',
+        patterns: [/git\s+reset\s+--hard/i],
+        action: 'confirm',
+        message: 'git reset --hard will discard all uncommitted changes. Are you sure?',
+        scope: ['bash'],
+        tags: ['builtin', 'git', 'destructive'],
+    },
+    {
+        id: 'git-clean',
+        name: 'Git Clean',
+        description: 'Detects git clean which deletes untracked files',
+        patterns: [/git\s+clean\s+-[fd]/i],
+        action: 'confirm',
+        message: 'git clean will permanently delete untracked files.',
+        scope: ['bash'],
+        tags: ['builtin', 'git', 'destructive'],
+    },
+    {
+        id: 'git-force-push',
+        name: 'Git Force Push',
+        description: 'Detects force push which can overwrite remote history',
+        patterns: [/git\s+push\s+.*--force/i, /git\s+push\s+-f\b/i],
+        action: 'warn',
+        message: 'Force push can overwrite remote history. Verify this is intentional.',
+        scope: ['bash'],
+        tags: ['builtin', 'git', 'destructive'],
+    },
+    {
+        id: 'git-checkout-discard',
+        name: 'Git Checkout Discard',
+        description: 'Detects git checkout -- which discards local changes',
+        patterns: [/git\s+checkout\s+--\s+/i],
+        action: 'warn',
+        message: 'git checkout -- will discard local changes to the specified files.',
+        scope: ['bash'],
+        tags: ['builtin', 'git', 'destructive'],
+    },
+    // ==========================================================================
+    // File System Dangers
+    // ==========================================================================
+    {
+        id: 'rm-rf',
+        name: 'Recursive Delete',
+        description: 'Detects rm -rf which recursively deletes without confirmation',
+        patterns: [/rm\s+-rf\s/i, /rm\s+.*-r.*-f/i, /rm\s+-fr\s/i],
+        action: 'confirm',
+        message: 'Recursive delete detected. Verify the path is correct.',
+        scope: ['bash'],
+        tags: ['builtin', 'filesystem', 'destructive'],
+    },
+    {
+        id: 'rm-root',
+        name: 'Root Delete Protection',
+        description: 'Prevents deletion of root or home directories',
+        patterns: [/rm\s+.*\s+\/($|\s)/, /rm\s+.*\s+~\/($|\s)/, /rm\s+.*\s+\$HOME($|\s|\/)/],
+        action: 'block',
+        message: 'Deletion of root or home directory is blocked.',
+        scope: ['bash'],
+        tags: ['builtin', 'filesystem', 'critical'],
+    },
+    {
+        id: 'chmod-777',
+        name: 'Insecure Permissions',
+        description: 'Detects chmod 777 which gives full access to everyone',
+        patterns: [/chmod\s+777/i, /chmod\s+a\+rwx/i],
+        action: 'warn',
+        message: 'chmod 777 gives full access to everyone. Consider more restrictive permissions.',
+        scope: ['bash'],
+        tags: ['builtin', 'filesystem', 'security'],
+    },
+    // ==========================================================================
+    // Database Dangers
+    // ==========================================================================
+    {
+        id: 'drop-table',
+        name: 'SQL Drop Table',
+        description: 'Detects DROP TABLE statements',
+        patterns: [/DROP\s+TABLE/i],
+        action: 'confirm',
+        message: 'DROP TABLE will permanently delete the table and all its data.',
+        scope: ['bash'],
+        tags: ['builtin', 'database', 'destructive'],
+    },
+    {
+        id: 'truncate-table',
+        name: 'SQL Truncate',
+        description: 'Detects TRUNCATE statements',
+        patterns: [/TRUNCATE\s+TABLE/i, /TRUNCATE\s+\w+/i],
+        action: 'confirm',
+        message: 'TRUNCATE will delete all data from the table.',
+        scope: ['bash'],
+        tags: ['builtin', 'database', 'destructive'],
+    },
+    {
+        id: 'delete-all',
+        name: 'SQL Delete Without WHERE',
+        description: 'Detects DELETE statements without WHERE clause',
+        patterns: [/DELETE\s+FROM\s+\w+\s*;/i, /DELETE\s+FROM\s+\w+\s*$/im],
+        action: 'warn',
+        message: 'DELETE without WHERE clause will delete all rows. Verify this is intentional.',
+        scope: ['bash'],
+        tags: ['builtin', 'database', 'destructive'],
+    },
+    {
+        id: 'drop-database',
+        name: 'SQL Drop Database',
+        description: 'Detects DROP DATABASE statements',
+        patterns: [/DROP\s+DATABASE/i],
+        action: 'block',
+        message: 'DROP DATABASE is blocked. This would delete the entire database.',
+        scope: ['bash'],
+        tags: ['builtin', 'database', 'critical'],
+    },
+    // ==========================================================================
+    // Secrets and Credentials
+    // ==========================================================================
+    {
+        id: 'env-exposure',
+        name: 'Environment Variable Exposure',
+        description: 'Detects commands that might expose secrets',
+        patterns: [
+            /echo\s+\$[A-Z_]*KEY/i,
+            /echo\s+\$[A-Z_]*SECRET/i,
+            /echo\s+\$[A-Z_]*PASSWORD/i,
+            /echo\s+\$[A-Z_]*TOKEN/i,
+            /printenv\s+[A-Z_]*KEY/i,
+            /printenv\s+[A-Z_]*SECRET/i,
+            /printenv\s+[A-Z_]*PASSWORD/i,
+        ],
+        action: 'warn',
+        message: 'This command may expose sensitive environment variables.',
+        scope: ['bash'],
+        tags: ['builtin', 'security', 'secrets'],
+    },
+    {
+        id: 'hardcoded-secrets',
+        name: 'Hardcoded Secrets Detection',
+        description: 'Detects potential hardcoded secrets in commands',
+        patterns: [
+            /password\s*=\s*['"][^'"]+['"]/i,
+            /api_key\s*=\s*['"][^'"]+['"]/i,
+            /secret\s*=\s*['"][^'"]+['"]/i,
+            /token\s*=\s*['"][^'"]+['"]/i,
+        ],
+        action: 'warn',
+        message: 'Potential hardcoded secret detected. Consider using environment variables.',
+        scope: ['bash'],
+        tags: ['builtin', 'security', 'secrets'],
+    },
+    // ==========================================================================
+    // Network and System
+    // ==========================================================================
+    {
+        id: 'curl-pipe-bash',
+        name: 'Curl Pipe to Bash',
+        description: 'Detects piping curl output directly to bash',
+        patterns: [
+            /curl\s+.*\|\s*bash/i,
+            /curl\s+.*\|\s*sh\b/i,
+            /wget\s+.*\|\s*bash/i,
+            /wget\s+.*\|\s*sh\b/i,
+        ],
+        action: 'warn',
+        message: 'Piping remote content directly to shell is risky. Consider downloading and reviewing first.',
+        scope: ['bash'],
+        tags: ['builtin', 'security', 'network'],
+    },
+    {
+        id: 'sudo-dangerous',
+        name: 'Dangerous Sudo Operations',
+        description: 'Detects potentially dangerous sudo commands',
+        patterns: [/sudo\s+rm\s+-rf\s+\//i, /sudo\s+dd\s+/i, /sudo\s+mkfs/i],
+        action: 'confirm',
+        message: 'This sudo command could cause system damage. Verify before proceeding.',
+        scope: ['bash'],
+        tags: ['builtin', 'system', 'critical'],
+    },
+];
+/**
+ * Get a copy of the built-in guardrails
+ */
+export function getBuiltinGuardrails() {
+    return BUILTIN_GUARDRAILS.map((g) => ({
+        ...g,
+        patterns: g.patterns.map((p) => new RegExp(p.source, p.flags)),
+        scope: g.scope ? [...g.scope] : undefined,
+        tags: g.tags ? [...g.tags] : undefined,
+    }));
+}
+/**
+ * Check if a guardrail is a built-in default
+ */
+export function isBuiltinGuardrail(guardrail) {
+    return guardrail.tags?.includes('builtin') ?? false;
+}
+/**
+ * Get built-in guardrail IDs
+ */
+export function getBuiltinGuardrailIds() {
+    return BUILTIN_GUARDRAILS.map((g) => g.id);
+}
+/**
+ * Get guardrails by tag
+ */
+export function getGuardrailsByTag(tag) {
+    return getBuiltinGuardrails().filter((g) => g.tags?.includes(tag));
+}

package/dist/guardrails/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Guardrails module - Pattern-based safety checks for tool execution
+ */
+export { GuardrailManager } from './manager.js';
+export { getBuiltinGuardrails, isBuiltinGuardrail, getBuiltinGuardrailIds, getGuardrailsByTag, BUILTIN_GUARDRAILS, } from './builtin.js';
+export type { Guardrail, GuardrailInput, GuardrailAction, GuardrailResult, GuardrailContext, GuardrailManagerOptions, GuardrailTriggeredHandler, GuardrailEventType, GuardrailEvent, GuardrailEventHandler, } from './types.js';

package/dist/guardrails/index.js

@@ -0,0 +1,5 @@
+/**
+ * Guardrails module - Pattern-based safety checks for tool execution
+ */
+export { GuardrailManager } from './manager.js';
+export { getBuiltinGuardrails, isBuiltinGuardrail, getBuiltinGuardrailIds, getGuardrailsByTag, BUILTIN_GUARDRAILS, } from './builtin.js';

package/dist/guardrails/manager.d.ts

@@ -0,0 +1,117 @@
+/**
+ * GuardrailManager - Pattern-based safety checks for tool execution
+ */
+import type { Guardrail, GuardrailInput, GuardrailResult, GuardrailManagerOptions, GuardrailEventHandler } from './types.js';
+/**
+ * GuardrailManager - Manages pattern-based safety checks for tool execution
+ *
+ * @example
+ * ```typescript
+ * const manager = new GuardrailManager({
+ *   enabled: true,
+ *   includeDefaults: true,
+ *   custom: [
+ *     {
+ *       id: 'no-prod-db',
+ *       name: 'Production Database Protection',
+ *       description: 'Prevent operations on production database',
+ *       patterns: [/prod.*db/i, /production.*database/i],
+ *       action: 'block',
+ *       message: 'Operations on production database are blocked',
+ *     }
+ *   ],
+ *   onTriggered: async (result, context) => {
+ *     if (result.action === 'confirm') {
+ *       return await askUserConfirmation(result.guardrail.message);
+ *     }
+ *     return result.action !== 'block';
+ *   }
+ * });
+ *
+ * // Check before tool execution
+ * const result = manager.check('bash', { command: 'rm -rf /' });
+ * if (result.triggered && result.action === 'block') {
+ *   throw new Error(result.guardrail.message);
+ * }
+ * ```
+ */
+export declare class GuardrailManager {
+    private readonly guardrails;
+    private readonly options;
+    private eventHandler?;
+    constructor(options?: GuardrailManagerOptions);
+    /**
+     * Set the event handler for guardrail events
+     */
+    onEvent(handler: GuardrailEventHandler): void;
+    /**
+     * Add a custom guardrail
+     */
+    add(input: GuardrailInput): Guardrail;
+    /**
+     * Get a guardrail by ID
+     */
+    get(id: string): Guardrail | undefined;
+    /**
+     * Get all guardrails
+     */
+    getAll(): Guardrail[];
+    /**
+     * Get guardrails that apply to a specific tool
+     */
+    getForTool(toolName: string): Guardrail[];
+    /**
+     * Check if a guardrail exists
+     */
+    has(id: string): boolean;
+    /**
+     * Remove a guardrail by ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Enable a guardrail
+     */
+    enable(id: string): boolean;
+    /**
+     * Disable a guardrail
+     */
+    disable(id: string): boolean;
+    /**
+     * Get the number of guardrails
+     */
+    get size(): number;
+    /**
+     * Check if guardrails are enabled
+     */
+    get enabled(): boolean;
+    /**
+     * Enable or disable all guardrails
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check tool input against all applicable guardrails
+     *
+     * @param toolName - Name of the tool being called
+     * @param input - Tool input to check
+     * @returns GuardrailResult indicating if any guardrail was triggered
+     */
+    check(toolName: string, input: unknown): GuardrailResult;
+    /**
+     * Check and handle guardrail triggering
+     *
+     * This method checks the input and calls the onTriggered handler if configured.
+     * Returns true if execution should proceed, false if blocked.
+     *
+     * @param toolName - Name of the tool being called
+     * @param input - Tool input to check
+     * @returns Promise<{ proceed: boolean; result: GuardrailResult }>
+     */
+    checkAndHandle(toolName: string, input: unknown): Promise<{
+        proceed: boolean;
+        result: GuardrailResult;
+    }>;
+    /**
+     * Stringify input for pattern matching
+     */
+    private stringifyInput;
+}