@tiens.nguyen/gonext-local-worker 1.0.343 → 1.0.347

package/gonext-repl.mjs

@@ -377,6 +377,9 @@ function slashRestoreHistory() {
 // which the earlier relative-cursor overlay hit whenever readline refreshed or the
 // menu was near the bottom of the screen and scrolled).
 let slashOverlayActive = false;
+// While true, readline's echo + line-refresh are muted so a typed secret (an API key) never
+// reaches the terminal or scrollback (task #127 — see askSecret + the _writeToOutput guards).
+let secretInput = false;
 
 // Visible width of PROMPT (">> ") — used to put the caret back on the input line by
 // COLUMN, since the string itself carries color escapes that don't occupy cells.
@@ -608,6 +611,20 @@ const ask = async (q) => {
 // re-uses the default. This replaces a fragile `(await ask()) || "y"` idiom where any
 // leftover character (a stray escape byte, a stray space) silently defeated the
 // default — the reported "[Y/n] + Enter registered as No" bug.
+// Masked prompt for a secret (an API key). Mutes readline's echo/refresh (secretInput)
+// so the typed value never hits the terminal or scrollback (task #127). Returns "" on a
+// bare Enter (skip).
+const askSecret = async (q) => {
+  process.stdout.write(q);
+  secretInput = true;
+  try {
+    const a = await nextLine();
+    return (a ?? "").trim();
+  } finally {
+    secretInput = false;
+    process.stdout.write("\n"); // the muted Enter left the cursor mid-line
+  }
+};
 const askYesNo = async (question, defaultYes) => {
   const suffix = defaultYes ? " [Y/n] " : " [y/N] ";
   const raw = (await ask(question + suffix)).trim().toLowerCase();
@@ -768,6 +785,22 @@ async function addOutputTokens(cwd, delta) {
   }
 }
 
+// Save the agent coding-model API key (task #127): the terminal prompts for the Kimi K3 key
+// when the default cloud coder has none, and POSTs it here (worker-key authed). Returns true
+// on success. Best-effort — a failure just leaves the reminder for next startup.
+async function saveCodingKey(apiKey) {
+  try {
+    const r = await fetch(`${apiBase}/api/worker/coding-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+      body: JSON.stringify({ apiKey }),
+    });
+    return r.ok;
+  } catch {
+    return false;
+  }
+}
+
 async function resetGlobalOutputTokens() {
   try {
     const r = await fetch(`${apiBase}/api/worker/output-tokens/reset-global`, {
@@ -1395,6 +1428,9 @@ rl._writeToOutput = (s) => {
   // slashOverlayActive: the slash-command overlay owns drawing (input line + menu), so
   // readline's own echo must be swallowed or it fights the overlay (bug #109).
   if (following || listPickerActive || slashOverlayActive) return;
+  // secretInput (task #127): the user is typing an API key — swallow the echo so it never
+  // appears in the terminal or scrollback.
+  if (secretInput) return;
   if (_origWriteToOutput) _origWriteToOutput(s);
   else process.stdout.write(s);
 };
@@ -1407,6 +1443,7 @@ rl._refreshLine = () => {
   // Suppress readline's line refresh (which does clearScreenDown → would wipe our menu)
   // while the slash overlay owns the screen. We redraw the input line ourselves (#109).
   if (following || listPickerActive || slashOverlayActive) return;
+  if (secretInput) return; // don't redraw the typed key (task #127)
   if (_origRefreshLine) _origRefreshLine();
 };
 
@@ -2316,9 +2353,50 @@ async function main() {
       } catch {
         /* doctor is best-effort — never block the REPL from starting */
       }
+      // Task #127: the default coding model is a cloud coder (Kimi K3) with no API key yet.
+      // Ask for it. If skipped, the account stays in this "waiting" state (server-side:
+      // coder configured, no key) and we ASK AGAIN on every startup until it's set. Until
+      // then the agent falls back to the chat model for coding, so the terminal still works.
+      if (p.codingKeyMissing) {
+        const model = String(p.codingKeyModel || "the coding model").trim();
+        console.log(
+          dim(`\ngonext: your agent coding model (`) + cyan(model) + dim(`) needs an API key.`)
+        );
+        console.log(
+          dim("  Until it's set, coding falls back to your local model. Enter the key now,")
+        );
+        console.log(dim("  or press Enter to skip (I'll ask again next time).\n"));
+        const key = await askSecret(`  ${model} API key: `);
+        if (key) {
+          const ok = await saveCodingKey(key);
+          console.log(
+            ok
+              ? green(`  ✓ saved — ${model} is now your coding model.\n`)
+              : red("  couldn't save the key — try again next start, or set it in web Settings → Agent.\n")
+          );
+        } else {
+          console.log(
+            dim("  ⏳ waiting for your ") + cyan(model) + dim(" API key — I'll ask again next time.\n")
+          );
+        }
+      }
     }
   } catch (err) {
-    console.error(red(`gonext: ${err.message}`));
+    // Task #127 (zero-config): a freshly-paired account is seeded with a default local
+    // agent model, so this "no model" path is normally unreachable. An account paired
+    // BEFORE that change has none — point them at re-login, which now seeds it, rather than
+    // only the raw web-Settings instruction.
+    if (/no agent model configured/i.test(err?.message ?? "")) {
+      console.error(
+        red("gonext: no agent model is configured for your account yet.") +
+          dim(
+            "\n  Run `gonext-local-worker login` to re-connect — new logins set up a local" +
+              "\n  default automatically. Or set the Agent model URL in the web app → Settings → Agent."
+          )
+      );
+    } else {
+      console.error(red(`gonext: ${err.message}`));
+    }
     process.exit(1);
   }
   console.log(dim("Ask about this repo. Type / to see commands (Tab completes). Ctrl-C aborts a running turn.\n"));

package/model-doctor.mjs

@@ -8,14 +8,52 @@
 // remote box). Downloads happen only when the model dir is genuinely absent AND the user
 // opts in.
 import { spawn, execFile } from "node:child_process";
-import { open, mkdir, readdir } from "node:fs/promises";
+import { open, mkdir, readdir, writeFile } from "node:fs/promises";
 import { homedir, totalmem } from "node:os";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 // Minimum RAM to run the default 14B-4bit chat model comfortably on Apple Silicon.
 const MIN_CHAT_RAM_GB = 16;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 
+// The RAG embedding model + server (task #127 — parity with the Wizard's model-embed step).
+// EMBED_PID_FILE / EMBED_LOG_FILE (which need DIR) are defined below, after DIR.
+export const EMBED_REPO = "mlx-community/Qwen3-Embedding-8B-4bit-DWQ";
+export const EMBED_DIR = join(homedir(), "mlx-models", "Qwen3-Embedding-8B-4bit-DWQ");
+export const EMBED_PORT = 8085;
+const EMBED_SCRIPT = fileURLToPath(new URL("./gonext_mlx_embed.py", import.meta.url));
+
+/** The python3 the worker uses to run its agent / model tooling (mirrors the daemon). */
+function python3Bin() {
+  return (
+    (process.env.GONEXT_PROBE_PYTHON ?? process.env.GONEXT_MLX_LM_PYTHON ?? "").trim() ||
+    "python3"
+  );
+}
+
+/** True when `python3 -c "import <mod>"` succeeds — i.e. the module is installed. */
+function pyHasModule(mod) {
+  return new Promise((resolve) => {
+    execFile(python3Bin(), ["-c", `import ${mod}`], (err) => resolve(!err));
+  });
+}
+
+/** pip install -U <pkgs> with live progress (inherit stdio). Rejects on non-zero exit. */
+function pipInstall(pkgs, log) {
+  log(`  installing ${pkgs.join(" ")} … (pip, this can take a minute)`);
+  return new Promise((resolve, reject) => {
+    const child = spawn(python3Bin(), ["-m", "pip", "install", "-U", ...pkgs], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`pip install ${pkgs.join(" ")} exited ${code}`))
+    );
+    child.on("error", reject);
+  });
+}
+
 /**
  * The yellow RAM notice shown before the multi-GB model download (user request): the
  * default 14B-4bit model wants a Mac with ≥16 GB. When the machine has less, add a plain
@@ -42,6 +80,8 @@ export function chatRamWarningLines(repo, totalBytes) {
 const DIR = join(homedir(), ".gonext");
 export const MODEL_PID_FILE = join(DIR, "model.pid");
 export const MODEL_LOG_FILE = join(DIR, "model.log");
+const EMBED_PID_FILE = join(DIR, "embed.pid");
+const EMBED_LOG_FILE = join(DIR, "embed.log");
 
 // The default base chat model (task #127 decision): matches the Wizard's model-chat step.
 export const DEFAULT_CHAT_REPO = "mlx-community/Qwen3-14B-4bit";
@@ -229,6 +269,13 @@ async function fetchModelConfig(apiBase, workerKey) {
  */
 export async function runDoctor({ apiBase, workerKey, log, confirm }) {
   const p = (await fetchModelConfig(apiBase, workerKey)) ?? {};
+
+  // Step 0: the agent's PYTHON deps must be present or every agent turn crashes at import
+  // — and the model download/start needs `hf`/`mlx-lm`. Ensure these FIRST (task #127:
+  // parity with the Wizard's pip-mlx-lm / pip-agent-libs / hf-cli steps). Fatal-ish: if the
+  // core framework is missing, say so, but keep going so the model steps still run.
+  const deps = await ensureAgentDeps({ log, confirm });
+
   // Chat model: prefer the account's configured URL; fall back to the default local one.
   const configuredChat = String(p.agentBaseURL || "").trim();
   const chatUrl = configuredChat || `http://127.0.0.1:${DEFAULT_CHAT_PORT}`;
@@ -338,5 +385,187 @@ export async function runDoctor({ apiBase, workerKey, log, confirm }) {
       log(`    answering. Start it there${codeModel ? ` (ollama pull ${codeModel})` : ""}.`);
     }
   }
-  return { chat };
+
+  // RAG (task #127: the user wants the terminal RAG-ready). Ensure the embedding model +
+  // server so rag_index / rag_search work. Uses the account's configured embed URL when
+  // local, else the default local one on EMBED_PORT.
+  const rag = await ensureRag({ p, log, confirm });
+
+  return { chat, deps, rag };
+}
+
+/**
+ * Ensure the agent's required runtime deps (task #127 — parity with the Wizard's pip steps).
+ * python3 can't be auto-installed (guidance only); hf / mlx-lm / smolagents+openai are
+ * offered via pip. Each install is confirmed. Returns a status map; missing deps are
+ * reported, never silently ignored — the agent hard-fails without smolagents+openai.
+ */
+export async function ensureAgentDeps({ log, confirm }) {
+  const out = {};
+  log("");
+  log("  Checking the agent's dependencies…");
+  // python3 — the whole agent runs on it; we can't install it for the user.
+  if (!(await pyHasModule("sys"))) {
+    log(`  ⚠ ${python3Bin()} not found. Install Python 3 (Xcode Command Line Tools or`);
+    log("    python.org), then run `gonext-local-worker doctor` again.");
+    out.python3 = "missing";
+    return out; // nothing else can be installed without python
+  }
+  out.python3 = "ok";
+
+  const ensurePkg = async (key, probeMod, pkgs, question) => {
+    if (await probeMod()) {
+      out[key] = "present";
+      return;
+    }
+    if (!(await confirm(question, true))) {
+      out[key] = "skipped";
+      log(`  Skipped ${pkgs.join(" ")} — install later: ${python3Bin()} -m pip install -U ${pkgs.join(" ")}`);
+      return;
+    }
+    try {
+      await pipInstall(pkgs, log);
+      out[key] = "installed";
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out[key] = "failed";
+    }
+  };
+
+  // hf CLI (model downloads). `huggingface_hub` provides the `hf` command.
+  await ensurePkg(
+    "hf",
+    () => which("hf"),
+    ["huggingface_hub"],
+    "Install the Hugging Face CLI (needed to download models)?"
+  );
+  // mlx-lm — runs the local chat + embedding model servers.
+  await ensurePkg("mlxLm", () => pyHasModule("mlx_lm"), ["mlx-lm"], "Install mlx-lm (runs the local model servers)?");
+  // The agent framework itself — WITHOUT this every agent turn crashes at import.
+  await ensurePkg(
+    "agentLibs",
+    async () => (await pyHasModule("smolagents")) && (await pyHasModule("openai")),
+    ["smolagents", "openai"],
+    "Install the agent framework (smolagents + openai) — required to run the agent?"
+  );
+  if (out.agentLibs === "skipped" || out.agentLibs === "failed") {
+    log(yellow("  ⚠ Without smolagents + openai the agent can't run — install them before asking a question."));
+  }
+  return out;
+}
+
+/**
+ * Start the MLX embeddings server (gonext_mlx_embed.py) DETACHED on `port` for `modelDir`,
+ * with its own pidfile/log. No-op + { ready:true } when one already answers (BC3). Waits up
+ * to waitMs for /v1/models to respond. Mirrors startChatModelServer.
+ */
+export async function startEmbedServer({ modelDir, port, waitMs = 60_000, log = () => {} }) {
+  const base = `http://127.0.0.1:${port}`;
+  if (await probeModelServer(base, { timeoutMs: 1500 })) {
+    return { started: false, ready: true, reason: "already-running" };
+  }
+  if (!(await pyHasModule("mlx_lm"))) {
+    return { started: false, ready: false, reason: "mlx-lm not installed (pip install mlx-lm)" };
+  }
+  await mkdir(DIR, { recursive: true });
+  const outLog = await open(EMBED_LOG_FILE, "a");
+  let pid;
+  try {
+    const child = spawn(
+      python3Bin(),
+      [EMBED_SCRIPT, "--model", modelDir, "--port", String(port), "--host", "127.0.0.1"],
+      { detached: true, stdio: ["ignore", outLog.fd, outLog.fd], env: process.env }
+    );
+    pid = child.pid;
+    await writeFile(EMBED_PID_FILE, String(pid ?? ""), "utf8");
+    child.unref();
+  } finally {
+    await outLog.close();
+  }
+  log(`  starting embeddings server (pid ${pid}) on port ${port} — waiting for it to load…`);
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    await sleep(2500);
+    if (await probeModelServer(base, { timeoutMs: 2000 })) return { started: true, ready: true, pid };
+  }
+  return { started: true, ready: false, pid, reason: `embeddings server still loading (see ${EMBED_LOG_FILE})` };
+}
+
+/**
+ * Ensure RAG is ready for the agent terminal (task #127): boto3 (cloud/S3 storage), the
+ * embedding model, and a running embeddings server. Uses the account's configured embed URL
+ * when it's local; otherwise the default local server on EMBED_PORT. BC3: an already-running
+ * embed server is left alone. Returns a status map.
+ */
+export async function ensureRag({ p, log, confirm }) {
+  const out = {};
+  log("");
+  log("  Checking RAG (agent knowledge base)…");
+  // boto3 — needed only for CLOUD (S3) RAG; local RAG stores on disk. Cheap + harmless, so
+  // offer it so cloud RAG works later without another setup pass.
+  if (!(await pyHasModule("boto3"))) {
+    if (await confirm("Install boto3 (needed only if you use cloud/S3 RAG)?", true)) {
+      try {
+        await pipInstall(["boto3"], log);
+        out.boto3 = "installed";
+      } catch (e) {
+        log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+        out.boto3 = "failed";
+      }
+    } else out.boto3 = "skipped";
+  } else out.boto3 = "present";
+
+  // Embed server URL: the account's configured local one, else the default local server.
+  const configuredEmbed = String(p?.ragEmbedUrl || "").trim();
+  const embedUrl =
+    configuredEmbed && isLocalModelUrl(configuredEmbed)
+      ? configuredEmbed
+      : `http://127.0.0.1:${EMBED_PORT}`;
+  const embedPort = parsePort(embedUrl) || EMBED_PORT;
+
+  if (await probeModelServer(embedUrl)) {
+    log(`  ✓ embeddings server already running at ${modelRoot(embedUrl)} — leaving it alone.`);
+    out.embed = "already-running";
+    return out;
+  }
+  if (configuredEmbed && !isLocalModelUrl(configuredEmbed)) {
+    log(`  ⚠ your embeddings server (${modelRoot(configuredEmbed)}) is remote and isn't`);
+    log("    answering. Start it there — this machine can't launch it.");
+    out.embed = "remote";
+    return out;
+  }
+  // Download the embed model if missing.
+  if (!(await modelDirReady(EMBED_DIR))) {
+    if (!(await confirm(`Download the RAG embedding model ${EMBED_REPO.split("/").pop()} (~4 GB)?`, true))) {
+      log("  Skipped. To do it yourself:");
+      log(`      hf download ${EMBED_REPO} --local-dir ${EMBED_DIR}`);
+      log(`      gonext-local-worker embed --model ${EMBED_DIR} --port ${embedPort}`);
+      out.embed = "skipped-model";
+      return out;
+    }
+    try {
+      await downloadModel({ repo: EMBED_REPO, dir: EMBED_DIR, log });
+    } catch (e) {
+      log(`  ⚠ ${e instanceof Error ? e.message : e}`);
+      out.embed = "download-failed";
+      return out;
+    }
+  }
+  if (!(await confirm(`Start the RAG embeddings server on port ${embedPort} now?`, true))) {
+    log(`  Skipped. Start it later: gonext-local-worker embed --model ${EMBED_DIR} --port ${embedPort}`);
+    out.embed = "not-started";
+    return out;
+  }
+  const r = await startEmbedServer({ modelDir: EMBED_DIR, port: embedPort, log });
+  if (r.ready) {
+    log(`  ✓ embeddings server is up on port ${embedPort}.`);
+    out.embed = "started";
+  } else if (r.started) {
+    log(`  … embeddings server is loading in the background on port ${embedPort}.`);
+    out.embed = "loading";
+  } else {
+    log(`  ⚠ ${r.reason}`);
+    out.embed = "start-failed";
+  }
+  return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gonext-local-worker",
-  "version": "1.0.343",
+  "version": "1.0.347",
   "description": "Polls GoNext cloud API for async local LLM jobs and runs them against Ollama/OpenAI-compatible servers on this Mac",
   "type": "module",
   "license": "MIT",