Something went wrong. Try again.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687import { 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 +eset -mbash -c "$1" </dev/null &command_pid=$!( cat >/dev/null kill -TERM -- -"$command_pid" 2>/dev/null sleep 1 kill -KILL -- -"$command_pid" 2>/dev/null) <&0 &watcher=$!set +mtrap 'kill -TERM -- -"$command_pid" 2>/dev/null' HUP INT TERMwait "$command_pid"status=$?kill -KILL -- -"$command_pid" 2>/dev/nullkill -TERM -- -"$watcher" 2>/dev/nullwait "$watcher" 2>/dev/nullexit "$status"`;
// Stage and verify the transfer before replacement so a lost channel cannot truncate the target.export const REMOTE_WRITE = `set -epath=$1links=0while test -L "$path"; do links=$((links + 1)) test "$links" -le 40 link=$(readlink -- "$path") case "$link" in /*) path=$link ;; *) path=$(dirname -- "$path")/$link ;; esacdonetest ! -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"' EXITtrap 'exit 130' HUP INT TERMif test -e "$path"; then cp -p -- "$path" "$staged"else chmod =rw "$staged"ficat > "$staged"if test "$(wc -c < "$staged")" -ne "$2"; then echo 'Incomplete remote write; original file unchanged' >&2 exit 1fimv -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<void>; controller: AbortController; running: Set<Promise<unknown>>;}
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<string, Connection>(); #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<Connection> { // 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<Connection> { 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<Connection> { if (!this.#connections.has(host)) { throw new Error(`No approved remote named ${host}`); } return this.connect(host); }
async disconnect(host: string): Promise<void> { 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<void> { 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<Buffer> { 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<void>((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<Buffer> { 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<ChannelResult> { 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<ChannelResult> { 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<void> { 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 }); }}