veto-sdk 1.0.0

package/dist/core/veto.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Main Veto guardrail class.
+ *
+ * This is the primary entry point for using Veto. It automatically loads
+ * configuration and rules from the veto/ directory and validates tool calls.
+ *
+ * @module core/veto
+ */
+import type { ToolDefinition, ToolCall } from '../types/tool.js';
+import type { Validator, NamedValidator, LogLevel } from '../types/config.js';
+import { type HistoryStats } from './history.js';
+import { ToolCallDeniedError, type InterceptionResult } from './interceptor.js';
+import type { Rule } from '../rules/types.js';
+import { KernelClient } from '../kernel/client.js';
+/**
+ * Veto operating mode.
+ * - "strict": Block tool calls when validation fails
+ * - "log": Only log validation failures, allow tool calls to proceed
+ */
+export type VetoMode = 'strict' | 'log';
+/**
+ * Validation mode - how tool calls are validated.
+ * - "api": Use external HTTP API for validation
+ * - "kernel": Use local kernel model via Ollama
+ */
+export type ValidationMode = 'api' | 'kernel';
+/**
+ * Wrapped handler function type.
+ */
+export type WrappedHandler = (args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Result of wrapping tools with Veto.
+ */
+export interface WrappedTools {
+    /** Tool definitions (schemas) to pass to AI models */
+    definitions: ToolDefinition[];
+    /** Wrapped handler functions keyed by tool name */
+    implementations: Record<string, WrappedHandler>;
+}
+/**
+ * Options for creating a Veto instance.
+ */
+export interface VetoOptions {
+    /**
+     * Path to the veto directory containing config and rules.
+     * Defaults to './veto' relative to current working directory.
+     */
+    configDir?: string;
+    /**
+     * Override the operating mode.
+     * - "strict": Block tool calls when validation fails
+     * - "log": Only log validation failures, allow tool calls to proceed
+     */
+    mode?: VetoMode;
+    /**
+     * Override log level.
+     * Can also be set via VETO_LOG_LEVEL environment variable.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Session ID for tracking.
+     * Can also be set via VETO_SESSION_ID environment variable.
+     */
+    sessionId?: string;
+    /**
+     * Agent ID for tracking.
+     * Can also be set via VETO_AGENT_ID environment variable.
+     */
+    agentId?: string;
+    /**
+     * Additional validators to run alongside rule-based validation.
+     */
+    validators?: (Validator | NamedValidator)[];
+    /**
+     * Injected kernel client for testing or custom configurations.
+     */
+    kernelClient?: KernelClient;
+}
+/**
+ * Veto - A guardrail system for AI agent tool calls.
+ *
+ * Veto automatically loads configuration from the veto/ directory and
+ * validates tool calls against defined rules via an external API.
+ *
+ * @example
+ * ```typescript
+ * import { Veto } from 'veto';
+ *
+ * // Initialize Veto (loads config from ./veto automatically)
+ * const veto = await Veto.init();
+ *
+ * // Wrap your tools
+ * const wrappedTools = veto.wrapTools(myTools);
+ *
+ * // Pass to AI provider, then validate calls
+ * const result = await veto.validateToolCall(toolCall);
+ * ```
+ */
+export declare class Veto {
+    private readonly logger;
+    private readonly validationEngine;
+    private readonly historyTracker;
+    private readonly interceptor;
+    private readonly registeredTools;
+    private readonly configDir;
+    private readonly mode;
+    private readonly validationMode;
+    private readonly apiBaseUrl;
+    private readonly apiEndpoint;
+    private readonly apiTimeout;
+    private readonly apiRetries;
+    private readonly apiRetryDelay;
+    private readonly sessionId?;
+    private readonly agentId?;
+    private kernelClient;
+    private readonly kernelConfig;
+    private readonly rules;
+    private constructor();
+    /**
+     * Initialize Veto by loading configuration and rules.
+     *
+     * @param options - Initialization options
+     * @returns Initialized Veto instance
+     *
+     * @example
+     * ```typescript
+     * // Use defaults (loads from ./veto)
+     * const veto = await Veto.init();
+     *
+     * // Custom config directory
+     * const veto = await Veto.init({ configDir: './my-veto-config' });
+     *
+     * // Override API URL
+     * const veto = await Veto.init({ apiBaseUrl: 'https://api.example.com' });
+     * ```
+     */
+    static init(options?: VetoOptions): Promise<Veto>;
+    /**
+     * Load rules from YAML files.
+     */
+    private static loadRules;
+    /**
+     * Find YAML files in a directory.
+     */
+    private static findYamlFiles;
+    /**
+     * Get rules applicable to a tool.
+     */
+    private getRulesForTool;
+    /**
+     * Validate a tool call with the external API.
+     */
+    private validateWithAPI;
+    /**
+     * Make the API request.
+     */
+    private makeAPIRequest;
+    /**
+     * Handle successful API response.
+     */
+    private handleAPIResponse;
+    /**
+     * Handle API failure. In log mode, always allow. In strict mode, block.
+     */
+    private handleAPIFailure;
+    /**
+     * Get or create the kernel client.
+     */
+    private getKernelClient;
+    /**
+     * Validate a tool call with the local kernel model.
+     */
+    private validateWithKernel;
+    /**
+     * Handle successful kernel response.
+     */
+    private handleKernelResponse;
+    /**
+     * Handle kernel failure. In log mode, always allow. In strict mode, block.
+     */
+    private handleKernelFailure;
+    /**
+     * Build history summary for API.
+     */
+    private buildHistorySummary;
+    /**
+     * Delay helper.
+     */
+    private delay;
+    /**
+     * Wrap tools for use with an AI provider.
+     *
+     * Returns an object containing:
+     * - `definitions`: Tool schemas to pass to the AI model
+     * - `implementations`: Object with wrapped handler functions keyed by tool name
+     *
+     * @param tools - Tools to wrap (must have handlers)
+     * @returns Object with toolDefinitions and toolImplementations
+     *
+     * @example
+     * ```typescript
+     * const tools = [
+     *   {
+     *     name: 'read_file',
+     *     inputSchema: { type: 'object', properties: { path: { type: 'string' } } },
+     *     handler: async (args) => fs.readFileSync(args.path, 'utf-8')
+     *   }
+     * ];
+     *
+     * const veto = await Veto.init();
+     * const { definitions, implementations } = veto.wrapTools(tools);
+     *
+     * // Pass definitions to AI model
+     * const response = await openai.chat.completions.create({
+     *   tools: toOpenAITools(definitions),
+     *   ...
+     * });
+     *
+     * // Execute tool calls using implementations
+     * const result = await implementations.read_file({ path: '/home/user/file.txt' });
+     * ```
+     */
+    wrapTools(tools: readonly ToolDefinition[]): WrappedTools;
+    /**
+     * Validate a tool call.
+     *
+     * @param call - The tool call to validate
+     * @returns Validation result
+     */
+    validateToolCall(call: ToolCall): Promise<InterceptionResult>;
+    /**
+     * Validate a tool call and throw if denied.
+     *
+     * @param call - The tool call to validate
+     * @returns Validation result (only if allowed)
+     * @throws {ToolCallDeniedError} If the call is denied
+     */
+    validateToolCallOrThrow(call: ToolCall): Promise<InterceptionResult>;
+    /**
+     * Get registered tools.
+     */
+    getRegisteredTools(): readonly ToolDefinition[];
+    /**
+     * Get loaded rules.
+     */
+    getLoadedRules(): readonly Rule[];
+    /**
+     * Get current operating mode.
+     */
+    getMode(): VetoMode;
+    /**
+     * Get current validation mode (api or kernel).
+     */
+    getValidationMode(): ValidationMode;
+    /**
+     * Get history statistics.
+     */
+    getHistoryStats(): HistoryStats;
+    /**
+     * Clear call history.
+     */
+    clearHistory(): void;
+}
+export { ToolCallDeniedError };
+//# sourceMappingURL=veto.d.ts.map

package/dist/core/veto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"veto.d.ts","sourceRoot":"","sources":["../../src/core/veto.ts"],"names":[],"mappings":"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"}