zevairouter 1.0.38 → 1.0.40

package/src/lib/headroom/detect.js

@@ -0,0 +1,192 @@
+import { execFileSync, execSync } from "child_process";
+import path from "path";
+
+// Extras that improve headroom compression quality. `proxy` is the base;
+// `code` adds tree-sitter AST compression; `ml` adds Kompress-v2 HF model.
+// Other `[all]` extras (image, voice, otel, reports, evals, ...) are not
+// useful for the 9router proxy use case, so we don't track them here.
+export const HEADROOM_COMPRESSION_EXTRAS = ["code", "ml"];
+
+// Marker packages that each extra pulls in. Detected from `pip list --format=json`
+// so one call can answer both the installed version and active extras.
+export const EXTRA_MARKERS = {
+  code: ["tree-sitter", "tree-sitter-language-pack"],
+  ml: ["torch", "huggingface-hub"],
+};
+
+const HEADROOM_PIP_TIMEOUT_MS = 8000;
+
+const IS_WIN = process.platform === "win32";
+const WHICH_CMD = IS_WIN ? "where" : "which";
+
+// Extra bin dirs often missing from a packaged/launchd PATH (Python installs headroom here).
+const EXTRA_BINS = IS_WIN
+  ? [
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python313\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python312\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python311\\Scripts`,
+      `${process.env.LOCALAPPDATA || ""}\\Programs\\Python\\Python310\\Scripts`,
+      `${process.env.APPDATA || ""}\\Python\\Python313\\Scripts`,
+    ]
+  : [
+      "/usr/local/bin",
+      "/opt/homebrew/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.13/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.12/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.11/bin",
+      "/Library/Frameworks/Python.framework/Versions/3.10/bin",
+      `${process.env.HOME || ""}/.local/bin`,
+      "/usr/bin",
+      "/bin",
+    ];
+
+const EXTENDED_PATH = [...EXTRA_BINS, process.env.PATH || ""].filter(Boolean).join(path.delimiter);
+const PYTHON_CANDIDATES = ["python3.13", "python3.12", "python3.11", "python3.10", "python3", "python"];
+const MIN_VERSION = [3, 10];
+const HEADROOM_HEALTH_TIMEOUT_MS = 1500;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+
+export const DEFAULT_HEADROOM_URL = process.env.HEADROOM_URL || "http://localhost:8787";
+
+// Detect whether the headroom CLI is installed and where its binary lives.
+export function findHeadroomBinary() {
+  try {
+    const out = execSync(`${WHICH_CMD} headroom`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    }).toString().trim();
+    // Windows `where` may return multiple lines — take the first.
+    return out ? out.split(/\r?\n/)[0].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Find a Python interpreter >= 3.10 (headroom-ai requires it). Returns null if none.
+// `python3`, `python3.13`, `python` can point at different envs on any OS. Prefer
+// the interpreter that can also see the installed `headroom-ai` package so the
+// dashboard probes and install action operate on the same interpreter as the CLI.
+// Falls back to the first version-eligible candidate when headroom-ai is not yet
+// installed anywhere (needed for the initial install).
+// Interpreters to probe, most specific first: the python next to the headroom
+// binary (guaranteed to have headroom-ai), then full paths from EXTRA_BINS, then
+// bare names resolved via PATH.
+function pythonCandidates() {
+  const list = [];
+  const bin = findHeadroomBinary();
+  if (bin) {
+    const dir = path.dirname(bin);
+    const names = IS_WIN ? ["python.exe", "python3.exe"] : ["python3", "python3.13", "python"];
+    for (const n of names) list.push(path.join(dir, n));
+  }
+  for (const dir of EXTRA_BINS) {
+    if (!dir) continue;
+    for (const n of PYTHON_CANDIDATES) list.push(path.join(dir, IS_WIN ? `${n}.exe` : n));
+  }
+  list.push(...PYTHON_CANDIDATES);
+  return list;
+}
+
+export function findPython310() {
+  let fallback = null;
+  for (const candidate of pythonCandidates()) {
+    try {
+      const ver = execSync(`${candidate} --version`, {
+        stdio: ["ignore", "pipe", "ignore"],
+        windowsHide: true,
+        env: { ...process.env, PATH: EXTENDED_PATH },
+      }).toString().trim();
+      const match = ver.match(/(\d+)\.(\d+)/);
+      if (!match) continue;
+      const [major, minor] = [parseInt(match[1], 10), parseInt(match[2], 10)];
+      if (!(major > MIN_VERSION[0] || (major === MIN_VERSION[0] && minor >= MIN_VERSION[1]))) continue;
+      if (!fallback) fallback = candidate;
+      try {
+        execFileSync(candidate, ["-m", "pip", "show", "headroom-ai"], {
+          stdio: ["ignore", "pipe", "ignore"],
+          windowsHide: true,
+          timeout: HEADROOM_PIP_TIMEOUT_MS,
+          env: { ...process.env, PATH: EXTENDED_PATH },
+        });
+        return candidate;
+      } catch {
+        // Keep scanning until an interpreter that sees headroom-ai is found.
+      }
+    } catch {
+      // candidate not present, try next
+    }
+  }
+  return fallback;
+}
+
+// Probe whether a Headroom proxy is reachable at the given URL by hitting /health.
+export async function probeProxyRunning(url) {
+  if (!url) return false;
+  const base = String(url).replace(/\/$/, "");
+  try {
+    const res = await fetch(`${base}/health`, { signal: AbortSignal.timeout(HEADROOM_HEALTH_TIMEOUT_MS) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function isLoopbackHeadroomUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return LOOPBACK_HOSTS.has(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+// Aggregate status for the dashboard: installed, running, python interpreter.
+export async function getHeadroomStatus(url) {
+  const path = findHeadroomBinary();
+  const python = findPython310();
+  const installed = Boolean(path);
+  const running = await probeProxyRunning(url);
+  const localUrl = isLoopbackHeadroomUrl(url);
+  const extrasStatus = installed ? getInstalledHeadroomExtras(python) : { installed: false, version: null, extras: { code: false, ml: false } };
+  return {
+    installed,
+    path,
+    running,
+    python,
+    localUrl,
+    canStart: installed && localUrl,
+    version: extrasStatus.version,
+    extras: extrasStatus.extras,
+  };
+}
+
+// Parse installed headroom-ai version + which compression extras are
+// actually installed (detected via marker package presence). One `pip list`
+// call is enough to answer both questions.
+//
+// Returns: { installed: bool, version: string|null, extras: { code, ml } }
+export function getInstalledHeadroomExtras(python) {
+  const py = python || findPython310();
+  if (!py) return { installed: false, version: null, extras: { code: false, ml: false } };
+  try {
+    const out = execFileSync(py, ["-m", "pip", "list", "--format=json", "--disable-pip-version-check"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      timeout: HEADROOM_PIP_TIMEOUT_MS,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    }).toString();
+    const packages = JSON.parse(out);
+    const names = new Set(packages.map((p) => String(p.name || "").toLowerCase()));
+    const installed = names.has("headroom-ai");
+    if (!installed) return { installed: false, version: null, extras: { code: false, ml: false } };
+    const version = packages.find((p) => p.name?.toLowerCase() === "headroom-ai")?.version || null;
+    const extras = {};
+    for (const extra of HEADROOM_COMPRESSION_EXTRAS) {
+      extras[extra] = EXTRA_MARKERS[extra].some((m) => names.has(m));
+    }
+    return { installed: true, version, extras };
+  } catch {
+    return { installed: false, version: null, extras: { code: false, ml: false } };
+  }
+}

package/src/lib/headroom/process.js

@@ -0,0 +1,260 @@
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import { DATA_DIR } from "@/lib/dataDir.js";
+import { findHeadroomBinary, findPython310, HEADROOM_COMPRESSION_EXTRAS, EXTRA_MARKERS, getInstalledHeadroomExtras } from "./detect.js";
+
+const HEADROOM_DIR = path.join(DATA_DIR, "headroom");
+const PID_FILE = path.join(HEADROOM_DIR, "proxy.pid");
+const LOG_FILE = path.join(HEADROOM_DIR, "proxy.log");
+const INSTALL_LOG_FILE = path.join(HEADROOM_DIR, "install.log");
+const DEFAULT_PORT = 8787;
+const STARTUP_TIMEOUT_MS = 8000;
+
+function ensureDir() {
+  if (!fs.existsSync(HEADROOM_DIR)) fs.mkdirSync(HEADROOM_DIR, { recursive: true });
+}
+
+function readPid() {
+  try {
+    if (fs.existsSync(PID_FILE)) return parseInt(fs.readFileSync(PID_FILE, "utf8"), 10);
+  } catch { /* ignore */ }
+  return null;
+}
+
+function writePid(pid) {
+  ensureDir();
+  fs.writeFileSync(PID_FILE, String(pid));
+}
+
+function clearPid() {
+  try { if (fs.existsSync(PID_FILE)) fs.unlinkSync(PID_FILE); } catch { /* ignore */ }
+}
+
+// process.kill throws if pid is dead — use this to probe.
+export function isPidAlive(pid) {
+  if (!pid || typeof pid !== "number") return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export function getManagedPid() {
+  const pid = readPid();
+  return pid && isPidAlive(pid) ? pid : null;
+}
+
+// Build proxy CLI flags for the active compression extras. `[code]` (AST
+// compression) is off by default in headroom → pass --code-aware to turn it on;
+// `[ml]` (Kompress) is on by default → pass --disable-kompress to turn it off.
+function extrasProxyArgs({ codeAware, kompress } = {}) {
+  const args = [];
+  if (codeAware) args.push("--code-aware");
+  if (kompress === false) args.push("--disable-kompress");
+  return args;
+}
+
+export async function startHeadroomProxy({ port = DEFAULT_PORT, codeAware = false, kompress = true } = {}) {
+  const safePort = Number(port) > 0 && Number(port) < 65536 ? Number(port) : DEFAULT_PORT;
+  const binary = findHeadroomBinary();
+  if (!binary) {
+    const err = new Error("Headroom CLI not installed");
+    err.code = "NOT_INSTALLED";
+    throw err;
+  }
+
+  const existing = getManagedPid();
+  if (existing) return { pid: existing, alreadyRunning: true };
+
+  ensureDir();
+  // spawn stdio requires fd numbers, not WriteStream objects.
+  const outFd = fs.openSync(LOG_FILE, "a");
+
+  const args = ["proxy", "--port", String(safePort), ...extrasProxyArgs({ codeAware, kompress })];
+  const child = spawn(binary, args, {
+    stdio: ["ignore", outFd, outFd],
+    detached: true,
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  if (!child.pid) {
+    fs.closeSync(outFd);
+    const err = new Error("Failed to spawn headroom proxy");
+    err.code = "SPAWN_FAILED";
+    throw err;
+  }
+
+  child.unref();
+  writePid(child.pid);
+
+  // Wait until the process either stays alive briefly (success) or exits fast (failure).
+  await new Promise((resolve, reject) => {
+    const startupTimer = setTimeout(() => {
+      if (isPidAlive(child.pid)) resolve();
+      else reject(new Error("headroom proxy exited during startup — see proxy.log"));
+    }, STARTUP_TIMEOUT_MS);
+
+    child.once("exit", (code) => {
+      clearTimeout(startupTimer);
+      clearPid();
+      fs.closeSync(outFd);
+      const e = new Error(`headroom proxy exited early (code=${code}) — see proxy.log`);
+      e.code = "EARLY_EXIT";
+      reject(e);
+    });
+  });
+
+  // Close parent's copy of the fd; child retains its own after unref.
+  fs.closeSync(outFd);
+
+  return { pid: child.pid, alreadyRunning: false };
+}
+
+export function stopHeadroomProxy() {
+  const pid = getManagedPid();
+  if (!pid) return { stopped: false, reason: "not_running" };
+  try {
+    process.kill(pid, "SIGTERM");
+    // Give it a moment, then force if still alive.
+    setTimeout(() => {
+      if (isPidAlive(pid)) {
+        try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+      }
+    }, 2000);
+    clearPid();
+    return { stopped: true, pid };
+  } catch (e) {
+    clearPid();
+    const err = new Error(`Failed to stop headroom proxy: ${e.message}`);
+    err.code = "STOP_FAILED";
+    throw err;
+  }
+}
+
+// Stop the managed proxy (if any), wait for the pid to die, then start again
+// with the given flags. Used when toggling active extras that require a restart.
+export async function restartHeadroomProxy(opts = {}) {
+  const pid = getManagedPid();
+  if (pid) {
+    try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+    // Wait up to ~3s for graceful exit, force-kill if still alive.
+    for (let i = 0; i < 30 && isPidAlive(pid); i++) {
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    if (isPidAlive(pid)) {
+      try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+      await new Promise((r) => setTimeout(r, 300));
+    }
+    clearPid();
+  }
+  return startHeadroomProxy(opts);
+}
+
+export function getHeadroomLogTail(maxLines = 200) {
+  try {
+    if (!fs.existsSync(LOG_FILE)) return "";
+    const content = fs.readFileSync(LOG_FILE, "utf8");
+    const lines = content.split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch { return ""; }
+}
+
+// Install (or upgrade) headroom-ai with the requested compression extras.
+// `extras` is a whitelist from HEADROOM_COMPRESSION_EXTRAS — anything else
+// is rejected to keep the install surface predictable. Always installs the
+// `proxy` base + whatever extras the user picked, regardless of what is
+// already present.
+export async function installHeadroomExtras(extras = []) {
+  const requested = Array.isArray(extras) ? extras.filter((e) => HEADROOM_COMPRESSION_EXTRAS.includes(e)) : [];
+  const py = findPython310();
+  if (!py) {
+    const err = new Error("Python >= 3.10 not found");
+    err.code = "NO_PYTHON";
+    throw err;
+  }
+  if (!findHeadroomBinary()) {
+    const err = new Error("headroom-ai not installed (run `pip install headroom-ai[proxy]` first)");
+    err.code = "NOT_INSTALLED";
+    throw err;
+  }
+  // pip install string is built from a closed set (HEADROOM_COMPRESSION_EXTRAS),
+  // so it cannot be poisoned by caller input — the comma-list is a fixed
+  // ['proxy', ...requested]. No shell interpolation.
+  const extrasList = ["proxy", ...requested].join(",");
+  const spec = `headroom-ai[${extrasList}]`;
+  const args = ["-m", "pip", "install", "--upgrade", spec];
+
+  ensureDir();
+  // Truncate ("w") so the log reflects only the current install for live progress.
+  const outFd = fs.openSync(INSTALL_LOG_FILE, "w");
+  const child = spawn(py, args, {
+    stdio: ["ignore", outFd, outFd],
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.once("error", (e) => { fs.closeSync(outFd); reject(e); });
+    child.once("exit", (code) => {
+      fs.closeSync(outFd);
+      if (code === 0) {
+        const status = getInstalledHeadroomExtras(py);
+        resolve({ success: true, code, spec, extras: requested, ...status });
+      } else {
+        const err = new Error(`pip install exited with code=${code} — see headroom/install.log`);
+        err.code = "INSTALL_FAILED";
+        reject(err);
+      }
+    });
+  });
+}
+
+// Uninstall the marker packages that back a single extra (e.g. `ml` → torch,
+// huggingface-hub). `headroom-ai` base and the `proxy` extra are never removed.
+export async function uninstallHeadroomExtras(extras = []) {
+  const requested = Array.isArray(extras) ? extras.filter((e) => HEADROOM_COMPRESSION_EXTRAS.includes(e)) : [];
+  const py = findPython310();
+  if (!py) {
+    const err = new Error("Python >= 3.10 not found");
+    err.code = "NO_PYTHON";
+    throw err;
+  }
+  const pkgs = [...new Set(requested.flatMap((e) => EXTRA_MARKERS[e] || []))];
+  if (pkgs.length === 0) {
+    const err = new Error("No valid extras to remove");
+    err.code = "INVALID_EXTRAS";
+    throw err;
+  }
+  const args = ["-m", "pip", "uninstall", "-y", ...pkgs];
+
+  ensureDir();
+  const outFd = fs.openSync(INSTALL_LOG_FILE, "w");
+  const child = spawn(py, args, {
+    stdio: ["ignore", outFd, outFd],
+    windowsHide: true,
+    env: { ...process.env },
+  });
+
+  return new Promise((resolve, reject) => {
+    child.once("error", (e) => { fs.closeSync(outFd); reject(e); });
+    child.once("exit", (code) => {
+      fs.closeSync(outFd);
+      if (code === 0) {
+        const status = getInstalledHeadroomExtras(py);
+        resolve({ success: true, code, removed: pkgs, extras: requested, ...status });
+      } else {
+        const err = new Error(`pip uninstall exited with code=${code} — see headroom/install.log`);
+        err.code = "UNINSTALL_FAILED";
+        reject(err);
+      }
+    });
+  });
+}
+
+// Read the tail of the install/uninstall log for live progress in the UI.
+export function getInstallLogTail(maxLines = 15) {
+  try {
+    if (!fs.existsSync(INSTALL_LOG_FILE)) return "";
+    const lines = fs.readFileSync(INSTALL_LOG_FILE, "utf8").split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch { return ""; }
+}

package/src/lib/pxpipe/events.js

@@ -0,0 +1,125 @@
+import fs from "fs";
+import path from "path";
+import { PXPIPE_DIR } from "./install.js";
+
+const EVENTS_FILE = path.join(PXPIPE_DIR, "events.jsonl");
+const ROTATED_FILE = path.join(PXPIPE_DIR, "events.jsonl.1");
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function ensureDir() {
+  if (!fs.existsSync(PXPIPE_DIR)) fs.mkdirSync(PXPIPE_DIR, { recursive: true });
+}
+
+// Fire-and-forget: stats must never break the request path.
+export function appendPxpipeEvent(event) {
+  try {
+    ensureDir();
+    try {
+      const stat = fs.statSync(EVENTS_FILE);
+      if (stat.size > MAX_FILE_BYTES) fs.renameSync(EVENTS_FILE, ROTATED_FILE);
+    } catch { /* no file yet */ }
+    fs.appendFile(EVENTS_FILE, JSON.stringify({ ts: Date.now(), ...event }) + "\n", () => {});
+  } catch { /* ignore */ }
+}
+
+export function readPxpipeEvents({ sinceMs = null, limit = null } = {}) {
+  const events = [];
+  for (const file of [ROTATED_FILE, EVENTS_FILE]) {
+    try {
+      if (!fs.existsSync(file)) continue;
+      for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+        if (!line) continue;
+        try {
+          const ev = JSON.parse(line);
+          if (sinceMs && ev.ts < sinceMs) continue;
+          events.push(ev);
+        } catch { /* skip corrupt line */ }
+      }
+    } catch { /* ignore */ }
+  }
+  events.sort((a, b) => a.ts - b.ts);
+  return limit ? events.slice(-limit) : events;
+}
+
+function emptyTotals() {
+  return {
+    requests: 0, compressed: 0, bypassed: 0, errors: 0,
+    tokensBeforeEst: 0, tokensAfterEst: 0, tokensSavedEst: 0, savedPct: 0,
+    imagesGenerated: 0, compressionTimeMs: 0, avgCompressionMs: 0,
+  };
+}
+
+function accumulate(totals, ev) {
+  totals.requests++;
+  if (ev.applied) {
+    totals.compressed++;
+    totals.tokensBeforeEst += ev.tokensBeforeEst || 0;
+    totals.tokensAfterEst += ev.tokensAfterEst || 0;
+    totals.tokensSavedEst += ev.tokensSavedEst || 0;
+    totals.imagesGenerated += ev.imageCount || 0;
+    totals.compressionTimeMs += ev.durationMs || 0;
+  } else if (ev.reason === "transform_error" || ev.reason === "timeout") {
+    totals.errors++;
+  } else {
+    totals.bypassed++;
+  }
+}
+
+function finalize(totals) {
+  totals.savedPct = totals.tokensBeforeEst > 0
+    ? +((totals.tokensSavedEst / totals.tokensBeforeEst) * 100).toFixed(2)
+    : 0;
+  totals.avgCompressionMs = totals.compressed > 0
+    ? Math.round(totals.compressionTimeMs / totals.compressed)
+    : 0;
+  return totals;
+}
+
+// Aggregated stats for the dashboard: all-time + windowed totals, a daily
+// tokens-saved timeline (last `timelineDays`), and the most recent events.
+export function getPxpipeStats({ timelineDays = 30, recentLimit = 100 } = {}) {
+  const events = readPxpipeEvents();
+  const now = Date.now();
+  const startOfToday = new Date(new Date(now).setHours(0, 0, 0, 0)).getTime();
+
+  const windows = {
+    all: emptyTotals(),
+    today: emptyTotals(),
+    yesterday: emptyTotals(),
+    last7d: emptyTotals(),
+    last30d: emptyTotals(),
+  };
+
+  const timeline = new Map();
+  for (let i = timelineDays - 1; i >= 0; i--) {
+    const day = new Date(startOfToday - i * DAY_MS);
+    timeline.set(day.toISOString().slice(0, 10), { date: day.toISOString().slice(0, 10), tokensSavedEst: 0, compressed: 0, requests: 0 });
+  }
+
+  for (const ev of events) {
+    accumulate(windows.all, ev);
+    if (ev.ts >= startOfToday) accumulate(windows.today, ev);
+    else if (ev.ts >= startOfToday - DAY_MS) accumulate(windows.yesterday, ev);
+    if (ev.ts >= now - 7 * DAY_MS) accumulate(windows.last7d, ev);
+    if (ev.ts >= now - 30 * DAY_MS) accumulate(windows.last30d, ev);
+
+    const key = new Date(ev.ts).toISOString().slice(0, 10);
+    const bucket = timeline.get(key);
+    if (bucket) {
+      bucket.requests++;
+      if (ev.applied) {
+        bucket.compressed++;
+        bucket.tokensSavedEst += ev.tokensSavedEst || 0;
+      }
+    }
+  }
+
+  for (const w of Object.values(windows)) finalize(w);
+
+  return {
+    windows,
+    timeline: [...timeline.values()],
+    recent: events.slice(-recentLimit).reverse(),
+  };
+}

package/src/lib/pxpipe/install.js

@@ -0,0 +1,123 @@
+import fs from "fs";
+import path from "path";
+import { spawn, execSync } from "child_process";
+import { DATA_DIR } from "@/lib/dataDir.js";
+
+export const PXPIPE_DIR = path.join(DATA_DIR, "pxpipe");
+export const PXPIPE_PACKAGE = "pxpipe-proxy";
+const INSTALL_LOG = path.join(PXPIPE_DIR, "install.log");
+const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+
+const IS_WIN = process.platform === "win32";
+const NPM_CMD = IS_WIN ? "npm.cmd" : "npm";
+
+// Same PATH extension trick as headroom/detect.js: packaged/launchd environments
+// often miss the Node bin dirs.
+const EXTRA_BINS = IS_WIN
+  ? [`${process.env.ProgramFiles || ""}\\nodejs`, `${process.env.APPDATA || ""}\\npm`]
+  : ["/usr/local/bin", "/opt/homebrew/bin", `${process.env.HOME || ""}/.local/bin`, "/usr/bin", "/bin"];
+const EXTENDED_PATH = [...EXTRA_BINS, process.env.PATH || ""].filter(Boolean).join(path.delimiter);
+
+let installInFlight = null;
+
+function ensureDir() {
+  if (!fs.existsSync(PXPIPE_DIR)) fs.mkdirSync(PXPIPE_DIR, { recursive: true });
+}
+
+export function packageRoot() {
+  return path.join(PXPIPE_DIR, "node_modules", PXPIPE_PACKAGE);
+}
+
+export function libraryEntry() {
+  return path.join(packageRoot(), "dist", "core", "library.js");
+}
+
+export function findNpm() {
+  try {
+    const out = execSync(`${IS_WIN ? "where" : "which"} npm`, {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    }).toString().trim();
+    return out ? out.split(/\r?\n/)[0].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+// { installed, version, path } — installed means the library entry exists on disk.
+export function getInstallInfo() {
+  try {
+    const pkgJson = path.join(packageRoot(), "package.json");
+    if (!fs.existsSync(pkgJson) || !fs.existsSync(libraryEntry())) {
+      return { installed: false, version: null, path: null };
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgJson, "utf8"));
+    return { installed: true, version: pkg.version || null, path: packageRoot() };
+  } catch {
+    return { installed: false, version: null, path: null };
+  }
+}
+
+export function isInstalling() {
+  return installInFlight !== null;
+}
+
+// Install (or repair by reinstalling) pxpipe-proxy into DATA_DIR/pxpipe.
+// Serialized: concurrent calls await the same run.
+export function installPxpipe() {
+  if (installInFlight) return installInFlight;
+  installInFlight = runInstall().finally(() => { installInFlight = null; });
+  return installInFlight;
+}
+
+async function runInstall() {
+  const npm = findNpm();
+  if (!npm) {
+    const err = new Error("npm not found on PATH — Node.js/npm is required to install PXPIPE");
+    err.code = "NPM_NOT_FOUND";
+    throw err;
+  }
+
+  ensureDir();
+  const pkgJson = path.join(PXPIPE_DIR, "package.json");
+  if (!fs.existsSync(pkgJson)) {
+    fs.writeFileSync(pkgJson, JSON.stringify({ name: "zevairouter-pxpipe-host", private: true }, null, 2));
+  }
+
+  const outFd = fs.openSync(INSTALL_LOG, "a");
+  fs.writeSync(outFd, `\n[${new Date().toISOString()}] npm install ${PXPIPE_PACKAGE}@latest\n`);
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(npm, ["install", `${PXPIPE_PACKAGE}@latest`, "--no-audit", "--no-fund", "--omit=dev"], {
+      cwd: PXPIPE_DIR,
+      stdio: ["ignore", outFd, outFd],
+      windowsHide: true,
+      env: { ...process.env, PATH: EXTENDED_PATH },
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("npm install timed out after 5 minutes — see install.log"));
+    }, INSTALL_TIMEOUT_MS);
+    child.once("error", (e) => { clearTimeout(timer); reject(e); });
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve();
+      else reject(new Error(`npm install exited with code ${code} — see install.log`));
+    });
+  }).finally(() => fs.closeSync(outFd));
+
+  const info = getInstallInfo();
+  if (!info.installed) throw new Error("install finished but package is missing — see install.log");
+  return info;
+}
+
+export function getInstallLogTail(maxLines = 200) {
+  try {
+    if (!fs.existsSync(INSTALL_LOG)) return "";
+    const lines = fs.readFileSync(INSTALL_LOG, "utf8").split(/\r?\n/).filter(Boolean);
+    return lines.slice(-maxLines).join("\n");
+  } catch {
+    return "";
+  }
+}