finch-remote-host 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,1645 @@
+import { randomUUID } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, posix } from "node:path";
+import { spawn } from "node:child_process";
+// finchapp/remote-host/src/audit.js
+const OUTPUT_CHARS = 4e3;
+const FILE_SCAN = 7;
+/** 审计目录，按需创建。 */
+function auditDir(ctx) {
+	const dir = join(ctx.storagePath, "audit");
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+/** 追加一条审计：时间、主机、会话、命令、判定、结果。 */
+function record(ctx, entry) {
+	const ts = (/* @__PURE__ */ new Date()).toISOString();
+	const row = {
+		ts,
+		...entry,
+		output: String(entry.output ?? "").slice(0, OUTPUT_CHARS)
+	};
+	appendFileSync(join(auditDir(ctx), `${ts.slice(0, 10)}.jsonl`), `${JSON.stringify(row)}\n`, "utf8");
+}
+/** 清掉某台主机的全部记录：逐文件过滤重写，别的主机一行不动。 */
+function clearHost(ctx, hostId) {
+	const dir = auditDir(ctx);
+	for (const name of readdirSync(dir).filter((item) => item.endsWith(".jsonl"))) {
+		const path = join(dir, name);
+		const kept = readFileSync(path, "utf8").split("\n").filter(Boolean).filter((line) => {
+			try {
+				return JSON.parse(line).hostId !== hostId;
+			} catch {
+				return true;
+			}
+		});
+		if (kept.length) writeFileSync(path, `${kept.join("\n")}\n`, "utf8");
+		else rmSync(path, { force: true });
+	}
+}
+/** 读最近记录：从最新文件往回翻，凑够 limit 条为止。 */
+function recent(ctx, { hostId, limit = 20 } = {}) {
+	const dir = auditDir(ctx);
+	const files = readdirSync(dir).filter((name) => name.endsWith(".jsonl")).toSorted().toReversed().slice(0, FILE_SCAN);
+	const rows = [];
+	for (const name of files) {
+		const lines = readFileSync(join(dir, name), "utf8").split("\n").filter(Boolean).toReversed();
+		for (const line of lines) {
+			let item;
+			try {
+				item = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (hostId && item.hostId !== hostId) continue;
+			rows.push(item);
+			if (rows.length >= limit) return rows;
+		}
+	}
+	return rows;
+}
+// finchapp/remote-host/src/policy.js
+const MODES = [
+	"query",
+	"readonly",
+	"confirm",
+	"trusted"
+];
+const DELETE_COMMANDS = /* @__PURE__ */ new Set(["rm", "rmdir"]);
+const ARG_STOPS = /* @__PURE__ */ new Set([
+	";",
+	"&",
+	"&&",
+	"|",
+	"||",
+	"(",
+	")",
+	">",
+	">>",
+	"<",
+	"2>",
+	"2>&1"
+]);
+/** 一级目标：`/`、`/var`、`/var/`、`/var/*`、不带路径的通配，以及家目录的三种写法。 */
+function isTopLevelPath(token) {
+	const bare = token.replace(/\/+$/, "").replace(/\/\*+$/, "");
+	if (bare === "" || bare === "*" || bare === "**") return true;
+	if (/^(?:~|\$HOME|\$\{HOME\})$/.test(bare)) return true;
+	return /^\/[^/*]+$/.test(bare);
+}
+function commandWord(token) {
+	return token.split("/").at(-1);
+}
+const PROTECTED_TREE = [
+	"/etc",
+	"/boot",
+	"/bin",
+	"/sbin",
+	"/lib",
+	"/lib32",
+	"/lib64",
+	"/libx32",
+	"/usr",
+	"/root",
+	"/var/www",
+	"/var/spool"
+];
+const PROTECTED_CHILD = [
+	"/home",
+	"/opt",
+	"/srv",
+	"/var/lib"
+];
+const PROTECTED_NAMES = [".ssh"];
+/** 目标路径是否命中保护名单。 */
+function isProtectedPath(token) {
+	const path = token.replace(/\/+$/, "");
+	if (!path) return false;
+	const parts = path.split("/");
+	if (PROTECTED_NAMES.some((name) => parts.includes(name))) return true;
+	if (PROTECTED_TREE.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))) return true;
+	return PROTECTED_CHILD.some((prefix) => path.startsWith(`${prefix}/`) && !path.slice(prefix.length + 1).includes("/"));
+}
+const DESTRUCTIVE_COMMANDS = /* @__PURE__ */ new Set([
+	"rm",
+	"rmdir",
+	"unlink",
+	"shred",
+	"truncate"
+]);
+/**
+* 命令是否在毁坏系统关键文件或目录：删除、清空、截断、写入。
+* 与删除判定一样先去掉引号再分段，`sh -c "truncate -s 0 /etc/passwd"` 也能看见。
+*/
+function touchesProtected(command) {
+	const text = String(command).replaceAll(/["']/g, " ");
+	for (const segment of splitSegments(text)) {
+		for (const match of segment.matchAll(/>{1,2}\s*(\S+)/g)) if (isProtectedPath(match[1])) return true;
+		const tokens = segment.split(/\s+/).filter(Boolean);
+		for (const [index, token] of tokens.entries()) {
+			const word = commandWord(token);
+			const args = tokens.slice(index + 1).filter((item) => !item.startsWith("-"));
+			if (word === "dd") {
+				if (args.some((item) => item.startsWith("of=") && isProtectedPath(item.slice(3)))) return true;
+				continue;
+			}
+			if (word === "find") {
+				if (tokens.includes("-delete") && args[0] && isProtectedPath(args[0])) return true;
+				continue;
+			}
+			if (!DESTRUCTIVE_COMMANDS.has(word)) continue;
+			for (const item of args) {
+				if (ARG_STOPS.has(item)) break;
+				if (isProtectedPath(item)) return true;
+			}
+		}
+	}
+	return false;
+}
+/**
+* 命令里是否在删根目录或某个一级目录。
+* 先去引号再分段扫描，`sh -c "rm -rf /var"` 、`sudo rm -rf /var` 这类包装也能看见。
+*/
+function deletesTopLevel(command) {
+	const text = String(command).replaceAll(/["']/g, " ");
+	for (const segment of splitSegments(text)) {
+		const tokens = segment.split(/\s+/).filter(Boolean);
+		for (const [index, token] of tokens.entries()) {
+			if (!DELETE_COMMANDS.has(commandWord(token))) continue;
+			for (const target of tokens.slice(index + 1)) {
+				if (ARG_STOPS.has(target)) break;
+				if (target.startsWith("-")) continue;
+				if (isTopLevelPath(target)) return true;
+			}
+		}
+	}
+	return false;
+}
+const HARD_DENY = [
+	{
+		name: "删除根目录或一级目录",
+		detail: "rm -rf /、rm -rf /var、rm -rf /var/*、rm -rf *",
+		test: deletesTopLevel
+	},
+	{
+		name: "毁坏系统关键路径",
+		detail: "删除、清空、截断、写入系统目录与密钥目录",
+		test: touchesProtected
+	},
+	{
+		name: "格式化文件系统",
+		detail: "mkfs 系列",
+		test: (text) => /\bmkfs(?:\.\w+)?\b/.test(text)
+	},
+	{
+		name: "写裸盘",
+		detail: "dd of=/dev/sd*、of=/dev/nvme* 等块设备",
+		test: (text) => /\bdd\b[^|;&]*\bof=\/dev\/(?:sd|nvme|hd|vd|mmcblk)/.test(text)
+	},
+	{
+		name: "重定向写裸盘",
+		detail: "> /dev/sd* 直接覆盖块设备",
+		test: (text) => />\s*\/dev\/(?:sd|nvme|hd|vd|mmcblk)/.test(text)
+	},
+	{
+		name: "fork 炸弹",
+		detail: ":(){ :|:& };: 这类无限分叉",
+		test: (text) => /:\s*\(\s*\)\s*\{[^}]*\|[^}]*&/.test(text)
+	},
+	{
+		name: "关机或重启",
+		detail: "shutdown、reboot、halt、poweroff、init 0",
+		test: (text) => /^\s*(?:shutdown|reboot|halt|poweroff)\b|^\s*init\s+0\b/.test(text)
+	},
+	{
+		name: "放开根目录权限",
+		detail: "chmod 777 /",
+		test: (text) => /\bchmod\s+(?:-[A-Za-z]+\s+)*777\s+\/(?=\s|$)/.test(text)
+	}
+];
+/**
+* 内置强制规则的可展示版：面板直接拿它渲染，不另拄一份文案。
+* 这些规则在任何模式下都生效，用户改不了，自定义规则只能在它们之外起作用。
+*/
+const BUILTIN_RULES = {
+	deny: HARD_DENY.map((rule) => ({
+		name: rule.name,
+		detail: rule.detail
+	})),
+	protectedTree: PROTECTED_TREE,
+	protectedChild: PROTECTED_CHILD,
+	protectedNames: PROTECTED_NAMES,
+	destructive: [...DESTRUCTIVE_COMMANDS]
+};
+const READONLY_COMMANDS = /* @__PURE__ */ new Set([
+	"ls",
+	"dir",
+	"cat",
+	"head",
+	"tail",
+	"grep",
+	"rg",
+	"wc",
+	"stat",
+	"file",
+	"du",
+	"df",
+	"free",
+	"uptime",
+	"whoami",
+	"id",
+	"pwd",
+	"hostname",
+	"uname",
+	"ps",
+	"date",
+	"echo",
+	"which",
+	"whereis",
+	"ss",
+	"netstat",
+	"lsof",
+	"ping",
+	"dig",
+	"nslookup",
+	"host",
+	"tree",
+	"jq",
+	"sort",
+	"uniq",
+	"cut",
+	"tr",
+	"md5sum",
+	"sha256sum",
+	"basename",
+	"dirname",
+	"realpath",
+	"readlink",
+	"nproc",
+	"arch",
+	"lsblk",
+	"w",
+	"users",
+	"last",
+	"vmstat",
+	"iostat"
+]);
+const WRITE_ARGUMENTS = [
+	{
+		name: "sort 写文件",
+		match: /^sort\b[^|]*\s-o\b/
+	},
+	{
+		name: "uniq 写文件",
+		match: /^uniq\b\s+\S+\s+\S+/
+	},
+	{
+		name: "date 改系统时间",
+		match: /^date\b[^|]*\s-[A-Za-z]*s/
+	},
+	{
+		name: "hostname 改名",
+		match: /^hostname\s+\S/
+	},
+	{
+		name: "find 带写动作",
+		match: /^find\b[^|]*\s-(?:fprint|fprint0|fls|delete|exec|execdir|ok)\b/
+	},
+	{
+		name: "ping 洪水",
+		match: /^ping\b[^|]*\s-f\b/
+	}
+];
+const READONLY_PHRASES = [
+	/^systemctl\s+(?:status|is-active|is-enabled|is-failed|list-units|list-timers|show)\b/,
+	/^journalctl\b/,
+	/^docker\s+(?:ps|images|logs|inspect|stats|version|info)\b/,
+	/^podman\s+(?:ps|images|logs|inspect)\b/,
+	/^git\s+(?:status|log|diff|show|branch|remote|rev-parse|describe)\b/,
+	/^pm2\s+(?:list|status|logs|describe)\b/,
+	/^nginx\s+-t\b/,
+	/^mysqladmin\s+status\b/
+];
+const WRITE_MARKERS = [
+	">",
+	"<",
+	"tee ",
+	"--delete",
+	"-delete",
+	"-exec",
+	"sed -i",
+	"chmod ",
+	"chown ",
+	"$(",
+	"`",
+	"${",
+	"<<"
+];
+const SENSITIVE = [
+	/(^|\s)\.env\b/,
+	/\bid_(?:rsa|ed25519|ecdsa|dsa)\b/,
+	/\.pem\b/,
+	/\/etc\/(?:shadow|sudoers)/,
+	/\bauthorized_keys\b/
+];
+/**
+* glob 匹配：优先用 Node 内置的 path.posix.matchesGlob，取不到时退回自写实现。
+* 固定 posix 语义，Windows 上也一样：`*` 不跨 `/`，跨层级用 `**`。
+*/
+const matchesGlob = typeof posix.matchesGlob === "function" ? posix.matchesGlob : (text, pattern) => patternToRegExp(pattern).test(text);
+/** 把 glob 编译成正则，语义与 posix.matchesGlob 对齐，留给老运行时兜底。 */
+function patternToRegExp(pattern) {
+	let source = "^";
+	for (let i = 0; i < pattern.length; i += 1) {
+		const char = pattern[i];
+		const next = pattern[i + 1];
+		if (char === "*" && next === "*") {
+			if (pattern[i + 2] === "/") {
+				source += "(?:.*/)?";
+				i += 2;
+			} else {
+				source += ".*";
+				i += 1;
+			}
+		} else if (char === "*") source += "[^/]*";
+		else if (char === "?") source += "[^/]";
+		else source += char.replaceAll(/[$()*+.?[\\\]^{|}]/g, "\\$&");
+	}
+	return new RegExp(`${source}$`);
+}
+/** 把多行文本或数组统一成规则列表，空行丢掉，顺手去重。 */
+function toRules(value) {
+	const list = Array.isArray(value) ? value : String(value ?? "").split(/\r?\n/).map((item) => item.trim());
+	const rules = [];
+	for (const item of list) {
+		const rule = String(item ?? "").trim();
+		if (rule && !rules.includes(rule)) rules.push(rule);
+	}
+	return rules;
+}
+/**
+* 按顶层分隔符切段：引号、转义、括号与反引号内部的符号不算分隔。
+* 拿不准时宁可不切——切不开的那段会被当成整段判断，失败方向是更严。
+*/
+function splitSegments(command) {
+	const segments = [];
+	let buffer = "";
+	let quote = "";
+	let depth = 0;
+	let tick = false;
+	for (let i = 0; i < command.length; i += 1) {
+		const char = command[i];
+		const next = command[i + 1];
+		if (tick) {
+			buffer += char;
+			if (char === "\\") {
+				buffer += next ?? "";
+				i += 1;
+			} else if (char === "`") tick = false;
+			continue;
+		}
+		if (quote === "'") {
+			buffer += char;
+			if (char === "'") quote = "";
+			continue;
+		}
+		if (quote === "\"") {
+			buffer += char;
+			if (char === "\\") {
+				buffer += next ?? "";
+				i += 1;
+			} else if (char === "\"") quote = "";
+			continue;
+		}
+		if (char === "'" || char === "\"") {
+			quote = char;
+			buffer += char;
+			continue;
+		}
+		if (char === "\\") {
+			buffer += char + (next ?? "");
+			i += 1;
+			continue;
+		}
+		if (char === "`") {
+			tick = true;
+			buffer += char;
+			continue;
+		}
+		if (char === "(") {
+			depth += 1;
+			buffer += char;
+			continue;
+		}
+		if (char === ")") {
+			depth = Math.max(0, depth - 1);
+			buffer += char;
+			continue;
+		}
+		if (depth > 0) {
+			buffer += char;
+			continue;
+		}
+		const pair = char + (next ?? "");
+		if (pair === "&&" || pair === "||") {
+			segments.push(buffer);
+			buffer = "";
+			i += 1;
+			continue;
+		}
+		if (char === ";" || char === "|" || char === "&" || char === "\n") {
+			segments.push(buffer);
+			buffer = "";
+			continue;
+		}
+		buffer += char;
+	}
+	segments.push(buffer);
+	return segments.map((item) => item.trim()).filter(Boolean);
+}
+/** 单段是否只读：白名单命令、无写标记、不碰写参数。 */
+function isReadonlySegment(segment) {
+	if (!segment) return false;
+	if (WRITE_MARKERS.some((marker) => segment.includes(marker))) return false;
+	if (WRITE_ARGUMENTS.some((rule) => rule.match.test(segment))) return false;
+	if (READONLY_PHRASES.some((rule) => rule.test(segment))) return true;
+	return READONLY_COMMANDS.has(segment.split(/\s+/)[0]);
+}
+/** 按模式给一段命令定性；返回 null 表示这一段需要确认。 */
+function judgeByMode(segment, mode) {
+	const readonly = isReadonlySegment(segment);
+	const sensitive = SENSITIVE.some((rule) => rule.test(segment));
+	if (mode === "trusted") return {
+		decision: "allow",
+		reason: "信任模式"
+	};
+	if (sensitive) return mode === "query" ? {
+		decision: "deny",
+		reason: "查询模式不允许读凭据文件"
+	} : {
+		decision: "confirm",
+		reason: "涉及凭据文件"
+	};
+	if (readonly) return {
+		decision: "allow",
+		reason: "只读命令"
+	};
+	if (mode === "query" || mode === "readonly") return {
+		decision: "deny",
+		reason: `当前为${mode === "query" ? "查询" : "只读"}模式，这条命令可能写磁盘`
+	};
+	return {
+		decision: "confirm",
+		reason: "非只读命令"
+	};
+}
+/**
+* 给一条命令定性。
+* 返回 { decision: "allow" | "confirm" | "deny", hits: string[], pending: string[] }，
+* hits 是逐段理由（给人看），pending 只装需要确认的那几段。
+*/
+function classify(command, policy = {}) {
+	const text = String(command ?? "").trim();
+	if (!text) return {
+		decision: "deny",
+		hits: ["空命令"],
+		pending: []
+	};
+	for (const rule of HARD_DENY) if (rule.test(text)) return {
+		decision: "deny",
+		hits: [`硬拒：${rule.name}`],
+		pending: []
+	};
+	const denyRules = toRules(policy.denyGlob);
+	const allowRules = toRules(policy.allowGlob);
+	const mode = MODES.includes(policy.mode) ? policy.mode : "confirm";
+	const segments = splitSegments(text);
+	if (!segments.length) return {
+		decision: "deny",
+		hits: ["空命令"],
+		pending: []
+	};
+	const hits = [];
+	const pending = [];
+	let confirmNeeded = false;
+	for (const [index, segment] of segments.entries()) {
+		const label = `第 ${index + 1} 段「${segment.length > 60 ? `${segment.slice(0, 60)}…` : segment}」`;
+		const denied = denyRules.find((rule) => matchesGlob(segment, rule));
+		if (denied) return {
+			decision: "deny",
+			hits: [`${label}命中拒绝规则 ${denied}`],
+			pending: []
+		};
+		const allowed = allowRules.find((rule) => matchesGlob(segment, rule));
+		if (allowed) {
+			hits.push(`${label}命中放行规则 ${allowed}`);
+			continue;
+		}
+		const verdict = judgeByMode(segment, mode);
+		hits.push(`${label}${verdict.reason}`);
+		if (verdict.decision === "deny") return {
+			decision: "deny",
+			hits,
+			pending: []
+		};
+		if (verdict.decision === "confirm") {
+			confirmNeeded = true;
+			pending.push(`${label}${verdict.reason}`);
+		}
+	}
+	return {
+		decision: confirmNeeded ? "confirm" : "allow",
+		hits,
+		pending
+	};
+}
+// finchapp/remote-host/src/hosts.js
+const HOSTS_KEY = "hosts";
+const RUNS_KEY = "runs";
+const AUTH_MODES = ["key", "password"];
+const HOST_PATTERN = /^[A-Za-z0-9._:[\]-]+$/;
+const USER_PATTERN = /^[A-Za-z0-9._-]+$/;
+/** 读全部主机；数据缺失或格式坏掉时当作空清单，顺手把策略字段补齐。 */
+async function listHosts(ctx) {
+	const stored = await ctx.storage.get(HOSTS_KEY);
+	if (!Array.isArray(stored)) return [];
+	return stored.filter((item) => item && typeof item.id === "string" && typeof item.host === "string").map((item) => ({
+		...item,
+		policy: {
+			mode: MODES.includes(item.policy?.mode) ? item.policy.mode : "confirm",
+			allowGlob: toRules(item.policy?.allowGlob),
+			denyGlob: toRules(item.policy?.denyGlob)
+		}
+	}));
+}
+/** 按 id 或名称找主机；名称不区分大小写。 */
+async function findHost(ctx, key) {
+	const needle = String(key ?? "").trim().toLowerCase();
+	if (!needle) return;
+	const hosts = await listHosts(ctx);
+	return hosts.find((item) => item.id.toLowerCase() === needle) ?? hosts.find((item) => String(item.name).toLowerCase() === needle);
+}
+/** 规整并校验一条主机配置，非法值直接抛错（菜单里会原样显示）。 */
+function normalizeHost(input, previous) {
+	const name = String(input.name ?? "").trim() || previous?.name || "未命名主机";
+	const host = String(input.host ?? "").trim();
+	if (!HOST_PATTERN.test(host)) throw new Error(`地址不合法：${host || "空"}`);
+	const user = String(input.user ?? "").trim();
+	if (!USER_PATTERN.test(user)) throw new Error(`用户名不合法：${user || "空"}`);
+	const port = Number(input.port ?? previous?.port ?? 22);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`端口不合法：${input.port}`);
+	const auth = AUTH_MODES.includes(input.auth) ? input.auth : previous?.auth ?? "key";
+	let keyPath = "";
+	if (auth === "key") {
+		keyPath = String(input.keyPath ?? "").trim();
+		if (!isAbsolute(keyPath)) throw new Error("密钥必须是绝对路径");
+	}
+	const mode = MODES.includes(input.mode) ? input.mode : previous?.policy?.mode ?? "confirm";
+	return {
+		name,
+		host,
+		port,
+		user,
+		auth,
+		keyPath,
+		policy: {
+			mode,
+			allowGlob: toRules(input.allowGlob ?? input.allow ?? previous?.policy?.allowGlob),
+			denyGlob: toRules(input.denyGlob ?? input.deny ?? previous?.policy?.denyGlob)
+		}
+	};
+}
+/** 密码在 secrets 里的 key，与 manifest 声明的 host.* 前缀一致。 */
+function passwordKey(id) {
+	return `host.${id}.password`;
+}
+/** 该主机是否已存过密码。 */
+async function hasPassword(ctx, id) {
+	return await ctx.secrets.get(passwordKey(id)) !== void 0;
+}
+/** 读密码；密钥认证的主机返回 undefined。 */
+async function readPassword(ctx, id) {
+	return ctx.secrets.get(passwordKey(id));
+}
+/** 保存主机：同 id 覆盖，否则追加。密码同步写进或清出 secrets。 */
+async function saveHost(ctx, input) {
+	const hosts = await listHosts(ctx);
+	const previous = input.id ? hosts.find((item) => item.id === input.id) : void 0;
+	const record = {
+		...normalizeHost(input, previous),
+		id: previous?.id ?? randomUUID().slice(0, 8)
+	};
+	const password = String(input.password ?? "");
+	if (record.auth === "password") {
+		if (password) await ctx.secrets.set(passwordKey(record.id), password);
+		else if (!await hasPassword(ctx, record.id)) throw new Error("密码认证需要填一次密码");
+	} else await ctx.secrets.delete(passwordKey(record.id));
+	const next = previous ? hosts.map((item) => item.id === previous.id ? record : item) : [...hosts, record];
+	await ctx.storage.set(HOSTS_KEY, next);
+	return record;
+}
+/** 删除主机，连同它的最近执行记录与密码。 */
+async function removeHost(ctx, id) {
+	const hosts = await listHosts(ctx);
+	await ctx.storage.set(HOSTS_KEY, hosts.filter((item) => item.id !== id));
+	const runs = await listRuns(ctx);
+	delete runs[id];
+	await ctx.storage.set(RUNS_KEY, runs);
+	await ctx.secrets.delete(passwordKey(id));
+}
+/** 记录某台主机最近一次执行：退出码、耗时、命令摘要。 */
+async function stampRun(ctx, id, run) {
+	const runs = await listRuns(ctx);
+	runs[id] = {
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		...run
+	};
+	await ctx.storage.set(RUNS_KEY, runs);
+}
+/** 读最近执行表，缺省为空对象。 */
+async function listRuns(ctx) {
+	const runs = await ctx.storage.get(RUNS_KEY);
+	return runs && typeof runs === "object" && !Array.isArray(runs) ? runs : {};
+}
+// finchapp/remote-host/src/ssh.js
+const queues = /* @__PURE__ */ new Map();
+const HEAD_CHARS = 6e3;
+const TAIL_CHARS = 3e3;
+const SSH_FAILURE = 255;
+const CAPTURE_CHARS = 4194304;
+const REPORT_MS = 1200;
+const COMMON_ARGS = [
+	"-T",
+	"-o",
+	"StrictHostKeyChecking=accept-new",
+	"-o",
+	"ConnectTimeout=10",
+	"-o",
+	"ServerAliveInterval=30",
+	"-o",
+	"ServerAliveCountMax=4",
+	"-o",
+	"LogLevel=ERROR"
+];
+/** 定位系统 OpenSSH 客户端：Windows 用系统自带那份，其余平台交给 PATH 里的 ssh。 */
+function sshBinary() {
+	if (process.platform !== "win32") return "ssh";
+	const root = process.env.SystemRoot;
+	if (!root) throw new Error("读不到 SystemRoot，无法定位系统 ssh");
+	const file = join(root, "System32", "OpenSSH", "ssh.exe");
+	if (!existsSync(file)) throw new Error(`系统没有 OpenSSH 客户端：${file}`);
+	return file;
+}
+/**
+* askpass 助手：ssh 需要密码时执行它，它只回显环境变量。
+* 文件本身不含密码，密码通过子进程环境变量传入，用完即随进程消失。
+* Windows 是 .bat，其余平台是带可执行位的小脚本——ssh 会直接 exec 它。
+*/
+function askpassHelper(storagePath) {
+	mkdirSync(storagePath, { recursive: true });
+	const windows = process.platform === "win32";
+	const file = join(storagePath, windows ? "askpass.bat" : "askpass.sh");
+	if (!existsSync(file)) {
+		writeFileSync(file, windows ? "@echo off\r\necho %FINCH_SSH_PASS%\r\n" : "#!/bin/sh\nprintf '%s\\n' \"$FINCH_SSH_PASS\"\n", "utf8");
+		if (!windows) chmodSync(file, 448);
+	}
+	return file;
+}
+/** 按认证方式拼参数与子进程环境。 */
+function buildInvocation(host, command, { askpassPath, password }) {
+	const target = `${host.user}@${host.host}`;
+	const port = ["-p", String(host.port)];
+	if (host.auth === "password") return {
+		args: [
+			...COMMON_ARGS,
+			"-o",
+			"BatchMode=no",
+			"-o",
+			"NumberOfPasswordPrompts=1",
+			"-o",
+			"PreferredAuthentications=password,keyboard-interactive",
+			"-o",
+			"PubkeyAuthentication=no",
+			...port,
+			target,
+			command
+		],
+		env: {
+			...process.env,
+			SSH_ASKPASS: askpassPath,
+			SSH_ASKPASS_REQUIRE: "force",
+			DISPLAY: ":0",
+			FINCH_SSH_PASS: String(password ?? "")
+		}
+	};
+	return {
+		args: [
+			...COMMON_ARGS,
+			"-o",
+			"BatchMode=yes",
+			"-o",
+			"PreferredAuthentications=publickey",
+			"-i",
+			host.keyPath,
+			...port,
+			target,
+			command
+		],
+		env: process.env
+	};
+}
+/**
+* 单次执行：边跑边收集，超时或取消时杀掉本地进程。
+* `onProgress` 只在运行期间收到节流后的快照，供调用方刷进度文案。
+*/
+function execute(host, { command, timeoutMs, signal, askpassPath, password, onProgress }) {
+	const { args, env } = buildInvocation(host, command, {
+		askpassPath,
+		password
+	});
+	return new Promise((resolve, reject) => {
+		const child = spawn(sshBinary(), args, {
+			windowsHide: true,
+			env
+		});
+		const startedAt = Date.now();
+		let stdout = "";
+		let stderr = "";
+		let overflow = false;
+		let lastReport = 0;
+		let settled = false;
+		/** 只结算一次，并清掉计时器与监听。 */
+		const finish = (fn, value) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", stop);
+			fn(value);
+		};
+		/** 杀掉本地 ssh；远端会随连接断开一起结束。 */
+		const stop = () => child.kill();
+		const timer = setTimeout(() => {
+			child.kill();
+			finish(reject, /* @__PURE__ */ new Error(`命令超时（${Math.round(timeoutMs / 1e3)} 秒），已在本地中断`));
+		}, timeoutMs);
+		if (signal?.aborted) stop();
+		else signal?.addEventListener("abort", stop, { once: true });
+		/** 追加一块输出；超过上限就停下不再扩大内存。 */
+		const append = (key, chunk) => {
+			const text = String(chunk);
+			if (overflow) return;
+			if (stdout.length + stderr.length + text.length > CAPTURE_CHARS) {
+				overflow = true;
+				return;
+			}
+			if (key === "out") stdout += text;
+			else stderr += text;
+		};
+		const tick = () => {
+			const now = Date.now();
+			if (now - lastReport < REPORT_MS) return;
+			lastReport = now;
+			const all = `${stdout}\n${stderr}`.trimEnd();
+			const lines = all ? all.split("\n").length : 0;
+			const last = all ? all.split("\n").at(-1).trim().slice(0, 80) : "";
+			onProgress?.({
+				lines,
+				chars: stdout.length + stderr.length,
+				last,
+				seconds: Math.round((now - startedAt) / 1e3)
+			});
+		};
+		child.stdout.on("data", (chunk) => {
+			append("out", chunk);
+			tick();
+		});
+		child.stderr.on("data", (chunk) => {
+			append("err", chunk);
+			tick();
+		});
+		child.on("error", (error) => finish(reject, new Error(error.code === "ENOENT" ? "系统没有 OpenSSH 客户端，ssh 不在 PATH 里" : error.message)));
+		child.on("close", (code) => {
+			const output = [stdout, stderr].filter(Boolean).join("\n").trim();
+			const tail = overflow ? `${output}\n…（输出超过 ${CAPTURE_CHARS} 字符，后续已丢弃）` : output;
+			if (code === SSH_FAILURE) {
+				finish(reject, new Error(tail || "ssh 连接失败（地址、端口、密钥或密码不对）"));
+				return;
+			}
+			finish(resolve, {
+				exitCode: code ?? 0,
+				output: tail
+			});
+		});
+	});
+}
+/** 在目标主机上跑一条命令；同一台主机排队，失败不影响队列。 */
+function runRemote(host, options) {
+	const task = (queues.get(host.id) ?? Promise.resolve()).then(() => execute(host, options), () => execute(host, options));
+	queues.set(host.id, task.then(() => {}, () => {}));
+	return task;
+}
+/** 输出超长时只留头尾，并标出截掉了多少字符。 */
+function clip(text) {
+	const value = String(text ?? "");
+	if (value.length <= 9e3) return value;
+	const cut = value.length - HEAD_CHARS - TAIL_CHARS;
+	return `${value.slice(0, HEAD_CHARS)}\n…（截断 ${cut} 字符）…\n${value.slice(-3e3)}`;
+}
+// finchapp/remote-host/src/tasks.js
+const TASKS_KEY = "tasks";
+const MAX_TASKS = 50;
+/** 读全部任务，最新的在前。 */
+async function listTasks(ctx) {
+	const stored = await ctx.storage.get(TASKS_KEY);
+	if (!Array.isArray(stored)) return [];
+	return stored.filter((item) => item && typeof item.id === "string" && typeof item.pid === "number");
+}
+/** 按 id 找任务。 */
+async function findTask(ctx, id) {
+	return (await listTasks(ctx)).find((item) => item.id === id);
+}
+/** 新增一条任务记录（id 由调用方带进来），顺手把最老的记录挤掉。 */
+async function createTask(ctx, task) {
+	const tasks = await listTasks(ctx);
+	const record = {
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		...task
+	};
+	const next = [record, ...tasks].slice(0, MAX_TASKS);
+	await ctx.storage.set(TASKS_KEY, next);
+	return record;
+}
+/** 局部更新一条任务，找不到就当无事发生。 */
+async function updateTask(ctx, id, patch) {
+	const next = (await listTasks(ctx)).map((item) => item.id === id ? {
+		...item,
+		...patch
+	} : item);
+	await ctx.storage.set(TASKS_KEY, next);
+	return next.find((item) => item.id === id);
+}
+// finchapp/remote-host/src/index.js
+const ACTIONS = [
+	"hosts",
+	"exec",
+	"start",
+	"status",
+	"stop",
+	"audit"
+];
+const TIMEOUT_DEFAULT_S = 120;
+const TIMEOUT_MAX_S = 600;
+const AUDIT_MAX = 200;
+const AUDIT_PANEL = 60;
+const AUDIT_PANEL_CHARS = 2e3;
+const PROBE_COMMAND = "echo finch-ok";
+const TOOL_DESCRIPTION = `在用户已配置的远程 Linux 主机上跑命令（走本机 OpenSSH，密钥与密码两种认证都支持）。
+
+什么时候用：要读服务器上的文件、查服务状态、看日志、跑运维命令时用；本机命令用本地终端工具，不要走这里。
+
+action:
+  hosts  列主机：id、名称、用户@地址、认证方式、策略模式、上次结果。第一次动手前先调它
+  exec   前台跑一条命令（需 command），默认最多 ${TIMEOUT_DEFAULT_S} 秒
+  start  远端后台跑（需 command），立即返回任务 id；预计超过 10 分钟就用它
+  status 查后台任务：还活着吗、行数、日志尾巴、退出码；不传 taskId 就列最近任务
+  stop   停后台任务（先 TERM 再 KILL），clean=true 顺手删远端日志
+  audit  最近执行记录：命令、判定、退出码、耗时；可按 hostId 过滤
+
+主机：不传 hostId 就用输入框下方选定的那台。没有可用主机时让用户到「远程主机」面板添加，Agent 不能新增或修改主机与策略，也不要向用户索要密码或私钥。
+
+策略：判定为确认会弹卡片，用户点了才跑；返回「策略拒绝执行」表示当前模式不允许，不要换写法绕过，直接告诉用户当前模式与实际需求。
+
+输出：头 ${HEAD_CHARS} 字符 + 尾 ${TAIL_CHARS} 字符，中间截断，命令里自己过滤（tail / grep / --max-count）比事后翻更省事。`;
+/** 统一包装成功输出。 */
+function text(value) {
+	return { content: [{
+		type: "text",
+		text: value
+	}] };
+}
+/** 统一包装失败输出：告诉模型错在哪，方便它自己修正或转告用户。 */
+function fail(value) {
+	return {
+		content: [{
+			type: "text",
+			text: value
+		}],
+		isError: true
+	};
+}
+/** 策略模式的中文名。 */
+function modeLabel(mode) {
+	return {
+		query: "仅查询",
+		readonly: "只读",
+		confirm: "每次确认",
+		trusted: "完全信任"
+	}[mode] ?? mode;
+}
+/** 认证方式的中文名。 */
+function authLabel(auth) {
+	return auth === "password" ? "密码" : "密钥";
+}
+/** 时间戳压成 yyyy-mm-dd hh:mm；审计与状态行共用。 */
+function shortTime(iso) {
+	return String(iso ?? "").slice(0, 16).replace("T", " ");
+}
+/** 把主机清单渲染成模型能直接读的文本；selectedId 标记当前会话选定的那台。 */
+function renderHosts(hosts, runs, selectedId) {
+	if (!hosts.length) return "还没有配置任何主机。需要用户在「远程主机」小程序的面板里新增，Agent 无法自行添加。";
+	const lines = hosts.map((host) => {
+		const run = runs[host.id];
+		const last = run ? `；上次退出码 ${run.exitCode}，${shortTime(run.at)}` : "；还没执行过";
+		const mark = host.id === selectedId ? "（当前会话）" : "";
+		return `- ${host.name}${mark}（id: ${host.id}）${host.user}@${host.host}:${host.port}，${authLabel(host.auth)}认证，模式 ${modeLabel(host.policy.mode)}${last}`;
+	});
+	return `共 ${hosts.length} 台主机：\n${lines.join("\n")}`;
+}
+/** 把审计记录渲染成一行一条的简表。 */
+function renderAudit(rows) {
+	if (!rows.length) return "没有审计记录。";
+	return rows.map((row) => {
+		const command = String(row.command ?? "").replace(/\s+/g, " ").slice(0, 120);
+		const code = row.exitCode === null || row.exitCode === void 0 ? "-" : row.exitCode;
+		return `${shortTime(row.ts)} ${row.hostName}｜${row.decision}｜退出码 ${code}｜${command}`;
+	}).join("\n");
+}
+/** 把执行结果渲染成模型能直接读的文本。 */
+function renderResult(host, command, result, durationMs) {
+	const output = clip(result.output) || "(无输出)";
+	return [
+		`${host.name} ${host.user}@${host.host}`,
+		`$ ${command}`,
+		`退出码 ${result.exitCode}，耗时 ${(durationMs / 1e3).toFixed(1)} 秒`,
+		"---",
+		output
+	].join("\n");
+}
+/** 用单引号包住一段远端 shell 文本，单引号本身转义成 '\''。 */
+function shellQuote(value) {
+	return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+/** 后台任务在远端的三份伴生文件：输出日志、退出码、真实 worker pid。 */
+function taskPaths(id) {
+	return {
+		logPath: `/tmp/finch-${id}.log`,
+		exitPath: `/tmp/finch-${id}.exit`,
+		pidPath: `/tmp/finch-${id}.pid`
+	};
+}
+/** 进程号要大于 1 才算数：0 和 1 是内核进程，拿它们按组 kill 会出事。 */
+function validPid(value) {
+	const pid = Number(value);
+	return Number.isInteger(pid) && pid > 1 ? pid : 0;
+}
+/** 把任务状态渲染成模型能直接读的文本。 */
+function renderTask(task, state) {
+	return [
+		`任务 ${task.id}｜${task.hostName}｜${state.alive ? "运行中" : "已结束"}`,
+		[
+			`pid ${task.pid}`,
+			`日志 ${task.logPath}`,
+			state.exit === void 0 ? "" : `退出码 ${state.exit}`
+		].filter(Boolean).join("｜"),
+		`$ ${task.command}`,
+		state.tail ? `---\n${state.tail}` : ""
+	].filter(Boolean).join("\n");
+}
+function activate(ctx) {
+	/** 取文案；占位符由 ctx.i18n.t 自己插值。 */
+	const t = (key, values) => ctx.i18n.t(key, values);
+	/** 取主机密码：密钥认证返回空串。 */
+	async function passwordOf(host) {
+		return host.auth === "password" ? await readPassword(ctx, host.id) ?? "" : "";
+	}
+	/** 会话选定的主机表：{ sessionId: hostId }。 */
+	async function readSelections() {
+		const value = await ctx.storage.get("selection");
+		return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	}
+	/** 记下某个会话选定的主机；hostId 为空则清除。 */
+	async function setSelection(sessionId, hostId) {
+		if (!sessionId) return;
+		const selections = await readSelections();
+		if (hostId) selections[sessionId] = hostId;
+		else delete selections[sessionId];
+		await ctx.storage.set("selection", selections);
+	}
+	/** 某个会话当前选定的主机 id，没选过返回空串。 */
+	async function selectionOf(sessionId) {
+		if (!sessionId) return "";
+		return (await readSelections())[sessionId] ?? "";
+	}
+	/** 删除主机后把指向它的会话选择清掉，避免悬空 id。 */
+	async function forgetSelection(hostId) {
+		const selections = await readSelections();
+		let changed = false;
+		for (const [sessionId, id] of Object.entries(selections)) if (id === hostId) {
+			delete selections[sessionId];
+			changed = true;
+		}
+		if (changed) await ctx.storage.set("selection", selections);
+	}
+	/** 判定为 confirm 时弹卡片等用户点，deny 直接拦下；返回 null 表示可以继续。 */
+	async function gate(exec, host, command, verdict, entry) {
+		if (verdict.decision === "deny") {
+			record(ctx, {
+				...entry,
+				decision: "拒绝",
+				exitCode: null
+			});
+			return fail(`策略拒绝执行：${verdict.hits.join("；")}。主机「${host.name}」当前模式为${modeLabel(host.policy.mode)}。`);
+		}
+		if (verdict.decision !== "confirm") return null;
+		const form = await exec.ui.requestForm({
+			title: t("confirm.title", { host: host.name }),
+			description: t("confirm.description", {
+				target: `${host.user}@${host.host}:${host.port}`,
+				hits: (verdict.pending.length ? verdict.pending : verdict.hits).join("；"),
+				command
+			}),
+			submitLabel: t("confirm.submit"),
+			cancelLabel: t("confirm.cancel"),
+			fields: [{
+				key: "ok",
+				label: t("confirm.tick"),
+				type: "boolean",
+				required: true
+			}]
+		});
+		if (form.submitted && form.values?.ok === true) return null;
+		const background = form.reason === "background";
+		record(ctx, {
+			...entry,
+			decision: background ? "无人确认" : "取消",
+			exitCode: null
+		});
+		return fail(background ? "当前会话跑在后台，没有人能确认这条危险命令，已放弃执行。" : "用户没有确认，命令没有执行。不要重复发起同一条命令，先问清用户想做什么。");
+	}
+	/** 在目标主机上执行一条命令：先定性，再决定直接跑、等确认还是拒绝。 */
+	async function runExec(input, exec) {
+		const key = input.hostId || await selectionOf(exec.sessionId);
+		if (!key) return fail("没指定主机，当前会话也没选。让用户在输入框下方的「远程主机」里选一台，或调 hosts 看已配置的主机。");
+		const host = await findHost(ctx, key);
+		if (!host) return fail(`没有主机「${key}」。先调 hosts 看已配置的主机；新增主机只能由用户在面板里操作。`);
+		const command = String(input.command ?? "").trim();
+		if (!command) return fail("command 不能为空。");
+		const password = await passwordOf(host);
+		if (host.auth === "password" && !password) return fail(`主机「${host.name}」用密码认证，但还没存密码，请用户到面板里补上。`);
+		const verdict = classify(command, host.policy);
+		const entry = {
+			hostId: host.id,
+			hostName: host.name,
+			target: `${host.user}@${host.host}:${host.port}`,
+			auth: host.auth,
+			sessionId: exec.sessionId,
+			toolCallId: exec.toolCallId,
+			command,
+			hits: verdict.hits
+		};
+		const blocked = await gate(exec, host, command, verdict, entry);
+		if (blocked) return blocked;
+		const timeoutSeconds = Math.min(Math.max(Number(input.timeoutSeconds) || TIMEOUT_DEFAULT_S, 1), TIMEOUT_MAX_S);
+		exec.progress.report({
+			stage: "running",
+			message: t("progress.running", { host: host.name })
+		});
+		const started = Date.now();
+		try {
+			const result = await runRemote(host, {
+				command,
+				timeoutMs: timeoutSeconds * 1e3,
+				signal: exec.signal,
+				askpassPath: askpassHelper(ctx.storagePath),
+				password,
+				onProgress: ({ lines, last, seconds }) => exec.progress.report({
+					stage: "running",
+					message: t("progress.streaming", {
+						host: host.name,
+						seconds,
+						lines,
+						last: last || t("progress.waiting")
+					})
+				})
+			});
+			const durationMs = Date.now() - started;
+			record(ctx, {
+				...entry,
+				decision: verdict.decision === "confirm" ? "确认后执行" : "直接执行",
+				exitCode: result.exitCode,
+				durationMs,
+				output: result.output
+			});
+			await stampRun(ctx, host.id, {
+				exitCode: result.exitCode,
+				durationMs,
+				command: command.slice(0, 120)
+			});
+			return text(renderResult(host, command, result, durationMs));
+		} catch (error) {
+			const durationMs = Date.now() - started;
+			const message = error instanceof Error ? error.message : String(error);
+			record(ctx, {
+				...entry,
+				decision: "失败",
+				exitCode: null,
+				durationMs,
+				output: message
+			});
+			return fail(`执行失败：${message}${message.includes("超时") ? `。更久的命令改用 action=start 起后台任务，或者把 timeoutSeconds 调大（上限 ${TIMEOUT_MAX_S}）。` : ""}`);
+		}
+	}
+	/** 起一个受管后台任务：远端脱离会话跑，pid、日志、退出码都记下来。 */
+	async function startTask(input, exec) {
+		const key = input.hostId || await selectionOf(exec.sessionId);
+		if (!key) return fail("没指定主机，当前会话也没选。让用户在输入框下方的「远程主机」里选一台。");
+		const host = await findHost(ctx, key);
+		if (!host) return fail(`没有主机「${key}」。先调 hosts 看已配置的主机。`);
+		const command = String(input.command ?? "").trim();
+		if (!command) return fail("command 不能为空。");
+		const password = await passwordOf(host);
+		if (host.auth === "password" && !password) return fail(`主机「${host.name}」还没存密码，请用户到面板里补上。`);
+		const verdict = classify(command, host.policy);
+		const entry = {
+			hostId: host.id,
+			hostName: host.name,
+			target: `${host.user}@${host.host}:${host.port}`,
+			auth: host.auth,
+			sessionId: exec.sessionId,
+			toolCallId: exec.toolCallId,
+			command,
+			hits: verdict.hits
+		};
+		const blocked = await gate(exec, host, command, verdict, entry);
+		if (blocked) return blocked;
+		const id = randomUUID().slice(0, 8);
+		const { logPath, exitPath, pidPath } = taskPaths(id);
+		const launch = `rm -f ${pidPath} ${exitPath}; if command -v setsid >/dev/null 2>&1; then SET=setsid; else SET=; fi; $SET sh -c ${shellQuote(`echo $$ > ${pidPath}; ${command}; echo $? > ${exitPath}`)} > ${logPath} 2>&1 < /dev/null & i=0; while [ $i -lt 25 ] && [ ! -s ${pidPath} ]; do sleep 0.2; i=$((i+1)); done; cat ${pidPath} 2>/dev/null`;
+		try {
+			const result = await runRemote(host, {
+				command: launch,
+				timeoutMs: 2e4,
+				signal: exec.signal,
+				askpassPath: askpassHelper(ctx.storagePath),
+				password
+			});
+			const pid = Number(result.output.trim().split("\n").at(-1)?.trim());
+			if (!Number.isInteger(pid) || pid <= 1) return fail(`启动失败，远端没有返回有效进程号：${clip(result.output) || "(空)"}`);
+			const task = await createTask(ctx, {
+				id,
+				hostId: host.id,
+				hostName: host.name,
+				target: `${host.user}@${host.host}`,
+				command,
+				pid,
+				logPath,
+				exitPath,
+				pidPath,
+				sessionId: exec.sessionId,
+				alive: true
+			});
+			record(ctx, {
+				...entry,
+				decision: "后台启动",
+				exitCode: null,
+				output: `pid=${pid}`
+			});
+			return text([
+				`后台任务 ${task.id} 已启动，pid ${pid}`,
+				`日志 ${logPath}`,
+				`接着用 action=status taskId=${task.id} 看进度，action=stop taskId=${task.id} 收尾。`
+			].join("\n"));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			record(ctx, {
+				...entry,
+				decision: "后台启动失败",
+				exitCode: null,
+				output: message
+			});
+			return fail(`启动失败：${message}`);
+		}
+	}
+	/** 探一次任务状态：活着吗、多少行、日志尾巴、退出码。 */
+	async function probeTask(task) {
+		const host = await findHost(ctx, task.hostId);
+		if (!host) return {
+			alive: false,
+			tail: "主机已删除"
+		};
+		const pid = validPid(task.pid);
+		if (!pid) return {
+			alive: false,
+			tail: "进程号无效，按已结束处理"
+		};
+		const output = (await runRemote(host, {
+			command: `sh -c ${shellQuote([
+				`P=${pid}`,
+				`if [ -n "$(ps -o pid= -g $P 2>/dev/null)" ] || kill -0 $P 2>/dev/null; then echo ALIVE; else echo DEAD; fi`,
+				`[ -f ${task.exitPath} ] && echo "EXIT=$(cat ${task.exitPath})"`,
+				`[ -f ${task.logPath} ] && echo "LINES=$(wc -l < ${task.logPath})" && echo --- && tail -n 20 ${task.logPath}`,
+				"exit 0"
+			].join("; "))}`,
+			timeoutMs: 2e4,
+			askpassPath: askpassHelper(ctx.storagePath),
+			password: await passwordOf(host)
+		})).output;
+		const exit = /EXIT=(-?\d+)/.exec(output)?.[1];
+		const marker = output.indexOf("---");
+		return {
+			alive: output.includes("ALIVE"),
+			exit: exit === void 0 ? void 0 : Number(exit),
+			tail: marker !== -1 ? output.slice(marker + 3).trim() : ""
+		};
+	}
+	/** 查任务：给 id 就探活取尾巴，不给就列最近的几个。 */
+	async function taskStatus(input) {
+		const tasks = await listTasks(ctx);
+		if (!input.taskId) {
+			if (!tasks.length) return text("没有后台任务。用 action=start 起一个。");
+			const lines = tasks.slice(0, 10).map((task) => `- ${task.id}｜${task.hostName}｜${shortTime(task.startedAt)}｜${task.command.replace(/\s+/g, " ").slice(0, 80)}`);
+			return text(`最近 ${lines.length} 个后台任务：\n${lines.join("\n")}\n单个任务详情：action=status taskId=<id>`);
+		}
+		const task = tasks.find((item) => item.id === input.taskId);
+		if (!task) return fail(`没有任务「${input.taskId}」。action=status 不带 taskId 可以看列表。`);
+		try {
+			const state = await probeTask(task);
+			const patch = {
+				alive: state.alive,
+				exitCode: state.exit ?? task.exitCode ?? null
+			};
+			if (!state.alive) patch.finishedAt = task.finishedAt ?? (/* @__PURE__ */ new Date()).toISOString();
+			await updateTask(ctx, task.id, patch);
+			return text(renderTask({
+				...task,
+				...patch
+			}, state));
+		} catch (error) {
+			return fail(`查不到任务 ${task.id}：${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	/** 停任务：先 TERM 整个进程组，1 秒后还在就 KILL，可顺手删远端文件。 */
+	async function stopTask(input, exec) {
+		const task = await findTask(ctx, String(input.taskId ?? ""));
+		if (!task) return fail(`没有任务「${input.taskId ?? ""}」。`);
+		const host = await findHost(ctx, task.hostId);
+		if (!host) return fail(`任务 ${task.id} 的主机已删除，无法停止。`);
+		const pid = validPid(task.pid);
+		if (!pid) return fail(`任务 ${task.id} 的进程号无效，不能停。`);
+		const script = [
+			`P=${pid}`,
+			`kill -TERM -- -$P 2>/dev/null || kill -TERM $P 2>/dev/null`,
+			`for c in $(ps -o pid= -g $P 2>/dev/null); do kill -TERM $c 2>/dev/null; done`,
+			"sleep 1",
+			`for c in $(ps -o pid= -g $P 2>/dev/null); do kill -KILL $c 2>/dev/null; done`,
+			"sleep 1",
+			`if [ -n "$(ps -o pid= -g $P 2>/dev/null)" ]; then echo ALIVE; else echo DEAD; fi`,
+			input.clean ? `rm -f ${task.logPath} ${task.exitPath} ${task.pidPath ?? ""}` : "",
+			"exit 0"
+		].filter(Boolean).join("; ");
+		try {
+			const result = await runRemote(host, {
+				command: `sh -c ${shellQuote(script)}`,
+				timeoutMs: 2e4,
+				signal: exec.signal,
+				askpassPath: askpassHelper(ctx.storagePath),
+				password: await passwordOf(host)
+			});
+			const alive = result.output.includes("ALIVE");
+			await updateTask(ctx, task.id, {
+				alive,
+				stoppedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			record(ctx, {
+				hostId: host.id,
+				hostName: host.name,
+				target: `${host.user}@${host.host}`,
+				sessionId: exec.sessionId,
+				toolCallId: exec.toolCallId,
+				command: `stop ${task.id}`,
+				decision: "停止任务",
+				exitCode: null,
+				output: clip(result.output)
+			});
+			return text(alive ? `任务 ${task.id} 仍然活着，可能权限不足，需要用户到机器上手动处理。` : `任务 ${task.id} 已停止${input.clean ? "，远端日志已删" : ""}。`);
+		} catch (error) {
+			return fail(`停止失败：${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	/** 面板用的完整状态：密码只给「已存」标记，从不回传值。 */
+	async function panelState() {
+		const hosts = await listHosts(ctx);
+		const items = [];
+		for (const host of hosts) items.push({
+			id: host.id,
+			name: host.name,
+			host: host.host,
+			port: host.port,
+			user: host.user,
+			auth: host.auth,
+			keyPath: host.keyPath,
+			mode: host.policy.mode,
+			allowGlob: host.policy.allowGlob,
+			denyGlob: host.policy.denyGlob,
+			hasPassword: await hasPassword(ctx, host.id)
+		});
+		return {
+			type: "state",
+			hosts: items,
+			builtin: BUILTIN_RULES
+		};
+	}
+	/** 测试连接：真连一次，只看能不能回显。 */
+	async function testConnection(input, password) {
+		try {
+			const previous = input?.id ? await findHost(ctx, input.id) : void 0;
+			const host = normalizeHost(input ?? {}, previous);
+			const secret = String(password ?? "") || (previous ? await passwordOf(previous) : "");
+			if (host.auth === "password" && !secret) return {
+				ok: false,
+				message: t("panel.needPassword")
+			};
+			const result = await runRemote({
+				...host,
+				id: `probe-${Date.now()}`
+			}, {
+				command: PROBE_COMMAND,
+				timeoutMs: 2e4,
+				askpassPath: askpassHelper(ctx.storagePath),
+				password: secret
+			});
+			return result.output.includes("finch-ok") ? {
+				ok: true,
+				message: t("panel.testOk")
+			} : {
+				ok: false,
+				message: result.output || t("panel.testFail")
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				message: error instanceof Error ? error.message : String(error)
+			};
+		}
+	}
+	/** 处理面板发来的消息；页面只发 command，后端从不回密码。 */
+	async function onPanelMessage(panel, message) {
+		if (!message || typeof message !== "object") return;
+		try {
+			switch (message.type) {
+				case "ready":
+					await panel.postMessage(await panelState());
+					return;
+				case "save": {
+					const host = await saveHost(ctx, {
+						...message.host,
+						password: message.password
+					});
+					await panel.postMessage({
+						type: "saved",
+						id: host.id
+					});
+					await panel.postMessage(await panelState());
+					return;
+				}
+				case "remove":
+					await removeHost(ctx, message.id);
+					await forgetSelection(message.id);
+					await panel.postMessage(await panelState());
+					return;
+				case "test":
+					await panel.postMessage({
+						type: "tested",
+						...await testConnection(message.host, message.password)
+					});
+					return;
+				case "preview":
+					await panel.postMessage({
+						type: "preview",
+						...classify(message.command, {
+							mode: message.mode,
+							allowGlob: message.allowGlob,
+							denyGlob: message.denyGlob
+						})
+					});
+					return;
+				case "audit": {
+					const rows = recent(ctx, {
+						hostId: message.hostId,
+						limit: AUDIT_PANEL
+					}).map((row) => ({
+						ts: row.ts,
+						command: row.command,
+						decision: row.decision ?? "",
+						exitCode: row.exitCode ?? null,
+						hits: row.hits ?? [],
+						output: String(row.output ?? "").slice(0, AUDIT_PANEL_CHARS)
+					}));
+					await panel.postMessage({
+						type: "audit",
+						rows
+					});
+					return;
+				}
+				case "clearAudit":
+					clearHost(ctx, message.hostId);
+					await panel.postMessage({
+						type: "audit",
+						rows: []
+					});
+					return;
+				default: return;
+			}
+		} catch (error) {
+			await panel.postMessage({
+				type: "error",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+	/** 打开主机面板；带 id 时直接选中那台主机。 */
+	async function openPanel(selectId) {
+		await ctx.ui.createPanel({
+			instanceMode: "single",
+			payload: { selectId: selectId ?? null }
+		});
+	}
+	/** 设置菜单：状态行在上，可点操作在下，主机行点开即定位到面板里的那台。 */
+	async function getMenu() {
+		const hosts = await listHosts(ctx);
+		const runs = await listRuns(ctx);
+		const items = [{
+			id: "count",
+			label: hosts.length ? t("menu.count", { count: hosts.length }) : t("menu.empty"),
+			iconName: "square-terminal",
+			disabled: true
+		}];
+		for (const host of hosts) {
+			const run = runs[host.id];
+			items.push({
+				id: `open:${host.id}`,
+				label: `${host.name} · ${host.user}@${host.host}`,
+				description: run ? `${modeLabel(host.policy.mode)} · ${run.exitCode === 0 ? t("menu.ok") : t("menu.failed", { code: run.exitCode })}` : modeLabel(host.policy.mode),
+				iconName: "square-terminal"
+			});
+		}
+		items.push({
+			id: "divider",
+			label: "",
+			separator: true
+		});
+		items.push({
+			id: "panel",
+			label: t("menu.panel"),
+			iconName: "settings"
+		});
+		return items;
+	}
+	/** 菜单点击：主机行与面板都在同一个面板里定位。 */
+	async function executeMenu(_context, itemId) {
+		if (itemId === "panel") return openPanel();
+		if (itemId.startsWith("open:")) return openPanel(itemId.slice(5));
+	}
+	ctx.subscriptions.push(ctx.tools.register({
+		name: "remote_host",
+		title: "远程主机",
+		description: TOOL_DESCRIPTION,
+		inputSchema: {
+			type: "object",
+			properties: {
+				action: {
+					type: "string",
+					enum: ACTIONS,
+					description: "要做的动作，各动作适用范围见上面 action 列表"
+				},
+				hostId: {
+					type: "string",
+					description: "主机 id 或名称；不传就用当前会话在输入框下方选定的那台"
+				},
+				command: {
+					type: "string",
+					description: "exec 与 start 必填：一条 shell 命令，可以带管道与 &&"
+				},
+				taskId: {
+					type: "string",
+					description: "status 与 stop 必填：start 返回的任务 id"
+				},
+				clean: {
+					type: "boolean",
+					description: "stop 用：true 时顺手删掉远端日志与退出文件"
+				},
+				timeoutSeconds: {
+					type: "number",
+					description: `exec 用：命令超时秒数，默认 ${TIMEOUT_DEFAULT_S}，最大 ${TIMEOUT_MAX_S}；到点本地中断`
+				},
+				limit: {
+					type: "number",
+					description: `audit 用：返回条数，默认 20，最大 ${AUDIT_MAX}`
+				}
+			},
+			required: ["action"]
+		},
+		risk: "high",
+		timeoutMs: 66e4,
+		async execute(input, exec) {
+			switch (input.action) {
+				case "hosts": return text(renderHosts(await listHosts(ctx), await listRuns(ctx), await selectionOf(exec.sessionId)));
+				case "audit": {
+					const limit = Math.min(Math.max(Number(input.limit) || 20, 1), AUDIT_MAX);
+					return text(renderAudit(recent(ctx, {
+						hostId: input.hostId,
+						limit
+					})));
+				}
+				case "exec": return runExec(input, exec);
+				case "start": return startTask(input, exec);
+				case "status": return taskStatus(input);
+				case "stop": return stopTask(input, exec);
+				default: return fail(`未知 action：${input.action}，可用值：${ACTIONS.join(" / ")}`);
+			}
+		}
+	}));
+	ctx.subscriptions.push(ctx.settingsMenu.register({
+		getMenu,
+		execute: executeMenu
+	}));
+	const hostAction = ctx.composerActions.register("host", {
+		/** 徽标直接显示选中的主机名。 */
+		async getBadge({ sessionId, surface }) {
+			if (surface !== "session" || !sessionId) return;
+			const host = await findHost(ctx, await selectionOf(sessionId));
+			return host ? {
+				text: host.name,
+				active: true
+			} : { text: t("badge.pick") };
+		},
+		/** 菜单：一台主机一行，当前那台打勾，末尾是面板入口。 */
+		async getMenu({ sessionId }) {
+			const hosts = await listHosts(ctx);
+			const current = await selectionOf(sessionId);
+			if (!hosts.length) return [{
+				id: "no-hosts",
+				label: t("menu.noHosts"),
+				iconName: "square-terminal",
+				disabled: true
+			}, {
+				id: "panel",
+				label: t("menu.panel"),
+				iconName: "settings"
+			}];
+			const items = hosts.map((host) => ({
+				id: `host:${host.id}`,
+				label: host.name,
+				description: `${host.user}@${host.host} · ${modeLabel(host.policy.mode)}`,
+				iconName: "square-terminal",
+				current: host.id === current
+			}));
+			items.push({
+				id: "composer-divider",
+				label: "",
+				separator: true
+			});
+			if (current) items.push({
+				id: "clear",
+				label: t("menu.clear"),
+				iconName: "toggle-left"
+			});
+			items.push({
+				id: "panel",
+				label: t("menu.panel"),
+				iconName: "settings"
+			});
+			return items;
+		},
+		/** 点选就记到当前会话上，徽标跟着刷新。 */
+		async execute({ sessionId }, itemId) {
+			if (itemId === "panel") {
+				await openPanel();
+				return;
+			}
+			if (itemId === "clear") {
+				await setSelection(sessionId, "");
+				hostAction.notifyUpdate();
+				return;
+			}
+			if (itemId.startsWith("host:")) {
+				await setSelection(sessionId, itemId.slice(5));
+				hostAction.notifyUpdate();
+			}
+		},
+		/** 每轮把选定主机告诉模型，省得它反复猜或每次都要 hostId。 */
+		async getReminder({ sessionId, surface }) {
+			if (surface !== "session" || !sessionId) return;
+			const host = await findHost(ctx, await selectionOf(sessionId));
+			if (!host) return;
+			return `当前会话选定的远程主机是「${host.name}」（id: ${host.id}，${host.user}@${host.host}:${host.port}）。用户说「这台机器」时指它，remote_host 的 exec 可以不传 hostId。`;
+		}
+	});
+	ctx.subscriptions.push(hostAction);
+	ctx.subscriptions.push(ctx.ui.onDidOpenPanel((panel) => {
+		const subscription = panel.onDidReceiveMessage((message) => onPanelMessage(panel, message));
+		if (subscription) ctx.subscriptions.push(subscription);
+	}));
+}
+function deactivate() {}
+export { activate, deactivate };