@gaunt-sloth/core 2.0.0-alpha.4 → 2.0.0-alpha.40

package/dist/providers/groq.js.map

@@ -1 +1 @@
-{"version":3,"file":"groq.js","sourceRoot":"","sources":["../../src/providers/groq.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAIhD,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC;AAE3E,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAwB;IAC9D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC7C,wEAAwE;IACxE,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,YAAY,CAAC;IACxD,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC;QACvB,GAAG,SAAS;QACZ,MAAM,EAAE,UAAU;QAClB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,qBAAqB;KAChD,CAAC,CAAC;AACL,CAAC;AAED,MAAM,WAAW,GAAG;;;;;EAKlB,CAAC;AAEH,MAAM,UAAU,IAAI,CAAC,cAAsB;IACzC,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,gCAAgC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAC9D,cAAc,CACZ,yBAAyB,cAAc,uBAAuB;QAC5D,8CAA8C,CACjD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"groq.js","sourceRoot":"","sources":["../../src/providers/groq.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAIhD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AACnG,OAAO,EACL,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,4CAA4C,CAAC;AAEpD,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAwB;IAC9D,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC7C,wEAAwE;IACxE,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,YAAY,CAAC;IACxD,qFAAqF;IACrF,gEAAgE;IAChE,uBAAuB,CAAC;QACtB,QAAQ,EAAE,MAAM;QAChB,aAAa,EAAG,SAAyC,CAAC,aAAa;QACvE,aAAa,EAAE,EAAE;QACjB,MAAM,EAAE,oBAAoB;QAC5B,QAAQ,EACN,0FAA0F;YAC1F,sFAAsF;YACtF,wCAAwC;KAC3C,CAAC,CAAC;IACH,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC;QACvB,GAAG,SAAS;QACZ,MAAM,EAAE,UAAU;QAClB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,uBAAuB,CAAC,MAAM,CAAC;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,cAAsB,EAAE,KAAK,GAAG,KAAK,EAAE,KAAc;IACxE,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,2BAA2B,CAAC,cAAc,EAAE,sBAAsB,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAC1F,cAAc,CACZ,yBAAyB,cAAc,uBAAuB;QAC5D,8CAA8C,CACjD,CAAC;AACJ,CAAC"}

package/dist/providers/huggingface.d.ts

@@ -0,0 +1,25 @@
+import { BaseChatModel, type BaseChatModelParams } from '@langchain/core/language_models/chat_models';
+import { OpenAIChatInput } from '@langchain/openai';
+import { ChatOpenAIFields } from '@langchain/openai';
+/**
+ * Hugging Face Inference Providers — OpenAI-compatible router.
+ *
+ * HF exposes a single OpenAI-compatible Chat Completions endpoint at
+ * `https://router.huggingface.co/v1` that fans requests out to the configured
+ * inference provider (Cerebras, Groq, Together, SambaNova, hf-inference, …). It
+ * supports tool/function calling, streaming and structured outputs, so we reuse
+ * LangChain's `ChatOpenAI` exactly like the OpenRouter provider — no dedicated
+ * `@langchain/huggingface` package is needed (the JS `@langchain/community`
+ * `HuggingFaceInference` is a text-completion LLM with no `bindTools`, so it is
+ * unusable for the agent loop).
+ *
+ * Auth uses a Hugging Face user access token with the "Inference Providers"
+ * permission, read from `HF_TOKEN` (canonical) or the `HUGGINGFACEHUB_API_TOKEN`
+ * / `HF_API_KEY` aliases.
+ *
+ * Model ids are Hub repo ids, e.g. `openai/gpt-oss-120b`. You may append a
+ * provider/policy suffix understood by the router (`:groq`, `:cheapest`,
+ * `:fastest`); it is part of the model id and passes straight through.
+ */
+export declare function processJsonConfig(llmConfig: OpenAIChatInput & ChatOpenAIFields & BaseChatModelParams): Promise<BaseChatModel>;
+export declare function init(configFileName: string, force?: boolean, model?: string): void;

package/dist/providers/huggingface.js

@@ -0,0 +1,69 @@
+import { displayWarning } from '#src/utils/consoleUtils.js';
+import { env } from '#src/utils/systemUtils.js';
+import { writeConfigFileWithMessages } from '#src/utils/fileUtils.js';
+import { buildInitConfigContent, getCuratedFallbackModel } from '#src/providers/modelDiscovery.js';
+/**
+ * Hugging Face Inference Providers — OpenAI-compatible router.
+ *
+ * HF exposes a single OpenAI-compatible Chat Completions endpoint at
+ * `https://router.huggingface.co/v1` that fans requests out to the configured
+ * inference provider (Cerebras, Groq, Together, SambaNova, hf-inference, …). It
+ * supports tool/function calling, streaming and structured outputs, so we reuse
+ * LangChain's `ChatOpenAI` exactly like the OpenRouter provider — no dedicated
+ * `@langchain/huggingface` package is needed (the JS `@langchain/community`
+ * `HuggingFaceInference` is a text-completion LLM with no `bindTools`, so it is
+ * unusable for the agent loop).
+ *
+ * Auth uses a Hugging Face user access token with the "Inference Providers"
+ * permission, read from `HF_TOKEN` (canonical) or the `HUGGINGFACEHUB_API_TOKEN`
+ * / `HF_API_KEY` aliases.
+ *
+ * Model ids are Hub repo ids, e.g. `openai/gpt-oss-120b`. You may append a
+ * provider/policy suffix understood by the router (`:groq`, `:cheapest`,
+ * `:fastest`); it is part of the model id and passes straight through.
+ */
+// Function to process JSON config and create Hugging Face LLM instance
+// noinspection JSUnusedGlobalSymbols
+export async function processJsonConfig(llmConfig) {
+    const { ChatOpenAI } = await import('@langchain/openai');
+    // Use environment variable if available, otherwise use the config value
+    const huggingFaceToken = getApiKey(llmConfig);
+    if (!huggingFaceToken) {
+        throw new Error('You need to define HF_TOKEN environment variable (a Hugging Face access token ' +
+            'with the "Inference Providers" permission), or set apiKey in your config file.');
+    }
+    const configFields = {
+        ...llmConfig,
+        apiKey: huggingFaceToken,
+        model: llmConfig.model || getCuratedFallbackModel('huggingface'),
+        configuration: {
+            baseURL: 'https://router.huggingface.co/v1',
+            ...(llmConfig.configuration || {}),
+        },
+    };
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delete configFields.type;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    delete configFields.apiKeyEnvironmentVariable;
+    return new ChatOpenAI(configFields);
+}
+function getApiKey(llmConfig) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const conf = llmConfig;
+    if (conf.apiKeyEnvironmentVariable && env[conf.apiKeyEnvironmentVariable]) {
+        return env[conf.apiKeyEnvironmentVariable];
+    }
+    else {
+        return llmConfig.apiKey || env.HF_TOKEN || env.HUGGINGFACEHUB_API_TOKEN || env.HF_API_KEY;
+    }
+}
+export function init(configFileName, force = false, model) {
+    // Determine which content to use based on file extension
+    if (!configFileName.endsWith('.json')) {
+        throw new Error('Only JSON config is supported.');
+    }
+    writeConfigFileWithMessages(configFileName, buildInitConfigContent('huggingface', model), force);
+    displayWarning(`You need to edit your ${configFileName} to configure model, ` +
+        'or define HF_TOKEN environment variable.');
+}
+//# sourceMappingURL=huggingface.js.map

package/dist/providers/huggingface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"huggingface.js","sourceRoot":"","sources":["../../src/providers/huggingface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAC;AAQhD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uEAAuE;AACvE,qCAAqC;AACrC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAmE;IAEnE,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACzD,wEAAwE;IACxE,MAAM,gBAAgB,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,gFAAgF;YAC9E,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG;QACnB,GAAG,SAAS;QACZ,MAAM,EAAE,gBAAgB;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,uBAAuB,CAAC,aAAa,CAAC;QAChE,aAAa,EAAE;YACb,OAAO,EAAE,kCAAkC;YAC3C,GAAG,CAAC,SAAS,CAAC,aAAa,IAAI,EAAE,CAAC;SACnC;KACF,CAAC;IACF,8DAA8D;IAC9D,OAAQ,YAAoB,CAAC,IAAI,CAAC;IAClC,8DAA8D;IAC9D,OAAQ,YAAoB,CAAC,yBAAyB,CAAC;IACvD,OAAO,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,SAAmE;IACpF,8DAA8D;IAC9D,MAAM,IAAI,GAAG,SAA0C,CAAC;IACxD,IAAI,IAAI,CAAC,yBAAyB,IAAI,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC1E,OAAO,GAAG,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;SAAM,CAAC;QACN,OAAO,SAAS,CAAC,MAAM,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,wBAAwB,IAAI,GAAG,CAAC,UAAU,CAAC;IAC5F,CAAC;AACH,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,cAAsB,EAAE,KAAK,GAAG,KAAK,EAAE,KAAc;IACxE,yDAAyD;IACzD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IAED,2BAA2B,CAAC,cAAc,EAAE,sBAAsB,CAAC,aAAa,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IACjG,cAAc,CACZ,yBAAyB,cAAc,uBAAuB;QAC5D,0CAA0C,CAC7C,CAAC;AACJ,CAAC"}

package/dist/providers/modelCatalog.d.ts

@@ -0,0 +1,109 @@
+import type { ProviderId } from '#src/providers/modelDiscovery.js';
+/** The single models.dev dataset endpoint (whole catalog; sliced per-provider on our side). */
+export declare const MODELS_DEV_URL = "https://models.dev/api.json";
+/**
+ * Cache freshness window. Pricing/limit metadata is near-static, so a day between refreshes is
+ * plenty; `gth models --refresh` is the manual escape hatch when a newer number is needed sooner.
+ */
+export declare const CATALOG_TTL_MS: number;
+/**
+ * Catalog fetch timeout. Deliberately generous (and separate from `/v1/models` discovery's 2 s
+ * interactive-path probe): `api.json` is a few MB and this fetch runs off the explicit `gth models`
+ * cache-fill path, not a first-run keystroke, so latency headroom matters more than snappiness.
+ */
+export declare const CATALOG_TIMEOUT_MS = 10000;
+/** Shown next to any enriched price/metadata. Costs from models.dev are US$ per 1M tokens. */
+export declare const CATALOG_ATTRIBUTION = "* model prices provided by models.dev";
+/**
+ * Map a Gaunt Sloth {@link ProviderId} to its models.dev top-level provider key. Cloud providers
+ * only; local/self-hosted providers (`ollama`) are intentionally absent so they get NO catalog
+ * lookup. Returns `undefined` for any provider without a models.dev slice.
+ */
+export declare const MODELS_DEV_PROVIDER_KEY: Partial<Record<ProviderId, string>>;
+/** Per-token cost metadata (US$ per 1M tokens), as published by models.dev. */
+export interface ModelCost {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** Context / output token limits. */
+export interface ModelLimit {
+    context?: number;
+    output?: number;
+}
+/** Input/output modalities (e.g. `text`, `image`, `pdf`). */
+export interface ModelModalities {
+    input?: string[];
+    output?: string[];
+}
+/**
+ * Normalised catalog metadata for one model id — the models.dev fields we surface, camelCased and
+ * detached from models.dev's raw JSON shape so a schema change there is absorbed in the parser.
+ */
+export interface ModelCatalogEntry {
+    /** models.dev display name (e.g. "Claude Opus 4.5"). */
+    name?: string;
+    cost?: ModelCost;
+    limit?: ModelLimit;
+    modalities?: ModelModalities;
+    /** True when the model exposes an extended-reasoning / thinking mode. */
+    reasoning?: boolean;
+    /** True when the model supports tool/function calling. */
+    toolCall?: boolean;
+}
+/** A provider's catalog slice: model-id → metadata, plus provenance for TTL / display. */
+export interface ProviderCatalog {
+    /** Gaunt Sloth provider id this slice belongs to. */
+    providerId: ProviderId;
+    /** models.dev provider key it was sliced from. */
+    providerKey: string;
+    /** Epoch ms the slice was fetched (drives TTL freshness). */
+    fetchedAt: number;
+    /** Metadata keyed by model id, exactly as models.dev keys them. */
+    models: Record<string, ModelCatalogEntry>;
+}
+/** Options shared by catalog reads; every field is injectable for hermetic tests. */
+export interface CatalogOptions {
+    /** Force a network refresh even when a fresh cache exists (backs `gth models --refresh`). */
+    refresh?: boolean;
+    /** Override the cache directory (defaults to `~/.gsloth/model-catalog`). */
+    cacheDir?: string;
+    /** Override "now" for TTL math (defaults to `Date.now()`). */
+    now?: number;
+    /** Override the fetch implementation (defaults to the global `fetch`). */
+    fetchImpl?: typeof fetch;
+    /** Override the TTL window in ms (defaults to {@link CATALOG_TTL_MS}). */
+    ttlMs?: number;
+}
+/**
+ * Get the models.dev catalog slice for one provider, cache-first.
+ *
+ * - **Local / self-hosted** (`ollama`, or any provider without a {@link MODELS_DEV_PROVIDER_KEY}):
+ *   returns `null` immediately, with **no network call**.
+ * - **Cloud, fresh cache** (and not `refresh`): returns the cached slice, no network call.
+ * - **Cloud, missing / stale cache, or `refresh`**: fetches `api.json` once, slices this provider,
+ *   writes the slice to the per-provider cache, and returns it.
+ * - **Fetch fails**: returns the stale cached slice if one exists (degrade, don't blank), else `null`.
+ *
+ * NEVER throws — catalog availability must never block model use.
+ */
+export declare function getProviderCatalog(providerId: ProviderId, options?: CatalogOptions): Promise<ProviderCatalog | null>;
+/** A {@link ModelInfo}-shaped record decorated with optional catalog metadata. */
+export interface EnrichedModel {
+    id: string;
+    preferred: boolean;
+    /** models.dev metadata for this id, when the catalog has an entry; absent = unenriched. */
+    enrichment?: ModelCatalogEntry;
+}
+/**
+ * Enrich a provider's discovered model list with catalog metadata, cache-first.
+ *
+ * `/v1/models` stays authoritative: every input model is returned, in order, whether or not
+ * models.dev knows it. Matched ids gain an `enrichment`; unmatched ids (and every model when the
+ * catalog is unavailable or the provider is local) are returned untouched. NEVER throws.
+ */
+export declare function enrichModels(providerId: ProviderId, models: ReadonlyArray<{
+    id: string;
+    preferred: boolean;
+}>, options?: CatalogOptions): Promise<EnrichedModel[]>;

package/dist/providers/modelCatalog.js

@@ -0,0 +1,245 @@
+/**
+ * @packageDocumentation
+ * Model catalog (GS2-6 / B16) — enriches CLOUD model entries with cost, context-limit and
+ * capability metadata sourced from {@link https://models.dev | models.dev} (MIT-licensed).
+ *
+ * ## What this is (and is not)
+ * This is an **enrichment** layer, never a gate. The authoritative set of callable models stays
+ * `/v1/models` live discovery (see `modelDiscovery.ts`). models.dev only decorates cloud model
+ * ids with `{ cost, limit, modalities, reasoning, toolCall }` where a match exists; a cloud model
+ * that models.dev has never heard of is still listed and still callable, just unenriched. If
+ * models.dev is unreachable (offline / on-prem no-egress / down) every model keeps working — it
+ * simply carries no metadata until the cache fills. Nothing here ever blocks model use.
+ *
+ * ## Fetch / cache shape
+ * models.dev publishes a **single** dataset at {@link MODELS_DEV_URL} (`api.json`, ~3 MB); there is
+ * no per-provider endpoint. So "lazy, per-provider" is realised on the **cache side**: on a miss for
+ * provider *X* we fetch `api.json` once, **slice out just X's models**, and persist that slice to a
+ * per-provider cache file (`~/.gsloth/model-catalog/<providerKey>.json`). Subsequent reads are served
+ * **cache-first** from that per-provider file and never touch the network within the {@link CATALOG_TTL_MS}
+ * TTL. A stale cache is refreshed on read, or on demand via `gth models --refresh`. If a refresh fetch
+ * fails but a stale slice exists, the stale slice is returned (degrade, don't blank).
+ *
+ * ## Local / self-hosted
+ * Only cloud providers have a models.dev key (see {@link MODELS_DEV_PROVIDER_KEY}). `ollama` and any
+ * other local/self-hosted provider return `null` from {@link getProviderCatalog} **without any network
+ * call** — they rely solely on `/v1/models` discovery.
+ *
+ * ## Attribution
+ * Wherever enriched prices/metadata are shown, surface {@link CATALOG_ATTRIBUTION}. models.dev is MIT
+ * licensed; we do not bundle or redistribute a seed dataset here, so no license file needs shipping.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getGlobalGslothDir } from '#src/utils/globalConfigUtils.js';
+import { displayDebug } from '#src/utils/consoleUtils.js';
+/** The single models.dev dataset endpoint (whole catalog; sliced per-provider on our side). */
+export const MODELS_DEV_URL = 'https://models.dev/api.json';
+/**
+ * Cache freshness window. Pricing/limit metadata is near-static, so a day between refreshes is
+ * plenty; `gth models --refresh` is the manual escape hatch when a newer number is needed sooner.
+ */
+export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+/**
+ * Catalog fetch timeout. Deliberately generous (and separate from `/v1/models` discovery's 2 s
+ * interactive-path probe): `api.json` is a few MB and this fetch runs off the explicit `gth models`
+ * cache-fill path, not a first-run keystroke, so latency headroom matters more than snappiness.
+ */
+export const CATALOG_TIMEOUT_MS = 10_000;
+/** Shown next to any enriched price/metadata. Costs from models.dev are US$ per 1M tokens. */
+export const CATALOG_ATTRIBUTION = '* model prices provided by models.dev';
+/**
+ * Map a Gaunt Sloth {@link ProviderId} to its models.dev top-level provider key. Cloud providers
+ * only; local/self-hosted providers (`ollama`) are intentionally absent so they get NO catalog
+ * lookup. Returns `undefined` for any provider without a models.dev slice.
+ */
+export const MODELS_DEV_PROVIDER_KEY = {
+    anthropic: 'anthropic',
+    openai: 'openai',
+    'google-genai': 'google',
+    vertexai: 'google-vertex',
+    groq: 'groq',
+    deepseek: 'deepseek',
+    xai: 'xai',
+    openrouter: 'openrouter',
+    huggingface: 'huggingface',
+    // ollama — local, no models.dev entry (excluded on purpose).
+};
+/** Resolve the per-provider cache directory. */
+function catalogCacheDir(options) {
+    return options.cacheDir ?? resolve(getGlobalGslothDir(), 'model-catalog');
+}
+/** Resolve the cache file path for one models.dev provider key. */
+function catalogCacheFile(providerKey, options) {
+    return resolve(catalogCacheDir(options), `${providerKey}.json`);
+}
+/**
+ * Coerce one models.dev raw model object into a {@link ModelCatalogEntry}, keeping only the fields
+ * we surface and only when they are the expected type (defensive against dataset drift).
+ */
+function normaliseEntry(raw) {
+    const m = (raw ?? {});
+    const entry = {};
+    if (typeof m.name === 'string')
+        entry.name = m.name;
+    if (typeof m.reasoning === 'boolean')
+        entry.reasoning = m.reasoning;
+    if (typeof m.tool_call === 'boolean')
+        entry.toolCall = m.tool_call;
+    const cost = m.cost;
+    if (cost && typeof cost === 'object') {
+        const c = {};
+        if (typeof cost.input === 'number')
+            c.input = cost.input;
+        if (typeof cost.output === 'number')
+            c.output = cost.output;
+        if (typeof cost.cache_read === 'number')
+            c.cacheRead = cost.cache_read;
+        if (typeof cost.cache_write === 'number')
+            c.cacheWrite = cost.cache_write;
+        if (Object.keys(c).length > 0)
+            entry.cost = c;
+    }
+    const limit = m.limit;
+    if (limit && typeof limit === 'object') {
+        const l = {};
+        if (typeof limit.context === 'number')
+            l.context = limit.context;
+        if (typeof limit.output === 'number')
+            l.output = limit.output;
+        if (Object.keys(l).length > 0)
+            entry.limit = l;
+    }
+    const modalities = m.modalities;
+    if (modalities && typeof modalities === 'object') {
+        const mod = {};
+        if (Array.isArray(modalities.input))
+            mod.input = modalities.input.filter((x) => typeof x === 'string');
+        if (Array.isArray(modalities.output))
+            mod.output = modalities.output.filter((x) => typeof x === 'string');
+        if ((mod.input?.length ?? 0) > 0 || (mod.output?.length ?? 0) > 0)
+            entry.modalities = mod;
+    }
+    return entry;
+}
+/**
+ * Slice one provider's models out of the full models.dev `api.json` payload and normalise them.
+ * Returns `{}` when the provider key is absent or malformed — an empty-but-present slice, which the
+ * caller still caches (models.dev simply has no data for that provider yet).
+ */
+function sliceProvider(payload, providerKey) {
+    const providerBlock = payload?.[providerKey];
+    const models = providerBlock?.models;
+    if (!models || typeof models !== 'object')
+        return {};
+    const out = {};
+    for (const [id, raw] of Object.entries(models)) {
+        out[id] = normaliseEntry(raw);
+    }
+    return out;
+}
+/** Read and validate a cached per-provider slice; returns null on any miss / parse failure. */
+function readCache(providerKey, options) {
+    const file = catalogCacheFile(providerKey, options);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed && typeof parsed.fetchedAt === 'number' && parsed.models)
+            return parsed;
+        return null;
+    }
+    catch (e) {
+        displayDebug(`Model catalog cache for "${providerKey}" is unreadable: ${errMsg(e)}`);
+        return null;
+    }
+}
+/** Persist a per-provider slice to the cache (best-effort; a write failure is non-fatal). */
+function writeCache(catalog, options) {
+    try {
+        const dir = catalogCacheDir(options);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(catalogCacheFile(catalog.providerKey, options), JSON.stringify(catalog), 'utf8');
+    }
+    catch (e) {
+        displayDebug(`Failed to write model catalog cache for "${catalog.providerKey}": ${errMsg(e)}`);
+    }
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** True when a cached slice is still within the TTL window. */
+function isFresh(cache, options) {
+    const now = options.now ?? Date.now();
+    const ttl = options.ttlMs ?? CATALOG_TTL_MS;
+    return now - cache.fetchedAt < ttl;
+}
+/**
+ * Get the models.dev catalog slice for one provider, cache-first.
+ *
+ * - **Local / self-hosted** (`ollama`, or any provider without a {@link MODELS_DEV_PROVIDER_KEY}):
+ *   returns `null` immediately, with **no network call**.
+ * - **Cloud, fresh cache** (and not `refresh`): returns the cached slice, no network call.
+ * - **Cloud, missing / stale cache, or `refresh`**: fetches `api.json` once, slices this provider,
+ *   writes the slice to the per-provider cache, and returns it.
+ * - **Fetch fails**: returns the stale cached slice if one exists (degrade, don't blank), else `null`.
+ *
+ * NEVER throws — catalog availability must never block model use.
+ */
+export async function getProviderCatalog(providerId, options = {}) {
+    const providerKey = MODELS_DEV_PROVIDER_KEY[providerId];
+    if (!providerKey)
+        return null; // local / unmapped provider → no catalog lookup at all.
+    const cached = readCache(providerKey, options);
+    if (cached && !options.refresh && isFresh(cached, options)) {
+        return cached;
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(MODELS_DEV_URL, {
+            method: 'GET',
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            displayDebug(`models.dev returned HTTP ${res.status}; using cached catalog if available.`);
+            return cached; // may be stale; may be null.
+        }
+        const payload = await res.json();
+        const catalog = {
+            providerId,
+            providerKey,
+            fetchedAt: options.now ?? Date.now(),
+            models: sliceProvider(payload, providerKey),
+        };
+        writeCache(catalog, options);
+        return catalog;
+    }
+    catch (e) {
+        // Offline / on-prem no-egress / timeout / malformed — degrade to the stale slice or nothing.
+        displayDebug(`models.dev fetch failed: ${errMsg(e)}; using cached catalog if available.`);
+        return cached;
+    }
+}
+/**
+ * Enrich a provider's discovered model list with catalog metadata, cache-first.
+ *
+ * `/v1/models` stays authoritative: every input model is returned, in order, whether or not
+ * models.dev knows it. Matched ids gain an `enrichment`; unmatched ids (and every model when the
+ * catalog is unavailable or the provider is local) are returned untouched. NEVER throws.
+ */
+export async function enrichModels(providerId, models, options = {}) {
+    let catalog = null;
+    try {
+        catalog = await getProviderCatalog(providerId, options);
+    }
+    catch {
+        catalog = null; // defensive: getProviderCatalog already swallows, but never let enrichment throw.
+    }
+    return models.map((m) => {
+        const enrichment = catalog?.models[m.id];
+        return enrichment ? { ...m, enrichment } : { id: m.id, preferred: m.preferred };
+    });
+}
+//# sourceMappingURL=modelCatalog.js.map

package/dist/providers/modelCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelCatalog.js","sourceRoot":"","sources":["../../src/providers/modelCatalog.ts"],"names":[],"mappings":"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"}