import { OutputGuardrail } from "../types.js";

//#region src/guardrails/builtins/tool-usage-validator.d.ts

/**
 * Shape of one observed tool call. Aligned with `ToolCall` from
 * `@graphorin/core` but decoupled - the validator reads only what it
 * needs so deployments can repurpose it for other shapes.
 *
 * @stable
 */
interface ObservedToolCall {
  readonly toolName: string;
  readonly toolCallId?: string;
  readonly args?: unknown;
}
/**
 * Options for `toolUsageValidator(...)`.
 *
 * @stable
 */
interface ToolUsageValidatorOptions {
  /** Tool names that must appear at least once. */
  readonly requiredTools?: ReadonlyArray<string>;
  /** Tool names that must NOT appear. */
  readonly forbiddenTools?: ReadonlyArray<string>;
  /** Maximum number of total tool invocations. */
  readonly maxCalls?: number;
  /** Maximum number of invocations per tool name. */
  readonly maxPerTool?: number;
  /**
   * Custom predicate. Returning `false` rejects the run with the
   * supplied `message`.
   */
  readonly predicate?: (calls: ReadonlyArray<ObservedToolCall>) => {
    readonly ok: true;
  } | {
    readonly ok: false;
    readonly message: string;
  };
  /** Action on rejection. Defaults to `'block'`. */
  readonly action?: 'block' | 'warn';
  /** Override guardrail name. */
  readonly name?: string;
}
/**
 * Construct the tool-usage validator.
 *
 * @stable
 */
declare function toolUsageValidator(opts?: ToolUsageValidatorOptions): OutputGuardrail<{
  readonly toolCalls?: ReadonlyArray<ObservedToolCall>;
} | unknown>;
//#endregion
export { ObservedToolCall, ToolUsageValidatorOptions, toolUsageValidator };
//# sourceMappingURL=tool-usage-validator.d.ts.map