@webskill/sdk 0.12.0 → 0.13.0

package/dist/{dist-sdKFgERo.js → dist-ExSQky4C.js}

@@ -607,6 +607,76 @@ function createSseFrameReader() {
 		}
 	};
 }
+/**
+* 内联 `<think>` 段落切分器（内部模块，不进公开导出）。
+*
+* 本地部署的思考型模型（Qwen 等经 OpenAI 兼容端点）不下发 `reasoning_content`，
+* 而是把推理直接写进 `content`，用 `<think>` … `</think>` 包起来。不切分的话
+* 思考正文会当成回答正文流进界面、进消息历史、进落盘，既污染上下文也没法折叠。
+*/
+const OPEN = "<think>";
+const CLOSE = "</think>";
+/** buffer 是否为 tag 的真前缀（还不能判定，得再等） */
+const isPartialPrefix = (buffer, tag) => buffer.length < tag.length && tag.startsWith(buffer);
+function createThinkTagSplitter() {
+	let buffer = "";
+	let inThink = false;
+	const consume = () => {
+		let text = "";
+		let thinking = "";
+		for (;;) {
+			const tag = inThink ? CLOSE : OPEN;
+			const hit = buffer.indexOf(tag);
+			if (hit >= 0) {
+				const before = buffer.slice(0, hit);
+				if (inThink) thinking += before;
+				else text += before;
+				buffer = buffer.slice(hit + tag.length);
+				inThink = !inThink;
+				continue;
+			}
+			const start = buffer.lastIndexOf("<");
+			const keep = start >= 0 && isPartialPrefix(buffer.slice(start), tag) ? start : buffer.length;
+			const emit = buffer.slice(0, keep);
+			if (inThink) thinking += emit;
+			else text += emit;
+			buffer = buffer.slice(keep);
+			return {
+				text,
+				thinking
+			};
+		}
+	};
+	return {
+		push(delta) {
+			buffer += delta;
+			return consume();
+		},
+		flush() {
+			const rest = buffer;
+			buffer = "";
+			return inThink ? {
+				text: "",
+				thinking: rest
+			} : {
+				text: rest,
+				thinking: ""
+			};
+		}
+	};
+}
+/** 非流式整段切分：返回正文与思考正文（无 `<think>` 时 thinking 为 undefined） */
+function splitThinkTags(content) {
+	if (!content.includes(OPEN)) return { text: content };
+	const splitter = createThinkTagSplitter();
+	const first = splitter.push(content);
+	const last = splitter.flush();
+	const thinking = first.thinking + last.thinking;
+	return {
+		text: first.text + last.text,
+		...thinking !== "" ? { thinking } : {}
+	};
+}
 const dataUrl = (part) => `data:${part.mimeType};base64,${part.data}`;
 /** parts → OpenAI content；纯文本折叠成字符串（兼容端点对数组形态支持不一） */
 const toOpenAiContent = (parts, where) => {
@@ -712,6 +782,7 @@ var OpenAiCompatibleClient = class {
 		const decoder = new TextDecoder();
 		const reader = res.body.getReader();
 		const frames = createSseFrameReader();
+		const think = createThinkTagSplitter();
 		let done = false;
 		let usage;
 		const handleFrame = function* (data) {
@@ -736,10 +807,17 @@ var OpenAiCompatibleClient = class {
 				type: "thinking-delta",
 				delta: delta["reasoning_content"]
 			};
-			if (typeof delta["content"] === "string" && delta["content"] !== "") yield {
-				type: "text-delta",
-				delta: delta["content"]
-			};
+			if (typeof delta["content"] === "string" && delta["content"] !== "") {
+				const split = think.push(delta["content"]);
+				if (split.thinking !== "") yield {
+					type: "thinking-delta",
+					delta: split.thinking
+				};
+				if (split.text !== "") yield {
+					type: "text-delta",
+					delta: split.text
+				};
+			}
 			const toolDeltas = delta["tool_calls"];
 			for (const td of toolDeltas ?? []) {
 				const index = td.index ?? 0;
@@ -767,6 +845,15 @@ var OpenAiCompatibleClient = class {
 		} finally {
 			reader.releaseLock();
 		}
+		const tail = think.flush();
+		if (tail.thinking !== "") yield {
+			type: "thinking-delta",
+			delta: tail.thinking
+		};
+		if (tail.text !== "") yield {
+			type: "text-delta",
+			delta: tail.text
+		};
 		if (toolCallsByIndex.size > 0) yield {
 			type: "tool-calls",
 			toolCalls: [...toolCallsByIndex.entries()].sort(([a], [b]) => a - b).map(([index, acc]) => {
@@ -822,7 +909,7 @@ var OpenAiCompatibleClient = class {
 		}
 		if (!res.ok) {
 			const detail = await res.text().catch(() => "");
-			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`);
+			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`, { status: res.status });
 		}
 		return res;
 	}
@@ -854,15 +941,21 @@ var OpenAiCompatibleClient = class {
 					...parseError ? { argumentsParseError: parseError } : {}
 				};
 			});
-			const content = choice["content"];
-			const thinking = choice["reasoning_content"];
+			const raw = choice["content"];
+			const split = typeof raw === "string" ? splitThinkTags(raw) : {
+				text: "",
+				thinking: void 0
+			};
+			const content = split.text;
+			const declared = choice["reasoning_content"];
+			const thinking = typeof declared === "string" && declared !== "" ? declared : split.thinking;
 			const usageRaw = data.usage;
 			const usage = usageRaw && (typeof usageRaw["prompt_tokens"] === "number" || typeof usageRaw["completion_tokens"] === "number") ? {
 				inputTokens: typeof usageRaw["prompt_tokens"] === "number" ? usageRaw["prompt_tokens"] : 0,
 				outputTokens: typeof usageRaw["completion_tokens"] === "number" ? usageRaw["completion_tokens"] : 0
 			} : void 0;
 			return {
-				content: typeof content === "string" && content !== "" ? textParts(content) : void 0,
+				content: content !== "" ? textParts(content) : void 0,
 				toolCalls: toolCalls?.length ? toolCalls : void 0,
 				...typeof thinking === "string" && thinking !== "" ? { thinking } : {},
 				...usage ? { usage } : {},
@@ -1123,7 +1216,7 @@ var AnthropicClient = class {
 		}
 		if (!res.ok) {
 			const detail = await res.text().catch(() => "");
-			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`);
+			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`, { status: res.status });
 		}
 		return res;
 	}
@@ -1388,7 +1481,7 @@ var GoogleGenAiClient = class {
 		}
 		if (!res.ok) {
 			const detail = await res.text().catch(() => "");
-			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`);
+			throw new WebSkillError("LLM_REQUEST_FAILED", `LLM request failed with HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`, { status: res.status });
 		}
 		return res;
 	}
@@ -2469,6 +2562,12 @@ function sampleBehaviorRecords(records, limits = DEFAULT_USER_PROFILE_LIMITS) {
 * 最后一句是重点：不明说「没有工具」，模型会凭训练记忆自己编造 tool_call 标记。
 */
 const PLAIN_CHAT_SYSTEM_PROMPT = "You are a helpful assistant. Answer the user's question directly and concisely. You have no tools available; do not describe or simulate tool calls.";
+/**
+* 按需披露的系统提示（分册 19 / FR-19.7）。
+* 只在本 run 确实存在按需工具时追加——没有按需工具却说「有些工具没列出来」，
+* 是在教模型怀疑一个完整的工具表。
+*/
+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.";
 const READ_LINKED_DOCUMENT_TOOL_NAME = "read_linked_document";
 /**
 * 能直接给模型用的 MIME。其余一律拒绝并列出这份清单——
@@ -2476,14 +2575,15 @@ const READ_LINKED_DOCUMENT_TOOL_NAME = "read_linked_document";
 */
 const SUPPORTED_DOCUMENT_MIME = {
 	pdf: "application/pdf",
-	docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+	docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
 };
 /** 引擎侧固定流程（§2.3）用到的错误文案，集中一处便于判据引用 */
-const UNSUPPORTED_DOCUMENT_MESSAGE = `Only PDF (${SUPPORTED_DOCUMENT_MIME.pdf}), Word (${SUPPORTED_DOCUMENT_MIME.docx}) and plain text documents can be read.`;
+const UNSUPPORTED_DOCUMENT_MESSAGE = `Only PDF (${SUPPORTED_DOCUMENT_MIME.pdf}), Word (${SUPPORTED_DOCUMENT_MIME.docx}), Excel (${SUPPORTED_DOCUMENT_MIME.xlsx}) and plain text documents can be read.`;
 /**
 * 内建工具：读页面链接指向的文档。
 *
-* **始终注册**（只要宿主装配了 reader）：docx 与纯文本这条路对所有模型成立。
+* **始终注册**（只要宿主装配了 reader）：docx / xlsx 与纯文本这条路对所有模型成立。
 * PDF 目标在模型不支持文档时**取数后拒绝**，而不是入口就拦 ——
 * 入口拦会误伤 docx，它抽成文本后根本不需要文档能力。
 */
@@ -2506,6 +2606,10 @@ function toBase64(bytes) {
 	for (const byte of bytes) binary += String.fromCharCode(byte);
 	return btoa(binary);
 }
+/** `toBase64` 的逆；分片里的文档要交回抽取器时用（0.13.0 FR-22.3） */
+function fromBase64(data) {
+	return Uint8Array.from(atob(data), (char) => char.charCodeAt(0));
+}
 /** 结构化 trace 记录器；时钟与 id 工厂可注入（golden trace 用固定值保证确定性） */
 var TraceRecorder = class {
 	#runId;
@@ -2745,6 +2849,30 @@ function evaluateToolAccess(state, llmToolName) {
 	};
 }
 /**
+* 分册 19 诊断（FR-19.6）：某条模式在给定工具名集合里有没有命中过。
+* 与点名判定分开，是因为这里问的是「作者写的这条规则有没有意义」，不是「某个工具能不能进上下文」。
+*/
+function patternMatchesAnyTool(pattern, declaringSkill, llmToolNames, activated) {
+	for (const name of llmToolNames) if (matchesPattern(pattern, declaringSkill, name, canonicalToolName(name, activated))) return true;
+	return false;
+}
+/**
+* 分册 19 的点名判定：**有没有某个已激活技能显式声明了这个工具**。
+*
+* 与 `evaluateToolAccess` 回答的不是同一个问题（那个回答「允不允许调用」，
+* 这个回答「要不要写进上下文」），因此故意不复用它，两处关键差异：
+* 1. 无人声明 ⇒ 这里返回 **false**（没人点名），那里返回 true（不受限）；
+* 2. 不含一票否决——某个技能没写清单，不影响另一个技能点名成功。
+*/
+function isNamedByActivatedSkill(state, llmToolName) {
+	const canonical = canonicalToolName(llmToolName, state.activated);
+	for (const [skill, patterns] of state.skillAllowedTools) {
+		if (!state.activated.has(skill)) continue;
+		for (const pattern of patterns) if (matchesPattern(pattern, skill, llmToolName, canonical)) return true;
+	}
+	return false;
+}
+/**
 * 参数敏感标注关键字（分册 30 / FR-30.3）。
 *
 * 不用 `format: 'password'`：`format` 是 JSON Schema 的规范关键字，provider 侧
@@ -2818,6 +2946,30 @@ const LLM_TURN_CODES = /* @__PURE__ */ new Set([
 	"LLM_REQUEST_FAILED",
 	"TOOL_SCHEMA_UNAVAILABLE"
 ]);
+/**
+* 模型侧图片通道收得下的位图格式（三家 provider 的交集）。
+* SVG 是文本、`application/octet-stream` 是未知字节——两者编成 data URL 发出去，
+* 端点当场 400（LM Studio：`'url' field must be a base64 encoded image.`），
+* 页面里一个内联图标就能把整次 run 打死。这不是「预判模型能不能读」，
+* 是这些字节根本进不了图片分片。
+*/
+const MODEL_IMAGE_MIME_TYPES = /* @__PURE__ */ new Set([
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+]);
+/** 分片是不是 PDF；mime 允许带参数与大小写差异，与 FR-11.1 的判定同口径 */
+const isPdfPart = (part) => part.type === "file" && part.mimeType.split(";")[0]?.trim().toLowerCase() === SUPPORTED_DOCUMENT_MIME.pdf;
+/**
+* LLM 客户端在 HTTP 失败时放进 `details` 的状态码（FR-22.2）。
+* 判不出来返回 undefined——网络层异常没有状态码，回退对它没有意义。
+*/
+const httpStatusOf = (e) => {
+	if (!(e instanceof WebSkillError) || typeof e.details !== "object" || e.details === null) return void 0;
+	const status = e.details.status;
+	return typeof status === "number" ? status : void 0;
+};
 /** 交互终态（取消/超时）：从工具执行深处直接终止 run */
 var RunTerminated = class extends Error {
 	outcome;
@@ -2842,6 +2994,16 @@ const summarizeArgs = (args) => {
 	const json = JSON.stringify(args);
 	return json.length > 100 ? `${json.slice(0, 100)}…` : json;
 };
+/**
+* 图片分片投不出去时换成一条说明（与超预算文档同一处置），多张合并成一条——
+* 一个页面上十几个内联图标各报一遍会把工具结果淹掉。
+* 静默丢掉会让模型以为自己看过了；直接发出去则整次请求 400，一张图连累全程。
+*/
+const undeliverableImageNote = (parts, toolName) => {
+	const formats = [...new Set(parts.map((p) => p.type === "image" ? p.mimeType : ""))].join(", ");
+	return `${parts.length === 1 ? "1 image" : `${parts.length} images`} from "${toolName}" ${parts.length === 1 ? "was" : "were"} not attached: ${formats} cannot be sent as model image input, which accepts only ${[...MODEL_IMAGE_MIME_TYPES].join(", ")}. Rely on the surrounding text, or ask for a raster version.`;
+};
+const isDeliverableImage = (part) => part.type !== "image" || MODEL_IMAGE_MIME_TYPES.has(part.mimeType.split(";")[0]?.trim().toLowerCase() ?? "");
 /** 外部工具的 inputSchema 索引（分册 30）；run 开始与 resume 各重建一次 */
 function indexExternalToolSchemas(state, specs) {
 	state.externalToolSchemas.clear();
@@ -2972,6 +3134,9 @@ var AgentLoop = class {
 			activatedTools: /* @__PURE__ */ new Map(),
 			skillAllowedTools: /* @__PURE__ */ new Map(),
 			warnedDeniedTools: /* @__PURE__ */ new Set(),
+			externalToolSources: /* @__PURE__ */ new Map(),
+			withheldTools: /* @__PURE__ */ new Set(),
+			pdfFallbackDone: false,
 			integrityVerdicts: /* @__PURE__ */ new Map(),
 			toolTimeoutMs: this.#config.toolTimeoutMs,
 			now,
@@ -3024,7 +3189,19 @@ var AgentLoop = class {
 				trace.record("run.warning", { message: `External tool source "${source.kind}" failed to build a system prompt: ${messageOf(e)}` });
 			}
 		}
-		const systemPrompt = this.#config.toolCallingDisabled ? PLAIN_CHAT_SYSTEM_PROMPT : [route.systemPrompt, ...externalSystemPrompts].join("\n\n");
+		const hasOnDemand = !this.#config.toolCallingDisabled && externalSpecs.some((spec) => {
+			const source = state.externalToolSources.get(spec.name);
+			try {
+				return source?.disclosure?.(spec.name) === "on-demand";
+			} catch {
+				return false;
+			}
+		});
+		const systemPrompt = this.#config.toolCallingDisabled ? PLAIN_CHAT_SYSTEM_PROMPT : [
+			route.systemPrompt,
+			...externalSystemPrompts,
+			...hasOnDemand ? [ON_DEMAND_TOOLS_HINT] : []
+		].join("\n\n");
 		const profileMessage = await this.#userProfileMessage(state);
 		state.messages = [
 			{
@@ -3083,6 +3260,44 @@ var AgentLoop = class {
 		}
 		return false;
 	}
+	/**
+	* 分册 19 暴露点：外部工具本轮是否披露。
+	*
+	* 与 `#checkToolAccess` 是两个问题：那个回答「允不允许调用」，这个只回答「要不要写进上下文」。
+	* 未披露**不影响可执行性**——分发点不看它，模型硬调照样执行（FR-19.5）。
+	*/
+	#disclosed(state, llmToolName) {
+		const source = state.externalToolSources.get(llmToolName);
+		if (source?.disclosure === void 0) return true;
+		let level;
+		try {
+			level = source.disclosure(llmToolName);
+		} catch (e) {
+			state.trace.record("run.warning", { message: `External tool source "${source.kind}" failed to report a disclosure level for "${llmToolName}"; treating it as always disclosed: ${messageOf(e)}` });
+			return true;
+		}
+		if (level !== "on-demand") return true;
+		if (isNamedByActivatedSkill(state, llmToolName)) return true;
+		if (!state.withheldTools.has(llmToolName)) {
+			state.withheldTools.add(llmToolName);
+			state.trace.record("tool.withheld", {
+				message: `Tool "${llmToolName}" is disclosed on demand and was not requested by any activated skill`,
+				data: { name: llmToolName }
+			});
+		}
+		return false;
+	}
+	/**
+	* FR-19.6：技能声明的外部工具模式一个已知工具都没命中时告警。
+	* 端点名拼错是最常见的失误，而它的表现是「工具静静地不出现」——不告警就无从排查。
+	*/
+	#warnUnmatchedToolPatterns(state, skillName, patterns) {
+		for (const pattern of patterns) {
+			if (!pattern.includes(":") && !pattern.includes("#")) continue;
+			if (patternMatchesAnyTool(pattern, skillName, state.externalToolSources.keys(), state.activated)) continue;
+			state.trace.record("run.warning", { message: `Skill "${skillName}" declares allowed-tools pattern "${pattern}", but it matches no known tool.` });
+		}
+	}
 	/** 分发点被拒时回喂给模型的结构化错误（不抛异常：模型造名字是常态，抛异常会终止整个 run） */
 	#deniedToolError(state, toolName) {
 		return toolError("TOOL_NOT_ALLOWED", evaluateToolAccess(state, toolName).reason ?? `Tool "${toolName}" is not allowed`);
@@ -3098,7 +3313,9 @@ var AgentLoop = class {
 				state.turn = turn;
 				if (turn > state.maxTurns) return finish("failed", "max-turns", `Agent loop exceeded the maximum of ${state.maxTurns} turns`, "RUN_MAX_TURNS_EXCEEDED");
 				if (this.#elapsed(state) > state.totalTimeoutMs) return finish("failed", "timeout", `Agent loop exceeded the total timeout of ${state.totalTimeoutMs}ms`, "RUN_TIMEOUT");
-				const skillToolSpecs = [...[...state.activatedTools.values()].map(toLlmToolSpec), ...externalSpecs].filter((spec) => this.#checkToolAccess(state, spec.name));
+				const scriptToolSpecs = [...state.activatedTools.values()].map(toLlmToolSpec).filter((spec) => this.#checkToolAccess(state, spec.name));
+				const externalToolSpecs = externalSpecs.filter((spec) => this.#disclosed(state, spec.name));
+				const skillToolSpecs = [...scriptToolSpecs, ...externalToolSpecs];
 				const toolSpecs = this.#config.toolCallingDisabled ? [] : [
 					toLlmToolSpec(READ_SKILL_FILE_TOOL),
 					...this.#deps.uiBridge ? [toLlmToolSpec(ASK_USER_TOOL)] : [],
@@ -3130,8 +3347,12 @@ var AgentLoop = class {
 						if (this.#cancelled.has(state.runId)) return finish("cancelled", "user-cancelled", "Run cancelled by user", "RUN_CANCELLED");
 						return finish("failed", "timeout", `Agent loop exceeded the total timeout of ${state.totalTimeoutMs}ms`, "RUN_TIMEOUT");
 					}
+					if (await this.#fallbackPdfToText(state, e)) {
+						turn--;
+						continue;
+					}
 					const code = e instanceof WebSkillError && LLM_TURN_CODES.has(e.code) ? e.code : "LLM_REQUEST_FAILED";
-					const hint = messages.some((message) => Array.isArray(message.content) && message.content.some((part) => part.type === "file")) ? " This turn attached a document; the selected model may not accept document input. Try another model, or link a Word or text file instead." : "";
+					const hint = state.pdfFallbackDone ? " The attached PDF was re-sent as extracted text after the endpoint rejected the original file, and that attempt failed as well." : messages.some((message) => message.content.some(isPdfPart)) ? " This turn attached a document; the selected model may not accept document input. Try another model, or link a Word or text file instead." : "";
 					return finish("failed", "llm-error", `${messageOf(e)}${hint}`, code);
 				}
 				if (response.thinking !== void 0 && response.thinking !== "") {
@@ -3364,6 +3585,9 @@ var AgentLoop = class {
 			activatedTools: new Map(snapshot.activatedTools.map((d) => [d.name, d])),
 			skillAllowedTools: new Map(Object.entries(snapshot.skillAllowedTools ?? {})),
 			warnedDeniedTools: /* @__PURE__ */ new Set(),
+			externalToolSources: /* @__PURE__ */ new Map(),
+			withheldTools: /* @__PURE__ */ new Set(),
+			pdfFallbackDone: false,
 			integrityVerdicts: /* @__PURE__ */ new Map(),
 			toolTimeoutMs: snapshot.config.toolTimeoutMs,
 			now,
@@ -3686,9 +3910,12 @@ var AgentLoop = class {
 	}
 	/** 外部工具 specs：单个来源失败跳过并记 warning（run 开始与 resume 共用） */
 	async #collectExternalSpecs(state) {
+		state.externalToolSources.clear();
 		return (await Promise.all((this.#deps.externalTools ?? []).map(async (source) => {
 			try {
-				return await source.listToolSpecs();
+				const specs = await source.listToolSpecs();
+				for (const spec of specs) state.externalToolSources.set(spec.name, source);
+				return specs;
 			} catch (e) {
 				state.trace.record("run.warning", { message: `External tool source "${source.kind}" failed to list specs: ${messageOf(e)}` });
 				return [];
@@ -3776,17 +4003,15 @@ var AgentLoop = class {
 		else if (call.name === "read_skill_file") result = await this.#handleReadSkillFile(call, state);
 		else if (call.name === "ask_user") result = await this.#handleAskUser(call, state);
 		else if (call.name === "read_linked_document" && this.#deps.linkedDocuments !== void 0) result = await this.#handleReadLinkedDocument(call, state);
-		else if (!this.#checkToolAccess(state, call.name)) result = this.#deniedToolError(state, call.name);
 		else {
 			const resolution = resolveToolName(call.name, state.activated, state.activatedTools.keys());
-			if (resolution.kind === "script") result = await this.#handleScriptTool(call, resolution.skillName, resolution.scriptName, state);
+			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);
 			else {
-				const source = (this.#deps.externalTools ?? []).find((s) => s.canHandle(call.name));
-				if (source) result = await source.call(call.name, call.arguments);
-				else {
-					if (resolution.kind === "not-found") state.unknownToolCalls += 1;
-					result = toolError(resolution.code, resolution.message, resolution.kind === "not-found" ? resolution.data : void 0);
-				}
+				if (resolution.kind === "not-found") state.unknownToolCalls += 1;
+				result = toolError(resolution.code, resolution.message, resolution.kind === "not-found" ? resolution.data : void 0);
 			}
 		}
 		const durationMs = Date.parse(state.now()) - callStartMs;
@@ -4177,17 +4402,20 @@ var AgentLoop = class {
 			};
 		}
 		let text;
-		if (mime === SUPPORTED_DOCUMENT_MIME.docx) {
-			if (this.#deps.docxExtractor === void 0) {
+		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) {
 				await audit({
 					...record,
 					ok: false,
-					reason: "no docx extractor"
+					reason: `no ${kind} extractor`
 				});
-				return toolError("TOOL_UNSUPPORTED", "Word documents cannot be read in this environment: no docx text extractor is configured.");
+				return toolError("TOOL_UNSUPPORTED", `${docx ? "Word documents" : "Excel workbooks"} cannot be read in this environment: no ${kind} text extractor is configured.`);
 			}
 			try {
-				text = await this.#deps.docxExtractor(fetched.bytes);
+				text = await extractor(fetched.bytes);
 			} catch (e) {
 				const message = messageOf(e);
 				await audit({
@@ -4398,6 +4626,57 @@ var AgentLoop = class {
 		return toolError("SKILL_NOT_FOUND", `Skill not found via external providers: ${skillKey}${detail}`);
 	}
 	/**
+	* 端点拒收 PDF 后，把消息里的 PDF 分片换成抽取文本，让本轮可以重发（FR-22.2 / FR-22.3）。
+	* 返回 true 表示已改写、调用方应重试本轮；返回 false 表示走原有失败路径。
+	*/
+	async #fallbackPdfToText(state, cause) {
+		const extract = this.#deps.pdfExtractor;
+		if (extract === void 0 || state.pdfFallbackDone) return false;
+		const status = httpStatusOf(cause);
+		if (status === void 0 || status < 400 || status >= 500) return false;
+		if (!state.messages.some((message) => message.content.some(isPdfPart))) return false;
+		state.pdfFallbackDone = true;
+		let converted = 0;
+		for (const message of state.messages) for (let i = 0; i < message.content.length; i++) {
+			const part = message.content[i];
+			if (part === void 0 || !isPdfPart(part)) continue;
+			message.content[i] = {
+				type: "text",
+				text: await this.#pdfAsText(state, part, extract)
+			};
+			converted++;
+		}
+		state.trace.record("run.warning", {
+			message: `The endpoint rejected ${converted} attached PDF file(s) with HTTP ${status}; they were replaced with extracted text and the turn was retried. Original error: ${messageOf(cause)}`,
+			data: {
+				converted,
+				status
+			}
+		});
+		return converted > 0;
+	}
+	/** 单个 PDF 分片 → 文本；包装形态与 chatEngine 的附件标签同口径（FR-22.3 / FR-22.4） */
+	async #pdfAsText(state, part, extract) {
+		const name = part.name ?? "document.pdf";
+		const label = (note) => `--- Attachment: ${name} (${SUPPORTED_DOCUMENT_MIME.pdf}, ${note}) ---\n`;
+		let text;
+		try {
+			text = await extract(fromBase64(part.data));
+		} catch (e) {
+			return `${label("text extraction failed")}${messageOf(e)}`;
+		}
+		if (text.trim() === "") return `${label("no extractable text")}This PDF has no text layer, so its contents could not be extracted. It is most likely a scan or an image-only export. Tell the user this instead of guessing what it contains.`;
+		const id = `doc-${state.runId}-${++state.documentSeq}`;
+		const tooLarge = this.#documentTooLarge({
+			type: "document-text",
+			text,
+			name,
+			id
+		});
+		if (tooLarge !== void 0) return `${label("not attached")}${tooLarge}`;
+		return `${label("extracted text")}${text}`;
+	}
+	/**
 	* 超预算的文档分片换成一条说明（FR-23.4）。**不截断**：
 	* 半份 PDF 是坏文件，半份抽取文本会让模型以为自己读全了。
 	*/
@@ -4441,6 +4720,7 @@ var AgentLoop = class {
 		};
 		const notes = [];
 		const carried = [];
+		const undeliverable = [];
 		for (const part of passthrough) {
 			const tooLarge = this.#documentTooLarge(part);
 			if (tooLarge) {
@@ -4448,6 +4728,10 @@ var AgentLoop = class {
 				notes.push(tooLarge);
 				continue;
 			}
+			if (!isDeliverableImage(part)) {
+				undeliverable.push(part);
+				continue;
+			}
 			if (part.type === "image") carried.push({
 				type: "image",
 				mimeType: part.mimeType,
@@ -4461,6 +4745,11 @@ var AgentLoop = class {
 			});
 			else if (part.type === "document-text") notes.push(part.text);
 		}
+		if (undeliverable.length > 0) {
+			const note = undeliverableImageNote(undeliverable, call.name);
+			state.trace.record("run.warning", { message: note });
+			notes.push(note);
+		}
 		return {
 			tool: [
 				{
@@ -4577,6 +4866,7 @@ var AgentLoop = class {
 			if (rawAllowed !== void 0) if (Array.isArray(rawAllowed)) {
 				allowedTools = rawAllowed.filter((e) => typeof e === "string");
 				state.skillAllowedTools.set(skillName, allowedTools);
+				this.#warnUnmatchedToolPatterns(state, skillName, allowedTools);
 			} else state.trace.record("run.warning", { message: `Skill "${skillName}" has a non-array "allowed-tools" metadata entry; ignored` });
 		} catch (e) {
 			state.trace.record("run.warning", { message: `Failed to read or parse SKILL.md of skill "${skillName}": ${messageOf(e)}` });
@@ -5140,6 +5430,8 @@ var WebSkillRuntime = class {
 			fetchData: this.#deps.fetchData,
 			linkedDocuments: this.#deps.linkedDocuments,
 			docxExtractor: this.#deps.docxExtractor,
+			xlsxExtractor: this.#deps.xlsxExtractor,
+			pdfExtractor: this.#deps.pdfExtractor,
 			documentAudit: this.#deps.documentAudit
 		}, this.#deps.config);
 		const runId = `run-${Math.random().toString(36).slice(2, 10)}`;
@@ -5266,6 +5558,8 @@ var WebSkillRuntime = class {
 			fetchData: this.#deps.fetchData,
 			linkedDocuments: this.#deps.linkedDocuments,
 			docxExtractor: this.#deps.docxExtractor,
+			xlsxExtractor: this.#deps.xlsxExtractor,
+			pdfExtractor: this.#deps.pdfExtractor,
 			documentAudit: this.#deps.documentAudit
 		}, this.#deps.config);
 		this.#loops.set(runId, loop);

package/dist/{dist-DU9KDAuR.js → dist-GK6dtjRv.js}

@@ -1,5 +1,5 @@
 import { M as messageOf, P as parseSkillMarkdown, g as assertRemoteUrlAllowed, h as WebSkillError, k as isValidSkillName } from "./dist-Bev6i6Ip.js";
-import { f as DEFAULT_MAX_DATA_SOURCE_BYTES } from "./dist-sdKFgERo.js";
+import { f as DEFAULT_MAX_DATA_SOURCE_BYTES } from "./dist-ExSQky4C.js";
 
 //#region ../agent/dist/index.js
 const STATUSES = [
@@ -875,6 +875,30 @@ function withDelegationOrigin(bridge, origin) {
 	};
 }
 /**
+* 帧指称的展示形式（分册 18 FR-18.2）。
+*
+* 感知与操作两侧各自声明自己的 scope 类型（那是刻意的，见各自 types.ts），
+* 但「一条帧路径写成给人看的字符串」只能有一份实现——
+* 两处各写一遍，审计里的帧名和确认卡里的帧名就会慢慢对不上。
+*/
+/**
+* 帧路径的稳定展示串：`'self'` / `'#a'` / `'#a >>> #b'`。
+*
+* `>>>` **只是展示分隔符**：CSS 选择器里可以合法出现任意字符，
+* 反向解析这个串取回路径是不成立的，实现层一律传原始形状（D-18-1）。
+* @experimental
+*/
+function frameLabel(frame) {
+	if (typeof frame === "string") return frame;
+	if (frame.length === 0) return "self";
+	return frame.join(" >>> ");
+}
+/** 把两种形状归一成逐层选择器数组；`'self'` 与空数组都归一成空数组 @experimental */
+function frameSteps(frame) {
+	if (typeof frame === "string") return frame === "self" ? [] : [frame];
+	return frame;
+}
+/**
 * 两种形状归一成帧列表；旧形状等价于一条 `frame:'self'`（FR-24.1）。
 *
 * **这是判别的单一来源。** 散在各处写 `'frames' in scope` 会让
@@ -937,7 +961,7 @@ var PagePerceptionPolicy = class {
 			at: this.#options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
 			include: frames.flatMap((frame) => [...frame.include]),
 			exclude: frames.flatMap((frame) => [...frame.exclude ?? []]),
-			...frames.length > 1 || frames[0]?.frame !== "self" ? { frames: frames.map((frame) => frame.frame) } : {},
+			...frames.length > 1 || frames[0] !== void 0 && frameLabel(frames[0].frame) !== "self" ? { frames: frames.map((frame) => frameLabel(frame.frame)) } : {},
 			nodeCount: nodes.length,
 			...capture?.images === true ? {
 				images: {
@@ -1035,7 +1059,8 @@ function createPagePerceptionToolSource(options) {
 				const capture = {
 					images: budget?.enabled === true,
 					maxImageBytes: budget?.maxImageBytes ?? 0,
-					maxImages: budget?.maxImages ?? 0
+					maxImages: budget?.maxImages ?? 0,
+					minImageArea: budget?.minImageArea ?? 0
 				};
 				const { nodes, images, imagesOmitted, record } = await policy.perceive(capture);
 				const data = {
@@ -1465,4 +1490,4 @@ function createPageActionToolSource(options) {
 }
 
 //#endregion
-export { createTodoToolSource as C, withDelegationOrigin as E, createSkillGenerationToolSource as S, toFrameScopes as T, TodoStore as _, GENERATE_SKILL_TOOL as a, createPageActionToolSource as b, PAGE_ACTION_SYSTEM_PROMPT as c, PERCEPTION_SYSTEM_PROMPT as d, PageActionPolicy as f, TODO_SYSTEM_PROMPT as g, SkillGenerator as h, DelegationOrchestrator as i, PAGE_ACTION_TOOL as l, SKILL_GENERATION_SYSTEM_PROMPT as m, DELEGATION_SYSTEM_PROMPT as n, MANAGE_TODO_TOOL as o, PagePerceptionPolicy as p, DataSourcePolicy as r, PAGE_ACTION_KINDS as s, DELEGATE_TASK_TOOL as t, PERCEIVE_PAGE_TOOL as u, createDelegationToolSource as v, toActionFrameScopes as w, createPagePerceptionToolSource as x, createHttpDataSourceTransport as y };
+export { createTodoToolSource as C, toFrameScopes as D, toActionFrameScopes as E, withDelegationOrigin as O, createSkillGenerationToolSource as S, frameSteps as T, TodoStore as _, GENERATE_SKILL_TOOL as a, createPageActionToolSource as b, PAGE_ACTION_SYSTEM_PROMPT as c, PERCEPTION_SYSTEM_PROMPT as d, PageActionPolicy as f, TODO_SYSTEM_PROMPT as g, SkillGenerator as h, DelegationOrchestrator as i, PAGE_ACTION_TOOL as l, SKILL_GENERATION_SYSTEM_PROMPT as m, DELEGATION_SYSTEM_PROMPT as n, MANAGE_TODO_TOOL as o, PagePerceptionPolicy as p, DataSourcePolicy as r, PAGE_ACTION_KINDS as s, DELEGATE_TASK_TOOL as t, PERCEIVE_PAGE_TOOL as u, createDelegationToolSource as v, frameLabel as w, createPagePerceptionToolSource as x, createHttpDataSourceTransport as y };

package/dist/governance.d.ts

@@ -1,5 +1,5 @@
 import { R as FileSystemProvider, S as UiBridge, U as Page, W as PageQuery, f as LlmMessage, it as SkillCatalogEntry, l as LlmClient, ot as SkillDocument, ut as SkillManagerPort } from "./types-DLctJep_-B5G4uk2u.js";
-import { Nt as RuntimeRun, Pn as WebSkillRuntime, Qt as SkillOutcomeReporter, Y as IntegrityVerdict, Zt as SkillIntegrityGuard, nn as SkillStateGuard } from "./index-C9pzXLKy.js";
+import { $t as SkillOutcomeReporter, In as WebSkillRuntime, Pt as RuntimeRun, Qt as SkillIntegrityGuard, Y as IntegrityVerdict, rn as SkillStateGuard } from "./index-DkvBhJQy.js";
 import { _ as SkillState, a as AuditLog, b as SkillVersionStore, c as CandidateFile, d as CandidateSkill, f as CandidateSource, g as SKILL_VERSION_PAGE_SIZE, h as CompositeApprovalPolicy, i as AuditEvent, l as CandidatePage, m as CandidateStore, n as ApprovalDecision, o as AuditQueryFilter, p as CandidateStatus, r as ApprovalPolicy, s as CANDIDATE_PAGE_SIZE, t as AlwaysHumanApprovalPolicy, u as CandidateRisk, v as SkillVersion, x as candidateToCatalogEntry, y as SkillVersionPage } from "./skillVersionStore-D-qHk9ZE-DheTIwAB.js";
 //#region ../governance/dist/index.d.ts
 //#region src/candidate/candidateNormalizer.d.ts

package/dist/{index-3fCHc1mQ.d.ts → index-C3XdItd_.d.ts}

@@ -1,5 +1,5 @@
 import { B as JsonSchema, C as UiSpecActionCapability, D as UiSpecSnapshot, S as UiBridge, b as RenderResultRequest, bt as UiSpecNode, c as InteractionResponse, r as ChartSpec, s as InteractionRequest, y as RenderBlock } from "./types-DLctJep_-B5G4uk2u.js";
-import { F as ExternalToolSource } from "./index-C9pzXLKy.js";
+import { F as ExternalToolSource } from "./index-DkvBhJQy.js";
 import { z } from "zod";
 import { ComponentType, ReactNode } from "react";
 //#region ../ui/dist/index.d.ts