saros-proxy 1.0.0 → 1.1.1

package/dist/models-catalog.d.ts

@@ -1,9 +1,10 @@
 /**
  * models-catalog.ts — Single source of truth for the bundled model catalog.
  *
- * `models.json` at the package root is the canonical definition. It is read
- * from disk at runtime (not imported) because `rootDir` is `./src` while the
- * file lives outside it. The same path is used by the daemon to seed
+ * `assets/models.json` is the canonical definition — generated by
+ * `npm run models:refresh`, never edited by hand. It is read from disk at
+ * runtime (not imported) because `rootDir` is `./src` while the file lives
+ * outside it. The same path is used by the daemon to seed
  * `~/.config/saros/models.json`.
  *
  * A missing or malformed catalog degrades to an empty map (callers fall back
@@ -12,9 +13,29 @@
 /**
  * Load the model catalog from disk, with in-memory caching.
  *
- * @param filePath — Catalog path (defaults to the bundled `models.json`)
+ * @param filePath — Catalog path (defaults to the bundled `assets/models.json`)
  * @returns The parsed catalog, or `{}` when the file is missing/invalid
  */
 export declare function loadModelsCatalog(filePath?: string): Record<string, unknown>;
 /** Clear the in-memory cache — test helper. */
 export declare function resetModelsCatalogCache(): void;
+/**
+ * Parse catalog content, throwing on invalid JSON or a non-object payload.
+ *
+ * `loadModelsCatalog` degrades to an empty map instead; this is for callers
+ * that must tell a corrupt file apart from an empty one (the daemon seed).
+ */
+export declare function parseCatalogObject(raw: string): Record<string, unknown>;
+/** Stable on-disk shape: 2-space JSON with a trailing newline. */
+export declare function serializeCatalogObject(models: Record<string, unknown>): string;
+/**
+ * Add the bundle's missing keys to a user catalog.
+ *
+ * Existing keys always win — a value the user customized is never overwritten.
+ * Returns `added: []` when the user copy already covers the bundle, so the
+ * caller can skip the write entirely.
+ */
+export declare function mergeMissingModels(existing: Record<string, unknown>, bundle: Record<string, unknown>): {
+    models: Record<string, unknown>;
+    added: string[];
+};

package/dist/models-catalog.js

@@ -1,9 +1,10 @@
 /**
  * models-catalog.ts — Single source of truth for the bundled model catalog.
  *
- * `models.json` at the package root is the canonical definition. It is read
- * from disk at runtime (not imported) because `rootDir` is `./src` while the
- * file lives outside it. The same path is used by the daemon to seed
+ * `assets/models.json` is the canonical definition — generated by
+ * `npm run models:refresh`, never edited by hand. It is read from disk at
+ * runtime (not imported) because `rootDir` is `./src` while the file lives
+ * outside it. The same path is used by the daemon to seed
  * `~/.config/saros/models.json`.
  *
  * A missing or malformed catalog degrades to an empty map (callers fall back
@@ -15,14 +16,14 @@ import { fileURLToPath } from 'node:url';
 import { logger } from './logger.js';
 /** Package root — works both from `src/` (tsx/vitest) and `dist/` (build). */
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-/** Bundled catalog path: `<package root>/models.json`. */
-const BUNDLED_MODELS_PATH = join(PACKAGE_ROOT, 'models.json');
+/** Bundled catalog path: `<package root>/assets/models.json`. */
+const BUNDLED_MODELS_PATH = join(PACKAGE_ROOT, 'assets', 'models.json');
 /** Parsed catalogs, keyed by absolute path (parsed once per process). */
 const cache = new Map();
 /**
  * Load the model catalog from disk, with in-memory caching.
  *
- * @param filePath — Catalog path (defaults to the bundled `models.json`)
+ * @param filePath — Catalog path (defaults to the bundled `assets/models.json`)
  * @returns The parsed catalog, or `{}` when the file is missing/invalid
  */
 export function loadModelsCatalog(filePath = BUNDLED_MODELS_PATH) {
@@ -40,16 +41,44 @@ export function resetModelsCatalogCache() {
 /** Read and validate one catalog file. Never throws. */
 function readCatalog(filePath) {
     try {
-        const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
-        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-            logger.warn({ path: filePath }, 'models catalog is not a JSON object; using empty catalog');
-            return {};
-        }
-        return parsed;
+        return parseCatalogObject(readFileSync(filePath, 'utf-8'));
     }
     catch (err) {
         logger.warn({ err, path: filePath }, 'failed to load models catalog; using empty catalog');
         return {};
     }
 }
+/**
+ * Parse catalog content, throwing on invalid JSON or a non-object payload.
+ *
+ * `loadModelsCatalog` degrades to an empty map instead; this is for callers
+ * that must tell a corrupt file apart from an empty one (the daemon seed).
+ */
+export function parseCatalogObject(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('models catalog is not a JSON object');
+    }
+    return parsed;
+}
+/** Stable on-disk shape: 2-space JSON with a trailing newline. */
+export function serializeCatalogObject(models) {
+    return `${JSON.stringify(models, null, 2)}\n`;
+}
+/**
+ * Add the bundle's missing keys to a user catalog.
+ *
+ * Existing keys always win — a value the user customized is never overwritten.
+ * Returns `added: []` when the user copy already covers the bundle, so the
+ * caller can skip the write entirely.
+ */
+export function mergeMissingModels(existing, bundle) {
+    const added = Object.keys(bundle).filter((key) => !(key in existing));
+    if (added.length === 0)
+        return { models: existing, added };
+    const models = { ...existing };
+    for (const key of added)
+        models[key] = bundle[key];
+    return { models, added };
+}
 //# sourceMappingURL=models-catalog.js.map

