@compilr-dev/agents 0.0.1

package/dist/guardrails/manager.js

@@ -0,0 +1,288 @@
+/**
+ * GuardrailManager - Pattern-based safety checks for tool execution
+ */
+import { getBuiltinGuardrails } from './builtin.js';
+/**
+ * Default options for GuardrailManager
+ */
+const DEFAULT_OPTIONS = {
+    enabled: true,
+    includeDefaults: true,
+};
+/**
+ * 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 class GuardrailManager {
+    guardrails = new Map();
+    options;
+    eventHandler;
+    constructor(options = {}) {
+        this.options = {
+            ...DEFAULT_OPTIONS,
+            ...options,
+        };
+        // Add built-in guardrails
+        if (this.options.includeDefaults) {
+            for (const guardrail of getBuiltinGuardrails()) {
+                this.guardrails.set(guardrail.id, guardrail);
+            }
+        }
+        // Add custom guardrails
+        if (options.custom) {
+            for (const input of options.custom) {
+                this.add(input);
+            }
+        }
+    }
+    /**
+     * Set the event handler for guardrail events
+     */
+    onEvent(handler) {
+        this.eventHandler = handler;
+    }
+    /**
+     * Add a custom guardrail
+     */
+    add(input) {
+        const guardrail = {
+            ...input,
+            enabled: input.enabled ?? true,
+        };
+        this.guardrails.set(guardrail.id, guardrail);
+        return guardrail;
+    }
+    /**
+     * Get a guardrail by ID
+     */
+    get(id) {
+        return this.guardrails.get(id);
+    }
+    /**
+     * Get all guardrails
+     */
+    getAll() {
+        return Array.from(this.guardrails.values());
+    }
+    /**
+     * Get guardrails that apply to a specific tool
+     */
+    getForTool(toolName) {
+        return this.getAll().filter((g) => {
+            // enabled defaults to true if not set
+            if (g.enabled === false)
+                return false;
+            if (!g.scope || g.scope.length === 0)
+                return true;
+            return g.scope.includes(toolName);
+        });
+    }
+    /**
+     * Check if a guardrail exists
+     */
+    has(id) {
+        return this.guardrails.has(id);
+    }
+    /**
+     * Remove a guardrail by ID
+     */
+    remove(id) {
+        return this.guardrails.delete(id);
+    }
+    /**
+     * Enable a guardrail
+     */
+    enable(id) {
+        const guardrail = this.guardrails.get(id);
+        if (!guardrail)
+            return false;
+        guardrail.enabled = true;
+        return true;
+    }
+    /**
+     * Disable a guardrail
+     */
+    disable(id) {
+        const guardrail = this.guardrails.get(id);
+        if (!guardrail)
+            return false;
+        guardrail.enabled = false;
+        return true;
+    }
+    /**
+     * Get the number of guardrails
+     */
+    get size() {
+        return this.guardrails.size;
+    }
+    /**
+     * Check if guardrails are enabled
+     */
+    get enabled() {
+        return this.options.enabled;
+    }
+    /**
+     * Enable or disable all guardrails
+     */
+    setEnabled(enabled) {
+        this.options.enabled = enabled;
+    }
+    /**
+     * 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, input) {
+        // If guardrails are disabled, allow everything
+        if (!this.options.enabled) {
+            return { triggered: false };
+        }
+        // Stringify the input for pattern matching
+        const inputString = this.stringifyInput(input);
+        // Get guardrails that apply to this tool
+        const applicableGuardrails = this.getForTool(toolName);
+        // Check each guardrail
+        for (const guardrail of applicableGuardrails) {
+            for (const pattern of guardrail.patterns) {
+                const match = inputString.match(pattern);
+                if (match) {
+                    return {
+                        triggered: true,
+                        guardrail,
+                        match: match[0],
+                        action: guardrail.action,
+                        toolName,
+                        input,
+                    };
+                }
+            }
+        }
+        return { triggered: false };
+    }
+    /**
+     * 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 }>
+     */
+    async checkAndHandle(toolName, input) {
+        const result = this.check(toolName, input);
+        if (!result.triggered) {
+            return { proceed: true, result };
+        }
+        const context = {
+            toolName,
+            input,
+            inputString: this.stringifyInput(input),
+        };
+        // Emit event
+        this.eventHandler?.({
+            type: 'guardrail:triggered',
+            result,
+            context,
+        });
+        // Handle based on action
+        switch (result.action) {
+            case 'block':
+                this.eventHandler?.({
+                    type: 'guardrail:blocked',
+                    result,
+                    context,
+                });
+                return { proceed: false, result };
+            case 'confirm':
+                if (this.options.onTriggered) {
+                    const confirmed = await this.options.onTriggered(result, context);
+                    if (confirmed) {
+                        this.eventHandler?.({
+                            type: 'guardrail:confirmed',
+                            result,
+                            context,
+                        });
+                        return { proceed: true, result };
+                    }
+                    else {
+                        this.eventHandler?.({
+                            type: 'guardrail:cancelled',
+                            result,
+                            context,
+                        });
+                        return { proceed: false, result };
+                    }
+                }
+                // No handler configured - block by default for confirm actions
+                return { proceed: false, result };
+            case 'warn':
+                this.eventHandler?.({
+                    type: 'guardrail:warning',
+                    result,
+                    context,
+                });
+                return { proceed: true, result };
+            default:
+                return { proceed: true, result };
+        }
+    }
+    /**
+     * Stringify input for pattern matching
+     */
+    stringifyInput(input) {
+        if (typeof input === 'string') {
+            return input;
+        }
+        if (input === null || input === undefined) {
+            return '';
+        }
+        // For objects, extract common command fields
+        if (typeof input === 'object') {
+            const obj = input;
+            // Common command field names
+            const commandFields = ['command', 'cmd', 'script', 'query', 'sql', 'content'];
+            for (const field of commandFields) {
+                const value = obj[field];
+                if (typeof value === 'string') {
+                    return value;
+                }
+            }
+            // Fallback to JSON
+            return JSON.stringify(input);
+        }
+        // For primitives (number, boolean, etc.)
+        return typeof input === 'string' ? input : JSON.stringify(input);
+    }
+}

