import type { TurnMiddleware } from "./turn-middleware.js";
/**
 * Information passed to the optional `onFallback` callback when a
 * candidate model fails and the middleware advances to the next.
 */
export interface ModelFallbackTransition {
    fromProvider: string;
    fromModel: string;
    error: unknown;
    /** 1-indexed attempt that failed (1 = primary, 2 = first fallback, ...). */
    attempt: number;
    /** Total candidates the middleware will try before giving up. */
    total: number;
}
export interface WithModelFallbackOptions {
    /**
     * Fires once per FAILED candidate, before the middleware moves to the
     * next. Equivalent to `cb.onFallback` from AgentTurnCallbacks but
     * structured for the middleware layer.
     */
    onFallback?: (transition: ModelFallbackTransition) => void | Promise<void>;
}
/**
 * Middleware that iterates fallback model candidates around the inner
 * TurnRunner. When `params.fallbackModels` is empty/undefined, this
 * middleware is a no-op pass-through.
 *
 * On each attempt the inner runner is called with the candidate's
 * `provider` and `modelId` substituted, and `fallbackModels` cleared so
 * the inner runner does not double-iterate.
 *
 * In addition to the optional `opts.onFallback` (explicit telemetry hook),
 * the middleware ALSO bridges fallback transitions to
 * `params.callbacks?.onFallback?(fromModel, "(next)", reason)` — that's
 * the AgentTurnCallbacks signature the production agent-runner-execution
 * chain expects today. Both hooks fire on every transition; either or
 * both may be unset.
 */
export declare function withModelFallback(opts?: WithModelFallbackOptions): TurnMiddleware;
