@xynogen/pix-ssh 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# pix-ssh
+
+Pi tool — `ssh_run`: run a shell command on a remote host over SSH, optionally as remote root.
+
+## What it does
+
+Registers the `ssh_run` tool, which executes a command on a remote machine behind a permission dialog (the shared overlay from `@xynogen/pix-pretty`, the same one pix-sudo uses). Every command requires explicit per-call Allow/Deny approval in the UI, with a 60-second auto-deny timeout — that approval step is never skipped. Output is truncated to 50 KB / 2000 lines. In non-interactive (RPC/JSON) mode the tool is blocked immediately.
+
+**Parameters:** `host` as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`), `command`, optional `sudo` (run as root on the remote), optional `reason`.
+
+### Authentication
+
+- **SSH login** — tries key/agent/existing-master auth first via a `BatchMode=yes` probe. If that succeeds, no login password is needed. If it fails, a masked overlay (`●` per character) collects the login password, fed to `sshpass -e` through the child's `SSHPASS` env var — never as an argv (no `ps` leak), never written to disk.
+- **Remote sudo** (`sudo: true`) — a separate masked prompt collects the remote sudo password, piped to the remote `sudo -S -p ''` on stdin, so it travels inside the encrypted SSH channel, not as an argv.
+
+Both passwords are cached **in-memory per host** for the session (keyed by `user@host:port`), never persisted. A wrong login password drops the login cache; a wrong sudo password drops the sudo cache — the next call re-prompts.
+
+### Connection reuse
+
+OpenSSH **ControlMaster multiplexing** keeps one authenticated connection per host alive for a short `ControlPersist` window, so repeat `ssh_run` calls to the same host skip re-auth. Host-key policy is `accept-new` and `ConnectTimeout` is 10s.
+
+While the approval dialog is open, `ssh_run` holds the shared **agent-state** coordinator in `blocked` (via `withAgentBlock` from [`@xynogen/pix-runtime`](https://www.npmjs.com/package/@xynogen/pix-runtime)), so an away user in a herdr pane is pinged when a command is waiting on approval. `/afk` (pix-commands) denies `ssh_run` immediately; `/yolo` auto-approves it only when no password is missing (a password prompt can't be auto-typed).
+
+Completed calls collapse after the configured Pix delay into a status row such as `✓ ssh deploy@10.0.0.5  apt update · exit 0 · 12 lines`. Configure the delay with `collapse.delaySec` and the per-tool toggle with `collapse.tools.ssh` in `~/.pi/agent/pix.json`. Overlays are never collapsed, and passwords are never included in result metadata or render state.
+
+## Requirements
+
+- `ssh` (OpenSSH) on the local machine.
+- `sshpass` on the local machine — only needed for password-based SSH login. Key-based auth works without it.
+
+## Install
+
+```bash
+pi install npm:@xynogen/pix-ssh
+```
+
+## Full distro
+
+Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@xynogen/pix-ssh",
+	"version": "0.1.0",
+	"description": "Pi tool — ssh_run: run remote commands over SSH with password/key auth and remote sudo",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"ssh",
+		"sudo",
+		"remote"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-ssh"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"typebox": "^1.1.38",
+		"@xynogen/pix-pretty": "^1.16.0",
+		"@xynogen/pix-runtime": "^0.6.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/src/index.ts

@@ -0,0 +1,601 @@
+/**
+ * pix-ssh — Pi extension
+ *
+ * Registers an `ssh_run` tool: run a shell command on a remote host over SSH,
+ * optionally as root (remote sudo). One overlay handles confirm + any needed
+ * password entry, mirroring pix-sudo.
+ *
+ * Auth:
+ *   - SSH: key/agent/existing-master first (BatchMode probe). If that fails,
+ *     a masked overlay collects the login password (fed to `sshpass -e` via
+ *     env — never argv, never disk). Login password is cached in-memory per
+ *     host for the session.
+ *   - Remote sudo (`sudo: true`): a separate masked prompt collects the remote
+ *     sudo password, piped to the remote `sudo -S` on stdin (inside the
+ *     encrypted channel). Cached in-memory per host for the session.
+ *
+ * Connection reuse: OpenSSH ControlMaster multiplexing keeps one authenticated
+ * connection per host alive (ControlPersist window), so repeat calls skip
+ * re-auth.
+ *
+ * Security notes:
+ *   - Passwords never leave JS memory; never written to disk; never in argv.
+ *   - Every command still requires explicit per-call confirmation in the UI.
+ *   - No UI (RPC / JSON mode) = blocked immediately.
+ *   - Output truncated to 50 KB / 2000 lines.
+ */
+
+import type { AgentToolUpdateCallback, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { FG_DIM, RST, resolveBaseBackground } from "@xynogen/pix-pretty/ansi";
+import { MAX_PREVIEW_LINES } from "@xynogen/pix-pretty/config";
+import { type OverlayResult, showOverlay } from "@xynogen/pix-pretty/gate-overlay";
+import { renderBashOutput } from "@xynogen/pix-pretty/renderers";
+import type { RenderContextLike, ThemeLike, ToolResultLike } from "@xynogen/pix-pretty/types";
+import {
+	dotJoin,
+	fillToolBackground,
+	getTextContent,
+	hideCollapsedToolCall,
+	normalizeLineEndings,
+	renderCollapsedToolRow,
+	renderToolError,
+	ruleFrame,
+	termW,
+} from "@xynogen/pix-pretty/utils";
+import { withAgentBlock } from "@xynogen/pix-runtime";
+import { type CollapseState, tickCollapse } from "@xynogen/pix-runtime/collapse";
+import { Type } from "typebox";
+import {
+	controlPathFor,
+	detectSshFailure,
+	detectSudoFailure,
+	type HostSpec,
+	hostTarget,
+	MAX_OUTPUT_BYTES,
+	MAX_OUTPUT_LINES,
+	parseHost,
+	probeKeyAuth,
+	runSsh,
+	truncate,
+} from "./lib.ts";
+
+const PROMPT_TIMEOUT_MS = 60_000;
+const MAX_PASSWORD_ATTEMPTS = 3;
+
+// In-memory per-host credential cache (session-scoped, never persisted).
+// Key = canonical "user@host:port". Cleared on process exit.
+interface HostCreds {
+	loginPassword?: string;
+	sudoPassword?: string;
+}
+const credCache = new Map<string, HostCreds>();
+
+function cacheKey(spec: HostSpec): string {
+	return `${spec.user ?? ""}@${spec.host}:${spec.port ?? 22}`;
+}
+
+type SshOutcome =
+	| "awaiting-approval"
+	| "running"
+	| "success"
+	| "denied"
+	| "timed-out"
+	| "cancelled"
+	| "error";
+
+type SshCancellationKind = "denied" | "timeout" | "missing-password" | "aborted";
+type SshErrorKind = "no-ui" | "auth-ssh" | "auth-sudo" | "execution" | "no-result" | "exit-code";
+
+export interface SshResultDetails {
+	_type: "sshResult";
+	command: string;
+	host: string;
+	sudo?: boolean;
+	reason?: string;
+	outcome: SshOutcome;
+	exitCode?: number;
+	lineCount?: number;
+	truncated?: boolean;
+	cancellationKind?: SshCancellationKind;
+	errorKind?: SshErrorKind;
+	_render?: string;
+}
+
+function safeOneLine(value: string): string {
+	return value
+		.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+function makeDetails(
+	command: string,
+	host: string,
+	sudo: boolean,
+	reason: string | undefined,
+	fields: Omit<SshResultDetails, "_type" | "command" | "host" | "sudo" | "reason">,
+): SshResultDetails {
+	return {
+		_type: "sshResult",
+		command,
+		host,
+		sudo,
+		...(reason?.trim() ? { reason: reason.trim() } : {}),
+		...fields,
+	};
+}
+
+function outputLineCount(output: string): number {
+	const normalized = normalizeLineEndings(output).replace(/^\n+|\n+$/g, "");
+	return normalized ? normalized.split("\n").length : 0;
+}
+
+function updatePresentation(
+	onUpdate: AgentToolUpdateCallback<SshResultDetails> | undefined,
+	command: string,
+	host: string,
+	sudo: boolean,
+	reason: string | undefined,
+	outcome: "awaiting-approval" | "running",
+): void {
+	onUpdate?.({
+		content: [
+			{
+				type: "text",
+				text: outcome === "awaiting-approval" ? "Awaiting approval…" : `Running on ${host}…`,
+			},
+		],
+		details: makeDetails(command, host, sudo, reason, { outcome }),
+	});
+}
+
+function terminalMeta(details: SshResultDetails): string {
+	if (details.outcome === "denied") return "denied";
+	if (details.outcome === "timed-out") return "timed out";
+	if (details.outcome === "cancelled") return "cancelled";
+	if (details.errorKind === "no-ui") return "interactive session required";
+	if (details.errorKind === "auth-ssh") return "ssh auth failed";
+	if (details.errorKind === "auth-sudo") return "sudo auth failed";
+	if (details.errorKind === "execution" || details.errorKind === "no-result") return "failed";
+
+	const hasLines = typeof details.lineCount === "number" && details.lineCount > 0;
+	return dotJoin([
+		typeof details.exitCode === "number" && `exit ${details.exitCode}`,
+		hasLines && `${details.lineCount} ${details.lineCount === 1 ? "line" : "lines"}`,
+		details.truncated && "truncated",
+	]);
+}
+
+function isTerminal(details: SshResultDetails): boolean {
+	return details.outcome !== "awaiting-approval" && details.outcome !== "running";
+}
+
+function cancelResult(
+	command: string,
+	host: string,
+	sudo: boolean,
+	reason: string | undefined,
+	action: OverlayResult["action"],
+): { content: { type: "text"; text: string }[]; details: SshResultDetails } {
+	const cancellationKind: SshCancellationKind =
+		action === "timeout" ? "timeout" : action === "denied" ? "denied" : "missing-password";
+	const outcome: SshOutcome =
+		cancellationKind === "timeout"
+			? "timed-out"
+			: cancellationKind === "denied"
+				? "denied"
+				: "cancelled";
+	const msg =
+		outcome === "timed-out"
+			? "Timed out — auto-denied."
+			: outcome === "denied"
+				? "Denied by user."
+				: "Cancelled — no password entered.";
+	return {
+		content: [{ type: "text", text: `Cancelled — ${msg}` }],
+		details: makeDetails(command, host, sudo, reason, { outcome, cancellationKind }),
+	};
+}
+
+// ── Extension entry point ─────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "ssh_run",
+		label: "Run over SSH",
+		description:
+			"Run a shell command on a remote host over SSH, optionally as root (remote sudo). " +
+			"Handles the connection and any password entry through a confirmation dialog — " +
+			"the command is NEVER executed without explicit user approval. " +
+			"SSH auth tries key/agent first, then prompts for a login password if needed. " +
+			"Set `sudo: true` to run the command as root on the remote machine (prompts for the " +
+			"remote sudo password). Always provide a clear `reason`.",
+		promptSnippet: "Run a command on a remote host over SSH (optionally as remote root)",
+		promptGuidelines: [
+			"Use ssh_run to execute commands on a remote machine over SSH. Provide `host` as " +
+				"`[user@]host[:port]`. Set `sudo: true` only when the remote command needs root. " +
+				"Always set `reason` to a short plain-English sentence explaining the intent.",
+		],
+
+		renderShell: "self",
+
+		parameters: Type.Object({
+			host: Type.String({
+				description: "Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`).",
+			}),
+			command: Type.String({
+				description: "Shell command to run on the remote host (passed to remote `sh -c`).",
+			}),
+			sudo: Type.Optional(
+				Type.Boolean({
+					description: "Run the command as root on the remote host via sudo. Default false.",
+				}),
+			),
+			reason: Type.Optional(
+				Type.String({
+					description: "Short plain-English explanation of intent, shown to the user.",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, sig, onUpdate, ctx) {
+			const { command, reason } = params;
+			const sudo = params.sudo === true;
+
+			let spec: HostSpec;
+			try {
+				spec = parseHost(params.host);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: `ssh_run failed: ${msg}` }],
+					details: makeDetails(command, params.host, sudo, reason, {
+						outcome: "error",
+						errorKind: "execution",
+					}),
+					isError: true,
+				};
+			}
+			const host = hostTarget(spec);
+			const controlPath = controlPathFor(spec);
+			const key = cacheKey(spec);
+			const creds = credCache.get(key) ?? {};
+
+			const g = globalThis as { __pixAfk?: boolean; __pixYolo?: boolean };
+			const yolo = g.__pixYolo === true;
+			if (g.__pixAfk === true && !yolo) {
+				return {
+					content: [{ type: "text", text: "ssh_run denied immediately — AFK mode is active." }],
+					details: makeDetails(command, host, sudo, reason, {
+						outcome: "denied",
+						cancellationKind: "denied",
+					}),
+				};
+			}
+
+			if (!ctx.hasUI) {
+				return {
+					content: [
+						{ type: "text", text: "ssh_run requires an interactive session (no UI available)." },
+					],
+					details: makeDetails(command, host, sudo, reason, {
+						outcome: "error",
+						errorKind: "no-ui",
+					}),
+					isError: true,
+				};
+			}
+
+			updatePresentation(onUpdate, command, host, sudo, reason, "awaiting-approval");
+
+			// Probe key/agent/existing-master auth (no password needed on success).
+			// Only prompt for a login password when the host is reachable but rejects
+			// key auth ("auth"). If it's unreachable (timeout/DNS/refused) a password
+			// can't help — skip the prompt and let runSsh surface the real error.
+			const probe = creds.loginPassword ? "ok" : await probeKeyAuth(spec, controlPath, sig);
+			const keyOk = probe === "ok";
+			// Which passwords must the overlay collect this call?
+			const needLogin = probe === "auth" && !creds.loginPassword;
+			const needSudo = sudo && !creds.sudoPassword;
+			// The overlay stage pipeline: any password we still need is prompted
+			// (login first, then sudo). Confirm-only when nothing is missing.
+			const promptFor: ("login" | "sudo")[] = [
+				...(needLogin ? (["login"] as const) : []),
+				...(needSudo ? (["sudo"] as const) : []),
+			];
+
+			const body = [
+				reason?.trim() ? `Intent: ${reason.trim()}` : "No reason provided by AI",
+				`Host: ${host}${spec.port ? ` (port ${spec.port})` : ""}`,
+				`Command: ${sudo ? "sudo " : ""}${command}`,
+				...(keyOk && !creds.loginPassword ? ["(key-based auth — no login password needed)"] : []),
+			];
+
+			const collected: { login?: string; sudo?: string } = {};
+
+			// Collect each still-missing password through the same overlay pattern
+			// pix-sudo uses (masked input, N attempts). We can't validate remote
+			// passwords without connecting, so validatePassword just accepts a
+			// non-empty entry; a wrong password surfaces as an auth error after run.
+			const runOverlay = (): Promise<OverlayResult> =>
+				withAgentBlock(pi.events, "ssh_run", "SSH approval required", async () => {
+					if (yolo && promptFor.length === 0) {
+						return { action: "approved", password: "" } as OverlayResult;
+					}
+					// Confirm-only when no password is missing.
+					if (promptFor.length === 0) {
+						return showOverlay(ctx.ui, {
+							mode: "confirm",
+							title: "🔐 SSH COMMAND REQUEST",
+							body,
+							accent: sudo ? "error" : "accent",
+							timeoutMs: PROMPT_TIMEOUT_MS,
+							choices: [
+								{ value: "yes", label: "Allow", description: "Run the command" },
+								{ value: "no", label: "Deny", description: "Block the command" },
+							],
+						});
+					}
+					// One masked prompt per missing password, in order.
+					let last: OverlayResult = { action: "approved", password: "" };
+					for (const stage of promptFor) {
+						const label = stage === "login" ? "SSH login password" : "Remote sudo password";
+						last = await showOverlay(ctx.ui, {
+							mode: "sudo",
+							title: "🔐 SSH COMMAND REQUEST",
+							body: [...body, `Enter: ${label}`],
+							accent: sudo ? "error" : "accent",
+							timeoutMs: PROMPT_TIMEOUT_MS,
+							maxPasswordAttempts: MAX_PASSWORD_ATTEMPTS,
+							passwordLabel: `${label}:`,
+							validatePassword: (pw) => Promise.resolve(pw.trim().length > 0),
+							choices: [
+								{
+									value: "yes",
+									label: "Allow",
+									description: `Enter ${label.toLowerCase()}`,
+								},
+								{ value: "no", label: "Deny", description: "Block the command" },
+							],
+						});
+						if (last.action !== "approved" || !last.password?.trim()) return last;
+						if (stage === "login") collected.login = last.password;
+						else collected.sudo = last.password;
+					}
+					return last;
+				});
+
+			const overlayResult = await runOverlay();
+			const missing =
+				overlayResult.action === "approved" &&
+				((needLogin && !collected.login) || (needSudo && !collected.sudo));
+			if (overlayResult.action !== "approved" || missing) {
+				const r = cancelResult(command, host, sudo, reason, overlayResult.action);
+				ctx.ui.notify(`🔐 ${r.content[0]?.text}`, "warning");
+				return r;
+			}
+
+			// Persist newly-entered passwords in the session cache.
+			const loginPassword = creds.loginPassword ?? collected.login;
+			const sudoPassword = creds.sudoPassword ?? collected.sudo;
+			credCache.set(key, {
+				...(loginPassword ? { loginPassword } : {}),
+				...(sudoPassword ? { sudoPassword } : {}),
+			});
+
+			updatePresentation(onUpdate, command, host, sudo, reason, "running");
+
+			let result: { stdout: string; stderr: string; code: number } | undefined;
+			try {
+				result = await runSsh(spec, command, {
+					controlPath,
+					...(loginPassword ? { loginPassword } : {}),
+					sudo,
+					...(sudo ? { sudoPassword: sudoPassword ?? "" } : {}),
+					...(sig ? { signal: sig } : {}),
+				});
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: `ssh_run failed: ${msg}` }],
+					details: makeDetails(
+						command,
+						host,
+						sudo,
+						reason,
+						sig?.aborted
+							? { outcome: "cancelled", cancellationKind: "aborted" }
+							: { outcome: "error", errorKind: "execution" },
+					),
+					isError: sig?.aborted !== true,
+				};
+			}
+
+			if (!result) {
+				return {
+					content: [{ type: "text", text: "ssh_run failed: command produced no result" }],
+					details: makeDetails(command, host, sudo, reason, {
+						outcome: "error",
+						errorKind: "no-result",
+					}),
+					isError: true,
+				};
+			}
+
+			// SSH auth failure → drop the bad login password from the cache so the
+			// next call re-prompts.
+			if (detectSshFailure(result.code, result.stderr)) {
+				credCache.delete(key);
+				ctx.ui.notify("🔐 SSH authentication failed", "error");
+				return {
+					content: [{ type: "text", text: `SSH authentication failed:\n${result.stderr}` }],
+					details: makeDetails(command, host, sudo, reason, {
+						outcome: "error",
+						exitCode: result.code,
+						lineCount: outputLineCount(result.stderr),
+						errorKind: "auth-ssh",
+						_render: normalizeLineEndings(result.stderr),
+					}),
+					isError: true,
+				};
+			}
+
+			// Remote sudo password failure → drop the bad sudo password.
+			if (sudo && detectSudoFailure(result.stderr)) {
+				credCache.set(key, loginPassword ? { loginPassword } : {});
+				ctx.ui.notify("🔐 Remote sudo authentication failed", "error");
+				return {
+					content: [{ type: "text", text: `Remote sudo authentication failed:\n${result.stderr}` }],
+					details: makeDetails(command, host, sudo, reason, {
+						outcome: "error",
+						exitCode: result.code,
+						lineCount: outputLineCount(result.stderr),
+						errorKind: "auth-sudo",
+						_render: normalizeLineEndings(result.stderr),
+					}),
+					isError: true,
+				};
+			}
+
+			const combined = [result.stdout, result.stderr].filter(Boolean).join("\n") || "(no output)";
+			const { text: truncatedText, truncated } = truncate(combined);
+			const suffix = truncated
+				? `\n\n[Output truncated to ${MAX_OUTPUT_LINES} lines / ${MAX_OUTPUT_BYTES / 1024}KB]`
+				: "";
+			const rendered = normalizeLineEndings(combined)
+				.replace(/\n{3,}/g, "\n\n")
+				.replace(/^\n+|\n+$/g, "");
+
+			return {
+				content: [{ type: "text", text: `Exit code: ${result.code}\n\n${truncatedText}${suffix}` }],
+				details: makeDetails(command, host, sudo, reason, {
+					outcome: result.code === 0 ? "success" : "error",
+					exitCode: result.code,
+					lineCount: outputLineCount(rendered),
+					truncated,
+					...(result.code === 0 ? {} : { errorKind: "exit-code" as const }),
+					_render: rendered,
+				}),
+				isError: result.code !== 0,
+			};
+		},
+
+		renderCall: ((
+			args: { command: string; host: string; sudo?: boolean; reason?: string },
+			theme: ThemeLike,
+			renderCtx: RenderContextLike,
+		) => {
+			resolveBaseBackground(theme);
+			const text = renderCtx.lastComponent ?? new Text("", 0, 0);
+			if (
+				hideCollapsedToolCall(renderCtx.state as CollapseState, renderCtx.expanded, (value) =>
+					text.setText(value),
+				)
+			)
+				return text;
+
+			const command = safeOneLine(args.command) || "(empty command)";
+			const host = safeOneLine(args.host);
+			const prefix = args.sudo ? "sudo " : "";
+			text.setText(
+				fillToolBackground(
+					`${theme.fg("toolTitle", theme.bold("ssh"))} ${theme.fg("dim", host)} ${theme.fg("accent", prefix + command)}`,
+				),
+			);
+			return text;
+		}) as never,
+
+		renderResult: ((
+			result: ToolResultLike,
+			_opt: unknown,
+			theme: ThemeLike,
+			renderCtx: RenderContextLike,
+		) => {
+			resolveBaseBackground(theme);
+			const text = renderCtx.lastComponent ?? new Text("", 0, 0);
+			const details = result.details as SshResultDetails | undefined;
+
+			if (details?._type !== "sshResult") {
+				if (renderCtx.isError) {
+					text.setText(renderToolError(getTextContent(result) || "Error", theme));
+				} else {
+					text.setText(
+						fillToolBackground(`  ${theme.fg("dim", getTextContent(result) || "done")}`),
+					);
+				}
+				return text;
+			}
+
+			if (
+				isTerminal(details) &&
+				tickCollapse(
+					"ssh",
+					renderCtx.state as CollapseState,
+					renderCtx.invalidate,
+					renderCtx.expanded,
+				)
+			) {
+				const status =
+					details.outcome === "success"
+						? "success"
+						: details.outcome === "error"
+							? "error"
+							: "warning";
+				text.setText(
+					renderCollapsedToolRow(
+						theme,
+						"ssh",
+						`${details.host}  ${safeOneLine(details.command)}`,
+						terminalMeta(details),
+						status,
+					),
+				);
+				return text;
+			}
+
+			if (details.outcome === "awaiting-approval" || details.outcome === "running") {
+				text.setText(
+					fillToolBackground(`  ${theme.fg("dim", getTextContent(result) || "working")}`),
+				);
+				return text;
+			}
+
+			if (details.outcome !== "success" && details.errorKind !== "exit-code") {
+				const diagnostic = getTextContent(result) || "Error";
+				text.setText(
+					details.outcome === "error"
+						? renderToolError(diagnostic, theme)
+						: fillToolBackground(`  ${theme.fg("warning", diagnostic)}`),
+				);
+				return text;
+			}
+
+			const code = typeof details.exitCode === "number" ? details.exitCode : null;
+			const rendered = typeof details._render === "string" ? details._render : "";
+			const { summary } = renderBashOutput(rendered, code, theme);
+			const lines = rendered ? rendered.split("\n") : [];
+			const lineCount = lines.length;
+
+			if (!rendered) {
+				text.setText(fillToolBackground(`  ${summary}`));
+				return text;
+			}
+
+			const maxShow = renderCtx.expanded ? lineCount : MAX_PREVIEW_LINES;
+			const show = lines.slice(0, maxShow);
+			const footer =
+				lineCount > maxShow ? [`${FG_DIM}  … ${lineCount - maxShow} more lines${RST}`] : [];
+			const statusKey = code === null ? "dim" : code === 0 ? "success" : "error";
+			const paint = (s: string) => theme.fg(statusKey, s);
+			const out = ruleFrame(
+				show.map((line) => `  ${line}`),
+				footer,
+				termW(),
+				paint,
+			);
+			text.setText(fillToolBackground(out.join("\n")));
+			return text;
+		}) as never,
+	});
+}

