@angelky7/dsh-browser-control 1.7.5 → 1.7.7

package/README.en.md

@@ -270,10 +270,11 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_drag` | Drag from/to a selector or viewport point: `auto` synthesizes html5 dragstart→dragover→drop for `draggable="true"` sources (no drop unless accepted), otherwise sends real mouse input (press, interpolated moves, release — sliders/canvas/sortable widgets). **Plugin-side only** over the cdp channel embedded in extension v1.7.2, v1.7.3+ |
 | `browser_audit` | Read this plugin session's in-memory audit trail — every command sent or refused (redacted params, `code`/`effectState`, duration), capped at 200 entries and wiped on restart; typed text and cookie values are redacted, eval expressions truncated. Plugin-local read, works in read-only mode (v1.7.4+) |
 | `browser_journal` | Read the **persistent journal across dsh restarts** (`<stateDir>/journal.jsonl`, last 1000 entries, grouped by run) — ask it after a restart "what was I doing in which tab"; same redaction; plugin-local disk read that works with the extension offline (v1.7.5+) |
+| `browser_sessions` | Multi-session isolation: list the dsh sessions sharing this browser and each one's **working tab**; `action:"release"` forgets yours. Calls that omit tabId default to THIS session's working tab (verified live) — concurrent sessions stop fighting over the active tab; explicit tabId always wins. Plugin-local, v1.7.6+ |
 | `browser_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-28 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`.
+29 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

@@ -240,7 +240,7 @@ curl -X POST http://127.0.0.1:9777/api/command \
 |---|---|
 | `browser_navigate` | 导航到 URL |
 | `browser_read` | 读取页面文本/HTML，正文直接给模型（`offset`/`limit` 窗口，长文分页） |
-| `browser_snapshot` | 页面快照 → 逐条列出 ref 的交互树（`mode:"ax"` 走 Chrome 无障碍树，拿 role + 可访问名） |
+| `browser_snapshot` | 页面快照 → 逐条列出 ref 的交互树（`mode:"ax"` 走 Chrome 无障碍树，拿 role + 可访问名）；v1.7.7 起支持 `offset` **分页**：页头写明「第几到第几 / 页面总数 / 下一页 offset」，超出扩展 200 条窗口的部分如实说明用 find/read 补齐 |
 | `browser_click` | 点击元素（by ref / selector） |
 | `browser_type` | 在输入框填入文本 |
 | `browser_press` | 模拟键盘按键（回车、Tab、方向键，以及 "Ctrl+A" / "Shift+ArrowRight" 这类组合键；一次按键只插入一次） |
@@ -263,11 +263,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_drag` | 拖拽：from/to 用选择器或视口坐标；`auto` 对 `draggable="true"` 的源走 html5 事件合成（dragstart→dragover→drop，未接受就不 drop），其余走真实鼠标输入（按下→插值移动→抬起，滑杆/画布/排序组件用这个）。**纯插件实现**（经 v1.7.2 预埋的 cdp 通道），v1.7.3+ |
 | `browser_audit` | 读本次插件会话的内存审计账本：发过/被拒的每条命令（参数脱敏、`code`/`effectState`、耗时），最多 200 条、dsh 重启即清；输入的文字与 cookie 值打码、eval 表达式截断。纯本地读，只读档下照常可用（v1.7.4+） |
 | `browser_journal` | 读**跨 dsh 重启**的持久命令账本（`<stateDir>/journal.jsonl`，最多 1000 条，按运行分组）——重启后先问它「上个会话在哪个标签页干了什么」；同样的脱敏规则；纯本地磁盘读，**扩展离线也能用**（v1.7.5+） |
+| `browser_sessions` | 多 session 隔离：列出共用这个浏览器的 dsh 会话与各自的**工作标签页**；`action:"release"` 释放自己的。省略 tabId 的调用默认落到**本会话**的工作标签页（先核验还开着），并发会话不再互相抢活动页；显式 tabId 永远有效。纯本地，v1.7.6+ |
 | `browser_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 28 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 29 个工具。`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

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -1135,6 +1136,70 @@ async function readJournal(stateDir, filter = {}) {
 	};
 }
 //#endregion
+//#region lib/types/sessions.js
+var SessionRegistry = class {
+	sessions = /* @__PURE__ */ new Map();
+	/** 记一次活动（无论成败）。 */
+	touch(sessionId) {
+		const now = Date.now();
+		const existing = this.sessions.get(sessionId);
+		if (existing === void 0) {
+			this.sessions.set(sessionId, {
+				sessionId,
+				lastActiveAt: now,
+				calls: 1,
+				createdAt: now
+			});
+			return;
+		}
+		existing.lastActiveAt = now;
+		existing.calls += 1;
+	}
+	/** 把某个标签页记为这个会话的工作标签页。 */
+	adopt(sessionId, tabId) {
+		const state = this.sessions.get(sessionId);
+		if (state === void 0) {
+			this.sessions.set(sessionId, {
+				sessionId,
+				workingTabId: tabId,
+				lastActiveAt: Date.now(),
+				calls: 0,
+				createdAt: Date.now()
+			});
+			return;
+		}
+		state.workingTabId = tabId;
+		state.lastActiveAt = Date.now();
+	}
+	/** 当前记录的工作标签页（不核对是否还开着——核对是控制器的事）。 */
+	workingTab(sessionId) {
+		return this.sessions.get(sessionId)?.workingTabId;
+	}
+	/** 清掉工作标签页；返回被清掉的 id。 */
+	release(sessionId) {
+		const state = this.sessions.get(sessionId);
+		if (state === void 0) return void 0;
+		const previous = state.workingTabId;
+		state.workingTabId = void 0;
+		return previous;
+	}
+	/** 全部会话，最近活跃的在前。 */
+	list() {
+		return [...this.sessions.values()].sort((a, b) => b.lastActiveAt - a.lastActiveAt).map((s) => {
+			const info = {
+				sessionId: s.sessionId,
+				lastActiveAt: s.lastActiveAt,
+				calls: s.calls
+			};
+			if (s.workingTabId !== void 0) info.workingTabId = s.workingTabId;
+			return info;
+		});
+	}
+	size() {
+		return this.sessions.size;
+	}
+};
+//#endregion
 //#region lib/types/index.js
 /**
 * Browser-bridge plugin: one local WebSocket endpoint the DSH Browser Control
@@ -1170,12 +1235,55 @@ const NAV_TIERS = {
 	load: 15e3
 };
 /**
+* Commands whose params carry no meaningful single tab: link probes, tab
+* management, window management and the global dialog policy. Everything else
+* defaults to the calling session's working tab when tabId is omitted
+* (v1.7.6 isolation). New tab-scoped commands need no registration here —
+* they inherit the default, which is the safe direction.
+*/
+const NO_TAB_DEFAULT_COMMANDS = /* @__PURE__ */ new Set([
+	"ping",
+	"browser.info",
+	"tabs.list",
+	"tabs.open",
+	"tabs.group",
+	"tabs.ungroup",
+	"windows.list",
+	"windows.open",
+	"windows.update",
+	"windows.close",
+	"windows.moveTab",
+	"dialog"
+]);
+/**
 * Extra time handed to the bridge on top of the navigation budget. Without it a
 * caller-requested budget longer than the bridge default (60s) would be beaten by
 * the bridge, and the model would get `command_timeout` (effect unknown) instead
 * of a navigation timeout (nothing was touched) - two very different next steps.
 */
 const BRIDGE_MARGIN_MS = 2e3;
