@tiens.nguyen/gu-cli 1.0.686

package/proxy-dispatcher.mjs

@@ -0,0 +1,132 @@
+/**
+ * The Node half of the proxy: turning a decision into an actual routed request (task #160).
+ *
+ * WHY THIS IS NOT JUST "SET HTTPS_PROXY". Node's global fetch is undici, and undici does NOT
+ * read HTTP_PROXY/HTTPS_PROXY — setting them changes nothing, silently. (Node 24 added
+ * NODE_USE_ENV_PROXY, but engines.node is >=18 here and the dev machine is on 22, so the
+ * dependency is the portable answer.) This is the trap most likely to produce a build where the
+ * Python agent works and every Node-side probe reports the model down.
+ *
+ * PER-REQUEST, NEVER GLOBAL. setGlobalDispatcher() would route EVERY fetch in the process
+ * through the proxy — including the terminal's constant polling of http://127.0.0.1:4100 — which
+ * is precisely the failure the allowlist exists to prevent, and it would survive turning the
+ * proxy off within a session. So the dispatcher is attached to the individual request, and only
+ * when shouldProxy() says so.
+ */
+import { shouldProxy, proxyUrl, redactSecrets } from "./proxy-config.mjs";
+
+/**
+ * One ProxyAgent per dial string, kept for reuse.
+ *
+ * Not an optimisation — a new agent per request opens a new connection pool per request, and a
+ * proxy that authenticates then re-authenticates on every single call, which is both slow and a
+ * good way to trip an account lockout policy. Keyed by the dial string so changing the password
+ * produces a new agent rather than silently reusing the old credentials.
+ */
+const agents = new Map();
+
+let ProxyAgentCtor;
+let loadError = "";
+
+/**
+ * undici, loaded lazily and tolerantly.
+ *
+ * A machine with no proxy configured must not fail to start because an optional dependency did
+ * not install — the whole feature is off by default, and "gu will not run" is a far worse
+ * outcome than "the proxy is unavailable". So a missing undici is reported only to someone who
+ * actually asked for a proxy.
+ */
+async function proxyAgentCtor() {
+  if (ProxyAgentCtor || loadError) return ProxyAgentCtor;
+  try {
+    ({ ProxyAgent: ProxyAgentCtor } = await import("undici"));
+  } catch (err) {
+    loadError = err?.message || String(err);
+  }
+  return ProxyAgentCtor;
+}
+
+/** The reusable agent for this proxy, or null if undici is unavailable. */
+export async function dispatcherFor(proxy) {
+  const url = proxyUrl(proxy);
+  if (!url) return null;
+  if (agents.has(url)) return agents.get(url);
+  const Ctor = await proxyAgentCtor();
+  if (!Ctor) return null;
+  const agent = new Ctor(url);
+  agents.set(url, agent);
+  return agent;
+}
+
+/**
+ * Has the undici package actually been LOADED in this process?
+ *
+ * Exists for the tests, and the property it pins is one the user asked for directly: a machine
+ * with no proxy must not merely avoid ROUTING through one — it must never touch the proxy stack
+ * at all. Import cost, an extra connection pool, and any bug in that code path are all things
+ * the overwhelming majority of users (who have no proxy) should never be exposed to. Nothing in
+ * the product reads this; a test is the only way to prove a negative like "it was not loaded".
+ */
+export function undiciLoaded() {
+  return Boolean(ProxyAgentCtor);
+}
+
+/** How many proxy agents exist. Also for the tests: zero means nothing was ever dialled. */
+export function dispatcherCount() {
+  return agents.size;
+}
+
+/** Why a proxy could not be used, in terms someone can act on. "" when there is no problem. */
+export function proxyUnavailableReason() {
+  return loadError
+    ? `the proxy needs the "undici" package, which is not installed here (${loadError}) — ` +
+        `reinstall gu, or run without a proxy`
+    : "";
+}
+
+/**
+ * fetch(), routed through the proxy when — and only when — this URL is one of the configured
+ * model endpoints and the proxy is enabled.
+ *
+ * A DROP-IN FOR fetch AT THE MODEL CALL SITES. Anything not in the allowlist gets a plain fetch
+ * with no dispatcher, byte for byte the behaviour it has today, which is what makes adopting
+ * this at a call site safe even if that call site sometimes talks to something else.
+ *
+ * Errors are re-thrown with the credentials stripped: undici puts the dial URL into connection
+ * error messages, and that text ends up in the worker log and in the model's context.
+ */
+export async function proxyFetch(url, init = {}, { proxy, settings } = {}) {
+  if (!shouldProxy(url, { proxy, settings })) return fetch(url, init);
+  const dispatcher = await dispatcherFor(proxy);
+  // No dispatcher means undici is missing. Going DIRECT is the honest fallback: on a network
+  // that needs the proxy the call fails with a real network error, which is actionable, whereas
+  // throwing here would take down a code path that has nothing to do with proxies.
+  if (!dispatcher) return fetch(url, init);
+  try {
+    return await fetch(url, { ...init, dispatcher });
+  } catch (err) {
+    const clean = new Error(redactSecrets(err?.message || String(err)));
+    clean.cause = err?.cause;
+    clean.viaProxy = true;
+    throw clean;
+  }
+}
+
+/**
+ * Drop cached agents — called when the proxy changes or is disabled.
+ *
+ * Without this, disabling the proxy leaves a live connection pool to it: harmless for routing
+ * (shouldProxy is consulted per request), but it holds sockets open to a machine the user has
+ * said they are no longer using, and on a laptop that has left the office those sockets fail
+ * slowly rather than immediately.
+ */
+export function resetDispatchers() {
+  for (const agent of agents.values()) {
+    try {
+      agent.close?.();
+    } catch {
+      /* closing a pool must never be the thing that fails a command */
+    }
+  }
+  agents.clear();
+}

