/** Provider-agnostic content block — normalized across adapters. */
type AIContentBlock = {
    type: 'text';
    text: string;
} | {
    type: 'image';
    image: {
        mediaType: string;
        data: string;
    };
};
type AIMessage = {
    role: 'system' | 'user' | 'assistant';
    content: string | AIContentBlock[];
};
type AIRequest = {
    model: string;
    messages: AIMessage[];
    maxTokens?: number;
    temperature?: number;
    stop?: string | string[];
    stream?: boolean;
    /**
     * Optional idempotency key. Adapters SHOULD forward it to the provider's
     * idempotency header (e.g. `Idempotency-Key`) when the provider supports it,
     * to deduplicate retried calls after a timeout-driven fallback. Adapters that
     * do not support the header may ignore it.
     */
    idempotencyKey?: string;
};
/** Raw token usage only — cost/accounting is host-domain. */
type AIUsage = {
    promptTokens: number;
    completionTokens: number;
};
type AIResponse = {
    content: string;
    model: string;
    provider: string;
    usage: AIUsage;
    finishReason?: string;
};
type ModelOption = {
    id: string;
    label: string;
};
type AIAdapter = {
    provider: string;
    call(req: AIRequest): Promise<AIResponse>;
    stream?(req: AIRequest): ReadableStream<string>;
    listModels?(): Promise<ModelOption[]>;
    /**
     * Capability flag — true when this adapter maps image content blocks
     * (`AIContentBlock` image variant) to the provider's vision wire shape.
     * Optional (same family as `stream?`/`listModels?`); additive to the seam,
     * not a `usage`/cost change. Lets a consumer route image requests safely.
     */
    supportsImage?: boolean;
};
declare abstract class AIError extends Error {
    abstract readonly retryable: boolean;
}
declare class RateLimitError extends AIError {
    readonly provider?: string | undefined;
    readonly cause?: unknown | undefined;
    readonly name = "RateLimitError";
    readonly retryable = true;
    constructor(message: string, provider?: string | undefined, cause?: unknown | undefined);
}
declare class TransientError extends AIError {
    readonly provider?: string | undefined;
    readonly cause?: unknown | undefined;
    readonly name = "TransientError";
    readonly retryable = true;
    constructor(message: string, provider?: string | undefined, cause?: unknown | undefined);
}
declare class QuotaExhaustedError extends AIError {
    readonly provider?: string | undefined;
    readonly cause?: unknown | undefined;
    readonly name = "QuotaExhaustedError";
    readonly retryable = true;
    constructor(message: string, provider?: string | undefined, cause?: unknown | undefined);
}
declare class AuthError extends AIError {
    readonly provider?: string | undefined;
    readonly cause?: unknown | undefined;
    readonly name = "AuthError";
    readonly retryable = false;
    constructor(message: string, provider?: string | undefined, cause?: unknown | undefined);
}
declare class FatalError extends AIError {
    readonly provider?: string | undefined;
    readonly cause?: unknown | undefined;
    readonly name = "FatalError";
    readonly retryable = false;
    constructor(message: string, provider?: string | undefined, cause?: unknown | undefined);
}
declare class AllModelsFailedError extends FatalError {
    readonly lastError?: AIError | undefined;
    constructor(message: string, lastError?: AIError | undefined);
}
type AIProvider = 'anthropic' | 'openai-compat' | 'google' | 'workers-ai';
type AIAdapterFactory = (creds: unknown) => AIAdapter;
type AIAdapterFactories = Partial<Record<AIProvider, AIAdapterFactory>>;
/** Wire adapter subpath makers without importing them from core (tree-shake safe). */
declare function setAdapterFactories(factories: AIAdapterFactories): void;
declare function getAdapter(provider: AIProvider, creds: unknown): AIAdapter;
type FallbackChainEntry = {
    adapter: AIAdapter;
    model?: string;
};
type ExecuteWithFallbackOpts = {
    timeoutMs?: number;
    /**
     * When true, non-retryable AIErrors (AuthError, FatalError) from one provider
     * also fall through to the next provider in the chain instead of aborting.
     * Useful in multi-provider fallback scenarios where a misconfigured credential
     * for one provider should not block other healthy providers.
     * Default: false (non-retryable errors abort immediately — the safe default for single-provider use).
     */
    continueOnNonRetryable?: boolean;
};
declare function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T>;
/**
 * Runtime boundary guard — usage must carry token counts and NOTHING else.
 * Allowlist (not a denylist): the spec mandates `{ promptTokens, completionTokens }`
 * exactly, so any extra key — cost/price/credits, a novel currency name, or a nested
 * accounting object — is a host-domain leak and is rejected. Cost is host-domain.
 */
declare function assertUsageBoundary(usage: AIUsage): void;
declare function executeWithFallback(req: AIRequest, chain: FallbackChainEntry[], opts?: ExecuteWithFallbackOpts): Promise<AIResponse>;

export { type AIAdapter, type AIAdapterFactories, type AIAdapterFactory, type AIContentBlock, AIError, type AIMessage, type AIProvider, type AIRequest, type AIResponse, type AIUsage, AllModelsFailedError, AuthError, type ExecuteWithFallbackOpts, type FallbackChainEntry, FatalError, type ModelOption, QuotaExhaustedError, RateLimitError, TransientError, assertUsageBoundary, executeWithFallback, getAdapter, setAdapterFactories, withTimeout };