@xingjisoft/neutrino 0.4.0 → 0.4.1

package/dist/tray.js

@@ -0,0 +1,138 @@
+/**
+ * Windows notification-area icon for the background Web console.
+ *
+ * Node cannot create a tray icon by itself, and the project deliberately has
+ * no native dependencies, so a tiny Windows PowerShell process hosts a
+ * `System.Windows.Forms.NotifyIcon`. It uses the same orbit badge as the
+ * regular console's top-left mark. Everything is best-effort: an unavailable
+ * icon must never stop the service.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { BACKGROUND_LOG_FILE, backgroundLog } from "./background.js";
+import { NEUTRINO_DIR } from "./config.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, "..");
+const ICON_FILE = path.join(PKG_ROOT, "assets", "neutrino.ico");
+/** Quote a value as a PowerShell single-quoted literal. */
+function psString(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** The icon itself. Only Windows has a notification area, and only it can run this. */
+export function startBackgroundTray(options) {
+    if (process.platform !== "win32")
+        return null;
+    if (process.env.NEUTRINO_NO_TRAY === "1")
+        return null;
+    if (!fs.existsSync(ICON_FILE)) {
+        backgroundLog(`tray icon not found at ${ICON_FILE}`);
+        return null;
+    }
+    // Separate files let an old icon close cleanly even if residency is turned
+    // back on before its PowerShell message loop has processed the shutdown.
+    const suffix = `${process.pid}-${randomBytes(8).toString("hex")}`;
+    const scriptFile = path.join(NEUTRINO_DIR, `tray-${suffix}.ps1`);
+    const closeFile = path.join(NEUTRINO_DIR, `tray-${suffix}.stop`);
+    const script = `
+$ErrorActionPreference = 'Continue'
+$scriptFile = ${psString(scriptFile)}
+$closeFile = ${psString(closeFile)}
+try {
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+$iconPath = ${psString(ICON_FILE)}
+$url = ${psString(options.url)}
+$stopUrl = ${psString(options.stopUrl)}
+$token = ${psString(options.token)}
+$parent = ${options.pid}
+$notify = New-Object System.Windows.Forms.NotifyIcon
+$notify.Icon = New-Object System.Drawing.Icon($iconPath)
+$notify.Text = 'Neutrino - background console'
+$notify.Visible = $true
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+$open = $menu.Items.Add('Open Neutrino console')
+$open.add_Click({ Start-Process -FilePath $url })
+$stop = $menu.Items.Add('Stop background service')
+$stop.add_Click({
+  try {
+    Invoke-RestMethod -Method Post -Uri $stopUrl -Headers @{ Authorization = "Bearer $token" } -TimeoutSec 5 | Out-Null
+  } catch {
+    Stop-Process -Id $parent -Force
+  }
+  $notify.Visible = $false
+  [System.Windows.Forms.Application]::Exit()
+})
+$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator)) | Out-Null
+$notify.ContextMenuStrip = $menu
+$notify.add_MouseClick({ param($sender, $eventArgs) if ($eventArgs.Button -eq [System.Windows.Forms.MouseButtons]::Left) { Start-Process -FilePath $url } })
+$notify.add_DoubleClick({ Start-Process -FilePath $url })
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 250
+$timer.add_Tick({
+  if ((Test-Path -LiteralPath $closeFile) -or -not (Get-Process -Id $parent -ErrorAction SilentlyContinue)) {
+    $notify.Visible = $false
+    [System.Windows.Forms.Application]::Exit()
+  }
+})
+$timer.Start()
+[System.Windows.Forms.Application]::Run()
+} finally {
+  if ($notify) { $notify.Visible = $false; $notify.Dispose() }
+  Remove-Item -LiteralPath $closeFile, $scriptFile -Force -ErrorAction SilentlyContinue
+}
+`;
+    const cleanup = () => {
+        for (const file of [scriptFile, closeFile]) {
+            try {
+                fs.rmSync(file, { force: true });
+            }
+            catch { /* The helper also cleans up. */ }
+        }
+    };
+    try {
+        fs.mkdirSync(NEUTRINO_DIR, { recursive: true });
+        fs.writeFileSync(scriptFile, `\ufeff${script}`, { encoding: "utf-8", mode: 0o600 });
+        const logFd = fs.openSync(BACKGROUND_LOG_FILE, "a");
+        let child;
+        try {
+            child = spawn("powershell.exe", [
+                "-NoProfile", "-NonInteractive", "-STA", "-ExecutionPolicy", "Bypass", "-WindowStyle", "Hidden",
+                "-File", scriptFile,
+            ], 
+            // Not detached: on Windows a detached PowerShell exits before its
+            // message loop starts. The icon outlives the service on its own; its
+            // timer notices the parent pid disappearing and shuts it down.
+            { stdio: ["ignore", "ignore", logFd], windowsHide: true });
+        }
+        finally {
+            fs.closeSync(logFd);
+        }
+        let active = true;
+        child.once("error", (error) => { active = false; cleanup(); backgroundLog(`tray failed: ${error.message}`); });
+        child.once("exit", (code) => { active = false; cleanup(); backgroundLog(`tray exited (${code ?? "signal"})`); });
+        child.unref();
+        backgroundLog(`tray icon started (pid ${child.pid ?? "unknown"})`);
+        return { close: () => {
+                if (!active)
+                    return;
+                try {
+                    fs.writeFileSync(closeFile, "", { mode: 0o600 });
+                }
+                catch {
+                    try {
+                        child.kill();
+                    }
+                    catch { /* Already gone. */ }
+                }
+            } };
+    }
+    catch (error) {
+        cleanup();
+        backgroundLog(`tray failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}

package/dist/web/hub.js

@@ -58,6 +58,10 @@ class LiveHub {
         const entry = this.entries.get(key);
         return Boolean(entry) && (!mode || entry.mode === mode);
     }
+    remoteAction(key) {
+        const agent = this.entries.get(key)?.agent;
+        return agent?.remoteAction ? agent.remoteAction.bind(agent) : null;
+    }
     /** All live sessions, newest registration last. Optionally one workspace only. */
     list(mode) {
         const out = [];

package/dist/web/server.js

@@ -15,6 +15,7 @@ import fs from "node:fs";
 import http from "node:http";
 import os from "node:os";
 import path from "node:path";
+import { timingSafeEqual } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { deleteSession, listSessions, loadConfig, normalizeApprovalMode, resolveModelSelection, saveConfig, sessionDir, } from "../config.js";
 import { getWebSettings, updateWebSettings } from "./settings.js";
@@ -22,9 +23,11 @@ import { WebAuth } from "./auth.js";
 import { normalizeCwd, sameCwd } from "../cwd.js";
 import { hub } from "./hub.js";
 import { writeCrashLog } from "../terminal/restore.js";
-import { createWebSession, proInitialSelection, resumeSession } from "./session.js";
+import { createWebSession, proInitialSelection, resumeSession, WebSession } from "./session.js";
 import { defaultProPreset, requireProPreset } from "../pro/config.js";
-import { listAgentSessions, loadAgentMessages } from "../agents.js";
+import { listAgentSessions, loadAgentMessages, loadAgentSession, safeAgentSessionId } from "../agents.js";
+import { migrateAgentSession, SessionMigrationError } from "../migration.js";
+import { runningBackground } from "../background.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // dist/web -> package root (mirrors the same trick used in config.ts).
 const PKG_ROOT = path.resolve(__dirname, "..", "..");
@@ -119,10 +122,26 @@ export function webUrls(host, port) {
  * is listening right now, so a run started with --lan shows as on even though
  * nothing was saved yet.
  */
+function validTerminalBridge(bridge, ownerPid) {
+    if (!bridge || typeof bridge !== "object" || Array.isArray(bridge) || typeof ownerPid !== "number")
+        return false;
+    const info = bridge;
+    if (typeof info.url !== "string" || typeof info.token !== "string" || !/^[a-f0-9]{64}$/.test(info.token))
+        return false;
+    try {
+        const url = new URL(info.url);
+        return url.protocol === "http:" && url.hostname === "127.0.0.1" && Boolean(url.port)
+            && url.pathname === "/" && !url.username && !url.password && !url.search && !url.hash;
+    }
+    catch {
+        return false;
+    }
+}
 function settingsPayload(mode, binding) {
     const payload = getWebSettings(mode);
     const lan = isWildcardHost(binding.host);
     const { urls } = webUrls(binding.host, binding.port);
+    const background = binding.service?.status?.() ?? runningBackground();
     return {
         ...payload,
         settings: {
@@ -131,6 +150,12 @@ function settingsPayload(mode, binding) {
             web_host: binding.host,
             // Addresses another device can open; empty unless every interface is bound.
             web_urls: lan ? urls.filter((url) => !url.includes("//127.0.0.1:")) : [],
+            // The background service is a process, not a workspace: both pages report
+            // the same state. The prompt is never shown once the setting is on.
+            background: background?.pid === process.pid ? background.resident : payload.settings.background,
+            background_running: background?.resident === true,
+            background_url: background?.url ?? "",
+            background_prompt: binding.prompt.pending && payload.settings.background !== true,
         },
     };
 }
@@ -194,7 +219,6 @@ function sendApiError(res, error) {
 }
 const MAX_RECENT_WORKSPACES = 12;
 const AGENT_IDS = new Set(["claude", "codex", "opencode"]);
-const AGENT_SESSION_ID_RE = /^[A-Za-z0-9._-]{1,200}$/;
 /** Expand `~` and require an absolute path; used by every folder route. */
 function absolutePath(raw) {
     if (typeof raw !== "string" || !raw.trim()) {
@@ -354,9 +378,6 @@ function createFolder(raw) {
 function isAgentId(value) {
     return AGENT_IDS.has(value);
 }
-function safeAgentSessionId(id) {
-    return AGENT_SESSION_ID_RE.test(id) && !id.includes("..") && id !== "." && id !== "..";
-}
 /** Build the sidebar payload: the selected workspace's sessions grouped by directory. */
 function buildOverview(mode = "standard") {
     const sessions = listSessions(mode);
@@ -484,6 +505,16 @@ function isSameOrigin(req) {
         return false;
     }
 }
+/** Constant-time comparison of the service's management token. */
+function hasServiceToken(req, token) {
+    const header = String(req.headers.authorization ?? "");
+    const prefix = "Bearer ";
+    if (!header.startsWith(prefix))
+        return false;
+    const supplied = Buffer.from(header.slice(prefix.length));
+    const expected = Buffer.from(token);
+    return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+}
 function serveStatic(res, pathname) {
     let rel = pathname === "/" ? "/index.html" : pathname;
     try {
@@ -576,6 +607,59 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
         res.end();
         return true;
     }
+    // Management endpoints of the detached service. They are called by the CLI
+    // and the tray icon, which have the token from ~/.neutrino/background.json
+    // but not necessarily a browser login cookie.
+    if (["/api/background/ping", "/api/background/stop", "/api/background/configure"].includes(pathname)) {
+        if (req.method !== "GET" && req.method !== "POST") {
+            sendJson(res, 405, { error: "method not allowed" });
+            return true;
+        }
+        if (!binding.service) {
+            sendJson(res, 404, { error: "this console is not running in the background" });
+            return true;
+        }
+        if (!hasServiceToken(req, binding.service.token)) {
+            sendJson(res, 401, { error: "background service token required" });
+            return true;
+        }
+        if (pathname.endsWith("/ping")) {
+            sendJson(res, 200, { ok: true, pid: process.pid, url: webUrls(binding.host, binding.port).url });
+            return true;
+        }
+        if (pathname.endsWith("/configure")) {
+            if (req.method !== "POST") {
+                sendJson(res, 405, { error: "method not allowed" });
+                return true;
+            }
+            if (!binding.service.configure) {
+                sendJson(res, 409, { error: "Restart the console to update background residency." });
+                return true;
+            }
+            try {
+                const body = await readJsonBody(req, 4096);
+                if (!body || typeof body !== "object" || Array.isArray(body)
+                    || Object.keys(body).some(key => key !== "resident" && key !== "ownerPid" && key !== "bridge")
+                    || (body.resident !== undefined && typeof body.resident !== "boolean")
+                    || (body.ownerPid !== undefined && (!Number.isSafeInteger(body.ownerPid) || body.ownerPid <= 0))
+                    || (body.bridge !== undefined && !validTerminalBridge(body.bridge, body.ownerPid))) {
+                    throw new Error("invalid background settings");
+                }
+                const updated = binding.service.configure(body);
+                if (updated.resident)
+                    binding.prompt.pending = false;
+                sendJson(res, 200, updated);
+            }
+            catch (error) {
+                sendJson(res, 400, { error: error instanceof Error ? error.message : "invalid background settings" });
+            }
+            return true;
+        }
+        sendJson(res, 200, { ok: true, stopping: true });
+        // Let the response reach the caller before the socket closes.
+        setImmediate(() => binding.service?.onStop());
+        return true;
+    }
     if (pathname === "/api/auth/login" || pathname === "/api/auth/logout") {
         if (req.method !== "POST") {
             sendJson(res, 405, { error: "method not allowed" });
@@ -610,6 +694,21 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
         sendJson(res, 401, { error: "Password login required." });
         return true;
     }
+    // The first browser to see the background-residency prompt consumes it for
+    // this console run, whether it accepted or dismissed it.
+    if (pathname === "/api/background/dismiss") {
+        if (req.method !== "POST") {
+            sendJson(res, 405, { error: "method not allowed" });
+        }
+        else if (!isSameOrigin(req)) {
+            sendJson(res, 403, { error: "cross-origin request rejected" });
+        }
+        else {
+            binding.prompt.pending = false;
+            sendJson(res, 200, { ok: true });
+        }
+        return true;
+    }
     if (pathname === "/api/settings") {
         if (req.method === "GET") {
             sendJson(res, 200, settingsPayload(mode, binding));
@@ -619,39 +718,15 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
                 sendJson(res, 403, { error: "cross-origin request rejected" });
                 return true;
             }
-            const wasLan = loadConfig(mode).web_lan === true;
             try {
                 const body = await readJsonBody(req);
-                updateWebSettings(body, mode);
-                // `web_lan` is both a saved preference and a live switch: apply it to
-                // the socket now so the console starts or stops answering on the LAN
-                // without a restart. Other settings never move the listener, and an
-                // explicit --host still decides the interface until this is changed.
-                const patch = body?.settings;
-                const desired = patch && Object.prototype.hasOwnProperty.call(patch, "web_lan")
-                    ? patch.web_lan === true
-                    : isWildcardHost(binding.host);
-                if (desired !== isWildcardHost(binding.host)) {
-                    await binding.setHost(desired ? WILDCARD_HOST : LOOPBACK_HOST);
-                }
+                await binding.updateSettings(body, mode);
                 if (body.settings?.web_password !== undefined) {
                     auth.remember(res);
                 }
                 sendJson(res, 200, settingsPayload(mode, binding));
             }
             catch (err) {
-                // A switch that could not bind must not pretend the socket moved:
-                // restore the saved preference so the file matches what is running.
-                if ((loadConfig(mode).web_lan === true) !== wasLan) {
-                    try {
-                        const config = loadConfig(mode);
-                        config.web_lan = wasLan;
-                        saveConfig(config, mode);
-                    }
-                    catch {
-                        // Reporting the original failure matters more than the rollback.
-                    }
-                }
                 sendJson(res, err?.code ? 500 : 400, {
                     error: err instanceof Error ? err.message : "invalid settings",
                 });
@@ -797,7 +872,7 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
         sendJson(res, 200, { ok: true, deleted: true });
         return true;
     }
-    // Read-only history recorded by other agents (Claude Code, Codex, OpenCode).
+    // History recorded by other agents (Claude Code, Codex, OpenCode).
     const agentSessionsMatch = /^\/api\/agents\/([^/]+)\/sessions$/.exec(pathname);
     if (req.method === "GET" && agentSessionsMatch) {
         const agent = decodeURIComponent(agentSessionsMatch[1]);
@@ -821,7 +896,59 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
             sendJson(res, 400, { error: "invalid session id" });
             return true;
         }
-        sendJson(res, 200, { agent, id, messages: loadAgentMessages(agent, id) });
+        const cwd = url.searchParams.get("cwd");
+        if (cwd) {
+            const source = loadAgentSession(agent, id, cwd);
+            if (!source) {
+                sendJson(res, 404, { error: "session not found in this working directory" });
+                return true;
+            }
+            sendJson(res, 200, { ...source, agent });
+        }
+        else {
+            sendJson(res, 200, { agent, id, messages: loadAgentMessages(agent, id) });
+        }
+        return true;
+    }
+    const migrateMatch = /^\/api\/agents\/([^/]+)\/sessions\/([^/]+)\/migrate$/.exec(pathname);
+    if (migrateMatch) {
+        if (req.method !== "POST") {
+            sendJson(res, 405, { error: "method not allowed" });
+            return true;
+        }
+        if (!isSameOrigin(req)) {
+            sendJson(res, 403, { error: "cross-origin request rejected" });
+            return true;
+        }
+        const agent = decodeURIComponent(migrateMatch[1]);
+        const id = decodeURIComponent(migrateMatch[2]);
+        if (!isAgentId(agent) || !safeAgentSessionId(id)) {
+            sendJson(res, 400, { error: !isAgentId(agent) ? "unknown agent" : "invalid session id" });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            if (!body || typeof body !== "object" || Array.isArray(body))
+                throw new Error("invalid JSON body");
+            const input = body;
+            const cwd = existingDirectory(input.cwd ?? process.cwd());
+            const preset = mode === "pro" ? requireProPreset(input.pro_preset ?? defaultProPreset()) : undefined;
+            const selection = mode === "pro" ? proInitialSelection(preset)
+                : resolveModelSelection(input.selection ?? getWebSettings(mode).selection, false);
+            const migrated = migrateAgentSession(agent, id, cwd, {
+                provider: selection.provider, model: selection.model.name, intensity: selection.intensity,
+            }, mode, preset);
+            const session = new WebSession(migrated, selection.model, mode);
+            const key = session.start();
+            webSessions.set(key, session);
+            sendJson(res, 201, { ok: true, id: migrated.id, key, cwd, snapshot: hub.snapshot(key) });
+        }
+        catch (err) {
+            if (err instanceof SessionMigrationError)
+                sendJson(res, err.status, { error: err.message });
+            else
+                sendApiError(res, err);
+        }
         return true;
     }
     const sessionMatch = /^\/api\/session\/([^/]+)$/.exec(pathname);
@@ -870,14 +997,29 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
         // Already running (TUI or another tab)? Attach instead of duplicating.
         const existing = hub.list(mode).find((entry) => entry.sessionId === id);
         if (existing) {
-            if (preset !== undefined) {
+            const remote = hub.remoteAction(existing.key);
+            if (remote && preset !== undefined) {
+                const result = await remote("pro-preset", { preset });
+                if (result.status !== 200) {
+                    sendJson(res, result.status, result.data);
+                    return true;
+                }
+            }
+            else if (remote && selection) {
+                const result = await remote("model", { provider: selection.provider, model: selection.model.name, intensity: selection.intensity });
+                if (result.status !== 200) {
+                    sendJson(res, result.status, result.data);
+                    return true;
+                }
+            }
+            if (!remote && preset !== undefined) {
                 const changed = hub.setProPreset(existing.key, preset);
                 if (!changed.ok) {
                     sendJson(res, 409, { error: changed.error });
                     return true;
                 }
             }
-            if (selection) {
+            if (!remote && selection) {
                 const changed = hub.configure(existing.key, selection);
                 if (!changed.ok) {
                     sendJson(res, 409, { error: changed.error });
@@ -941,6 +1083,23 @@ async function handleApi(req, res, url, auth, mode, pathname, binding) {
                 sendJson(res, 404, { error: "unknown live session" });
                 return true;
             }
+            const remote = hub.remoteAction(key);
+            if (remote) {
+                if (action === "close") {
+                    sendJson(res, 400, { error: "this session is owned by the terminal UI" });
+                    return true;
+                }
+                try {
+                    const body = ["approve", "approval-mode", "message", "model", "pro-preset"].includes(action)
+                        ? await readJsonBody(req) : {};
+                    const result = await remote(action, body);
+                    sendJson(res, result.status, result.data);
+                }
+                catch (error) {
+                    sendJson(res, 400, { error: error instanceof Error ? error.message : "invalid request" });
+                }
+                return true;
+            }
             if (action === "pro-preset") {
                 if (mode !== "pro") {
                     sendJson(res, 404, { error: "Pro presets are only available in Pro mode" });
@@ -1123,6 +1282,9 @@ export async function startWebServer(options) {
         host,
         port,
         setHost: (next) => rebind(next),
+        prompt: { pending: options.backgroundPrompt === true },
+        service: options.backgroundService,
+        updateSettings: (body, mode) => updateSettings(body, mode),
     };
     const server = http.createServer((req, res) => {
         handleRequest(req, res, auth, binding).catch((err) => {
@@ -1170,6 +1332,7 @@ export async function startWebServer(options) {
         handle.port = port;
         handle.url = address.url;
         handle.urls = address.urls;
+        options.onAddressChange?.();
     };
     // Two tabs saving at once must not interleave close/listen on one socket.
     let switches = Promise.resolve();
@@ -1211,6 +1374,51 @@ export async function startWebServer(options) {
         switches = task.catch(() => undefined);
         return task;
     }
+    // Serialize saves from both workspaces so a failed switch cannot roll back
+    // another tab's successful change.
+    let settingsChanges = Promise.resolve();
+    function updateSettings(body, mode) {
+        const task = settingsChanges.then(async () => {
+            const previous = loadConfig(mode);
+            const wasHost = binding.host;
+            try {
+                updateWebSettings(body, mode);
+                const patch = body?.settings;
+                const desiredHost = patch && Object.prototype.hasOwnProperty.call(patch, "web_lan")
+                    ? patch.web_lan === true ? WILDCARD_HOST : LOOPBACK_HOST
+                    : binding.host;
+                if (desiredHost !== binding.host)
+                    await binding.setHost(desiredHost);
+                if (patch && Object.prototype.hasOwnProperty.call(patch, "background")) {
+                    if (!binding.service?.configure) {
+                        throw new Error("Background residency could not be applied. Restart the console and try again.");
+                    }
+                    binding.service.configure({ resident: patch.background === true });
+                    if (patch.background === true)
+                        binding.prompt.pending = false;
+                }
+            }
+            catch (error) {
+                // A failed lifetime or address change must not look saved or active.
+                if (binding.host !== wasHost) {
+                    try {
+                        await binding.setHost(wasHost);
+                    }
+                    catch { /* Report the original failure. */ }
+                }
+                const config = loadConfig(mode);
+                config.web_lan = previous.web_lan;
+                config.background = previous.background;
+                try {
+                    saveConfig(config, mode);
+                }
+                catch { /* Report the original failure. */ }
+                throw error;
+            }
+        });
+        settingsChanges = task.catch(() => undefined);
+        return task;
+    }
     const handle = {
         host,
         port,