@webskill/sdk 0.12.0 → 0.14.0

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

@@ -1,5 +1,5 @@
-import { K as validateSkills, M as messageOf, P as parseSkillMarkdown, R as renderAvailableSkillsXml, V as resolveInsideRoot, _ as assertSafePathSegment, g as assertRemoteUrlAllowed, h as WebSkillError, m as SkillReader, p as SkillDiscovery, v as atomicWriteText, y as buildCatalog } from "./dist-Bev6i6Ip.js";
-import { a as textParts, i as rejectUnsupportedPart, n as partsToText, o as validateLlmMessages, r as promptText, t as MemoryArtifactStore } from "./memoryArtifactStore-52Zn9npI-LbCQaqyx.js";
+import { B as messageOf, C as assertSafePathSegment, H as parseSkillMarkdown, K as renderAvailableSkillsXml, S as assertRemoteUrlAllowed, T as buildCatalog, Y as resolveInsideRoot, _ as SkillDiscovery, b as WebSkillError, et as validateSkills, v as SkillReader, w as atomicWriteText } from "./dist-D5YhlCdY.js";
+import { a as textParts, i as rejectUnsupportedPart, n as partsToText, o as validateLlmMessages, r as promptText, t as MemoryArtifactStore } from "./memoryArtifactStore-52Zn9npI-BxtUkrgV.js";
 
 //#region ../runtime/dist/index.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,41 @@ 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"
+]);
+/**
+* 数据源清单里的出处标注（0.14.0 分册 21，FR-21.6）。
+*
+* 措辞必须说出「这段说明来自页面、可能不准确」：`description` 已在候选层剥掉换行与控制字符，
+* 它无法把自己伪装成上下文里的新一行指令——**剥换行与这句标注是一对，只做一件都不够**。
+*/
+const DATA_SOURCE_PROVENANCE_NOTE = {
+	"": "",
+	"page-declared": "  [declared by the current site; this description comes from the page and may be inaccurate]",
+	"tool-projection": "  [projected from a tool the current site registered; this description comes from the page and may be inaccurate]"
+};
+/** 分片是不是 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 +3005,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 +3145,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 +3200,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 +3271,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 +3324,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 +3358,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 +3596,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 +3921,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 +4014,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, { runId: state.runId });
 			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 +4413,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 +4637,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 +4731,7 @@ var AgentLoop = class {
 		};
 		const notes = [];
 		const carried = [];
+		const undeliverable = [];
 		for (const part of passthrough) {
 			const tooLarge = this.#documentTooLarge(part);
 			if (tooLarge) {
@@ -4448,6 +4739,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 +4756,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: [
 				{
@@ -4500,7 +4800,9 @@ var AgentLoop = class {
 		}
 		const head = text.slice(0, Math.floor(max * .6));
 		const tail = text.slice(-Math.floor(max * .3));
-		return `${head}\n...[truncated ${text.length - head.length - tail.length} chars; ${note}]...\n${tail}`;
+		const omitted = text.length - head.length - tail.length;
+		state.trace.record("run.warning", { message: `Tool result for "${call.name}" exceeded ${String(max)} chars and was truncated in the middle; ${String(omitted)} chars omitted (${note}).` });
+		return `${head}\n...[truncated ${omitted} chars; ${note}]...\n${tail}`;
 	}
 	/** SkillStateGuard 判定（无注入默认全放行；仅显式 false 拦截） */
 	async #guardDenied(kind, skillName) {
