@yawlabs/ssh-mcp 0.16.1 → 0.17.0

package/dist/index.js

@@ -1307,6 +1307,29 @@ function testConnection(host, port = 22) {
 
 // src/pool.ts
 import { createHash } from "crypto";
+var POOL_FULL_ERROR_CODE = "ERR_SSH_MCP_POOL_FULL";
+var PoolFullError = class extends Error {
+  code = POOL_FULL_ERROR_CODE;
+  maxPoolSize;
+  waitedMs;
+  constructor(maxPoolSize, waitedMs) {
+    const base = `Connection pool is full (${maxPoolSize} connections in use or dialing, the SSH_MCP_MAX_POOL_SIZE cap)`;
+    super(
+      waitedMs === void 0 ? base : (
+        // "became available to this call", not "freed up": every capacity signal wakes every
+        // parked caller, so a slot can free during the wait and still go to someone else.
+        `${base}; no slot became available to this call within ${Math.round(waitedMs)}ms. Retry once the calls holding the slots finish, or raise the cap (SSH_MCP_MAX_POOL_SIZE in the MCP server's environment).`
+      )
+    );
+    this.name = "PoolFullError";
+    this.maxPoolSize = maxPoolSize;
+    if (waitedMs !== void 0) this.waitedMs = waitedMs;
+  }
+};
+function isPoolFullError(err) {
+  return typeof err === "object" && err !== null && err.code === POOL_FULL_ERROR_CODE;
+}
+var MAX_TIMER_MS = 2147483647;
 function defaultMaxPoolSize() {
   const raw = process.env.SSH_MCP_MAX_POOL_SIZE;
   if (!raw) return 100;
@@ -1359,11 +1382,42 @@ var ConnectionPool = class {
   // factory closes the freshly-connected client instead of registering it.
   // Consumers must construct a new pool to use again.
   drained = false;
+  // Callers parked in waitForCapacity(). Every site that can free a slot for a NEW key calls
+  // notifyCapacity(), which wakes all of them: an entry dropping to refCount 0 (it becomes
+  // evictable), an entry leaving the map (markDead, idle expiry), a dial failing without
+  // registering, and drain(). Waking all rather than one means a woken caller that does not
+  // take the slot (its retry fails for another reason, or joins a same-key dial) cannot
+  // strand the rest; the losers of a wake just find the pool full again and re-park.
+  capacityWaiters = /* @__PURE__ */ new Set();
   constructor(options) {
     this.idleTtlMs = options?.idleTtlMs ?? 6e4;
     this.maxPoolSize = options?.maxPoolSize ?? defaultMaxPoolSize();
   }
-  async acquire(config) {
+  /**
+   * Checks out a connection for `config`, dialing one if needed. Fails fast on a full pool
+   * unless `options.waitForCapacityMs` is set, in which case the caller parks and retries on
+   * every capacity signal until it wins a slot or the budget is spent. The wait is bounded,
+   * never a reservation: a woken caller can lose the slot to another and simply parks again
+   * for whatever budget is left. The final rejection carries the budget in its message.
+   */
+  async acquire(config, options) {
+    const budgetMs = options?.waitForCapacityMs ?? 0;
+    if (!(budgetMs > 0)) return this.acquireNow(config);
+    const deadline = performance.now() + budgetMs;
+    for (; ; ) {
+      try {
+        return await this.acquireNow(config);
+      } catch (err) {
+        if (!isPoolFullError(err)) throw err;
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) throw new PoolFullError(this.maxPoolSize, budgetMs);
+        await this.waitForCapacity(remaining);
+      }
+    }
+  }
+  // The fail-fast acquire: one admission check, one dial (or a join on an in-flight one).
+  async acquireNow(config) {
+    if (this.drained) throw new Error("ConnectionPool was drained");
     const resolved = resolveOrDiagnose(config);
     const cc = resolved.connectConfig;
     const key = `${cc.username}@${cc.host}:${cc.port}#${authFingerprint(cc)}`;
@@ -1387,25 +1441,20 @@ var ConnectionPool = class {
       }
       let inflight = this.pending.get(key);
       if (!inflight) {
-        if (this.entries.size >= this.maxPoolSize) {
-          let evicted = false;
-          for (const [k, e] of this.entries) {
-            if (e.refCount === 0) {
-              if (e.idleTimer) clearTimeout(e.idleTimer);
-              try {
-                e.client.end();
-              } catch {
-              }
-              this.entries.delete(k);
-              evicted = true;
-              break;
-            }
+        if (this.entries.size + this.pending.size >= this.maxPoolSize) {
+          const victim = this.findEvictable();
+          if (!victim) {
+            throw new PoolFullError(this.maxPoolSize);
           }
-          if (!evicted) {
-            throw new Error(`Connection pool is full (${this.maxPoolSize} active connections)`);
+          if (victim.idleTimer) clearTimeout(victim.idleTimer);
+          try {
+            victim.client.end();
+          } catch {
           }
+          this.entries.delete(victim.key);
         }
         const promise = (async () => {
+          let registered = false;
           try {
             const client2 = await connectWithProxy(resolved);
             if (this.drained) {
@@ -1425,15 +1474,18 @@ var ConnectionPool = class {
               }
               if (this.entries.get(key) === entry2) {
                 this.entries.delete(key);
+                this.notifyCapacity();
               }
             };
             client2.on("close", markDead);
             client2.on("end", markDead);
             client2.on("error", markDead);
             this.entries.set(key, entry2);
+            registered = true;
             return client2;
           } finally {
             this.pending.delete(key);
+            if (!registered) this.notifyCapacity();
           }
         })();
         inflight = { promise, resolved };
@@ -1472,8 +1524,10 @@ var ConnectionPool = class {
             } catch {
             }
             this.entries.delete(entry.key);
+            this.notifyCapacity();
           }, this.idleTtlMs);
           entry.idleTimer.unref();
+          this.notifyCapacity();
         }
         return;
       }
@@ -1483,8 +1537,9 @@ var ConnectionPool = class {
     } catch {
     }
   }
-  async withConnection(config, fn) {
-    const client = await this.acquire(config);
+  /** `acquire()` + `fn` + `release()`, with the same optional bounded wait for a slot. */
+  async withConnection(config, fn, options) {
+    const client = await this.acquire(config, options);
     try {
       return await fn(client);
     } finally {
@@ -1504,10 +1559,81 @@ var ConnectionPool = class {
     }
     this.entries.clear();
     this.pending.clear();
+    this.notifyCapacity();
+  }
+  /**
+   * Parks until the pool's capacity may have changed, for a caller whose `acquire()` just
+   * rejected with a {@link PoolFullError} and that would rather wait than fail. This is the
+   * primitive behind `acquire()`'s `waitForCapacityMs` option; a bare `acquire()` never waits.
+   *
+   * Resolves `true` when a slot may be free (woken by a release, an entry closing or expiring,
+   * a failed dial, or `drain()`), or at once if a new host would fit right now or the pool is
+   * already drained. Resolves `false` after `timeoutMs` with nothing having changed. Never
+   * rejects. A `true` is a hint, not a reservation: another caller can take the slot first,
+   * so retry `acquire()` and wait again on another `PoolFullError`. The timer is cleared on
+   * wake and unref'd, so a parked caller never holds the process open.
+   *
+   * Aborting `signal` ends the park early with `false`, as if the timer had run out; an
+   * already-aborted signal resolves `false` without parking, unless the pool is drained or a
+   * new host would fit right now. A wake that lands first still resolves `true`. A caller that
+   * gives up on its own (`ssh_multi_exec` declaring the call starved) aborts rather than racing
+   * this promise against another: the race would add a promise hop to every wake.
+   */
+  waitForCapacity(timeoutMs, signal) {
+    return new Promise((resolve) => {
+      let timer;
+      const settle = (woken) => {
+        if (timer !== void 0) clearTimeout(timer);
+        this.capacityWaiters.delete(wake);
+        signal?.removeEventListener("abort", abort);
+        resolve(woken);
+      };
+      const wake = () => settle(true);
+      const abort = () => settle(false);
+      this.capacityWaiters.add(wake);
+      if (this.drained) {
+        wake();
+        return;
+      }
+      if (this.hasCapacity()) {
+        wake();
+        return;
+      }
+      if (!(timeoutMs > 0) || signal?.aborted) {
+        abort();
+        return;
+      }
+      timer = setTimeout(abort, Math.min(timeoutMs, MAX_TIMER_MS));
+      timer.unref();
+      signal?.addEventListener("abort", abort, { once: true });
+    });
+  }
+  // acquireNow()'s admission test for a new key: below the cap, or an entry to evict.
+  hasCapacity() {
+    return this.entries.size + this.pending.size < this.maxPoolSize || this.findEvictable() !== void 0;
+  }
+  // The eviction rule, in one place: the first entry (insertion order) no caller holds. Both
+  // acquireNow()'s eviction and hasCapacity() read it, so waitForCapacity's re-check can never
+  // disagree with what an acquire would actually evict.
+  findEvictable() {
+    for (const e of this.entries.values()) {
+      if (e.refCount === 0) return e;
+    }
+    return void 0;
+  }
+  notifyCapacity() {
+    if (this.capacityWaiters.size === 0) return;
+    const waiters = [...this.capacityWaiters];
+    this.capacityWaiters.clear();
+    for (const wake of waiters) wake();
   }
   get size() {
     return this.entries.size;
   }
+  /** The connection cap (`maxPoolSize`), counting pooled entries plus in-flight dials. */
+  get maxSize() {
+    return this.maxPoolSize;
+  }
   get stats() {
     let active = 0;
     let idle = 0;
@@ -1537,26 +1663,83 @@ function shellQuote(s) {
   return `'${s.replace(/'/g, "'\\''")}'`;
 }
 async function multiExec(pool, hosts, command, timeoutMs = 3e4) {
-  const results = await Promise.allSettled(
-    hosts.map(async (hostConfig) => {
-      return pool.withConnection(hostConfig, async (client) => {
-        const result = await exec(client, command, timeoutMs);
-        return { host: hostConfig.host, ...result };
-      });
-    })
-  );
-  return results.map((result, i) => {
-    if (result.status === "fulfilled") {
-      return result.value;
-    }
-    return {
-      host: hosts[i].host,
-      stdout: "",
-      stderr: "",
-      code: -1,
-      error: result.reason instanceof Error ? result.reason.message : String(result.reason)
-    };
+  const cap = pool.maxSize;
+  const limit = typeof cap === "number" && cap >= 1 ? Math.min(hosts.length, Math.floor(cap)) : hosts.length;
+  let lastProgressAt = performance.now();
+  let starvedError;
+  const starvation = new AbortController();
+  let running = 0;
+  let parked = 0;
+  const canWait = typeof pool.waitForCapacity === "function";
+  const freshBudgetMs = timeoutMs >= 1 ? timeoutMs : 1;
+  const errorResult = (host, error) => ({
+    host,
+    stdout: "",
+    stderr: "",
+    code: -1,
+    error
   });
+  const runHost = async (hostConfig) => {
+    for (; ; ) {
+      if (starvedError !== void 0) return errorResult(hostConfig.host, starvedError);
+      let rejection;
+      try {
+        return await pool.withConnection(hostConfig, async (client) => {
+          lastProgressAt = performance.now();
+          try {
+            const result = await exec(client, command, timeoutMs);
+            return { host: hostConfig.host, ...result };
+          } finally {
+            lastProgressAt = performance.now();
+          }
+        });
+      } catch (reason) {
+        if (!isPoolFullError(reason)) {
+          lastProgressAt = performance.now();
+          return errorResult(hostConfig.host, reason instanceof Error ? reason.message : String(reason));
+        }
+        if (!canWait) return errorResult(hostConfig.host, reason.message);
+        rejection = reason;
+      }
+      for (; ; ) {
+        if (starvedError !== void 0) return errorResult(hostConfig.host, starvedError);
+        const remaining = lastProgressAt + timeoutMs - performance.now();
+        let waitMs;
+        if (remaining > 0) {
+          waitMs = Math.ceil(remaining);
+        } else if (running - parked > 1) {
+          waitMs = freshBudgetMs;
+        } else {
+          starvedError ??= new PoolFullError(rejection.maxPoolSize, timeoutMs).message;
+          starvation.abort();
+          return errorResult(hostConfig.host, starvedError);
+        }
+        parked++;
+        let woken;
+        try {
+          woken = await pool.waitForCapacity(waitMs, starvation.signal);
+        } finally {
+          parked--;
+        }
+        if (woken) break;
+      }
+    }
+  };
+  const results = new Array(hosts.length);
+  let next = 0;
+  const worker = async () => {
+    running++;
+    try {
+      while (next < hosts.length) {
+        const i = next++;
+        results[i] = await runHost(hosts[i]);
+      }
+    } finally {
+      running--;
+    }
+  };
+  await Promise.all(Array.from({ length: limit }, worker));
+  return results;
 }
 var VALID_FIND_SIZE = /^\d+[cwbkMG]?$/;
 var FIND_EXPRESSION_TOKENS = /* @__PURE__ */ new Set(["(", ")", "!", ","]);
@@ -1669,7 +1852,9 @@ var KeyPathSchema = z.string().optional().describe("Path to SSH private key");
 var PasswordSchema = z.string().optional().describe(
   "SSH password. STRONGLY prefer key-based auth (privateKeyPath or ssh-agent). Passwords pass through MCP protocol frames as plaintext and may be logged by the transport or host process."
 );
-var TimeoutSchema = z.number().int().positive().optional().describe("Command timeout in milliseconds (default: 30000)");
+var TimeoutSchema = z.number().int().positive().optional().describe(
+  "Command timeout in milliseconds (default: 30000). Also the longest the call waits for a free connection-pool slot (SSH_MCP_MAX_POOL_SIZE, default 100) before the command starts; the wait and the command are bounded separately."
+);
 var EnvSchema = z.record(z.string(), z.string()).optional().describe(
   "Environment variables to set for this command. Injected as a `KEY='value' ...` prefix; works on any sshd regardless of AcceptEnv config. VALUES are POSIX-single-quoted, so any byte is safe in a value. KEYS cannot be quoted (a shell assignment prefix requires a bare name), so each key must match /^[A-Za-z_][A-Za-z0-9_]*$/ (the POSIX name grammar) \u2014 a key outside that grammar is rejected and the call fails before anything is sent to a host. Command policy is checked against the PREFIXED command, so a `^`-anchored whitelist pattern stops matching once this is set."
 );
@@ -1680,6 +1865,9 @@ var connectionParams = {
   privateKeyPath: KeyPathSchema,
   password: PasswordSchema
 };
+var DEFAULT_TIMEOUT_MS = 3e4;
+var poolWait = (timeoutMs = DEFAULT_TIMEOUT_MS) => ({ waitForCapacityMs: timeoutMs });
+var SFTP_POOL_WAIT_NOTE = ` If the connection pool is full (SSH_MCP_MAX_POOL_SIZE, default 100), waits up to ${DEFAULT_TIMEOUT_MS / 1e3}s for a free slot before starting.`;
 var POLICY_EXEMPT_NOTE = " NOT gated by SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST: command policy applies only to ssh_exec and ssh_multi_exec, so a blacklist such as `^rm` does NOT block this tool.";
 var ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function applyEnvPrefix(command, env) {
@@ -1710,21 +1898,26 @@ function registerTools(server, pool) {
     async ({ command, env, timeout, ...conn }) => {
       const { finalCommand, envPrefixApplied } = applyEnvPrefix(command, env);
       enforcePolicy(finalCommand, { envPrefixApplied });
-      return connectionPool.withConnection(conn, async (client) => {
-        const result = await exec(client, finalCommand, timeout || 3e4);
-        const parts = [];
-        if (result.stdout) parts.push(result.stdout);
-        if (result.stderr) parts.push(`[stderr]
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const result = await exec(client, finalCommand, timeoutMs);
+          const parts = [];
+          if (result.stdout) parts.push(result.stdout);
+          if (result.stderr) parts.push(`[stderr]
 ${result.stderr}`);
-        if (result.signal) parts.push(`[signal: ${result.signal}]`);
-        parts.push(`[exit code: ${result.code}]`);
-        return { content: [{ type: "text", text: parts.join("\n") }] };
-      });
+          if (result.signal) parts.push(`[signal: ${result.signal}]`);
+          parts.push(`[exit code: ${result.code}]`);
+          return { content: [{ type: "text", text: parts.join("\n") }] };
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
   server.tool(
     "ssh_read_file",
-    "Read a file from a remote host via SFTP.",
+    `Read a file from a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       path: z.string().refine((p) => p.startsWith("/"), {
@@ -1732,101 +1925,125 @@ ${result.stderr}`);
       }).describe("Absolute path to the remote file. Must start with /.")
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const content = await readFile(client, path);
-        return { content: [{ type: "text", text: content }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const content = await readFile(client, path);
+          return { content: [{ type: "text", text: content }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_write_file",
-    `Write content to a file on a remote host via SFTP. Creates or overwrites the file.${POLICY_EXEMPT_NOTE}`,
+    `Write content to a file on a remote host via SFTP. Creates or overwrites the file.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
       content: z.string().describe("File content to write")
     },
     async ({ path, content, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await writeFile(client, path, content);
-        const bytes = Buffer.byteLength(content, "utf8");
-        return { content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await writeFile(client, path, content);
+          const bytes = Buffer.byteLength(content, "utf8");
+          return { content: [{ type: "text", text: `Wrote ${bytes} bytes to ${path}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_upload",
-    `Upload a local file to a remote host via SFTP.${POLICY_EXEMPT_NOTE}`,
+    `Upload a local file to a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       localPath: z.string().describe("Path to the local file to upload"),
       remotePath: AbsoluteRemotePathSchema.describe("Absolute path on the remote host. Must start with /.")
     },
     async ({ localPath, remotePath, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await uploadFile(client, localPath, remotePath);
-        return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await uploadFile(client, localPath, remotePath);
+          return { content: [{ type: "text", text: `Uploaded ${localPath} \u2192 ${remotePath}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_download",
-    "Download a file from a remote host to local filesystem via SFTP.",
+    `Download a file from a remote host to local filesystem via SFTP.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       remotePath: AbsoluteRemotePathSchema.describe("Absolute path to the remote file. Must start with /."),
       localPath: z.string().describe("Local path to save the downloaded file")
     },
     async ({ remotePath, localPath, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await downloadFile(client, remotePath, localPath);
-        return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await downloadFile(client, remotePath, localPath);
+          return { content: [{ type: "text", text: `Downloaded ${remotePath} \u2192 ${localPath}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_ls",
-    "List files in a directory on a remote host via SFTP.",
+    `List files in a directory on a remote host via SFTP.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote directory. Must start with /.")
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const files = await listDir(client, path);
-        if (files.length === 0) {
-          return { content: [{ type: "text", text: `Directory is empty: ${path}` }] };
-        }
-        return { content: [{ type: "text", text: files.join("\n") }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const files = await listDir(client, path);
+          if (files.length === 0) {
+            return { content: [{ type: "text", text: `Directory is empty: ${path}` }] };
+          }
+          return { content: [{ type: "text", text: files.join("\n") }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_stat",
-    "Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and the path type. Symlinks are reported as `symlink -> <target kind>`: the type describes the link itself while size/mode/mtime describe its TARGET, and a dangling symlink is reported rather than erroring. Use this instead of parsing `ls -la` output.",
+    `Get metadata for a file or directory on a remote host via SFTP. Returns size, permissions (octal), uid/gid, mtime/atime, and the path type. Symlinks are reported as \`symlink -> <target kind>\`: the type describes the link itself while size/mode/mtime describe its TARGET, and a dangling symlink is reported rather than erroring. Use this instead of parsing \`ls -la\` output.${SFTP_POOL_WAIT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe("Absolute path to the remote file or directory. Must start with /.")
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const stats = await statFile(client, path);
-        const lines = [];
-        const targetKind = stats.isDirectory ? "directory" : stats.isFile ? "file" : "other";
-        const kind = stats.isSymbolicLink ? `symlink -> ${targetKind}` : targetKind;
-        lines.push(`${path}: ${kind}`);
-        lines.push(`  Size: ${stats.size} bytes`);
-        lines.push(`  Mode: ${stats.modeOctal}`);
-        lines.push(`  Owner: uid=${stats.uid} gid=${stats.gid}`);
-        lines.push(`  Modified: ${new Date(stats.mtime * 1e3).toISOString()}`);
-        lines.push(`  Accessed: ${new Date(stats.atime * 1e3).toISOString()}`);
-        return { content: [{ type: "text", text: lines.join("\n") }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const stats = await statFile(client, path);
+          const lines = [];
+          const targetKind = stats.isDirectory ? "directory" : stats.isFile ? "file" : "other";
+          const kind = stats.isSymbolicLink ? `symlink -> ${targetKind}` : targetKind;
+          lines.push(`${path}: ${kind}`);
+          lines.push(`  Size: ${stats.size} bytes`);
+          lines.push(`  Mode: ${stats.modeOctal}`);
+          lines.push(`  Owner: uid=${stats.uid} gid=${stats.gid}`);
+          lines.push(`  Modified: ${new Date(stats.mtime * 1e3).toISOString()}`);
+          lines.push(`  Accessed: ${new Date(stats.atime * 1e3).toISOString()}`);
+          return { content: [{ type: "text", text: lines.join("\n") }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_mkdir",
-    `Create a directory on a remote host via SFTP. Set \`recursive: true\` to create parent directories as needed (like \`mkdir -p\`). Existing intermediate dirs are tolerated; an existing leaf path is still an error. Unlike the other SFTP tools, the path may be relative.${POLICY_EXEMPT_NOTE}`,
+    `Create a directory on a remote host via SFTP. Set \`recursive: true\` to create parent directories as needed (like \`mkdir -p\`). Existing intermediate dirs are tolerated; an existing leaf path is still an error. Unlike the other SFTP tools, the path may be relative.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: z.string().describe(
@@ -1835,15 +2052,19 @@ ${result.stderr}`);
       recursive: z.boolean().optional().describe("Create parent directories as needed (default: false). Like `mkdir -p`.")
     },
     async ({ path, recursive, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await makeDir(client, path, recursive ?? false);
-        return { content: [{ type: "text", text: `Created directory ${path}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await makeDir(client, path, recursive ?? false);
+          return { content: [{ type: "text", text: `Created directory ${path}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
     "ssh_delete",
-    `Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with \`rm -rf\` explicitly so the destructive intent is visible in the tool trace.${POLICY_EXEMPT_NOTE}`,
+    `Delete a file or empty directory on a remote host via SFTP. Auto-detects the path type and calls the right SFTP op (unlink for files/symlinks, rmdir for empty dirs). Recursive directory delete is intentionally NOT supported -- for that, use ssh_exec with \`rm -rf\` explicitly so the destructive intent is visible in the tool trace.${SFTP_POOL_WAIT_NOTE}${POLICY_EXEMPT_NOTE}`,
     {
       ...connectionParams,
       path: AbsoluteRemotePathSchema.describe(
@@ -1851,10 +2072,14 @@ ${result.stderr}`);
       )
     },
     async ({ path, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        await deleteFile(client, path);
-        return { content: [{ type: "text", text: `Deleted ${path}` }] };
-      });
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          await deleteFile(client, path);
+          return { content: [{ type: "text", text: `Deleted ${path}` }] };
+        },
+        poolWait()
+      );
     }
   );
   server.tool(
@@ -2044,7 +2269,7 @@ ${result.stderr}`);
   );
   server.tool(
     "ssh_multi_exec",
-    "Execute a command on multiple remote hosts in parallel. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out).",
+    "Execute a command on multiple remote hosts in parallel. Runs at most SSH_MCP_MAX_POOL_SIZE hosts at once (default 100) and works through a longer list as slots free up. `timeout` is per host: it bounds each host's command, not the whole call. Each parallel slot works through its share of the list one host at a time, so with the pool to itself a call can take up to about ceil(hosts / SSH_MCP_MAX_POOL_SIZE) x (`timeout` + connect time). The connection pool is shared with every other tool; when it is full this call waits for slots instead of failing, and gives up only when none of its own hosts holds a slot and a full `timeout` has passed with none of them starting or finishing. The hosts waiting at that point (up to one per parallel slot) and every host still queued then report `Connection pool is full`; the queued ones are never attempted. Rerun those hosts once the other calls finish, or raise SSH_MCP_MAX_POOL_SIZE. Returns results per host. Use this instead of calling ssh_exec multiple times \u2014 it's faster and shows results side by side. Use `env` to set environment variables for this call without modifying the command string. Subject to SSH_MCP_COMMAND_WHITELIST / SSH_MCP_COMMAND_BLACKLIST if configured (policy is checked once, against the env-prefixed command, before fan-out).",
     {
       hosts: z.array(z.string()).describe("List of SSH hostnames or IPs"),
       command: z.string().describe("Shell command to execute on all hosts"),
@@ -2053,13 +2278,17 @@ ${result.stderr}`);
       privateKeyPath: KeyPathSchema,
       password: PasswordSchema,
       env: EnvSchema,
-      timeout: TimeoutSchema
+      // Not the shared text: here the pool wait is the call-level no-progress budget, not a
+      // wait before one command starts.
+      timeout: TimeoutSchema.describe(
+        "Per-host command timeout in milliseconds (default: 30000): bounds each host's command, not the whole call. Also the call's no-progress budget on a full pool (see the tool description)."
+      )
     },
     async ({ hosts, command, port, username, privateKeyPath, password, env, timeout }) => {
       const { finalCommand, envPrefixApplied } = applyEnvPrefix(command, env);
       enforcePolicy(finalCommand, { envPrefixApplied });
       const hostConfigs = hosts.map((host) => ({ host, port, username, privateKeyPath, password }));
-      const results = await multiExec(connectionPool, hostConfigs, finalCommand, timeout || 3e4);
+      const results = await multiExec(connectionPool, hostConfigs, finalCommand, timeout || DEFAULT_TIMEOUT_MS);
       const lines = [];
       for (const r of results) {
         lines.push(`--- ${r.host} ---`);
@@ -2092,14 +2321,19 @@ ${result.stderr}`);
       timeout: TimeoutSchema
     },
     async ({ path, name, type, maxdepth, minsize, maxsize, newer, timeout, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const files = await find(client, { path, name, type, maxdepth, minsize, maxsize, newer }, timeout || 3e4);
-        if (files.length === 0) {
-          return { content: [{ type: "text", text: "No files found." }] };
-        }
-        return { content: [{ type: "text", text: `Found ${files.length} result(s):
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const files = await find(client, { path, name, type, maxdepth, minsize, maxsize, newer }, timeoutMs);
+          if (files.length === 0) {
+            return { content: [{ type: "text", text: "No files found." }] };
+          }
+          return { content: [{ type: "text", text: `Found ${files.length} result(s):
 ${files.join("\n")}` }] };
-      });
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
   server.tool(
@@ -2113,20 +2347,25 @@ ${files.join("\n")}` }] };
       timeout: TimeoutSchema
     },
     async ({ path, lines, grep, timeout, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const output = await tail(client, path, lines || 100, grep, timeout || 3e4);
-        if (!output.trim()) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: grep ? `No lines matching "${grep}" in last ${lines || 100} lines.` : "File is empty (no content in the last lines read; whitespace-only counts as empty here)."
-              }
-            ]
-          };
-        }
-        return { content: [{ type: "text", text: output }] };
-      });
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const output = await tail(client, path, lines || 100, grep, timeoutMs);
+          if (!output.trim()) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: grep ? `No lines matching "${grep}" in last ${lines || 100} lines.` : "File is empty (no content in the last lines read; whitespace-only counts as empty here)."
+                }
+              ]
+            };
+          }
+          return { content: [{ type: "text", text: output }] };
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
   server.tool(
@@ -2138,18 +2377,23 @@ ${files.join("\n")}` }] };
       timeout: TimeoutSchema
     },
     async ({ service, timeout, ...conn }) => {
-      return connectionPool.withConnection(conn, async (client) => {
-        const status = await serviceStatus(client, service, timeout || 3e4);
-        const lines = [];
-        lines.push(`Service: ${status.name}`);
-        lines.push(`Status: ${status.status}`);
-        if (status.description) lines.push(`Description: ${status.description}`);
-        if (status.pid) lines.push(`PID: ${status.pid}`);
-        if (status.since) lines.push(`Since: ${status.since}`);
-        lines.push("");
-        lines.push(status.raw);
-        return { content: [{ type: "text", text: lines.join("\n") }], isError: status.unknown };
-      });
+      const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+      return connectionPool.withConnection(
+        conn,
+        async (client) => {
+          const status = await serviceStatus(client, service, timeoutMs);
+          const lines = [];
+          lines.push(`Service: ${status.name}`);
+          lines.push(`Status: ${status.status}`);
+          if (status.description) lines.push(`Description: ${status.description}`);
+          if (status.pid) lines.push(`PID: ${status.pid}`);
+          if (status.since) lines.push(`Since: ${status.since}`);
+          lines.push("");
+          lines.push(status.raw);
+          return { content: [{ type: "text", text: lines.join("\n") }], isError: status.unknown };
+        },
+        poolWait(timeoutMs)
+      );
     }
   );
 }