@xingjisoft/neutrino 0.4.0 → 0.5.0

package/dist/bin.js

@@ -3,7 +3,12 @@ import process from "node:process";
 import { App } from "./app.js";
 import { loadConfig } from "./config.js";
 import { installCrashGuard } from "./terminal/restore.js";
-import { startWebServer } from "./web/server.js";
+import { webUrls } from "./web/server.js";
+import { runningBackground, startBackgroundService, stopBackgroundService, } from "./background.js";
+import { runWebService } from "./web/service.js";
+import { openInBrowser } from "./browser.js";
+import { PRO_MODEL_FILE, PRO_MODELS_URL, syncProModels } from "./pro/config.js";
+import { checkForUpdate } from "./update.js";
 const DEFAULT_WEB_PORT = 8765;
 /** Binding here makes the UI reachable from every interface. */
 const WILDCARD_HOST = "0.0.0.0";
@@ -35,6 +40,11 @@ Usage:
   neutrino                     Start the terminal UI (with the web UI).
   neutrino --lan               Start both, reachable from other devices.
   neutrino web [--port <port>] Start only the web UI (serves saved history).
+  neutrino background start    Run the web UI in the background; conversations
+                               started there survive the terminal/CLI exiting.
+  neutrino background stop     Stop the background service.
+  neutrino background status   Show whether it is running and where.
+  neutrino background open     Open its console in the default browser.
 
 Options:
   -p, --port <port>   Web UI port. Default: ${DEFAULT_WEB_PORT}
@@ -43,12 +53,16 @@ Options:
                       devices on your LAN or VPN.
       --no-web        Do not start the web UI with the terminal UI.
       --no-auth       Serve without password login.
+      --no-tray       Do not show the Windows notification-area icon of the
+                      background service.
       --web-port <n>  Deprecated alias for --port while the TUI runs.
   -h, --help          Show this help.
 
 Environment:
   NEUTRINO_WEB_PORT   Same as --port in either mode.
   NEUTRINO_WEB_HOST   Same as --host.
+  NEUTRINO_NO_TRAY    Set to 1 to keep the background service out of the
+                      Windows notification area.
 
 The web UI starts by default alongside the terminal UI on loopback. Turn it
 off for one run with --no-web, or permanently in Settings → Web console. It can
@@ -58,6 +72,13 @@ on, and off, in the browser's Settings → Web access; the choice is saved for t
 next launch, while --host/--lan win for the current one. Log in with the
 permanent password (default: 114514). Change it in Settings. --no-auth disables
 password login.
