ai-sdk-guardrails/dist/guardrails/tools.d.cts

Input and output guardrails middleware for Vercel AI SDK.

import { A as AIResult, n as GuardrailRetryConfig, O as OutputGuardrail } from '../types-C7t6e3EI.cjs';
import 'ai';
import '@ai-sdk/provider';

/**
 * Metadata returned by the expectedToolUse guardrail.
 * Used for type-safe access in getRetryInstruction and buildRetryParams.
 */
interface ExpectedToolUseMetadata extends Record<string, unknown> {
    expectedTools: string[];
    observedTools: string[];
    observedMarkers: string[];
    missingTools: string[];
    detection: string;
}
interface ExpectedToolUseOptions {
    /** One or more tool names that must be used. */
    tools: string | string[];
    /** Whether all tools must be observed. If false, any match passes. Default: true */
    requireAll?: boolean;
    /**
     * Detection mode:
     * - 'auto': try provider metadata, then text markers (default)
     * - 'provider': provider metadata only
     * - 'marker': text marker(s) only
     */
    mode?: 'auto' | 'provider' | 'marker';
    /**
     * Build one or more markers to search for in the final text output for each tool.
     * Default marker builder: (t) => `TOOL_USED: ${t}`
     */
    textMarkers?: ((tool: string) => string | string[]) | string[];
    /**
     * Optional custom extractor to read tool call names from the raw AIResult.
     * Return an array of tool names observed.
     */
    providerExtractor?: (result: AIResult) => string[];
    /**
     * Retry configuration for this guardrail.
     * When specified, enables automatic retry with context-aware instructions.
     *
     * @example
     * ```typescript
     * expectedToolUse({
     *   tools: 'calculator',
     *   retry: { maxRetries: 2 }
     * })
     * ```
     */
    retry?: GuardrailRetryConfig;
}
/**
 * Best-effort extraction of observed tool-call names from an AI result, checking
 * the AI SDK `content` array, a `toolCalls` array, and common provider-metadata
 * spots. Shared by the tool guardrails and the plan-risk guardrail.
 */
declare function extractToolNamesFromResult(result: AIResult): string[];
/**
 * Guardrail that verifies evidence of expected tool usage.
 *
 * **Improved DX in v5.0:** Now supports guardrail-level retry configuration
 * with context-aware retry instructions.
 *
 * @example Simple usage
 * ```typescript
 * expectedToolUse({ tools: 'calculator' })
 * ```
 *
 * @example With retry (new in v5.0)
 * ```typescript
 * expectedToolUse({
 *   tools: 'calculator',
 *   retry: { maxRetries: 2 }
 * })
 * ```
 *
 * @example Multiple tools
 * ```typescript
 * expectedToolUse({
 *   tools: ['search', 'browser'],
 *   requireAll: false
 * })
 * ```
 */
declare function expectedToolUse(options: ExpectedToolUseOptions): OutputGuardrail<ExpectedToolUseMetadata>;
/**
 * Tool-call/egress policy guardrail that controls which tools can be called
 * and validates parameters and URLs for security
 */
interface ToolEgressPolicyOptions {
    /** List of allowed tool names. If empty, all tools are allowed */
    allowedTools?: string[];
    /** List of denied tool names */
    deniedTools?: string[];
    /** Allowed hosts for URL parameters */
    allowedHosts?: string[];
    /** Blocked hosts for URL parameters */
    blockedHosts?: string[];
    /** Parameter validation rules */
    parameterRules?: {
        [toolName: string]: {
            allowedParams?: string[];
            deniedParams?: string[];
            maxParamLength?: number;
        };
    };
    /** Whether to scan parameter values for URLs */
    scanForUrls?: boolean;
    /** Whether to allow file:// URLs */
    allowFileUrls?: boolean;
    /** Whether to allow localhost/127.0.0.1 URLs */
    allowLocalhost?: boolean;
}
declare function toolEgressPolicy(options?: ToolEgressPolicyOptions): OutputGuardrail;

export { type ExpectedToolUseMetadata, type ExpectedToolUseOptions, type ToolEgressPolicyOptions, expectedToolUse, extractToolNamesFromResult, toolEgressPolicy };