@tiens.nguyen/gu-cli 1.0.686

package/coding-provider-setup.mjs

@@ -0,0 +1,808 @@
+/**
+ * Adding an OpenAI-compatible coding provider from the terminal (task #223).
+ *
+ *     node --test tests/coding-provider-setup.test.mjs
+ *
+ * The DECISIONS live here and the presentation lives in gu-repl.mjs, the same split
+ * ollama-setup.mjs / reconfigureOllamaServer uses — so what a URL means and what a model list is
+ * worth can be tested without a terminal, and first-run setup and /model cannot disagree.
+ *
+ * WHY THE URL RULES ARE NOT ollama-setup's. normalizeOllamaUrl DISCARDS the path, and it is right
+ * to: Ollama serves /v1 and /api at the root of the box, so ".../v1/chat/completions" pasted from
+ * a log means the box. An OpenAI-compatible provider is the opposite — the path is part of the
+ * address. https://openrouter.ai/api/v1 is OpenRouter's documented base, and dropping the /api
+ * from it 404s every call. So this keeps the path and mirrors the API's normalizeOpenAiV1Root
+ * instead, including that function's one hard-won exception.
+ */
+
+/** Cloud instance-metadata addresses. Never a model server, always the first thing an SSRF
+ *  probe reaches for, and the one block worth having in a product whose normal target is a
+ *  machine on your own LAN. */
+const METADATA_HOSTS = new Set([
+  "metadata.google.internal",
+  "metadata",
+  "100.100.100.200", // Alibaba Cloud
+  "fd00:ec2::254", // AWS IMDS over IPv6
+]);
+
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+
+/** Loopback, LAN, or a name that can only resolve inside a network. */
+export function hostLocality(hostname) {
+  let host = String(hostname ?? "").toLowerCase().replace(/\.$/, "");
+  // A PORT MAY COME ALONG. Callers hand this both a bare hostname (from URL.hostname) and a
+  // provider LABEL, which carries the port precisely so two local servers can be told apart —
+  // and "192.168.1.45:11434" read as a hostname has a dot and no IPv4 match, so it came out
+  // PUBLIC. That inverted every locality decision for exactly the machines this product is
+  // built around. Bracketed IPv6 keeps its colons; only a trailing :port is stripped.
+  if (host.startsWith("[")) host = host.replace(/](:\d+)$/, "]");
+  else host = host.replace(/:\d+$/, "");
+  if (!host) return "invalid";
+  if (host === "localhost" || host === "::1" || host === "[::1]") return "loopback";
+  const v4 = host.match(IPV4);
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    if ([a, b, Number(v4[3]), Number(v4[4])].some((n) => n > 255)) return "invalid";
+    if (a === 127) return "loopback";
+    if (a === 169 && b === 254) return "link-local"; // includes 169.254.169.254 (IMDS)
+    if (a === 10) return "private";
+    if (a === 172 && b >= 16 && b <= 31) return "private";
+    if (a === 192 && b === 168) return "private";
+    return "public";
+  }
+  // IPv6 in brackets: fc00::/7 is the unique-local range.
+  if (host.startsWith("[")) {
+    const inner = host.slice(1, -1);
+    if (/^f[cd]/.test(inner)) return "private";
+    if (/^fe80:/.test(inner)) return "link-local";
+    return "public";
+  }
+  // A single-label name, or one of the names that exist only inside a network.
+  if (!host.includes(".")) return "private";
+  if (/\.(local|lan|internal|home|intranet|localdomain)$/.test(host)) return "private";
+  return "public";
+}
+
+/**
+ * Normalize and VET a provider base URL.
+ *
+ * Returns { ok: true, url, host, locality, schemeAssumed } or { ok: false, why }.
+ *
+ * WHERE THIS DEPARTS FROM THE TASK'S LETTER, deliberately. Requirement 6 says "require https for
+ * a non-loopback host". Taken literally that refuses http://192.168.1.45:11434 — which is not an
+ * edge case here, it is the product's normal configuration, already stored in thousands of
+ * existing coding-backend rows, and the whole point of a local-first agent. A rule that refuses
+ * the main use case would not be obeyed; it would be worked around.
+ *
+ * So the line is drawn where the risk actually is: a PUBLIC host over http means the API key is
+ * posted across the internet in clear text, and that is refused. A loopback or LAN host over
+ * http is allowed without comment, because the traffic never leaves a network the user controls
+ * and because refusing it would break local vLLM, LM Studio and Ollama.
+ *
+ * The SSRF half of that requirement gets the block that is worth having: instance metadata. In a
+ * product whose legitimate targets include 10.0.0.0/8 and localhost, refusing "internal
+ * addresses" wholesale is meaningless — but 169.254.169.254 and metadata.google.internal are
+ * never a model server, and they are what an SSRF probe asks for first.
+ */
+export function normalizeProviderUrl(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return { ok: false, why: "empty" };
+  if (/\s/.test(text)) return { ok: false, why: "spaces" };
+
+  const hadScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text);
+  // Reject a scheme we cannot speak BEFORE prefixing, or "ftp://box" becomes
+  // "https://ftp://box" and fails with a baffling message.
+  if (hadScheme && !/^https?:\/\//i.test(text)) return { ok: false, why: "scheme" };
+  // No scheme: guess from what the host looks like, and SAY that we guessed. https for something
+  // that looks like a hosted provider, http for a LAN box — the same split ollama-setup makes,
+  // for the same reason (one guess is right for one shape of address and wrong for the other).
+  const guessed = hostLocality(text.split("/")[0].split(":")[0]) === "public" ? "https" : "http";
+  const withScheme = hadScheme ? text : `${guessed}://${text}`;
+
+  let u;
+  try {
+    u = new URL(withScheme);
+  } catch {
+    return { ok: false, why: "unparseable" };
+  }
+  if (!u.hostname) return { ok: false, why: "unparseable" };
+  // A key or password in the URL would be STORED in settings and DISPLAYED back — a secret must
+  // only ever arrive through the key field, which is write-only and masked.
+  if (u.username || u.password) return { ok: false, why: "credentials" };
+
+  const host = u.hostname.replace(/\.$/, "").toLowerCase();
+  const locality = hostLocality(host);
+  if (locality === "invalid") return { ok: false, why: "unparseable" };
+  if (METADATA_HOSTS.has(host) || locality === "link-local") {
+    return { ok: false, why: "metadata" };
+  }
+  if (locality === "public" && u.protocol === "http:") {
+    return { ok: false, why: "insecure" };
+  }
+
+  const port = u.port ? `:${u.port}` : "";
+  // The PATH IS KEPT — see the file header. Trailing slashes go, then /v1 is ensured with the
+  // API's own rule, including the "/api/v1 is not an Ollama path" exception.
+  const path = u.pathname.replace(/\/+$/, "");
+  const base = `${u.protocol}//${host}${port}${path}`;
+  return {
+    ok: true,
+    url: ensureV1Root(base),
+    host,
+    locality,
+    schemeAssumed: !hadScheme,
+  };
+}
+
+/**
+ * Ensure a base URL ends at its OpenAI-compatible /v1 root.
+ *
+ * MIRRORS normalizeOpenAiV1Root (api/src/app.ts) and _normalize_openai_base
+ * (gonext_agent_chat.py). All three run over the same stored URL — this one when it is typed,
+ * the API when it is saved, python at turn time — so a difference between them means a URL that
+ * is accepted here and silently rewritten later.
+ *
+ * A bare "/api/v1" SURVIVES: the Ollama strip takes a native verb ("/api/generate"), and making
+ * that verb optional is what used to eat OpenRouter's "/api/v1" and 404 every call.
+ */
+export function ensureV1Root(base) {
+  const stripped = String(base ?? "")
+    .replace(/\/+$/, "")
+    .replace(/\/api(?:\/(?:generate|chat|tags|embeddings|embed)(?:\/v1)?)?$/i, "");
+  return /\/v1$/i.test(stripped) ? stripped : `${stripped}/v1`;
+}
+
+/** What to say about a URL we refused. One line; the caller adds the gutter. */
+export function describeUrlProblem(why, typed = "") {
+  switch (why) {
+    case "empty":
+      return ["type the provider's base URL, e.g. https://api.openai.com/v1"];
+    case "spaces":
+      return ["that has a space in it — a URL cannot"];
+    case "scheme":
+      return ["only http:// and https:// addresses work here"];
+    case "credentials":
+      return [
+        "take the key out of the URL — it would be stored and shown back",
+        "paste the address only; the key is asked for next and kept hidden",
+      ];
+    case "metadata":
+      return [
+        "that is a cloud metadata address, not a model server",
+        "if you meant a machine on your network, use its own IP or name",
+      ];
+    case "insecure":
+      return [
+        `http:// to a public host would send your API key across the internet in clear text`,
+        `use https://${typed.replace(/^https?:\/\//i, "")} — or a LAN address, where http is fine`,
+      ];
+    default:
+      return ["that is not an address I can use — try https://api.openai.com/v1"];
+  }
+}
+
+/** Where the model list lives for a normalized /v1 root. */
+export function modelsUrlFor(url) {
+  return `${String(url ?? "").replace(/\/+$/, "")}/models`;
+}
+
+/** mlx_lm's placeholder, which is a mapping and not a model anyone can pick. */
+export const PLACEHOLDER_MODEL = "default_model";
+
+/** The sanitizer stores at most this many models per backend, so offering more would quietly
+ *  drop the tail — better to say the list was long than to lose part of it invisibly. */
+export const MODEL_CAP = 100;
+
+/**
+ * What a GET {url}/v1/models body is actually worth.
+ *
+ * Returns { models, why, total } — `why` names the case so the caller can SAY it:
+ *   ""            a usable list
+ *   "empty"       parsed fine, nothing in it
+ *   "unreadable"  not the shape an OpenAI-compatible /v1/models returns
+ *   "placeholder" the single "default_model" mapping mlx_lm advertises
+ *   "capped"      more than MODEL_CAP; `models` is the first MODEL_CAP and `total` the real count
+ *
+ * TRUSTED ONLY AS A SUGGESTION, and this is the reason the caller must never block on it. Known
+ * liars, all from this repo's own history: mlx_lm advertises its whole HF cache plus a
+ * "default_model" placeholder; aggregators return hundreds; some endpoints refuse to list at all
+ * without a key — and a LISTED model is still not a usable CODER, since the agent's protocol is a
+ * literal <code> block and a model that spells it differently loses its reasoning silently.
+ */
+/**
+ * Has the provider itself said this model is finished? (task #223 follow-up.)
+ *
+ * ASKED FOR after a RETIRED model was picked from a list that still advertised it, and the turn
+ * died on `model_not_found`. When an endpoint publishes lifecycle metadata, believing it is
+ * strictly better than finding out mid-task.
+ *
+ * ABSENCE MEANS ACTIVE — the rule the request came with, and the only safe default. Most
+ * endpoints publish nothing (OpenAI's public /v1/models returns id/object/created/owned_by and
+ * no lifecycle at all), so treating a missing field as "retired" would empty the picker for
+ * almost everyone. Anything unparseable is treated the same way: keep it, and let the real
+ * request be the judge.
+ *
+ * A DATE IN THE FUTURE IS NOT A RETIREMENT. A model announced for shutdown next year is usable
+ * today, and hiding it would be this filter overruling the provider's own schedule.
+ *
+ * `created` is deliberately NOT consulted: it is when the model appeared, and old is not dead.
+ */
+export function modelRetired(row, now = Date.now()) {
+  if (!row || typeof row !== "object") return false;
+  // A flag, where one is given. Several gateways use one of these instead of a date.
+  const status = String(row.status ?? row.lifecycle_status ?? row.lifecycle ?? "").toLowerCase();
+  if (/^(deprecated|retired|disabled|sunset|removed|inactive)$/.test(status)) return true;
+  if (row.deprecated === true || row.retired === true) return true;
+  for (const field of [row.shutdown_date, row.shutdownDate, row.deprecation, row.sunset_date]) {
+    if (field === undefined || field === null || field === "") continue;
+    // Epoch seconds, epoch millis, or an ISO string — providers use all three.
+    const raw = typeof field === "object" ? (field.date ?? field.at ?? "") : field;
+    if (raw === undefined || raw === null || raw === "") continue;
+    let ms = NaN;
+    if (typeof raw === "number") ms = raw > 1e12 ? raw : raw * 1000;
+    else if (/^\d+$/.test(String(raw))) {
+      const n = Number(raw);
+      ms = n > 1e12 ? n : n * 1000;
+    } else ms = new Date(String(raw)).getTime();
+    if (!Number.isFinite(ms)) continue; // unparseable → not a claim we can act on
+    if (ms <= now) return true;
+  }
+  return false;
+}
+
+export function parseProviderModels(body, now = Date.now()) {
+  const rows = Array.isArray(body?.data) ? body.data : Array.isArray(body) ? body : null;
+  if (!rows) return { models: [], why: "unreadable", total: 0, retired: 0 };
+  const ids = [];
+  const seen = new Set();
+  let retired = 0;
+  for (const r of rows) {
+    const id = typeof r === "string" ? r.trim() : typeof r?.id === "string" ? r.id.trim() : "";
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    // BELIEVE THE PROVIDER when it says a model is done. Offering one that is already retired is
+    // offering a choice whose only outcome is a 404 several steps into a task.
+    if (modelRetired(r, now)) {
+      retired++;
+      continue;
+    }
+    ids.push(id);
+  }
+  if (ids.length === 0) return { models: [], why: "empty", total: 0, retired };
+  // ONLY when it is the whole list: an MLX host that lists its cache AND the placeholder is
+  // perfectly usable — you just must not pick the placeholder. One entry and nothing else means
+  // the server told us nothing about what it has loaded.
+  if (ids.length === 1 && ids[0] === PLACEHOLDER_MODEL) {
+    return { models: [], why: "placeholder", total: 1, retired };
+  }
+  const usable = ids.filter((id) => id !== PLACEHOLDER_MODEL);
+  if (usable.length > MODEL_CAP) {
+    return { models: usable.slice(0, MODEL_CAP), why: "capped", total: usable.length, retired };
+  }
+  return { models: usable, why: "", total: usable.length, retired };
+}
+
+/** What to say about a list we could not use. The flow continues in every case — a failed probe
+ *  must never be the end of the road, only the end of the convenience. */
+export function describeModelProblem(why, { host = "", total = 0 } = {}) {
+  switch (why) {
+    case "empty":
+      return [`${host} answered but listed no models — type the model id yourself`];
+    // `retired` is reported ALONGSIDE any of these, by retiredNote below.
+    case "unreadable":
+      return [`${host} did not answer with a model list — type the model id yourself`];
+    case "placeholder":
+      return [
+        `${host} only reports "${PLACEHOLDER_MODEL}", which is a placeholder, not a model`,
+        "type the model id the server expects",
+      ];
+    case "capped":
+      return [`${host} listed ${total} models — showing the first ${MODEL_CAP}`];
+    case "all-retired":
+      return [
+        `${host} lists models, but every one of them is marked retired`,
+        "type the model id you want — the list is not offering a usable one",
+      ];
+    default:
+      return [];
+  }
+}
+
+/**
+ * Why a probe failed, in words that point at the cause.
+ *
+ * A 401 HERE IS THE MOST USEFUL ANSWER THIS FLOW CAN GIVE: it means the address is right and the
+ * key is wrong, found at setup instead of several steps into a turn where it surfaces as a coder
+ * that silently dropped to the chat model.
+ */
+export function describeProbeFailure({ status = 0, err = null } = {}) {
+  if (status === 401 || status === 403) {
+    return { fatal: true, lines: ["the server rejected that key (HTTP " + status + ")"] };
+  }
+  if (status === 404) {
+    return {
+      fatal: false,
+      lines: ["no /v1/models on that address — it may still work; check the URL's path"],
+    };
+  }
+  if (status >= 500) {
+    return { fatal: false, lines: [`the server answered HTTP ${status}`] };
+  }
+  if (status) return { fatal: false, lines: [`HTTP ${status} from that address`] };
+  const msg = String(err?.message ?? err ?? "").toLowerCase();
+  if (msg.includes("abort") || msg.includes("timeout")) {
+    return { fatal: false, lines: ["no answer in time — the address may be wrong, or /proxy"] };
+  }
+  if (msg.includes("certificate") || msg.includes("self-signed")) {
+    return { fatal: false, lines: ["its TLS certificate could not be verified"] };
+  }
+  return { fatal: false, lines: ["could not reach it — check the address and /proxy"] };
+}
+
+/**
+ * A hosted provider needs a CONTEXT WINDOW set (requirement 11).
+ *
+ * A hosted /v1/models returns id/object/created/owned_by and no size, so gu falls back to
+ * assuming 24,000 prompt tokens and compacts there. On a large hosted model that throws history
+ * away every single turn for no reason, and produces a bill with no explanation. Worth one line
+ * after the provider is saved — and only for a hosted one, since a local server is usually
+ * small-windowed anyway and the advice would be noise.
+ */
+export function shouldMentionContextWindow(locality) {
+  return locality === "public";
+}
+
+/**
+ * The API stores at most this many backend rows (sanitizeCodingBackends caps at 8).
+ *
+ * MIRRORED ON PURPOSE, because exceeding it is SILENT: the save returns 200 and the row beyond
+ * the cap is simply not there — the exact failure shape this whole task was filed around. Better
+ * to refuse with a reason than to appear to succeed.
+ */
+export const MAX_BACKENDS = 8;
+
+/**
+ * The backend rows an account ALREADY has, in the shape a save must preserve.
+ *
+ * WHY THIS IS NOT JUST `settings.agentCodingBackends`. A pre-#123 account has no array at all —
+ * its single coding backend lives in the legacy agentCodingModel* fields, and the API synthesizes
+ * it on read. Writing `[newRow]` for such an account would mean the array now exists and holds
+ * only the new provider, so the backend the user has been coding with all along VANISHES from
+ * /model while its legacy fields sit there unread. Synthesizing it here, exactly as
+ * codingBackends() does, makes "add" additive for every account rather than only for recent ones.
+ */
+export function existingBackendRows(settings) {
+  const rows = Array.isArray(settings?.agentCodingBackends) ? settings.agentCodingBackends : [];
+  const clean = rows.filter((b) => b && typeof b === "object" && String(b.url ?? "").trim());
+  if (clean.length > 0) return clean;
+  const url = String(settings?.agentCodingModelUrl ?? "").trim();
+  if (!url) return [];
+  const kind = String(settings?.agentCodingModelKind ?? "").trim();
+  return [
+    {
+      // No id: the API identifies a pre-#223 row by its KIND, which keeps every stored pick of
+      // `openai::kimi-k3` resolving. Inventing one here would change that id for no reason.
+      kind,
+      enabled: true,
+      url,
+      defaultModel: String(settings?.agentCodingModelName ?? "").trim(),
+      models: Array.isArray(settings?.agentCodingModelAllowed)
+        ? settings.agentCodingModelAllowed.filter((m) => typeof m === "string")
+        : [],
+    },
+  ];
+}
+
+/**
+ * An id for a NEW provider row, minted on this side.
+ *
+ * MINTED HERE RATHER THAN READ BACK, because the flow needs it twice in a row: the backend is
+ * saved first, then the key is attached to it by id — and POST /coding-keys refuses a backendId
+ * naming a row that does not exist. Sending an explicit id (which the API preserves) makes that
+ * one round trip instead of save-then-fetch-and-guess-which-row-is-mine.
+ *
+ * AVOIDS THE KIND NAMES TOO: "openai", "ollama", "local" and "auto" are what the API synthesizes
+ * for a row that carries no id, so taking one of them could collide with a pre-#223 row that is
+ * not in the list yet.
+ */
+export function mintProviderId(existingIds = []) {
+  const taken = new Set([...existingIds, "openai", "ollama", "local", "auto", ""]);
+  for (let i = 0; i < 50; i++) {
+    const id = `prov_${Math.random().toString(36).slice(2, 10)}`;
+    if (!taken.has(id)) return id;
+  }
+  return `prov_${Date.now().toString(36)}`;
+}
+
+/** The row to append for a new OpenAI-compatible provider. */
+export function newProviderRow({ id, url, model }) {
+  return {
+    id,
+    kind: "openai",
+    enabled: true,
+    url: String(url ?? ""),
+    defaultModel: String(model ?? "").trim(),
+    // Empty, not "everything the probe listed": a listed model is not a usable coder, and an
+    // allow-list full of untested names makes /model long and no more useful. More can be added
+    // by running this again or from the web.
+    models: [],
+  };
+}
+
+/**
+ * The WIRE ID for a freshly added provider's model — what the folder stores and sends.
+ *
+ * THE QUALIFICATION RULE IS THE API'S, AND GETTING IT WRONG HERE BREAKS THE NEXT TURN.
+ * codingModelChoiceList qualifies ids as `${rowId}::${model}` only when there is more than one
+ * backend to disambiguate; with exactly one it keeps the BARE model name, so that existing REPLs
+ * and stored picks keep resolving. So on an account that had NO backends, the provider just added
+ * is the only one, and storing "prov_x::gpt-4o" would be a pick resolveCodingModelOverride has
+ * never heard of — it is not an exact id, it is not a bare model name, and the turn fails with
+ * "not in your allowed coding models" on a provider that was configured seconds earlier.
+ *
+ * `backendCount` is the number of backends the account will have AFTER the save — enabled, with a
+ * URL, the same rows codingBackends() would return.
+ */
+export function wireIdFor({ backendId, model, backendCount }) {
+  const m = String(model ?? "").trim();
+  if (!m) return "";
+  return Number(backendCount) > 1 ? `${backendId}::${m}` : m;
+}
+
+/** How many of these rows the API will actually offer models from. */
+export function usableRowCount(rows) {
+  return (Array.isArray(rows) ? rows : []).filter(
+    (b) => b && b.enabled !== false && String(b.url ?? "").trim()
+  ).length;
+}
+
+/**
+ * The keys that may actually be used with a given provider (task #223).
+ *
+ * MIRRORS THE API'S ELIGIBILITY RULE (resolveCodingApiKey): keys bound to this backend, then
+ * UNBOUND ones — every key stored before providers could be told apart, and the derived legacy
+ * one, which remain usable anywhere. Bound first, so the row the picker highlights first is the
+ * one the API would actually resolve to.
+ *
+ * WHY THE PICKER MUST FILTER AT ALL. The API refuses to send a key belonging to another provider,
+ * so offering one here would be offering a choice that silently does nothing: the turn would run
+ * with a substituted key, or with none. A list that includes options which cannot be chosen is
+ * worse than a shorter list.
+ *
+ * NO backendId MEANS DO NOT FILTER. That is an API older than the field, and hiding keys on a
+ * guess would be worse than showing all of them, which is exactly what happened before.
+ */
+export function keysForBackend(keys, backendId) {
+  const list = Array.isArray(keys) ? keys : [];
+  const want = String(backendId ?? "").trim();
+  if (!want) return list;
+  return [
+    ...list.filter((k) => k?.backendId === want),
+    ...list.filter((k) => !k?.backendId),
+  ];
+}
+
+/**
+ * The URL to offer when someone opens this flow (task #223 follow-up, reported by the user:
+ * "it says 'provider URL', please give default one, everyone know that right?").
+ *
+ * https://api.openai.com/v1 is the one address in this space that needs no research — it is what
+ * "OpenAI-compatible" is named after, and typing it out is pure ceremony for the commonest case.
+ *
+ * WHY THIS IS NOT THE CURATED TABLE I ARGUED AGAINST. A hardcoded MODEL list would be a whitelist
+ * that goes stale and rejects what the user actually has; this is one overtypeable default for a
+ * single field, offered before anything is known, and wrong at worst by one keystroke.
+ *
+ * RETURNS "" WHEN IT IS ALREADY CONFIGURED. Offering a default that will immediately be refused
+ * as a duplicate is worse than offering none — it invites an Enter press whose only outcome is an
+ * error message.
+ */
+export const DEFAULT_PROVIDER_URL = "https://api.openai.com/v1";
+
+export function defaultProviderUrl(existingRows = []) {
+  const taken = (Array.isArray(existingRows) ? existingRows : []).some(
+    (b) => ensureV1Root(String(b?.url ?? "")) === DEFAULT_PROVIDER_URL
+  );
+  return taken ? "" : DEFAULT_PROVIDER_URL;
+}
+
+/** The host of a stored URL, for display in a list of providers. Not the tag rule — just enough
+ *  to tell two rows apart on screen when their models are both unhelpful. */
+export function providerHost(url) {
+  try {
+    const u = new URL(String(url ?? ""));
+    return u.port ? `${u.hostname}:${u.port}` : u.hostname;
+  } catch {
+    return String(url ?? "");
+  }
+}
+
+/**
+ * The provider rows this flow may EDIT (task #223 follow-up).
+ *
+ * WHY THIS EXISTS AT ALL: the flow could add a provider and nothing could change one afterwards.
+ * A typo in the model id — reported, as "dfdf" — was permanent: /model offers the row but cannot
+ * edit it, re-adding the same URL is refused as a duplicate, and web Settings draws ONE CARD PER
+ * KIND, so a second openai row is not even visible there. Add-only was a dead end and this is the
+ * exit from it.
+ *
+ * OPENAI ROWS ONLY. An Ollama or MLX row is owned by its own flow ("change the Ollama server this
+ * machine uses…"), which sets URL, models and roles together; editing one field of it from here
+ * would half-configure a thing that has its own notion of complete.
+ */
+export function manageableProviders(rows) {
+  const out = [];
+  const taken = new Set();
+  for (const b of Array.isArray(rows) ? rows : []) {
+    if (!b || typeof b !== "object") continue;
+    if (String(b.kind ?? "") !== "openai") continue;
+    const url = String(b.url ?? "").trim();
+    if (!url) continue;
+    // The same identity rule the API uses, so an id shown here is the id it will patch.
+    const id = String(b.id ?? "").trim() || (taken.has("openai") ? "" : "openai");
+    if (!id || taken.has(id)) continue;
+    taken.add(id);
+    out.push({
+      id,
+      url,
+      model: String(b.defaultModel ?? "").trim(),
+      host: providerHost(url),
+      enabled: b.enabled !== false,
+    });
+  }
+  return out;
+}
+
+/** Replace one row's default model, leaving every other row untouched. */
+export function patchProviderModel(rows, id, model) {
+  const want = String(model ?? "").trim();
+  return (Array.isArray(rows) ? rows : []).map((b) =>
+    rowMatches(b, id) ? { ...b, defaultModel: want } : b
+  );
+}
+
+/** Replace one row's URL. The caller normalizes and clash-checks first. */
+export function patchProviderUrl(rows, id, url) {
+  const want = String(url ?? "").trim();
+  return (Array.isArray(rows) ? rows : []).map((b) =>
+    rowMatches(b, id) ? { ...b, url: want } : b
+  );
+}
+
+/** Drop one row. */
+export function removeProvider(rows, id) {
+  return (Array.isArray(rows) ? rows : []).filter((b) => !rowMatches(b, id));
+}
+
+/** A row is the one named when its id matches — or, for a row that carries none, when the id IS
+ *  its kind, which is exactly how the API identifies a pre-#223 row. */
+function rowMatches(b, id) {
+  if (!b || typeof b !== "object") return false;
+  const own = String(b.id ?? "").trim();
+  return own ? own === id : String(b.kind ?? "") === id;
+}
+
+/**
+ * The keys that would be STRANDED by removing a provider.
+ *
+ * They are not merely unused: a key bound to a row that no longer exists is ineligible for every
+ * provider AND filtered out of every picker, so it can never be selected, never be used, and
+ * never be deleted from the terminal again. Removing a provider therefore has to take its keys
+ * with it — and say so first, because deleting a credential is not undoable.
+ */
+export function keysBoundTo(keys, backendId) {
+  const want = String(backendId ?? "").trim();
+  if (!want) return [];
+  return (Array.isArray(keys) ? keys : []).filter((k) => k?.backendId === want);
+}
+
+/**
+ * Which of a provider's models could plausibly WRITE CODE (task #223 follow-up).
+ *
+ * REPORTED with the list to prove it: api.openai.com reports 129 ids, and the picker offered all
+ * of them — embeddings, moderation, TTS, transcription, image, video, realtime, search. Not one
+ * of those speaks /v1/chat/completions, so picking one produces a coder that fails on its first
+ * turn, and finding the handful that work means reading a hundred rows.
+ *
+ * A HEURISTIC ON NAMES, AND THEREFORE NEVER A GATE. The caller must always offer the full list
+ * behind one more keypress: this cannot know what a private gateway calls its models, and a
+ * filter that hides the only usable model with no way back is worse than no filter. Same rule as
+ * the probe itself — a suggestion, not validation.
+ *
+ * EXCLUSIONS ONLY, NO ALLOW-LIST. "Which ids are coders" goes stale the day a provider ships a
+ * new family; "an id with `embedding` in it is not a chat model" does not.
+ */
+const NOT_A_CHAT_MODEL = [
+  /embed/i,
+  /moderation/i,
+  /\btts\b|-tts|text-to-speech/i,
+  /whisper|transcribe|audio|realtime|voice/i,
+  /image|vision-preview|dall-?e|sora/i,
+  /search(-preview|-api)?$|-search-/i,
+  /rerank|guard|classifier/i,
+  // OpenAI's original completion endpoints — they take a prompt, not messages.
+  /^(davinci|babbage|curie|ada)(-|$)|instruct/i,
+];
+
+export function codingModelCandidates(models) {
+  const all = (Array.isArray(models) ? models : []).filter((m) => typeof m === "string" && m.trim());
+  const kept = all.filter((m) => !NOT_A_CHAT_MODEL.some((re) => re.test(m)));
+  // EVERYTHING FILTERED OUT MEANS THE HEURISTIC IS WRONG FOR THIS SERVER, not that the server has
+  // no coders. Hand back the whole list rather than an empty picker.
+  if (kept.length === 0) return { models: all, filtered: 0 };
+  return { models: kept, filtered: all.length - kept.length };
+}
+
+/** One line when the provider itself said some of its models are finished (task #223 follow-up).
+ *  Said out loud rather than silently shortening the list: a picker that quietly drops entries
+ *  looks like a provider with fewer models, which is a different and wrong story. */
+export function retiredNote(retired, host = "") {
+  const n = Number(retired) || 0;
+  if (n <= 0) return "";
+  return `${n} retired model${n === 1 ? "" : "s"} hidden${host ? ` — ${host} says they are shut down` : ""}`;
+}
+
+/**
+ * Does this look like an API key at all? (task #223 follow-up, asked for directly.)
+ *
+ * Returns { level: "" | "hint" | "warn", note } — a JUDGEMENT ABOUT SHAPE, never a network call
+ * and never a refusal. Only the provider can say whether a key is valid; all this can catch is
+ * the class of mistake that is obvious on sight: an empty box, "abc", "aaa", a placeholder left
+ * in from a README. Catching those at the prompt saves a turn that would otherwise die on a 401
+ * several steps in.
+ *
+ * A LOCAL SERVER IS EXEMPT FROM THE PLACEHOLDER RULES, and that is the important part. llama.cpp,
+ * vLLM, LM Studio and Ollama accept ANY string — "abc" is a perfectly good key there, and warning
+ * about it would be this function telling the user their working setup is wrong. Only the
+ * structural checks (blank, whitespace) apply to a LAN or loopback address.
+ *
+ * The `sk-` hint is deliberately the ONLY host-specific rule: api.openai.com is the default this
+ * flow now offers, so a key that cannot be one of its is worth a word. It is a hint, not a gate —
+ * a gateway proxying OpenAI may well issue its own format.
+ */
+const PLACEHOLDER_KEYS =
+  /^(test|dummy|none|null|nil|abc|xyz|foo|bar|key|apikey|api[-_]?key|secret|password|changeme|placeholder|your[-_]?(api[-_]?)?key(here)?|<[^>]*>|x+|sk-x+|\.+|-+)$/i;
+
+export function describeApiKeyShape(key, { host = "", locality = "" } = {}) {
+  const k = String(key ?? "");
+  const trimmed = k.trim();
+  if (!trimmed) return { level: "warn", note: "no key was entered" };
+  // STRUCTURAL, and true everywhere — a key with a space in it is nearly always a paste that
+  // took the surrounding text with it.
+  if (/\s/.test(k)) {
+    return { level: "warn", note: "that has whitespace in it — a pasted key usually should not" };
+  }
+  const local = locality === "loopback" || locality === "private";
+  if (local) return { level: "", note: "" };
+
+  if (PLACEHOLDER_KEYS.test(trimmed)) {
+    return { level: "warn", note: `"${trimmed}" looks like a placeholder, not a key` };
+  }
+  // One repeated character ("aaaa", "1111"), which no provider issues.
+  if (trimmed.length > 1 && new Set(trimmed).size === 1) {
+    return { level: "warn", note: "that is the same character repeated — not a key" };
+  }
+  if (trimmed.length < 16) {
+    return { level: "warn", note: `that is only ${trimmed.length} characters — keys are longer` };
+  }
+  if (/openai\.com$/i.test(host) && !/^sk-/.test(trimmed)) {
+    return { level: "hint", note: "OpenAI keys start with \"sk-\" — check you pasted the whole one" };
+  }
+  return { level: "", note: "" };
+}
+
+/**
+ * WHICH OF THE PROVIDERS WE JUST SAVED DID THE API NOT GIVE BACK? (reported live)
+ *
+ * "whenever i add or change an openai-compatible provider, it replace the old one in this list
+ * and only keep 1 for ollama default, one for openai-compatible, can we allow multiple ones".
+ *
+ * It was not a limit anyone chose. An API older than row ids identifies a backend by its KIND —
+ * its choice ids read `openai::gpt-5`, not `prov_9ez1q69s::gpt-5` — so a second openai row
+ * collides with the first and evicts it. The save answers 200 either way, and the add flow's
+ * existing check only asks whether the model it JUST added is offered, which it is. Nothing
+ * noticed that a different provider had disappeared, so the loss was silent and looked like a
+ * deliberate one-per-kind rule.
+ *
+ * COMPARED BY URL, not by id, deliberately. The id is exactly what the two API versions disagree
+ * about — ours are minted `prov_…`, an old one answers with the kind — so keying on it would
+ * report every row as lost against an old API and none against a new one. The URL is the one
+ * thing both versions carry and neither rewrites, beyond the /v1 normalising this module already
+ * owns.
+ *
+ * ROWS WITH NO MODEL ARE NOT LOST, they are empty: a backend offers one choice per model, so a
+ * row saved with nothing to pick from correctly produces no choice on ANY version. Counting it
+ * as lost would fire this warning on a perfectly good save.
+ *
+ * @param sentRows  the rows just written (each {url, defaultModel?, models?})
+ * @param choices   codingChoices as the API reports them AFTER the write
+ * @returns the URLs that went in and did not come back, in the order they were sent
+ */
+export function providerUrlsLost(sentRows, choices) {
+  // EMPTY IN, EMPTY OUT. ensureV1Root("") answers "/v1" — a truthy path, not a URL — and feeding
+  // that into the set made one url-less choice look like a real backend, so every row that had
+  // actually been saved was then reported as evicted. Caught by the junk-input test.
+  const norm = (u) => {
+    const t = String(u ?? "").trim();
+    return t ? ensureV1Root(t).toLowerCase() : "";
+  };
+  const offered = new Set();
+  for (const c of Array.isArray(choices) ? choices : []) {
+    const u = norm(c?.url);
+    if (u) offered.add(u);
+  }
+  // Nothing came back at all: the API is unreachable or answered a shape we do not understand.
+  // That is not evidence of eviction, and guessing it is would turn a network blip into a
+  // confident claim about the user's data.
+  if (offered.size === 0) return [];
+  const out = [];
+  for (const r of Array.isArray(sentRows) ? sentRows : []) {
+    const hasModel =
+      String(r?.defaultModel ?? "").trim() !== "" ||
+      (Array.isArray(r?.models) && r.models.some((m) => String(m ?? "").trim()));
+    if (!hasModel) continue;
+    const u = norm(r?.url);
+    if (u && !offered.has(u) && !out.includes(u)) out.push(u);
+  }
+  return out;
+}
+
+/**
+ * Does this API still identify a backend by its KIND rather than by a row id?
+ *
+ * The tell is in the choices it returns: a new API reports `backendId` on every one. Used to
+ * explain WHY a provider was evicted, rather than only that it was — "restart your API" is an
+ * instruction, and an instruction without its reason is the kind of thing that gets ignored
+ * twice before someone acts on it.
+ */
+export function apiKeysBackendsByKind(choices) {
+  const list = Array.isArray(choices) ? choices : [];
+  if (list.length === 0) return false;
+  return list.every((c) => !String(c?.backendId ?? "").trim());
+}
+
+/**
+ * WHICH PROVIDERS STOPPED BEING OFFERED ACROSS A SAVE? (reported live)
+ *
+ * The stronger half of providerUrlsLost, and the one that catches the case that actually bit:
+ * an eviction the client never had a chance to prevent.
+ *
+ * providerUrlsLost compares what we SENT against what came back, so it can only notice a row we
+ * knew about. The real loss was upstream of that — GET /api/worker/settings did not return
+ * agentCodingBackends at all, so existingBackendRows fell back to the single legacy row, the
+ * previously-added provider was never in `existing`, and the save wrote it out of existence. It
+ * was absent from the sent rows too, so nothing downstream could miss it.
+ *
+ * Comparing the API's OWN answer before and against after needs no such knowledge: a provider
+ * that was being offered and now is not has been lost, whoever dropped it and whatever version
+ * of the API is running. That makes this the check that survives an API older OR newer than this
+ * client.
+ *
+ * `expectUrl` is the provider being added — it is expected to appear, never to disappear, and
+ * passing it keeps a re-save of the SAME provider (a model change) from reporting itself.
+ */
+export function providersNoLongerOffered(before, after, expectUrl = "") {
+  const norm = (u) => {
+    const t = String(u ?? "").trim();
+    return t ? ensureV1Root(t).toLowerCase() : "";
+  };
+  const urls = (list) => {
+    const out = new Set();
+    for (const c of Array.isArray(list) ? list : []) {
+      const u = norm(c?.url);
+      if (u) out.add(u);
+    }
+    return out;
+  };
+  const was = urls(before);
+  const now = urls(after);
+  // NOTHING BEFORE, or nothing after: no comparison is possible. A failed probe must not be
+  // reported as the user's providers having been deleted.
+  if (was.size === 0 || now.size === 0) return [];
+  const keep = norm(expectUrl);
+  const gone = [];
+  for (const u of was) {
+    if (u !== keep && !now.has(u)) gone.push(u);
+  }
+  return gone;
+}