package/dist/guardrails/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Guardrails - Pattern-based detection of risky operations
+ *
+ * Guardrails scan tool inputs/commands before execution, match against
+ * known dangerous patterns, and emit warnings or block execution.
+ */
+/**
+ * Action to take when a guardrail is triggered
+ * - warn: Log warning but proceed with execution
+ * - confirm: Require confirmation before proceeding
+ * - block: Prevent execution entirely
+ */
+export type GuardrailAction = 'warn' | 'confirm' | 'block';
+/**
+ * A guardrail definition
+ */
+export interface Guardrail {
+    /**
+     * Unique identifier for this guardrail
+     */
+    id: string;
+    /**
+     * Human-readable name
+     */
+    name: string;
+    /**
+     * Description of what this guardrail protects against
+     */
+    description: string;
+    /**
+     * Patterns to match against tool inputs
+     */
+    patterns: RegExp[];
+    /**
+     * Action to take when triggered
+     */
+    action: GuardrailAction;
+    /**
+     * Message to display when triggered
+     */
+    message: string;
+    /**
+     * Which tools this guardrail applies to (empty = all tools)
+     */
+    scope?: string[];
+    /**
+     * Whether this guardrail is enabled (default: true)
+     */
+    enabled?: boolean;
+    /**
+     * Tags for grouping/filtering guardrails
+     */
+    tags?: string[];
+}
+/**
+ * Input for adding a custom guardrail
+ */
+export interface GuardrailInput {
+    id: string;
+    name: string;
+    description: string;
+    patterns: RegExp[];
+    action: GuardrailAction;
+    message: string;
+    scope?: string[];
+    enabled?: boolean;
+    tags?: string[];
+}
+/**
+ * Result of checking a guardrail
+ */
+export interface GuardrailResult {
+    /**
+     * Whether any guardrail was triggered
+     */
+    triggered: boolean;
+    /**
+     * The guardrail that was triggered (if any)
+     */
+    guardrail?: Guardrail;
+    /**
+     * The matched pattern (if any)
+     */
+    match?: string;
+    /**
+     * The action to take
+     */
+    action?: GuardrailAction;
+    /**
+     * The tool that triggered the guardrail
+     */
+    toolName?: string;
+    /**
+     * The input that triggered the guardrail
+     */
+    input?: unknown;
+}
+/**
+ * Context passed to guardrail handlers
+ */
+export interface GuardrailContext {
+    /**
+     * The tool being called
+     */
+    toolName: string;
+    /**
+     * The tool input
+     */
+    input: unknown;
+    /**
+     * The stringified input used for pattern matching
+     */
+    inputString: string;
+}
+/**
+ * Handler called when a guardrail is triggered
+ *
+ * @param result - The guardrail check result
+ * @param context - Context about the tool call
+ * @returns true to proceed with execution, false to block
+ */
+export type GuardrailTriggeredHandler = (result: GuardrailResult, context: GuardrailContext) => boolean | Promise<boolean>;
+/**
+ * Configuration for the GuardrailManager
+ */
+export interface GuardrailManagerOptions {
+    /**
+     * Enable guardrails (default: true)
+     */
+    enabled?: boolean;
+    /**
+     * Custom guardrails to add
+     */
+    custom?: GuardrailInput[];
+    /**
+     * Include built-in guardrails (default: true)
+     */
+    includeDefaults?: boolean;
+    /**
+     * Handler called when a guardrail is triggered
+     */
+    onTriggered?: GuardrailTriggeredHandler;
+}
+/**
+ * Event types for guardrail operations
+ */
+export type GuardrailEventType = 'guardrail:triggered' | 'guardrail:warning' | 'guardrail:blocked' | 'guardrail:confirmed' | 'guardrail:cancelled';
+/**
+ * Guardrail event payload
+ */
+export interface GuardrailEvent {
+    type: GuardrailEventType;
+    result: GuardrailResult;
+    context: GuardrailContext;
+}
+/**
+ * Event handler for guardrail events
+ */
+export type GuardrailEventHandler = (event: GuardrailEvent) => void;

