export type FallbackTriggerClass = "rate_limit" | "quota" | "auth" | "server" | "unknown" | "other";
/**
 * Refinement of an `auth` trigger.
 *
 * The transport deliberately collapses HTTP 401 and 403 into a single `auth`
 * class, but the two demand opposite handling: a credential problem may be
 * recoverable by trying a different stored credential, whereas a plain
 * `forbidden` is an authorization or configuration defect that rotation would
 * only hide — it would cycle and block every otherwise-healthy credential.
 *
 * This is a refinement rather than a new {@link FallbackTriggerClass} member so
 * every existing `trigger.class === "auth"` consumer keeps compiling and keeps
 * its current behavior until it explicitly opts into the distinction.
 */
export type AuthDisposition = "credential" | "forbidden";
export interface FallbackTrigger {
    class: FallbackTriggerClass;
    retryAfterMs?: number;
    /** Present only when `class === "auth"`. */
    authDisposition?: AuthDisposition;
}
/** Stable code for streams that time out before producing semantic progress. */
export declare const STREAM_FIRST_EVENT_TIMEOUT_PROVIDER_CODE = "stream_first_event_timeout";
/** Stable code for a nominally successful response with no content or token usage. */
export declare const EMPTY_RESPONSE_PROVIDER_CODE = "empty_response";
export type TransportHeaders = Headers | Record<string, string | undefined>;
/**
 * Structured facts from an upstream HTTP or transport failure. Retry decisions
 * must use these facts rather than provider- or application-owned error text.
 *
 * `headers` is always a plain record limited to the retained retry-signal
 * entries: facts travel on persisted `AssistantMessage`s and through
 * `structuredClone` snapshots (managed fallback attempt staging), so they must
 * never carry a live `Headers` instance — cloning one throws `DataCloneError`
 * ("The object can not be cloned.") and masks the real provider failure.
 */
export interface TransportFailureFacts {
    kind: "transport";
    status?: number;
    /** Canonical provider error code used for fallback classification. */
    providerCode?: string;
    /** Anthropic's typed `error.type`, preserved separately at the transport boundary. */
    anthropicErrorType?: string;
    /** OpenAI's typed `error.code`, preserved separately at the transport boundary. */
    openaiErrorCode?: string;
    headers?: Record<string, string>;
    /** Safe request-size observation for retry amplification policy. Never contains body content. */
    requestBytes?: number;
    /** Time spent waiting for the first semantic stream event on the failed request. */
    firstEventElapsedMs?: number;
    /** Configured first-event window before any bounded endpoint grace. */
    firstEventTimeoutMs?: number;
    /** Coarse endpoint class; deliberately excludes host, path, credentials, and query parameters. */
    endpointClass?: "canonical" | "custom";
    /** Provider-supplied ceiling for total attempts, including the initial request. */
    retryMaxAttempts?: number;
}
/** Opaque per-invocation marker required by managed fallback transport calls. */
export interface FallbackAttemptToken {
    readonly modelKey: string;
    readonly attemptId: string | number;
}
/**
 * Marks a single outer fallback invocation. Accounting belongs to the caller;
 * this token prevents managed transport calls from silently bypassing it.
 */
export declare function beginAttempt(modelKey: string, attemptId: string | number): FallbackAttemptToken;
export declare function assertManagedAttempt(options: {
    fallbackManaged?: boolean;
    fallbackAttempt?: FallbackAttemptToken;
} | undefined): void;
/**
 * Compatibility input for callers that have not yet wrapped their HTTP facts
 * in the discriminated form. Only its structured fields are inspected.
 */
export interface FallbackTriggerInput {
    status?: number;
    providerCode?: string;
    code?: string;
    headers?: TransportHeaders;
    response?: {
        status?: number;
        headers?: TransportHeaders;
    };
    error?: {
        code?: string;
        type?: string;
    };
}
/** Extracts only explicit HTTP/transport metadata; it never parses error text. */
export declare function transportFailureFacts(error: unknown, capturedResponse?: {
    status?: number;
    headers?: TransportHeaders;
}): TransportFailureFacts | undefined;
/** Classifies only typed upstream transport facts without consuming response bodies. */
export declare function classifyFallbackTrigger(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): FallbackTrigger;
/**
 * True when a failure is an `auth` failure that must NOT rotate credentials.
 *
 * Callers that mutate credential state on auth failures should consult this
 * first so a plain `forbidden` cannot block otherwise-healthy credentials.
 */
export declare function isForbiddenAuthFailure(errorOrFacts: TransportFailureFacts | FallbackTriggerInput | unknown): boolean;