package/proxy-selftest.mjs

@@ -0,0 +1,234 @@
+/**
+ * "Does the proxy work on THIS machine?" — shipped, so it can be run where the problem is.
+ *
+ * WHY THIS EXISTS SEPARATELY FROM THE TEST SUITE. tests/ is not published: an installed machine
+ * has gu-cli and nothing else. But a proxy is the one feature whose failures are entirely
+ * about the machine it runs on — a corporate network, a Windows box, an odd interception rule —
+ * so the checks have to be runnable exactly there. Same shape as rag-selftest.mjs, and for the
+ * same reason: `gu-cli rag --test` exists because RAG could only be diagnosed in place.
+ *
+ * NEEDS NOTHING AND CHANGES NOTHING. It starts its own proxy and its own origin server on
+ * loopback, checks them, and shuts them down. No network, no MongoDB, no Docker, no configuration
+ * — and it does not read or modify the user's own proxy settings, so running it on a working
+ * machine cannot break that machine. That makes it safe to tell anyone to run at any time.
+ *
+ * WINDOWS. Deliberately built from node:http and node:net alone: no shelling out, no ports
+ * assumed free (0 = let the OS choose), no POSIX signals, no path handling. The one platform
+ * question that remains is whether undici can dial a proxy at all, which is check 1.
+ */
+import net from "node:net";
+import http from "node:http";
+import { once } from "node:events";
+import {
+  shouldProxy,
+  proxyUrl,
+  isLoopbackUrl,
+  redactSecrets,
+  classifyProxyFailure,
+} from "./proxy-config.mjs";
+import { proxyFetch, resetDispatchers, undiciLoaded } from "./proxy-dispatcher.mjs";
+
+const USER = "selftest";
+const PASS = "selftest-secret";
+
+/** A real CONNECT proxy that records what it was asked for. The recording IS the test. */
+function startProxy() {
+  const seen = [];
+  const authed = (req) => {
+    const [, b64] = String(req.headers["proxy-authorization"] || "").split(" ");
+    if (!b64) return false;
+    const [u, p] = Buffer.from(b64, "base64").toString().split(":");
+    return u === USER && p === PASS;
+  };
+  const server = http.createServer((req, res) => {
+    if (!authed(req)) {
+      res.writeHead(407, { "Proxy-Authenticate": 'Basic realm="gu"' });
+      res.end("proxy auth required");
+      return;
+    }
+    seen.push(req.url);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ viaProxy: true }));
+  });
+  server.on("connect", (req, clientSocket, head) => {
+    if (!authed(req)) {
+      clientSocket.end("HTTP/1.1 407 Proxy Authentication Required\r\n\r\n");
+      return;
+    }
+    seen.push(req.url);
+    // The PROXY resolves the name — which is why the checks below can use a hostname that does
+    // not exist in DNS. Reaching the origin then proves the tunnel carried the request.
+    const port = Number(req.url.split(":")[1]);
+    const upstream = net.connect(port, "127.0.0.1", () => {
+      clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+      upstream.write(head);
+      upstream.pipe(clientSocket);
+      clientSocket.pipe(upstream);
+    });
+    upstream.on("error", () => clientSocket.destroy());
+    clientSocket.on("error", () => upstream.destroy());
+  });
+  return { server, seen };
+}
+
+/** Stands in for a model endpoint, and records what actually arrived. */
+function startOrigin() {
+  const hits = [];
+  const server = http.createServer((req, res) => {
+    hits.push(req.url);
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ origin: true }));
+  });
+  return { server, hits };
+}
+
+const listen = async (server) => {
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  return server.address().port;
+};
+
+/**
+ * Run the checks. Returns { ok, checks:[{title, ok, detail}] } — the same contract as
+ * runRagSelfTest, so the CLI, the npm script and the deploy-app can all render it identically.
+ */
+export async function runProxySelfTest({ onStep = () => {} } = {}) {
+  const checks = [];
+  const step = async (title, fn) => {
+    try {
+      const detail = await fn();
+      checks.push({ title, ok: true, detail: detail ?? "" });
+      onStep({ title, ok: true, detail: detail ?? "" });
+    } catch (e) {
+      const detail = redactSecrets(String(e?.message ?? e).split("\n")[0]);
+      checks.push({ title, ok: false, detail });
+      onStep({ title, ok: false, detail });
+    }
+  };
+
+  const proxyFx = startProxy();
+  const originFx = startOrigin();
+  const proxyPort = await listen(proxyFx.server);
+  const originPort = await listen(originFx.server);
+
+  // The "model" is named by a hostname that does not resolve, on purpose: any request that
+  // reaches the origin can only have got there through the proxy.
+  const MODEL_URL = `http://model.invalid:${originPort}/v1`;
+  const settings = { agentModelUrl: MODEL_URL, agentCodingModelUrl: MODEL_URL, ragEmbedUrl: MODEL_URL };
+  const proxy = {
+    enabled: true,
+    host: "127.0.0.1",
+    port: proxyPort,
+    username: USER,
+    password: PASS,
+  };
+  const LOCAL_API = `http://127.0.0.1:${originPort}/api/worker/jobs/next`;
+
+  try {
+    await step("undici can be loaded", async () => {
+      const { dispatcherFor } = await import("./proxy-dispatcher.mjs");
+      const d = await dispatcherFor(proxy);
+      if (!d) {
+        throw new Error(
+          'the "undici" package is missing — reinstall gu (npm i -g @tiens.nguyen/gu-cli)'
+        );
+      }
+      return "the proxy transport is available";
+    });
+
+    await step("a model call goes THROUGH the proxy", async () => {
+      proxyFx.seen.length = 0;
+      originFx.hits.length = 0;
+      const res = await proxyFetch(`${MODEL_URL}/chat/completions`, {}, { proxy, settings });
+      if (!res.ok) throw new Error(`the proxied call returned HTTP ${res.status}`);
+      // Two witnesses: the proxy was asked to connect, and the request arrived at the far end.
+      if (proxyFx.seen.length === 0) throw new Error("the proxy never saw the request");
+      if (originFx.hits.length === 0) throw new Error("the request never reached the endpoint");
+      return `tunnelled to ${proxyFx.seen[0]}`;
+    });
+
+    await step("all three model roles are routed", async () => {
+      originFx.hits.length = 0;
+      for (const p of ["/chat/completions", "/completions", "/embeddings"]) {
+        await proxyFetch(`${MODEL_URL}${p}`, {}, { proxy, settings });
+      }
+      if (originFx.hits.length !== 3) {
+        throw new Error(`only ${originFx.hits.length} of 3 arrived — chat, code and embed differ`);
+      }
+      return "chat, code and embed all reached the endpoint";
+    });
+
+    await step("local traffic is NOT proxied", async () => {
+      // The check that matters most on a real machine: if this fails, every turn breaks the
+      // moment a proxy is switched on, because the terminal's own API calls get routed.
+      proxyFx.seen.length = 0;
+      const res = await proxyFetch(LOCAL_API, {}, { proxy, settings });
+      if (!res.ok) throw new Error(`the local call returned HTTP ${res.status}`);
+      if (proxyFx.seen.length > 0) {
+        throw new Error(`the local API was sent through the proxy (${proxyFx.seen[0]})`);
+      }
+      if (!isLoopbackUrl(LOCAL_API)) throw new Error("loopback was not recognised as local");
+      return "127.0.0.1 and localhost go direct";
+    });
+
+    await step("a disabled proxy routes nothing", async () => {
+      proxyFx.seen.length = 0;
+      const off = { ...proxy, enabled: false };
+      if (shouldProxy(`${MODEL_URL}/chat/completions`, { proxy: off, settings })) {
+        throw new Error("a disabled proxy was still selected for a model call");
+      }
+      // And the call genuinely goes out on its own — which is why it must FAIL to resolve.
+      let wentDirect = false;
+      try {
+        await proxyFetch(`${MODEL_URL}/chat/completions`, {}, { proxy: off, settings });
+      } catch {
+        wentDirect = true;
+      }
+      if (!wentDirect || proxyFx.seen.length > 0) {
+        throw new Error("a disabled proxy still carried the request");
+      }
+      return "off means off";
+    });
+
+    await step("bad credentials are reported as an auth failure", async () => {
+      // So a wrong password reads as "retype it", not as the model being down.
+      const bad = { ...proxy, password: "definitely-wrong" };
+      let status = 0;
+      try {
+        status = (await proxyFetch(`${MODEL_URL}/chat/completions`, {}, { proxy: bad, settings })).status;
+      } catch (e) {
+        if (String(e.message).includes("definitely-wrong")) {
+          throw new Error("the password leaked into the error message");
+        }
+        status = 407;
+      }
+      const kind = classifyProxyFailure({ status });
+      if (kind !== "proxy-auth") throw new Error(`a wrong password was classified as "${kind}"`);
+      return "407 is recognised as a credentials problem";
+    });
+
+    await step("the password never appears in output", async () => {
+      // The failure with no error message. Checked against the real dial string, which is the
+      // one place the secret genuinely lives.
+      const dialled = proxyUrl(proxy);
+      if (!dialled.includes(PASS)) throw new Error("the self-test is not exercising a password");
+      const shown = redactSecrets(`connect failed via ${dialled}`);
+      if (shown.includes(PASS)) throw new Error("the password survived redaction");
+      if (!shown.includes("***")) throw new Error("redaction removed the password without a trace");
+      return "credentials are redacted wherever they are printed";
+    });
+
+    await step("nothing was left running", async () => {
+      resetDispatchers();
+      return undiciLoaded()
+        ? "proxy connections closed"
+        : "proxy connections closed (undici was never needed)";
+    });
+  } finally {
+    resetDispatchers();
+    proxyFx.server.close();
+    originFx.server.close();
+  }
+
+  return { ok: checks.every((c) => c.ok), checks };
+}