package/dist/models-catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"models-catalog.js","sourceRoot":"","sources":["../src/models-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,8EAA8E;AAC9E,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAE5E,0DAA0D;AAC1D,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;AAE9D,yEAAyE;AACzE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAW,mBAAmB;IACtE,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACrC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,uBAAuB;IACrC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,wDAAwD;AACxD,SAAS,WAAW,CAAC,QAAgB;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;QAEpE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3E,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,0DAA0D,CAAC,CAAC;YAC5F,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,MAAiC,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,oDAAoD,CAAC,CAAC;QAC3F,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"models-catalog.js","sourceRoot":"","sources":["../src/models-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,8EAA8E;AAC9E,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;AAE5E,iEAAiE;AACjE,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AAExE,yEAAyE;AACzE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAW,mBAAmB;IACtE,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACrC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,uBAAuB;IACrC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,wDAAwD;AACxD,SAAS,WAAW,CAAC,QAAgB;IACnC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,oDAAoD,CAAC,CAAC;QAC3F,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAExC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAiC,CAAC;AAC3C,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,sBAAsB,CAAC,MAA+B;IACpE,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAiC,EACjC,MAA+B;IAE/B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC;IACtE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAE3D,MAAM,MAAM,GAA4B,EAAE,GAAG,QAAQ,EAAE,CAAC;IACxD,KAAK,MAAM,GAAG,IAAI,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACnD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC"}

package/dist/models-dev.d.ts

@@ -0,0 +1,72 @@
+/**
+ * models-dev.ts — Read models.dev canonical metadata per provider.
+ *
+ * `GET https://models.dev/api.json` is one document keyed by provider id
+ * (235 providers, 5.9 MB on 2026-11-06). Saros only consumes the providers it
+ * proxies; this module owns the fetch, the per-provider extraction and the TTL
+ * cache so every consumer (opencode.json sync, pi/omp harness sync) reads the
+ * same slice the same way.
+ *
+ * The request sends a stable CLI `User-Agent`. models.dev's edge has answered
+ * 403 to a library-default UA while `User-Agent: cli` got 200 (measured
+ * 2026-11-06); a recheck minutes later returned 200 for both, so treat the
+ * header as a fixed contract — it keeps the fetch independent of whatever UA
+ * the local HTTP stack defaults to — not as a reproducible gate.
+ */
+/** Model id → models.dev metadata entry. */
+export type ModelsDevModelMap = Record<string, Record<string, unknown>>;
+/** Identity sent to models.dev — a stable CLI UA, never the HTTP stack default. */
+export declare const MODELS_DEV_USER_AGENT = "saros-proxy";
+/**
+ * Extract one provider's model map from a parsed models.dev document.
+ *
+ * Pure — callers handle JSON parsing and error recovery.
+ *
+ * @param parsed — Parsed models.dev JSON (`{ providerId: { models: {...} } }`)
+ * @param providerId — models.dev provider id (e.g. "opencode-go")
+ * @returns Model id → metadata map, or `{}` when the provider is absent
+ *          or malformed
+ */
+export declare function extractProviderModels(parsed: Record<string, unknown>, providerId: string): ModelsDevModelMap;
+/**
+ * Pick only whitelisted fields from a models.dev metadata entry.
+ *
+ * Whitelisting keeps provider-specific/unknown keys (e.g. `provider`,
+ * `release_date`) out of configs written by saros.
+ */
+export declare function pickModelsDevFields(entry: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Bare names that two or more entries of one catalog normalize to.
+ *
+ * Matching by such a name would return whichever entry `Object.keys` yields
+ * first — silently pricing/limiting the wrong model — so callers must fall
+ * back to exact ids. `models-refresh` aborts the generation on the same
+ * condition; runtime stays lenient but warns once per slice.
+ *
+ * @param models — id → entry catalog (models.dev slice or bundled catalog)
+ * @param normalize — id → bare name function for that catalog's id shape
+ */
+export declare function collidingBareNames(models: Record<string, unknown>, normalize: (id: string) => string): Set<string>;
+/**
+ * Find a model entry inside one provider's slice.
+ *
+ * Exact id first, then the bare name: live catalogs prefix ids
+ * (`deepseek/deepseek-v4-flash`) while models.dev may key the same model
+ * bare, and vice versa. Matching stays inside the provider slice so a
+ * commandcode model never receives opencode-go prices.
+ *
+ * @returns The metadata entry, or undefined when not found
+ */
+export declare function findProviderModel(models: ModelsDevModelMap, modelId: string): Record<string, unknown> | undefined;
+/**
+ * Fetch one provider's model map, with the shared TTL cache.
+ *
+ * The document is fetched once and split per provider, so asking for both
+ * opencode-go and commandcode costs a single request.
+ *
+ * @returns Model id → metadata map; `{}` when the provider is absent;
+ *          null when the document could not be fetched/parsed
+ */
+export declare function fetchModelsDevProvider(providerId: string): Promise<ModelsDevModelMap | null>;
+/** Clear the models.dev document cache (test helper). */
+export declare function resetModelsDevCache(): void;

package/dist/models-dev.js

@@ -0,0 +1,196 @@
+/**
+ * models-dev.ts — Read models.dev canonical metadata per provider.
+ *
+ * `GET https://models.dev/api.json` is one document keyed by provider id
+ * (235 providers, 5.9 MB on 2026-11-06). Saros only consumes the providers it
+ * proxies; this module owns the fetch, the per-provider extraction and the TTL
+ * cache so every consumer (opencode.json sync, pi/omp harness sync) reads the
+ * same slice the same way.
+ *
+ * The request sends a stable CLI `User-Agent`. models.dev's edge has answered
+ * 403 to a library-default UA while `User-Agent: cli` got 200 (measured
+ * 2026-11-06); a recheck minutes later returned 200 for both, so treat the
+ * header as a fixed contract — it keeps the fetch independent of whatever UA
+ * the local HTTP stack defaults to — not as a reproducible gate.
+ */
+import { MODELS_DEV_CACHE_TTL_MS, MODELS_DEV_SAFE_FIELDS, MODELS_DEV_TIMEOUT_MS, MODELS_DEV_URL, } from './constants.js';
+import { logger } from './logger.js';
+/** Identity sent to models.dev — a stable CLI UA, never the HTTP stack default. */
+export const MODELS_DEV_USER_AGENT = 'saros-proxy';
+/** Cached parsed document. Null = never fetched / reset. */
+let documentCache = null;
+/**
+ * Fetch in progress, if any. Concurrent cold-cache callers await this instead
+ * of each pulling the 5.9 MB document.
+ */
+let documentRequest = null;
+/**
+ * Extract one provider's model map from a parsed models.dev document.
+ *
+ * Pure — callers handle JSON parsing and error recovery.
+ *
+ * @param parsed — Parsed models.dev JSON (`{ providerId: { models: {...} } }`)
+ * @param providerId — models.dev provider id (e.g. "opencode-go")
+ * @returns Model id → metadata map, or `{}` when the provider is absent
+ *          or malformed
+ */
+export function extractProviderModels(parsed, providerId) {
+    const provider = parsed[providerId];
+    if (typeof provider !== 'object' || provider === null)
+        return {};
+    const models = provider.models;
+    if (typeof models !== 'object' || models === null || Array.isArray(models))
+        return {};
+    return models;
+}
+/**
+ * Pick only whitelisted fields from a models.dev metadata entry.
+ *
+ * Whitelisting keeps provider-specific/unknown keys (e.g. `provider`,
+ * `release_date`) out of configs written by saros.
+ */
+export function pickModelsDevFields(entry) {
+    const result = {};
+    for (const key of MODELS_DEV_SAFE_FIELDS) {
+        if (key in entry) {
+            result[key] = entry[key];
+        }
+    }
+    return result;
+}
+/**
+ * Normalize a model id for cross-catalog matching: strip a provider routing
+ * suffix (`…@commandcode`), keep the last path segment, lowercase and turn
+ * underscores into hyphens.
+ */
+function bareModelName(modelId) {
+    const withoutSuffix = modelId.split('@')[0];
+    const parts = withoutSuffix.split('/');
+    return parts[parts.length - 1].toLowerCase().replaceAll('_', '-');
+}
+/** Catalogs already checked for bare-name collisions (one warning per slice). */
+const collisionReported = new WeakSet();
+/**
+ * Bare names that two or more entries of one catalog normalize to.
+ *
+ * Matching by such a name would return whichever entry `Object.keys` yields
+ * first — silently pricing/limiting the wrong model — so callers must fall
+ * back to exact ids. `models-refresh` aborts the generation on the same
+ * condition; runtime stays lenient but warns once per slice.
+ *
+ * @param models — id → entry catalog (models.dev slice or bundled catalog)
+ * @param normalize — id → bare name function for that catalog's id shape
+ */
+export function collidingBareNames(models, normalize) {
+    const counts = new Map();
+    for (const [id, entry] of Object.entries(models)) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+            continue;
+        const bare = normalize(id);
+        if (!bare)
+            continue;
+        counts.set(bare, (counts.get(bare) ?? 0) + 1);
+    }
+    const collisions = new Set([...counts].filter(([, count]) => count > 1).map(([bare]) => bare));
+    if (collisions.size > 0 && !collisionReported.has(models)) {
+        collisionReported.add(models);
+        logger.warn({ bareNames: [...collisions] }, 'model catalog has bare-name collisions; only exact ids will match');
+    }
+    return collisions;
+}
+/**
+ * Find a model entry inside one provider's slice.
+ *
+ * Exact id first, then the bare name: live catalogs prefix ids
+ * (`deepseek/deepseek-v4-flash`) while models.dev may key the same model
+ * bare, and vice versa. Matching stays inside the provider slice so a
+ * commandcode model never receives opencode-go prices.
+ *
+ * @returns The metadata entry, or undefined when not found
+ */
+export function findProviderModel(models, modelId) {
+    const exact = models[modelId];
+    if (typeof exact === 'object' && exact !== null && !Array.isArray(exact)) {
+        return exact;
+    }
+    const bare = bareModelName(modelId);
+    if (!bare)
+        return undefined;
+    // Two ids share this bare name: matching one of them would be arbitrary.
+    if (collidingBareNames(models, bareModelName).has(bare))
+        return undefined;
+    for (const [id, entry] of Object.entries(models)) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+            continue;
+        if (bareModelName(id) === bare)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Fetch and parse the models.dev document. Never throws; failures are not
+ * cached, so a later call retries.
+ */
+async function loadModelsDevDocument() {
+    try {
+        const response = await fetch(MODELS_DEV_URL, {
+            headers: {
+                'User-Agent': MODELS_DEV_USER_AGENT,
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(MODELS_DEV_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            return null;
+        const parsed = JSON.parse(await response.text());
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        documentCache = { ts: Date.now(), parsed: parsed };
+        return documentCache.parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch (or reuse) the parsed models.dev document.
+ *
+ * Concurrent cold-cache callers share one request: the pending promise is
+ * cached, not just its result. A successful document is then cached for
+ * `MODELS_DEV_CACHE_TTL_MS`.
+ */
+async function fetchModelsDevDocument() {
+    if (documentCache !== null && Date.now() - documentCache.ts < MODELS_DEV_CACHE_TTL_MS) {
+        return documentCache.parsed;
+    }
+    if (documentRequest !== null)
+        return documentRequest;
+    const request = loadModelsDevDocument().finally(() => {
+        // Only clear our own request: a reset() may already have installed one.
+        if (documentRequest === request)
+            documentRequest = null;
+    });
+    documentRequest = request;
+    return request;
+}
+/**
+ * Fetch one provider's model map, with the shared TTL cache.
+ *
+ * The document is fetched once and split per provider, so asking for both
+ * opencode-go and commandcode costs a single request.
+ *
+ * @returns Model id → metadata map; `{}` when the provider is absent;
+ *          null when the document could not be fetched/parsed
+ */
+export async function fetchModelsDevProvider(providerId) {
+    const parsed = await fetchModelsDevDocument();
+    if (parsed === null)
+        return null;
+    return extractProviderModels(parsed, providerId);
+}
+/** Clear the models.dev document cache (test helper). */
+export function resetModelsDevCache() {
+    documentCache = null;
+    documentRequest = null;
+}
+//# sourceMappingURL=models-dev.js.map

package/dist/models-dev.js.map

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

package/dist/models-refresh.d.ts

@@ -0,0 +1,144 @@
+/**
+ * models-refresh.ts — Deterministic generator for the bundled model catalog.
+ *
+ * `npm run models:refresh` (scripts/refresh-models.ts) is the only writer of
+ * `assets/models.json`. It merges models.dev metadata for the two providers
+ * this proxy serves with the live catalogs, so a model that no longer exists
+ * upstream leaves the bundle and a new one enters without a hand edit.
+ *
+ * The merge is a pure function (`mergeModelCatalog`) so the catalog rules are
+ * testable without network access:
+ *   - membership follows the live catalogs: a model the provider serves enters
+ *     with the metadata the live payload carries even when models.dev omits it,
+ *     and it stays while the provider keeps advertising it;
+ *   - `opencode-go` metadata wins when both providers know a model;
+ *   - a field already in the current file survives when models.dev is silent
+ *     about it (models.dev drops fields occasionally and a regeneration must
+ *     not discard the value);
+ *   - two raw ids that collapse to the same bare key abort the refresh;
+ *   - output keys, including nested object keys, are sorted so a refresh diff
+ *     only shows real changes;
+ *   - a failed fetch — or an empty/partial response — aborts before the file is
+ *     read, and a merge that would drop more than half of the current models
+ *     needs `allowShrink` before it writes anything.
+ */
+/** Public opencode-go catalog — no auth, but Cloudflare wants a CLI signature. */
+export declare const OPENCODE_GO_MODELS_URL = "https://opencode.ai/zen/go/v1/models";
+/** Public CommandCode catalog (200 with any or no Authorization header). */
+export declare const COMMANDCODE_MODELS_URL = "https://api.commandcode.ai/provider/v1/models";
+/**
+ * models.dev sits behind Cloudflare and answers 403 `error code: 1010` to
+ * browser-like or missing signatures. Any stable non-browser UA works.
+ */
+export declare const MODELS_REFRESH_USER_AGENT = "saros-proxy-models-refresh";
+/** Minimal fetch surface, injected in tests. */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** Fetch and validate the models.dev catalog. */
+export declare function fetchModelsDevCatalog(fetchImpl?: FetchLike, timeoutMs?: number): Promise<Record<string, unknown>>;
+/**
+ * One entry of a live provider catalog: the id plus the metadata the payload
+ * carries. `name` and `context_length` seed a catalog entry when models.dev
+ * does not know the model yet.
+ */
+export interface LiveModel {
+    id: string;
+    name?: string;
+    context_length?: number;
+}
+/**
+ * Fetch the opencode-go live catalog.
+ *
+ * The list is authoritative for membership: models.dev keeps models the
+ * provider already retired (`space-bunny`, `cat-jam-free`, …), and publishing
+ * those as connectable models is what this gate prevents.
+ */
+export declare function fetchOpencodeGoModels(fetchImpl?: FetchLike, timeoutMs?: number): Promise<LiveModel[]>;
+/**
+ * Fetch the CommandCode live catalog.
+ *
+ * Only models that advertise `/chat/completions` are usable through the proxy,
+ * which relays chat/completions shapes. `claude-*` entries list `/messages`
+ * only (verified live: chat/completions → unsupported_model); a vendor-prefixed
+ * Claude model would slip past a bare `^claude` test, so the endpoint field —
+ * not the id — decides.
+ */
+export declare function fetchCommandcodeModels(fetchImpl?: FetchLike, timeoutMs?: number): Promise<LiveModel[]>;
+/** Default network sources for the CLI. */
+export interface RefreshFetchers {
+    modelsDev: () => Promise<Record<string, unknown>>;
+    opencodeModels: () => Promise<readonly LiveModel[]>;
+    commandcodeModels: () => Promise<readonly LiveModel[]>;
+}
+/** Build the real fetchers — the only place the CLI touches the network. */
+export declare function defaultRefreshFetchers(): RefreshFetchers;
+/**
+ * Return one provider's `models` map from a parsed models.dev payload.
+ *
+ * Thin delegate: the parse lives in `models-dev.ts` so the generator and the
+ * runtime read agree on what a provider slice is.
+ */
+export declare function extractModelsDevProviderModels(parsed: Record<string, unknown>, providerId: string): Record<string, Record<string, unknown>>;
+export interface ModelCatalogMergeInput {
+    /** Parsed `https://models.dev/api.json`. */
+    modelsDev: Record<string, unknown>;
+    /** Live opencode-go `/models` entries. */
+    opencodeModels: readonly LiveModel[];
+    /** Live CommandCode `/provider/v1/models` entries (chat/completions only). */
+    commandcodeModels: readonly LiveModel[];
+    /** Current bundled catalog, parsed; null/absent for a fresh file. */
+    current?: Record<string, unknown> | null;
+}
+export interface ModelCatalogMergeResult {
+    /** Merged catalog with alphabetically sorted keys (top level and nested). */
+    models: Record<string, Record<string, unknown>>;
+    /** Keys that were absent from the current file. */
+    added: string[];
+    /** Keys that disappeared from both upstream catalogs. */
+    removed: string[];
+    /** Keys present in both files whose content changed. */
+    changed: string[];
+}
+/**
+ * Merge models.dev metadata with the live catalogs and the current file.
+ *
+ * Membership is decided by upstream: only ids that the live catalog advertises
+ * are kept, and a live id enters even when models.dev has never heard of it.
+ * Fields inside a surviving entry are additive — the current file's value
+ * survives whenever the upstream source does not carry that field.
+ */
+export declare function mergeModelCatalog(input: ModelCatalogMergeInput): ModelCatalogMergeResult;
+/** Stable on-disk format: 2-space indent, sorted keys, trailing newline. */
+export declare function serializeModelCatalog(models: Record<string, unknown>): string;
+/** Parse a catalog file. `null`/empty content is an empty catalog. */
+export declare function parseCatalogContent(raw: string | null): Record<string, unknown>;
+export interface RefreshIo {
+    /** Read the current catalog file, or null when it does not exist. */
+    read: () => string | null;
+    /** Write the new catalog file. */
+    write: (content: string) => void;
+}
+export interface RefreshOptions {
+    /** Show the diff and skip the write. */
+    dryRun?: boolean;
+    /** Allow a merge that removes more than half of the current models. */
+    allowShrink?: boolean;
+}
+export interface ModelCatalogRefreshResult extends ModelCatalogMergeResult {
+    previousContent: string | null;
+    nextContent: string;
+    /** False on a dry run and when the generated bytes already match the file. */
+    written: boolean;
+    /** True when only key order/whitespace differs from the file on disk. */
+    formattingOnly: boolean;
+}
+/**
+ * Fetch, merge, and (unless dry-running) write the catalog.
+ *
+ * Sources are validated before the file is read: a 2xx with an empty body (a
+ * Cloudflare hiccup, a partial rollout) used to empty the catalog and mark
+ * every model removed. A merge that would drop more than half of the current
+ * models is treated the same way unless `allowShrink` opts in.
+ */
+export declare function refreshModelCatalog(io: RefreshIo, fetchers?: RefreshFetchers, options?: RefreshOptions): Promise<ModelCatalogRefreshResult>;
+/** Human-readable model-level diff between the old and the new catalog. */
+export declare function formatCatalogDiff(previous: Record<string, unknown> | null, next: Record<string, unknown>): string;