package/src/lib.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "bun:test";
+import {
+	baseSshArgs,
+	controlPathFor,
+	detectSshFailure,
+	detectSudoFailure,
+	filterSudoPrompt,
+	hostTarget,
+	isUnreachable,
+	parseHost,
+	remoteCommand,
+	shellQuote,
+	truncate,
+} from "./lib.ts";
+
+describe("parseHost", () => {
+	it("parses bare host", () => {
+		expect(parseHost("example.com")).toEqual({ host: "example.com" });
+	});
+	it("parses user@host", () => {
+		expect(parseHost("deploy@10.0.0.5")).toEqual({ user: "deploy", host: "10.0.0.5" });
+	});
+	it("parses user@host:port", () => {
+		expect(parseHost("deploy@10.0.0.5:2222")).toEqual({
+			user: "deploy",
+			host: "10.0.0.5",
+			port: 2222,
+		});
+	});
+	it("parses bracketed IPv6 with port", () => {
+		expect(parseHost("root@[::1]:22")).toEqual({ user: "root", host: "::1", port: 22 });
+	});
+	it("leaves bare IPv6 (multiple colons) as host", () => {
+		expect(parseHost("fe80::1")).toEqual({ host: "fe80::1" });
+	});
+	it("rejects empty host", () => {
+		expect(() => parseHost("   ")).toThrow();
+		expect(() => parseHost("user@")).toThrow();
+	});
+	it("rejects invalid port", () => {
+		expect(() => parseHost("h:0")).toThrow();
+		expect(() => parseHost("h:70000")).toThrow();
+		expect(() => parseHost("h:abc")).toThrow();
+	});
+});
+
+describe("hostTarget", () => {
+	it("joins user and host", () => {
+		expect(hostTarget({ user: "a", host: "b" })).toBe("a@b");
+		expect(hostTarget({ host: "b" })).toBe("b");
+	});
+});
+
+describe("controlPathFor", () => {
+	it("is stable per host+user+port and differs across hosts", () => {
+		const a = controlPathFor({ user: "u", host: "h", port: 22 });
+		expect(a).toBe(controlPathFor({ user: "u", host: "h", port: 22 }));
+		expect(a).not.toBe(controlPathFor({ user: "u", host: "h", port: 23 }));
+		expect(a).not.toBe(controlPathFor({ user: "x", host: "h", port: 22 }));
+		expect(a).toContain("pix-ssh-");
+		expect(a.endsWith(".sock")).toBe(true);
+	});
+});
+
+describe("baseSshArgs", () => {
+	it("enables multiplexing and includes the control path", () => {
+		const args = baseSshArgs({ host: "h" }, "/tmp/x.sock");
+		expect(args).toContain("ControlMaster=auto");
+		expect(args).toContain("ControlPath=/tmp/x.sock");
+		expect(args.some((a) => a.startsWith("ControlPersist="))).toBe(true);
+	});
+	it("adds -p only when a port is set", () => {
+		expect(baseSshArgs({ host: "h" }, "s")).not.toContain("-p");
+		const withPort = baseSshArgs({ host: "h", port: 2222 }, "s");
+		expect(withPort).toContain("-p");
+		expect(withPort).toContain("2222");
+	});
+});
+
+describe("remoteCommand + shellQuote", () => {
+	it("returns the command unchanged without sudo", () => {
+		expect(remoteCommand("whoami", false)).toBe("whoami");
+	});
+	it("wraps in sudo -S with a quoted inner command", () => {
+		const out = remoteCommand("apt update", true);
+		expect(out).toStartWith("sudo -S -p '' -- sh -c ");
+		expect(out).toContain("'apt update'");
+	});
+	it("escapes embedded single quotes safely", () => {
+		expect(shellQuote("it's")).toBe(`'it'\\''s'`);
+		// The wrapped form has no unescaped quote that would break out of the string.
+		const wrapped = remoteCommand("echo 'hi'", true);
+		expect(wrapped).toContain(`'echo '\\''hi'\\'''`);
+	});
+});
+
+describe("detectSshFailure", () => {
+	it("is false on exit 0", () => {
+		expect(detectSshFailure(0, "permission denied")).toBe(false);
+	});
+	it("flags common ssh errors", () => {
+		expect(detectSshFailure(255, "Permission denied (publickey,password).")).toBe(true);
+		expect(detectSshFailure(255, "ssh: connect to host x: Connection refused")).toBe(true);
+		expect(detectSshFailure(255, "Could not resolve hostname x")).toBe(true);
+	});
+	it("does not flag a normal nonzero command exit", () => {
+		expect(detectSshFailure(1, "ls: no such file")).toBe(false);
+	});
+});
+
+describe("isUnreachable", () => {
+	it("flags connection/DNS failures (not auth)", () => {
+		expect(isUnreachable("ssh: connect to host x port 22: Connection timed out")).toBe(true);
+		expect(isUnreachable("ssh: connect to host x port 22: Connection refused")).toBe(true);
+		expect(isUnreachable("ssh: Could not resolve hostname x")).toBe(true);
+		expect(isUnreachable("ssh: connect to host x: No route to host")).toBe(true);
+	});
+	it("does NOT flag a password rejection (that's an auth failure)", () => {
+		expect(isUnreachable("Permission denied, please try again.")).toBe(false);
+		expect(isUnreachable("Permission denied (publickey,password).")).toBe(false);
+	});
+});
+
+describe("detectSudoFailure", () => {
+	it("flags wrong sudo password", () => {
+		expect(detectSudoFailure("Sorry, try again.")).toBe(true);
+		expect(detectSudoFailure("sudo: 1 incorrect password attempt")).toBe(true);
+		expect(detectSudoFailure("sudo: a password is required")).toBe(true);
+	});
+	it("ignores unrelated stderr", () => {
+		expect(detectSudoFailure("warning: something")).toBe(false);
+	});
+});
+
+describe("filterSudoPrompt", () => {
+	it("strips bare password prompt lines", () => {
+		expect(filterSudoPrompt("[sudo] password for u:\nreal output")).toBe("real output");
+		expect(filterSudoPrompt("Password:\nx")).toBe("x");
+	});
+	it("keeps normal lines", () => {
+		expect(filterSudoPrompt("line one\nline two")).toBe("line one\nline two");
+	});
+});
+
+describe("truncate", () => {
+	it("passes short text through", () => {
+		expect(truncate("a\nb").truncated).toBe(false);
+	});
+	it("caps by line count", () => {
+		const many = Array.from({ length: 3000 }, (_, i) => `l${i}`).join("\n");
+		const out = truncate(many, 2000);
+		expect(out.truncated).toBe(true);
+		expect(out.text.split("\n").length).toBe(2000);
+	});
+});