package/proxy-store.mjs

@@ -0,0 +1,69 @@
+/**
+ * Where the proxy configuration lives (task #160).
+ *
+ * A LOCAL FILE, NOT THE SETTINGS ROW, and that is the whole reason this module exists rather
+ * than the proxy riding along in Mongo with the model settings. A proxy is a property of the
+ * NETWORK a machine is sitting on, not of the user's account: the same account on a laptop at
+ * home and a workstation in an office needs the proxy on one and not the other. Storing it
+ * per-account would push a corporate proxy onto every machine the moment one of them configured
+ * it — and in Client Expert the settings row lives in a database that only that machine can
+ * read anyway, so there is nothing to gain.
+ *
+ * IT ALSO HOLDS A PASSWORD, which decides the file mode. Same treatment as worker.env: 0600,
+ * never logged, never echoed. See proxy-config.mjs redactSecrets() for the printing side.
+ */
+import { readFile, writeFile, mkdir, chmod, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { normalizeProxy } from "./proxy-config.mjs";
+
+const GONEXT_DIR = join(homedir(), ".gonext");
+export const PROXY_FILE = join(GONEXT_DIR, "proxy.json");
+
+/**
+ * The configured proxy, or a disabled empty one.
+ *
+ * NEVER THROWS. This is read on the startup path of every turn; a corrupt or half-written file
+ * must degrade to "no proxy" rather than taking the terminal down with it. The cost of guessing
+ * wrong in this direction is a model call that fails with a network error the user can act on —
+ * far better than a CLI that will not start.
+ */
+export async function loadProxy() {
+  try {
+    return normalizeProxy(JSON.parse(await readFile(PROXY_FILE, "utf8")));
+  } catch {
+    return normalizeProxy({});
+  }
+}
+
+/**
+ * Write it back, 0600.
+ *
+ * chmod AFTER the write, and on every save: the mode of an existing file is not changed by
+ * writeFile, so a file created before this rule existed would keep its old permissions forever.
+ * Best-effort on platforms where it means nothing (Windows), which is why it is not awaited into
+ * a failure.
+ */
+export async function saveProxy(proxy) {
+  const p = normalizeProxy(proxy);
+  await mkdir(GONEXT_DIR, { recursive: true });
+  await writeFile(PROXY_FILE, JSON.stringify(p, null, 2) + "\n", { mode: 0o600 });
+  await chmod(PROXY_FILE, 0o600).catch(() => {});
+  return p;
+}
+
+/**
+ * Turn it on or off WITHOUT touching the credentials.
+ *
+ * Deliberately not "disable = delete the file": a proxy that has to be retyped every time it is
+ * switched off is one users leave on, which is exactly the state that breaks their machine when
+ * they take the laptop home.
+ */
+export async function setProxyEnabled(enabled) {
+  return saveProxy({ ...(await loadProxy()), enabled: enabled === true });
+}
+
+/** Forget it entirely — the escape hatch when the credentials are wrong and confusing things. */
+export async function clearProxy() {
+  await unlink(PROXY_FILE).catch(() => {});
+}

package/rag-job-config.mjs

@@ -0,0 +1,59 @@
+/**
+ * The RAG slice of the agent config the worker hands python (#170).
+ *
+ * WHY THIS IS ITS OWN FILE. It was eleven lines inside runAgentChatJob, which lives in
+ * gu-cli.mjs — a bin script that starts the worker loop on import, so a test cannot reach it
+ * without launching a daemon. Untestable in place meant untested, and untested is how the bug
+ * below survived: the API had been sending `ragEmbedModelPath` since task #133, the worker never
+ * forwarded it, and the branch in gonext_agent_chat.py that reads it had been dead the whole time.
+ * Nothing failed. The label just said "from the server URL" for an embedder configured as a
+ * folder, and no test could have noticed.
+ *
+ * THE RULE THIS FILE EXISTS TO ENFORCE: every RAG field the API puts in a job payload reaches
+ * python. Dropping one is silent at both ends — the API keeps sending it, python keeps defaulting
+ * it — so the two lists have to be pinned against each other rather than kept in step by hand.
+ */
+
+/**
+ * Every RAG field the API's job payload carries, with the default to use when it does not.
+ *
+ * Mirrors the `ragPayload` object in api/src/app.ts (~line 1024). A field added there and not
+ * here does not break anything loudly, which is exactly why the test asserts the two agree.
+ *
+ * The defaults are NOT cosmetic. Empty means "not set", which the agent reports as such — see
+ * task #133, where defaulting the embed model to "nomic-embed-text" put a model the user never
+ * chose into the logs and the status table, the same lie #170 then had to undo at runtime.
+ */
+export const RAG_JOB_FIELDS = Object.freeze({
+  ragEnabled: false,
+  // S3 store + the user's own credentials: the worker talks to their bucket directly with these
+  // (boto3), NOT via presigned URLs.
+  ragS3Location: "",
+  ragAwsRegion: "",
+  ragAwsAccessKeyId: "",
+  ragAwsSecretAccessKey: "",
+  // The embedder, in three parts that are not interchangeable: the NAME (only Ollama needs it —
+  // it serves many models from one port), the URL, and the model FOLDER a single-model server is
+  // started from. The API derives the URL from the folder when no explicit URL is set, so a
+  // machine can legitimately have a folder and a derived URL and no name at all.
+  ragEmbedModel: "",
+  ragEmbedUrl: "",
+  ragEmbedModelPath: "",
+  ragTopK: 6,
+});
+
+/**
+ * The RAG fields to merge into the agent config, from an API job payload.
+ *
+ * A pass-through with defaults and nothing else: no validation, no derivation. python re-checks
+ * everything it is given (ragMode, ragTopK bounds, whether an embedder is reachable at all),
+ * and a second opinion here would only be a second place to be wrong.
+ */
+export function ragJobConfig(payload) {
+  const src = payload ?? {};
+  const out = {};
+  for (const [key, fallback] of Object.entries(RAG_JOB_FIELDS)) {
+    out[key] = src[key] ?? fallback;
+  }
+  return out;
+}