+
+Background residency is off by default. Turn it on in Settings → Background
+(shared by the regular and Pro workspaces). Switching it takes effect immediately,
+including for browser tasks already running. The background service keeps
+running when this terminal closes, so tasks started
+from the browser are not interrupted. Stop it with 'neutrino background stop',
+the tray icon, or Settings → Web console in the terminal.
 `);
 }
 /** Read the value that follows a flag, so `--host` alone is an error. */
@@ -68,13 +89,28 @@ function requireValue(argv, index, flag) {
     }
     return value;
 }
+const BACKGROUND_ACTIONS = new Set(["run", "start", "stop", "status", "open"]);
 function parseArgs(argv) {
-    const options = { mode: "tui", port: null, lan: false, noWeb: false, noAuth: false };
+    const options = {
+        mode: "tui", backgroundAction: null, port: null, lan: false, noWeb: false, noAuth: false, noTray: false,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "web") {
             options.mode = "web";
         }
+        else if (arg === "background") {
+            options.mode = "background";
+            options.backgroundAction = "status";
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                if (!BACKGROUND_ACTIONS.has(next)) {
+                    throw new Error(`unknown background action "${next}"`);
+                }
+                options.backgroundAction = next;
+                i += 1;
+            }
+        }
         else if (arg === "--port" || arg === "-p") {
             options.port = parsePort(argv[++i]);
         }
@@ -102,6 +138,25 @@ function parseArgs(argv) {
         else if (arg === "--no-auth") {
             options.noAuth = true;
         }
+        else if (arg === "--no-tray") {
+            options.noTray = true;
+        }
+        else if (arg === "--start") {
+            options.mode = "background";
+            options.backgroundAction = "start";
+        }
+        else if (arg === "--stop") {
+            options.mode = "background";
+            options.backgroundAction = "stop";
+        }
+        else if (arg === "--status") {
+            options.mode = "background";
+            options.backgroundAction = "status";
+        }
+        else if (arg === "--open") {
+            options.mode = "background";
+            options.backgroundAction = "open";
+        }
         else if (arg === "--help" || arg === "-h") {
             printHelp();
             process.exit(0);
@@ -116,31 +171,64 @@ function parseArgs(argv) {
     if (options.noWeb && options.mode === "web") {
         throw new Error("--no-web cannot be used with the 'web' command");
     }
+    if (options.noWeb && options.mode === "background") {
+        throw new Error("--no-web cannot be used with the 'background' command");
+    }
     if (options.noWeb && (options.port !== null || options.host !== undefined || options.lan)) {
         throw new Error("use either --no-web or web UI options, not both");
     }
     return options;
 }
-/** Print every address a client can open, plus what it takes to open one. */
-function reportAccess(handle) {
-    process.stdout.write(`Neutrino web UI listening on ${handle.host}:${handle.port}\n`);
-    const multiple = handle.urls.length > 1;
+/** Print where an already-running detached console can be opened. */
+function reportBackgroundAccess(status, started) {
+    process.stdout.write(`Neutrino ${status.resident ? "background " : ""}Web console ${started ? "started" : "already running"} `
+        + `(pid ${status.pid}) on ${status.host}:${status.port}\n`);
+    const { urls } = webUrls(status.host, status.port);
+    const multiple = urls.length > 1;
     process.stdout.write(multiple ? "Open the address that matches your device:\n" : "Open:\n");
-    for (const url of handle.urls)
+    for (const url of urls)
         process.stdout.write(`  ${url}\n`);
-    const wildcard = handle.host === "0.0.0.0" || handle.host === "::";
-    if (wildcard && !handle.urls.some((url) => !url.includes("//127.0.0.1:"))) {
-        // Bound to every interface, yet nothing outside this machine is reachable:
-        // usually Wi-Fi is off, the VPN is down, or the only adapters left are
-        // virtual ones we deliberately hide.
+    if ((status.host === "0.0.0.0" || status.host === "::")
+        && !urls.some((url) => !url.includes("//127.0.0.1:"))) {
         process.stdout.write("note: no reachable network address found, so only this machine can connect.\n");
     }
-    if (handle.authRequired) {
-        process.stdout.write("Sign in with your permanent Web password (default: 114514). Change it in Settings.\n");
+    if (status.auth_required) {
+        process.stdout.write("Sign in with your permanent Web password (default: 114514).\n");
     }
     else {
         process.stdout.write("Password login is disabled.\n");
     }
+    if (status.resident) {
+        process.stdout.write("It keeps running after this terminal exits. Stop it with 'neutrino background stop'"
+            + (process.platform === "win32" ? " or the tray icon" : "") + ".\n");
+    }
+}
+/**
+ * The detached service itself (`neutrino background run`).
+ *
+ * It owns the Web console and every browser conversation for as long as the
+ * machine's user session keeps it alive. The token written into the status
+ * file is the only way another local process can ask it to stop.
+ */
+async function runBackgroundService(host, auth) {
+    await runWebService({ port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT, host, auth, tray: !options.noTray });
+}
+function printBackgroundStatus() {
+    const status = runningBackground();
+    if (!status) {
+        process.stdout.write("No background service is running.\n");
+        process.stdout.write("Start one with 'neutrino background start'.\n");
+        return;
+    }
+    process.stdout.write(`Neutrino background service: running (pid ${status.pid})\n`);
+    process.stdout.write(`Residency: ${status.resident ? "on" : "off (follows the terminal)"}\n`);
+    process.stdout.write(`Started: ${status.started_at}\n`);
+    process.stdout.write(`Address: ${status.url}\n`);
+    const { urls } = webUrls(status.host, status.port);
+    for (const url of urls) {
+        if (url.replace(/\/$/, "") !== status.url)
+            process.stdout.write(`Also: ${url}\n`);
+    }
 }
 let options;
 try {
@@ -152,29 +240,82 @@ catch (err) {
     process.exit(2);
 }
 // Installed before either mode starts: a crash must leave a usable terminal
-// (TUI) and a log line (both), never a shell flooded with mouse reports.
-installCrashGuard();
+// (TUI) and a log line (both), never a shell flooded with mouse reports. A
+// detached service keeps its own SIGHUP handler so closing the terminal cannot
+// take it down.
+installCrashGuard({ surviveHangup: options.mode === "background" });
 const host = options.lan ? WILDCARD_HOST : options.host || process.env.NEUTRINO_WEB_HOST || undefined;
 const auth = !options.noAuth;
 const portFromEnv = envPort();
 if (options.mode === "web") {
-    // Headless: serve the saved history (and any live sessions in this process,
-    // which for a standalone server is none).
-    const port = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
-    try {
-        const handle = await startWebServer({ port, host, auth });
-        reportAccess(handle);
-        process.stdout.write("Serving saved conversations. Press Ctrl+C to stop.\n");
-        const shutdown = () => {
-            handle.close().finally(() => process.exit(0));
-        };
-        process.on("SIGINT", shutdown);
-        process.on("SIGTERM", shutdown);
-    }
-    catch (err) {
-        process.stderr.write(`neutrino: failed to start web server: ${err instanceof Error ? err.message : String(err)}\n`);
+    const result = await startBackgroundService({
+        port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT, host, auth,
+        tray: !options.noTray, resident: loadConfig().background === true, ownerPid: process.pid,
+        strictPort: options.port !== null,
+    });
+    if (!result.ok) {
+        process.stderr.write(`neutrino: failed to start web server: ${result.error}\n`);
         process.exit(1);
     }
+    reportBackgroundAccess(result.status, result.started);
+    process.stdout.write("Serving saved conversations. Press Ctrl+C to close this terminal.\n");
+    // The owner monitor in the service also handles an abrupt terminal close.
+    const keepAlive = setInterval(() => { }, 60_000);
+    const shutdown = () => { clearInterval(keepAlive); process.exit(0); };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+else if (options.mode === "background") {
+    const action = options.backgroundAction ?? "status";
+    if (action === "run") {
+        // The detached child. It does not own a terminal, so its stdio is ignored
+        // by the parent and every diagnostic goes to background.log.
+        await runBackgroundService(host, auth);
+    }
+    else if (action === "start") {
+        const result = await startBackgroundService({
+            port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT,
+            host,
+            auth,
+            tray: !options.noTray,
+        });
+        if (!result.ok) {
+            process.stderr.write(`neutrino: ${result.error}\n`);
+            process.exit(1);
+        }
+        reportBackgroundAccess(result.status, result.started);
+        process.exitCode = 0;
+    }
+    else if (action === "stop") {
+        const result = await stopBackgroundService();
+        if (!result.ok) {
+            process.stderr.write(`neutrino: ${result.error}\n`);
+            process.exit(1);
+        }
+        process.stdout.write(result.stopped ? "Background service stopped.\n" : "No background service is running.\n");
+        process.exitCode = 0;
+    }
+    else if (action === "open") {
+        const started = await startBackgroundService({
+            port: options.port ?? portFromEnv ?? DEFAULT_WEB_PORT,
+            host,
+            auth,
+            tray: !options.noTray,
+        });
+        if (!started.ok) {
+            process.stderr.write(`neutrino: ${started.error}\n`);
+            process.exit(1);
+        }
+        if (started.started)
+            reportBackgroundAccess(started.status, true);
+        openInBrowser(started.status.url);
+        process.stdout.write(`Opening ${started.status.url}\n`);
+        process.exitCode = 0;
+    }
+    else {
+        printBackgroundStatus();
+        process.exitCode = 0;
+    }
 }
 else {
     if (!process.stdout.isTTY || !process.stdin.isTTY) {
@@ -182,28 +323,45 @@ else {
         process.stderr.write("To serve the web UI without a terminal, run 'neutrino web --port <port>'.\n");
         process.exit(1);
     }
+    // The Pro presets are downloaded, not shipped, and kept in line with the
+    // official copy before any workspace can ask for a preset. A failure is not
+    // fatal: Pro mode reports the missing file (or keeps the local presets), and
+    // the next start tries again.
+    await syncProModels().then((result) => {
+        if (result.status === "updated") {
+            process.stderr.write(`neutrino: updated the Pro presets at ${PRO_MODEL_FILE} from ${PRO_MODELS_URL}\n`);
+        }
+    }).catch((error) => {
+        process.stderr.write(`neutrino: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+    // Ask the registry for the published version as early as possible, while the
+    // Web console is still starting: the first screen must not wait on the
+    // network. Offline is an ordinary state, hence no diagnostic here.
+    const updateCheck = checkForUpdate();
     const app = new App();
     const webPort = options.port ?? portFromEnv ?? DEFAULT_WEB_PORT;
