@lzm04521/ssh-mcp-server 1.1.5

package/build/services/ssh-connection-manager.js

@@ -0,0 +1,1775 @@
+import { createRequire } from "node:module";
+import { Logger } from "../utils/logger.js";
+import { collectSystemStatus } from "../utils/status-collector.js";
+import { ToolError } from "../utils/tool-error.js";
+import { getFlatHosts, getFlatHostByName } from "./config-store.js";
+import { globalAuditStore } from "./audit-store.js";
+import fs from "fs";
+import path from "path";
+import { pipeline } from "node:stream/promises";
+import { StringDecoder } from "node:string_decoder";
+const require = createRequire(import.meta.url);
+const ANSI_OSC_PATTERN = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+const ANSI_CSI_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+// Matches the exit code that `buildShellCommandScript` prints right after the
+// end marker prefix, anchored so it can only be read at the expected offset.
+const SHELL_EXIT_CODE_PATTERN = /^(-?\d+)__(?:\r)?\n/;
+const SHELL_EXIT_CODE_MAX_LENGTH = 32;
+const COMMAND_TEMPLATE_PLACEHOLDER = "<command>";
+const QUOTED_COMMAND_TEMPLATE_PLACEHOLDER = "<quotedCommand>";
+const DEFAULT_CONNECTION_TIMEOUT_MS = 30000;
+const DEFAULT_COMMAND_TIMEOUT_MS = 30000;
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 10000;
+const DEFAULT_KEEPALIVE_COUNT_MAX = 3;
+const DEFAULT_SFTP_TIMEOUT_MS = 300000;
+const DEFAULT_MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+// ssh2's SFTP ReadStream/WriteStream keep a single request in flight, so
+// transfer throughput is capped at one chunk per round trip regardless of the
+// available bandwidth. fastGet/fastPut pipeline `concurrency` chunks instead,
+// which is what makes large transfers usable on high latency links.
+const SFTP_FAST_TRANSFER_OPTIONS = {
+    concurrency: 64,
+    chunkSize: 32 * 1024,
+};
+// Under this size the streaming path already completes in a couple of round
+// trips, so the extra stat fastGet needs would cost more than the concurrency
+// saves. Staying on the streaming path below the threshold also keeps the
+// existing behaviour for files whose reported size is unusable: fastGet/fastPut
+// plan their chunks from that size and treat `size <= 0` as "nothing to
+// transfer", which would silently produce an empty file for pseudo files such
+// as /proc/cpuinfo.
+const SFTP_FAST_TRANSFER_MIN_BYTES = 256 * 1024;
+function applyCommandTemplate(template, command) {
+    const quotedCommand = shellQuote(command);
+    return template
+        .split(QUOTED_COMMAND_TEMPLATE_PLACEHOLDER)
+        .join(quotedCommand)
+        .split(`'${COMMAND_TEMPLATE_PLACEHOLDER}'`)
+        .join(quotedCommand)
+        .split(`"${COMMAND_TEMPLATE_PLACEHOLDER}"`)
+        .join(quotedCommand)
+        .split(COMMAND_TEMPLATE_PLACEHOLDER)
+        .join(command);
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The caller cannot see the process working directory or the server's path
+ * configuration, so a rejection that only says "must be within an allowed path"
+ * leaves it nothing to correct against. Name the roots instead.
+ */
+function describeAllowedRoots(kind, allowedRoots) {
+    return `Allowed ${kind} paths for this connection: ${allowedRoots.join(", ")}.`;
+}
+function isPathWithinRoot(candidate, root) {
+    const relativePath = path.relative(root, candidate);
+    return (relativePath === "" ||
+        (relativePath !== "" &&
+            !relativePath.startsWith("..") &&
+            !path.isAbsolute(relativePath)));
+}
+function redactProxyUrl(proxyUrl) {
+    const redactedUrl = new URL(proxyUrl.toString());
+    if (redactedUrl.username) {
+        redactedUrl.username = "***";
+    }
+    if (redactedUrl.password) {
+        redactedUrl.password = "***";
+    }
+    return redactedUrl.toString();
+}
+function normalizeUrlHostname(hostname) {
+    if (hostname.startsWith("[") && hostname.endsWith("]")) {
+        return hostname.slice(1, -1);
+    }
+    return hostname;
+}
+function formatHostPort(host, port) {
+    const formattedHost = host.includes(":") && !host.startsWith("[")
+        ? `[${host}]`
+        : host;
+    return `${formattedHost}:${port}`;
+}
+function parseProxyPort(proxyUrl, defaultPort) {
+    const port = proxyUrl.port
+        ? Number.parseInt(proxyUrl.port, 10)
+        : defaultPort;
+    if (!port || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error("Proxy URL must include a valid port");
+    }
+    return port;
+}
+function isPasswordPrompt(prompt) {
+    const promptText = prompt.toLowerCase();
+    return promptText.includes("password") || promptText.includes("密码");
+}
+function isAuthMethodAllowedByServer(method, methodsLeft) {
+    if (methodsLeft === null) {
+        return true;
+    }
+    // ssh-agent uses the SSH publickey protocol method.
+    if (method === "agent") {
+        return methodsLeft.includes("publickey");
+    }
+    return methodsLeft.includes(method);
+}
+/**
+ * SSH Connection Manager class
+ */
+export class SSHConnectionManager {
+    static instance;
+    clients = new Map();
+    configs = {};
+    connected = new Map();
+    statusCache = new Map();
+    pendingConnections = new Map();
+    pendingStatusCollections = new Map();
+    commandWhitelistRegexes = new Map();
+    commandBlacklistRegexes = new Map();
+    shellStreams = new Map();
+    shellReady = new Map();
+    shellQueues = new Map();
+    shellBuffers = new Map();
+    // A multi-byte character can be split across two TCP chunks, so the channel
+    // needs one decoder for its whole lifetime rather than a decode per chunk.
+    shellDecoders = new Map();
+    defaultName = "default";
+    currentConfig = null;
+    constructor() { }
+    /**
+     * Get singleton instance
+     */
+    static getInstance() {
+        if (!SSHConnectionManager.instance) {
+            SSHConnectionManager.instance = new SSHConnectionManager();
+        }
+        return SSHConnectionManager.instance;
+    }
+    /**
+     * Batch set SSH configurations
+     */
+    setConfig(cfg, defaultName) {
+        this.disconnect();
+        this.commandWhitelistRegexes.clear();
+        this.commandBlacklistRegexes.clear();
+        let configs;
+        if (cfg && typeof cfg === "object" && "projects" in cfg) {
+            const global = cfg;
+            this.currentConfig = global;
+            const flat = getFlatHosts(global);
+            const sec = global.security || {};
+            configs = {};
+            for (const [flatName, entry] of flat) {
+                // 全局安全兜底：白名单/路径在连接级留空时跟随全局，配置了则以连接级为准；
+                // 黑名单取并集——全局高危拦截不能被连接级配置清空
+                const c = { ...entry.config };
+                if ((!c.commandWhitelist || c.commandWhitelist.length === 0) && Array.isArray(sec.commandWhitelist) && sec.commandWhitelist.length > 0) {
+                    c.commandWhitelist = sec.commandWhitelist;
+                }
+                if (Array.isArray(sec.commandBlacklist) && sec.commandBlacklist.length > 0) {
+                    c.commandBlacklist = [...sec.commandBlacklist, ...(c.commandBlacklist || [])];
+                }
+                if ((!c.allowedLocalPaths || c.allowedLocalPaths.length === 0) && Array.isArray(sec.allowedLocalPaths) && sec.allowedLocalPaths.length > 0) {
+                    c.allowedLocalPaths = sec.allowedLocalPaths;
+                }
+                if ((!c.allowedRemotePaths || c.allowedRemotePaths.length === 0) && Array.isArray(sec.allowedRemotePaths) && sec.allowedRemotePaths.length > 0) {
+                    c.allowedRemotePaths = sec.allowedRemotePaths;
+                }
+                configs[flatName] = c;
+            }
+            globalAuditStore.retentionDays = global.audit?.retentionDays;
+        }
+        else {
+            this.currentConfig = null;
+            configs = cfg;
+        }
+        for (const [name, config] of Object.entries(configs)) {
+            this.commandWhitelistRegexes.set(name, this.compilePatterns(config.commandWhitelist, name, "whitelist"));
+            this.commandBlacklistRegexes.set(name, this.compilePatterns(config.commandBlacklist, name, "blacklist"));
+        }
+        this.configs = configs;
+        if (defaultName && configs[defaultName]) {
+            this.defaultName = defaultName;
+        }
+        else if (Object.keys(configs).length > 0) {
+            this.defaultName = Object.keys(configs)[0];
+        }
+    }
+    /** 审计埋点：enabled=false 全关；logResults=false 只记失败。存储异常静默，不影响命令执行 */
+    auditLog(connection, tool, ok, detail) {
+        const audit = this.currentConfig?.audit;
+        if (audit?.enabled === false)
+            return;
+        if (ok && audit?.logResults === false)
+            return;
+        try {
+            globalAuditStore.log({ connection, tool, status: ok ? "ok" : "fail", sql: detail });
+        }
+        catch { }
+    }
+    auditName(name) {
+        return name || this.defaultName;
+    }
+    resolveFlatName(name) {
+        if (!name) {
+            if (Object.keys(this.configs).length === 0) {
+                throw new ToolError("HOST_NOT_FOUND", "SSH configuration not set: No hosts configured", false);
+            }
+            if (this.configs[this.defaultName]) {
+                return this.defaultName;
+            }
+            return Object.keys(this.configs)[0];
+        }
+        if (this.configs[name]) {
+            return name;
+        }
+        if (this.currentConfig) {
+            const result = getFlatHostByName(name, this.currentConfig);
+            if (result) {
+                if (result.ambiguous) {
+                    throw new ToolError("AMBIGUOUS_HOST", `Ambiguous host '${name}': candidates ${result.candidates.join(", ")}`, false);
+                }
+                return result.flatName;
+            }
+            throw new ToolError("HOST_NOT_FOUND", `SSH configuration for '${name}' not set`, false);
+        }
+        throw new ToolError("HOST_NOT_FOUND", `SSH configuration for '${name}' not set`, false);
+    }
+    /**
+     * Get specified connection configuration
+     */
+    getConfig(name) {
+        const key = this.resolveFlatName(name);
+        const cfg = this.configs[key];
+        if (!cfg) {
+            throw new ToolError("HOST_NOT_FOUND", `SSH configuration for '${key}' not set`, false);
+        }
+        return cfg;
+    }
+    /**
+     * Batch connect all configured SSH connections
+     */
+    async connectAll() {
+        const names = Object.keys(this.configs);
+        const results = await Promise.allSettled(names.map((name) => this.connect(name)));
+        const failures = results
+            .map((result, index) => ({ result, name: names[index] }))
+            .filter((entry) => entry.result.status === "rejected");
+        if (failures.length > 0) {
+            throw new ToolError("SSH_CONNECTION_FAILED", failures
+                .map(({ name, result }) => `[${name}] ${result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason)}`)
+                .join("; "), true);
+        }
+    }
+    /**
+     * Connect to SSH with specified name
+     */
+    async connect(name) {
+        const key = this.resolveFlatName(name);
+        if (this.hasUsableConnection(key)) {
+            return;
+        }
+        const existingConnection = this.pendingConnections.get(key);
+        if (existingConnection) {
+            await existingConnection;
+            return;
+        }
+        const config = this.getConfig(key);
+        const client = this.createClient();
+        const connectionPromise = new Promise(async (resolve, reject) => {
+            let settled = false;
+            const timeoutMs = this.getConnectionTimeoutMs(config);
+            const timeoutId = setTimeout(() => {
+                rejectOnce(new ToolError("SSH_CONNECTION_TIMEOUT", `SSH connection [${key}] timed out after ${timeoutMs}ms`, true));
+                this.invalidateConnection(key);
+                try {
+                    client.destroy();
+                }
+                catch {
+                    // Ignore cleanup errors during connection timeout.
+                }
+            }, timeoutMs);
+            const clearConnectionTimeout = () => clearTimeout(timeoutId);
+            const resolveOnce = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearConnectionTimeout();
+                resolve();
+            };
+            const rejectOnce = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearConnectionTimeout();
+                reject(error);
+            };
+            client.on("ready", async () => {
+                Logger.log(`Successfully connected to SSH server [${key}] ${config.host}:${config.port}`);
+                try {
+                    if (this.getTransportMode(config) === "shell") {
+                        await this.initializeShellSession(client, key, config);
+                    }
+                    this.clients.set(key, client);
+                    this.connected.set(key, true);
+                    this.scheduleStatusCollection(key);
+                    resolveOnce();
+                }
+                catch (error) {
+                    this.connected.set(key, false);
+                    this.cleanupShellState(key, true);
+                    try {
+                        client.end();
+                    }
+                    catch {
+                        // Ignore cleanup errors during failed initialization.
+                    }
+                    rejectOnce(error instanceof ToolError
+                        ? error
+                        : new ToolError("SSH_CONNECTION_FAILED", `SSH connection [${key}] failed: ${error.message}`, true));
+                }
+            });
+            client.on("error", (err) => {
+                this.connected.set(key, false);
+                if (this.clients.get(key) === client || this.shellStreams.has(key)) {
+                    this.invalidateConnection(key);
+                }
+                rejectOnce(new ToolError("SSH_CONNECTION_FAILED", `SSH connection [${key}] failed: ${err.message}`, true));
+            });
+            client.on("close", () => {
+                this.clearConnectionState(key);
+                Logger.log(`SSH connection [${key}] closed`, "info");
+            });
+            try {
+                const sshConfig = await this.buildClientConfig(key, config);
+                client.connect(sshConfig);
+            }
+            catch (error) {
+                rejectOnce(error);
+            }
+        });
+        this.pendingConnections.set(key, connectionPromise);
+        try {
+            await connectionPromise;
+        }
+        finally {
+            this.pendingConnections.delete(key);
+        }
+    }
+    /**
+     * Get SSH Client with specified name
+     */
+    getClient(name) {
+        const key = this.resolveFlatName(name);
+        const client = this.clients.get(key);
+        if (!client) {
+            throw new Error(`SSH client for '${key}' not connected`);
+        }
+        return client;
+    }
+    /**
+     * Execute SSH command
+     */
+    async executeCommand(cmdString, directory, name, options = {}) {
+        try {
+            const result = await this.runCommandInternal(cmdString, directory, name, options);
+            this.auditLog(this.auditName(name), "execute-command", true, directory ? `cd ${directory} && ${cmdString}` : cmdString);
+            return result;
+        }
+        catch (e) {
+            this.auditLog(this.auditName(name), "execute-command", false, directory ? `cd ${directory} && ${cmdString}` : cmdString);
+            throw e;
+        }
+    }
+    /**
+     * Upload file
+     */
+    validateLocalPath(localPath, name, purpose = "read") {
+        if (typeof localPath !== "string" || localPath.length === 0) {
+            throw new ToolError("LOCAL_PATH_NOT_ALLOWED", "Local path must be a non-empty string.", false);
+        }
+        if (localPath.includes("\0")) {
+            throw new ToolError("LOCAL_PATH_NOT_ALLOWED", "Local path must not contain null bytes.", false);
+        }
+        const resolvedPath = path.resolve(localPath);
+        const allowedRoots = this.getAllowedLocalRoots(name);
+        const parentPath = path.dirname(resolvedPath);
+        const existingPath = this.tryRealpath(resolvedPath);
+        const parentRealPath = this.tryRealpath(parentPath);
+        let pathToCheck = existingPath;
+        if (!pathToCheck && parentRealPath) {
+            pathToCheck = path.join(parentRealPath, path.basename(resolvedPath));
+        }
+        if (!pathToCheck) {
+            pathToCheck = resolvedPath;
+        }
+        if (purpose === "write" && !parentRealPath) {
+            throw new ToolError("LOCAL_PATH_NOT_ALLOWED", `Local path parent directory must exist and be within an allowed local path. Resolved to: ${resolvedPath}. ${describeAllowedRoots("local", allowedRoots)}`, false);
+        }
+        const isAllowed = allowedRoots.some((allowedRoot) => isPathWithinRoot(pathToCheck, allowedRoot));
+        if (!isAllowed) {
+            throw new ToolError("LOCAL_PATH_NOT_ALLOWED", `Path traversal detected. Local path resolved to: ${pathToCheck}. ${describeAllowedRoots("local", allowedRoots)}`, false);
+        }
+        return resolvedPath;
+    }
+    getAllowedLocalRoots(name) {
+        const config = this.getConfig(name);
+        return [process.cwd(), ...(config.allowedLocalPaths || [])]
+            .filter((allowedPath) => allowedPath.trim().length > 0)
+            .map((allowedPath) => {
+            const resolvedRoot = path.resolve(allowedPath);
+            return this.tryRealpath(resolvedRoot) || resolvedRoot;
+        });
+    }
+    tryRealpath(localPath) {
+        try {
+            return fs.realpathSync.native(localPath);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    validateRemotePath(remotePath, name) {
+        if (typeof remotePath !== "string" || remotePath.length === 0) {
+            throw new ToolError("REMOTE_PATH_NOT_ALLOWED", "Remote path must be a non-empty string.", false);
+        }
+        if (remotePath.includes("\0")) {
+            throw new ToolError("REMOTE_PATH_NOT_ALLOWED", "Remote path must not contain null bytes.", false);
+        }
+        if (!path.posix.isAbsolute(remotePath)) {
+            throw new ToolError("REMOTE_PATH_NOT_ALLOWED", `Remote path must be an absolute POSIX path, got: ${remotePath}`, false);
+        }
+        const resolvedPath = path.posix.normalize(remotePath);
+        const config = this.getConfig(name);
+        const allowedRoots = config.allowedRemotePaths || [];
+        if (allowedRoots.length === 0) {
+            return resolvedPath;
+        }
+        const isAllowed = allowedRoots.some((allowedRoot) => resolvedPath === allowedRoot ||
+            resolvedPath.startsWith(allowedRoot.endsWith("/") ? allowedRoot : `${allowedRoot}/`));
+        if (!isAllowed) {
+            throw new ToolError("REMOTE_PATH_NOT_ALLOWED", `Remote path is not within the configured allowedRemotePaths. Resolved to: ${resolvedPath}. ${describeAllowedRoots("remote", allowedRoots)}`, false);
+        }
+        return resolvedPath;
+    }
+    /**
+     * Upload file
+     */
+    async upload(localPath, remotePath, name) {
+        try {
+            const result = await this.uploadInternal(localPath, remotePath, name);
+            this.auditLog(this.auditName(name), "upload", true, `${localPath} → ${remotePath}`);
+            return result;
+        }
+        catch (e) {
+            this.auditLog(this.auditName(name), "upload", false, `${localPath} → ${remotePath}`);
+            throw e;
+        }
+    }
+    async uploadInternal(localPath, remotePath, name) {
+        const config = this.getConfig(name);
+        const key = this.resolveFlatName(name);
+        if (this.getTransportMode(config) === "shell") {
+            throw new ToolError("UNSUPPORTED_IN_SHELL_MODE", "Current bastion shell mode does not support SFTP upload/download.", false);
+        }
+        const validatedLocalPath = this.validateLocalPath(localPath, name, "read");
+        const validatedRemotePath = this.validateRemotePath(remotePath, name);
+        const client = await this.ensureConnected(name);
+        const sftpTimeoutMs = this.getSftpTimeoutMs(config);
+        const sftp = await this.withTimeout(this.openSftp(client), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP open timed out after ${sftpTimeoutMs}ms`);
+        try {
+            const localSize = await this.getLocalSizeForFastTransfer(validatedLocalPath);
+            if (localSize === undefined) {
+                await this.withTimeout(pipeline(fs.createReadStream(validatedLocalPath), sftp.createWriteStream(validatedRemotePath)), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP upload timed out after ${sftpTimeoutMs}ms`);
+            }
+            else {
+                await this.withTimeout(new Promise((resolve, reject) => {
+                    sftp.fastPut(validatedLocalPath, validatedRemotePath, SFTP_FAST_TRANSFER_OPTIONS, (err) => (err ? reject(err) : resolve()));
+                }), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP upload timed out after ${sftpTimeoutMs}ms`);
+                await this.appendUploadTail(sftp, validatedLocalPath, validatedRemotePath, localSize, sftpTimeoutMs, key);
+            }
+            return "File uploaded successfully";
+        }
+        catch (error) {
+            if (error instanceof ToolError && error.code === "OPERATION_TIMEOUT") {
+                throw error;
+            }
+            if (this.errorPathMatches(error, validatedLocalPath)) {
+                throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read local file: ${error.message}`, false);
+            }
+            throw new ToolError("SFTP_ERROR", `File upload failed: ${error.message}`, true);
+        }
+        finally {
+            this.closeSftp(sftp);
+        }
+    }
+    /**
+     * List remote directory
+     */
+    async listDirectory(remotePath, name) {
+        try {
+            const result = await this.listDirectoryInternal(remotePath, name);
+            this.auditLog(this.auditName(name), "list-directory", true, remotePath);
+            return result;
+        }
+        catch (e) {
+            this.auditLog(this.auditName(name), "list-directory", false, remotePath);
+            throw e;
+        }
+    }
+    async listDirectoryInternal(remotePath, name) {
+        const config = this.getConfig(name);
+        const key = this.resolveFlatName(name);
+        if (this.getTransportMode(config) === "shell") {
+            throw new ToolError("UNSUPPORTED_IN_SHELL_MODE", "Current bastion shell mode does not support SFTP directory listing. Use execute-command with ls instead.", false);
+        }
+        const validatedRemotePath = this.validateRemotePath(remotePath, name);
+        const client = await this.ensureConnected(name);
+        const sftpTimeoutMs = this.getSftpTimeoutMs(config);
+        const sftp = await this.withTimeout(this.openSftp(client), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP open timed out after ${sftpTimeoutMs}ms`);
+        let entries;
+        try {
+            entries = await this.withTimeout(new Promise((resolve, reject) => {
+                sftp.readdir(validatedRemotePath, (err, list) => err ? reject(err) : resolve(list));
+            }), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP readdir timed out after ${sftpTimeoutMs}ms`);
+        }
+        catch (error) {
+            const err = error;
+            if (err?.code === "ENOENT" || /no such file/i.test(String(err?.message))) {
+                throw new ToolError("DIR_NOT_FOUND", `Remote directory not found: ${validatedRemotePath}`, false);
+            }
+            if (err instanceof ToolError)
+                throw err;
+            if (/not a directory/i.test(String(err?.message))) {
+                throw new ToolError("NOT_A_DIRECTORY", `Remote path is not a directory: ${validatedRemotePath}`, false);
+            }
+            throw new ToolError("SFTP_ERROR", `Directory listing failed: ${String(err?.message || err)}`, true);
+        }
+        finally {
+            this.closeSftp(sftp);
+        }
+        const mapped = entries.map((e) => ({
+            name: String(e.filename),
+            type: e.longname?.[0] === "d" ? "dir" : e.longname?.[0] === "l" ? "symlink" : "file",
+            size: typeof e.attrs?.size === "number" ? e.attrs.size : undefined,
+            mtimeMs: typeof e.attrs?.mtime === "number" ? e.attrs.mtime * 1000 : undefined,
+        }));
+        // 目录在前、其余按名称排序，方便模型快速定位
+        mapped.sort((a, b) => a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1);
+        return mapped;
+    }
+    /**
+     * Download file
+     */
+    async download(remotePath, localPath, name) {
+        try {
+            const result = await this.downloadInternal(remotePath, localPath, name);
+            this.auditLog(this.auditName(name), "download", true, `${remotePath} → ${localPath}`);
+            return result;
+        }
+        catch (e) {
+            this.auditLog(this.auditName(name), "download", false, `${remotePath} → ${localPath}`);
+            throw e;
+        }
+    }
+    async downloadInternal(remotePath, localPath, name) {
+        const config = this.getConfig(name);
+        const key = this.resolveFlatName(name);
+        if (this.getTransportMode(config) === "shell") {
+            throw new ToolError("UNSUPPORTED_IN_SHELL_MODE", "Current bastion shell mode does not support SFTP upload/download.", false);
+        }
+        const validatedLocalPath = this.validateLocalPath(localPath, name, "write");
+        const validatedRemotePath = this.validateRemotePath(remotePath, name);
+        const client = await this.ensureConnected(name);
+        const sftpTimeoutMs = this.getSftpTimeoutMs(config);
+        const sftp = await this.withTimeout(this.openSftp(client), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP open timed out after ${sftpTimeoutMs}ms`);
+        const tempLocalPath = `${validatedLocalPath}.tmp-${process.pid}-${Date.now()}-${Math.random()
+            .toString(16)
+            .slice(2)}`;
+        try {
+            const remoteSize = await this.getRemoteSizeForFastTransfer(sftp, validatedRemotePath, sftpTimeoutMs, key);
+            if (remoteSize === undefined) {
+                await this.withTimeout(pipeline(sftp.createReadStream(validatedRemotePath), fs.createWriteStream(tempLocalPath, { flags: "wx" })), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP download timed out after ${sftpTimeoutMs}ms`);
+            }
+            else {
+                // fastGet opens the destination with "w", which would drop the
+                // exclusive-create guarantee the streaming path gets from "wx".
+                // Claiming the temp name first keeps it.
+                await fs.promises.writeFile(tempLocalPath, "", { flag: "wx" });
+                await this.withTimeout(new Promise((resolve, reject) => {
+                    sftp.fastGet(validatedRemotePath, tempLocalPath, SFTP_FAST_TRANSFER_OPTIONS, (err) => (err ? reject(err) : resolve()));
+                }), sftpTimeoutMs, () => this.invalidateConnection(key), `SFTP download timed out after ${sftpTimeoutMs}ms`);
+                await this.appendDownloadTail(sftp, validatedRemotePath, tempLocalPath, sftpTimeoutMs, key);
+            }
+            await fs.promises.rename(tempLocalPath, validatedLocalPath);
+            return "File downloaded successfully";
+        }
+        catch (error) {
+            await this.unlinkIfExists(tempLocalPath);
+            if (error instanceof ToolError && error.code === "OPERATION_TIMEOUT") {
+                throw error;
+            }
+            if (this.errorPathMatches(error, tempLocalPath) ||
+                this.errorPathMatches(error, validatedLocalPath)) {
+                throw new ToolError("LOCAL_FILE_WRITE_FAILED", `Failed to save file: ${error.message}`, false);
+            }
+            throw new ToolError("SFTP_ERROR", `File download failed: ${error.message}`, true);
+        }
+        finally {
+            this.closeSftp(sftp);
+        }
+    }
+    openSftp(client) {
+        return new Promise((resolve, reject) => {
+            client.sftp((err, sftp) => {
+                if (err) {
+                    reject(new ToolError("SFTP_ERROR", `SFTP connection failed: ${err.message}`, true));
+                    return;
+                }
+                resolve(sftp);
+            });
+        });
+    }
+    statRemote(sftp, remotePath) {
+        return new Promise((resolve, reject) => {
+            sftp.stat(remotePath, (err, stats) => err ? reject(err) : resolve(stats));
+        });
+    }
+    /**
+     * Size to hand to the concurrent transfer path, or undefined to stay on the
+     * streaming path. Anything unexpected — a missing file, a directory, a
+     * server without stat support — falls back so the streaming path reports the
+     * same error it reports today.
+     */
+    async getRemoteSizeForFastTransfer(sftp, remotePath, timeoutMs, key) {
+        let stats;
+        try {
+            stats = await this.withTimeout(this.statRemote(sftp, remotePath), timeoutMs, () => this.invalidateConnection(key), `SFTP stat timed out after ${timeoutMs}ms`);
+        }
+        catch (error) {
+            // A timeout already tore the connection down, so it has to surface.
+            if (error instanceof ToolError) {
+                throw error;
+            }
+            return undefined;
+        }
+        return stats.isFile() && stats.size >= SFTP_FAST_TRANSFER_MIN_BYTES
+            ? stats.size
+            : undefined;
+    }
+    async getLocalSizeForFastTransfer(localPath) {
+        try {
+            const stats = await fs.promises.stat(localPath);
+            return stats.isFile() && stats.size >= SFTP_FAST_TRANSFER_MIN_BYTES
+                ? stats.size
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * fastGet transfers exactly the byte count the remote file had when it
+     * started, so data appended while it ran would be dropped. The streaming path
+     * reads until EOF and would have picked that tail up, so fetch it here to
+     * keep both paths equivalent for files that are still being written.
+     */
+    async appendDownloadTail(sftp, remotePath, tempLocalPath, timeoutMs, key) {
+        const downloadedBytes = (await fs.promises.stat(tempLocalPath)).size;
+        const stats = await this.withTimeout(this.statRemote(sftp, remotePath), timeoutMs, () => this.invalidateConnection(key), `SFTP stat timed out after ${timeoutMs}ms`);
+        if (stats.size <= downloadedBytes) {
+            return;
+        }
+        await this.withTimeout(pipeline(sftp.createReadStream(remotePath, { start: downloadedBytes }), fs.createWriteStream(tempLocalPath, { flags: "a" })), timeoutMs, () => this.invalidateConnection(key), `SFTP download timed out after ${timeoutMs}ms`);
+    }
+    /**
+     * Upload counterpart of appendDownloadTail. The local stat is free, so the
+     * remote round trip only happens when the local file actually grew.
+     */
+    async appendUploadTail(sftp, localPath, remotePath, sizeBeforeTransfer, timeoutMs, key) {
+        const currentLocalSize = (await fs.promises.stat(localPath)).size;
+        if (currentLocalSize <= sizeBeforeTransfer) {
+            return;
+        }
+        const stats = await this.withTimeout(this.statRemote(sftp, remotePath), timeoutMs, () => this.invalidateConnection(key), `SFTP stat timed out after ${timeoutMs}ms`);
+        if (stats.size >= currentLocalSize) {
+            return;
+        }
+        await this.withTimeout(pipeline(fs.createReadStream(localPath, { start: stats.size }), sftp.createWriteStream(remotePath, { flags: "a" })), timeoutMs, () => this.invalidateConnection(key), `SFTP upload timed out after ${timeoutMs}ms`);
+    }
+    closeSftp(sftp) {
+        try {
+            sftp.end();
+        }
+        catch {
+            // Ignore cleanup errors after transfer completion.
+        }
+    }
+    withTimeout(promise, timeoutMs, onTimeout, message) {
+        let timeoutId;
+        return new Promise((resolve, reject) => {
+            timeoutId = setTimeout(() => {
+                try {
+                    onTimeout();
+                }
+                catch {
+                    // Ignore cleanup errors while rejecting a timed out operation.
+                }
+                reject(new ToolError("OPERATION_TIMEOUT", message, true));
+            }, timeoutMs);
+            promise.then((value) => {
+                clearTimeout(timeoutId);
+                resolve(value);
+            }, (error) => {
+                clearTimeout(timeoutId);
+                reject(error);
+            });
+        });
+    }
+    errorPathMatches(error, localPath) {
+        const errorPath = error.path;
+        return typeof errorPath === "string" && path.resolve(errorPath) === localPath;
+    }
+    async unlinkIfExists(localPath) {
+        try {
+            await fs.promises.unlink(localPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                Logger.log(`Failed to remove partial local file ${localPath}: ${error.message}`, "error");
+            }
+        }
+    }
+    /**
+     * Disconnect SSH connection
+     */
+    disconnect() {
+        for (const timeoutId of this.pendingStatusCollections.values()) {
+            clearTimeout(timeoutId);
+        }
+        this.pendingStatusCollections.clear();
+        for (const [key] of this.clients) {
+            this.cleanupShellState(key, true);
+        }
+        if (this.clients.size > 0) {
+            for (const client of this.clients.values()) {
+                client.end();
+            }
+            this.clients.clear();
+        }
+        this.connected.clear();
+        this.statusCache.clear();
+        this.pendingConnections.clear();
+        this.commandWhitelistRegexes.clear();
+        this.commandBlacklistRegexes.clear();
+        this.shellStreams.clear();
+        this.shellReady.clear();
+        this.shellQueues.clear();
+        this.shellBuffers.clear();
+        this.shellDecoders.clear();
+    }
+    /**
+     * Get basic information of all configured servers
+     */
+    getAllServerInfos() {
+        return Object.keys(this.configs).map((key) => {
+            const config = this.configs[key];
+            const status = this.statusCache.get(key);
+            let project;
+            let environment;
+            let hostName;
+            if (this.currentConfig) {
+                const flat = getFlatHosts(this.currentConfig);
+                const entry = flat.get(key);
+                if (entry) {
+                    project = entry.project;
+                    environment = entry.environment;
+                    hostName = entry.host;
+                }
+            }
+            return {
+                name: key,
+                host: config.host,
+                port: config.port,
+                username: config.username,
+                connected: this.connected.get(key) === true,
+                status: status,
+                project,
+                environment,
+                hostName,
+            };
+        });
+    }
+    createClient() {
+        const { Client } = require("ssh2");
+        return new Client();
+    }
+    async ensureConnected(name) {
+        const key = this.resolveFlatName(name);
+        if (!this.hasUsableConnection(key)) {
+            await this.connect(key);
+        }
+        const client = this.clients.get(key);
+        if (!client) {
+            throw new Error(`SSH client for '${key}' not initialized`);
+        }
+        return client;
+    }
+    hasUsableConnection(key) {
+        const client = this.clients.get(key);
+        if (!client || this.connected.get(key) !== true) {
+            return false;
+        }
+        const config = this.getConfig(key);
+        if (this.getTransportMode(config) === "shell") {
+            return (this.shellReady.get(key) === true && this.shellStreams.has(key));
+        }
+        return true;
+    }
+    getTransportMode(config) {
+        return config.transportMode || "exec";
+    }
+    getShellReadyTimeoutMs(config) {
+        return config.shellReadyTimeoutMs || 10000;
+    }
+    getShellCommandTimeoutMs(config) {
+        return config.shellCommandTimeoutMs || DEFAULT_COMMAND_TIMEOUT_MS;
+    }
+    getCommandTimeoutMs(config) {
+        return config.commandTimeoutMs || DEFAULT_COMMAND_TIMEOUT_MS;
+    }
+    getConnectionTimeoutMs(config) {
+        return config.connectionTimeoutMs || DEFAULT_CONNECTION_TIMEOUT_MS;
+    }
+    getSftpTimeoutMs(config) {
+        return config.sftpTimeoutMs || DEFAULT_SFTP_TIMEOUT_MS;
+    }
+    getMaxOutputBytes(config) {
+        const configured = config.maxOutputBytes;
+        if (configured === undefined) {
+            return DEFAULT_MAX_OUTPUT_BYTES;
+        }
+        if (!Number.isSafeInteger(configured) || configured < 0) {
+            throw new ToolError("COMMAND_VALIDATION_FAILED", `maxOutputBytes must be a non-negative integer, got: ${String(configured)}`, false);
+        }
+        return configured;
+    }
+    async createSocksProxySocket(proxyUrl, config) {
+        const { SocksClient } = require("socks");
+        const proxyHost = normalizeUrlHostname(proxyUrl.hostname);
+        const proxyPort = parseProxyPort(proxyUrl);
+        if (!proxyHost) {
+            throw new Error("Proxy URL must include a host");
+        }
+        const proxy = {
+            host: proxyHost,
+            port: proxyPort,
+            type: 5,
+        };
+        if (proxyUrl.username) {
+            proxy.userId = decodeURIComponent(proxyUrl.username);
+        }
+        if (proxyUrl.password) {
+            proxy.password = decodeURIComponent(proxyUrl.password);
+        }
+        const { socket } = await SocksClient.createConnection({
+            proxy,
+            command: "connect",
+            destination: {
+                host: config.host,
+                port: config.port,
+            },
+            timeout: this.getConnectionTimeoutMs(config),
+        });
+        return socket;
+    }
+    createHttpProxySocket(proxyUrl, config) {
+        const isTlsProxy = proxyUrl.protocol === "https:";
+        const proxyHost = normalizeUrlHostname(proxyUrl.hostname);
+        const proxyPort = parseProxyPort(proxyUrl, isTlsProxy ? 443 : 80);
+        if (!proxyHost) {
+            throw new Error("Proxy URL must include a host");
+        }
+        const destination = formatHostPort(config.host, config.port);
+        const headers = { Host: destination };
+        if (proxyUrl.username || proxyUrl.password) {
+            const username = decodeURIComponent(proxyUrl.username);
+            const password = decodeURIComponent(proxyUrl.password);
+            headers["Proxy-Authorization"] = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+        }
+        return new Promise((resolve, reject) => {
+            const options = {
+                method: "CONNECT",
+                hostname: proxyHost,
+                port: proxyPort,
+                path: destination,
+                headers,
+            };
+            const proxyRequest = isTlsProxy
+                ? require("node:https").request(options)
+                : require("node:http").request(options);
+            proxyRequest.once("connect", (response, socket, head) => {
+                proxyRequest.setTimeout(0);
+                if (response.statusCode !== 200) {
+                    socket.destroy();
+                    reject(new Error(`HTTP proxy CONNECT failed with status ${response.statusCode ?? "unknown"}`));
+                    return;
+                }
+                if (head.length > 0) {
+                    socket.unshift(head);
+                }
+                resolve(socket);
+            });
+            proxyRequest.once("error", reject);
+            proxyRequest.setTimeout(this.getConnectionTimeoutMs(config), () => {
+                proxyRequest.destroy(new Error("HTTP proxy CONNECT timed out"));
+            });
+            proxyRequest.end();
+        });
+    }
+    async createProxySocket(proxyUrl, config) {
+        switch (proxyUrl.protocol) {
+            case "socks:":
+            case "socks5:":
+                return this.createSocksProxySocket(proxyUrl, config);
+            case "http:":
+            case "https:":
+                return this.createHttpProxySocket(proxyUrl, config);
+            default:
+                throw new Error(`Unsupported proxy protocol '${proxyUrl.protocol}'. Use socks://, socks5://, http://, or https://`);
+        }
+    }
+    async buildClientConfig(key, config) {
+        const sshConfig = {
+            host: config.host,
+            port: config.port,
+            username: config.username,
+            readyTimeout: this.getConnectionTimeoutMs(config),
+            timeout: this.getConnectionTimeoutMs(config),
+            keepaliveInterval: config.keepaliveIntervalMs || DEFAULT_KEEPALIVE_INTERVAL_MS,
+            keepaliveCountMax: config.keepaliveCountMax || DEFAULT_KEEPALIVE_COUNT_MAX,
+        };
+        if (config.algorithms) {
+            sshConfig.algorithms = config.algorithms;
+        }
+        if (config.proxy && config.socksProxy) {
+            throw new ToolError("SSH_CONNECTION_FAILED", `Proxy configuration for [${key}] cannot use both 'proxy' and 'socksProxy'`, false);
+        }
+        const proxyValue = config.proxy || config.socksProxy;
+        if (proxyValue) {
+            try {
+                const proxyUrl = new URL(proxyValue);
+                if (config.socksProxy &&
+                    proxyUrl.protocol !== "socks:" &&
+                    proxyUrl.protocol !== "socks5:") {
+                    throw new Error("The legacy 'socksProxy' option only supports socks:// or socks5:// URLs; use 'proxy' for HTTP or HTTPS proxies");
+                }
+                Logger.log(`Using proxy for [${key}]: ${redactProxyUrl(proxyUrl)}`, "info");
+                sshConfig.sock = await this.createProxySocket(proxyUrl, config);
+                Logger.log(`SSH config object with proxy: ${JSON.stringify(sshConfig, (field, value) => (field === "sock" ? "[Socket object]" : value))}`, "info");
+            }
+            catch (error) {
+                throw new ToolError("SSH_CONNECTION_FAILED", `Failed to create proxy connection for [${key}]: ${error.message}`, true);
+            }
+        }
+        // Enable keyboard-interactive authentication for 2FA/MFA
+        if (config.tryKeyboard) {
+            sshConfig.tryKeyboard = true;
+            // Build ordered preference of methods this connection supports.
+            const authMethods = [];
+            if (config.privateKey) {
+                authMethods.push("publickey");
+            }
+            if (config.agent) {
+                authMethods.push("agent");
+            }
+            if (config.password) {
+                authMethods.push("password");
+            }
+            authMethods.push("keyboard-interactive");
+            const triedMethods = [];
+            const maxAuthAttempts = authMethods.length;
+            sshConfig.authHandler = (methodsLeft, partialSuccess, callback) => {
+                // Prevent infinite retry loops.
+                if (triedMethods.length >= maxAuthAttempts) {
+                    Logger.log(`[${key}] Authentication failed after trying [${triedMethods.join(", ")}]`, "error");
+                    return callback(false);
+                }
+                // Pick the next preferred method that hasn't been attempted yet
+                // (and is still allowed by the server if methodsLeft is provided).
+                const candidates = methodsLeft !== null
+                    ? authMethods.filter((m) => isAuthMethodAllowedByServer(m, methodsLeft))
+                    : authMethods;
+                const nextMethod = candidates.find((m) => !triedMethods.includes(m));
+                if (!nextMethod) {
+                    Logger.log(`[${key}] All supported auth methods exhausted`, "error");
+                    return callback(false);
+                }
+                triedMethods.push(nextMethod);
+                Logger.log(`[${key}] Trying auth method: ${nextMethod} (${triedMethods.length}/${maxAuthAttempts})`, "info");
+                return callback(nextMethod);
+            };
+            // Handle keyboard-interactive prompts (for 2FA codes)
+            sshConfig.keyboard = (name, instructions, instructionsLang, prompts, finish) => {
+                Logger.log(`[${key}] Keyboard-interactive authentication requested`, "info");
+                Logger.log(`[${key}] Name: ${name}`, "debug");
+                Logger.log(`[${key}] Instructions: ${instructions}`, "debug");
+                Logger.log(`[${key}] Prompts: ${JSON.stringify(prompts)}`, "debug");
+                const otpCode = process.env.SSH_MCP_2FA_CODE;
+                const responses = [];
+                for (const prompt of prompts) {
+                    if (config.password && isPasswordPrompt(prompt.prompt)) {
+                        // For password prompts, use the configured password
+                        responses.push(config.password);
+                        Logger.log(`[${key}] Responding to password prompt: ${prompt.prompt}`, "debug");
+                    }
+                    else if (otpCode) {
+                        // For 2FA/verification code prompts, use SSH_MCP_2FA_CODE if provided
+                        responses.push(otpCode);
+                        Logger.log(`[${key}] Responding to non-password prompt with SSH_MCP_2FA_CODE: ${prompt.prompt}`, "info");
+                    }
+                    else if (config.password && prompts.length === 1 && !prompt.echo) {
+                        // Single non-echoing prompt without "password" label:
+                        // treat as password prompt (common on embedded devices)
+                        responses.push(config.password);
+                        Logger.log(`[${key}] Responding to single non-echo prompt (assumed password): ${prompt.prompt}`, "debug");
+                    }
+                    else {
+                        // No code available — empty response will fail the auth attempt;
+                        // set SSH_MCP_2FA_CODE before connecting to enable 2FA/MFA.
+                        responses.push("");
+                        Logger.log(`[${key}] Empty response for prompt (set SSH_MCP_2FA_CODE to satisfy 2FA): ${prompt.prompt}`, "info");
+                    }
+                }
+                finish(responses);
+            };
+        }
+        if (config.agent) {
+            sshConfig.agent = config.agent;
+            Logger.log(`Using SSH agent authentication for [${key}]: ${config.agent}`, "info");
+            if (!config.tryKeyboard) {
+                return sshConfig;
+            }
+        }
+        if (config.privateKey) {
+            try {
+                sshConfig.privateKey = fs.readFileSync(config.privateKey, "utf8");
+                if (config.passphrase) {
+                    sshConfig.passphrase = config.passphrase;
+                }
+                Logger.log(`Using SSH private key authentication for [${key}]`, "info");
+                if (!config.tryKeyboard) {
+                    return sshConfig;
+                }
+            }
+            catch (error) {
+                throw new ToolError("LOCAL_FILE_READ_FAILED", `Failed to read private key file for [${key}]: ${error.message}`, false);
+            }
+        }
+        if (config.password) {
+            sshConfig.password = config.password;
+            Logger.log(`Using password authentication for [${key}]`, "info");
+            if (!config.tryKeyboard) {
+                return sshConfig;
+            }
+        }
+        if (!config.agent && !config.privateKey && !config.password && !config.tryKeyboard) {
+            throw new ToolError("SSH_AUTHENTICATION_MISSING", `No valid authentication method provided for [${key}] (agent, password, private key, or tryKeyboard)`, false);
+        }
+        return sshConfig;
+    }
+    scheduleStatusCollection(key) {
+        const existingStatusCollection = this.pendingStatusCollections.get(key);
+        if (existingStatusCollection) {
+            clearTimeout(existingStatusCollection);
+        }
+        const timeoutId = setTimeout(() => {
+            this.pendingStatusCollections.delete(key);
+            void this.collectStatusForConnection(key);
+        }, 1000);
+        this.pendingStatusCollections.set(key, timeoutId);
+    }
+    async collectStatusForConnection(key) {
+        try {
+            const status = await collectSystemStatus((command, connectionName) => this.runCommandInternal(command, undefined, connectionName, {
+                prevalidatedInternalCommand: true,
+            }), key, (command, connectionName) => this.validateCommand(command, connectionName).isAllowed);
+            this.statusCache.set(key, status);
+            Logger.log(`System status collected for [${key}]`, "info");
+        }
+        catch (error) {
+            Logger.log(`Failed to collect system status for [${key}]: ${error.message}`, "error");
+            this.statusCache.set(key, {
+                reachable: true,
+                lastUpdated: new Date().toISOString(),
+            });
+        }
+    }
+    compilePatterns(patterns, connectionName, kind) {
+        if (!patterns || patterns.length === 0) {
+            return [];
+        }
+        return patterns.map((pattern) => {
+            try {
+                return new RegExp(pattern);
+            }
+            catch (error) {
+                throw new Error(`Invalid ${kind} pattern for '${connectionName}': ${pattern} (${error.message})`);
+            }
+        });
+    }
+    validateCommand(command, name) {
+        const key = this.resolveFlatName(name);
+        const whitelistRegexes = this.commandWhitelistRegexes.get(key) || [];
+        if (whitelistRegexes.length > 0) {
+            const matchesWhitelist = whitelistRegexes.some((regex) => regex.test(command));
+            if (!matchesWhitelist) {
+                return {
+                    isAllowed: false,
+                    reason: "Command not in whitelist, execution forbidden",
+                };
+            }
+        }
+        const blacklistRegexes = this.commandBlacklistRegexes.get(key) || [];
+        if (blacklistRegexes.length > 0) {
+            const matchesBlacklist = blacklistRegexes.some((regex) => regex.test(command));
+            if (matchesBlacklist) {
+                return {
+                    isAllowed: false,
+                    reason: "Command matches blacklist, execution forbidden",
+                };
+            }
+        }
+        return {
+            isAllowed: true,
+        };
+    }
+    formatCommandFailure(stdout, stderr, exitCode, exitSignal) {
+        const outputSections = [];
+        if (stdout) {
+            outputSections.push(stdout);
+        }
+        if (stderr) {
+            outputSections.push(`[stderr]\n${stderr}`);
+        }
+        if (exitCode !== undefined) {
+            outputSections.push(`[exit code] ${exitCode}`);
+        }
+        if (exitSignal) {
+            outputSections.push(`[signal] ${exitSignal}`);
+        }
+        return outputSections.join("\n");
+    }
+    /**
+     * Format the output of a command that finished successfully.
+     *
+     * stderr is kept instead of being dropped: with `pty: false` a successful
+     * command's stderr is delivered on a separate channel, and discarding it
+     * silently loses warnings and progress output written there by tools such as
+     * git, docker and npm. With the default `pty: true` the remote end merges
+     * stderr into stdout, so `stderr` is empty here and the output is unchanged.
+     */
+    formatCommandSuccess(stdout, stderr) {
+        if (!stderr) {
+            return stdout;
+        }
+        return [stdout, `[stderr]\n${stderr}`].filter(Boolean).join("\n");
+    }
+    async runCommandInternal(cmdString, directory, name, options = {}) {
+        if (!options.prevalidatedInternalCommand) {
+            const validationResult = this.validateCommand(cmdString, name);
+            if (!validationResult.isAllowed) {
+                throw new ToolError("COMMAND_VALIDATION_FAILED", `Command validation failed: ${validationResult.reason}`, false);
+            }
+        }
+        const key = this.resolveFlatName(name);
+        const config = this.getConfig(name);
+        const transportMode = this.getTransportMode(config);
+        const timeout = options.timeout ??
+            (transportMode === "shell"
+                ? this.getShellCommandTimeoutMs(config)
+                : this.getCommandTimeoutMs(config));
+        const connectionTimeoutMs = this.getConnectionTimeoutMs(config);
+        const client = await this.withTimeout(this.ensureConnected(name), connectionTimeoutMs, () => this.invalidateConnection(key), `SSH connection [${key}] timed out after ${connectionTimeoutMs}ms`);
+        if (transportMode === "shell") {
+            return this.runShellCommand(cmdString, directory, name, timeout);
+        }
+        return this.runExecCommand(client, config, cmdString, directory, timeout, key);
+    }
+    runExecCommand(client, config, cmdString, directory, timeout, key) {
+        let commandToRun = directory
+            ? `cd -- ${shellQuote(directory)} && ${cmdString}`
+            : cmdString;
+        if (config.commandTemplate) {
+            commandToRun = applyCommandTemplate(config.commandTemplate, commandToRun);
+        }
+        const maxOutputBytes = this.getMaxOutputBytes(config);
+        return new Promise((resolve, reject) => {
+            let openTimeoutId;
+            let commandTimeoutId;
+            let settled = false;
+            const cleanup = () => {
+                if (openTimeoutId) {
+                    clearTimeout(openTimeoutId);
+                }
+                if (commandTimeoutId) {
+                    clearTimeout(commandTimeoutId);
+                }
+            };
+            client.exec(commandToRun, { pty: config.pty !== undefined ? config.pty : true }, (err, stream) => {
+                if (openTimeoutId) {
+                    clearTimeout(openTimeoutId);
+                    openTimeoutId = undefined;
+                }
+                if (settled) {
+                    try {
+                        stream?.close();
+                    }
+                    catch {
+                        // Ignore late stream cleanup errors after timeout.
+                    }
+                    return;
+                }
+                if (err) {
+                    cleanup();
+                    settled = true;
+                    reject(new ToolError("COMMAND_EXECUTION_ERROR", `Command execution error: ${err.message}`, true));
+                    return;
+                }
+                let data = "";
+                let errorData = "";
+                let exitCode;
+                let exitSignal;
+                let capturedBytes = 0;
+                // Decoding each chunk on its own corrupts any multi-byte character
+                // that happens to be split across a chunk boundary.
+                const stdoutDecoder = new StringDecoder("utf8");
+                const stderrDecoder = new StringDecoder("utf8");
+                // Without a cap a single command (`cat` on a huge file, an unbounded
+                // `journalctl`, ...) can buffer unbounded output in memory until the
+                // command timeout fires. Stop capturing and close the channel instead.
+                const appendChunk = (chunk, isStderr) => {
+                    if (settled) {
+                        return;
+                    }
+                    if (maxOutputBytes > 0 &&
+                        capturedBytes + chunk.length > maxOutputBytes) {
+                        const remaining = maxOutputBytes - capturedBytes;
+                        if (remaining > 0) {
+                            const partial = chunk.subarray(0, remaining);
+                            if (isStderr) {
+                                errorData += stderrDecoder.write(partial);
+                            }
+                            else {
+                                data += stdoutDecoder.write(partial);
+                            }
+                        }
+                        capturedBytes = maxOutputBytes;
+                        cleanup();
+                        settled = true;
+                        try {
+                            stream.close();
+                        }
+                        catch {
+                            // Ignore close errors while aborting an oversized command.
+                        }
+                        const stdout = data.trimEnd();
+                        const stderr = errorData.trimEnd();
+                        reject(new ToolError("OUTPUT_LIMIT_EXCEEDED", [
+                            this.formatCommandSuccess(stdout, stderr),
+                            `[truncated] Output exceeded maxOutputBytes=${maxOutputBytes}; the command was aborted.`,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"), false));
+                        return;
+                    }
+                    capturedBytes += chunk.length;
+                    if (isStderr) {
+                        errorData += stderrDecoder.write(chunk);
+                    }
+                    else {
+                        data += stdoutDecoder.write(chunk);
+                    }
+                };
+                stream.on("data", (chunk) => appendChunk(chunk, false));
+                stream.stderr.on("data", (chunk) => appendChunk(chunk, true));
+                stream.on("exit", (code, signal) => {
+                    exitCode = code;
+                    exitSignal = signal;
+                });
+                stream.on("close", (code, signal) => {
+                    cleanup();
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    if (exitCode === undefined) {
+                        exitCode = code;
+                    }
+                    if (!exitSignal && signal) {
+                        exitSignal = signal;
+                    }
+                    // Flush any trailing incomplete multi-byte sequence.
+                    const stdout = (data + stdoutDecoder.end()).trimEnd();
+                    const stderr = (errorData + stderrDecoder.end()).trimEnd();
+                    const hasNonZeroExitCode = exitCode !== undefined && exitCode !== 0;
+                    const hasExitSignal = exitSignal !== undefined && exitSignal !== "";
+                    if (hasNonZeroExitCode || hasExitSignal) {
+                        reject(new ToolError("COMMAND_EXECUTION_ERROR", this.formatCommandFailure(stdout, stderr, exitCode, exitSignal) ||
+                            (hasExitSignal
+                                ? `Command terminated by signal ${exitSignal}${exitCode !== undefined ? ` (exit code ${exitCode})` : ""}`
+                                : `Command failed with exit code ${exitCode}`), false));
+                        return;
+                    }
+                    resolve(this.formatCommandSuccess(stdout, stderr));
+                });
+                stream.on("error", (streamError) => {
+                    cleanup();
+                    settled = true;
+                    reject(new ToolError("COMMAND_EXECUTION_ERROR", `Stream error: ${streamError.message}`, true));
+                });
+                commandTimeoutId = setTimeout(() => {
+                    try {
+                        stream.close();
+                    }
+                    catch {
+                        // Ignore stream close errors during timeout handling.
+                    }
+                    if (!settled) {
+                        settled = true;
+                        const stdout = data.trimEnd();
+                        const stderr = errorData.trimEnd();
+                        reject(new ToolError("COMMAND_TIMEOUT", [
+                            this.formatCommandFailure(stdout, stderr),
+                            `[timeout] Command timed out after ${timeout}ms`,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"), true));
+                    }
+                }, timeout);
+            });
+            openTimeoutId = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    this.invalidateConnection(key);
+                    reject(new ToolError("COMMAND_TIMEOUT", `[timeout] Command channel did not open within ${timeout}ms`, true));
+                }
+            }, timeout);
+        });
+    }
+    async initializeShellSession(client, key, config) {
+        const stream = await new Promise((resolve, reject) => {
+            client.shell({ term: "xterm" }, (err, channel) => {
+                if (err) {
+                    reject(new ToolError("SSH_CONNECTION_FAILED", `Failed to initialize shell transport for [${key}]: ${err.message}`, true));
+                    return;
+                }
+                resolve(channel);
+            });
+        });
+        this.shellStreams.set(key, stream);
+        this.shellReady.set(key, false);
+        this.shellQueues.set(key, Promise.resolve());
+        this.shellBuffers.set(key, "");
+        this.shellDecoders.set(key, new StringDecoder("utf8"));
+        const readyId = this.generateMarkerId("ready");
+        const readyMarker = `__MCP_READY__${readyId}__`;
+        try {
+            await this.waitForShellReady(key, stream, readyMarker, this.getShellReadyTimeoutMs(config));
+            await this.configureShellSession(key, stream, config);
+            this.shellReady.set(key, true);
+            this.attachShellLifecycleListeners(key, stream);
+        }
+        catch (error) {
+            this.cleanupShellState(key, true);
+            throw new ToolError("SSH_CONNECTION_FAILED", `Shell transport initialization failed for [${key}]: ${error.message}`, true);
+        }
+    }
+    waitForShellReady(key, stream, readyMarker, timeout) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId;
+            let probeIntervalId;
+            // Escape the marker in the probe payload so the command text does not
+            // contain the literal marker string.  When the PTY echoes the probe
+            // command back (echo is still on during the first probe), the echo no
+            // longer matches readyMarker, so resolveIfReady only fires once the
+            // printf actually executes and emits the literal marker.  Without this,
+            // waitForShellReady resolves on the echoed command line, before the
+            // probed command has run — which is fatal when the probed command is
+            // `stty -echo` in configureShellSession: the next real command would be
+            // sent before echo is disabled and would itself be echoed, leaving
+            // extractShellCommandResult matching markers inside the echoed script.
+            const escapedMarker = readyMarker
+                .replace(/\\/g, "\\\\")
+                .replace(/_/g, "\\137");
+            const payload = `printf '${escapedMarker}\\n'\n`;
+            const cleanup = () => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                if (probeIntervalId) {
+                    clearInterval(probeIntervalId);
+                }
+                stream.off("data", onData);
+                stream.off("close", onClose);
+                stream.off("error", onError);
+            };
+            const resolveIfReady = () => {
+                const buffer = this.shellBuffers.get(key) || "";
+                const markerIndex = buffer.indexOf(readyMarker);
+                if (markerIndex === -1) {
+                    return;
+                }
+                const lineEndIndex = buffer.indexOf("\n", markerIndex);
+                if (lineEndIndex === -1) {
+                    return;
+                }
+                if (!settled) {
+                    settled = true;
+                    this.shellBuffers.set(key, buffer.slice(lineEndIndex + 1));
+                    cleanup();
+                    resolve();
+                }
+            };
+            const onData = (chunk) => {
+                this.appendShellBuffer(key, chunk);
+                resolveIfReady();
+            };
+            const onClose = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(new Error("Shell channel closed before ready probe completed"));
+            };
+            const onError = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            stream.on("data", onData);
+            stream.on("close", onClose);
+            stream.on("error", onError);
+            timeoutId = setTimeout(() => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(new Error(`Timed out waiting for shell ready marker after ${timeout}ms`));
+            }, timeout);
+            stream.write(payload);
+            probeIntervalId = setInterval(() => {
+                if (!settled) {
+                    stream.write(payload);
+                }
+            }, 1000);
+            resolveIfReady();
+        });
+    }
+    attachShellLifecycleListeners(key, stream) {
+        const handleUnavailable = (reason) => {
+            if (this.shellStreams.get(key) !== stream) {
+                return;
+            }
+            Logger.log(`Shell channel [${key}] unavailable: ${reason}`, "error");
+            this.invalidateConnection(key);
+        };
+        stream.on("close", () => handleUnavailable("closed"));
+        stream.on("error", (error) => handleUnavailable(`error: ${error.message}`));
+    }
+    async configureShellSession(key, stream, config) {
+        // Send `export PS1=''` and `stty -echo` first.  The verification probe
+        // (printf, emitted by waitForShellReady below with an escaped marker)
+        // follows them in the same shell input stream, so by the time the
+        // probe's literal marker is emitted, stty has executed and terminal echo
+        // is off.  We must NOT write our own `printf '${marker}'` here: that
+        // payload contains the literal marker, so when echo is still on it would
+        // be echoed back and waitForShellReady would resolve prematurely, before
+        // stty runs — leaving the next real command echoed.
+        stream.write("export PS1=''\n");
+        stream.write("stty -echo >/dev/null 2>&1 || true\n");
+        const verifyId = this.generateMarkerId("stty");
+        const verifyMarker = `__MCP_CONFIGURE__${verifyId}__`;
+        await this.waitForShellReady(key, stream, verifyMarker, this.getShellReadyTimeoutMs(config));
+    }
+    runShellCommand(cmdString, directory, name, timeout) {
+        const key = this.resolveFlatName(name);
+        return this.enqueueShellCommand(key, () => this.executeShellCommand(key, cmdString, directory, timeout));
+    }
+    enqueueShellCommand(key, task) {
+        const previous = this.shellQueues.get(key) || Promise.resolve();
+        const next = previous.catch(() => undefined).then(task);
+        this.shellQueues.set(key, next.then(() => undefined, () => undefined));
+        return next;
+    }
+    executeShellCommand(key, cmdString, directory, timeout) {
+        const stream = this.shellStreams.get(key);
+        if (!stream || this.shellReady.get(key) !== true) {
+            throw new ToolError("SSH_CONNECTION_FAILED", `Shell transport for [${key}] is not ready`, true);
+        }
+        const commandId = this.generateMarkerId("command");
+        const config = this.getConfig(key);
+        const script = this.buildShellCommandScript(commandId, cmdString, directory, config.commandTemplate);
+        const maxOutputBytes = this.getMaxOutputBytes(config);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeoutId;
+            const scanState = {
+                outputStartIndex: -1,
+                tail: "",
+                // Whatever the previous command left behind cannot hold this command's
+                // markers, so the scan starts past it.
+                tailStart: (this.shellBuffers.get(key) || "").length,
+                countedOutputEndIndex: -1,
+                capturedOutputBytes: 0,
+            };
+            const cleanup = () => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                stream.off("data", onData);
+                stream.off("close", onClose);
+                stream.off("error", onError);
+            };
+            const finish = (error, output) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve(output || "");
+            };
+            const resolveIfComplete = () => {
+                const matched = this.extractShellCommandResult(key, commandId, scanState);
+                if (maxOutputBytes > 0 &&
+                    scanState.capturedOutputBytes > maxOutputBytes) {
+                    // The shell channel is shared by every command on this connection,
+                    // so it cannot simply be closed like an exec channel: the command
+                    // would keep writing into the buffer. Drop the connection instead.
+                    this.invalidateConnection(key);
+                    finish(new ToolError("OUTPUT_LIMIT_EXCEEDED", `[truncated] Output exceeded maxOutputBytes=${maxOutputBytes}; the command was aborted.`, false));
+                    return;
+                }
+                if (!matched) {
+                    return;
+                }
+                this.shellBuffers.set(key, matched.remainder);
+                const output = this.stripLeadingBeginMarker(this.cleanShellOutput(matched.output), commandId).trimEnd();
+                if (matched.exitCode !== 0) {
+                    finish(new ToolError("COMMAND_EXECUTION_ERROR", this.formatCommandFailure(output, "", matched.exitCode) ||
+                        `Command failed with exit code ${matched.exitCode}`, false));
+                    return;
+                }
+                finish(undefined, output);
+            };
+            const onData = (chunk) => {
+                scanState.tail += this.appendShellBuffer(key, chunk);
+                resolveIfComplete();
+            };
+            const onClose = () => {
+                finish(new ToolError("COMMAND_EXECUTION_ERROR", "Shell channel closed during command execution", true));
+            };
+            const onError = (error) => {
+                finish(new ToolError("COMMAND_EXECUTION_ERROR", `Shell channel error during command execution: ${error.message}`, true));
+            };
+            stream.on("data", onData);
+            stream.on("close", onClose);
+            stream.on("error", onError);
+            timeoutId = setTimeout(() => {
+                this.invalidateConnection(key);
+                finish(new ToolError("COMMAND_TIMEOUT", `[timeout] Command timed out after ${timeout}ms`, true));
+            }, timeout);
+            stream.write(script);
+            resolveIfComplete();
+        });
+    }
+    buildShellCommandScript(commandId, cmdString, directory, commandTemplate) {
+        const beginMarker = `__MCP_BEGIN__${commandId}__`;
+        const endMarker = `__MCP_END__${commandId}__RC__`;
+        let commandBody = directory
+            ? `cd -- ${shellQuote(directory)} && { ${cmdString}; }`
+            : `{ ${cmdString}; }`;
+        if (commandTemplate) {
+            commandBody = applyCommandTemplate(commandTemplate, commandBody);
+        }
+        return [
+            `printf '${beginMarker}\\n'`,
+            commandBody,
+            "__mcp_rc=$?",
+            `printf '\\n${endMarker}%s__\\n' "$__mcp_rc"`,
+            "",
+        ].join("\n");
+    }
+    /**
+     * Drop the part of the tail that can no longer start a marker: a marker only
+     * straddles the boundary of the chunk that just arrived, so keeping the last
+     * `markerLength - 1` characters is enough.
+     */
+    trimShellScanTail(scanState, markerLength) {
+        this.advanceShellScanTail(scanState, scanState.tail.length - Math.min(scanState.tail.length, markerLength - 1));
+    }
+    advanceShellScanTail(scanState, offset) {
+        if (offset <= 0) {
+            return;
+        }
+        scanState.tailStart += offset;
+        scanState.tail = scanState.tail.slice(offset);
+    }
+    /**
+     * Locate a finished command, scanning only the freshly arrived tail. The
+     * accumulated buffer is read once, after the whole end marker is in hand.
+     */
+    extractShellCommandResult(key, commandId, scanState) {
+        if (scanState.outputStartIndex === -1) {
+            const beginMarker = `__MCP_BEGIN__${commandId}__`;
+            const beginIndex = scanState.tail.indexOf(beginMarker);
+            if (beginIndex === -1) {
+                this.trimShellScanTail(scanState, beginMarker.length);
+                return null;
+            }
+            const beginLineEndIndex = scanState.tail.indexOf("\n", beginIndex);
+            if (beginLineEndIndex === -1) {
+                this.advanceShellScanTail(scanState, beginIndex);
+                return null;
+            }
+            this.advanceShellScanTail(scanState, beginLineEndIndex + 1);
+            scanState.outputStartIndex = scanState.tailStart;
+            scanState.countedOutputEndIndex = scanState.tailStart;
+        }
+        // Search the fixed prefix rather than the whole pattern: its length is
+        // known, which is what makes the retained overlap provably sufficient. The
+        // exit code is then parsed from the short slice that follows it.
+        const endPrefix = `__MCP_END__${commandId}__RC__`;
+        const endIndex = scanState.tail.indexOf(endPrefix);
+        if (endIndex === -1) {
+            // Keep the marker overlap plus CRLF immediately before it. The command
+            // wrapper emits that newline as framing, so it must not count against the
+            // user's output limit.
+            this.trimShellScanTail(scanState, endPrefix.length + 2);
+            this.countShellOutputThrough(key, scanState, scanState.tailStart);
+            return null;
+        }
+        const absoluteEndIndex = scanState.tailStart + endIndex;
+        const buffer = this.shellBuffers.get(key) || "";
+        let outputEndIndex = absoluteEndIndex;
+        if (buffer[outputEndIndex - 1] === "\n") {
+            outputEndIndex -= 1;
+            if (buffer[outputEndIndex - 1] === "\r") {
+                outputEndIndex -= 1;
+            }
+        }
+        this.countShellOutputThrough(key, scanState, outputEndIndex);
+        const exitCodeStart = endIndex + endPrefix.length;
+        const matched = SHELL_EXIT_CODE_PATTERN.exec(scanState.tail.slice(exitCodeStart, exitCodeStart + SHELL_EXIT_CODE_MAX_LENGTH));
+        if (!matched) {
+            // The prefix arrived but the exit code has not; resume from here.
+            this.advanceShellScanTail(scanState, endIndex);
+            return null;
+        }
+        const consumedEndIndex = absoluteEndIndex + endPrefix.length + matched[0].length;
+        return {
+            output: buffer.slice(scanState.outputStartIndex, absoluteEndIndex),
+            exitCode: Number.parseInt(matched[1], 10),
+            remainder: buffer.slice(consumedEndIndex),
+        };
+    }
+    countShellOutputThrough(key, scanState, endIndex) {
+        if (scanState.outputStartIndex === -1 ||
+            endIndex <= scanState.countedOutputEndIndex) {
+            return;
+        }
+        const buffer = this.shellBuffers.get(key) || "";
+        scanState.capturedOutputBytes += Buffer.byteLength(buffer.slice(scanState.countedOutputEndIndex, endIndex), "utf8");
+        scanState.countedOutputEndIndex = endIndex;
+    }
+    /** Appends the decoded chunk and returns just that text. */
+    appendShellBuffer(key, chunk) {
+        let decoder = this.shellDecoders.get(key);
+        if (!decoder) {
+            decoder = new StringDecoder("utf8");
+            this.shellDecoders.set(key, decoder);
+        }
+        // Concatenation alone stays cheap; it is reading the result that forces the
+        // rope to flatten, so nothing here may inspect the accumulated buffer.
+        const text = decoder.write(chunk);
+        const current = this.shellBuffers.get(key) || "";
+        this.shellBuffers.set(key, current + text);
+        return text;
+    }
+    cleanShellOutput(output) {
+        return output
+            .replace(ANSI_OSC_PATTERN, "")
+            .replace(ANSI_CSI_PATTERN, "")
+            .replace(/\r\n/g, "\n")
+            .replace(/\r/g, "\n");
+    }
+    stripLeadingBeginMarker(output, commandId) {
+        const beginPrefix = `__MCP_BEGIN__${commandId}__`;
+        if (!output.startsWith(beginPrefix)) {
+            return output;
+        }
+        const newlineIndex = output.indexOf("\n");
+        if (newlineIndex === -1) {
+            return "";
+        }
+        return output.slice(newlineIndex + 1);
+    }
+    generateMarkerId(prefix) {
+        return `${prefix}_${Date.now()}_${Math.random().toString(16).slice(2, 10)}`;
+    }
+    cleanupShellState(key, closeStream = false) {
+        const stream = this.shellStreams.get(key);
+        if (closeStream && stream) {
+            try {
+                stream.close();
+            }
+            catch {
+                // Ignore shell close errors during cleanup.
+            }
+        }
+        this.shellStreams.delete(key);
+        this.shellReady.delete(key);
+        this.shellQueues.delete(key);
+        this.shellBuffers.delete(key);
+        this.shellDecoders.delete(key);
+    }
+    clearConnectionState(key) {
+        const pendingStatusCollection = this.pendingStatusCollections.get(key);
+        if (pendingStatusCollection) {
+            clearTimeout(pendingStatusCollection);
+            this.pendingStatusCollections.delete(key);
+        }
+        this.cleanupShellState(key);
+        this.connected.set(key, false);
+        this.clients.delete(key);
+        this.pendingConnections.delete(key);
+    }
+    invalidateConnection(key) {
+        const client = this.clients.get(key);
+        this.clearConnectionState(key);
+        if (client) {
+            try {
+                client.end();
+            }
+            catch {
+                // Ignore client close errors during invalidation.
+            }
+        }
+    }
+}
+//# sourceMappingURL=ssh-connection-manager.js.map