@tiens.nguyen/gu-cli 1.0.802 → 1.0.803

package/README.md

@@ -1,52 +1,150 @@
 # @tiens.nguyen/gu-cli
-Run:
-  GONEXT_API_BASE=... GONEXT_WORKER_KEY=... npx -y --package @tiens.nguyen/gu-cli gu-cli
 
-## Agent chat mode
+**gu** is a terminal coding agent for the folder you are in, plus the local worker that runs
+agent / OCR / PDF / embedding jobs on your machine (Ollama, MLX or any OpenAI-compatible server).
 
-Select **Agent** (instead of Chat) under the composer in the web app. Your
-free-form prompt is handed to a [smolagents](https://github.com/huggingface/smolagents)
-agent running on your local MLX/Ollama model. The agent can call tools (v1:
-`http_request`) and streams its thinking steps + final answer directly into the
-chat thread.
+```sh
+npm install -g @tiens.nguyen/gu-cli
+gu            # open the REPL in the current folder
+```
 
-Requires smolagents in the worker's Python environment:
+The package installs three commands: `gu` (the terminal REPL), `gu-cli` and `gu-local-worker`
+(the same worker CLI). Requires Node.js 18 or newer. The install runs `fix-path` for you; if
+npm's global bin folder is not on your PATH afterwards, run `gu-cli fix-path`.
+On Windows, PowerShell's built-in `gu` alias (Get-Unique) shadows this CLI — run
+`gu-cli fix-powershell` to drop it.
+
+## Quick start
+
+1. `gu login` — browser sign-in; writes `~/.gonext/worker.env`.
+   (Client Expert machines can instead paste a token from the Account page with `gu-cli token <token>`.)
+2. `gu doctor` — set up and check the models on this machine
+   (`gu doctor --client` installs only the agent dependencies when the models live on another machine).
+3. `gu` in a project folder, then type a request. Conversation history is saved per folder in
+   `~/.gonext/sessions` and resumed next time; `/new` starts a fresh one and archives the old one.
+
+A first install asks how this machine runs (hosted client / MLX host / private). Pass
+`--license <pro token>` to choose a pro license up front; without it a first install is private,
+meaning the whole stack runs on this machine.
+
+## The `gu` REPL
 
-```sh
-pip install smolagents certifi
 ```
+gu [-v|--verbose] [--log] [--license <pro token>]
+```
+
+- `-v, --verbose` shows RAG index-file activity in the bottom bar.
+- `--log` logs this run in detail to `~/.gonext/worker.log`. Without it only starts, stops and errors are logged.
+- Ctrl-C stops following a turn.
+
+### Three models, three commands
+
+| Command | Model it switches |
+| --- | --- |
+| `/model` | the CODING model (the one that writes code), for this session |
+| `/agent-model` | the AGENT model (the one that talks) — saved on this machine |
+| `/embed-model` | the RAG EMBEDDING model (nomic-embed-text / qwen3-embedding) and its server; re-indexes what is already indexed; supports a remote URL + API key |
 
-- `certifi` supplies a trusted CA bundle so the agent's `http_request` tool can
-  verify HTTPS certificates on macOS (where Python's default bundle may be
-  missing). The worker falls back to the system bundle if certifi is absent.
-- Agent mode is blocked for cloud models (the API returns 400). Select a local
-  MLX or Ollama model first.
-- Tool steps appear in the collapsible reasoning (`<think>`) area; the final
-  answer is the message body — no new UI needed.
+`/agent-model` saves the model's server URL (`agentModelUrl`) together with its name, so picking a
+model from another provider (for example OpenAI) can no longer leave chat pointed at the old
+server. After picking, `gu doctor` shows the URL and model that are actually in use.
 
-The agent script is `gonext_agent_chat.py` (reads `{messages, agentBaseURL,
-agentApiKey, agentModelId, tools, maxSteps}` on stdin; emits NDJSON
-`{"type":"step"/"final","text":"..."}` lines on stdout).
+### Slash commands
 
-## API Check / HTTP probe (Tools & Agents modes)
+| Command | What it does |
+| --- | --- |
+| `/model`, `/agent-model`, `/embed-model` | switch models (see above) |
+| `/context-window [tokens\|auto]` | tell gu how big the coding model's context is (hosted models cannot be probed) |
+| `/doctor` | check every configured model answers, especially the embedder |
+| `/tokens` | break down the last prompt sent to the coding model — how much of it was RAG |
+| `/prices [update]` | price and cache tables, and what the last turn and this session cost |
+| `/rag` | where this folder's RAG knowledge base lives: local, cloud, or both |
+| `/s3 [test]` | set up your own S3 bucket (RAG index, generated PDFs/downloads) and check the AWS keys |
+| `/proxy [show\|set\|on\|off\|clear\|test]` | route model calls through an HTTP proxy (local calls always go direct) |
+| `/test-auto` | toggle auto-test (verify and fix until it passes) for this folder |
+| `/undo [runId]` | put back the files the last stopped turn changed, from its backups (asks first) |
+| `/server` | pick a deployment server (host/user) for this session |
+| `/host-mode` | undo client mode — run agent turns on this machine again |
+| `/save-settings [name\|path]`, `/load-settings [name\|path]` | move providers, models and key names (no secrets) to another machine |
+| `/save-preset [name]`, `/open-presets [name]`, `/use-presets [name]` | presets: your whole setup, keys included, to copy to another computer, edit, and apply (backs up first) |
+| `/hooks [list\|approve\|unapprove]` | commands gu runs on onStart, onAsk, onToolDone, onTurnEnd |
+| `/mcp [list\|tools\|add\|remove\|enable\|disable\|approve\|allow\|disallow\|reconnect]` | manage MCP servers and which of their tools run without asking |
+| `/switch-skill [claude\|gu]` | use Claude Code's (`.claude`) or gu's own (`.gonext`) skills, MCP servers and hooks for this folder |
+| `/clear-logs` | show what logs, RAG indexes and old API versions take on disk, then ask what to clear |
+| `/new` | start a new conversation in this folder (the old one is archived) |
+| `/help`, `/exit` (`/quit`) | list commands / quit |
 
-The worker can run Postman-style HTTP probes queued from the web app
-("Tools" = `tool_only`, "Agents" = `agentic`). The worker always performs the
-actual HTTP request itself (Node `fetch`, so TLS works), measures the
-status/latency/headers/body, and classifies it (2xx/3xx/4xx/5xx/timeout/
-network_error).
+Each skill in `~/.gonext/skills/<name>/SKILL.md` (and the folder's `.gonext/skills`) is also a
+slash command of its own. Run `/help` in the REPL for the list your version offers.
 
-- **Tools (`tool_only`)** — no extra setup. The selected local model writes a
-  one-line health summary of the measured result.
-- **Agents (`agentic`)** — a smolagents agent (running on the selected local
-  model) produces the summary. Requires `pip install smolagents`.
+## Shell commands
+
+```
+gu status                      worker + a table of the running model servers
+gu start | stop | restart      run the polling daemon in the background (stop --models: model servers too)
+gu logs [--lines N] [-f]       tail the daemon log; gu logs <port|pid|chat|embed> [-f] tails a model server's log
+gu doctor [--client]           set up models here
+gu rag                         test the embedder end-to-end and list knowledge bases
+gu rag plan [path]             is RAG worth it here? files / chars / chunks -> estimated index time
+gu rag --test                  can this machine embed and retrieve?
+gu api <start|stop|restart|status|upgrade>   the local API (Local / Client Expert only)
+gu workspace revert [runId]    undo an agent run's file edits from its backups
+gu test-proxy                  can this machine route model calls through a proxy?
+gu mongo migrate-from-docker   macOS: move a Docker MongoDB to native (Homebrew)
+gu clear [--scratch|--keep-history] [--yes]   back to a fresh machine (asks first)
+gu fix-path | fix-powershell   repair PATH / drop PowerShell's `gu` alias
+```
 
-  The agent talks to your local MLX OpenAI-compatible server (no cloud calls).
-  The agent only summarizes; the worker's measurement stays the source of truth,
-  so if smolagents or the model is unavailable the probe still returns the
-  measured result with a note.
+`gu-cli` accepts the same commands, plus `login [--api-base <url>]`, `set <workerKey> [--api-base <url>]`,
+`token [<token>]`, `ws-ping-test` and `simulate-chat [text...]`.
+`gu api restart` runs the installed version; an upgrade changes the files, not a process that is already serving.
 
-### Env vars
+## Files and settings
+
+| Path | Contents |
+| --- | --- |
+| `~/.gonext/worker.env` | sign-in: worker key and API base |
+| `~/.gonext/sessions/` | per-folder conversation history (`archive/` holds old conversations) |
+| `~/.gonext/worker.log` | worker log (detailed with `--log`) |
+| `~/.gonext/local-api.log` | the local API's log |
+| `~/.gonext/mcp.json` | MCP servers and their allow rules |
+| `~/.gonext/skills/`, `.gonext/skills` | skills (global / this folder) |
+
+## Worker modes
+
+The background worker polls the API for jobs queued from the web app and runs them on this machine.
+
+### Agent chat
+
+Choosing **Agent** under the composer in the web app hands your prompt to a
+[smolagents](https://github.com/huggingface/smolagents) agent running on your local model. It
+needs `pip install smolagents certifi` in the worker's Python environment (`certifi` gives
+HTTPS a trusted CA bundle on macOS). Agent mode is blocked for cloud models; pick a local
+MLX or Ollama model first. The script is `gonext_agent_chat.py`.
+
+### API check / HTTP probe
+
+- **Tools (`tool_only`)**: the worker runs the HTTP request itself, measures status, latency, headers and
+  body, classifies it (2xx/3xx/4xx/5xx/timeout/network_error), and the local model writes a one-line summary.
+- **Agents (`agentic`)**: a smolagents agent writes the summary; the measurement stays the source of truth.
+
+### Environment variables
+
+| Variable | Meaning |
+| --- | --- |
+| `GONEXT_API_BASE`, `GONEXT_WORKER_KEY` | API URL and worker key (normally from `~/.gonext/worker.env`) |
+| `GONEXT_PROBE_PYTHON` | Python for smolagents scripts (default: `GONEXT_MLX_LM_PYTHON` or `python3`) |
+| `GONEXT_MLX_LM_PYTHON` | Python for the MLX LM native probe (default `python3`) |
+| `GONEXT_OCR_MODEL_PATH` | local GLM-OCR-bf16 directory (default `~/mlx-models/GLM-OCR-bf16`) |
+| `GONEXT_OCR_DEBUG=1` | print raw OCR stdout/stderr snippets |
+| `GONEXT_SIMULATE_TEXT` | default reply body for `simulate-chat` |
+
+## Development
+
+```sh
+npm test            # python unittest + node --test
+npm run preflight   # checks before a release
+npm run publish:org # npm publish --access public
+```
 
-  GONEXT_PROBE_PYTHON   Python executable for smolagents scripts
-                        (default: GONEXT_MLX_LM_PYTHON or python3)
+Source and issues: https://github.com/tiennsloit/gu

package/gu-repl.mjs

@@ -111,6 +111,7 @@ import {
   bulletKind,
   workspaceScopeWarning,
   isLocalApiBase,
+  apiVersionSuffix,
   modeRow,
   nothingToAnswerWith,
   NO_MODEL_LINES,
@@ -8583,6 +8584,18 @@ async function chooseAgentModel() {
     console.log(dim(`   already using ${current} — nothing changed.\n`));
     return;
   }
+  if (rows[idx].missing) {
+    // The one row agentModelRows injects WITHOUT the host listing it (#108): picking it re-affirms
+    // a name the server no longer has, which fails later as a confused agent, not here. The user
+    // can still insist — it may be a list outage — but the consequence is said BEFORE the write.
+    console.log(GUTTER + yellow(`${chosen} is not on ${listHost || "the server"} any more — it may have been removed there.`));
+    console.log(GUTTER + yellow("As the agent model it would fail on your next question, not now."));
+    const go = await pickFromList([`use it anyway`, `pick something else`], 1);
+    if (go !== 0) {
+      console.log(dim("   (kept)\n"));
+      return;
+    }
+  }
   if (rows[idx].embedder) {
     // Not a refusal — it is their box and their call — but the consequence has to be said BEFORE
     // the write, because an embedder as the chat model does not fail here. It fails as an agent
@@ -8597,9 +8610,17 @@ async function chooseAgentModel() {
   }
 
   const md = await import("./model-doctor.mjs");
-  // BOTH FIELDS. With a direct agentModelUrl set — the Client Expert shape — the API reads
-  // agentModelName; agentModel is the legacy mirror. Writing one leaves the two disagreeing.
+  const ps2 = await import("./coding-provider-setup.mjs");
+  // THREE FIELDS — NAME **AND** SERVER (#108). This picker once wrote only agentModelName +
+  // agentModel, leaving agentModelUrl wherever it was: choosing an OpenAI model while the stored
+  // URL still said the shared Ollama box meant every turn went to that (dead) host and died as an
+  // nginx 502, with the valid OpenAI key never touched — the key is chosen by MATCHING the URL.
+  // The URL saved is the one this very list came from (agentListSource reads settings.agentModelUrl),
+  // normalised to the /v1 root so it matches the provider row app.ts resolves the key against —
+  // the same shape the add-server flow's saveAgentModel stores. Name and server can no longer diverge.
+  const agentUrl = ps2.ensureV1Root(String(settings?.agentModelUrl ?? source.url ?? ""));
   const saved = await md.saveWorkerSettings(apiBase, workerKey, {
+    agentModelUrl: agentUrl,
     agentModelName: chosen,
     agentModel: chosen,
   });
@@ -8611,7 +8632,7 @@ async function chooseAgentModel() {
     console.log(GUTTER + dim("`gu api restart` to pick up the current version.\n"));
     return;
   }
-  console.log(accent(` ✓ agent model → ${chosen}`));
+  console.log(accent(` ✓ agent model → ${chosen}`) + (listHost ? dim(`  · ${listHost}`) : ""));
   console.log(dim("   takes effect on your next question.\n"));
 }
 
@@ -12795,8 +12816,21 @@ async function main() {
             agentUrl: p.agentBaseURL,
             servers: await (await import("./model-doctor.mjs")).discoverModelServers(),
           });
+      // Task #18: in client expert / private mode the API is a SEPARATE build running on this
+      // machine — `gu-cli api upgrade` moves it without touching the CLI, so `v<cli>` alone
+      // does not say what is answering. Ask its /api/health for the running version and show
+      // both. Best-effort and only in that mode: a client machine's API is the hosted service,
+      // whose version the user cannot act on, and an unreachable local API must not hold up or
+      // break the banner.
+      let apiBannerVersion = "";
+      if (isClientExpert()) {
+        try {
+          const ceApi = await import("./client-expert-api.mjs");
+          apiBannerVersion = String((await ceApi.probeLocalApi()).body?.version ?? "").trim();
+        } catch { /* absent beats guessed — no suffix */ }
+      }
       const statusRows = [
-        bold(accent("GU AGENT")) + dim(`  v${REPL_VERSION}`),
+        bold(accent("GU AGENT")) + dim(`  v${REPL_VERSION}${apiVersionSuffix(apiBannerVersion)}`),
         // Task #134: a client machine OVERRIDES the account's agent model locally (the
         // account value points at the model host's own server). Show what will actually be
         // used, not a value this machine can't reach.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.802",
+  "version": "1.0.803",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",

package/terminal-layout.mjs

@@ -2320,6 +2320,17 @@ export function isLocalApiBase(apiBase) {
  * entire distinction — go unmentioned. Reported live on a fully set-up Ubuntu box that said
  * plain "client".
  */
+/**
+ * The banner's API-version suffix for client expert / private mode (task #18). There the API
+ * runs on THIS machine and its build can differ from the CLI's — an `api upgrade` without a gu
+ * update is the common way — so the banner shows both, next to `v<cli>`. An empty version means
+ * the running build did not report one (or is unreachable), and absent beats guessed: no suffix.
+ */
+export function apiVersionSuffix(version) {
+  const v = String(version ?? "").trim();
+  return v ? ` · api v${v}` : "";
+}
+
 export function modeRow({ clientExpert, clientMode, modelUrls = [], coderWhere }) {
   if (clientExpert) {
     // "models remote" WAS A CONSTANT (task #333): a box running its own Ollama on 127.0.0.1 —