host-execution-mcp 1.0.0

package/dist/kubectl/runner.js

@@ -0,0 +1,79 @@
+import { assertNamespaceAllowed } from "../config.js";
+import { bashSingleQuote, shellEscapeArg } from "../utils/shell-quote.js";
+export function buildListPodsCommand(namespace, options) {
+    const parts = ["kubectl get pods", `-n ${shellEscapeArg(namespace)}`];
+    if (options.labelSelector) {
+        parts.push(`-l ${shellEscapeArg(options.labelSelector)}`);
+    }
+    if (options.fieldSelector) {
+        parts.push(`--field-selector=${shellEscapeArg(options.fieldSelector)}`);
+    }
+    const output = options.output ?? "wide";
+    if (output === "json") {
+        parts.push("-o json");
+    }
+    else if (output === "name") {
+        parts.push("-o name");
+    }
+    else {
+        parts.push("-o wide");
+    }
+    return parts.join(" ");
+}
+export function buildKubectlExecCommand(namespace, pod, command, container) {
+    const parts = [
+        "kubectl exec",
+        `-n ${shellEscapeArg(namespace)}`,
+        shellEscapeArg(pod),
+    ];
+    if (container) {
+        parts.push(`-c ${shellEscapeArg(container)}`);
+    }
+    parts.push("--", "bash", "-lc", bashSingleQuote(command));
+    return parts.join(" ");
+}
+export function buildKubectlLogsCommand(namespace, pod, options) {
+    const parts = [
+        "kubectl logs",
+        `-n ${shellEscapeArg(namespace)}`,
+        shellEscapeArg(pod),
+    ];
+    if (options.container) {
+        parts.push(`-c ${shellEscapeArg(options.container)}`);
+    }
+    if (options.since) {
+        parts.push(`--since=${shellEscapeArg(options.since)}`);
+    }
+    parts.push(`--tail=${options.tail ?? 200}`);
+    return parts.join(" ");
+}
+export async function runOnAccess(client, config, command, timeoutMs, cwd) {
+    return client.exec(command, timeoutMs ?? config.defaultTimeoutMs, cwd);
+}
+export function validateNamespace(config, namespace) {
+    assertNamespaceAllowed(config, namespace);
+}
+export class KubectlRunner {
+    client;
+    config;
+    constructor(client, config) {
+        this.client = client;
+        this.config = config;
+    }
+    listPods(namespace, options, timeoutMs) {
+        validateNamespace(this.config, namespace);
+        const command = buildListPodsCommand(namespace, options);
+        return runOnAccess(this.client, this.config, command, timeoutMs);
+    }
+    exec(namespace, pod, command, container, timeoutMs) {
+        validateNamespace(this.config, namespace);
+        const kubectlCommand = buildKubectlExecCommand(namespace, pod, command, container);
+        return runOnAccess(this.client, this.config, kubectlCommand, timeoutMs);
+    }
+    logs(namespace, pod, options, timeoutMs) {
+        validateNamespace(this.config, namespace);
+        const kubectlCommand = buildKubectlLogsCommand(namespace, pod, options);
+        return runOnAccess(this.client, this.config, kubectlCommand, timeoutMs);
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/kubectl/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/kubectl/runner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAI1E,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,OAIC;IAED,MAAM,KAAK,GAAG,CAAC,kBAAkB,EAAE,MAAM,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAEtE,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,MAAM,cAAc,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,oBAAoB,cAAc,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;IACxC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;SAAM,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,SAAiB,EACjB,GAAW,EACX,OAAe,EACf,SAAkB;IAElB,MAAM,KAAK,GAAG;QACZ,cAAc;QACd,MAAM,cAAc,CAAC,SAAS,CAAC,EAAE;QACjC,cAAc,CAAC,GAAG,CAAC;KACpB,CAAC;IAEF,IAAI,SAAS,EAAE,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,MAAM,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,SAAiB,EACjB,GAAW,EACX,OAIC;IAED,MAAM,KAAK,GAAG;QACZ,cAAc;QACd,MAAM,cAAc,CAAC,SAAS,CAAC,EAAE;QACjC,cAAc,CAAC,GAAG,CAAC;KACpB,CAAC;IAEF,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,MAAM,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,WAAW,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAU,OAAO,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAoB,EACpB,MAAiB,EACjB,OAAe,EACf,SAAkB,EAClB,GAAY;IAEZ,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,IAAI,MAAM,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,SAAiB;IACpE,sBAAsB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,OAAO,aAAa;IAEL;IACA;IAFnB,YACmB,MAAoB,EACpB,MAAiB;QADjB,WAAM,GAAN,MAAM,CAAc;QACpB,WAAM,GAAN,MAAM,CAAW;IACjC,CAAC;IAEJ,QAAQ,CACN,SAAiB,EACjB,OAIC,EACD,SAAkB;QAElB,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IACnE,CAAC;IAED,IAAI,CACF,SAAiB,EACjB,GAAW,EACX,OAAe,EACf,SAAkB,EAClB,SAAkB;QAElB,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC1C,MAAM,cAAc,GAAG,uBAAuB,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;QACnF,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;IAC1E,CAAC;IAED,IAAI,CACF,SAAiB,EACjB,GAAW,EACX,OAIC,EACD,SAAkB;QAElB,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC1C,MAAM,cAAc,GAAG,uBAAuB,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;QACxE,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;IAC1E,CAAC;CACF"}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AppConfig } from "./config.js";
+export declare function createServer(config: AppConfig): McpServer;

package/dist/server.js

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VERSION } from "./version.js";
+import { AccessRuntime } from "./access/index.js";
+import { buildServerInstructions } from "./instructions.js";
+import { KubectlRunner } from "./kubectl/runner.js";
+import { AccessClient } from "./ssh/access-client.js";
+import { registerPrompts, registerTools } from "./tools/register.js";
+import { RemoteExecutor } from "./utils/remote-executor.js";
+export function createServer(config) {
+    const server = new McpServer({
+        name: "host-execution-mcp",
+        version: VERSION,
+    }, {
+        instructions: buildServerInstructions(config),
+    });
+    const accessClient = new AccessClient(config);
+    const access = new AccessRuntime(config, accessClient);
+    const kubectl = new KubectlRunner(accessClient, config);
+    const remote = new RemoteExecutor(access, kubectl, config);
+    registerTools(server, { config, accessClient, access, kubectl, remote });
+    registerPrompts(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC5C,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,OAAO;KACjB,EACD;QACE,YAAY,EAAE,uBAAuB,CAAC,MAAM,CAAC;KAC9C,CACF,CAAC;IAEF,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAE3D,aAAa,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,eAAe,CAAC,MAAM,CAAC,CAAC;IAExB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/ssh/access-client.d.ts

@@ -0,0 +1,62 @@
+import type { AppConfig } from "../config.js";
+import { type SftpCopyOptions, type SftpTransferResult } from "../utils/copy-transfer.js";
+import { type AccessCheckResult } from "./access-errors.js";
+export interface ExecOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+}
+export declare class AccessClient {
+    private client;
+    private connecting;
+    /** Serializes ensureAccessReady / check cache updates. */
+    private gate;
+    private readonly config;
+    private readyUntil;
+    private unavailableUntil;
+    private lastUnavailable;
+    constructor(config: AppConfig);
+    /**
+     * Ensure accessClient is reachable (TTL-cached). Uses an ephemeral SSH probe ?
+     * never disconnects an in-flight shared exec session on success.
+     */
+    ensureAccessReady(): Promise<void>;
+    /**
+     * Short-timeout Local to ACCESS probe (ephemeral client; <=10s worst case).
+     * Respects negative TTL (returns cached failure). Does not sever shared exec SSH.
+     */
+    check(): Promise<AccessCheckResult>;
+    exec(command: string, timeoutMs?: number, cwd?: string, signal?: AbortSignal): Promise<ExecOutput>;
+    disconnect(): void;
+    /**
+     * Upload local path (file or directory) ? accessClient via independent Hop1 SFTP.
+     * Transfer-phase errors are not reclassified into ACCESS_UNAVAILABLE.
+     */
+    uploadPath(localPath: string, remotePath: string, options?: SftpCopyOptions): Promise<SftpTransferResult>;
+    /**
+     * Download accessClient path (file or directory) ? local via independent Hop1 SFTP.
+     */
+    downloadPath(remotePath: string, localPath: string, options?: SftpCopyOptions): Promise<SftpTransferResult>;
+    private withGate;
+    private markReady;
+    /**
+     * Record a connect-phase failure. Negative TTL only for classified causes
+     * (not UNKNOWN), so transient unknowns are not blackholed for 15s.
+     */
+    private markConnectUnavailable;
+    /** Ephemeral SSH + shell probe; never assigns or disconnects `this.client`. */
+    private probeEphemeral;
+    private remoteSha256;
+    private ensureConnected;
+    private ensureConnectedUnlocked;
+    private requireClient;
+    /**
+     * Open a dedicated ssh2 Client with readyTimeout + hard deadline
+     * (covers TCP blackhole where ssh2 readyTimeout alone is insufficient).
+     * Paradi auto: try slash then compound on AUTH_FAILED; pin winner for this process.
+     */
+    private openSshClient;
+    private connectOnce;
+    private execOnClient;
+}

package/dist/ssh/access-client.js

@@ -0,0 +1,470 @@
+import { Client } from "ssh2";
+import { resolveAccessSshIdentity, resolveSshAuthOptions } from "../config.js";
+import { getPinnedParadiAuth, isParadiAuthFailureMessage, pinParadiAuth, resolveParadiAuthModesToTry, resolveParadiConnectParams, } from "../access/paradi-auth.js";
+import { bashSingleQuote, buildBashLcCommand } from "../utils/shell-quote.js";
+import { throwIfAborted, } from "../utils/copy-transfer.js";
+import { transferLocalAccess } from "./access-sftp.js";
+import { AccessUnavailableError, isAccessUnavailableError, shouldRetryAccessConnect, toAccessUnavailableError, } from "./access-errors.js";
+/** Positive readiness TTL after a successful probe / connect. */
+const READY_TTL_MS = 30_000;
+/** Negative cache after classified connect failure (avoid hammering). */
+const UNAVAILABLE_TTL_MS = 15_000;
+/** SSH readyTimeout + hard deadline for probe / check. */
+const PROBE_READY_TIMEOUT_MS = 5_000;
+/** Shell verify after SSH ready (within overall ?10s probe budget). */
+const PROBE_SHELL_TIMEOUT_MS = 5_000;
+/** Shared exec session connect timeout. */
+const EXEC_CONNECT_TIMEOUT_MS = 20_000;
+/** Max reconnects for transient stream-phase drops during exec. */
+const MAX_RECONNECT_ATTEMPTS = 3;
+export class AccessClient {
+    client = null;
+    connecting = null;
+    /** Serializes ensureAccessReady / check cache updates. */
+    gate = Promise.resolve();
+    config;
+    readyUntil = 0;
+    unavailableUntil = 0;
+    lastUnavailable = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Ensure accessClient is reachable (TTL-cached). Uses an ephemeral SSH probe ?
+     * never disconnects an in-flight shared exec session on success.
+     */
+    async ensureAccessReady() {
+        await this.withGate(async () => {
+            const now = Date.now();
+            if (now < this.unavailableUntil && this.lastUnavailable) {
+                throw this.lastUnavailable;
+            }
+            if (this.client && now < this.readyUntil) {
+                return;
+            }
+            try {
+                await this.probeEphemeral();
+                this.markReady();
+                if (!this.client) {
+                    await this.ensureConnectedUnlocked();
+                }
+            }
+            catch (error) {
+                throw this.markConnectUnavailable(error);
+            }
+        });
+    }
+    /**
+     * Short-timeout Local to ACCESS probe (ephemeral client; <=10s worst case).
+     * Respects negative TTL (returns cached failure). Does not sever shared exec SSH.
+     */
+    async check() {
+        return this.withGate(async () => {
+            const identity = resolveAccessSshIdentity(this.config);
+            const host = identity.host;
+            const port = identity.port;
+            const now = Date.now();
+            if (now < this.unavailableUntil && this.lastUnavailable) {
+                return this.lastUnavailable.toJSON();
+            }
+            const started = Date.now();
+            try {
+                await this.probeEphemeral();
+                this.markReady();
+                const pinned = getPinnedParadiAuth(this.config);
+                const kindHint = this.config.accessKind === "paradi-gateway"
+                    ? ` (paradi → ${this.config.targetHost}${pinned ? `, auth=${pinned}` : ""})`
+                    : "";
+                return {
+                    reachable: true,
+                    latencyMs: Date.now() - started,
+                    host,
+                    port,
+                    auth: "ok",
+                    ...(pinned ? { paradiAuth: pinned } : {}),
+                    message: `ACCESS OK: ${host}:${port}${kindHint}`,
+                };
+            }
+            catch (error) {
+                return this.markConnectUnavailable(error).toJSON();
+            }
+        });
+    }
+    async exec(command, timeoutMs, cwd, signal) {
+        const effectiveTimeout = timeoutMs ?? this.config.defaultTimeoutMs;
+        const remoteCommand = buildBashLcCommand(command, cwd);
+        const started = Date.now();
+        await this.ensureAccessReady();
+        let lastError;
+        for (let attempt = 1; attempt <= MAX_RECONNECT_ATTEMPTS; attempt++) {
+            try {
+                throwIfAborted(signal);
+                await this.ensureConnected();
+                const result = await this.execOnClient(this.requireClient(), remoteCommand, {
+                    timeoutMs: effectiveTimeout,
+                    signal,
+                });
+                this.markReady();
+                return { ...result, durationMs: Date.now() - started };
+            }
+            catch (error) {
+                lastError = error;
+                const msg = error instanceof Error ? error.message : String(error);
+                if (signal?.aborted || msg === "Copy aborted") {
+                    break;
+                }
+                // Stream-phase: only elevate true accessClient-down signals (not ECONNRESET/EPIPE).
+                const unavailable = toAccessUnavailableError(error, this.config.accessHost, this.config.accessPort, "stream");
+                if (unavailable) {
+                    throw this.markConnectUnavailable(unavailable);
+                }
+                if (!shouldRetryAccessConnect(error)) {
+                    break;
+                }
+                this.disconnect();
+                if (attempt === MAX_RECONNECT_ATTEMPTS) {
+                    break;
+                }
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    disconnect() {
+        if (this.client) {
+            this.client.end();
+            this.client = null;
+        }
+        this.connecting = null;
+    }
+    /**
+     * Upload local path (file or directory) ? accessClient via independent Hop1 SFTP.
+     * Transfer-phase errors are not reclassified into ACCESS_UNAVAILABLE.
+     */
+    async uploadPath(localPath, remotePath, options) {
+        await this.ensureAccessReady();
+        try {
+            return await transferLocalAccess({
+                direction: "upload",
+                localPath,
+                remotePath,
+                config: this.config,
+                options,
+            }, (remote, timeoutMs) => this.remoteSha256(remote, timeoutMs));
+        }
+        catch (error) {
+            // Only connect-time AccessUnavailableError from Hop1 SFTP connect is cached.
+            if (isAccessUnavailableError(error)) {
+                throw this.markConnectUnavailable(error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Download accessClient path (file or directory) ? local via independent Hop1 SFTP.
+     */
+    async downloadPath(remotePath, localPath, options) {
+        await this.ensureAccessReady();
+        try {
+            return await transferLocalAccess({
+                direction: "download",
+                localPath,
+                remotePath,
+                config: this.config,
+                options,
+            }, (remote, timeoutMs) => this.remoteSha256(remote, timeoutMs));
+        }
+        catch (error) {
+            if (isAccessUnavailableError(error)) {
+                throw this.markConnectUnavailable(error);
+            }
+            throw error;
+        }
+    }
+    async withGate(fn) {
+        const prev = this.gate;
+        let release;
+        this.gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
+    markReady() {
+        this.readyUntil = Date.now() + READY_TTL_MS;
+        this.unavailableUntil = 0;
+        this.lastUnavailable = null;
+    }
+    /**
+     * Record a connect-phase failure. Negative TTL only for classified causes
+     * (not UNKNOWN), so transient unknowns are not blackholed for 15s.
+     */
+    markConnectUnavailable(error) {
+        const unavailable = (isAccessUnavailableError(error) ? error : null) ??
+            toAccessUnavailableError(error, this.config.accessHost, this.config.accessPort, "connect") ??
+            new AccessUnavailableError({
+                causeCode: "UNKNOWN",
+                host: this.config.accessHost,
+                port: this.config.accessPort,
+                detail: error instanceof Error ? error.message : String(error),
+                cause: error,
+            });
+        this.disconnect();
+        this.readyUntil = 0;
+        if (unavailable.causeCode === "UNKNOWN") {
+            this.unavailableUntil = 0;
+            this.lastUnavailable = null;
+        }
+        else {
+            this.unavailableUntil = Date.now() + UNAVAILABLE_TTL_MS;
+            this.lastUnavailable = unavailable;
+        }
+        return unavailable;
+    }
+    /** Ephemeral SSH + shell probe; never assigns or disconnects `this.client`. */
+    async probeEphemeral() {
+        const client = await this.openSshClient(PROBE_READY_TIMEOUT_MS);
+        try {
+            const result = await this.execOnClient(client, "echo access_ok", {
+                timeoutMs: PROBE_SHELL_TIMEOUT_MS,
+            });
+            if (result.exitCode !== 0 || !result.stdout.includes("access_ok")) {
+                throw new AccessUnavailableError({
+                    causeCode: "SSH_HANDSHAKE",
+                    host: this.config.accessHost,
+                    port: this.config.accessPort,
+                    detail: `shell probe failed: exit=${result.exitCode} stdout=${result.stdout.trim()}`,
+                });
+            }
+        }
+        finally {
+            try {
+                client.end();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    async remoteSha256(remotePath, timeoutMs) {
+        const raw = await this.exec(`sha256sum ${bashSingleQuote(remotePath)} | awk '{print $1}'`, timeoutMs);
+        const hash = raw.stdout.trim().split(/\s+/)[0];
+        if (!/^[a-f0-9]{64}$/i.test(hash)) {
+            throw new Error(`Failed to compute remote sha256 for ${remotePath}: ${raw.stdout || raw.stderr}`);
+        }
+        return hash.toLowerCase();
+    }
+    async ensureConnected() {
+        await this.withGate(() => this.ensureConnectedUnlocked());
+    }
+    async ensureConnectedUnlocked() {
+        if (this.client) {
+            return;
+        }
+        if (this.connecting) {
+            await this.connecting;
+            return;
+        }
+        this.connecting = (async () => {
+            try {
+                const client = await this.openSshClient(EXEC_CONNECT_TIMEOUT_MS);
+                this.client = client;
+                client.on("close", () => {
+                    if (this.client === client) {
+                        this.client = null;
+                    }
+                });
+            }
+            catch (error) {
+                throw this.markConnectUnavailable(error);
+            }
+        })();
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new Error("SSH client is not connected");
+        }
+        return this.client;
+    }
+    /**
+     * Open a dedicated ssh2 Client with readyTimeout + hard deadline
+     * (covers TCP blackhole where ssh2 readyTimeout alone is insufficient).
+     * Paradi auto: try slash then compound on AUTH_FAILED; pin winner for this process.
+     */
+    async openSshClient(readyTimeoutMs) {
+        if (this.config.accessKind !== "paradi-gateway") {
+            const auth = resolveSshAuthOptions(this.config);
+            const identity = resolveAccessSshIdentity(this.config);
+            return this.connectOnce(readyTimeoutMs, {
+                host: identity.host,
+                port: identity.port,
+                username: identity.username,
+                password: auth.password,
+                privateKey: auth.privateKey,
+                agent: auth.agent,
+            });
+        }
+        const baseAuth = resolveSshAuthOptions(this.config);
+        const modes = resolveParadiAuthModesToTry(this.config);
+        let lastError;
+        for (let i = 0; i < modes.length; i++) {
+            const mode = modes[i];
+            const params = resolveParadiConnectParams(this.config, mode);
+            try {
+                const client = await this.connectOnce(readyTimeoutMs, {
+                    host: params.host,
+                    port: params.port,
+                    username: params.username,
+                    // Compound replaces ACCESS_PASSWORD; slash keeps it (and keys/agent still tried).
+                    password: params.password ?? baseAuth.password,
+                    privateKey: baseAuth.privateKey,
+                    agent: baseAuth.agent,
+                });
+                pinParadiAuth(this.config, mode);
+                return client;
+            }
+            catch (error) {
+                lastError = error;
+                const msg = error instanceof Error ? error.message : String(error);
+                const authFail = isParadiAuthFailureMessage(msg);
+                const hasNext = i < modes.length - 1;
+                if (authFail && hasNext) {
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+    connectOnce(readyTimeoutMs, opts) {
+        const connectConfig = {
+            host: opts.host,
+            port: opts.port,
+            username: opts.username,
+            readyTimeout: readyTimeoutMs,
+        };
+        if (opts.agent) {
+            connectConfig.agent = opts.agent;
+        }
+        if (opts.privateKey) {
+            connectConfig.privateKey = opts.privateKey;
+        }
+        if (opts.password) {
+            connectConfig.password = opts.password;
+        }
+        return new Promise((resolve, reject) => {
+            const client = new Client();
+            let settled = false;
+            const finish = (fn) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                fn();
+            };
+            const timer = setTimeout(() => {
+                finish(() => {
+                    try {
+                        client.end();
+                    }
+                    catch {
+                        // ignore
+                    }
+                    reject(Object.assign(new Error("Timed out while waiting for handshake"), {
+                        code: "ETIMEDOUT",
+                    }));
+                });
+            }, readyTimeoutMs);
+            client
+                .on("ready", () => {
+                finish(() => resolve(client));
+            })
+                .on("error", (error) => {
+                finish(() => reject(error));
+            })
+                .on("close", () => {
+                finish(() => reject(new Error("SSH closed before ready")));
+            })
+                .connect(connectConfig);
+        });
+    }
+    execOnClient(client, command, options = { timeoutMs: 60_000 }) {
+        throwIfAborted(options.signal);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let stream;
+            const cleanup = () => {
+                clearTimeout(timer);
+                options.signal?.removeEventListener("abort", onAbort);
+            };
+            const fail = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                try {
+                    stream?.close?.();
+                    stream?.destroy?.();
+                }
+                catch {
+                    // ignore
+                }
+                reject(error instanceof Error ? error : new Error(String(error)));
+            };
+            const onAbort = () => {
+                fail(new Error("Copy aborted"));
+            };
+            const timer = setTimeout(() => {
+                fail(new Error(`Operation timed out after ${options.timeoutMs}ms`));
+            }, options.timeoutMs);
+            if (options.signal) {
+                if (options.signal.aborted) {
+                    onAbort();
+                    return;
+                }
+                options.signal.addEventListener("abort", onAbort, { once: true });
+            }
+            client.exec(command, (error, execStream) => {
+                if (error) {
+                    fail(error);
+                    return;
+                }
+                stream = execStream;
+                let stdout = "";
+                let stderr = "";
+                execStream
+                    .on("close", (code) => {
+                    if (settled) {
+                        return;
+                    }
+                    settled = true;
+                    cleanup();
+                    resolve({
+                        stdout,
+                        stderr,
+                        exitCode: code ?? 1,
+                    });
+                })
+                    .on("data", (chunk) => {
+                    stdout += chunk.toString();
+                });
+                execStream.stderr.on("data", (chunk) => {
+                    stderr += chunk.toString();
+                });
+            });
+        });
+    }
+}
+//# sourceMappingURL=access-client.js.map