/**
 * Live model catalog cache — fetches and persists models.dev/api.json.
 *
 * Resolution priority:
 *   1. Disk cache (versioned under `<CLEO_DATA_DIR>/llm-catalog/`)
 *   2. Bundled snapshot (curated-models.json in this package)
 *
 * The cache is keyed by a Unix-timestamp prefix: `<ts>-models.json`. A
 * stable `latest.json` symlink points to the most recent entry for quick
 * access without scanning the directory.
 *
 * Stale-fallback behaviour (network failures):
 *   - If the network fetch fails, the most-recently-written `*.json` in
 *     the cache directory is returned instead.
 *   - If the cache directory is empty or absent, the bundled snapshot is
 *     returned so callers always get *some* data.
 *
 * Source: https://models.dev/api.json
 *
 * @module llm/catalog-cache
 * @task T9314
 * @epic T9261 (T-LLM-CRED-CENTRALIZATION Phase 5)
 */
/** Live catalog endpoint. */
export declare const MODELS_DEV_URL = "https://models.dev/api.json";
/**
 * A single model entry as returned by models.dev/api.json.
 *
 * Only the fields we actually consume are typed here; the rest are captured
 * in the `extra` pass-through so the raw file round-trips faithfully.
 */
export interface ModelsCatalogEntry {
    /** Model identifier. */
    id: string;
    /** Human-readable display name. */
    name?: string;
    /** ISO 8601 date when the model was released (e.g. `"2025-08-07"`). Used to
     * derive a provider's latest model when no explicit default is pinned. */
    release_date?: string;
    /** Context + output window limits. */
    limit?: {
        context?: number;
        output?: number;
    };
}
/**
 * Provider record within the models.dev response envelope.
 */
export interface ModelsCatalogProvider {
    /** Provider identifier. */
    id: string;
    /** Models offered by this provider, keyed by model ID. */
    models: Record<string, ModelsCatalogEntry>;
}
/**
 * Top-level shape of models.dev/api.json.
 *
 * The file is a flat object whose keys are provider IDs and whose values
 * are {@link ModelsCatalogProvider} records.
 */
export type ModelsCatalogFile = Record<string, ModelsCatalogProvider>;
/**
 * Flattened model index derived from the catalog.
 *
 * Maps model ID → context length (token count). Models that do not
 * advertise a context length are omitted from the index so callers can
 * distinguish "known with context" from "missing from catalog".
 */
export type ModelContextIndex = Record<string, number>;
/**
 * Resolve the directory where catalog snapshots are stored.
 *
 * Respects `CLEO_DATA_DIR` env override (same convention used by the
 * credentials layer), then falls back to
 * `$XDG_DATA_HOME/cleo` → `~/.local/share/cleo`.
 */
export declare function getCatalogDir(): string;
/**
 * Return the path to the most-recently-written `*-models.json` in `dir`.
 *
 * Entries are sorted by `mtime` descending so the first item is the
 * freshest. Returns `null` when the directory is empty or does not exist.
 */
export declare function findLatestCacheFile(dir: string): string | null;
/**
 * Write `data` to `<dir>/<timestamp>-models.json` and update the
 * `latest.json` symlink to point at the new file.
 *
 * @returns Absolute path of the written file.
 */
export declare function writeCacheFile(dir: string, data: ModelsCatalogFile): string;
/**
 * Read a `ModelsCatalogFile` from `filePath`.
 *
 * Returns `null` on any parse or I/O error so callers can fall through to
 * the next tier without crashing.
 */
export declare function readCacheFile(filePath: string): ModelsCatalogFile | null;
/**
 * Flatten a {@link ModelsCatalogFile} into a {@link ModelContextIndex}.
 *
 * Iterates every provider → model pair and extracts `limit.context` when
 * present. The last writer wins for duplicate IDs across providers.
 */
export declare function buildContextIndex(catalog: ModelsCatalogFile): ModelContextIndex;
/**
 * Fetch the live catalog from models.dev and persist it to disk.
 *
 * On network or parse failure the error is surfaced as a thrown
 * {@link CatalogRefreshError} so callers can handle it explicitly (e.g.
 * fall back to a stale cache entry).
 *
 * @param dir - Directory to write the cache file into (defaults to
 *              {@link getCatalogDir}).
 * @returns The written file path and the parsed catalog.
 */
export declare function fetchAndCacheCatalog(dir?: string): Promise<{
    filePath: string;
    catalog: ModelsCatalogFile;
}>;
/**
 * Structured error thrown by {@link fetchAndCacheCatalog} when the network
 * request or JSON parse fails.
 */
export declare class CatalogRefreshError extends Error {
    /** Machine-readable error code. */
    readonly code: string;
    constructor(message: string, code: string);
}
/**
 * Load the context index from the disk cache only — no network fetch.
 *
 * Used by the runtime model-metadata resolver so that reading context lengths
 * never triggers an outbound HTTP request. Populate the cache first with
 * {@link resolveContextIndex} (called by `cleo llm refresh-catalog`).
 *
 * Returns `null` when no disk snapshot exists yet.
 *
 * @param dir - Cache directory override (used in tests).
 */
export declare function loadDiskCatalogIndex(dir?: string): {
    index: ModelContextIndex;
    source: 'disk-cache';
} | null;
/**
 * Resolve a live (or stale-cached) {@link ModelContextIndex}.
 *
 * Resolution order:
 *   1. Try fetching from models.dev (always attempted at call time).
 *   2. On network failure, fall back to the most-recent disk cache entry.
 *   3. If the cache is empty, return `null` so the caller can use the
 *      bundled curated-models.json snapshot.
 *
 * This function performs a network request. Use {@link loadDiskCatalogIndex}
 * when you only need to read the locally-cached snapshot.
 *
 * @param dir - Cache directory override (used in tests).
 */
export declare function resolveContextIndex(dir?: string): Promise<{
    index: ModelContextIndex;
    source: 'live' | 'stale-cache';
} | null>;
//# sourceMappingURL=catalog-cache.d.ts.map