/**
 * FailoverError — uniform terminal error after all candidate provider/model
 * attempts have failed.
 *
 * Used by capability runtimes (image / audio / video) so that:
 *   - the agent surface gets a single error message
 *   - the tool layer can serialize structured `attempts` for the LLM and UI
 *   - downstream code can reason about a "reason" enum instead of parsing
 *     vendor-specific status codes.
 *
 * Step 1: pure model. Step 2 wires it into the new image-generation runtime.
 */
/**
 * Coarse failure category. UI / LLM should branch on this rather than
 * `error.message`.
 */
export type FailoverReason = 'timeout' | 'aborted' | 'auth' | 'rate_limit' | 'bad_request' | 'not_found' | 'server_error' | 'network' | 'capability_unsupported' | 'config' | 'unknown';
/** One attempt against a single provider/model. */
export interface FallbackAttempt {
    /** Provider id, e.g. "openai". */
    provider: string;
    /** Model id, e.g. "gpt-image-2". */
    model: string;
    /** Short, human-readable failure summary. */
    error: string;
    /** Coarse category. */
    reason: FailoverReason;
    /** HTTP status when applicable. */
    status?: number;
    /** Vendor-specific code when assertOk could parse one. */
    code?: string;
    /** Wall-clock duration of this attempt in ms. */
    durationMs?: number;
}
export interface FailoverErrorInit {
    /** Capability that failed, e.g. "image-generation", "tts". */
    capability: string;
    /** Ordered attempts that ran. */
    attempts: FallbackAttempt[];
    /** Optional final aggregate message; default summarises attempts. */
    message?: string;
    /** Last underlying error for `cause` chain. */
    cause?: unknown;
}
export declare class FailoverError extends Error {
    readonly capability: string;
    readonly attempts: ReadonlyArray<FallbackAttempt>;
    /** Convenience: reason from the last attempt, or 'unknown' if empty. */
    readonly reason: FailoverReason;
    /** Convenience: status from the last attempt. */
    readonly status?: number;
    /** Convenience: code from the last attempt. */
    readonly code?: string;
    /** Convenience: provider from the last attempt. */
    readonly provider?: string;
    /** Convenience: model from the last attempt. */
    readonly model?: string;
    constructor(init: FailoverErrorInit);
}
/** Cross-realm-safe predicate (instanceof breaks across vm boundaries). */
export declare function isFailoverError(e: unknown): e is FailoverError;
/**
 * Pretty multi-line description for logs / CLI output. Each line is
 * `<i>. <provider>/<model> [<reason>] (status=<n>): <error>`.
 */
export declare function describeFailoverError(e: FailoverError): string;
/**
 * Map an HTTP status to a {@link FailoverReason}.
 */
export declare function reasonFromHttpStatus(status: number | undefined): FailoverReason;
/**
 * Best-effort classifier from an arbitrary thrown value into a
 * {@link FallbackAttempt}-friendly shape.
 */
export declare function classifyAttemptError(e: unknown): {
    reason: FailoverReason;
    status?: number;
    code?: string;
    message: string;
};