@webskill/sdk 0.15.0 → 0.16.0

package/dist/agent.js

@@ -3,7 +3,7 @@ import { b as parseSkillMarkdown, y as isValidSkillName } from "./skill-CAJMsLod
 import { t as assertRemoteUrlAllowed } from "./urlSafety-CiSuCJvX.js";
 import { c as formatAttachmentText, l as UNTRUSTED_LINE_LIMIT, o as XLSX_MIME, s as classifyAttachment, u as sanitizeUntrustedLine } from "./kind-DxgS8LM-.js";
 import { o as toBase64, s as DEFAULT_MAX_DATA_SOURCE_BYTES } from "./linkedDocument-xNXF-z8n.js";
-import { a as frameSteps, i as frameLabel, n as toActionFrameScopes, r as toFrameScopes, t as PAGE_ACTION_KINDS } from "./types-TUydnxaj.js";
+import { a as frameLabel, i as toFrameScopes, n as PAGE_DOCUMENT_REF, o as frameSteps, r as toActionFrameScopes, t as PAGE_ACTION_KINDS } from "./types-BuacBov_.js";
 
 //#region ../agent/src/todo/store.ts
 const STATUSES = [
@@ -182,7 +182,7 @@ const INPUT_SCHEMA$4 = {
 	required: ["action"],
 	additionalProperties: false
 };
-function toolError$5(code, message) {
+function toolError$6(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -231,15 +231,15 @@ function createTodoToolSource(options = {}) {
 		try {
 			if (action === "create") {
 				const items = parseItems(args["items"]);
-				if (typeof items === "string") return Promise.resolve(toolError$5("VALIDATION_FAILED", items));
+				if (typeof items === "string") return Promise.resolve(toolError$6("VALIDATION_FAILED", items));
 				const list = store.create(items);
 				return Promise.resolve(ok(events, progressText(list.items)));
 			}
 			if (action === "update") {
 				const id = args["id"];
 				const status = args["status"];
-				if (typeof id !== "string") return Promise.resolve(toolError$5("VALIDATION_FAILED", "The \"id\" argument is required for action \"update\""));
-				if (status !== void 0 && typeof status !== "string") return Promise.resolve(toolError$5("VALIDATION_FAILED", "The \"status\" argument must be a string"));
+				if (typeof id !== "string") return Promise.resolve(toolError$6("VALIDATION_FAILED", "The \"id\" argument is required for action \"update\""));
+				if (status !== void 0 && typeof status !== "string") return Promise.resolve(toolError$6("VALIDATION_FAILED", "The \"status\" argument must be a string"));
 				const title = args["title"];
 				const list = store.update(id, {
 					...status !== void 0 ? { status } : {},
@@ -251,10 +251,10 @@ function createTodoToolSource(options = {}) {
 				store.clear();
 				return Promise.resolve(ok(events, progressText([])));
 			}
-			return Promise.resolve(toolError$5("VALIDATION_FAILED", "The \"action\" argument must be one of create, update, clear"));
+			return Promise.resolve(toolError$6("VALIDATION_FAILED", "The \"action\" argument must be one of create, update, clear"));
 		} catch (e) {
 			const code = e instanceof Error && "code" in e ? String(e.code) : "VALIDATION_FAILED";
-			return Promise.resolve(toolError$5(code, e instanceof Error ? e.message : String(e)));
+			return Promise.resolve(toolError$6(code, e instanceof Error ? e.message : String(e)));
 		} finally {
 			unsubscribe();
 		}
@@ -557,7 +557,7 @@ const INPUT_SCHEMA$3 = {
 	],
 	additionalProperties: false
 };
-function toolError$4(code, message) {
+function toolError$5(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -626,7 +626,7 @@ function createSkillGenerationToolSource(options) {
 	const generator = new SkillGenerator(options);
 	const call = async (_name, args) => {
 		const draft = readDraft(args);
-		if (typeof draft === "string") return toolError$4("SKILL_GENERATION_VALIDATION_FAILED", draft);
+		if (typeof draft === "string") return toolError$5("SKILL_GENERATION_VALIDATION_FAILED", draft);
 		try {
 			const outcome = await generator.generate(draft);
 			if (outcome.status === "declined") return {
@@ -650,7 +650,7 @@ function createSkillGenerationToolSource(options) {
 				}]
 			};
 		} catch (e) {
-			return toolError$4(e instanceof Error && "code" in e ? String(e.code) : "SKILL_GENERATION_VALIDATION_FAILED", e instanceof Error ? e.message : String(e));
+			return toolError$5(e instanceof Error && "code" in e ? String(e.code) : "SKILL_GENERATION_VALIDATION_FAILED", e instanceof Error ? e.message : String(e));
 		}
 	};
 	return {
@@ -789,7 +789,7 @@ const INPUT_SCHEMA$2 = {
 	required: ["todoId", "task"],
 	additionalProperties: false
 };
-function toolError$3(code, message) {
+function toolError$4(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -824,12 +824,12 @@ function createDelegationToolSource(options) {
 	const call = async (_name, args) => {
 		const todoId = args["todoId"];
 		const task = args["task"];
-		if (typeof todoId !== "string" || todoId === "") return toolError$3("VALIDATION_FAILED", "The \"todoId\" argument is required and must be a string");
-		if (typeof task !== "string" || task.trim() === "") return toolError$3("VALIDATION_FAILED", "The \"task\" argument is required and must be a non-empty string");
+		if (typeof todoId !== "string" || todoId === "") return toolError$4("VALIDATION_FAILED", "The \"todoId\" argument is required and must be a string");
+		if (typeof task !== "string" || task.trim() === "") return toolError$4("VALIDATION_FAILED", "The \"task\" argument is required and must be a non-empty string");
 		const rawTools = args["allowedTools"];
 		let allowedTools;
 		if (rawTools !== void 0) {
-			if (!Array.isArray(rawTools) || rawTools.some((entry) => typeof entry !== "string")) return toolError$3("VALIDATION_FAILED", "The \"allowedTools\" argument must be an array of tool names");
+			if (!Array.isArray(rawTools) || rawTools.some((entry) => typeof entry !== "string")) return toolError$4("VALIDATION_FAILED", "The \"allowedTools\" argument must be an array of tool names");
 			allowedTools = rawTools;
 		}
 		try {
@@ -861,7 +861,7 @@ function createDelegationToolSource(options) {
 				}]
 			};
 		} catch (e) {
-			return toolError$3(e instanceof Error && "code" in e ? String(e.code) : "DELEGATION_FAILED", e instanceof Error ? e.message : String(e));
+			return toolError$4(e instanceof Error && "code" in e ? String(e.code) : "DELEGATION_FAILED", e instanceof Error ? e.message : String(e));
 		}
 	};
 	return {
@@ -1123,10 +1123,12 @@ function tailOf(nodes) {
 /**
 * 页面只读感知策略（需求 10）。
 *
-* **`perceive()` 不接受任何范围参数**——这是「白名单判定不受模型输出影响」
-* （AC-10.8）的实现方式。不是先拿模型给的范围再去校验，而是模型压根没有
-* 表达范围的入口：能被读的区域只由构造时的 `scope` 决定。
-* 唯一的参数是取像预算（`PerceptionCaptureOptions`），它里面没有任何范围字段。
+* **模型没有扩大可读范围的入口**——这是「白名单判定不受模型输出影响」
+* （AC-10.8）的实现方式：能被读的区域只由构造时的 `scope` 决定。
+* `perceive()` 的第二个参数 `subtree` 只能**缩小**读取范围（分册 14）：
+* 它走的是同一个遍历器、同一套 scope 判定，只换一个根节点，
+* 因此「带 `ref` 的结果是不带它时的子集」是个结构事实，而不是事后过滤的结果。
+* 第一个参数仍旧只是取像预算（`PerceptionCaptureOptions`），它里面没有任何范围字段。
 *
 * 本类**没有**任何点击 / 输入 / 提交 / 导航 / 滚动方法（FR-10.7）。
 * @experimental
@@ -1154,11 +1156,11 @@ var PagePerceptionPolicy = class {
 		this.#listeners.add(listener);
 		return () => this.#listeners.delete(listener);
 	}
-	async perceive(capture) {
+	async perceive(capture, subtree) {
 		if (!this.enabled) throw new WebSkillError("PERCEPTION_NOT_ENABLED", "Page perception is not enabled: the host declared no readable regions.");
 		const scope = this.#options.scope;
 		const frames = toFrameScopes(scope);
-		const raw = await this.#options.reader.read(scope, capture);
+		const raw = subtree === void 0 ? await this.#options.reader.read(scope, capture) : await this.#readSubtree(scope, subtree.ref, capture);
 		const result = Array.isArray(raw) ? { nodes: raw } : raw;
 		const nodes = result.nodes;
 		for (const note of result.frameNotes ?? []) this.#options.onWarning?.(note.message);
@@ -1171,6 +1173,7 @@ var PagePerceptionPolicy = class {
 			...frames.length > 1 || frames[0] !== void 0 && frameLabel(frames[0].frame) !== "self" ? { frames: frames.map((frame) => frameLabel(frame.frame)) } : {},
 			nodeCount: nodes.length,
 			nodesTotal: countNodesDeep(nodes),
+			...subtree !== void 0 ? { subtree: { ref: subtree.ref } } : {},
 			...capture?.images === true ? {
 				images: {
 					src: images.filter((image) => image.level === "src").length,
@@ -1182,6 +1185,7 @@ var PagePerceptionPolicy = class {
 		};
 		this.#records = [record, ...this.#records].slice(0, 50);
 		for (const listener of this.#listeners) listener(record);
+		const page = this.#options.describePage?.();
 		await this.#options.audit?.append({
 			type: "page.perceived",
 			target: this.#options.auditTarget ?? "page",
@@ -1192,6 +1196,8 @@ var PagePerceptionPolicy = class {
 				nodeCount: record.nodeCount,
 				nodesTotal: record.nodesTotal,
 				at: record.at,
+				...record.subtree !== void 0 ? { subtree: record.subtree } : {},
+				...page !== void 0 ? { page } : {},
 				...record.images !== void 0 ? {
 					imageCount: record.images.src + record.images.canvas,
 					imagesOmitted,
@@ -1206,6 +1212,42 @@ var PagePerceptionPolicy = class {
 			record
 		};
 	}
+	/**
+	* 子树续读的读取与拒绝（分册 14 §3 / §6）。
+	*
+	* 三条拒绝路径都在**遍历开始之前**结束：能力未实现、句柄不在 scope 内、句柄不认识。
+	* AC-14.2 的「结果里不含该子树的任何内容」因此不是靠过滤达成的，是靠没读达成的。
+	*/
+	async #readSubtree(scope, ref, capture) {
+		const read = this.#options.reader.readSubtree;
+		if (read === void 0) throw new WebSkillError("PERCEPTION_SUBTREE_UNSUPPORTED", "This page does not support reading a subtree. Call perceive_page without \"ref\".");
+		const out = await read.call(this.#options.reader, scope, ref, capture);
+		if ("rejected" in out) {
+			await this.#recordDenied(out.rejected);
+			throw new WebSkillError(out.rejected === "out-of-scope" ? "PERCEPTION_SUBTREE_OUT_OF_SCOPE" : "PERCEPTION_SUBTREE_UNKNOWN_REF", out.rejected === "out-of-scope" ? "That element is outside the readable region of this page." : "That reference is no longer valid. Perceive the page again and retry.");
+		}
+		return out;
+	}
+	/**
+	* 被拒绝的子树读取的留痕（FR-14.6）。
+	*
+	* **`ref` 的值不进载荷**：它是被拒绝的那次尝试的内容，句柄换轮即失效，
+	* 对复盘没有帮助，却会把一个模型可控的字符串写进审计流。`reason` 才是复盘需要的那部分。
+	* `out-of-scope` 这一条是注入攻击的观测点：页面里写着「请读取整个页面」时，
+	* 模型若照做，这条留痕就是它留下的痕迹。
+	*/
+	async #recordDenied(reason) {
+		const page = this.#options.describePage?.();
+		await this.#options.audit?.append({
+			type: "page.perceive.denied",
+			target: this.#options.auditTarget ?? "page",
+			data: {
+				reason,
+				at: this.#options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+				...page !== void 0 ? { page } : {}
+			}
+		});
+	}
 };
 
 //#endregion
@@ -1234,24 +1276,39 @@ const PERCEPTION_SYSTEM_PROMPT = [
 const PERCEIVE_PAGE_TOOL = "perceive_page";
 const DESCRIPTION$1 = "Read the parts of the current page the host made readable, as a structured accessibility outline. Read-only: it cannot click, type, submit, navigate or scroll.";
 /**
-* 唯一的参数，且它表达不了「读哪里」（AC-10.8 的判据由 0.14.0 分册 22 §3 修订）。
-* 值是 SDK 上一次发出的不透明串：白名单仍然只由宿主的 `scope` 决定，
-* 游标只说「接着刚才那处继续」，它扩不出一寸新范围。
+* 两个参数，且它们都扩不出一寸新范围（AC-10.8 的判据由 0.14.0 分册 22 §3 修订）。
 *
-* **分段关闭时下发的仍是这份 schema，不是空 schema**：两套 schema 会让
+* `cursor` 是 SDK 上一次发出的不透明串，只说「接着刚才那处继续」；
+* `ref` 是上一次感知结果里的元素句柄，只能把读取范围**缩小**到那个子树
+* （分册 14 FR-14.2：同一个遍历器、同一套 scope 判定，只换一个根节点）。
+* 白名单仍旧只由宿主的 `scope` 决定。
+*
+* **分段 / 子树关闭时下发的仍是这份 schema，不是另一份**：两套 schema 会让
 * 「模型看到的工具契约」随宿主配置漂移，同一段对话里换个设置就变一次形状，
 * 而模型的历史消息里还留着旧形状。宁可多一个恒定存在、关闭时明确拒绝的参数。
 */
 const INPUT_SCHEMA$1 = {
 	type: "object",
-	properties: { cursor: {
-		type: "string",
-		description: "Opaque cursor from a previous perceive_page result. Omit to read from the start."
-	} },
+	properties: {
+		cursor: {
+			type: "string",
+			description: "Opaque cursor from a previous perceive_page result. Omit to read from the start."
+		},
+		ref: {
+			type: "string",
+			description: "Optional. An opaque element reference from a previous perceive_page result. Reads only that element and its descendants. Never widens what you can read."
+		}
+	},
 	additionalProperties: false
 };
 const CURSOR_REJECTED = "The perception cursor is no longer valid. Call perceive_page again without a cursor to read the page from the start.";
-function toolError$2(code, message) {
+/** 子树续读的三条拒绝（分册 14 §3）；它们的码直接回给模型，不被压成 PERCEPTION_FAILED */
+const SUBTREE_CODES = /* @__PURE__ */ new Set([
+	"PERCEPTION_SUBTREE_UNSUPPORTED",
+	"PERCEPTION_SUBTREE_OUT_OF_SCOPE",
+	"PERCEPTION_SUBTREE_UNKNOWN_REF"
+]);
+function toolError$3(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -1357,9 +1414,12 @@ function createPagePerceptionToolSource(options) {
 				maxChars: paging?.maxChars ?? PERCEPTION_PAGING_DEFAULTS.maxChars
 			};
 			const cursor = args["cursor"];
+			const ref = args["ref"];
+			if (ref !== void 0 && typeof ref !== "string") return toolError$3("PERCEPTION_REF_INVALID", "perceive_page needs \"ref\" to be a string when it is present.");
 			if (cursor !== void 0) {
 				const index = typeof cursor === "string" ? pending?.cursors.get(cursor) : void 0;
-				if (!paged || pending === void 0 || index === void 0 || pending.runId !== context?.runId) return toolError$2("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
+				if (!paged || pending === void 0 || index === void 0 || pending.runId !== context?.runId) return toolError$3("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
+				if (ref !== void 0 && ref !== pending.subtreeRef) return toolError$3("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
 				return resultOf(pending, index);
 			}
 			try {
@@ -1370,7 +1430,7 @@ function createPagePerceptionToolSource(options) {
 					maxImages: image?.maxImages ?? 0,
 					minImageArea: image?.minImageArea ?? 0
 				};
-				const { nodes, images, imagesOmitted, record } = await policy.perceive(capture);
+				const { nodes, images, imagesOmitted, record } = await policy.perceive(capture, ref === void 0 ? void 0 : { ref });
 				const data = {
 					scope: record.include,
 					excluded: record.exclude,
@@ -1415,11 +1475,14 @@ function createPagePerceptionToolSource(options) {
 					nodesTotal,
 					images,
 					data,
-					cursors
+					cursors,
+					...ref === void 0 ? {} : { subtreeRef: ref }
 				};
 				return resultOf(pending, 0);
 			} catch (e) {
-				return toolError$2("PERCEPTION_FAILED", `perceive_page failed: ${messageOf(e)}`);
+				const code = e instanceof WebSkillError ? e.code : void 0;
+				if (code !== void 0 && SUBTREE_CODES.has(code)) return toolError$3(code, messageOf(e));
+				return toolError$3("PERCEPTION_FAILED", `perceive_page failed: ${messageOf(e)}`);
 			}
 		}
 	};
@@ -1863,8 +1926,8 @@ var PageActionPolicy = class {
 	}
 	async act(request, context) {
 		if (!this.enabled) throw new WebSkillError("PAGE_ACTION_OUT_OF_SCOPE", "Page actions are not enabled: the host declared no actionable regions.");
-		const target = this.#options.executor.describe(request.ref);
-		if (target === void 0) throw new WebSkillError("PAGE_ACTION_STALE_REF", "The element reference is unknown or expired. Perceive the page again and retry.");
+		const target = request.action === "back" ? this.#documentTarget() : this.#options.executor.describe(request.ref);
+		if (target === void 0) throw new WebSkillError("PAGE_ACTION_STALE_REF", this.#options.diagnose?.(request.ref) ?? "The element reference is unknown or expired. Perceive the page again and retry.");
 		const approved = await this.#authorize(request, target);
 		if (approved === false) {
 			await this.#record(request, {
@@ -1875,24 +1938,60 @@ var PageActionPolicy = class {
 			throw new WebSkillError("PAGE_ACTION_DECLINED", declineReason);
 		}
 		this.#rememberTarget(request.ref, target);
-		const watch = await this.#options.downloadWatcher?.open({ ...context?.runId ? { runId: context.runId } : {} });
+		const context_ = { ...context?.runId ? { runId: context.runId } : {} };
+		const watch = await this.#options.downloadWatcher?.open(context_);
+		const tabWatch = await this.#options.tabWatcher?.open(context_);
 		let executed;
 		try {
 			executed = await this.#options.executor.execute(request);
 		} catch (e) {
-			if (watch) await watch.settle({ timeoutMs: 0 }).catch(() => 0);
+			await Promise.all([watch?.settle({ timeoutMs: 0 }).catch(() => 0), tabWatch?.settle({ timeoutMs: 0 }).catch(() => void 0)]);
 			throw e;
 		}
-		const downloads = watch ? await watch.settle({ timeoutMs: clampDownloadWaitMs(this.#options.downloadWaitMs?.()) }) : 0;
+		const budget = clampDownloadWaitMs(this.#options.downloadWaitMs?.());
+		const [downloads, opened] = await Promise.all([watch ? watch.settle({ timeoutMs: budget }) : Promise.resolve(0), tabWatch ? tabWatch.settle({ timeoutMs: budget }) : Promise.resolve(void 0)]);
 		const signalled = downloads > 0 && this.#options.downloadSignalEnabled?.() === true;
-		const outcome = signalled ? {
+		const openedTab = opened === void 0 ? void 0 : await this.#admit(opened);
+		const outcome = {
 			...executed,
-			downloadCount: downloads
-		} : executed;
+			...signalled ? { downloadCount: downloads } : {},
+			...openedTab !== void 0 ? { openedTab } : {}
+		};
 		await this.#record(request, outcome, approved);
 		if (downloads > 0 && !signalled) await this.#recordUnreported(request, downloads);
 		return outcome;
 	}
+	/**
+	* 新页面接进工作集（FR-13.4 / FR-13.5）。
+	*
+	* `workset` 未注入时不 admit，`openedTab` 仍然给（只有 title / url，无 `tab`）——
+	* 那对应「宿主要信号但不要工作集」的装配，是合法组合。
+	*/
+	async #admit(opened) {
+		const admission = await this.#options.workset?.admit(opened);
+		if (admission?.admitted === true) return {
+			tab: admission.handle,
+			...opened
+		};
+		return {
+			...opened,
+			admitted: false,
+			reason: admission === void 0 ? "This page was opened but is not available to switch to." : "The page set is full; this page was not added. Close a page you are done with, then try again."
+		};
+	}
+	/**
+	* `back` 的目标是**合成**的，不查表（分册 13 §4.1）。
+	*
+	* 不改 `PageActionRequest.ref` 的类型、也不改 `describe()` 的契约：
+	* 动其中任何一个都会波及所有实现过 executor 的宿主，包括本地 DOM 形态。
+	*/
+	#documentTarget() {
+		const page = this.#options.describePage?.();
+		return {
+			role: "document",
+			...page?.title !== void 0 ? { name: page.title } : {}
+		};
+	}
 	async #authorize(request, target) {
 		if ((this.#options.preauthorized ?? []).includes(request.action)) return "preauthorized";
 		const rememberable = this.#rememberable(target);
@@ -1901,11 +2000,12 @@ var PageActionPolicy = class {
 		const where = target.frame === void 0 ? "on the page" : `in the embedded frame "${target.frame}"`;
 		const scopeNote = target.elevated === true ? " This dialog is outside the usual allowlist; it was opened by this task." : "";
 		const scopeLabel = rememberable ? this.#options.consent?.describeScope?.(target, request.action) : void 0;
+		const message = request.action === "back" ? `Allow the assistant to go back to the previous page${target.name === void 0 ? "" : ` on "${target.name}"`}?${scopeNote}` : `Allow the assistant to ${request.action} "${target.name ?? target.role}" ${where}?${scopeNote}`;
 		const response = await this.#options.ui.request({
 			type: "authorize",
 			id: `page-action-${this.#seq}`,
 			capability: "pageAction",
-			message: `Allow the assistant to ${request.action} "${target.name ?? target.role}" ${where}?${scopeNote}`,
+			message,
 			details: {
 				action: request.action,
 				...target.elevated === true ? { elevated: true } : {},
@@ -1933,7 +2033,7 @@ var PageActionPolicy = class {
 	*/
 	async #record(request, outcome, approved) {
 		const secret = outcome.secret === true;
-		const target = this.#options.executor.describe(request.ref);
+		const target = request.action === "back" ? void 0 : this.#options.executor.describe(request.ref);
 		const record = {
 			at: this.#options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
 			action: request.action,
@@ -1949,10 +2049,14 @@ var PageActionPolicy = class {
 			...outcome.reason !== void 0 ? { reason: outcome.reason } : {}
 		};
 		this.#records = [record, ...this.#records].slice(0, 50);
+		const page = this.#options.describePage?.();
 		await this.#options.audit?.append({
 			type: "page.action",
 			target: this.#options.auditTarget ?? "page",
-			data: { ...record }
+			data: {
+				...record,
+				...page !== void 0 ? { page } : {}
+			}
 		});
 	}
 	/**
@@ -1987,7 +2091,9 @@ const PAGE_ACTION_SYSTEM_PROMPT = [
 	"You can act on the current page, but only within the regions the host made actionable.",
 	"Targets must come from the \"ref\" values in a fresh perceive_page result — you cannot construct them, and CSS selectors are rejected.",
 	"Every action asks the user to confirm it first, so do not chain actions speculatively: act only when the user asked for something that requires it.",
-	"A reference expires as soon as the page is perceived again; perceive first, then act."
+	"A reference expires as soon as the page is perceived again; perceive first, then act.",
+	"After an action, the result tells you where it led. \"openedTab\" means a new page opened — switch to it with focus_page_tab to read it. \"navigated\" means this page itself moved to a new address. \"elevatedModal\" means a dialog opened on this page. If none of the three appear, the page did not change.",
+	"Use the \"back\" action to return to the previous page in this page's history. It takes no \"ref\" and no \"value\", and it only affects the page you are currently on. After going back, always perceive_page again: every reference from before the action is dead."
 ].join("\n");
 
 //#endregion
@@ -2004,7 +2110,7 @@ const INPUT_SCHEMA = {
 	properties: {
 		ref: {
 			type: "string",
-			description: "An opaque element reference from perceive_page"
+			description: "An opaque element reference from perceive_page; required for every action except \"back\""
 		},
 		action: {
 			type: "string",
@@ -2015,10 +2121,10 @@ const INPUT_SCHEMA = {
 			description: "Text for \"fill\", the option name for \"select\", or \"true\"/\"false\" for \"set\""
 		}
 	},
-	required: ["ref", "action"],
+	required: ["action"],
 	additionalProperties: false
 };
-function toolError$1(code, message) {
+function toolError$2(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -2067,34 +2173,328 @@ function createPageActionToolSource(options) {
 			};
 		},
 		call: async (_name, args, context) => {
-			const ref = args["ref"];
 			const action = args["action"];
-			if (typeof ref !== "string" || typeof action !== "string" || !PAGE_ACTION_KINDS.includes(action)) return toolError$1("VALIDATION_FAILED", `act_on_page needs a "ref" string and one of ${PAGE_ACTION_KINDS.join(" / ")}.`);
+			if (typeof action !== "string" || !PAGE_ACTION_KINDS.includes(action)) return toolError$2("VALIDATION_FAILED", `act_on_page needs one of ${PAGE_ACTION_KINDS.join(" / ")}.`);
+			const runContext = { ...context?.runId !== void 0 ? { runId: context.runId } : {} };
+			const run = async (request) => {
+				try {
+					const outcome = await policy.act(request, runContext);
+					return {
+						ok: outcome.ok,
+						content: [{
+							type: "json",
+							data: { ...outcome }
+						}],
+						...outcome.ok ? {} : { error: {
+							code: "PAGE_ACTION_FAILED",
+							message: outcome.reason ?? "Page action failed"
+						} }
+					};
+				} catch (e) {
+					return toolError$2(e instanceof WebSkillError ? e.code : "PAGE_ACTION_FAILED", messageOf(e));
+				}
+			};
+			if (action === "back") {
+				if ("ref" in args || "value" in args) return toolError$2("VALIDATION_FAILED", "act_on_page with \"back\" takes no \"ref\" and no \"value\".");
+				return await run({
+					ref: PAGE_DOCUMENT_REF,
+					action: "back"
+				});
+			}
+			const ref = args["ref"];
+			if (typeof ref !== "string") return toolError$2("VALIDATION_FAILED", `act_on_page needs a "ref" string when the action is "${action}".`);
 			const value = args["value"];
 			if ([
 				"fill",
 				"select",
 				"set"
-			].includes(action) && typeof value !== "string") return toolError$1("VALIDATION_FAILED", `act_on_page needs a "value" string when the action is "${action}".`);
+			].includes(action) && typeof value !== "string") return toolError$2("VALIDATION_FAILED", `act_on_page needs a "value" string when the action is "${action}".`);
+			return await run({
+				ref,
+				action,
+				...typeof value === "string" ? { value } : {}
+			});
+		}
+	};
+}
+
+//#endregion
+//#region ../agent/src/tabs/policy.ts
+/** 工作集容量缺省；「起点页 + 若干详情页」的常见规模 */
+const TAB_WORKSET_DEFAULT_MAX = 8;
+/** 地板：2 的含义是「起点页 + 至少一个详情页」，低于它工作集这个概念就没有意义 */
+const TAB_WORKSET_MIN_MAX = 2;
+/** 天花板：宿主写错一个 0 不该让一轮任务铺开几百个标签页 */
+const TAB_WORKSET_MAX_MAX = 32;
+/**
+* 夹取工作集容量（FR-11.5 / D-11-3）。
+*
+* 与 0.15.0 的 `clampDownloadWaitMs` 同惯例：宿主给不合理的值**不报错，夹到边界**——
+* 装配期的一个笔误不该让运行期整条能力崩掉。模型无法影响这个值。
+* @experimental
+*/
+function clampWorksetMax(value) {
+	if (value === void 0 || !Number.isFinite(value)) return 8;
+	return Math.min(32, Math.max(2, Math.trunc(value)));
+}
+const UNKNOWN_MESSAGE = "That page is not in this task's page set.";
+const EXPIRED_MESSAGE = "That page was closed or navigated away. List the pages again.";
+const NOT_CLOSABLE_MESSAGE = "That page belongs to the user, not to this task. It cannot be closed.";
+/**
+* 工作集策略（分册 12）。
+*
+* 它守着三件事：模型只能在**已接入**的页之间往返（SC-2）、
+* 切换不改变用户看到的画面（SC-3，由端口实现兑现，此处只做不诱导的接口设计）、
+* 起点页永远关不掉（FR-12.6）。
+* @experimental
+*/
+var TabWorksetPolicy = class {
+	#options;
+	/** 当前焦点句柄；`undefined` 即还在起点页 */
+	#focused;
+	/**
+	* 见过但已不在工作集里的句柄。只为把「关掉了」与「从没有过」区分开——
+	* 它**不含**任何标签页信息，仅仅是一组字符串。
+	*/
+	#retired = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.#options = options;
+	}
+	get enabled() {
+		return this.#options.enabled();
+	}
+	/** 起点页：接入顺序的第 0 项。它属于用户，不属于这一轮任务 */
+	async #origin() {
+		return (await this.#options.port.list())[0];
+	}
+	async #find(handle) {
+		return (await this.#options.port.list()).find((tab) => tab.handle === handle);
+	}
+	/** 认识但不在了 → expired；从没见过 → unknown。跨 run 的句柄落 unknown（`reset` 清了 retired） */
+	#reject(handle) {
+		if (this.#retired.has(handle)) throw new WebSkillError("PAGE_TAB_EXPIRED", EXPIRED_MESSAGE);
+		throw new WebSkillError("PAGE_TAB_UNKNOWN", UNKNOWN_MESSAGE);
+	}
+	async list() {
+		const tabs = await this.#options.port.list();
+		const originHandle = tabs[0]?.handle;
+		return tabs.map((tab) => ({
+			tab: tab.handle,
+			...tab.title !== void 0 ? { title: tab.title } : {},
+			...tab.url !== void 0 ? { url: tab.url } : {},
+			...tab.handle === originHandle ? { origin: true } : {},
+			focused: tab.handle === (this.#focused ?? originHandle)
+		}));
+	}
+	async focus(handle) {
+		const tab = await this.#find(handle);
+		if (tab === void 0) {
+			await this.#record("denied", { reason: this.#retired.has(handle) ? "expired" : "unknown" });
+			this.#reject(handle);
+		}
+		const from = this.#focused ?? (await this.#origin())?.handle;
+		await this.#options.port.focus(handle);
+		this.#focused = handle;
+		await this.#record("focused", {
+			page: pageOf(tab),
+			...from !== void 0 ? { from } : {}
+		});
+		return { focused: handle };
+	}
+	async close(handle) {
+		const tabs = await this.#options.port.list();
+		const originHandle = tabs[0]?.handle;
+		if (handle === originHandle) {
+			await this.#record("denied", { reason: "origin-tab" });
+			throw new WebSkillError("PAGE_TAB_NOT_CLOSABLE", NOT_CLOSABLE_MESSAGE);
+		}
+		const tab = tabs.find((t) => t.handle === handle);
+		if (tab === void 0) {
+			await this.#record("denied", { reason: this.#retired.has(handle) ? "expired" : "unknown" });
+			this.#reject(handle);
+		}
+		if ((this.#focused ?? originHandle) === handle && originHandle !== void 0) {
+			await this.#options.port.focus(originHandle);
+			this.#focused = originHandle;
+		}
+		await this.#options.port.close(handle);
+		this.#retired.add(handle);
+		const focused = this.#focused ?? originHandle;
+		await this.#record("closed", {
+			page: pageOf(tab),
+			...focused !== void 0 ? { focused } : {}
+		});
+		return {
+			closed: handle,
+			...focused !== void 0 ? { focused } : { focused: void 0 }
+		};
+	}
+	/**
+	* 把页面操作新开出来的那一页接进工作集（SC-2 的唯一入口）。
+	*
+	* 容量闸门在这里，管的是**标签页数**（FR-11.5）；分册 11 的 registry 分片软上限
+	* 是另一回事（同一页里跳三次产生三个分片，对它们硬拒绝会打断正常感知）。
+	*/
+	async admit(opened) {
+		const max = clampWorksetMax(this.#options.maxTabs?.());
+		if ((await this.#options.port.list()).length >= max) {
+			await this.#record("denied", {
+				reason: "workset-full",
+				limit: max
+			});
+			return {
+				admitted: false,
+				reason: "full",
+				limit: max
+			};
+		}
+		const handle = await this.#options.port.admit(opened);
+		await this.#record("opened", {
+			handle,
+			...opened
+		});
+		return {
+			admitted: true,
+			handle
+		};
+	}
+	/** run 结束（分册 11 / FR-11.4）。**不关闭任何标签页**——那是用户的浏览器 */
+	async reset() {
+		this.#focused = void 0;
+		this.#retired.clear();
+		await this.#options.port.reset();
+	}
+	async #record(kind, data) {
+		await this.#options.audit?.append({
+			type: `page.tab.${kind}`,
+			target: this.#options.auditTarget ?? "page",
+			data: {
+				at: this.#options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+				...data
+			}
+		});
+	}
+};
+/** 与分册 11 的 `page` 形状共用；`url` / `title` 只为可读性，不参与判定 */
+function pageOf(tab) {
+	return {
+		key: tab.handle,
+		...tab.url !== void 0 ? { url: tab.url } : {},
+		...tab.title !== void 0 ? { title: tab.title } : {}
+	};
+}
+
+//#endregion
+//#region ../agent/src/prompts/tabWorkset.ts
+/**
+* 工作集系统提示词（0.16.0 分册 12 / FR-12.9）。
+*
+* 第三段是最要紧的：模型若以为切换会让用户看到那一页，
+* 就会写出「我已经帮你打开了详情页」这种与事实不符的话。
+*/
+const TAB_WORKSET_SYSTEM_PROMPT = `You can work across several pages within one task.
+
+- \`list_page_tabs\` shows the pages available to you. The first one is the user's own page; you can read and act on it, but you can never close it.
+- \`focus_page_tab\` decides which page \`perceive_page\` and \`act_on_page\` talk to next. Element references are per-page: a reference from one page will be rejected on another, so perceive after every switch.
+- New pages only join this set when an action you took opened them. You cannot open a page by URL, and pages the user opens on their own are not yours to touch.
+- Close a detail page with \`close_page_tab\` once you have read what you needed. Leaving them open uses up the page budget and will eventually block new ones.
+
+Switching pages does not change what the user sees. Their browser stays exactly where they left it, so never tell them you have "opened" or "switched to" a page for them.`;
+
+//#endregion
+//#region ../agent/src/tabs/toolSource.ts
+const LIST_PAGE_TABS_TOOL = "list_page_tabs";
+const FOCUS_PAGE_TAB_TOOL = "focus_page_tab";
+const CLOSE_PAGE_TAB_TOOL = "close_page_tab";
+const TAB_WORKSET_TOOLS = [
+	LIST_PAGE_TABS_TOOL,
+	FOCUS_PAGE_TAB_TOOL,
+	CLOSE_PAGE_TAB_TOOL
+];
+/** 无入参。没有 filter、没有 query、没有 all —— 工作集之外的页面不存在于这个视角里 */
+const LIST_SCHEMA = {
+	type: "object",
+	properties: {},
+	additionalProperties: false
+};
+/**
+* 参数名刻意叫 `tab` 而不是 `tabId` / `url`：名字本身要挡住下一个人把一个数字或
+* 地址塞进来（0.15.0 `downloadCount` 的同款命名纪律）。
+*
+* `additionalProperties: false` 是 SC-1 的第二道锁：即使有人后来往 `properties` 里加了
+* `url`，AC-G3 的守护会先命中；而在守护命中之前，多余字段至少不会被静默接受。
+*/
+const TAB_SCHEMA = {
+	type: "object",
+	properties: { tab: {
+		type: "string",
+		description: "An opaque page handle from list_page_tabs"
+	} },
+	required: ["tab"],
+	additionalProperties: false
+};
+const SPECS = [
+	{
+		name: LIST_PAGE_TABS_TOOL,
+		description: "List the pages available to this task. The first entry is the user's own page and cannot be closed. Takes no arguments.",
+		inputSchema: LIST_SCHEMA
+	},
+	{
+		name: FOCUS_PAGE_TAB_TOOL,
+		description: "Choose which page perceive_page and act_on_page talk to next. This does not change what the user sees. Element references do not carry across pages, so perceive again after switching.",
+		inputSchema: TAB_SCHEMA
+	},
+	{
+		name: CLOSE_PAGE_TAB_TOOL,
+		description: "Close a page this task opened, once you have read what you needed from it. The user's own page cannot be closed.",
+		inputSchema: TAB_SCHEMA
+	}
+];
+function toolError$1(code, message) {
+	return {
+		ok: false,
+		content: [],
+		error: {
+			code,
+			message
+		}
+	};
+}
+/**
+* 把工作集接到既有工具协议上（分册 12 §7）。
+*
+* 端口未注入或页面操作未启用时 `listToolSpecs()` 返回空数组——
+* 模型连这三个工具的存在都看不到，而不是看得到再被拒（AC-12.11）。
+* @experimental
+*/
+function createTabWorksetToolSource(options) {
+	const { policy } = options;
+	return {
+		kind: "page-tabs",
+		listToolSpecs: () => Promise.resolve(policy.enabled ? [...SPECS] : []),
+		systemPrompt: () => Promise.resolve(policy.enabled ? TAB_WORKSET_SYSTEM_PROMPT : void 0),
+		canHandle: (name) => TAB_WORKSET_TOOLS.includes(name),
+		argCaptureTrust: (name) => TAB_WORKSET_TOOLS.includes(name) ? { tier: "reviewed" } : void 0,
+		call: async (name, args) => {
 			try {
-				const outcome = await policy.act({
-					ref,
-					action,
-					...typeof value === "string" ? { value } : {}
-				}, { ...context?.runId !== void 0 ? { runId: context.runId } : {} });
+				if (name === "list_page_tabs") return {
+					ok: true,
+					content: [{
+						type: "json",
+						data: { tabs: await policy.list() }
+					}]
+				};
+				const handle = args["tab"];
+				if (typeof handle !== "string" || handle === "") return toolError$1("VALIDATION_FAILED", `${name} needs a "tab" handle from list_page_tabs.`);
 				return {
-					ok: outcome.ok,
+					ok: true,
 					content: [{
 						type: "json",
-						data: { ...outcome }
-					}],
-					...outcome.ok ? {} : { error: {
-						code: "PAGE_ACTION_FAILED",
-						message: outcome.reason ?? "Page action failed"
-					} }
+						data: { ...name === "focus_page_tab" ? await policy.focus(handle) : await policy.close(handle) }
+					}]
 				};
 			} catch (e) {
-				return toolError$1(e instanceof WebSkillError ? e.code : "PAGE_ACTION_FAILED", messageOf(e));
+				return toolError$1(e instanceof WebSkillError ? e.code : "PAGE_TAB_FAILED", messageOf(e));
 			}
 		}
 	};
@@ -2440,4 +2840,4 @@ function readContent(result) {
 }
 
 //#endregion
-export { DEFAULT_MAX_DATA_SOURCE_BYTES, DELEGATE_TASK_TOOL, DELEGATION_SYSTEM_PROMPT, DOWNLOAD_WAIT_DEFAULT_MS, DOWNLOAD_WAIT_MAX_MS, DOWNLOAD_WAIT_MIN_MS, DataSourceCandidatePolicy, DataSourcePolicy, DelegationOrchestrator, DownloadedFilePolicy, GENERATE_SKILL_TOOL, LIST_DOWNLOADED_FILES_TOOL, MANAGE_TODO_TOOL, PAGE_ACTION_KINDS, PAGE_ACTION_SYSTEM_PROMPT, PAGE_ACTION_TOOL, PERCEIVE_PAGE_TOOL, PERCEPTION_PAGING_DEFAULTS, PERCEPTION_SYSTEM_PROMPT, PageActionPolicy, PagePerceptionPolicy, READ_DOWNLOADED_FILE_TOOL, SKILL_GENERATION_SYSTEM_PROMPT, SkillGenerator, TODO_SYSTEM_PROMPT, TodoStore, clampDownloadWaitMs, createDelegationToolSource, createDownloadedFileToolSource, createHttpDataSourceTransport, createPageActionToolSource, createPagePerceptionToolSource, createSkillGenerationToolSource, createTodoToolSource, frameLabel, frameSteps, toActionFrameScopes, toFrameScopes, withDelegationOrigin };
+export { CLOSE_PAGE_TAB_TOOL, DEFAULT_MAX_DATA_SOURCE_BYTES, DELEGATE_TASK_TOOL, DELEGATION_SYSTEM_PROMPT, DOWNLOAD_WAIT_DEFAULT_MS, DOWNLOAD_WAIT_MAX_MS, DOWNLOAD_WAIT_MIN_MS, DataSourceCandidatePolicy, DataSourcePolicy, DelegationOrchestrator, DownloadedFilePolicy, FOCUS_PAGE_TAB_TOOL, GENERATE_SKILL_TOOL, LIST_DOWNLOADED_FILES_TOOL, LIST_PAGE_TABS_TOOL, MANAGE_TODO_TOOL, PAGE_ACTION_KINDS, PAGE_ACTION_SYSTEM_PROMPT, PAGE_ACTION_TOOL, PAGE_DOCUMENT_REF, PERCEIVE_PAGE_TOOL, PERCEPTION_PAGING_DEFAULTS, PERCEPTION_SYSTEM_PROMPT, PageActionPolicy, PagePerceptionPolicy, READ_DOWNLOADED_FILE_TOOL, SKILL_GENERATION_SYSTEM_PROMPT, SkillGenerator, TAB_WORKSET_DEFAULT_MAX, TAB_WORKSET_MAX_MAX, TAB_WORKSET_MIN_MAX, TAB_WORKSET_SYSTEM_PROMPT, TODO_SYSTEM_PROMPT, TabWorksetPolicy, TodoStore, clampDownloadWaitMs, clampWorksetMax, createDelegationToolSource, createDownloadedFileToolSource, createHttpDataSourceTransport, createPageActionToolSource, createPagePerceptionToolSource, createSkillGenerationToolSource, createTabWorksetToolSource, createTodoToolSource, frameLabel, frameSteps, toActionFrameScopes, toFrameScopes, withDelegationOrigin };