better-dsh 0.2.4 → 0.2.5

package/lib/remote/plugin.js

@@ -0,0 +1,1095 @@
+import { Context } from "@deepseek-ai/cordis";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { readFile } from "node:fs/promises";
+
+//#region src/remote/oneshot.ts
+/** 单流硬收集帽（4M UTF-16 code units，ASCII≈4MB）：防失控输出吃内存；模型面截断由上层 tailWindow 负责。 */
+const HARD_CAP = 4e6;
+/** One-shot：子进程退出码即收尾（spec §五.1），stdout/stderr 分离保留。 */
+async function runOneShot(argv, opts = {}) {
+	const started = Date.now();
+	const child = spawn(argv[0], argv.slice(1), {
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		detached: true
+	});
+	let stdout = "";
+	let stderr = "";
+	let timedOut = false;
+	child.stdout.setEncoding("utf8").on("data", (d) => {
+		if (stdout.length < HARD_CAP) stdout = (stdout + d).slice(0, HARD_CAP);
+	});
+	child.stderr.setEncoding("utf8").on("data", (d) => {
+		if (stderr.length < HARD_CAP) stderr = (stderr + d).slice(0, HARD_CAP);
+	});
+	child.stdin.on("error", () => {});
+	if (opts.stdin !== void 0) child.stdin.write(opts.stdin);
+	child.stdin.end();
+	let termTimer;
+	let killTimer;
+	const clearTimers = () => {
+		if (termTimer !== void 0) clearTimeout(termTimer);
+		if (killTimer !== void 0) clearTimeout(killTimer);
+	};
+	if (opts.timeoutSec !== void 0) {
+		const killGroup = (sig) => {
+			if (child.pid === void 0) {
+				child.kill(sig);
+				return;
+			}
+			try {
+				process.kill(-child.pid, sig);
+			} catch {}
+		};
+		termTimer = setTimeout(() => {
+			timedOut = true;
+			killGroup("SIGTERM");
+			killTimer = setTimeout(() => killGroup("SIGKILL"), 2e3);
+		}, opts.timeoutSec * 1e3);
+	}
+	const exit = await new Promise((resolve$1) => {
+		child.once("close", (code) => resolve$1(code));
+		child.once("error", (err) => {
+			stderr += `\n[remote: spawn failed: ${err.message}]`;
+			resolve$1(null);
+		});
+	});
+	clearTimers();
+	return {
+		exit,
+		timedOut,
+		stdout,
+		stderr,
+		durationMs: Date.now() - started
+	};
+}
+
+//#endregion
+//#region src/remote/nonce-framing.ts
+/** 8 字节随机串的 hex 形（spec §五.2：每次下发前生成）。 */
+function genNonce(bytes = 8) {
+	return randomBytes(bytes).toString("hex");
+}
+/** 命令整行：花括号复合体 + Nonce 收帧尾（spec §五.2 的 printf 逐字落地 + cwd 第三字段）。 */
+function wrapPtyCommand(cmd, nonce) {
+	return `{\n${cmd}\n} ; printf '\\033]133;D;${nonce};%s;%s\\007' "$?" "$PWD"\n`;
+}
+/** init 整行：哑终端（echo/PS1/PS2/TERM）+ 固定 40×120（Non-Goal ③）+ INIT 帧。 */
+function buildInitCommand(nonce) {
+	return `stty -echo 2>/dev/null ; stty rows 40 cols 120 2>/dev/null ; PS1='' ; PS2='' ; export TERM=dumb ; printf '\\033]133;D;${nonce};0;%s\\007' "$PWD"\n`;
+}
+const ANSI_RE = /\x1b(?:\][^\x07\x1b]*(?:\x07|\x1b\\)?|\[[0-9;?]*[ -/]*[@-~]|[@-Z\\-_])/g;
+function stripAnsi(s) {
+	return s.replace(ANSI_RE, "");
+}
+function normalizePtyText(s) {
+	return stripAnsi(s).replace(/\r\n/g, "\n").replace(/\r/g, "");
+}
+function tailWindow(text, cap) {
+	if (text.length <= cap) return { text };
+	return {
+		text: `[truncated: showing last ${cap} of ${text.length} chars]\n${text.slice(text.length - cap)}`,
+		truncated: text.length
+	};
+}
+const FRAME_BODY_RE = /^(\d+);([^\x07\x1b]*)(?:\x07|\x1b\\)/;
+/**
+* 单 nonce、单帧解析器：一轮 dispatch 一个实例。只认 `\x1b]133;D;<nonce>;`，
+* 错误 nonce 的静态/伪造 marker 永不匹配，按普通输出流过（再经 ANSI 剥洗）。
+* 缓冲尾若可能是 marker 前缀则扣留，flush() 时作为输出放出。
+*/
+function createNonceFrameParser(nonce, events) {
+	const prefix = `\x1b]133;D;${nonce};`;
+	let buf = "";
+	let done = false;
+	const emit = (raw) => {
+		const text = normalizePtyText(raw);
+		if (text.length > 0) events.onOutput?.(text);
+	};
+	const holdback = () => {
+		const max = Math.min(buf.length, prefix.length - 1);
+		for (let k = max; k > 0; k--) if (buf.endsWith(prefix.slice(0, k))) return k;
+		return 0;
+	};
+	const consume = () => {
+		if (done) return;
+		const i = buf.indexOf(prefix);
+		if (i < 0) {
+			const keep = holdback();
+			emit(buf.slice(0, buf.length - keep));
+			buf = buf.slice(buf.length - keep);
+			return;
+		}
+		emit(buf.slice(0, i));
+		const rest = buf.slice(i + prefix.length);
+		const m = FRAME_BODY_RE.exec(rest);
+		if (m === null) {
+			buf = buf.slice(i);
+			return;
+		}
+		events.onFrame({
+			exit: Number(m[1]),
+			cwd: m[2].length > 0 ? m[2] : null
+		});
+		done = true;
+		buf = "";
+	};
+	return {
+		feed(chunk) {
+			buf += chunk;
+			consume();
+		},
+		flush() {
+			if (buf.length > 0) events.onOutput?.(buf);
+			buf = "";
+		}
+	};
+}
+
+//#endregion
+//#region src/remote/pty-session.ts
+/** spec §五.2 逐字。 */
+const RECONNECT_NOTICE = "[remote: session reconnected to fresh shell; cwd reset to default]";
+const DEFAULT_INIT_TIMEOUT_SEC = 30;
+const INTERRUPT_GRACE_MS = 3e3;
+/** pty 收集内存安全帽（Ruling P15，与 oneshot HARD_CAP 对齐）：模型面只见尾窗，保留尾部。 */
+const OUTPUT_HARD_CAP = 4e6;
+var PtySession = class {
+	proc = null;
+	state = "cold";
+	startPromise = null;
+	queue = Promise.resolve();
+	idleTimer = null;
+	onChunk = null;
+	deathWaiters = [];
+	diag = "";
+	inFlight = 0;
+	lastSettleAt = 0;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	get sessionState() {
+		return this.state;
+	}
+	/** status 面快照：state + busy（有命令在跑）+ idleMs（上次 settle 至今）+ pid（进程组头，kill 兜底可观测）。 */
+	get snapshot() {
+		return {
+			state: this.state,
+			busy: this.inFlight > 0,
+			idleMs: this.lastSettleAt > 0 ? Date.now() - this.lastSettleAt : null,
+			pid: this.proc?.pid ?? null
+		};
+	}
+	/** 同一会话命令严格串行（FIFO）；死亡/冷态先重启。 */
+	dispatch(cmd, dOpts = {}) {
+		const attempt = async () => {
+			const started = Date.now();
+			const reconnected = this.state === "dead";
+			if (this.state !== "ready") await this.start();
+			this.inFlight++;
+			return await new Promise((resolve$1) => {
+				const nonce = genNonce();
+				let output = "";
+				let interrupted = false;
+				let settled = false;
+				let interruptTimer;
+				let killTimer;
+				const deathWaiter = () => finish({
+					output,
+					exit: null,
+					cwd: null,
+					timedOut: interrupted
+				});
+				const cleanup = () => {
+					this.onChunk = null;
+					this.deathWaiters = this.deathWaiters.filter((w) => w !== deathWaiter);
+					if (interruptTimer !== void 0) clearTimeout(interruptTimer);
+					if (killTimer !== void 0) clearTimeout(killTimer);
+				};
+				const finish = (r) => {
+					if (settled) return;
+					settled = true;
+					cleanup();
+					this.inFlight--;
+					this.lastSettleAt = Date.now();
+					this.resetIdleTimer();
+					resolve$1({
+						...r,
+						reconnected,
+						durationMs: Date.now() - started
+					});
+				};
+				const parser = createNonceFrameParser(nonce, {
+					onOutput: (t) => {
+						output += t;
+						if (output.length > OUTPUT_HARD_CAP) {
+							output = output.slice(output.length - OUTPUT_HARD_CAP);
+							if (output.charCodeAt(0) >= 56320 && output.charCodeAt(0) <= 57343) output = output.slice(1);
+						}
+					},
+					onFrame: ({ exit, cwd }) => finish({
+						output,
+						exit,
+						cwd,
+						timedOut: interrupted
+					})
+				});
+				this.onChunk = (c) => parser.feed(c);
+				this.write(wrapPtyCommand(cmd, nonce));
+				if (dOpts.stdin !== void 0) this.write(dOpts.stdin);
+				interruptTimer = setTimeout(() => {
+					interrupted = true;
+					this.write("");
+					this.write(`printf '\\033]133;D;${nonce};130;%s\\007' "$PWD"\n`);
+					killTimer = setTimeout(() => {
+						this.killTree();
+						this.markDead();
+						finish({
+							output,
+							exit: null,
+							cwd: null,
+							timedOut: true
+						});
+					}, INTERRUPT_GRACE_MS);
+				}, dOpts.timeoutSec === void 0 ? 12e4 : dOpts.timeoutSec * 1e3);
+				this.deathWaiters.push(deathWaiter);
+			});
+		};
+		const run = this.queue.then(attempt, attempt);
+		this.queue = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	/** TTL / row teardown：尽力 exit，1s 后杀组，出池。 */
+	async dispose() {
+		if (this.state === "disposed") return;
+		this.clearIdleTimer();
+		this.state = "disposed";
+		this.startPromise = null;
+		this.write("exit\n");
+		setTimeout(() => this.killTree(), 1e3).unref();
+		this.opts.onDead?.();
+	}
+	write(s) {
+		if (this.proc?.stdin?.writable !== true) return;
+		try {
+			this.proc.stdin.write(s);
+		} catch {}
+	}
+	async start() {
+		if (this.state === "disposed") throw new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' was disposed — the pool replaces disposed sessions; this reference is stale`);
+		if (this.startPromise === null) {
+			this.state = "starting";
+			this.startPromise = this.doStart().catch((err) => {
+				this.startPromise = null;
+				this.markDead();
+				throw err;
+			});
+		}
+		return this.startPromise;
+	}
+	async doStart() {
+		const proc = spawn(this.opts.argv[0], this.opts.argv.slice(1), {
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			detached: true
+		});
+		this.proc = proc;
+		proc.stdout.setEncoding("utf8");
+		proc.stdout.on("data", (d) => {
+			this.onChunk?.(d);
+		});
+		proc.stderr.setEncoding("utf8").on("data", (d) => {
+			this.diag = (this.diag + d).slice(-2e3);
+		});
+		proc.once("close", () => this.markDead());
+		proc.once("error", (err) => {
+			this.diag = (this.diag + `\n[remote: spawn failed: ${err.message}]`).slice(-2e3);
+		});
+		const initTimeoutSec = this.opts.initTimeoutSec ?? DEFAULT_INIT_TIMEOUT_SEC;
+		const initNonce = genNonce();
+		await new Promise((resolve$1, reject) => {
+			const timer = setTimeout(() => {
+				this.killTree();
+				reject(/* @__PURE__ */ new Error(`[E_SESSION_START] remote pty session '${this.opts.key}' did not initialize in ${initTimeoutSec}s` + (this.diag.length > 0 ? `; transport stderr tail: ${this.diag}` : "")));
+			}, initTimeoutSec * 1e3);
+			const waiter = () => {
+				clearTimeout(timer);
+				reject(/* @__PURE__ */ new Error(`[E_SESSION_DIED] remote pty session '${this.opts.key}' died before initializing` + (this.diag.length > 0 ? `; transport stderr tail: ${this.diag}` : "")));
+			};
+			this.deathWaiters.push(waiter);
+			const parser = createNonceFrameParser(initNonce, { onFrame: () => {
+				clearTimeout(timer);
+				this.deathWaiters = this.deathWaiters.filter((w) => w !== waiter);
+				if (this.state === "disposed") {
+					reject(/* @__PURE__ */ new Error(`[E_SESSION_DISPOSED] remote pty session '${this.opts.key}' disposed during init`));
+					return;
+				}
+				this.state = "ready";
+				this.resetIdleTimer();
+				resolve$1();
+			} });
+			this.onChunk = (c) => parser.feed(c);
+			this.write(buildInitCommand(initNonce));
+		});
+	}
+	markDead() {
+		if (this.state === "disposed") {
+			const waiters$1 = this.deathWaiters;
+			this.deathWaiters = [];
+			for (const w of waiters$1) w();
+			return;
+		}
+		this.state = "dead";
+		this.startPromise = null;
+		this.clearIdleTimer();
+		const waiters = this.deathWaiters;
+		this.deathWaiters = [];
+		for (const w of waiters) w();
+	}
+	resetIdleTimer() {
+		this.clearIdleTimer();
+		this.idleTimer = setTimeout(() => void this.dispose(), this.opts.idleTtlSec * 1e3);
+		this.idleTimer.unref();
+	}
+	clearIdleTimer() {
+		if (this.idleTimer !== null) {
+			clearTimeout(this.idleTimer);
+			this.idleTimer = null;
+		}
+	}
+	killTree() {
+		const pid = this.proc?.pid;
+		this.proc = null;
+		if (pid === void 0) return;
+		try {
+			process.kill(-pid, "SIGTERM");
+		} catch {}
+		setTimeout(() => {
+			try {
+				process.kill(-pid, "SIGKILL");
+			} catch {}
+		}, 2e3).unref();
+	}
+};
+/** 会话池：键 → 会话。意外死亡的会话留在池内（下次 dispatch 带 reconnect 提示）。 */
+var PtyPool = class {
+	sessions = /* @__PURE__ */ new Map();
+	constructor(defaults) {
+		this.defaults = defaults;
+	}
+	get size() {
+		return this.sessions.size;
+	}
+	/** status 面：键上的会话快照（无会话 = undefined → "none — dials on first exec"）。 */
+	inspect(key) {
+		return this.sessions.get(key)?.snapshot;
+	}
+	/** roster 面：池内全部会话（key 含 agent 前缀 `${sessionKey}|t:<target>` / `|s:<spawn>`）。 */
+	list() {
+		return [...this.sessions.entries()].map(([key, s]) => ({
+			key,
+			snapshot: s.snapshot
+		}));
+	}
+	getOrCreate(key, argv) {
+		let s = this.sessions.get(key);
+		if (s === void 0 || s.sessionState === "disposed") {
+			s = new PtySession({
+				key,
+				argv,
+				...this.defaults,
+				onDead: () => this.sessions.delete(key)
+			});
+			this.sessions.set(key, s);
+		}
+		return s;
+	}
+	async disposeAll() {
+		await Promise.all([...this.sessions.values()].map((s) => s.dispose()));
+		this.sessions.clear();
+	}
+};
+
+//#endregion
+//#region src/remote/target.ts
+var TargetFormatError = class extends Error {
+	code = "E_TARGET_FORMAT";
+	constructor(message) {
+		super(message);
+		this.name = "TargetFormatError";
+	}
+};
+/** 显式协议选择器（Ruling P16）：可扩展新协议——加一个词即一条新传输腿。 */
+const PREFIX_RE = /^(docker|incus|ssh):(.+)$/;
+/** spec §二.2 智能路由（Ruling P18）：显式选择器 > ssh 缺省；无别名表面——容器一律显式前缀，发现走 on-demand probe。 */
+function resolveTarget(target) {
+	const raw = target.trim();
+	if (raw.length === 0) throw new TargetFormatError("[E_TARGET_FORMAT] remote: empty target");
+	const direct = PREFIX_RE.exec(raw);
+	if (direct !== null) {
+		if (direct[1] === "ssh") return {
+			kind: "ssh",
+			host: direct[2]
+		};
+		return {
+			kind: direct[1],
+			container: direct[2]
+		};
+	}
+	return {
+		kind: "ssh",
+		host: raw
+	};
+}
+
+//#endregion
+//#region src/remote/status.ts
+function oneLine$1(s) {
+	return s.trim().split(/\r?\n/).filter(Boolean).at(-1) ?? "";
+}
+/**
+* On-demand 探测（Ruling 17）：调用瞬间拨一次，双重超时（ssh ConnectTimeout
+* 5s + 外层 hard 10s），结果即当时事实。绝不缓存、绝不在 boot 时扫。
+*/
+async function probeTarget(plan, opts = {}) {
+	const ct = opts.connectTimeoutSec ?? 5;
+	const hard = opts.hardTimeoutSec ?? 10;
+	const runner = opts.runner ?? runOneShot;
+	const started = Date.now();
+	const r = await runner(plan.kind === "ssh" ? [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		`ConnectTimeout=${ct}`,
+		"-T",
+		"--",
+		plan.host,
+		"true"
+	] : plan.kind === "docker" ? [
+		"docker",
+		"inspect",
+		"--format",
+		"{{.State.Status}}",
+		plan.container
+	] : [
+		"incus",
+		"list",
+		plan.container,
+		"--format",
+		"csv",
+		"--columns",
+		"ns"
+	], { timeoutSec: hard });
+	if (plan.kind === "ssh") {
+		if (r.exit === 0 && !r.timedOut) return {
+			state: "reachable",
+			rttMs: Date.now() - started
+		};
+		return {
+			state: "unreachable",
+			detail: r.timedOut ? `probe timed out after ${hard}s` : oneLine$1(r.stderr) || `ssh exited ${r.exit}`
+		};
+	}
+	if (plan.kind === "docker") {
+		if (r.exit === 0 && !r.timedOut) return {
+			state: "container",
+			status: r.stdout.trim()
+		};
+		return {
+			state: "error",
+			detail: oneLine$1(r.stderr) || `docker inspect exited ${r.exit}`
+		};
+	}
+	const row = r.stdout.trim().split(/\r?\n/).find((l) => l.split(",")[0] === plan.container);
+	if (r.exit === 0 && !r.timedOut && row !== void 0) return {
+		state: "container",
+		status: row.split(",")[1]?.trim() ?? "unknown"
+	};
+	if (r.exit === 0 && !r.timedOut) return {
+		state: "error",
+		detail: `incus list has no container named '${plan.container}'`
+	};
+	return {
+		state: "error",
+		detail: oneLine$1(r.stderr) || `incus exited ${r.exit}`
+	};
+}
+function renderProbe(p) {
+	switch (p.state) {
+		case "reachable": return `probe: reachable in ${p.rttMs}ms (just now, on demand)`;
+		case "unreachable": return `probe: unreachable — ${p.detail}`;
+		case "error": return `probe: error — ${p.detail}`;
+		case "container": return `probe: container ${p.status} (just now, on demand)`;
+	}
+}
+/**
+* 唯一偏离 brief 处：brief 的 renderSession 测试以不含 `pid` 的三字段字面量直呼本函数，而
+* SessionSnapshot.pid 为必填 → 按测试意图（会话层词汇只由 state/busy/idleMs 决定）收窄为
+* 结构子集；传完整 SessionSnapshot 仍然成立，运行时语义零变化。
+*/
+function renderSession(s) {
+	if (s === void 0 || s.state === "cold" || s.state === "starting" || s.state === "disposed") return "session: none — dials on first exec";
+	if (s.state === "dead") return "session: died — next exec cold-starts a fresh shell";
+	if (s.busy) return "session: busy (a command is running)";
+	return `session: idle ${Math.round((s.idleMs ?? 0) / 1e3)}s (connected)`;
+}
+
+//#endregion
+//#region src/remote/ssh-config.ts
+/** Per-entry Host-line pattern lists — module-private, so the public entry shape stays exactly as declared. */
+const PATTERNS = /* @__PURE__ */ new WeakMap();
+/** `~` / `~/` prefix → real home directory (IdentityFile only). */
+function expandHome(path) {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return homedir() + path.slice(1);
+	return path;
+}
+function parseSshConfig(text) {
+	const entries = [];
+	const skipped = [];
+	const skippedSeen = /* @__PURE__ */ new Set();
+	let current;
+	const skip = (key) => {
+		const lower = key.toLowerCase();
+		if (!skippedSeen.has(lower)) {
+			skippedSeen.add(lower);
+			skipped.push(key);
+		}
+	};
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (line === "" || line.startsWith("#")) continue;
+		const match = /^([^\s=]+)\s*(?:=\s*)?(.*)$/.exec(line);
+		if (match === null) continue;
+		const key = match[1];
+		const value = (match[2] ?? "").trim();
+		if (key.toLowerCase() === "host") {
+			const patterns = value.split(/[\s,]+/).filter((p) => p !== "");
+			if (patterns.length === 0) {
+				skip(key);
+				continue;
+			}
+			current = {
+				host: patterns[0],
+				identityFiles: []
+			};
+			PATTERNS.set(current, patterns);
+			entries.push(current);
+			continue;
+		}
+		switch (key.toLowerCase()) {
+			case "hostname":
+				if (current !== void 0 && current.hostName === void 0) current.hostName = value;
+				break;
+			case "user":
+				if (current !== void 0 && current.user === void 0) current.user = value;
+				break;
+			case "port": {
+				if (current === void 0) break;
+				const port = /^\d+$/.test(value) ? Number.parseInt(value, 10) : void 0;
+				if (current.port === void 0) if (port === void 0) skip(key);
+				else current.port = port;
+				break;
+			}
+			case "identityfile":
+				if (current !== void 0) current.identityFiles.push(expandHome(value));
+				break;
+			case "proxyjump":
+				if (current !== void 0 && current.proxyJump === void 0) current.proxyJump = value;
+				break;
+			default: skip(key);
+		}
+	}
+	return {
+		entries,
+		skipped
+	};
+}
+
+//#endregion
+//#region src/remote/roster.ts
+function oneLine(s) {
+	return s.trim().split(/\r?\n/).filter(Boolean).at(-1) ?? "";
+}
+/** ssh config 里的字面别名（无通配、非否定的首个模式）；通配块是默认值来源不是目标。 */
+function literalHosts(text) {
+	const { entries } = parseSshConfig(text);
+	const hosts = [];
+	let wildcardBlocks = 0;
+	for (const entry of entries) if (/[*?]/.test(entry.host) || entry.host.startsWith("!")) wildcardBlocks++;
+	else hosts.push(entry.host);
+	return {
+		hosts,
+		wildcardBlocks
+	};
+}
+/**
+* Build the roster text. Sections render independently; a failing section
+* renders its native error (honest vocabulary: never invent, never hide).
+*/
+async function renderRoster(sessions, opts = {}) {
+	const runner = opts.runner ?? runOneShot;
+	const readSshConfig = opts.readSshConfig ?? (async () => await readFile(join(homedir(), ".ssh", "config"), "utf8"));
+	const hard = opts.hardTimeoutSec ?? 10;
+	const lines = [];
+	try {
+		const { hosts, wildcardBlocks } = literalHosts(await readSshConfig());
+		lines.push(`ssh hosts (~/.ssh/config): ${hosts.length > 0 ? hosts.join(", ") : "(none)"}${wildcardBlocks > 0 ? ` (+${wildcardBlocks} wildcard default blocks, not listed)` : ""}`);
+	} catch (error) {
+		lines.push(`ssh hosts: no readable ~/.ssh/config (${error instanceof Error ? error.message : String(error)})`);
+	}
+	const docker = await runner([
+		"docker",
+		"ps",
+		"-a",
+		"--format",
+		"{{.Names}}	{{.State}}"
+	], { timeoutSec: hard });
+	if (docker.exit === 0) {
+		const rows = docker.stdout.trim().split(/\r?\n/).filter(Boolean).map((l) => {
+			const [name$1, state] = l.split("	");
+			return `${name$1}${state !== void 0 && state !== "" ? ` (${state})` : ""}`;
+		});
+		lines.push(`docker containers: ${rows.length > 0 ? rows.join(", ") : "(none)"}`);
+	} else lines.push(`docker containers: unavailable — ${docker.timedOut ? `scan timed out after ${hard}s` : oneLine(docker.stderr) || `docker exited ${docker.exit}`}`);
+	const incus = await runner([
+		"incus",
+		"list",
+		"--format",
+		"csv",
+		"--columns",
+		"ns"
+	], { timeoutSec: hard });
+	if (incus.exit === 0) {
+		const rows = incus.stdout.trim().split(/\r?\n/).filter(Boolean).map((l) => {
+			const [name$1, state] = l.split(",");
+			return `${name$1}${state !== void 0 && state !== "" ? ` (${state.trim()})` : ""}`;
+		});
+		lines.push(`incus containers: ${rows.length > 0 ? rows.join(", ") : "(none)"}`);
+	} else lines.push(`incus containers: unavailable — ${incus.timedOut ? `scan timed out after ${hard}s` : oneLine(incus.stderr) || `incus exited ${incus.exit}`}`);
+	lines.push(sessions.length > 0 ? `live pty sessions: ${sessions.map((s) => `${s.target} [${s.state}${s.idleSec !== null ? `, idle ${s.idleSec}s` : ""}]`).join(", ")}` : "live pty sessions: none");
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/remote/transports.ts
+/** POSIX 单引号机械转义（唯一一层转义，spec §三"一层机械转义"）。 */
+function shQuote(s) {
+	return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+/** One-shot（§五.1）：不分配 tty，收尾 = 子进程退出码，零字符串扫描。 */
+function buildOneShotArgv(plan, cmd) {
+	switch (plan.kind) {
+		case "ssh": return [
+			"ssh",
+			"-o",
+			"BatchMode=yes",
+			"-T",
+			"--",
+			plan.host,
+			`bash -lc ${shQuote(cmd)}`
+		];
+		case "docker": return [
+			"docker",
+			"exec",
+			"-i",
+			"--",
+			plan.container,
+			"bash",
+			"-lc",
+			cmd
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-noninteractive",
+			plan.container,
+			"--",
+			"bash",
+			"-lc",
+			cmd
+		];
+	}
+}
+/** Persistent pty（Ruling 2）：ssh/incus 走宿主管道，docker 经 script(1) 托管宿主 PTY。 */
+function buildPtyArgv(plan) {
+	switch (plan.kind) {
+		case "ssh": return [
+			"ssh",
+			"-tt",
+			"-o",
+			"BatchMode=yes",
+			"--",
+			plan.host,
+			"bash"
+		];
+		case "docker": return [
+			"script",
+			"-qfec",
+			`stty -echo 2>/dev/null ; exec docker exec -it -- ${shQuote(plan.container)} bash`,
+			"/dev/null"
+		];
+		case "incus": return [
+			"incus",
+			"exec",
+			"--force-interactive",
+			plan.container,
+			"--",
+			"bash"
+		];
+	}
+}
+/** BYO-PTY（§三 spawn）：工具只提供 PTY 托管 + Nonce 注入 + 收帧。 */
+function buildSpawnArgv(spawnCommand) {
+	return [
+		"script",
+		"-qfec",
+		`stty -echo 2>/dev/null ; exec ${spawnCommand}`,
+		"/dev/null"
+	];
+}
+
+//#endregion
+//#region src/remote/driver.ts
+/** 双轨调度器（spec §七 Phase 2）：参数校验 → 路由 → oneshot 子进程 / pty 会话池。 */
+var RemoteDriver = class {
+	pool;
+	constructor(opts = {}) {
+		this.opts = opts;
+		this.pool = new PtyPool({ idleTtlSec: opts.idleTtlSec ?? 600 });
+	}
+	async call(params, callCtx = {}) {
+		const started = Date.now();
+		try {
+			const routing = this.route(params);
+			const result = await this.execute(params, routing, callCtx);
+			this.audit({
+				target: routing.display,
+				cmd: params.cmd,
+				cwd: result.cwd ?? void 0,
+				exit: result.exit,
+				durationMs: Date.now() - started
+			});
+			return result;
+		} catch (error) {
+			this.audit({
+				target: params.target ?? params.spawn ?? "?",
+				cmd: params.cmd,
+				error: error instanceof Error ? error.message : String(error),
+				durationMs: Date.now() - started
+			});
+			throw error;
+		}
+	}
+	/** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
+	/**
+	* Ruling P20：裸名先按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
+	* 撞名 ssh 优先，查无 → 默认 ssh 交原生错误）。选择器前缀的 target 不经此路径。
+	*/
+	async resolveBareName(name$1) {
+		const runner = this.opts.rosterRunner ?? runOneShot;
+		const readCfg = this.opts.sshConfigReader ?? (async () => await readFile(join(homedir(), ".ssh", "config"), "utf8"));
+		try {
+			const { hosts } = literalHosts(await readCfg());
+			if (hosts.some((h) => h.toLowerCase() === name$1.toLowerCase())) return {
+				kind: "ssh",
+				host: name$1
+			};
+		} catch {}
+		const docker = await runner([
+			"docker",
+			"ps",
+			"-a",
+			"--format",
+			"{{.Names}}"
+		], { timeoutSec: 10 });
+		if (docker.exit === 0 && docker.stdout.trim().split(/\r?\n/).some((n) => n.trim().toLowerCase() === name$1.toLowerCase())) return {
+			kind: "docker",
+			container: name$1
+		};
+		const incus = await runner([
+			"incus",
+			"list",
+			"--format",
+			"csv",
+			"--columns",
+			"n"
+		], { timeoutSec: 10 });
+		if (incus.exit === 0 && incus.stdout.trim().split(/\r?\n/).some((n) => n.split(",")[0]?.trim().toLowerCase() === name$1.toLowerCase())) return {
+			kind: "incus",
+			container: name$1
+		};
+		return {
+			kind: "ssh",
+			host: name$1
+		};
+	}
+	/** Ruling P19：roster = 注意力入口——本地廉价扫描（ssh config/docker ps/incus list + 池内活会话），零拨号。 */
+	async roster() {
+		return await renderRoster(this.pool.list().map(({ key, snapshot }) => {
+			const raw = key.includes("|") ? key.slice(key.indexOf("|") + 1) : key;
+			return {
+				target: raw.startsWith("t:") ? raw.slice(2) : raw.startsWith("s:") ? `spawn:${raw.slice(2)}` : raw,
+				state: snapshot.state,
+				idleSec: snapshot.idleMs !== null ? Math.round(snapshot.idleMs / 1e3) : null
+			};
+		}), this.opts.rosterRunner !== void 0 ? { runner: this.opts.rosterRunner } : {});
+	}
+	async status(target, callCtx = {}) {
+		const plan = /^(docker|incus|ssh):/.test(target) ? resolveTarget(target) : await this.resolveBareName(target);
+		const head = `${target} — ${plan.kind === "ssh" ? "ssh host" : `${plan.kind} container`}`;
+		const probe = await probeTarget(plan, { runner: this.opts.probeRunner });
+		const key = `${callCtx.sessionKey ?? "no-session"}|t:${target}`;
+		return [
+			head,
+			renderProbe(probe),
+			renderSession(this.pool.inspect(key))
+		].join("\n");
+	}
+	/** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径（成功被毒化成失败+双重审计）。 */
+	audit(r) {
+		try {
+			this.opts.onAudit?.(r);
+		} catch {}
+	}
+	route(params) {
+		const hasTarget = params.target !== void 0 && params.target.length > 0;
+		const hasSpawn = params.spawn !== void 0 && params.spawn.length > 0;
+		if (hasTarget && hasSpawn) throw new Error("[E_PARAMS] remote: pass exactly one of target or spawn, not both");
+		if (!hasTarget && !hasSpawn) throw new Error("[E_PARAMS] remote: target or spawn is required (e.g. { target: \"dev4\", cmd: \"git status\" })");
+		if (params.timeout !== void 0 && (!Number.isFinite(params.timeout) || params.timeout <= 0)) throw new Error(`[E_BAD_TIMEOUT] remote: timeout must be a positive number of seconds (got ${JSON.stringify(params.timeout)})`);
+		if (params.stdin !== void 0 && (params.cmd === void 0 || params.cmd.length === 0)) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd");
+		const mode = hasSpawn ? "pty" : params.mode ?? "oneshot";
+		if (hasSpawn) return {
+			mode,
+			display: params.spawn,
+			spawn: params.spawn
+		};
+		const direct = /^(docker|incus|ssh):/.test(params.target);
+		return {
+			mode,
+			display: params.target,
+			...direct ? { plan: resolveTarget(params.target) } : { bare: params.target }
+		};
+	}
+	async execute(params, routing, callCtx) {
+		if (routing.bare !== void 0) routing.plan = await this.resolveBareName(routing.bare);
+		const timeoutSec = params.timeout ?? this.opts.execTimeoutSec ?? 120;
+		const cap = this.opts.maxOutputChars ?? 3e4;
+		if (routing.mode === "oneshot") {
+			const r$1 = await runOneShot((this.opts.oneshotArgvFor ?? buildOneShotArgv)(routing.plan, params.cmd), {
+				stdin: params.stdin,
+				timeoutSec
+			});
+			const out$1 = tailWindow(r$1.stdout, cap);
+			const err = r$1.stderr.length > 0 ? tailWindow(r$1.stderr, cap) : void 0;
+			return {
+				mode: "oneshot",
+				target: routing.display,
+				exit: r$1.exit,
+				cwd: null,
+				timedOut: r$1.timedOut,
+				reconnected: false,
+				stdout: out$1.text,
+				...err !== void 0 ? { stderr: err.text } : {},
+				durationMs: r$1.durationMs,
+				...out$1.truncated !== void 0 ? { truncated: out$1.truncated } : {}
+			};
+		}
+		const argv = routing.spawn !== void 0 ? (this.opts.spawnArgvFor ?? buildSpawnArgv)(routing.spawn) : (this.opts.ptyArgvFor ?? buildPtyArgv)(routing.plan);
+		const key = `${callCtx.sessionKey ?? "no-session"}|${routing.spawn !== void 0 ? `s:${routing.spawn}` : `t:${routing.display}`}`;
+		const r = await this.pool.getOrCreate(key, argv).dispatch(params.cmd, {
+			stdin: params.stdin,
+			timeoutSec
+		});
+		const out = tailWindow(r.output, cap);
+		return {
+			mode: "pty",
+			target: routing.display,
+			exit: r.exit,
+			cwd: r.cwd,
+			timedOut: r.timedOut,
+			reconnected: r.reconnected,
+			stdout: out.text,
+			durationMs: r.durationMs,
+			...out.truncated !== void 0 ? { truncated: out.truncated } : {}
+		};
+	}
+	async dispose() {
+		await this.pool.disposeAll();
+	}
+};
+
+//#endregion
+//#region src/remote/tool.ts
+const NO_SESSION_KEY = "remote:no-session";
+function createRemoteTool(driver, opts = {}) {
+	const getSessionKey = opts.getSessionKey ?? ((exec) => exec.agent?.id ?? NO_SESSION_KEY);
+	return defineTool({
+		name: "remote",
+		description: "Remote execution over three transports (ssh / docker / incus). Pick the call shape first:\n  {}            → roster: known target names from a local scan (no dialing)\n  {target}      → on-demand status probe of that one target\n  {target, cmd} → run cmd — oneshot by default; mode \"pty\" for a persistent shell\n  {spawn, cmd}  → BYO-PTY: you supply the interactive-shell command\nBare names match by name first (ssh config, then docker, then incus; on a collision ssh wins; unknown names go to ssh and its native error surfaces). \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a transport when you must be explicit. oneshot: stateless `bash -lc`, stdout/stderr separate, the exit code is the remote process's own. pty: one persistent shell per (agent, target) — cwd/env survive across calls, streams merge, Ctrl-C interrupts without killing the session, idle sessions are reaped after 600s (a reconnect notice precedes the fresh shell). Output is tail-truncated at ~30k chars with a \"[truncated: …]\" header — redirect bulk output to a file yourself. `stdin` feeds the command; `timeout` (seconds) interrupts then kills. Native transport errors pass through verbatim — self-correct from them. Background processes must redirect their own output (`cmd > log 2>&1 &`). Status probes report \"reachable\"/\"unreachable — <native error>\" or the factual container state plus the session layer (\"idle Ns\" / \"busy\" / \"none — dials on first exec\"), always probed at call time.",
+		parameters: {
+			target: {
+				type: "string",
+				description: "Bare name / IP / domain matches by name (ssh config, then docker, then incus; collision → ssh). \"docker:<name>\" / \"incus:<name>\" / \"ssh:<name>\" force a transport. Exactly one of target / spawn."
+			},
+			spawn: {
+				type: "string",
+				description: "BYO-PTY escape hatch: the full command that starts an interactive shell (e.g. \"docker exec -it img bash\"). Requires cmd, excludes target; mode is locked to pty; nested hops are dumb pipes (only the innermost bash frames)."
+			},
+			cmd: {
+				type: "string",
+				description: "One raw shell string parsed by the remote bash (multi-line = one compound; exit = last command's). Omit with target → status probe; omit everything → roster."
+			},
+			mode: {
+				type: "string",
+				enum: ["oneshot", "pty"],
+				description: "'oneshot' (default): stateless `bash -lc`, stdout/stderr separate, exit code is the process's own. 'pty': one persistent shell per (agent, target), cwd/env survive, streams merge, idle TTL 600s."
+			},
+			stdin: {
+				type: "string",
+				description: "Input fed to the command. oneshot: piped to stdin. pty: written right after the command line (REPL-style) — only helps commands that read stdin there. Requires cmd."
+			},
+			timeout: {
+				type: "number",
+				description: "Per-command timeout in seconds (default 120, row-configurable). pty: Ctrl-C first, then kill; an interrupt does not kill the session."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					kind: {
+						type: "string",
+						required: true,
+						enum: [
+							"exec",
+							"status",
+							"roster"
+						]
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					exit: { oneOf: [{ type: "integer" }, { type: "null" }] },
+					durationMs: { type: "integer" },
+					cwd: { type: "string" },
+					stderr: { type: "string" },
+					timedOut: { type: "boolean" },
+					reconnected: { type: "boolean" },
+					truncated: { type: "integer" }
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderValue(value)
+			}]
+		},
+		async execute(args, exec) {
+			const hasCmd = typeof args.cmd === "string" && args.cmd.length > 0;
+			const hasTarget = typeof args.target === "string" && args.target.length > 0;
+			const hasSpawn = typeof args.spawn === "string" && args.spawn.length > 0;
+			if (args.mode !== void 0 && args.mode !== "oneshot" && args.mode !== "pty") throw new Error(`[E_BAD_MODE] remote: mode must be 'oneshot' or 'pty' (got ${JSON.stringify(args.mode)})`);
+			if (!hasCmd) {
+				if (args.stdin !== void 0) throw new Error("[E_STDIN_WITHOUT_CMD] remote: stdin requires cmd — status probes take no input");
+				if (hasSpawn) throw new Error("[E_PARAMS] remote: spawn is an exec channel — pass cmd (there is nothing to probe for BYO-PTY)");
+				if (!hasTarget) return {
+					kind: "roster",
+					text: await driver.roster(),
+					exit: null,
+					durationMs: 0
+				};
+				return {
+					kind: "status",
+					text: await driver.status(args.target, { sessionKey: getSessionKey(exec) }),
+					exit: null,
+					durationMs: 0
+				};
+			}
+			const r = await driver.call({
+				target: args.target,
+				spawn: args.spawn,
+				cmd: args.cmd,
+				mode: args.mode === "oneshot" || args.mode === "pty" ? args.mode : void 0,
+				stdin: args.stdin,
+				timeout: args.timeout
+			}, { sessionKey: getSessionKey(exec) });
+			const v = {
+				kind: "exec",
+				text: r.stdout,
+				exit: r.exit,
+				durationMs: r.durationMs
+			};
+			if (r.cwd !== null) v.cwd = r.cwd;
+			if (r.stderr !== void 0) v.stderr = r.stderr;
+			if (r.timedOut) v.timedOut = true;
+			if (r.reconnected) v.reconnected = true;
+			if (r.truncated !== void 0) v.truncated = r.truncated;
+			return v;
+		}
+	});
+}
+function renderValue(v) {
+	if (v.kind === "status" || v.kind === "roster") return v.text;
+	const parts = [];
+	if (v.reconnected === true) parts.push(RECONNECT_NOTICE);
+	parts.push(v.text);
+	const secs = ((v.durationMs ?? 0) / 1e3).toFixed(1);
+	const markers = [];
+	if (v.timedOut === true) markers.push("interrupted");
+	if (v.truncated !== void 0) markers.push(`truncated, original ${v.truncated} chars`);
+	const suffix = markers.length > 0 ? ` · ${markers.join(" · ")}` : "";
+	const cwdTag = typeof v.cwd === "string" && v.cwd.length > 0 ? ` · cwd ${v.cwd}` : "";
+	parts.push(`[exit ${v.exit} · ${secs}s${suffix}${cwdTag}]`);
+	if (v.stderr !== void 0 && v.stderr.length > 0) parts.push("[stderr]", v.stderr);
+	return parts.join("\n");
+}
+
+//#endregion
+//#region src/remote/plugin.ts
+const name = "dashr-remote";
+const inject = [];
+const Config = z.object({
+	execTimeoutSec: z.natural().min(1).default(120),
+	idleTtlSec: z.natural().min(1).default(600),
+	maxOutputChars: z.natural().min(1).default(3e4)
+}).default({
+	execTimeoutSec: 120,
+	idleTtlSec: 600,
+	maxOutputChars: 3e4
+});
+/** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
+const apply = (ctx, config) => {
+	const driver = new RemoteDriver({
+		execTimeoutSec: config.execTimeoutSec,
+		idleTtlSec: config.idleTtlSec,
+		maxOutputChars: config.maxOutputChars
+	});
+	ctx.inject(["tools"], (toolsCtx) => {
+		toolsCtx.tools.register(createRemoteTool(driver, { getSessionKey: (exec) => exec.agent?.id ?? "remote:no-session" }));
+	});
+	return () => void driver.dispose();
+};
+var plugin_default = {
+	name,
+	inject,
+	Config,
+	apply
+};
+
+//#endregion
+export { Config, apply, plugin_default as default, inject, name };