@tiens.nguyen/gu-cli 1.0.686

package/client-expert-api.mjs

@@ -0,0 +1,736 @@
+/**
+ * The back half of Client Expert (#154): make a database, start the local API, and point this
+ * terminal at it. Everything up to here only CHECKED things; this is the part that acts.
+ *
+ * The decisions worth knowing:
+ *
+ *   · The API's own MongoDB driver is reused rather than adding one to the CLI. The package
+ *     installs `mongodb` next to itself, and `mongosh` is NOT bundled with the MongoDB Server
+ *     MSI on Windows — so shelling out to a shell that may not exist would fail on the exact
+ *     platform this was written for.
+ *
+ *   · DATA_BACKEND=mongo is mandatory and is verified after boot, not assumed. Without it the
+ *     API starts happily, answers /api/health with 200, and writes everything to a DynamoDB
+ *     that is not there. That is the worst kind of broken — it looks fine — and it is why
+ *     apiIsUsable() checks the health BODY rather than the status code.
+ *
+ * The pure decisions (env, health verdict, readiness) are separated from the IO so they can be
+ * tested without a database, a network, or Windows.
+ */
+import { createRequire } from "node:module";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { spawnSurviving, pidOnPort } from "./platform-tools.mjs";
+import { spawn } from "node:child_process";
+import { writeFile, mkdir, readFile, access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Where the local API listens. 4100 keeps clear of the hosted API and of Vite's 5173. */
+export const LOCAL_API_PORT = Number(process.env.GONEXT_LOCAL_API_PORT ?? "4100") || 4100;
+export const LOCAL_API_BASE = `http://127.0.0.1:${LOCAL_API_PORT}`;
+export const LOCAL_MONGO_URI = process.env.GONEXT_LOCAL_MONGO_URI || "mongodb://127.0.0.1:27017";
+export const LOCAL_DB_NAME = process.env.GONEXT_LOCAL_DB_NAME || "gu";
+
+const GONEXT_DIR = join(homedir(), ".gonext");
+export const API_PID_FILE = join(GONEXT_DIR, "local-api.pid");
+export const API_LOG_FILE = join(GONEXT_DIR, "local-api.log");
+
+/** The API authenticates a worker by sha256 of the key — same function it uses server-side. */
+export function hashWorkerKey(secret) {
+  return createHash("sha256").update(String(secret), "utf8").digest("hex");
+}
+
+/** Same shape the hosted API issues, so nothing downstream can tell the difference. */
+export function generateWorkerKey() {
+  return `wk_${randomBytes(24).toString("base64url")}`;
+}
+
+/**
+ * A local identity. There is no Firebase here, and every row is keyed by userId, so one is
+ * minted once and kept — changing it later would orphan every conversation already stored.
+ */
+export function generateLocalUserId() {
+  return `local-${randomUUID()}`;
+}
+
+/**
+ * Environment for the local API.
+ *
+ * DATA_BACKEND is the whole point: it defaults to "dynamo" inside the API, so omitting it
+ * yields a server that runs and persists nothing.
+ */
+export function apiEnv({
+  port = LOCAL_API_PORT,
+  mongoUri = LOCAL_MONGO_URI,
+  dbName = LOCAL_DB_NAME,
+  base = {},
+} = {}) {
+  return {
+    ...base,
+    PORT: String(port),
+    DATA_BACKEND: "mongo",
+    MONGODB_URI: mongoUri,
+    MONGODB_DB: dbName,
+  };
+}
+
+/**
+ * Is this health body a usable API?
+ *
+ * A 200 is not the question. The API answers 200 while writing to a DynamoDB that does not
+ * exist, so the body is what decides: the backend must be mongo AND persistence must be on.
+ */
+export function apiIsUsable(body) {
+  if (!body || typeof body !== "object") return { ok: false, why: "no health response" };
+  if (body.ok !== true) return { ok: false, why: "API reports not ok" };
+  if (body.dataBackend !== "mongo") {
+    return {
+      ok: false,
+      why: `API is using "${body.dataBackend}" instead of mongo — it would persist nothing locally`,
+    };
+  }
+  if (body.persistence !== true) {
+    return { ok: false, why: "API reached mongo but reports persistence off" };
+  }
+  return { ok: true, why: "" };
+}
+
+/** Load the API's own `mongodb` package. Throws a legible error when deps are not installed. */
+export function loadMongoDriver(apiDir) {
+  try {
+    return createRequire(join(apiDir, "package.json"))("mongodb");
+  } catch (e) {
+    throw new Error(
+      `the API's dependencies are not installed in ${apiDir} (${e.code || e.message})`
+    );
+  }
+}
+
+/** Have the API's dependencies been installed? */
+export async function apiDepsInstalled(apiDir) {
+  try {
+    await access(join(apiDir, "node_modules", "mongodb", "package.json"));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `npm install` inside the downloaded API. ~360 packages, so it is reported, not silent.
+ *
+ * WINDOWS NEEDS A SHELL, and not for the usual reason. npm there is `npm.cmd`, and since the
+ * fix for CVE-2024-27980 (Node 18.20 / 20.12) spawning a .cmd or .bat WITHOUT a shell throws
+ * `spawn EINVAL` outright — which is exactly what a Windows 11 machine reported here. The
+ * shell is the supported way to run a batch script, not a workaround.
+ *
+ * Safe because every argument is a literal flag: nothing user-supplied reaches the command
+ * line. The one value that could contain spaces — the install directory — is passed as `cwd`,
+ * which never goes through the shell.
+ */
+export function npmInstallCommand(platform = process.platform) {
+  const windows = platform === "win32";
+  const cmd = windows ? "npm.cmd" : "npm";
+  const args = ["install", "--omit=dev", "--no-audit", "--no-fund", "--loglevel=error"];
+  return {
+    cmd,
+    args,
+    // Only where it is required. A shell on POSIX would add quoting rules for no benefit.
+    shell: windows,
+    /**
+     * The shell form: ONE string, no args array.
+     *
+     * Node 22 prints DEP0190 — "Passing args to a child process with shell option true can
+     * lead to security vulnerabilities, as the arguments are not escaped, only concatenated" —
+     * and printed it in the middle of the Windows setup output, which reads like something
+     * went wrong. Node is right: with a shell, the array is concatenated anyway, so building
+     * the line explicitly is both quieter AND more honest about what runs. Safe because every
+     * argument here is a literal flag (asserted in the tests).
+     */
+    line: [cmd, ...args].join(" "),
+  };
+}
+
+export function installApiDeps(apiDir, { onLine } = {}) {
+  const { cmd, args, shell, line } = npmInstallCommand();
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      // With a shell, pass the whole line and NO args array — see `line` above (DEP0190).
+      child = shell
+        ? spawn(line, { cwd: apiDir, stdio: ["ignore", "pipe", "pipe"], shell: true })
+        : spawn(cmd, args, { cwd: apiDir, stdio: ["ignore", "pipe", "pipe"], shell: false });
+    } catch (e) {
+      // spawn() can throw SYNCHRONOUSLY (EINVAL does). Without this the raw "spawn EINVAL"
+      // surfaced with no clue as to which command failed — which is how it was first reported.
+      reject(new Error(`could not run ${cmd} in ${apiDir}: ${e.message}`));
+      return;
+    }
+    let err = "";
+    child.stdout.on("data", (b) => onLine?.(String(b).trim()));
+    child.stderr.on("data", (b) => {
+      err += String(b);
+      onLine?.(String(b).trim());
+    });
+    child.on("error", (e) => reject(new Error(`could not run ${cmd} in ${apiDir}: ${e.message}`)));
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`npm install failed (exit ${code}) ${err.slice(-400)}`))
+    );
+  });
+}
+
+/**
+ * Create the database and the worker key.
+ *
+ * The API builds its own indexes lazily on first use, so only the ones setup depends on are
+ * made here — the unique index on keyHash, which is what makes seeding idempotent.
+ */
+export async function seedDatabase({
+  apiDir,
+  mongoUri = LOCAL_MONGO_URI,
+  dbName = LOCAL_DB_NAME,
+  userId,
+  workerKey,
+} = {}) {
+  const { MongoClient } = loadMongoDriver(apiDir);
+  const client = new MongoClient(mongoUri, { serverSelectionTimeoutMS: 8000 });
+  await client.connect();
+  try {
+    const db = client.db(dbName);
+    const keys = db.collection("worker_keys");
+    await keys.createIndex({ keyHash: 1 }, { unique: true });
+    const key = workerKey || generateWorkerKey();
+    const uid = userId || generateLocalUserId();
+    await keys.updateOne(
+      { keyHash: hashWorkerKey(key) },
+      {
+        $set: {
+          keyHash: hashWorkerKey(key),
+          userId: uid,
+          workerHostId: "",
+          updatedAt: new Date().toISOString(),
+        },
+      },
+      { upsert: true }
+    );
+    return { workerKey: key, userId: uid, dbName };
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+/**
+ * Start the API so it OUTLIVES this terminal — including an SSH session.
+ *
+ * `detached: true` is not enough on Windows: an SSH session runs inside a JOB OBJECT, and
+ * Windows kills every process in the job when the session ends. Proved on a real box — the
+ * API died, and so did the worker daemon, which uses the same detached spawn that survives
+ * perfectly from an ordinary console window. spawnSurviving() goes through the task scheduler
+ * there, whose children are not in our job.
+ */
+export async function startLocalApi({
+  apiDir,
+  port = LOCAL_API_PORT,
+  mongoUri = LOCAL_MONGO_URI,
+  dbName = LOCAL_DB_NAME,
+} = {}) {
+  await mkdir(GONEXT_DIR, { recursive: true });
+  const res = await spawnSurviving({
+    cmd: process.execPath,
+    args: ["index.js"],
+    cwd: apiDir,
+    env: apiEnv({ port, mongoUri, dbName }),
+    logFile: API_LOG_FILE,
+    taskName: "gu-local-api",
+  });
+  // A task-launched process is not our child, so its pid is discovered from the port it
+  // serves — which is the better question anyway: what matters is who is answering, not who
+  // we spawned. Recorded after the server is up, by the caller's waitForApi.
+  const pid = res.pid ?? null;
+  if (pid) await writeFile(API_PID_FILE, String(pid) + "\n").catch(() => {});
+  return { pid, how: res.how };
+}
+
+/** Record whoever is serving the port, so `api stop` has something to stop. */
+export async function recordApiPid(port = LOCAL_API_PORT) {
+  const pid = await pidOnPort(port);
+  if (pid) await writeFile(API_PID_FILE, String(pid) + "\n").catch(() => {});
+  return pid;
+}
+
+/** Poll /api/health until it is USABLE (see apiIsUsable) or the budget runs out. */
+export async function waitForApi({ port = LOCAL_API_PORT, timeoutMs = 45000, now = Date.now } = {}) {
+  const deadline = now() + timeoutMs;
+  let last = { ok: false, why: "never answered" };
+  while (now() < deadline) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+        signal: AbortSignal.timeout(4000),
+      });
+      const body = await res.json();
+      last = apiIsUsable(body);
+      if (last.ok) {
+        // The pid is only knowable once something is LISTENING, and on Windows the process is
+        // not our child at all — so it is learned from the port rather than from the spawn.
+        await recordApiPid(port).catch(() => {});
+        return { ...last, body };
+      }
+      // A wrong-backend API will never become right by waiting — fail fast instead of
+      // spending the whole budget on something a restart cannot fix.
+      if (body && body.ok === true) return { ...last, body };
+    } catch (e) {
+      last = { ok: false, why: e.name === "TimeoutError" ? "health timed out" : "not up yet" };
+    }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return { ...last, body: null };
+}
+
+/**
+ * Wait until nothing is answering on the port — the opposite of waitForApi (task #170 P4).
+ *
+ * WHY THIS IS NOT `await sleep(1500)`. Killing a server and sleeping is a guess about how long
+ * the OS takes to release a listening socket, and it is wrong in both directions: too short on a
+ * loaded CI runner, where the next start then fails with EADDRINUSE and looks like a product bug,
+ * and pure waste on a fast machine. The condition is observable, so observe it.
+ *
+ * Polls faster than waitForApi because going down is quick and this sits on the critical path of
+ * every restart.
+ */
+export async function waitForApiDown({ port = LOCAL_API_PORT, timeoutMs = 20000, now = Date.now } = {}) {
+  const deadline = now() + timeoutMs;
+  while (now() < deadline) {
+    if (!(await probeLocalApi(port)).reachable) return { down: true, why: "" };
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  // Reported rather than thrown: a caller that is about to start a fresh server may still want to
+  // try, and the message is more useful attached to THAT failure than raised here.
+  return { down: false, why: `something is still answering on ${port} after ${timeoutMs}ms` };
+}
+
+/** Is a previously started API still answering? Used by status/doctor and by resume. */
+export async function probeLocalApi(port = LOCAL_API_PORT) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      signal: AbortSignal.timeout(3000),
+    });
+    const body = await res.json();
+    return { reachable: true, ...apiIsUsable(body), body };
+  } catch {
+    return { reachable: false, ok: false, why: "no API on the port", body: null };
+  }
+}
+
+/** KEY=VALUE lines → object. Comments and blanks ignored; the first `=` splits. */
+export function parseEnvFile(text) {
+  const out = {};
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const eq = t.indexOf("=");
+    if (eq <= 0) continue;
+    out[t.slice(0, eq).trim()] = t.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+/**
+ * The worker.env this terminal reads, MERGED over whatever is already there.
+ *
+ * Both existing writers rewrite the file from three fixed keys, which silently drops anything
+ * else a user has set (GONEXT_SEARXNG_URL and GONEXT_PROBE_PYTHON are both real examples). A
+ * setup step is the worst place to lose someone's configuration, so this one only overrides
+ * the two values it actually owns.
+ */
+export function workerEnvContents({ apiBase, workerKey, existing = "" }) {
+  const merged = {
+    GONEXT_POLL_MS: "500",
+    ...parseEnvFile(existing),
+    GONEXT_API_BASE: String(apiBase).replace(/\/+$/, ""),
+    GONEXT_WORKER_KEY: workerKey,
+  };
+  return (
+    "# gu — Local mode: the API and database are on THIS machine.\n" +
+    "# Written by `gu` setup; `gu clear` removes it.\n" +
+    Object.entries(merged)
+      .map(([k, v]) => `${k}=${v}`)
+      .join("\n") +
+    "\n"
+  );
+}
+
+export async function writeWorkerEnv({ apiBase, workerKey }) {
+  await mkdir(GONEXT_DIR, { recursive: true });
+  const path = join(GONEXT_DIR, "worker.env");
+  const existing = await readFile(path, "utf8").catch(() => "");
+  await writeFile(path, workerEnvContents({ apiBase, workerKey, existing }));
+  return path;
+}
+
+/** Does worker.env already point at the local API? Answers the "worker-env" step's probe. */
+export async function workerEnvPointsLocal(port = LOCAL_API_PORT) {
+  try {
+    const txt = await readFile(join(GONEXT_DIR, "worker.env"), "utf8");
+    return txt.includes(`:${port}`) && /GONEXT_API_BASE=https?:\/\/(127\.0\.0\.1|localhost)/.test(txt);
+  } catch {
+    return false;
+  }
+}
+
+/* ------------------------------------------------------------------ settings ----------- */
+
+/**
+ * Defaults for a brand-new Client Expert machine.
+ *
+ * These MIRROR what the hosted API seeds when a normal account pairs (routes/workerHosts.ts,
+ * task #127). Client Expert never pairs with that API — it makes its own database — so nothing
+ * was seeding them here, and the terminal stopped dead on "no agent model is configured for
+ * your account yet" with advice (`gu-cli login`) that points at a server this machine
+ * deliberately does not use.
+ */
+export const DEFAULT_CODER_URL = "https://api.moonshot.ai/v1";
+export const DEFAULT_CODER_MODEL = "kimi-k3";
+export const DEFAULT_MLX_AGENT_URL = "http://127.0.0.1:8082";
+export const DEFAULT_OLLAMA_AGENT_URL = "http://127.0.0.1:11434/v1";
+export const DEFAULT_EMBED_URL = "http://127.0.0.1:8085";
+export const DEFAULT_EMBED_MODEL = "mlx-community/Qwen3-Embedding-8B-4bit-DWQ";
+
+/** Is a local Ollama serving models, and what does it have? */
+export async function probeLocalOllama() {
+  try {
+    const res = await fetch("http://127.0.0.1:11434/api/tags", {
+      signal: AbortSignal.timeout(1500),
+    });
+    if (!res.ok) return { ok: false, models: [] };
+    const body = await res.json();
+    const models = (body?.models ?? []).map((m) => String(m?.name ?? "")).filter(Boolean);
+    return { ok: true, models };
+  } catch {
+    return { ok: false, models: [] };
+  }
+}
+
+/**
+ * The model backends a Client Expert machine can be pointed at.
+ *
+ * A CHOICE, not a guess. The old code seeded whatever it could infer — a local Ollama URL on a
+ * machine with no Ollama, or the Apple-only MLX port — so setup finished "successfully" and the
+ * first question failed with a model that was never going to answer. Two options that both
+ * WORK are better than one that might.
+ */
+/** The shared Ollama every client machine can already reach. */
+export const SHARED_OLLAMA_URL =
+  process.env.GONEXT_CLIENT_AGENT_URL?.trim() || "https://ollama1.gomarsic.cc/v1";
+/**
+ * Chat model — the one the agent routes and thinks with, on every step of every turn.
+ *
+ * Deliberately NOT the code model. Measured on the shared box: this one is 6GB resident and
+ * sits 100% in VRAM, while the 28GB coder does not fit on a 24GB card at all and spills to
+ * CPU. The chat model is called constantly, so its latency is the one a person feels; the
+ * coder is called for the code and is worth waiting for.
+ */
+export const SHARED_CHAT_MODEL =
+  process.env.GONEXT_CLIENT_AGENT_MODEL?.trim() || "gemma4:e4b";
+/** Code model: the bigger one, chosen deliberately for capability over latency. */
+export const SHARED_CODE_MODEL =
+  process.env.GONEXT_CLIENT_CODE_MODEL?.trim() || "gemma4-quadro-49k:latest";
+/**
+ * A SECOND coder on the same box, offered by `/model` (user request, 2026-08-24).
+ *
+ * Not a replacement for SHARED_CODE_MODEL and not the default — an alternative to switch to when
+ * the default one is struggling, which is the situation `/model` exists for. Same host, so it
+ * needs no URL, no key and no extra setup; it is purely a name added to the offered list.
+ */
+export const SHARED_ALT_CODE_MODEL =
+  process.env.GONEXT_CLIENT_ALT_CODE_MODEL?.trim() || "qwen3.8:27b";
+/**
+ * Embedder for RAG. Named here because the hosted default is an MLX server on :8085 — Apple
+ * Silicon only, and not running on a Client Expert box at all. Seeding that meant RAG could
+ * never work off a Mac; this is an embedder every client can actually reach.
+ */
+export const SHARED_EMBED_MODEL =
+  process.env.GONEXT_CLIENT_EMBED_MODEL?.trim() || "nomic-embed-text:latest";
+
+/**
+ * The three models a Client Expert machine starts with, all on the shared Ollama.
+ *
+ * NO QUESTION AT SETUP. There was one — Ollama or Kimi — and it earned its keep while the
+ * alternative was "a URL that answers nothing", but all three of these work out of the box and
+ * need no credential. The coder is changeable afterwards with `/model`, which is the right
+ * place for it: a decision you can revisit beats a question you must answer before you have
+ * seen the thing work.
+ */
+export const CLIENT_EXPERT_MODELS = {
+  url: SHARED_OLLAMA_URL,
+  /** Chat: routing and plain replies, on EVERY turn — so this is the latency you feel. */
+  chat: SHARED_CHAT_MODEL,
+  /** Code: writes the code blocks that drive the tools. Worth waiting for. */
+  code: SHARED_CODE_MODEL,
+  /** Embeddings for RAG. */
+  embed: SHARED_EMBED_MODEL,
+};
+
+/**
+ * The coding backends to register.
+ *
+ * TWO of them, and the KIND is what makes it work. `codingNeedsKey` in the API is
+ * `kind === "openai"`, so an "ollama" backend needs no credential and is usable the moment it
+ * is written — while Kimi is registered as "openai" so `/model` lists it and asks for the key
+ * only if the user actually switches. One slot per kind, so these cannot collide.
+ */
+export function codingBackendsForClientExpert(models = CLIENT_EXPERT_MODELS) {
+  const M = models ?? CLIENT_EXPERT_MODELS;
+  // The chat model is offered too, so `/model` can drop to the fast one for simple work, plus
+  // whatever else was chosen to switch UP to when the default coder is not coping.
+  //
+  // `altCoders` comes from the setup flow when the user picked their own box (task #220);
+  // SHARED_ALT_CODE_MODEL is the seeded default for the shared box. Deduped and stripped of the
+  // primary coder, because a `/model` list that offers the model you are already on — twice —
+  // is a list nobody trusts.
+  const offered = [M.chat, ...(M.altCoders ?? [SHARED_ALT_CODE_MODEL])].filter(
+    (name, i, all) => name && name !== M.code && all.indexOf(name) === i,
+  );
+  return [
+    {
+      kind: "ollama",
+      enabled: true,
+      url: M.url,
+      defaultModel: M.code,
+      models: offered,
+    },
+    {
+      kind: "openai",
+      enabled: true,
+      url: DEFAULT_CODER_URL,
+      defaultModel: DEFAULT_CODER_MODEL,
+      models: [],
+    },
+  ];
+}
+
+/**
+ * Which agent model to seed when nobody is asked (a non-interactive run).
+ *
+ * The hosted defaults assume MLX on :8082 — Apple-Silicon only. Client Expert runs on Linux
+ * and Windows too, where that port will never answer, so a local Ollama is preferred when one
+ * is actually serving. Pure, so the choice is testable without either being installed.
+ */
+export function chooseAgentModel({ platform, ollama }) {
+  if (ollama?.ok) {
+    // A model that is already pulled beats a name that has to be downloaded first. Preference
+    // order is only a nicety — any served model is better than a URL that answers nothing.
+    const preferred = ["gemma4:12b", "qwen3:14b", "llama3.1:8b"];
+    const model =
+      preferred.find((p) => ollama.models.includes(p)) ?? ollama.models[0] ?? "";
+    return { url: DEFAULT_OLLAMA_AGENT_URL, model, why: "local Ollama is serving models" };
+  }
+  if (platform === "darwin") {
+    return { url: DEFAULT_MLX_AGENT_URL, model: "", why: "MLX default — `gu doctor` starts it" };
+  }
+  // No Ollama and not a Mac: seed the Ollama URL anyway. It is the only local server that runs
+  // here, so it is the right thing to point at once one exists — and a configured-but-silent
+  // URL still lets the terminal START, which a missing setting does not.
+  return {
+    url: DEFAULT_OLLAMA_AGENT_URL,
+    model: "",
+    why: "no local model server yet — install Ollama, or point the Agent model URL elsewhere",
+  };
+}
+
+/**
+ * Models this machine should be OFFERED that its stored settings do not list yet.
+ * → an updated agentCodingBackends array, or null when nothing is missing.
+ *
+ * WHY A BACKFILL AND NOT JUST A BIGGER SEED. The seed runs behind `if (!hasCoder)`, so it fires
+ * once, at first setup, and never again. Adding a model to codingBackendsForClientExpert()
+ * therefore reaches NEW installs only — every machine already running would keep the list it was
+ * seeded with and never see the new name in `/model`. That is the shape of "a published fix
+ * reached nobody" that `api upgrade` was created to solve (see its comment in gu-cli.mjs).
+ *
+ * ADDITIVE, AND ONLY ADDITIVE. It appends names to `models`; it never removes one, never touches
+ * defaultModel, and never touches agentCodingDefaultKind — so what this machine actually RUNS is
+ * unchanged, and the only effect is that `/model` offers one more entry. The known cost: a user
+ * who deliberately pruned a model from the list would get it back. There is no UI to prune one in
+ * Client Expert (the list is seeded), so that is theoretical today, and the alternative — never
+ * updating the list — is the failure being fixed.
+ *
+ * SCOPED TO THE SHARED OLLAMA BY URL. An "ollama" backend the user re-pointed at their own box
+ * must not be told it serves ollama1's models; the names would be offered, picked, and fail at a
+ * host that has never heard of them.
+ */
+export function backfillCodingModels(existing = {}) {
+  const backends = existing?.agentCodingBackends;
+  if (!Array.isArray(backends) || backends.length === 0) return null;
+  const sameHost = (a, b) =>
+    String(a ?? "").trim().replace(/\/+$/, "") === String(b ?? "").trim().replace(/\/+$/, "");
+  const shared = codingBackendsForClientExpert().find((b) => b.kind === "ollama");
+  const known = [shared.defaultModel, ...shared.models].map((m) => String(m ?? "").trim()).filter(Boolean);
+  let changed = false;
+  const next = backends.map((b) => {
+    if ((b?.kind ?? "") !== "ollama" || !sameHost(b?.url, shared.url)) return b;
+    const listed = Array.isArray(b.models) ? b.models : [];
+    const have = new Set(
+      [b.defaultModel, ...listed].map((m) => String(m ?? "").trim()).filter(Boolean)
+    );
+    const missing = known.filter((m) => !have.has(m));
+    if (missing.length === 0) return b;
+    changed = true;
+    return { ...b, models: [...listed, ...missing] };
+  });
+  return changed ? next : null;
+}
+
+/**
+ * What to write, given what is already stored.
+ *
+ * ONLY fills what is missing, exactly like the hosted seeding: re-running setup must never
+ * overwrite a model the user has since chosen. Pure — the interesting behaviour is what it
+ * declines to touch. The one deliberate exception is backfillCodingModels, which ADDS offered
+ * model names to a list that already exists; see its docstring for why that is not "overwriting
+ * a model the user has since chosen".
+ */
+export function settingsPatch({ existing = {}, models = CLIENT_EXPERT_MODELS } = {}) {
+  const patch = {};
+  // `models` is either the seeded shared-Ollama defaults (nobody was asked) or the box the user
+  // chose at setup (task #220). Everything below is written in terms of M, so the two paths
+  // cannot drift into configuring different fields.
+  const M = models ?? CLIENT_EXPERT_MODELS;
+
+  const hasAgent =
+    Boolean(existing.agentModelUrl?.trim()) ||
+    Boolean(existing.agentModel?.trim()) ||
+    Boolean(existing.agentModelName?.trim());
+  if (!hasAgent) {
+    patch.agentModelUrl = M.url;
+    const name = M.chat;
+    // agentModelNAME is the field that matters. With a direct agent URL the API reads
+    // `agentModelName` and falls back to the literal string "default_model" when it is empty —
+    // which is what the banner showed, and what the agent actually asked Ollama for.
+    // `agentModel` is the OTHER thing: the legacy mlx-host key.
+    patch.agentModelName = name;
+    patch.agentModel = name;
+  }
+
+  const hasRag = existing.ragEnabled === true || Boolean(existing.ragEmbedUrl?.trim());
+  // NO EMBEDDER, NO RAG. When the user points at their own box (task #220) it may have no
+  // embedding model on it at all, and `embed` is then ABSENT rather than empty. Enabling RAG
+  // anyway would leave it configured and pointing at nothing — the same failure the MLX-on-8085
+  // seed used to produce, which is why the URL below is M.url and not that port.
+  if (!hasRag && M.embed) {
+    patch.ragEnabled = true;
+    patch.ragEmbedUrl = M.url;
+    patch.ragEmbedModel = M.embed;
+  }
+
+  const hasCoder =
+    (Array.isArray(existing.agentCodingBackends) && existing.agentCodingBackends.length > 0) ||
+    Boolean(existing.agentCodingModelUrl?.trim()) ||
+    Boolean(existing.agentCodingModelName?.trim());
+  if (!hasCoder) {
+    patch.agentCodingBackends = codingBackendsForClientExpert(M);
+    patch.agentCodingDefaultKind = "ollama";
+    // Legacy mirror, so an older worker resolves the same coder.
+    patch.agentCodingModelKind = "ollama";
+    patch.agentCodingModelUrl = M.url;
+    patch.agentCodingModelName = M.code;
+    // NO api key is stored. The default coder is kind "ollama", which the API does not require
+    // one for — and a placeholder here would be SENT to Kimi the moment someone switched with
+    // `/model`, failing at the provider with an auth error nobody expected.
+  } else {
+    // Already configured — so the seed above will never run again on this machine. Add any
+    // newly-offered shared-Ollama models to the list it was seeded with, without changing which
+    // coder it uses. See backfillCodingModels.
+    const merged = backfillCodingModels(existing);
+    if (merged) patch.agentCodingBackends = merged;
+  }
+
+  // FULL CODE-MODEL RESPONSES ARE SAVED IN THIS MODE (user, 2026-08-10: "in Client Expert,
+  // lets make in On by default for now").
+  //
+  // Why it has to be seeded rather than left to the user: agentSaveFullResponse's only writer
+  // is PATCH /api/settings, which is mounted behind requireFirebaseAuth — and Client Expert
+  // deliberately has no Firebase, and no web app pointed at the local API. So a Client Expert
+  // machine cannot turn this on by ANY supported route; off was not a default anyone chose, it
+  // was the only reachable state. Seeding is what makes the setting exist at all here.
+  //
+  // Why ON is defensible in THIS mode specifically: the text never leaves the machine. It is
+  // written to a MongoDB on the user's own disk, which is the entire premise of Client Expert —
+  // whereas on the hosted deployment the same flag ships full model output to our servers, which
+  // is exactly why it is opt-in there. Same field, different blast radius.
+  //
+  // What it buys: the raw reply that failed to parse (task #161). Diagnosing a code-parsing
+  // error without it means inferring the model's output from the error message about it.
+  //
+  // Only when the row does not already say — an explicit false is the user's choice, and a
+  // re-run of setup must not silently switch logging back on for someone who turned it off.
+  if (typeof existing.agentSaveFullResponse !== "boolean") {
+    patch.agentSaveFullResponse = true;
+  }
+  return patch;
+}
+
+/** Write the settings row this machine's own API will read. Returns what was written. */
+/**
+ * Is this machine's model configuration already set?
+ *
+ * Exists so the setup flow can decide whether to ASK (task #220). settingsPatch deliberately
+ * leaves a configured machine alone — that rule protects anyone who set their models up by hand
+ * — but combined with a question it produces the one behaviour this codebase keeps removing:
+ * asking something and then ignoring the answer. On a first run there is nothing here and the
+ * question is honoured; on a re-run of the models step there is, and the honest move is to not
+ * ask and to point at `/model`, which CAN change a configured machine.
+ *
+ * Best-effort: an unreachable database returns false, so the question is asked and seedSettings
+ * makes the real decision a moment later. Being wrong in that direction costs a question; being
+ * wrong the other way costs the answer.
+ */
+export async function modelsAlreadyConfigured({
+  apiDir,
+  mongoUri = LOCAL_MONGO_URI,
+  dbName = LOCAL_DB_NAME,
+  userId,
+} = {}) {
+  try {
+    const { MongoClient } = loadMongoDriver(apiDir);
+    const client = new MongoClient(mongoUri, { serverSelectionTimeoutMS: 4000 });
+    await client.connect();
+    try {
+      const existing = (await client.db(dbName).collection("settings").findOne({ userId })) ?? {};
+      return Object.keys(settingsPatch({ existing })).length === 0;
+    } finally {
+      await client.close().catch(() => {});
+    }
+  } catch {
+    return false;
+  }
+}
+
+export async function seedSettings({
+  apiDir,
+  mongoUri = LOCAL_MONGO_URI,
+  dbName = LOCAL_DB_NAME,
+  userId,
+  // The box the user chose at setup (task #220), or the shared-Ollama defaults when the
+  // question was skipped or declined. Passed straight to settingsPatch so there is exactly one
+  // place that decides what a Client Expert machine is configured with.
+  models = CLIENT_EXPERT_MODELS,
+} = {}) {
+  const { MongoClient } = loadMongoDriver(apiDir);
+  const client = new MongoClient(mongoUri, { serverSelectionTimeoutMS: 8000 });
+  await client.connect();
+  try {
+    const col = client.db(dbName).collection("settings");
+    const existing = (await col.findOne({ userId })) ?? {};
+    const patch = settingsPatch({ existing, models });
+    if (Object.keys(patch).length > 0) {
+      await col.updateOne(
+        { userId },
+        { $set: { ...patch, userId, updatedAt: new Date().toISOString() } },
+        { upsert: true },
+      );
+    }
+    return patch;
+  } finally {
+    await client.close().catch(() => {});
+  }
+}