dsh-remote-bridge 2.8.0 → 2.8.1

package/lib/index.js

@@ -9,6 +9,7 @@ import { pipeline } from "node:stream/promises";
 import { isIP } from "node:net";
 import { createServer } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Buffer as Buffer$1 } from "node:buffer";
 //#region src/shared/contracts.ts
 const DEVICE_SCOPES = [
@@ -3293,7 +3294,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.8.0";
+const PLUGIN_VERSION = "2.8.1";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -8370,6 +8371,101 @@ function decodeFrame(text) {
 		return null;
 	}
 }
+/**
+* **不**回显 `requestId` 的服务端帧 kind：流式分块与服务端主动推送。
+*
+* 这些帧不与「某一次请求」一一对应（一次请求可能引发 0..N 条），客户端拿它们去配对
+* 只会误伤；而 `speech-state` 例外地在处理器里手写了 `requestId`，那属于它自己的
+* 语义，注入层不覆盖（见 {@link withRequestIdEcho} 的「已有不覆盖」规则）。
+*
+* 显式列举而非前缀/启发式判断：新增推送 kind 时**必须**同步本表，否则会误注入。
+*/
+const REQUEST_ID_ECHO_EXCLUDED_KINDS = /* @__PURE__ */ new Set([
+	"hello",
+	"paired",
+	"pong",
+	"subscribed",
+	"event",
+	"question-requested",
+	"approval-requested",
+	"approval-resolved",
+	"question-resolved",
+	"speech-state",
+	"speech-transcript",
+	"speech-preparing",
+	"tasks-updated",
+	"goal-updated",
+	"session-title-changed",
+	"queue-item-updated",
+	"connection-resync-required",
+	"file-download-chunk",
+	"file-upload-chunk-accepted"
+]);
+/**
+* 反压溢出后的「你漏了 N 帧，重拉一次」提示帧 kind。
+*
+* 为什么必须有一条这样的帧：`sendFrame` 的发送队列是有界的（[SOCKET_QUEUE_LIMIT] 同量级），
+* 溢出时只能丢帧。**丢帧本身不可怕，静默丢帧才可怕** —— 客户端会以为自己看到的是完整
+* 事件流，于是本地状态与内核悄悄分叉（少了一条审批、少了一个 goal 变更），而且没有任何
+* 判据能让它发现。所以溢出时优先丢可重建的帧，并在队列排空后补一条本帧，把「静默」
+* 变成「告知」。
+*/
+const RESYNC_REQUIRED_KIND = "connection-resync-required";
+/**
+* 可重建的服务端帧：丢掉之后客户端重拉一次（history / tasks / goal）就能补齐。
+*
+* 判据是「这帧的信息是否只存在于这一帧里」：
+* - `event`（含 `chat.message.delta`）——增量文本，丢了下一个 delta 就断句，但正文在
+*   history 里，客户端按 `asOfSeq` 重拉即补齐；
+* - `tasks-updated` / `goal-updated` / `session-title-changed` / `queue-item-updated` ——
+*   都是「某某变了」的通知，真正的状态在 REST/`tasks`/`goal` 帧里可重取。
+*
+* 反过来，**应答帧一律不可重建**（丢了这次请求就永远等不到回音）、大载荷帧
+* （`history` / `file-*` / `speech-*`）也不可 —— 重发成本远高于丢弃一条 delta。
+*/
+const REBUILDABLE_SERVER_KINDS = /* @__PURE__ */ new Set([
+	"event",
+	"tasks-updated",
+	"goal-updated",
+	"session-title-changed",
+	"queue-item-updated"
+]);
+/** 该服务端帧是否属于「丢了可以重拉补齐」的类型（反压溢出时优先丢它）。 */
+function isRebuildableServerFrame(kind) {
+	return REBUILDABLE_SERVER_KINDS.has(kind);
+}
+/**
+* 从客户端帧取 `requestId`：只认非空字符串，其余（缺失 / 空串 / 非字符串）一律
+* 视为「没带」——契约规定 absent ⇒ 应答里连 `requestId` 键都不出现。
+*/
+function requestIdOf(frame) {
+	const value = frame.requestId;
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+/**
+* 给应答帧的 `data` 注入 `requestId`（纯函数，不改动入参）。
+*
+* 四条「原样返回」规则：
+* 1. 请求没带 `requestId`（absent / 空串）——不许凭空造出这个键；
+* 2. kind 属于流式或主动推送（{@link REQUEST_ID_ECHO_EXCLUDED_KINDS}）；
+* 3. `data` 不是普通对象（省略 / 数组 / `null` / 标量）——没有放的位置，改形状会破坏契约；
+* 4. `data` 里已经有 `requestId`——处理器手写的回显优先，**绝不覆盖**已验收的行为。
+*/
+function withRequestIdEcho(frame, requestId) {
+	if (requestId === void 0 || requestId === "") return frame;
+	if (REQUEST_ID_ECHO_EXCLUDED_KINDS.has(frame.kind)) return frame;
+	const data = frame.data;
+	if (data === null || typeof data !== "object" || Array.isArray(data)) return frame;
+	const record = data;
+	if ("requestId" in record) return frame;
+	return {
+		...frame,
+		data: {
+			...record,
+			requestId
+		}
+	};
+}
 //#endregion
 //#region src/host/ws-file-transfer.ts
 /**
@@ -10888,15 +10984,23 @@ var SessionHandler = class {
 	async handleSessionCreate(principal, frame) {
 		const rootId = typeof frame.rootId === "string" ? frame.rootId : void 0;
 		const cwd = typeof frame.cwd === "string" ? frame.cwd : void 0;
-		const roots = principal.rootIds;
-		const resolvedRootId = rootId ?? (roots === "all" ? "" : [...roots][0] ?? "");
+		const workspaceId = typeof frame.workspaceId === "string" && frame.workspaceId !== "" ? frame.workspaceId : void 0;
+		const agentPreset = typeof frame.agentPreset === "string" && frame.agentPreset !== "" ? frame.agentPreset : void 0;
+		const reuseBlank = typeof frame.reuseBlank === "boolean" ? frame.reuseBlank : void 0;
 		try {
-			const created = await this.chat.createSession(principal, resolvedRootId, cwd ?? "", { reuseBlank: false });
+			const created = workspaceId !== void 0 ? await this.chat.createSessionInWorkspace(principal, workspaceId, {
+				...agentPreset === void 0 ? {} : { agentPreset },
+				...reuseBlank === void 0 ? {} : { reuseBlank }
+			}) : await this.chat.createSession(principal, rootId ?? (principal.rootIds === "all" ? "" : [...principal.rootIds][0] ?? ""), cwd ?? "", {
+				...agentPreset === void 0 ? {} : { agentPreset },
+				...reuseBlank === void 0 ? {} : { reuseBlank }
+			});
 			this.sendFrame({
 				kind: "session-created",
 				data: {
 					sessionId: created.id,
-					rootId: resolvedRootId
+					...workspaceId === void 0 ? { rootId } : { workspaceId },
+					...created.agentPreset === void 0 ? {} : { agentPreset: created.agentPreset }
 				}
 			});
 		} catch (error) {
@@ -12583,7 +12687,11 @@ var MobileEventBridge = class {
 //#endregion
 //#region src/host/ws-handler.ts
 /** 单条连接的最大发送队列深度（与 /api/v1/events 保持一致）。 */
-const SOCKET_QUEUE_LIMIT = 512;
+const DEFAULT_MOBILE_QUEUE_LIMIT = 512;
+/** 同时允许的 `/ws/mobile` 连接数上限（与 PROTOCOL/API 文档承诺的 32 一致）。 */
+const DEFAULT_MOBILE_MAX_CONNECTIONS = 32;
+/** 心跳周期。连续错过 **两个** 周期才 terminate（偶发丢包不误杀）。 */
+const DEFAULT_MOBILE_HEARTBEAT_INTERVAL_MS = 3e4;
 /** 从 IncomingMessage 取单个请求头（Node 里同名头可能是数组，取第一个）。 */
 function headerValue(req, name) {
 	const raw = req.headers[name.toLowerCase()];
@@ -12623,6 +12731,15 @@ var MobileGatewayWsHandler = class {
 	auth;
 	capabilitiesFlags;
 	sockets = /* @__PURE__ */ new Map();
+	/**
+	* 当前异步上下文里正在处理的那一帧客户端请求的 `requestId`。
+	*
+	* **为什么必须是 AsyncLocalStorage 而不是实例字段/闭包变量**：`webSocket.on('message')`
+	* 里是 `void this.handleMessage(...)`（不 await），同一条连接可以同时有多个请求在途；
+	* 任何「先存起来、发送时再读」的共享槽位都会把并发请求的 id 串到一起。ALS 把上下文
+	* 绑定在**这条 await 链**上，`await` 穿过它、并发分支各持一份，互不可见。
+	*/
+	frameRequestId = new AsyncLocalStorage();
 	settingsService;
 	filesService;
 	/**
@@ -12653,11 +12770,22 @@ var MobileGatewayWsHandler = class {
 		if (this.speech === void 0) this.speech = new SpeechHandler(remote, (key) => (frame) => this.sendFrame(key, frame));
 		else this.speech.setRemote(remote);
 	}
-	constructor(database, chat, auth, events, capabilitiesFlags) {
+	/** 同时允许的连接数上限（鉴权后计数；server.ts 在 Upgrade 前据此回 429）。 */
+	maxConnections;
+	/** 心跳周期：每周期 ping 一次，连续两个周期没回 pong 就 terminate。 */
+	heartbeatIntervalMs;
+	/** 单连接发送队列深度（溢出时先丢可重建帧）。 */
+	queueLimit;
+	/** 心跳定时器（首个连接接入时惰性启动，{@link stop} 时清掉）。 */
+	heartbeatTimer;
+	constructor(database, chat, auth, events, capabilitiesFlags, options = {}) {
 		this.database = database;
 		this.chat = chat;
 		this.auth = auth;
 		this.capabilitiesFlags = capabilitiesFlags;
+		this.maxConnections = Math.max(1, options.maxConnections ?? DEFAULT_MOBILE_MAX_CONNECTIONS);
+		this.heartbeatIntervalMs = Math.max(1, options.heartbeatIntervalMs ?? DEFAULT_MOBILE_HEARTBEAT_INTERVAL_MS);
+		this.queueLimit = Math.max(1, options.queueLimit ?? DEFAULT_MOBILE_QUEUE_LIMIT);
 		this.eventBridge = new MobileEventBridge(events, makeEventAuthorizer(chat), (conn, event) => this.sendFrame(conn, {
 			kind: "event",
 			data: event
@@ -12793,6 +12921,7 @@ var MobileGatewayWsHandler = class {
 			queue: [],
 			draining: false,
 			isAlive: true,
+			dropped: 0,
 			subscribed: void 0,
 			handlers: {
 				sessions: new SessionHandler(this.chat, (frame) => this.sendFrame(webSocket, frame), this.database),
@@ -12810,6 +12939,7 @@ var MobileGatewayWsHandler = class {
 		};
 		this.sockets.set(webSocket, state);
 		this.eventBridge.attach(webSocket, state.principal);
+		this.startHeartbeat();
 		webSocket.on("pong", () => {
 			state.isAlive = true;
 		});
@@ -12883,6 +13013,15 @@ var MobileGatewayWsHandler = class {
 			rootIds: [...principal.rootIds]
 		};
 	}
+	/**
+	* 收到一条文本帧的入口：解码 → 校验 → **绑定 requestId 上下文** → 分发。
+	*
+	* 这里同时是唯一的异常兜底点。调用方是 `webSocket.on('message')` 里的
+	* `void this.handleMessage(...)`（不 await），任何从这里冒出去的 rejection 都会成为
+	* 进程级 unhandledRejection —— DSH 宿主装了 `installFailLoud`，直接 `proc.exit(1)`。
+	* 而 `handleHistory` 等基础帧是直接 `await this.chat.*`，一次越权的 `sessionId` 就能抛
+	* `ApiError(404, 'SESSION_NOT_FOUND')`。所以分发必须整体包在 try/catch 里。
+	*/
 	async handleMessage(webSocket, state, text) {
 		const frame = decodeFrame(text);
 		if (frame === null || typeof frame !== "object" || Array.isArray(frame)) {
@@ -12895,6 +13034,17 @@ var MobileGatewayWsHandler = class {
 			this.sendError(webSocket, "MISSING_TYPE", "Frame missing \"type\" field.");
 			return;
 		}
+		const requestId = requestIdOf(clientFrame);
+		await this.frameRequestId.run(requestId, async () => {
+			try {
+				await this.routeFrame(webSocket, state, clientFrame, type);
+			} catch (error) {
+				this.reportFrameError(webSocket, type, error);
+			}
+		});
+	}
+	/** 把一帧已解码、已校验的请求分发给对应的处理器（异常由 {@link handleMessage} 兜底）。 */
+	async routeFrame(webSocket, state, clientFrame, type) {
 		switch (type) {
 			case "ping":
 				this.handlePing(webSocket);
@@ -13057,13 +13207,14 @@ var MobileGatewayWsHandler = class {
 		const opts = {};
 		if (beforeSeq !== void 0) opts.beforeSeq = beforeSeq;
 		if (maxMessages !== void 0) opts.maxMessages = maxMessages;
-		const { events, hasMore } = await this.chat.history(state.principal, sessionId, opts);
+		const { events, hasMore, projections } = await this.chat.history(state.principal, sessionId, opts);
 		this.sendFrame(webSocket, {
 			kind: "history",
 			data: {
 				sessionId,
 				events,
-				hasMore
+				hasMore,
+				...beforeSeq !== void 0 || projections === void 0 ? {} : { projections }
 			}
 		});
 	}
@@ -13090,10 +13241,17 @@ var MobileGatewayWsHandler = class {
 			}
 		});
 	}
-	/** 向一条连接发一条帧（带背压队列）。 */
+	/**
+	* 向一条连接发一条帧（带背压队列）。
+	*
+	* 应答帧统一在这里回显 `requestId`：从 {@link frameRequestId} 取**当前异步上下文**的
+	* requestId，交给 {@link withRequestIdEcho} 决定要不要塞进 `data`。处理器无需再各自
+	* 复制一遍（已手写回显的处理器不受影响 —— 注入规则是「`data` 里已有就不覆盖」）。
+	*/
 	sendFrame(webSocket, frame) {
 		const state = this.stateOf(webSocket);
-		const text = encodeFrame(frame);
+		const text = encodeFrame(withRequestIdEcho(frame, this.frameRequestId.getStore()));
+		const rebuildable = isRebuildableServerFrame(frame.kind);
 		const send = () => {
 			if (webSocket.readyState !== WebSocket.OPEN) return;
 			try {
@@ -13102,8 +13260,30 @@ var MobileGatewayWsHandler = class {
 				this.sockets.delete(webSocket);
 			}
 		};
-		if (state.queue.length >= SOCKET_QUEUE_LIMIT) state.queue.shift();
-		state.queue.push(send);
+		this.enqueue(webSocket, state, {
+			send,
+			rebuildable
+		});
+	}
+	/**
+	* 压入发送队列，队列满时**先牺牲可重建的帧**。
+	*
+	* 与 `/api/v1/events`（server.ts 的 `enqueue`）同一套取舍，只是这里没有「可重建事件
+	* 标记表」可用，改用 kind 判据。为什么不能无脑 `shift()` 丢最旧：最旧的那条可能正是
+	* 某次请求的**应答**，丢掉它客户端就会一直等到超时（而它等的那个东西其实早成功了），
+	* 反过来一条 `chat.message.delta` 丢了只影响一句的流式观感，history 一拉就齐。
+	*
+	* 被丢的帧数累加到 `state.dropped`，由 {@link drain} 在排空后补一条
+	* `connection-resync-required` 告知客户端 —— **静默丢帧比丢帧本身更糟**。
+	*/
+	enqueue(webSocket, state, item) {
+		if (state.queue.length >= this.queueLimit) {
+			const victim = state.queue.findIndex((entry) => entry.rebuildable);
+			if (victim >= 0) state.queue.splice(victim, 1);
+			else state.queue.shift();
+			state.dropped += 1;
+		}
+		state.queue.push(item);
 		if (!state.draining) {
 			state.draining = true;
 			this.drain(webSocket, state);
@@ -13119,15 +13299,58 @@ var MobileGatewayWsHandler = class {
 			}
 		});
 	}
-	/** 把队列里的帧逐条发出去。 */
+	/**
+	* 把分发过程中冒出来的异常变成一条 `error` 帧（范式与各域处理器的 `reportError` 一致）。
+	*
+	* **这里的 try/catch 不是多余的**：`sendFrame` 第一行就是 `this.stateOf(webSocket)`，而
+	* `teardown` 会在 `close`/`error` 时把连接从 `sockets` 摘掉。连接已断时 `stateOf` 抛
+	* `ApiError(4001, 'NOT_AUTHENTICATED')` —— 在 catch 块里再抛一次，就等于没修。
+	*/
+	reportFrameError(webSocket, type, error) {
+		const data = error instanceof ApiError ? {
+			code: error.code,
+			message: error.message,
+			statusCode: error.status,
+			requestType: type
+		} : {
+			code: "INTERNAL_ERROR",
+			message: "Frame handling failed.",
+			requestType: type
+		};
+		try {
+			this.sendFrame(webSocket, {
+				kind: "error",
+				data
+			});
+		} catch {}
+	}
+	/**
+	* 把队列里的帧逐条发出去，排空后按需补一条「你漏了 N 帧」的告知帧。
+	*
+	* 补发放在**排空之后**而不是溢出当场：溢出那一刻队列正满，插一条进去还得再挤掉别人；
+	* 等排空再补，既不会二次溢出，也能把同一段时间内多次溢出合并成一条（`dropped` 累加）。
+	*/
 	async drain(webSocket, state) {
 		while (state.queue.length > 0) {
-			const send = state.queue.shift();
-			if (send === void 0) break;
-			send();
+			const item = state.queue.shift();
+			if (item === void 0) break;
+			item.send();
 			await new Promise((resolve) => setImmediate(resolve));
 		}
 		state.draining = false;
+		if (state.dropped > 0) {
+			const dropped = state.dropped;
+			state.dropped = 0;
+			try {
+				this.sendFrame(webSocket, {
+					kind: RESYNC_REQUIRED_KIND,
+					data: {
+						dropped,
+						reason: "backpressure"
+					}
+				});
+			} catch {}
+		}
 	}
 	/** 拒绝未鉴权连接（401 close code）。 */
 	closeUnauthorized(webSocket) {
@@ -13143,6 +13366,7 @@ var MobileGatewayWsHandler = class {
 	}
 	/** 关闭所有连接（server.stop 时调用）。 */
 	async stop(timeoutMs = 1e3) {
+		this.clearHeartbeat();
 		this.eventBridge.dispose();
 		const closures = [];
 		for (const webSocket of [...this.sockets.keys()]) closures.push(new Promise((resolve) => {
@@ -13153,6 +13377,50 @@ var MobileGatewayWsHandler = class {
 		await Promise.all(closures);
 		this.sockets.clear();
 	}
+	/**
+	* 心跳循环：每 `heartbeatIntervalMs` ping 一次，**连续错过两个周期**才 terminate。
+	*
+	* 为什么必须有这一步：`/ws/mobile` 是手机上的长连接，切网、熄屏、NAT 表项过期都会留下
+	* **半开连接** —— 内核这边没有任何事件，TCP 要等自己超时才报错（默认以分钟计），期间
+	* 这条连接一直占着 `sockets` 里的额度、每次广播还白查一遍库。API 文档承诺「连续错过
+	* 2 个心跳周期 terminate」，这里就是把它兑现。
+	*
+	* 两个刻意的取舍：
+	* - `terminate()` 而不是 `close()`：对端已经不在，优雅挥手没人收，只会多等一个超时；
+	*   `close`/`error` 里注册的 `teardown` 会照常摘表、摘事件桥、中止语音与文件传输；
+	* - 存活标记用底层 `pong` 控制帧：客户端库自动回，不需要业务代码配合（业务层的
+	*   `ping` 帧是另一回事，用于测 RTT）。
+	*/
+	startHeartbeat() {
+		if (this.heartbeatTimer !== void 0) return;
+		this.heartbeatTimer = setInterval(() => {
+			for (const [socket, state] of this.sockets) {
+				if (!state.isAlive) {
+					socket.terminate();
+					continue;
+				}
+				state.isAlive = false;
+				try {
+					socket.ping();
+				} catch {}
+			}
+		}, this.heartbeatIntervalMs);
+		this.heartbeatTimer.unref?.();
+	}
+	clearHeartbeat() {
+		if (this.heartbeatTimer === void 0) return;
+		clearInterval(this.heartbeatTimer);
+		this.heartbeatTimer = void 0;
+	}
+	/**
+	* 连接数上限（供 server.ts 在 **Upgrade 之前**判定是否回 429）。
+	*
+	* 为什么要在 upgrade 前判：升级之后就只能发 WS 关闭码，`Retry-After` 根本无法表达，
+	* 客户端也拿不到「稍后再试」这个语义（只会看到一次莫名其妙的断连）。
+	*/
+	connectionLimit() {
+		return this.maxConnections;
+	}
 	/** 当前连接数（供 metrics / 观测）。 */
 	connectionCount() {
 		return this.sockets.size;
@@ -13231,7 +13499,11 @@ var RemoteApiServer = class {
 			clientTracking: false,
 			maxPayload: Math.max(1, options.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES)
 		});
-		this.wsMobile = new MobileGatewayWsHandler(options.database, options.chat, options.auth, options.events, { jobs: options.capabilities?.jobs === true });
+		this.wsMobile = new MobileGatewayWsHandler(options.database, options.chat, options.auth, options.events, { jobs: options.capabilities?.jobs === true }, {
+			maxConnections: this.maxConnections,
+			heartbeatIntervalMs: this.heartbeatIntervalMs,
+			queueLimit: this.socketQueueLimit
+		});
 	}
 	/**
 	* 注入全局模型目录与文件浏览依赖（index.ts 在 router 装配期调用）。
@@ -13469,6 +13741,11 @@ var RemoteApiServer = class {
 		try {
 			const url = new URL(req.url ?? "/", "http://workspace.local");
 			if (this.wsMobile.ownsPath(req)) {
+				if (this.wsMobile.connectionCount() >= this.wsMobile.connectionLimit()) {
+					recordWsRejected();
+					socket.end("HTTP/1.1 429 Too Many Requests\r\nConnection: close\r\nRetry-After: 5\r\nContent-Length: 0\r\n\r\n");
+					return;
+				}
 				this.webSockets.handleUpgrade(req, socket, head, (webSocket) => {
 					this.wsMobile.onConnection(webSocket, req);
 				});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-bridge",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Versioned REST bridge for DeepSeek Harness: remote access for trusted clients (chat, files, devices) plus a Phone-settings panel inside the DSH WebUI.",
   "type": "module",
   "packageManager": "pnpm@11.19.0",