agentsw 0.7.2 → 0.8.0

package/dist/i18n.js

@@ -1,7 +1,7 @@
 const messages = {
     "root.description": {
-        en: "Manage OpenAI/Anthropic-protocol model providers and sync them into coding agents\n(Claude Code, Codex, omp, pi, prime-agent, opencode, Hermes, WorkBuddy, DeepSeek Harness).\nModel metadata (context window, input/output limits, reasoning levels) is enriched from\nmodels.dev; existing providers can be imported from the agents and from cc-switch.\n\nRun without arguments (or via `npx agentsw`) for the interactive menu.",
-        "zh-CN": "管理 OpenAI / Anthropic 协议的模型供应商并同步到编码智能体\n(Claude Code、Codex、omp、pi、prime-agent、opencode、Hermes、WorkBuddy、DeepSeek Harness)。\n模型元数据(上下文、输入/输出上限、推理等级)由 models.dev 补全;\n也可从各智能体与 cc-switch 导入已有供应商。\n\n不带参数运行(或 `npx agentsw`)即可打开交互菜单。",
+        en: "Manage OpenAI/Anthropic-protocol model providers and sync them into coding agents\n(Claude Code, Codex, omp, pi, prime-agent, opencode, Hermes, WorkBuddy, DeepSeek Harness).\nModel metadata (context window, input/output limits, reasoning levels) is enriched from\nmodels.dev first, with automatic AI Gateway supplementation when needed.\nExisting providers can be imported from the agents and from cc-switch.\n\nRun without arguments (or via `npx agentsw`) for the interactive menu.",
+        "zh-CN": "管理 OpenAI / Anthropic 协议的模型供应商并同步到编码智能体\n(Claude Code、Codex、omp、pi、prime-agent、opencode、Hermes、WorkBuddy、DeepSeek Harness)。\n模型元数据(上下文、输入/输出上限、推理等级)优先由 models.dev 补全，必要时自动查询 AI Gateway；\n也可从各智能体与 cc-switch 导入已有供应商。\n\n不带参数运行(或 `npx agentsw`)即可打开交互菜单。",
     },
     "help.language": { en: "UI language: en | zh-CN (also AGENTSW_LANG)", "zh-CN": "界面语言: en | zh-CN (也可用 AGENTSW_LANG)" },
     "error.language": { en: "unsupported language \"{value}\"; use en or zh-CN", "zh-CN": "不支持语言 \"{value}\";请使用 en 或 zh-CN" },
@@ -16,12 +16,12 @@ const messages = {
     "cmd.sync": { en: "re-apply the active provider (or --provider) to app configs", "zh-CN": "将当前供应商(或 --provider)重新应用到应用配置" },
     "cmd.status": { en: "show detected apps and what they currently point at", "zh-CN": "显示检测到的应用及当前供应商" },
     "cmd.models": { en: "search models.dev, or show a configured provider's models", "zh-CN": "搜索 models.dev 或显示已配置供应商的模型" },
-    "cmd.discover": { en: "refresh a provider's models via /v1/models and models.dev", "zh-CN": "通过 /v1/models 和 models.dev 刷新供应商模型" },
+    "cmd.discover": { en: "refresh a provider's model list and configured metadata sources", "zh-CN": "获取供应商模型列表，并通过已启用的目录补全参数" },
     "cmd.import": { en: "scan app configs, preview and dedupe existing custom providers, then import", "zh-CN": "扫描应用配置,预览并去重已有自定义供应商后导入" },
     "cmd.apps": { en: "check installed agents: current version vs latest", "zh-CN": "检查智能体已安装版本与最新版本" },
     "cmd.install": { en: "install an agent CLI", "zh-CN": "安装智能体 CLI" },
     "cmd.upgrade": { en: "upgrade agent CLIs (no args = everything outdated)", "zh-CN": "升级智能体 CLI(无参数时升级全部过期项)" },
-    "cmd.refresh": { en: "re-fetch models.dev metadata for all providers", "zh-CN": "重新拉取所有供应商的 models.dev 元数据" },
+    "cmd.refresh": { en: "refresh metadata for saved models; optionally configure Gateway supplementation", "zh-CN": "刷新已有模型参数，可设置 Gateway 补充源（不改变模型列表）" },
     "opt.id": { en: "custom provider id (default: full hostname + protocol)", "zh-CN": "自定义供应商 ID（默认：完整域名 + 协议）" },
     "opt.name": { en: "display name", "zh-CN": "显示名称" },
     "opt.protocol": { en: "wire protocol: openai | anthropic", "zh-CN": "接口协议: openai | anthropic" },
@@ -41,6 +41,12 @@ const messages = {
     "opt.dedup": { en: "deduplicate model snapshot aliases", "zh-CN": "合并重复的模型快照别名" },
     "opt.noDedup": { en: "keep snapshot duplicates (-latest/date suffixes)", "zh-CN": "保留快照重复项(-latest/日期后缀)" },
     "opt.modelsDev": { en: "models.dev provider id for metadata matching", "zh-CN": "用于元数据匹配的 models.dev 供应商 id" },
+    "opt.metadataMode": { en: "save Gateway mode: auto (default, only when needed), on, or off; omission keeps saved mode", "zh-CN": "保存 Gateway 模式：auto（默认，按需补缺）、on 或 off；省略则沿用已保存模式" },
+    "opt.gatewayMetadata": { en: "always supplement from AI Gateway (same as --metadata-mode on)", "zh-CN": "始终使用 AI Gateway 补缺（等同 --metadata-mode on）" },
+    "opt.noGatewayMetadata": { en: "disable Gateway fetching; keep saved parameters (same as --metadata-mode off)", "zh-CN": "关闭 Gateway 获取，保留已保存参数（等同 --metadata-mode off）" },
+    "opt.gatewayModels": { en: 'replace exact aliases as JSON: {"local-id":"creator/model"}; {} clears them', "zh-CN": '用 JSON 替换精确映射：{"本地模型ID":"creator/model"}；{} 清空' },
+    "opt.metadataDetails": { en: "show field sources, conflicts and Gateway reference pricing as JSON (requires --provider)", "zh-CN": "以 JSON 查看字段来源、冲突和 Gateway 参考价格（需 --provider）" },
+    "opt.refreshProvider": { en: "refresh/configure only this saved provider (default: all)", "zh-CN": "仅刷新和设置该供应商（默认全部）" },
     "opt.yes": { en: "non-interactive; require all flags", "zh-CN": "非交互模式;要求提供全部参数" },
     "opt.prune": { en: "also remove entries from app configs", "zh-CN": "同时从应用配置中移除条目" },
     "opt.apps": { en: "comma-separated apps or 'all'", "zh-CN": "逗号分隔的应用或 'all'" },
@@ -75,6 +81,16 @@ const messages = {
     "menu.list": { en: "View providers saved in agentsw", "zh-CN": "查看 agentsw 供应商列表" },
     "menu.sync": { en: "Re-sync the current provider to agents", "zh-CN": "重新同步当前供应商" },
     "menu.discover": { en: "Update a provider's model list", "zh-CN": "更新供应商模型列表" },
+    "menu.metadata": { en: "Configure and refresh model metadata", "zh-CN": "设置并刷新模型参数补充源" },
+    "menu.metadataHelp": { en: "Keep the model list; choose automatic, always-on or disabled AI Gateway lookup, then refresh saved parameters only.", "zh-CN": "保留模型列表，选择 AI Gateway 自动按需、始终补充或关闭，仅刷新保存的参数。" },
+    "menu.metadataProvider": { en: "which provider's metadata settings should be updated?", "zh-CN": "选择要设置模型参数补充源的供应商" },
+    "menu.metadataMode": { en: "AI Gateway lookup mode (no API key is sent)", "zh-CN": "AI Gateway 查询模式（请求不携带 API key）" },
+    "menu.metadataAuto": { en: "Automatic (recommended)", "zh-CN": "自动按需（推荐）" },
+    "menu.metadataAutoHelp": { en: "models.dev first; query Gateway for missing core specs, to refresh its saved fields or verify tracked identity conflicts.", "zh-CN": "优先 models.dev；仅在核心参数缺失、需刷新已有 Gateway 字段或核实旧自动值身份冲突时查询。" },
+    "menu.metadataOn": { en: "Always supplement", "zh-CN": "始终补充" },
+    "menu.metadataOnHelp": { en: "Check Gateway on every metadata lookup; models.dev still takes priority.", "zh-CN": "每次补全参数都查询 Gateway，仍以 models.dev 为优先。" },
+    "menu.metadataOff": { en: "Disabled", "zh-CN": "关闭" },
+    "menu.metadataOffHelp": { en: "Never query Gateway; keep previously saved model parameters.", "zh-CN": "不查询 Gateway，保留已保存的模型参数。" },
     "menu.remove": { en: "Delete provider configuration", "zh-CN": "删除供应商配置" },
     "menu.rename": { en: "Change a provider ID", "zh-CN": "修改供应商 ID" },
     "menu.renameProvider": { en: "which provider ID should be changed?", "zh-CN": "选择要修改 ID 的供应商" },
@@ -172,7 +188,7 @@ const messages = {
     "add.added": { en: "added", "zh-CN": "已添加" },
     "add.updated": { en: "updated", "zh-CN": "已更新" },
     "add.saved": { en: "{status} provider {id} ({protocol})", "zh-CN": "{status}供应商 {id} ({protocol})" },
-    "add.metadata": { en: "models.dev metadata: {matched}/{total} models matched", "zh-CN": "models.dev 元数据:匹配 {matched}/{total} 个模型" },
+    "add.metadata": { en: "model metadata: {matched}/{total} models have a context limit", "zh-CN": "模型参数：{matched}/{total} 个模型已有上下文上限" },
     "add.providerHint": { en: " (provider hint: {hint})", "zh-CN": " (供应商提示:{hint})" },
     "add.next": { en: "next: agentsw use {id}", "zh-CN": "下一步: agentsw use {id}" },
     "quick.probing": { en: "probing protocols at {url} ...", "zh-CN": "正在探测 {url} 支持的协议..." },
@@ -186,7 +202,7 @@ const messages = {
     "menu.useHelp": { en: "Select a provider and default model, then write them to compatible agent configs.", "zh-CN": "选择供应商和默认模型，然后写入支持该协议的智能体配置。" },
     "menu.statusHelp": { en: "Show detected agents, their current providers and config file locations.", "zh-CN": "查看检测到的智能体、所用供应商及配置文件位置。" },
     "menu.listHelp": { en: "Show only the providers, protocols and default models saved in agentsw.", "zh-CN": "只查看 agentsw 已保存的供应商、协议和默认模型。" },
-    "menu.syncHelp": { en: "Write the current agentsw provider to agent configs without fetching a new model list.", "zh-CN": "将 agentsw 当前供应商写入智能体配置，不重新获取模型列表。" },
+    "menu.syncHelp": { en: "Write the current agentsw provider to agent configs without fetching a model list or metadata catalogs.", "zh-CN": "将 agentsw 当前供应商写入智能体配置，不重新获取模型列表或元数据目录。" },
     "menu.discoverHelp": { en: "Fetch models from the provider, fill in model metadata, and optionally sync to agents.", "zh-CN": "从供应商接口重新获取模型并补全模型参数，可选择同步到智能体。" },
     "menu.renameHelp": { en: "Change the config ID and update references; keep custom display names.", "zh-CN": "修改配置中的标识并更新关联引用，保留自定义显示名称。" },
     "menu.removeHelp": { en: "Choose where to delete: agentsw only, one agent only, or both.", "zh-CN": "先选择删除范围：仅 agentsw、仅某个智能体，或两处一起。" },

package/dist/index.js

@@ -63,6 +63,10 @@ program
     .option("--dedup", t("opt.dedup"))
     .option("--no-dedup", t("opt.noDedup"))
     .option("--models-dev <id>", t("opt.modelsDev"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .option("-y, --yes", t("opt.yes"))
     .action(cmdAdd);
 program
@@ -72,6 +76,10 @@ program
     .option("--name <name>", t("opt.name"))
     .option("--openai-api <flavor>", t("opt.openaiApi"))
     .option("--models-dev <id>", t("opt.modelsDev"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .option("--base-url <url>", t("opt.baseUrl"))
     .option("--api-key <key>", t("opt.apiKey"))
     .option("--default-model <id>", t("opt.defaultModel"))
@@ -126,6 +134,7 @@ program
     .command("models [query]")
     .description(t("cmd.models"))
     .option("-p, --provider <id>", t("opt.showProvider"))
+    .option("--metadata", t("opt.metadataDetails"))
     .option("-r, --refresh", t("opt.refresh"))
     .option("-l, --limit <n>", t("opt.limit"), "30")
     .action(cmdModels);
@@ -139,16 +148,32 @@ program
     .option("--dedup", t("opt.dedup"))
     .option("--no-dedup", t("opt.noDedup"))
     .option("--no-filter", t("opt.noFilter"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .action(cmdDiscover);
 program
     .command("import")
     .description(t("cmd.import"))
     .option("--all", t("opt.all"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
     .action(cmdImport);
 program.command("apps").description(t("cmd.apps")).action(cmdApps);
 program.command("install <app>").description(t("cmd.install")).action(cmdInstall);
 program.command("upgrade [apps...]").description(t("cmd.upgrade")).action(cmdUpgrade);
-program.command("refresh").description(t("cmd.refresh")).action(cmdRefreshMeta);
+program
+    .command("refresh")
+    .description(t("cmd.refresh"))
+    .option("-p, --provider <id>", t("opt.refreshProvider"))
+    .option("--metadata-mode <auto|on|off>", t("opt.metadataMode"))
+    .option("--gateway-metadata", t("opt.gatewayMetadata"))
+    .option("--no-gateway-metadata", t("opt.noGatewayMetadata"))
+    .option("--gateway-models <json>", t("opt.gatewayModels"))
+    .action(cmdRefreshMeta);
 program.parseAsync().catch((err) => {
     process.stderr.write(`error: ${err.message}\n`);
     process.exit(1);

package/dist/menu.js

@@ -1,7 +1,8 @@
 import pc from "picocolors";
 import prompts from "prompts";
-import { cmdAdd, cmdQuickAdd, cmdApps, cmdInstall, cmdDiscover, cmdImport, cmdList, cmdStatus, cmdSync, cmdUpgrade, cmdUse, } from "./commands.js";
+import { cmdAdd, cmdQuickAdd, cmdApps, cmdInstall, cmdDiscover, cmdImport, cmdRefreshMeta, cmdList, cmdStatus, cmdSync, cmdUpgrade, cmdUse, } from "./commands.js";
 import { getLocale, setLocale, t } from "./i18n.js";
+import { getMetadataMode } from "./metadata.js";
 import { loadStore, saveStore } from "./store.js";
 import { appPackages, appCommand, installedVersion } from "./apps.js";
 import { cmdRemoveProvider, cmdRename } from "./provider-actions.js";
@@ -166,6 +167,7 @@ export async function cmdMenu() {
                 { title: t("menu.list"), description: t("menu.listHelp"), value: "list" },
                 { title: t("menu.sync"), description: t("menu.syncHelp"), value: "sync" },
                 { title: t("menu.discover"), description: t("menu.discoverHelp"), value: "discover" },
+                { title: t("menu.metadata"), description: t("menu.metadataHelp"), value: "metadata" },
                 { title: t("menu.rename"), description: t("menu.renameHelp"), value: "rename" },
                 { title: t("menu.remove"), description: t("menu.removeHelp"), value: "remove" },
                 { title: t("menu.apps"), description: t("menu.appsHelp"), value: "apps" },
@@ -227,6 +229,25 @@ export async function cmdMenu() {
             const sync = await askToggle(t("menu.pushRefresh"));
             await cmdDiscover(picked.id, { sync });
         }
+        else if (action === "metadata") {
+            const picked = await pickProvider(t("menu.metadataProvider"));
+            if (!picked)
+                continue;
+            const current = loadStore().providers[picked.id];
+            const { metadataMode } = await prompts({
+                type: "select",
+                name: "metadataMode",
+                message: t("menu.metadataMode"),
+                hint: t("menu.selectInstructions"),
+                initial: ["auto", "on", "off"].indexOf(getMetadataMode(current)),
+                choices: [
+                    { title: t("menu.metadataAuto"), description: t("menu.metadataAutoHelp"), value: "auto" },
+                    { title: t("menu.metadataOn"), description: t("menu.metadataOnHelp"), value: "on" },
+                    { title: t("menu.metadataOff"), description: t("menu.metadataOffHelp"), value: "off" },
+                ],
+            }, cancel);
+            await cmdRefreshMeta({ provider: picked.id, metadataMode });
+        }
         else if (action === "rename" || action === "remove") {
             try {
                 if (action === "rename")

package/dist/metadata.js

@@ -0,0 +1,400 @@
+import { findModelMeta, getCatalogFetchedAt, toModelSpec } from "./modelsdev.js";
+import { loadGatewayCatalog } from "./gateway.js";
+const forbiddenKeys = new Set(["__proto__", "prototype", "constructor"]);
+const canonicalId = /^[^/\s]+\/[^/\s]+(?:\/[^/\s]+)*$/;
+export function getMetadataMode(settings) {
+    if (settings.gatewayMetadata === undefined || settings.gatewayMetadata === "auto")
+        return "auto";
+    if (settings.gatewayMetadata === true)
+        return "on";
+    if (settings.gatewayMetadata === false)
+        return "off";
+    throw new Error("Gateway metadata must be a boolean or auto");
+}
+function validateSettings(settings) {
+    const result = {};
+    if (settings.gatewayMetadata !== undefined) {
+        getMetadataMode(settings);
+        result.gatewayMetadata = settings.gatewayMetadata;
+    }
+    const aliases = settings.gatewayModelAliases;
+    if (aliases !== undefined) {
+        if (!aliases || typeof aliases !== "object" || Array.isArray(aliases)
+            || ![Object.prototype, null].includes(Object.getPrototypeOf(aliases))) {
+            throw new Error("Gateway model mappings must be a plain object of exact IDs to creator/model IDs");
+        }
+        const entries = Object.entries(aliases);
+        for (const [id, target] of entries) {
+            if (!id || /\s/.test(id) || forbiddenKeys.has(id) || typeof target !== "string" || !canonicalId.test(target)) {
+                throw new Error("Gateway model mappings must contain valid exact IDs and creator/model IDs");
+            }
+        }
+        result.gatewayModelAliases = Object.fromEntries(entries);
+    }
+    return result;
+}
+/** Validate before any mutation or fetch; omitted settings preserve the previous values. */
+export function resolveMetadataOptions(opts, previous) {
+    const settings = validateSettings(previous ?? {});
+    if (opts.gatewayMetadata !== undefined) {
+        if (typeof opts.gatewayMetadata !== "boolean")
+            throw new Error("Gateway metadata must be a boolean");
+        settings.gatewayMetadata = opts.gatewayMetadata;
+    }
+    if (opts.metadataMode !== undefined) {
+        if (opts.metadataMode !== "auto" && opts.metadataMode !== "on" && opts.metadataMode !== "off") {
+            throw new Error("Metadata mode must be auto, on, or off");
+        }
+        const mode = opts.metadataMode === "auto" ? "auto" : opts.metadataMode === "on";
+        if (opts.gatewayMetadata !== undefined && opts.gatewayMetadata !== mode) {
+            throw new Error("Metadata mode conflicts with Gateway metadata flag");
+        }
+        settings.gatewayMetadata = mode;
+    }
+    if (opts.gatewayModels !== undefined) {
+        if (typeof opts.gatewayModels !== "string")
+            throw new Error("Gateway model mappings must be a JSON object");
+        let aliases;
+        try {
+            aliases = JSON.parse(opts.gatewayModels);
+        }
+        catch {
+            throw new Error("Gateway model mappings must be a JSON object");
+        }
+        settings.gatewayModelAliases = validateSettings({ gatewayModelAliases: aliases }).gatewayModelAliases;
+    }
+    return settings;
+}
+const fields = [
+    "name", "contextWindow", "maxInput", "maxOutput", "reasoning", "reasoningEfforts", "imageInput",
+    "cost.input", "cost.output", "cost.cacheRead", "cost.cacheWrite",
+];
+const gatewayFields = fields.filter((field) => !field.startsWith("cost."));
+const limits = ["maxInput", "maxOutput"];
+const coreFields = ["contextWindow", "maxOutput", "reasoning", "imageInput"];
+function fieldValue(spec, field) {
+    if (field.startsWith("cost."))
+        return spec.cost?.[field.slice(5)];
+    return spec[field];
+}
+function setField(spec, field, value) {
+    if (field.startsWith("cost.")) {
+        const leaf = field.slice(5);
+        if (value === undefined) {
+            if (spec.cost)
+                delete spec.cost[leaf];
+        }
+        else {
+            spec.cost ??= {};
+            spec.cost[leaf] = value;
+        }
+    }
+    else {
+        const record = spec;
+        if (value === undefined)
+            delete record[field];
+        else
+            record[field] = Array.isArray(value) ? [...value] : value;
+    }
+}
+function equalValue(a, b) {
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((value, index) => value === b[index]);
+    return a === b;
+}
+function indexCatalog(catalog) {
+    const exact = new Map();
+    const canonical = new Map();
+    for (const provider of Object.values(catalog)) {
+        for (const [key, model] of Object.entries(provider.models)) {
+            const modelId = model.id.includes("/") ? model.id : `${provider.id}/${model.id}`;
+            const entry = { provider: provider.id, modelId, model };
+            for (const id of new Set([key, model.id])) {
+                const matches = exact.get(id);
+                if (matches)
+                    matches.push(entry);
+                else
+                    exact.set(id, [entry]);
+            }
+            const matches = canonical.get(modelId);
+            if (matches)
+                matches.push(entry);
+            else
+                canonical.set(modelId, [entry]);
+        }
+    }
+    return { exact, canonical };
+}
+function indexGatewayBareIds(gateway) {
+    const result = new Map();
+    for (const id of Object.keys(gateway.models)) {
+        const slash = id.indexOf("/");
+        if (slash < 1 || slash !== id.lastIndexOf("/") || !canonicalId.test(id))
+            continue;
+        const bare = id.slice(slash + 1);
+        result.set(bare, result.has(bare) ? null : id);
+    }
+    return result;
+}
+function selectExact(index, id, hint, aliases, gateway, gatewayBareIds) {
+    const alias = aliases && Object.hasOwn(aliases, id) ? aliases[id] : undefined;
+    const bare = !id.includes("/");
+    let gatewayId = alias;
+    if (gatewayId === undefined && gateway) {
+        if (canonicalId.test(id) && Object.hasOwn(gateway.models, id))
+            gatewayId = id;
+        else if (bare) {
+            const candidate = gatewayBareIds?.get(id);
+            const evidence = index?.exact.get(id);
+            const hintedEvidence = hint ? evidence?.filter((entry) => entry.provider === hint) : undefined;
+            const identities = new Set((hintedEvidence?.length ? hintedEvidence : evidence)?.map((entry) => entry.modelId));
+            // A unique exact basename is safe only with absent or agreeing primary evidence.
+            // Explicit provider hints can resolve primary ambiguity, but never Gateway ambiguity.
+            if (candidate && (identities.size === 0 || (identities.size === 1 && identities.has(candidate))))
+                gatewayId = candidate;
+        }
+    }
+    const candidates = gatewayId !== undefined
+        ? index?.canonical.get(gatewayId)
+        : (bare && hint ? index?.canonical.get(`${hint}/${id}`) : undefined)
+            ?? index?.canonical.get(id) ?? index?.exact.get(id);
+    const hinted = candidates?.find((entry) => entry.provider === hint);
+    const identities = new Set(candidates?.map((entry) => entry.modelId));
+    const primary = hinted ?? (identities.size === 1
+        ? candidates?.find((entry) => entry.modelId.startsWith(`${entry.provider}/`)) ?? candidates?.[0]
+        : undefined);
+    return { primary, gatewayId, alias };
+}
+function legacyPrimary(catalog, id, hint) {
+    const hit = findModelMeta(catalog, id, hint);
+    if (!hit)
+        return undefined;
+    const provider = Object.values(catalog).find((candidate) => candidate.id === hit.provider);
+    const base = id.slice(id.lastIndexOf("/") + 1).toLowerCase();
+    const model = provider && (Object.hasOwn(provider.models, id) ? provider.models[id]
+        : Object.entries(provider.models).find(([key]) => key.slice(key.lastIndexOf("/") + 1).toLowerCase() === base)?.[1]);
+    if (!model)
+        return undefined;
+    hit.spec.id = model.id;
+    return { spec: hit.spec, modelId: model.id.includes("/") ? model.id : `${hit.provider}/${model.id}` };
+}
+function clearGatewayIdentity(spec) {
+    const metadata = spec.metadata;
+    if (!metadata)
+        return;
+    for (const field of fields) {
+        const origin = metadata.fields?.[field];
+        if (origin?.source !== "ai-gateway")
+            continue;
+        if (equalValue(fieldValue(spec, field), origin.value))
+            setField(spec, field, undefined);
+        delete metadata.fields[field];
+    }
+    delete metadata.gateway;
+    if (metadata.conflicts)
+        metadata.conflicts = metadata.conflicts.filter((conflict) => conflict.source !== "ai-gateway");
+}
+function clearStaleIdentity(spec, modelId) {
+    const metadata = spec.metadata;
+    if (!metadata)
+        return;
+    for (const field of fields) {
+        const origin = metadata.fields?.[field];
+        if (!origin || origin.modelId === modelId)
+            continue;
+        if (equalValue(fieldValue(spec, field), origin.value))
+            setField(spec, field, undefined);
+        delete metadata.fields[field];
+    }
+    if (metadata.gateway && metadata.gateway.modelId !== modelId)
+        delete metadata.gateway;
+    if (metadata.conflicts)
+        metadata.conflicts = metadata.conflicts.filter((conflict) => conflict.modelId === modelId);
+}
+/** Apply a source as a set of field proposals, checking bounds against retained values first. */
+function mergeSource(spec, incoming, source, modelId, now, fetchedAt, supplementalGateway) {
+    const sourceFields = source === "ai-gateway" ? gatewayFields : fields;
+    const proposals = new Map();
+    const conflicts = [];
+    const conflict = (field, value, keptValue, blockedBy) => {
+        conflicts.push({ field, source, modelId, value: Array.isArray(value) ? [...value] : value,
+            keptValue: Array.isArray(keptValue) ? [...keptValue] : keptValue, ...(blockedBy ? { blockedBy } : {}) });
+    };
+    for (const field of sourceFields) {
+        const value = fieldValue(incoming, field);
+        if (value === undefined)
+            continue;
+        if (field === "name" && (value === incoming.id || value === modelId))
+            continue;
+        const current = fieldValue(spec, field);
+        const origin = spec.metadata?.fields?.[field];
+        if (current === undefined || (origin && (source === "models.dev" || origin.source === source))) {
+            proposals.set(field, value);
+        }
+        else if (!equalValue(current, value)) {
+            conflict(field, value, current);
+        }
+    }
+    // A proposed context may shrink only when every retained limit still fits.
+    let context = proposals.get("contextWindow") ?? spec.contextWindow;
+    if (typeof context === "number" && proposals.has("contextWindow")) {
+        for (const field of limits) {
+            const proposed = proposals.get(field);
+            const primaryFits = typeof proposed === "number" && proposed <= context;
+            let retained = primaryFits ? proposed : fieldValue(spec, field);
+            // The supplement runs next: account for a still-owned limit that it can
+            // lower in this same refresh, rather than requiring a second refresh.
+            const next = supplementalGateway && spec.metadata?.fields?.[field]?.source === "ai-gateway"
+                ? supplementalGateway[field] : undefined;
+            if (!primaryFits && typeof next === "number" && next <= context)
+                retained = next;
+            if (typeof retained === "number" && retained > context) {
+                conflict("contextWindow", context, retained, field);
+                proposals.delete("contextWindow");
+                context = spec.contextWindow;
+                break;
+            }
+        }
+    }
+    for (const field of limits) {
+        const value = proposals.get(field);
+        if (typeof value === "number" && typeof context === "number" && value > context) {
+            conflict(field, value, context, "contextWindow");
+            proposals.delete(field);
+        }
+    }
+    const reasoning = proposals.get("reasoning") ?? spec.reasoning;
+    if (reasoning === false) {
+        const efforts = proposals.get("reasoningEfforts");
+        const emptyEfforts = Array.isArray(efforts) && efforts.length === 0;
+        if (efforts !== undefined && !emptyEfforts) {
+            conflict("reasoningEfforts", efforts, false, "reasoning");
+            proposals.delete("reasoningEfforts");
+        }
+        // Do not introduce a contradictory false flag over retained effort settings.
+        if (proposals.has("reasoning") && spec.reasoning !== false && !emptyEfforts && spec.reasoningEfforts?.length) {
+            conflict("reasoning", false, spec.reasoningEfforts, "reasoningEfforts");
+            proposals.delete("reasoning");
+        }
+    }
+    const metadata = spec.metadata ??= {};
+    if (metadata.conflicts)
+        metadata.conflicts = metadata.conflicts.filter((entry) => entry.source !== source);
+    if (conflicts.length)
+        metadata.conflicts = [...(metadata.conflicts ?? []), ...conflicts];
+    for (const [field, value] of proposals) {
+        const previous = metadata.fields?.[field];
+        const unchanged = previous?.source === source && previous.modelId === modelId && equalValue(previous.value, value);
+        const origin = {
+            source, modelId, value: Array.isArray(value) ? [...value] : value,
+            updatedAt: unchanged ? previous.updatedAt : now,
+        };
+        const timestamp = fetchedAt ?? (unchanged ? previous.fetchedAt : undefined);
+        if (timestamp !== undefined)
+            origin.fetchedAt = timestamp;
+        (metadata.fields ??= {})[field] = origin;
+        setField(spec, field, value);
+    }
+}
+/** Supplement metadata only; IDs, routes, protocol and provider-effective pricing remain untouched. */
+export async function enrichProviderModels(catalog, ids, settings, options = {}) {
+    const validated = validateSettings(settings);
+    const mode = getMetadataMode(validated);
+    if (ids.length === 0)
+        return [];
+    const enabled = mode !== "off";
+    const index = enabled && catalog ? indexCatalog(catalog) : undefined;
+    const existing = new Map(settings.models?.map((model) => [model.id, model]));
+    const fetchedAt = catalog ? getCatalogFetchedAt(catalog) : undefined;
+    const now = new Date().toISOString();
+    const enrich = (gateway) => {
+        const gatewayBareIds = gateway ? indexGatewayBareIds(gateway) : undefined;
+        return ids.map((id) => {
+            const previous = existing.get(id);
+            const spec = previous ? structuredClone(previous) : { id };
+            for (const field of fields) {
+                const origin = spec.metadata?.fields?.[field];
+                if (origin && !equalValue(fieldValue(spec, field), origin.value))
+                    delete spec.metadata.fields[field];
+            }
+            let primary;
+            let supplement;
+            let match;
+            if (enabled) {
+                match = selectExact(index, id, settings.modelsDevId, validated.gatewayModelAliases, gateway, gatewayBareIds);
+                const oldGateway = spec.metadata?.gateway;
+                if (oldGateway && (oldGateway.alias !== match.alias
+                    || (match.gatewayId !== undefined && oldGateway.modelId !== match.gatewayId))) {
+                    clearGatewayIdentity(spec);
+                }
+                if (match.primary)
+                    primary = { spec: toModelSpec(match.primary.model.id, match.primary.model), modelId: match.primary.modelId };
+                if (gateway && match.gatewayId !== undefined && Object.hasOwn(gateway.models, match.gatewayId)) {
+                    supplement = gateway.models[match.gatewayId];
+                }
+                // An explicit mapping establishes identity even offline. An outage without
+                // a mapping or exact catalog evidence does not justify deleting metadata.
+                const confirmedId = match.alias ?? match.primary?.modelId ?? supplement?.id;
+                if (confirmedId !== undefined)
+                    clearStaleIdentity(spec, confirmedId);
+            }
+            else if (catalog) {
+                primary = legacyPrimary(catalog, id, settings.modelsDevId);
+            }
+            if (primary)
+                mergeSource(spec, primary.spec, "models.dev", primary.modelId, now, fetchedAt, supplement?.spec);
+            if (supplement && gateway && match) {
+                mergeSource(spec, supplement.spec, "ai-gateway", supplement.id, now, gateway.fetchedAt);
+                const audit = { modelId: supplement.id, fetchedAt: gateway.fetchedAt };
+                if (match.alias !== undefined)
+                    audit.alias = match.alias;
+                if (supplement.referenceCost !== undefined)
+                    audit.referenceCost = structuredClone(supplement.referenceCost);
+                if (supplement.pricingIsVariable !== undefined)
+                    audit.pricingIsVariable = supplement.pricingIsVariable;
+                (spec.metadata ??= {}).gateway = audit;
+            }
+            if (spec.metadata?.fields && Object.keys(spec.metadata.fields).length === 0)
+                delete spec.metadata.fields;
+            if (spec.metadata?.conflicts?.length === 0)
+                delete spec.metadata.conflicts;
+            if (spec.metadata && Object.keys(spec.metadata).length === 0)
+                delete spec.metadata;
+            return spec;
+        });
+    };
+    if (!enabled)
+        return enrich();
+    if (options.gateway !== undefined)
+        return enrich(options.gateway ?? undefined);
+    const primaryOnly = mode === "auto" ? enrich() : undefined;
+    if (primaryOnly && !primaryOnly.some((spec) => {
+        if (coreFields.some((field) => spec[field] === undefined)
+            || gatewayFields.some((field) => spec.metadata?.fields?.[field]?.source === "ai-gateway"))
+            return true;
+        // Complete legacy basename metadata still needs an exact identity check,
+        // unless an explicit mapping or current primary match already confirms it.
+        if (!canonicalId.test(spec.id) || !fields.some((field) => {
+            const origin = spec.metadata?.fields?.[field];
+            return origin && origin.modelId !== spec.id;
+        }))
+            return false;
+        const match = selectExact(index, spec.id, settings.modelsDevId, validated.gatewayModelAliases, undefined);
+        const confirmedId = match.alias ?? match.primary?.modelId ?? spec.id;
+        return fields.some((field) => {
+            const origin = spec.metadata?.fields?.[field];
+            return origin && origin.modelId !== confirmedId;
+        });
+    }))
+        return primaryOnly;
+    let gateway;
+    try {
+        gateway = await (options.gatewayLoader ?? loadGatewayCatalog)() ?? null;
+    }
+    catch {
+        gateway = null;
+    }
+    // Never feed the primary pre-pass back into merging: identity and coordinated
+    // bounds must be resolved with the supplement against the original values.
+    return gateway ? enrich(gateway) : primaryOnly ?? enrich();
+}