-    // Remember where the UI should live even when it is off right now, so the
-    // Settings toggle can mount it without restarting the terminal.
-    app.configureWeb(webPort, host, auth);
-    // Explicit web settings win over the saved preference; otherwise the web UI
-    // is part of a normal launch unless the user turned it off in Settings.
+    const saved = loadConfig();
+    app.configureWeb(webPort, host, auth, true, !options.noTray);
     const requested = options.port !== null || options.host !== undefined || options.lan
         || options.noAuth || portFromEnv !== null || Boolean(process.env.NEUTRINO_WEB_HOST);
-    const enabledByDefault = loadConfig().web_console !== false;
-    if (!options.noWeb && (requested || enabledByDefault)) {
+    if (!options.noWeb && (requested || saved.web_console !== false)) {
         try {
-            const handle = await app.enableWeb(webPort, host, auth);
-            reportAccess(handle);
+            const previous = runningBackground();
+            const status = await app.enableWeb(webPort, host, auth);
+            if (options.port !== null && options.port !== 0 && status.port !== webPort) {
+                process.stderr.write(`note: the Web console is already running on port ${status.port}; --port was not applied.\n`);
+            }
+            reportBackgroundAccess(status, previous?.pid !== status.pid);
         }
         catch (err) {
-            // A console that cannot bind (usually a second instance on 8765) must
-            // never take the terminal down with it.
             const detail = err instanceof Error ? err.message : String(err);
             process.stderr.write(`neutrino: web UI not started: ${detail}\n`);
             process.stderr.write("The terminal UI will keep running. Pass --port <port> to use another port, or --no-web to skip the web UI.\n");
         }
     }
+    void updateCheck.then((status) => {
+        if (status.hasUpdate)
+            app.promptUpdate(status);
+    });
     await app.start();
 }

