@tiens.nguyen/gu-cli 1.0.686

package/ollama-setup.mjs

@@ -0,0 +1,832 @@
+/**
+ * Pointing a Client Expert machine at ITS OWN Ollama box (task #220).
+ *
+ * Setup used to seed https://ollama1.gomarsic.cc and three model names, so anyone whose box is
+ * somewhere else — a company LAN, http://192.168.1.40:11434, their own dnsname — had to know to
+ * override environment variables they had never heard of. This module is the pure half of asking
+ * instead: normalise whatever URL they type, and turn the list that box actually reports into the
+ * three role choices gu needs.
+ *
+ * PURE ON PURPOSE. Every decision below is a function from strings to strings, so the whole
+ * "what does this URL mean / which model should each role default to" table is a test rather
+ * than a thing you find out by re-running setup against a real box.
+ *
+ * THE ONE RULE THIS MODULE EXISTS TO ENFORCE, from client-expert-api.mjs:457 — a setup question
+ * was deliberately REMOVED once, because the alternative was "a URL that answers nothing" and a
+ * machine that reported success and then failed its first question. Re-adding the question is
+ * only safe because the box is PROVEN to answer before setup accepts it. Nothing here invents a
+ * model name, guesses a host, or fills a role from a list that came back empty: every function
+ * returns null rather than a plausible-looking value it cannot stand behind.
+ */
+import { isLikelyEmbedder } from "./agent-model-command.mjs";
+
+/** Ollama's native port, used when someone types a bare host or an IP with no port. */
+export const OLLAMA_DEFAULT_PORT = 11434;
+
+/**
+ * THE TWO MODELS A SERVER MUST ACTUALLY HAVE, and why these two are not a free choice while the
+ * coder is (user, 2026-09-04).
+ *
+ *  · AGENT — gemma4:e4b routes every turn and writes every plain reply. Swapping it does not
+ *    just change the answers, it changes whether the ROUTER works: the agent/chat decision, the
+ *    tool-call shapes and the thought normalising were all tuned against this family, and a
+ *    model that cannot follow them fails as an agent that answers confidently and does nothing.
+ *  · EMBED — nomic-embed-text decides the shape of every vector on disk. A different embedder
+ *    does not error, it returns numbers: cosine over two models still ranks, rag_search still
+ *    prints a top-k, and the model still answers from it. That failure is invisible and
+ *    permanent, which is why /embed-model's list is two known-good options rather than live.
+ *
+ * The CODER is deliberately not on this list. It is the one model that IS interchangeable —
+ * `/model` exists to swap it — so it is chosen from whatever the box has.
+ *
+ * WHAT IS REQUIRED IS THE FAMILY, NOT THE TAG (user, 2026-09-06). The reasoning above is about
+ * gemma4 — the router, the tool-call shapes and the thought normalising were tuned against that
+ * family — and nothing in it singles out `:e4b` over `:12b` or a local `gemma4-quadro` build.
+ * Demanding one exact tag turned a box that had three perfectly good gemma4s into "not ready",
+ * and told the reader to pull a fourth. So the gate is the PREFIX, and which of the matching
+ * models fills the role is the user's choice, the same way the coder already is.
+ */
+export const REQUIRED_AGENT_PREFIX = "gemma4";
+/** The shipped default, and the name `ollama pull` is suggested for when the family is absent. */
+export const REQUIRED_AGENT_MODEL = "gemma4:e4b";
+export const REQUIRED_EMBED_MODEL = "nomic-embed-text:latest";
+
+/** Is this one of the models allowed to fill the AGENT role? */
+const hasAgentPrefix = (name, prefix = REQUIRED_AGENT_PREFIX) =>
+  String(name ?? "").trim().toLowerCase().startsWith(String(prefix).toLowerCase());
+
+/**
+ * The models on this box that may fill the AGENT role — the gemma4 family, minus any embedder.
+ *
+ * Embedders are excluded rather than merely sorted last: one cannot route a turn at all, so
+ * offering it as a choice offers a way to break the machine.
+ */
+export function agentCandidates(models, { prefix = REQUIRED_AGENT_PREFIX } = {}) {
+  return (Array.isArray(models) ? models : []).filter(
+    (m) => !isLikelyEmbedder(m) && hasAgentPrefix(m.model, prefix)
+  );
+}
+
+/**
+ * Which candidate to offer first: what the machine is already set to, else the shipped default,
+ * else the SMALLEST — the agent runs on every step of every turn, so its latency is the one a
+ * person feels (the same reasoning defaultRoles applies to `chat`).
+ */
+export function defaultAgentModel(models, preferred = "") {
+  const cands = agentCandidates(models);
+  if (!cands.length) return "";
+  const has = (name) => cands.some((m) => m.model === name);
+  if (preferred && has(preferred)) return preferred;
+  if (has(REQUIRED_AGENT_MODEL)) return REQUIRED_AGENT_MODEL;
+  return [...cands].sort(
+    (a, b) => (a.sizeBytes || 0) - (b.sizeBytes || 0) || a.model.localeCompare(b.model)
+  )[0].model;
+}
+
+/** "nomic-embed-text" and "nomic-embed-text:latest" are the same model to a person. */
+const sameModel = (a, b) => {
+  const bare = (s) => String(s ?? "").trim().toLowerCase().replace(/:latest$/, "");
+  return bare(a) === bare(b);
+};
+
+/**
+ * Does this server have what the agent and RAG actually need?
+ *
+ * Returns the MISSING names, so the caller can print the exact `ollama pull` lines rather than
+ * "some models are missing" — the difference between a message someone can act on and one they
+ * have to decode.
+ */
+export function checkRequired(
+  models,
+  { agentPrefix = REQUIRED_AGENT_PREFIX, agentExample = REQUIRED_AGENT_MODEL, embed = REQUIRED_EMBED_MODEL } = {},
+) {
+  const list = Array.isArray(models) ? models : [];
+  const missing = [];
+  // The AGENT is satisfied by any model in the family (see REQUIRED_AGENT_PREFIX). What goes in
+  // `missing` is still a concrete, pullable name — `ollama pull gemma4` is not a command, so
+  // reporting the prefix would produce a line that cannot be run.
+  if (!agentCandidates(list, { prefix: agentPrefix }).length) missing.push(agentExample);
+  // The EMBEDDER is still exact, and deliberately: a different one does not error, it returns
+  // numbers, which corrupts every vector on disk invisibly and permanently.
+  if (!list.some((m) => sameModel(m.model, embed))) missing.push(embed);
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * "This server is not ready", said as the two commands that make it ready.
+ *
+ * NOT a refusal to continue — the caller decides that. A box missing these can still be used as
+ * a CODER host, which is exactly the split this flow supports.
+ */
+export function describeNotReady(host, missing) {
+  const lines = [`${host || "That server"} is not ready for the agent — it is missing:`];
+  for (const m of missing ?? []) lines.push(`  ${m}`);
+  lines.push("Pull them there, then load again:");
+  for (const m of missing ?? []) lines.push(`  ollama pull ${String(m).replace(/:latest$/, "")}`);
+  return lines;
+}
+
+/**
+ * What people actually type, turned into one canonical URL.
+ *
+ * The field accepts every shape someone reasonably offers for "my Ollama box":
+ *
+ *   192.168.1.40                 → http://192.168.1.40:11434/v1
+ *   192.168.1.40:11434           → http://192.168.1.40:11434/v1
+ *   ollama.local                 → http://ollama.local:11434/v1
+ *   http://box:11434/v1          → http://box:11434/v1
+ *   https://ollama1.gomarsic.cc  → https://ollama1.gomarsic.cc/v1
+ *   https://ollama1.gomarsic.cc/v1/ → https://ollama1.gomarsic.cc/v1
+ *
+ * TWO DEFAULTS, AND THEY ARE NOT SYMMETRICAL:
+ *
+ *  · SCHEME — http, not https, when none is given. A bare host or an IP is a LAN box, and LAN
+ *    boxes overwhelmingly do not have a certificate. Defaulting to https would fail TLS on the
+ *    common case and report it as "unreachable", sending the reader to debug their network
+ *    instead of typing four more characters. An explicit https:// is of course kept.
+ *  · PORT — added only when the host has none AND no scheme was given. `https://host` means a
+ *    reverse proxy on 443 (that is what ollama1 is); pinning :11434 onto it would break the
+ *    exact deployment we ship against.
+ *
+ * Returns null for anything that is not a host at all, so the caller can say "that is not a URL"
+ * rather than proceeding with a mangled one.
+ */
+export function normalizeOllamaUrl(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return null;
+  // A path, a query, or whitespace inside means this is not a host we can reason about.
+  if (/\s/.test(text)) return null;
+
+  const hadScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text);
+  // Reject a scheme we cannot speak BEFORE prefixing, or "ftp://box" silently becomes
+  // "http://ftp://box" and fails with a baffling message.
+  if (hadScheme && !/^https?:\/\//i.test(text)) return null;
+  const withScheme = hadScheme ? text : `http://${text}`;
+
+  let u;
+  try {
+    u = new URL(withScheme);
+  } catch {
+    return null;
+  }
+  if (!u.hostname) return null;
+  // A trailing-dot FQDN ("box.local.") is legal DNS but breaks string comparison against the
+  // same host written without it, and every later locality/proxy check compares hostnames.
+  const host = u.hostname.replace(/\.$/, "");
+  if (!host) return null;
+
+  const port = u.port || (hadScheme ? "" : String(OLLAMA_DEFAULT_PORT));
+  const origin = `${u.protocol}//${host}${port ? `:${port}` : ""}`;
+
+  // The path is discarded rather than preserved. Ollama serves /v1 and /api at the ROOT of the
+  // box; a user who pastes ".../v1/chat/completions" (copied from a log or a curl) means the
+  // box, not that endpoint, and keeping the path would build /v1/chat/completions/api/tags.
+  return {
+    /** The OpenAI-compatible base, which is what every settings field in gu stores. */
+    url: `${origin}/v1`,
+    /** Ollama's NATIVE face, where /api/tags and /api/ps live. */
+    root: origin,
+    host,
+    /** True when we supplied the scheme — worth saying, since we guessed http for them. */
+    schemeAssumed: !hadScheme,
+  };
+}
+
+/**
+ * Every address a bare hostname could reasonably mean, in the order worth trying.
+ *
+ * ONE GUESS IS NOT ENOUGH, and this was found by typing a real hostname at a real prompt:
+ * `ollama2.gomarsic.cc` became `http://ollama2.gomarsic.cc:11434` and timed out, because that
+ * box is behind a reverse proxy on HTTPS:443 — exactly like ollama1. The single default is
+ * right for a LAN box and wrong for a public name, and the reader has no way to know which
+ * assumption we made beyond a timeout that looks like their server is down.
+ *
+ * So when the user gave NEITHER a scheme NOR a port, we produce both readings and let the LOAD
+ * decide — which costs one extra request, and only when the first guess was wrong. The order is
+ * a heuristic and nothing rests on it:
+ *   · an IP, a single-label host, or a .local/.lan/.internal name is a LAN box → http:11434 first
+ *   · anything else looks like a public FQDN behind a proxy → https:443 first
+ *
+ * Anything explicit — a scheme, a port, or both — is taken at its word and produces exactly one
+ * candidate. Guessing past what someone typed is how you end up connecting somewhere they did
+ * not ask for.
+ */
+export function urlCandidates(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return [];
+  const explicit = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) || /:\d+(\/|$)/.test(text);
+  const first = normalizeOllamaUrl(text);
+  if (!first) return [];
+  if (explicit) return [first];
+
+  const host = first.host;
+  const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+  const lanish = isIp || !host.includes(".") || /\.(local|lan|internal|home|localdomain)$/i.test(host);
+  const lan = normalizeOllamaUrl(`http://${host}:${OLLAMA_DEFAULT_PORT}`);
+  const proxied = normalizeOllamaUrl(`https://${host}`);
+  return lanish ? [lan, proxied] : [proxied, lan];
+}
+
+/**
+ * WHEN THE ADDRESS IS NOT AN OLLAMA AT ALL, BUT A HOSTED PROVIDER.
+ *
+ * Reported while setting up Client Expert: `https://api.moonshot.ai` typed at the coding-model
+ * question, answered with "could not reach api.moonshot.ai: HTTP 404 — check the address, or
+ * that Ollama is running there". The address was perfect. It is simply not an Ollama: Moonshot
+ * speaks the OpenAI dialect, and this prompt only ever asks for /api/tags.
+ *
+ * Telling someone to check a correct address is the worst kind of error message, so the failure
+ * path asks one more question — does /v1/models answer? — and says something true instead.
+ *
+ * 401 AND 403 COUNT AS YES. A hosted provider without a key answers "unauthorised", not "not
+ * found": that response IS the proof the endpoint exists and speaks OpenAI. Measured on
+ * api.moonshot.ai — /api/tags 404, /v1/models 401. Requiring 200 here would recognise only the
+ * providers that need no credential, which is nearly none of them.
+ */
+/** The real probe: the status of GET <root>/v1/models, or 0 if it could not be reached. */
+async function defaultProbeStatus(url) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(4000) });
+    return res.status;
+  } catch {
+    return 0;
+  }
+}
+
+export const OPENAI_PROBE_PATH = "/v1/models";
+
+/** Pure: does this HTTP status mean "an OpenAI-compatible endpoint is here"? */
+export function isOpenAiStatus(status) {
+  const n = Number(status);
+  if (!Number.isFinite(n)) return false;
+  // 2xx = it answered with a list. 401/403 = it is there and wants a key, which is the normal
+  // reply from every hosted provider and the common case for this message.
+  return (n >= 200 && n < 300) || n === 401 || n === 403;
+}
+
+/** The root to probe, from whatever the person typed. `/v1` is added, never doubled. */
+export function openAiProbeUrl(raw) {
+  const base = String(raw ?? "").trim().replace(/\/+$/, "");
+  if (!base) return "";
+  const withScheme = /^https?:\/\//i.test(base) ? base : `https://${base}`;
+  return withScheme.replace(/\/v1$/i, "") + OPENAI_PROBE_PATH;
+}
+
+/**
+ * What to say when the coding-model question was given a hosted provider.
+ *
+ * It names the ONE path that actually works today. Moonshot is already registered as an
+ * openai-kind coding backend by codingBackendsForClientExpert — with the key asked for only if
+ * you switch to it — so the answer is not "you cannot", it is "not here, and here is where".
+ */
+export function describeOpenAiCoder(host) {
+  return [
+    `${host} is an OpenAI-compatible provider, not an Ollama server.`,
+    "This question wants an Ollama address — it asks the box which models it holds, and a",
+    "hosted provider will not answer that without a key.",
+    "Kimi (api.moonshot.ai) is already set up as a coding backend on this machine. Press Enter",
+    "to finish with the local coder, then run `/model` to switch to it and enter your API key.",
+  ];
+}
+
+/** And for the agent question, where a hosted provider genuinely cannot do the job. */
+export function describeOpenAiAgent(host) {
+  return [
+    `${host} is an OpenAI-compatible provider, not an Ollama server.`,
+    "This role needs an Ollama: it runs the embedder for RAG as well as the agent model, and",
+    "an embedding model is not something a chat provider serves.",
+  ];
+}
+
+/**
+ * THIS MACHINE'S OWN OLLAMA.
+ *
+ * http, not https: nothing is listening for TLS on a loopback port, and 127.0.0.1 rather than
+ * "localhost" because that name can resolve to ::1 first on a Mac while Ollama binds IPv4 only —
+ * a connection refused against a server that is plainly running.
+ */
+export const LOCAL_OLLAMA_URL = `http://127.0.0.1:${OLLAMA_DEFAULT_PORT}`;
+
+/**
+ * What the setup question should OFFER as its default: this machine's Ollama if it is actually
+ * there, else whatever was going to be offered anyway.
+ *
+ * WHY IT IS A PROBE AND NOT JUST A NEW CONSTANT. The shared server is the default today for a
+ * documented reason — the code before it "seeded whatever it could infer, a local Ollama URL on
+ * a machine with no Ollama, so setup finished successfully and the first question failed with a
+ * model that was never going to answer". Swapping one guess for another would walk straight back
+ * into that. Asking the port settles it in a few milliseconds, and a machine with nothing
+ * listening is offered exactly what it is offered today.
+ *
+ * IT DOES NOT REQUIRE THE gemma4 FAMILY. A local Ollama that answers but has no models yet is
+ * still the right default for a machine whose whole mode is "nothing it does is shared": the
+ * prompt then names the models that are missing, which is a better thing to learn than that we
+ * quietly pointed a private install at somebody else's server.
+ */
+export async function localOllamaDefault(fallbackUrl, fetchTags, { log } = {}) {
+  const normalized = normalizeOllamaUrl(LOCAL_OLLAMA_URL);
+  if (!normalized || typeof fetchTags !== "function") return fallbackUrl;
+  try {
+    const models = await fetchTags(tagsUrlFor(normalized));
+    if (!usableModelList(models).ok) return fallbackUrl;
+    log?.(`  found Ollama on this machine (${models.length} model${models.length === 1 ? "" : "s"})`);
+    return normalized.url;
+  } catch {
+    // Not running, not installed, a different port — all the same answer, and none worth a line
+    // of output on a machine that was never going to use it.
+    return fallbackUrl;
+  }
+}
+
+/**
+ * The same server, written the way a person should type it — WITHOUT /v1.
+ *
+ * DISPLAY ONLY. Every settings field in gu stores the /v1 base, because that is the
+ * OpenAI-compatible endpoint the API actually calls; nothing about what is SAVED changes here.
+ * What changes is what we show: a default of "https://ollama1.gomarsic.cc/v1" reads as an
+ * instruction, and the reader is left wondering whether their own address needs the suffix too
+ * (reported 2026-09-04: "it makes user confused if he/she should input v1 to the url").
+ *
+ * They do not need it, and never did — normalizeOllamaUrl accepts the address with /v1, without
+ * it, with a trailing slash, or with a whole endpoint pasted on the end. Showing the bare host
+ * is simply the honest version of a field that was always that forgiving.
+ *
+ * SAFE TO FEED BACK IN, which is the property that matters: strip → normalize returns exactly
+ * the URL we started with, so the displayed default can be passed straight back as the default
+ * without drifting. Pinned by a round-trip test.
+ */
+export function displayUrl(url) {
+  return String(url ?? "").trim().replace(/\/+$/, "").replace(/\/v1$/i, "");
+}
+
+/**
+ * GET /api/tags for a normalised URL.
+ *
+ * Deliberately built from `root`, not from the /v1 base: /api/tags is on Ollama's native face
+ * and does not exist under /v1. agentTagsUrl() does the same job starting from a settings
+ * object; this one starts from what the user just typed, before anything has been saved.
+ */
+export function tagsUrlFor(normalized) {
+  return normalized?.root ? `${normalized.root}/api/tags` : "";
+}
+
+/**
+ * Is this list good enough to finish setup with?
+ *
+ * THE GUARD THE WHOLE TASK TURNS ON. Reachable-but-empty is not success: it is a box with no
+ * models pulled, or a proxy politely answering for something that is not Ollama. Accepting it
+ * would produce exactly the machine the removed setup question used to produce — configured,
+ * reported as fine, and unable to answer the first thing asked of it.
+ *
+ * Also rejects a list with NOTHING BUT EMBEDDERS: nomic-embed-text alone cannot chat or write
+ * code, so a box holding only that cannot fill two of the three roles, and finding out at the
+ * first turn is worse than finding out here.
+ */
+export function usableModelList(models) {
+  const list = Array.isArray(models) ? models : [];
+  if (list.length === 0) return { ok: false, why: "empty" };
+  if (list.every((m) => isLikelyEmbedder(m))) return { ok: false, why: "embedders-only" };
+  return { ok: true, why: "" };
+}
+
+/** Say what an unusable list means, in the reader's terms rather than ours. */
+export function describeUnusableList(why, url) {
+  const where = url || "that server";
+  if (why === "embedders-only") {
+    return [
+      `${where} answered, but every model on it is an embedder.`,
+      "An embedder cannot chat or write code — pull a chat model there (e.g. `ollama pull",
+      "gemma4:e4b`) and load again.",
+    ];
+  }
+  return [
+    `${where} answered, but has no models pulled.`,
+    "Pull at least one there (e.g. `ollama pull gemma4:e4b`), then load again.",
+  ];
+}
+
+/**
+ * Which model each role should START on, given what the box actually has.
+ *
+ * A DEFAULT, NOT A DECISION — the user confirms all three, and every one of them is a plain
+ * single-select over the same list. The point of choosing well here is that Enter-Enter-Enter
+ * should be right on a normal box, not that the guess is authoritative.
+ *
+ * The rules, and why:
+ *  · EMBED takes the first embedder. isLikelyEmbedder is the same test /agent-model uses to sink
+ *    them out of the chat list, so the two cannot disagree about what an embedder is.
+ *  · CHAT takes the SMALLEST non-embedder. Chat runs on every step of every turn, so its latency
+ *    is the one a person feels — the reasoning already written down for SHARED_CHAT_MODEL, here
+ *    applied to whatever this box happens to hold rather than to a hardcoded name.
+ *  · CODE takes the LARGEST non-embedder, for the mirror reason: it writes the code and is worth
+ *    waiting for.
+ *  · With exactly one non-embedder, chat and code are the same model. That is correct and not a
+ *    bug — one model is what that box has.
+ *
+ * Sizes can be 0 (a list that reports none), in which case both fall back to list order, which
+ * parseOllamaTags has already made stable and alphabetical.
+ */
+export function defaultRoles(models, { preferred = {} } = {}) {
+  const list = Array.isArray(models) ? models : [];
+  const chatable = list.filter((m) => !isLikelyEmbedder(m));
+  const embedders = list.filter((m) => isLikelyEmbedder(m));
+  if (chatable.length === 0) return null;
+
+  // DETERMINISTIC, which is all a tie-break can honestly buy here. Found live on ollama2:
+  // gemma4-quadro:latest and gemma4-quadro-49k:latest are byte-identical (28052911405), so
+  // "largest wins" is a tie and without a second key the winner depends on the order the server
+  // happened to list them in — the same box could seed two machines differently. It does NOT
+  // pick the right one: only `preferred` can, because "right" here means the shipped default
+  // (the -49k build, with the configured 49152 context), which is knowledge this function does
+  // not have and should not hardcode. Callers pass it; see client-expert-run.mjs.
+  const bySize = [...chatable].sort(
+    (a, b) => (a.sizeBytes || 0) - (b.sizeBytes || 0) || a.model.localeCompare(b.model)
+  );
+  const has = (name) => list.some((m) => m.model === name);
+
+  // A model the machine is ALREADY set to wins its role, when the box still has it. Re-running
+  // this flow to change one thing must not silently re-pick the other two.
+  const keep = (want, fallback) =>
+    want && has(want) ? want : fallback;
+
+  return {
+    chat: keep(preferred.chat, bySize[0].model),
+    code: keep(preferred.code, bySize[bySize.length - 1].model),
+    // null, never a guess: a box with no embedder cannot do RAG, and naming a chat model here
+    // would produce an index of meaningless vectors that fails silently at search time.
+    embed: keep(preferred.embed, embedders[0]?.model ?? null),
+  };
+}
+
+/**
+ * The models object the rest of Client Expert already understands.
+ *
+ * Shaped exactly like CLIENT_EXPERT_MODELS so settingsPatch() can take either — the seeded
+ * defaults when nobody was asked, or this, when they were.
+ *
+ * `extras` are the additional coders `/model` should offer later. Filtered to models the box
+ * actually reported and to things that are not the primary coder, so the list cannot contain a
+ * duplicate or a name that came from a previous, different box.
+ */
+export function modelsFromRoles({ url, roles, extras = [], available = [], codeUrl = "" } = {}) {
+  if (!url || !roles?.chat || !roles?.code) return null;
+  const known = new Set((available ?? []).map((m) => m.model));
+  const seen = new Set([roles.code]);
+  const alt = [];
+  for (const name of extras ?? []) {
+    if (!known.has(name) || seen.has(name)) continue;
+    seen.add(name);
+    alt.push(name);
+  }
+  return {
+    url,
+    chat: roles.chat,
+    code: roles.code,
+    // TWO SERVERS ARE ALLOWED (user, 2026-09-04): the agent + embedder on one box, the coder on
+    // another. `codeUrl` is ABSENT when they are the same, so every existing caller and every
+    // stored settings row that assumes one host keeps working unchanged — a second field that
+    // is only there when it differs cannot break the single-host case.
+    ...(codeUrl && codeUrl !== url ? { codeUrl } : {}),
+    // Absent rather than empty: seedSettings must be able to tell "no embedder on this box, do
+    // not enable RAG" from "an embedder called empty string".
+    ...(roles.embed ? { embed: roles.embed } : {}),
+    altCoders: alt,
+  };
+}
+
+/**
+ * One line per role, for the confirmation the user reads before Save.
+ *
+ * Says the HOST too. A setup that reports three model names without saying which box they are on
+ * is exactly the report someone re-running this flow cannot check.
+ */
+export function summarizeChoice(models, { host = "", codeHost = "" } = {}) {
+  if (!models) return [];
+  const at = host ? `  @ ${host}` : "";
+  // The coder may be on a DIFFERENT box, and if it is, that is the single most important thing
+  // on this screen — a summary that showed one host would be quietly wrong about where half the
+  // work happens.
+  const codeAt = models.codeUrl ? (codeHost ? `  @ ${codeHost}` : "  @ (other server)") : at;
+  const rows = [
+    `chat   ${models.chat}${at}`,
+    `code   ${models.code}${codeAt}`,
+  ];
+  rows.push(models.embed ? `RAG    ${models.embed}${at}` : "RAG    — no embedder on this box");
+  if (models.altCoders?.length) {
+    rows.push(`also   ${models.altCoders.join(", ")}${dimNote(models.altCoders.length)}`);
+  }
+  return rows;
+}
+
+const dimNote = (n) => `  — offered by /model (${n} more)`;
+
+// ---------------------------------------------------------------------------------------
+// THE ASKING. Numbered menus and line input, NOT the REPL's ↑/↓ picker.
+//
+// This runs during first-run setup, where there is no REPL, no raw mode and no frozen zone —
+// `ask` is a plain line reader and every question in client-expert-run.mjs is a numbered list
+// answered by typing a digit (see askMode). Matching that idiom is not a compromise, it is the
+// only thing available here; a picker would need raw stdin that setup does not own. The same
+// choice re-run later from `/model` CAN use the real picker, because by then the REPL exists.
+//
+// Multi-select therefore reads as "1,3" rather than as ticked boxes — the line-input equivalent
+// of a checkbox list, and the only one this context supports.
+//
+// Everything below is pure except askOllamaSetup, whose `ask` and `fetchTags` are injected, so
+// the entire flow — including every failure branch — runs offline in tests.
+// ---------------------------------------------------------------------------------------
+
+/** Menu rows for one role, current/default marked. Pure. */
+export function renderModelMenu(models, { defaultModel = "", formatSize = () => "" } = {}) {
+  return (models ?? []).map((m, i) => {
+    const n = String(i + 1).padStart(2, " ");
+    const size = formatSize(m.sizeBytes);
+    const mark = m.model === defaultModel ? " ←" : "";
+    const kind = isLikelyEmbedder(m) ? "  (embedder)" : "";
+    return `   ${n}  ${m.model}${size ? `  ${size}` : ""}${kind}${mark}`;
+  });
+}
+
+/**
+ * A typed answer → the model it names, or the default on empty.
+ *
+ * Accepts the NUMBER or the NAME. People who can see a list of names type names, and refusing
+ * that in favour of "you must type the digit" is the kind of small rudeness that makes a setup
+ * flow feel hostile. Returns null for anything that matches neither, so the caller re-asks
+ * instead of silently taking the default — which would configure a model nobody chose.
+ */
+export function parseMenuChoice(typed, models, fallback = "") {
+  const text = String(typed ?? "").trim();
+  if (!text) return fallback || null;
+  const list = models ?? [];
+  const n = Number(text);
+  if (Number.isInteger(n) && n >= 1 && n <= list.length) return list[n - 1].model;
+  const hit = list.find((m) => m.model.toLowerCase() === text.toLowerCase());
+  return hit ? hit.model : null;
+}
+
+/**
+ * "1,3" or "1 3" or "big:27b, mid:13b" → the models named. Unknown entries are DROPPED.
+ *
+ * Silent on junk, unlike parseMenuChoice, and deliberately: this list is optional extras. A typo
+ * in an optional field should cost the typo, not the whole flow — whereas a role must never be
+ * filled by accident, which is why the single-choice parser refuses instead.
+ */
+export function parseMultiChoice(typed, models) {
+  const text = String(typed ?? "").trim();
+  if (!text) return [];
+  const list = models ?? [];
+  const out = [];
+  for (const part of text.split(/[,\s]+/).filter(Boolean)) {
+    const name = parseMenuChoice(part, list, "");
+    if (name && !out.includes(name)) out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Ask for the box, prove it answers, and pick the three roles.
+ *
+ * Returns the models object for settingsPatch, or null when the user declines Ollama — which is
+ * a real answer, not a failure: the caller then follows today's Kimi path unchanged.
+ *
+ * THE URL IS PREFILLED with the shared box, so Enter keeps exactly today's behaviour. That is
+ * what makes adding this question safe for existing machines: the default path is one keypress
+ * and cannot be got wrong, and typing over it is the new capability.
+ *
+ * NOTHING IS ACCEPTED UNTIL THE BOX HAS LISTED A USABLE MODEL. See usableModelList — this is the
+ * guard that lets the setup question exist at all (client-expert-api.mjs:457).
+ */
+export async function askOllamaSetup(
+  ask,
+  {
+    defaultUrl,
+    fetchTags,
+    log = console.log,
+    formatSize = () => "",
+    preferred = {},
+    attempts = 3,
+    // Asked ONLY when the Ollama probe has already failed, so the common path costs nothing.
+    // Injected so the tests can drive it; defaults to a real request with a short deadline,
+    // because this runs while someone is waiting at a prompt.
+    probeStatus = defaultProbeStatus,
+  } = {},
+) {
+  // ---- SERVER 1: the agent model and the embedder -------------------------------------
+  // These two are REQUIRED and not a free choice (see REQUIRED_AGENT_MODEL). A box without
+  // them is "not ready" rather than "wrong": it may still be a perfectly good coder host, which
+  // is why this refusal does not end the flow.
+  let agent = null;
+  for (let attempt = 0; attempt < attempts && !agent; attempt++) {
+    const typed = (await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `)).trim();
+    if (isDecline(typed)) break;
+    const tried = await loadFirstThatAnswers(typed || defaultUrl, fetchTags, log);
+    if (!tried || tried.failed) {
+      // One explanation, the best one available: the provider message when we recognise the
+      // address, otherwise the reachability advice we were going to give anyway.
+      const explained = await explainIfOpenAi(typed || defaultUrl, probeStatus, log, describeOpenAiAgent);
+      if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
+      continue;
+    }
+    const { normalized, models } = tried;
+    const usable = usableModelList(models);
+    if (!usable.ok) {
+      for (const l of describeUnusableList(usable.why, normalized.host)) log(`  ${l}`);
+      continue;
+    }
+    const need = checkRequired(models);
+    if (!need.ok) {
+      for (const l of describeNotReady(normalized.host, need.missing)) log(`  ${l}`);
+      log("  (or press Enter with no address to skip — you can set it later with /model)");
+      continue;
+    }
+    log(`  ✓ ${normalized.host} has the ${REQUIRED_AGENT_PREFIX} family and the embedder`);
+    agent = { normalized, models };
+  }
+
+  // ---- SERVER 2: the coder ------------------------------------------------------------
+  // Defaults to the agent server, because one box is the common case and Enter should mean
+  // "same". A DIFFERENT address here is the whole point of asking separately: the coder is the
+  // heavy model and is often on other hardware than the little one that routes every turn.
+  const coderDefault = agent?.normalized?.url ?? defaultUrl;
+  let coder = null;
+  for (let attempt = 0; attempt < attempts && !coder; attempt++) {
+    const typed = (await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `)).trim();
+    if (isDecline(typed)) break;
+    // Same box as the agent server → reuse the list we already have rather than fetching twice.
+    const same = normalizeOllamaUrl(typed || coderDefault);
+    const tried =
+      agent && same && same.url === agent.normalized.url
+        ? { normalized: same, models: agent.models }
+        : await loadFirstThatAnswers(typed || coderDefault, fetchTags, log);
+    if (!tried || tried.failed) {
+      // One explanation, the best one available: the provider message when we recognise the
+      // address, otherwise the reachability advice we were going to give anyway.
+      const explained = await explainIfOpenAi(typed || coderDefault, probeStatus, log, describeOpenAiCoder);
+      if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
+      continue;
+    }
+    const { normalized, models } = tried;
+    const usable = usableModelList(models);
+    if (!usable.ok) {
+      for (const l of describeUnusableList(usable.why, normalized.host)) log(`  ${l}`);
+      continue;
+    }
+    coder = { normalized, models };
+  }
+
+  // ---- NOTHING CHOSEN ------------------------------------------------------------------
+  // A real answer, not a failure. The machine finishes setup unconfigured, the bar shows the
+  // roles as unset, and the first question says so instead of hanging — which is the entire
+  // reason declining is allowed to be this easy.
+  if (!agent && !coder) return null;
+
+  // ---- PICK THE MODELS -----------------------------------------------------------------
+  // THE AGENT IS CHOSEN, not assumed (user, 2026-09-06). The gate above proved the family is
+  // there; which member fills the role is a real decision — a box may hold gemma4:e4b for speed
+  // and gemma4:12b for quality, and only the person running the machine knows which they want.
+  // Not asked when there is exactly one candidate: a menu with a single row is a question with
+  // one answer, and answering it is pure ceremony.
+  const embed = agent ? REQUIRED_EMBED_MODEL : null;
+  let chat = "";
+  if (agent) {
+    const cands = agentCandidates(agent.models);
+    const agentDefault = defaultAgentModel(agent.models, preferred.chat);
+    if (cands.length <= 1) {
+      chat = agentDefault;
+    } else {
+      log("");
+      log("  AGENT model — routes every turn and writes the plain replies");
+      for (const row of renderModelMenu(cands, { defaultModel: agentDefault, formatSize })) log(row);
+      for (let t = 0; t < attempts && !chat; t++) {
+        const answer = await ask(`  agent [${agentDefault}]: `);
+        chat = parseMenuChoice(answer, cands, agentDefault) ?? "";
+        if (!chat) log(`  no model called that — type its number, or Enter for ${agentDefault}`);
+      }
+      chat = chat || agentDefault;
+    }
+  }
+  let code = "";
+  let extras = [];
+  if (coder) {
+    const roles = defaultRoles(coder.models, { preferred });
+    log("");
+    log("  CODING model — writes the code; worth waiting for");
+    for (const row of renderModelMenu(coder.models, { defaultModel: roles.code, formatSize })) log(row);
+    for (let t = 0; t < attempts && !code; t++) {
+      const answer = await ask(`  code [${roles.code}]: `);
+      code = parseMenuChoice(answer, coder.models, roles.code) ?? "";
+      if (!code) log(`  no model called that — type its number, or Enter for ${roles.code}`);
+    }
+    code = code || roles.code;
+
+    const rest = coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code);
+    if (rest.length) {
+      log("");
+      log("  Also offer in /model?  (numbers separated by commas, or Enter for none)");
+      for (const row of renderModelMenu(rest, { formatSize })) log(row);
+      extras = parseMultiChoice(await ask("  also: "), rest);
+    }
+  }
+
+  // HALF-CONFIGURED IS A REAL STATE and must be representable. Someone with an agent box but no
+  // coder yet, or a coder but no agent box, has made progress worth keeping — forcing both or
+  // nothing would throw away the half they got right and is exactly the all-or-nothing shape
+  // that makes people abandon a setup flow.
+  return {
+    url: agent?.normalized?.url ?? coder.normalized.url,
+    chat,
+    code,
+    ...(agent && coder && coder.normalized.url !== agent.normalized.url
+      ? { codeUrl: coder.normalized.url }
+      : {}),
+    ...(!agent && coder ? { codeUrl: coder.normalized.url } : {}),
+    ...(embed ? { embed } : {}),
+    altCoders: (extras ?? []).filter((n) => n !== code),
+    ready: Boolean(agent && coder),
+  };
+}
+
+/** "no", "skip", "-" — a decline, not an address. */
+function isDecline(typed) {
+  return /^(no|n|skip|-)$/i.test(String(typed ?? "").trim());
+}
+
+/**
+ * Node's fetch says "fetch failed" for everything and puts the actual cause one level down.
+ *
+ * ENOTFOUND (the name does not resolve) and ECONNREFUSED (it resolves, nothing is listening) are
+ * different problems with different fixes — a typo versus a stopped server — and "fetch failed"
+ * tells the reader neither.
+ */
+export function networkReason(err) {
+  const cause = err?.cause;
+  const code = cause?.code || err?.code;
+  if (code === "ENOTFOUND") return "no such host — check the name";
+  if (code === "ECONNREFUSED") return "nothing is listening there — is Ollama running?";
+  if (code === "ETIMEDOUT" || err?.name === "TimeoutError") return "timed out — no answer";
+  if (code === "CERT_HAS_EXPIRED" || /certificate/i.test(cause?.message ?? "")) {
+    return "the TLS certificate was rejected";
+  }
+  return String(cause?.message || err?.message || err);
+}
+
+/**
+ * Try each reading of what was typed and keep the first that answers.
+ *
+ * Returns {normalized, models} or null (having already said why). Only the LAST failure is
+ * reported: telling someone "http://host:11434 failed AND https://host failed" when they typed
+ * one address is two errors for one mistake, and neither names the address they gave.
+ */
+/**
+ * After an Ollama probe has failed, say something TRUE about what the address actually is.
+ *
+ * Silent unless it recognises a hosted provider — a genuinely unreachable box has already had
+ * the right message printed by loadFirstThatAnswers, and a second guess on top of it would only
+ * muddy a correct one.
+ */
+async function explainIfOpenAi(raw, probeStatus, log, describe) {
+  if (typeof probeStatus !== "function") return false;
+  const url = openAiProbeUrl(raw);
+  if (!url) return false;
+  let status = 0;
+  try {
+    status = await probeStatus(url);
+  } catch {
+    return false;
+  }
+  if (!isOpenAiStatus(status)) return false;
+  let host = String(raw ?? "").trim();
+  try {
+    host = new URL(url).host;
+  } catch {
+    /* keep what was typed */
+  }
+  for (const line of describe(host)) log(`  ${line}`);
+  return true;
+}
+
+async function loadFirstThatAnswers(raw, fetchTags, log) {
+  const candidates = urlCandidates(raw);
+  if (!candidates.length) {
+    return { failed: ["that is not a server address — try 192.168.1.40, ollama.local, or a full URL"] };
+  }
+  let last = null;
+  for (const normalized of candidates) {
+    try {
+      const models = await fetchTags(tagsUrlFor(normalized));
+      // Say WHICH reading answered, but only when we had to guess — otherwise it is noise
+      // repeating what the user just typed.
+      if (candidates.length > 1) log(`  using ${displayUrl(normalized.url)}`);
+      log(`  found ${models.length} model${models.length === 1 ? "" : "s"} on ${normalized.host}`);
+      return { normalized, models };
+    } catch (e) {
+      last = e;
+    }
+  }
+  // NOT PRINTED HERE ANY MORE. "check that Ollama is running there" is exactly the wrong thing
+  // to say about a correct address for a hosted provider, and the caller is the only one that
+  // knows whether it found a better explanation. It prints one message or the other, never both.
+  return { failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
+                    "check the address, or that Ollama is running there and listening on the network."] };
+}