@oh-my-pi/pi-catalog 15.10.11

package/dist/types/discovery/cursor.d.ts

@@ -0,0 +1,23 @@
+import type { ModelSpec } from "../types";
+/**
+ * Options for fetching dynamic Cursor models from `GetUsableModels`.
+ */
+export interface CursorModelDiscoveryOptions {
+    /** Cursor access token used for bearer authentication. */
+    apiKey: string;
+    /** Optional Cursor API base URL override. */
+    baseUrl?: string;
+    /** Optional client version override sent as `x-cursor-client-version`. */
+    clientVersion?: string;
+    /** Optional request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Optional list of custom Cursor model ids to include in request context. */
+    customModelIds?: string[];
+}
+/**
+ * Fetches Cursor models through `GetUsableModels` and normalizes them into canonical model entries.
+ *
+ * Returns `null` on request/decode failures.
+ * Returns `[]` only when the endpoint responds successfully with no usable models.
+ */
+export declare function fetchCursorUsableModels(options: CursorModelDiscoveryOptions): Promise<ModelSpec<"cursor-agent">[] | null>;

package/dist/types/discovery/gemini.d.ts

@@ -0,0 +1,25 @@
+import type { FetchImpl, ModelSpec } from "../types";
+/**
+ * Configuration for Google Generative AI model discovery.
+ */
+export interface GeminiDiscoveryOptions {
+    /** API key for the Google Generative AI public endpoint. */
+    apiKey: string;
+    /** Optional endpoint override for testing or proxying. */
+    baseUrl?: string;
+    /** Optional requested page size for model listing. */
+    pageSize?: number;
+    /** Maximum number of pages to request before stopping pagination. */
+    maxPages?: number;
+    /** Optional abort signal for HTTP requests. */
+    signal?: AbortSignal;
+    /** Optional fetch implementation override for tests. */
+    fetch?: FetchImpl;
+}
+/**
+ * Fetches and normalizes Google Generative AI models from the public models endpoint.
+ *
+ * Returns `null` on transport/protocol failures.
+ * Returns `[]` only when the endpoint responds successfully with no usable models.
+ */
+export declare function fetchGeminiModels(options: GeminiDiscoveryOptions): Promise<ModelSpec<"google-generative-ai">[] | null>;

package/dist/types/discovery/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./antigravity";
+export * from "./codex";
+export * from "./gemini";
+export * from "./openai-compatible";

package/dist/types/discovery/openai-compatible.d.ts

