vexp-cli 3.3.9 → 3.4.0

package/dist/devmind.js

@@ -0,0 +1,269 @@
+// DevMind (vexp's optional local LLM) as the CLI tells it.
+//
+// Since 3.3.9 DevMind runs only on a GPU. Every frontend rendered that
+// policy as a fault: doctor counted a WARN with "restarting will NOT change
+// this - fix the cause above", the REPL said "(active)" from the config
+// alone, and the sidebar showed a warning banner. A user spent an hour
+// trying to fix a machine that had nothing wrong with it (field report,
+// 2026-11-08). The engine now names the cause (index_status.llm_off_cause,
+// `setup-llm --status` "DevMind:" and "Off cause:" lines); this module reads
+// it and words it, so doctor, the REPL and the report agree.
+//
+// The constants and the kind strings are the engine's
+// (packages/vexp-core/src/prose_compress/llm/gate.rs). Lockstep with that
+// file, with packages/vexp-vscode/src/ui/llm-advice.ts and with
+// packages/vexp-mcp/src/tools/index-status.ts
+// (test/devmind.lockstep.test.ts reads gate.rs).
+/** The one reassurance sentence (gate.rs DEVMIND_OPTIONAL). */
+export const DEVMIND_OPTIONAL = "DevMind is optional: everything else in vexp works the same without it.";
+/** The requirement, said before anyone downloads (gate.rs DEVMIND_REQUIREMENT). */
+export const DEVMIND_REQUIREMENT = "DevMind needs an NVIDIA GPU (Linux, Windows) or an Apple Silicon Mac; without one it stays off and vexp works the same.";
+/** gate.rs `kind::ALL`, in the order the gate checks them. */
+export const DEVMIND_OFF_KINDS = [
+    "no_gpu",
+    "container_no_gpu",
+    "intel_mac",
+    "prefer_gpu_off",
+    "gpu_failed_before",
+    "gpu_too_old",
+    "gpu_too_small",
+    "cuda_plugin_missing",
+    "cuda_plugin_broken",
+    "gpu_init_failed",
+];
+/** gate.rs `kind_is_fixable`: the user can change something here. Frontends read `llm_off_fixable`; this is for the lockstep test. */
+export const DEVMIND_FIXABLE_KINDS = ["prefer_gpu_off", "gpu_failed_before", "cuda_plugin_missing", "cuda_plugin_broken", "gpu_init_failed"];
+/**
+ * Is the rule compressor this daemon runs DevMind's policy, not a fault?
+ * A daemon from 3.4.0 always sends `llm_off_cause`: a kind string, or null
+ * for every fault (an endpoint that does not answer, a model that failed to
+ * load, the startup sync). A daemon without the field (3.3.9) said "DevMind
+ * needs a GPU and none is usable on this machine" for every policy cause,
+ * and nothing else it said contains "needs a GPU": that sentence is the
+ * policy, with no kind and nothing the user is told to fix.
+ */
+export function devmindOff(st) {
+    if (!st || st.compressor === "llm")
+        return null;
+    const raw = typeof st.llm_inactive_reason === "string" ? st.llm_inactive_reason : "";
+    const reason = raw.trim().replace(/\.+$/, "");
+    if ("llm_off_cause" in st) {
+        if (typeof st.llm_off_cause !== "string" || st.llm_off_cause === "")
+            return null;
+        return { kind: st.llm_off_cause, fixable: st.llm_off_fixable === true, reason: reason || "DevMind needs a GPU" };
+    }
+    if (/needs a GPU/i.test(reason))
+        return { kind: null, fixable: false, reason };
+    return null;
+}
+/**
+ * The note doctor prints for DevMind off by policy, at INFO: nothing is
+ * broken, so it counts as no warning and brings no restart tip. Word for
+ * word the extension Doctor's line (packages/vexp-vscode doctor-lines.ts).
+ * A fixable cause adds the restart the fix needs: the daemon decides at its
+ * start.
+ */
+export function devmindOffNote(off) {
+    return (`DevMind (optional local LLM) is off on this machine: ${off.reason}. ${DEVMIND_OPTIONAL} ` +
+        `'vexp setup-llm --disable' hides this note; 'vexp setup-llm --uninstall' also frees the disk space.` +
+        (off.fixable ? " After the fix, restart the daemon." : ""));
+}
+/** An `[llm] endpoint` that did not answer when the daemon started (gate.rs endpoint_unreachable_reason). */
+export function isEndpointUnreachable(reason) {
+    return reason !== undefined && /^endpoint \S+ unreachable \(/.test(reason);
+}
+const statusField = (stdout, label) => {
+    const m = new RegExp(`^[ \\t]*${label}:[ \\t]*(.*?)[ \\t]*$`, "m").exec(stdout);
+    return m ? m[1] : undefined;
+};
+export function parseSetupLlmStatus(stdout) {
+    const build = statusField(stdout, "Build");
+    const devmindLine = statusField(stdout, "DevMind");
+    let devmind = null;
+    if (devmindLine !== undefined) {
+        const runs = /^runs here \((.*)\)$/.exec(devmindLine);
+        const off = /^off here - (.*)$/.exec(devmindLine);
+        if (runs)
+            devmind = { runs: true, label: runs[1] };
+        else if (off)
+            devmind = { runs: false, reason: off[1].replace(/\.+$/, "") };
+    }
+    const daemonLine = statusField(stdout, "Daemon now");
+    let daemon = null;
+    if (daemonLine !== undefined) {
+        if (/^v\S* running the model/.test(daemonLine))
+            daemon = { state: "model" };
+        else if (/^no daemon answered/.test(daemonLine))
+            daemon = { state: "none" };
+        else if (/^v\S* using the /.test(daemonLine)) {
+            // The daemon's reason is the line right under it, when it gave one.
+            const lines = stdout.split(/\r?\n/);
+            const at = lines.findIndex((l) => /^[ \t]*Daemon now:/.test(l));
+            const why = /^[ \t]*reason:[ \t]*(.*?)[ \t]*$/.exec(lines[at + 1] ?? "");
+            daemon = { state: "rule", reason: why?.[1] || undefined };
+        }
+    }
+    const endpoint = statusField(stdout, "Endpoint");
+    return {
+        build: build === undefined ? null : /vanilla/i.test(build) ? "vanilla" : "llm",
+        enabled: /^true$/i.test(statusField(stdout, "Enabled") ?? ""),
+        installed: /^yes\b/i.test(statusField(stdout, "Installed") ?? ""),
+        operational: /^true$/i.test(statusField(stdout, "Operational") ?? ""),
+        model: statusField(stdout, "Model") ?? "",
+        devmind,
+        offCause: statusField(stdout, "Off cause") || null,
+        preferGpuOff: /^false$/i.test(statusField(stdout, "prefer_gpu") ?? ""),
+        endpoint: endpoint ? endpoint.replace(/\s*\(configured\)\s*$/, "") : null,
+        daemon,
+    };
+}
+export const LLM_MENU = [
+    { key: "1", label: "Install / Reinstall", note: "(~3.5 GB model; needs an NVIDIA GPU or Apple Silicon)", flag: "--install", aliases: ["install", "reinstall"] },
+    { key: "2", label: "Start", note: "(enable without re-downloading)", flag: "--enable", aliases: ["start", "enable"] },
+    { key: "3", label: "Check for updates", note: "(no download if up to date)", flag: "--check-updates", aliases: ["update", "updates", "check-updates"] },
+    { key: "4", label: "Status", note: "(config, hardware, whether DevMind runs here)", flag: "--status", aliases: ["status"] },
+    { key: "5", label: "Disable", note: "(keep files, stop using LLM)", flag: "--disable", aliases: ["disable", "stop"] },
+    { key: "6", label: "Remove files", note: "(delete the model and CUDA files vexp downloaded)", flag: "--uninstall", aliases: ["uninstall", "remove"] },
+];
+/** The entry a typed answer at the llm> prompt picks: its key or one of its words. */
+export function llmMenuChoice(input) {
+    const c = input.trim().toLowerCase();
+    return LLM_MENU.find((e) => e.key === c || e.aliases.includes(c));
+}
+/** What to type from the main menu to reach the entry for `flag`: Setup & Config (1), setup-llm (6), then its key. */
+export function llmMenuPath(flag) {
+    const e = LLM_MENU.find((m) => m.flag === flag);
+    if (!e)
+        throw new Error(`no llm> entry for ${flag}`);
+    return `1 > 6 > ${e.key}`;
+}
+/** A banner line as the REPL prints it. */
+export function bannerText(l) {
+    return `${l.mark === "on" ? "  ● " : l.mark === "off" ? "  ○ " : "    → "}${l.text}`;
+}
+/**
+ * The REPL banner's LLM lines. "(active)" only when the workspace daemon
+ * runs the model: "Operational: true" is the config's truth, and it was
+ * shown as active on every machine where DevMind stays off (review,
+ * 2026-11-08). Off here is said calmly, with no download offered.
+ *
+ * The local gate speaks only for the local model. An `[llm] endpoint`
+ * serves without it, and a daemon that runs a model is the answer over
+ * both: "(off here: needs a GPU)" and "'1 > 6 > 5' turns it off" were told
+ * to an NPU user whose endpoint was serving. And a CUDA plugin that is
+ * missing (on every NVIDIA machine before the first setup) or does not load
+ * is what the install fetches: "needs a GPU" was told to a fresh RTX user,
+ * with a download hint that left out the model (review, 2026-11-08).
+ * Lockstep with the sidebar's engineOff / pluginMissing (vexp-vscode
+ * sidebar-panel.ts).
+ */
+export function llmBannerLines(s) {
+    const name = s.model || "local";
+    if (s.build === "vanilla") {
+        const out = [{ tone: "dim", mark: "off", text: "LLM: not in this build (everything else works the same, with the rule compressor)" }];
+        if (s.enabled) {
+            out.push({ tone: "dim", mark: "hint", text: `your config still switches it on, left from a build that had one: type '${llmMenuPath("--disable")}', or \`vexp setup-llm --disable\`` });
+        }
+        return out;
+    }
+    if (s.operational && s.daemon?.state === "model") {
+        return [{ tone: "green", mark: "on", text: s.endpoint ? `LLM: active, through the [llm] endpoint ${s.endpoint}` : `LLM: ${name} (active)` }];
+    }
+    // A 3.3.9 engine has no DevMind line: its daemon's one policy sentence.
+    const offReason = s.endpoint
+        ? null
+        : s.devmind && !s.devmind.runs
+            ? s.devmind.reason
+            : s.devmind === null && s.daemon?.state === "rule" && /needs a GPU/i.test(s.daemon.reason ?? "")
+                ? s.daemon.reason
+                : null;
+    if (offReason !== null) {
+        if (s.offCause === "cuda_plugin_missing" || s.offCause === "cuda_plugin_broken") {
+            if (!s.installed && !s.enabled) {
+                return [
+                    { tone: "dim", mark: "off", text: "LLM: not installed" },
+                    { tone: "dim", mark: "hint", text: `type '${llmMenuPath("--install")}' to download (~3.5 GB model + ~1 GB CUDA plugin), or \`vexp setup-llm --install\`` },
+                ];
+            }
+            const missing = s.offCause === "cuda_plugin_missing";
+            return [
+                { tone: "yellow", mark: "off", text: `LLM: ${name} (${missing ? "CUDA plugin not installed" : "CUDA plugin does not load"})` },
+                {
+                    tone: "dim",
+                    mark: "hint",
+                    text: missing
+                        ? `type '${llmMenuPath("--install")}' to download vexp's CUDA plugin, or \`vexp setup-llm --install\``
+                        : `type '${llmMenuPath("--install")}' to fetch the CUDA runtime it needs (and the plugin again), or \`vexp setup-llm --install\``,
+                },
+            ];
+        }
+        if (!s.enabled && !s.installed) {
+            return [
+                { tone: "dim", mark: "off", text: "LLM: off here (needs a GPU)" },
+                { tone: "dim", mark: "hint", text: DEVMIND_REQUIREMENT },
+            ];
+        }
+        const out = [{ tone: "dim", mark: "off", text: `LLM: ${name} (off here: needs a GPU)` }];
+        out.push({ tone: "dim", mark: "hint", text: `${DEVMIND_OPTIONAL} Why: '${llmMenuPath("--status")}'` });
+        out.push({
+            tone: "dim",
+            mark: "hint",
+            text: s.enabled
+                ? `'${llmMenuPath("--disable")}' turns it off; '${llmMenuPath("--uninstall")}' also frees the disk space`
+                : `'${llmMenuPath("--uninstall")}' frees the disk space (\`vexp setup-llm --uninstall\`)`,
+        });
+        return out;
+    }
+    if (s.operational) {
+        if (s.daemon?.state === "rule") {
+            const out = [{ tone: "yellow", mark: "off", text: `LLM: ${name} (enabled, but this daemon runs the rule compressor)` }];
+            if (s.daemon.reason)
+                out.push({ tone: "dim", mark: "hint", text: `reason: ${s.daemon.reason}` });
+            out.push({ tone: "dim", mark: "hint", text: "`vexp doctor` says what to do" });
+            return out;
+        }
+        if (s.daemon?.state === "none")
+            return [{ tone: "green", mark: "on", text: `LLM: ${name} (enabled: the daemon loads it when it starts)` }];
+        return [{ tone: "green", mark: "on", text: `LLM: ${name} (enabled)` }];
+    }
+    if (s.installed) {
+        return [
+            { tone: "yellow", mark: "off", text: "LLM: installed but not active" },
+            { tone: "dim", mark: "hint", text: `type '${llmMenuPath("--enable")}' to start it, or \`vexp setup-llm --enable\`` },
+        ];
+    }
+    return [
+        { tone: "dim", mark: "off", text: "LLM: not installed" },
+        { tone: "dim", mark: "hint", text: `type '${llmMenuPath("--install")}' to download (~3.5 GB), or \`vexp setup-llm --install\`` },
+    ];
+}
+// The `setup-llm --status` lines a doctor report carries. An allow-list:
+// the rest of the output (library inventory, file listings) is noise in a
+// report, and nothing else can carry a secret by accident. The engine
+// prints the endpoint's origin only and never the api key; the Endpoint
+// line is stripped of userinfo and query here as well, and the report masks
+// secret shapes on top.
+const REPORT_LABELS = /^[ \t]*(Build|Enabled|Model|Installed|Operational|DevMind|Off cause|prefer_gpu|Endpoint|Model file|DevMind files|Accelerator|Plugin|GPU|GPU offload|GPU in use|Daemon now):/;
+const REPORT_FOLLOWERS = new Set(["GPU offload", "GPU in use", "Daemon now"]);
+/** The lines of `setup-llm --status` that the doctor report's LLM section quotes. */
+export function llmStatusReportLines(stdout) {
+    const out = [];
+    let follows = false;
+    for (const raw of stdout.split(/\r?\n/)) {
+        const line = raw.replace(/\s+$/, "");
+        const m = REPORT_LABELS.exec(line);
+        if (m) {
+            const text = m[1] === "Endpoint" ? line.replace(/\/\/[^/@\s]*@/, "//").replace(/[?#]\S*/, "") : line;
+            out.push(text);
+            follows = REPORT_FOLLOWERS.has(m[1]);
+            continue;
+        }
+        // The indented reason/verdict/marker lines under the three lines that have them.
+        if (follows && /^[ \t]{6,}(reason|verdict|marker|retry|note|spent):/.test(line)) {
+            out.push(line);
+            continue;
+        }
+        follows = false;
+    }
+    return out;
+}