package/dist/guardrails/types.js

@@ -0,0 +1,7 @@
+/**
+ * Guardrails - Pattern-based detection of risky operations
+ *
+ * Guardrails scan tool inputs/commands before execution, match against
+ * known dangerous patterns, and emit warnings or block execution.
+ */
+export {};

package/dist/hooks/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hooks System - Lifecycle hooks for agent customization
+ *
+ * @example
+ * ```typescript
+ * import { HooksManager, HooksConfig } from '@compilr-dev/agents';
+ *
+ * // Configure hooks
+ * const hooks: HooksConfig = {
+ *   beforeTool: [
+ *     async (ctx) => {
+ *       console.log(`Tool ${ctx.toolName} starting...`);
+ *     }
+ *   ],
+ *   afterTool: [
+ *     async (ctx) => {
+ *       console.log(`Tool ${ctx.toolName} completed in ${ctx.durationMs}ms`);
+ *     }
+ *   ]
+ * };
+ *
+ * // Use with Agent
+ * const agent = new Agent({
+ *   provider,
+ *   hooks,
+ * });
+ * ```
+ */
+export { HooksManager } from './manager.js';
+export type { HooksManagerOptions } from './manager.js';
+export type { HooksConfig, HookRegistrationOptions, HookContext, IterationHookContext, LLMHookContext, AfterLLMHookContext, ToolHookContext, AfterToolHookContext, ErrorHookContext, BeforeIterationHook, AfterIterationHook, BeforeLLMHook, AfterLLMHook, BeforeToolHook, AfterToolHook, OnErrorHook, BeforeLLMHookResult, BeforeToolHookResult, AfterToolHookResult, ErrorHookResult, RegisteredHook, HookEventType, HookEvent, HookEventHandler, } from './types.js';

package/dist/hooks/index.js

@@ -0,0 +1,29 @@
+/**
+ * Hooks System - Lifecycle hooks for agent customization
+ *
+ * @example
+ * ```typescript
+ * import { HooksManager, HooksConfig } from '@compilr-dev/agents';
+ *
+ * // Configure hooks
+ * const hooks: HooksConfig = {
+ *   beforeTool: [
+ *     async (ctx) => {
+ *       console.log(`Tool ${ctx.toolName} starting...`);
+ *     }
+ *   ],
+ *   afterTool: [
+ *     async (ctx) => {
+ *       console.log(`Tool ${ctx.toolName} completed in ${ctx.durationMs}ms`);
+ *     }
+ *   ]
+ * };
+ *
+ * // Use with Agent
+ * const agent = new Agent({
+ *   provider,
+ *   hooks,
+ * });
+ * ```
+ */
+export { HooksManager } from './manager.js';

package/dist/hooks/manager.d.ts