@@ -0,0 +1,72 @@
+import type { Api, FetchImpl, ModelSpec, Provider } from "../types";
+/**
+ * Minimal OpenAI-style model entry shape consumed by discovery.
+ *
+ * Providers may return additional fields; this type only captures
+ * fields that are useful for generic normalization.
+ */
+export interface OpenAICompatibleModelRecord {
+    id?: unknown;
+    name?: unknown;
+    object?: unknown;
+    owned_by?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Tolerant envelope for OpenAI-compatible `/models` responses.
+ *
+ * Common providers return `{ data: [...] }`, but variants such as
+ * `{ models: [...] }`, `{ result: [...] }`, or direct arrays are also
+ * accepted during extraction.
+ */
+export interface OpenAICompatibleModelsEnvelope {
+    data?: unknown;
+    models?: unknown;
+    result?: unknown;
+    items?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Context passed to custom OpenAI-compatible model mappers.
+ */
+export interface OpenAICompatibleModelMapperContext<TApi extends Api> {
+    api: TApi;
+    provider: Provider;
+    baseUrl: string;
+}
+/**
+ * Options for fetching and normalizing OpenAI-compatible `/models` catalogs.
+ */
+export interface FetchOpenAICompatibleModelsOptions<TApi extends Api> {
+    /** API type assigned to normalized models. */
+    api: TApi;
+    /** Provider id assigned to normalized models. */
+    provider: Provider;
+    /** Provider base URL used for both fetch and normalized model records. */
+    baseUrl: string;
+    /** Optional bearer token for Authorization header. */
+    apiKey?: string;
+    /** Additional request headers. */
+    headers?: Record<string, string>;
+    /** Optional AbortSignal for request cancellation. */
+    signal?: AbortSignal;
+    /** Optional fetch implementation override for testing/custom runtimes. */
+    fetch?: FetchImpl;
+    /**
+     * Optional post-normalization filter.
+     * Return false to skip a model.
+     */
+    filterModel?: (entry: OpenAICompatibleModelRecord, model: ModelSpec<TApi>) => boolean;
+    /**
+     * Optional mapper override for provider-specific quirks.
+     * Return null to skip a model.
+     */
+    mapModel?: (entry: OpenAICompatibleModelRecord, defaults: ModelSpec<TApi>, context: OpenAICompatibleModelMapperContext<TApi>) => ModelSpec<TApi> | null;
+}
+/**
+ * Fetches and normalizes an OpenAI-compatible `/models` catalog.
+ *
+ * Returns `null` on transport/protocol failures.
+ * Returns `[]` only when the endpoint responds successfully with no usable models.
+ */
+export declare function fetchOpenAICompatibleModels<TApi extends Api>(options: FetchOpenAICompatibleModelsOptions<TApi>): Promise<ModelSpec<TApi>[] | null>;

package/dist/types/effort.d.ts

@@ -0,0 +1,9 @@
+/** User-facing thinking levels, ordered least to most intensive. */
+export declare const enum Effort {
+    Minimal = "minimal",
+    Low = "low",
+    Medium = "medium",
+    High = "high",
+    XHigh = "xhigh"
+}
+export declare const THINKING_EFFORTS: readonly Effort[];

package/dist/types/fireworks-model-id.d.ts

@@ -0,0 +1,10 @@
+export declare function toFireworksPublicModelId(modelId: string): string;
+export declare function toFireworksWireModelId(modelId: string): string;
+/**
+ * Fire Pass exposes its Kimi K2.6 Turbo subscription through a dedicated router
+ * endpoint at `accounts/fireworks/routers/<id>` rather than the `models/` namespace.
+ * We keep a friendly public id (e.g. `kimi-k2.6-turbo`) in the catalog and translate
+ * to the wire form (`accounts/fireworks/routers/kimi-k2p6-turbo`) at request time.
+ */
+export declare function toFirepassPublicModelId(modelId: string): string;
+export declare function toFirepassWireModelId(modelId: string): string;

package/dist/types/hosts.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Known model-endpoint host classification — the single vocabulary for the
+ * `provider === id || baseUrl.includes(marker)` idiom that gates wire-level
+ * behavior (compat detection, routing, header shaping, watchdog floors).
+ *
+ * Markers are case-insensitive substrings matched against the base URL, NOT
+ * parsed hostnames: proxies regularly embed the upstream host in a path
+ * segment, and the historical call sites all used substring semantics.
+ * Callers that need strict hostname matching — where a substring false
+ * positive is dangerous, e.g. the Anthropic official-endpoint OAuth gate —
+ * parse the URL and compare the hostname themselves.
+ */
+export declare const KNOWN_HOSTS: {
+    readonly openai: {
+        readonly providers: readonly ["openai"];
+        readonly urlMarkers: readonly ["api.openai.com"];
+    };
+    readonly azureOpenAI: {
+        readonly providers: readonly ["azure"];
+        readonly urlMarkers: readonly [".openai.azure.com", "azure.com/openai", "models.inference.ai.azure.com"];
+    };
+    readonly openrouter: {
+        readonly providers: readonly ["openrouter"];
+        readonly urlMarkers: readonly ["openrouter.ai"];
+    };
+    readonly vercelAIGateway: {
+        readonly providers: readonly ["vercel-ai-gateway"];
+        readonly urlMarkers: readonly ["ai-gateway.vercel.sh"];
+    };
+    readonly githubCopilot: {
+        readonly providers: readonly ["github-copilot"];
+        readonly urlMarkers: readonly ["githubcopilot.com", "copilot-api."];
+    };
+    readonly anthropic: {
+        readonly providers: readonly ["anthropic"];
+        readonly urlMarkers: readonly ["api.anthropic.com"];
+    };
+    /** DeepSeek's first-party API only — gates direct-API quirks (max_tokens field, thinking extraBody). */
+    readonly deepseekDirect: {
+        readonly providers: readonly ["deepseek"];
+        readonly urlMarkers: readonly ["api.deepseek.com"];
+    };
+    /** Any DeepSeek-operated host (first-party API, web-chat fronts). Wider than `deepseekDirect` on purpose. */
+    readonly deepseekFamily: {
+        readonly providers: readonly ["deepseek"];
+        readonly urlMarkers: readonly ["deepseek.com"];
+    };
+    readonly cerebras: {
+        readonly providers: readonly ["cerebras"];
+        readonly urlMarkers: readonly ["cerebras.ai"];
+    };
+    readonly zai: {
+        readonly providers: readonly ["zai"];
+        readonly urlMarkers: readonly ["api.z.ai"];
+    };
+    readonly zhipu: {
+        readonly providers: readonly ["zhipu-coding-plan"];
+        readonly urlMarkers: readonly ["open.bigmodel.cn"];
+    };
+    readonly kilo: {
+        readonly providers: readonly ["kilo"];
+        readonly urlMarkers: readonly ["api.kilo.ai"];
+    };
+    readonly alibabaDashscope: {
+        readonly providers: readonly ["alibaba-coding-plan"];
+        readonly urlMarkers: readonly ["dashscope"];
+    };
+    readonly xiaomi: {
+        readonly providers: readonly ["xiaomi"];
+        readonly providerPrefixes: readonly ["xiaomi-token-plan-"];
+        readonly urlMarkers: readonly ["xiaomimimo.com"];
+    };
+    readonly xai: {
+        readonly providers: readonly ["xai"];
+        readonly urlMarkers: readonly ["api.x.ai"];
+    };
+    readonly mistral: {
+        readonly providers: readonly ["mistral"];
+        readonly urlMarkers: readonly ["mistral.ai"];
+    };
+    readonly together: {
+        readonly providers: readonly ["together"];
+        readonly urlMarkers: readonly ["api.together.xyz"];
+    };
+    /** URL-only on purpose: the `fireworks`/`firepass` providers route per-model and not every model is Fireworks-shaped. */
+    readonly fireworks: {
+        readonly urlMarkers: readonly ["fireworks.ai"];
+    };
+    readonly groq: {
+        readonly providers: readonly ["groq"];
+        readonly urlMarkers: readonly ["api.groq.com"];
+    };
+    readonly minimax: {
+        readonly providers: readonly ["minimax", "minimax-code", "minimax-code-cn"];
+        readonly urlMarkers: readonly ["api.minimax.io", "api.minimaxi.com"];
+    };
+    readonly qwenPortal: {
+        readonly providers: readonly ["qwen-portal"];
+        readonly urlMarkers: readonly ["portal.qwen.ai"];
+    };
+    readonly moonshotNative: {
+        readonly providers: readonly ["moonshot", "kimi-code"];
+        readonly urlMarkers: readonly ["api.moonshot.ai", "api.kimi.com"];
+    };
+    readonly opencode: {
+        readonly providers: readonly ["opencode-go", "opencode-zen"];
+        readonly urlMarkers: readonly ["opencode.ai"];
+    };
+    readonly chutes: {
+        readonly urlMarkers: readonly ["chutes.ai"];
+    };
+};
+export type KnownHost = keyof typeof KNOWN_HOSTS;
+/** URL-only host check (for call sites that have no provider id, e.g. raw env config). */
+export declare function hostMatchesUrl(baseUrl: string | undefined, host: KnownHost): boolean;
+/** Provider-or-URL host check — the canonical `provider === id || baseUrl.includes(marker)` idiom. */
+export declare function modelMatchesHost(model: {
+    provider: string;
+    baseUrl: string;
+}, host: KnownHost): boolean;
+/** Vertex AI express-mode OpenAI-compatible endpoint (`…/endpoints/openapi`). */
+export declare function isVertexExpressOpenAIUrl(baseUrl: string): boolean;
+/** Vertex AI Anthropic raw-predict endpoints (`:streamRawPredict` / `:rawPredict`). */
+export declare function isVertexRawPredictUrl(baseUrl: string): boolean;
+/** Azure OpenAI deployment-scoped path (`…/deployments/<name>/…`). */
+export declare function isAzureDeploymentsUrl(baseUrl: string): boolean;
+/** Alibaba DashScope consumer `compatible-mode` endpoint (rejects multimodal arrays for some text-only SKUs). */
+export declare function isDashscopeCompatibleModeUrl(baseUrl: string): boolean;

package/dist/types/identity/bundled.d.ts

@@ -0,0 +1,6 @@
+import { type CanonicalReferenceData } from "./equivalence";
+import { type ModelReferenceIndex } from "./reference";
+/** Canonical-equivalence reference data over the bundled catalog. */
+export declare function getBundledCanonicalReferenceData(): CanonicalReferenceData;
+/** Proxy-reference index over the bundled catalog. */
+export declare function getBundledModelReferenceIndex(): ModelReferenceIndex;

package/dist/types/identity/classify.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Model-id classification: parse a model id into its family (gemini / anthropic /
+ * openai), kind/variant, and version. This is the shared layer both catalog
+ * policy rules (`model-thinking.ts`) and downstream consumers build on —
+ * classification lives here, the rules that consume it stay with their domain.
+ */
+export type SemVer = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export type GeminiKind = "pro" | "flash";
+export type AnthropicKind = "opus" | "sonnet" | "fable" | "mythos";
+export type OpenAIVariant = "base" | "codex" | "codex-max" | "codex-mini" | "codex-spark" | "mini" | "max" | "nano";
+export interface GeminiModel {
+    family: "gemini";
+    kind: GeminiKind;
+    version: SemVer;
+}
+export interface AnthropicModel {
+    family: "anthropic";
+    kind: AnthropicKind;
+    version: SemVer;
+}
+export interface OpenAIModel {
+    family: "openai";
+    variant: OpenAIVariant;
+    version: SemVer;
+}
+export interface UnknownModel {
+    family: "unknown";
+    id: string;
+}
+export type ParsedModel = GeminiModel | AnthropicModel | OpenAIModel | UnknownModel;
+/** Strip a provider namespace prefix (`openai/gpt-5.4` → `gpt-5.4`). */
+export declare function bareModelId(modelId: string): string;
+export declare function parseKnownModel(modelId: string): ParsedModel;
+export declare function parseGeminiModel(modelId: string): GeminiModel | null;
+export declare function parseAnthropicModel(modelId: string): AnthropicModel | null;
+export declare function parseOpenAIModel(modelId: string): OpenAIModel | null;
+export declare function isFableOrMythos(kind: AnthropicKind): boolean;
+export declare function parseSemVer(version: string): SemVer | null;
+export declare function semverGte(left: SemVer | string, right: SemVer | string): boolean;
+export declare function semverEqual(left: SemVer | string, right: SemVer | string): boolean;
+export declare function compareSemVer(left: SemVer | string | null, right: SemVer | string | null): number;

package/dist/types/identity/equivalence.d.ts

@@ -0,0 +1,46 @@
+import type { Api, Model } from "../types";
+export type CanonicalModelSource = "override" | "bundled" | "heuristic" | "fallback";
+export interface ModelEquivalenceConfig {
+    overrides?: Record<string, string>;
+    exclude?: string[];
+}
+export interface CanonicalModelVariant {
+    canonicalId: string;
+    selector: string;
+    model: Model<Api>;
+    source: CanonicalModelSource;
+}
+export interface CanonicalModelRecord {
+    id: string;
+    name: string;
+    variants: CanonicalModelVariant[];
+}
+export interface CanonicalModelIndex {
+    records: CanonicalModelRecord[];
+    byId: Map<string, CanonicalModelRecord>;
+    bySelector: Map<string, string>;
+}
+export interface CanonicalReferenceData {
+    references: ReadonlyMap<string, Model<Api>>;
+    officialIds: ReadonlySet<string>;
+    suffixAliases: ReadonlyMap<string, string>;
+    [kResolutionCaches]?: WeakMap<CompiledEquivalenceConfig, Map<string, ResolvedCanonicalModel>>;
+}
+interface CompiledEquivalenceConfig {
+    overrides: Map<string, string>;
+    exclude: Set<string>;
+}
+interface ResolvedCanonicalModel {
+    id: string;
+    source: CanonicalModelSource;
+}
+declare const kResolutionCaches: unique symbol;
+/**
+ * Build canonical reference data from a model catalog (typically the bundled
+ * models). Pure: callers are responsible for memoizing the result — the
+ * canonical index keeps per-reference resolution caches internally.
+ */
+export declare function buildCanonicalReferenceData(models: Iterable<Model<Api>>): CanonicalReferenceData;
+export declare function formatCanonicalVariantSelector(model: Model<Api>): string;
+export declare function buildCanonicalModelIndex(models: readonly Model<Api>[], reference: CanonicalReferenceData, equivalence?: ModelEquivalenceConfig): CanonicalModelIndex;
+export {};

package/dist/types/identity/family.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Model-family id predicates: the shared vocabulary for "is this id a member
+ * of family X" checks that gate wire-level behavior across hosts (a Kimi or
+ * DeepSeek model keeps its quirks no matter which OpenAI-compatible proxy
+ * serves it). Looser per-feature heuristics (e.g. stream-markup healing)
+ * deliberately keep their own patterns — only provably-shared matchers live
+ * here.
+ */
+/** Kimi family ids in any namespace form (`moonshotai/kimi-*`, `kimi-k2.6`, `vendor/kimi.x`). */
+export declare function isKimiModelId(modelId: string): boolean;
+/** Kimi K2.6 specifically (preserved-thinking transport on Moonshot-native hosts). */
+export declare function isKimiK26ModelId(modelId: string): boolean;
+/** Claude ids in any namespace form (`claude-*`, `vendor/claude.x`). */
+export declare function isClaudeModelId(modelId: string): boolean;
+/** `anthropic/`-namespaced ids (aggregator catalogs like OpenRouter). */
+export declare function isAnthropicNamespacedModelId(modelId: string): boolean;
+/** Qwen family ids (substring match — Qwen SKUs have no stable prefix shape). */
+export declare function isQwenModelId(modelId: string): boolean;
+/** DeepSeek family by id or display name (proxies often rename the id but keep the name). */
+export declare function isDeepseekModelIdOrName(value: string): boolean;
+/** Xiaomi MiMo family by id or display name. */
+export declare function isMimoModelIdOrName(value: string): boolean;
+/**
+ * Adaptive thinking `display` is supported starting with Claude Opus 4.7 and
+ * the Claude Fable/Mythos 5 generation. Older adaptive-thinking models
+ * (Opus 4.6, Sonnet 4.6+) reject the field. Classifier-based, so dotted and
+ * dashed version forms both match while bare dated ids
+ * (`claude-opus-4-20250514` = Opus 4.0) stay excluded.
+ */
+export declare function supportsAdaptiveThinkingDisplay(modelId: string): boolean;
+/**
+ * Returns true for Anthropic models with Opus 4.7+/Fable/Mythos API restrictions:
+ * - Sampling parameters (temperature/top_p/top_k) return 400 error
+ * - Thinking content is omitted by default (needs display: "summarized")
+ */
+export declare function hasOpus47ApiRestrictions(modelId: string): boolean;
+/**
+ * Mid-conversation `role: "system"` messages (system instructions appended at
+ * non-first positions in the `messages` array) are supported starting with
+ * Claude Opus 4.8 and the Claude Fable/Mythos 5 generation. Earlier Claude
+ * models reject the role.
+ * @see https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages
+ */
+export declare function supportsMidConversationSystemMessages(modelId: string): boolean;
+export declare function isAnthropicFableOrMythosModel(modelId: string): boolean;

package/dist/types/identity/id.d.ts

@@ -0,0 +1,12 @@
+export declare function getModelLikeIdSegments(modelId: string): string[];
+export declare function getLongestModelLikeIdSegment(modelId: string): string | undefined;
+/**
+ * Strip reseller / wrapper tags that are injected as bracketed affixes around an
+ * upstream model id, e.g.
+ *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
+ *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
+ */
+export declare function getBracketStrippedModelIdCandidates(modelId: string): string[];
+export declare function stripBracketedModelIdAffixes(modelId: string): string | undefined;

package/dist/types/identity/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./bundled";
+export * from "./classify";
+export * from "./equivalence";
+export * from "./family";
+export * from "./id";
+export * from "./markers";
+export * from "./priority";
+export * from "./reference";
+export * from "./selection";

package/dist/types/identity/markers.d.ts

@@ -0,0 +1,4 @@
+/** Marker pattern used by canonical-id resolution (`search` excluded). */
+export declare const CANONICAL_TRAILING_MARKER_PATTERN: RegExp;
+/** Marker pattern used by proxy-reference lookup (`search` included). */
+export declare const REFERENCE_TRAILING_MARKER_PATTERN: RegExp;

package/dist/types/identity/priority.d.ts

@@ -0,0 +1 @@
+export declare function buildModelProviderPriorityRank(configuredProviderOrder?: readonly string[]): Map<string, number>;

package/dist/types/identity/reference.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Proxy/reseller reference lookup: given a custom model id served through a
+ * proxy (`[Kiro] claude-opus-4-8`, `gpt-5.4:cloud`, `vendor/claude-sonnet-4-6-thinking`),
+ * find the bundled upstream model so missing pricing/capability metadata can be
+ * inherited while keeping the custom transport.
+ *
+ * Kept separate from canonical-id resolution (`./equivalence`): this lookup
+ * may strip `search`-style markers and prefers cache-pricing-complete
+ * references, both of which would be wrong for canonical coalescing.
+ */
+import type { Api, Model } from "../types";
+export interface ModelReferenceIndex {
+    exact: Map<string, Model<Api>>;
+    suffixAlias: Map<string, Model<Api>>;
+}
+/**
+ * Build a reference index from a model catalog (typically the bundled models).
+ * Pure: callers are responsible for memoizing the result.
+ */
+export declare function buildModelReferenceIndex(models: Iterable<Model<Api>>): ModelReferenceIndex;
+/** Resolve a (possibly proxied/affixed) model id to its bundled upstream reference. */
+export declare function resolveModelReference(modelId: string, index: ModelReferenceIndex): Model<Api> | undefined;

package/dist/types/identity/selection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical-variant selection: pick the preferred variant of a canonical
+ * model record given caller-supplied provider and candidate orderings.
+ */
+import type { Api, Model } from "../types";
+import { type CanonicalModelVariant } from "./equivalence";
+export interface CanonicalVariantPreferences {
+    /** Lowercased provider id → rank (lower wins). */
+    providerRank: ReadonlyMap<string, number>;
+    /** Variant selector (`provider/id`) → candidate-list position (lower wins). */
+    modelOrder: ReadonlyMap<string, number>;
+}
+/** Selector → index map over an ordered candidate list, for `modelOrder` tiebreaks. */
+export declare function buildCanonicalModelOrder(candidates: readonly Model<Api>[]): Map<string, number>;
+/**
+ * Pick the preferred variant. Sort order: configured provider rank →
+ * exact-id match → variant source (override/bundled > heuristic > fallback)
+ * → shorter id → candidate-list order.
+ */
+export declare function resolveCanonicalVariant(variants: readonly CanonicalModelVariant[], preferences: CanonicalVariantPreferences): CanonicalModelVariant | undefined;

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./compat/openai";
+export * from "./discovery";
+export * from "./effort";
+export * from "./fireworks-model-id";
+export * from "./identity";
+export * from "./model-cache";
+export * from "./model-manager";
+export * from "./model-thinking";
+export * from "./models";
+export * from "./provider-models";
+export * from "./types";
+export * from "./utils";
+export * from "./wire/codex";
+export * from "./wire/gemini-headers";
+export * from "./wire/github-copilot";

package/dist/types/model-cache.d.ts

@@ -0,0 +1,17 @@
+import type { Api, Model, ModelSpec } from "./types";
+interface CacheEntry<TApi extends Api = Api> {
+    models: ModelSpec<TApi>[];
+    fresh: boolean;
+    authoritative: boolean;
+    updatedAt: number;
+    /**
+     * Hash of the static catalog slice that was merged into `models` when this
+     * row was written. `resolveProviderModels` compares against the current
+     * static fingerprint and bypasses the static+cache re-merge when they
+     * match — the cache already incorporates the same static state.
+     */
+    staticFingerprint: string;
+}
+export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
+export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string): void;
+export {};

