@webskill/sdk 0.19.0 → 0.21.0

package/dist/agent.js

@@ -1,9 +1,10 @@
 import { n as messageOf, t as WebSkillError } from "./errors-BDZNpC13.js";
 import { b as parseSkillMarkdown, y as isValidSkillName } from "./skill-CAJMsLod.js";
 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 frameLabel, i as toFrameScopes, n as PAGE_DOCUMENT_REF, o as frameSteps, r as toActionFrameScopes, t as PAGE_ACTION_KINDS } from "./types-DOJI5YC3.js";
+import { n as sanitizeUntrustedLine, t as UNTRUSTED_LINE_LIMIT } from "./untrustedText-BIaRvPZK.js";
+import { c as formatAttachmentText, o as XLSX_MIME, s as classifyAttachment } from "./kind-DaKqLX2F.js";
+import { c as SPREADSHEET_EXTENSION, f as DEFAULT_MAX_DATA_SOURCE_BYTES, l as SPREADSHEET_LIMITS, o as toBase64, s as encodeSpreadsheet, u as SPREADSHEET_MIME_TYPE } from "./linkedDocument-C0gj1sMq.js";
+import { _ as frameSteps, a as defersImage, c as isPdfTextTrustworthy, d as DOCUMENT_READ_BUDGET, f as PAGE_ACTION_KINDS, g as frameLabel, h as toFrameScopes, i as asReadMode, l as measurePdfTextQuality, m as toActionFrameScopes, n as READ_DOCUMENT_TOOL, o as takesImage, p as PAGE_DOCUMENT_REF, r as createDocumentToolSource, s as PDF_GARBLED_RATIO, t as PDF_LARGE_IMAGE_RATIO, u as sniffDocumentFormat } from "./toolSource-C9oNuKmr.js";
 
 //#region ../agent/src/todo/store.ts
 const STATUSES = [
@@ -129,7 +130,7 @@ const STATUS_ENUM = [
 	"completed"
 ];
 const TODO_TOOL_DESCRIPTION = "Maintain the visible task list for a multi-step request. The rules are in the system prompt.";
-const INPUT_SCHEMA$4 = {
+const INPUT_SCHEMA$5 = {
 	type: "object",
 	properties: {
 		action: {
@@ -182,7 +183,7 @@ const INPUT_SCHEMA$4 = {
 	required: ["action"],
 	additionalProperties: false
 };
-function toolError$6(code, message) {
+function toolError$7(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -231,15 +232,15 @@ function createTodoToolSource(options = {}) {
 		try {
 			if (action === "create") {
 				const items = parseItems(args["items"]);
-				if (typeof items === "string") return Promise.resolve(toolError$6("VALIDATION_FAILED", items));
+				if (typeof items === "string") return Promise.resolve(toolError$7("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$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"));
+				if (typeof id !== "string") return Promise.resolve(toolError$7("VALIDATION_FAILED", "The \"id\" argument is required for action \"update\""));
+				if (status !== void 0 && typeof status !== "string") return Promise.resolve(toolError$7("VALIDATION_FAILED", "The \"status\" argument must be a string"));
 				const title = args["title"];
 				const list = store.update(id, {
 					...status !== void 0 ? { status } : {},
@@ -251,10 +252,10 @@ function createTodoToolSource(options = {}) {
 				store.clear();
 				return Promise.resolve(ok(events, progressText([])));
 			}
-			return Promise.resolve(toolError$6("VALIDATION_FAILED", "The \"action\" argument must be one of create, update, clear"));
+			return Promise.resolve(toolError$7("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$6(code, e instanceof Error ? e.message : String(e)));
+			return Promise.resolve(toolError$7(code, e instanceof Error ? e.message : String(e)));
 		} finally {
 			unsubscribe();
 		}
@@ -266,7 +267,7 @@ function createTodoToolSource(options = {}) {
 		listToolSpecs: () => Promise.resolve([{
 			name: MANAGE_TODO_TOOL,
 			description: TODO_TOOL_DESCRIPTION,
-			inputSchema: INPUT_SCHEMA$4
+			inputSchema: INPUT_SCHEMA$5
 		}]),
 		canHandle: (name) => name === MANAGE_TODO_TOOL,
 		argCaptureTrust: (name) => name === "manage_todo" ? { tier: "reviewed" } : void 0,
@@ -499,7 +500,7 @@ const SKILL_GENERATION_SYSTEM_PROMPT = [
 //#region ../agent/src/skillGeneration/toolSource.ts
 const GENERATE_SKILL_TOOL = "generate_skill";
 const TOOL_DESCRIPTION = "Turn the procedure just demonstrated in this conversation into a skill candidate. The user must confirm it, and a reviewer must approve it before anyone can use it.";
-const INPUT_SCHEMA$3 = {
+const INPUT_SCHEMA$4 = {
 	type: "object",
 	properties: {
 		name: {
@@ -557,7 +558,7 @@ const INPUT_SCHEMA$3 = {
 	],
 	additionalProperties: false
 };
-function toolError$5(code, message) {
+function toolError$6(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -626,7 +627,7 @@ function createSkillGenerationToolSource(options) {
 	const generator = new SkillGenerator(options);
 	const call = async (_name, args) => {
 		const draft = readDraft(args);
-		if (typeof draft === "string") return toolError$5("SKILL_GENERATION_VALIDATION_FAILED", draft);
+		if (typeof draft === "string") return toolError$6("SKILL_GENERATION_VALIDATION_FAILED", draft);
 		try {
 			const outcome = await generator.generate(draft);
 			if (outcome.status === "declined") return {
@@ -650,7 +651,7 @@ function createSkillGenerationToolSource(options) {
 				}]
 			};
 		} catch (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 toolError$6(e instanceof Error && "code" in e ? String(e.code) : "SKILL_GENERATION_VALIDATION_FAILED", e instanceof Error ? e.message : String(e));
 		}
 	};
 	return {
@@ -659,7 +660,7 @@ function createSkillGenerationToolSource(options) {
 		listToolSpecs: () => Promise.resolve([{
 			name: GENERATE_SKILL_TOOL,
 			description: TOOL_DESCRIPTION,
-			inputSchema: INPUT_SCHEMA$3
+			inputSchema: INPUT_SCHEMA$4
 		}]),
 		canHandle: (name) => name === GENERATE_SKILL_TOOL,
 		argCaptureTrust: (name) => name === "generate_skill" ? { tier: "reviewed" } : void 0,
@@ -769,7 +770,7 @@ const DELEGATION_SYSTEM_PROMPT = [
 //#region ../agent/src/delegation/toolSource.ts
 const DELEGATE_TASK_TOOL = "delegate_task";
 const DELEGATE_TOOL_DESCRIPTION = "Hand one self-contained sub-task to a sub-agent and wait for its summary. One delegation at a time.";
-const INPUT_SCHEMA$2 = {
+const INPUT_SCHEMA$3 = {
 	type: "object",
 	properties: {
 		todoId: {
@@ -789,7 +790,7 @@ const INPUT_SCHEMA$2 = {
 	required: ["todoId", "task"],
 	additionalProperties: false
 };
-function toolError$4(code, message) {
+function toolError$5(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -824,12 +825,12 @@ function createDelegationToolSource(options) {
 	const call = async (_name, args) => {
 		const todoId = args["todoId"];
 		const task = args["task"];
-		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");
+		if (typeof todoId !== "string" || todoId === "") return toolError$5("VALIDATION_FAILED", "The \"todoId\" argument is required and must be a string");
+		if (typeof task !== "string" || task.trim() === "") return toolError$5("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$4("VALIDATION_FAILED", "The \"allowedTools\" argument must be an array of tool names");
+			if (!Array.isArray(rawTools) || rawTools.some((entry) => typeof entry !== "string")) return toolError$5("VALIDATION_FAILED", "The \"allowedTools\" argument must be an array of tool names");
 			allowedTools = rawTools;
 		}
 		try {
@@ -861,7 +862,7 @@ function createDelegationToolSource(options) {
 				}]
 			};
 		} catch (e) {
-			return toolError$4(e instanceof Error && "code" in e ? String(e.code) : "DELEGATION_FAILED", e instanceof Error ? e.message : String(e));
+			return toolError$5(e instanceof Error && "code" in e ? String(e.code) : "DELEGATION_FAILED", e instanceof Error ? e.message : String(e));
 		}
 	};
 	return {
@@ -871,7 +872,7 @@ function createDelegationToolSource(options) {
 		listToolSpecs: () => Promise.resolve([{
 			name: DELEGATE_TASK_TOOL,
 			description: DELEGATE_TOOL_DESCRIPTION,
-			inputSchema: INPUT_SCHEMA$2
+			inputSchema: INPUT_SCHEMA$3
 		}]),
 		canHandle: (name) => name === DELEGATE_TASK_TOOL,
 		argCaptureTrust: (name) => name === "delegate_task" ? { tier: "reviewed" } : void 0,
@@ -1274,7 +1275,7 @@ const PERCEPTION_SYSTEM_PROMPT = [
 //#endregion
 //#region ../agent/src/perception/toolSource.ts
 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 or navigate.";
+const DESCRIPTION$2 = "Read the parts of the current page the host made readable, as a structured accessibility outline. Read-only: it cannot click, type, submit or navigate.";
 /**
 * 两个参数，且它们都扩不出一寸新范围（AC-10.8 的判据由 0.14.0 分册 22 §3 修订）。
 *
@@ -1287,7 +1288,7 @@ const DESCRIPTION$1 = "Read the parts of the current page the host made readable
 * 「模型看到的工具契约」随宿主配置漂移，同一段对话里换个设置就变一次形状，
 * 而模型的历史消息里还留着旧形状。宁可多一个恒定存在、关闭时明确拒绝的参数。
 */
-const INPUT_SCHEMA$1 = {
+const INPUT_SCHEMA$2 = {
 	type: "object",
 	properties: {
 		cursor: {
@@ -1308,7 +1309,7 @@ const SUBTREE_CODES = /* @__PURE__ */ new Set([
 	"PERCEPTION_SUBTREE_OUT_OF_SCOPE",
 	"PERCEPTION_SUBTREE_UNKNOWN_REF"
 ]);
-function toolError$3(code, message) {
+function toolError$4(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -1400,8 +1401,8 @@ function createPagePerceptionToolSource(options) {
 		kind: "page-perception",
 		listToolSpecs: () => Promise.resolve(policy.enabled ? [{
 			name: PERCEIVE_PAGE_TOOL,
-			description: DESCRIPTION$1,
-			inputSchema: INPUT_SCHEMA$1
+			description: DESCRIPTION$2,
+			inputSchema: INPUT_SCHEMA$2
 		}] : []),
 		systemPrompt: () => Promise.resolve(policy.enabled ? PERCEPTION_SYSTEM_PROMPT : void 0),
 		canHandle: (name) => name === PERCEIVE_PAGE_TOOL,
@@ -1415,11 +1416,11 @@ function createPagePerceptionToolSource(options) {
 			};
 			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 (ref !== void 0 && typeof ref !== "string") return toolError$4("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$3("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
-				if (ref !== void 0 && ref !== pending.subtreeRef) return toolError$3("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
+				if (!paged || pending === void 0 || index === void 0 || pending.runId !== context?.runId) return toolError$4("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
+				if (ref !== void 0 && ref !== pending.subtreeRef) return toolError$4("PERCEPTION_CURSOR_INVALID", CURSOR_REJECTED);
 				return resultOf(pending, index);
 			}
 			try {
@@ -1481,8 +1482,8 @@ function createPagePerceptionToolSource(options) {
 				return resultOf(pending, 0);
 			} catch (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)}`);
+				if (code !== void 0 && SUBTREE_CODES.has(code)) return toolError$4(code, messageOf(e));
+				return toolError$4("PERCEPTION_FAILED", `perceive_page failed: ${messageOf(e)}`);
 			}
 		}
 	};
@@ -1655,7 +1656,7 @@ const RECORD_LIMIT$1 = 50;
 function sanitizeDescription(value) {
 	return sanitizeUntrustedLine(value, DESCRIPTION_LIMIT);
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
 /**
@@ -1665,7 +1666,7 @@ function isRecord(value) {
 * 标成后者会让读代码的人以为它已经被验证过了。
 */
 function validate(raw, provenance) {
-	if (!isRecord(raw)) return void 0;
+	if (!isRecord$1(raw)) return void 0;
 	const { id, kind, description, target } = raw;
 	if (typeof id !== "string" || !ID_PATTERN.test(id)) return void 0;
 	if (typeof kind !== "string" || !OFFERABLE_KINDS.includes(kind)) return void 0;
@@ -2105,13 +2106,13 @@ const PAGE_ACTION_SYSTEM_PROMPT = [
 //#endregion
 //#region ../agent/src/pageAction/toolSource.ts
 const PAGE_ACTION_TOOL = "act_on_page";
-const DESCRIPTION = "Act on one element of the current page. The target must be a \"ref\" from a fresh perceive_page result; selectors are rejected. Each call asks the user to confirm before anything happens.";
+const DESCRIPTION$1 = "Act on one element of the current page. The target must be a \"ref\" from a fresh perceive_page result; selectors are rejected. Each call asks the user to confirm before anything happens.";
 /**
 * 入参里**没有** `scope` / `selector` / `include` / `frame` 一类字段（AC-23.2）：
 * 工具一旦接受它们，「能操作哪里」就有了一条从模型输出流进来的路径。
 * 模型能表达的只有「在哪个句柄上做哪个动作」。
 */
-const INPUT_SCHEMA = {
+const INPUT_SCHEMA$1 = {
 	type: "object",
 	properties: {
 		ref: {
@@ -2130,7 +2131,7 @@ const INPUT_SCHEMA = {
 	required: ["action"],
 	additionalProperties: false
 };
-function toolError$2(code, message) {
+function toolError$3(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -2153,8 +2154,8 @@ function createPageActionToolSource(options) {
 		kind: "page-action",
 		listToolSpecs: () => Promise.resolve(policy.enabled ? [{
 			name: PAGE_ACTION_TOOL,
-			description: DESCRIPTION,
-			inputSchema: INPUT_SCHEMA
+			description: DESCRIPTION$1,
+			inputSchema: INPUT_SCHEMA$1
 		}] : []),
 		systemPrompt: () => Promise.resolve(policy.enabled ? PAGE_ACTION_SYSTEM_PROMPT : void 0),
 		canHandle: (name) => name === PAGE_ACTION_TOOL,
@@ -2180,7 +2181,7 @@ function createPageActionToolSource(options) {
 		},
 		call: async (_name, args, context) => {
 			const action = args["action"];
-			if (typeof action !== "string" || !PAGE_ACTION_KINDS.includes(action)) return toolError$2("VALIDATION_FAILED", `act_on_page needs one of ${PAGE_ACTION_KINDS.join(" / ")}.`);
+			if (typeof action !== "string" || !PAGE_ACTION_KINDS.includes(action)) return toolError$3("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 {
@@ -2197,25 +2198,25 @@ function createPageActionToolSource(options) {
 						} }
 					};
 				} catch (e) {
-					return toolError$2(e instanceof WebSkillError ? e.code : "PAGE_ACTION_FAILED", messageOf(e));
+					return toolError$3(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\".");
+				if ("ref" in args || "value" in args) return toolError$3("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}".`);
+			if (typeof ref !== "string") return toolError$3("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$2("VALIDATION_FAILED", `act_on_page needs a "value" string when the action is "${action}".`);
-			if (action === "scroll" && value !== "down" && value !== "up") return toolError$2("VALIDATION_FAILED", "act_on_page with \"scroll\" needs a \"value\" of \"down\" or \"up\".");
+			].includes(action) && typeof value !== "string") return toolError$3("VALIDATION_FAILED", `act_on_page needs a "value" string when the action is "${action}".`);
+			if (action === "scroll" && value !== "down" && value !== "up") return toolError$3("VALIDATION_FAILED", "act_on_page with \"scroll\" needs a \"value\" of \"down\" or \"up\".");
 			return await run({
 				ref,
 				action,
@@ -2457,7 +2458,7 @@ const SPECS = [
 		inputSchema: TAB_SCHEMA
 	}
 ];
-function toolError$1(code, message) {
+function toolError$2(code, message) {
 	return {
 		ok: false,
 		content: [],
@@ -2492,7 +2493,7 @@ function createTabWorksetToolSource(options) {
 					}]
 				};
 				const handle = args["tab"];
-				if (typeof handle !== "string" || handle === "") return toolError$1("VALIDATION_FAILED", `${name} needs a "tab" handle from list_page_tabs.`);
+				if (typeof handle !== "string" || handle === "") return toolError$2("VALIDATION_FAILED", `${name} needs a "tab" handle from list_page_tabs.`);
 				return {
 					ok: true,
 					content: [{
@@ -2501,7 +2502,7 @@ function createTabWorksetToolSource(options) {
 					}]
 				};
 			} catch (e) {
-				return toolError$1(e instanceof WebSkillError ? e.code : "PAGE_TAB_FAILED", messageOf(e));
+				return toolError$2(e instanceof WebSkillError ? e.code : "PAGE_TAB_FAILED", messageOf(e));
 			}
 		}
 	};
@@ -2622,6 +2623,42 @@ var DownloadedFilePolicy = class {
 		});
 		return result;
 	}
+	/**
+	* 取原始字节，不做形态化（0.21.0 分册 22 · FR-22.4）。
+	*
+	* 授权卡、审计留痕与 `read()` 完全一致——逐单元读文档要的是字节本身，
+	* 但绝不能因此绕过策略：那等于给「读用户本机磁盘」开第二个没有授权的入口。
+	* @experimental
+	*/
+	async readBytes(id) {
+		const reader = this.#reader();
+		const entry = await this.#resolve(id);
+		const approved = await this.#authorize("read", entry);
+		if (approved === false) {
+			const reason = `Reading "${entry.name}" was declined by the user.`;
+			await this.#record({
+				action: "read",
+				...describe(entry),
+				approved: false,
+				ok: false,
+				reason
+			});
+			throw new WebSkillError("TOOL_DENIED", reason);
+		}
+		const { contentType, bytes } = await reader.read(id);
+		await this.#record({
+			action: "read",
+			...describe(entry),
+			contentType,
+			approved,
+			ok: true
+		});
+		return {
+			entry,
+			contentType,
+			bytes
+		};
+	}
 	async #materialize(entry, contentType, kind, bytes) {
 		if (kind === "text" || kind === "document-text") {
 			const body = kind === "text" ? new TextDecoder().decode(bytes) : await this.#extract(contentType, entry.name)(bytes);
@@ -2629,15 +2666,10 @@ var DownloadedFilePolicy = class {
 				entry,
 				contentType,
 				kind,
-				text: formatAttachmentText({
-					name: entry.name,
-					contentType,
-					body,
-					kind,
-					origin: "download"
-				})
+				text: this.#label(entry, contentType, body, kind)
 			};
 		}
+		if (kind === "file" && this.#overDocumentLimit(bytes)) return await this.#pdfAsText(entry, contentType, bytes);
 		return {
 			entry,
 			contentType,
@@ -2645,6 +2677,43 @@ var DownloadedFilePolicy = class {
 			bytes
 		};
 	}
+	/** 与手动上传共用同一个格式化器：两条入口的产出必须逐字一致（AC-20.6） */
+	#label(entry, contentType, body, kind) {
+		return formatAttachmentText({
+			name: entry.name,
+			contentType,
+			body,
+			kind,
+			origin: "download"
+		});
+	}
+	/** base64 编码后才是请求体里的长度，量原始字节会漏掉那三分之一（与上传侧同口径） */
+	#overDocumentLimit(bytes) {
+		const max = this.#options.maxDocumentBytes?.();
+		return max !== void 0 && Math.ceil(bytes.length / 3) * 4 > max;
+	}
+	/**
+	* 超阈值 PDF 退到抽取文本（AC-21.2），抽不出就**拒绝并说明**（AC-21.3）：
+	* 半份原件是坏文件，半份抽取文本会让模型以为自己读全了。与上传侧 `#routeDocument` 同一套判断。
+	*/
+	async #pdfAsText(entry, contentType, bytes) {
+		const tooLarge = `${entry.name} is ${formatSize(bytes.length)}, over the request limit for sending a document as is. It was not truncated, because a partial document would be unusable.`;
+		const extract = this.#options.pdfExtractor;
+		if (extract === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `${tooLarge} This environment has no PDF text extractor either, so no fallback is available. Tell the user to switch to a model that accepts large documents.`);
+		let body;
+		try {
+			body = await extract(bytes);
+		} catch (e) {
+			throw new WebSkillError("TOOL_UNSUPPORTED", `${tooLarge} Text extraction failed as well: ${e instanceof Error ? e.message : String(e)}. Ask the user for a smaller file or a specific page range.`);
+		}
+		if (body.trim() === "") throw new WebSkillError("TOOL_UNSUPPORTED", `${tooLarge} It has no text layer either — most likely a scan or an image-only export — so nothing could be extracted. Tell the user this instead of guessing what it contains.`);
+		return {
+			entry,
+			contentType,
+			kind: "document-text",
+			text: this.#label(entry, contentType, body, "document-text")
+		};
+	}
 	#extract(contentType, name) {
 		const extract = isSpreadsheet(contentType, name) ? this.#options.xlsxExtractor : this.#options.docxExtractor;
 		if (extract === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", this.#noExtractorReason(contentType, name));
@@ -2756,8 +2825,8 @@ const READ_INPUT_SCHEMA = {
 	required: ["id"],
 	additionalProperties: false
 };
-const SYSTEM_PROMPT = "You can list and read files the user downloaded in this browser with list_downloaded_files and read_downloaded_file. Every call asks the user for permission, so only use them when the task actually needs a local file. Never guess an id: always list first, and never treat the listing as evidence about files you were not shown.";
-function toolError(e) {
+const SYSTEM_PROMPT$1 = "You can list and read files the user downloaded in this browser with list_downloaded_files and read_downloaded_file. Every call asks the user for permission, so only use them when the task actually needs a local file. Never guess an id: always list first, and never treat the listing as evidence about files you were not shown.";
+function toolError$1(e) {
 	return {
 		ok: false,
 		content: [],
@@ -2787,7 +2856,7 @@ function createDownloadedFileToolSource(options) {
 			description: READ_DESCRIPTION,
 			inputSchema: READ_INPUT_SCHEMA
 		}] : []),
-		systemPrompt: () => Promise.resolve(policy.enabled ? SYSTEM_PROMPT : void 0),
+		systemPrompt: () => Promise.resolve(policy.enabled ? SYSTEM_PROMPT$1 : void 0),
 		canHandle: (name) => name === "list_downloaded_files" || name === "read_downloaded_file",
 		argCaptureTrust: (name) => name === "list_downloaded_files" || name === "read_downloaded_file" ? { tier: "reviewed" } : void 0,
 		call: async (name, args) => {
@@ -2806,7 +2875,7 @@ function createDownloadedFileToolSource(options) {
 					content: readContent(await policy.read(id))
 				};
 			} catch (e) {
-				return toolError(e);
+				return toolError$1(e);
 			}
 		}
 	};
@@ -2847,4 +2916,151 @@ function readContent(result) {
 }
 
 //#endregion
-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 };
+//#region ../agent/src/spreadsheet/toolSource.ts
+const EXPORT_SPREADSHEET_TOOL = "export_spreadsheet";
+const DESCRIPTION = "Write tabular data to an Excel (.xlsx) file the user can download.";
+const INPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		fileName: {
+			type: "string",
+			description: "Name for the workbook, for example \"sales-2026.xlsx\". A missing .xlsx suffix is added for you."
+		},
+		spec: {
+			type: "object",
+			properties: { sheets: {
+				type: "array",
+				minItems: 1,
+				maxItems: SPREADSHEET_LIMITS.sheets,
+				items: {
+					type: "object",
+					properties: {
+						name: {
+							type: "string",
+							description: "Sheet name: at most 31 characters, and none of : \\ / ? * [ ]"
+						},
+						columns: {
+							type: "array",
+							items: { type: "string" },
+							description: "Optional header row. When given it becomes the first, bold row."
+						},
+						rows: {
+							type: "array",
+							maxItems: SPREADSHEET_LIMITS.rowsPerSheet,
+							items: {
+								type: "array",
+								maxItems: SPREADSHEET_LIMITS.columnsPerSheet,
+								items: {
+									anyOf: [
+										{ type: "string" },
+										{ type: "number" },
+										{ type: "boolean" },
+										{ type: "null" }
+									],
+									description: "Text is never re-parsed as a number or a date: \"0123\" stays \"0123\". Use null for an empty cell."
+								}
+							}
+						}
+					},
+					required: ["name", "rows"],
+					additionalProperties: false
+				}
+			} },
+			required: ["sheets"],
+			additionalProperties: false
+		}
+	},
+	required: ["fileName", "spec"],
+	additionalProperties: false
+};
+const SYSTEM_PROMPT = "Use export_spreadsheet when the user asks for a downloadable Excel file. The tool returns only a summary; the file itself is delivered to the user as a card. Do not re-read the file you just wrote. Cell values are written literally — the tool never turns text into a number or a date, and it writes no styling, formulas, merged cells or charts.";
+function toolError(e) {
+	return {
+		ok: false,
+		content: [],
+		error: {
+			code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
+			message: messageOf(e)
+		}
+	};
+}
+const isRecord = (v) => typeof v === "object" && v !== null;
+/**
+* FR-10.3a 的两条分支。忘写后缀是模型的高频行为，为它打断一整轮不划算；
+* 写成 `.csv` 则是**意图冲突**而不是疏漏，必须拒。
+*
+* 路径安全不在这里做：`writeArtifact` 那一条（`resolveInsideRoot`）是唯一的一份，
+* FR-10.3b 明确禁止另写一份。
+*/
+function resolveFileName(value) {
+	if (typeof value !== "string" || value.trim() === "") throw new WebSkillError("VALIDATION_FAILED", "export_spreadsheet requires a non-empty \"fileName\".");
+	const fileName = value.trim();
+	const lastSegment = fileName.split(/[\\/]/).pop() ?? "";
+	const dot = lastSegment.lastIndexOf(".");
+	const extension = dot <= 0 ? "" : lastSegment.slice(dot + 1);
+	if (extension === "") return `${fileName}${SPREADSHEET_EXTENSION}`;
+	if (extension.toLowerCase() === "xlsx") return fileName;
+	throw new WebSkillError("VALIDATION_FAILED", `export_spreadsheet writes .xlsx files; "${fileName}" asks for .${extension}. Drop the suffix or use .xlsx.`);
+}
+function summarize(spec) {
+	const sheets = spec.sheets;
+	return {
+		sheetCount: sheets.length,
+		rowCount: sheets.reduce((total, sheet) => total + sheet.rows.length, 0)
+	};
+}
+/**
+* 把表格导出接到既有工具协议上。
+*
+* 做成 `ExternalToolSource` 而不是 `AgentLoop` 的内置数组（DV-4）：本工具需要
+* `argCaptureTrust` 与 `captureArgs` 两个钩子，内置数组里没有这两个概念。
+* @experimental
+*/
+function createSpreadsheetToolSource(options) {
+	const { writeArtifact } = options;
+	return {
+		kind: "spreadsheet",
+		listToolSpecs: () => Promise.resolve(writeArtifact ? [{
+			name: EXPORT_SPREADSHEET_TOOL,
+			description: DESCRIPTION,
+			inputSchema: INPUT_SCHEMA
+		}] : []),
+		systemPrompt: () => Promise.resolve(writeArtifact ? SYSTEM_PROMPT : void 0),
+		canHandle: (name) => name === EXPORT_SPREADSHEET_TOOL,
+		captureArgs: (_name, args) => {
+			const spec = args["spec"];
+			const sheets = isRecord(spec) && Array.isArray(spec["sheets"]) ? spec["sheets"] : [];
+			const rowCount = sheets.reduce((total, sheet) => total + (isRecord(sheet) && Array.isArray(sheet["rows"]) ? sheet["rows"].length : 0), 0);
+			return {
+				...typeof args["fileName"] === "string" ? { fileName: args["fileName"] } : {},
+				sheetCount: sheets.length,
+				rowCount
+			};
+		},
+		call: async (name, args, context) => {
+			try {
+				if (name !== "export_spreadsheet" || !writeArtifact) throw new WebSkillError("TOOL_UNSUPPORTED", `${name} is not available in this host.`);
+				const fileName = resolveFileName(args["fileName"]);
+				const spec = args["spec"];
+				const bytes = await encodeSpreadsheet(spec);
+				const artifact = await writeArtifact(fileName, bytes, SPREADSHEET_MIME_TYPE, context);
+				return {
+					ok: true,
+					content: [{
+						type: "json",
+						data: {
+							path: artifact.path,
+							size: artifact.size,
+							...summarize(spec)
+						}
+					}]
+				};
+			} catch (e) {
+				return toolError(e);
+			}
+		}
+	};
+}
+
+//#endregion
+export { CLOSE_PAGE_TAB_TOOL, DEFAULT_MAX_DATA_SOURCE_BYTES, DELEGATE_TASK_TOOL, DELEGATION_SYSTEM_PROMPT, DOCUMENT_READ_BUDGET, DOWNLOAD_WAIT_DEFAULT_MS, DOWNLOAD_WAIT_MAX_MS, DOWNLOAD_WAIT_MIN_MS, DataSourceCandidatePolicy, DataSourcePolicy, DelegationOrchestrator, DownloadedFilePolicy, EXPORT_SPREADSHEET_TOOL, 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, PDF_GARBLED_RATIO, PDF_LARGE_IMAGE_RATIO, PERCEIVE_PAGE_TOOL, PERCEPTION_PAGING_DEFAULTS, PERCEPTION_SYSTEM_PROMPT, PageActionPolicy, PagePerceptionPolicy, READ_DOCUMENT_TOOL, 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, asReadMode, clampDownloadWaitMs, clampWorksetMax, createDelegationToolSource, createDocumentToolSource, createDownloadedFileToolSource, createHttpDataSourceTransport, createPageActionToolSource, createPagePerceptionToolSource, createSkillGenerationToolSource, createSpreadsheetToolSource, createTabWorksetToolSource, createTodoToolSource, defersImage, frameLabel, frameSteps, isPdfTextTrustworthy, measurePdfTextQuality, sniffDocumentFormat, takesImage, toActionFrameScopes, toFrameScopes, withDelegationOrigin };