package/src/lib.ts

@@ -0,0 +1,304 @@
+/**
+ * Pure / side-effect-free helpers for pix-ssh, extracted so they can be
+ * unit-tested without opening real SSH connections or loading the Pi host.
+ *
+ * Security model:
+ *   - SSH login password (when key auth fails) is fed to `sshpass -e` via the
+ *     SSHPASS env var of the child only — never as an argv (no `ps` leak),
+ *     never written to disk.
+ *   - Remote sudo password is piped to the remote `sudo -S -p ''` on stdin,
+ *     so it travels inside the encrypted SSH channel, not as an argv.
+ *   - ControlMaster multiplexing means one authenticated connection per host
+ *     is reused by later calls (ControlPersist window), so the password is
+ *     entered once per session per host.
+ */
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const MAX_OUTPUT_BYTES = 50 * 1024;
+export const MAX_OUTPUT_LINES = 2000;
+
+/** ControlPersist window (seconds) — the multiplexed connection lingers this
+ * long after the last call, so repeat commands skip re-auth. */
+const CONTROL_PERSIST_SECONDS = 120;
+const CONNECT_TIMEOUT_SECONDS = 10;
+
+export interface HostSpec {
+	user?: string;
+	host: string;
+	port?: number;
+}
+
+export interface SshResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+}
+
+// ── Host parsing ─────────────────────────────────────────────────────────────
+
+/** Parse `[user@]host[:port]` into parts. Throws on empty host. */
+export function parseHost(spec: string): HostSpec {
+	const trimmed = spec.trim();
+	if (!trimmed) throw new Error("Empty host");
+
+	let user: string | undefined;
+	let rest = trimmed;
+	const at = rest.lastIndexOf("@");
+	if (at !== -1) {
+		user = rest.slice(0, at) || undefined;
+		rest = rest.slice(at + 1);
+	}
+
+	let port: number | undefined;
+	// IPv6 literals use brackets: [::1]:22 — only split a port off the tail
+	// when there is exactly one colon (plain host:port), leaving bare IPv6 alone.
+	const colons = rest.split(":").length - 1;
+	if (rest.startsWith("[")) {
+		const end = rest.indexOf("]");
+		const hostPart = rest.slice(1, end);
+		const tail = rest.slice(end + 1);
+		if (tail.startsWith(":")) port = parsePort(tail.slice(1));
+		rest = hostPart;
+	} else if (colons === 1) {
+		const [h, p] = rest.split(":");
+		rest = h ?? "";
+		port = parsePort(p ?? "");
+	}
+
+	if (!rest) throw new Error(`Invalid host: ${spec}`);
+	return { user, host: rest, ...(port !== undefined ? { port } : {}) };
+}
+
+function parsePort(value: string): number {
+	const n = Number.parseInt(value, 10);
+	if (!Number.isInteger(n) || n < 1 || n > 65535) {
+		throw new Error(`Invalid port: ${value}`);
+	}
+	return n;
+}
+
+/** Canonical `[user@]host` target string for ssh argv. */
+export function hostTarget(spec: HostSpec): string {
+	return spec.user ? `${spec.user}@${spec.host}` : spec.host;
+}
+
+/** Stable per-host ControlMaster socket path (survives across calls in a
+ * session so multiplexing can reuse the connection). */
+export function controlPathFor(spec: HostSpec): string {
+	const key = `${spec.user ?? ""}@${spec.host}:${spec.port ?? 22}`;
+	const hash = createHash("sha256").update(key).digest("hex").slice(0, 16);
+	return join(tmpdir(), `pix-ssh-${hash}.sock`);
+}
+
+// ── ssh argv construction ────────────────────────────────────────────────────
+
+/** Base ssh options shared by every invocation: multiplexing + timeouts +
+ * non-interactive prompts (BatchMode is toggled by the caller). */
+export function baseSshArgs(spec: HostSpec, controlPath: string): string[] {
+	const args = [
+		"-o",
+		"ControlMaster=auto",
+		"-o",
+		`ControlPath=${controlPath}`,
+		"-o",
+		`ControlPersist=${CONTROL_PERSIST_SECONDS}`,
+		"-o",
+		`ConnectTimeout=${CONNECT_TIMEOUT_SECONDS}`,
+		"-o",
+		"StrictHostKeyChecking=accept-new",
+	];
+	if (spec.port !== undefined) args.push("-p", String(spec.port));
+	return args;
+}
+
+/** Wrap a command for optional remote sudo. `sudo -S -p ''` reads the sudo
+ * password from stdin with no prompt echo; the command runs under `sh -c`. */
+export function remoteCommand(command: string, sudo: boolean): string {
+	if (!sudo) return command;
+	return `sudo -S -p '' -- sh -c ${shellQuote(command)}`;
+}
+
+/** Single-quote a string for POSIX sh (wrap in quotes, escape embedded quotes). */
+export function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+// ── Auth-failure detection ───────────────────────────────────────────────────
+
+/** SSH-level auth/connection failure (wrong login password, refused, etc.). */
+export function detectSshFailure(code: number, stderr: string): boolean {
+	if (code === 0) return false;
+	const lower = stderr.toLowerCase();
+	return (
+		lower.includes("permission denied") ||
+		lower.includes("connection refused") ||
+		lower.includes("connection timed out") ||
+		lower.includes("could not resolve hostname") ||
+		lower.includes("no route to host") ||
+		lower.includes("host key verification failed")
+	);
+}
+
+/** Remote sudo password failure. */
+export function detectSudoFailure(stderr: string): boolean {
+	const lower = stderr.toLowerCase();
+	return (
+		lower.includes("incorrect password") ||
+		lower.includes("sudo: a password is required") ||
+		lower.includes("authentication failure") ||
+		lower.includes("sorry, try again")
+	);
+}
+
+/** Strip the remote sudo prompt lines from stderr (we pass `-p ''` but some
+ * sudo builds still emit a newline or prompt fragment). */
+export function filterSudoPrompt(raw: string): string {
+	return raw
+		.split("\n")
+		.filter((l) => !/^\s*(\[sudo\] )?password( for .*)?:?\s*$/i.test(l))
+		.join("\n");
+}
+
+// ── Output truncation ────────────────────────────────────────────────────────
+
+export function truncate(
+	text: string,
+	maxLines = MAX_OUTPUT_LINES,
+	maxBytes = MAX_OUTPUT_BYTES,
+): { text: string; truncated: boolean } {
+	const lines = text.split("\n");
+	const byteLen = Buffer.byteLength(text, "utf8");
+	if (lines.length <= maxLines && byteLen <= maxBytes) {
+		return { text, truncated: false };
+	}
+	const kept = lines.slice(0, maxLines);
+	let result = kept.join("\n");
+	if (Buffer.byteLength(result, "utf8") > maxBytes) {
+		result = Buffer.from(result, "utf8").slice(0, maxBytes).toString("utf8");
+	}
+	return { text: result, truncated: true };
+}
+
+// ── Runners ──────────────────────────────────────────────────────────────────
+
+/** Outcome of the key-auth probe. `ok` = connected without a password;
+ * `auth` = reachable but needs a password; `unreachable` = host down / timeout
+ * / DNS — a password won't help, so don't prompt. */
+export type ProbeResult = "ok" | "auth" | "unreachable";
+
+/**
+ * Probe key-based (or agent, or existing-master) auth with `BatchMode=yes` so
+ * ssh never prompts. Distinguishes three cases from the exit code + stderr:
+ * clean connect (ok), auth rejected but host reachable (auth), and
+ * connection/DNS failure (unreachable) — the last must NOT trigger a password
+ * prompt, since a login password can't fix an unreachable host.
+ */
+export function probeKeyAuth(
+	spec: HostSpec,
+	controlPath: string,
+	signal?: AbortSignal,
+): Promise<ProbeResult> {
+	const args = [...baseSshArgs(spec, controlPath), "-o", "BatchMode=yes", hostTarget(spec), "true"];
+	return new Promise((resolve) => {
+		let stderr = "";
+		const proc = spawn("ssh", args, { stdio: ["ignore", "ignore", "pipe"] });
+		proc.stderr.on("data", (c: Buffer) => {
+			stderr += c.toString();
+		});
+		proc.on("error", () => resolve("unreachable"));
+		proc.on("close", (code) => {
+			if (code === 0) return resolve("ok");
+			if (isUnreachable(stderr)) return resolve("unreachable");
+			resolve("auth");
+		});
+		signal?.addEventListener("abort", () => proc.kill("SIGTERM"), { once: true });
+	});
+}
+
+/** Connection/DNS-level failure (not an auth rejection) — a password can't fix it. */
+export function isUnreachable(stderr: string): boolean {
+	const lower = stderr.toLowerCase();
+	return (
+		lower.includes("connection timed out") ||
+		lower.includes("connection refused") ||
+		lower.includes("could not resolve hostname") ||
+		lower.includes("no route to host") ||
+		lower.includes("network is unreachable") ||
+		lower.includes("operation timed out")
+	);
+}
+
+export interface RunOptions {
+	/** SSH login password (only used when key auth failed). Fed via SSHPASS env. */
+	loginPassword?: string;
+	/** Run the remote command under sudo -S. */
+	sudo?: boolean;
+	/** Remote sudo password, piped to sudo's stdin. */
+	sudoPassword?: string;
+	controlPath: string;
+	signal?: AbortSignal;
+}
+
+/**
+ * Run `command` on the remote host. When `loginPassword` is set, ssh is wrapped
+ * in `sshpass -e` (password via env, not argv). When `sudo` is set, the command
+ * is wrapped in `sudo -S` and `sudoPassword` is written to the remote stdin.
+ */
+export function runSsh(spec: HostSpec, command: string, opts: RunOptions): Promise<SshResult> {
+	const remote = remoteCommand(command, opts.sudo === true);
+	const sshArgs = [...baseSshArgs(spec, opts.controlPath), hostTarget(spec), remote];
+
+	let bin = "ssh";
+	let args = sshArgs;
+	let env = process.env;
+	if (opts.loginPassword) {
+		bin = "sshpass";
+		args = ["-e", "ssh", ...sshArgs];
+		env = { ...process.env, SSHPASS: opts.loginPassword };
+	}
+
+	return new Promise((resolve, reject) => {
+		const proc = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"], env });
+		let stdout = "";
+		let stderr = "";
+
+		proc.stdout.on("data", (c: Buffer) => {
+			stdout += c.toString();
+		});
+		proc.stderr.on("data", (c: Buffer) => {
+			const filtered = opts.sudo ? filterSudoPrompt(c.toString()) : c.toString();
+			if (filtered) stderr += filtered;
+		});
+
+		proc.on("error", reject);
+		proc.on("close", (code) => resolve({ stdout, stderr, code: code ?? 1 }));
+
+		// Remote sudo reads its password from stdin (first line); anything else
+		// closes stdin so the remote command sees EOF.
+		if (opts.sudo && opts.sudoPassword !== undefined) {
+			proc.stdin.write(`${opts.sudoPassword}\n`);
+		}
+		proc.stdin.end();
+
+		signal(opts.signal, proc, reject);
+	});
+}
+
+function signal(
+	sig: AbortSignal | undefined,
+	proc: ReturnType<typeof spawn>,
+	reject: (e: Error) => void,
+): void {
+	sig?.addEventListener(
+		"abort",
+		() => {
+			proc.kill("SIGTERM");
+			reject(new Error("Cancelled"));
+		},
+		{ once: true },
+	);
+}