@@ -0,0 +1,147 @@
+/**
+ * HooksManager - Manages lifecycle hooks for agent customization
+ *
+ * Provides:
+ * - Hook registration with priorities
+ * - Sequential execution in priority order
+ * - Type-safe hook invocation
+ * - Error handling and recovery
+ */
+import type { HooksConfig, IterationHookContext, LLMHookContext, AfterLLMHookContext, ToolHookContext, AfterToolHookContext, ErrorHookContext, BeforeIterationHook, AfterIterationHook, BeforeLLMHook, AfterLLMHook, BeforeToolHook, AfterToolHook, OnErrorHook, ErrorHookResult, HookRegistrationOptions, HookEventHandler } from './types.js';
+import type { Message } from '../providers/types.js';
+import type { ToolDefinition, ToolExecutionResult } from '../tools/types.js';
+/**
+ * Options for creating a HooksManager
+ */
+export interface HooksManagerOptions {
+    /**
+     * Initial hooks configuration
+     */
+    hooks?: HooksConfig;
+    /**
+     * Event handler for hook lifecycle events
+     */
+    onEvent?: HookEventHandler;
+}
+/**
+ * Manages lifecycle hooks for agent customization
+ */
+export declare class HooksManager {
+    private beforeIterationHooks;
+    private afterIterationHooks;
+    private beforeLLMHooks;
+    private afterLLMHooks;
+    private beforeToolHooks;
+    private afterToolHooks;
+    private onErrorHooks;
+    private readonly onEvent?;
+    private hookIdCounter;
+    constructor(options?: HooksManagerOptions);
+    /**
+     * Register hooks from a configuration object
+     */
+    registerFromConfig(config: HooksConfig): void;
+    /**
+     * Register a before:iteration hook
+     */
+    registerBeforeIteration(hook: BeforeIterationHook, options?: HookRegistrationOptions): string;
+    /**
+     * Register an after:iteration hook
+     */
+    registerAfterIteration(hook: AfterIterationHook, options?: HookRegistrationOptions): string;
+    /**
+     * Register a before:llm hook
+     */
+    registerBeforeLLM(hook: BeforeLLMHook, options?: HookRegistrationOptions): string;
+    /**
+     * Register an after:llm hook
+     */
+    registerAfterLLM(hook: AfterLLMHook, options?: HookRegistrationOptions): string;
+    /**
+     * Register a before:tool hook
+     */
+    registerBeforeTool(hook: BeforeToolHook, options?: HookRegistrationOptions): string;
+    /**
+     * Register an after:tool hook
+     */
+    registerAfterTool(hook: AfterToolHook, options?: HookRegistrationOptions): string;
+    /**
+     * Register an onError hook
+     */
+    registerOnError(hook: OnErrorHook, options?: HookRegistrationOptions): string;
+    /**
+     * Unregister a hook by ID
+     */
+    unregister(hookId: string): boolean;
+    /**
+     * Clear all hooks
+     */
+    clear(): void;
+    /**
+     * Run before:iteration hooks
+     *
+     * @returns true to continue, false to skip iteration
+     */
+    runBeforeIteration(context: IterationHookContext): Promise<boolean>;
+    /**
+     * Run after:iteration hooks
+     */
+    runAfterIteration(context: IterationHookContext & {
+        toolCalls: Array<{
+            name: string;
+            input: Record<string, unknown>;
+            result: ToolExecutionResult;
+        }>;
+        completedWithText: boolean;
+    }): Promise<void>;
+    /**
+     * Run before:llm hooks
+     *
+     * @returns potentially modified messages and tools
+     */
+    runBeforeLLM(context: LLMHookContext): Promise<{
+        messages: Message[];
+        tools: ToolDefinition[];
+    }>;
+    /**
+     * Run after:llm hooks
+     */
+    runAfterLLM(context: AfterLLMHookContext): Promise<void>;
+    /**
+     * Run before:tool hooks
+     *
+     * @returns whether to proceed and potentially modified input or skip result
+     */
+    runBeforeTool(context: ToolHookContext): Promise<{
+        proceed: boolean;
+        input: Record<string, unknown>;
+        skipResult?: ToolExecutionResult;
+    }>;
+    /**
+     * Run after:tool hooks
+     *
+     * @returns potentially modified result
+     */
+    runAfterTool(context: AfterToolHookContext): Promise<ToolExecutionResult>;
+    /**
+     * Run onError hooks
+     *
+     * @returns error handling result
+     */
+    runOnError(context: ErrorHookContext): Promise<ErrorHookResult>;
+    /**
+     * Check if any hooks are registered
+     */
+    hasHooks(): boolean;
+    /**
+     * Get hook counts by type
+     */
+    getHookCounts(): Record<keyof HooksConfig, number>;
+    /**
+     * Get all registered hook IDs
+     */
+    getHookIds(): string[];
+    private generateId;
+    private sortByPriority;
+    private emitEvent;
+}