@openagents-org/agent-launcher 0.2.168 → 0.2.170

package/src/installer.js

@@ -8,10 +8,32 @@ const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache, a
 const { EnvManager } = require('./env');
 const { nodeDistUrls, installRegistry } = require('./mirrors');
 const { readinessReason, REASON } = require('./adapters/health-status');
+const { checkInstallPrereqs, missingPrereqError } = require('./install-preflight');
+const { detectShadowedNodeShims, shadowedNodeWarning } = require('./node-shims');
 
 const STATUS_CACHE_TTL_MS = 10000;
 const statusCache = new Map();
 
+/**
+ * How long a streaming install may produce NO output before it is treated as
+ * hung and killed. Generous on purpose: a slow npm postinstall or a large
+ * extraction can legitimately go quiet for a while, and killing a working
+ * install is worse than waiting. Set OPENAGENTS_INSTALL_STALL_MS=0 to disable.
+ */
+const INSTALL_STALL_MS = (() => {
+  const raw = process.env.OPENAGENTS_INSTALL_STALL_MS;
+  if (raw === undefined || raw === '') return 10 * 60 * 1000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 10 * 60 * 1000;
+})();
+
+/**
+ * How often the stall watchdog checks. Capped at half the stall budget so the
+ * poll granularity never dominates the deadline (matters for a short budget in
+ * tests; in production the 15s ceiling applies).
+ */
+const STALL_POLL_MS = Math.max(50, Math.min(15000, Math.floor(INSTALL_STALL_MS / 2) || 15000));
+
 // Version detection is comparatively expensive (spawns `<bin> --version`), so
 // results are cached briefly and invalidated on install/uninstall.
 const VERSION_CACHE_TTL_MS = 60000;
@@ -609,7 +631,12 @@ class Installer {
         env: getEnhancedEnv(),
         timeout: 10000,
       }).trim();
-      const match = raw.match(/(\d+[\d.]+\d+)/);
+      // The optional `-prerelease` tail is NOT decoration. An agent pinned to a
+      // preview release (`@deepseek-ai/dsh@0.1.0-rc.6`) is gated on the exact
+      // version, and dropping the suffix reported a correctly installed rc.6 as
+      // plain `0.1.0` — which then failed its own gate. Agents without a
+      // prerelease segment match exactly as before.
+      const match = raw.match(/(\d+[\d.]+\d+(?:-[0-9A-Za-z.-]+)?)/);
       version = match ? match[1] : (raw.split('\n')[0] || null);
     } catch {}
 
