agentsw 0.7.2 → 0.8.0

package/README.md

@@ -45,7 +45,7 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
   keys it does not model — `authHeader`, `headers`, `compat`, `discovery` — per-model extras
   like `thinkingLevelMap`, and YAML comments all survive a re-sync.
 - **Model metadata, not just an id list.** Reseller `/v1/models` endpoints return bare ids.
-  agentsw enriches them from [models.dev](https://models.dev) and writes what each app
+  agentsw enriches them from [models.dev](https://models.dev), automatically fills meaningful gaps from AI Gateway when needed, and writes what each app
   actually reads: `thinkingLevelMap` for pi/prime, `limit`/`attachment` for opencode,
   `contextWindow`/`maxTokens` for omp, `reasoningEfforts`/`input` for dsh.
 - **Adopts what you already have** — including [cc-switch](https://github.com/farion1231/cc-switch).
@@ -146,8 +146,8 @@ use `--all` explicitly in scripts. Model discovery may update the local metadata
 ## Model discovery filters
 
 `--discover` lists model ids from the provider's `/v1/models`, then enriches each id from
-models.dev. Reseller lists are noisy, so filters are persisted per provider and re-applied on
-every `discover`:
+models.dev first, with automatic AI Gateway supplementation when needed. Reseller lists are noisy,
+so filters are persisted per provider and re-applied on every `discover`:
 
 ```bash
 # snapshot duplicates (gpt-5.2-latest, glm-4.7-250414, ...) are DROPPED by default
@@ -160,6 +160,77 @@ asw discover myproxy --no-filter                # clear it
 
 Explicit `--models` entries and the default model are never filtered out.
 
+## Automatic model metadata
+
+**No extra flags are needed.** New providers and providers without a saved mode use `auto`:
+models.dev is checked first, then the public
+[AI Gateway model catalog](https://vercel.com/docs/ai-gateway/models-and-providers#dynamic-model-discovery)
+is consulted only for missing core parameters (context window, maximum output, reasoning or image input),
+to refresh unchanged Gateway-supplied fields that models.dev has not replaced, or to verify an identity
+conflict in previously tracked automatic values. Missing names, prices, optional input limits or
+reasoning-effort lists alone do not trigger a Gateway lookup.
+agentsw directly fetches `https://ai-gateway.vercel.sh/v1/models` without provider credentials or an AI SDK dependency.
+
+```bash
+# Refresh only saved models using the saved mode (auto if unset)
+# No model discovery or agent config writes
+asw refresh --provider myproxy
+
+# Inspect effective mode, sources, conflicts and reference pricing (no API key)
+asw models --provider myproxy --metadata
+
+# Custom or ambiguous names need explicit aliases; wire model IDs stay unchanged
+asw refresh --provider myproxy --metadata-mode auto \
+  --gateway-models '{"my-model":"openai/gpt-5.4"}'
+
+# Always consult Gateway, even when core parameters are complete
+asw refresh --provider myproxy --metadata-mode on
+
+# Stop future Gateway fetches; retain saved model parameters
+asw refresh --provider myproxy --metadata-mode off
+
+# Return an explicitly disabled provider to automatic mode
+asw refresh --provider myproxy --metadata-mode auto
+
+# Preview and apply separately; sync does not query catalogs
+asw sync --provider myproxy --dry-run
+asw sync --provider myproxy
+```
+
+The menu's **Configure and refresh model metadata** action offers **Automatic (recommended)**,
+**Always supplement**, and **Disabled**, with the provider's current mode selected. Onboarding has no extra prompts.
+`add`, `quick`, `discover`, `import`, and `refresh` accept `--metadata-mode <auto|on|off>`.
+The existing `--gateway-metadata` and `--no-gateway-metadata` flags remain explicit `on` and `off` choices.
+Omitted options preserve saved settings: an existing `false` remains off until you select `auto` or `on`.
+Invalid modes and conflicting mode/boolean flags are rejected before fetching or saving.
+Without `--provider`, `refresh` applies to all providers, including any supplied mode.
+`--gateway-models` replaces the whole alias map (`{}` clears it); aliases do not change the saved mode or override `off`.
+Import still skips already configured accounts.
+
+- **Field-level priority:** manual values > models.dev > Gateway gap filling. Tracked automatic values may
+  refresh; subsequent manual edits are retained. Legacy values without provenance are conservatively treated
+  as manual overrides. Unmodeled extension fields survive enrichment too.
+- **Exact identities:** automatic lookup can map a bare, case-sensitive ID (no `/`) to a unique Gateway
+  `creator/model` identity when models.dev evidence is absent or agrees. Ambiguous creator evidence in either
+  catalog is rejected; custom or ambiguous names need explicit aliases. Qualified IDs never have their prefixes
+  stripped, and matching never guesses from substrings, case folding or versions. Auto/on mode also uses conservative
+  exact models.dev matching; off retains the legacy models.dev lookup. Unmatched models remain usable.
+  Alias changes clear unchanged automatic values tied to confirmed superseded identities, never manual edits.
+- **No routing changes:** metadata never adds available models or changes IDs, protocols, URLs, defaults or
+  accounts. Gateway capabilities are reference specs, not proof of reseller support. `supported_specifications`
+  is not a URL version.
+- **Reference-only prices:** Gateway prices are converted to USD per million tokens and stored separately in
+  `metadata.gateway.referenceCost`, not effective provider `cost` or runtime agent pricing. Variable/tiered
+  pricing is flagged separately.
+  Auto does not fetch solely to refresh this reference snapshot: check `metadata.gateway.fetchedAt`, or use
+  `refresh --provider <id> --metadata-mode on` to request fresh reference prices.
+- **Auditable and optional:** `metadata.fields` records origins, value snapshots and timestamps;
+  `metadata.conflicts` records disagreements with retained values. This audit stays in agentsw, never runtime agent configs.
+  Gateway has a separate 24-hour cache; failures use stale cached data or skip supplementation.
+- **Automatic lookup is not automatic sync:** enrichment updates saved metadata during add/quick/discover/import/refresh.
+  It does not add an automatic push to agents. Sync behavior is unchanged: ordinary `sync` only writes saved settings
+  and fetches neither model lists nor metadata catalogs.
+
 ## Commands
 
 | Command | What it does |
@@ -175,7 +246,8 @@ Explicit `--models` entries and the default model are never filtered out.
 | `sync` | re-apply the active provider (after an agent update, say) |
 | `discover <id> [--sync]` | refresh the model list + metadata from `/v1/models` |
 | `models [query]` | search the models.dev catalog |
-| `refresh` | re-fetch metadata for every configured provider |
+| `refresh [--provider <id>]` | refresh saved metadata and optionally configure Gateway; keep the model list |
+| `models --provider <id> --metadata` | inspect field sources, conflicts and reference pricing as JSON |
 | `prune <id>` / `remove <id> [--prune]` | remove from app configs / from the store |
 | `remove <id> --apps omp` | delete only the selected app's entry; supports `--dry-run` |
 | `apps` / `install <app>` / `upgrade` | agent version manager |

package/README.zh-CN.md

@@ -44,7 +44,7 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
   （`authHeader`、`headers`、`compat`、`discovery`）、`thinkingLevelMap` 之类的模型级字段、
   以及 YAML 注释，都会在重新同步后原样保留。
 - **写的是元数据，不只是模型 id。** 转售商 `/v1/models` 只返回裸 id；agentsw 从
-  [models.dev](https://models.dev) 补全，并按各应用真正读取的字段下发：pi/prime 的
+  [models.dev](https://models.dev) 优先补全，并在有实际缺口时自动查询 AI Gateway，按各应用真正读取的字段下发：pi/prime 的
   `thinkingLevelMap`、opencode 的 `limit`/`attachment`、omp 的 `contextWindow`/`maxTokens`、
   dsh 的 `reasoningEfforts`/`input`。
 - **接管你已有的配置——包括 [cc-switch](https://github.com/farion1231/cc-switch)。**
@@ -143,7 +143,7 @@ imported zhipu-glm · anthropic · https://open.bigmodel.cn/api/anthropic · 1 m
 
 ## 模型发现过滤
 
-`--discover` 从供应商 `/v1/models` 拉取模型 id，再从 models.dev 补全元数据。
+`--discover` 从供应商 `/v1/models` 拉取模型 id，优先从 models.dev 补全元数据，必要时自动查询 AI Gateway。
 转售商列表噪音大，过滤规则持久化在供应商上，每次 `discover` 自动复用：
 
 ```bash
@@ -157,6 +157,69 @@ asw discover myproxy --no-filter                # 清除规则
 
 手动 `--models` 指定的 id 和默认模型永不被过滤。
 
+## 自动补全模型元数据
+
+**默认无需额外参数。** 新供应商和未保存模式的供应商使用 `auto`：先查询 models.dev，
+仅在核心参数（上下文窗口、最大输出、推理或图片输入能力）仍缺失、已有 Gateway 自动字段
+未被手动修改或 models.dev 替代而需刷新，或需核实旧自动值的身份冲突时，才查询公开的
+[AI Gateway 模型目录](https://vercel.com/docs/ai-gateway/models-and-providers#dynamic-model-discovery)。
+仅缺名称、价格、可选输入上限或推理等级列表，不会触发 Gateway 查询。
+直接请求 `https://ai-gateway.vercel.sh/v1/models`，不携带供应商密钥，也不安装 AI SDK。
+
+```bash
+# 按保存的模式刷新已有模型参数（未设置时为 auto）
+# 不发现新模型、不写智能体配置
+asw refresh --provider myproxy
+
+# 查看生效模式、字段来源、冲突和参考价格；JSON 不含 API key
+asw models --provider myproxy --metadata
+
+# 自定义或有歧义的名称需显式映射；实际调用的模型 ID 不变
+asw refresh --provider myproxy --metadata-mode auto \
+  --gateway-models '{"my-model":"openai/gpt-5.4"}'
+
+# 即使核心参数完整，也始终查询 Gateway
+asw refresh --provider myproxy --metadata-mode on
+
+# 停止后续 Gateway 获取；保留已保存的参数
+asw refresh --provider myproxy --metadata-mode off
+
+# 将显式关闭的供应商恢复为自动模式
+asw refresh --provider myproxy --metadata-mode auto
+
+# 单独预览、同步；sync 不查询目录
+asw sync --provider myproxy --dry-run
+asw sync --provider myproxy
+```
+
+交互菜单的“设置并刷新模型参数补充源”提供“自动按需（推荐）”“始终补充”“关闭”，
+默认选中该供应商当前模式；添加供应商时不增加提问。
+`add`、`quick`、`discover`、`import`、`refresh` 均支持 `--metadata-mode <auto|on|off>`。
+原有 `--gateway-metadata` / `--no-gateway-metadata` 仍分别表示显式 `on` / `off`。
+省略参数会保留已保存的设置：已有 `false` 仍保持关闭，直到主动选择 `auto` 或 `on`。
+无效模式或相互冲突的模式/布尔开关，会在查询或保存之前报错。
+`refresh` 不传 `--provider` 会作用于全部供应商，包括更新传入的模式。
+`--gateway-models` 替换整个映射，传 `{}` 清空；映射不会更改保存的模式，也不会覆盖 `off`。
+导入仍跳过已经配置的账号。
+
+- **按字段合并：** 用户手动值优先，其次 models.dev，最后 Gateway 补缺。已记录来源的自动值可以刷新，
+  手动修改后会保留；旧版本中没有来源记录的已有值保守视为手动值，不强制覆盖。未知扩展字段也保留。
+- **精确匹配：** 不含 `/` 的裸 ID 可按大小写精确匹配唯一的 Gateway `creator/model` 身份，
+  前提是 models.dev 没有身份线索或线索一致。任一目录中的创建者身份有歧义时拒绝自动匹配；
+  自定义或有歧义的名称仍需显式映射。带命名空间的 ID 不会剥离前缀，不按子串、大小写折叠或版本相似度猜测。
+  `auto` / `on` 模式下 models.dev 也采用保守的精确匹配；`off` 保留原有 models.dev 查询行为。
+  匹配失败不妨碍模型继续使用。修改/删除映射时，只清理确认已失效身份的自动值，保留手动修改。
+- **不改变调用语义：** 目录不会给供应商增加模型，不改模型 ID、协议、URL、默认模型或账户；
+  Gateway 能力是参考规格，不保证转售商实际实现。`supported_specifications` 不是 URL 版本。
+- **价格仅供参考：** Gateway 价格转换为美元/百万 token，单独保存在 `metadata.gateway.referenceCost`，
+  不写入供应商的有效 `cost`，也不下发为智能体计费价格；分档/供应商差异另有标记。
+  自动模式不会仅为刷新参考价格而查询：可查看 `metadata.gateway.fetchedAt` 判断快照时间，
+  需要重新查询参考价格时使用 `refresh --provider <id> --metadata-mode on`。
+- **可追溯、可降级：** `metadata.fields` 记录来源、原值快照和时间，`metadata.conflicts` 记录保留值与冲突。
+  审计信息仅保存在 agentsw，不写入智能体运行配置。Gateway 目录独立缓存 24 小时；请求失败可使用旧缓存，无缓存时只跳过补充。
+- **自动查询不等于自动同步：** 添加、快速添加、发现、导入、刷新时补全保存的元数据，并不新增自动推送。
+  同步行为不变：普通 `sync` 仅写入已保存的设置，既不获取模型列表，也不请求元数据目录。
+
 ## 命令
 
 | 命令 | 作用 |
@@ -172,7 +235,8 @@ asw discover myproxy --no-filter                # 清除规则
 | `sync` | 重新应用当前供应商（比如某个智能体升级之后） |
 | `discover <id> [--sync]` | 从 `/v1/models` 刷新模型列表与元数据 |
 | `models [query]` | 搜索 models.dev 目录 |
-| `refresh` | 重新拉取所有供应商的元数据 |
+| `refresh [--provider <id>]` | 刷新已有模型参数，可设置 Gateway 补充源，不改变模型列表 |
+| `models --provider <id> --metadata` | 以 JSON 查看字段来源、冲突和参考价格 |
 | `prune <id>` / `remove <id> [--prune]` | 从各应用配置中清除 / 从存储中删除 |
 | `remove <id> --apps omp` | 仅删除指定智能体内的条目，支持 `--dry-run` |
 | `apps` / `install <app>` / `upgrade` | 智能体版本管理 |

package/dist/commands.js

@@ -7,7 +7,9 @@ import pc from "picocolors";
 import prompts from "prompts";
 import { loadStore, saveStore, getProvider, configFile } from "./store.js";
 import { scanCandidates, normalizeUrl, findMatchingProvider } from "./import.js";
-import { enrichModels, loadCatalog, searchCatalog } from "./modelsdev.js";
+import { loadCatalog, searchCatalog } from "./modelsdev.js";
+import { enrichProviderModels, getMetadataMode, resolveMetadataOptions } from "./metadata.js";
+import { loadGatewayCatalog } from "./gateway.js";
 import { resolveTargets, supportsProtocol, targets } from "./targets/index.js";
 import { discoverProviderModels, probeProtocols } from "./discover.js";
 import { appCommand, appPackages, installedVersion, isNewer, latestVersion, normalizeAppVersion, runShell } from "./apps.js";
@@ -15,6 +17,11 @@ import { drainPendingWrites, readTextIfExists, setDryRun } from "./fsutil.js";
 import { applyModelFilter } from "./filter.js";
 import { availableProviderId, providerIdFromBaseUrl, providerNameFromBaseUrl } from "./slug.js";
 import { t } from "./i18n.js";
+/** Share successes and failures without fetching until a model actually needs the supplement. */
+function sharedGatewayLoader(refresh = false) {
+    let pending;
+    return () => pending ??= loadGatewayCatalog({ refresh }).then((catalog) => catalog ?? null);
+}
 function fail(message) {
     process.stderr.write(pc.red(`error: ${message}\n`));
     process.exit(1);
@@ -58,16 +65,16 @@ function modelRows(models) {
         fmtTokens(m.contextWindow),
         fmtTokens(m.maxInput),
         fmtTokens(m.maxOutput),
-        m.reasoning ? (m.reasoningEfforts?.join("/") ?? "yes") : "no",
+        m.reasoning === undefined ? "-" : m.reasoning ? (m.reasoningEfforts?.length ? m.reasoningEfforts.join("/") : "yes") : "no",
         m.cost ? `$${m.cost.input ?? "?"}/$${m.cost.output ?? "?"}` : "-",
     ]);
 }
 const MODEL_HEADER = ["MODEL", "CTX", "IN", "OUT", "REASONING", "$IN/$OUT per M"];
-/** Print a dim hint when some models have no models.dev metadata. */
+/** Print a dim hint when some models have no catalog metadata. */
 function printUncatalogedHint(models) {
     const bare = models.filter((m) => m.contextWindow === undefined && !m.cost);
     if (bare.length > 0) {
-        console.log(pc.dim(`${bare.length} model(s) have no models.dev metadata (shown as "-")`));
+        console.log(pc.dim(`${bare.length} model(s) have no catalog metadata (shown as "-")`));
     }
 }
 /** Guess the models.dev provider whose API host matches the configured baseUrl. */
@@ -113,6 +120,7 @@ function reportDropped(dropped) {
 }
 export async function cmdAdd(opts) {
     const store = loadStore();
+    resolveMetadataOptions(opts);
     const interactive = process.stdin.isTTY && !opts.yes;
     let answers = {};
     if (interactive) {
@@ -192,6 +200,7 @@ export async function cmdAdd(opts) {
     const existing = explicitId ? store.providers[explicitId] : findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey: answers.apiKey });
     const id = explicitId ?? existing?.id ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
     const openaiApi = protocol === "openai" ? wire ?? existing?.openaiApi : undefined;
+    const metadataOptions = resolveMetadataOptions(opts, existing);
     const manualIds = (answers.models ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     let modelIds = manualIds;
     const modelFilter = parseFilterOpts(opts, existing?.modelFilter);
@@ -215,7 +224,7 @@ export async function cmdAdd(opts) {
         fail(t("add.atLeastOne"));
     const catalog = await loadCatalog();
     const hint = opts.modelsDev ?? existing?.modelsDevId ?? guessProviderHint(catalog, answers.baseUrl);
-    const models = enrichModels(catalog, modelIds, hint);
+    const models = await enrichProviderModels(catalog, modelIds, { ...metadataOptions, modelsDevId: hint, models: existing?.models });
     const matched = models.filter((m) => m.contextWindow !== undefined).length;
     const defaultModel = opts.defaultModel ?? existing?.defaultModel ?? modelIds[0];
     if (!modelIds.includes(defaultModel))
@@ -235,6 +244,7 @@ export async function cmdAdd(opts) {
         smallModel: opts.smallModel ?? existing?.smallModel,
         reasoningEffort: opts.reasoningEffort ?? existing?.reasoningEffort,
         modelsDevId: hint,
+        ...metadataOptions,
         modelFilter,
     };
     const existed = store.providers[provider.id] !== undefined;
@@ -252,9 +262,10 @@ export async function cmdAdd(opts) {
 /** Shared logic to create and save a single provider from discovered models. */
 async function createProvider(opts) {
     const { store, id, name, protocol, openaiApi, baseUrl, apiKey, modelIds, modelFilter } = opts;
+    const metadataOptions = resolveMetadataOptions(opts, opts.existing);
     const catalog = await loadCatalog();
     const hint = opts.modelsDev ?? opts.existing?.modelsDevId ?? guessProviderHint(catalog, baseUrl);
-    const models = enrichModels(catalog, modelIds, hint);
+    const models = await enrichProviderModels(catalog, modelIds, { ...metadataOptions, modelsDevId: hint, models: opts.existing?.models }, { gatewayLoader: opts.gatewayLoader });
     const matched = models.filter((m) => m.contextWindow !== undefined).length;
     const defaultModel = opts.defaultModel ?? opts.existing?.defaultModel ?? modelIds[0];
     if (!modelIds.includes(defaultModel))
@@ -275,6 +286,7 @@ async function createProvider(opts) {
         smallModel,
         reasoningEffort: opts.reasoningEffort ?? opts.existing?.reasoningEffort,
         modelsDevId: hint,
+        ...metadataOptions,
         modelFilter,
     };
     const existed = store.providers[provider.id] !== undefined;
@@ -295,6 +307,7 @@ async function createProvider(opts) {
  */
 export async function cmdQuickAdd(opts) {
     const store = loadStore();
+    resolveMetadataOptions(opts);
     const interactive = process.stdin.isTTY && !opts.yes;
     let baseUrl;
     let apiKey;
@@ -323,6 +336,7 @@ export async function cmdQuickAdd(opts) {
         fail(t("add.openaiApiInvalid"));
     const multi = protocols.length > 1;
     const createdIds = [];
+    const gatewayLoader = sharedGatewayLoader();
     for (const protocol of protocols) {
         const explicitId = opts.id === undefined ? undefined : `${opts.id}${multi ? `-${protocol}` : ""}`;
         const existing = explicitId === undefined ? findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey }) : store.providers[explicitId];
@@ -357,6 +371,10 @@ export async function cmdQuickAdd(opts) {
             existing,
             openaiApi: opts.openaiApi,
             modelsDev: opts.modelsDev,
+            gatewayMetadata: opts.gatewayMetadata,
+            gatewayModels: opts.gatewayModels,
+            metadataMode: opts.metadataMode,
+            gatewayLoader,
         });
         createdIds.push(provider.id);
         console.log(pc.dim(`\n${t("add.next", { id: provider.id })}`));
@@ -605,9 +623,21 @@ export function cmdStatus() {
     console.log(table(rows, ["APP", t("table.found"), t("table.protocols"), t("table.current"), t("table.config")]));
 }
 export async function cmdModels(query, opts) {
+    if (opts.metadata && !opts.provider)
+        fail("--metadata requires --provider");
     if (opts.provider) {
         const store = loadStore();
         const provider = getProvider(store, opts.provider);
+        if (opts.metadata) {
+            console.log(JSON.stringify({
+                provider: provider.id,
+                gatewayMetadata: provider.gatewayMetadata ?? "auto",
+                metadataMode: getMetadataMode(provider),
+                gatewayModelAliases: provider.gatewayModelAliases ?? {},
+                models: provider.models.map(({ id, metadata }) => ({ id, metadata })),
+            }, null, 2));
+            return;
+        }
         console.log(`${pc.bold(provider.id)} (${provider.protocol}) · ${provider.baseUrl}`);
         console.log(table(modelRows(provider.models), MODEL_HEADER));
         printUncatalogedHint(provider.models);
@@ -630,20 +660,26 @@ export async function cmdModels(query, opts) {
     });
     console.log(table(rows, ["PROVIDER", ...MODEL_HEADER]));
 }
-export async function cmdRefreshMeta() {
+export async function cmdRefreshMeta(opts = {}) {
     const store = loadStore();
+    const providers = opts.provider ? [getProvider(store, opts.provider)] : Object.values(store.providers);
+    resolveMetadataOptions(opts);
+    for (const provider of providers)
+        Object.assign(provider, resolveMetadataOptions(opts, provider));
     const catalog = await loadCatalog({ refresh: true });
-    if (!catalog)
-        fail("models.dev catalog unavailable");
+    const gatewayLoader = sharedGatewayLoader(true);
     let updated = 0;
-    for (const provider of Object.values(store.providers)) {
+    for (const provider of providers) {
         const before = JSON.stringify(provider.models);
-        provider.models = enrichModels(catalog, provider.models.map((m) => m.id), provider.modelsDevId ?? guessProviderHint(catalog, provider.baseUrl));
+        provider.models = await enrichProviderModels(catalog, provider.models.map((m) => m.id), {
+            ...provider,
+            modelsDevId: provider.modelsDevId ?? guessProviderHint(catalog, provider.baseUrl),
+        }, { gatewayLoader });
         if (JSON.stringify(provider.models) !== before)
             updated++;
     }
     saveStore(store);
-    console.log(pc.green(`refreshed models.dev metadata (${updated} provider(s) changed)`));
+    console.log(pc.green(`checked model metadata (${updated} provider(s) changed)`));
     if (updated > 0)
         console.log(pc.dim("run `agentsw sync` to push updated metadata into app configs"));
 }
@@ -651,6 +687,7 @@ export async function cmdDiscover(id, opts) {
     resolveTargets(opts.apps);
     const store = loadStore();
     const provider = getProvider(store, id);
+    Object.assign(provider, resolveMetadataOptions(opts, provider));
     // flags override and re-persist the filter; --no-filter clears it
     const flagFilter = parseFilterOpts(opts, provider.modelFilter);
     if (opts.filter === false)
@@ -659,17 +696,18 @@ export async function cmdDiscover(id, opts) {
         provider.modelFilter = flagFilter;
     process.stderr.write(pc.dim(`discovering models from ${provider.baseUrl} ...\n`));
     const listed = await discoverProviderModels(provider);
-    const outcome = applyModelFilter(listed, provider.modelFilter, [provider.defaultModel]);
+    const pinned = [provider.defaultModel, provider.smallModel].filter((model) => !!model);
+    const outcome = applyModelFilter(listed, provider.modelFilter, pinned);
     reportDropped(outcome.dropped);
     const ids = outcome.kept;
     const known = provider.models.map((m) => m.id);
     const added = ids.filter((m) => !known.includes(m));
     const gone = known.filter((m) => !ids.includes(m));
     const catalog = await loadCatalog();
-    provider.models = enrichModels(catalog, ids, provider.modelsDevId ?? guessProviderHint(catalog, provider.baseUrl));
+    const retainedIds = [...new Set([...ids, ...pinned])];
+    provider.models = await enrichProviderModels(catalog, retainedIds, { ...provider, modelsDevId: provider.modelsDevId ?? guessProviderHint(catalog, provider.baseUrl) });
     if (!ids.includes(provider.defaultModel)) {
         console.log(pc.yellow(`default model ${provider.defaultModel} no longer listed; keeping it anyway`));
-        provider.models.push({ id: provider.defaultModel });
     }
     saveStore(store);
     console.log(`${pc.bold(id)}: ${ids.length} models (${pc.green(`+${added.length}`)} / ${pc.red(`-${gone.length}`)})` +
@@ -820,6 +858,7 @@ export async function cmdUpgrade(ids) {
 }
 /** Collect custom providers, dedupe by endpoint and credentials, and import what is new. */
 export async function cmdImport(opts) {
+    const metadataOptions = resolveMetadataOptions(opts);
     const rows = scanCandidates();
     const fresh = rows.filter((r) => !r.configured);
     for (const r of rows) {
@@ -864,6 +903,7 @@ export async function cmdImport(opts) {
     }
     const store = loadStore();
     const catalog = await loadCatalog();
+    const gatewayLoader = sharedGatewayLoader();
     const imported = [];
     for (const c of chosen) {
         let apiKey = c.apiKey;
@@ -901,7 +941,7 @@ export async function cmdImport(opts) {
             fail(t("import.noModelsImport", { id: c.id }));
         const id = availableProviderId(c.id, store.providers);
         const hint = guessProviderHint(catalog, c.baseUrl);
-        const models = enrichModels(catalog, ids, hint);
+        const models = await enrichProviderModels(catalog, ids, { ...metadataOptions, modelsDevId: hint }, { gatewayLoader });
         const defaultModel = c.defaultModel && ids.includes(c.defaultModel) ? c.defaultModel : ids[0];
         const existed = store.providers[id] !== undefined;
         store.providers[id] = {
@@ -914,6 +954,7 @@ export async function cmdImport(opts) {
             models,
             defaultModel,
             modelsDevId: hint,
+            ...metadataOptions,
         };
         if (!store.active)
             store.active = id;

package/dist/gateway.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readJsonIfExists, writeFileAtomic } from "./fsutil.js";
+import { configDir } from "./store.js";
+const API_URL = "https://ai-gateway.vercel.sh/v1/models";
+const CACHE_FILE = path.join(configDir, "ai-gateway.json");
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_BODY_BYTES = 5 * 1024 * 1024;
+const REASONING_EFFORTS = {
+    none: true, minimal: true, low: true, medium: true, high: true, xhigh: true, max: true,
+};
+const PRICE_FIELDS = [
+    ["input", "input"],
+    ["output", "output"],
+    ["cachedInputTokens", "cacheRead"],
+    ["cacheCreationInputTokens", "cacheWrite"],
+];
+function isStringList(value) {
+    return Array.isArray(value) && value.length > 0 &&
+        value.every((entry) => typeof entry === "string" && entry.length > 0 && entry.trim() === entry);
+}
+function reasoningEfforts(options) {
+    if (!Array.isArray(options))
+        return undefined;
+    let effort;
+    for (const option of options) {
+        if (!option || typeof option !== "object" || Array.isArray(option) || !("type" in option) || option.type !== "effort")
+            continue;
+        if (effort)
+            return undefined; // Conflicting declarations are not an authoritative effort list.
+        effort = option;
+    }
+    const values = effort?.values;
+    if (!isStringList(values) || !values.every((value) => Object.hasOwn(REASONING_EFFORTS, value)))
+        return undefined;
+    return [...new Set(values)];
+}
+function perMillion(value) {
+    if (typeof value === "string") {
+        const text = value.trim();
+        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(text))
+            return undefined;
+        value = Number(text);
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+        return undefined;
+    const converted = value * 1_000_000;
+    return Number.isFinite(converted) ? converted : undefined;
+}
+/** Normalize public REST metadata without interpreting SDK versions as provider routing. */
+export function parseGatewayCatalog(body, fetchedAt) {
+    if (!body || typeof body !== "object" || Array.isArray(body) || !("data" in body) || !Array.isArray(body.data)) {
+        throw new Error("Invalid AI Gateway catalog");
+    }
+    const models = Object.create(null);
+    const seen = new Set();
+    for (const entry of body.data) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const row = entry;
+        if (typeof row.id !== "string" || !/^[^/\s]+(?:\/[^/\s]+)+$/.test(row.id))
+            continue;
+        if (seen.has(row.id))
+            throw new Error("Duplicate AI Gateway model identity");
+        seen.add(row.id);
+        if (row.type !== "language")
+            continue;
+        const spec = { id: row.id };
+        if (typeof row.name === "string" && row.name.trim())
+            spec.name = row.name;
+        const context = typeof row.context_window === "number" && Number.isSafeInteger(row.context_window) && row.context_window > 0
+            ? row.context_window : undefined;
+        const output = typeof row.max_tokens === "number" && Number.isSafeInteger(row.max_tokens) && row.max_tokens > 0
+            ? row.max_tokens : undefined;
+        // Neither member of an inconsistent pair is safe to treat as authoritative.
+        if (context === undefined || output === undefined || output <= context) {
+            if (context !== undefined)
+                spec.contextWindow = context;
+            if (output !== undefined)
+                spec.maxOutput = output;
+        }
+        const efforts = reasoningEfforts(row.reasoning_options);
+        if (efforts)
+            spec.reasoningEfforts = efforts;
+        if ((isStringList(row.tags) && row.tags.includes("reasoning")) || efforts?.some((effort) => effort !== "none")) {
+            spec.reasoning = true;
+        }
+        if (row.modalities && typeof row.modalities === "object" && !Array.isArray(row.modalities) &&
+            "input" in row.modalities && isStringList(row.modalities.input)) {
+            spec.imageInput = row.modalities.input.includes("image");
+        }
+        const model = { id: row.id, spec };
+        if (row.pricing && typeof row.pricing === "object" && !Array.isArray(row.pricing)) {
+            const pricing = row.pricing;
+            const referenceCost = {};
+            for (const [source, target] of PRICE_FIELDS) {
+                const price = perMillion(pricing[source]);
+                if (price !== undefined)
+                    referenceCost[target] = price;
+            }
+            if (Object.keys(referenceCost).length)
+                model.referenceCost = referenceCost;
+            if ((Array.isArray(pricing.inputTiers) && pricing.inputTiers.length > 0) ||
+                (Array.isArray(pricing.outputTiers) && pricing.outputTiers.length > 0)) {
+                model.pricingIsVariable = true;
+            }
+            else if (typeof pricing.varies_by_provider === "boolean") {
+                model.pricingIsVariable = pricing.varies_by_provider;
+            }
+        }
+        models[row.id] = model;
+    }
+    return { fetchedAt, models };
+}
+function readCache() {
+    try {
+        // Bound local reads as well; the persisted envelope is only slightly larger than the response.
+        if (fs.statSync(CACHE_FILE).size > MAX_BODY_BYTES + 1024)
+            return undefined;
+        const cache = readJsonIfExists(CACHE_FILE);
+        if (!cache || typeof cache !== "object" || Array.isArray(cache) ||
+            !("version" in cache) || cache.version !== 1 ||
+            !("fetchedAt" in cache) || typeof cache.fetchedAt !== "string" || !("body" in cache))
+            return undefined;
+        const timestamp = Date.parse(cache.fetchedAt);
+        if (!Number.isFinite(timestamp) || timestamp > Date.now() || new Date(timestamp).toISOString() !== cache.fetchedAt) {
+            return undefined;
+        }
+        return parseGatewayCatalog(cache.body, cache.fetchedAt);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readResponseBody(response) {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null && Number(contentLength) > MAX_BODY_BYTES) {
+        await response.body?.cancel().catch(() => { });
+        throw new Error("AI Gateway catalog exceeds size limit");
+    }
+    if (!response.body)
+        throw new Error("Missing AI Gateway catalog body");
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_BODY_BYTES)
+                throw new Error("AI Gateway catalog exceeds size limit");
+            chunks.push(decoder.decode(value, { stream: true }));
+        }
+        chunks.push(decoder.decode());
+        return chunks.join("");
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Optional supplement: offline never fetches, and every failure leaves discovery usable. */
+export async function loadGatewayCatalog(opts = {}) {
+    const cached = readCache();
+    if (opts.offline)
+        return cached;
+    if (!opts.refresh && cached && Date.now() - Date.parse(cached.fetchedAt) < CACHE_TTL_MS)
+        return cached;
+    try {
+        const response = await fetch(API_URL, {
+            signal: AbortSignal.timeout(15_000),
+            credentials: "omit",
+            redirect: "error",
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw new Error("AI Gateway catalog request failed");
+        }
+        const body = JSON.parse(await readResponseBody(response));
+        const catalog = parseGatewayCatalog(body, new Date().toISOString());
+        try {
+            writeFileAtomic(CACHE_FILE, JSON.stringify({ version: 1, fetchedAt: catalog.fetchedAt, body }) + "\n", 0o600);
+        }
+        catch {
+            process.stderr.write("warning: could not cache AI Gateway metadata\n");
+        }
+        return catalog;
+    }
+    catch {
+        process.stderr.write(cached
+            ? "warning: could not refresh AI Gateway metadata; using cached metadata\n"
+            : "warning: could not load AI Gateway metadata\n");
+        return cached;
+    }
+}