import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process"; import { randomBytes } from "node:crypto"; import { closeSync, createReadStream, existsSync, mkdirSync, mkdtempSync, openSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join, posix } from "node:path"; import { Readable } from "node:stream"; import { setTimeout as delay } from "node:timers/promises"; import { type BashOperations, type ReadOperations, type WriteOperations, withFileMutationQueue, } from "@earendil-works/pi-coding-agent"; export function quote(value: string): string { if (value.includes("\0")) { throw new Error("Remote paths and commands cannot contain NUL"); } return `'${value.replaceAll("'", "'\\''")}'`; } // A closed channel's stdin must stop the command group, including ordinary child processes. export const REMOTE_COMMAND = `set +e set -m bash -c "$1" /dev/null kill -TERM -- -"$command_pid" 2>/dev/null sleep 1 kill -KILL -- -"$command_pid" 2>/dev/null ) <&0 & watcher=$! set +m trap 'kill -TERM -- -"$command_pid" 2>/dev/null' HUP INT TERM wait "$command_pid" status=$? kill -KILL -- -"$command_pid" 2>/dev/null kill -TERM -- -"$watcher" 2>/dev/null wait "$watcher" 2>/dev/null exit "$status"`; // Stage and verify the transfer before replacement so a lost channel cannot truncate the target. export const REMOTE_WRITE = `set -e path=$1 links=0 while test -L "$path"; do links=$((links + 1)) test "$links" -le 40 link=$(readlink -- "$path") case "$link" in /*) path=$link ;; *) path=$(dirname -- "$path")/$link ;; esac done test ! -e "$path" || test -f "$path" staged=$(mktemp "$(dirname -- "$path")/.pi-write.XXXXXXXX") || { echo 'Atomic remote writes require write access to the parent directory' >&2 exit 1 } trap 'rm -f -- "$staged"' EXIT trap 'exit 130' HUP INT TERM if test -e "$path"; then cp -p -- "$path" "$staged" else chmod =rw "$staged" fi cat > "$staged" if test "$(wc -c < "$staged")" -ne "$2"; then echo 'Incomplete remote write; original file unchanged' >&2 exit 1 fi mv -f -- "$staged" "$path"`; type SpawnSSH = (args: string[]) => ChildProcessWithoutNullStreams; function spawnSSH(args: string[]): ChildProcessWithoutNullStreams { const env = { ...process.env }; delete env.SANDBOX_RUNTIME; return spawn("ssh", args, { env, detached: true, stdio: "pipe" }); } // Signal the process group even after its leader exits, because proxy helpers can outlive it. function kill(child: ChildProcessWithoutNullStreams): void { if (!child.pid) { return; } try { process.kill(-child.pid, "SIGKILL"); } catch { // ESRCH means the group is gone. macOS returns EPERM for a group that contains only zombies. } } export interface Connection { host: string; socket: string; cwd: string; ready: boolean; connecting: boolean; master?: ChildProcessWithoutNullStreams; masterDone?: Promise; controller: AbortController; running: Set>; } interface ChannelResult { code: number | null; output: Buffer; error: string; } interface ChannelOptions { signal?: AbortSignal; timeout?: number; input?: string | Readable; onData?: (data: Buffer) => void; onStdout?: (data: Buffer) => void; keepStdin?: boolean; } export class RemoteConnections { readonly #spawn: SpawnSSH; readonly #connections = new Map(); #directory?: string; // Called when an established master exits without /remote disconnect or reconnect. onDisconnect?: (host: string, reason: string) => void; constructor(start: SpawnSSH = spawnSSH) { this.#spawn = start; } list(): Connection[] { return [...this.#connections.values()]; } require(host: string): Connection { const connection = this.#connections.get(host); if (!connection) { throw new Error( `Remote ${JSON.stringify(host)} is not approved. Ask the user to run /remote connect.`, ); } if (!connection.ready) { throw new Error( `Remote ${JSON.stringify(host)} is disconnected. Ask the user to run /remote reconnect ${host}.`, ); } return connection; } async connect(host: string): Promise { // The host becomes an ssh argument, so it must not look like an option. if (!/^(?:[\w.-]+@)?[\w.:[\]-]+$/.test(host) || host.startsWith("-")) { throw new Error(`Invalid SSH host ${JSON.stringify(host)}`); } let connection = this.#connections.get(host); if (connection?.connecting) { throw new Error(`Remote ${host} is already connecting`); } if (connection?.ready) { return connection; } this.#directory ??= mkdtempSync(join(tmpdir(), "pi-ssh-")); if (!connection) { connection = { host, socket: join(this.#directory, randomBytes(6).toString("hex")), cwd: "/", ready: false, connecting: false, controller: new AbortController(), running: new Set(), }; this.#connections.set(host, connection); } const current = connection; current.connecting = true; try { await this.#close(current); if (this.#connections.get(host) !== current) { throw new Error(`Remote ${host} was disconnected`); } return await this.#open(current); } finally { current.connecting = false; } } async #open(current: Connection): Promise { current.controller = new AbortController(); const config = join(dirname(current.socket), "config"); // ProxyJump helpers inherit -F, so they must not attach to the user's shared masters. writeFileSync( config, "Host *\n ControlMaster no\n ControlPath none\n ControlPersist no\n ForwardAgent no\n ForwardX11 no\n ClearAllForwardings yes\nInclude ~/.ssh/config\nInclude /etc/ssh/ssh_config\n", { mode: 0o600 }, ); const args = [ "-F", config, "-M", "-N", "-T", "-S", current.socket, "-o", "ControlMaster=yes", "-o", "ControlPersist=no", "-o", "BatchMode=yes", "-o", "ForwardAgent=no", "-o", "ForwardX11=no", "-o", "ClearAllForwardings=yes", "-o", "ServerAliveInterval=30", "-o", "ServerAliveCountMax=3", ]; args.push("--", current.host); const master = this.#spawn(args); current.master = master; let failure = ""; master.stdout.on("data", () => {}); master.stderr.on("data", (data: Buffer) => { failure = (failure + data.toString()).slice(-50_000); }); master.stdin.end(); current.masterDone = new Promise((resolve) => { let settled = false; let unexpected = false; let drainTimer: NodeJS.Timeout | undefined; const finished = () => { if (settled) { return; } settled = true; unexpected ||= current.ready; clearTimeout(drainTimer); kill(master); current.ready = false; current.master = undefined; current.controller.abort(); master.stdout.destroy(); master.stderr.destroy(); resolve(); if (unexpected) { const reason = failure.trim().split("\n").at(-1)?.trim(); this.onDisconnect?.(current.host, reason || "SSH master exited"); } }; master.once("error", (error) => { failure = error.message; finished(); }); master.once("exit", () => { unexpected = current.ready; current.ready = false; current.controller.abort(); // Proxy helpers can retain stdio after the master exits. Allow diagnostics to drain, then close them. drainTimer = setTimeout(finished, 100); }); master.once("close", finished); }); const signal = AbortSignal.any([current.controller.signal, AbortSignal.timeout(120_000)]); try { while (!signal.aborted) { if (existsSync(current.socket)) { const checked = await this.#channel(current, ["-O", "check"], { signal, timeout: 5, }); if (checked.code === 0) { const result = await this.#channel(current, ["pwd"], { signal, timeout: 10, }); if (result.code !== 0 || !result.output.toString().trim().startsWith("/")) { throw new Error( result.error || "Could not determine remote working directory", ); } current.cwd = result.output.toString().trim(); current.ready = true; return current; } } await delay(100, undefined, { signal }); } throw new Error("SSH connection ended before it became ready"); } catch (error) { await this.#close(current); throw new Error( failure.trim() || (error instanceof Error ? error.message : String(error)), ); } } async reconnect(host: string): Promise { if (!this.#connections.has(host)) { throw new Error(`No approved remote named ${host}`); } return this.connect(host); } async disconnect(host: string): Promise { const connection = this.#connections.get(host); if (!connection) { throw new Error(`No approved remote named ${host}`); } this.#connections.delete(host); await this.#close(connection); } async closeAll(): Promise { const connections = this.list(); this.#connections.clear(); await Promise.all(connections.map((connection) => this.#close(connection))); if (this.#directory) { rmSync(this.#directory, { recursive: true, force: true }); this.#directory = undefined; } } files(host: string, path: string, signal?: AbortSignal): ReadOperations & WriteOperations { const connection = this.require(host); const absolute = this.#resolve(connection, path); const run = (command: string, input?: string) => this.#run(connection, command, { signal, input, timeout: 60 }); return { readFile: () => run(`cat -- ${quote(absolute)}`), createReadStream: (_path, options) => this.#stream( connection, `cat -- ${quote(absolute)}`, AbortSignal.any([signal, options.signal].filter((s) => s !== undefined)), ), access: async () => { await run(`test -r ${quote(absolute)}`); }, detectImageMimeType: async () => { const result = await run( `file --mime-type -b -- ${quote(absolute)} 2>/dev/null || true`, ); const mime = result.toString().trim(); return ["image/png", "image/jpeg", "image/gif", "image/webp", "image/bmp"].includes( mime, ) ? mime : null; }, mkdir: async () => { await run(`mkdir -p -- ${quote(posix.dirname(absolute))}`); }, writeFile: async (_path, content) => { await run( `bash -c ${quote(REMOTE_WRITE)} pi-write ${quote(absolute)} ${Buffer.byteLength(content)}`, content, ); }, }; } async upload(host: string, local: string, path: string, signal?: AbortSignal) { const connection = this.require(host); const absolute = this.#resolve(connection, path); const stats = statSync(local); if (!stats.isFile()) { throw new Error(`${local} is not a regular file`); } const input = createReadStream(local); try { await this.#run( connection, `mkdir -p -- ${quote(posix.dirname(absolute))} && bash -c ${quote(REMOTE_WRITE)} pi-write ${quote(absolute)} ${stats.size}`, { signal, input, timeout: 3600 }, ); } finally { input.destroy(); } return { path: absolute, bytes: stats.size }; } async download(host: string, path: string, local: string, signal?: AbortSignal) { const connection = this.require(host); const absolute = this.#resolve(connection, path); const target = existsSync(local) ? realpathSync(local) : local; return withFileMutationQueue(target, async () => { mkdirSync(dirname(target), { recursive: true }); // Stage beside the target so a failed transfer leaves the target unchanged. const staged = `${target}.pi-copy-${randomBytes(4).toString("hex")}`; const mode = existsSync(target) ? statSync(target).mode & 0o7777 : 0o666; const fd = openSync(staged, "wx", mode); let bytes = 0; try { try { await this.#run(connection, `cat -- ${quote(absolute)}`, { signal, timeout: 3600, onStdout(data) { bytes += writeSync(fd, data); }, }); } finally { closeSync(fd); } renameSync(staged, target); } catch (error) { rmSync(staged, { force: true }); throw error; } return { path: absolute, bytes }; }); } async *#stream( connection: Connection, command: string, signal: AbortSignal, ): AsyncGenerator { const stop = new AbortController(); const chunks: Buffer[] = []; let done = false; let wake: (() => void) | undefined; const notify = () => { wake?.(); wake = undefined; }; const result = this.#run(connection, command, { signal: AbortSignal.any([signal, stop.signal]), timeout: 60, onStdout(data) { chunks.push(data); notify(); }, }).finally(() => { done = true; notify(); }); result.catch(() => {}); try { for (;;) { const chunk = chunks.shift(); if (chunk) { yield chunk; } else if (done) { break; } else { await new Promise((resolve) => (wake = resolve)); } } await result; } finally { stop.abort(); await result.catch(() => {}); } } // The login cwd stands in for the remote home directory. #resolve(connection: Connection, path: string): string { return posix.resolve(connection.cwd, path.replace(/^@/, "").replace(/^~(?=\/|$)/, ".")); } async #run(connection: Connection, command: string, options: ChannelOptions): Promise { this.#assertCurrent(connection); const result = await this.#channel(connection, [command], options); if (result.code !== 0) { throw new Error(result.error || `Remote file operation failed (${result.code})`); } return result.output; } bash(host: string): BashOperations { const connection = this.require(host); return { exec: async (command, cwd, options) => { this.#assertCurrent(connection); const script = `cd -- ${quote(cwd)} && exec bash -c ${quote(REMOTE_COMMAND)} pi-remote ${quote(command)}`; const result = await this.#channel(connection, [script], { ...options, keepStdin: true, }); return { exitCode: result.code }; }, }; } #assertCurrent(connection: Connection): void { if (this.require(connection.host) !== connection || connection.controller.signal.aborted) { throw new Error("Remote grant changed before execution"); } } #channel( connection: Connection, command: string[], options: ChannelOptions, ): Promise { const result = this.#runChannel(connection, command, options).then(async (result) => { // A remote command can also exit with 255, so only a failed master check means a lost connection. if ( result.code !== 255 || command[0] === "-O" || (await this.#runChannel(connection, ["-O", "check"], { timeout: 5 })).code === 0 ) { return result; } connection.ready = false; throw new Error( `SSH channel failed. Remote completion is uncertain. Run /remote reconnect ${connection.host} before further operations.`, ); }); connection.running.add(result); void result.finally(() => connection.running.delete(result)).catch(() => {}); return result; } #runChannel( connection: Connection, command: string[], options: ChannelOptions, ): Promise { const { timeout } = options; if ( timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0 || timeout * 1000 > 2_147_483_647) ) { throw new Error("Remote timeout must be positive and at most 2147483 seconds"); } const signal = AbortSignal.any([ connection.controller.signal, ...(options.signal ? [options.signal] : []), ...(timeout === undefined ? [] : [AbortSignal.timeout(Math.ceil(timeout * 1000))]), ]); signal.throwIfAborted(); const args = [ "-F", "none", "-S", connection.socket, "-o", "ControlMaster=no", "-o", "ProxyCommand=false", "-o", "BatchMode=yes", "-T", ]; const control = command[0] === "-O"; if (control) { args.push(...command, "--", connection.host); } else { args.push("--", connection.host, ...command); } const child = this.#spawn(args); return new Promise((resolve, reject) => { const chunks: Buffer[] = []; let bytes = 0; let stderr = ""; let failure: Error | undefined; let forced = false; let stopping = false; let forceTimer: NodeJS.Timeout | undefined; const abort = () => { if (stopping) { return; } stopping = true; child.stdin.end(); forceTimer = setTimeout( () => { forced = true; kill(child); }, options.keepStdin ? 1500 : 0, ); }; const onData = (data: Buffer) => { if (options.onData) { options.onData(data); } else { bytes += data.length; if (bytes > 64 * 1024 * 1024) { kill(child); failure = new Error("Remote output exceeds 64 MiB"); } else { chunks.push(data); } } }; const { onStdout } = options; child.stdout.on( "data", onStdout ? (data: Buffer) => { if (failure) { return; } try { onStdout(data); } catch (error) { failure = error instanceof Error ? error : new Error(String(error)); kill(child); } } : onData, ); child.stderr.on("data", (data: Buffer) => { stderr = (stderr + data.toString()).slice(-50_000); options.onData?.(data); }); child.stdin.on("error", () => {}); child.once("error", (error) => { failure = error; }); signal.addEventListener("abort", abort, { once: true }); if (signal.aborted) { abort(); } if (options.input instanceof Readable) { options.input.once("error", (error) => { failure = error; kill(child); }); options.input.pipe(child.stdin); } else if (!options.keepStdin) { child.stdin.end(options.input); } child.once("close", (code) => { clearTimeout(forceTimer); signal.removeEventListener("abort", abort); if (failure) { reject(failure); } else if (signal.aborted) { if (forced && options.keepStdin) { options.onData?.( Buffer.from("\nRemote process termination could not be confirmed.\n"), ); } // Pi's bash tool keeps partial output only for the "aborted" and "timeout:N" errors. reject( new Error( options.signal?.aborted ? "aborted" : connection.controller.signal.aborted ? "Remote disconnected" : options.keepStdin ? `timeout:${timeout}` : `Remote operation timed out after ${timeout} seconds`, ), ); } else { resolve({ code, output: Buffer.concat(chunks), error: stderr }); } }); }); } async #close(connection: Connection): Promise { connection.ready = false; connection.controller.abort(); await Promise.allSettled(connection.running); if (connection.master) { kill(connection.master); await connection.masterDone; } rmSync(connection.socket, { force: true }); } }