@@ -618,14 +645,52 @@ class Installer {
   }
 
   /**
-   * Evaluate `install.min_version` against a detected version. Generic for any
+   * Evaluate a registry version gate against a detected version. Generic for any
    * agent. Returns { compatible: true|false|null, minVersion, message }.
-   *   • no min_version declared → compatible:true (gate disabled)
-   *   • version unparseable      → compatible:null  ("unknown", don't false-pass)
-   *   • version < min_version    → compatible:false (block + upgrade hint)
-   *   • version >= min_version   → compatible:true
+   *
+   * Two gate shapes, in priority order:
+   *
+   *   `install.supported_version` — EXACT match. For agents pinned to an
+   *   upstream preview whose configuration can change between releases, a floor
+   *   is the wrong shape: it happily admits the next preview, which is precisely
+   *   the version the adapter has not been written against. Declared by
+   *   deepseek (dsh is a developer preview).
+   *
+   *   `install.min_version` / `check_ready.min_version` — a floor (>=). The
+   *   original behaviour, unchanged for every agent that does not declare
+   *   supported_version.
    */
   _evaluateCompatibility(entry, version) {
+    const supported = (entry && entry.install && entry.install.supported_version) || null;
+    if (supported) {
+      // Compare the version-shaped token from each side, prerelease included.
+      // `compareVersions` cannot be used: it strips `-rc.N`, so rc.5 and rc.6
+      // would compare equal and the exact gate would admit the wrong preview.
+      const norm = (v) => {
+        const m = String(v == null ? '' : v).match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/);
+        return m ? m[0] : null;
+      };
+      const got = norm(version);
+      const want = norm(supported);
+      if (!got) {
+        return {
+          compatible: null,
+          minVersion: supported,
+          message: `Version unknown (requires exactly ${supported})`,
+        };
+      }
+      if (got !== want) {
+        return {
+          compatible: false,
+          minVersion: supported,
+          message:
+            `${(entry.label || entry.name || 'This agent')} ${got} is not supported — ` +
+            `it is pinned to ${want} exactly (upstream ships it as a developer preview).`,
+        };
+      }
+      return { compatible: true, minVersion: supported, message: null };
+    }
+
     // Opt-in floor declared under either install.min_version or
     // check_ready.min_version (e.g. cline pins check_ready.min_version).
     const minVersion = (entry && (
@@ -825,6 +890,17 @@ class Installer {
         }
         return 'absent';
       }
+      // A named field, for a file that exists in both states. Gemini's
+      // google_accounts.json is written on install and records a signed-OUT
+      // account as `active: null`, so its existence proves nothing — only the
+      // field does. Still content-free: the value is tested for emptiness, never
+      // read out, logged or returned.
+      if (checkReady.creds_key) {
+        const parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        const value = parsed && typeof parsed === 'object' ? parsed[checkReady.creds_key] : null;
+        const filled = typeof value === 'string' ? !!value.trim() : !!value;
+        return filled ? 'present' : 'absent';
+      }
       return st.size > 0 ? 'present' : 'absent';
     } catch {
       return 'unreadable';
@@ -922,6 +998,8 @@ class Installer {
       return { success: true, output: `${entry.label || agentType} uses direct API mode; no binary install needed.` };
     }
 
+    this._assertPrereqs(agentType, entry);
+
     let cmd = this._getInstallCommand(entry.install);
     if (!cmd) {
       throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
@@ -991,6 +1069,8 @@ class Installer {
       return { success: true, command: 'api-only' };
     }
 
+    this._assertPrereqs(agentType, entry, onData);
+
     let rawCmd = this._getInstallCommand(entry.install);
     if (!rawCmd) {
       throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
@@ -1073,14 +1153,30 @@ class Installer {
 
     return new Promise((resolve, reject) => {
       // windowsHide stops a console window from flashing up on every install.
-      const proc = spawn(spawnFile, spawnArgs, { shell: useShell, env, cwd: installCwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+      //
+      // detached (Unix): puts the installer in its own process group, which is
+      // what makes the stall watchdog able to stop the WHOLE tree. Without it
+      // the direct child is a shell and the actual work — curl, git, uv — runs
+      // in grandchildren that survive a signal aimed at the shell. It does not
+      // change lifetime semantics: an install was never killed by the launcher
+      // exiting, before or after this.
+      const proc = spawn(spawnFile, spawnArgs, {
+        shell: useShell,
+        env,
+        cwd: installCwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        detached: process.platform !== 'win32',
+      });
 
       if (proc.stdout) proc.stdout.setEncoding('utf-8');
       if (proc.stderr) proc.stderr.setEncoding('utf-8');
 
       let outputTail = '';
+      let lastOutputAt = Date.now();
       const captureOutput = (d) => {
         const text = String(d);
+        lastOutputAt = Date.now();
         outputTail = (outputTail + text).slice(-4000);
         if (onData) onData(text);
       };
@@ -1088,8 +1184,40 @@ class Installer {
       if (proc.stdout) proc.stdout.on('data', captureOutput);
       if (proc.stderr) proc.stderr.on('data', captureOutput);
 
-      proc.on('error', (err) => reject(err));
+      // Stall watchdog. A third-party installer that decides to wait — hermes's
+      // install.sh polls for up to 900s after asking macOS for the developer
+      // tools — otherwise hangs this promise indefinitely, and the only visible
+      // symptom is a progress bar that stopped moving. The preflight now
+      // prevents that specific case, but the general shape (a download that
+      // never returns, a prompt on a stdin nobody is reading) is not specific
+      // to any one installer, so time is bounded here for all of them.
+      let stallTimer = null;
+      let stalled = false;
+      const clearStallTimer = () => {
+        if (stallTimer) { clearInterval(stallTimer); stallTimer = null; }
+      };
+      if (INSTALL_STALL_MS > 0) {
+        stallTimer = setInterval(() => {
+          if (Date.now() - lastOutputAt < INSTALL_STALL_MS) return;
+          stalled = true;
+          clearStallTimer();
+          const minutes = Math.round(INSTALL_STALL_MS / 60000);
+          const msg = `Install stalled: no output for ${minutes} minutes. `
+            + 'The installer was stopped. It may be waiting on a prompt, or on a '
+            + 'download that never returns.';
+          if (onData) onData(`\n${msg}\n`);
+          this._killProcessTree(proc);
+          reject(new Error(msg));
+        }, STALL_POLL_MS);
+        // Never hold the event loop open for the watchdog alone.
+        if (typeof stallTimer.unref === 'function') stallTimer.unref();
+      }
+
+      proc.on('error', (err) => { clearStallTimer(); reject(err); });
       proc.on('close', (code) => {
+        clearStallTimer();
+        // The watchdog already rejected; this close is the kill it performed.
+        if (stalled) return;
         if (code === 0) {
           // Aider-only: confirm a real, genuine binary exists before recording
           // the install (verify-before-mark; never writes a marker on
@@ -1127,6 +1255,13 @@ class Installer {
               return;
             }
             if (onData) onData(`\nHermes CLI resolved: ${hermes.path}\n`);
+            // Its installer may have repointed the machine's node/npm/npx at
+            // its own Node. See node-shims.js — we report, never rewrite.
+            const shimWarning = shadowedNodeWarning(
+              entry.label || agentType,
+              detectShadowedNodeShims(),
+            );
+            if (shimWarning && onData) onData(`${shimWarning}\n`);
           }
           // Cursor-only: same failure shape as hermes above — its installer
           // exits 0 after a failed download. See _verifyCursorBinary.
@@ -1307,6 +1442,51 @@ class Installer {
     });
   }
 
+  /**
+   * Refuse to run a third-party installer whose hard dependencies are missing.
+   *
+   * See install-preflight.js for why this is worth doing before the spawn: the
+   * scripts we shell out to handle a missing dependency by opening OS dialogs
+   * and sleeping for minutes, which the launcher can only render as a frozen
+   * progress bar.
+   */
+  _assertPrereqs(agentType, entry, onData, check = checkInstallPrereqs) {
+    const { ok, missing } = check(entry);
+    if (ok) return;
+    const err = missingPrereqError(entry.label || agentType, missing);
+    if (onData) onData(`${err.message}\n`);
+    throw err;
+  }
+
+  /**
+   * Stop a spawned installer and everything it started.
+   *
+   * The child is usually a shell (`curl … | bash`, powershell) whose real work
+   * happens in grandchildren, so signalling the direct child alone leaves the
+   * download running. On Unix the process group is signalled; on Windows
+   * taskkill /T walks the tree.
+   */
+  _killProcessTree(proc) {
+    if (!proc || proc.exitCode !== null) return;
+    try {
+      if (process.platform === 'win32') {
+        try {
+          execSync(`taskkill /F /T /PID ${proc.pid}`, {
+            stdio: 'ignore', timeout: 5000, windowsHide: true,
+          });
+        } catch { proc.kill(); }
+        return;
+      }
+      try { process.kill(-proc.pid, 'SIGTERM'); } catch { proc.kill('SIGTERM'); }
+      setTimeout(() => {
+        if (proc.exitCode !== null) return;
+        try { process.kill(-proc.pid, 'SIGKILL'); } catch { proc.kill('SIGKILL'); }
+      }, 5000).unref();
+    } catch {
+      /* the process is already gone */
+    }
+  }
+
   /**
    * Get install command for current platform.
    */
@@ -1326,11 +1506,18 @@ class Installer {
     // npm install -g <pkg> → npm uninstall --prefix <runtimeDir> <pkg>
     if (installCmd.includes('npm install')) {
       const prefixDir = agentType ? getRuntimePrefix(agentType) : path.join(os.homedir(), '.openagents', 'nodejs');
-      return installCmd
+      const cmd = installCmd
         .replace('npm install -g', `npm uninstall --prefix "${prefixDir}"`)
-        .replace('npm install', 'npm uninstall')
-        .replace(/@latest/g, '')
-        .replace(/@[\d.]+/g, '');
+        .replace('npm install', 'npm uninstall');
+      // Drop the version spec, whatever shape it takes. This used to be two
+      // blind global replaces — `@latest` and `@[\d.]+` — and the second one
+      // understood only digits and dots, so a PRERELEASE pin was cut in half:
+      //   @deepseek-ai/dsh@0.1.0-rc.6  →  @deepseek-ai/dsh-rc.6
+      // npm exits 0 when asked to remove a package that is not installed, so
+      // the uninstall reported success, removed nothing, and left the agent
+      // looking installed forever. Anchoring to the package token at the end of
+      // the command makes the shape of the version irrelevant.
+      return cmd.replace(/(\s@?[\w-]+(?:\/[\w-]+)?)@\S+\s*$/, '$1');
     }
 
     // pip install <pkg> → pip uninstall -y <pkg>

package/src/node-shims.js

@@ -0,0 +1,103 @@
+/**
+ * Detecting an agent installer that has taken over the machine's `node`.
+ *
+ * Hermes's install.sh, when it decides the system Node is too old, downloads
+ * its own and then does this:
+ *
+ *   ln -sf "$HERMES_HOME/node/bin/node" "$HOME/.local/bin/node"
+ *   ln -sf "$HERMES_HOME/node/bin/npm"  "$HOME/.local/bin/npm"
+ *   ln -sf "$HERMES_HOME/node/bin/npx"  "$HOME/.local/bin/npx"
+ *
+ * `ln -sf` overwrites. On a machine where ~/.local/bin comes before nvm or
+ * Homebrew on PATH — a very common layout — the user's default `node` silently
+ * becomes the agent's, for every shell and every unrelated project, and npm's
+ * global prefix is rewritten to ~/.local along with it. Nothing announces this,
+ * and nothing connects a project that suddenly builds differently back to
+ * having installed an agent.
+ *
+ * This module only looks and reports. Rewriting a user's PATH or deleting their
+ * symlinks would be a second uninvited change on top of the first, and the
+ * agent's Node may be exactly what they want. Telling them precisely what
+ * happened, and how to undo it, is the part that was missing.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * node/npm/npx under `linkDir` that are symlinks into `ownerDir`, together with
+ * whether they shadow another installation the user already had.
+ *
+ * @param {object} [deps] - seams for tests; production passes nothing.
+ * @returns {{ shims: Array<{name: string, link: string, target: string}>, shadowed: string|null }}
+ */
+function detectShadowedNodeShims(deps = {}) {
+  const home = deps.home || os.homedir();
+  const linkDir = deps.linkDir || path.join(home, '.local', 'bin');
+  const ownerDir = deps.ownerDir || path.join(home, '.hermes', 'node', 'bin');
+  const readLink = deps.readLink || defaultReadLink;
+  const exists = deps.exists || ((p) => fs.existsSync(p));
+  const entries = deps.pathEntries || (process.env.PATH || '').split(path.delimiter);
+
+  const shims = [];
+  for (const name of ['node', 'npm', 'npx']) {
+    const link = path.join(linkDir, name);
+    const target = readLink(link);
+    if (!target) continue;
+    const resolved = path.resolve(linkDir, target);
+    if (resolved === path.join(ownerDir, name) || resolved.startsWith(ownerDir + path.sep)) {
+      shims.push({ name, link, target: resolved });
+    }
+  }
+  if (shims.length === 0) return { shims: [], shadowed: null };
+
+  // Only a problem if the user HAD another node. On a machine with none, these
+  // symlinks are the installer doing something useful.
+  const normalized = entries.map((d) => d.trim()).filter(Boolean);
+  const linkIndex = normalized.indexOf(linkDir);
+  const after = linkIndex === -1 ? normalized : normalized.slice(linkIndex + 1);
+  for (const dir of after) {
+    if (dir === linkDir) continue;
+    const candidate = path.join(dir, 'node');
+    try {
+      if (exists(candidate)) return { shims, shadowed: candidate };
+    } catch {
+      /* unreadable dir on PATH — skip */
+    }
+  }
+  return { shims, shadowed: null };
+}
+
+/** lstat + readlink, or null when the path is absent or not a symlink. */
+function defaultReadLink(p) {
+  try {
+    if (!fs.lstatSync(p).isSymbolicLink()) return null;
+    return fs.readlinkSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The warning text, or null when there is nothing worth saying. Written to be
+ * read in an install log by someone who did not expect any of this.
+ */
+function shadowedNodeWarning(agentLabel, detection) {
+  if (!detection || detection.shims.length === 0 || !detection.shadowed) return null;
+  const names = detection.shims.map((s) => s.name).join(', ');
+  const dir = path.dirname(detection.shims[0].link);
+  return [
+    '',
+    `Note: the ${agentLabel} installer replaced ${names} in ${dir} with links to its own Node.`,
+    `That now takes precedence over ${detection.shadowed} for every shell on this machine,`,
+    'so other projects will build with the agent\'s Node version from here on.',
+    '',
+    'To put your own Node back, remove the links (this does not affect the agent):',
+    `  rm -f ${detection.shims.map((s) => s.link).join(' ')}`,
+  ].join('\n');
+}
+
+module.exports = { detectShadowedNodeShims, shadowedNodeWarning };