import { type AgentProviderId } from "../client/agent-provider-catalog.js";
export declare const PROVIDER_KEY_CHECK_PROVIDERS: readonly AgentProviderId[];
/**
 * Why a check did not list models. `rejected` is the provider refusing the
 * key; `wrong-provider` is a key with another provider's prefix, refused
 * before it is sent anywhere; `unreachable` and `provider-error` say nothing
 * about the key itself.
 */
export type ProviderKeyCheckCode = "rejected" | "wrong-provider" | "missing-key" | "invalid-endpoint" | "unreachable" | "provider-error";
export type ProviderKeyCheckResult = {
    ok: true;
    provider: AgentProviderId;
    models: string[];
    /** More pages existed than one check reads; `models` is a prefix. */
    truncated?: true;
    checkedAt: number;
} | {
    ok: false;
    provider: AgentProviderId;
    models: [];
    code: ProviderKeyCheckCode;
    /** English copy from the spec; clients localize from `code` instead. */
    reason: string;
    /** The provider's HTTP status, for `rejected` and `provider-error`. */
    status?: number;
    /** Set when a rejected key lacks the provider's documented prefix. */
    expectedPrefix?: string;
    /** The provider whose prefix a `wrong-provider` key carries. */
    detectedProvider?: AgentProviderId;
    checkedAt: number;
};
export interface ProviderKeyCheckInput {
    provider: AgentProviderId;
    /** A pasted key. Omit to check the saved key. */
    key?: string;
    /**
     * OpenAI-compatible gateway or Ollama endpoint. `undefined` uses the saved
     * endpoint (the one a save without an endpoint keeps); `null` uses the
     * provider's default. Only with a pasted `key` (Ollama sends none): a saved
     * key only ever goes to its saved endpoint.
     */
    baseUrl?: string | null;
    /**
     * Which saved row to read when `key` and `baseUrl` are omitted. `org` is for
     * owners and admins only.
     */
    scope?: "user" | "org";
}
/** A request the check refuses before reading or sending anything. */
export declare class ProviderKeyCheckRequestError extends Error {
    readonly statusCode: 400 | 403;
    constructor(message: string, statusCode: 400 | 403);
}
export declare function isProviderKeyCheckProvider(value: unknown): value is AgentProviderId;
export declare function providerForKeyEnvVar(envVar: string): AgentProviderId | null;
/** The provider a key's prefix belongs to, when only one provider uses it. */
export declare function detectKeyProvider(key: string): AgentProviderId | null;
/** The headline a UI shows above a `rejected` or `wrong-provider` reason. */
export declare function providerKeyRejectedHeadline(provider: AgentProviderId): string;
/**
 * Ask the provider which models a key reaches. The same answer validates the
 * key and fills the model checklist. Reads saved keys and endpoints through
 * the ambient request context, so callers outside an action run it inside
 * `runWithRequestContext`. Never logs or returns the key.
 */
export declare function checkProviderKey(input: ProviderKeyCheckInput): Promise<ProviderKeyCheckResult>;
/**
 * The key-save gate: the same check, folded into the save route's error
 * shape. Rejections are 400s; an unreachable provider is a 502 so the key is
 * not stored unverified.
 */
export declare function checkProviderKeyForSave(input: ProviderKeyCheckInput & {
    key: string;
}): Promise<{
    ok: true;
    models: string[];
} | {
    ok: false;
    statusCode: number;
    error: string;
    code: ProviderKeyCheckCode;
}>;