agentsw 0.7.1 → 0.8.0

package/dist/commands.js

@@ -1,15 +1,27 @@
+import path from "node:path";
+import { parse as parseJsonc } from "jsonc-parser";
+import { parse as parseToml } from "smol-toml";
+import { parseDocument } from "yaml";
+import { envAssignments } from "./envfile.js";
 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, runShell } from "./apps.js";
+import { appCommand, appPackages, installedVersion, isNewer, latestVersion, normalizeAppVersion, runShell } from "./apps.js";
 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);
@@ -53,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. */
@@ -89,14 +101,15 @@ function guessProviderHint(catalog, baseUrl) {
     }
     return undefined;
 }
-function parseFilterOpts(opts) {
-    const split = (s) => s?.split(",").map((x) => x.trim()).filter(Boolean);
-    const include = split(opts.include);
-    const exclude = split(opts.exclude);
-    // dedup (dropping snapshot duplicates) is on by default; persist only the opt-out
-    if (!include?.length && !exclude?.length && opts.dedup !== false)
-        return undefined;
-    return { include, exclude, ...(opts.dedup === false ? { dedup: false } : {}) };
+function parseFilterOpts(opts, previous) {
+    if (opts.include === undefined && opts.exclude === undefined && opts.dedup === undefined)
+        return previous;
+    return {
+        ...previous,
+        ...(opts.include !== undefined ? { include: opts.include.split(",").map((x) => x.trim()).filter(Boolean) } : {}),
+        ...(opts.exclude !== undefined ? { exclude: opts.exclude.split(",").map((x) => x.trim()).filter(Boolean) } : {}),
+        ...(opts.dedup !== undefined ? { dedup: opts.dedup } : {}),
+    };
 }
 function reportDropped(dropped) {
     if (!dropped.length)
@@ -107,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) {
@@ -179,13 +193,17 @@ export async function cmdAdd(opts) {
     if (protocol !== "openai" && protocol !== "anthropic")
         fail(t("add.protocolInvalid"));
     const wire = answers.openaiApi ?? opts.openaiApi;
-    if (wire && wire !== "completions" && wire !== "responses")
+    if (wire !== undefined && wire !== "completions" && wire !== "responses")
         fail(t("add.openaiApiInvalid"));
-    const openaiApi = protocol === "openai" ? wire : undefined;
     const baseUrl = normalizeUrl(answers.baseUrl);
+    const explicitId = answers.id || undefined;
+    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);
+    const modelFilter = parseFilterOpts(opts, existing?.modelFilter);
     const shouldDiscover = opts.discover || manualIds.length === 0;
     if (shouldDiscover) {
         if (!opts.discover) {
@@ -196,36 +214,37 @@ export async function cmdAdd(opts) {
         console.log(t("add.providerLists", { count: discovered.length }));
         modelIds = [...new Set([...manualIds, ...discovered])];
     }
-    const pinned = [...manualIds, ...(opts.defaultModel ? [opts.defaultModel] : [])];
+    const retained = [opts.defaultModel === undefined ? existing?.defaultModel : undefined, opts.smallModel === undefined ? existing?.smallModel : undefined].filter((id) => !!id);
+    modelIds = [...new Set([...modelIds, ...retained])];
+    const pinned = [...manualIds, ...retained, ...(opts.defaultModel ? [opts.defaultModel] : []), ...(opts.smallModel ? [opts.smallModel] : [])];
     const outcome = applyModelFilter(modelIds, modelFilter, pinned);
     reportDropped(outcome.dropped);
     modelIds = outcome.kept;
     if (modelIds.length === 0)
         fail(t("add.atLeastOne"));
     const catalog = await loadCatalog();
-    const hint = opts.modelsDev ?? guessProviderHint(catalog, answers.baseUrl);
-    const models = enrichModels(catalog, modelIds, hint);
+    const hint = opts.modelsDev ?? existing?.modelsDevId ?? guessProviderHint(catalog, answers.baseUrl);
+    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 ?? modelIds[0];
+    const defaultModel = opts.defaultModel ?? existing?.defaultModel ?? modelIds[0];
     if (!modelIds.includes(defaultModel))
         fail(t("add.defaultMissing", { model: defaultModel }));
     if (opts.smallModel && !modelIds.includes(opts.smallModel))
         fail(t("add.smallMissing", { model: opts.smallModel }));
-    const explicitId = answers.id || undefined;
-    const existing = explicitId ? undefined : findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey: answers.apiKey });
-    const id = explicitId ?? existing?.id ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
     const provider = {
+        ...existing,
         id,
         name: answers.name || existing?.name || (explicitId ? explicitId : providerNameFromBaseUrl(baseUrl, protocol)),
         protocol,
-        ...(openaiApi ? { openaiApi } : {}),
+        openaiApi,
         baseUrl,
         apiKey: answers.apiKey,
         models,
         defaultModel,
-        smallModel: opts.smallModel,
-        reasoningEffort: opts.reasoningEffort,
+        smallModel: opts.smallModel ?? existing?.smallModel,
+        reasoningEffort: opts.reasoningEffort ?? existing?.reasoningEffort,
         modelsDevId: hint,
+        ...metadataOptions,
         modelFilter,
     };
     const existed = store.providers[provider.id] !== undefined;
@@ -243,25 +262,31 @@ 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 = guessProviderHint(catalog, baseUrl);
-    const models = enrichModels(catalog, modelIds, hint);
+    const hint = opts.modelsDev ?? opts.existing?.modelsDevId ?? guessProviderHint(catalog, baseUrl);
+    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 ?? modelIds[0];
+    const defaultModel = opts.defaultModel ?? opts.existing?.defaultModel ?? modelIds[0];
     if (!modelIds.includes(defaultModel))
         fail(t("add.defaultMissing", { model: defaultModel }));
+    const smallModel = opts.smallModel ?? opts.existing?.smallModel;
+    if (smallModel && !modelIds.includes(smallModel))
+        fail(t("add.smallMissing", { model: smallModel }));
     const provider = {
+        ...opts.existing,
         id,
         name,
         protocol,
-        ...(openaiApi ? { openaiApi } : {}),
+        openaiApi: protocol === "openai" ? openaiApi ?? opts.existing?.openaiApi : undefined,
         baseUrl,
         apiKey,
         models,
         defaultModel,
-        smallModel: opts.smallModel,
-        reasoningEffort: opts.reasoningEffort,
+        smallModel,
+        reasoningEffort: opts.reasoningEffort ?? opts.existing?.reasoningEffort,
         modelsDevId: hint,
+        ...metadataOptions,
         modelFilter,
     };
     const existed = store.providers[provider.id] !== undefined;
@@ -282,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;
@@ -306,19 +332,23 @@ export async function cmdQuickAdd(opts) {
     if (protocols.length === 0) {
         fail(t("quick.noProtocol"));
     }
-    const modelFilter = parseFilterOpts(opts);
+    if (opts.openaiApi !== undefined && opts.openaiApi !== "completions" && opts.openaiApi !== "responses")
+        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 }) : undefined;
+        const existing = explicitId === undefined ? findMatchingProvider(Object.values(store.providers), { protocol, baseUrl, apiKey }) : store.providers[explicitId];
         const id = explicitId ?? existing?.id ?? availableProviderId(providerIdFromBaseUrl(baseUrl, protocol), store.providers);
-        const name = existing?.name ?? (opts.id === undefined ? providerNameFromBaseUrl(baseUrl, protocol) : multi ? `${opts.id} (${protocol})` : opts.id);
+        const name = opts.name ?? existing?.name ?? (opts.id === undefined ? providerNameFromBaseUrl(baseUrl, protocol) : multi ? `${opts.id} (${protocol})` : opts.id);
+        const modelFilter = parseFilterOpts(opts, existing?.modelFilter);
         process.stderr.write(pc.dim(`${t("add.discovering", { url: baseUrl })} [${protocol}]\n`));
         const discovered = await discoverProviderModels({ baseUrl, apiKey, protocol });
         console.log(t("add.providerLists", { count: discovered.length }));
-        let modelIds = discovered;
-        const pinned = [...(opts.defaultModel ? [opts.defaultModel] : [])];
+        const retained = [opts.defaultModel === undefined ? existing?.defaultModel : undefined, opts.smallModel === undefined ? existing?.smallModel : undefined].filter((id) => !!id);
+        let modelIds = [...new Set([...discovered, ...retained])];
+        const pinned = [...retained, ...(opts.defaultModel ? [opts.defaultModel] : []), ...(opts.smallModel ? [opts.smallModel] : [])];
         const outcome = applyModelFilter(modelIds, modelFilter, pinned);
         reportDropped(outcome.dropped);
         modelIds = outcome.kept;
@@ -338,6 +368,13 @@ export async function cmdQuickAdd(opts) {
             smallModel: opts.smallModel,
             reasoningEffort: opts.reasoningEffort,
             modelFilter,
+            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 })}`));
@@ -384,7 +421,7 @@ function reportResults(results) {
             console.log(`     ${" ".repeat(9)} ${pc.dim(note)}`);
     }
 }
-async function runTargets(op, provider, appsFilter) {
+async function runTargets(op, provider, appsFilter, redactErrors = false) {
     const selected = resolveTargets(appsFilter);
     const explicit = appsFilter !== undefined && appsFilter !== "all";
     const results = [];
@@ -398,48 +435,131 @@ async function runTargets(op, provider, appsFilter) {
             });
             continue;
         }
-        if (!target.detect() && !explicit) {
-            results.push({ app: target.id, changed: [], notes: [], skipped: `${target.name} not detected (pass --apps ${target.id} to force)` });
-            continue;
-        }
         try {
+            if (!explicit && !target.detect()) {
+                results.push({ app: target.id, changed: [], notes: [], skipped: `${target.name} not detected (pass --apps ${target.id} to force)` });
+                continue;
+            }
             results.push(await target[op](provider));
         }
         catch (err) {
-            results.push({ app: target.id, changed: [], notes: [], skipped: pc.red(`failed: ${err.message}`) });
+            results.push({ app: target.id, changed: [], notes: [], skipped: pc.red(redactErrors ? "failed: configuration could not be previewed safely" : `failed: ${err.message}`) });
             process.exitCode = 1;
         }
     }
     return results;
 }
-/** naive line diff for config previews: order-preserving added/removed lines */
-function printFileDiff(file, next) {
+/** Parse first: an unknown format or malformed document must never fall back to raw secrets. */
+function previewDocument(file, text) {
+    if (!text.trim())
+        return undefined;
+    if (path.basename(file) === ".env" || file.endsWith(".env")) {
+        return Object.fromEntries(envAssignments(file, text).map(({ name }) => [name, "[REDACTED]"]));
+    }
+    switch (path.extname(file).toLowerCase()) {
+        case ".json":
+        case ".jsonc": {
+            const errors = [];
+            const value = parseJsonc(text, errors, { allowTrailingComma: true });
+            if (errors.length)
+                throw new Error("invalid JSON configuration");
+            return value;
+        }
+        case ".toml": return parseToml(text);
+        case ".yaml":
+        case ".yml": {
+            const document = parseDocument(text);
+            if (document.errors.length)
+                throw new Error("invalid YAML configuration");
+            return document.toJS();
+        }
+        default: throw new Error("unsupported configuration format");
+    }
+}
+/** Normalized semantic diff: comments and unparseable raw input never enter output. */
+function printFileDiff(file, next, apiKey) {
     const before = readTextIfExists(file) ?? "";
     if (before === next) {
         console.log(`${pc.dim("unchanged")} ${file}`);
         return;
     }
-    console.log(pc.bold(`--- ${file}`));
-    const oldLines = before.split("\n");
-    const newLines = next.split("\n");
-    const oldSeen = {};
-    for (const l of oldLines)
-        oldSeen[l] = (oldSeen[l] ?? 0) + 1;
-    const newSeen = {};
-    for (const l of newLines)
-        newSeen[l] = (newSeen[l] ?? 0) + 1;
-    for (const l of oldLines) {
-        if ((newSeen[l] ?? 0) > 0)
-            newSeen[l]--;
+    console.log(pc.bold(`--- ${file} (redacted configuration)`));
+    let oldText;
+    let newText;
+    try {
+        const oldDocument = previewDocument(file, before);
+        const newDocument = previewDocument(file, next);
+        const sensitive = /key|token|secret|password|auth|credential|cookie|headers/i;
+        const credentialFile = path.basename(file) === ".credentials.yaml";
+        const secrets = new Set(apiKey ? [apiKey] : []);
+        const visited = new WeakSet();
+        const collect = (value, hidden = false) => {
+            if (typeof value === "string" && hidden && value)
+                secrets.add(value);
+            if (!value || typeof value !== "object" || visited.has(value))
+                return;
+            visited.add(value);
+            for (const [key, child] of Object.entries(value))
+                collect(child, hidden || sensitive.test(key));
+        };
+        collect(oldDocument, credentialFile);
+        collect(newDocument, credentialFile);
+        const orderedSecrets = [...secrets].sort((a, b) => b.length - a.length);
+        const redact = (key, value) => {
+            if (sensitive.test(key))
+                return "[REDACTED]";
+            if ((key === "" || credentialFile) && typeof value === "string")
+                return "[REDACTED]";
+            if (typeof value !== "string")
+                return value;
+            let safe = value;
+            if (/^https?:\/\//i.test(safe)) {
+                const url = new URL(safe);
+                if (url.username)
+                    url.username = "[REDACTED]";
+                if (url.password)
+                    url.password = "[REDACTED]";
+                for (const name of new Set(url.searchParams.keys()))
+                    if (sensitive.test(name))
+                        url.searchParams.set(name, "[REDACTED]");
+                url.hash = "";
+                safe = url.toString();
+            }
+            for (const secret of orderedSecrets)
+                safe = safe.split(secret).join("[REDACTED]");
+            return safe.replace(/\b(?:Bearer|Basic)\s+[^\s"',;]+/gi, "[REDACTED]");
+        };
+        oldText = JSON.stringify(oldDocument, redact, 2) ?? "";
+        newText = JSON.stringify(newDocument, redact, 2) ?? "";
+    }
+    catch {
+        console.log(pc.dim("[content withheld: unsupported or malformed configuration]"));
+        return;
+    }
+    const oldLines = oldText.split("\n");
+    const newLines = newText.split("\n");
+    const oldSeen = new Map();
+    for (const line of oldLines)
+        oldSeen.set(line, (oldSeen.get(line) ?? 0) + 1);
+    const newSeen = new Map();
+    for (const line of newLines)
+        newSeen.set(line, (newSeen.get(line) ?? 0) + 1);
+    for (const line of oldLines) {
+        const count = newSeen.get(line) ?? 0;
+        if (count > 0)
+            newSeen.set(line, count - 1);
         else
-            console.log(pc.red(`- ${l}`));
+            console.log(pc.red(`- ${line}`));
     }
-    for (const l of newLines) {
-        if ((oldSeen[l] ?? 0) > 0)
-            oldSeen[l]--;
+    for (const line of newLines) {
+        const count = oldSeen.get(line) ?? 0;
+        if (count > 0)
+            oldSeen.set(line, count - 1);
         else
-            console.log(pc.green(`+ ${l}`));
+            console.log(pc.green(`+ ${line}`));
     }
+    if (oldText === newText)
+        console.log(pc.dim("[only redacted values or formatting changed]"));
 }
 async function runWithOptionalDryRun(op, provider, apps, dryRun) {
     if (!dryRun) {
@@ -448,7 +568,7 @@ async function runWithOptionalDryRun(op, provider, apps, dryRun) {
     }
     setDryRun(true);
     try {
-        const results = await runTargets(op, provider, apps);
+        const results = await runTargets(op, provider, apps, true);
         const writes = drainPendingWrites();
         for (const r of results) {
             if (r.skipped)
@@ -456,13 +576,14 @@ async function runWithOptionalDryRun(op, provider, apps, dryRun) {
         }
         console.log(pc.bold(`\ndry run — ${writes.length} file(s) would be written:\n`));
         for (const w of writes)
-            printFileDiff(w.file, w.content);
+            printFileDiff(w.file, w.content, provider.apiKey);
     }
     finally {
         setDryRun(false);
     }
 }
 export async function cmdUse(id, opts) {
+    resolveTargets(opts.apps);
     const store = loadStore();
     const provider = getProvider(store, id);
     if (opts.model) {
@@ -479,6 +600,7 @@ export async function cmdUse(id, opts) {
     await runWithOptionalDryRun("apply", provider, opts.apps, opts.dryRun);
 }
 export async function cmdSync(opts) {
+    resolveTargets(opts.apps);
     const store = loadStore();
     const id = opts.provider ?? store.active;
     if (!id)
@@ -501,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);
@@ -526,45 +660,54 @@ 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"));
 }
 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);
+    const flagFilter = parseFilterOpts(opts, provider.modelFilter);
     if (opts.filter === false)
         provider.modelFilter = undefined;
     else if (flagFilter)
         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}`)})` +
@@ -582,18 +725,29 @@ export async function cmdDiscover(id, opts) {
 }
 async function collectAppRows() {
     return Promise.all(appPackages.map(async (app) => {
-        const [installed, latest] = await Promise.all([
-            Promise.resolve(installedVersion(app)),
+        const [installedResult, latestResult] = await Promise.allSettled([
+            Promise.resolve().then(() => installedVersion(app)),
             latestVersion(app),
         ]);
-        const knownInstalled = !!installed && installed !== "?";
+        const installed = installedResult.status === "fulfilled" ? installedResult.value : "?";
+        const latest = latestResult.status === "fulfilled" ? latestResult.value : undefined;
+        const knownInstalled = normalizeAppVersion(installed);
+        const knownLatest = normalizeAppVersion(latest);
+        const checkFailed = installedResult.status === "rejected"
+            ? "installed version check failed"
+            : installed && !knownInstalled
+                ? "installed version unknown"
+                : installed && !knownLatest
+                    ? "latest version unavailable"
+                    : undefined;
         return {
             id: app.id,
             name: app.name,
             installed,
             latest,
-            upgradable: knownInstalled && !!latest && isNewer(installed, latest),
+            upgradable: !!knownInstalled && !!knownLatest && isNewer(knownInstalled, knownLatest),
             installable: !installed && !!appCommand(app, "install"),
+            checkFailed,
         };
     }));
 }
@@ -610,7 +764,7 @@ export async function cmdApps() {
                 ? r.installable
                     ? pc.dim("installable")
                     : pc.dim("-")
-                : r.installed === "?" || !r.latest
+                : r.checkFailed || !normalizeAppVersion(r.latest)
                     ? pc.dim("unknown")
                     : pc.green("up to date"),
     ]), ["APP", "INSTALLED", "LATEST", "STATUS"]));
@@ -632,38 +786,69 @@ export async function cmdInstall(id) {
     }
     console.log(`installing ${app.name}: ${pc.dim(installCmd)}`);
     runShell(installCmd);
-    console.log(pc.green(`${app.name} installed: ${installedVersion(app) ?? "version unknown"}`));
+    const detected = installedVersion(app);
+    if (!detected)
+        throw new Error(`${app.name}: installer completed but the app is still not detected; check the installation and PATH`);
+    const version = normalizeAppVersion(detected);
+    if (!version) {
+        console.log(pc.yellow(`${app.name}: installer completed; app detected but version unknown`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(pc.green(`${app.name} installed: ${version}`));
 }
 export async function cmdUpgrade(ids) {
     let selected = appPackages.filter((a) => ids.length === 0 || ids.includes(a.id));
     const unknown = ids.filter((id) => !appPackages.some((a) => a.id === id));
     if (unknown.length)
         fail(`unknown app(s): ${unknown.join(", ")}`);
+    const expectedVersions = new Map();
     if (ids.length === 0) {
         // no args: upgrade everything that is installed and outdated
         process.stderr.write(pc.dim("checking versions ...\n"));
         const rows = await collectAppRows();
-        const upgradable = rows.filter((r) => r.upgradable).map((r) => r.id);
+        const managed = rows.filter((row) => !!appCommand(appPackages.find((app) => app.id === row.id), "upgrade"));
+        const failed = managed.filter((row) => row.checkFailed);
+        for (const row of failed)
+            console.log(pc.yellow(`${row.id}: ${row.checkFailed}; update status unknown`));
+        if (failed.length)
+            process.exitCode = 1;
+        const upgradable = managed.filter((row) => row.upgradable);
         if (upgradable.length === 0) {
-            console.log("everything is up to date");
+            if (failed.length)
+                console.log("could not determine update status for every installed app");
+            else if (managed.some((row) => row.installed))
+                console.log("all checked apps are up to date");
+            else
+                console.log("no installed CLI-managed apps to upgrade");
             return;
         }
-        selected = appPackages.filter((a) => upgradable.includes(a.id));
+        for (const row of upgradable)
+            expectedVersions.set(row.id, row.latest);
+        selected = appPackages.filter((app) => expectedVersions.has(app.id));
     }
     for (const app of selected) {
         const cmd = appCommand(app, "upgrade");
         if (!cmd) {
             console.log(`${pc.yellow("skip")} ${app.id}: not CLI-upgradable`);
+            process.exitCode = 1;
             continue;
         }
-        if (!installedVersion(app)) {
-            console.log(`${pc.yellow("skip")} ${app.id}: not installed (use \`agentsw install ${app.id}\`)`);
-            continue;
-        }
-        console.log(`upgrading ${app.name}: ${pc.dim(cmd)}`);
         try {
+            if (!installedVersion(app)) {
+                console.log(`${pc.yellow("skip")} ${app.id}: not installed (use \`agentsw install ${app.id}\`)`);
+                process.exitCode = 1;
+                continue;
+            }
+            console.log(`upgrading ${app.name}: ${pc.dim(cmd)}`);
             runShell(cmd);
-            console.log(pc.green(`${app.id} -> ${installedVersion(app) ?? "?"}`));
+            const version = normalizeAppVersion(installedVersion(app));
+            if (!version)
+                throw new Error("upgrade command completed but installed version is unknown or app is not detected");
+            const expected = expectedVersions.get(app.id);
+            if (expected && isNewer(version, expected))
+                throw new Error(`upgrade command completed but ${version} is older than available ${expected}`);
+            console.log(pc.green(`${app.id} -> ${version}`));
         }
         catch (err) {
             console.log(pc.red(`${app.id} upgrade failed: ${err.message}`));
@@ -673,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) {
@@ -717,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;
@@ -754,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] = {
@@ -767,6 +954,7 @@ export async function cmdImport(opts) {
             models,
             defaultModel,
             modelsDevId: hint,
+            ...metadataOptions,
         };
         if (!store.active)
             store.active = id;