dsh-remote-bridge 2.3.7 → 2.4.0

package/lib/index.js

@@ -1,5 +1,6 @@
 import path, { join } from "node:path";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { execFile, spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
@@ -132,6 +133,581 @@ function isLoopbackOrigin(origin) {
 	}
 }
 //#endregion
+//#region src/host/cloudflared.ts
+/** 平台/架构 -> cloudflared 归档后缀。 */
+function archSuffix(platform = process.platform) {
+	if (platform !== "linux") throw new Error(`cloudflared 尚不支持 ${platform} 平台。`);
+	switch (process.arch) {
+		case "x64": return "linux-amd64";
+		case "arm64": return "linux-arm64";
+		default: throw new Error(`cloudflared 尚不支持 ${process.arch} 架构。`);
+	}
+}
+const OFFICIAL_BASE = `https://github.com/cloudflare/cloudflared/releases/download/2024.11.1/cloudflared-`;
+/**
+* 官方 deb 兜底仓库（GitHub 被墙时回退）。
+* `pkg.cloudflare.com` 是 Cloudflare 官方仓库，实测在 GitHub 直连被墙的机器上可达可用
+* （见 PITFALLS §国内下载 cloudflared 必须择源）。版本比 GitHub 默认新（2026.10.1），
+* 仅在官方 GitHub 失败时兜底，不改变「默认先 GitHub」的语义。
+*/
+const DEB_FALLBACK_URL = "https://pkg.cloudflare.com/cloudflared/pool/main/c/cloudflared/cloudflared_2026.10.1_amd64.deb";
+async function downloadHttps(url, ms, onProgress) {
+	const mod = url.startsWith("http:") ? await import("node:http") : await import("node:https");
+	return await new Promise((resolve, reject) => {
+		const req = mod.get(url, { headers: { "User-Agent": "dsh-remote-bridge" } }, (response) => {
+			clearTimeout(timer);
+			const total = Number(response.headers["content-length"] ?? -1);
+			const chunks = [];
+			let received = 0;
+			response.on("data", (c) => {
+				const buf = c;
+				chunks.push(buf);
+				received += buf.length;
+				onProgress?.(received, total);
+			});
+			response.on("error", (cause) => reject(/* @__PURE__ */ new Error(`下载中止：${url}（${cause.message}）`)));
+			response.on("end", () => {
+				resolve({
+					ok: statusOk(response.statusCode),
+					status: response.statusCode ?? 0,
+					body: Buffer.concat(chunks)
+				});
+			});
+		});
+		const timer = setTimeout(() => {
+			req.destroy(ms < Number.POSITIVE_INFINITY ? /* @__PURE__ */ new Error(`连接${ms}ms无响应：${url}`) : void 0);
+		}, ms);
+		req.on("error", (cause) => reject(/* @__PURE__ */ new Error(`下载失败：${url}（${cause.message}）`)));
+		req.on("close", () => clearTimeout(timer));
+	});
+}
+function statusOk(code) {
+	return typeof code === "number" && code >= 200 && code < 300;
+}
+/** 环境变量注入的下载源配置；空则回退官方。 */
+function mirrorBase() {
+	return process.env.CLOUDFLARED_MIRROR?.trim() ?? "";
+}
+/**
+* 判定当前下载源是否为「Deb 仓库」。用 `deb+` 前缀声明：后续拼一个 `https://...deb` 完整地址。
+* 例：`CLOUDFLARED_MIRROR=deb+https://pkg.cloudflare.com/cloudflared/pool/main/c/cloudflared/cloudflared_2026.10.1_amd64.deb`
+* 与「裸二进制基址」镜像（拼 `cloudflared-linux-amd64`）区分开。
+*/
+function isDebSource() {
+	return mirrorBase().startsWith("deb+");
+}
+/** 返回要下载的源 URL：deb 源返回完整 .deb 地址；裸镜像基址拼架构后缀；否则官方 GitHub。 */
+function downloadUrlFor() {
+	const suffix = archSuffix();
+	const mirror = mirrorBase();
+	if (mirror === "") return `${OFFICIAL_BASE}${suffix}`;
+	if (mirror.startsWith("deb+")) return mirror.slice(4);
+	return `${mirror}${suffix}`;
+}
+/** 从进程输出文本提取 `trycloudflare.com` 地址；找不到返回 null。 */
+function extractQuickTunnelUrl(text) {
+	const match = /https:\/\/([a-z0-9-]+\.trycloudflare\.com)/i.exec(text);
+	return match?.[1] ? `https://${match[1]}` : null;
+}
+/**
+* 确保 cloudflared 可执行文件就位：先看 `dataDir/cloudflared` 是否已存在，否则下载。
+* 返回可执行文件绝对路径。
+*
+* 下载失败会把错误抛给调用方（router -> 面板可见），不会把半个文件当「已就位」——
+* 用临时文件 + rename 原子落盘。
+*
+* @param report 可选进度上报：下载/解包过程各阶段推进时回调（前端据此渲染进度条）。
+*/
+async function ensureCloudflared(dataDir, report) {
+	const existing = path.join(dataDir, "cloudflared");
+	report?.({
+		stage: "locating",
+		label: "定位本机二进制…",
+		percent: null
+	});
+	try {
+		if ((await stat(existing)).isFile()) {
+			report?.({
+				stage: "locating",
+				label: "已找到本机二进制，直接复用",
+				percent: 100
+			});
+			return existing;
+		}
+	} catch {}
+	await mkdir(dataDir, { recursive: true });
+	const candidates = mirrorBase() !== "" ? [{
+		url: downloadUrlFor(),
+		deb: isDebSource()
+	}] : [{
+		url: downloadUrlFor(),
+		deb: false
+	}, {
+		url: DEB_FALLBACK_URL,
+		deb: true
+	}];
+	const errors = [];
+	for (const { url, deb } of candidates) {
+		report?.({
+			stage: "downloading",
+			label: `正在下载 cloudflared（${deb ? "官方 deb 仓库" : "官方 GitHub"}）…`,
+			percent: null
+		});
+		try {
+			const res = await downloadHttps(url, 15e3, (received, total) => {
+				const percent = total > 0 ? Math.min(99, Math.round(received / total * 100)) : null;
+				if (percent !== null) {
+					const mb = (received / 1024 / 1024).toFixed(1);
+					const all = (total / 1024 / 1024).toFixed(1);
+					report?.({
+						stage: "downloading",
+						label: `正在下载 cloudflared… ${mb}/${all} MB`,
+						percent
+					});
+				}
+			});
+			if (!res.ok) {
+				errors.push(`HTTP ${res.status}`);
+				continue;
+			}
+			if (deb) {
+				report?.({
+					stage: "unpacking",
+					label: "解包官方 deb 并提取二进制…",
+					percent: null
+				});
+				return writeFromDeb(dataDir, res.body, url);
+			}
+			report?.({
+				stage: "unpacking",
+				label: "写入二进制并赋予执行权限…",
+				percent: null
+			});
+			const tmp = path.join(dataDir, `.cloudflared.tmp-${process.pid}`);
+			await writeFile(tmp, res.body);
+			await chmod(tmp, 493);
+			await rename(tmp, existing);
+			return existing;
+		} catch (cause) {
+			errors.push(cause instanceof Error ? cause.message : String(cause));
+		}
+	}
+	const tried = candidates.map((c) => c.url).join("\n  ");
+	throw new Error(`下载 cloudflared 失败：\n  ${tried}\n原因：${errors.join("；")}`);
+}
+/**
+* 从 `.deb` 包字节中提取 `usr/bin/cloudflared`，原子落到 `dataDir/cloudflared`。
+* 不调用系统 `dpkg -i`（避免污染包数据库），只做解包 + 提取。
+*/
+async function writeFromDeb(dataDir, debBuffer, url) {
+	await mkdir(dataDir, { recursive: true });
+	const debPath = path.join(dataDir, `.cloudflared.deb-${process.pid}`);
+	const extractDir = path.join(dataDir, `.cloudflared-extract-${process.pid}`);
+	await writeFile(debPath, debBuffer);
+	await mkdir(extractDir, { recursive: true });
+	try {
+		await new Promise((resolve, reject) => {
+			execFile("dpkg-deb", [
+				"-x",
+				debPath,
+				extractDir
+			], (err) => err ? reject(err) : resolve());
+		});
+		const inner = path.join(extractDir, "usr", "bin", "cloudflared");
+		const out = path.join(dataDir, "cloudflared");
+		const bin = await readFile(inner);
+		await writeFile(out, bin);
+		await chmod(out, 493);
+		return out;
+	} finally {
+		await rm(debPath, { force: true }).catch(() => {});
+		await rm(extractDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/** 一次 cloudflared 子进程生命周期 + 对外状态机。 */
+var CloudflaredTunnelManager = class {
+	process = null;
+	url = null;
+	channel = null;
+	errorText = void 0;
+	listeners = [];
+	activity = {
+		stage: "idle",
+		label: "",
+		percent: null
+	};
+	/** 当前进行中任务的阶段进度（无任务时 stage 为 idle）。 */
+	get activityState() {
+		return this.activity;
+	}
+	/** 上报一条阶段进度（前端轮询 /cloudflare/activity 可见）。 */
+	reportActivity(a) {
+		this.activity = a;
+		this.emit();
+	}
+	/** 任务结束（成功或失败）时清空进行中进度。 */
+	clearActivity() {
+		this.activity = {
+			stage: "idle",
+			label: "",
+			percent: null
+		};
+		this.emit();
+	}
+	get publicState() {
+		return {
+			channel: this.channel,
+			url: this.url,
+			running: this.process !== null && !this.process.killed,
+			...this.errorText === void 0 ? {} : { error: this.errorText }
+		};
+	}
+	/** 订阅状态变化；返回取消函数。 */
+	onStatus(cb) {
+		this.listeners.push(cb);
+		return () => {
+			this.listeners = this.listeners.filter((fn) => fn !== cb);
+		};
+	}
+	emit() {
+		for (const fn of this.listeners) fn();
+	}
+	setError(message) {
+		this.errorText = message;
+		this.emit();
+	}
+	/**
+	* 启动一次 Quick Tunnel。
+	* @param exe cloudflared 可执行文件路径（来自 [ensureCloudflared]）
+	* @param port bridge 监听端口，cloudflared 把外网请求转发到 localhost:port
+	*/
+	async startQuick(exe, port) {
+		if (this.process !== null && !this.process.killed) throw new Error("隧道已经在运行中，请先停止。");
+		this.errorText = void 0;
+		this.reportActivity({
+			stage: "starting",
+			label: "正在启动 cloudflared 隧道…",
+			percent: null
+		});
+		const child = spawn(exe, [
+			"tunnel",
+			"--url",
+			`http://127.0.0.1:${port}`,
+			"--no-autoupdate"
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		this.process = child;
+		this.channel = "quick";
+		this.emit();
+		const onData = (buf) => {
+			const found = extractQuickTunnelUrl(buf.toString("utf8"));
+			if (found !== null && this.url === null) {
+				this.url = found;
+				this.clearActivity();
+				this.emit();
+			}
+		};
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+		child.on("exit", (code, signal) => {
+			const wasThis = this.process === child;
+			this.process = null;
+			this.channel = null;
+			this.emit();
+			if (wasThis) {
+				if (this.url === null) this.setError(`cloudflared 退出（code=${code ?? "?"}, signal=${signal ?? "?"}），未拿到隧道地址。`);
+				this.url = null;
+				if (this.channel === null) this.clearActivity();
+			}
+		});
+		return this.publicState;
+	}
+	/** 停止当前隧道。 */
+	stop() {
+		const child = this.process;
+		if (child !== null && !child.killed) child.kill("SIGTERM");
+		this.process = null;
+		this.channel = null;
+		this.url = null;
+		this.emit();
+		return this.publicState;
+	}
+	/** 注入已抓到的地址 + 通道（命名隧道用）。 */
+	setNamed(url) {
+		this.url = url;
+		this.channel = "named";
+		this.emit();
+		return this.publicState;
+	}
+};
+//#endregion
+//#region src/shared/version.ts
+const PLUGIN_VERSION = "2.4.0";
+//#endregion
+//#region src/host/capabilities.ts
+/**
+* 桥的**能力位**：这个服务端能做哪些事，由服务端自己声明。
+*
+* ## 为什么要有它（而不是让客户端比版本号）
+*
+* 先说清一件事：README 里那句「要求 bridge ≥ 2.3.7」是给**用户**看的安装门槛，
+* 而客户端**代码里并没有**版本比较、也没有处理 `connection.ready`（已核实）。
+* 于是服务端能力不足时，手机端只会「静默少一个功能」—— 审批卡片不弹，
+* 看起来与「本来就没有待审批」一模一样（这个坑踩过两次，根因都在插件侧）。
+* 这份清单要解决的正是它：让客户端能把「服务端不支持」与「本来就没有待办」分开。
+*
+* 顺带说清为什么版本号不适合当判据 —— 它有两个毛病：
+*
+* 1. **粒度太粗**：一个版本里加了五件事，客户端只能整包接受或整包拒绝；
+* 2. **方向错了**：能不能用取决于「服务端现在提供什么」，而版本号只是它的历史编号。
+*    服务端完全可能在同一版本里因为配置原因关掉某个能力（比如文件下载开关）。
+*
+* 所以 `connection.ready` 会带上这份清单，客户端可以按**能力位**做特性探测。
+* 版本号仍然保留（诊断与日志要用），但不再是唯一的兼容判据。
+*
+* ## 两类用途（别把第二类当死代码删掉）
+*
+* 这份清单同时服务两个目的，**同一项能力位对它们意味着不同的事**：
+*
+* 1. **我方客户端的分支判据** —— 目前只有 3 项：
+*    `approvals-v1` / `questions-v1`（`dsh-companion` 的 `REQUIRED_CAPABILITIES`：
+*    缺了就明说「插件过旧、卡片不会出现」）与 `session-archive-list-v1`
+*    （决定会话面板是否显示「已归档」入口）。
+* 2. **对外声明** —— 其余 23 项。它们回答的是「这台服务端能做什么」，
+*    **服务的是任何客户端（包括第三方）**，而不是某一处分支。
+*
+* 所以：**「我方客户端没用到」不等于「没人用」**。删掉第 2 类会破坏对外承诺
+* （而且第 1 类里那两个名字一旦消失，客户端会对**所有用户**误报插件过旧 ——
+* `tests/capabilities.spec.ts` 因此专门钉住了它们）。
+*
+* 反过来，**加位要克制**：只有当「客户端可能需要据此分支」或「这是一个稳定的对外能力面」时才加。
+* 服务端加端点/事件时应当同步考虑加位（它是对外契约的一部分），但不要为一次性的内部改动加位。
+*
+* ## 纪律（加之前先读）
+*
+* - 能力位是**对外承诺**：加了就不能悄悄撤（客户端可能已经按它分支），
+*   要撤必须发新的能力位并把旧的标成 deprecated。
+* - 命名固定为 `<能力>-v<主版本>`；语义变更（不是新增字段，而是改变既有字段含义）
+*   要升 `-v2`，不能原地改 `-v1` 的含义。
+* - **加能力位必须能在契约里指出依据**：一个 OpenAPI 路径 + 方法，或一个 AsyncAPI 事件。
+*   `tests/capabilities.spec.ts` 会拿这份依据去 `docs/api/openapi.yaml` 里逐条核对 ——
+*   声明与契约文件绑死，避免「文档说支持、契约里没有」。
+* - 只声明**已经稳定**的东西：还在改的接口先别进来（宁可客户端探测不到而走老路）。
+*/
+const BRIDGE_CAPABILITIES = [
+	"device-pairing-v1",
+	"file-browse-v1",
+	"file-write-v1",
+	"file-trash-v1",
+	"session-list-v1",
+	"session-rename-v1",
+	"session-fork-v1",
+	"session-archive-v1",
+	"session-archive-list-v1",
+	"history-v1",
+	"turn-cancel-v1",
+	"session-config-v1",
+	"commands-v1",
+	"agent-presets-v1",
+	"workspace-list-v1",
+	"workspace-manage-v1",
+	"provider-settings-v1",
+	"model-catalog-v1",
+	"plugin-inventory-v1",
+	"plugin-toggle-v1",
+	"approvals-v1",
+	"questions-v1",
+	"turn-failure-v1",
+	"history-byte-budget-v1",
+	"interaction-replay-v1",
+	"session-snapshot-v1"
+];
+/**
+* `connection.ready` 事件的载荷。
+*
+* 每次调用返回**新的副本**：调用方（或测试）改它不该影响常量，
+* 否则一处手滑就会让整个进程后续所有连接都收到被改过的能力清单。
+*/
+function connectionReadyData() {
+	return {
+		bridgeVersion: PLUGIN_VERSION,
+		capabilities: [...BRIDGE_CAPABILITIES]
+	};
+}
+//#endregion
+//#region src/host/history-budget.ts
+/**
+* 历史响应的**字节预算**与**通用裁剪**。
+*
+* ## 为什么需要
+*
+* `GET /chat/sessions/{id}/messages` 是原样透传 DSH 的 history 事件。这些事件里
+* 最重的是工具输出 —— 一条 `cargo build`、一次大文件读取、一段日志回放，
+* 单条就能到几 MB。手机端拿到这种响应要**先在内存里解析整份 JSON**，
+* 于是「翻一次历史把 App 卡住甚至 OOM」是完全可能的，而服务端这边毫无察觉
+* （序列化成功、HTTP 也正常返回）。
+*
+* 对标第三方移动网关：它给历史/订阅基线设了字节预算（单帧 4 MiB、订阅基线 256 KiB），
+* 并在 `tool/result` 上做「首尾各保留 8000 字符 + `outputTruncated` 标记」。
+*
+* ## 我们为什么不照抄字段级的做法
+*
+* 它的做法依赖**自己归一化过的**事件形状（它知道哪个字段装工具输出）。
+* 本仓是**原样透传内核事件**：`tool/result` 这个类型名在本仓（`src/`、`tests/`、`docs/`）零命中；
+* 而**内核契约不在本仓可查范围内** —— `node_modules` 下没有 `@deepseek-ai/*`
+* （那些包随 DSH 主包安装，本仓只把它们列为 peer 依赖，见 `CHANGELOG-DEV.md` 里 2.1.x 的记录）。
+* 所以「工具结果挂在哪个字段上」在本仓是**不可证**，而不是「查过、没有」——
+* 两者结论相同，但证据强度完全不同，把后者写进注释等于伪造一条证据。
+* 按猜出来的字段名写裁剪，最坏结果是**静默无效**（裁剪器一条都没命中，界面上看不出区别，
+* 直到某天线上真的 OOM）。
+*
+* 所以这里做**形状无关**的两层防护：
+*
+* 1. **单条事件超限** → 对该事件里所有超长字符串做首尾保留，并在外层元素上打
+*    `bridgeTruncated: true`。递归找字符串，不需要知道字段名。
+* 2. **整份响应超限** → 从**最旧**的开始丢整条，保留最新的连续后缀，并把 `hasMore` 置真。
+*    这与既有分页语义一致：客户端仍可带 `beforeSeq` 往回翻，丢掉的只是「本次没必要传」的部分。
+*
+* 两层都**只在真的动手时**才加标记 —— 正常响应与改动前逐字节一致（有测试钉住）。
+*/
+/** 单次 history 响应最多返回的 UTF-8 字节数。 */
+const HISTORY_BYTE_BUDGET = 2097152;
+/** 单条事件超过这个字节数就走字符串级裁剪。 */
+const HISTORY_EVENT_BYTE_BUDGET = 524288;
+/** 裁剪时首尾各保留的字符数（对标值）。 */
+const HISTORY_KEEP_CHARS = 8e3;
+/** 省略号：让被裁剪的文本一眼能看出「中间没了」。 */
+const ELLIPSIS = "\n…[truncated]…\n";
+/**
+* 按 **UTF-8 字节**量一份 JSON 的大小。
+*
+* 为什么不数字符（`JSON.stringify(value).length`）：预算要拦的是**出网体积**，
+* 而中文一个字在 UTF-8 里占 3 字节、emoji 占 4 字节 —— 按字符数算会让一份全中文的历史
+* 看起来「还没超」，实际传出去是它的三倍。
+*/
+function byteLength(value) {
+	try {
+		return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+	} catch {
+		return 0;
+	}
+}
+/**
+* 把超过 [limit] 的字符串替换成「首尾保留」版本；返回新结构（不改入参）。
+*
+* 只处理字符串：数字/布尔/空值本来就不占体积，对象与数组由递归覆盖。
+* 循环引用用 [seen] 兜住 —— 内核事件是 JSON 来的，理论上无环，
+* 但这里是**出网路径**，宁可退化成「原样返回该子树」也不能抛异常把整个响应打掉。
+*/
+function clampStrings(value, limit, seen) {
+	if (typeof value === "string") {
+		if (value.length <= limit) return {
+			value,
+			clamped: 0
+		};
+		const keep = Math.max(1, Math.min(limit, HISTORY_KEEP_CHARS));
+		return {
+			value: `${value.slice(0, keep)}${ELLIPSIS}${value.slice(-keep)}`,
+			clamped: 1
+		};
+	}
+	if (value === null || typeof value !== "object") return {
+		value,
+		clamped: 0
+	};
+	if (seen.has(value)) return {
+		value,
+		clamped: 0
+	};
+	seen.add(value);
+	let clamped = 0;
+	if (Array.isArray(value)) return {
+		value: value.map((item) => {
+			const result = clampStrings(item, limit, seen);
+			clamped += result.clamped;
+			return result.value;
+		}),
+		clamped
+	};
+	const source = value;
+	const next = {};
+	for (const [key, item] of Object.entries(source)) {
+		const result = clampStrings(item, limit, seen);
+		clamped += result.clamped;
+		next[key] = result.value;
+	}
+	return {
+		value: next,
+		clamped
+	};
+}
+/**
+* 按预算裁剪 history 事件：先逐条限幅，再从最旧端丢弃，直到整份落在预算内。
+*
+* 丢弃**从最旧端**开始是刻意的：客户端永远从最新往回看，翻历史靠 `beforeSeq`。
+* 若从最新端丢，用户会看到「刚发生的事没了」，那才是真的坏。
+*/
+function clampHistoryEvents(events, byteBudget = HISTORY_BYTE_BUDGET, perEventBudget = HISTORY_EVENT_BYTE_BUDGET) {
+	let clampedStrings = 0;
+	const prepared = events.map((entry) => {
+		if (byteLength(entry) <= perEventBudget) return entry;
+		const result = clampStrings(entry, perEventBudget, /* @__PURE__ */ new WeakSet());
+		if (result.clamped === 0) return entry;
+		clampedStrings += result.clamped;
+		const marker = { truncated: true };
+		const clampedValue = result.value;
+		return clampedValue !== null && typeof clampedValue === "object" && !Array.isArray(clampedValue) ? {
+			...clampedValue,
+			bridgeTruncated: marker
+		} : {
+			value: clampedValue,
+			bridgeTruncated: marker
+		};
+	});
+	const kept = [];
+	let bytes = 0;
+	for (let index = prepared.length - 1; index >= 0; index -= 1) {
+		const size = byteLength(prepared[index]);
+		if (kept.length > 0 && bytes + size > byteBudget) break;
+		bytes += size;
+		kept.push(prepared[index]);
+	}
+	kept.reverse();
+	return {
+		events: kept,
+		bytes,
+		droppedOldest: prepared.length - kept.length,
+		clampedStrings
+	};
+}
+/**
+* 把预算结果套回 history 响应体（adapter 唯一要调用的入口）。
+*
+* 抽成纯函数而不是写在 adapter 里，是因为这几行决定**客户端会不会误判「到底了」**：
+* 丢了最旧事件却不把 `hasMore` 置真，用户就再也翻不回更早的历史；
+* 而裁剪过却不给 `truncated` 标记，客户端会把被截断的正文当完整正文展示。
+* 放在这里可以直接断言，不必为了测四行逻辑去复刻 adapter 的 principal/database/roots 夹具。
+*/
+function applyHistoryBudget(raw, byteBudget = HISTORY_BYTE_BUDGET, perEventBudget = HISTORY_EVENT_BYTE_BUDGET) {
+	const clamped = clampHistoryEvents(raw.events, byteBudget, perEventBudget);
+	const touched = clamped.droppedOldest > 0 || clamped.clampedStrings > 0;
+	return {
+		...raw,
+		events: clamped.events,
+		hasMore: raw.hasMore === true || clamped.droppedOldest > 0,
+		...touched ? {
+			bytes: clamped.bytes,
+			truncated: true
+		} : {}
+	};
+}
+//#endregion
 //#region src/host/path-policy.ts
 const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
 function validateRelativePath(value) {
@@ -228,7 +804,21 @@ var DshChatAdapter = class {
 		this.database = database;
 		this.commandServices = commandServices;
 	}
-	async listSessions(principal) {
+	/**
+	* 列出会话。
+	*
+	* `options.archived === true` 时返回**已归档**的那批；默认返回未归档的。
+	*
+	* 为什么需要这个参数：内核把「归档」实现为**从所有分组界面隐藏**，本桥默认照做 ——
+	* 于是用户在手机上一归档，那条会话就**再也看不到**（连找都找不到），
+	* 「归档」变成了单向门。参数化之后客户端至少能提供一个「已归档」入口。
+	*
+	* **恢复（取消归档）不在本桥能力内**：适配层只声明了内核的 `archiveSession`，
+	* 内核是否提供 unarchive 从本仓**不可证** —— `node_modules` 下没有 `@deepseek-ai/*`
+	* （那些包随 DSH 主包安装）。按 `PITFALLS.md` §空结果的来源要验证，
+	* 这里只能写「不可证」，不能写「没有」。
+	*/
+	async listSessions(principal, options = {}) {
 		const [sessionsResponse, workspaceResponse] = await Promise.all([this.api.sessions.list({
 			rpcId: randomUUID(),
 			payload: {}
@@ -243,7 +833,7 @@ var DshChatAdapter = class {
 		const roots = this.authorizedRoots(principal);
 		const visible = [];
 		for (const session of value.items) {
-			if (archivedSessionIds.has(session.sessionId)) continue;
+			if (archivedSessionIds.has(session.sessionId) !== (options.archived === true)) continue;
 			const absoluteCwd = session.cwd;
 			if (absoluteCwd === void 0) continue;
 			const match = matchRoot(roots, absoluteCwd);
@@ -387,10 +977,13 @@ var DshChatAdapter = class {
 			...options.beforeSeq === void 0 ? {} : { beforeSeq: options.beforeSeq },
 			...options.maxMessages === void 0 ? {} : { maxMessages: options.maxMessages }
 		};
-		return unwrapDsh(await this.api.sessions.history({
-			rpcId: randomUUID(),
-			payload
-		}));
+		return {
+			...applyHistoryBudget(unwrapDsh(await this.api.sessions.history({
+				rpcId: randomUUID(),
+				payload
+			}))),
+			historyFormatVersion: 1
+		};
 	}
 	async prompt(principal, sessionId, parts, mode, clientTimeZone, locale) {
 		await this.requireSession(principal, sessionId);
@@ -523,6 +1116,49 @@ var DshChatAdapter = class {
 		} catch {}
 		return records.sort((left, right) => left.requestedAt - right.requestedAt).map((record) => publicApproval(record, findToolCallDetail(history, record.callId)));
 	}
+	/**
+	* 连接建立时重放的待处理审批事件。
+	*
+	* ## 为什么需要
+	*
+	* 「连接后要不要主动查一次 REST」是**客户端自己的选择**：我方 App 会
+	* （`HarnessViewModel` 的 `connection` 回调里刷新历史/审批/提问/命令），
+	* 但协议不该把「审批不丢」寄托在这一点上 —— 客户端若只在收到事件时才刷新，
+	* 重连窗口里产生的审批就会静默消失：内核阻塞着等决定，手机上却一片安静。
+	* 重放把这件事变成**服务端保证**；对已经在连接后刷新的客户端，它只是一次幂等冗余。
+	*
+	* 对标第三方移动网关：它在**连接建立**与**订阅**两个触发点重发仍待处理的提问/审批，
+	* 客户端按 id 去重。我们这里给事件加 `data.replayed = true`，
+	* 客户端可以据此跳过「新卡片」动画，也可以完全忽略（刷新本身是幂等的）。
+	*
+	* ## 为什么先只做审批
+	*
+	* 审批是**阻塞内核**的那一类：漏掉它，Agent 会一直等；提问不阻塞（Agent 已经继续跑）。
+	* 提问侧的待处理数据在 `dsh-0.2-bridge` 的 `QuestionBridge.pending` 里，
+	* 要重放得先通过 `apiProxy` 暴露一个「全部会话」入口 —— 那是独立的一小步，
+	* 不塞进本次改动里凑数。
+	*/
+	async replayPendingApprovals(principal) {
+		const allowed = [];
+		for (const record of this.pendingApprovals.values()) if (await this.isSessionAuthorized(principal, record.sessionId)) allowed.push(record);
+		return approvalReplayEvents(allowed);
+	}
+	/**
+	* 连接建立时重放的**挂起提问**事件。
+	*
+	* 与 [replayPendingApprovals] 同一动机：把「新连接一定能拿到仍待处理的东西」
+	* 变成**服务端保证**，而不是每个客户端各自的义务（论证与纠错记录见该方法的 KDoc）。
+	*
+	* 两者一个区别：提问**不阻塞内核**（Agent 已经继续跑），漏掉它的代价小一些；
+	* 但「卡片不出现、用户以为没问题」同样是坏体验，所以对称补上。
+	* 数据来自适配层的 `userQuestions.pendingAll()` —— 老实现不提供时跳过（可选方法），不报错。
+	*/
+	async replayPendingQuestions(principal) {
+		const pending = this.api.userQuestions.pendingAll?.() ?? [];
+		const allowed = [];
+		for (const item of pending) if (await this.isSessionAuthorized(principal, item.sessionId)) allowed.push(item);
+		return questionReplayEvents(allowed);
+	}
 	async decideApproval(principal, sessionId, approvalId, outcome) {
 		await this.requireSession(principal, sessionId);
 		const key = approvalKey(sessionId, approvalId);
@@ -797,6 +1433,20 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			...typeof payload.outcome === "string" ? { outcome: payload.outcome } : {}
 		}
 	};
+	if (payloadType === "session/snapshot" && typeof payload.sessionId === "string") {
+		const cursor = typeof payload.cursor === "number" ? payload.cursor : void 0;
+		return {
+			id: `${payload.sessionId}:snapshot:${cursor ?? "unknown"}`,
+			type: "chat.session.snapshot",
+			time,
+			data: {
+				sessionId: payload.sessionId,
+				...cursor === void 0 ? {} : { cursor },
+				...typeof payload.hasMore === "boolean" ? { hasMore: payload.hasMore } : {},
+				...typeof payload.recordCount === "number" ? { recordCount: payload.recordCount } : {}
+			}
+		};
+	}
 	if (payloadType === "session/event" && typeof payload.sessionId === "string" && isRecord$1(payload.event)) {
 		const event = payload.event;
 		const eventType = typeof event.type === "string" ? event.type : "unknown";
@@ -820,8 +1470,8 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 						kind,
 						text: rawChunk.text,
 						index: rawChunk.index,
-						...typeof assistantData.turn === "number" ? { turn: assistantData.turn } : {},
-						...typeof assistantData.step === "number" ? { step: assistantData.step } : {}
+						turn: typeof assistantData.turn === "number" ? assistantData.turn : 0,
+						step: typeof assistantData.step === "number" ? assistantData.step : 0
 					}
 				};
 			}
@@ -840,6 +1490,19 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 				}
 			};
 		}
+		if (eventType === "deliverables/presented") {
+			const data = isRecord$1(payload.event) ? payload.event.data : void 0;
+			const files = isRecord$1(data) && Array.isArray(data.files) ? data.files : [];
+			return {
+				id: `${payload.sessionId}:deliverables:${seq ?? files.length}`,
+				type: "chat.deliverables.presented",
+				time,
+				data: {
+					...base,
+					files
+				}
+			};
+		}
 		if (eventType === "turn/start" || eventType === "turn/end") {
 			if (eventType === "turn/end") {
 				const failure = turnFailureOf(event);
@@ -954,6 +1617,53 @@ function approvalKey(sessionId, approvalId) {
 function approvalRisk(reason) {
 	return reason?.toLowerCase().includes("danger-full-access") === true ? "full-access" : "standard";
 }
+/**
+* 把待处理审批记录转成可重放的事件（纯函数，好测）。
+*
+* 抽出来的理由：这几行决定「重连后手机能不能看见那张卡」，而它本身与授权、IO 无关；
+* 放在 `replayPendingApprovals` 里就得为了测它去复刻 principal/database 整套夹具。
+*
+* 按 `requestedAt` 升序：先申请的排前面，客户端依次刷新时不会因为顺序错乱而闪。
+* `id` 与实时事件保持同一形状（`<approvalId>:requested`），
+* 于是「同一审批」在实时与重放两条路径上对客户端是**同一个事件 id**（便于去重）。
+*/
+function approvalReplayEvents(records, time = Date.now()) {
+	return [...records].sort((left, right) => left.requestedAt - right.requestedAt).map((record) => ({
+		id: `${record.approvalId}:requested`,
+		type: "chat.approval.requested",
+		time,
+		data: {
+			sessionId: record.sessionId,
+			approvalId: record.approvalId,
+			toolName: record.toolName,
+			risk: approvalRisk(record.reason),
+			replayed: true
+		}
+	}));
+}
+/**
+* 把挂起中的提问记录转成可重放的事件（纯函数，好测）。
+*
+* 事件类型与**实时路径**一致（`chat.userQuestions/requested`，由 `normalizeDshEvent`
+* 末段的 `chat.${payloadType}` 兜底产生），data 字段也保持同一组，只多 `replayed: true`。
+* `id` 用 `<callId>:requested`，与实时事件的 id 形状不冲突（实时用帧 rpcId）——
+* 客户端按 `callId` 去重，两条路径指向同一道题。
+*/
+function questionReplayEvents(items, time = Date.now()) {
+	return items.map((item) => ({
+		id: `${item.callId}:requested`,
+		type: "chat.userQuestions/requested",
+		time,
+		data: {
+			type: "userQuestions/requested",
+			sessionId: item.sessionId,
+			callId: item.callId,
+			rpcId: item.rpcId,
+			questions: item.questions,
+			replayed: true
+		}
+	}));
+}
 function publicApproval(record, detail) {
 	const reason = record.reason === void 0 ? void 0 : redactApprovalText(record.reason, 500);
 	const safeDetail = detail === void 0 ? void 0 : redactApprovalText(detail, 1200);
@@ -1898,6 +2608,16 @@ var SessionEventRelay = class {
 		for await (const rawFrame of stream) {
 			if (signal.aborted) break;
 			const frame = rawFrame;
+			if (frame.type === "snapshot") {
+				this.mux.push({
+					type: "session/snapshot",
+					sessionId,
+					...typeof frame.cursor === "number" ? { cursor: frame.cursor } : {},
+					...typeof frame.hasMore === "boolean" ? { hasMore: frame.hasMore } : {},
+					recordCount: Array.isArray(frame.records) ? frame.records.length : 0
+				});
+				continue;
+			}
 			if (frame.type === "event") {
 				this.mux.push({
 					type: "session/event",
@@ -1909,8 +2629,8 @@ var SessionEventRelay = class {
 			if (frame.type !== "assistant-stream" || frame.frame === void 0) continue;
 			const inner = frame.frame;
 			if (inner.type === "start") {
-				turn = typeof inner.turn === "number" ? inner.turn : void 0;
-				step = typeof inner.step === "number" ? inner.step : void 0;
+				turn = typeof inner.turn === "number" ? inner.turn : 0;
+				step = typeof inner.step === "number" ? inner.step : 0;
 				continue;
 			}
 			if (inner.type !== "chunk") continue;
@@ -1919,7 +2639,6 @@ var SessionEventRelay = class {
 				sessionId,
 				event: {
 					type: "assistant/chunk",
-					seq: typeof inner.index === "number" ? inner.index : 0,
 					time: typeof inner.time === "number" ? inner.time : Date.now(),
 					data: {
 						chunk: inner.chunk,
@@ -2164,6 +2883,22 @@ var QuestionBridge = class {
 		}
 		return out;
 	}
+	/**
+	* **全部会话**挂起中的提问（连接重放用）。
+	*
+	* 与 `pendingFor` 的唯一区别是「不过滤会话」：重放要遍历所有会话，
+	* 再按每条连接的授权逐条过滤 —— 授权判断在 chat-adapter 侧做，这里只给事实。
+	* 带上 `rpcId` 是为了让重放事件与实时事件**字段集一致**：
+	* 客户端按 `callId` 回答，但字段对齐能避免两条路径悄悄漂移（见 chat-adapter 的契约钉子测试）。
+	*/
+	pendingAll() {
+		return [...this.pending.entries()].map(([rpcId, entry]) => ({
+			rpcId,
+			sessionId: entry.sessionId,
+			callId: entry.callId,
+			questions: [...entry.questions]
+		}));
+	}
 };
 /**
 * 答案批次的最小校验（路由层已校验过一遍，这里是防御性第二道）。
@@ -2659,6 +3394,7 @@ function createDsh02ApiProxy(host, options = {}) {
 			})
 		},
 		userQuestions: {
+			pendingAll: () => questions.pendingAll(),
 			list: (request) => call(async () => {
 				const { sessionId } = request.payload;
 				const bridged = questions.pendingFor(sessionId);
@@ -3713,8 +4449,97 @@ async function inspectResolvedPath(root, wirePath) {
 	};
 }
 //#endregion
-//#region src/shared/version.ts
-const PLUGIN_VERSION = "2.3.7";
+//#region src/host/wire-json.ts
+/**
+* 出网 JSON 的安全序列化：把**孤立 UTF-16 代理项**换成 U+FFFD。
+*
+* ## 为什么需要这一层（实发场景）
+*
+* DSH 内核在生成事件摘要时会按**字符数**截断字符串。若截断点正好落在
+* 一个代理对（emoji、部分 CJK 扩展字、某些工具输出的花括号表情）中间，
+* 字符串里就只剩**半个**代理项。`JSON.stringify` 会把它老实转义成 `\udXXX`，
+* 于是线上出现一份「语法合法、语义非法」的 JSON：
+* JavaScript 侧照常解析，而 **Swift/Foundation 的 JSONDecoder 会直接拒绝整帧**。
+* 症状极具误导性 —— 一条工具输出的半个 emoji，把整条 WebSocket 连接打死，
+* 客户端表现为「突然不再更新」，日志里只有一句解码失败。
+*
+* ## 为什么在传输层做，而不是在产生摘要的地方做
+*
+* 摘要不只一处（chat-adapter 的工具输出、内核自己拼的标题、历史重放…），
+* 逐个补是打地鼠；而**出网**只有两个口（HTTP JSON 响应与 WebSocket 帧），
+* 在这里做一次就等于全覆盖，且未来新增事件类型自动受益。
+*
+* ## 为什么不用正则
+*
+* 「孤立代理项」的判定需要看**相邻字符**。带后向断言的正则在超长字符串上
+* 有性能与兼容两个问题（KMP/Server 端行为不一致），而这是一条会被每个事件
+* 走到的热路径。这里用单遍字符扫描：O(n)、无递归、无回溯，且对合法代理对
+* 原样放行（emoji 不会被吃掉）。
+*
+* 对标：第三方移动网关 `dsh-plugin-mobile-gateway` 的 `lib/wire-json.mjs` 做了同一件事
+* （它只用了 7 行 —— 我们这边多出来的部分全是给「为什么不那样做」留的注释）。
+*/
+/** 孤儿代理项的统一替身：Unicode 的「替换字符」。 */
+const REPLACEMENT = "�";
+const HIGH_SURROGATE_START = 55296;
+const HIGH_SURROGATE_END = 56319;
+const LOW_SURROGATE_START = 56320;
+const LOW_SURROGATE_END = 57343;
+/**
+* 把字符串里所有**孤立**的 UTF-16 代理项替换为 U+FFFD；合法代理对原样保留。
+*
+* 无代理项时**返回原引用**（快路径）：绝大多数事件不含代理项，
+* 这条路径应当零分配 —— 它跑在每次广播上。
+*/
+function sanitizeLoneSurrogates(text) {
+	let firstBad = -1;
+	for (let i = 0; i < text.length; i += 1) {
+		const code = text.charCodeAt(i);
+		if (code < HIGH_SURROGATE_START || code > LOW_SURROGATE_END) continue;
+		if (code <= HIGH_SURROGATE_END) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= LOW_SURROGATE_START && next <= LOW_SURROGATE_END) {
+				i += 1;
+				continue;
+			}
+		}
+		firstBad = i;
+		break;
+	}
+	if (firstBad < 0) return text;
+	let out = text.slice(0, firstBad);
+	for (let i = firstBad; i < text.length; i += 1) {
+		const code = text.charCodeAt(i);
+		if (code < HIGH_SURROGATE_START || code > LOW_SURROGATE_END) {
+			out += text.charAt(i);
+			continue;
+		}
+		if (code <= HIGH_SURROGATE_END) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= LOW_SURROGATE_START && next <= LOW_SURROGATE_END) {
+				out += text.charAt(i) + text.charAt(i + 1);
+				i += 1;
+				continue;
+			}
+		}
+		out += REPLACEMENT;
+	}
+	return out;
+}
+/**
+* 出网的 `JSON.stringify`：先消毒所有**字符串值**，再交给原生序列化。
+*
+* 用 `replacer` 而不是「先深拷贝再清洗」，是为了不复制事件对象 ——
+* 工具结果动辄几百 KB，多一次深拷贝就是白烧一次内存与 GC。
+*
+* **已知边界**：`replacer` 不会经过**对象的键**，所以键名里的孤立代理项不会被修。
+* 这是刻意接受的：本项目的键要么是协议里固定的 ASCII 字段名，要么由内核以
+* 固定字面量拼出，不存在「按字符数截断的键」。真出现这种键，应从产生侧修，
+* 而不是在这里做全量 JSON 词法扫描（那会让每次广播都多一遍 O(n) 解析）。
+*/
+function stringifyWire(value) {
+	return JSON.stringify(value, (_key, item) => typeof item === "string" ? sanitizeLoneSurrogates(item) : item);
+}
 //#endregion
 //#region src/host/router.ts
 var ApiRouter = class {
@@ -3979,7 +4804,8 @@ var ApiRouter = class {
 		if (pathname === "/api/v1/chat/sessions") {
 			if (method === "GET") {
 				this.options.auth.requireScope(principal, "chat.read");
-				sendJson(res, 200, { items: await this.options.chat.listSessions(principal) });
+				const archived = url.searchParams.get("archived") === "true";
+				sendJson(res, 200, { items: await this.options.chat.listSessions(principal, { archived }) });
 				return;
 			}
 			if (method === "POST") {
@@ -4351,6 +5177,42 @@ var ApiRouter = class {
 			res.end();
 			return;
 		}
+		if (this.options.tunnels !== void 0 && pathname === "/manage/cloudflare/status") {
+			if (method === "GET" || method === "HEAD") {
+				sendJson(res, 200, this.options.tunnels.publicState);
+				return;
+			}
+		}
+		if (this.options.tunnels !== void 0 && pathname === "/manage/cloudflare/activity") {
+			if (method === "GET" || method === "HEAD") {
+				sendJson(res, 200, this.options.tunnels.activityState);
+				return;
+			}
+		}
+		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/create") {
+			const binDir = this.options.cloudflaredBinDir;
+			let exe;
+			try {
+				exe = await ensureCloudflared(binDir ?? this.options.database.dataDir, (a) => {
+					this.options.tunnels.reportActivity(a);
+				});
+			} catch (cause) {
+				this.options.tunnels.clearActivity();
+				throw new ApiError(502, "TUNNEL_DOWNLOAD_FAILED", cause instanceof Error ? cause.message : String(cause));
+			}
+			const port = this.options.remote.status().configuredPort ?? 3090;
+			const state = await this.options.tunnels.startQuick(exe, port);
+			this.options.tunnels.clearActivity();
+			this.options.database.audit("admin", "loopback-admin", "cloudflare.create", void 0, void 0, {}, requestId);
+			sendJson(res, 201, state);
+			return;
+		}
+		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/stop") {
+			const state = this.options.tunnels.stop();
+			this.options.database.audit("admin", "loopback-admin", "cloudflare.stop", void 0, void 0, {}, requestId);
+			sendJson(res, 200, state);
+			return;
+		}
 		throw new ApiError(404, "ROUTE_NOT_FOUND", "The requested management route does not exist.");
 	}
 	async dispatchEntries(req, res, url, principal, root, requestId) {
@@ -4478,7 +5340,7 @@ async function readBytes(req, maxBytes) {
 	return Buffer.concat(chunks);
 }
 function sendJson(res, status, body) {
-	const encoded = Buffer.from(JSON.stringify(body));
+	const encoded = Buffer.from(stringifyWire(body));
 	res.writeHead(status, {
 		"Content-Type": "application/json; charset=utf-8",
 		"Content-Length": encoded.length
@@ -4870,17 +5732,42 @@ var RemoteApiServer = class {
 				webSocket.on("error", () => {
 					this.sockets.delete(webSocket);
 				});
-				webSocket.send(JSON.stringify({
+				webSocket.send(stringifyWire({
 					id: randomUUID(),
 					type: "connection.ready",
 					time: Date.now(),
-					data: {}
+					data: connectionReadyData()
 				}));
+				this.replayPendingInteractions(webSocket, principal);
 			});
 		} catch {
 			socket.destroy();
 		}
 	}
+	/**
+	* 把待处理的**审批与提问**补推给刚建立的这条连接。
+	*
+	* 为什么要有这一步：「连接后要不要主动查一次 REST」是**每个客户端自己的选择**。
+	* 我方 App 会（`HarnessViewModel` 的 `connection` 回调里刷新历史/审批/提问/命令），
+	* 但协议不该把「审批不丢」寄托在这一点上：客户端若只在收到事件时才刷新，
+	* 重连窗口里产生的审批就会静默消失（内核阻塞着等决定、手机上却一片安静）。
+	* 重放把「新连接一定能拿到仍待处理的审批」变成**服务端保证**，而不是客户端的义务。
+	*
+	* 三个刻意的取舍：
+	* - **不 await**：重放要按会话做授权过滤（异步），握手不能为它排队；
+	* - **只发这一条连接**：不走 `broadcast`，避免每次有人重连就骚扰所有在线设备；
+	* - **失败静默**：重放是补救措施，它出错不该影响这条连接正常收事件。
+	*   客户端侧「连接后/亮屏后主动刷新」仍是兜底，但不再是唯一依赖。
+	*/
+	async replayPendingInteractions(socket, principal) {
+		try {
+			const events = [...await this.options.chat.replayPendingApprovals(principal), ...await this.options.chat.replayPendingQuestions(principal)];
+			for (const event of events) {
+				if (socket.readyState !== WebSocket.OPEN) return;
+				socket.send(stringifyWire(event));
+			}
+		} catch {}
+	}
 	async broadcast(event) {
 		for (const [socket, principal] of this.sockets) {
 			if (socket.readyState !== WebSocket.OPEN) continue;
@@ -4901,7 +5788,7 @@ var RemoteApiServer = class {
 				this.sockets.set(socket, currentPrincipal);
 			}
 			if (!await this.eventAllowed(currentPrincipal, event)) continue;
-			socket.send(JSON.stringify(event));
+			socket.send(stringifyWire(event));
 		}
 	}
 	async eventAllowed(principal, event) {
@@ -5410,6 +6297,8 @@ async function apply(ctx, config = {}) {
 		chat,
 		settings,
 		remote,
+		tunnels: new CloudflaredTunnelManager(),
+		cloudflaredBinDir: path.join(dataDir, "cloudflared-bin"),
 		maxUploadBytes,
 		imageFallbackDir: imageHandoffDir
 	});