import type { CompletionRequest, CompletionResult, ProviderId, SuccessfulRequestSnapshot } from "../types.js";
import { ProviderError } from "./http.js";
import type { ReasoningEffort } from "../types.js";
import { type ProviderStreamEventSink } from "./stream-events.js";
import { type ProviderKeyEvent } from "./key-rotation.js";
import type { LlmProvider, ProviderAuth } from "./provider.js";
import { OperationUsageRecorder, type OperationUsageSnapshot } from "./operation-usage.js";
import { OperationLedger } from "./operation-ledger.js";
/** Toast replace-key so key rotation never stacks notifications. */
export declare const API_KEY_TOAST_KEY = "api-key-rotation";
export type ProviderKeyEventHandler = (event: ProviderKeyEvent) => void;
export interface StreamWithProviderOptions {
    readonly onStatus?: ((message: string) => void) | undefined;
    readonly onKeyEvent?: ProviderKeyEventHandler | undefined;
    readonly onStreamEvent?: ProviderStreamEventSink | undefined;
    /** Additive per-admission accounting for this logical operation. */
    readonly attemptUsage?: OperationUsageRecorder | undefined;
    readonly operation?: OperationLedger | undefined;
    readonly adoptFallback?: boolean | undefined;
    /** Receives the immutable terminal snapshot on success or failure. */
    readonly onOperationUsage?: ((snapshot: OperationUsageSnapshot) => void) | undefined;
    /** Cap retries for this request (default MAX_RETRIES). Use 0-1 for compaction. */
    readonly maxRetries?: number | undefined;
    /**
     * Pin the route and emit exactly one physical generation request: no provider
     * fallback, no key or endpoint rotation, no capability-adaptation retry. Used
     * by operations whose prompt is too expensive to send twice (compaction) and
     * by auxiliary requests that must not multiply.
     */
    readonly singleDispatch?: boolean | undefined;
    readonly onSuccessfulRequest?: ((snapshot: SuccessfulRequestSnapshot) => void) | undefined;
}
export declare function effortCandidatesFor(providerId: ProviderId, model: string, requested: ReasoningEffort): readonly ReasoningEffort[];
/**
 * User-facing classification of provider failures (auth, capacity, disconnect,
 * empty admission, context limit). Used by the fallback table and tests.
 */
export declare function formatProviderFailureForUser(error: unknown): string;
/**
 * Aggregate failure that keeps the most actionable `status` /
 * `retryAfterSeconds` instead of forcing every consumer to regex the message
 * (Phase 2.2). `classifyStreamFailure` already prefers `errorStatus(error)`.
 */
export declare class AggregateProviderError extends ProviderError {
    readonly failures: ReadonlyArray<{
        provider: ProviderId;
        message: string;
    }>;
    constructor(message: string, failures: ReadonlyArray<{
        provider: ProviderId;
        message: string;
    }>, status?: number | undefined, retryAfterSeconds?: number | undefined);
}
/**
 * True when a stream/complete failure was a fully empty model completion — no
 * visible text and no tool calls. Safe to retry with a nudge (common right
 * after auto-compaction when the tail ends on re-injected system context).
 */
export declare function isEmptyCompletionError(error: unknown): boolean;
export declare const providers: Record<ProviderId, LlmProvider>;
export declare function buildFallbackChain(requested: ProviderId, freeOnly: boolean, enabled?: boolean, preferAlternates?: boolean): ProviderId[];
export declare function getProvider(provider: ProviderId): LlmProvider;
export declare function providerAuth(provider: ProviderId): Promise<ProviderAuth>;
export declare function completeWithProvider(request: CompletionRequest, options?: StreamWithProviderOptions): Promise<CompletionResult>;
export declare function streamWithProvider(request: CompletionRequest, onToken: (token: string) => void, onStatusOrOptions?: ((message: string) => void) | StreamWithProviderOptions): Promise<CompletionResult>;
export declare function pingProvider(providerId: ProviderId, secretOverride?: string): Promise<void>;