package/dist/types/model-manager.d.ts

@@ -0,0 +1,64 @@
+import type { Api, Model, ModelSpec, Provider } from "./types";
+/**
+ * Controls when dynamic endpoint models should be fetched.
+ */
+export type ModelRefreshStrategy = "online" | "offline" | "online-if-uncached";
+/**
+ * Hook for loading and mapping models.dev fallback data into canonical model objects.
+ */
+export interface ModelsDevFallback<TApi extends Api = Api, TPayload = unknown> {
+    /** Fetches raw fallback payload (for example from models.dev). */
+    fetch(): Promise<TPayload>;
+    /** Maps payload into provider models. */
+    map(payload: TPayload, providerId: Provider): readonly ModelSpec<TApi>[];
+}
+/**
+ * Configuration for provider model resolution.
+ */
+export interface ModelManagerOptions<TApi extends Api = Api, TModelsDevPayload = unknown> {
+    /** Provider id used for static lookup and cache namespacing. */
+    providerId: Provider;
+    /** Optional static list override. When omitted, bundled models.json is used. */
+    staticModels?: readonly ModelSpec<TApi>[];
+    /** Optional override for the cache database path. Default: <agent-dir>/models.db. */
+    cacheDbPath?: string;
+    /** Maximum cache age in milliseconds before considered stale. Default: 24h. */
+    cacheTtlMs?: number;
+    /** When true, a successful dynamic fetch is the complete provider catalog and prunes static-only models. */
+    dynamicModelsAuthoritative?: boolean;
+    /** Optional dynamic endpoint fetcher. */
+    fetchDynamicModels?: () => Promise<readonly ModelSpec<TApi>[] | null>;
+    /** Optional models.dev fallback hook. */
+    modelsDev?: ModelsDevFallback<TApi, TModelsDevPayload>;
+    /** Clock override for deterministic tests. */
+    now?: () => number;
+}
+/**
+ * Resolution result.
+ *
+ * `stale` is false when the resolved catalog is authoritative for the selected provider:
+ * - dynamic endpoint data was fetched in this call,
+ * - a still-fresh authoritative cache was reused in `online-if-uncached` mode, or
+ * - the provider has no dynamic fetcher configured.
+ */
+export interface ModelResolutionResult<TApi extends Api = Api> {
+    models: Model<TApi>[];
+    stale: boolean;
+}
+/**
+ * Stateful facade over provider model resolution.
+ */
+export interface ModelManager<TApi extends Api = Api> {
+    refresh(strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;
+}
+/**
+ * Creates a reusable provider model manager.
+ */
+export declare function createModelManager<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>): ModelManager<TApi>;
+/**
+ * Resolves provider models with source precedence:
+ * static -> models.dev -> cache -> dynamic.
+ *
+ * Later sources override earlier ones by model id.
+ */
+export declare function resolveProviderModels<TApi extends Api = Api, TModelsDevPayload = unknown>(options: ModelManagerOptions<TApi, TModelsDevPayload>, strategy?: ModelRefreshStrategy): Promise<ModelResolutionResult<TApi>>;