@openagents-org/agent-launcher 0.2.186 → 0.2.188

package/src/installer.js

@@ -4,7 +4,18 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, exec } = require('child_process');
-const { whichBinary, getEnhancedEnv, getRuntimePrefix, clearBinaryLookupCache, aiderBinDirs, resolveBinaryInKnownDirs } = require('./paths');
+const {
+  whichBinary,
+  getEnhancedEnv,
+  getRuntimePrefix,
+  clearBinaryLookupCache,
+  aiderBinDirs,
+  resolveBinaryInKnownDirs,
+  resolveManagedNpmBinary,
+  resolveManagedNpmPackageBin,
+  isNodeShebangScript,
+  whereAll,
+} = require('./paths');
 const { isWslBinary, bridgedCommandString, wslHomeUnc } = require('./wsl');
 const { canBlock } = require('./probe-mode');
 const { EnvManager } = require('./env');
@@ -610,6 +621,14 @@ class Installer {
     if (/\.(mjs|cjs|js)$/i.test(binary)) {
       return `"${this._nodeBinary()}" "${binary}" --version`;
     }
+    // Same problem, no extension to spot it by: npm's package bin is often an
+    // extensionless `#!/usr/bin/env node` script (node_modules/cline/bin/cline),
+    // which is what we resolve whenever npm wrote no .cmd shim. cmd.exe cannot
+    // run it — the probe dies with "is not recognized as an internal or external
+    // command" — and the agent then shows up in the app with no version at all.
+    if (isNodeShebangScript(binary)) {
+      return `"${this._nodeBinary()}" "${binary}" --version`;
+    }
     return `"${binary}" --version`;
   }
 
@@ -1083,6 +1102,19 @@ class Installer {
       throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
     }
 
