@angelky7/dsh-browser-control 1.5.0 → 1.7.0

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.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/DSH-Browser-Control-v1.5.0.zip) | Chrome extension (unzip and load; this release adds the archive command — reinstall required) |
-| [dsh-browser-control-plugin-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/dsh-browser-control-plugin-v1.5.0.zip) | dsh plugin (offline fallback; online installs use Option A/B) |
+| [DSH-Browser-Control-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/DSH-Browser-Control-v1.7.0.zip) | Chrome extension (unzip and load; this release adds the history navigation commands — reinstall required) |
+| [dsh-browser-control-plugin-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/dsh-browser-control-plugin-v1.7.0.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.5.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.0"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -256,19 +256,20 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_dialog` | Read or set the native-dialog policy accept/dismiss/manual, plus the recent dialog log (v1.0.9+) |
 | `browser_hold` | Put or remove a cancellable take-over overlay on a tab (tells the user, stops mis-clicks); `covered:false` says why it could not cover the page. A soft layer, not a security boundary |
 | `browser_cookies` | Read/set/remove cookies visible to a tab (`action: get/set/remove`; get takes a `domain` filter, set/remove need a `url` or `domain` anchor, remove re-checks and reports `remaining`). **Cookie values are credentials** — a get puts them fully into the model-visible text; see SECURITY.md |
-| `browser_tabs` | Tab management (list/open/close/activate/group/ungroup; see "What agent tabs look like") |
+| `browser_tabs` | Tab management (list/open/close/activate/group/ungroup; v1.7.0+ history back/forward — same arrival judging as navigate, reports unchanged at the history edge) |
 | `browser_evaluate` | Run arbitrary JS |
-| `browser_screenshot` | Capture page screenshot |
+| `browser_screenshot` | Capture page screenshot (v1.7.0+ receipt carries the real pixel size; fullPage captures the whole scrollable page, selector captures one element) |
 | `browser_console_log` | Captured console entries, listed with their text (v1.0.7+) |
 | `browser_network_log` | Captured HTTP requests, listed with method/status/URL (v1.0.7+) |
 | `browser_network_clear` | Clear the network log buffer on its own (v1.0.7+) |
 | `browser_pdf` | Export the current page as PDF (v1.0.7+) |
 | `browser_archive` | Save the whole page as a single-file MHTML (text/images/styles inline; a greppable offline evidence snapshot — embedded scripts do not run, v1.5.0+) |
+| `browser_windows` | Window control: list / open / update state & geometry / close a whole window / move tabs across windows (the only tool that may touch window geometry, v1.6.0+) |
 | `browser_emulate` | Switch to a device viewport (mobile / desktop / custom, v1.0.7+) |
 | `browser_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-23 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
+24 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
 
 ## Architecture
 

package/README.md

@@ -64,8 +64,8 @@ Chrome 扩展（CDP 驱动）
 
 | 文件 | 说明 |
 |---|---|
-| [DSH-Browser-Control-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/DSH-Browser-Control-v1.5.0.zip) | Chrome 扩展（解压后加载；这一版扩展新增 archive 存档命令，**必须重装**） |
-| [dsh-browser-control-plugin-v1.5.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.5.0/dsh-browser-control-plugin-v1.5.0.zip) | dsh 插件（离线兜底，在线装直接用方式 A/B） |
+| [DSH-Browser-Control-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/DSH-Browser-Control-v1.7.0.zip) | Chrome 扩展（解压后加载；这一版扩展新增 tabs.back/forward 历史导航命令，**必须重装**） |
+| [dsh-browser-control-plugin-v1.7.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.7.0/dsh-browser-control-plugin-v1.7.0.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.5.0"
+dsh plugin --profile web add "github:angelky7/dsh-browser-control#v1.7.0"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -250,19 +250,20 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_dialog` | 读改原生弹窗应答策略 accept/dismiss/manual，并回最近弹窗记录（v1.0.9+） |
 | `browser_hold` | 在某个标签页上加/撤一层可取消的接管浮层（告知用户 + 防误触）；`covered:false` 时说明盖不住的原因。软层，不是安全边界 |
 | `browser_cookies` | 读/设/删某标签页可见的 cookie（`action: get/set/remove`；get 带 `domain` 过滤，set/remove 需要 `url` 或 `domain` 锚点，remove 复查并回报 `remaining`）。**cookie 的值是凭据**，get 会把值完整放进模型可见文本——见 SECURITY.md |
-| `browser_tabs` | 标签页管理（列表/新建/关闭/切换/归组/拆组；见「agent 开的标签长什么样」） |
+| `browser_tabs` | 标签页管理（列表/新建/关闭/切换/归组/拆组；v1.7.0 起支持历史 back/forward——落地判据与 navigate 同一套，历史尽头如实报 unchanged） |
 | `browser_evaluate` | 执行任意 JS |
-| `browser_screenshot` | 截取页面截图 |
+| `browser_screenshot` | 截取页面截图（v1.7.0 起回执带**真实像素尺寸**；fullPage 一张截全页、selector 只截一个元素） |
 | `browser_console_log` | 抓取页面 console 日志并逐条给出正文（v1.0.7+） |
 | `browser_network_log` | 抓取 HTTP 请求/响应并逐条给出方法/状态/URL（v1.0.7+） |
 | `browser_network_clear` | 单独清空网络日志缓冲（v1.0.7+） |
 | `browser_pdf` | 当前页导出 PDF（v1.0.7+） |
 | `browser_archive` | 整页存成单文件 MHTML（正文/图片/样式全内联，可当文本 grep 的离线证据；是快照，内嵌脚本不会跑，v1.5.0+） |
 | `browser_emulate` | 切设备视口（移动 / 桌面 / 自定义，v1.0.7+） |
+| `browser_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 23 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 24 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
 
 ## 架构
 

package/lib/index.js

@@ -117,8 +117,11 @@ const WRITE_COMMANDS = /* @__PURE__ */ new Set([
 	"tabs.closeMany",
 	"tabs.activate",
 	"dialog",
+	"tabs.back",
+	"tabs.forward",
 	"cleanup",
-	"hold"
+	"hold",
+	"windows.open"
 ]);
 /** 该命令是否可能留下副作用。 */
 function isWriteCommand(command) {
@@ -874,6 +877,7 @@ const READ_ONLY_ALLOWED = /* @__PURE__ */ new Set([
 	"tabs.list",
 	"console.log",
 	"network.log",
+	"windows.list",
 	"cookies.get"
 ]);
 /**
@@ -1183,6 +1187,10 @@ function requireTabId(args, action) {
 	if (typeof args.tabId !== "number") throw new Error(`${action} requires tabId`);
 	return args.tabId;
 }
+function requireWindowId(args, action) {
+	if (typeof args.windowId !== "number") throw new Error(`${action} requires windowId`);
+	return args.windowId;
+}
 /**
 * Every tab the caller asked to close. `tabId` and `tabIds` are both accepted
 * (a batch call that repeats one id, or passes both, must not close it twice),
@@ -1194,6 +1202,17 @@ function closeTabIds(args) {
 	if (ids.length === 0) throw new Error("close requires tabId or tabIds");
 	return ids;
 }
+/** Actual pixel dimensions straight from the PNG's IHDR chunk (width/height are
+*  big-endian at offsets 16/20 after the 8-byte signature + 4-byte length + 4-byte
+*  type). The receipt should say how big the picture IS — fullPage captures are
+*  often 3-5 viewports tall and the model cannot tell from the byte count. */
+function pngDimensions(buffer) {
+	if (buffer.length < 24 || buffer.toString("latin1", 12, 16) !== "IHDR") return {};
+	return {
+		width: buffer.readUInt32BE(16),
+		height: buffer.readUInt32BE(20)
+	};
+}
 /** Write one screenshot payload to the shots directory and return its durable location. */
 async function saveScreenshot(controller, payload) {
 	const dir = controller.shotsDir;
@@ -1204,12 +1223,15 @@ async function saveScreenshot(controller, payload) {
 	const file = path.join(dir, `${stamp}-${random}.${payload.format === "jpeg" ? "jpg" : "png"}`);
 	const buffer = Buffer.from(payload.base64, "base64");
 	await writeFile(file, buffer);
+	const dims = payload.format === "png" ? pngDimensions(buffer) : {};
 	return {
 		file,
 		bytes: buffer.length,
 		tabId: payload.tabId,
 		title: payload.tabTitle,
-		url: payload.tabUrl
+		url: payload.tabUrl,
+		...dims,
+		...payload.elementRect === void 0 ? {} : { elementRect: payload.elementRect }
 	};
 }
 /** Write one PDF payload to `path` (absolute or relative to `controller.shotsDir`)
@@ -2035,12 +2057,12 @@ function applyBrowserTools(ctx, controller) {
 	}));
 	ctx.tools.register(defineTool({
 		name: "browser_tabs",
-		description: "List tabs, or open/close/activate/group/ungroup. `close` takes one tab (`tabId`) or several (`tabIds`); the result accounts for every id, so a retry is safe.",
+		description: "List tabs, or open/close/activate/group/ungroup, or go back/forward in the tab's history. `close` takes one tab (`tabId`) or several (`tabIds`); the result accounts for every id, so a retry is safe.",
 		parameters: {
 			action: {
 				type: "string",
 				required: true,
-				description: "One of: list, open, close, activate, group, ungroup."
+				description: "One of: list, open, close, activate, group, ungroup, back, forward."
 			},
 			url: {
 				type: "string",
@@ -2048,7 +2070,7 @@ function applyBrowserTools(ctx, controller) {
 			},
 			tabId: {
 				type: "number",
-				description: "Target tab for close/activate/group."
+				description: "Target tab for close/activate/group/back/forward; defaults to the active tab for back/forward."
 			},
 			tabIds: {
 				type: "array",
@@ -2065,11 +2087,11 @@ function applyBrowserTools(ctx, controller) {
 			},
 			waitUntil: {
 				type: "string",
-				description: "For open: when the new tab counts as arrived — same tiers as browser_navigate (load default / domcontentloaded / commit / none)."
+				description: "For open/back/forward: when the navigation counts as arrived — same tiers as browser_navigate (load default / domcontentloaded / commit / none). back/forward report unchanged:true + a reason when the tab is already at the oldest/newest history entry."
 			},
 			timeoutMs: {
 				type: "number",
-				description: "For open: wait budget, overriding the waitUntil tier (load 15000, commit/domcontentloaded 4000)."
+				description: "For open/back/forward: wait budget, overriding the waitUntil tier (load 15000, commit/domcontentloaded 4000)."
 			},
 			windowId: {
 				type: "number",
@@ -2115,6 +2137,18 @@ function applyBrowserTools(ctx, controller) {
 					return ids.length === 1 ? await controller.execute("tabs.close", { tabId: ids[0] }, exec.signal) : await controller.execute("tabs.closeMany", { tabIds: ids }, exec.signal);
 				}
 				case "activate": return await controller.execute("tabs.activate", { tabId: requireTabId(args, "activate") }, exec.signal);
+				case "back":
+				case "forward": {
+					const waitUntil = args.waitUntil === void 0 ? "load" : String(args.waitUntil);
+					if (!(waitUntil in NAV_TIERS)) throw new Error(`browser_tabs ${args.action}: waitUntil must be one of none, commit, domcontentloaded, load — got "${waitUntil}"`);
+					const params = { waitUntil };
+					if (args.tabId !== void 0) params.tabId = args.tabId;
+					let budgetMs = NAV_TIERS[waitUntil];
+					if (typeof args.timeoutMs === "number" && Number.isFinite(args.timeoutMs)) budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
+					params.timeoutMs = budgetMs;
+					if (args.action === "back") return await controller.execute("tabs.back", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+					return await controller.execute("tabs.forward", params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+				}
 				case "group": return await controller.execute("tabs.group", { tabId: requireTabId(args, "group") }, exec.signal);
 				case "ungroup": {
 					const params = {};
@@ -2125,6 +2159,132 @@ function applyBrowserTools(ctx, controller) {
 			}
 		}
 	}));
+	ctx.tools.register(defineTool({
+		name: "browser_windows",
+		description: "Inspect and control browser windows: list windows with geometry and state, open a new window (optionally positioned/sized), update state (minimize / maximize / fullscreen / focus) or geometry, close a whole window (all its tabs go too), or move tabs between windows. Geometry and state changes happen only through this tool. open is the only non-idempotent action: if it times out, run action:\"list\" first — the window may already exist.",
+		parameters: {
+			action: {
+				type: "string",
+				required: true,
+				description: "One of: list, open, update, close, moveTab."
+			},
+			windowId: {
+				type: "number",
+				description: "Target window for update/close/moveTab."
+			},
+			url: {
+				type: "string",
+				description: "For open: a URL or an array of URLs (one tab each); defaults to about:blank."
+			},
+			state: {
+				type: "string",
+				description: "For open/update: normal | minimized | maximized | fullscreen."
+			},
+			left: {
+				type: "number",
+				description: "For open/update: window left edge in screen pixels."
+			},
+			top: {
+				type: "number",
+				description: "For open/update: window top edge in screen pixels."
+			},
+			width: {
+				type: "number",
+				description: "For open/update: window width in screen pixels."
+			},
+			height: {
+				type: "number",
+				description: "For open/update: window height in screen pixels."
+			},
+			focused: {
+				type: "boolean",
+				description: "For open/update: focus the window. focused:true on a minimized window restores it WITHOUT un-maximizing (state:\"normal\" would un-maximize)."
+			},
+			alwaysOnTop: {
+				type: "boolean",
+				description: "For update: keep the window above others."
+			},
+			drawAttention: {
+				type: "boolean",
+				description: "For update: flash the taskbar entry to get the user's attention without stealing focus."
+			},
+			incognito: {
+				type: "boolean",
+				description: "For open: open in incognito. Fails honestly when the extension is not allowed in incognito."
+			},
+			tabId: {
+				type: "number",
+				description: "For moveTab: one tab to move."
+			},
+			tabIds: {
+				type: "array",
+				items: { type: "number" },
+				description: "For moveTab: several tabs to move in order; each is reported individually."
+			},
+			index: {
+				type: "number",
+				description: "For moveTab: target position in the destination window; omit for the end."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: clampRendered(JSON.stringify(value))
+			}]
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Browser windows: ${args.action}`,
+			kind: "other"
+		}),
+		async execute(args, exec) {
+			switch (args.action) {
+				case "list": return await controller.execute("windows.list", {}, exec.signal);
+				case "open": {
+					const params = {};
+					if (args.url !== void 0) params.url = args.url;
+					if (args.state !== void 0) params.state = args.state;
+					if (args.incognito === true) params.incognito = true;
+					for (const k of [
+						"left",
+						"top",
+						"width",
+						"height"
+					]) if (typeof args[k] === "number") params[k] = args[k];
+					if (args.focused !== void 0) params.focused = args.focused;
+					return await controller.execute("windows.open", params, exec.signal);
+				}
+				case "update": {
+					const params = { windowId: requireWindowId(args, "update") };
+					if (args.state !== void 0) params.state = args.state;
+					for (const k of [
+						"left",
+						"top",
+						"width",
+						"height"
+					]) if (typeof args[k] === "number") params[k] = args[k];
+					if (args.focused !== void 0) params.focused = args.focused;
+					if (args.alwaysOnTop !== void 0) params.alwaysOnTop = args.alwaysOnTop;
+					if (args.drawAttention === true) params.drawAttention = true;
+					return await controller.execute("windows.update", params, exec.signal);
+				}
+				case "close": return await controller.execute("windows.close", { windowId: requireWindowId(args, "close") }, exec.signal);
+				case "moveTab": {
+					if (args.tabId === void 0 && args.tabIds === void 0) throw new Error("moveTab requires tabId or tabIds");
+					const params = { windowId: requireWindowId(args, "moveTab") };
+					if (args.tabId !== void 0) params.tabId = args.tabId;
+					if (args.tabIds !== void 0) params.tabIds = args.tabIds;
+					if (args.index !== void 0) params.index = args.index;
+					return await controller.execute("windows.moveTab", params, exec.signal);
+				}
+				default: throw new Error(`unknown windows action: ${String(args.action)} (use list|open|update|close|moveTab)`);
+			}
+		}
+	}));
 	/** Page-side ceiling of the eval race in the extension; the bridge budget adds slack on top. */
 	const EVAL_MAX_MS = 12e4;
 	ctx.tools.register(defineTool({
@@ -2194,7 +2354,7 @@ function applyBrowserTools(ctx, controller) {
 	}));
 	ctx.tools.register(defineTool({
 		name: "browser_screenshot",
-		description: "Capture the tab as PNG/JPEG, save it under the configured shots directory, and return the absolute file path.",
+		description: "Capture the tab as PNG/JPEG, save it under the configured shots directory, and return the absolute file path plus the image's real pixel size. fullPage captures the whole scrollable page in one shot (sticky/fixed headers may repeat); selector captures one element.",
 		parameters: {
 			tabId: {
 				type: "number",
@@ -2202,7 +2362,11 @@ function applyBrowserTools(ctx, controller) {
 			},
 			fullPage: {
 				type: "boolean",
-				description: "Capture beyond the viewport."
+				description: "Capture the entire scrollable page instead of just the viewport. The receipt's width/height show the real size."
+			},
+			selector: {
+				type: "string",
+				description: "CSS selector: capture just that element (scrolled into view); the receipt carries its rect."
 			},
 			format: {
 				type: "string",
@@ -2227,12 +2391,36 @@ function applyBrowserTools(ctx, controller) {
 						required: true
 					},
 					title: { type: "string" },
-					url: { type: "string" }
+					url: { type: "string" },
+					width: { type: "number" },
+					height: { type: "number" },
+					elementRect: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							x: {
+								type: "number",
+								required: true
+							},
+							y: {
+								type: "number",
+								required: true
+							},
+							w: {
+								type: "number",
+								required: true
+							},
+							h: {
+								type: "number",
+								required: true
+							}
+						}
+					}
 				}
 			},
 			render: (_args, value) => [{
 				type: "text",
-				text: `Saved ${value.file} (${value.bytes} bytes)`
+				text: `Saved ${value.file} (${value.bytes} bytes${value.width !== void 0 && value.height !== void 0 ? `, ${value.width}×${value.height}` : ""}${value.elementRect !== void 0 ? `, element at ${value.elementRect.x},${value.elementRect.y} size ${value.elementRect.w}×${value.elementRect.h}` : ""})`
 			}]
 		},
 		presentCall: () => ({
@@ -2244,6 +2432,7 @@ function applyBrowserTools(ctx, controller) {
 			const params = { format: args.format === "jpeg" ? "jpeg" : "png" };
 			if (args.tabId !== void 0) params.tabId = args.tabId;
 			if (args.fullPage !== void 0) params.fullPage = args.fullPage;
+			if (args.selector !== void 0) params.selector = args.selector;
 			return saveScreenshot(controller, await controller.execute("screenshot", params, exec.signal));
 		}
 	}));

package/lib/types/errors.js

@@ -41,6 +41,9 @@ export const HOLD_ABORTED_MARKER = 'browser-hold-aborted:';
 const WRITE_COMMANDS = new Set([
     'nav', 'click', 'input', 'press', 'scroll', 'eval', 'emulate',
     'tabs.open', 'tabs.close', 'tabs.closeMany', 'tabs.activate', 'dialog',
+    // 历史导航与 nav 同族：超时/掉线后重试可能**多跳一条**历史（第一次 back 其实
+    // 已经落了地），报 unknown 才诚实。
+    'tabs.back', 'tabs.forward',
     // 这条不是扩展命令，而是插件本地命令 `browser_cleanup`：它逐条 rm，中途失败
     // （Windows 上被占用的截图会 EPERM）时前面的文件已经没了，报 not_started
     // 就是告诉模型「什么都没发生，重试安全」，而那正好是假的。
@@ -48,6 +51,10 @@ const WRITE_COMMANDS = new Set([
     // 往页面里插一个宿主元素 = 改页面 DOM。超时/掉线之后重试，可能多留一层浮层
     //（旧的那层还挂着），所以报 unknown 而不是「没动过页面」。
     'hold',
+    // 开窗不是幂等的：超时/掉线后重试可能真的开出第二个窗口——必须报 unknown。
+    // update/close/moveTab 是幂等的（重设同一几何、关已关的窗、挪到同一位置），
+    // 按判据算读，登记在 verify_errors 的 classifiedRead 里。
+    'windows.open',
 ]);
 /** 该命令是否可能留下副作用。 */
 export function isWriteCommand(command) {

package/lib/types/index.js

@@ -289,6 +289,11 @@ function requireTabId(args, action) {
         throw new Error(`${action} requires tabId`);
     return args.tabId;
 }
+function requireWindowId(args, action) {
+    if (typeof args.windowId !== 'number')
+        throw new Error(`${action} requires windowId`);
+    return args.windowId;
+}
 /**
  * Every tab the caller asked to close. `tabId` and `tabIds` are both accepted
  * (a batch call that repeats one id, or passes both, must not close it twice),
@@ -304,6 +309,15 @@ function closeTabIds(args) {
         throw new Error('close requires tabId or tabIds');
     return ids;
 }
+/** Actual pixel dimensions straight from the PNG's IHDR chunk (width/height are
+ *  big-endian at offsets 16/20 after the 8-byte signature + 4-byte length + 4-byte
+ *  type). The receipt should say how big the picture IS — fullPage captures are
+ *  often 3-5 viewports tall and the model cannot tell from the byte count. */
+function pngDimensions(buffer) {
+    if (buffer.length < 24 || buffer.toString('latin1', 12, 16) !== 'IHDR')
+        return {};
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+}
 /** Write one screenshot payload to the shots directory and return its durable location. */
 async function saveScreenshot(controller, payload) {
     const dir = controller.shotsDir;
@@ -315,12 +329,15 @@ async function saveScreenshot(controller, payload) {
     const file = path.join(dir, `${stamp}-${random}.${payload.format === 'jpeg' ? 'jpg' : 'png'}`);
     const buffer = Buffer.from(payload.base64, 'base64');
     await writeFile(file, buffer);
+    const dims = payload.format === 'png' ? pngDimensions(buffer) : {};
     return {
         file,
         bytes: buffer.length,
         tabId: payload.tabId,
         title: payload.tabTitle,
         url: payload.tabUrl,
+        ...dims,
+        ...(payload.elementRect === undefined ? {} : { elementRect: payload.elementRect }),
     };
 }
 /** Write one PDF payload to `path` (absolute or relative to `controller.shotsDir`)
@@ -876,16 +893,16 @@ function applyBrowserTools(ctx, controller) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_tabs',
-        description: 'List tabs, or open/close/activate/group/ungroup. `close` takes one tab (`tabId`) or several (`tabIds`); the result accounts for every id, so a retry is safe.',
+        description: 'List tabs, or open/close/activate/group/ungroup, or go back/forward in the tab\'s history. `close` takes one tab (`tabId`) or several (`tabIds`); the result accounts for every id, so a retry is safe.',
         parameters: {
-            action: { type: 'string', required: true, description: 'One of: list, open, close, activate, group, ungroup.' },
+            action: { type: 'string', required: true, description: 'One of: list, open, close, activate, group, ungroup, back, forward.' },
             url: { type: 'string', description: 'URL for the open action.' },
-            tabId: { type: 'number', description: 'Target tab for close/activate/group.' },
+            tabId: { type: 'number', description: 'Target tab for close/activate/group/back/forward; defaults to the active tab for back/forward.' },
             tabIds: { type: 'array', items: { type: 'number' }, description: 'For close: every tab to close in one call. The result reports each id (closed / alreadyGone / failed) instead of stopping at the first failure.' },
             active: { type: 'boolean', description: 'Whether a newly opened tab becomes active; defaults to true.' },
             group: { type: 'boolean', description: 'For open: put the new tab in the DSH tab group. Defaults to true; pass false to keep it loose.' },
-            waitUntil: { type: 'string', description: 'For open: when the new tab counts as arrived — same tiers as browser_navigate (load default / domcontentloaded / commit / none).' },
-            timeoutMs: { type: 'number', description: 'For open: wait budget, overriding the waitUntil tier (load 15000, commit/domcontentloaded 4000).' },
+            waitUntil: { type: 'string', description: 'For open/back/forward: when the navigation counts as arrived — same tiers as browser_navigate (load default / domcontentloaded / commit / none). back/forward report unchanged:true + a reason when the tab is already at the oldest/newest history entry.' },
+            timeoutMs: { type: 'number', description: 'For open/back/forward: wait budget, overriding the waitUntil tier (load 15000, commit/domcontentloaded 4000).' },
             windowId: { type: 'number', description: 'For ungroup: only dissolve that window’s DSH group; omit to clear every window.' },
         },
         output: {
@@ -929,6 +946,28 @@ function applyBrowserTools(ctx, controller) {
                 }
                 case 'activate':
                     return await controller.execute('tabs.activate', { tabId: requireTabId(args, 'activate') }, exec.signal);
+                case 'back':
+                case 'forward': {
+                    // Same wait-shape as open: tier default load, explicit budget, bridge
+                    // margin so the reply can outlive the tier without the bridge timing out.
+                    // 两条各写一个字面量调用点（surface 台对账 execute 字面量，拼名字会瞎）。
+                    const waitUntil = args.waitUntil === undefined ? 'load' : String(args.waitUntil);
+                    if (!(waitUntil in NAV_TIERS)) {
+                        throw new Error(`browser_tabs ${args.action}: waitUntil must be one of none, commit, domcontentloaded, load — got "${waitUntil}"`);
+                    }
+                    const params = { waitUntil };
+                    if (args.tabId !== undefined)
+                        params.tabId = args.tabId;
+                    let budgetMs = NAV_TIERS[waitUntil];
+                    if (typeof args.timeoutMs === 'number' && Number.isFinite(args.timeoutMs)) {
+                        budgetMs = Math.min(NAV_MAX_MS, Math.max(100, Math.trunc(args.timeoutMs)));
+                    }
+                    params.timeoutMs = budgetMs;
+                    if (args.action === 'back') {
+                        return await controller.execute('tabs.back', params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+                    }
+                    return await controller.execute('tabs.forward', params, exec.signal, budgetMs + BRIDGE_MARGIN_MS);
+                }
                 case 'group':
                     return await controller.execute('tabs.group', { tabId: requireTabId(args, 'group') }, exec.signal);
                 case 'ungroup': {
@@ -942,6 +981,89 @@ function applyBrowserTools(ctx, controller) {
             }
         },
     }));
+    // Window control is an explicit, opt-in surface: no other tool ever touches
+    // window geometry or state (the input path only focuses), so everything the
+    // model does to the user's windows is visible as a browser_windows call.
+    ctx.tools.register(defineTool({
+        name: 'browser_windows',
+        description: 'Inspect and control browser windows: list windows with geometry and state, open a new window (optionally positioned/sized), update state (minimize / maximize / fullscreen / focus) or geometry, close a whole window (all its tabs go too), or move tabs between windows. Geometry and state changes happen only through this tool. open is the only non-idempotent action: if it times out, run action:"list" first — the window may already exist.',
+        parameters: {
+            action: { type: 'string', required: true, description: 'One of: list, open, update, close, moveTab.' },
+            windowId: { type: 'number', description: 'Target window for update/close/moveTab.' },
+            url: { type: 'string', description: 'For open: a URL or an array of URLs (one tab each); defaults to about:blank.' },
+            state: { type: 'string', description: 'For open/update: normal | minimized | maximized | fullscreen.' },
+            left: { type: 'number', description: 'For open/update: window left edge in screen pixels.' },
+            top: { type: 'number', description: 'For open/update: window top edge in screen pixels.' },
+            width: { type: 'number', description: 'For open/update: window width in screen pixels.' },
+            height: { type: 'number', description: 'For open/update: window height in screen pixels.' },
+            focused: { type: 'boolean', description: 'For open/update: focus the window. focused:true on a minimized window restores it WITHOUT un-maximizing (state:"normal" would un-maximize).' },
+            alwaysOnTop: { type: 'boolean', description: 'For update: keep the window above others.' },
+            drawAttention: { type: 'boolean', description: 'For update: flash the taskbar entry to get the user\'s attention without stealing focus.' },
+            incognito: { type: 'boolean', description: 'For open: open in incognito. Fails honestly when the extension is not allowed in incognito.' },
+            tabId: { type: 'number', description: 'For moveTab: one tab to move.' },
+            tabIds: { type: 'array', items: { type: 'number' }, description: 'For moveTab: several tabs to move in order; each is reported individually.' },
+            index: { type: 'number', description: 'For moveTab: target position in the destination window; omit for the end.' },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => [{ type: 'text', text: clampRendered(JSON.stringify(value)) }],
+        },
+        presentCall: args => ({ card: 'generic', title: `Browser windows: ${args.action}`, kind: 'other' }),
+        async execute(args, exec) {
+            switch (args.action) {
+                case 'list':
+                    return await controller.execute('windows.list', {}, exec.signal);
+                case 'open': {
+                    const params = {};
+                    if (args.url !== undefined)
+                        params.url = args.url;
+                    if (args.state !== undefined)
+                        params.state = args.state;
+                    if (args.incognito === true)
+                        params.incognito = true;
+                    for (const k of ['left', 'top', 'width', 'height']) {
+                        if (typeof args[k] === 'number')
+                            params[k] = args[k];
+                    }
+                    if (args.focused !== undefined)
+                        params.focused = args.focused;
+                    return await controller.execute('windows.open', params, exec.signal);
+                }
+                case 'update': {
+                    const params = { windowId: requireWindowId(args, 'update') };
+                    if (args.state !== undefined)
+                        params.state = args.state;
+                    for (const k of ['left', 'top', 'width', 'height']) {
+                        if (typeof args[k] === 'number')
+                            params[k] = args[k];
+                    }
+                    if (args.focused !== undefined)
+                        params.focused = args.focused;
+                    if (args.alwaysOnTop !== undefined)
+                        params.alwaysOnTop = args.alwaysOnTop;
+                    if (args.drawAttention === true)
+                        params.drawAttention = true;
+                    return await controller.execute('windows.update', params, exec.signal);
+                }
+                case 'close':
+                    return await controller.execute('windows.close', { windowId: requireWindowId(args, 'close') }, exec.signal);
+                case 'moveTab': {
+                    if (args.tabId === undefined && args.tabIds === undefined)
+                        throw new Error('moveTab requires tabId or tabIds');
+                    const params = { windowId: requireWindowId(args, 'moveTab') };
+                    if (args.tabId !== undefined)
+                        params.tabId = args.tabId;
+                    if (args.tabIds !== undefined)
+                        params.tabIds = args.tabIds;
+                    if (args.index !== undefined)
+                        params.index = args.index;
+                    return await controller.execute('windows.moveTab', params, exec.signal);
+                }
+                default:
+                    throw new Error(`unknown windows action: ${String(args.action)} (use list|open|update|close|moveTab)`);
+            }
+        },
+    }));
     /** Page-side ceiling of the eval race in the extension; the bridge budget adds slack on top. */
     const EVAL_MAX_MS = 120_000;
     ctx.tools.register(defineTool({
@@ -990,10 +1112,11 @@ function applyBrowserTools(ctx, controller) {
     }));
     ctx.tools.register(defineTool({
         name: 'browser_screenshot',
-        description: 'Capture the tab as PNG/JPEG, save it under the configured shots directory, and return the absolute file path.',
+        description: 'Capture the tab as PNG/JPEG, save it under the configured shots directory, and return the absolute file path plus the image\'s real pixel size. fullPage captures the whole scrollable page in one shot (sticky/fixed headers may repeat); selector captures one element.',
         parameters: {
             tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
-            fullPage: { type: 'boolean', description: 'Capture beyond the viewport.' },
+            fullPage: { type: 'boolean', description: 'Capture the entire scrollable page instead of just the viewport. The receipt\'s width/height show the real size.' },
+            selector: { type: 'string', description: 'CSS selector: capture just that element (scrolled into view); the receipt carries its rect.' },
             format: { type: 'string', description: '"png" (default) or "jpeg".' },
         },
         output: {
@@ -1006,9 +1129,24 @@ function applyBrowserTools(ctx, controller) {
                     tabId: { type: 'number', required: true },
                     title: { type: 'string' },
                     url: { type: 'string' },
+                    width: { type: 'number' },
+                    height: { type: 'number' },
+                    elementRect: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            x: { type: 'number', required: true },
+                            y: { type: 'number', required: true },
+                            w: { type: 'number', required: true },
+                            h: { type: 'number', required: true },
+                        },
+                    },
                 },
             },
-            render: (_args, value) => [{ type: 'text', text: `Saved ${value.file} (${value.bytes} bytes)` }],
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Saved ${value.file} (${value.bytes} bytes${value.width !== undefined && value.height !== undefined ? `, ${value.width}×${value.height}` : ''}${value.elementRect !== undefined ? `, element at ${value.elementRect.x},${value.elementRect.y} size ${value.elementRect.w}×${value.elementRect.h}` : ''})`,
+                }],
         },
         presentCall: () => ({ card: 'generic', title: 'Browser screenshot', kind: 'other' }),
         async execute(args, exec) {
@@ -1018,6 +1156,8 @@ function applyBrowserTools(ctx, controller) {
                 params.tabId = args.tabId;
             if (args.fullPage !== undefined)
                 params.fullPage = args.fullPage;
+            if (args.selector !== undefined)
+                params.selector = args.selector;
             const payload = await controller.execute('screenshot', params, exec.signal);
             return saveScreenshot(controller, payload);
         },

package/lib/types/policy.js

@@ -24,6 +24,8 @@ export const READ_ONLY_ALLOWED = new Set([
     'content', 'find', 'snapshot', 'screenshot', 'pdf', 'wait',
     // 读扩展采集到的缓冲
     'tabs.list', 'console.log', 'network.log',
+    // 读窗口清单（几何/状态/tabIds）；open/update/close/moveTab 改窗口，不在此列
+    'windows.list',
     // 读浏览器自己的状态（cookie 是凭据，但 get 不改任何东西；set/remove 不在此列）
     'cookies.get',
 ]);

package/llms.txt

@@ -35,7 +35,7 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱
 
 ## 关键文件
 
-- `src/index.ts` - 23 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 24 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
 - `src/policy.ts` - 三张互不相同的表：只读白名单、脚本命令、插件本地破坏性命令（`browser_cleanup` 不经过 `execute()`，必须自己站闸门）
 - `src/server.ts` - WebSocket 服务 + HTTP 面（鉴权、来源校验、状态页）
 - `src/ws.ts` - RFC 6455 帧编解码

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.5.0",
+  "version": "1.7.0",
   "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"
+    "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"
   },
   "publishConfig": {
     "access": "public",