dsh-remote-bridge 2.4.2 → 2.5.0

package/lib/index.js

@@ -1,4 +1,4 @@
-import path, { join } from "node:path";
+import path, { join, sep } 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";
@@ -134,10 +134,22 @@ function isLoopbackOrigin(origin) {
 }
 //#endregion
 //#region src/host/cloudflared.ts
-/** 平台/架构 -> cloudflared 归档后缀。 */
-function archSuffix(platform = process.platform) {
+/**
+* 平台/架构 -> cloudflared 归档后缀。
+*
+* **架构必须能单独传**，不能读 `process.arch`：
+* 2026-10-20 CI 实锤 —— 旧实现里 platform 是参数、arch 却写死 `process.arch`，
+* 于是 `archSuffix('linux')` 在 macOS runner（arm64）上返回 `linux-arm64`，
+* 而调用方要的是「linux 平台该用哪个官方归档」。同一函数里 platform 可控、
+* arch 不可控，是**自相矛盾的设计**；测试在 macOS 上红、Linux 上绿，全平台矩阵
+* （ubuntu/windows/macos × 两个 Node 版本）里只有 Linux 那两格能过。
+*
+* 两个参数都带默认值时保持旧行为（本机平台 + 本机架构）；显式传入时，
+* 结果只由入参决定 —— 这才让「算一个别的平台的后缀」成为可能。
+*/
+function archSuffix(platform = process.platform, arch = process.arch) {
 	if (platform !== "linux") throw new Error(`cloudflared 尚不支持 ${platform} 平台。`);
-	switch (process.arch) {
+	switch (arch) {
 		case "x64": return "linux-amd64";
 		case "arm64": return "linux-arm64";
 		default: throw new Error(`cloudflared 尚不支持 ${process.arch} 架构。`);
@@ -197,8 +209,20 @@ function isDebSource() {
 	return mirrorBase().startsWith("deb+");
 }
 /** 返回要下载的源 URL：deb 源返回完整 .deb 地址；裸镜像基址拼架构后缀；否则官方 GitHub。 */
-function downloadUrlFor() {
-	const suffix = archSuffix();
+/**
+* cloudflared 官方归档的下载地址。
+*
+* **platform/arch 都能显式传入**（2026-10-20 CI 实锤后加）：旧实现里
+* `downloadUrlFor()` 走 `archSuffix()` 的默认参数 —— 也就是**本机** platform/arch。
+* 于是这个函数在 macOS runner 上直接抛「尚不支持 darwin 平台」，
+* 而它要回答的问题其实是「linux 的 cloudflared 该从哪下」。
+*
+* 默认值保持本机（生产调用点 `ensureCloudflared` 就在 linux 上跑，行为不变），
+* 但显式传入后结果只由入参决定 —— 这才让「算别的平台的 URL」成为可能，
+* 也让测试不依赖跑在什么机器上。
+*/
+function downloadUrlFor(platform = process.platform, arch = process.arch) {
+	const suffix = archSuffix(platform, arch);
 	const mirror = mirrorBase();
 	if (mirror === "") return `${OFFICIAL_BASE}${suffix}`;
 	if (mirror.startsWith("deb+")) return mirror.slice(4);
@@ -796,7 +820,33 @@ function parentWirePath(relativePath) {
 * 调用方必须自己给出可读的错误（见 readAttachment），而不是让用户看到一个
 * 语焉不详的 500。
 */
+/**
+* 读一个**可选**宿主服务：存在就返回，不存在返回 null。
+*
+* ## 为什么必须走 `ctx.reflect.get(name, false)`，不能直接读属性
+*
+* cordis 的 `inject` 是**硬依赖**（`registry.d.ts` 的 `Inject` 类型只有数组与映射两种
+* 形式，注释原文是 "required services"）：inject 里任何一个服务缺失，`_refresh()`
+* 就把 epoch 置为 INACTIVE，**整个插件不激活**。
+*
+* 所以「可选服务」**不能**写进 inject —— 写了就变成「哪个内核版本缺它、插件在哪一版
+* 整个死掉」。而直接读属性（`host[name]`）也不行：不在 inject 里的属性会抛
+* `cannot get property "x" without inject`，与「服务不存在」**报同一个错**，
+* 于是这个函数会永远返回 null（这正是它此前的实际行为，
+* `attachments` / `fileUploads` 一直在走降级路径）。
+*
+* `ctx.reflect.get(name, false)` 是 cordis 给这件事准备的正路
+* （`cordis/lib/index.js` 的 ReflectService.get，注释原文：
+* "Read a service from the store **without the inject requirement**"）：
+* 不要求 inject 声明，服务不存在时返回 `undefined` 而不是抛错。
+*/
 function optionalService(host, name) {
+	const reflect = host.reflect;
+	if (reflect !== void 0 && typeof reflect.get === "function") try {
+		const value = reflect.get(name, false);
+		if (value === void 0 || value === null) return null;
+		return value;
+	} catch {}
 	try {
 		return host[name];
 	} catch {
@@ -1413,7 +1463,7 @@ function writeHandoffFile(dir, workspace, mediaType, data) {
 	if (!existsSync(absolute)) writeFileSync(absolute, bytes, { mode: 384 });
 	return {
 		absolute,
-		relative: workspace !== void 0 && absolute.startsWith(workspace + "/") ? absolute.slice(workspace.length + 1) : fileName
+		relative: workspace !== void 0 && absolute.startsWith(workspace + sep) ? absolute.slice(workspace.length + 1).split(sep).join("/") : fileName
 	};
 }
 /** 交接文件名只允许「内容哈希 + 图片扩展名」：挡住一切路径穿越。 */
@@ -1528,12 +1578,36 @@ const FALLBACK_PERMISSION_CATALOG = {
 	defaultPreset: "workspace-write"
 };
 /**
+* 从 follow 的 snapshot 帧里取投影基线。
+*
+* 0.2.1 起 `SessionFollowFrame` 的 snapshot 分支自带
+* `projections: SessionProjectionBaseline`，所以正常情况下**不需要**再打一次
+* `sessionController.projections()`。这个函数就是那个判断：有就用，没有返回 undefined
+* 让调用方回落。
+*
+* 为什么用结构探测而不是类型收窄：本插件刻意不 import `@deepseek-ai/*`，
+* `snapshot` 在这里是结构类型，看不到内核的判别联合。按形状判断是唯一办法，
+* 也与本文件其余部分的风格一致。
+*/
+function projectionsOf(snapshot) {
+	if (snapshot === null || typeof snapshot !== "object") return void 0;
+	const projections = snapshot.projections;
+	if (projections === null || typeof projections !== "object") return void 0;
+	const values = projections.values;
+	if (values === null || typeof values !== "object") return void 0;
+	const asOfSeq = projections.asOfSeq;
+	return {
+		...typeof asOfSeq === "number" ? { asOfSeq } : {},
+		values
+	};
+}
+/**
 * 读会话的**投影基线**（`permissions` / `modelSelection` / `title` …）。
 *
 * @patch
 * id: history-projections-passthrough
 * for: 内核 `sessionController.follow()` 的 snapshot 与 `page()` 都**不返回 projections**
-*      （类型上就是 `{ cursor, records, hasMore }`），而客户端要靠
+*      （0.2.0 的类型上就是 `{ cursor, records, hasMore }`），而客户端要靠
 *      `projections.values.permissions` 才能显示会话的当前权限档位。
 *      内核那边确实注册了这条投影（`dsh-permission-presets` 里
 *      `ctx.sessionProjections.register({ key: 'permissions', … })`），
@@ -1542,6 +1616,9 @@ const FALLBACK_PERMISSION_CATALOG = {
 *      不补的后果是 Android 客户端的权限档位 Pill 与 ⋯ 菜单权限项**从不渲染**
 *      —— v2.2.44 真机验收实测到了这个，而当时 `PARITY.md` 还把它标成 `done`。
 * until: 内核把 projections 并进 follow/page 的返回。
+*       **0.2.1 已达成**：snapshot 分支现在自带 `projections`，history 首屏走
+*       `projectionsOf(snapshot)`，不再打这次 RPC。本函数降级为**老内核回落路径**，
+*       保留到最低支持版本升过 0.2.1 之后再删。
 * test: tests/history-projections.spec.ts
 */
 async function readSessionProjections(host, sessionId, signal) {
@@ -1755,7 +1832,7 @@ function createDsh02ApiProxy(host, options = {}) {
 						events: [],
 						hasMore: false
 					};
-					const projections = await readSessionProjections(host, sessionId, controller.signal);
+					const projections = projectionsOf(snapshot) ?? await readSessionProjections(host, sessionId, controller.signal);
 					const withProjections = (payload) => projections === void 0 ? payload : {
 						...payload,
 						projections
@@ -1986,7 +2063,13 @@ function createDsh02ApiProxy(host, options = {}) {
 					settingsNs: entry.settingsNs,
 					settingsPath: [...entry.settingsPath],
 					active: live.has(entry.provider),
-					...entry.declared === void 0 ? {} : { declared: entry.declared }
+					...entry.declared === void 0 ? {} : { declared: entry.declared },
+					...entry.defaultBaseURL === void 0 ? {} : { defaultBaseURL: entry.defaultBaseURL },
+					...entry.baseURLEnv === void 0 ? {} : { baseURLEnv: [...entry.baseURLEnv] },
+					...entry.nativeAuth === void 0 ? {} : { nativeAuth: {
+						...entry.nativeAuth,
+						...entry.nativeAuth.env === void 0 ? {} : { env: [...entry.nativeAuth.env] }
+					} }
 				})) };
 			}),
 			models: () => call(async () => {
@@ -2009,7 +2092,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.4.2";
+const PLUGIN_VERSION = "2.5.0";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -2087,7 +2170,10 @@ const BRIDGE_CAPABILITIES = [
 	"turn-failure-v1",
 	"history-byte-budget-v1",
 	"interaction-replay-v1",
-	"session-snapshot-v1"
+	"session-snapshot-v1",
+	"job-list-v1",
+	"job-output-v1",
+	"job-kill-v1"
 ];
 /**
 * `connection.ready` 事件的载荷。
@@ -3205,10 +3291,51 @@ function redactApprovalText(value, maxLength = 1200) {
 }
 //#endregion
 //#region src/host/database.ts
+/**
+* 本进程内打开的库（弱引用集合）。
+*
+* ## 为什么需要它
+*
+* `WorkspaceDatabase` 用 `PRAGMA journal_mode=WAL` 打开 sqlite，会留下
+* `workspace.sqlite` / `-wal` / `-shm` 三个文件，**且句柄不关就删不掉**。
+* Linux/macOS 上删一个仍被打开的文件是允许的（unlink 只是断链），所以问题
+* 在那里看不出来；**Windows 上直接 EBUSY**：
+*
+* ```
+* EBUSY: resource busy or locked, unlink 'C:\...\Temp\daw-xxx\state\workspace.sqlite'
+* ```
+*
+* 2026-10-20 CI 在 windows-latest 上实锤（macOS/Linux 全绿、Windows 全红）。
+*
+* ## 它的作用
+*
+* 进程退出时统一关闭所有还开着的库 —— 无论调用方记不记得 `close()`。
+* 这不是「代替 close」，而是**兜底**：正常路径仍应显式 close（早关早释放），
+* 但漏掉的那一个不会在 Windows 上变成 EBUSY 式的删除失败。
+*
+* 弱引用：不阻止 GC，也不阻止正常 close 后的移除（close 时会从集合里摘掉）。
+*/
+const openDatabases = /* @__PURE__ */ new Set();
+/** 进程退出时尽力关闭所有还开着的库。 */
+function closeAllOpenDatabases() {
+	for (const ref of [...openDatabases]) {
+		const db = ref.deref();
+		if (db === void 0) {
+			openDatabases.delete(ref);
+			continue;
+		}
+		try {
+			db.close();
+		} catch {}
+	}
+	openDatabases.clear();
+}
+process.once("exit", closeAllOpenDatabases);
 var WorkspaceDatabase = class {
 	dataDir;
 	trashDir;
 	db;
+	closed = false;
 	constructor(dataDir) {
 		this.dataDir = path.resolve(dataDir);
 		this.trashDir = path.join(this.dataDir, "trash");
@@ -3216,8 +3343,13 @@ var WorkspaceDatabase = class {
 		this.db = new DatabaseSync(path.join(this.dataDir, "workspace.sqlite"));
 		this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
 		this.migrate();
+		openDatabases.add(new WeakRef(this));
 	}
+	/** 关闭数据库。**幂等** —— 重复调用不抛错。 */
 	close() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const ref of [...openDatabases]) if (ref.deref() === this) openDatabases.delete(ref);
 		this.db.close();
 	}
 	/**
@@ -4011,6 +4143,309 @@ function trashView(record) {
 		status: record.status
 	};
 }
+//#endregion
+//#region src/host/host-service-probe.ts
+/**
+* 宿主服务注入面探针。
+*
+* 为什么需要它：本插件刻意不 import 任何 `@deepseek-ai/*`（见
+* docs/project/COMPATIBILITY.md），全部宿主服务按结构类型 + Host 注入消费。
+* 好处是跨内核版本零漂移，**代价是「服务到底注进来了没有」只能靠猜** ——
+* cordis 的注入属性是惰性访问器，读一个没人提供的服务会抛
+* `cannot get property "x" without inject`，而这个错误只在真的去读的那一刻出现。
+*
+* 于是历史上反复出现同一类事故：某功能静默不工作，两侧日志都不说一句话，
+* 排错者先从客户端查起，查到服务端才发现服务压根没注入。
+* 2.0.0 的 `attachments`、2.0.2 的 `fileUploads` 都是这么炸的（见
+* dsh-0.2-bridge.ts 里那段长注释）。
+*
+* 这个探针把「猜」变成「问」：在 apply 期间（注入属性还可读时）逐个试读一次，
+* 记录每个服务的**可解析性**，之后任何时候都能回答「0.2.x 上到底有哪些服务可用」。
+* 它不改变任何行为 —— 纯粹是观测。
+*
+* 使用方式：`GET /dsh-workspace-api/api/v1/debug/host-services`
+* （需要设备 token 或 loopback admin，与其它 REST 端点同一套鉴权）。
+*/
+/**
+* 插件 `cordis.patch.yml` 与 `src/index.ts` 里 inject 声明的全部服务名
+* （**两份清单必须一致**，docs:check 有对齐门禁）。
+*
+* ⚠️ 只能放「两个支持版本（0.2.0-rc.2 与 0.2.1-rc.2）上都存在的服务」——
+* cordis 的 inject 是硬依赖，缺一个整个插件不激活（2026-10-20 在 0.2.0-rc.2 的
+* smoke-profile-install 上实锤过）。可选服务一律走 OPTIONAL_SERVICE_NAMES。
+*/
+const INJECTED_SERVICE_NAMES = [
+	"sessionController",
+	"workspaceController",
+	"workspaceRegistry",
+	"settingsController",
+	"credentialsController",
+	"agentPresets",
+	"llm",
+	"webServer",
+	"agents",
+	"commands"
+];
+/**
+* **可选服务**：不写进 inject（inject 是硬依赖），由插件经
+* `ctx.reflect.get(name, false)` 运行时读取 —— 读到就走该能力，读不到按能力位降级。
+*
+* 探针用同一条 `reflect.get` 读取它们：这样报告的是「内核**真的**提供了什么」，
+* 而不是「我们 inject 了什么」。两者的差就是「可选能力在这台内核上可用与否」。
+*/
+const OPTIONAL_SERVICE_NAMES = [
+	"permissionPresets",
+	"jobController",
+	"fileUploads",
+	"attachments",
+	"workingDirectory",
+	"workspaceFiles"
+];
+/**
+* 在注入属性**仍可读**的时机（即 `apply` 执行期间）逐个试读服务。
+*
+* 为什么必须在 apply 期间读、不能留到 HTTP 回调里：cordis 的注入属性是
+* 有生命周期的惰性访问器，`apply` 一结束就读不到了（会抛
+* `cannot get property "attachments" without inject`）。这正是
+* dsh-0.2-bridge.ts 里 `optionalService` 那段注释记的教训 ——
+* 2.0.1 把读取留到回调里，结果整个插件激活失败。
+*
+* @param host - `ctx` 本身（不是取到的服务对象）。
+* @returns 每个服务的可解析性报告。
+*/
+function probeHostServices(host, pluginVersion) {
+	const reflect = host.reflect;
+	const probeOptional = (name) => {
+		if (reflect === void 0 || typeof reflect.get !== "function") return {
+			name,
+			available: false,
+			resolvable: false,
+			error: "ctx.reflect.get unavailable on this cordis"
+		};
+		try {
+			const value = reflect.get(name, false);
+			const resolvable = value !== null && value !== void 0;
+			return {
+				name,
+				available: true,
+				resolvable,
+				...resolvable ? {} : { error: "not provided by this kernel/profile" }
+			};
+		} catch (caught) {
+			return {
+				name,
+				available: false,
+				resolvable: false,
+				error: caught instanceof Error ? caught.message : String(caught)
+			};
+		}
+	};
+	const probeOne = (name) => {
+		let available = false;
+		let resolvable = false;
+		let error;
+		try {
+			const value = host[name];
+			available = true;
+			resolvable = value !== null && value !== void 0;
+			if (!resolvable) error = "resolved to null/undefined";
+		} catch (caught) {
+			error = caught instanceof Error ? caught.message : String(caught);
+		}
+		return {
+			name,
+			available,
+			resolvable,
+			...error === void 0 ? {} : { error }
+		};
+	};
+	const injected = INJECTED_SERVICE_NAMES.map(probeOne);
+	const observed = OPTIONAL_SERVICE_NAMES.map(probeOptional);
+	return {
+		pluginVersion,
+		injected,
+		observed,
+		summary: {
+			injectedTotal: injected.length,
+			injectedAvailable: injected.filter((service) => service.available).length,
+			injectedMissing: injected.filter((service) => !service.available).map((service) => service.name),
+			observedAvailable: observed.filter((service) => service.resolvable).map((service) => service.name)
+		}
+	};
+}
+//#endregion
+//#region src/host/job-adapter.ts
+/**
+* job 适配层的错误。
+*
+* **继承 `ApiError` 而不是另起一套**：两者的形状（status + code + message）
+* 完全一致，继承之后 router 现有的 `asApiError` 直接就能把它转成正确的
+* HTTP 响应，不必在路由里再写一层转换。这是刻意少造一个概念。
+*/
+var JobApiError = class extends ApiError {};
+/** 把内核 `JobView` 收敛成对外形状。
+*
+* 只挑客户端真用得上的字段，并且**逐个校验类型** —— 内核返回的是结构类型，
+* 一个字段形状变了就该在这里显形，而不是把一个 `undefined` 透给客户端
+* 让它的严格解码器报 `Field 'x' is required`。
+*/
+function toJobView(raw) {
+	if (raw === null || typeof raw !== "object") throw new JobApiError(502, "JOB_SHAPE_INVALID", "The kernel returned a malformed job row.");
+	const job = raw;
+	const id = job["id"];
+	const kind = job["kind"];
+	const label = job["label"];
+	const status = job["status"];
+	const startedAt = job["startedAt"];
+	if (typeof id !== "string" || typeof kind !== "string" || typeof label !== "string") throw new JobApiError(502, "JOB_SHAPE_INVALID", "The kernel returned a job row without id/kind/label.");
+	if (typeof status !== "string" || ![
+		"running",
+		"stopping",
+		"completed",
+		"killed",
+		"failed"
+	].includes(status)) throw new JobApiError(502, "JOB_SHAPE_INVALID", `The kernel returned an unknown job status: ${String(status)}`);
+	if (typeof startedAt !== "number") throw new JobApiError(502, "JOB_SHAPE_INVALID", "The kernel returned a job row without startedAt.");
+	const owner = job["owner"];
+	const progress = job["progress"];
+	const detail = job["detail"];
+	const finishedAt = job["finishedAt"];
+	return {
+		id,
+		kind,
+		label,
+		...typeof owner === "string" ? { owner } : {},
+		status,
+		...typeof progress === "string" ? { progress } : {},
+		...typeof detail === "string" ? { detail } : {},
+		startedAt,
+		...typeof finishedAt === "number" ? { finishedAt } : {}
+	};
+}
+var JobAdapter = class {
+	host;
+	constructor(host) {
+		this.host = host;
+	}
+	/**
+	* 列出某个会话可见的后台任务。
+	*
+	* 读流的**第一帧**（内核保证它是全量 truth）。若流首帧就不是 `rows`
+	* （内核升级改了帧型），明确报错而不是返回空清单 ——
+	* 空清单会被客户端理解成「没有任务」，那是**假的**。
+	*/
+	async list(sessionId, signal) {
+		const frame = (await this.host.jobController.list({ sessionId }, signal)[Symbol.asyncIterator]().next()).value;
+		if (frame === void 0 || frame === null) throw new JobApiError(502, "JOB_STREAM_EMPTY", "The job roster stream closed before its first frame.");
+		if (frame.type !== "rows") throw new JobApiError(502, "JOB_FRAME_UNKNOWN", `Unexpected first job frame: ${String(frame.type)}`);
+		const jobs = frame.jobs;
+		if (!Array.isArray(jobs)) throw new JobApiError(502, "JOB_SHAPE_INVALID", "The job roster frame carried no rows array.");
+		return { jobs: jobs.map(toJobView) };
+	}
+	/**
+	* 读一个任务已保留的输出（从指定字节偏移继续）。
+	*
+	* 内核的 `follow` 是流：`opened` 锚点 → 若干 `output` 批次 → 终态 `status`。
+	* 这里**只读到第一个终态帧或流结束为止**，把批次摊平成一个文本块 ——
+	* 手机端要看的是「这任务打印了什么」，不是逐帧的字节偏移记账。
+	*
+	* 但 `next` 偏移会一并返回：客户端想增量续读时，拿它当 `from` 再调一次即可，
+	* 不必从头拉。`lossy` 也透出去，让客户端知道「有字节被留存策略吃掉了」，
+	* 而不是把一段对不上的输出当成完整的。
+	*/
+	async follow(sessionId, jobId, from, signal) {
+		const stream = this.host.jobController.follow({
+			sessionId,
+			jobId,
+			...from === void 0 ? {} : { from }
+		}, signal);
+		const parts = [];
+		let next = from ?? 0;
+		let lossy = false;
+		let status;
+		let sawOpened = false;
+		try {
+			for await (const frame of stream) {
+				if (frame === null || typeof frame !== "object") continue;
+				if (frame.type === "opened") {
+					sawOpened = true;
+					status = toJobView(frame.job).status;
+					next = typeof frame.from === "number" ? frame.from : next;
+					continue;
+				}
+				if (frame.type === "output") {
+					const chunks = frame.chunks;
+					if (Array.isArray(chunks)) {
+						for (const chunk of chunks) if (chunk !== null && typeof chunk === "object" && typeof chunk.text === "string") parts.push(chunk.text);
+					}
+					if (typeof frame.next === "number") next = frame.next;
+					if (frame.lossy === true) lossy = true;
+					continue;
+				}
+				if (frame.type === "status") {
+					status = toJobView(frame.job).status;
+					break;
+				}
+			}
+		} catch (error) {
+			if (isJobNotFound(error)) throw new JobApiError(404, "JOB_NOT_FOUND", `No observable job ${jobId} for this session.`);
+			throw new JobApiError(502, "JOB_FOLLOW_FAILED", error instanceof Error ? error.message : String(error));
+		}
+		if (!sawOpened) throw new JobApiError(502, "JOB_STREAM_EMPTY", "The job observation stream closed before its anchor.");
+		return {
+			jobId,
+			text: parts.join(""),
+			next,
+			lossy,
+			...status === void 0 ? {} : { status }
+		};
+	}
+	/**
+	* 终止一个后台任务。
+	*
+	* 内核的 `kill` 是**同步**的，且只有 `requested` / `already-finished` 两种返回；
+	* 「这个任务不存在或该会话看不到它」走 `job/not-found` 远程错误，在这里转成 404。
+	*/
+	kill(sessionId, jobId) {
+		let value;
+		try {
+			value = this.host.jobController.kill({
+				sessionId,
+				jobId
+			});
+		} catch (error) {
+			if (isJobNotFound(error)) throw new JobApiError(404, "JOB_NOT_FOUND", `No killable job ${jobId} in this session.`);
+			throw new JobApiError(502, "JOB_KILL_FAILED", error instanceof Error ? error.message : String(error));
+		}
+		return {
+			jobId,
+			outcome: value.outcome
+		};
+	}
+};
+/** 内核 `job/not-found` 远程错误的识别。
+*
+* 内核的「任务不存在」有**两种错误形态**，判别必须都覆盖（2026-10-20 真机实测）：
+*
+* 1. **`kill`（同步 Remote 调用）**：抛带 `code: 'job/not-found'` 的 Remote 错误
+*    （`RemoteErrorDetailsMap` 里登记的那种）。看 code，不猜文案。
+* 2. **`follow` / `list`（AsyncIterable 流）**：流里 throw 的是普通
+*    `Error("unknown job <id>")`，**没有 code 元数据** —— 流帧协议里没有
+*    Remote 错误通道。只能认 message 前缀 `unknown job`。
+*
+* 这条曾漏过第二形态：output 对不存在的 job 返回 502 JOB_FOLLOW_FAILED
+* （「内核失败」）而非 404 JOB_NOT_FOUND（「任务不存在」）——
+* 客户端会把一次查错当成一次内核故障。真机一打就现形。
+*/
+function isJobNotFound(error) {
+	if (error === null || typeof error !== "object") return false;
+	const candidate = error;
+	if (candidate.code === "job/not-found") return true;
+	const details = candidate.details;
+	if (details !== null && typeof details === "object" && details.code === "job/not-found") return true;
+	if (typeof candidate.message !== "string") return false;
+	return candidate.message.includes("job/not-found") || candidate.message.startsWith("unknown job");
+}
 function normalizeListenerHost(value) {
 	if (typeof value !== "string" || value.trim() === "" || isIP(value.trim()) === 0) throw new ApiError(400, "LISTENER_HOST_INVALID", "host must be a numeric IPv4 or IPv6 address.");
 	return value.trim();
@@ -4496,20 +4931,36 @@ function timestamp() {
 //#endregion
 //#region src/host/root-resolver.ts
 /**
-* 在授权根集合里找出包含该绝对路径的那一个（**纯字符串匹配，不触碰文件系统**）。
+* 与 [matchAuthorizedRoot] 相同，但**两侧都做 realpath 归一**再比较。
+*
+* ## 为什么需要它
+*
+* 授权根在入库时走了 `canonicalRoot()`（`database.ts` 的 addRoot），存的是**解析过
+* 符号链接**的路径；而客户端请求里的路径通常**没解析**。两者字面不同就匹配不上，
+* 结果是「明明在授权根内」却报 404 `PATH_OUTSIDE_ROOTS`。
+*
+* 最常见的触发场景就是 **macOS 的临时目录**：`os.tmpdir()` 给的是
+* `/var/folders/...`，而它是指向 `/private/var/folders/...` 的**符号链接**。
+* 于是测试里 `mkdtemp(os.tmpdir())` 造出的根与请求路径字面不一致 → 404。
+* 2026-10-20 CI 在 macOS runner 上实锤（Linux 上 tmpdir 不带 symlink，所以只在 macOS 炸）。
 *
-* 多个根相互嵌套时取**最长**的那个 —— 否则外层根会把内层根下的文件解析成更长的相对路径，
-* 虽然仍能读到同一文件，但会绕过内层根更严格的授权语义。
+* 这不只是测试问题：用户给一个经 symlink 的路径加授权根、或客户端用 symlink 别名
+* 请求，都会踩到。**归一后两侧是同一条真实路径**，语义也就正确了。
 *
-* 注意这只是粗筛：字符串前缀相等不代表真实落在根内（根内可能存在指向外部的符号链接）。
-* 真正的安全校验由 [inspectResolvedPath] 经 `resolveAuthorizedPath` 完成。
+* ## 安全边界不变
+*
+* 归一只解决「同一个目录的两种写法」，**不放宽**任何权限：
+* 真正的越权校验仍由 [inspectResolvedPath] → `resolveAuthorizedPath` 逐段做
+* （它会拒绝指向根外的符号链接）。这里只是把「找哪个根」这一步做准。
 */
-function matchAuthorizedRoot(absolutePath, roots) {
+async function matchAuthorizedRootResolved(absolutePath, roots) {
+	const candidate = await canonicalOrSelf(absolutePath);
 	let best;
 	for (const root of roots) {
-		const relative = wireRelative(root.realPath, absolutePath);
+		const canonicalRoot = await canonicalOrSelf(root.realPath);
+		const relative = wireRelative(canonicalRoot, candidate);
 		if (relative === void 0) continue;
-		if (best === void 0 || root.realPath.length > best.root.realPath.length) best = {
+		if (best === void 0 || canonicalRoot.length > best.root.realPath.length) best = {
 			root,
 			relative
 		};
@@ -4519,6 +4970,14 @@ function matchAuthorizedRoot(absolutePath, roots) {
 		path: best.relative
 	};
 }
+/** 取路径的真实形式；取不到（路径不存在、无权限等）就原样返回。 */
+async function canonicalOrSelf(target) {
+	try {
+		return await realpath(target);
+	} catch {
+		return target;
+	}
+}
 const CONTENT_TYPES = {
 	".md": "text/markdown",
 	".txt": "text/plain",
@@ -4662,6 +5121,32 @@ function stringifyWire(value) {
 }
 //#endregion
 //#region src/host/router.ts
+function matchJobRoute(pathname) {
+	const jobs = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs$/);
+	if (jobs !== null) return {
+		kind: "list",
+		sessionId: decodeURIComponent(jobs[1])
+	};
+	const output = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs\/([^/]+)\/output$/);
+	if (output !== null) return {
+		kind: "output",
+		sessionId: decodeURIComponent(output[1]),
+		jobId: decodeURIComponent(output[2])
+	};
+	const kill = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs\/([^/]+)\/kill$/);
+	if (kill !== null) return {
+		kind: "kill",
+		sessionId: decodeURIComponent(kill[1]),
+		jobId: decodeURIComponent(kill[2])
+	};
+	const bare = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/jobs\/([^/]+)$/);
+	if (bare !== null) return {
+		kind: "unknown",
+		sessionId: decodeURIComponent(bare[1]),
+		jobId: decodeURIComponent(bare[2])
+	};
+	return null;
+}
 var ApiRouter = class {
 	options;
 	constructor(options) {
@@ -4706,6 +5191,12 @@ var ApiRouter = class {
 			});
 			return;
 		}
+		if (method === "GET" && pathname === "/api/v1/debug/host-services") {
+			const report = this.options.hostServiceReport;
+			if (report === void 0) throw new ApiError(404, "NOT_FOUND", "host service probe is not available in this build.");
+			sendJson(res, 200, report);
+			return;
+		}
 		if (method === "POST" && pathname === "/api/v1/pairings/exchange") {
 			this.options.auth.pairingAttempts.consume(requestAddress(req));
 			const body = await readJson(req, 16384);
@@ -4748,7 +5239,7 @@ var ApiRouter = class {
 			const requested = url.searchParams.get("path")?.trim() ?? "";
 			if (requested === "") throw new ApiError(400, "BODY_INVALID", "path is required.");
 			if (!path.isAbsolute(requested)) throw new ApiError(400, "PATH_NOT_ABSOLUTE", "path must be an absolute path.");
-			const match = matchAuthorizedRoot(path.resolve(requested), this.authorizedRoots(principal));
+			const match = await matchAuthorizedRootResolved(path.resolve(requested), this.authorizedRoots(principal));
 			if (match === void 0) throw new ApiError(404, "PATH_OUTSIDE_ROOTS", "The path is not inside any root this device may access.");
 			sendJson(res, 200, await inspectResolvedPath(this.requireRoot(principal, match.rootId), match.path));
 			return;
@@ -4990,6 +5481,35 @@ var ApiRouter = class {
 			sendJson(res, 200, { archived: true });
 			return;
 		}
+		const jobDispatch = matchJobRoute(pathname);
+		if (jobDispatch !== null) {
+			const jobs = this.options.jobs;
+			if (jobs === void 0) throw new ApiError(404, "NOT_FOUND", "Background jobs are not available in this build.");
+			if (method === "GET" && jobDispatch.kind === "list") {
+				this.options.auth.requireScope(principal, "chat.read");
+				sendJson(res, 200, await jobs.list(jobDispatch.sessionId, AbortSignal.timeout(15e3)));
+				return;
+			}
+			if (method === "GET" && jobDispatch.kind === "output") {
+				this.options.auth.requireScope(principal, "chat.read");
+				const from = url.searchParams.get("from");
+				const offset = from === null ? void 0 : Number(from);
+				if (offset !== void 0 && !Number.isFinite(offset)) throw new ApiError(400, "QUERY_INVALID", "from must be a finite byte offset.");
+				sendJson(res, 200, await jobs.follow(jobDispatch.sessionId, jobDispatch.jobId, offset, AbortSignal.timeout(3e4)));
+				return;
+			}
+			if (method === "POST" && jobDispatch.kind === "kill") {
+				this.options.auth.requireScope(principal, "chat.write");
+				const result = jobs.kill(jobDispatch.sessionId, jobDispatch.jobId);
+				this.audit(principal, "chat.job.kill", void 0, void 0, requestId, {
+					sessionId: jobDispatch.sessionId,
+					jobId: jobDispatch.jobId
+				});
+				sendJson(res, 200, result);
+				return;
+			}
+			throw new ApiError(405, "METHOD_NOT_ALLOWED", "Unsupported method for the jobs resource.");
+		}
 		const messagesRoute = pathname.match(/^\/api\/v1\/chat\/sessions\/([^/]+)\/messages$/);
 		if (messagesRoute !== null) {
 			const sessionId = decodeURIComponent(messagesRoute[1]);
@@ -6072,6 +6592,10 @@ var DshSettingsAdapter = class {
 					configurable: entry.settingsNs !== "",
 					configured,
 					removable,
+					...entry.defaultBaseURL === void 0 ? {} : { defaultBaseURL: entry.defaultBaseURL },
+					...entry.baseURLEnv === void 0 ? {} : { baseURLEnv: entry.baseURLEnv },
+					...entry.nativeAuth === void 0 ? {} : { nativeAuth: entry.nativeAuth },
+					...entry.settingsNs === "" ? {} : { settingsNs: entry.settingsNs },
 					credential: {
 						ref,
 						...credential
@@ -6111,12 +6635,18 @@ var DshSettingsAdapter = class {
 			});
 		}
 		if (patch.models !== void 0) {
-			validateModels(patch.models);
-			ops.push({
-				op: "set",
-				path: [...context.entry.settingsPath, "models"],
-				value: patch.models
+			if (patch.models === null) ops.push({
+				op: "unset",
+				path: [...context.entry.settingsPath, "models"]
 			});
+			else {
+				validateModels(patch.models);
+				ops.push({
+					op: "set",
+					path: [...context.entry.settingsPath, "models"],
+					value: patch.models
+				});
+			}
 		}
 		const ref = text(context.profile?.apiKeyEnv) ?? keyRef(providerId);
 		if (context.entry.settingsPath.length > 0 && context.profile === void 0) ops.unshift({
@@ -6366,13 +6896,10 @@ const inject = [
 	"settingsController",
 	"credentialsController",
 	"agentPresets",
-	"permissionPresets",
 	"llm",
 	"webServer",
 	"agents",
-	"commands",
-	"fileUploads",
-	"attachments"
+	"commands"
 ];
 async function apply(ctx, config = {}) {
 	const dataDir = path.resolve(config.dataDir ?? path.join(process.cwd(), ".dsh-workspace"));
@@ -6406,7 +6933,20 @@ async function apply(ctx, config = {}) {
 		commands: ctx.commands
 	});
 	const settings = new DshSettingsAdapter(apiProxy);
+	let hostServiceReport;
+	try {
+		hostServiceReport = probeHostServices(ctx, PLUGIN_VERSION);
+		const { injectedAvailable, injectedTotal, injectedMissing } = hostServiceReport.summary;
+		const detail = injectedMissing.length === 0 ? "" : `，缺失：${injectedMissing.join(", ")}`;
+		ctx.logger.info(`dsh-remote-bridge: host services ${injectedAvailable}/${injectedTotal} 可注入${detail}`);
+		if (hostServiceReport.summary.observedAvailable.length > 0) ctx.logger.info(`dsh-remote-bridge: 观测到可用但未 inject 的服务：${hostServiceReport.summary.observedAvailable.join(", ")}`);
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: host service probe failed: ${String(error)}`));
+	}
 	let router;
+	const reflect = ctx.reflect;
+	const jobControllerAvailable = reflect?.get !== void 0 && reflect.get("jobController", false) !== void 0;
+	if (!jobControllerAvailable) ctx.logger.warn(/* @__PURE__ */ new Error("dsh-remote-bridge: jobController not provided by this kernel, background-job endpoints disabled"));
 	const remote = new RemoteApiServer({
 		port,
 		remoteHost,
@@ -6426,7 +6966,9 @@ async function apply(ctx, config = {}) {
 		tunnels: new CloudflaredTunnelManager(),
 		cloudflaredBinDir: path.join(dataDir, "cloudflared-bin"),
 		maxUploadBytes,
-		imageFallbackDir: imageHandoffDir
+		imageFallbackDir: imageHandoffDir,
+		...hostServiceReport === void 0 ? {} : { hostServiceReport },
+		...jobControllerAvailable && reflect?.get ? { jobs: new JobAdapter({ jobController: reflect.get("jobController", false) }) } : {}
 	});
 	try {
 		await remote.start();