import type { CompletionRequest, ReasoningEffort, ReasoningPreference } from "../types.js";
/**
 * Gradual reasoning-effort fallback ladder.
 *
 * When a provider rejects a reasoning knob (e.g. `reasoning_effort`), we do
 * not immediately strip reasoning. Instead we walk down the ladder to the
 * nearest commonly-supported effort, and only strip reasoning entirely once
 * every candidate has been rejected. This keeps reasoning quality when the
 * model merely does not support the *highest* requested depth, while still
 * degrading gracefully for models that reject the knob altogether.
 *
 * The ladder is expressed in clai's internal effort levels; the provider's
 * `buildReasoningPayload` maps them onto the wire values it actually accepts.
 */
/** Canonical descending ladder (highest → lowest commonly-supported). */
export declare const EFFORT_LADDER: readonly ReasoningEffort[];
/**
 * Ordered fallback efforts for a rejected `requested` effort, nearest first.
 *
 * Only the extended efforts above "high" have a meaningful fallback: a gateway
 * that rejects "max"/"xhigh" usually still accepts the classic low/medium/high
 * set. Everything else strips reasoning immediately rather than walking a long
 * ladder — a long ladder can loop against a gateway that 503s reasoning-enabled
 * requests (each rung re-triggers the same server error instead of progressing).
 */
export declare function fallbackEffortsFor(requested: ReasoningEffort): ReasoningEffort[];
/**
 * Deduplicated candidate efforts to try, starting with the requested effort
 * and followed by its fallback ladder.
 */
export declare function effortCandidates(thinking: ReasoningPreference | undefined): ReasoningEffort[];
/**
 * Detects a provider error that means the model rejected a reasoning *effort*
 * value (as opposed to a transient/network error). Mirrors the stricter
 * wording providers use for "value must be one of …" rejections.
 */
export declare function isEffortRejectedError(error: unknown): boolean;
/**
 * Runs `attempt` once per candidate effort, catching effort-value rejections
 * and moving to the next candidate. Non-effort errors propagate immediately.
 * When every candidate is rejected, the last error is rethrown (the caller's
 * router then strips reasoning entirely).
 */
export declare function withEffortFallback<T>(request: CompletionRequest, attempt: (thinking: CompletionRequest["thinking"]) => Promise<T>, onExhausted: () => never): Promise<T>;