package/dist/config.js

@@ -24,10 +24,10 @@ export const PRO_CONFIG_FILE = path.join(PRO_DIR, "config.json");
 export const PRO_SESSION_DIR = path.join(PRO_DIR, "session");
 /**
  * Settings that intentionally apply to both workspaces. The Web password, the
- * approval policy and the console's interface are properties of this process,
- * not of a conversation workspace.
+ * approval policy, the console's interface/LAN access and background residency
+ * are properties of this process, not of a conversation workspace.
  */
-export const SHARED_CONFIG_KEYS = ["web_password_hash", "approval_mode", "auto_approve_extreme_risk", "web_lan"];
+export const SHARED_CONFIG_KEYS = ["web_password_hash", "approval_mode", "auto_approve_extreme_risk", "web_lan", "background"];
 export function normalizeMode(value) {
     return typeof value === "string" && value.trim().toLowerCase() === "pro" ? "pro" : "standard";
 }
@@ -136,6 +136,10 @@ export const DEFAULT_CONFIG = {
     // Listen on every interface (the equivalent of --lan) instead of loopback.
     // The listener belongs to the process, so both workspaces share this value.
     web_lan: false,
+    // Keep the Web console and the conversations it runs alive after the
+    // terminal UI exits. This is a property of the machine, not of a workspace,
+    // so the regular site and Pro share it.
+    background: false,
     // Working directories opened from the browser, newest first. They remain
     // listed even when they hold no conversations yet.
     web_workspaces: [],

package/dist/header.js

@@ -26,7 +26,8 @@ export function drawHeader(buf, state) {
     if (state.webUrl) {
         // A short reminder that the browser console is live; the startup message
         // prints the full addresses when more than one works.
-        text += `  ·  web ${state.webUrl.replace(/^https?:\/\//, "").replace(/\/$/, "")}`;
+        const label = state.webBackground ? "web (background)" : "web";
+        text += `  ·  ${label} ${state.webUrl.replace(/^https?:\/\//, "").replace(/\/$/, "")}`;
     }
     text = truncateByWidth(text, w);
     buf.centerText(0, text, { fg: C.accent, bg: C.highlightBg, bold: true });

package/dist/llm/tools.js

@@ -157,7 +157,9 @@ function runCommand(command, cwd) {
             resolve("[Error: empty command]");
             return;
         }
-        exec(command, { cwd, timeout: 120000, maxBuffer: MAX_OUTPUT * 4 }, (error, stdout, stderr) => {
+        exec(command, 
+        // A detached Windows service has no console for its tool shells to inherit.
+        { cwd, timeout: 120000, maxBuffer: MAX_OUTPUT * 4, windowsHide: true }, (error, stdout, stderr) => {
             const parts = [];
             if (stdout)
                 parts.push(stdout);

package/dist/migration.js

@@ -0,0 +1,33 @@
+import { loadAgentSession, safeAgentSessionId } from "./agents.js";
+import { loadConfig, loadSession, normalizeApprovalMode, saveSession, } from "./config.js";
+export class SessionMigrationError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Copy the readable conversation into a fresh native transcript, ready to resume. */
+export function migrateAgentSession(agent, sourceId, cwd, selection, mode = "standard", proPreset) {
+    if (!safeAgentSessionId(sourceId))
+        throw new SessionMigrationError(400, "invalid session id");
+    const source = loadAgentSession(agent, sourceId, cwd);
+    if (!source)
+        throw new SessionMigrationError(404, "session not found in this working directory");
+    // Preserve the roles and text exposed by the history viewer. Resumed native
+    // sessions supply their own system prompt and model/tool configuration.
+    const messages = source.messages.map(({ role, content }) => ({ role, content }));
+    if (!messages.length)
+        throw new SessionMigrationError(400, "this session has no messages to migrate");
+    let id;
+    try {
+        id = saveSession(messages, selection.model, selection.provider, selection.intensity, source.cwd, undefined, { prompt: 0, completion: 0 }, undefined, normalizeApprovalMode(loadConfig(mode).approval_mode), undefined, mode, proPreset);
+    }
+    catch (error) {
+        throw new SessionMigrationError(500, error instanceof Error ? error.message : String(error));
+    }
+    const saved = loadSession(id, mode);
+    if (!saved)
+        throw new SessionMigrationError(500, "could not read the migrated conversation");
+    return saved;
+}

package/dist/pro/config.js

@@ -1,10 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
+import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { PRO_DIR, loadConfig } from "../config.js";
 /** Provider URLs and credentials stay in the shared, ordinary model catalogue. */
 export const PRO_MODEL_FILE = path.join(PRO_DIR, "model.json");
+/** Presets the user adds or rewrites themselves; a same-named preset here wins. */
+export const PRO_CUSTOM_MODEL_FILE = path.join(PRO_DIR, "model-custom.json");
+/** The official presets, fetched on first use: nothing is bundled with the package. */
+export const PRO_MODELS_URL = "https://ius.neutrino.xingjisoft.com/model.json";
 const ASSET_DIR = fileURLToPath(new URL("../../assets/pro/", import.meta.url));
+const DOWNLOAD_TIMEOUT_MS = 10_000;
 export const PRO_ROLES = [
     "main_model", "thinking_model", "front_output_model", "backend_output_model",
     "confirm_model", "genimage_model", "plan_model", "modeling_model",
@@ -15,29 +21,125 @@ export const PRO_ROLE_LABELS = {
     backend_output_model: "Backend", confirm_model: "Approval", genimage_model: "Image generation",
     plan_model: "Planning", modeling_model: "Modeling",
 };
-/** Copy the bundled template byte-for-byte, exclusively on first use. */
+let downloading = null;
+/**
+ * Make sure the Pro presets are on disk, downloading the official set the first
+ * time. A file the user already has is never touched here; a failed download
+ * leaves nothing behind, so the next start simply tries again.
+ */
 export function ensureProModels() {
     fs.mkdirSync(PRO_DIR, { recursive: true });
+    if (fs.existsSync(PRO_MODEL_FILE))
+        return Promise.resolve();
+    downloading ??= downloadProModels().finally(() => { downloading = null; });
+    return downloading;
+}
+async function downloadProModels() {
+    const body = await fetchProModels();
+    // An error page or a truncated reply must never become the user's presets.
+    parseProModels(body, "model.json", PRO_MODELS_URL);
     try {
-        fs.copyFileSync(path.join(ASSET_DIR, "model-template.json"), PRO_MODEL_FILE, fs.constants.COPYFILE_EXCL);
+        fs.writeFileSync(PRO_MODEL_FILE, body, { flag: "wx" });
     }
     catch (error) {
+        // Another process won the race and wrote the file first: that is fine.
         if (error.code !== "EEXIST")
             throw error;
     }
 }
-export function loadProModels() {
-    ensureProModels();
+/**
+ * Keep ~/.neutrino/pro/model.json in step with the official presets, which own
+ * that file: any difference is overwritten. Presets the user keeps for
+ * themselves belong in model-custom.json, so nothing personal is lost. When the
+ * official copy cannot be read, the local presets stay exactly as they are.
+ *
+ * Called once at start-up by both the terminal and the Web console.
+ */
+export async function syncProModels() {
+    const failure = `could not download the Pro model presets from ${PRO_MODELS_URL}`;
+    let body;
+    try {
+        body = await fetchProModels();
+    }
+    catch (error) {
+        // Offline, or the server is down: the local presets are still usable.
+        if (!fs.existsSync(PRO_MODEL_FILE))
+            throw error;
+        return { status: "kept", detail: error instanceof Error ? error.message : String(error) };
+    }
+    const remote = parseProModels(body, "model.json", PRO_MODELS_URL);
+    const present = fs.existsSync(PRO_MODEL_FILE);
+    if (remote.tier.length === 0) {
+        if (!present)
+            throw new Error(`${failure}: it contains no presets`);
+        return { status: "kept", detail: `${failure}: it contains no presets` };
+    }
+    // Only formatting differences are not a difference: the file keeps its shape.
+    // A local file that does not parse is replaced, so a hand edit cannot block Pro.
+    if (present && samePresets(readProModelsQuietly(), remote))
+        return { status: "unchanged" };
+    writeProModels(body);
+    return { status: "updated" };
+}
+async function fetchProModels() {
+    try {
+        const response = await fetch(PRO_MODELS_URL, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        return await response.text();
+    }
+    catch (error) {
+        throw new Error(`could not download the Pro model presets from ${PRO_MODELS_URL}: `
+            + `${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Write the official copy in one step, so no reader ever sees half a file. */
+function writeProModels(body) {
+    fs.mkdirSync(PRO_DIR, { recursive: true });
+    const temp = `${PRO_MODEL_FILE}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temp, body);
+        fs.renameSync(temp, PRO_MODEL_FILE);
+    }
+    catch (error) {
+        fs.rmSync(temp, { force: true });
+        throw error;
+    }
+}
+function readProModelsQuietly() {
+    try {
+        return readProModels(PRO_MODEL_FILE, "model.json");
+    }
+    catch {
+        return null;
+    }
+}
+function samePresets(left, right) {
+    return left !== null && canonicalJson(left) === canonicalJson(right);
+}
+/** Compare documents by content, so reformatting alone is never a difference. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** Parse and validate one presets document; each file has to be valid on its own. */
+function parseProModels(text, label, where) {
     let value;
     try {
-        value = JSON.parse(fs.readFileSync(PRO_MODEL_FILE, "utf8"));
+        value = JSON.parse(text);
     }
     catch {
-        throw new Error("Pro model.json is not valid JSON; fix ~/.neutrino/pro/model.json");
+        throw new Error(`Pro ${label} is not valid JSON; fix ${where}`);
     }
-    if (!value || typeof value !== "object" || !Array.isArray(value.tier) ||
-        value.tier.length === 0) {
-        throw new Error("Pro model.json must contain a nonempty tier array");
+    if (!value || typeof value !== "object" || !Array.isArray(value.tier)) {
+        throw new Error(`Pro ${label} must contain a tier array`);
     }
     const names = new Set();
     for (const preset of value.tier) {
@@ -59,6 +161,30 @@ export function loadProModels() {
     }
     return value;
 }
+function readProModels(file, label) {
+    return parseProModels(fs.readFileSync(file, "utf8"), label, `~/.neutrino/pro/${label}`);
+}
+export function loadProModels() {
+    if (!fs.existsSync(PRO_MODEL_FILE)) {
+        // The download is asynchronous, so it happens at start-up (see ensureProModels).
+        throw new Error(`Pro model.json is missing; it is downloaded from ${PRO_MODELS_URL} on first use`);
+    }
+    const { tier } = readProModels(PRO_MODEL_FILE, "model.json");
+    // Presets the user keeps in model-custom.json are merged in: a same-named entry
+    // replaces the one from model.json in place, new ones are appended.
+    if (fs.existsSync(PRO_CUSTOM_MODEL_FILE)) {
+        for (const preset of readProModels(PRO_CUSTOM_MODEL_FILE, "model-custom.json").tier) {
+            const index = tier.findIndex((entry) => entry.name === preset.name);
+            if (index === -1)
+                tier.push(preset);
+            else
+                tier[index] = preset;
+        }
+    }
+    if (tier.length === 0)
+        throw new Error("Pro model.json must contain a nonempty tier array");
+    return { tier };
+}
 export function requireProPreset(value) {
     if (typeof value !== "string" || !loadProModels().tier.some((preset) => preset.name === value)) {
         throw new Error("Unknown Pro preset");