@webskill/sdk 0.20.0 → 0.22.0

package/dist/{approval-Bbh_Apwg.js → approval-DWQlDPbY.js}

@@ -3,11 +3,11 @@ import { b as parseSkillMarkdown, i as buildCatalog, n as SkillDiscovery, r as S
 import { a as atomicWriteText, r as resolveInsideRoot, t as assertSafePathSegment } from "./pathSecurity-B1owvJAF.js";
 import { t as assertRemoteUrlAllowed } from "./urlSafety-CiSuCJvX.js";
 import { c as findUnpairedToolCalls, d as partsToText, f as promptText, l as interruptedToolResult, p as textParts, u as sealToolCallPairs } from "./llm-eIQNO9tr.js";
-import { a as fromBase64, c as DEFAULT_MAX_DOCUMENT_BYTES, d as TEXT_BUDGETED_CONTENT_TYPES, i as UNSUPPORTED_DOCUMENT_MESSAGE, l as DEFAULT_MAX_DOCUMENT_TEXT_BYTES, n as READ_LINKED_DOCUMENT_TOOL_NAME, o as toBase64, r as SUPPORTED_DOCUMENT_MIME, t as READ_LINKED_DOCUMENT_TOOL } from "./linkedDocument-xNXF-z8n.js";
+import { a as UNSUPPORTED_DOCUMENT_MESSAGE, c as toBase64, f as SPREADSHEET_MIME_TYPE, g as DEFAULT_MAX_DOCUMENT_TEXT_BYTES, h as DEFAULT_MAX_DOCUMENT_BYTES, i as SUPPORTED_DOCUMENT_MIME, l as encodeSpreadsheet, n as READ_LINKED_DOCUMENT_TOOL, o as fromBase64, r as READ_LINKED_DOCUMENT_TOOL_NAME, s as isBytesOnlyDocument, v as TEXT_BUDGETED_CONTENT_TYPES } from "./linkedDocument-CIuh_Yp0.js";
 import { t as mergeCatalogEntries } from "./external-_ZRQe-V9.js";
 import { i as isArtifactCardHidden, n as extractChartSpec, r as admitArtifactMetadata, t as buildRenderResult } from "./renderResult-D9Q-Vu2x.js";
 import { t as extractUiSpecEvents } from "./surface-DVGiCmwq.js";
-import { t as MemoryArtifactStore } from "./memoryArtifactStore-D6dLeY55.js";
+import { t as MemoryArtifactStore } from "./memoryArtifactStore-Bs7glPqm.js";
 
 //#region ../core/src/render/xmlRenderer.ts
 /** 转义 XML 五个特殊字符：& < > " ' */
@@ -298,12 +298,68 @@ function resolveSkillDir(skillRoot, dir, relativePath) {
 	return resolveInsideRoot(skillRoot, `${dir}/${relativePath}`);
 }
 /**
+* 脚本上下文里 `context.writeSpreadsheet` 的图片引用解析（FR-20.8）。
+*
+* 前缀族与文档那一侧同源（分册 11）：`artifact:` 读本 run 已写出的产物，
+* `upload:` 读发起本 run 的那条消息里的附件。两条都**不经模型**、也不经沙箱桥——
+* 脚本交上来的始终只是一个引用，字节在这里才第一次出现。
+*
+* `remote:` 不收：表格必须把字节嵌进去，留外链等于交一份在别人机器上打不开的表。
+* 要用远端图，先落成产物再引用。
+*/
+function createScriptImageResolver(deps) {
+	return async (ref) => {
+		const separator = ref.indexOf(":");
+		const kind = separator === -1 ? "" : ref.slice(0, separator);
+		const rest = ref.slice(separator + 1);
+		if (kind === "artifact") {
+			if (deps.artifactStore.readArtifact === void 0) return void 0;
+			const found = (await deps.artifactStore.listArtifacts(deps.runId)).find((a) => a.path === rest);
+			if (found === void 0) return void 0;
+			return {
+				bytes: await deps.artifactStore.readArtifact(deps.runId, rest),
+				contentType: found.mimeType ?? "application/octet-stream"
+			};
+		}
+		if (kind === "upload") {
+			if (deps.uploadFiles === void 0) return void 0;
+			const files = await deps.uploadFiles.list();
+			const info = files.find((file) => file.id === rest) ?? files.find((file) => file.name === rest);
+			if (info === void 0) return void 0;
+			return {
+				bytes: await deps.uploadFiles.read(info.id),
+				contentType: info.contentType
+			};
+		}
+		if (kind === "remote") throw new WebSkillError("VALIDATION_FAILED", `image reference "${ref}" cannot be embedded: spreadsheets need the bytes, not a link. Fetch it into an artifact first and reference that.`);
+		throw new WebSkillError("VALIDATION_FAILED", `image reference "${ref}" has no known prefix; expected artifact: or upload:`);
+	};
+}
+/**
 * 脚本执行上下文：只暴露 readReference / readAsset / readAssetBinary / writeArtifact
 * 四个显式能力，不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
 */
 function createScriptContext(deps) {
 	const { fs, artifactStore, skillName, skillRoot, runId, confirm, fetchData, uploadFiles, onWarning, onArtifactCreated } = deps;
 	const readFs = fs.withRoot?.(skillRoot) ?? fs;
+	const writeArtifact = async (path, content, options) => {
+		const metadata = options?.metadata === void 0 ? void 0 : admitArtifactMetadata(options.metadata);
+		const artifact = typeof content === "string" ? await artifactStore.createTextArtifact({
+			runId,
+			path,
+			content,
+			mimeType: options?.mimeType,
+			...metadata === void 0 ? {} : { metadata }
+		}) : await artifactStore.createBinaryArtifact({
+			runId,
+			path,
+			content,
+			mimeType: options?.mimeType,
+			...metadata === void 0 ? {} : { metadata }
+		});
+		onArtifactCreated?.(artifact);
+		return artifact;
+	};
 	return {
 		skillName,
 		runId,
@@ -316,24 +372,18 @@ function createScriptContext(deps) {
 		async readAssetBinary(relativePath) {
 			return readFs.readBinary(resolveSkillDir(skillRoot, "assets", relativePath));
 		},
-		async writeArtifact(path, content, options) {
-			const metadata = options?.metadata === void 0 ? void 0 : admitArtifactMetadata(options.metadata);
-			const artifact = typeof content === "string" ? await artifactStore.createTextArtifact({
+		writeArtifact,
+		...deps.writeSpreadsheet ? { writeSpreadsheet: async (path, spec, options) => {
+			const resolveImage = createScriptImageResolver({
+				artifactStore,
 				runId,
-				path,
-				content,
-				mimeType: options?.mimeType,
-				...metadata === void 0 ? {} : { metadata }
-			}) : await artifactStore.createBinaryArtifact({
-				runId,
-				path,
-				content,
-				mimeType: options?.mimeType,
-				...metadata === void 0 ? {} : { metadata }
+				...uploadFiles ? { uploadFiles } : {}
 			});
-			onArtifactCreated?.(artifact);
-			return artifact;
-		},
+			return writeArtifact(path, await encodeSpreadsheet(spec, resolveImage), {
+				mimeType: SPREADSHEET_MIME_TYPE,
+				...options?.metadata === void 0 ? {} : { metadata: options.metadata }
+			});
+		} } : {},
 		...confirm ? { confirm } : {},
 		...fetchData ? { fetchData } : {},
 		...deps.documentSurface ? { documentSurface: true } : {},
@@ -687,6 +737,90 @@ function renderCurrentTimePrompt(nowIso) {
 */
 const ON_DEMAND_TOOLS_HINT = "Some tools are disclosed on demand and are not listed above. If a capability you need seems missing, look for a related skill in the catalog and read its SKILL.md first — activating it may reveal additional tools. Do not conclude the capability does not exist.";
 
+//#endregion
+//#region ../runtime/src/engine/visionBatch.ts
+/**
+* 视觉委派的分批并发调度（0.21.0 分册 26 · FR-26.5 ~ FR-26.7）。
+*
+* 从 `agentLoop` 里拆出来，是因为它有三条彼此独立的分支——并发、慢降级、失败隔离——
+* 塞进那个已经三千行的文件里就只能靠端到端测，而这三条恰恰是最需要单独逼出来的。
+* @experimental
+*/
+/** 并发度上限。再高只会让每一张都变慢，同时把端点的速率限制撞穿（FR-26.5） @experimental */
+const VISION_MAX_CONCURRENCY = 3;
+/** @experimental */
+const VISION_DEFAULT_CONCURRENCY = 2;
+/**
+* 超过它就退回串行（FR-26.6）。云端视觉端点单张 3–15 秒，本地 Qwen-VL 一类 20–40 秒；
+* 越过 25 秒说明端点已经在排队，继续并发只会让第一张有用的描述来得更晚。
+* @experimental
+*/
+const VISION_SLOW_THRESHOLD_MS = 25e3;
+/** 配错了应该退化成能用，不是让 run 失败（FR-26.5） @experimental */
+function clampVisionConcurrency(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return 2;
+	return Math.min(3, Math.max(1, Math.round(value)));
+}
+/**
+* 逐张委派、按并发度并行。
+*
+* 第一波结算后测一次墙钟决定要不要降级：测第一波而不是第一张，
+* 因为并发下第一张返回得早纯属运气，一波的完成时间才反映端点的实际吞吐。
+* 降级是**单向**的，本次委派内不再回升。
+* @experimental
+*/
+async function runVisionBatch(options) {
+	const total = options.images.length;
+	const now = options.now ?? (() => Date.now());
+	const slowThresholdMs = options.slowThresholdMs ?? 25e3;
+	const outcome = {
+		described: new Array(total).fill(void 0),
+		failures: [],
+		declined: false
+	};
+	let cursor = 0;
+	let done = 0;
+	let concurrency = clampVisionConcurrency(options.concurrency);
+	const settle = (index, result) => {
+		if (result.outcome === "described") {
+			outcome.described[index] = result.text;
+			outcome.endpoint ??= result.endpoint;
+		} else if (result.outcome === "declined") outcome.declined = true;
+		else outcome.failures.push({
+			index,
+			reason: result.reason
+		});
+		done += 1;
+		options.onProgress?.(done, total);
+	};
+	const stopped = () => outcome.declined || options.signal?.aborted === true;
+	const one = async (index) => {
+		try {
+			settle(index, await options.describe(options.images[index], index));
+		} catch (e) {
+			settle(index, {
+				outcome: "failed",
+				reason: e instanceof Error ? e.message : String(e)
+			});
+		}
+	};
+	const firstWave = [];
+	const startedAt = now();
+	for (; cursor < total && firstWave.length < concurrency; cursor += 1) firstWave.push(one(cursor));
+	await Promise.all(firstWave);
+	if (now() - startedAt > slowThresholdMs) concurrency = 1;
+	const worker = async () => {
+		while (!stopped()) {
+			const index = cursor;
+			if (index >= total) return;
+			cursor += 1;
+			await one(index);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(concurrency, total - cursor) }, () => worker()));
+	return outcome;
+}
+
 //#endregion
 //#region ../runtime/src/trace/traceRecorder.ts
 /** 结构化 trace 记录器；时钟与 id 工厂可注入（golden trace 用固定值保证确定性） */
@@ -1047,6 +1181,11 @@ const LLM_TURN_CODES = /* @__PURE__ */ new Set([
 	"TOOL_SCHEMA_UNAVAILABLE"
 ]);
 /**
+* 端点 200 但整轮 run 没给出任何答复时的说明。
+* 上下文撑爆只是最常见的成因，不是判据——判据是「一句回答都没有」这个事实本身。
+*/
+const EMPTY_RESPONSE_MESSAGE = "The model produced no answer and requested no tools, so this run has nothing to show. The most common cause is a conversation that has outgrown the model context window: start a new chat, remove large attachments, or switch to a model with a larger context window.";
+/**
 * 模型侧图片通道收得下的位图格式（三家 provider 的交集）。
 * SVG 是文本、`application/octet-stream` 是未知字节——两者编成 data URL 发出去，
 * 端点当场 400（LM Studio：`'url' field must be a base64 encoded image.`），
@@ -1198,7 +1337,8 @@ var AgentLoop = class {
 			maxUnknownToolRetries: config.maxUnknownToolRetries ?? 2,
 			askUserMaxFields: config.askUserMaxFields ?? 20,
 			maxDocumentBytes: config.maxDocumentBytes ?? 256e5,
-			maxDocumentTextBytes: config.maxDocumentTextBytes ?? 512e3,
+			maxDocumentTextBytes: config.maxDocumentTextBytes ?? 512e4,
+			visionConcurrency: clampVisionConcurrency(config.visionConcurrency),
 			temperature: config.temperature,
 			renderResult: config.renderResult,
 			remoteUrl: config.remoteUrl
@@ -1256,6 +1396,7 @@ var AgentLoop = class {
 			interactionSeq: 0,
 			surfaceActionSeq: 0,
 			documentSeq: 0,
+			binaries: /* @__PURE__ */ new Map(),
 			messages: [],
 			turn: 0,
 			renderBlocks: [],
@@ -1421,6 +1562,7 @@ var AgentLoop = class {
 		const { llm } = this.#deps;
 		const { trace, messages } = state;
 		this.#armDeadline(state);
+		let producedOutput = false;
 		try {
 			for (let turn = startTurn;; turn++) {
 				state.turn = turn;
@@ -1502,12 +1644,14 @@ var AgentLoop = class {
 					outputTokens: response.usage.outputTokens
 				} });
 				if (!response.toolCalls?.length) {
+					if (responseText === "" && !producedOutput) return finish("failed", "llm-error", EMPTY_RESPONSE_MESSAGE, "LLM_REQUEST_FAILED");
 					messages.push({
 						role: "assistant",
 						content: response.content ?? []
 					});
 					return finish("completed", "final-answer", responseText);
 				}
+				producedOutput = true;
 				await this.#lifecycle({
 					phase: "execute",
 					data: {
@@ -1698,6 +1842,7 @@ var AgentLoop = class {
 			trace,
 			reader: new SkillReader(this.#deps.fs, this.#deps.skillIndex),
 			documentSeq: 0,
+			binaries: /* @__PURE__ */ new Map(),
 			activated: new Set(snapshot.activeSkillNames),
 			activatedTools: new Map(snapshot.activatedTools.map((d) => [d.name, d])),
 			skillAllowedTools: new Map(Object.entries(snapshot.skillAllowedTools ?? {})),
@@ -2126,7 +2271,11 @@ var AgentLoop = class {
 			const source = resolution.kind === "script" ? void 0 : (this.#deps.externalTools ?? []).find((s) => s.canHandle(call.name));
 			if (source === void 0 && !this.#checkToolAccess(state, call.name)) result = this.#deniedToolError(state, call.name);
 			else if (resolution.kind === "script") result = await this.#handleScriptTool(call, resolution.skillName, resolution.scriptName, state);
-			else if (source) result = await source.call(call.name, call.arguments, { runId: state.runId });
+			else if (source) result = await source.call(call.name, call.arguments, {
+				runId: state.runId,
+				signal: state.controller.signal,
+				binaries: { get: (id) => state.binaries.get(id) }
+			});
 			else {
 				if (resolution.kind === "not-found") state.unknownToolCalls += 1;
 				result = toolError(resolution.code, resolution.message, resolution.kind === "not-found" ? resolution.data : void 0);
@@ -2520,20 +2669,55 @@ var AgentLoop = class {
 			};
 		}
 		let text;
-		if (mime === SUPPORTED_DOCUMENT_MIME.docx || mime === SUPPORTED_DOCUMENT_MIME.xlsx) {
-			const docx = mime === SUPPORTED_DOCUMENT_MIME.docx;
-			const kind = docx ? "docx" : "xlsx";
-			const extractor = docx ? this.#deps.docxExtractor : this.#deps.xlsxExtractor;
-			if (extractor === void 0) {
+		if (isBytesOnlyDocument(mime, target.href)) {
+			state.binaries.set(id, {
+				name,
+				mimeType: mime,
+				bytes: fetched.bytes
+			});
+			await audit(record);
+			return {
+				ok: true,
+				content: [{
+					type: "json",
+					data: {
+						id,
+						name,
+						mimeType: mime,
+						bytes: fetched.bytes.length,
+						note: "Stored for tools. Its contents are not readable as text — pass this id to a tool that reads this format."
+					}
+				}]
+			};
+		}
+		const route = {
+			[SUPPORTED_DOCUMENT_MIME.docx]: {
+				kind: "docx",
+				label: "Word documents",
+				...this.#deps.docxExtractor ? { extractor: this.#deps.docxExtractor } : {}
+			},
+			[SUPPORTED_DOCUMENT_MIME.xlsx]: {
+				kind: "xlsx",
+				label: "Excel workbooks",
+				...this.#deps.xlsxExtractor ? { extractor: this.#deps.xlsxExtractor } : {}
+			},
+			[SUPPORTED_DOCUMENT_MIME.pptx]: {
+				kind: "pptx",
+				label: "PowerPoint presentations",
+				...this.#deps.pptxExtractor ? { extractor: this.#deps.pptxExtractor } : {}
+			}
+		}[mime];
+		if (route !== void 0) {
+			if (route.extractor === void 0) {
 				await audit({
 					...record,
 					ok: false,
-					reason: `no ${kind} extractor`
+					reason: `no ${route.kind} extractor`
 				});
-				return toolError("TOOL_UNSUPPORTED", `${docx ? "Word documents" : "Excel workbooks"} cannot be read in this environment: no ${kind} text extractor is configured.`);
+				return toolError("TOOL_UNSUPPORTED", `${route.label} cannot be read in this environment: no ${route.kind} text extractor is configured.`);
 			}
 			try {
-				text = await extractor(fetched.bytes);
+				text = await route.extractor(fetched.bytes);
 			} catch (e) {
 				const message = messageOf(e);
 				await audit({
@@ -2811,6 +2995,131 @@ var AgentLoop = class {
 		});
 		return dropped > 0;
 	}
+	/**
+	* 工具产出的图 → 第二个端点认出来的文本（0.21.0 分册 17）。
+	*
+	* 返回 `undefined` 表示「本次不委派」，调用方原样投图——注入位缺席、
+	* 选中模型本来就看得了图、或者这批结果里根本没有图，都走这条。
+	* 返回值里的 `kept` 是去掉图之后仍要投出的分片（PDF 等文件分片不受影响）。
+	*
+	* 四种失败一律**返回可读说明**而不是抛错：静默丢图会让主模型以为自己看过了
+	* （FR-17.5a，与 `#dropRejectedImages` 同口径）。
+	*/
+	async #delegateVision(state, call, carried) {
+		const delegate = this.#deps.visionDelegate;
+		if (delegate === void 0) return void 0;
+		const images = carried.filter(isImagePart);
+		if (images.length === 0) return void 0;
+		try {
+			if (await delegate.applies() !== true) return void 0;
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Vision delegation availability check failed: ${messageOf(e)}` });
+			return;
+		}
+		const kept = carried.filter((part) => !isImagePart(part));
+		const subject = `the ${images.length === 1 ? "image" : `${images.length} images`} from "${call.name}"`;
+		const dropped = `The ${images.length === 1 ? "image was" : "images were"} not attached; work from the surrounding text, and say so if the answer depends on what ${images.length === 1 ? "it shows" : "they show"}.`;
+		const finish = (note) => {
+			state.trace.record("run.warning", {
+				message: note,
+				data: {
+					images: images.length,
+					tool: call.name
+				}
+			});
+			return {
+				kept,
+				note
+			};
+		};
+		const remainingTurns = state.maxTurns - state.turn;
+		const remainingMs = state.totalTimeoutMs - this.#elapsed(state);
+		const timeoutMs = Math.min(state.toolTimeoutMs * images.length, remainingMs);
+		if (remainingTurns < 1 || timeoutMs <= 0) return finish(`The parent run has no budget left to describe ${subject} (${remainingTurns} turns and ${Math.max(0, Math.round(remainingMs))} ms remaining). ${dropped}`);
+		const payload = images.map((part) => ({
+			mimeType: part.mimeType,
+			data: part.data
+		}));
+		const cancelled = state.controller.signal;
+		const describeOne = async (image) => {
+			const left = state.totalTimeoutMs - this.#elapsed(state);
+			const budget = Math.min(state.toolTimeoutMs, left);
+			if (budget <= 0) return {
+				outcome: "failed",
+				reason: "the parent run has no time budget left"
+			};
+			const controller = new AbortController();
+			const cancelParent = () => controller.abort(cancelled.reason);
+			cancelled.addEventListener("abort", cancelParent, { once: true });
+			let timedOut = false;
+			const timer = setTimeout(() => {
+				timedOut = true;
+				controller.abort(/* @__PURE__ */ new Error("vision delegation timed out"));
+			}, budget);
+			try {
+				const one = await delegate.describe({
+					images: [image],
+					task: state.run.userPrompt,
+					source: call.name,
+					batch: {
+						id: call.id,
+						total: payload.length
+					},
+					timeoutMs: budget,
+					signal: controller.signal
+				});
+				return timedOut ? {
+					outcome: "failed",
+					reason: `exceeded its ${budget} ms budget`
+				} : one;
+			} catch (e) {
+				return {
+					outcome: "failed",
+					reason: timedOut ? `exceeded its ${budget} ms budget` : messageOf(e)
+				};
+			} finally {
+				clearTimeout(timer);
+				cancelled.removeEventListener("abort", cancelParent);
+			}
+		};
+		const batch = await runVisionBatch({
+			images: payload,
+			concurrency: clampVisionConcurrency(this.#config.visionConcurrency),
+			describe: describeOne,
+			signal: cancelled,
+			onProgress: (progressed, total) => {
+				this.#lifecycle({
+					phase: "execute",
+					data: {
+						kind: "vision-progress",
+						source: call.name,
+						done: progressed,
+						total
+					}
+				}, state);
+			}
+		});
+		if (batch.declined) return finish(`The user declined to send ${subject} to another provider for description. ${dropped}`);
+		const describedCount = batch.described.filter((text) => text !== void 0).length;
+		if (describedCount === 0) return finish(`Due to image recognition errors, ${subject} could not be read: ${batch.failures[0]?.reason ?? "no description was produced"}. ${dropped}`);
+		const lines = batch.described.map((text, index) => {
+			const failure = batch.failures.find((entry) => entry.index === index);
+			const body = text ?? `not read due to image recognition errors: ${failure?.reason ?? "the endpoint gave no reason"}`;
+			return images.length === 1 ? body : `[${index + 1}/${images.length}] ${body}`;
+		});
+		if (describedCount < images.length) state.trace.record("run.warning", {
+			message: `Due to image recognition errors, ${images.length - describedCount} of ${images.length} images from "${call.name}" were not read.`,
+			data: {
+				images: images.length,
+				described: describedCount,
+				tool: call.name
+			}
+		});
+		return {
+			kept,
+			note: `--- ${images.length === 1 ? "Image" : `${images.length} images`} from "${call.name}", described by ${batch.endpoint ?? "another model"} because the assistant model cannot read images ---\n${lines.join("\n")}`
+		};
+	}
 	/** 单个 PDF 分片 → 文本；包装形态与 chatEngine 的附件标签同口径（FR-22.3 / FR-22.4） */
 	async #pdfAsText(state, part, extract) {
 		const name = part.name ?? "document.pdf";
@@ -2906,6 +3215,12 @@ var AgentLoop = class {
 			state.trace.record("run.warning", { message: note });
 			notes.push(note);
 		}
+		const delegated = await this.#delegateVision(state, call, carried);
+		if (delegated !== void 0) {
+			carried.length = 0;
+			carried.push(...delegated.kept);
+			notes.push(delegated.note);
+		}
 		return {
 			tool: [
 				{
@@ -3193,6 +3508,7 @@ var AgentLoop = class {
 			confirm: (message) => this.#confirm(message, state),
 			...this.#deps.fetchData ? { fetchData: this.#deps.fetchData } : {},
 			...this.#deps.documentSurface ? { documentSurface: true } : {},
+			...this.#deps.writeSpreadsheet ? { writeSpreadsheet: true } : {},
 			...this.#deps.uploadFiles ? { uploadFiles: this.#uploadFilePort(this.#deps.uploadFiles, skillName, state) } : {},
 			onWarning: (message) => state.trace.record("run.warning", { message }),
 			onArtifactCreated: (artifact) => createdIds.add(artifact.id)
@@ -3535,6 +3851,148 @@ var AgentLoop = class {
 	}
 };
 
+//#endregion
+//#region ../runtime/src/engine/compaction.ts
+/** 摘要消息的固定前缀：压缩留痕靠它识别，UI 与后续压缩都读这个标记 */
+const COMPACTION_PREFIX = "[Earlier conversation summary]";
+/** 触发比例默认值：留出四分之一余量，够装下这一轮的提问与工具结果 */
+const DEFAULT_COMPACTION_THRESHOLD = .75;
+/** 压缩后至少保留的原文消息数 */
+const DEFAULT_KEEP_RECENT_MESSAGES = 12;
+/** 保留原文的下界：压到比这更少就等于换了个会话（FR-20.6 第 3 条） */
+const MIN_KEEP_RECENT_MESSAGES = 6;
+/**
+* 要不要压缩。三个输入缺一不压（FR-20.6 第 4 条的「不猜」）：
+* 没有窗口就没有分母，没有真实用量就没有分子——两者都不许估算。
+*/
+function shouldCompact(lastInputTokens, contextWindow, threshold) {
+	if (lastInputTokens === void 0 || contextWindow === void 0) return false;
+	if (!Number.isFinite(lastInputTokens) || !Number.isFinite(contextWindow) || contextWindow <= 0) return false;
+	return lastInputTokens / contextWindow >= threshold;
+}
+/**
+* 把想要的切点挪到不破坏 tool 契约的位置：
+* 切点之后不得以孤儿 `tool` 消息开头（它的 assistant 调用会被压掉），
+* 切点之前不得以未应答的 assistant `toolCalls` 结尾。
+*
+* 与 `trimSessionHistory` 是同一套边界规则，区别只在这里要的是**一个**切点。
+* 返回 0 表示没有安全切点，调用方应当放弃本次压缩。
+*/
+function alignCut(messages, desired) {
+	let cut = Math.max(0, Math.min(desired, messages.length));
+	while (cut < messages.length && messages[cut].role === "tool") cut += 1;
+	if (cut >= messages.length) return 0;
+	while (cut > 0) {
+		const last = messages[cut - 1];
+		if (last.role === "assistant" && last.toolCalls?.length) cut -= 1;
+		else break;
+	}
+	return cut;
+}
+/** 把一段消息压成给模型看的纯文本转录；图片与文件只留占位，不塞 base64 */
+function transcribe(messages) {
+	return messages.map((message) => {
+		const body = message.content.map((part) => {
+			if (part.type === "text") return part.text;
+			if (part.type === "image") return "[image]";
+			return `[file${part.name !== void 0 ? ` ${part.name}` : ""}]`;
+		}).join("\n").trim();
+		const calls = message.toolCalls?.map((call) => `[called ${call.name}]`).join(" ") ?? "";
+		return `${message.role.toUpperCase()}: ${[body, calls].filter((s) => s !== "").join(" ")}`.trim();
+	}).join("\n");
+}
+const SUMMARY_INSTRUCTION = "Summarize the conversation transcript below so that another assistant can continue the conversation without seeing the original messages. Keep every fact, decision, user preference, identifier, number and unfinished task. Drop greetings, acknowledgements and repetition. Write plain prose, no headings, no bullet lists, under 400 words. Do not add information that is not in the transcript.";
+/**
+* 压缩会话历史：最早的一段换成一条摘要消息，最近若干条保留原文。
+*
+* 返回 `undefined` 表示**没压**——历史还不够长、找不到安全切点、或摘要调用失败。
+* 压缩是优化，任何一步不顺都退回原历史，不能把一次正常提问变成一次失败（FR-20.6 第 5 条）。
+*
+* 摘要用 `user` 角色而不是 `system`：会话历史里本就不含 system（每轮 run 由路由重起），
+* 且 Anthropic 不接受非首条的 system 消息。
+*/
+async function compactHistory(history, options) {
+	const keep = Math.max(6, options.keepRecentMessages ?? 12);
+	const cut = alignCut(history, history.length - keep);
+	if (cut <= 0) return void 0;
+	const head = history.slice(0, cut);
+	const tail = history.slice(cut);
+	let summary;
+	try {
+		summary = ((await options.llm.complete({ messages: [{
+			role: "system",
+			content: [{
+				type: "text",
+				text: SUMMARY_INSTRUCTION
+			}]
+		}, {
+			role: "user",
+			content: [{
+				type: "text",
+				text: transcribe(head)
+			}]
+		}] })).content ?? []).map((part) => part.type === "text" ? part.text : "").join("").trim();
+	} catch (e) {
+		options.onWarn?.(`compaction summary request failed: ${e instanceof Error ? e.message : String(e)}`);
+		return;
+	}
+	if (summary === "") {
+		options.onWarn?.("compaction summary was empty; history left untouched");
+		return;
+	}
+	return {
+		messages: [{
+			role: "user",
+			content: [{
+				type: "text",
+				text: `${COMPACTION_PREFIX}\n${summary}`
+			}]
+		}, ...tail],
+		removed: head.length,
+		kept: tail.length
+	};
+}
+
+//#endregion
+//#region ../runtime/src/engine/usage.ts
+/**
+* 从 run 的 trace 聚合大模型用量（请求次数 + 输入/输出 token）。
+* 与 `summarizeToolCalls` 同型：消费方不再各自遍历 trace。
+* @stable
+*/
+function summarizeRunUsage(trace) {
+	let llmCalls = 0;
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let hasUsage = false;
+	let lastInputTokens;
+	for (const event of trace) {
+		if (event.type === "llm.request") {
+			llmCalls += 1;
+			continue;
+		}
+		if (event.type !== "llm.usage") continue;
+		const input = event.data?.["inputTokens"];
+		const output = event.data?.["outputTokens"];
+		const hasInput = typeof input === "number" && Number.isFinite(input);
+		const hasOutput = typeof output === "number" && Number.isFinite(output);
+		if (hasInput) {
+			inputTokens += input;
+			lastInputTokens = input;
+		}
+		if (hasOutput) outputTokens += output;
+		if (hasInput || hasOutput) hasUsage = true;
+	}
+	return {
+		llmCalls,
+		...hasUsage ? {
+			inputTokens,
+			outputTokens
+		} : {},
+		...lastInputTokens !== void 0 ? { lastInputTokens } : {}
+	};
+}
+
 //#endregion
 //#region ../runtime/src/engine/runtime.ts
 /**
@@ -3604,24 +4062,46 @@ var WebSkillRuntime = class {
 	* 既有 runtime.run(prompt) 保持无状态单次语义不变。
 	* 同 handle 并发 run 经 per-handle 队列串行化（防历史 last-writer-wins 丢轮次）；
 	* maxHistoryMessages（默认取 `DEFAULT_LOOP_LIMITS`）超出时滚动裁剪中段（保留首尾；边界对齐 tool 契约）。
+	*
+	* 配了 `contextWindow` 时另加一道**主动压缩**（分册 20 FR-20.6）：按上一轮的真实
+	* `prompt_tokens` 与窗口的比值判定，超阈值就在下一轮发起前把最早的一段摘要掉。
+	* 三个输入（窗口、用量、足够长的历史）缺一不压——不估算、不猜。
 	*/
 	createSession(options = {}) {
 		const sessionId = options.sessionId ?? `session-${Math.random().toString(36).slice(2, 10)}`;
 		const createdAt = (/* @__PURE__ */ new Date()).toISOString();
 		const maxHistory = options.maxHistoryMessages ?? DEFAULT_LOOP_LIMITS.maxHistoryMessages;
+		const threshold = options.compactionThreshold ?? .75;
 		let history = [];
 		let queue = Promise.resolve();
+		/** 上一轮结束时的上下文水位线；没拿到 usage 就一直是 undefined，届时不压缩 */
+		let lastInputTokens;
 		return {
 			id: sessionId,
 			createdAt,
 			run: (prompt, runOptions = {}) => {
 				const result = queue.then(async () => {
+					if (shouldCompact(lastInputTokens, options.contextWindow, threshold)) {
+						const compacted = await compactHistory(history, {
+							llm: this.#deps.llm,
+							...options.keepRecentMessages !== void 0 ? { keepRecentMessages: options.keepRecentMessages } : {}
+						});
+						if (compacted) {
+							history = compacted.messages;
+							lastInputTokens = void 0;
+							options.onCompacted?.({
+								removed: compacted.removed,
+								kept: compacted.kept
+							});
+						}
+					}
 					const r = await this.run(prompt, {
 						sessionId,
 						history,
 						...runOptions
 					});
 					history = trimSessionHistory(r.messages.slice(1), maxHistory);
+					lastInputTokens = summarizeRunUsage(r.run.trace).lastInputTokens;
 					return r;
 				});
 				queue = result.then(() => void 0, () => void 0);
@@ -3686,8 +4166,10 @@ var WebSkillRuntime = class {
 			docxExtractor: this.#deps.docxExtractor,
 			xlsxExtractor: this.#deps.xlsxExtractor,
 			pdfExtractor: this.#deps.pdfExtractor,
+			visionDelegate: this.#deps.visionDelegate,
 			documentAudit: this.#deps.documentAudit,
 			documentSurface: this.#deps.documentSurface,
+			writeSpreadsheet: this.#deps.writeSpreadsheet,
 			uploadFileAudit: this.#deps.uploadFileAudit,
 			maxUploadFileBytes: this.#deps.maxUploadFileBytes,
 			uploadFiles: options.uploadFiles
@@ -3819,8 +4301,10 @@ var WebSkillRuntime = class {
 			docxExtractor: this.#deps.docxExtractor,
 			xlsxExtractor: this.#deps.xlsxExtractor,
 			pdfExtractor: this.#deps.pdfExtractor,
+			visionDelegate: this.#deps.visionDelegate,
 			documentAudit: this.#deps.documentAudit,
 			documentSurface: this.#deps.documentSurface,
+			writeSpreadsheet: this.#deps.writeSpreadsheet,
 			uploadFileAudit: this.#deps.uploadFileAudit,
 			maxUploadFileBytes: this.#deps.maxUploadFileBytes
 		}, this.#deps.config);
@@ -3979,6 +4463,9 @@ var FsArtifactStore = class {
 			return [];
 		}
 	}
+	async readArtifact(runId, path) {
+		return this.#fs.readBinary(this.#artifactPath(runId, path));
+	}
 	#artifactPath(runId, artifactPath) {
 		assertSafePathSegment(runId, "runId");
 		return resolveInsideRoot(`${this.#root}/${runId}`, artifactPath);
@@ -4030,6 +4517,17 @@ function parseBridgeRequest(data) {
 				..."metadata" in data ? { metadata: data["metadata"] } : {}
 			};
 		}
+		case "writeSpreadsheet": {
+			const { path, spec } = data;
+			if (!isNonEmptyString(path) || !isRecord(spec)) return void 0;
+			return {
+				kind,
+				id,
+				path,
+				spec,
+				..."metadata" in data ? { metadata: data["metadata"] } : {}
+			};
+		}
 		case "confirm": return isNonEmptyString(data["message"]) ? {
 			kind,
 			id,
@@ -4255,4 +4753,4 @@ var CapabilityApproval = class CapabilityApproval {
 };
 
 //#endregion
-export { scriptToolName as $, readUserProfile as A, createScriptContext as B, TraceRecorder as C, mergeProfileEntries as D, appendBehaviorRecords as E, DEFAULT_USER_PROFILE_LIMITS as F, ASK_USER_TOOL_NAME as G, ASK_USER_INPUT_SCHEMA as H, EMPTY_USER_PROFILE as I, READ_SKILL_FILE_TOOL_NAME as J, READ_SKILL_FILE_INPUT_SCHEMA as K, SerializingMemoryStore as L, USER_PROFILE_NO_INVENTION_RULE as M, USER_PROFILE_PROMPT_HEADER as N, readBehaviorRecords as O, renderUserProfileContext as P, schemaSourceLabel as Q, EventBus as R, extractTodoTraceEvents as S, USER_PROFILE_KEY as T, ASK_USER_MAX_FIELDS as U, ASK_USER_FIELD_TYPES as V, ASK_USER_TOOL as W, formatSkillScriptManifest as X, ALLOWED_TOOLS_EXCLUSION_REASON as Y, listSkillScripts as Z, RUN_SNAPSHOT_SCHEMA_VERSION as _, networkPolicyLibSource as a, xmlRenderer as at, MAX_TOOL_STEP_ARG_BYTES as b, bridgeError as c, FsMemoryStore as d, resolveToolName as et, WebSkillRuntime as f, FsRunSnapshotStore as g, redactToolStepArgs as h, isNetworkAllowed as i, renderAvailableSkillsXml as it, sampleBehaviorRecords as j, readProfileEntries as k, parseBridgeRequest as l, SENSITIVE_ANNOTATION as m, normalizeErrorCode as n, ProgressiveRouter as nt, networkUrlHost as o, AgentLoop as p, READ_SKILL_FILE_TOOL as q, normalizeToolError as r, escapeXml as rt, UPLOAD_FILES_UNAVAILABLE as s, CapabilityApproval as t, toLlmToolSpec as tt, FsArtifactStore as u, isUnsupportedRunSnapshot as v, BEHAVIOR_RECORDS_KEY as w, extractSkillCandidate as x, DEFAULT_LOOP_LIMITS as y, schemaToForm as z };
+export { READ_SKILL_FILE_TOOL as $, BEHAVIOR_RECORDS_KEY as A, renderUserProfileContext as B, extractTodoTraceEvents as C, VISION_SLOW_THRESHOLD_MS as D, VISION_MAX_CONCURRENCY as E, readProfileEntries as F, schemaToForm as G, EMPTY_USER_PROFILE as H, readUserProfile as I, ASK_USER_INPUT_SCHEMA as J, createScriptContext as K, sampleBehaviorRecords as L, appendBehaviorRecords as M, mergeProfileEntries as N, clampVisionConcurrency as O, readBehaviorRecords as P, READ_SKILL_FILE_INPUT_SCHEMA as Q, USER_PROFILE_NO_INVENTION_RULE as R, extractSkillCandidate as S, VISION_DEFAULT_CONCURRENCY as T, SerializingMemoryStore as U, DEFAULT_USER_PROFILE_LIMITS as V, EventBus as W, ASK_USER_TOOL as X, ASK_USER_MAX_FIELDS as Y, ASK_USER_TOOL_NAME as Z, FsRunSnapshotStore as _, networkPolicyLibSource as a, scriptToolName as at, DEFAULT_LOOP_LIMITS as b, bridgeError as c, ProgressiveRouter as ct, FsMemoryStore as d, xmlRenderer as dt, READ_SKILL_FILE_TOOL_NAME as et, WebSkillRuntime as f, redactToolStepArgs as g, SENSITIVE_ANNOTATION as h, isNetworkAllowed as i, schemaSourceLabel as it, USER_PROFILE_KEY as j, runVisionBatch as k, parseBridgeRequest as l, escapeXml as lt, AgentLoop as m, normalizeErrorCode as n, formatSkillScriptManifest as nt, networkUrlHost as o, resolveToolName as ot, summarizeRunUsage as p, ASK_USER_FIELD_TYPES as q, normalizeToolError as r, listSkillScripts as rt, UPLOAD_FILES_UNAVAILABLE as s, toLlmToolSpec as st, CapabilityApproval as t, ALLOWED_TOOLS_EXCLUSION_REASON as tt, FsArtifactStore as u, renderAvailableSkillsXml as ut, RUN_SNAPSHOT_SCHEMA_VERSION as v, TraceRecorder as w, MAX_TOOL_STEP_ARG_BYTES as x, isUnsupportedRunSnapshot as y, USER_PROFILE_PROMPT_HEADER as z };