@@ -4569,6 +4871,7 @@ var AgentLoop = class {
 		if (!root) return "";
 		let allowedTools;
 		let dependencies = [];
+		let declaredSources = [];
 		try {
 			const { metadata } = parseSkillMarkdown(skillMdText ?? await this.#deps.fs.readText(`${root}/SKILL.md`));
 			const rawDeps = metadata["dependencies"];
@@ -4577,7 +4880,11 @@ 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` });
+			const rawSources = metadata["data-sources"];
+			if (rawSources !== void 0) if (Array.isArray(rawSources)) declaredSources = rawSources.filter((e) => typeof e === "string");
+			else state.trace.record("run.warning", { message: `Skill "${skillName}" has a non-array "data-sources" metadata entry; ignored` });
 		} catch (e) {
 			state.trace.record("run.warning", { message: `Failed to read or parse SKILL.md of skill "${skillName}": ${messageOf(e)}` });
 		}
@@ -4613,6 +4920,7 @@ var AgentLoop = class {
 			}
 		}
 		let note = (loaded.length ? `\n\nActivated tools: ${loaded.join(", ")}` : "") + formatSkillScriptManifest(scripts);
+		note += this.#dataSourceNotice(skillName, declaredSources, state);
 		for (const dep of dependencies) {
 			if (state.activated.has(dep)) continue;
 			if (!this.#deps.skillIndex.has(dep)) {
@@ -4624,6 +4932,26 @@ var AgentLoop = class {
 		return note;
 	}
 	/**
+	* 0.14.0 分册 19：技能声明的源在本宿主缺失时，把「缺哪些 / 有哪些」写进激活回执与 trace。
+	* 宿主没注入清单时一个字不说——那是「未知」，不是「没有」。
+	*
+	* 0.14.0 分册 21（DV-7）：「有哪些」由 id 列表升级为 `<id> — <description>`，
+	* 并对非宿主声明的条目附出处标注。`description` 可能来自页面，
+	* 因此标注必须与它同时出现——只写说明不写出处，等于让站点以宿主口吻讲话。
+	*/
+	#dataSourceNotice(skillName, declared, state) {
+		const declaredSources = this.#deps.dataSources;
+		const available = typeof declaredSources === "function" ? declaredSources() : declaredSources;
+		if (declared.length === 0 || available === void 0) return "";
+		const have = new Set(available.map((source) => source.id));
+		const missing = declared.filter((id) => !have.has(id));
+		if (missing.length === 0) return "";
+		const listed = available.map((source) => `\n- ${source.id} — ${source.description}${DATA_SOURCE_PROVENANCE_NOTE[source.provenance ?? ""] ?? ""}`).join("");
+		const message = `Skill "${skillName}" declares data source(s) this host does not provide: ${missing.join(", ")}. Available here:${listed || " (none)"}\nDo not retry them or invent their values; tell the user which data source is missing.`;
+		state.trace.record("run.warning", { message });
+		return `\n\n${message}`;
+	}
+	/**
 	* D2 Schema 兜底链（同一 run 内激活时只算一次）：
 	* 显式 inputSchema > sidecar scripts/<name>.schema.json > schemaInferer 推导 > schemaUnavailable
 	* 返回值即最终来源，进技能清单告诉模型该信谁（FR-18.1）。
@@ -5138,8 +5466,11 @@ var WebSkillRuntime = class {
 			skillIntegrityGuard: this.#deps.skillIntegrityGuard,
 			skillOutcomeReporter: this.#deps.skillOutcomeReporter,
 			fetchData: this.#deps.fetchData,
+			dataSources: this.#deps.dataSources,
 			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)}`;
@@ -5264,8 +5595,11 @@ var WebSkillRuntime = class {
 			skillIntegrityGuard: this.#deps.skillIntegrityGuard,
 			skillOutcomeReporter: this.#deps.skillOutcomeReporter,
 			fetchData: this.#deps.fetchData,
+			dataSources: this.#deps.dataSources,
 			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);
@@ -6544,4 +6878,4 @@ var FsToolStepStore = class {
 };
 
 //#endregion
-export { bridgeError as $, ProgressiveRouter as A, refineUserProfile as At, SUPPORTED_DOCUMENT_MIME as B, toLlmToolSpec as Bt, FsSessionStore as C, normalizeToolError as Ct, HookRunner as D, readProfileEntries as Dt, GoogleGenAiClient as E, readBehaviorRecords as Et, READ_SKILL_FILE_TOOL_NAME as F, schemaToForm as Ft, USER_PROFILE_EXPORT_VERSION as G, TEXT_BUDGETED_CONTENT_TYPES as H, toVercelToolSpecs as Ht, RUN_SNAPSHOT_SCHEMA_VERSION as I, scriptToolName as It, USER_PROFILE_PROMPT_HEADER as J, USER_PROFILE_KEY as K, RUN_TRACE_SCHEMA_VERSION as L, sealToolCallPairs as Lt, READ_LINKED_DOCUMENT_TOOL_NAME as M, resolveToolName as Mt, READ_SKILL_FILE_INPUT_SCHEMA as N, sampleBehaviorRecords as Nt, MAX_TOOL_STEP_ARG_BYTES as O, readUserProfile as Ot, READ_SKILL_FILE_TOOL as P, schemaSourceLabel as Pt, applyUserProfileImport as Q, SENSITIVE_ANNOTATION as R, summarizeRunUsage as Rt, FsRunTraceStore as S, normalizeToolContent as St, FullDisclosureRouter as T, parseUserProfileExport as Tt, TraceRecorder as U, validateUiSpecEvent as Ut, SerializingMemoryStore as V, toRecordDigests as Vt, UNSUPPORTED_DOCUMENT_MESSAGE as W, validateUiSpecNode as Wt, WebSkillRuntime as X, USER_PROFILE_REFINE_PROMPT as Y, appendBehaviorRecords as Z, EventBus as _, mergeCatalogEntries as _t, ASK_USER_TOOL as a, extractChartSpec as at, FsMemoryStore as b, networkUrlHost as bt, AnthropicClient as c, extractUiSpecEvents as ct, DEFAULT_LOOP_LIMITS as d, fromVercelResult as dt, buildRenderResult as et, DEFAULT_MAX_DATA_SOURCE_BYTES as f, fromVercelStreamPart as ft, EMPTY_USER_PROFILE as g, listSkillScripts as gt, DEFAULT_USER_PROFILE_LIMITS as h, isUnsupportedRunSnapshot as ht, ASK_USER_MAX_FIELDS as i, exportUserProfile as it, READ_LINKED_DOCUMENT_TOOL as j, renderUserProfileContext as jt, OpenAiCompatibleClient as k, redactToolStepArgs as kt, BEHAVIOR_RECORDS_KEY as l, findUnpairedToolCalls as lt, DEFAULT_MAX_DOCUMENT_TEXT_BYTES as m, isNetworkAllowed as mt, ASK_USER_FIELD_TYPES as n, createWebSkillApi as nt, ASK_USER_TOOL_NAME as o, extractSkillCandidate as ot, DEFAULT_MAX_DOCUMENT_BYTES as p, interruptedToolResult as pt, USER_PROFILE_NO_INVENTION_RULE as q, ASK_USER_INPUT_SCHEMA as r, diffUserProfile as rt, AgentLoop as s, extractTodoTraceEvents as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, createScriptContext as tt, CapabilityApproval as u, formatSkillScriptManifest as ut, FS_SESSION_PAGE_SIZE as v, mergeProfileEntries as vt, FsToolStepStore as w, parseBridgeRequest as wt, FsRunSnapshotStore as x, normalizeErrorCode as xt, FsArtifactStore as y, networkPolicyLibSource as yt, SESSION_SCHEMA_VERSION as z, summarizeToolCalls as zt };
+export { bridgeError as $, ProgressiveRouter as A, refineUserProfile as At, SUPPORTED_DOCUMENT_MIME as B, toBase64 as Bt, FsSessionStore as C, normalizeToolError as Ct, HookRunner as D, readProfileEntries as Dt, GoogleGenAiClient as E, readBehaviorRecords as Et, READ_SKILL_FILE_TOOL_NAME as F, schemaToForm as Ft, USER_PROFILE_EXPORT_VERSION as G, validateUiSpecNode as Gt, TEXT_BUDGETED_CONTENT_TYPES as H, toRecordDigests as Ht, RUN_SNAPSHOT_SCHEMA_VERSION as I, scriptToolName as It, USER_PROFILE_PROMPT_HEADER as J, USER_PROFILE_KEY as K, RUN_TRACE_SCHEMA_VERSION as L, sealToolCallPairs as Lt, READ_LINKED_DOCUMENT_TOOL_NAME as M, resolveToolName as Mt, READ_SKILL_FILE_INPUT_SCHEMA as N, sampleBehaviorRecords as Nt, MAX_TOOL_STEP_ARG_BYTES as O, readUserProfile as Ot, READ_SKILL_FILE_TOOL as P, schemaSourceLabel as Pt, applyUserProfileImport as Q, SENSITIVE_ANNOTATION as R, summarizeRunUsage as Rt, FsRunTraceStore as S, normalizeToolContent as St, FullDisclosureRouter as T, parseUserProfileExport as Tt, TraceRecorder as U, toVercelToolSpecs as Ut, SerializingMemoryStore as V, toLlmToolSpec as Vt, UNSUPPORTED_DOCUMENT_MESSAGE as W, validateUiSpecEvent as Wt, WebSkillRuntime as X, USER_PROFILE_REFINE_PROMPT as Y, appendBehaviorRecords as Z, EventBus as _, mergeCatalogEntries as _t, ASK_USER_TOOL as a, extractChartSpec as at, FsMemoryStore as b, networkUrlHost as bt, AnthropicClient as c, extractUiSpecEvents as ct, DEFAULT_LOOP_LIMITS as d, fromVercelResult as dt, buildRenderResult as et, DEFAULT_MAX_DATA_SOURCE_BYTES as f, fromVercelStreamPart as ft, EMPTY_USER_PROFILE as g, listSkillScripts as gt, DEFAULT_USER_PROFILE_LIMITS as h, isUnsupportedRunSnapshot as ht, ASK_USER_MAX_FIELDS as i, exportUserProfile as it, READ_LINKED_DOCUMENT_TOOL as j, renderUserProfileContext as jt, OpenAiCompatibleClient as k, redactToolStepArgs as kt, BEHAVIOR_RECORDS_KEY as l, findUnpairedToolCalls as lt, DEFAULT_MAX_DOCUMENT_TEXT_BYTES as m, isNetworkAllowed as mt, ASK_USER_FIELD_TYPES as n, createWebSkillApi as nt, ASK_USER_TOOL_NAME as o, extractSkillCandidate as ot, DEFAULT_MAX_DOCUMENT_BYTES as p, interruptedToolResult as pt, USER_PROFILE_NO_INVENTION_RULE as q, ASK_USER_INPUT_SCHEMA as r, diffUserProfile as rt, AgentLoop as s, extractTodoTraceEvents as st, ALLOWED_TOOLS_EXCLUSION_REASON as t, createScriptContext as tt, CapabilityApproval as u, formatSkillScriptManifest as ut, FS_SESSION_PAGE_SIZE as v, mergeProfileEntries as vt, FsToolStepStore as w, parseBridgeRequest as wt, FsRunSnapshotStore as x, normalizeErrorCode as xt, FsArtifactStore as y, networkPolicyLibSource as yt, SESSION_SCHEMA_VERSION as z, summarizeToolCalls as zt };