@angelky7/dsh-browser-control 1.5.0 → 1.6.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.6.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.6.0/DSH-Browser-Control-v1.6.0.zip) | Chrome extension (unzip and load; this release adds the windows commands — reinstall required) |
+| [dsh-browser-control-plugin-v1.6.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.6.0/dsh-browser-control-plugin-v1.6.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.6.0"
 
 # Local checkout for debugging (note: the explicit file: prefix is required)
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -264,11 +264,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `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.6.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.6.0/DSH-Browser-Control-v1.6.0.zip) | Chrome 扩展（解压后加载；这一版扩展新增 windows 窗口控制命令，**必须重装**） |
+| [dsh-browser-control-plugin-v1.6.0.zip](https://github.com/angelky7/dsh-browser-control/releases/download/v1.6.0/dsh-browser-control-plugin-v1.6.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.6.0"
 
 # 本地目录调试（注意：必须显式 file: 前缀）
 dsh plugin --profile web add "file:D:\path\to\dsh-browser-control"
@@ -259,10 +259,11 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `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

@@ -118,7 +118,8 @@ const WRITE_COMMANDS = /* @__PURE__ */ new Set([
 	"tabs.activate",
 	"dialog",
 	"cleanup",
-	"hold"
+	"hold",
+	"windows.open"
 ]);
 /** 该命令是否可能留下副作用。 */
 function isWriteCommand(command) {
@@ -874,6 +875,7 @@ const READ_ONLY_ALLOWED = /* @__PURE__ */ new Set([
 	"tabs.list",
 	"console.log",
 	"network.log",
+	"windows.list",
 	"cookies.get"
 ]);
 /**
@@ -1183,6 +1185,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),
@@ -2125,6 +2131,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({

package/lib/types/errors.js

@@ -48,6 +48,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),
@@ -942,6 +947,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({

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.6.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"
   },
   "publishConfig": {
     "access": "public",