@webskill/sdk 0.27.0 → 0.28.1

package/dist/agent.js

@@ -305,7 +305,7 @@ const SCRIPT_EXTENSIONS = [".ts", ".js"];
 function defaultConfirmSkill(draft) {
 	return `Save this conversation as the skill "${draft.name}"? ${draft.description}\nIt will be submitted for review, not activated. Please check the preview below for anything that must not be stored.`;
 }
-function fail$2(message, details) {
+function fail$4(message, details) {
 	throw new WebSkillError("SKILL_GENERATION_VALIDATION_FAILED", message, details);
 }
 /**
@@ -313,21 +313,21 @@ function fail$2(message, details) {
 * 再去打扰用户——不让用户确认一个注定会失败的技能。
 */
 function validateDraft(draft) {
-	if (!isValidSkillName(draft.name)) fail$2(`"${draft.name}" is not a valid skill name; use lowercase letters, digits and hyphens`);
-	if (draft.description.trim() === "") fail$2("The skill description must not be empty");
-	if (typeof draft.content !== "string" || draft.content.trim() === "") fail$2("The SKILL.md content must not be empty");
+	if (!isValidSkillName(draft.name)) fail$4(`"${draft.name}" is not a valid skill name; use lowercase letters, digits and hyphens`);
+	if (draft.description.trim() === "") fail$4("The skill description must not be empty");
+	if (typeof draft.content !== "string" || draft.content.trim() === "") fail$4("The SKILL.md content must not be empty");
 	let metadata;
 	try {
 		metadata = parseSkillMarkdown(draft.content).metadata;
 	} catch (e) {
-		fail$2(`The SKILL.md content is not a valid skill document: ${e instanceof Error ? e.message : String(e)}`);
+		fail$4(`The SKILL.md content is not a valid skill document: ${e instanceof Error ? e.message : String(e)}`);
 	}
-	if (metadata.name !== draft.name) fail$2(`The SKILL.md frontmatter declares name "${metadata.name}" but the draft name is "${draft.name}"`);
+	if (metadata.name !== draft.name) fail$4(`The SKILL.md frontmatter declares name "${metadata.name}" but the draft name is "${draft.name}"`);
 	for (const file of draft.files ?? []) {
 		const path = file.path;
-		if (path.trim() === "") fail$2("Every attached file needs a path");
-		if (path.startsWith("/") || path.includes("\\") || path.split("/").includes("..")) fail$2(`The attached file path "${path}" must be relative and must not escape the skill folder`);
-		if (path.startsWith("scripts/") && !SCRIPT_EXTENSIONS.some((ext) => path.endsWith(ext))) fail$2(`The script "${path}" must end with .ts or .js`);
+		if (path.trim() === "") fail$4("Every attached file needs a path");
+		if (path.startsWith("/") || path.includes("\\") || path.split("/").includes("..")) fail$4(`The attached file path "${path}" must be relative and must not escape the skill folder`);
+		if (path.startsWith("scripts/") && !SCRIPT_EXTENSIONS.some((ext) => path.endsWith(ext))) fail$4(`The script "${path}" must end with .ts or .js`);
 	}
 }
 /** 确认面板正文：完整 SKILL.md + 附带文件，供用户逐字检查（FR-9.4 风险缓解） */
@@ -359,25 +359,25 @@ async function materializeBinaries(draft, options) {
 	const out = /* @__PURE__ */ new Map();
 	if (claimed.length === 0) return out;
 	const resolve = options.resolveAttachment;
-	if (resolve === void 0) fail$2("This host cannot put uploaded files into a skill. Remove \"attachmentId\" from the file entries and write their contents instead.");
+	if (resolve === void 0) fail$4("This host cannot put uploaded files into a skill. Remove \"attachmentId\" from the file entries and write their contents instead.");
 	const maxOne = options.policy?.maxBinaryBytes ?? DEFAULT_MAX_BINARY_BYTES;
 	const maxTotal = options.policy?.maxTotalBinaryBytes ?? DEFAULT_MAX_TOTAL_BINARY_BYTES;
 	let total = 0;
 	for (const file of claimed) {
 		const id = file.attachmentId;
 		const attachment = await resolve(id);
-		if (attachment === void 0) fail$2(`No file with attachment id "${id}" was uploaded in this conversation, so "${file.path}" cannot be added to the skill.`, {
+		if (attachment === void 0) fail$4(`No file with attachment id "${id}" was uploaded in this conversation, so "${file.path}" cannot be added to the skill.`, {
 			attachmentId: id,
 			path: file.path
 		});
 		const size = attachment.bytes.byteLength;
-		if (size > maxOne) fail$2(`The attached file "${attachment.name}" is ${size} bytes, above the ${maxOne} byte limit for one file.`, {
+		if (size > maxOne) fail$4(`The attached file "${attachment.name}" is ${size} bytes, above the ${maxOne} byte limit for one file.`, {
 			path: file.path,
 			size,
 			limit: maxOne
 		});
 		total += size;
-		if (total > maxTotal) fail$2(`The attached files add up to ${total} bytes, above the ${maxTotal} byte limit for one skill.`, {
+		if (total > maxTotal) fail$4(`The attached files add up to ${total} bytes, above the ${maxTotal} byte limit for one skill.`, {
 			path: file.path,
 			total,
 			limit: maxTotal
@@ -404,7 +404,7 @@ function assertStepsAreBackedByTrace(draft, records) {
 	const executed = new Set(records.map((r) => r.tool));
 	const unknown = [...new Set(claimed.map((s) => s.tool).filter((tool) => !executed.has(tool)))];
 	if (unknown.length === 0) return;
-	fail$2(`The skill claims tools that were never called in this session: ${unknown.join(", ")}. Tools actually called: ${executed.size === 0 ? "(none)" : [...executed].sort().join(", ")}. Rewrite the skill using only the tools above.`, {
+	fail$4(`The skill claims tools that were never called in this session: ${unknown.join(", ")}. Tools actually called: ${executed.size === 0 ? "(none)" : [...executed].sort().join(", ")}. Rewrite the skill using only the tools above.`, {
 		claimed: unknown,
 		executed: [...executed].sort()
 	});
@@ -422,7 +422,7 @@ function assertStepsAreNotTruncated(draft, records) {
 	const usable = new Set(records.filter((r) => r.truncated !== true).map((r) => r.tool));
 	const truncated = [...new Set(claimed.map((s) => s.tool).filter((tool) => !usable.has(tool)))];
 	if (truncated.length === 0) return;
-	fail$2(`The arguments of these tool calls were too large to record, so the skill cannot state them: ${truncated.join(", ")}. Rewrite the skill without these steps.`, { truncated });
+	fail$4(`The arguments of these tool calls were too large to record, so the skill cannot state them: ${truncated.join(", ")}. Rewrite the skill without these steps.`, { truncated });
 }
 /**
 * 确认卡证据（AC-30.12 / AC-30.13）：逐条列出模型**写进技能的**步骤，
@@ -561,6 +561,7 @@ const SKILL_GENERATION_SYSTEM_PROMPT = [
 	"  from inside SKILL.md as `skill:<the skill name>/<the path you gave it>`, for example",
 	"  `skill:monthly-report/assets/template.xlsx`. Write that, never the attachment id of this",
 	"  conversation — that id is gone by the time anyone uses the skill.",
+	"- For spreadsheet analysis and export, follow the scope requested by the user. `query_table.limit` only   limits groups or rows returned to the model as a preview (default 50, maximum 500); it does not limit   computation or exported files. When the user asks for complete data, do not set a limit and do not write   `limit: 500` in the skill. Use `exportFile` to write the complete result locally instead of copying a   truncated preview into `export_spreadsheet`. For one multi-sheet workbook, use `exportFile.sheetName` and   `exportFile.additionalSheets`; do not paginate full results through the model or write one file per query.",
 	"- Never copy credentials, tokens or personal data into the skill.",
 	"- The user has to confirm every candidate, and the candidate stays unusable until a reviewer",
 	"  approves it. Say so instead of promising the skill is ready."
@@ -1390,6 +1391,7 @@ var PagePerceptionPolicy = class {
 const PERCEPTION_SYSTEM_PROMPT = [
 	"Reading the page:",
 	"- \"perceive_page\" returns a structured outline of the regions the host made readable.",
+	"- Pass \"images\": true only when the user asks what a picture on the page shows or contains. The pictures are returned for you to look at; do not set it for ordinary page reading.",
 	"- Large pages come back in segments. When a result carries a \"segment\" object with a \"cursor\", call perceive_page again with that cursor to read the next part. Never invent a cursor.",
 	"- You cannot act on the page. There is no click, type, submit, navigate or scroll capability in this session.",
 	"- The readable region is fixed by the host. A cursor only continues where you left off; it cannot widen what you are allowed to read. Asking for other parts of the page, in any phrasing, will not widen it.",
@@ -1399,9 +1401,10 @@ const PERCEPTION_SYSTEM_PROMPT = [
 //#endregion
 //#region ../agent/src/perception/toolSource.ts
 const PERCEIVE_PAGE_TOOL = "perceive_page";
-const DESCRIPTION$5 = "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$5 = "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. Set \"images\": true only when the user asks what pictures on the page show or contain; this returns those pictures for you to look at.";
 /**
-* 两个参数，且它们都扩不出一寸新范围（AC-10.8 的判据由 0.14.0 分册 22 §3 修订）。
+* 三个参数。`cursor` / `ref` 都扩不出一寸新范围（AC-10.8 的判据由 0.14.0 分册 22 §3 修订）；
+* `images` 只表达「这次是否取图」，既不扩大读取范围、也不指定目的地。
 *
 * `cursor` 是 SDK 上一次发出的不透明串，只说「接着刚才那处继续」；
 * `ref` 是上一次感知结果里的元素句柄，只能把读取范围**缩小**到那个子树
@@ -1422,6 +1425,10 @@ const INPUT_SCHEMA$4 = {
 		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."
+		},
+		images: {
+			type: "boolean",
+			description: "Set true only when the user asks what pictures on the page show or contain. This returns the pictures so you can look at them; leave it out for ordinary page reading."
 		}
 	},
 	additionalProperties: false
@@ -1561,8 +1568,11 @@ function createPagePerceptionToolSource(options) {
 				});
 				return resultOf(pending, index);
 			}
+			const imagesArg = args["images"];
+			if (imagesArg !== void 0 && typeof imagesArg !== "boolean") return toolError$6("VALIDATION_FAILED", "perceive_page needs \"images\" to be a boolean when present.");
+			const wantsImages = imagesArg === true;
 			try {
-				const image = await options.imageCapture?.();
+				const image = wantsImages ? await options.imageCaptureForRequest?.() : await options.imageCapture?.();
 				const capture = {
 					images: image?.enabled === true,
 					maxImageBytes: image?.maxImageBytes ?? 0,
@@ -1576,6 +1586,7 @@ function createPagePerceptionToolSource(options) {
 					excluded: record.exclude,
 					nodes
 				};
+				if (wantsImages && image?.enabled !== true) data["imagesUnavailable"] = image?.unavailableReason ?? "Page pictures were not returned. The host has page image capture off, or no image-capable model is configured. Do not describe the pictures from the surrounding text; tell the user what is missing.";
 				if (imagesOmitted > 0) data["imagesOmitted"] = imagesOmitted;
 				if ((record.imageFailures ?? 0) > 0) data["imageFailures"] = record.imageFailures;
 				const { segments, nodesTotal } = segmentPerception(nodes, budget);
@@ -1795,7 +1806,7 @@ const RECORD_LIMIT$1 = 50;
 function sanitizeDescription(value) {
 	return sanitizeUntrustedLine(value, DESCRIPTION_LIMIT);
 }
-function isRecord$2(value) {
+function isRecord$3(value) {
 	return typeof value === "object" && value !== null;
 }
 /**
@@ -1805,7 +1816,7 @@ function isRecord$2(value) {
 * 标成后者会让读代码的人以为它已经被验证过了。
 */
 function validate(raw, provenance) {
-	if (!isRecord$2(raw)) return void 0;
+	if (!isRecord$3(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;
@@ -3084,7 +3095,7 @@ function readContent(result) {
 //#region ../agent/src/spreadsheet/toolSource.ts
 const EXPORT_SPREADSHEET_TOOL = "export_spreadsheet";
 const DESCRIPTION$3 = "Write tabular data — and, when they belong in the sheet, pictures — to an Excel (.xlsx) file the user can download.";
-const CELL_SCHEMA = {
+const CELL_SCHEMA$1 = {
 	anyOf: [
 		{ type: "string" },
 		{ type: "number" },
@@ -3180,7 +3191,7 @@ function inputSchema(withImages) {
 								items: {
 									type: "array",
 									maxItems: SPREADSHEET_LIMITS.columnsPerSheet,
-									items: CELL_SCHEMA
+									items: CELL_SCHEMA$1
 								}
 							},
 							...withImages ? { images: IMAGES_SCHEMA } : {}
@@ -3210,7 +3221,7 @@ function toolError$2(e) {
 		}
 	};
 }
-const isRecord$1 = (v) => typeof v === "object" && v !== null;
+const isRecord$2 = (v) => typeof v === "object" && v !== null;
 /**
 * FR-10.3a 的两条分支。忘写后缀是模型的高频行为，为它打断一整轮不划算；
 * 写成 `.csv` 则是**意图冲突**而不是疏漏，必须拒。
@@ -3218,15 +3229,15 @@ const isRecord$1 = (v) => typeof v === "object" && v !== null;
 * 路径安全不在这里做：`writeArtifact` 那一条（`resolveInsideRoot`）是唯一的一份，
 * FR-10.3b 明确禁止另写一份。
 */
-function resolveFileName$1(value) {
-	if (typeof value !== "string" || value.trim() === "") throw new WebSkillError("VALIDATION_FAILED", "export_spreadsheet requires a non-empty \"fileName\".");
+function resolveFileName$1(value, toolName = "export_spreadsheet") {
+	if (typeof value !== "string" || value.trim() === "") throw new WebSkillError("VALIDATION_FAILED", `${toolName} 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.`);
+	throw new WebSkillError("VALIDATION_FAILED", `${toolName} writes .xlsx files; "${fileName}" asks for .${extension}. Drop the suffix or use .xlsx.`);
 }
 function summarize(spec) {
 	const sheets = spec.sheets;
@@ -3260,8 +3271,8 @@ function createSpreadsheetToolSource(options) {
 		canHandle: (name) => name === EXPORT_SPREADSHEET_TOOL,
 		captureArgs: (_name, args) => {
 			const spec = args["spec"];
-			const sheets = isRecord$1(spec) && Array.isArray(spec["sheets"]) ? spec["sheets"] : [];
-			const rowCount = sheets.reduce((total, sheet) => total + (isRecord$1(sheet) && Array.isArray(sheet["rows"]) ? sheet["rows"].length : 0), 0);
+			const sheets = isRecord$2(spec) && Array.isArray(spec["sheets"]) ? spec["sheets"] : [];
+			const rowCount = sheets.reduce((total, sheet) => total + (isRecord$2(sheet) && Array.isArray(sheet["rows"]) ? sheet["rows"].length : 0), 0);
 			return {
 				...typeof args["fileName"] === "string" ? { fileName: args["fileName"] } : {},
 				sheetCount: sheets.length,
@@ -3317,17 +3328,17 @@ function columnLetter(index) {
 	}
 	return out;
 }
-const blank = (cells) => cells.every((cell) => cell.trim() === "");
-function fail$1(message) {
+const blank$1 = (cells) => cells.every((cell) => cell.trim() === "");
+function fail$3(message) {
 	throw new WebSkillError("VALIDATION_FAILED", message);
 }
 /** 先按序号（1 基）、再按表名定位；缺省取第一张有内容的表 */
 function resolveSheet(workbook, ref) {
 	const { sheets } = workbook;
-	if (sheets.length === 0) fail$1("This workbook has no sheets.");
+	if (sheets.length === 0) fail$3("This workbook has no sheets.");
 	const names = () => sheets.map((sheet, i) => `${i + 1}: "${sheet.name}"`).join(", ");
 	if (ref === void 0) {
-		const found = sheets.findIndex((sheet) => sheet.rows.some((row) => !blank(row)));
+		const found = sheets.findIndex((sheet) => sheet.rows.some((row) => !blank$1(row)));
 		const index = found === -1 ? 0 : found;
 		return {
 			sheet: sheets[index],
@@ -3336,7 +3347,7 @@ function resolveSheet(workbook, ref) {
 	}
 	if (typeof ref === "number") {
 		const sheet = Number.isInteger(ref) ? sheets[ref - 1] : void 0;
-		if (sheet === void 0) fail$1(`There is no sheet number ${String(ref)}. Sheets: ${names()}.`);
+		if (sheet === void 0) fail$3(`There is no sheet number ${String(ref)}. Sheets: ${names()}.`);
 		return {
 			sheet,
 			index: ref - 1
@@ -3344,24 +3355,24 @@ function resolveSheet(workbook, ref) {
 	}
 	if (typeof ref === "string") {
 		const index = sheets.findIndex((sheet) => sheet.name === ref);
-		if (index === -1) fail$1(`There is no sheet named "${ref}". Sheets: ${names()}.`);
+		if (index === -1) fail$3(`There is no sheet named "${ref}". Sheets: ${names()}.`);
 		return {
 			sheet: sheets[index],
 			index
 		};
 	}
-	return fail$1("\"sheet\" must be a sheet name or a 1-based sheet number.");
+	return fail$3("\"sheet\" must be a sheet name or a 1-based sheet number.");
 }
 /** 表头行（缺省为第一个有内容的行）+ 其后有内容的行；行号保持工作表的 1 基行号 */
 function buildView(workbook, sheetRef, headerRowArg) {
 	const { sheet, index } = resolveSheet(workbook, sheetRef);
 	const rows = sheet.rows;
 	let headerIndex;
-	if (headerRowArg === void 0) headerIndex = rows.findIndex((row) => !blank(row));
+	if (headerRowArg === void 0) headerIndex = rows.findIndex((row) => !blank$1(row));
 	else {
-		if (typeof headerRowArg !== "number" || !Number.isInteger(headerRowArg) || headerRowArg < 1) fail$1("\"headerRow\" must be a positive integer (1-based worksheet row number).");
+		if (typeof headerRowArg !== "number" || !Number.isInteger(headerRowArg) || headerRowArg < 1) fail$3("\"headerRow\" must be a positive integer (1-based worksheet row number).");
 		headerIndex = headerRowArg - 1;
-		if (headerIndex >= rows.length) fail$1(`"headerRow" ${headerRowArg} is past the last row (${rows.length}) of the sheet.`);
+		if (headerIndex >= rows.length) fail$3(`"headerRow" ${headerRowArg} is past the last row (${rows.length}) of the sheet.`);
 	}
 	if (headerIndex === -1) return {
 		sheetName: sheet.name,
@@ -3375,7 +3386,7 @@ function buildView(workbook, sheetRef, headerRowArg) {
 	let width = header.length;
 	for (let i = headerIndex + 1; i < rows.length; i += 1) {
 		const cells = rows[i];
-		if (blank(cells)) continue;
+		if (blank$1(cells)) continue;
 		if (cells.length > width) width = cells.length;
 		data.push({
 			row: i + 1,
@@ -3408,16 +3419,16 @@ function listColumns(view) {
 }
 /** 表头文字优先，其次列字母；表头重名时拒绝按表头引用，并点出同名各列的列字母 */
 function resolveColumn(view, ref, what) {
-	if (typeof ref !== "string" || ref.trim() === "") fail$1(`${what} must name a column (header text or column letter).`);
+	if (typeof ref !== "string" || ref.trim() === "") fail$3(`${what} must name a column (header text or column letter).`);
 	const text = ref.trim();
 	const byHeader = view.columns.filter((column) => column.header === text);
 	if (byHeader.length === 1) return byHeader[0];
-	if (byHeader.length > 1) fail$1(`${what}: the header "${text}" is shared by columns ${byHeader.map((c) => c.letter).join(", ")}. Refer to the column by its letter instead.`);
+	if (byHeader.length > 1) fail$3(`${what}: the header "${text}" is shared by columns ${byHeader.map((c) => c.letter).join(", ")}. Refer to the column by its letter instead.`);
 	if (LETTER_RE.test(text)) {
 		const byLetter = view.columns.find((column) => column.letter === text.toUpperCase());
 		if (byLetter !== void 0) return byLetter;
 	}
-	return fail$1(`${what}: no column "${text}" on sheet "${view.sheetName}". Columns: ${listColumns(view)}.`);
+	return fail$3(`${what}: no column "${text}" on sheet "${view.sheetName}". Columns: ${listColumns(view)}.`);
 }
 /** Neumaier 补偿求和：几万个小数相加不累积漂移 */
 var Summer = class {
@@ -3437,9 +3448,9 @@ const tidy = (x) => Number(x.toPrecision(12));
 
 //#endregion
 //#region ../agent/src/table/profile.ts
-const PROFILE_MAX_CHARS = 8e3;
-const DISTINCT_CAP = 1e4;
-const SAMPLE_ROWS = 5;
+const PROFILE_MAX_CHARS$1 = 8e3;
+const DISTINCT_CAP$1 = 1e4;
+const SAMPLE_ROWS$1 = 5;
 function statsOf(view, column) {
 	let filled = 0;
 	let numbers = 0;
@@ -3470,7 +3481,7 @@ function statsOf(view, column) {
 		} else texts += 1;
 		const seen = freq.get(text);
 		if (seen !== void 0) freq.set(text, seen + 1);
-		else if (freq.size < DISTINCT_CAP) freq.set(text, 1);
+		else if (freq.size < DISTINCT_CAP$1) freq.set(text, 1);
 		else capped = true;
 	}
 	let type;
@@ -3495,16 +3506,16 @@ function statsOf(view, column) {
 		top
 	};
 }
-const clip$2 = (text, max) => {
+const clip$3 = (text, max) => {
 	const chars = [...text.replace(/[\r\n\t]+/g, " ")];
 	return chars.length <= max ? chars.join("") : `${chars.slice(0, max - 1).join("")}…`;
 };
 /** 超出字符预算时的收缩阶梯：先少表、再少列、再收样本、最后去掉 top */
-const LADDER = [
+const LADDER$1 = [
 	{
 		maxSheets: 8,
 		maxColumns: 40,
-		sampleRows: SAMPLE_ROWS,
+		sampleRows: SAMPLE_ROWS$1,
 		sampleCell: 40,
 		withTop: true,
 		note: void 0
@@ -3512,7 +3523,7 @@ const LADDER = [
 	{
 		maxSheets: 3,
 		maxColumns: 40,
-		sampleRows: SAMPLE_ROWS,
+		sampleRows: SAMPLE_ROWS$1,
 		sampleCell: 40,
 		withTop: true,
 		note: "sheets"
@@ -3520,7 +3531,7 @@ const LADDER = [
 	{
 		maxSheets: 3,
 		maxColumns: 20,
-		sampleRows: SAMPLE_ROWS,
+		sampleRows: SAMPLE_ROWS$1,
 		sampleCell: 40,
 		withTop: true,
 		note: "sheets, columns"
@@ -3542,29 +3553,29 @@ const LADDER = [
 		note: "sheets, columns, sample, top values"
 	}
 ];
-function columnLine(column, stats, withTop) {
+function columnLine$1(column, stats, withTop) {
 	const parts = [
-		`${column.letter} ${clip$2(column.header, 40)}`.trimEnd(),
+		`${column.letter} ${clip$3(column.header, 40)}`.trimEnd(),
 		stats.type,
 		`${stats.filled} filled`
 	];
-	parts.push(stats.distinct === void 0 ? `>${DISTINCT_CAP} distinct` : `${stats.distinct} distinct`);
+	parts.push(stats.distinct === void 0 ? `>${DISTINCT_CAP$1} distinct` : `${stats.distinct} distinct`);
 	if (stats.min !== void 0 && stats.max !== void 0) parts.push(`min ${tidy(stats.min)}`, `max ${tidy(stats.max)}`, `sum ${tidy(stats.sum)}`);
 	if (stats.earliest !== void 0 && stats.latest !== void 0) parts.push(`${stats.earliest} … ${stats.latest}`);
-	if (withTop && stats.top.length > 0) parts.push(`top: ${stats.top.map(([value, count]) => `${clip$2(value, 24)} ×${count}`).join(", ")}`);
+	if (withTop && stats.top.length > 0) parts.push(`top: ${stats.top.map(([value, count]) => `${clip$3(value, 24)} ×${count}`).join(", ")}`);
 	return parts.join(" | ");
 }
-function sheetSection(view, rung, expanded, statsFor) {
+function sheetSection$1(view, rung, expanded, statsFor) {
 	const head = `Sheet ${view.sheetIndex + 1} "${view.sheetName}": ${view.data.length} data rows × ${view.columns.length} columns` + (view.headerRow > 0 ? `, header at row ${view.headerRow}` : ", empty");
 	if (!expanded || view.columns.length === 0) return [head];
 	const lines = [head, "Columns:"];
 	const shown = view.columns.slice(0, rung.maxColumns);
-	for (const column of shown) lines.push(columnLine(column, statsFor(column), rung.withTop));
+	for (const column of shown) lines.push(columnLine$1(column, statsFor(column), rung.withTop));
 	if (view.columns.length > shown.length) lines.push(`+${view.columns.length - shown.length} more columns — call query_table with op "describe" and this sheet to list them`);
 	const sample = view.data.slice(0, rung.sampleRows);
 	if (sample.length > 0) {
 		lines.push(`Sample (sheet rows ${sample[0].row}–${sample[sample.length - 1].row}):`);
-		for (const { cells } of sample) lines.push(shown.map((column) => clip$2((cells[column.index] ?? "").trim(), rung.sampleCell)).join("	"));
+		for (const { cells } of sample) lines.push(shown.map((column) => clip$3((cells[column.index] ?? "").trim(), rung.sampleCell)).join("	"));
 	}
 	return lines;
 }
@@ -3591,13 +3602,293 @@ function profileTable(input) {
 		return stats;
 	};
 	let result = "";
-	for (const rung of LADDER) {
+	for (const rung of LADDER$1) {
 		const lines = [header];
 		let expandedCount = 0;
 		for (const [index, view] of views.entries()) {
 			const expanded = only === void 0 ? expandedCount < rung.maxSheets : index === only;
 			if (expanded && view.data.length > 0) expandedCount += 1;
-			lines.push(...sheetSection(view, rung, expanded && (only !== void 0 || view.data.length > 0), statsFor(view)));
+			lines.push(...sheetSection$1(view, rung, expanded && (only !== void 0 || view.data.length > 0), statsFor(view)));
+		}
+		if (rung.note !== void 0) lines.push(`Profile shortened to fit: ${rung.note}. Call query_table with op "describe" for the rest.`);
+		result = lines.join("\n");
+		if (result.length <= PROFILE_MAX_CHARS$1) return result;
+	}
+	return `${result.slice(0, PROFILE_MAX_CHARS$1 - 80)}\nProfile cut at ${PROFILE_MAX_CHARS$1} characters.`;
+}
+
+//#endregion
+//#region ../agent/src/table/streaming.ts
+function isStreamingTableWorkbook(workbook) {
+	return "kind" in workbook && workbook.kind === "streaming";
+}
+const blank = (cells) => cells.every((cell) => cell.trim() === "");
+function fail$2(message) {
+	throw new WebSkillError("VALIDATION_FAILED", message);
+}
+async function resolveStreamingSheet(workbook, ref) {
+	const { sheets } = workbook;
+	if (sheets.length === 0) fail$2("This workbook has no sheets.");
+	const names = () => sheets.map((sheet, i) => `${i + 1}: "${sheet.name}"`).join(", ");
+	if (ref === void 0) {
+		for (const [index, sheet] of sheets.entries()) if ((await sheet.meta()).firstNonEmptyRow > 0) return {
+			sheet,
+			index
+		};
+		return {
+			sheet: sheets[0],
+			index: 0
+		};
+	}
+	if (typeof ref === "number") {
+		const sheet = Number.isInteger(ref) ? sheets[ref - 1] : void 0;
+		if (sheet === void 0) fail$2(`There is no sheet number ${String(ref)}. Sheets: ${names()}.`);
+		return {
+			sheet,
+			index: ref - 1
+		};
+	}
+	if (typeof ref === "string") {
+		const index = sheets.findIndex((sheet) => sheet.name === ref);
+		if (index === -1) fail$2(`There is no sheet named "${ref}". Sheets: ${names()}.`);
+		return {
+			sheet: sheets[index],
+			index
+		};
+	}
+	return fail$2("\"sheet\" must be a sheet name or a 1-based sheet number.");
+}
+async function rowAt(sheet, row) {
+	for await (const entry of sheet.scan()) {
+		if (entry.row === row) return entry.cells;
+		if (entry.row > row) return void 0;
+	}
+}
+async function buildStreamingView(workbook, sheetRef, headerRowArg) {
+	const { sheet, index } = await resolveStreamingSheet(workbook, sheetRef);
+	const meta = await sheet.meta();
+	let headerRow;
+	if (headerRowArg === void 0) headerRow = meta.firstNonEmptyRow;
+	else {
+		if (typeof headerRowArg !== "number" || !Number.isInteger(headerRowArg) || headerRowArg < 1) fail$2("\"headerRow\" must be a positive integer (1-based worksheet row number).");
+		headerRow = headerRowArg;
+		if (headerRow > meta.rowCount) fail$2(`"headerRow" ${headerRowArg} is past the last row (${meta.rowCount}) of the sheet.`);
+	}
+	if (headerRow === 0) return {
+		sheetName: sheet.name,
+		sheetIndex: index,
+		headerRow: 0,
+		columns: [],
+		data: (async function* () {})()
+	};
+	const header = headerRow === meta.firstNonEmptyRow ? meta.firstRow : await rowAt(sheet, headerRow) ?? [];
+	const width = Math.max(meta.columnCount, header.length);
+	const columns = Array.from({ length: width }, (_, columnIndex) => {
+		const text = (header[columnIndex] ?? "").trim();
+		const letter = columnLetter(columnIndex);
+		return {
+			index: columnIndex,
+			letter,
+			header: text,
+			label: text === "" ? letter : `${letter} ${text}`,
+			name: text === "" ? letter : text
+		};
+	});
+	const data = (async function* () {
+		for await (const entry of sheet.scan()) if (entry.row > headerRow && !blank(entry.cells)) yield entry;
+	})();
+	return {
+		sheetName: sheet.name,
+		sheetIndex: index,
+		headerRow,
+		columns,
+		data
+	};
+}
+async function summarizeStreamingWorkbook(workbook) {
+	let tokens = 0;
+	let dataRows = 0;
+	let textChars = 0;
+	for (const sheet of workbook.sheets) {
+		const meta = await sheet.meta();
+		tokens += meta.estimatedTokens;
+		dataRows += meta.dataRows;
+		textChars += meta.textChars;
+	}
+	return {
+		tokens,
+		dataRows,
+		textChars
+	};
+}
+
+//#endregion
+//#region ../agent/src/table/streamingProfile.ts
+const PROFILE_MAX_CHARS = 8e3;
+const DISTINCT_CAP = 1e4;
+const SAMPLE_ROWS = 5;
+var Stats = class {
+	filled = 0;
+	numbers = 0;
+	dates = 0;
+	texts = 0;
+	summer = new Summer();
+	min;
+	max;
+	earliest;
+	latest;
+	freq = /* @__PURE__ */ new Map();
+	capped = false;
+	add(raw) {
+		const text = raw.trim();
+		const kind = kindOf(text);
+		if (kind === "empty") return;
+		this.filled += 1;
+		if (kind === "number") {
+			this.numbers += 1;
+			const value = Number(text);
+			this.summer.add(value);
+			if (this.min === void 0 || value < this.min) this.min = value;
+			if (this.max === void 0 || value > this.max) this.max = value;
+		} else if (kind === "date") {
+			this.dates += 1;
+			if (this.earliest === void 0 || text < this.earliest) this.earliest = text;
+			if (this.latest === void 0 || text > this.latest) this.latest = text;
+		} else this.texts += 1;
+		const seen = this.freq.get(text);
+		if (seen !== void 0) this.freq.set(text, seen + 1);
+		else if (this.freq.size < DISTINCT_CAP) this.freq.set(text, 1);
+		else this.capped = true;
+	}
+	finish() {
+		let type;
+		if (this.filled === 0) type = "empty";
+		else if (this.numbers >= this.filled * .95) type = "number";
+		else if (this.dates >= this.filled * .95) type = "date";
+		else if (this.numbers + this.dates <= this.filled * .05) type = "text";
+		else type = "mixed";
+		const top = this.capped || type !== "text" && type !== "mixed" ? [] : [...this.freq.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).slice(0, 3);
+		return {
+			filled: this.filled,
+			type,
+			distinct: this.capped ? void 0 : this.freq.size,
+			sum: this.summer.total,
+			min: this.min,
+			max: this.max,
+			earliest: this.earliest,
+			latest: this.latest,
+			top
+		};
+	}
+};
+async function analyze(view) {
+	const collectors = view.columns.map(() => new Stats());
+	const sample = [];
+	let dataRows = 0;
+	for await (const entry of view.data) {
+		dataRows += 1;
+		if (sample.length < SAMPLE_ROWS) sample.push(entry);
+		for (const column of view.columns) collectors[column.index].add(entry.cells[column.index] ?? "");
+	}
+	return {
+		dataRows,
+		sample,
+		columns: collectors.map((stats) => stats.finish())
+	};
+}
+const clip$2 = (text, max) => {
+	const chars = [...text.replace(/[\r\n\t]+/g, " ")];
+	return chars.length <= max ? chars.join("") : `${chars.slice(0, max - 1).join("")}…`;
+};
+const LADDER = [
+	{
+		maxSheets: 8,
+		maxColumns: 40,
+		sampleRows: SAMPLE_ROWS,
+		sampleCell: 40,
+		withTop: true,
+		note: void 0
+	},
+	{
+		maxSheets: 3,
+		maxColumns: 40,
+		sampleRows: SAMPLE_ROWS,
+		sampleCell: 40,
+		withTop: true,
+		note: "sheets"
+	},
+	{
+		maxSheets: 3,
+		maxColumns: 20,
+		sampleRows: SAMPLE_ROWS,
+		sampleCell: 40,
+		withTop: true,
+		note: "sheets, columns"
+	},
+	{
+		maxSheets: 3,
+		maxColumns: 20,
+		sampleRows: 3,
+		sampleCell: 16,
+		withTop: true,
+		note: "sheets, columns, sample"
+	},
+	{
+		maxSheets: 2,
+		maxColumns: 12,
+		sampleRows: 2,
+		sampleCell: 12,
+		withTop: false,
+		note: "sheets, columns, sample, top values"
+	}
+];
+function columnLine(column, stats, withTop) {
+	const parts = [
+		`${column.letter} ${clip$2(column.header, 40)}`.trimEnd(),
+		stats.type,
+		`${stats.filled} filled`
+	];
+	parts.push(stats.distinct === void 0 ? `>${DISTINCT_CAP} distinct` : `${stats.distinct} distinct`);
+	if (stats.min !== void 0 && stats.max !== void 0) parts.push(`min ${tidy(stats.min)}`, `max ${tidy(stats.max)}`, `sum ${tidy(stats.sum)}`);
+	if (stats.earliest !== void 0 && stats.latest !== void 0) parts.push(`${stats.earliest} … ${stats.latest}`);
+	if (withTop && stats.top.length > 0) parts.push(`top: ${stats.top.map(([value, count]) => `${clip$2(value, 24)} ×${count}`).join(", ")}`);
+	return parts.join(" | ");
+}
+function sheetSection(view, analysis, rung, expanded) {
+	const head = `Sheet ${view.sheetIndex + 1} "${view.sheetName}": ${analysis.dataRows} data rows × ${view.columns.length} columns` + (view.headerRow > 0 ? `, header at row ${view.headerRow}` : ", empty");
+	if (!expanded || view.columns.length === 0) return [head];
+	const lines = [head, "Columns:"];
+	const shown = view.columns.slice(0, rung.maxColumns);
+	for (const column of shown) lines.push(columnLine(column, analysis.columns[column.index], rung.withTop));
+	if (view.columns.length > shown.length) lines.push(`+${view.columns.length - shown.length} more columns — call query_table with op "describe" and this sheet to list them`);
+	const sample = analysis.sample.slice(0, rung.sampleRows);
+	if (sample.length > 0) {
+		lines.push(`Sample (sheet rows ${sample[0].row}–${sample[sample.length - 1].row}):`);
+		for (const entry of sample) lines.push(shown.map((column) => clip$2((entry.cells[column.index] ?? "").trim(), rung.sampleCell)).join("	"));
+	}
+	return lines;
+}
+async function profileStreamingTable(input) {
+	const { workbook } = input;
+	const total = workbook.sheets.length;
+	const only = input.sheet === void 0 ? void 0 : (await buildStreamingView(workbook, input.sheet, input.headerRow)).sheetIndex;
+	const header = `--- Spreadsheet profile: ${input.name} (id: ${input.id}) · ${total} sheet${total === 1 ? "" : "s"} ---`;
+	const views = [];
+	const analyses = [];
+	for (let index = 0; index < workbook.sheets.length; index += 1) {
+		const view = await buildStreamingView(workbook, index + 1, only === index ? input.headerRow : void 0);
+		views.push(view);
+		analyses.push(await analyze(view));
+	}
+	let result = "";
+	for (const rung of LADDER) {
+		const lines = [header];
+		let expandedCount = 0;
+		for (const [index, view] of views.entries()) {
+			const analysis = analyses[index];
+			const expanded = only === void 0 ? expandedCount < rung.maxSheets : index === only;
+			if (expanded && analysis.dataRows > 0) expandedCount += 1;
+			lines.push(...sheetSection(view, analysis, rung, expanded && (only !== void 0 || analysis.dataRows > 0)));
 		}
 		if (rung.note !== void 0) lines.push(`Profile shortened to fit: ${rung.note}. Call query_table with op "describe" for the rest.`);
 		result = lines.join("\n");
@@ -3613,6 +3904,8 @@ const QUERY_LIMITS = {
 	maxRows: 500,
 	maxFilters: 20,
 	maxGroupBy: 3,
+	maxPivotBy: 2,
+	maxPivotColumns: 100,
 	maxMetrics: 8,
 	maxOrderBy: 3,
 	maxIn: 200,
@@ -3647,32 +3940,32 @@ const BUCKETS = [
 	"month",
 	"day"
 ];
-function fail(message) {
+function fail$1(message) {
 	throw new WebSkillError("VALIDATION_FAILED", message);
 }
 const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function list(v, what, max) {
 	if (v === void 0) return [];
-	if (!Array.isArray(v)) fail(`"${what}" must be an array.`);
-	if (v.length > max) fail(`"${what}" has ${v.length} entries; at most ${max} are allowed.`);
+	if (!Array.isArray(v)) fail$1(`"${what}" must be an array.`);
+	if (v.length > max) fail$1(`"${what}" has ${v.length} entries; at most ${max} are allowed.`);
 	return v;
 }
 function oneOf(v, allowed, what) {
 	if (typeof v === "string" && allowed.includes(v)) return v;
-	return fail(`${what} must be one of: ${allowed.join(", ")}.`);
+	return fail$1(`${what} must be one of: ${allowed.join(", ")}.`);
 }
 function noOtherKeys(obj, allowed, what) {
 	const extra = Object.keys(obj).filter((key) => !allowed.includes(key));
-	if (extra.length > 0) fail(`${what} has unknown field${extra.length > 1 ? "s" : ""}: ${extra.join(", ")}.`);
+	if (extra.length > 0) fail$1(`${what} has unknown field${extra.length > 1 ? "s" : ""}: ${extra.join(", ")}.`);
 }
 function scalar(v, what) {
 	if (typeof v === "string") return v;
 	if (typeof v === "number" && Number.isFinite(v)) return v;
-	return fail(`${what} must be a string or a finite number.`);
+	return fail$1(`${what} must be a string or a finite number.`);
 }
 function compileFilter(view, raw, index, uncomparable) {
 	const what = `where[${index}]`;
-	if (!isObject(raw)) fail(`${what} must be an object.`);
+	if (!isObject(raw)) fail$1(`${what} must be an object.`);
 	noOtherKeys(raw, [
 		"column",
 		"op",
@@ -3692,7 +3985,7 @@ function compileFilter(view, raw, index, uncomparable) {
 	};
 	if (op === "in") {
 		const values = raw["value"];
-		if (!Array.isArray(values) || values.length === 0 || values.length > QUERY_LIMITS.maxIn) fail(`${what}.value must be a non-empty array of at most ${QUERY_LIMITS.maxIn} strings or numbers for op "in".`);
+		if (!Array.isArray(values) || values.length === 0 || values.length > QUERY_LIMITS.maxIn) fail$1(`${what}.value must be a non-empty array of at most ${QUERY_LIMITS.maxIn} strings or numbers for op "in".`);
 		const texts = /* @__PURE__ */ new Set();
 		const numbers = /* @__PURE__ */ new Set();
 		for (const item of values) {
@@ -3708,7 +4001,7 @@ function compileFilter(view, raw, index, uncomparable) {
 			}
 		};
 	}
-	if (raw["value"] === void 0) fail(`${what}.value is required for op "${op}".`);
+	if (raw["value"] === void 0) fail$1(`${what}.value is required for op "${op}".`);
 	const value = String(scalar(raw["value"], `${what}.value`)).trim();
 	const valueKind = kindOf(value);
 	if (op === "contains") {
@@ -3730,7 +4023,7 @@ function compileFilter(view, raw, index, uncomparable) {
 			test: op === "eq" ? equal : (cells) => !equal(cells)
 		};
 	}
-	if (valueKind !== "number" && valueKind !== "date") fail(`${what}.value must be a number or an ISO date (YYYY-MM-DD) for op "${op}", received "${value}".`);
+	if (valueKind !== "number" && valueKind !== "date") fail$1(`${what}.value must be a number or an ISO date (YYYY-MM-DD) for op "${op}", received "${value}".`);
 	const numericValue = valueKind === "number" ? Number(value) : 0;
 	const satisfied = (order) => op === "gt" ? order > 0 : op === "gte" ? order >= 0 : op === "lt" ? order < 0 : order <= 0;
 	return {
@@ -3753,7 +4046,7 @@ function parseLimit(v) {
 		limit: QUERY_LIMITS.defaultRows,
 		clamped: false
 	};
-	if (typeof v !== "number" || !Number.isInteger(v) || v < 1) fail("\"limit\" must be a positive integer.");
+	if (typeof v !== "number" || !Number.isInteger(v) || v < 1) fail$1("\"limit\" must be a positive integer.");
 	return v > QUERY_LIMITS.maxRows ? {
 		limit: QUERY_LIMITS.maxRows,
 		clamped: true
@@ -3762,32 +4055,49 @@ function parseLimit(v) {
 		clamped: false
 	};
 }
+function parseGroups(args, view, field) {
+	const max = field === "groupBy" ? QUERY_LIMITS.maxGroupBy : QUERY_LIMITS.maxPivotBy;
+	const groups = list(args[field], field, max).map((raw, i) => {
+		if (!isObject(raw)) fail$1(`${field}[${i}] must be an object.`);
+		noOtherKeys(raw, ["column", "bucket"], `${field}[${i}]`);
+		const column = resolveColumn(view, raw["column"], `${field}[${i}].column`);
+		return {
+			column,
+			bucket: raw["bucket"] === void 0 ? "value" : oneOf(raw["bucket"], BUCKETS, `${field}[${i}].bucket`),
+			name: column.name
+		};
+	});
+	if (new Set(groups.map((group) => group.column.index)).size !== groups.length) fail$1(`"${field}" names the same column twice.`);
+	if (new Set(groups.map((group) => group.name)).size !== groups.length) for (const group of groups) group.name = group.column.label;
+	return groups;
+}
 function parseQuery(args, view) {
 	const op = oneOf(args["op"], ["aggregate", "rows"], "\"op\"");
 	const uncomparable = /* @__PURE__ */ new Map();
 	const filters = list(args["where"], "where", QUERY_LIMITS.maxFilters).map((raw, i) => compileFilter(view, raw, i, uncomparable));
 	const { limit, clamped } = parseLimit(args["limit"]);
 	const orderRaw = list(args["orderBy"], "orderBy", QUERY_LIMITS.maxOrderBy).map((raw, i) => {
-		if (!isObject(raw)) fail(`orderBy[${i}] must be an object.`);
+		if (!isObject(raw)) fail$1(`orderBy[${i}] must be an object.`);
 		noOtherKeys(raw, ["key", "desc"], `orderBy[${i}]`);
-		if (typeof raw["key"] !== "string" || raw["key"].trim() === "") fail(`orderBy[${i}].key must be a string.`);
-		if (raw["desc"] !== void 0 && typeof raw["desc"] !== "boolean") fail(`orderBy[${i}].desc must be a boolean.`);
+		if (typeof raw["key"] !== "string" || raw["key"].trim() === "") fail$1(`orderBy[${i}].key must be a string.`);
+		if (raw["desc"] !== void 0 && typeof raw["desc"] !== "boolean") fail$1(`orderBy[${i}].desc must be a boolean.`);
 		return {
 			key: raw["key"].trim(),
 			desc: raw["desc"] === true
 		};
 	});
 	if (op === "rows") {
-		if (args["groupBy"] !== void 0 || args["metrics"] !== void 0) fail("\"groupBy\" and \"metrics\" belong to op \"aggregate\". Use op \"rows\" with \"columns\" to list rows.");
+		if (args["groupBy"] !== void 0 || args["pivotBy"] !== void 0 || args["metrics"] !== void 0) fail$1("\"groupBy\", \"pivotBy\" and \"metrics\" belong to op \"aggregate\". Use op \"rows\" with \"columns\" to list rows.");
 		const columns = list(args["columns"], "columns", view.columns.length || 1).map((ref, i) => resolveColumn(view, ref, `columns[${i}]`));
 		for (const entry of orderRaw) resolveColumn(view, entry.key, "orderBy.key");
 		const offset = args["offset"];
-		if (offset !== void 0 && (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)) fail("\"offset\" must be a non-negative integer.");
+		if (offset !== void 0 && (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)) fail$1("\"offset\" must be a non-negative integer.");
 		return {
 			op,
 			filters,
 			uncomparable,
 			groups: [],
+			pivot: [],
 			metrics: [],
 			columns: columns.length > 0 ? columns : [...view.columns],
 			order: orderRaw,
@@ -3796,31 +4106,22 @@ function parseQuery(args, view) {
 			offset: typeof offset === "number" ? offset : 0
 		};
 	}
-	if (args["columns"] !== void 0 || args["offset"] !== void 0) fail("\"columns\" and \"offset\" belong to op \"rows\". Use op \"aggregate\" with \"groupBy\" and \"metrics\".");
-	const groups = list(args["groupBy"], "groupBy", QUERY_LIMITS.maxGroupBy).map((raw, i) => {
-		if (!isObject(raw)) fail(`groupBy[${i}] must be an object.`);
-		noOtherKeys(raw, ["column", "bucket"], `groupBy[${i}]`);
-		const column = resolveColumn(view, raw["column"], `groupBy[${i}].column`);
-		return {
-			column,
-			bucket: raw["bucket"] === void 0 ? "value" : oneOf(raw["bucket"], BUCKETS, `groupBy[${i}].bucket`),
-			name: column.name
-		};
-	});
-	if (new Set(groups.map((g) => g.column.index)).size !== groups.length) fail("\"groupBy\" names the same column twice.");
-	if (new Set(groups.map((g) => g.name)).size !== groups.length) for (const g of groups) g.name = g.column.label;
+	if (args["columns"] !== void 0 || args["offset"] !== void 0) fail$1("\"columns\" and \"offset\" belong to op \"rows\". Use op \"aggregate\" with \"groupBy\" and \"metrics\".");
+	const groups = parseGroups(args, view, "groupBy");
+	const pivot = parseGroups(args, view, "pivotBy");
+	if (pivot.some((dimension) => groups.some((group) => group.column.index === dimension.column.index))) fail$1("A column cannot appear in both \"groupBy\" and \"pivotBy\".");
 	const metricsRaw = list(args["metrics"], "metrics", QUERY_LIMITS.maxMetrics);
 	const metrics = (metricsRaw.length > 0 ? metricsRaw : [{ fn: "count" }]).map((raw, i) => {
-		if (!isObject(raw)) fail(`metrics[${i}] must be an object.`);
+		if (!isObject(raw)) fail$1(`metrics[${i}] must be an object.`);
 		noOtherKeys(raw, [
 			"fn",
 			"column",
 			"as"
 		], `metrics[${i}]`);
 		const fn = oneOf(raw["fn"], METRIC_FNS, `metrics[${i}].fn`);
-		if (raw["column"] === void 0 && fn !== "count") fail(`metrics[${i}].column is required for "${fn}".`);
+		if (raw["column"] === void 0 && fn !== "count") fail$1(`metrics[${i}].column is required for "${fn}".`);
 		const column = raw["column"] === void 0 ? void 0 : resolveColumn(view, raw["column"], `metrics[${i}].column`);
-		if (raw["as"] !== void 0 && (typeof raw["as"] !== "string" || raw["as"].trim() === "")) fail(`metrics[${i}].as must be a non-empty string.`);
+		if (raw["as"] !== void 0 && (typeof raw["as"] !== "string" || raw["as"].trim() === "")) fail$1(`metrics[${i}].as must be a non-empty string.`);
 		const alias = typeof raw["as"] === "string" ? raw["as"].trim() : column === void 0 ? fn : `${fn}(${column.name})`;
 		return column === void 0 ? {
 			fn,
@@ -3831,18 +4132,19 @@ function parseQuery(args, view) {
 			alias
 		};
 	});
-	if (new Set(metrics.map((m) => m.alias)).size !== metrics.length) fail("Two metrics have the same name; give one of them a distinct \"as\".");
+	if (new Set(metrics.map((m) => m.alias)).size !== metrics.length) fail$1("Two metrics have the same name; give one of them a distinct \"as\".");
 	const available = () => [...metrics.map((m) => m.alias), ...groups.map((g) => g.name)].join(", ");
 	for (const entry of orderRaw) {
 		if (metrics.some((m) => m.alias === entry.key)) continue;
 		const column = resolveColumn(view, entry.key, "orderBy.key");
-		if (!groups.some((g) => g.column.index === column.index)) fail(`orderBy.key "${entry.key}" is neither a metric nor a grouped column. Available: ${available()}.`);
+		if (!groups.some((g) => g.column.index === column.index)) fail$1(`orderBy.key "${entry.key}" is neither a metric nor a grouped column. Available: ${available()}.`);
 	}
 	return {
 		op,
 		filters,
 		uncomparable,
 		groups,
+		pivot,
 		metrics,
 		columns: [],
 		order: orderRaw,
@@ -3906,7 +4208,8 @@ function finish(metric, acc) {
 			return (metric.fn === "min" ? acc.minD : acc.maxD) ?? null;
 	}
 }
-function runAggregate(view, query) {
+async function runAggregate(view, query, complete = false) {
+	if (query.pivot.length > 0) return await runPivot(view, query, complete);
 	const { groups: groupSpecs, metrics } = query;
 	const skipped = new Map(metrics.map((m) => [m.alias, {
 		empty: 0,
@@ -3914,6 +4217,7 @@ function runAggregate(view, query) {
 	}]));
 	const unbucketed = /* @__PURE__ */ new Map();
 	const table = /* @__PURE__ */ new Map();
+	let dataRows = 0;
 	let matched = 0;
 	const groupOf = (key) => {
 		const id = key.map((part) => part === null ? "\0" : part).join("
");
@@ -3928,7 +4232,8 @@ function runAggregate(view, query) {
 		return group;
 	};
 	if (groupSpecs.length === 0) groupOf([]);
-	for (const { cells } of view.data) {
+	for await (const { cells } of view.data) {
+		dataRows += 1;
 		if (!query.filters.every((filter) => filter.test(cells))) continue;
 		matched += 1;
 		const group = groupOf(groupSpecs.map((spec) => {
@@ -4001,7 +4306,10 @@ function runAggregate(view, query) {
 	const out = rows.slice(0, query.limit).map((row) => ({
 		key: Object.fromEntries(row.key.map((part, i) => {
 			if (part === null) return [names[i], null];
-			const cut = clip$1(part);
+			const cut = complete ? {
+				text: part,
+				clipped: false
+			} : clip$1(part);
 			if (cut.clipped) cellsTruncated = true;
 			return [names[i], cut.text];
 		})),
@@ -4016,6 +4324,7 @@ function runAggregate(view, query) {
 		};
 	}
 	return {
+		dataRows,
 		matchedRows: matched,
 		uncomparable: Object.fromEntries(query.uncomparable),
 		groups: out,
@@ -4025,8 +4334,194 @@ function runAggregate(view, query) {
 		cellsTruncated
 	};
 }
-function runRows(view, query) {
-	const matched = view.data.filter((entry) => query.filters.every((filter) => filter.test(entry.cells)));
+async function runPivot(view, query, complete) {
+	const { groups: rowSpecs, pivot: columnSpecs, metrics } = query;
+	const skipped = new Map(metrics.map((metric) => [metric.alias, {
+		empty: 0,
+		nonNumeric: 0
+	}]));
+	const unbucketed = /* @__PURE__ */ new Map();
+	const table = /* @__PURE__ */ new Map();
+	const columnKeys = /* @__PURE__ */ new Map();
+	const labels = /* @__PURE__ */ new Map();
+	const uniqueLabels = /* @__PURE__ */ new Set();
+	let dataRows = 0;
+	let matched = 0;
+	let cellsTruncated = false;
+	const keyOf = (specs, cells) => specs.map((spec) => {
+		const text = (cells[spec.column.index] ?? "").trim();
+		if (text === "") return null;
+		if (spec.bucket === "value") return text;
+		if (kindOf(text) === "date") return text.slice(0, spec.bucket === "year" ? 4 : spec.bucket === "month" ? 7 : 10);
+		unbucketed.set(spec.name, (unbucketed.get(spec.name) ?? 0) + 1);
+		return null;
+	});
+	const idOf = (key) => key.map((part) => part === null ? "\0" : part).join("
");
+	const add = (metric, acc, cells, skip) => {
+		if (metric.column === void 0) {
+			acc.rows += 1;
+			return;
+		}
+		const text = (cells[metric.column.index] ?? "").trim();
+		if (metric.fn === "count") {
+			if (text !== "") acc.rows += 1;
+			return;
+		}
+		if (metric.fn === "countDistinct") {
+			if (text !== "") acc.distinct.add(text);
+			return;
+		}
+		const kind = kindOf(text);
+		if (kind === "empty") {
+			if (skip !== void 0) skip.empty += 1;
+		} else if (kind === "number") {
+			const value = Number(text);
+			acc.numbers += 1;
+			if (metric.fn === "sum" || metric.fn === "avg") acc.sum.add(value);
+			else if (metric.fn === "median") acc.values.push(value);
+			else if (metric.fn === "min") acc.minN = acc.minN === void 0 ? value : Math.min(acc.minN, value);
+			else acc.maxN = acc.maxN === void 0 ? value : Math.max(acc.maxN, value);
+		} else if (kind === "date" && (metric.fn === "min" || metric.fn === "max")) {
+			acc.dates += 1;
+			if (metric.fn === "min") acc.minD = acc.minD === void 0 ? text : acc.minD < text ? acc.minD : text;
+			else acc.maxD = acc.maxD === void 0 ? text : acc.maxD > text ? acc.maxD : text;
+		} else if (skip !== void 0) skip.nonNumeric += 1;
+	};
+	for await (const { cells } of view.data) {
+		dataRows += 1;
+		if (!query.filters.every((filter) => filter.test(cells))) continue;
+		matched += 1;
+		const rowKey = keyOf(rowSpecs, cells);
+		const columnKey = keyOf(columnSpecs, cells);
+		const rowId = idOf(rowKey);
+		const columnId = idOf(columnKey);
+		let group = table.get(rowId);
+		if (group === void 0) {
+			group = {
+				key: rowKey,
+				totals: metrics.map(newAcc),
+				cells: /* @__PURE__ */ new Map()
+			};
+			table.set(rowId, group);
+		}
+		if (!columnKeys.has(columnId)) {
+			columnKeys.set(columnId, columnKey);
+			const base = columnKey.map((part) => part ?? "(empty)").join(" / ");
+			let label = base;
+			let suffix = 2;
+			while (uniqueLabels.has(label)) label = `${base} (#${suffix++})`;
+			labels.set(columnId, label);
+			uniqueLabels.add(label);
+		}
+		let cellAccs = group.cells.get(columnId);
+		if (cellAccs === void 0) {
+			cellAccs = metrics.map(newAcc);
+			group.cells.set(columnId, cellAccs);
+		}
+		for (const [index, metric] of metrics.entries()) {
+			add(metric, group.totals[index], cells, skipped.get(metric.alias));
+			add(metric, cellAccs[index], cells);
+		}
+	}
+	const usedLabels = /* @__PURE__ */ new Set();
+	const columnLabel = (base, alias) => {
+		const clipped = complete ? {
+			text: `${base} | ${alias}`,
+			clipped: false
+		} : clip$1(`${base} | ${alias}`);
+		if (clipped.clipped) cellsTruncated = true;
+		let label = clipped.text;
+		let suffix = 2;
+		while (usedLabels.has(label)) label = `${clipped.text.slice(0, 190)} (#${suffix++})`;
+		usedLabels.add(label);
+		return label;
+	};
+	const descriptors = [...columnKeys.keys()].map((id) => ({
+		id,
+		label: labels.get(id)
+	}));
+	const shown = complete ? descriptors : descriptors.slice(0, QUERY_LIMITS.maxPivotColumns);
+	const dynamicColumns = shown.flatMap(({ label }) => metrics.map((metric) => columnLabel(label, metric.alias)));
+	const totalColumns = metrics.map((metric) => columnLabel("Total", metric.alias));
+	const outputColumns = [...dynamicColumns, ...totalColumns];
+	const ordered = [...table.values()].map((group) => ({
+		key: group.key,
+		values: Object.fromEntries(metrics.map((metric, index) => [totalColumns[index], finish(metric, group.totals[index])]))
+	}));
+	const keyIndexOf = (key) => {
+		const column = metrics.some((metric) => metric.alias === key) ? void 0 : resolveColumn(view, key, "orderBy.key");
+		return column === void 0 ? -1 : rowSpecs.findIndex((spec) => spec.column.index === column.index);
+	};
+	const comparators = [];
+	for (const entry of query.order) {
+		const metric = metrics.find((candidate) => candidate.alias === entry.key);
+		const metricIndex = metric === void 0 ? -1 : metrics.indexOf(metric);
+		const groupIndex = metricIndex === -1 ? keyIndexOf(entry.key) : -1;
+		comparators.push((a, b) => metricIndex === -1 ? compareNullable(a.key[groupIndex] ?? null, b.key[groupIndex] ?? null, entry.desc) : compareNullable(a.values[totalColumns[metricIndex]] ?? null, b.values[totalColumns[metricIndex]] ?? null, entry.desc));
+	}
+	if (comparators.length === 0 && rowSpecs.length > 0) {
+		comparators.push((a, b) => compareNullable(a.values[totalColumns[0]] ?? null, b.values[totalColumns[0]] ?? null, true));
+		for (let index = 0; index < rowSpecs.length; index += 1) comparators.push((a, b) => compareNullable(a.key[index] ?? null, b.key[index] ?? null, false));
+	}
+	ordered.sort((a, b) => {
+		for (const compare of comparators) {
+			const order = compare(a, b);
+			if (order !== 0) return order;
+		}
+		return 0;
+	});
+	const names = rowSpecs.map((spec) => spec.name);
+	const groups = ordered.slice(0, query.limit).map((entry) => {
+		const original = table.get(idOf(entry.key));
+		const values = {};
+		for (const [index, metric] of metrics.entries()) {
+			for (const [columnIndex, { id }] of shown.entries()) {
+				const accs = original.cells.get(id);
+				values[dynamicColumns[columnIndex * metrics.length + index]] = accs === void 0 ? null : finish(metric, accs[index]);
+			}
+			values[totalColumns[index]] = finish(metric, original.totals[index]);
+		}
+		return {
+			key: Object.fromEntries(entry.key.map((part, index) => {
+				if (part === null) return [names[index], null];
+				const cut = complete ? {
+					text: part,
+					clipped: false
+				} : clip$1(part);
+				if (cut.clipped) cellsTruncated = true;
+				return [names[index], cut.text];
+			})),
+			values
+		};
+	});
+	const skippedOut = {};
+	for (const [alias, { empty, nonNumeric }] of skipped) {
+		if (empty === 0 && nonNumeric === 0) continue;
+		skippedOut[alias] = {
+			...empty > 0 ? { empty } : {},
+			...nonNumeric > 0 ? { nonNumeric } : {}
+		};
+	}
+	return {
+		dataRows,
+		matchedRows: matched,
+		uncomparable: Object.fromEntries(query.uncomparable),
+		groups,
+		totalGroups: table.size,
+		columns: outputColumns,
+		...complete || descriptors.length <= QUERY_LIMITS.maxPivotColumns ? {} : { pivotColumnsTruncated: true },
+		...Object.keys(skippedOut).length > 0 ? { skipped: skippedOut } : {},
+		...unbucketed.size > 0 ? { unbucketed: Object.fromEntries(unbucketed) } : {},
+		cellsTruncated
+	};
+}
+async function runRows(view, query, complete = false) {
+	const matched = [];
+	let dataRows = 0;
+	for await (const entry of view.data) {
+		dataRows += 1;
+		if (query.filters.every((filter) => filter.test(entry.cells))) matched.push(entry);
+	}
 	if (query.order.length > 0) {
 		const keys = query.order.map((entry) => ({
 			index: resolveColumn(view, entry.key, "orderBy.key").index,
@@ -4048,12 +4543,17 @@ function runRows(view, query) {
 	const rows = matched.slice(query.offset, query.offset + query.limit).map((entry) => ({
 		row: entry.row,
 		cells: query.columns.map((column) => {
-			const cut = clip$1((entry.cells[column.index] ?? "").trim());
+			const raw = (entry.cells[column.index] ?? "").trim();
+			const cut = complete ? {
+				text: raw,
+				clipped: false
+			} : clip$1(raw);
 			if (cut.clipped) cellsTruncated = true;
 			return cut.text;
 		})
 	}));
 	return {
+		dataRows,
 		matchedRows: matched.length,
 		uncomparable: Object.fromEntries(query.uncomparable),
 		rows,
@@ -4062,13 +4562,220 @@ function runRows(view, query) {
 	};
 }
 
+//#endregion
+//#region ../agent/src/table/export.ts
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function fail(message) {
+	throw new WebSkillError("VALIDATION_FAILED", message);
+}
+function onlyKeys(value, allowed, path) {
+	const extra = Object.keys(value).filter((key) => !allowed.includes(key));
+	if (extra.length > 0) fail(`${path} has unsupported field(s): ${extra.join(", ")}.`);
+}
+function sheetName(value, path) {
+	if (typeof value !== "string" || value.trim() === "") fail(`${path} must be a non-empty sheet name.`);
+	return value.trim();
+}
+function literalRows(value, path) {
+	if (!Array.isArray(value)) fail(`${path} must be an array of rows.`);
+	return value.map((row, rowIndex) => {
+		if (!Array.isArray(row)) fail(`${path}[${rowIndex}] must be an array of cells.`);
+		return row.map((cell, columnIndex) => {
+			if (cell !== null && ![
+				"string",
+				"number",
+				"boolean"
+			].includes(typeof cell)) fail(`${path}[${rowIndex}][${columnIndex}] must be a string, number, boolean or null.`);
+			return cell;
+		});
+	});
+}
+function parseExportFile(raw) {
+	if (raw === void 0) return void 0;
+	if (!isRecord$1(raw)) fail("\"exportFile\" must be an object with a \"fileName\".");
+	onlyKeys(raw, [
+		"fileName",
+		"sheetName",
+		"additionalSheets"
+	], "\"exportFile\"");
+	const additionalRaw = raw["additionalSheets"];
+	if (additionalRaw !== void 0 && (!Array.isArray(additionalRaw) || additionalRaw.length === 0)) fail("\"exportFile.additionalSheets\" must be a non-empty array when present.");
+	const additionalSheets = (additionalRaw ?? []).map((entry, index) => {
+		const path = `exportFile.additionalSheets[${index}]`;
+		if (!isRecord$1(entry)) fail(`"${path}" must be an object.`);
+		const name = sheetName(entry["name"], `"${path}.name"`);
+		if ("query" in entry) {
+			onlyKeys(entry, ["name", "query"], `"${path}"`);
+			if (!isRecord$1(entry["query"])) fail(`"${path}.query" must be an aggregate or rows query object.`);
+			return {
+				name,
+				query: entry["query"]
+			};
+		}
+		onlyKeys(entry, [
+			"name",
+			"columns",
+			"rows"
+		], `"${path}"`);
+		const columns = entry["columns"];
+		if (columns !== void 0 && (!Array.isArray(columns) || columns.some((column) => typeof column !== "string"))) fail(`"${path}.columns" must be an array of header strings.`);
+		return {
+			name,
+			...columns !== void 0 ? { columns } : {},
+			rows: literalRows(entry["rows"], `${path}.rows`)
+		};
+	});
+	return {
+		fileName: resolveFileName$1(raw["fileName"], "query_table"),
+		sheetName: raw["sheetName"] === void 0 ? "Query result" : sheetName(raw["sheetName"], "\"exportFile.sheetName\""),
+		additionalSheets
+	};
+}
+const CELL_SCHEMA = { anyOf: [
+	{ type: "string" },
+	{ type: "number" },
+	{ type: "boolean" },
+	{ type: "null" }
+] };
+function createExportFileSchema(queryProperties) {
+	const nestedQueryProperties = Object.fromEntries(Object.entries(queryProperties).filter(([key]) => ![
+		"id",
+		"limit",
+		"offset"
+	].includes(key)).map(([key, value]) => key === "op" ? [key, {
+		...value,
+		enum: ["aggregate", "rows"],
+		description: "The query operation for this sheet."
+	}] : [key, value]));
+	return {
+		type: "object",
+		description: "Write complete query results directly to one Excel file. Preview limits do not apply. The top-level query forms the primary sheet; additionalSheets can add more complete queries or small literal notes sheets.",
+		properties: {
+			fileName: {
+				type: "string",
+				description: "Workbook file name, for example \"contract-analysis.xlsx\"."
+			},
+			sheetName: {
+				type: "string",
+				description: "Name of the primary sheet produced by the top-level query. Defaults to \"Query result\"."
+			},
+			additionalSheets: {
+				type: "array",
+				minItems: 1,
+				maxItems: SPREADSHEET_LIMITS.sheets - 1,
+				description: "Additional sheets in the same workbook. Use {name, query} for complete query results. Use {name, columns, rows} only for a small notes or definitions sheet, never to copy large query results.",
+				items: { anyOf: [{
+					type: "object",
+					properties: {
+						name: {
+							type: "string",
+							description: "Output sheet name."
+						},
+						query: {
+							type: "object",
+							description: "A complete aggregate or rows query against the same workbook id. Every result row is written directly to this sheet without passing through the model. Preview limit and offset do not apply.",
+							properties: nestedQueryProperties,
+							required: ["op"],
+							additionalProperties: false
+						}
+					},
+					required: ["name", "query"],
+					additionalProperties: false
+				}, {
+					type: "object",
+					description: "A small literal notes or definitions sheet, not a way to transport large query results.",
+					properties: {
+						name: {
+							type: "string",
+							description: "Output sheet name."
+						},
+						columns: {
+							type: "array",
+							maxItems: SPREADSHEET_LIMITS.columnsPerSheet,
+							items: { type: "string" }
+						},
+						rows: {
+							type: "array",
+							maxItems: SPREADSHEET_LIMITS.rowsPerSheet,
+							items: {
+								type: "array",
+								maxItems: SPREADSHEET_LIMITS.columnsPerSheet,
+								items: CELL_SCHEMA
+							}
+						}
+					},
+					required: ["name", "rows"],
+					additionalProperties: false
+				}] }
+			}
+		},
+		required: ["fileName"],
+		additionalProperties: false
+	};
+}
+function sheetFromQuery(query, output, name) {
+	if (output.groups !== void 0) {
+		const valueColumns = query.pivot.length > 0 ? output.columns ?? [] : query.metrics.map((metric) => metric.alias);
+		return {
+			name,
+			columns: [...query.groups.map((group) => group.name), ...valueColumns],
+			rows: output.groups.map((group) => [...query.groups.map((dimension) => group.key[dimension.name] ?? null), ...valueColumns.map((column) => group.values[column] ?? null)])
+		};
+	}
+	return {
+		name,
+		columns: output.columns ?? [],
+		rows: (output.rows ?? []).map((row) => row.cells)
+	};
+}
+async function exportQuerySheet(workbook, args, name) {
+	const view = isStreamingTableWorkbook(workbook) ? await buildStreamingView(workbook, args["sheet"], args["headerRow"]) : buildView(workbook, args["sheet"], args["headerRow"]);
+	const query = parseQuery(args, view);
+	const computation = {
+		...query,
+		limit: Number.MAX_SAFE_INTEGER,
+		offset: 0,
+		limitClamped: false
+	};
+	const output = computation.op === "aggregate" ? await runAggregate(view, computation, true) : await runRows(view, computation, true);
+	return {
+		sheet: sheetFromQuery(query, output, name),
+		matchedRows: output.matchedRows,
+		...output.totalGroups !== void 0 ? { totalGroups: output.totalGroups } : {}
+	};
+}
+function captureTableQueryArgs(args) {
+	const exportFile = args["exportFile"];
+	if (!isRecord$1(exportFile)) return args;
+	const sheets = exportFile["additionalSheets"];
+	if (!Array.isArray(sheets)) return args;
+	let redacted = false;
+	const captured = sheets.map((sheet) => {
+		if (!isRecord$1(sheet) || !Array.isArray(sheet["rows"])) return sheet;
+		redacted = true;
+		const summary = {
+			...sheet,
+			rowCount: sheet["rows"].length
+		};
+		delete summary["rows"];
+		return summary;
+	});
+	return redacted ? {
+		...args,
+		exportFile: {
+			...exportFile,
+			additionalSheets: captured
+		}
+	} : args;
+}
+
 //#endregion
 //#region ../agent/src/table/toolSource.ts
 /** @experimental */
 const QUERY_TABLE_TOOL = "query_table";
-const DESCRIPTION$2 = "Run exact statistics over an Excel (.xlsx) workbook the user attached, without reading it row by row: describe its sheets and columns, aggregate (filter, group, count, distinct count, sum, average, min, max, median), or list matching rows. Every query covers all rows and is computed on the user’s device.";
+const DESCRIPTION$2 = "Run exact statistics over an Excel (.xlsx) workbook the user attached, without reading it row by row: describe its sheets and columns, aggregate (filter, group, pivot, count, distinct count, sum, average, min, max, median), or list matching rows. Every query covers all rows and is computed on the user’s device.";
 const DESCRIPTION_WITH_DOWNLOADS = DESCRIPTION$2.replace("the user attached,", "the user attached or downloaded,");
-const SYSTEM_PROMPT$3 = "query_table computes over every row of an attached .xlsx workbook. Use it for any count, total, average, extreme, median, ranking or breakdown, and quote its numbers as returned — they are exact. Do not estimate statistics from sample rows, and do not page through a whole sheet with read_document to compute them. When a result reports skipped or uncomparable cells, tell the user how many and why. Attachment ids from earlier messages of this conversation stay valid for this tool.";
+const SYSTEM_PROMPT$3 = "query_table computes over every row of an attached .xlsx workbook. Use it for any count, total, average, extreme, median, ranking or breakdown, and quote its numbers as returned — they are exact. Do not estimate statistics from sample rows, and do not page through a whole sheet with read_document to compute them. For a multi-dimensional distinct count, put every row dimension in groupBy and use countDistinct directly. For a cross-tab, additionally put column dimensions in pivotBy; row totals are included. Do not delegate these single-scan queries to subagents. When a result reports skipped or uncomparable cells, tell the user how many and why. Attachment ids from earlier messages of this conversation stay valid for this tool.";
 const SYSTEM_PROMPT_WITH_DOWNLOADS = `${SYSTEM_PROMPT$3} A downloaded workbook\u2019s id from list_downloaded_files works too.`;
 const ID_DESCRIPTION = "The attachment id from the message that carried the workbook.";
 const ID_DESCRIPTION_WITH_DOWNLOADS = `${ID_DESCRIPTION} For a downloaded file, use the id from list_downloaded_files; the user is asked for permission to read it.`;
@@ -4150,6 +4857,24 @@ const INPUT_SCHEMA$2 = {
 				additionalProperties: false
 			}
 		},
+		pivotBy: {
+			type: "array",
+			maxItems: QUERY_LIMITS.maxPivotBy,
+			description: "aggregate only. Pivot column dimensions. groupBy supplies the row dimensions and pivotBy supplies the column dimensions; every metric is computed for each cell and for the row total.",
+			items: {
+				type: "object",
+				properties: {
+					column: COLUMN,
+					bucket: {
+						type: "string",
+						enum: [...BUCKETS],
+						description: "\"value\" (default) groups by the cell text; year/month/day bucket ISO date cells."
+					}
+				},
+				required: ["column"],
+				additionalProperties: false
+			}
+		},
 		metrics: {
 			type: "array",
 			maxItems: QUERY_LIMITS.maxMetrics,
@@ -4193,7 +4918,7 @@ const INPUT_SCHEMA$2 = {
 		limit: {
 			type: "integer",
 			minimum: 1,
-			description: `Groups or rows to return. Default ${QUERY_LIMITS.defaultRows}, at most ${QUERY_LIMITS.maxRows}.`
+			description: `Preview groups or rows to return. Default ${QUERY_LIMITS.defaultRows}, at most ${QUERY_LIMITS.maxRows}. Ignored when exportFile is present: exported files contain the complete query result.`
 		},
 		offset: {
 			type: "integer",
@@ -4238,10 +4963,17 @@ function fit(head, field, items, more) {
 * @experimental
 */
 function createTableQueryToolSource(options) {
-	const schemaWithDownloads = {
+	const schema = options.writeArtifact === void 0 ? INPUT_SCHEMA$2 : {
 		...INPUT_SCHEMA$2,
 		properties: {
 			...INPUT_SCHEMA$2.properties,
+			exportFile: createExportFileSchema(INPUT_SCHEMA$2.properties ?? {})
+		}
+	};
+	const schemaWithDownloads = {
+		...schema,
+		properties: {
+			...schema.properties,
 			id: {
 				type: "string",
 				description: ID_DESCRIPTION_WITH_DOWNLOADS
@@ -4249,6 +4981,7 @@ function createTableQueryToolSource(options) {
 		}
 	};
 	const downloads = () => options.downloadedFiles?.() === true;
+	const exportPrompt = options.writeArtifact === void 0 ? "" : " When the user asks for an Excel file of query results, call this tool with exportFile so every group or matching row is written locally without passing through the model. Never copy a truncated preview into export_spreadsheet. For one workbook with multiple sheets, keep the primary query at the top level, name it with exportFile.sheetName, and put additional complete queries in exportFile.additionalSheets as {name, query}. A small notes sheet may use {name, columns, rows}. Do not page full results through the model or write one file per query when the user asked for one workbook.";
 	return {
 		kind: "table-query",
 		listToolSpecs: () => Promise.resolve([downloads() ? {
@@ -4258,11 +4991,12 @@ function createTableQueryToolSource(options) {
 		} : {
 			name: QUERY_TABLE_TOOL,
 			description: DESCRIPTION$2,
-			inputSchema: INPUT_SCHEMA$2
+			inputSchema: schema
 		}]),
-		systemPrompt: () => Promise.resolve(downloads() ? SYSTEM_PROMPT_WITH_DOWNLOADS : SYSTEM_PROMPT$3),
+		systemPrompt: () => Promise.resolve((downloads() ? SYSTEM_PROMPT_WITH_DOWNLOADS : SYSTEM_PROMPT$3) + exportPrompt),
 		canHandle: (name) => name === QUERY_TABLE_TOOL,
 		argCaptureTrust: (name) => name === "query_table" ? { tier: "reviewed" } : void 0,
+		captureArgs: (_name, args) => captureTableQueryArgs(args),
 		call: async (name, args, context) => {
 			try {
 				if (name !== "query_table") throw new WebSkillError("TOOL_NOT_FOUND", `Unknown tool ${name}.`);
@@ -4278,26 +5012,83 @@ function createTableQueryToolSource(options) {
 		const loaded = await options.tables.load(id, context);
 		if (loaded === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", `No readable workbook with id "${id}". Use the id of an Excel file attached in this conversation; files from other conversations are not available.`);
 		const { workbook, name } = loaded;
-		if (args["op"] === "describe") return {
+		const op = args["op"];
+		const exportRequest = parseExportFile(args["exportFile"]);
+		if (exportRequest !== void 0 && op === "describe") throw new WebSkillError("VALIDATION_FAILED", "\"exportFile\" applies to aggregate or rows, not describe.");
+		if (exportRequest !== void 0 && options.writeArtifact === void 0) throw new WebSkillError("TOOL_UNSUPPORTED", "This host cannot write query results as Excel files.");
+		const profileInput = {
+			name,
+			id,
+			...args["sheet"] !== void 0 ? { sheet: args["sheet"] } : {},
+			...args["headerRow"] !== void 0 ? { headerRow: args["headerRow"] } : {}
+		};
+		if (op === "describe") return {
 			ok: true,
 			content: [{
 				type: "text",
-				text: profileTable({
-					name,
-					id,
-					workbook,
-					...args["sheet"] !== void 0 ? { sheet: args["sheet"] } : {},
-					...args["headerRow"] !== void 0 ? { headerRow: args["headerRow"] } : {}
+				text: isStreamingTableWorkbook(workbook) ? await profileStreamingTable({
+					...profileInput,
+					workbook
+				}) : profileTable({
+					...profileInput,
+					workbook
 				})
 			}]
 		};
-		const view = buildView(workbook, args["sheet"], args["headerRow"]);
+		if (exportRequest !== void 0) {
+			const main = await exportQuerySheet(workbook, args, exportRequest.sheetName);
+			const spec = { sheets: [main.sheet] };
+			const sheetSummaries = [{
+				name: exportRequest.sheetName,
+				rowCount: main.sheet.rows.length,
+				matchedRows: main.matchedRows,
+				...main.totalGroups !== void 0 ? { totalGroups: main.totalGroups } : {}
+			}];
+			for (const additional of exportRequest.additionalSheets) if ("query" in additional) {
+				const result = await exportQuerySheet(workbook, additional.query, additional.name);
+				spec.sheets.push(result.sheet);
+				sheetSummaries.push({
+					name: additional.name,
+					rowCount: result.sheet.rows.length,
+					matchedRows: result.matchedRows,
+					...result.totalGroups !== void 0 ? { totalGroups: result.totalGroups } : {}
+				});
+			} else {
+				spec.sheets.push({
+					name: additional.name,
+					...additional.columns !== void 0 ? { columns: additional.columns } : {},
+					rows: additional.rows
+				});
+				sheetSummaries.push({
+					name: additional.name,
+					rowCount: additional.rows.length
+				});
+			}
+			const bytes = await encodeSpreadsheet(spec);
+			const artifact = await options.writeArtifact(exportRequest.fileName, bytes, SPREADSHEET_MIME_TYPE, context);
+			return {
+				ok: true,
+				content: [{
+					type: "json",
+					data: {
+						path: artifact.path,
+						size: artifact.size,
+						sheetCount: spec.sheets.length,
+						rowCount: spec.sheets.reduce((total, sheet) => total + sheet.rows.length, 0),
+						matchedRows: main.matchedRows,
+						...main.totalGroups !== void 0 ? { totalGroups: main.totalGroups } : {},
+						...exportRequest.additionalSheets.length > 0 ? { sheets: sheetSummaries } : {}
+					}
+				}]
+			};
+		}
+		const view = isStreamingTableWorkbook(workbook) ? await buildStreamingView(workbook, args["sheet"], args["headerRow"]) : buildView(workbook, args["sheet"], args["headerRow"]);
 		const query = parseQuery(args, view);
-		const output = query.op === "aggregate" ? runAggregate(view, query) : runRows(view, query);
+		const output = query.op === "aggregate" ? await runAggregate(view, query, false) : await runRows(view, query, false);
 		const head = {
 			sheet: view.sheetName,
 			headerRow: view.headerRow,
-			dataRows: view.data.length,
+			dataRows: output.dataRows,
 			matchedRows: output.matchedRows,
 			...output.totalGroups !== void 0 ? { totalGroups: output.totalGroups } : {},
 			...output.columns !== void 0 ? { columns: output.columns } : {},
@@ -4305,10 +5096,11 @@ function createTableQueryToolSource(options) {
 			...output.unbucketed !== void 0 ? { unbucketed: output.unbucketed } : {},
 			...Object.keys(output.uncomparable).length > 0 ? { uncomparable: output.uncomparable } : {},
 			...output.cellsTruncated ? { cellsTruncated: true } : {},
+			...output.pivotColumnsTruncated ? { pivotColumnsTruncated: true } : {},
 			...query.limitClamped ? { limitClamped: QUERY_LIMITS.maxRows } : {}
 		};
 		const items = output.groups ?? output.rows ?? [];
-		const more = output.groups !== void 0 ? (output.totalGroups ?? 0) > output.groups.length : query.offset + items.length < output.matchedRows;
+		const more = output.pivotColumnsTruncated === true || (output.groups !== void 0 ? (output.totalGroups ?? 0) > output.groups.length : query.offset + items.length < output.matchedRows);
 		return {
 			ok: true,
 			content: [{
@@ -4772,7 +5564,7 @@ function json(data) {
 //#endregion
 //#region ../agent/src/pageImage/toolSource.ts
 const CAPTURE_PAGE_IMAGE_TOOL = "capture_page_image";
-const DESCRIPTION$1 = "Save a picture that is already on the page as a run artifact, so a skill can place it in a document.";
+const DESCRIPTION$1 = "Save a picture that is already on the page as a run artifact, so a skill can place it in a document. To see what a picture shows, use perceive_page with images: true instead.";
 const INPUT_SCHEMA$1 = {
 	type: "object",
 	properties: {
@@ -4788,7 +5580,7 @@ const INPUT_SCHEMA$1 = {
 	required: ["ref"],
 	additionalProperties: false
 };
-const SYSTEM_PROMPT$2 = "Use capture_page_image when a picture on the current page belongs in a document you are about to produce. It returns a reference, never the picture itself — pass that reference to the skill, do not try to read it back. Capturing does not tell you what the picture shows; ask for a page perception with images if you need that. Capture one picture per call, and only for nodes the page perception marked as capturable. Do not list the captured references back to the user. They are working material for the document, not a deliverable; say how many pictures went in and leave it at that.";
+const SYSTEM_PROMPT$2 = "Use capture_page_image when a picture on the current page belongs in a document you are about to produce. It returns a reference, never the picture itself — pass that reference to the skill, do not try to read it back. To see what a picture shows, call perceive_page with images: true; capturing here only saves it for a document and does not tell you what it shows. Capture one picture per call, and only for nodes the page perception marked as capturable. Do not list the captured references back to the user. They are working material for the document, not a deliverable; say how many pictures went in and leave it at that.";
 const isFailure$1 = (result) => "reason" in result;
 /**
 * 页面取像工具（0.22.0 分册 12）。
@@ -5149,4 +5941,4 @@ function createDwgToolSource(options) {
 }
 
 //#endregion
-export { CAPTURE_PAGE_IMAGE_TOOL, 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, DWG_MODEL_VIEW_ID, DataSourceCandidatePolicy, DataSourcePolicy, DelegationOrchestrator, DownloadedFilePolicy, EMU_PER_PIXEL, EMU_PER_POINT, EMU_PER_TWIP, EXPORT_SPREADSHEET_TOOL, FETCH_REMOTE_IMAGE_TOOL, FILL_TEMPLATE_TOOL, FOCUS_PAGE_TAB_TOOL, GENERATE_SKILL_TOOL, INSPECT_TEMPLATE_TOOL, LIST_DOWNLOADED_FILES_TOOL, LIST_PAGE_TABS_TOOL, MANAGE_TODO_TOOL, MAX_DIGIT_WIDTH, 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, QUERY_TABLE_TOOL, READ_DOCUMENT_TOOL, READ_DOWNLOADED_FILE_TOOL, SCROLL_DIRECTIONS, SKILL_GENERATION_SYSTEM_PROMPT, SkillGenerator, TAB_WORKSET_DEFAULT_MAX, TAB_WORKSET_MAX_MAX, TAB_WORKSET_MIN_MAX, TAB_WORKSET_SYSTEM_PROMPT, TEMPLATE_INSPECT_BUDGET, TODO_SYSTEM_PROMPT, TabWorksetPolicy, TodoStore, VIEW_DWG_TOOL, asReadMode, clampDownloadWaitMs, clampWorksetMax, columnWidthToPixels, createDelegationToolSource, createDocumentToolSource, createDownloadedFileToolSource, createDwgToolSource, createHttpDataSourceTransport, createPageActionToolSource, createPageImageToolSource, createPagePerceptionToolSource, createRemoteImageToolSource, createSkillGenerationToolSource, createSpreadsheetToolSource, createTabWorksetToolSource, createTableQueryToolSource, createTemplateToolSource, createTodoToolSource, defersImage, dwgPickView, dwgViewsOf, fitWithin, formatCellAddress, frameLabel, frameSteps, isPdfTextTrustworthy, isRangeTopLeft, measurePdfTextQuality, parseCellAddress, parseCellRange, profileTable, rangeContains, readImageSize, sniffDocumentFormat, takesImage, toActionFrameScopes, toFrameScopes, withDelegationOrigin };
+export { CAPTURE_PAGE_IMAGE_TOOL, 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, DWG_MODEL_VIEW_ID, DataSourceCandidatePolicy, DataSourcePolicy, DelegationOrchestrator, DownloadedFilePolicy, EMU_PER_PIXEL, EMU_PER_POINT, EMU_PER_TWIP, EXPORT_SPREADSHEET_TOOL, FETCH_REMOTE_IMAGE_TOOL, FILL_TEMPLATE_TOOL, FOCUS_PAGE_TAB_TOOL, GENERATE_SKILL_TOOL, INSPECT_TEMPLATE_TOOL, LIST_DOWNLOADED_FILES_TOOL, LIST_PAGE_TABS_TOOL, MANAGE_TODO_TOOL, MAX_DIGIT_WIDTH, 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, QUERY_TABLE_TOOL, READ_DOCUMENT_TOOL, READ_DOWNLOADED_FILE_TOOL, SCROLL_DIRECTIONS, SKILL_GENERATION_SYSTEM_PROMPT, SkillGenerator, TAB_WORKSET_DEFAULT_MAX, TAB_WORKSET_MAX_MAX, TAB_WORKSET_MIN_MAX, TAB_WORKSET_SYSTEM_PROMPT, TEMPLATE_INSPECT_BUDGET, TODO_SYSTEM_PROMPT, TabWorksetPolicy, TodoStore, VIEW_DWG_TOOL, asReadMode, buildStreamingView, clampDownloadWaitMs, clampWorksetMax, columnWidthToPixels, createDelegationToolSource, createDocumentToolSource, createDownloadedFileToolSource, createDwgToolSource, createHttpDataSourceTransport, createPageActionToolSource, createPageImageToolSource, createPagePerceptionToolSource, createRemoteImageToolSource, createSkillGenerationToolSource, createSpreadsheetToolSource, createTabWorksetToolSource, createTableQueryToolSource, createTemplateToolSource, createTodoToolSource, defersImage, dwgPickView, dwgViewsOf, fitWithin, formatCellAddress, frameLabel, frameSteps, isPdfTextTrustworthy, isRangeTopLeft, isStreamingTableWorkbook, measurePdfTextQuality, parseCellAddress, parseCellRange, profileStreamingTable, profileTable, rangeContains, readImageSize, sniffDocumentFormat, summarizeStreamingWorkbook, takesImage, toActionFrameScopes, toFrameScopes, withDelegationOrigin };