howtofixcli 0.7.24 → 0.7.26

package/dist/howtofix-account.js

@@ -0,0 +1,834 @@
+/**
+ * Connecting a howtofix.id account to the CLI.
+ *
+ * `howtofix.id` is the product's own gateway: one token, one base URL
+ * (`https://api.howtofix.id/v1`), OpenAI-compatible, and 50-odd models behind it
+ * (Claude, GPT, Gemini, Qwen, DeepSeek, ...). Two facts drive this module, both
+ * verified against the live service rather than assumed:
+ *
+ * 1. **There is no OAuth.** `/.well-known/openid-configuration` returns the SPA's
+ *    HTML, `/api/device/code` and `/v1/oauth/device` are 404, and the SDK's only
+ *    provider-level OAuth is `oauth: "radius"`. The documented flow is: sign up
+ *    on howtofix.id, create a token in the Console, paste it. So "connect your
+ *    account" means *token*, and this module makes that flow verify the token
+ *    instead of storing it blind.
+ * 2. **`models.json` is a static file.** A provider entry lists the models the
+ *    CLI may use, and the gateway exposes `GET /v1/models` (50 ids). Without a
+ *    sync the user pays for one model and can reach one model, which is the whole
+ *    point of the product wasted.
+ *
+ * The policy is pure and the network call is injected, so both the merge rules
+ * and the failure messages are testable without a network or a session.
+ */
+/** The gateway the product is built on. */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomicSync } from "./fs-atomic.js";
+import { CLI_CLIENT_HEADER, cliClientHeader } from "./cli-auth.js";
+import { catalogCachePath, deserializeCatalog, fetchCatalog, lookupModel, normalizeModelId, serializeCatalog } from "./model-catalog.js";
+export const HOWTOFIX_BASE_URL = "https://api.howtofix.id/v1";
+/**
+ * Where a user creates a token.
+ *
+ * This is the dashboard's API-keys page. It used to point at
+ * `https://howtofix.id/console/token`, which is **not a route in the panel**:
+ * the dashboard is new-api's, its file-based route tree contains no `/console`
+ * entry at all, and the keys page is `/keys`. Signed out, the router's auth
+ * guard answers with the sign-in page for any unknown path, so the dead link
+ * looked fine from the outside — a user only found out after signing in.
+ *
+ * There is still no OAuth callback a local client can receive: the panel's
+ * callback completes into a *browser session*, and its redirect sanitizer
+ * refuses anything that is not the panel's own origin, so a loopback callback
+ * would need a change on the panel, not in this CLI. The token is the supported
+ * sign-in.
+ */
+export const HOWTOFIX_CONSOLE_URL = "https://howtofix.id/keys";
+/** The provider ids in `models.json` that point at that gateway. */
+export const HOWTOFIX_PROVIDERS = ["howtofix", "howtofix-free"];
+/**
+ * The provider ids the user actually configured in `models.json`.
+ *
+ * The runtime also offers catalogue entries for providers this account has no key
+ * for (opencode, opencode-go). Listing them in `/model` invites a choice that
+ * cannot work, so the picker shows only what the file defines. An empty or
+ * unreadable file returns an empty set, and callers read that as "show all".
+ */
+export function configuredProviderIds(agentDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(agentDir, "models.json"), "utf8"));
+        const providers = parsed.providers;
+        if (!providers || typeof providers !== "object")
+            return new Set();
+        return new Set(Object.keys(providers));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * The provider entry for a gateway account, created when the file has none.
+ *
+ * A fresh install has no `models.json` at all, so `/connect` used to verify the
+ * token, report "connected", and then store nothing — the first thing a new user
+ * does left them with zero models.
+ *
+ * There is deliberately **no `apiKey` field**. An empty-string `apiKey` makes the
+ * SDK drop the whole provider: measured against the SDK, `apiKey: ""` yields zero
+ * models while omitting the field, `"$SOME_VAR"`, or a literal key all yield the
+ * full list. The credential is supplied at runtime by `setRuntimeApiKey`, which is
+ * what `/connect` calls, so the entry must leave the field out rather than blank.
+ */
+export function newProviderEntry() {
+    return {
+        baseUrl: HOWTOFIX_BASE_URL,
+        api: "openai-completions",
+        // Names the CLI on every model call, so the gateway's usage log records the
+        // run as "CLI (0.4.92)" instead of the token's generic name.
+        headers: { [CLI_CLIENT_HEADER]: cliClientHeader() },
+    };
+}
+/**
+ * Repair the gateway's models in `models.json` in place, and say whether the file
+ * changed.
+ *
+ * The gateway refuses the `developer` role (`code 11128`, "Illegal API invocation
+ * from an unapproved channel") for every model that declares `reasoning: true`,
+ * and the SDK picks `developer` over `system` exactly for those models — so an
+ * entry without `compat.supportsDeveloperRole: false` fails every prompt. The
+ * symptom is the worst kind: the spinner turns, the context meter barely moves,
+ * and nothing is ever reported, because the failure happens before a response.
+ *
+ * `/connect` writes the flag for models it adds, but that only helps an account
+ * connected *after* the flag existed. Anyone who connected earlier keeps a
+ * `models.json` that is entirely broken, and no command they run repairs it. So
+ * the check runs at every start, over the howtofix entries only — another
+ * provider's compat is its own business.
+ *
+ * Returns the number of models repaired. Never throws: an unreadable or
+ * unwritable file must not stop the session, and the caller reports the count
+ * rather than failing.
+ */
+export function repairGatewayModels(agentDir) {
+    const path = join(agentDir, "models.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return 0;
+    }
+    const providers = parsed.providers;
+    if (!providers || typeof providers !== "object")
+        return 0;
+    let changed = 0;
+    for (const id of HOWTOFIX_PROVIDERS) {
+        const entry = providers[id];
+        if (!entry || !Array.isArray(entry.models))
+            continue;
+        const repaired = applyCompat(entry.models);
+        // A machine that connected before the client header existed still names
+        // itself on the next call: the entry is written here rather than only at
+        // /connect, so an update is enough and nobody has to reconnect.
+        const wanted = { ...(entry.headers ?? {}), [CLI_CLIENT_HEADER]: cliClientHeader() };
+        const headerMissing = entry.headers?.[CLI_CLIENT_HEADER] !== wanted[CLI_CLIENT_HEADER];
+        if (repaired.changed === 0 && !headerMissing)
+            continue;
+        entry.models = repaired.models;
+        entry.headers = wanted;
+        changed += repaired.changed === 0 ? 1 : repaired.changed;
+    }
+    if (changed === 0)
+        return 0;
+    try {
+        writeFileAtomicSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
+    }
+    catch {
+        return 0;
+    }
+    return changed;
+}
+/** How long a cached catalogue is trusted before it is refreshed. */
+export const CATALOG_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Load the model catalogue, from the cache when it is fresh and from the network
+ * otherwise, and write the cache back.
+ *
+ * The cache is what makes this affordable on every start: the catalogue is ~5 MB
+ * and eight thousand models, and a start that waited for it would be a start the
+ * user notices. A stale or missing cache fetches; a fetch that fails falls back
+ * to whatever the cache holds, so a machine that is offline keeps the numbers it
+ * already learned rather than losing them.
+ */
+export async function loadCatalog(agentDir, options) {
+    const path = catalogCachePath(agentDir);
+    const now = options?.now ?? Date.now();
+    let cached;
+    let cachedAt = 0;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof raw?.entries === "string") {
+            cached = deserializeCatalog(raw.entries);
+            cachedAt = Number(raw.at) || 0;
+        }
+    }
+    catch {
+        cached = undefined;
+    }
+    const fresh = cached && cached.size > 0 && now - cachedAt < CATALOG_CACHE_TTL_MS;
+    if (fresh && !options?.force)
+        return { index: cached };
+    const fetched = await fetchCatalog({ fetchImpl: options?.fetchImpl });
+    if (!fetched.ok) {
+        if (cached && cached.size > 0)
+            return { index: cached, message: fetched.message };
+        return { index: new Map(), message: fetched.message };
+    }
+    try {
+        mkdirSync(agentDir, { recursive: true });
+        writeFileAtomicSync(path, `${JSON.stringify({ at: now, entries: serializeCatalog(fetched.index) })}\n`);
+    }
+    catch {
+        // A cache that cannot be written is not a reason to lose the answer.
+    }
+    return { index: fetched.index };
+}
+/**
+ * Give the gateway's models their real context window and reasoning flag.
+ *
+ * Runs on every start, over the howtofix providers only. It is the repair half of
+ * the same problem {@link repairGatewayModels} handles: an account connected
+ * before the catalogue existed has 128k stamped on every model and no `reasoning`
+ * field anywhere, and no command they can run fixes it. Existing entries are
+ * corrected only where this module's own default was left in place, so a value
+ * the user chose survives.
+ *
+ * Never throws: an unreachable catalogue leaves the file as it is and reports why.
+ */
+export async function repairModelFacts(agentDir, options) {
+    const path = join(agentDir, "models.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return { changed: 0 };
+    }
+    const providers = parsed.providers;
+    if (!providers || typeof providers !== "object")
+        return { changed: 0 };
+    const { index, message } = await loadCatalog(agentDir, options);
+    // A missing catalogue used to abort the whole repair. The gateway price is a
+    // separate answer that often exists where the catalogue does not, so the loop
+    // still runs and only the fields it has are written.
+    if (index.size === 0 && !options?.prices)
+        return { changed: 0, message };
+    let changed = 0;
+    for (const id of HOWTOFIX_PROVIDERS) {
+        const entry = providers[id];
+        if (!entry || !Array.isArray(entry.models))
+            continue;
+        const repaired = applyCatalog(entry.models, index, options?.prices);
+        if (repaired.changed === 0)
+            continue;
+        entry.models = repaired.models;
+        changed += repaired.changed;
+    }
+    if (changed > 0) {
+        try {
+            writeFileAtomicSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
+        }
+        catch {
+            return { changed: 0, message: "the models file could not be written" };
+        }
+    }
+    return { changed, message };
+}
+/**
+ * A stalled provider must not look like a hang.
+ *
+ * The SDK's HTTP idle timeout defaults to 300000 ms (5 minutes) and it is the
+ * per-provider request timeout, so a gateway that accepts the connection and then
+ * goes quiet leaves the user staring at a spinner for that long with no answer
+ * and no error.
+ *
+ * This was 90s, chosen to keep that wait short. It is wrong for the case the
+ * gateway is built to serve: a reasoning model on a long calculation can think
+ * for minutes, and the gateway now emits an SSE keepalive comment every 15s
+ * (`PingData` in the relay, `general_setting.ping_interval_enabled`) precisely so
+ * that a thinking model does not look stalled. Measured with a stub upstream that
+ * sent only keepalive comments for 75s and then a real chunk, a client with a raw
+ * 20s socket timeout received every ping and finished normally — so a ping resets
+ * this clock. 90s therefore cut real work at exactly 90s while the model was
+ * still drawing its first token, which is what users reported as "thinking is cut
+ * mid stream".
+ *
+ * Matching the SDK's own 5 minutes keeps the stalled-provider protection (the
+ * reason the key is written at all) while leaving room for a think the keepalive
+ * is already covering.
+ */
+export const HTTP_IDLE_TIMEOUT_MS = 300_000;
+/**
+ * Write the network settings the gateway needs, if they are not already there.
+ *
+ * Only `httpIdleTimeoutMs` is set, and only when the key is absent: a value the
+ * user chose is theirs to keep. The rest of `settings.json` is left exactly as it
+ * was, and a file that cannot be parsed is never overwritten.
+ *
+ * Returns true when the file changed.
+ */
+export function ensureGatewaySettings(agentDir) {
+    const path = join(agentDir, "settings.json");
+    let parsed = {};
+    try {
+        const raw = readFileSync(path, "utf8");
+        const candidate = JSON.parse(raw);
+        if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
+            parsed = candidate;
+        }
+    }
+    catch {
+        // Missing file (the normal first run) or unreadable JSON: start from an empty
+        // object. An existing but invalid file is left alone below, not clobbered.
+        if (existsSync(path))
+            return false;
+    }
+    if ("httpIdleTimeoutMs" in parsed)
+        return false;
+    parsed.httpIdleTimeoutMs = HTTP_IDLE_TIMEOUT_MS;
+    try {
+        mkdirSync(agentDir, { recursive: true });
+        writeFileAtomicSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/**
+ * What every model behind the howtofix.id gateway needs.
+ *
+ * The gateway accepts `system` and `user` instructions and refuses `developer`,
+ * so the adapter must never choose the `developer` role for a reasoning model.
+ */
+export const HOWTOFIX_MODEL_COMPAT = { supportsDeveloperRole: false };
+/**
+ * A conservative default context window for a model the gateway does not
+ * describe.
+ *
+ * `GET /v1/models` returns only ids, so a synced model has no declared window.
+ * Guessing high would let the CLI overflow a model's real limit; 128k is the
+ * common floor for the families on offer and the user can edit the entry.
+ */
+export const DEFAULT_CONTEXT_WINDOW = 128_000;
+/** A short, non-reversible hint for a token, safe to show in the feed. */
+export function maskToken(token) {
+    const trimmed = token.trim();
+    if (trimmed.length <= 10)
+        return "***";
+    return `${trimmed.slice(0, 6)}…${trimmed.slice(-4)}`;
+}
+/** Whether a token looks like the ones the Console issues. */
+export function looksLikeToken(token) {
+    return /^sk-[A-Za-z0-9_-]{8,}$/.test(token.trim());
+}
+/**
+ * Read the model ids out of a `GET /v1/models` payload.
+ *
+ * Tolerant on purpose: gateways wrap the list differently (`data`, `models`,
+ * or a bare array), and a strict reader would turn a working token into
+ * "connection failed".
+ */
+export function parseModelIds(payload) {
+    const list = (() => {
+        if (Array.isArray(payload))
+            return payload;
+        if (payload && typeof payload === "object") {
+            const record = payload;
+            if (Array.isArray(record.data))
+                return record.data;
+            if (Array.isArray(record.models))
+                return record.models;
+        }
+        return [];
+    })();
+    const ids = [];
+    for (const entry of list) {
+        const id = typeof entry === "string" ? entry : entry && typeof entry === "object" && typeof entry.id === "string" ? entry.id : undefined;
+        if (id && !ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+/** Whether a provider id points at the howtofix.id gateway. */
+export function isHowtofixProvider(providerId) {
+    return HOWTOFIX_PROVIDERS.includes(providerId);
+}
+/**
+ * The value the gateway returns for an unlimited token.
+ *
+ * `GetSubscription` computes `(remainQuota + usedQuota) / QuotaPerUnit`, and
+ * then overwrites it with this literal when the token has `UnlimitedQuota` — so
+ * a huge round number is not a balance, it is the absence of one. Presenting it
+ * as money would tell an unlimited account it has 100,000,000 of something.
+ */
+export const UNLIMITED_SENTINEL = 100_000_000;
+/**
+ * Read the unit the gateway displays balances in.
+ *
+ * `GET /api/status` carries `quota_display_type` ("USD", "CNY" or "TOKENS"),
+ * and it is public, so this needs no credential. A failure is not an error: the
+ * caller falls back to USD rather than refusing to show a balance.
+ */
+async function readDisplayUnit(doFetch, statusUrl) {
+    const response = await doFetch(statusUrl, { headers: { Accept: "application/json" } });
+    if (!response.ok)
+        return "USD";
+    const payload = (await response.json());
+    const raw = payload?.data?.quota_display_type;
+    return typeof raw === "string" && raw.trim() ? raw.trim().toUpperCase() : "USD";
+}
+/**
+ * Ask the gateway what an account has left.
+ *
+ * The balance is real and reachable with the API key alone — measured on the
+ * live gateway, `GET /v1/dashboard/billing/subscription` and
+ * `GET /v1/dashboard/billing/usage` both answer 200 to a plain `sk-` token,
+ * while `/v1/me` and `/api/user/self` are 404/401. So no dashboard session and
+ * no OAuth are needed to sync it.
+ *
+ * Two conventions have to be undone to read it:
+ *
+ *  - `soft_limit_usd` is *total granted* (remaining + used), not remaining, so
+ *    what is left is `limit - used`;
+ *  - `GetUsage` multiplies by 100, so its `total_usage` is in hundredths.
+ *
+ * Never throws: any failure is a sentence, because this runs from a command.
+ */
+export async function checkUsage(token, options) {
+    const baseUrl = (options?.baseUrl ?? HOWTOFIX_BASE_URL).replace(/\/+$/, "");
+    const doFetch = options?.fetchImpl ?? fetch;
+    const timeoutMs = options?.timeoutMs ?? 15_000;
+    const trimmed = token.trim();
+    if (!trimmed)
+        return { ok: false, unlimited: false, unit: "USD", message: "no token given" };
+    // The gateway reports which unit it displays balances in. Reading it beats
+    // assuming USD: a CNY instance would otherwise print a dollar sign on yuan.
+    const statusUrl = `${baseUrl.replace(/\/v1$/, "")}/api/status`;
+    const unit = await readDisplayUnit(doFetch, statusUrl).catch(() => "USD");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const headers = { Authorization: `Bearer ${trimmed}` };
+    try {
+        const [subscriptionResponse, usageResponse] = await Promise.all([doFetch(`${baseUrl}/dashboard/billing/subscription`, { headers, signal: controller.signal }), doFetch(`${baseUrl}/dashboard/billing/usage`, { headers, signal: controller.signal })]);
+        if (subscriptionResponse.status === 401 || subscriptionResponse.status === 403) {
+            return { ok: false, unlimited: false, unit, message: "the gateway rejected that token when asking for the balance" };
+        }
+        if (!subscriptionResponse.ok) {
+            return { ok: false, unlimited: false, unit, message: `the balance endpoint answered ${subscriptionResponse.status}` };
+        }
+        const subscription = (await subscriptionResponse.json());
+        if (subscription.error?.message) {
+            return { ok: false, unlimited: false, unit, message: subscription.error.message };
+        }
+        const limit = Number(subscription.hard_limit_usd ?? subscription.soft_limit_usd ?? 0);
+        if (limit >= UNLIMITED_SENTINEL) {
+            return { ok: true, unlimited: true, unit, message: "this token has no quota limit" };
+        }
+        let used = 0;
+        if (usageResponse.ok) {
+            const usage = (await usageResponse.json());
+            // The gateway multiplies by 100 on the way out; undo it.
+            used = Number(usage.total_usage ?? 0) / 100;
+        }
+        const remaining = Math.max(0, limit - used);
+        return {
+            ok: true,
+            unlimited: false,
+            limit,
+            used,
+            remaining,
+            unit,
+            message: `${remaining.toFixed(2)} ${unit} left of ${limit.toFixed(2)} (${used.toFixed(2)} used)`,
+        };
+    }
+    catch (cause) {
+        const aborted = cause instanceof Error && cause.name === "AbortError";
+        return {
+            ok: false,
+            unlimited: false,
+            unit,
+            message: aborted ? `the gateway did not answer within ${Math.round(timeoutMs / 1000)}s` : "could not reach the gateway",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Add the account's current model ids to every howtofix entry in `models.json`,
+ * silently and without touching the runtime.
+ *
+ * This is the start-time half of `/sync`: the gateway list follows the
+ * account's tier, and a snapshot taken weeks ago keeps showing what the
+ * account could reach then. Running this on every start means a downgrade
+ * cannot leave a VIP model offered to a free account on the next launch, and
+ * an upgrade puts the new models in reach without anyone re-pasting a
+ * credential. Only ids missing from the file are added; entries the user
+ * wrote by hand are kept, because this function cannot tell a hand-written
+ * model from a synced one and deleting a model the user chose is worse than
+ * leaving a stale one for `/sync` to refresh.
+ *
+ * Never throws: a start must not die over a catalogue it could not read.
+ */
+export async function syncGatewayModelsOnStart(agentDir, ids, prices) {
+    const path = join(agentDir, "models.json");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return { added: 0, touched: 0 };
+    }
+    const providers = parsed.providers;
+    if (!providers || typeof providers !== "object")
+        return { added: 0, touched: 0 };
+    const { index } = await loadCatalog(agentDir).catch(() => ({ index: new Map() }));
+    let added = 0;
+    let touched = 0;
+    for (const id of HOWTOFIX_PROVIDERS) {
+        const entry = providers[id];
+        if (!entry || !Array.isArray(entry.models))
+            continue;
+        const before = entry.models.length;
+        entry.models = mergeModels(entry.models, ids, index, prices);
+        added += entry.models.length - before;
+        touched++;
+    }
+    if (added === 0)
+        return { added: 0, touched };
+    try {
+        writeFileAtomicSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
+    }
+    catch {
+        return { added: 0, touched };
+    }
+    return { added, touched };
+}
+/**
+ * Merge gateway model ids into a provider's existing model list.
+ *
+ * Existing entries are kept **as they are** — a user who set `contextWindow` or
+ * `maxTokens` for a model must not have it overwritten by a sync — and only ids
+ * that are missing are appended. The order is preserved: hand-written models
+ * first, then whatever the gateway added, so the list stays readable.
+ *
+ * New entries take their numbers from the model catalogue when it knows the
+ * model, and only fall back to {@link DEFAULT_CONTEXT_WINDOW} when it does not.
+ * The default is a floor for an unknown model, not a description of every model:
+ * the gateway serves 1,000,000-token windows, and stamping 128k on one of those
+ * made the context meter read many times too full and compact a conversation
+ * that had barely started.
+ */
+export function mergeModels(existing, ids, catalog, costs) {
+    const known = new Set(existing.map((model) => model.id));
+    const merged = [...existing];
+    for (const id of ids) {
+        if (known.has(id))
+            continue;
+        known.add(id);
+        const entry = catalog?.get(normalizeModelId(id)) ?? (catalog ? lookupModel(catalog, id) : undefined);
+        merged.push({
+            id,
+            contextWindow: entry?.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+            ...(entry?.maxTokens ? { maxTokens: entry.maxTokens } : {}),
+            ...(entry ? { reasoning: entry.reasoning } : {}),
+            // Written only when the model takes an image. The SDK's own default for a
+            // model with no `input` is `["text"]`, so stating it for every text model
+            // would add noise to the file and to the "N models updated" count without
+            // changing behaviour; naming it for a vision model is the part that matters.
+            ...(entry?.vision ? { input: ["text", "image"] } : {}),
+            ...(costs?.get(id) ? { cost: costs.get(id) } : {}),
+            compat: { ...HOWTOFIX_MODEL_COMPAT },
+        });
+    }
+    return merged;
+}
+/**
+ * Fill in the numbers a synced model never got, without touching a user's own.
+ *
+ * The repair runs over every gateway model on each start, for the same reason
+ * {@link applyCompat} does: an account connected before the catalogue existed has
+ * a `models.json` full of 128k entries and no `reasoning` flag, and no command
+ * they can run fixes it. Only the fields this module owns are written — a
+ * `contextWindow` the user edited by hand is left alone, which is why the check
+ * is "is it exactly the old default" rather than "is it present".
+ *
+ * Returns how many entries were changed. Never throws.
+ */
+export function applyCatalog(models, catalog, costs) {
+    let changed = 0;
+    const repaired = models.map((model) => {
+        const entry = lookupModel(catalog, model.id);
+        // The gateway price and the model catalogue answer different questions, so
+        // one can exist without the other: `nemotron-ultra` and `mimo-v2.6` are
+        // priced by the gateway but absent from models.dev, and a model the gateway
+        // has never priced must not be called free. So a missing catalogue entry
+        // skips the window/reasoning repair below but not the price.
+        if (!entry) {
+            const onlyCost = costs?.get(model.id);
+            if (!onlyCost || model.cost)
+                return model;
+            changed++;
+            return { ...model, cost: onlyCost };
+        }
+        const next = { ...model };
+        let touched = false;
+        // The old default is the marker of "never given a real number". A user's own
+        // value is anything else, and is kept.
+        if (entry.contextWindow && model.contextWindow === DEFAULT_CONTEXT_WINDOW) {
+            next.contextWindow = entry.contextWindow;
+            touched = true;
+        }
+        if (entry.maxTokens && !model.maxTokens) {
+            next.maxTokens = entry.maxTokens;
+            touched = true;
+        }
+        if (model.reasoning === undefined) {
+            next.reasoning = entry.reasoning;
+            touched = true;
+        }
+        // A synced model never got an `input`, so a vision model stayed blind. Add
+        // the image capability where the catalogue states it. Only ever *adds*: a
+        // model the user marked as image-capable keeps that, and one the catalogue
+        // knows to be text-only is not downgraded — an unlisted model is the
+        // conservative default, and silently removing a capability a user set is
+        // worse than leaving one the catalogue disagrees with.
+        if (entry.vision && !(model.input ?? []).includes("image")) {
+            next.input = [...(model.input ?? ["text"]).filter((v) => v !== "image"), "image"];
+            touched = true;
+        }
+        // A model synced before the gateway's price was read carries no `cost`, and
+        // the SDK reads that as zero — so the picker called a $2/M model free. Only
+        // written when absent: a `cost` already in the file may be the user's own
+        // override, and overwriting a number they chose is worse than a stale one.
+        const cost = costs?.get(model.id);
+        if (cost && !model.cost) {
+            next.cost = cost;
+            touched = true;
+        }
+        if (!touched)
+            return model;
+        changed++;
+        return next;
+    });
+    return { models: repaired, changed };
+}
+/**
+ * Give every model the gateway's compatibility flags, and say how many changed.
+ *
+ * A sync that only stamped new entries would leave every model already in the
+ * file broken: a user who connected before this flag existed has 50 models that
+ * all send the `developer` role and all fail. So the whole list is repaired, not
+ * just the new part. Entries that already carry the flag are left untouched.
+ */
+export function applyCompat(models) {
+    let changed = 0;
+    const repaired = models.map((model) => {
+        if (model.compat?.supportsDeveloperRole === false)
+            return model;
+        changed++;
+        return { ...model, compat: { ...model.compat, ...HOWTOFIX_MODEL_COMPAT } };
+    });
+    return { models: repaired, changed };
+}
+/** How many models a merge would add, for a message that says what happened. */
+export function countNewModels(existing, ids) {
+    const known = new Set(existing.map((model) => model.id));
+    return ids.filter((id) => !known.has(id)).length;
+}
+/**
+ * Ask the gateway whether a model actually answers.
+ *
+ * `/v1/models` lists what an account *may* call, which is not the same as what
+ * works right now: measured on the live gateway, one listed model returned 500
+ * (its channel is down) and another returned 401 (the token is not allowed to
+ * call it). Selecting the first listed model therefore hands a new user a model
+ * that fails on their first prompt, which reads as a broken install.
+ *
+ * A one-token request is enough to tell the difference. Never throws: any failure
+ * is reported as not-ok with the reason.
+ */
+export async function probeModel(model, token, options) {
+    const baseUrl = (options?.baseUrl ?? HOWTOFIX_BASE_URL).replace(/\/+$/, "");
+    const doFetch = options?.fetchImpl ?? fetch;
+    const timeoutMs = options?.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await doFetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ model, messages: [{ role: "user", content: "hi" }], max_tokens: 1 }),
+            signal: controller.signal,
+        });
+        if (response.ok)
+            return { ok: true, detail: "ok" };
+        // The gateway reports the real reason in the body even when the status is 200.
+        const text = await response.text().catch(() => "");
+        const message = /"message"\s*:\s*"([^"]{0,80})/.exec(text)?.[1] ?? `HTTP ${response.status}`;
+        return { ok: false, detail: message };
+    }
+    catch (cause) {
+        const aborted = cause instanceof Error && cause.name === "AbortError";
+        return { ok: false, detail: aborted ? "timed out" : "unreachable" };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Which of these candidates answer right now, probed at most `limit` at a time.
+ *
+ * The channel behind one id being down says nothing about its neighbours —
+ * measured on the live gateway, one listed model answered 500 while another
+ * answered 401 and a third was fine. So when a run dies with "no available
+ * channel", the useful next step is a handful of one-token probes against the
+ * *other* candidates: cheap enough to run inline, and the answer is what
+ * decides whether opening the model picker is worth the user's attention.
+ *
+ * `exclude` drops the id that just failed: probing it again spends one of the
+ * `limit` probes on an answer we already have. Probes run in parallel (each
+ * carries its own timeout), so the whole batch costs one probe's latency, not
+ * `limit` of them. Never throws: `probeModel` reports every failure as not-ok.
+ */
+export async function findLiveModels(candidates, token, options) {
+    const limit = Math.max(0, options?.limit ?? 4);
+    const probed = [...new Set(candidates)].filter((id) => id !== options?.exclude).slice(0, limit);
+    const results = await Promise.all(probed.map((id) => probeModel(id, token, options)));
+    return { live: probed.filter((_, index) => results[index]?.ok), probed };
+}
+/**
+ * Ask the gateway which models a token may call.
+ *
+ * One request, a bounded timeout, and every failure turned into a sentence —
+ * a 401 is "the token was rejected", not an exception the TUI has to catch.
+ * The token is only ever placed in the `Authorization` header.
+ */
+export async function checkAccount(token, options) {
+    const baseUrl = (options?.baseUrl ?? HOWTOFIX_BASE_URL).replace(/\/+$/, "");
+    const doFetch = options?.fetchImpl ?? fetch;
+    const timeoutMs = options?.timeoutMs ?? 15_000;
+    const trimmed = token.trim();
+    if (!trimmed)
+        return { ok: false, models: [], message: "no token given" };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await doFetch(`${baseUrl}/models`, {
+            headers: { Authorization: `Bearer ${trimmed}` },
+            signal: controller.signal,
+        });
+        if (response.status === 401) {
+            return { ok: false, models: [], message: "the gateway rejected that token (401). Check it in the Console, or make a new one." };
+        }
+        if (response.status === 403) {
+            return { ok: false, models: [], message: "that token is not allowed to list models (403). The Console shows what a token may call." };
+        }
+        if (!response.ok) {
+            return { ok: false, models: [], message: `the gateway answered ${response.status}` };
+        }
+        const ids = parseModelIds(await response.json());
+        if (ids.length === 0) {
+            return { ok: false, models: [], message: "the token works but the gateway listed no models" };
+        }
+        return { ok: true, models: ids, message: `${ids.length} models available to this token` };
+    }
+    catch (cause) {
+        const aborted = cause instanceof Error && cause.name === "AbortError";
+        return {
+            ok: false,
+            models: [],
+            message: aborted ? `the gateway did not answer within ${Math.round(timeoutMs / 1000)}s` : "could not reach the gateway",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The gateway's own per-token rates, in USD per million tokens.
+ *
+ * `/api/pricing` publishes the operator's listed rate — the same numbers the
+ * usage log bills at — as ratios rather than dollars:
+ *
+ *   model_ratio      = input USD per 1M / 2
+ *   completion_ratio = output / input
+ *   cache_ratio      = cache_read / input
+ *   create_cache_ratio = cache_write / input
+ *
+ * The divisor is 2 because a ratio of 1 charges 500 quota per 1M tokens and the
+ * gateway defines 500,000 quota as one dollar (`QuotaPerUnit`). Verified against
+ * a live row: `grok-4.6` at ratio 1 / completion 3 / cache 0.25 is $2 in, $6 out,
+ * $0.50 cached — the published xAI price.
+ *
+ * Read from the gateway rather than from models.dev on purpose. The catalogue
+ * lists every reseller's price for an id; the gateway charges the operator's
+ * listed rate. Using the catalogue made the picker disagree with the invoice.
+ *
+ * `quota_type !== 0` marks a per-request price with no per-token rate, which
+ * `models.json` cannot express; those rows are skipped rather than reported as
+ * free. Never throws: a start must not die over a price list.
+ */
+export async function fetchGatewayPrices(token, options) {
+    const baseUrl = (options?.baseUrl ?? HOWTOFIX_BASE_URL).replace(/\/+$/, "");
+    // `/api/pricing` sits beside `/v1`, not under it.
+    const url = `${baseUrl.replace(/\/v1$/, "")}/api/pricing`;
+    const doFetch = options?.fetchImpl ?? fetch;
+    const timeoutMs = options?.timeoutMs ?? 15_000;
+    const prices = new Map();
+    const trimmed = token.trim();
+    if (!trimmed)
+        return prices;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await doFetch(url, {
+            headers: { Authorization: `Bearer ${trimmed}` },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return prices;
+        const body = (await response.json());
+        if (!Array.isArray(body?.data))
+            return prices;
+        for (const raw of body.data) {
+            const id = typeof raw?.model_name === "string" ? raw.model_name : "";
+            if (!id)
+                continue;
+            // Per-request pricing has no per-token rate to write down.
+            if (Number(raw.quota_type ?? 0) !== 0)
+                continue;
+            const ratio = Number(raw.model_ratio);
+            if (!Number.isFinite(ratio) || ratio < 0)
+                continue;
+            const input = ratio * 2;
+            const completion = Number(raw.completion_ratio);
+            const cache = Number(raw.cache_ratio);
+            const createCache = Number(raw.create_cache_ratio);
+            prices.set(id, {
+                input,
+                output: Number.isFinite(completion) && completion >= 0 ? input * completion : 0,
+                cacheRead: Number.isFinite(cache) && cache >= 0 ? input * cache : 0,
+                cacheWrite: Number.isFinite(createCache) && createCache >= 0 ? input * createCache : 0,
+            });
+        }
+    }
+    catch {
+        // An unreachable price list leaves the existing numbers alone.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return prices;
+}