import type { ModelsDevPayload, ModelsRegistry, ResolvedModel, ResolvedProvider, WireFamily } from '../types/models-registry.js';
import type { Logger } from '../types/logger.js';
export interface DefaultModelsRegistryOptions {
    cacheFile: string;
    url?: string | undefined;
    ttlSeconds?: number | undefined;
    fetchImpl?: typeof fetch | undefined;
    /** Pre-seeded payload — useful for offline scenarios and tests. */
    seed?: ModelsDevPayload | undefined;
    /**
     * Maximum age in seconds for stale cache fallback when network fails.
     * Defaults to 7 days. Set to `Infinity` for full offline resilience
     * (risk: deprecated models, wrong pricing). Set to `0` to disable
     * stale fallback entirely.
     */
    maxStaleAgeSeconds?: number | undefined;
    /**
     * Timeout in milliseconds for the models.dev network fetch. When exceeded,
     * the fetch is aborted and cache/stale fallback is used instead.
     * Defaults to 15 seconds. Set to `0` to disable (infinite wait).
     */
    refreshTimeoutMs?: number | undefined;
    /**
     * Curated override payload deep-merged ON TOP of the models.dev base via
     * `mergeModelsPayload` — adds providers/models the base lacks and overrides
     * fields it gets wrong. Resolution order (first non-empty wins): this
     * in-memory `overlay` → `overlayUrl` (fetched, cached) → `overlayFile`
     * (bundled, read from disk). A missing/broken overlay degrades to `{}` and
     * never throws, so the base alone still works.
     */
    overlay?: ModelsDevPayload | undefined;
    /** GitHub-raw (or any) URL serving the curated overlay `providers.json`. */
    overlayUrl?: string | undefined;
    /** Path to the bundled overlay `providers.json` (offline floor). */
    overlayFile?: string | undefined;
    /** Cache file for the fetched `overlayUrl`. Defaults next to `cacheFile`. */
    overlayCacheFile?: string | undefined;
    /**
     * Structured logger. Defaults to noOpLogger (silent).
     * Callers pass a Logger to capture operator-visible diagnostics (cache
     * fallback warnings, overlay unavailability, etc.).
     */
    logger?: Logger | undefined;
}
export declare function classifyFamily(npm: string | undefined): WireFamily;
export declare class DefaultModelsRegistry implements ModelsRegistry {
    /** Merged (base + overlay) payload — what every reader sees. */
    private payload?;
    /** Memoised overlay payload (in-memory / fetched / file). */
    private overlayPayload?;
    /**
     * Extra providers injected at runtime via `mergeOverlay()` — e.g. an
     * openai-compatible server (omniroute, LiteLLM, …) auto-discovered from its
     * `/v1/models` endpoint at boot. Applied LAST (on top of base + curated
     * overlay) and re-applied across `refresh()` so the discovered catalog
     * survives a models.dev refetch.
     */
    private extraOverlay?;
    private fetchedAt?;
    private readonly cacheFile;
    private readonly url;
    private readonly ttlMs;
    private readonly fetchImpl;
    private readonly seed?;
    private readonly maxStaleAgeMs;
    private readonly refreshTimeoutMs;
    private readonly overlay?;
    private readonly overlayUrl?;
    private readonly overlayFile?;
    private readonly overlayCacheFile?;
    private readonly logger;
    constructor(opts: DefaultModelsRegistryOptions);
    load(opts?: {
        force?: boolean | undefined;
    }): Promise<ModelsDevPayload>;
    /**
     * Merge an additional provider payload on top of the resolved catalog. Used
     * for runtime-discovered openai-compatible providers. Remembered so it is
     * re-applied across `refresh()`. A no-op for an empty payload.
     */
    mergeOverlay(payload: ModelsDevPayload): void;
    private withExtraOverlay;
    /**
     * Load the models.dev base payload: fresh cache → network → stale cache.
     * On total failure, degrade to `{}` (so a non-empty overlay still drives
     * the catalog) rather than throwing — unless there's no curated overlay to
     * fall back on, in which case the original error propagates so pure-
     * models.dev setups still surface the problem.
     */
    private loadBase;
    /** Fetch + cache the models.dev base. Throws on failure (used by `refresh`). */
    private refreshBase;
    /**
     * Resolve the curated overlay, memoised. Order: in-memory `overlay` →
     * fetched `overlayUrl` (cached, same TTL/stale rules) → `overlayFile` on
     * disk. Never throws — a missing/broken overlay yields `{}`.
     */
    private loadOverlay;
    private loadOverlayFromUrl;
    private readOverlayFile;
    refresh(): Promise<ModelsDevPayload>;
    listProviders(): Promise<ResolvedProvider[]>;
    getProvider(id: string): Promise<ResolvedProvider | undefined>;
    getModel(providerId: string, modelId: string): Promise<ResolvedModel | undefined>;
    suggestModel(providerId: string): Promise<string | undefined>;
    ageSeconds(): Promise<number>;
    private resolveProvider;
    private isFresh;
    private isWithinMaxStaleAge;
    private readCacheAt;
    /** Used by `wstack models refresh` to expose where the cache lives. */
    cacheLocation(): string;
}
//# sourceMappingURL=models-registry.d.ts.map