/** * 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 * * For inputs with a `command` field (e.g. bash tool), automatically * parses compound commands and checks each subcommand independently. * * @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 a compound shell command against guardrails. * * Parses the command into subcommands (splitting on |, &&, ||, ;) * and validates each independently. Also checks the full command string * to catch cross-subcommand patterns (e.g. `curl ... | bash`). * Returns the highest-severity match with subcommand context. * * @param toolName - Name of the tool being called * @param command - The shell command string * @param originalInput - The original tool input (for result metadata) * @returns GuardrailResult indicating if any guardrail was triggered */ checkCommand(toolName: string, command: string, originalInput?: unknown): GuardrailResult; /** * Check an input string against all applicable guardrail patterns */ private checkPatterns; /** * 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; }