@yawlabs/ssh-mcp 0.18.0 → 0.18.1

package/README.md

@@ -207,7 +207,7 @@ If you don't trust the agent's `env` values at all, the simplest mitigation is t
 
 On Windows, ssh-mcp uses the OpenSSH Authentication Agent's `\\.\pipe\openssh-ssh-agent` named pipe automatically when `SSH_AUTH_SOCK` is not set. No `SSH_AUTH_SOCK` needed — just make sure the OpenSSH agent service is running.
 
-On the [oam](https://oamjs.org) runtime, agent auth needs oam 0.18.0 or newer: that is the first oam whose `net` can dial a named pipe or a Unix socket, which is how ssh2 reaches the agent (and the launcher never serves on an older one). Agent-backed remote operations have so far been verified end to end on Node only; on oam, the handshake and `ssh_config_lookup` were verified, not an agent-only `ssh_exec`. If agent auth fails on oam, set `SSH_MCP_RUNTIME=node` to rule the runtime out.
+On the [oam](https://oamjs.org) runtime, the launcher serves only on oam 0.19.1 or newer. Agent auth needs a `net` that can dial a named pipe or a Unix socket (that is how ssh2 reaches the agent), which older oam releases could not do. On oam 0.19.1 (Windows) the MCP handshake, `ssh_config_lookup`, `ssh_key_list` and `ssh_agent_ensure` were verified through the launcher, and ssh2's own agent client was verified dialing a named pipe and listing identities. An agent-only `ssh_exec` end to end has so far been verified on Node only. If agent auth fails on oam, set `SSH_MCP_RUNTIME=node` to rule the runtime out.
 
 `ssh_agent_ensure` and `ssh_diagnose` probe that pipe and tell you if the service is down. Remote operations do *not*: they assume the pipe and let the connection fail on its own if the agent isn't there. That is why a stopped agent service shows up as an auth failure rather than an "agent not running" error until you run the diagnostic tools.
 
@@ -328,27 +328,27 @@ for (const check of report.checks) {
 
 ## Runtime selection
 
-The `ssh-mcp` command — what `npx @yawlabs/ssh-mcp` runs — is a small launcher. It prefers the [oam](https://oamjs.org) runtime and otherwise runs the server on Node, so oam is optional. Its minimum is the **latest oam release, currently 0.18.0**, and it never serves on an older oam.
+The `ssh-mcp` command — what `npx @yawlabs/ssh-mcp` runs — is a small launcher. It prefers the [oam](https://oamjs.org) runtime and otherwise runs the server on Node, so oam is optional. Its minimum is the **latest oam release, currently 0.19.1**, and it never serves on an older oam.
 
 Two environment variables control the choice; set them in your MCP client's `env` block:
 
 - `SSH_MCP_RUNTIME` — which runtime to use. Case-insensitive; any value other than `oam` or `node` behaves as `auto`.
-  - `auto` (default) — use the newest oam it can find at 0.18.0 or newer, otherwise run on Node.
+  - `auto` (default) — use the newest oam it can find at 0.19.1 or newer, otherwise run on Node.
   - `oam` — require oam. Fails loudly: if no usable oam is found, the launcher prints what it found and why each one was passed over to stderr, and exits with status 1 instead of starting the server.
   - `node` — always Node. The launcher does not look for oam, and `OAM_BIN` is ignored.
-- `OAM_BIN` — path to an oam binary to use in preference to discovery, when it is 0.18.0 or newer. If it does not exist, is older, or will not run, the launcher says so on stderr and carries on with discovery.
+- `OAM_BIN` — path to an oam binary to use in preference to discovery, when it is 0.19.1 or newer. If it does not exist, is older, will not run, or does not answer `--version` with oam's own `oam x.y.z` banner (another program's version, such as Node's `v22.x.y`, does not count), the launcher says so on stderr and carries on with discovery.
 
-Discovery looks in `$OAM_INSTALL_DIR` (when set — the oam installer's install target), then `%LOCALAPPDATA%\oam\bin` (Windows only), then `~/.oam/bin`, then every directory on `PATH`; asks every oam binary it finds for its version; and uses the newest one at 0.18.0 or newer. On a tie the one found first wins, so an installed copy beats one on `PATH`. On Windows only `oam.exe` counts: an `oam.cmd`/`oam.bat` shim on `PATH` is never run, and is named on stderr when no usable oam is found.
+Discovery looks in `$OAM_INSTALL_DIR` (when set — the oam installer's install target), then `%LOCALAPPDATA%\oam\bin` (Windows only), then `~/.oam/bin`, then every directory on `PATH`; asks every oam binary it finds for its version, counting only an answer that carries oam's own `oam x.y.z` banner; and uses the newest one at 0.19.1 or newer. On a tie the one found first wins, so an installed copy beats one on `PATH`. On Windows only `oam.exe` counts: an `oam.cmd`/`oam.bat` shim on `PATH` is never run, and is named on stderr when no usable oam is found.
 
-By default an unusable oam is not an error. When Node starts the launcher (`npx` or a global install, run directly by your MCP client), `auto` mode falls back to Node — silently when there was nothing to find, or with a note on stderr naming each oam (and `OAM_BIN`) it passed over and why: older than 0.18.0, not runnable, or a shim. A chosen oam that then fails to start is named on stderr too. When an older oam starts the launcher, the handoff to Node is always noted on stderr (see below). With `SSH_MCP_RUNTIME=oam`, each of these cases exits with status 1 instead.
+By default an unusable oam is not an error. When Node starts the launcher (`npx` or a global install, run directly by your MCP client), `auto` mode falls back to Node — silently when there was nothing to find, or with a note on stderr naming each oam (and `OAM_BIN`) it passed over and why: older than 0.19.1, not runnable, or a shim. A chosen oam that then fails to start is named on stderr too. When an older oam starts the launcher, the handoff to Node is always noted on stderr (see below). With `SSH_MCP_RUNTIME=oam`, each of these cases exits with status 1 instead.
 
 When the launcher is itself started by oam (`oam run <path>/bin/ssh-mcp.mjs`, which is how Yaw MCP starts an `npx @yawlabs/ssh-mcp` entry when a recent oam is installed):
 
-- On oam 0.18.0 or newer it runs the server on that oam, in the same process. Nothing is discovered or spawned, `OAM_BIN` is not read, and `SSH_MCP_RUNTIME=oam` counts it as the oam it requires.
+- On oam 0.19.1 or newer it runs the server on that oam, in the same process. Nothing is discovered or spawned, `OAM_BIN` is not read, and `SSH_MCP_RUNTIME=oam` counts it as the oam it requires.
 - On an older oam it never runs the server there. It hands the server off to the newest usable oam it can find, or to Node on `PATH`, or exits with status 1 when there is neither (`SSH_MCP_RUNTIME=oam` exits with status 1 rather than handing off to Node).
 - With `SSH_MCP_RUNTIME=node` it hands the server off to Node on `PATH`, whatever the oam version.
 
-Whenever an oam host starts a child (the handoffs above), the launcher removes `--permission` and `--allow-*` flags from the child's inherited `NODE_OPTIONS`. oam 0.18.0 adds its own permission flags to every child's `NODE_OPTIONS`, and Node refuses some of them there (`--allow-net is not allowed in NODE_OPTIONS`, exit 9); this server is not sandboxed, so there is nothing to pass on. An oam that was itself started with `--permission` re-adds the flags inside `spawn()`, which the launcher cannot undo, so do not start it that way.
+Whenever an oam host starts a child (the handoffs above), the launcher removes `--permission` and `--allow-*` flags from the child's inherited `NODE_OPTIONS`. oam (since 0.18.0) adds its own permission flags to every child's `NODE_OPTIONS`, and Node refuses some of them there (`--allow-net is not allowed in NODE_OPTIONS`, exit 9); this server is not sandboxed, so there is nothing to pass on. An oam that was itself started with `--permission` re-adds the flags inside `spawn()`, which the launcher cannot undo, so do not start it that way.
 
 For example, to always run on Node:
 
@@ -370,7 +370,7 @@ On Windows, add the same `env` block to the `cmd /c` form from [Quick start](#qu
 
 - Node.js 18+
 - SSH client installed (for diagnostics and environment management)
-- Optional: [oam](https://oamjs.org) 0.18.0+ — see [Runtime selection](#runtime-selection)
+- Optional: [oam](https://oamjs.org) 0.19.1+ — see [Runtime selection](#runtime-selection)
 
 ## License
 

package/bin/ssh-mcp.mjs

@@ -40,7 +40,7 @@
  * named on stderr, and discovery carries on. It used to stop everything: a typo
  * in OAM_BIN meant Node, with no hint why. The discovered binaries that were
  * passed over, and any .cmd/.bat shim on PATH, are named only when NO usable
- * oam is found -- with 0.9.0 installed and 0.18.0 on PATH, stderr stays empty.
+ * oam is found -- with 0.9.0 installed and 0.19.1 on PATH, stderr stays empty.
  *
  * ALREADY RUNNING ON OAM
  * A host can resolve this package's `bin` and launch `oam run <this file>`
@@ -77,11 +77,14 @@
  * wired up here.
  *
  * MINIMUM OAM VERSION
- * The latest oam release, 0.18.0 -- bump OAM_MIN when oam ships a newer one.
+ * The latest oam release, 0.19.1 -- bump OAM_MIN when oam ships a newer one.
  * Only the current oam is used and verified; an older one is passed over.
+ * Verified on 0.19.1 through this launcher (`oam run bin/ssh-mcp.mjs`): MCP
+ * initialize, tools/list and tools/call on ssh_key_list, ssh_config_lookup and
+ * ssh_agent_ensure, plus ssh2's agent client dialing a Windows named pipe.
  *
- * The floor is not cosmetic. Two things this server does need 0.18.0 itself,
- * so anyone lowering it has to answer for both:
+ * The floor is not cosmetic. Two things this server does were first fixed in
+ * oam 0.18.0, so anyone taking it below that has to answer for both:
  *
  *   1. An explicit child `env` that DELETES a variable. probeAgent
  *      (src/env.ts:85-90) runs `ssh-add -l` with SSH_AUTH_SOCK removed, so
@@ -96,6 +99,13 @@
  *      `new Socket().connect(path)` for every agent-backed connection. Up to
  *      0.17.x oam could not dial either (oam CHANGELOG 0.18.0, F1).
  *
+ * What moving to 0.19.1 changed here: oam used to start EVERY child with
+ * CREATE_NO_WINDOW and ignore `windowsHide`; 0.19.1 honours `windowsHide` as
+ * Node does, so by default a child shares the console (oam CHANGELOG 0.19.1).
+ * runArgs (src/diagnose.ts) and runArgsWithEnv (src/env.ts) therefore pass
+ * `windowsHide: true` themselves, or every ssh / ssh-add / ssh-keygen probe could
+ * flash a console window on Windows.
+ *
  * Background, long before the current floor: before 0.9.0
  * `child_process.execFile` ran its arguments through a SHELL, `exec` accepted
  * `timeout` and ignored it, `spawnSync` truncated at `maxBuffer` while
@@ -120,12 +130,13 @@ import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
- * Oldest oam this server runs on: the one whose explicit child `env` replaces
- * the environment (needed by probeAgent, src/env.ts) and whose `net` dials named
- * pipes and Unix sockets (needed by ssh2's agent client, src/ssh.ts). See MINIMUM
- * OAM VERSION above.
+ * Oldest oam this server runs on: the latest release, the one it is verified on.
+ * It must also keep 0.18.0's explicit child `env` that replaces the environment
+ * (needed by probeAgent, src/env.ts) and `net` dialing named pipes and Unix
+ * sockets (needed by ssh2's agent client, src/ssh.ts). See MINIMUM OAM VERSION
+ * above.
  */
-const OAM_MIN = [0, 18, 0];
+const OAM_MIN = [0, 19, 1];
 
 /**
  * Bound on each `oam --version` probe. A healthy oam answers in milliseconds;
@@ -227,7 +238,7 @@ async function errSync(message) {
  * A pre-release suffix (0.9.0-rc.1) truncates to its base version.
  *
  * Shared by the two places a version is read -- a discovered binary's
- * `oam --version` output ("oam 0.15.1") and the host's own
+ * `oam --version` banner ("oam 0.15.1", via oamBanner) and the host's own
  * `process.versions.oam` ("0.15.1") -- so they cannot disagree about what a
  * version string means, or which floor it has to clear.
  */
@@ -236,6 +247,19 @@ function parseVersion(text) {
   return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
 }
 
+/**
+ * `oam --version` output -> [major, minor, patch], or null unless it carries
+ * oam's own banner ("oam 0.19.1" at the start of a line). Any x.y.z is NOT
+ * enough: an OAM_BIN (or an oam.exe on disk) that is really another program --
+ * node prints "v22.22.2" -- would clear the floor, and the launcher would then
+ * spawn `<it> run dist/index.js`, which dies with no Node fallback because the
+ * spawn itself succeeded. process.versions.oam needs no banner: only oam sets it.
+ */
+function oamBanner(text) {
+  const m = /^oam\s+(\d+\.\d+\.\d+)/m.exec(text);
+  return m ? parseVersion(m[1]) : null;
+}
+
 /** `oam --version` -> [major, minor, patch], or null when it cannot be read. */
 function oamVersion(cmd) {
   try {
@@ -245,7 +269,7 @@ function oamVersion(cmd) {
       timeout: VERSION_PROBE_TIMEOUT_MS,
       windowsHide: true,
     });
-    return parseVersion(out);
+    return oamBanner(out);
   } catch {
     // Not executable, wrong arch, wedged, or deleted since the stat. Caller degrades.
     return null;
@@ -662,7 +686,10 @@ const hostOam = process.versions.oam;
 const plan = runtimePlan({ mode, hostOam });
 
 if (plan === "in-process") {
-  await runInProcess();
+  // Guarded like every other in-process fallback: a broken install (missing
+  // dist/index.js) must print this launcher's diagnostic, not a raw Node stack
+  // trace from the bare import().
+  await runInProcess().catch(fallbackFailed);
 } else if (plan === "handoff-node") {
   const belowFloor = !atLeast(parseVersion(hostOam), OAM_MIN);
   await handOffToNode(belowFloor ? `this process is oam ${hostOam}, older than ${OAM_MIN.join(".")}` : "");

package/dist/index.js

@@ -46,7 +46,12 @@ function isValidHostname(host) {
 }
 function runArgs(cmd, args) {
   try {
-    const stdout = execFileSync(cmd, args, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
+    const stdout = execFileSync(cmd, args, {
+      encoding: "utf8",
+      timeout: 1e4,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
     const err = e;
@@ -1064,7 +1069,9 @@ function runArgsWithEnv(cmd, args, extraEnv) {
       env,
       encoding: "utf8",
       timeout: 1e4,
-      stdio: ["pipe", "pipe", "pipe"]
+      stdio: ["pipe", "pipe", "pipe"],
+      // No console window for ssh-add on Windows; see runArgs in diagnose.ts.
+      windowsHide: true
     });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
@@ -1396,9 +1403,9 @@ function isPoolFullError(err) {
 }
 var MAX_TIMER_MS = 2147483647;
 function defaultMaxPoolSize() {
-  const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
-  if (!raw) return 100;
-  const parsed = Number.parseInt(raw, 10);
+  const raw = process.env.SSH_MCP_MAX_POOL_SIZE?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return 100;
+  const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
 }
 var AUTH_FINGERPRINT_SECRET = randomBytes(32);

package/dist/server.js

@@ -36,7 +36,12 @@ function isValidHostname(host) {
 }
 function runArgs(cmd, args) {
   try {
-    const stdout = execFileSync(cmd, args, { encoding: "utf8", timeout: 1e4, stdio: ["pipe", "pipe", "pipe"] });
+    const stdout = execFileSync(cmd, args, {
+      encoding: "utf8",
+      timeout: 1e4,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true
+    });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
     const err = e;
@@ -1081,7 +1086,9 @@ function runArgsWithEnv(cmd, args, extraEnv) {
       env,
       encoding: "utf8",
       timeout: 1e4,
-      stdio: ["pipe", "pipe", "pipe"]
+      stdio: ["pipe", "pipe", "pipe"],
+      // No console window for ssh-add on Windows; see runArgs in diagnose.ts.
+      windowsHide: true
     });
     return { stdout: stdout.trim(), ok: true };
   } catch (e) {
@@ -1408,9 +1415,9 @@ function isPoolFullError(err) {
 }
 var MAX_TIMER_MS = 2147483647;
 function defaultMaxPoolSize() {
-  const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
-  if (!raw) return 100;
-  const parsed = Number.parseInt(raw, 10);
+  const raw = process.env.SSH_MCP_MAX_POOL_SIZE?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return 100;
+  const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
 }
 var AUTH_FINGERPRINT_SECRET = randomBytes(32);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "mcpName": "io.github.YawLabs/ssh-mcp",
   "description": "SSH MCP server: run remote commands, transfer files over SFTP, manage ssh-agent keys and known_hosts, and auto-diagnose SSH failures.",
   "type": "module",
@@ -76,7 +76,6 @@
     "@vitest/coverage-v8": "^4.1.11",
     "@yawlabs/mcp-compliance": "^0.20.4",
     "esbuild": "^0.28.1",
-    "postject": "^1.0.0-alpha.6",
     "tsup": "^8.5.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.6"