@angelky7/dsh-browser-control 1.7.7 → 1.7.8

package/README.en.md

@@ -64,8 +64,8 @@ In one line: **for "use MY browser" tasks (logged-in Bilibili, Zhihu, admin pane
 
 | File | Purpose |
 |---|---|
-| [DSH-Browser-Control-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/DSH-Browser-Control-v1.7.2.zip) | Chrome extension (unzip and load; **the extension no longer changes with feature updates from v1.7.2 on**: v1.7.3 does not touch the extension — skip this if v1.7.2 is already loaded) |
-| [dsh-browser-control-plugin-v1.7.3.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.3/dsh-browser-control-plugin-v1.7.3.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
+| [DSH-Browser-Control-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/DSH-Browser-Control-v1.7.2.zip) | Chrome extension (unzip and load; **the extension no longer changes with feature updates from v1.7.2 on**: v1.7.3–v1.7.8 do not touch the extension — skip this if v1.7.2 is already loaded) |
+| [dsh-browser-control-plugin-v1.7.8.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.8/dsh-browser-control-plugin-v1.7.8.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
 
 ## Install the Chrome extension (30 seconds)
 
@@ -104,7 +104,7 @@ npm install @angelky7/dsh-browser-control
 
 ```bash
 # Straight from GitHub
-dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.3"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.8"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"

package/README.md

@@ -64,8 +64,8 @@ Chrome 扩展（CDP 驱动）
 
 | 文件 | 说明 |
 |---|---|
-| [DSH-Browser-Control-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/DSH-Browser-Control-v1.7.2.zip) | Chrome 扩展（解压后加载；**扩展从 v1.7.2 起不再随功能更新**：v1.7.3 没有动扩展，装过 v1.7.2 的不用重装） |
-| [dsh-browser-control-plugin-v1.7.3.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.3/dsh-browser-control-plugin-v1.7.3.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
+| [DSH-Browser-Control-v1.7.2.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.2/DSH-Browser-Control-v1.7.2.zip) | Chrome 扩展（解压后加载；**扩展从 v1.7.2 起不再随功能更新**：v1.7.3–v1.7.8 都没有动扩展，装过 v1.7.2 的不用重装） |
+| [dsh-browser-control-plugin-v1.7.8.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.8/dsh-browser-control-plugin-v1.7.8.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
 
 ## 安装 Chrome 扩展（30 秒）
 
@@ -104,7 +104,7 @@ npm install @angelky7/dsh-browser-control
 
 ```bash
 # 直接从 GitHub 安装
-dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.3"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.8"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -195,7 +195,9 @@ config:
 
 被拦的命令**不会发到浏览器**（零副作用），错误码 `blocked_by_policy`，文案写明改哪个字段。
 注意 `readOnly` 单独打开**不等于**拿掉了任意脚本能力：`browser_evaluate` 能做其它工具能做的所有事，
-所以「能不能执行脚本」是单独一项。这两个开关只管模型那条工具面，HTTP 面（带 token）不受影响。
+所以「能不能执行脚本」是单独一项。`browser_wait` 带 `fn` 参数时同样在页面里执行任意 JS，
+因此按脚本调用处理（`allowScript: false` 拒；`readOnly: true` 时也拒——只放行 `selector` / `text` 两种纯查询）。
+这两个开关对工具面与 HTTP `/api/command` 一视同仁：HTTP 面的写命令同样会收到 `blocked_by_policy`（403）。
 
 ### agent 开的标签长什么样（自动归进 DSH 分组）
 

package/lib/index.js

@@ -136,7 +136,7 @@ const HINTS = {
 	extension_offline: "浏览器扩展没连上：让用户打开装了 DSH Browser Control 的那个浏览器（扩展图标应为绿色），确认端口与 Token 两边一致后再试。",
 	command_timeout: "扩展超时未回应：先别重试。用 browser_find / browser_snapshot 看页面当前状态，判断动作是否其实已经生效。",
 	link_lost: "命令在途时链路断了：动作可能已经落到页面上。先用只读工具确认页面状态，再决定是否重做。",
-	cancelled: "调用被取消：按需重新发起，不必当作错误处理。",
+	cancelled: "调用被取消：effectState=not_started 时命令确定没发出去，可以按需重新发起；unknown 时动作可能已经执行，先确认页面状态再决定，不要直接重做。",
 	not_configured: "插件还没读到配置：确认 dsh 已加载本插件（dsh plugin list）后再试。",
 	held_by_user: "这是用户在页面上的接管浮层里按下的「中止操作」，不是故障：命令一条都没有发出。先与用户确认；他同意继续之后调用 browser_hold action=off 解除，然后再继续原来的步骤。不要重试，也不要换成别的工具绕过它。",
 	blocked_by_policy: "这是本机策略拦下的，不是故障：命令没有发给浏览器（零副作用）。要放开改 profile 的 cordis.patch.yml（browser-bridge 的 readOnly / allowScript）并重启 dsh，或换成本机允许的只读工具；不要原地重试。",
@@ -190,14 +190,17 @@ var BridgeError = class extends Error {
 /**
 * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
 * 保证多次包裹不会把 code 洗掉。
+* @param params - 这次调用的参数。只有 `wait` 需要它：`fn` 是在页面里执行任意 JS，
+*   超时/掉线时与写命令同档报 `unknown`（谓词跑过就不能断言页面没被动过）；
+*   不带 `fn` 的 wait 仍是只读。
 */
-function classify(command, error) {
+function classify(command, error, params) {
 	if (error instanceof BridgeError) return error;
 	const raw = error instanceof Error ? error.message : String(error);
 	const locked = raw.startsWith("browser-locked-by-user:") ? "locked_by_user" : raw.startsWith("browser-lock-unreadable:") ? "lock_unreadable" : raw.startsWith("browser-hold-aborted:") ? "held_by_user" : void 0;
 	const markerLength = locked === "locked_by_user" ? 23 : locked === "lock_unreadable" ? 24 : locked === "held_by_user" ? 21 : 0;
 	const message = locked ? raw.slice(markerLength).trim() : raw;
-	const unknownIsPossible = isWriteCommand(command);
+	const unknownIsPossible = isWriteCommand(command) || command === "wait" && typeof params?.fn === "string" && params.fn.trim().length > 0;
 	let code;
 	if (locked !== void 0) code = locked;
 	else if (/no browser extension connected/.test(message)) code = "extension_offline";
@@ -207,7 +210,8 @@ function classify(command, error) {
 	else if (/尚未加载配置|not configured yet/.test(message)) code = "not_configured";
 	else if (/未启用|not enabled|桥接启动失败|listen EADDR|settings integration/.test(message)) code = "bridge_disabled";
 	else code = "command_failed";
-	return new BridgeError(command, code, code === "command_timeout" || code === "link_lost" ? unknownIsPossible ? "unknown" : "not_started" : code === "command_failed" ? unknownIsPossible ? "unknown" : "not_started" : "not_started", message);
+	const effectState = code === "command_timeout" || code === "link_lost" ? unknownIsPossible ? "unknown" : "not_started" : code === "command_failed" ? unknownIsPossible ? "unknown" : "not_started" : code === "cancelled" ? /cancelled before send/.test(message) ? "not_started" : unknownIsPossible ? "unknown" : "not_started" : "not_started";
+	return new BridgeError(command, code, effectState, message);
 }
 //#endregion
 //#region lib/types/server.js
@@ -286,7 +290,12 @@ var BridgeServer = class {
 	connectedAt;
 	pending = /* @__PURE__ */ new Map();
 	lastError;
-	continuationRemainder = "";
+	/**
+	* Payloads of the message being reassembled. **Buffers, not strings**: decoding
+	* each fragment with `toString('utf8')` corrupts any multi-byte character that
+	* straddles a fragment boundary. Decode once, at FIN.
+	*/
+	continuationChunks = [];
 	continuationOpen = false;
 	constructor(options) {
 		this.options = options;
@@ -391,7 +400,7 @@ var BridgeServer = class {
 		if (signal !== void 0) {
 			entry.onAbort = () => {
 				if (!this.pending.delete(id)) return;
-				entry.reject(/* @__PURE__ */ new Error(`browser command cancelled: ${command}`));
+				entry.reject(/* @__PURE__ */ new Error(`browser command cancelled after send: ${command}`));
 			};
 			signal.addEventListener("abort", entry.onAbort, { once: true });
 		}
@@ -406,7 +415,7 @@ var BridgeServer = class {
 		try {
 			return await result;
 		} catch (error) {
-			throw classify(command, error);
+			throw classify(command, error, params);
 		} finally {
 			clearTimeout(entry.timer);
 			if (entry.onAbort !== void 0 && signal !== void 0) signal.removeEventListener("abort", entry.onAbort);
@@ -544,20 +553,29 @@ var BridgeServer = class {
 				});
 				return;
 			}
-			if (typeof parsed.command !== "string" || parsed.command.length === 0) {
+			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 				this.respondJson(res, 400, {
 					ok: false,
 					error: "body must be {\"command\": \"...\", \"params\": {...}}"
 				});
 				return;
 			}
-			const timeoutMs = typeof parsed.timeoutMs === "number" ? parsed.timeoutMs : void 0;
-			this.execute(parsed.command, parsed.params ?? {}, timeoutMs === void 0 ? {} : { timeoutMs }).then((result) => this.respondJson(res, 200, {
+			const body = parsed;
+			if (typeof body.command !== "string" || body.command.length === 0) {
+				this.respondJson(res, 400, {
+					ok: false,
+					error: "body must be {\"command\": \"...\", \"params\": {...}}"
+				});
+				return;
+			}
+			const timeoutMs = typeof body.timeoutMs === "number" ? body.timeoutMs : void 0;
+			const options = timeoutMs === void 0 ? {} : { timeoutMs };
+			(this.options.httpCommand ?? ((command, params, opts) => this.execute(command, params, opts)))(body.command, body.params ?? {}, options).then((result) => this.respondJson(res, 200, {
 				ok: true,
 				result
 			}), (error) => {
 				if (error instanceof BridgeError) {
-					const status = error.code === "extension_offline" || error.code === "bridge_disabled" || error.code === "not_configured" ? 503 : error.code === "command_timeout" || error.code === "link_lost" ? 504 : 502;
+					const status = error.code === "extension_offline" || error.code === "bridge_disabled" || error.code === "not_configured" ? 503 : error.code === "command_timeout" || error.code === "link_lost" ? 504 : error.code === "blocked_by_policy" ? 403 : 502;
 					this.respondJson(res, status, error.toJSON());
 					return;
 				}
@@ -610,11 +628,15 @@ Sec-WebSocket-Accept: ${accept}\r\n\r
 		this.clientSocket = socket;
 		this.hello = void 0;
 		this.connectedAt = /* @__PURE__ */ new Date();
-		this.continuationRemainder = "";
+		this.continuationChunks = [];
 		this.continuationOpen = false;
 		this.log(`extension connected from ${socket.remoteAddress}:${socket.remotePort}`);
 		const reader = new FrameReader();
 		socket.on("data", (chunk) => {
+			if (this.clientSocket !== socket) {
+				socket.destroy();
+				return;
+			}
 			reader.push(chunk);
 			try {
 				reader.drain((frame) => this.handleFrame(frame));
@@ -637,7 +659,7 @@ Sec-WebSocket-Accept: ${accept}\r\n\r
 		switch (frame.opcode) {
 			case 1:
 			case 0:
-				this.handleText(frame.payload.toString("utf8"), frame.fin, frame.opcode);
+				this.handleText(frame.payload, frame.fin, frame.opcode);
 				return;
 			case 8:
 				this.closeClientSocket(1e3, "");
@@ -648,14 +670,14 @@ Sec-WebSocket-Accept: ${accept}\r\n\r
 			default: return;
 		}
 	}
-	handleText(text, fin, opcode) {
+	handleText(payload, fin, opcode) {
 		if (opcode === 0 && !this.continuationOpen) return;
-		if (opcode === 1) this.continuationRemainder = "";
+		if (opcode === 1) this.continuationChunks = [];
 		this.continuationOpen = opcode === 0 || !fin;
-		this.continuationRemainder += text;
+		this.continuationChunks.push(payload);
 		if (!fin) return;
-		const full = this.continuationRemainder;
-		this.continuationRemainder = "";
+		const full = Buffer.concat(this.continuationChunks).toString("utf8");
+		this.continuationChunks = [];
 		this.continuationOpen = false;
 		let msg;
 		try {
@@ -889,9 +911,22 @@ const READ_ONLY_ALLOWED = /* @__PURE__ */ new Set([
 /**
 * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
 * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+*
+* **按命令名判不够**：`wait` 的 `fn` 参数同样是在页面里执行任意 JS（扩展侧用
+* `(${fn})()` 求出谓词），只按名字看它会从只读白名单和脚本开关两道门缝里同时漏过去。
+* 所以真正判「是不是脚本」的是下面 `isScriptCall()`：命令名 + 参数一起看，
+* `wait(selector)` / `wait(text)` 仍按只读处理，`wait({fn})` 与 `eval` 同档。
 */
 const SCRIPT_COMMANDS = /* @__PURE__ */ new Set(["eval"]);
 /**
+* 这次调用会不会在页面里执行任意 JS。判据是「这次实际要做的动作」，不是命令名：
+* `wait` 只有带 `fn` 时才升级为脚本调用（`selector` / `text` 是纯查询）。
+*/
+function isScriptCall(command, params) {
+	if (SCRIPT_COMMANDS.has(command)) return true;
+	return command === "wait" && typeof params?.fn === "string" && params.fn.trim().length > 0;
+}
+/**
 * 不经过扩展、直接在插件进程里改动本机文件的命令名。
 *
 * `browser_cleanup` 走 `BridgeController.cleanup()`，**不经过 `execute()`**，所以它天然
@@ -922,7 +957,9 @@ const CONFIG_HINT = "开关在 profile 的 cordis.patch.yml 里（browser-bridge
 * @returns 拒绝时写给 agent 的整句理由；放行时 `undefined`。
 */
 function policyRefusal(command, flags, params) {
-	if (!flags.allowScript && SCRIPT_COMMANDS.has(command)) return `在页面里执行任意脚本已被关闭（allowScript: false）：命令 ${command} 被拒绝，没有向浏览器发出任何操作。要读页面内容请改用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+	const scriptCall = isScriptCall(command, params);
+	if (!flags.allowScript && scriptCall) return `在页面里执行任意脚本已被关闭（allowScript: false）：${command === "wait" ? "命令 wait 的 fn 参数（会在页面里执行任意 JS）被拒绝" : `命令 ${command} 被拒绝`}，没有向浏览器发出任何操作。要等页面就绪请改用 wait 的 selector / text（只读），读页面内容用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+	if (flags.readOnly && command === "wait" && scriptCall) return `只读模式已开启（readOnly: true）：命令 wait 的 fn 参数会在页面里执行任意 JS（可能改变页面状态），已被拒绝，没有向浏览器发出任何操作。要等页面就绪请改用 wait 的 selector / text（只读）；要放开请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
 	if (flags.readOnly && LOCAL_DESTRUCTIVE_COMMANDS.has(command)) return `只读模式已开启（readOnly: true）：命令 ${command} 会删除本机保存的截图与临时文件，删除不可逆，所以已被拒绝，没有任何文件被删除。只读档的含义是「什么都不要改」，清理属于改动；要释放磁盘请由用户自己关掉 readOnly，${CONFIG_HINT}。不要原地重试本命令。`;
 	const isReadOnlyAction = command === "hold" && params?.action === "status";
 	if (flags.readOnly && PAGE_MUTATING_COMMANDS.has(command) && !isReadOnlyAction) return `只读模式已开启（readOnly: true）：命令 ${command} 会往页面里插入一层接管浮层（改页面 DOM），已被拒绝，没有向浏览器发出任何操作。浮层是给用户看的提示层，不是安全边界；只读档里连这种「只是提示」的改动也一并拒绝。要开浮层请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
@@ -1393,7 +1430,8 @@ var BridgeController = class {
 	* Journal appends are queued and never block the command path.
 	*/
 	recordAudit(input) {
-		this.journal?.append(this.audit.record(input));
+		const entry = this.audit.record(input);
+		this.journal?.append(entry);
 	}
 	/**
 	* Current policy flags. Tools that compose several commands (browser_drag
@@ -1488,7 +1526,8 @@ var BridgeController = class {
 			port: config.port,
 			token: config.token,
 			shotsDir,
-			log: this.log
+			log: this.log,
+			httpCommand: (command, params, options) => this.execute(command, params, new AbortController().signal, options.timeoutMs)
 		});
 		try {
 			await server.start();
@@ -1560,18 +1599,35 @@ var BridgeController = class {
 	* to work; when it is gone we forget it and let the browser's active tab
 	* answer, exactly like before this feature existed.
 	*/
-	async isolateParams(command, params, sessionId, signal) {
-		if (typeof params.tabId === "number" || NO_TAB_DEFAULT_COMMANDS.has(command)) return params;
+	/**
+	* The calling session's working tab, after the same liveness probe isolateParams
+	* uses. Tools that compose several commands (browser_drag) need the id *before*
+	* issuing anything, so they must not fall back to the browser's active tab on
+	* their own — that would silently bypass session isolation.
+	*/
+	async sessionTab(signal) {
+		const sessionId = TOOL_SESSION.getStore();
+		if (sessionId === void 0) return void 0;
+		return await this.liveRecordedTab(sessionId, signal);
+	}
+	/** Recorded working tab if it is still open; a gone tab is forgotten here. */
+	async liveRecordedTab(sessionId, signal) {
 		const recorded = this.sessions.workingTab(sessionId);
-		if (recorded === void 0) return params;
+		if (recorded === void 0) return void 0;
 		const server = this.server;
 		if (server !== void 0) try {
 			const listing = await server.execute("tabs.list", {}, { signal });
 			if (!(Array.isArray(listing?.tabs) && listing.tabs.some((tab) => tab?.id === recorded))) {
 				this.sessions.release(sessionId);
-				return params;
+				return;
 			}
 		} catch {}
+		return recorded;
+	}
+	async isolateParams(command, params, sessionId, signal) {
+		if (typeof params.tabId === "number" || NO_TAB_DEFAULT_COMMANDS.has(command)) return params;
+		const recorded = await this.liveRecordedTab(sessionId, signal);
+		if (recorded === void 0) return params;
 		return {
 			...params,
 			tabId: recorded
@@ -3667,16 +3723,26 @@ async function resolveDragPoint(ctrl, tabId, target, signal) {
 	}, signal))?.nodeId ?? 0;
 	if (nodeId === 0) throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
 	await cdpCall(ctrl, tabId, "DOM.scrollIntoViewIfNeeded", { nodeId }, signal);
+	return await measureDragNode(ctrl, tabId, nodeId, selector, signal);
+}
+/**
+* Read a node's **current** viewport geometry without scrolling. Needed after the
+* *other* endpoint's scrollIntoViewIfNeeded: that scroll can move the first
+* endpoint (and this one), so coordinates measured before it are stale. DOM
+* geometry is viewport-relative; dispatching the old numbers would drag from
+* wherever the element used to be.
+*/
+async function measureDragNode(ctrl, tabId, nodeId, label, signal) {
 	let box;
 	try {
 		box = await cdpCall(ctrl, tabId, "DOM.getBoxModel", { nodeId }, signal);
 	} catch (error) {
-		throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+		throw new Error(`cannot measure ${JSON.stringify(label)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
 	}
 	const q = box?.model?.content;
-	if (!Array.isArray(q) || q.length < 8) throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+	if (!Array.isArray(q) || q.length < 8) throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(label)}`);
 	return {
-		selector,
+		selector: label,
 		x: (q[0] + q[2] + q[4] + q[6]) / 4,
 		y: (q[1] + q[3] + q[5] + q[7]) / 4,
 		width: typeof box?.model?.width === "number" ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]),
@@ -3684,6 +3750,19 @@ async function resolveDragPoint(ctrl, tabId, target, signal) {
 		nodeId
 	};
 }
+/** CSS viewport size via Page.getLayoutMetrics (no page JS, works with allowScript off). */
+async function viewportSize(ctrl, tabId, signal) {
+	try {
+		const metrics = await cdpCall(ctrl, tabId, "Page.getLayoutMetrics", {}, signal);
+		const viewport = metrics?.cssVisualViewport ?? metrics?.cssLayoutViewport;
+		const width = Number(viewport?.clientWidth);
+		const height = Number(viewport?.clientHeight);
+		if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0) return {
+			width,
+			height
+		};
+	} catch {}
+}
 /** Whether the source declares the native HTML5 `draggable` attribute. */
 async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
 	const attrs = await cdpCall(ctrl, tabId, "DOM.getAttributes", { nodeId }, signal);
@@ -3859,6 +3938,7 @@ function registerDragTool(ctx, controller) {
 			controller.requireExtensionCommand("cdp", "1.7.2");
 			if (controller.policy.readOnly) throw new Error("browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag");
 			let tabId = args.tabId;
+			if (tabId === void 0) tabId = await controller.sessionTab(exec.signal);
 			if (tabId === void 0) {
 				const listing = await controller.execute("tabs.list", {}, exec.signal);
 				if (typeof listing?.activeTabId !== "number") throw new Error("could not resolve the active tab — pass tabId explicitly");
@@ -3871,56 +3951,92 @@ function registerDragTool(ctx, controller) {
 			if (mode === "auto" && source?.nodeId !== void 0 && await sourceIsDraggable(controller, tabId, source.nodeId, exec.signal)) resolvedMode = "html5";
 			if (resolvedMode === "mouse") {
 				const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+				let sourcePoint = source;
+				let targetPoint = target;
+				if (source?.nodeId !== void 0 && target.nodeId !== void 0) {
+					sourcePoint = await measureDragNode(controller, tabId, source.nodeId, String(from.selector), exec.signal);
+					targetPoint = await measureDragNode(controller, tabId, target.nodeId, String(to.selector), exec.signal);
+				}
+				const viewport = await viewportSize(controller, tabId, exec.signal);
+				if (viewport !== void 0) {
+					const describe = (p) => `${p.selector !== void 0 ? JSON.stringify(p.selector) : "point"} at (${Math.round(p.x)},${Math.round(p.y)})`;
+					const outside = (p) => p.x < 0 || p.y < 0 || p.x > viewport.width || p.y > viewport.height;
+					if (outside(sourcePoint) || outside(targetPoint)) throw new Error(`drag endpoints are not both visible in the viewport (${describe(sourcePoint)} → ${describe(targetPoint)}, viewport ${Math.round(viewport.width)}×${Math.round(viewport.height)}) — scroll so both fit, then retry; mode:"html5" takes selectors and needs no viewport coordinates`);
+				}
 				const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === "number" ? args.steps : 12)));
-				const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+				const sx = sourcePoint.x, sy = sourcePoint.y, tx = targetPoint.x, ty = targetPoint.y;
 				const dispatch = async (params) => {
 					await cdpCall(controller, tabId, "Input.dispatchMouseEvent", params, exec.signal);
 				};
-				await dispatch({
-					type: "mouseMoved",
-					x: sx,
-					y: sy,
-					button: "none",
-					buttons: 0
-				});
-				await dispatch({
-					type: "mousePressed",
-					x: sx,
-					y: sy,
-					button: "left",
-					buttons: 1,
-					clickCount: 1
-				});
-				for (let i = 1; i <= steps; i++) {
-					const f = i / steps;
+				let pressedAt;
+				try {
 					await dispatch({
 						type: "mouseMoved",
-						x: sx + (tx - sx) * f,
-						y: sy + (ty - sy) * f,
+						x: sx,
+						y: sy,
+						button: "none",
+						buttons: 0
+					});
+					await dispatch({
+						type: "mousePressed",
+						x: sx,
+						y: sy,
+						button: "left",
+						buttons: 1,
+						clickCount: 1
+					});
+					pressedAt = {
+						x: sx,
+						y: sy
+					};
+					for (let i = 1; i <= steps; i++) {
+						const f = i / steps;
+						await dispatch({
+							type: "mouseMoved",
+							x: sx + (tx - sx) * f,
+							y: sy + (ty - sy) * f,
+							button: "left",
+							buttons: 1
+						});
+						pressedAt = {
+							x: sx + (tx - sx) * f,
+							y: sy + (ty - sy) * f
+						};
+					}
+					await dispatch({
+						type: "mouseReleased",
+						x: tx,
+						y: ty,
 						button: "left",
-						buttons: 1
+						buttons: 0,
+						clickCount: 1
+					});
+					pressedAt = void 0;
+					await dispatch({
+						type: "mouseMoved",
+						x: tx,
+						y: ty,
+						button: "none",
+						buttons: 0
 					});
+				} catch (error) {
+					if (pressedAt !== void 0) try {
+						await cdpCall(controller, tabId, "Input.dispatchMouseEvent", {
+							type: "mouseReleased",
+							x: pressedAt.x,
+							y: pressedAt.y,
+							button: "left",
+							buttons: 0,
+							clickCount: 1
+						}, new AbortController().signal);
+					} catch {}
+					throw error;
 				}
-				await dispatch({
-					type: "mouseReleased",
-					x: tx,
-					y: ty,
-					button: "left",
-					buttons: 0,
-					clickCount: 1
-				});
-				await dispatch({
-					type: "mouseMoved",
-					x: tx,
-					y: ty,
-					button: "none",
-					buttons: 0
-				});
 				return {
 					tabId,
 					mode: "mouse",
-					from: roundDragPoint(source),
-					to: roundDragPoint(target),
+					from: roundDragPoint(sourcePoint),
+					to: roundDragPoint(targetPoint),
 					steps,
 					dispatched: steps + 4,
 					elapsedMs: Date.now() - started

package/lib/types/errors.d.ts

@@ -60,5 +60,8 @@ export declare class BridgeError extends Error {
 /**
  * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
  * 保证多次包裹不会把 code 洗掉。
+ * @param params - 这次调用的参数。只有 `wait` 需要它：`fn` 是在页面里执行任意 JS，
+ *   超时/掉线时与写命令同档报 `unknown`（谓词跑过就不能断言页面没被动过）；
+ *   不带 `fn` 的 wait 仍是只读。
  */
-export declare function classify(command: string, error: unknown): BridgeError;
+export declare function classify(command: string, error: unknown, params?: Record<string, unknown>): BridgeError;

package/lib/types/errors.js

@@ -69,7 +69,7 @@ const HINTS = {
     extension_offline: '浏览器扩展没连上：让用户打开装了 DSH Browser Control 的那个浏览器（扩展图标应为绿色），确认端口与 Token 两边一致后再试。',
     command_timeout: '扩展超时未回应：先别重试。用 browser_find / browser_snapshot 看页面当前状态，判断动作是否其实已经生效。',
     link_lost: '命令在途时链路断了：动作可能已经落到页面上。先用只读工具确认页面状态，再决定是否重做。',
-    cancelled: '调用被取消：按需重新发起，不必当作错误处理。',
+    cancelled: '调用被取消：effectState=not_started 时命令确定没发出去，可以按需重新发起；unknown 时动作可能已经执行，先确认页面状态再决定，不要直接重做。',
     not_configured: '插件还没读到配置：确认 dsh 已加载本插件（dsh plugin list）后再试。',
     held_by_user: '这是用户在页面上的接管浮层里按下的「中止操作」，不是故障：命令一条都没有发出。先与用户确认；他同意继续之后调用 browser_hold action=off 解除，然后再继续原来的步骤。不要重试，也不要换成别的工具绕过它。',
     blocked_by_policy: '这是本机策略拦下的，不是故障：命令没有发给浏览器（零副作用）。要放开改 profile 的 cordis.patch.yml（browser-bridge 的 readOnly / allowScript）并重启 dsh，或换成本机允许的只读工具；不要原地重试。',
@@ -126,8 +126,11 @@ export class BridgeError extends Error {
 /**
  * 把任意底层抛出的错误归类成 BridgeError。已经分类过的原样返回，
  * 保证多次包裹不会把 code 洗掉。
+ * @param params - 这次调用的参数。只有 `wait` 需要它：`fn` 是在页面里执行任意 JS，
+ *   超时/掉线时与写命令同档报 `unknown`（谓词跑过就不能断言页面没被动过）；
+ *   不带 `fn` 的 wait 仍是只读。
  */
-export function classify(command, error) {
+export function classify(command, error, params) {
     if (error instanceof BridgeError)
         return error;
     const raw = error instanceof Error ? error.message : String(error);
@@ -144,7 +147,9 @@ export function classify(command, error) {
                 : 0;
     const message = locked ? raw.slice(markerLength).trim() : raw;
     // 写操作一旦超时或掉线，结果就是未知的；读操作永远可以安全重试。
-    const unknownIsPossible = isWriteCommand(command);
+    // wait(fn) 例外：谓词是任意 JS，按写命令同档处理（见函数顶部 @param params）。
+    const unknownIsPossible = isWriteCommand(command)
+        || (command === 'wait' && typeof params?.fn === 'string' && params.fn.trim().length > 0);
     let code;
     if (locked !== undefined)
         code = locked;
@@ -166,6 +171,10 @@ export function classify(command, error) {
         ? (unknownIsPossible ? 'unknown' : 'not_started')
         : code === 'command_failed'
             ? (unknownIsPossible ? 'unknown' : 'not_started')
-            : 'not_started';
+            // 取消分两段：写命令在 socket.write 之后才被取消时，帧已经出去了，结果未知；
+            // 「before send」的那一条确定没发，仍是 not_started。读命令没有页面副作用。
+            : code === 'cancelled'
+                ? (/cancelled before send/.test(message) ? 'not_started' : (unknownIsPossible ? 'unknown' : 'not_started'))
+                : 'not_started';
     return new BridgeError(command, code, effectState, message);
 }

package/lib/types/index.js

@@ -183,7 +183,10 @@ class BridgeController {
      * Journal appends are queued and never block the command path.
      */
     recordAudit(input) {
-        this.journal?.append(this.audit.record(input));
+        // 先记账再落盘：`this.journal?.append(this.audit.record(input))` 会让可选链
+        // 短路掉 audit.record —— journal 没开（默认就是关的）时内存审计整本丢失。
+        const entry = this.audit.record(input);
+        this.journal?.append(entry);
     }
     /**
      * Current policy flags. Tools that compose several commands (browser_drag
@@ -281,7 +284,15 @@ class BridgeController {
             this.lastError = undefined;
             return;
         }
-        const server = new BridgeServer({ port: config.port, token: config.token, shotsDir, log: this.log });
+        const server = new BridgeServer({
+            port: config.port,
+            token: config.token,
+            shotsDir,
+            log: this.log,
+            // HTTP /api/command 与工具走同一条闸门与账本：裸 server.execute() 会绕开
+            // 只读档/allowScript，而且不在审计里留下痕迹（默认 token 还是公开的那一个）。
+            httpCommand: (command, params, options) => this.execute(command, params, new AbortController().signal, options.timeoutMs),
+        });
         try {
             await server.start();
         }
@@ -349,12 +360,23 @@ class BridgeController {
      * to work; when it is gone we forget it and let the browser's active tab
      * answer, exactly like before this feature existed.
      */
-    async isolateParams(command, params, sessionId, signal) {
-        if (typeof params.tabId === 'number' || NO_TAB_DEFAULT_COMMANDS.has(command))
-            return params;
+    /**
+     * The calling session's working tab, after the same liveness probe isolateParams
+     * uses. Tools that compose several commands (browser_drag) need the id *before*
+     * issuing anything, so they must not fall back to the browser's active tab on
+     * their own — that would silently bypass session isolation.
+     */
+    async sessionTab(signal) {
+        const sessionId = TOOL_SESSION.getStore();
+        if (sessionId === undefined)
+            return undefined;
+        return await this.liveRecordedTab(sessionId, signal);
+    }
+    /** Recorded working tab if it is still open; a gone tab is forgotten here. */
+    async liveRecordedTab(sessionId, signal) {
         const recorded = this.sessions.workingTab(sessionId);
         if (recorded === undefined)
-            return params;
+            return undefined;
         const server = this.server;
         if (server !== undefined) {
             try {
@@ -362,11 +384,19 @@ class BridgeController {
                 const live = Array.isArray(listing?.tabs) && listing.tabs.some((tab) => tab?.id === recorded);
                 if (!live) {
                     this.sessions.release(sessionId);
-                    return params;
+                    return undefined;
                 }
             }
             catch { /* 列不出来就按旧行为走活动标签页 */ }
         }
+        return recorded;
+    }
+    async isolateParams(command, params, sessionId, signal) {
+        if (typeof params.tabId === 'number' || NO_TAB_DEFAULT_COMMANDS.has(command))
+            return params;
+        const recorded = await this.liveRecordedTab(sessionId, signal);
+        if (recorded === undefined)
+            return params;
         return { ...params, tabId: recorded };
     }
     /** Record the call and adopt the tab it actually touched (params or result). */
@@ -1936,21 +1966,44 @@ async function resolveDragPoint(ctrl, tabId, target, signal) {
     if (nodeId === 0)
         throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
     await cdpCall(ctrl, tabId, 'DOM.scrollIntoViewIfNeeded', { nodeId }, signal);
+    return await measureDragNode(ctrl, tabId, nodeId, selector, signal);
+}
+/**
+ * Read a node's **current** viewport geometry without scrolling. Needed after the
+ * *other* endpoint's scrollIntoViewIfNeeded: that scroll can move the first
+ * endpoint (and this one), so coordinates measured before it are stale. DOM
+ * geometry is viewport-relative; dispatching the old numbers would drag from
+ * wherever the element used to be.
+ */
+async function measureDragNode(ctrl, tabId, nodeId, label, signal) {
     let box;
     try {
         box = await cdpCall(ctrl, tabId, 'DOM.getBoxModel', { nodeId }, signal);
     }
     catch (error) {
-        throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+        throw new Error(`cannot measure ${JSON.stringify(label)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
     }
     const q = box?.model?.content;
     if (!Array.isArray(q) || q.length < 8)
-        throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+        throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(label)}`);
     const x = (q[0] + q[2] + q[4] + q[6]) / 4;
     const y = (q[1] + q[3] + q[5] + q[7]) / 4;
     const width = typeof box?.model?.width === 'number' ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]);
     const height = typeof box?.model?.height === 'number' ? box.model.height : Math.hypot(q[4] - q[2], q[5] - q[3]);
-    return { selector, x, y, width, height, nodeId };
+    return { selector: label, x, y, width, height, nodeId };
+}
+/** CSS viewport size via Page.getLayoutMetrics (no page JS, works with allowScript off). */
+async function viewportSize(ctrl, tabId, signal) {
+    try {
+        const metrics = await cdpCall(ctrl, tabId, 'Page.getLayoutMetrics', {}, signal);
+        const viewport = metrics?.cssVisualViewport ?? metrics?.cssLayoutViewport;
+        const width = Number(viewport?.clientWidth);
+        const height = Number(viewport?.clientHeight);
+        if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0)
+            return { width, height };
+    }
+    catch { /* 量不出视口就跳过边界检查，不让一条查询失败挡掉拖拽本身 */ }
+    return undefined;
 }
 /** Whether the source declares the native HTML5 `draggable` attribute. */
 async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
@@ -2098,6 +2151,8 @@ function registerDragTool(ctx, controller) {
             if (controller.policy.readOnly)
                 throw new Error('browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag');
             let tabId = args.tabId;
+            if (tabId === undefined)
+                tabId = await controller.sessionTab(exec.signal);
             if (tabId === undefined) {
                 const listing = await controller.execute('tabs.list', {}, exec.signal);
                 if (typeof listing?.activeTabId !== 'number')
@@ -2114,24 +2169,59 @@ function registerDragTool(ctx, controller) {
             }
             if (resolvedMode === 'mouse') {
                 const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+                // 目标端点的 scrollIntoViewIfNeeded 会把页面滚走，源端点先前的视口坐标就失效了；
+                // 两端都是选择器时按当前几何重测一次（getBoxModel 不滚动，不会再次互相干扰）。
+                // 若滚完后两端不在同一视口里，宁可拒绝，也不盲发一组越界坐标去拖错东西。
+                let sourcePoint = source;
+                let targetPoint = target;
+                if (source?.nodeId !== undefined && target.nodeId !== undefined) {
+                    sourcePoint = await measureDragNode(controller, tabId, source.nodeId, String(from.selector), exec.signal);
+                    targetPoint = await measureDragNode(controller, tabId, target.nodeId, String(to.selector), exec.signal);
+                }
+                const viewport = await viewportSize(controller, tabId, exec.signal);
+                if (viewport !== undefined) {
+                    const describe = (p) => `${p.selector !== undefined ? JSON.stringify(p.selector) : 'point'} at (${Math.round(p.x)},${Math.round(p.y)})`;
+                    const outside = (p) => p.x < 0 || p.y < 0 || p.x > viewport.width || p.y > viewport.height;
+                    if (outside(sourcePoint) || outside(targetPoint)) {
+                        throw new Error(`drag endpoints are not both visible in the viewport (${describe(sourcePoint)} → ${describe(targetPoint)}, viewport ${Math.round(viewport.width)}×${Math.round(viewport.height)}) — scroll so both fit, then retry; mode:"html5" takes selectors and needs no viewport coordinates`);
+                    }
+                }
                 const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === 'number' ? args.steps : 12)));
-                const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+                const sx = sourcePoint.x, sy = sourcePoint.y, tx = targetPoint.x, ty = targetPoint.y;
                 const dispatch = async (params) => {
                     await cdpCall(controller, tabId, 'Input.dispatchMouseEvent', params, exec.signal);
                 };
-                await dispatch({ type: 'mouseMoved', x: sx, y: sy, button: 'none', buttons: 0 });
-                await dispatch({ type: 'mousePressed', x: sx, y: sy, button: 'left', buttons: 1, clickCount: 1 });
-                for (let i = 1; i <= steps; i++) {
-                    const f = i / steps;
-                    await dispatch({ type: 'mouseMoved', x: sx + (tx - sx) * f, y: sy + (ty - sy) * f, button: 'left', buttons: 1 });
+                // 按住之后任何一步失败（取消、超时、CDP 报错）都必须尽力抬起：否则页面会
+                // 停在「鼠标左键按着」的状态，用户下一次点击会被当成拖拽的延续。
+                let pressedAt;
+                try {
+                    await dispatch({ type: 'mouseMoved', x: sx, y: sy, button: 'none', buttons: 0 });
+                    await dispatch({ type: 'mousePressed', x: sx, y: sy, button: 'left', buttons: 1, clickCount: 1 });
+                    pressedAt = { x: sx, y: sy };
+                    for (let i = 1; i <= steps; i++) {
+                        const f = i / steps;
+                        await dispatch({ type: 'mouseMoved', x: sx + (tx - sx) * f, y: sy + (ty - sy) * f, button: 'left', buttons: 1 });
+                        pressedAt = { x: sx + (tx - sx) * f, y: sy + (ty - sy) * f };
+                    }
+                    await dispatch({ type: 'mouseReleased', x: tx, y: ty, button: 'left', buttons: 0, clickCount: 1 });
+                    pressedAt = undefined;
+                    await dispatch({ type: 'mouseMoved', x: tx, y: ty, button: 'none', buttons: 0 });
+                }
+                catch (error) {
+                    if (pressedAt !== undefined) {
+                        // 独立信号：调用方的 signal 可能已经 abort，清扫仍要发出去。
+                        try {
+                            await cdpCall(controller, tabId, 'Input.dispatchMouseEvent', { type: 'mouseReleased', x: pressedAt.x, y: pressedAt.y, button: 'left', buttons: 0, clickCount: 1 }, new AbortController().signal);
+                        }
+                        catch { /* 清扫失败不能盖掉原始错误 */ }
+                    }
+                    throw error;
                 }
-                await dispatch({ type: 'mouseReleased', x: tx, y: ty, button: 'left', buttons: 0, clickCount: 1 });
-                await dispatch({ type: 'mouseMoved', x: tx, y: ty, button: 'none', buttons: 0 });
                 const receipt = {
                     tabId,
                     mode: 'mouse',
-                    from: roundDragPoint(source),
-                    to: roundDragPoint(target),
+                    from: roundDragPoint(sourcePoint),
+                    to: roundDragPoint(targetPoint),
                     steps,
                     dispatched: steps + 4,
                     elapsedMs: Date.now() - started,

package/lib/types/policy.d.ts

@@ -21,6 +21,11 @@ export declare const READ_ONLY_ALLOWED: ReadonlySet<string>;
 /**
  * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
  * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+ *
+ * **按命令名判不够**：`wait` 的 `fn` 参数同样是在页面里执行任意 JS（扩展侧用
+ * `(${fn})()` 求出谓词），只按名字看它会从只读白名单和脚本开关两道门缝里同时漏过去。
+ * 所以真正判「是不是脚本」的是下面 `isScriptCall()`：命令名 + 参数一起看，
+ * `wait(selector)` / `wait(text)` 仍按只读处理，`wait({fn})` 与 `eval` 同档。
  */
 export declare const SCRIPT_COMMANDS: ReadonlySet<string>;
 /**

package/lib/types/policy.js

@@ -35,8 +35,22 @@ export const READ_ONLY_ALLOWED = new Set([
 /**
  * 会执行**任意页面脚本**的扩展命令。这条与只读档分开管，因为用户可能想「可以读、
  * 也可以点，但别在我页面里跑任意 JS」——`browser_evaluate` 能绕开其他所有工具做的事。
+ *
+ * **按命令名判不够**：`wait` 的 `fn` 参数同样是在页面里执行任意 JS（扩展侧用
+ * `(${fn})()` 求出谓词），只按名字看它会从只读白名单和脚本开关两道门缝里同时漏过去。
+ * 所以真正判「是不是脚本」的是下面 `isScriptCall()`：命令名 + 参数一起看，
+ * `wait(selector)` / `wait(text)` 仍按只读处理，`wait({fn})` 与 `eval` 同档。
  */
 export const SCRIPT_COMMANDS = new Set(['eval']);
+/**
+ * 这次调用会不会在页面里执行任意 JS。判据是「这次实际要做的动作」，不是命令名：
+ * `wait` 只有带 `fn` 时才升级为脚本调用（`selector` / `text` 是纯查询）。
+ */
+function isScriptCall(command, params) {
+    if (SCRIPT_COMMANDS.has(command))
+        return true;
+    return command === 'wait' && typeof params?.fn === 'string' && params.fn.trim().length > 0;
+}
 /**
  * 不经过扩展、直接在插件进程里改动本机文件的命令名。
  *
@@ -69,9 +83,19 @@ const CONFIG_HINT = '开关在 profile 的 cordis.patch.yml 里（browser-bridge
  * @returns 拒绝时写给 agent 的整句理由；放行时 `undefined`。
  */
 export function policyRefusal(command, flags, params) {
-    if (!flags.allowScript && SCRIPT_COMMANDS.has(command)) {
-        return `在页面里执行任意脚本已被关闭（allowScript: false）：命令 ${command} 被拒绝，没有向浏览器发出任何操作。`
-            + `要读页面内容请改用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+    const scriptCall = isScriptCall(command, params);
+    if (!flags.allowScript && scriptCall) {
+        const what = command === 'wait'
+            ? '命令 wait 的 fn 参数（会在页面里执行任意 JS）被拒绝'
+            : `命令 ${command} 被拒绝`;
+        return `在页面里执行任意脚本已被关闭（allowScript: false）：${what}，没有向浏览器发出任何操作。`
+            + `要等页面就绪请改用 wait 的 selector / text（只读），读页面内容用 browser_read / browser_snapshot / browser_find；确实需要执行脚本时，${CONFIG_HINT}之后再说。`;
+    }
+    // wait 白名单是按命令名放的，但带 fn 的那一种和 eval 同档：任意 JS 可以改页面，
+    // 只读档不能因为「它叫 wait」就放行。不带 fn 的 wait 仍走下面的白名单。
+    if (flags.readOnly && command === 'wait' && scriptCall) {
+        return `只读模式已开启（readOnly: true）：命令 wait 的 fn 参数会在页面里执行任意 JS（可能改变页面状态），已被拒绝，没有向浏览器发出任何操作。`
+            + `要等页面就绪请改用 wait 的 selector / text（只读）；要放开请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
     }
     if (flags.readOnly && LOCAL_DESTRUCTIVE_COMMANDS.has(command)) {
         return `只读模式已开启（readOnly: true）：命令 ${command} 会删除本机保存的截图与临时文件，删除不可逆，所以已被拒绝，没有任何文件被删除。`

package/lib/types/server.d.ts

@@ -90,6 +90,12 @@ export interface BridgeServerOptions {
     readonly scratchDir?: string;
     /** Optional line logger for lifecycle diagnostics. */
     readonly log?: (line: string) => void;
+    /**
+     * Executor for the HTTP command face. The plugin passes its controller so
+     * `/api/command` goes through the same policy gate and audit trail as tools;
+     * without it (bare BridgeServer users, tests) the face stays raw.
+     */
+    readonly httpCommand?: (command: string, params: Record<string, unknown>, options: BridgeExecuteOptions) => Promise<unknown>;
 }
 /**
  * Clear the screenshots directory and delete agent scratch files. Only the
@@ -116,7 +122,12 @@ export declare class BridgeServer {
     private connectedAt;
     private readonly pending;
     private lastError;
-    private continuationRemainder;
+    /**
+     * Payloads of the message being reassembled. **Buffers, not strings**: decoding
+     * each fragment with `toString('utf8')` corrupts any multi-byte character that
+     * straddles a fragment boundary. Decode once, at FIN.
+     */
+    private continuationChunks;
     private continuationOpen;
     constructor(options: BridgeServerOptions);
     /** Current link state, also served verbatim as `/api/status`. */

package/lib/types/server.js

@@ -87,7 +87,12 @@ export class BridgeServer {
     connectedAt;
     pending = new Map();
     lastError;
-    continuationRemainder = '';
+    /**
+     * Payloads of the message being reassembled. **Buffers, not strings**: decoding
+     * each fragment with `toString('utf8')` corrupts any multi-byte character that
+     * straddles a fragment boundary. Decode once, at FIN.
+     */
+    continuationChunks = [];
     continuationOpen = false;
     constructor(options) {
         this.options = options;
@@ -202,7 +207,10 @@ export class BridgeServer {
             entry.onAbort = () => {
                 if (!this.pending.delete(id))
                     return;
-                entry.reject(new Error(`browser command cancelled: ${command}`));
+                // 监听器只可能在 socket.write 之后触发（execute 从注册到写出是同步的、中间
+                // 没有 await），所以这里必须说 after send：写命令的结果是未知，而不是
+                // 「取消 = 什么都没发生」。before send 的那条检查在函数开头，措辞不同。
+                entry.reject(new Error(`browser command cancelled after send: ${command}`));
             };
             signal.addEventListener('abort', entry.onAbort, { once: true });
         }
@@ -215,8 +223,9 @@ export class BridgeServer {
         catch (error) {
             // One choke point: everything above this line that can fail is a link or
             // extension failure, and the caller needs to know whether the page may
-            // already have been changed. See src/errors.ts.
-            throw classify(command, error);
+            // already have been changed. See src/errors.ts. `params` matters for wait(fn):
+            // 谓词是任意 JS，超时/取消时按写命令报 unknown。
+            throw classify(command, error, params);
         }
         finally {
             clearTimeout(entry.timer);
@@ -359,19 +368,33 @@ export class BridgeServer {
                 this.respondJson(res, 400, { ok: false, error: `invalid JSON body: ${errorMessage(error)}` });
                 return;
             }
-            if (typeof parsed.command !== 'string' || parsed.command.length === 0) {
+            // `null` parses fine and is NOT an object: without this guard the property
+            // reads below throw a TypeError inside an event callback (uncaught).
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                this.respondJson(res, 400, { ok: false, error: 'body must be {"command": "...", "params": {...}}' });
+                return;
+            }
+            const body = parsed;
+            if (typeof body.command !== 'string' || body.command.length === 0) {
                 this.respondJson(res, 400, { ok: false, error: 'body must be {"command": "...", "params": {...}}' });
                 return;
             }
-            const timeoutMs = typeof parsed.timeoutMs === 'number' ? parsed.timeoutMs : undefined;
-            this.execute(parsed.command, (parsed.params ?? {}), timeoutMs === undefined ? {} : { timeoutMs }).then((result) => this.respondJson(res, 200, { ok: true, result }), (error) => {
+            const timeoutMs = typeof body.timeoutMs === 'number' ? body.timeoutMs : undefined;
+            const options = timeoutMs === undefined ? {} : { timeoutMs };
+            // The plugin's controller carries the read-only / script gates and the audit
+            // trail; the raw execute() below is only the fallback for bare users.
+            const run = this.options.httpCommand ?? ((command, params, opts) => this.execute(command, params, opts));
+            run(body.command, (body.params ?? {}), options).then((result) => this.respondJson(res, 200, { ok: true, result }), (error) => {
                 if (error instanceof BridgeError) {
-                    // 503 = 现在根本没法工作；504 = 超时且结果未知；502 = 扩展报了具体失败
+                    // 503 = 现在根本没法工作；504 = 超时且结果未知；403 = 本机策略拦下（零副作用）；
+                    // 502 = 扩展报了具体失败
                     const status = error.code === 'extension_offline' || error.code === 'bridge_disabled' || error.code === 'not_configured'
                         ? 503
                         : error.code === 'command_timeout' || error.code === 'link_lost'
                             ? 504
-                            : 502;
+                            : error.code === 'blocked_by_policy'
+                                ? 403
+                                : 502;
                     this.respondJson(res, status, error.toJSON());
                     return;
                 }
@@ -425,11 +448,19 @@ export class BridgeServer {
         this.clientSocket = socket;
         this.hello = undefined;
         this.connectedAt = new Date();
-        this.continuationRemainder = '';
+        this.continuationChunks = [];
         this.continuationOpen = false;
         this.log(`extension connected from ${socket.remoteAddress}:${socket.remotePort}`);
         const reader = new FrameReader();
         socket.on('data', (chunk) => {
+            // A replaced connection can still deliver buffered frames. Without this
+            // guard its pong/frames would be applied to the NEW link, and its close
+            // event could tear the new socket down (the close handler already checks,
+            // the data handler did not).
+            if (this.clientSocket !== socket) {
+                socket.destroy();
+                return;
+            }
             reader.push(chunk);
             try {
                 reader.drain((frame) => this.handleFrame(frame));
@@ -454,7 +485,7 @@ export class BridgeServer {
         switch (frame.opcode) {
             case 0x1:
             case 0x0:
-                this.handleText(frame.payload.toString('utf8'), frame.fin, frame.opcode);
+                this.handleText(frame.payload, frame.fin, frame.opcode);
                 return;
             case 0x8:
                 this.closeClientSocket(1000, '');
@@ -466,17 +497,19 @@ export class BridgeServer {
                 return; // pong or binary: nothing to do
         }
     }
-    handleText(text, fin, opcode) {
+    handleText(payload, fin, opcode) {
         if (opcode === 0x0 && !this.continuationOpen)
             return; // stray continuation
         if (opcode === 0x1)
-            this.continuationRemainder = '';
+            this.continuationChunks = [];
         this.continuationOpen = opcode === 0x0 || !fin;
-        this.continuationRemainder += text;
+        this.continuationChunks.push(payload);
         if (!fin)
             return;
-        const full = this.continuationRemainder;
-        this.continuationRemainder = '';
+        // Decode only the complete message: per-fragment toString('utf8') splits
+        // multi-byte characters at fragment boundaries and corrupts the JSON.
+        const full = Buffer.concat(this.continuationChunks).toString('utf8');
+        this.continuationChunks = [];
         this.continuationOpen = false;
         let msg;
         try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angelky7/dsh-browser-control",
   "description": "Local WebSocket bridge between dsh and the DSH Browser Control browser extension, with model-facing browser_* tools and a Settings-managed on/off switch",
-  "version": "1.7.7",
+  "version": "1.7.8",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -37,7 +37,7 @@
     "build": "tsc -p tsconfig.json && tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "check": "npm run typecheck && npm run build && publint",
-    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_audit.mjs && node verify/verify_journal.mjs && node verify/verify_sessions.mjs && node verify/verify_snapshot_page.mjs && node verify/verify_compat_matrix.mjs"
+    "verify": "node verify/verify_config_patch.mjs && node verify/verify_peers.mjs && node verify/verify_surface.mjs && node verify/verify_tab_groups.mjs && node verify/verify_tabs_close_many.mjs && node verify/verify_cdp_retry.mjs && node verify/verify_snapshot_ax.mjs && node verify/verify_hard_lock.mjs && node verify/verify_policy.mjs && node verify/verify_cookies.mjs && node verify/verify_extension_e2e.mjs && node verify/verify_plugin.mjs legacy && node verify/verify_plugin.mjs conflict && node verify/verify_plugin.mjs new && node verify/verify_http.mjs && node verify/verify_errors.mjs && node verify/verify_server_hardening.mjs && node verify/verify_hold.mjs && node verify/verify_protocol.mjs && node verify/verify_bundle_http.mjs && node verify/verify_nav_report.mjs && node verify/verify_nav_landing.mjs && node verify/verify_render_contract.mjs && node verify/verify_press_events.mjs && node verify/verify_nav_timeout.mjs && node verify/verify_nav_waituntil.mjs && node verify/verify_archive.mjs && node verify/verify_windows.mjs && node verify/verify_history_nav.mjs && node verify/verify_metrics_throttle.mjs && node verify/verify_drag.mjs && node verify/verify_audit.mjs && node verify/verify_journal.mjs && node verify/verify_sessions.mjs && node verify/verify_snapshot_page.mjs && node verify/verify_compat_matrix.mjs"
   },
   "publishConfig": {
     "access": "public",