+    let bootstrapEnv = this._buildShellEnv();
+    let installEnv;
+    if (agentType === 'hermes' && process.platform === 'win32') {
+      const prepared = this._prepareWindowsPowerShellInstall(cmd, bootstrapEnv);
+      cmd = prepared.command;
+      bootstrapEnv = prepared.env;
+      installEnv = prepared.env;
+    }
+
+    // Same uv bootstrap the streaming path does — `agn install hermes` and the
+    // workspace's remote create must not behave differently from the button.
+    await this._bootstrapManagedUv(agentType, bootstrapEnv, null);
+
     // Use bundled node/npm if system npm not available
     if (cmd.startsWith('npm install')) {
       const prefixDir = getRuntimePrefix(agentType);
@@ -1091,7 +1123,7 @@ class Installer {
       cmd = this._resolveNpmCommand(args);
     }
 
-    const output = await this._execShell(cmd);
+    const output = await this._execShell(cmd, 300000, installEnv);
 
     // Aider-only: the curl/uv/pipx installer can exit 0 without landing a
     // runnable (or genuine) binary, so verify the real CLI exists BEFORE
@@ -1159,9 +1191,23 @@ class Installer {
       await this.installNodejs(onData);
     }
 
-    const env = this._buildShellEnv();
+    let env = this._buildShellEnv();
     const isWin = process.platform === 'win32';
 
+    // Hermes's registry command names the inbox Windows PowerShell host for
+    // compatibility, but some Windows environments expose only PowerShell 7.
+    // Resolve the host that actually exists and keep module paths from the
+    // launcher's own PowerShell runtime out of both installer processes.
+    if (agentType === 'hermes' && isWin) {
+      const prepared = this._prepareWindowsPowerShellInstall(rawCmd, env);
+      rawCmd = prepared.command;
+      env = prepared.env;
+    }
+
+    // Hand the installer a uv it can use, so its own fragile bootstrap is
+    // never reached. No-op for every agent but hermes on Windows.
+    await this._bootstrapManagedUv(agentType, env, onData);
+
     // Build the spawn invocation. Three shapes:
     //   1. npm install via bundled `node npm-cli.js` — argv array, no shell.
     //      Path-safe under non-ASCII home dirs on Windows (preferred).
@@ -1297,15 +1343,27 @@ class Installer {
         // The watchdog already rejected; this close is the kill it performed.
         if (stalled) return;
         if (code === 0) {
+          // An installer that exits 0 without leaving a runnable binary is
+          // the class below (aider/amp/hermes/cursor). The "…could not be
+          // found" sentence alone says nothing about WHY, and the reason is
+          // sitting in the output we just captured — hermes's install.ps1, for
+          // one, prints "[X] Installation failed: uv installation failed" and
+          // exits 0, and without the tail the launcher could only shrug
+          // ("The installer stopped before it could finish"). Carry the tail
+          // into the rejection so the message the user sees, and the copy that
+          // classifies it, both have the real error in them.
+          const failVerify = (message) => {
+            const tail = outputTail.trim();
+            if (onData) onData(`\n${message}\n`);
+            reject(new Error(tail ? `${message}\n\nInstaller output:\n${tail}` : message));
+          };
           // Aider-only: confirm a real, genuine binary exists before recording
           // the install (verify-before-mark; never writes a marker on
           // failure). Other agent types are unaffected.
           if (agentType === 'aider') {
             const aider = this._verifyAiderBinary();
             if (!aider) {
-              const msg = this._aiderBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._aiderBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nAider CLI resolved: ${aider.path}${aider.version ? ` (${aider.version})` : ''}\n`);
@@ -1315,9 +1373,7 @@ class Installer {
           if (agentType === 'amp') {
             const amp = this._verifyAmpBinary();
             if (!amp) {
-              const msg = this._ampBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._ampBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nAmp CLI resolved: ${amp.path}${amp.version ? ` (${amp.version})` : ''}\n`);
@@ -1327,9 +1383,7 @@ class Installer {
           if (agentType === 'hermes') {
             const hermes = this._verifyHermesBinary();
             if (!hermes) {
-              const msg = this._hermesBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._hermesBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nHermes CLI resolved: ${hermes.path}\n`);
@@ -1346,9 +1400,7 @@ class Installer {
           if (agentType === 'cursor') {
             const cursor = this._verifyCursorBinary();
             if (!cursor) {
-              const msg = this._cursorBinaryNotFoundMessage();
-              if (onData) onData(`\n${msg}\n`);
-              reject(new Error(msg));
+              failVerify(this._cursorBinaryNotFoundMessage());
               return;
             }
             if (onData) onData(`\nCursor CLI resolved: ${cursor.path}\n`);
@@ -1683,29 +1735,7 @@ class Installer {
     const pkgName = npmPkg || npmPkgFromCmd;
     if (!pkgName) return null; // script-installed agent: nothing of ours to prefer
 
-    const prefixes = [
-      path.join(getRuntimePrefix(agentType), 'node_modules'),
-      path.join(os.homedir(), '.openagents', 'nodejs', 'node_modules'),
-    ];
-    const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
-    for (const modules of prefixes) {
-      try {
-        if (!fs.existsSync(path.join(modules, pkgName, 'package.json'))) continue;
-      } catch { continue; }
-      for (const name of [binary, ...aliases]) {
-        for (const ext of exts) {
-          const candidate = path.join(modules, '.bin', `${name}${ext}`);
-          try {
-            if (fs.existsSync(candidate)) return candidate;
-          } catch {}
-        }
-      }
-      // npm does not always link the root package's own bin — same case
-      // _resolvePackageBin exists for.
-      const own = this._resolvePackageBin(agentType, entry, binary);
-      if (own) return own;
-    }
-    return null;
+    return resolveManagedNpmBinary(agentType, pkgName, [binary, ...aliases]);
   }
 
   /**
@@ -1723,25 +1753,7 @@ class Installer {
       if (m) npmPkgFromCmd = m[1];
     }
     const pkgName = npmPkg || npmPkgFromCmd || binary;
-    const prefixes = [
-      path.join(getRuntimePrefix(agentType), 'node_modules'),
-      path.join(os.homedir(), '.openagents', 'nodejs', 'node_modules'),
-    ];
-    for (const modules of prefixes) {
-      const pkgDir = path.join(modules, pkgName);
-      const pkgJsonPath = path.join(pkgDir, 'package.json');
-      try {
-        if (!fs.existsSync(pkgJsonPath)) continue;
-        const bin = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).bin;
-        let rel = null;
-        if (typeof bin === 'string') rel = bin;
-        else if (bin && typeof bin === 'object') rel = bin[binary] || bin[pkgName] || Object.values(bin)[0];
-        if (!rel) continue;
-        const abs = path.join(pkgDir, rel);
-        if (fs.existsSync(abs)) return abs;
-      } catch {}
-    }
-    return null;
+    return resolveManagedNpmPackageBin(agentType, pkgName, binary);
   }
 
   // -- Markers --
@@ -1907,6 +1919,168 @@ class Installer {
     return env;
   }
 
+  /**
+   * Build an isolated environment for a PowerShell child process.
+   *
+   * PowerShell constructs PSModulePath for the host that is starting. Passing
+   * through a value created by another host (for example pwsh -> powershell)
+   * can make it load binary modules from the wrong runtime. Remove every
+   * casing of the key and let the child rebuild its own defaults.
+   */
+  _powerShellChildEnv(env) {
+    const childEnv = { ...env };
+    for (const key of Object.keys(childEnv)) {
+      if (key.toLowerCase() === 'psmodulepath') delete childEnv[key];
+    }
+    return childEnv;
+  }
+
+  /**
+   * Resolve a PowerShell host without assuming Windows PowerShell 5.1 exists.
+   * Prefer the Windows inbox host for compatibility with existing installer
+   * scripts, then fall back to pwsh from PATH or its standard install folder.
+   *
+   * `platform` and `exists` are seams so the Windows rules run on every CI
+   * platform without touching the real machine.
+   */
+  _resolveWindowsPowerShellHost(
+    env,
+    platform = process.platform,
+    exists = fs.existsSync,
+  ) {
+    if (platform !== 'win32') return null;
+    const value = (name) => {
+      const key = Object.keys(env).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+      return key ? env[key] : '';
+    };
+    const systemRoot = value('SystemRoot') || 'C:\\Windows';
+    const windowsPowerShell = path.win32.join(
+      systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe',
+    );
+    if (exists(windowsPowerShell)) return windowsPowerShell;
+
+    for (const rawDir of (value('Path') || '').split(';')) {
+      const dir = rawDir.trim().replace(/^"|"$/g, '');
+      if (!dir) continue;
+      const candidate = path.win32.join(dir, 'pwsh.exe');
+      if (exists(candidate)) return candidate;
+    }
+
+    const programFiles = value('ProgramFiles') || 'C:\\Program Files';
+    const standardPwsh = path.win32.join(programFiles, 'PowerShell', '7', 'pwsh.exe');
+    return exists(standardPwsh) ? standardPwsh : null;
+  }
+
+  /** Replace only the leading PowerShell executable in an install command. */
+  _retargetPowerShellCommand(command, executable) {
+    const hostPrefix = /^(\s*)(?:"[^"]*\\(?:powershell|pwsh)(?:\.exe)?"|(?:powershell|pwsh)(?:\.exe)?)\s+/i;
+    return command.replace(hostPrefix, `$1"${executable}" `);
+  }
+
+  /** Prepare a Windows PowerShell install without leaking another host's modules. */
+  _prepareWindowsPowerShellInstall(
+    command,
+    env,
+    platform = process.platform,
+    exists = fs.existsSync,
+  ) {
+    const host = this._resolveWindowsPowerShellHost(env, platform, exists);
+    if (!host) {
+      throw new Error('Windows PowerShell or PowerShell 7 is required for this installer.');
+    }
+    return {
+      command: this._retargetPowerShellCommand(command, host),
+      env: this._powerShellChildEnv(env),
+      host,
+    };
+  }
+
+  /**
+   * Put uv where hermes's installer looks for it, before that installer runs.
+   *
+   * hermes's Install-Uv bootstraps its OWN copy at <HERMES_HOME>\bin\uv.exe
+   * ("no PATH probing, no conda guards" — a uv already on the machine is not
+   * used), and it does that by spawning a child PowerShell for the astral
+   * installer WITHOUT -NoProfile. When that child cannot run — a profile that
+   * throws, a PSModulePath that cannot load built-in modules — uv never lands,
+   * and hermes prints "Installation failed: uv installation failed" and exits
+   * 0 anyway, leaving a half-installed agent.
+   *
+   * Doing the same download ourselves, from an environment we control, takes
+   * that fragile hop out of the install. Its early
+   * `if (Test-Path $managedUv) { return $true }` then short-circuits the whole
+   * step. Best-effort by design: any failure here is logged and the install
+   * proceeds exactly as it does today, so this can only add successes.
+   *
+   * Windows-only. The Unix install.sh runs the uv installer through `sh`,
+   * which reads no profile and has never shown this failure.
+   *
+   * `platform` and `exists` are seams for tests; production passes neither.
+   * They must be threaded into the host lookup below — without them it falls
+   * back to the real filesystem and can never resolve a Windows path on a
+   * Linux or macOS CI runner, which silently turned every assertion about the
+   * spawn into a no-op.
+   */
+  async _bootstrapManagedUv(
+    agentType,
+    env,
+    onData,
+    platform = process.platform,
+    exists = fs.existsSync,
+  ) {
+    if (agentType !== 'hermes' || platform !== 'win32') return;
+    const home = os.homedir();
+    const hermesHome = env.HERMES_HOME
+      || path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'hermes');
+    const binDir = path.join(hermesHome, 'bin');
+    const managedUv = path.join(binDir, 'uv.exe');
+    try { if (exists(managedUv)) return; } catch { return; }
+
+    if (onData) onData(`\nProvisioning uv for Hermes into ${binDir} ...\n`);
+    try {
+      const psExe = this._resolveWindowsPowerShellHost(env, platform, exists);
+      if (!psExe) throw new Error('no Windows PowerShell or PowerShell 7 host found');
+      fs.mkdirSync(binDir, { recursive: true });
+      await new Promise((resolve, reject) => {
+        // `_spawnForTest` is a seam so a test can inspect the environment this
+        // child is given; production never sets it.
+        const spawnFn = this._spawnForTest || require('child_process').spawn;
+        const child = spawnFn(
+          psExe,
+          [
+            '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+            // Force UTF-8 out of the child before it prints anything. A
+            // Chinese-locale Windows emits GBK, which reaches the install log
+            // as mojibake — the user saw a wall of "??" where the error was.
+            '-Command',
+            '[Console]::OutputEncoding=[Text.Encoding]::UTF8; irm https://astral.sh/uv/install.ps1 | iex',
+          ],
+          {
+            // UV_INSTALL_DIR is what the astral script honours; it is the same
+            // variable hermes sets for its own attempt.
+            env: this._powerShellChildEnv({ ...env, UV_INSTALL_DIR: binDir }),
+            cwd: home,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+          },
+        );
+        const relay = (d) => { if (onData) onData(String(d)); };
+        if (child.stdout) child.stdout.on('data', relay);
+        if (child.stderr) child.stderr.on('data', relay);
+        child.on('error', reject);
+        child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`exit code ${code}`))));
+      });
+    } catch (e) {
+      if (onData) onData(`\nCould not provision uv ahead of the installer (${e.message}); letting Hermes try its own.\n`);
+      return;
+    }
+    if (onData) {
+      onData(fs.existsSync(managedUv)
+        ? `uv ready at ${managedUv}\n`
+        : `uv installer finished but ${managedUv} is absent; letting Hermes try its own.\n`);
+    }
+  }
+
   /**
    * True if `node` exists outside the bundled launcher directory. Uses raw
    * process.env.PATH (no enhancement) so we don't accidentally detect the
@@ -1914,18 +2088,10 @@ class Installer {
    */
   _hasSystemNode(bundledDir) {
     try {
-      const { execFileSync } = require('child_process');
-      const cmd = process.platform === 'win32' ? 'where' : 'which';
-      const args = process.platform === 'win32' ? ['node'] : ['node'];
-      const out = execFileSync(cmd, args, {
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'ignore'],
-        timeout: 5000,
-        windowsHide: true,
-        env: { ...process.env },
-      });
+      // In-process PATH walk: `where` prints in the OEM codepage, so on a
+      // non-ASCII profile its UTF-8-decoded lines never matched bundledDir.
       const prefix = (bundledDir || '').toLowerCase();
-      for (const line of out.split(/\r?\n/).map(s => s.trim()).filter(Boolean)) {
+      for (const line of whereAll('node')) {
         if (!prefix || !line.toLowerCase().startsWith(prefix)) return true;
       }
       return false;
@@ -2273,12 +2439,15 @@ class Installer {
     const psTokens = /\b(irm|iwr|iex|Invoke-RestMethod|Invoke-WebRequest|Invoke-Expression|Expand-Archive|Get-[A-Z]\w*|Set-[A-Z]\w*)\b/;
     if (!psTokens.test(cmd)) return cmd;
     const escaped = cmd.replace(/"/g, '\\"');
-    return `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "${escaped}"`;
+    // PowerShell writes to a pipe in the OEM codepage (936 on zh-CN) and this
+    // output is read as UTF-8, so a non-ASCII path in an installer's log or
+    // error came back garbled. Switch the console encoding first.
+    return `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "[Console]::OutputEncoding=[Text.Encoding]::UTF8; ${escaped}"`;
   }
 
-  _execShell(cmd, timeoutMs = 300000) {
+  _execShell(cmd, timeoutMs = 300000, envOverride = null) {
     return new Promise((resolve, reject) => {
-      const env = this._buildShellEnv();
+      const env = envOverride || this._buildShellEnv();
 
       let shell = true;
       if (process.platform === 'win32') {

package/src/model-list.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Ask an OpenAI- or Anthropic-compatible endpoint which models it serves.
+ *
+ * The daemon answers the workspace's `list_models` command with this, so the
+ * model picker offers what the agent's relay actually has, and the key the
+ * request needs never leaves the device. Mirrors the launcher's
+ * model-catalog listOpenAiModels / listAnthropicModels.
+ */
+
+const MAX_MODELS = 300;
+
+/** The one line worth showing from an error body (relays nest it in JSON). */
+function briefError(text) {
+  try {
+    const j = JSON.parse(text);
+    const msg = typeof j.error === 'string' ? j.error : j.error && j.error.message;
+    const line = String(msg || j.message || '').trim();
+    if (line) return line.slice(0, 160);
+  } catch {}
+  return String(text || '').trim().slice(0, 160);
+}
+
+function isOfficialAnthropic(url) {
+  return url.hostname.toLowerCase() === 'api.anthropic.com';
+}
+
+/** `{data: [...]}`, a bare array, or a relay's `{models: [...]}`; ids deduped and sorted. */
+function parseModels(text) {
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { return []; }
+  const list = Array.isArray(parsed)
+    ? parsed
+    : (parsed && (parsed.data || parsed.models)) || [];
+  if (!Array.isArray(list)) return [];
+  const seen = new Map();
+  for (const entry of list) {
+    const id = String(typeof entry === 'string' ? entry : (entry && entry.id) || '').trim();
+    if (!id || seen.has(id)) continue;
+    const label = entry && typeof entry === 'object' && typeof entry.display_name === 'string'
+      ? entry.display_name.trim()
+      : '';
+    seen.set(id, { id, label: label || id });
+  }
+  return [...seen.values()].sort((a, b) => a.id.localeCompare(b.id)).slice(0, MAX_MODELS);
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.baseUrl   The base URL the agent's CLI is pointed at.
+ * @param {string} opts.apiKey
+ * @param {string} [opts.protocol] 'anthropic', or OpenAI-compatible (default).
+ * @returns {Promise<{models: {id: string, label: string}[], error?: string}>}
+ */
+async function listEndpointModels({ baseUrl, apiKey, protocol = 'openai', fetchImpl = globalThis.fetch, timeoutMs = 15000 }) {
+  let url;
+  try {
+    url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(baseUrl) ? baseUrl : `http://${baseUrl}`);
+  } catch {
+    return { models: [], error: 'The configured base URL is not a valid URL.' };
+  }
+  if (!apiKey) return { models: [], error: 'No API key is configured for this agent.' };
+
+  const headers = { Accept: 'application/json' };
+  let path = url.pathname.replace(/\/+$/, '');
+  if (protocol === 'anthropic') {
+    // Official takes x-api-key; relays only ever honor a bearer token.
+    if (isOfficialAnthropic(url)) headers['x-api-key'] = apiKey;
+    else headers.Authorization = `Bearer ${apiKey}`;
+    headers['anthropic-version'] = '2023-06-01';
+    path = `${path.replace(/\/v1$/, '')}/v1/models`;
+    url.search = '?limit=100';
+  } else {
+    headers.Authorization = `Bearer ${apiKey}`;
+    // A bare host means the /v1 API; a path (…/v1, …/v1beta/openai) is used as given.
+    path = `${path || '/v1'}/models`;
+    url.search = '';
+  }
+  url.pathname = path;
+  url.username = '';
+  url.password = '';
+
+  let res;
+  let text;
+  try {
+    res = await fetchImpl(url.toString(), { headers, signal: AbortSignal.timeout(timeoutMs) });
+    text = await res.text();
+  } catch (e) {
+    const reason = e && e.name === 'TimeoutError' ? 'the endpoint did not answer in time' : (e && e.message) || String(e);
+    return { models: [], error: `Could not reach ${url.host}: ${reason}` };
+  }
+  if (res.status >= 400) {
+    return { models: [], error: `HTTP ${res.status}: ${briefError(text)}` };
+  }
+  const models = parseModels(text);
+  return models.length ? { models } : { models: [], error: 'The endpoint listed no models.' };
+}
+
+module.exports = { listEndpointModels, parseModels };

package/src/paths.js

@@ -403,6 +403,20 @@ function whereBinary(names, env) {
   return null;
 }
 
+/**
+ * Every PATH hit for a name, in PATH order — for callers that filter the list
+ * (skip the bundled node, find the first one that runs). Like whereBinary it
+ * walks PATH in-process: `where` prints in the OEM codepage, and decoding that
+ * as UTF-8 mangles any non-ASCII profile path.
+ *
+ * @param {string} name
+ * @param {object} [env]  env whose PATH to search (defaults to process.env)
+ * @returns {string[]}
+ */
+function whereAll(name, env) {
+  return _searchPath(name, env || process.env);
+}
+
 /**
  * Drop the bin-dir snapshots and every lookup answered from them — for when a
  * background probe has just learned of directories they did not include.
@@ -1132,6 +1146,105 @@ function aiderBinDirs() {
 /** Executable suffixes to try for a bare binary name, per platform. */
 const BIN_EXTS = IS_WINDOWS ? ['.cmd', '.exe', '.bat', ''] : [''];
 
+/**
+ * A `#!...node` shebang line, as the Windows launcher matches it (win-exec.ts).
+ * `env -S`/flag forms are allowed; `#!/bin/sh -c node` is NOT a node script.
+ */
+const NODE_SHEBANG_RE =
+  /^#!\s*(?:(?:\S*[\\/])?env(?:\.exe)?\s+(?:-\S+\s+)*)?(?:\S*[\\/])?node(?:\.exe)?(?:\s|$)/i;
+
+/**
+ * True when a file is an extensionless Node script — npm's package bin shape
+ * (e.g. node_modules/cline/bin/cline). Windows cannot execute one: handed to
+ * cmd.exe it fails with "is not recognized as an internal or external command",
+ * so every caller that shells out to a resolved binary must prefix `node`.
+ */
+function isNodeShebangScript(filePath) {
+  if (!filePath) return false;
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(64);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      const firstLine = buf.subarray(0, n).toString('utf-8').split('\n', 1)[0];
+      return NODE_SHEBANG_RE.test(firstLine);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+}
+
+/** Managed npm module roots, in the same priority order used by Installer. */
+function managedNpmModuleDirs(agentType) {
+  const dirs = [
+    path.join(getRuntimePrefix(agentType), 'node_modules'),
+    path.join(os.homedir(), '.openagents', 'nodejs', 'node_modules'),
+  ];
+  return [...new Set(dirs)];
+}
+
+/**
+ * Resolve a package's declared `bin` target from an OpenAgents-managed npm
+ * prefix. This covers packages such as Cline whose root package is installed
+ * successfully but npm does not create a node_modules/.bin shim for it.
+ */
+function resolveManagedNpmPackageBin(agentType, packageName, binaryName) {
+  if (!agentType || !packageName || !binaryName) return null;
+
+  for (const modules of managedNpmModuleDirs(agentType)) {
+    const pkgDir = path.join(modules, packageName);
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    try {
+      if (!fs.existsSync(pkgJsonPath)) continue;
+      const bin = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).bin;
+      let rel = null;
+      if (typeof bin === 'string') rel = bin;
+      else if (bin && typeof bin === 'object') {
+        rel = bin[binaryName] || bin[packageName] || Object.values(bin)[0];
+      }
+      if (!rel) continue;
+      const abs = path.join(pkgDir, rel);
+      if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return abs;
+    } catch {
+      /* malformed or unreadable package — keep looking */
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the copy of an npm CLI installed in an OpenAgents-managed prefix.
+ * Package presence gates the lookup so an orphaned shim cannot shadow a
+ * working global install. The package's own bin is the final managed fallback.
+ */
+function resolveManagedNpmBinary(agentType, packageName, names) {
+  const list = (Array.isArray(names) ? names : [names]).filter(Boolean);
+  if (!agentType || !packageName || !list.length) return null;
+
+  for (const modules of managedNpmModuleDirs(agentType)) {
+    try {
+      if (!fs.existsSync(path.join(modules, packageName, 'package.json'))) continue;
+    } catch {
+      continue;
+    }
+    for (const name of list) {
+      for (const ext of BIN_EXTS) {
+        const candidate = path.join(modules, '.bin', `${name}${ext}`);
+        try {
+          if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+        } catch {
+          /* unreadable shim — keep looking */
+        }
+      }
+    }
+    const own = resolveManagedNpmPackageBin(agentType, packageName, list[0]);
+    if (own) return own;
+  }
+  return null;
+}
+
 /**
  * Last-resort binary lookup: walk the directories we already know agent CLIs
  * land in and check the filesystem directly, instead of asking the shell.
@@ -1205,6 +1318,10 @@ module.exports = {
   getEnhancedEnv,
   whichBinary,
   whereBinary,
+  whereAll,
+  resolveManagedNpmBinary,
+  resolveManagedNpmPackageBin,
+  isNodeShebangScript,
   resolveBinaryInKnownDirs,
   clearBinaryLookupCache,
   primeBinaryLookup,