+/**
+* 每个工具体都跑在调用方 agent 的会话上下文里（exec.agent.id）。控制器用它
+* 解析「这个会话的工作标签页」。没有 agent 身份的调用（HTTP 面、测试、老宿主）
+* store 是 undefined，行为与以前完全一致。
+*/
+const TOOL_SESSION = new AsyncLocalStorage();
+/**
+* 包一层宿主的 defineTool：注册处全部走这里，工具体自动带上会话上下文。
+* 这是 v1.7.6 多 session 隔离能集中实现、而不用改二十多处 execute 的原因。
+*/
+function defineTool$1(options) {
+	const inner = options.execute;
+	const execute = ((args, exec) => {
+		const agent = exec.agent;
+		const sessionId = typeof agent?.id === "string" && agent.id.length > 0 ? agent.id : void 0;
+		return TOOL_SESSION.run(sessionId, () => inner(args, exec));
+	});
+	return defineTool({
+		...options,
+		execute
+	});
+}
 /** Cordis plugin name used by loader diagnostics. */
 const name = "browser-bridge";
 /** The tool registry this plugin contributes `browser_*` tools to. */
@@ -1267,6 +1375,8 @@ var BridgeController = class {
 	journalKey = "";
 	/** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
 	audit = new AuditLog();
+	/** 多 session 隔离：每个 dsh 会话的工作标签页（见 sessions.ts）。 */
+	sessions = new SessionRegistry();
 	constructor(log) {
 		this.log = log;
 	}
@@ -1405,16 +1515,19 @@ var BridgeController = class {
 	*/
 	async execute(command, params, signal, timeoutMs) {
 		const started = Date.now();
-		const summary = summarizeAuditParams(command, params);
-		const tabId = typeof params.tabId === "number" ? params.tabId : void 0;
+		const sessionId = TOOL_SESSION.getStore();
+		const resolved = sessionId === void 0 ? params : await this.isolateParams(command, params, sessionId, signal);
+		const summary = summarizeAuditParams(command, resolved);
+		const tabId = typeof resolved.tabId === "number" ? resolved.tabId : void 0;
 		try {
-			this.policyGate(command, params);
+			this.policyGate(command, resolved);
 			const server = this.server;
 			if (server === void 0) throw classify(command, new Error(this.lastError ?? "浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）"));
-			const result = await server.execute(command, params, timeoutMs === void 0 ? { signal } : {
+			const result = await server.execute(command, resolved, timeoutMs === void 0 ? { signal } : {
 				signal,
 				timeoutMs
 			});
+			if (sessionId !== void 0) this.noteSession(sessionId, resolved, result);
 			this.recordAudit({
 				command,
 				tabId,
@@ -1424,6 +1537,7 @@ var BridgeController = class {
 			});
 			return result;
 		} catch (error) {
+			if (sessionId !== void 0) this.sessions.touch(sessionId);
 			const code = error.code;
 			const effectState = error.effectState;
 			this.recordAudit({
@@ -1440,6 +1554,37 @@ var BridgeController = class {
 		}
 	}
 	/**
+	* Apply per-session tab isolation: when a call omits `tabId`, default it to
+	* the calling session's working tab — but only after asking the extension
+	* whether that tab is still open. A stale id must never fail a call that used
+	* 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;
+		const recorded = this.sessions.workingTab(sessionId);
+		if (recorded === void 0) return params;
+		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;
+			}
+		} catch {}
+		return {
+			...params,
+			tabId: recorded
+		};
+	}
+	/** Record the call and adopt the tab it actually touched (params or result). */
+	noteSession(sessionId, params, result) {
+		this.sessions.touch(sessionId);
+		if (typeof params.tabId === "number") this.sessions.adopt(sessionId, params.tabId);
+		const resultTab = result?.tabId;
+		if (typeof resultTab === "number") this.sessions.adopt(sessionId, resultTab);
+	}
+	/**
 	* Refuse a command the local policy forbids, before anything is sent or deleted.
 	*
 	* The gate sits above the link and above the filesystem, not inside either: a
@@ -1689,7 +1834,7 @@ function applyBrowserTools(ctx, controller) {
 		order: 112,
 		text: "The browser_* tools drive the user's real, logged-in browser through the DSH Browser Control extension; they act on the active tab unless a tabId is passed. Prefer browser_snapshot first on unfamiliar pages: it numbers interactive elements, and browser_click/browser_type accept the returned ref instead of guessing CSS selectors. browser_read extracts page text in a window (offset/limit) and reports how much text is left, browser_screenshot saves a PNG/JPEG and returns its file path (view it with an image tool). Calls fail with actionable copy while the bridge is disabled or no browser is connected. When a result is cut to bound token cost it is marked \"[renderedTruncated omittedChars=N limitChars=L]\" — re-issue a narrower query (smaller limit, a pattern filter, or browser_read's offset) instead of assuming the page is shorter than it is."
 	});
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_navigate",
 		description: "Navigate a browser tab to a URL and wait for the page load to settle.",
 		parameters: {
@@ -1784,7 +1929,7 @@ function applyBrowserTools(ctx, controller) {
 			return out;
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_read",
 		description: "Read the current page: title, URL and the page text itself (or full HTML) in a window you control with offset/limit. The returned text is what you see — no separate fetch step is needed.",
 		parameters: {
@@ -1879,7 +2024,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_snapshot",
 		description: "Inventory the page's interactive elements with stable refs; pass a ref to browser_click/browser_type afterwards. mode:\"ax\" numbers them by Chrome's accessibility tree (role + accessible name), which survives a DOM redesign; the default mode matches CSS selectors.",
 		parameters: {
@@ -1887,9 +2032,13 @@ function applyBrowserTools(ctx, controller) {
 				type: "number",
 				description: "Target tab; defaults to the active tab."
 			},
+			offset: {
+				type: "number",
+				description: "Skip this many items into the inventory (paging); default 0. Refs are valid for THIS call only — take the next page in the same breath if you need stable refs."
+			},
 			limit: {
 				type: "number",
-				description: "Max elements returned; defaults to 120, capped at 200."
+				description: "Page size: max items returned by this call; defaults to 120. The extension supplies up to a 200-item window per call."
 			},
 			mode: {
 				type: "string",
@@ -1915,6 +2064,17 @@ function applyBrowserTools(ctx, controller) {
 					},
 					mode: { type: "string" },
 					axFallback: { type: "string" },
+					offset: {
+						type: "number",
+						required: true
+					},
+					total: { type: "number" },
+					returned: { type: "number" },
+					nextOffset: { type: "number" },
+					hasMore: {
+						type: "boolean",
+						required: true
+					},
 					items: {
 						type: "array",
 						required: true,
@@ -1939,9 +2099,13 @@ function applyBrowserTools(ctx, controller) {
 				}
 			},
 			render: (_args, value) => {
+				const shown = value.items.length;
+				const start = value.offset + 1;
+				const end = value.offset + shown;
+				const totalText = value.total === void 0 ? `${value.returned ?? shown} available` : `${value.total} on the page`;
 				return [{
 					type: "text",
-					text: clampRendered([`${value.items.length} interactive elements on ${value.title} (mode ${value.mode ?? "dom"}); click or fill them by ref:` + (value.axFallback === void 0 ? "" : `\n(mode ax fell back to dom: ${value.axFallback})`), ...value.items.map((item) => {
+					text: clampRendered([`${shown === 0 ? `no items at offset ${value.offset}` : `items ${start}–${end} of ${totalText}`}${value.total !== void 0 && value.returned !== void 0 && value.total > value.returned ? ` (this extension returns at most ${value.returned}-item windows — use browser_find/browser_read to reach the rest)` : ""}${value.nextOffset === void 0 ? "" : `; next page: offset ${value.nextOffset}`} (mode ${value.mode ?? "dom"}); click or fill them by ref:` + (value.axFallback === void 0 ? "" : `\n(mode ax fell back to dom: ${value.axFallback})`), ...value.items.map((item) => {
 						const name = item.name === void 0 ? "" : ` "${flattenOneLine(item.name, 80)}"`;
 						const href = item.href === void 0 ? "" : ` -> ${flattenOneLine(item.href, 100)}`;
 						return `[${item.ref}] ${item.role ?? item.tag}${name}${href}`;
@@ -1955,20 +2119,33 @@ function applyBrowserTools(ctx, controller) {
 			kind: "other"
 		}),
 		async execute(args, exec) {
-			const params = { limit: Math.min(200, Math.max(1, args.limit ?? 120)) };
+			const offset = Math.max(0, Math.trunc(typeof args.offset === "number" && Number.isFinite(args.offset) ? args.offset : 0));
+			const limit = Math.min(200, Math.max(1, typeof args.limit === "number" && Number.isFinite(args.limit) ? Math.trunc(args.limit) : 120));
+			const params = { limit: 200 };
 			if (typeof args.tabId === "number") params.tabId = args.tabId;
 			if (typeof args.mode === "string") params.mode = args.mode;
 			const raw = await controller.execute("snapshot", params, exec.signal);
 			const requestedAx = args.mode === "ax";
 			const gotAx = raw.mode === "ax" || raw.ax !== void 0;
 			const axFallback = typeof raw.axFallback === "string" && raw.axFallback.length > 0 ? raw.axFallback : requestedAx && !gotAx ? "this extension ignored mode:\"ax\" and returned CSS-DOM matches (AX mode needs DSH Browser Control extension v1.0.11 or newer) — the names below are tag names, not accessible names" : void 0;
+			const window = Array.isArray(raw.items) ? raw.items : [];
+			const returned = window.length;
+			const reportedTotal = typeof raw.total === "number" && Number.isFinite(raw.total) ? Math.trunc(raw.total) : void 0;
+			const total = reportedTotal === void 0 ? void 0 : Math.max(returned, reportedTotal);
+			const page = window.slice(offset, offset + limit);
+			const hasMore = offset + page.length < returned;
 			return {
 				tabId: raw.tabId,
 				title: raw.title ?? "",
 				url: raw.url ?? "",
 				...raw.mode === void 0 ? {} : { mode: raw.mode },
 				...axFallback === void 0 ? {} : { axFallback },
-				items: (raw.items ?? []).map((item) => ({
+				offset,
+				...total === void 0 ? {} : { total },
+				returned,
+				hasMore,
+				...hasMore ? { nextOffset: offset + page.length } : {},
+				items: page.map((item) => ({
 					ref: item.ref,
 					tag: item.tag,
 					...item.role === void 0 ? {} : { role: item.role },
@@ -1978,7 +2155,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_click",
 		description: "Click a page element with real mouse events; target it by snapshot ref or CSS selector.",
 		parameters: {
@@ -2021,7 +2198,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("click", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_type",
 		description: "Fill an input/textarea/select/contentEditable (React-compatible events); optionally press Enter afterwards.",
 		parameters: {
@@ -2076,7 +2253,7 @@ function applyBrowserTools(ctx, controller) {
 			return filled;
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_press",
 		description: "Send a real keyboard event to the page: a named key (Enter, Tab, Escape, ArrowDown…), a single character, or a combination such as \"Ctrl+A\" / \"Shift+ArrowRight\".",
 		parameters: {
@@ -2117,7 +2294,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("press", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_scroll",
 		description: "Scroll the page viewport by a delta and report the resulting position.",
 		parameters: {
@@ -2160,7 +2337,7 @@ function applyBrowserTools(ctx, controller) {
 	}));
 	/** Page-side ceiling of `cmdWait`; the bridge budget adds slack on top. */
 	const WAIT_MAX_MS = 12e4;
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_wait",
 		description: "Block until a selector appears, some text shows up in the body, or a page-side predicate turns true. Use it after navigation for SPA routes and lazy-rendered content, which browser_navigate does not wait for.",
 		parameters: {
@@ -2217,7 +2394,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("wait", params, exec.signal, timeoutMs + 1e4);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_find",
 		description: "Describe the elements matching a CSS selector — count, tag, id, class, text, href and viewport rect. Read-only; use it to decide what to click and to verify the page state.",
 		parameters: {
@@ -2257,7 +2434,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("find", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_hold",
 		description: "Put a cancellable take-over overlay on a tab so the user can see that you are working on this page and cannot mis-click. The card title is fixed by the extension; your `note` is the body text only (≤400 chars, newlines flattened). The user double-clicks the page (or presses Escape twice, or holds Escape) to close it — you can keep working. Pressing the card's abort button blocks your click/input/press/nav on that tab until you call action=\"off\" (which counts as confirming you continue). This is a soft layer, not a security boundary: the popup lock is the thing that actually freezes the browser. Returns `covered:false` with a `reason` when the page cannot be covered (browser pages, error pages, CSP-strict frames, PDF viewer, an open native dialog).",
 		parameters: {
@@ -2308,7 +2485,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("hold", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_cookies",
 		description: "Read, set or remove cookies of a tab (CDP Network.*, no new permission). Cookie values are credentials — a get returns them in full and they land in the model-visible text, so filter by domain and do not point this at a page whose cookies you do not actually need. set/remove need an anchor: url, or domain (with optional path).",
 		parameters: {
@@ -2397,7 +2574,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("cookies.remove", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_dialog",
 		description: "Read or change how native alert/confirm/prompt dialogs are answered (accept, dismiss, or manual), and get the recent dialog log so you can prove one appeared.",
 		parameters: { policy: {
@@ -2430,7 +2607,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("dialog", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_info",
 		description: "Report which browser and which extension build is actually attached. Run it first when behaviour looks wrong — a stale extension or the wrong browser profile explains most of it.",
 		parameters: {},
@@ -2453,7 +2630,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("browser.info", {}, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_tabs",
 		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: {
@@ -2561,7 +2738,7 @@ function applyBrowserTools(ctx, controller) {
 			}
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		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: {
@@ -2696,7 +2873,7 @@ function applyBrowserTools(ctx, controller) {
 	}));
 	/** 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({
+	ctx.tools.register(defineTool$1({
 		name: "browser_evaluate",
 		description: "Run JavaScript in the page and get the JSON result back as a string. Prefer read-only inspection.",
 		parameters: {
@@ -2761,7 +2938,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_screenshot",
 		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: {
@@ -2845,7 +3022,7 @@ function applyBrowserTools(ctx, controller) {
 			return saveScreenshot(controller, await controller.execute("screenshot", params, exec.signal));
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_cleanup",
 		description: "Delete generated screenshots and agent scratch files (__-prefixed temp scripts/artifacts) from their top-level directories.",
 		parameters: {},
@@ -2883,7 +3060,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_console_log",
 		description: "Read the captured `console.log/info/warn/error` entries for a tab, with the entry text itself. Set `clear:true` to also empty the buffer so the next call shows only entries recorded after this one. Useful for \"what did the page log after I clicked submit\".",
 		parameters: {
@@ -2981,7 +3158,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_network_log",
 		description: "Read captured HTTP request/response pairs for a tab. `includeStatic:true` adds images / fonts / stylesheets / scripts (filtered by default — they dominate the buffer). `methodPattern` / `urlPattern` / `status` filter server-side results; `clear:true` empties the buffer.",
 		parameters: {
@@ -3096,7 +3273,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_network_clear",
 		description: "Empty the per-tab network capture buffer without returning the rows.",
 		parameters: { tabId: {
@@ -3134,7 +3311,7 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("network.clear", params, exec.signal);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_pdf",
 		description: "Export the current page to a PDF. `path` may be absolute (saved there) or omitted (saved under the configured shotsDir). Returns the absolute path + size; the PDF preserves text (selectable, searchable) and print-media CSS.",
 		parameters: {
@@ -3212,7 +3389,7 @@ function applyBrowserTools(ctx, controller) {
 			return await savePdf(controller, await controller.execute("pdf", params, exec.signal), typeof args.path === "string" ? args.path : void 0);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_archive",
 		description: "Save the whole page as a single-file MHTML archive (text, images and styles inline; no network needed to reopen it). Returns the absolute path. The archive is a snapshot of when it was taken — scripts inside do not run and later page changes are not reflected; read it back with file tools or grep it like text.",
 		parameters: {
@@ -3261,7 +3438,7 @@ function applyBrowserTools(ctx, controller) {
 			return await saveMhtml(controller, await controller.execute("archive", params, exec.signal), typeof args.path === "string" ? args.path : void 0);
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_emulate",
 		description: "Switch the tab into a device viewport (mobile / tablet / desktop) for responsive-UI testing, and throttle the network or CPU to test slow conditions. `device:\"reset\"` restores the user's actual viewport and clears all throttling. `network` presets (this tool's own numbers): slow3g = 400ms RTT + ~50KB/s both ways, fast3g = 150ms + ~200KB/s down / ~94KB/s up, offline, reset to clear. `cpuThrottlingRate` multiplies CPU cost (1 = off, up to 20). Throttling lives in the debugger session — it is gone when the extension detaches, and device:\"reset\" clears it too. Custom `width`/`height`/`deviceScaleFactor`/`isMobile`/`hasTouch` override any preset field.",
 		parameters: {
@@ -3378,7 +3555,7 @@ function applyBrowserTools(ctx, controller) {
 			};
 		}
 	}));
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_metrics",
 		description: "Read the tab's performance counters (Performance.getMetrics): DOM node count, JS heap usage, layout/style recalc counts, script/task durations. Use it to back \"this page is heavy\" with numbers, before and after an action. Read-only.",
 		parameters: { tabId: {
@@ -3448,6 +3625,7 @@ function applyBrowserTools(ctx, controller) {
 	registerDragTool(ctx, controller);
 	registerAuditTool(ctx, controller);
 	registerJournalTool(ctx, controller);
+	registerSessionsTool(ctx, controller);
 }
 /** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
 async function cdpCall(ctrl, tabId, method, params, signal) {
@@ -3564,7 +3742,7 @@ function roundDragPoint(p) {
 	return out;
 }
 function registerDragTool(ctx, controller) {
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_drag",
 		description: "Drag a page element or point onto another with real input. mode \"mouse\" sends trusted press→moves→release input via CDP (canvas, sliders, sortable widgets); mode \"html5\" synthesizes dragstart/dragover/drop in the page for [draggable] elements and needs page scripting; \"auto\" (default) picks html5 only when the source declares draggable=\"true\". Endpoints are CSS selectors (top document) or fromX/fromY + toX/toY viewport coordinates. Needs browser extension v1.7.2+ (embedded cdp channel).",
 		parameters: {
@@ -3777,7 +3955,7 @@ function registerDragTool(ctx, controller) {
 	}));
 }
 function registerAuditTool(ctx, controller) {
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_audit",
 		description: "Read this plugin session's in-memory audit trail: every command sent to the browser extension (and every policy/gate refusal), with redacted params, outcome code and duration. Newest last; capped at 200 entries and wiped when dsh restarts. Values typed into pages and cookie values are redacted; eval expressions are truncated. Plugin-local read — works in read-only mode.",
 		parameters: {
@@ -3890,7 +4068,7 @@ function registerAuditTool(ctx, controller) {
 	}));
 }
 function registerJournalTool(ctx, controller) {
-	ctx.tools.register(defineTool({
+	ctx.tools.register(defineTool$1({
 		name: "browser_journal",
 		description: "Read the persistent command journal across dsh restarts: every command from previous runs of this plugin (written to <stateDir>/journal.jsonl, last 1000 entries), grouped by run. Same redaction as browser_audit. Plugin-local disk read — works with the extension offline and in read-only mode, so it is the way to recover \"what was I doing\" after a restart.",
 		parameters: {
@@ -4013,6 +4191,93 @@ function registerJournalTool(ctx, controller) {
 		}
 	}));
 }
+function registerSessionsTool(ctx, controller) {
+	ctx.tools.register(defineTool$1({
+		name: "browser_sessions",
+		description: "List the dsh agent sessions sharing this browser and each one's working tab, or release your own working tab (\"release\"). Isolation: when a browser tool omits tabId, it defaults to THIS session's working tab (verified live against the extension) instead of the browser's active tab — concurrent sessions stop fighting over whatever tab is active. Explicit tabId always wins. Plugin-local; works read-only.",
+		parameters: { action: {
+			type: "string",
+			description: "\"list\" (default) or \"release\" (forget your working tab)."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					current: { type: "string" },
+					sessions: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								sessionId: {
+									type: "string",
+									required: true
+								},
+								workingTabId: { type: "number" },
+								lastActiveAt: {
+									type: "number",
+									required: true
+								},
+								calls: {
+									type: "number",
+									required: true
+								}
+							}
+						}
+					},
+					releasedTabId: { type: "number" }
+				}
+			},
+			render: (_args, value) => {
+				const v = value;
+				const short = (id) => id.length <= 18 ? id : `${id.slice(0, 16)}…`;
+				if (v.releasedTabId !== void 0) return [{
+					type: "text",
+					text: `Sessions: released your working tab ${v.releasedTabId} — later calls without tabId follow the browser's active tab again.`
+				}];
+				if (v.sessions.length === 0) return [{
+					type: "text",
+					text: "Sessions: 0 — no agent-scoped tool calls yet (calls without an agent identity keep the old active-tab behaviour)."
+				}];
+				const lines = v.sessions.map((s) => {
+					const me = s.sessionId === v.current ? "* " : "  ";
+					const tab = s.workingTabId === void 0 ? "no working tab" : `tab ${s.workingTabId}`;
+					return `${me}${short(s.sessionId)} — ${tab}, ${s.calls} calls, last ${formatClock(s.lastActiveAt)}`;
+				});
+				return [{
+					type: "text",
+					text: clampRendered(`Sessions: ${v.sessions.length}${v.current === void 0 ? "" : ` (you: ${short(v.current)})`}\n${lines.join("\n")}`)
+				}];
+			}
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: args.action === "release" ? "Release session tab" : "Browser sessions",
+			kind: "other"
+		}),
+		async execute(args) {
+			const current = TOOL_SESSION.getStore();
+			if (args.action === "release") {
+				const sessions = controller.sessions.list();
+				if (current === void 0) return { sessions };
+				const released = controller.sessions.release(current);
+				const payload = {
+					current,
+					sessions
+				};
+				if (released !== void 0) payload.releasedTabId = released;
+				return payload;
+			}
+			if (args.action !== void 0 && args.action !== "list") throw new Error(`action must be "list" or "release" — got ${JSON.stringify(args.action)}`);
+			const payload = { sessions: controller.sessions.list() };
+			if (current !== void 0) payload.current = current;
+			return payload;
+		}
+	}));
+}
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 function apply(ctx, config) {
 	const resolved = config;

package/lib/types/index.js

@@ -17,16 +17,18 @@
  * fix, so the model can tell the user what to do instead of hanging.
  * @module @deepseek-ai/dsh-browser-bridge
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { defineTool } from '@deepseek-ai/dsh-tools';
+import { defineTool as defineHostTool } from '@deepseek-ai/dsh-tools';
 import { BridgeServer, cleanupArtifacts } from "./server.js";
 import { BridgeError, classify } from "./errors.js";
 import { policyRefusal } from "./policy.js";
 import { AUDIT_MAX_ENTRIES, AuditLog, summarizeAuditParams } from "./audit.js";
 import { Journal, readJournal } from "./journal.js";
+import { SessionRegistry } from "./sessions.js";
 /** Navigation wait ceiling (same as browser_wait); the bridge gets this plus BRIDGE_MARGIN_MS. */
 const NAV_MAX_MS = 120_000;
 /**
@@ -36,6 +38,19 @@ const NAV_MAX_MS = 120_000;
  * protocol: a value only one side knows is a lie on the other).
  */
 const NAV_TIERS = { none: 0, commit: 4_000, domcontentloaded: 4_000, load: 15_000 };
+/**
+ * Commands whose params carry no meaningful single tab: link probes, tab
+ * management, window management and the global dialog policy. Everything else
+ * defaults to the calling session's working tab when tabId is omitted
+ * (v1.7.6 isolation). New tab-scoped commands need no registration here —
+ * they inherit the default, which is the safe direction.
+ */
+const NO_TAB_DEFAULT_COMMANDS = new Set([
+    'ping', 'browser.info',
+    'tabs.list', 'tabs.open', 'tabs.group', 'tabs.ungroup',
+    'windows.list', 'windows.open', 'windows.update', 'windows.close', 'windows.moveTab',
+    'dialog',
+]);
 /**
  * Extra time handed to the bridge on top of the navigation budget. Without it a
  * caller-requested budget longer than the bridge default (60s) would be beaten by
@@ -43,6 +58,31 @@ const NAV_TIERS = { none: 0, commit: 4_000, domcontentloaded: 4_000, load: 15_00
  * of a navigation timeout (nothing was touched) - two very different next steps.
  */
 const BRIDGE_MARGIN_MS = 2_000;
+/**
+ * 每个工具体都跑在调用方 agent 的会话上下文里（exec.agent.id）。控制器用它
+ * 解析「这个会话的工作标签页」。没有 agent 身份的调用（HTTP 面、测试、老宿主）
+ * store 是 undefined，行为与以前完全一致。
+ */
+const TOOL_SESSION = new AsyncLocalStorage();
+/**
+ * 包一层宿主的 defineTool：注册处全部走这里，工具体自动带上会话上下文。
+ * 这是 v1.7.6 多 session 隔离能集中实现、而不用改二十多处 execute 的原因。
+ */
+function defineTool(options) {
+    // The body is typed through ToolRunContext and cast at both boundaries: letting
+    // TS deep-compare the generic option shape through a spread blows its recursion
+    // budget ("excessive stack depth comparing InferObject").
+    const inner = options.execute;
+    const execute = ((args, exec) => {
+        const agent = exec.agent;
+        const sessionId = typeof agent?.id === 'string' && agent.id.length > 0 ? agent.id : undefined;
+        return TOOL_SESSION.run(sessionId, () => inner(args, exec));
+    });
+    // Call the host helper through a non-generic point: re-instantiating its
+    // recursive InferObject types from inside a generic wrapper is what TS chokes on.
+    const hostDefine = defineHostTool;
+    return hostDefine({ ...options, execute });
+}
 // Re-exported so the policy tables stay testable from the published bundle
 // (verify/verify_policy.mjs reconciles them against the extension's COMMANDS).
 export { LOCAL_DESTRUCTIVE_COMMANDS, PAGE_MUTATING_COMMANDS, READ_ONLY_ALLOWED, SCRIPT_COMMANDS, policyRefusal } from "./policy.js";
@@ -125,6 +165,8 @@ class BridgeController {
     journalKey = '';
     /** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
     audit = new AuditLog();
+    /** 多 session 隔离：每个 dsh 会话的工作标签页（见 sessions.ts）。 */
+    sessions = new SessionRegistry();
     constructor(log) {
         this.log = log;
     }
@@ -266,19 +308,25 @@ class BridgeController {
      */
     async execute(command, params, signal, timeoutMs) {
         const started = Date.now();
-        const summary = summarizeAuditParams(command, params);
-        const tabId = typeof params.tabId === 'number' ? params.tabId : undefined;
+        const sessionId = TOOL_SESSION.getStore();
+        const resolved = sessionId === undefined ? params : await this.isolateParams(command, params, sessionId, signal);
+        const summary = summarizeAuditParams(command, resolved);
+        const tabId = typeof resolved.tabId === 'number' ? resolved.tabId : undefined;
         try {
-            this.policyGate(command, params);
+            this.policyGate(command, resolved);
             const server = this.server;
             if (server === undefined) {
                 throw classify(command, new Error(this.lastError ?? '浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）'));
             }
-            const result = await server.execute(command, params, timeoutMs === undefined ? { signal } : { signal, timeoutMs });
+            const result = await server.execute(command, resolved, timeoutMs === undefined ? { signal } : { signal, timeoutMs });
+            if (sessionId !== undefined)
+                this.noteSession(sessionId, resolved, result);
             this.recordAudit({ command, tabId, params: summary, ok: true, durationMs: Date.now() - started });
             return result;
         }
         catch (error) {
+            if (sessionId !== undefined)
+                this.sessions.touch(sessionId);
             const code = error.code;
             const effectState = error.effectState;
             this.recordAudit({
@@ -294,6 +342,42 @@ class BridgeController {
             throw error;
         }
     }
+    /**
+     * Apply per-session tab isolation: when a call omits `tabId`, default it to
+     * the calling session's working tab — but only after asking the extension
+     * whether that tab is still open. A stale id must never fail a call that used
+     * 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;
+        const recorded = this.sessions.workingTab(sessionId);
+        if (recorded === undefined)
+            return params;
+        const server = this.server;
+        if (server !== undefined) {
+            try {
+                const listing = await server.execute('tabs.list', {}, { signal });
+                const live = Array.isArray(listing?.tabs) && listing.tabs.some((tab) => tab?.id === recorded);
+                if (!live) {
+                    this.sessions.release(sessionId);
+                    return params;
+                }
+            }
+            catch { /* 列不出来就按旧行为走活动标签页 */ }
+        }
+        return { ...params, tabId: recorded };
+    }
+    /** Record the call and adopt the tab it actually touched (params or result). */
+    noteSession(sessionId, params, result) {
+        this.sessions.touch(sessionId);
+        if (typeof params.tabId === 'number')
+            this.sessions.adopt(sessionId, params.tabId);
+        const resultTab = result?.tabId;
+        if (typeof resultTab === 'number')
+            this.sessions.adopt(sessionId, resultTab);
+    }
     /**
      * Refuse a command the local policy forbids, before anything is sent or deleted.
      *
@@ -725,7 +809,8 @@ function applyBrowserTools(ctx, controller) {
         description: 'Inventory the page\'s interactive elements with stable refs; pass a ref to browser_click/browser_type afterwards. mode:"ax" numbers them by Chrome\'s accessibility tree (role + accessible name), which survives a DOM redesign; the default mode matches CSS selectors.',
         parameters: {
             tabId: { type: 'number', description: 'Target tab; defaults to the active tab.' },
-            limit: { type: 'number', description: 'Max elements returned; defaults to 120, capped at 200.' },
+            offset: { type: 'number', description: 'Skip this many items into the inventory (paging); default 0. Refs are valid for THIS call only — take the next page in the same breath if you need stable refs.' },
+            limit: { type: 'number', description: 'Page size: max items returned by this call; defaults to 120. The extension supplies up to a 200-item window per call.' },
             mode: { type: 'string', description: '"ax" for the accessibility tree, "dom" (default) for the selector list. "ax" falls back to "dom" with axFallback set if the page gives no a11y tree.' },
         },
         output: {
@@ -738,6 +823,11 @@ function applyBrowserTools(ctx, controller) {
                     url: { type: 'string', required: true },
                     mode: { type: 'string' },
                     axFallback: { type: 'string' },
+                    offset: { type: 'number', required: true },
+                    total: { type: 'number' },
+                    returned: { type: 'number' },
+                    nextOffset: { type: 'number' },
+                    hasMore: { type: 'boolean', required: true },
                     items: {
                         type: 'array',
                         required: true,
@@ -756,7 +846,16 @@ function applyBrowserTools(ctx, controller) {
                 },
             },
             render: (_args, value) => {
-                const head = `${value.items.length} interactive elements on ${value.title}`
+                const shown = value.items.length;
+                const start = value.offset + 1;
+                const end = value.offset + shown;
+                const totalText = value.total === undefined ? `${value.returned ?? shown} available` : `${value.total} on the page`;
+                const range = shown === 0 ? `no items at offset ${value.offset}` : `items ${start}–${end} of ${totalText}`;
+                const capped = value.total !== undefined && value.returned !== undefined && value.total > value.returned
+                    ? ` (this extension returns at most ${value.returned}-item windows — use browser_find/browser_read to reach the rest)`
+                    : '';
+                const next = value.nextOffset === undefined ? '' : `; next page: offset ${value.nextOffset}`;
+                const head = `${range}${capped}${next}`
                     + ` (mode ${value.mode ?? 'dom'}); click or fill them by ref:`
                     + (value.axFallback === undefined ? '' : `\n(mode ax fell back to dom: ${value.axFallback})`);
                 const lines = value.items.map(item => {
@@ -769,8 +868,12 @@ function applyBrowserTools(ctx, controller) {
         },
         presentCall: () => ({ card: 'generic', title: 'Snapshot browser page', kind: 'other' }),
         async execute(args, exec) {
-            const limit = Math.min(200, Math.max(1, args.limit ?? 120));
-            const params = { limit };
+            const offset = Math.max(0, Math.trunc(typeof args.offset === 'number' && Number.isFinite(args.offset) ? args.offset : 0));
+            const limit = Math.min(200, Math.max(1, typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.trunc(args.limit) : 120));
+            // Ask for the largest window the extension offers (200) and page in the
+            // plugin: older surfaces never learned an offset parameter, and they do
+            // report `total`, so paging stays plugin-side (v1.7.7).
+            const params = { limit: 200 };
             if (typeof args.tabId === 'number')
                 params.tabId = args.tabId;
             if (typeof args.mode === 'string')
@@ -788,13 +891,24 @@ function applyBrowserTools(ctx, controller) {
                 : (requestedAx && !gotAx
                     ? 'this extension ignored mode:"ax" and returned CSS-DOM matches (AX mode needs DSH Browser Control extension v1.0.11 or newer) — the names below are tag names, not accessible names'
                     : undefined);
-            return {
+            const window = Array.isArray(raw.items) ? raw.items : [];
+            const returned = window.length;
+            const reportedTotal = typeof raw.total === 'number' && Number.isFinite(raw.total) ? Math.trunc(raw.total) : undefined;
+            const total = reportedTotal === undefined ? undefined : Math.max(returned, reportedTotal);
+            const page = window.slice(offset, offset + limit);
+            const hasMore = offset + page.length < returned;
+            const receipt = {
                 tabId: raw.tabId,
                 title: raw.title ?? '',
                 url: raw.url ?? '',
                 ...(raw.mode === undefined ? {} : { mode: raw.mode }),
                 ...(axFallback === undefined ? {} : { axFallback }),
-                items: (raw.items ?? []).map(item => ({
+                offset,
+                ...(total === undefined ? {} : { total }),
+                returned,
+                hasMore,
+                ...(hasMore ? { nextOffset: offset + page.length } : {}),
+                items: page.map(item => ({
                     ref: item.ref,
                     tag: item.tag,
                     ...(item.role === undefined ? {} : { role: item.role }),
@@ -802,6 +916,7 @@ function applyBrowserTools(ctx, controller) {
                     ...(item.href === undefined ? {} : { href: item.href }),
                 })),
             };
+            return receipt;
         },
     }));
     ctx.tools.register(defineTool({
@@ -1783,6 +1898,7 @@ function applyBrowserTools(ctx, controller) {
     registerDragTool(ctx, controller);
     registerAuditTool(ctx, controller);
     registerJournalTool(ctx, controller);
+    registerSessionsTool(ctx, controller);
 }
 /* ------------------- browser_drag: composed plugin-side over the cdp channel ------------------- */
 /** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
@@ -2183,6 +2299,75 @@ function registerJournalTool(ctx, controller) {
         },
     }));
 }
+function registerSessionsTool(ctx, controller) {
+    ctx.tools.register(defineTool({
+        name: 'browser_sessions',
+        description: 'List the dsh agent sessions sharing this browser and each one\'s working tab, or release your own working tab ("release"). Isolation: when a browser tool omits tabId, it defaults to THIS session\'s working tab (verified live against the extension) instead of the browser\'s active tab — concurrent sessions stop fighting over whatever tab is active. Explicit tabId always wins. Plugin-local; works read-only.',
+        parameters: {
+            action: { type: 'string', description: '"list" (default) or "release" (forget your working tab).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    current: { type: 'string' },
+                    sessions: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                sessionId: { type: 'string', required: true },
+                                workingTabId: { type: 'number' },
+                                lastActiveAt: { type: 'number', required: true },
+                                calls: { type: 'number', required: true },
+                            },
+                        },
+                    },
+                    releasedTabId: { type: 'number' },
+                },
+            },
+            render: (_args, value) => {
+                const v = value;
+                const short = (id) => (id.length <= 18 ? id : `${id.slice(0, 16)}…`);
+                if (v.releasedTabId !== undefined) {
+                    return [{ type: 'text', text: `Sessions: released your working tab ${v.releasedTabId} — later calls without tabId follow the browser's active tab again.` }];
+                }
+                if (v.sessions.length === 0) {
+                    return [{ type: 'text', text: 'Sessions: 0 — no agent-scoped tool calls yet (calls without an agent identity keep the old active-tab behaviour).' }];
+                }
+                const lines = v.sessions.map((s) => {
+                    const me = s.sessionId === v.current ? '* ' : '  ';
+                    const tab = s.workingTabId === undefined ? 'no working tab' : `tab ${s.workingTabId}`;
+                    return `${me}${short(s.sessionId)} — ${tab}, ${s.calls} calls, last ${formatClock(s.lastActiveAt)}`;
+                });
+                return [{ type: 'text', text: clampRendered(`Sessions: ${v.sessions.length}${v.current === undefined ? '' : ` (you: ${short(v.current)})`}\n${lines.join('\n')}`) }];
+            },
+        },
+        presentCall: args => ({ card: 'generic', title: args.action === 'release' ? 'Release session tab' : 'Browser sessions', kind: 'other' }),
+        async execute(args) {
+            const current = TOOL_SESSION.getStore();
+            if (args.action === 'release') {
+                const sessions = controller.sessions.list();
+                if (current === undefined)
+                    return { sessions };
+                const released = controller.sessions.release(current);
+                const payload = { current, sessions };
+                if (released !== undefined)
+                    payload.releasedTabId = released;
+                return payload;
+            }
+            if (args.action !== undefined && args.action !== 'list')
+                throw new Error(`action must be "list" or "release" — got ${JSON.stringify(args.action)}`);
+            const payload = { sessions: controller.sessions.list() };
+            if (current !== undefined)
+                payload.current = current;
+            return payload;
+        },
+    }));
+}
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 export function apply(ctx, config) {
     const resolved = config;

package/lib/types/sessions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 多 session 隔离（v1.7.6）：同一个插件实例、同一个浏览器，可能同时被好几个
+ * dsh 会话（agent）驱动。以前它们都默认落到「浏览器当前活动标签页」——谁刚切了
+ * 页，谁就把别人的上下文抢走。这一层给每个 agent 记住它自己的工作标签页：
+ *
+ *   - 省略 tabId 的工具调用默认落到**本会话的工作标签页**（先向扩展核对它还开着）；
+ *   - 工作标签页被关掉 → 退回活动标签页，并改记新的；
+ *   - 没带 agent 身份的调用（HTTP 面、测试、宿主老版本）完全维持旧行为。
+ *
+ * 这是**建议性隔离**，不是所有权锁：显式传 tabId 永远有效，跨会话交接不需要解锁。
+ * 硬性归属（borrow/return + 用户仲裁）留给扩展侧那一版。
+ */
+export interface SessionInfo {
+    sessionId: string;
+    workingTabId?: number;
+    /** epoch 毫秒 */
+    lastActiveAt: number;
+    calls: number;
+}
+export declare class SessionRegistry {
+    private readonly sessions;
+    /** 记一次活动（无论成败）。 */
+    touch(sessionId: string): void;
+    /** 把某个标签页记为这个会话的工作标签页。 */
+    adopt(sessionId: string, tabId: number): void;
+    /** 当前记录的工作标签页（不核对是否还开着——核对是控制器的事）。 */
+    workingTab(sessionId: string): number | undefined;
+    /** 清掉工作标签页；返回被清掉的 id。 */
+    release(sessionId: string): number | undefined;
+    /** 全部会话，最近活跃的在前。 */
+    list(): SessionInfo[];
+    size(): number;
+}

package/lib/types/sessions.js

@@ -0,0 +1,51 @@
+export class SessionRegistry {
+    sessions = new Map();
+    /** 记一次活动（无论成败）。 */
+    touch(sessionId) {
+        const now = Date.now();
+        const existing = this.sessions.get(sessionId);
+        if (existing === undefined) {
+            this.sessions.set(sessionId, { sessionId, lastActiveAt: now, calls: 1, createdAt: now });
+            return;
+        }
+        existing.lastActiveAt = now;
+        existing.calls += 1;
+    }
+    /** 把某个标签页记为这个会话的工作标签页。 */
+    adopt(sessionId, tabId) {
+        const state = this.sessions.get(sessionId);
+        if (state === undefined) {
+            this.sessions.set(sessionId, { sessionId, workingTabId: tabId, lastActiveAt: Date.now(), calls: 0, createdAt: Date.now() });
+            return;
+        }
+        state.workingTabId = tabId;
+        state.lastActiveAt = Date.now();
+    }
+    /** 当前记录的工作标签页（不核对是否还开着——核对是控制器的事）。 */
+    workingTab(sessionId) {
+        return this.sessions.get(sessionId)?.workingTabId;
+    }
+    /** 清掉工作标签页；返回被清掉的 id。 */
+    release(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (state === undefined)
+            return undefined;
+        const previous = state.workingTabId;
+        state.workingTabId = undefined;
+        return previous;
+    }
+    /** 全部会话，最近活跃的在前。 */
+    list() {
+        return [...this.sessions.values()]
+            .sort((a, b) => b.lastActiveAt - a.lastActiveAt)
+            .map((s) => {
+            const info = { sessionId: s.sessionId, lastActiveAt: s.lastActiveAt, calls: s.calls };
+            if (s.workingTabId !== undefined)
+                info.workingTabId = s.workingTabId;
+            return info;
+        });
+    }
+    size() {
+        return this.sessions.size;
+    }
+}

package/llms.txt

@@ -42,7 +42,7 @@ Chrome 浏览器扩展 + DeepSeek Harness 插件，让 AI Agent 通过 CDP 驱
 
 ## 关键文件
 
-- `src/index.ts` - 28 个 `browser_*` 工具注册 + settings 接线的版本兼容分支
+- `src/index.ts` - 29 个 `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.7.5",
+  "version": "1.7.7",
   "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_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_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",