@webskill/sdk 0.2.8 → 0.4.0

package/dist/{dist-B9VLwOME.js → dist-C-Sh0MDU.js}

@@ -1,28 +1,111 @@
-import { C as messageOf, N as validateSkills, O as renderAvailableSkillsXml, T as parseSkillMarkdown, c as SkillDiscovery, f as assertSafePathSegment, j as resolveInsideRoot, l as SkillReader, m as buildCatalog, u as WebSkillError } from "./dist-BQzncxXg.js";
-import { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.js";
+import { A as parseSkillMarkdown, L as resolveInsideRoot, O as messageOf, P as renderAvailableSkillsXml, V as validateSkills, f as SkillDiscovery, g as assertSafePathSegment, m as WebSkillError, p as SkillReader, v as buildCatalog } from "./dist-8oQRa8Xz.js";
+import { a as validateLlmMessages, i as textParts, n as partsToText, r as rejectUnsupportedPart, t as MemoryArtifactStore } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
 
 //#region ../runtime/dist/index.js
+function createSseFrameReader() {
+	let buffer = "";
+	let data = [];
+	const dispatch = (out) => {
+		if (data.length === 0) return;
+		out.push(data.join("\n"));
+		data = [];
+	};
+	const consumeLine = (line, out) => {
+		if (line === "") {
+			dispatch(out);
+			return;
+		}
+		if (line.startsWith(":")) return;
+		const colon = line.indexOf(":");
+		if (colon < 0) return;
+		if (line.slice(0, colon) !== "data") return;
+		const value = line.slice(colon + 1);
+		data.push(value.startsWith(" ") ? value.slice(1) : value);
+	};
+	return {
+		push(chunk) {
+			const out = [];
+			buffer += chunk;
+			buffer = buffer.replace(/\r\n/g, "\n");
+			let newline;
+			while ((newline = buffer.indexOf("\n")) >= 0) {
+				const line = buffer.slice(0, newline);
+				buffer = buffer.slice(newline + 1);
+				consumeLine(line, out);
+			}
+			return out;
+		},
+		flush() {
+			const out = [];
+			if (buffer !== "") {
+				const line = buffer;
+				buffer = "";
+				consumeLine(line, out);
+			}
+			dispatch(out);
+			return out;
+		}
+	};
+}
+const dataUrl = (part) => `data:${part.mimeType};base64,${part.data}`;
+/** parts → OpenAI content；纯文本折叠成字符串（兼容端点对数组形态支持不一） */
+const toOpenAiContent = (parts, where) => {
+	if (parts.every((p) => p.type === "text")) return partsToText(parts);
+	return parts.map((part) => {
+		switch (part.type) {
+			case "text": return {
+				type: "text",
+				text: part.text
+			};
+			case "image": return {
+				type: "image_url",
+				image_url: { url: dataUrl(part) }
+			};
+			case "file": return {
+				type: "file",
+				file: {
+					...part.name !== void 0 ? { filename: part.name } : {},
+					file_data: dataUrl(part)
+				}
+			};
+			default: return rejectUnsupportedPart(part, "OpenAI", where);
+		}
+	});
+};
+/** system / tool 消息只接受文本：这两类在 OpenAI 协议里没有多模态形态 */
+const toOpenAiText = (parts, where) => {
+	const nonText = parts.find((p) => p.type !== "text");
+	if (nonText) rejectUnsupportedPart(nonText, "OpenAI", where);
+	return partsToText(parts);
+};
 const toOpenAiMessage = (msg) => {
 	if (msg.role === "tool") return {
 		role: "tool",
 		tool_call_id: msg.toolCallId,
-		content: msg.content
+		content: toOpenAiText(msg.content, "tool")
 	};
-	if (msg.role === "assistant" && msg.toolCalls?.length) return {
-		role: "assistant",
-		content: msg.content === "" ? null : msg.content,
-		tool_calls: msg.toolCalls.map((call) => ({
-			id: call.id,
-			type: "function",
-			function: {
-				name: call.name,
-				arguments: JSON.stringify(call.arguments)
-			}
-		}))
+	if (msg.role === "system") return {
+		role: "system",
+		content: toOpenAiText(msg.content, "system")
 	};
+	if (msg.role === "assistant" && msg.toolCalls?.length) {
+		const content = toOpenAiContent(msg.content, "assistant");
+		return {
+			role: "assistant",
+			content: content === "" ? null : content,
+			tool_calls: msg.toolCalls.map((call) => ({
+				id: call.id,
+				type: "function",
+				function: {
+					name: call.name,
+					arguments: JSON.stringify(call.arguments)
+				}
+			}))
+		};
+	}
 	return {
 		role: msg.role,
-		content: msg.content
+		content: toOpenAiContent(msg.content, msg.role)
 	};
 };
 const toOpenAiTools = (tools) => tools.map((tool) => ({
@@ -68,7 +151,7 @@ var OpenAiCompatibleClient = class {
 		const toolCallsByIndex = /* @__PURE__ */ new Map();
 		const decoder = new TextDecoder();
 		const reader = res.body.getReader();
-		let buffer = "";
+		const frames = createSseFrameReader();
 		let done = false;
 		const handleFrame = function* (data) {
 			if (data === "[DONE]") {
@@ -104,19 +187,12 @@ var OpenAiCompatibleClient = class {
 		try {
 			for (;;) {
 				const { value, done: readerDone } = await reader.read();
-				if (readerDone) break;
-				buffer += decoder.decode(value, { stream: true });
-				buffer = buffer.replace(/\r\n/g, "\n");
-				let newline;
-				while ((newline = buffer.indexOf("\n")) >= 0) {
-					const line = buffer.slice(0, newline).trim();
-					buffer = buffer.slice(newline + 1);
-					if (line === "" || line.startsWith(":")) continue;
-					if (!line.startsWith("data:")) continue;
-					yield* handleFrame(line.slice(5).trim());
+				const payloads = readerDone ? frames.flush() : frames.push(decoder.decode(value, { stream: true }));
+				for (const payload of payloads) {
+					yield* handleFrame(payload);
 					if (done) break;
 				}
-				if (done) break;
+				if (done || readerDone) break;
 			}
 		} finally {
 			reader.releaseLock();
@@ -143,6 +219,7 @@ var OpenAiCompatibleClient = class {
 	}
 	async #postChat(input, stream) {
 		const { baseUrl, apiKey, model } = this.#requireConfig();
+		validateLlmMessages(input.messages);
 		const body = {
 			model: input.model ?? model,
 			messages: input.messages.map(toOpenAiMessage)
@@ -196,7 +273,7 @@ var OpenAiCompatibleClient = class {
 			});
 			const content = choice["content"];
 			return {
-				content: typeof content === "string" ? content : void 0,
+				content: typeof content === "string" && content !== "" ? textParts(content) : void 0,
 				toolCalls: toolCalls?.length ? toolCalls : void 0,
 				raw: data
 			};
@@ -207,9 +284,41 @@ var OpenAiCompatibleClient = class {
 };
 const ANTHROPIC_VERSION = "2023-06-01";
 const errorMessage$1 = (e) => e instanceof Error ? e.message : String(e);
+/** parts → Anthropic content blocks（image/document 均为 base64 source） */
+const toAnthropicBlocks = (parts, where) => parts.map((part) => {
+	switch (part.type) {
+		case "text": return {
+			type: "text",
+			text: part.text
+		};
+		case "image": return {
+			type: "image",
+			source: {
+				type: "base64",
+				media_type: part.mimeType,
+				data: part.data
+			}
+		};
+		case "file": return {
+			type: "document",
+			source: {
+				type: "base64",
+				media_type: part.mimeType,
+				data: part.data
+			}
+		};
+		default: return rejectUnsupportedPart(part, "Anthropic", where);
+	}
+});
+/** system 是独立的字符串参数，无多模态形态 */
+const toAnthropicSystemText = (parts) => {
+	const nonText = parts.find((p) => p.type !== "text");
+	if (nonText) rejectUnsupportedPart(nonText, "Anthropic", "system");
+	return partsToText(parts);
+};
 /** LlmMessage 序列 → system 独立参数 + user/assistant 消息（tool 结果合并进 user 消息 tool_result blocks） */
 function toAnthropicMessages(messages) {
-	const system = messages.filter((m) => m.role === "system").map((m) => m.content).join("\n");
+	const system = messages.filter((m) => m.role === "system").map((m) => toAnthropicSystemText(m.content)).join("\n");
 	const out = [];
 	for (const msg of messages) {
 		if (msg.role === "system") continue;
@@ -217,7 +326,7 @@ function toAnthropicMessages(messages) {
 			const block = {
 				type: "tool_result",
 				tool_use_id: msg.toolCallId ?? "",
-				content: msg.content
+				content: toAnthropicBlocks(msg.content, "tool")
 			};
 			const last = out.at(-1);
 			if (last && last.role === "user" && Array.isArray(last.content)) last.content.push(block);
@@ -228,11 +337,7 @@ function toAnthropicMessages(messages) {
 			continue;
 		}
 		if (msg.role === "assistant" && msg.toolCalls?.length) {
-			const content = [];
-			if (msg.content !== "") content.push({
-				type: "text",
-				text: msg.content
-			});
+			const content = toAnthropicBlocks(msg.content, "assistant");
 			for (const call of msg.toolCalls) content.push({
 				type: "tool_use",
 				id: call.id,
@@ -247,7 +352,7 @@ function toAnthropicMessages(messages) {
 		}
 		out.push({
 			role: msg.role,
-			content: msg.content
+			content: toAnthropicBlocks(msg.content, msg.role)
 		});
 	}
 	return system === "" ? { messages: out } : {
@@ -296,7 +401,7 @@ var AnthropicClient = class {
 		const toolCallsByIndex = /* @__PURE__ */ new Map();
 		const decoder = new TextDecoder();
 		const reader = res.body.getReader();
-		let buffer = "";
+		const frames = createSseFrameReader();
 		const handleFrame = function* (data) {
 			let chunk;
 			try {
@@ -343,17 +448,9 @@ var AnthropicClient = class {
 		try {
 			for (;;) {
 				const { value, done: readerDone } = await reader.read();
+				const payloads = readerDone ? frames.flush() : frames.push(decoder.decode(value, { stream: true }));
+				for (const payload of payloads) yield* handleFrame(payload);
 				if (readerDone) break;
-				buffer += decoder.decode(value, { stream: true });
-				buffer = buffer.replace(/\r\n/g, "\n");
-				let newline;
-				while ((newline = buffer.indexOf("\n")) >= 0) {
-					const line = buffer.slice(0, newline).trim();
-					buffer = buffer.slice(newline + 1);
-					if (line === "" || line.startsWith(":") || line.startsWith("event:")) continue;
-					if (!line.startsWith("data:")) continue;
-					yield* handleFrame(line.slice(5).trim());
-				}
 			}
 		} finally {
 			reader.releaseLock();
@@ -379,6 +476,7 @@ var AnthropicClient = class {
 		yield { type: "done" };
 	}
 	async #post(input, stream) {
+		validateLlmMessages(input.messages);
 		const { system, messages } = toAnthropicMessages(input.messages);
 		const body = {
 			model: input.model ?? this.#config.model,
@@ -425,7 +523,7 @@ var AnthropicClient = class {
 				arguments: typeof b["input"] === "object" && b["input"] !== null ? b["input"] : {}
 			}));
 			return {
-				content: text === "" ? void 0 : text,
+				content: text === "" ? void 0 : textParts(text),
 				toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
 				raw: data
 			};
@@ -435,6 +533,24 @@ var AnthropicClient = class {
 	}
 };
 const errorMessage = (e) => e instanceof Error ? e.message : String(e);
+/** parts → GenAI parts（二进制统一走 inlineData） */
+const toGenAiParts = (parts, where) => parts.map((part) => {
+	switch (part.type) {
+		case "text": return { text: part.text };
+		case "image":
+		case "file": return { inlineData: {
+			mimeType: part.mimeType,
+			data: part.data
+		} };
+		default: return rejectUnsupportedPart(part, "Google GenAI", where);
+	}
+});
+/** systemInstruction 与 functionResponse 只接受文本 */
+const toGenAiText = (parts, where) => {
+	const nonText = parts.find((p) => p.type !== "text");
+	if (nonText) rejectUnsupportedPart(nonText, "Google GenAI", where);
+	return partsToText(parts);
+};
 /** tool 结果文本包装为 functionResponse.response 对象 */
 function responseObject(content) {
 	try {
@@ -445,7 +561,7 @@ function responseObject(content) {
 }
 /** LlmMessage 序列 → systemInstruction + contents（tool 结果合并进 user 消息 functionResponse parts） */
 function toGenAiContents(messages) {
-	const system = messages.filter((m) => m.role === "system").map((m) => m.content).join("\n");
+	const system = messages.filter((m) => m.role === "system").map((m) => toGenAiText(m.content, "system")).join("\n");
 	const nameByCallId = /* @__PURE__ */ new Map();
 	for (const msg of messages) if (msg.role === "assistant") for (const call of msg.toolCalls ?? []) nameByCallId.set(call.id, call.name);
 	const out = [];
@@ -455,7 +571,7 @@ function toGenAiContents(messages) {
 			const callId = msg.toolCallId ?? "";
 			const part = { functionResponse: {
 				name: nameByCallId.get(callId) ?? callId,
-				response: responseObject(msg.content)
+				response: responseObject(toGenAiText(msg.content, "tool"))
 			} };
 			const last = out.at(-1);
 			if (last && last.role === "user") last.parts.push(part);
@@ -466,8 +582,7 @@ function toGenAiContents(messages) {
 			continue;
 		}
 		if (msg.role === "assistant") {
-			const parts = [];
-			if (msg.content !== "") parts.push({ text: msg.content });
+			const parts = toGenAiParts(msg.content, "assistant");
 			for (const call of msg.toolCalls ?? []) parts.push({ functionCall: {
 				name: call.name,
 				args: call.arguments
@@ -480,7 +595,7 @@ function toGenAiContents(messages) {
 		}
 		out.push({
 			role: "user",
-			parts: [{ text: msg.content }]
+			parts: toGenAiParts(msg.content, msg.role)
 		});
 	}
 	return system === "" ? { contents: out } : {
@@ -516,7 +631,7 @@ var GoogleGenAiClient = class {
 		const text = parts.filter((p) => typeof p["text"] === "string").map((p) => String(p["text"])).join("");
 		const toolCalls = this.#functionCalls(parts);
 		return {
-			content: text === "" ? void 0 : text,
+			content: text === "" ? void 0 : textParts(text),
 			toolCalls: toolCalls.length > 0 ? toolCalls : void 0,
 			raw: data
 		};
@@ -528,7 +643,7 @@ var GoogleGenAiClient = class {
 		const toolCalls = [];
 		const decoder = new TextDecoder();
 		const reader = res.body.getReader();
-		let buffer = "";
+		const frames = createSseFrameReader();
 		const handleFrame = function* (data) {
 			let chunk;
 			try {
@@ -556,17 +671,9 @@ var GoogleGenAiClient = class {
 		try {
 			for (;;) {
 				const { value, done: readerDone } = await reader.read();
+				const payloads = readerDone ? frames.flush() : frames.push(decoder.decode(value, { stream: true }));
+				for (const payload of payloads) yield* handleFrame(payload);
 				if (readerDone) break;
-				buffer += decoder.decode(value, { stream: true });
-				buffer = buffer.replace(/\r\n/g, "\n");
-				let newline;
-				while ((newline = buffer.indexOf("\n")) >= 0) {
-					const line = buffer.slice(0, newline).trim();
-					buffer = buffer.slice(newline + 1);
-					if (line === "" || line.startsWith(":") || line.startsWith("event:")) continue;
-					if (!line.startsWith("data:")) continue;
-					yield* handleFrame(line.slice(5).trim());
-				}
 			}
 		} finally {
 			reader.releaseLock();
@@ -580,6 +687,7 @@ var GoogleGenAiClient = class {
 	async #post(input, stream) {
 		const model = input.model ?? this.#config.model;
 		const action = stream ? ":streamGenerateContent?alt=sse" : ":generateContent";
+		validateLlmMessages(input.messages);
 		const { systemInstruction, contents } = toGenAiContents(input.messages);
 		const body = { contents };
 		if (systemInstruction) body["systemInstruction"] = systemInstruction;
@@ -655,7 +763,7 @@ function fromVercelResult(result) {
 		};
 	});
 	return {
-		content: typeof r.text === "string" && r.text !== "" ? r.text : void 0,
+		content: typeof r.text === "string" && r.text !== "" ? textParts(r.text) : void 0,
 		toolCalls: toolCalls.length ? toolCalls : void 0,
 		raw: result
 	};
@@ -938,11 +1046,8 @@ function buildRenderResult(run, output, renderBlocks = []) {
 }
 const MAX_SURFACE_BYTES = 256 * 1024;
 const MAX_ACTIONS = 32;
-const MAX_FORM_FIELDS = 64;
-const MAX_OPTIONS = 256;
-const MAX_TABLE_COLUMNS = 128;
-const MAX_TABLE_ROWS = 1e4;
-const MAX_CHART_POINTS = 2e4;
+const MAX_NODES = 2e3;
+const MAX_NODE_DEPTH = 32;
 const MAX_JSON_DEPTH = 16;
 const MAX_PATCH_OPERATIONS = 128;
 const actionIntents = /* @__PURE__ */ new Set([
@@ -952,16 +1057,6 @@ const actionIntents = /* @__PURE__ */ new Set([
 	"download",
 	"refresh"
 ]);
-const fieldTypes = /* @__PURE__ */ new Set([
-	"text",
-	"number",
-	"date",
-	"textarea",
-	"select",
-	"multi-select",
-	"toggle",
-	"file"
-]);
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -982,98 +1077,39 @@ function isJsonValue(value, depth = 0) {
 	if (!isRecord$1(value)) return false;
 	return Object.keys(value).every((key) => key !== "__proto__" && key !== "constructor" && isJsonValue(value[key], depth + 1));
 }
+/**
+* Runtime 只做结构校验；组件名白名单与 props schema 属于 catalog 语义，
+* 留在 `@webskill/ui`——runtime 不得为了校验反向依赖 ui。
+*/
+function assertNode(value, path, depth, counter) {
+	if (depth > MAX_NODE_DEPTH) reject(`A UI spec tree must not nest deeper than ${MAX_NODE_DEPTH} levels`);
+	if (++counter.nodes > MAX_NODES) reject(`A UI spec tree must contain at most ${MAX_NODES} nodes`);
+	if (!isRecord$1(value)) reject(`${path} must be an object`);
+	requireString(value["component"], `${path}.component`);
+	if (value["id"] !== void 0) requireString(value["id"], `${path}.id`);
+	if (value["props"] !== void 0 && (!isRecord$1(value["props"]) || !isJsonValue(value["props"]))) reject(`${path}.props must be a JSON object`);
+	const children = value["children"];
+	if (children === void 0) return;
+	if (!Array.isArray(children)) reject(`${path}.children must be an array`);
+	children.forEach((child, index) => assertNode(child, `${path}.children[${index}]`, depth + 1, counter));
+}
 function assertActions(value) {
 	if (value === void 0) return;
 	if (!Array.isArray(value) || value.length > MAX_ACTIONS) reject(`Surface actions must contain at most ${MAX_ACTIONS} items`);
 	for (const action of value) {
 		if (!isRecord$1(action)) reject("A surface action must be an object");
 		requireString(action["id"], "Surface action ID");
-		requireString(action["label"], "Surface action label");
-		if (typeof action["intent"] !== "string" || !actionIntents.has(action["intent"])) reject("Surface action intent is invalid");
-		if (action["disabled"] !== void 0 && typeof action["disabled"] !== "boolean") reject("Surface action disabled must be a boolean");
+		const intent = action["intent"];
+		if (typeof intent !== "string" || !actionIntents.has(intent)) reject("Surface action intent is invalid");
 		if (action["awaitResponse"] !== void 0 && typeof action["awaitResponse"] !== "boolean") reject("Surface action awaitResponse must be a boolean");
 		if (action["nonce"] !== void 0 && (typeof action["nonce"] !== "string" || action["nonce"] === "")) reject("Surface action nonce must be a non-empty string");
 	}
 }
-function assertForm(surface) {
-	if (!Array.isArray(surface["fields"]) || surface["fields"].length > MAX_FORM_FIELDS) reject(`A form surface must contain at most ${MAX_FORM_FIELDS} fields`);
-	for (const field of surface["fields"]) {
-		if (!isRecord$1(field)) reject("A form field must be an object");
-		requireString(field["name"], "Form field name");
-		requireString(field["label"], "Form field label");
-		if (typeof field["type"] !== "string" || !fieldTypes.has(field["type"])) reject("Form field type is invalid");
-		if (field["required"] !== void 0 && typeof field["required"] !== "boolean") reject("Form field required must be a boolean");
-		if (field["description"] !== void 0 && typeof field["description"] !== "string") reject("Form field description must be a string");
-		if (field["defaultValue"] !== void 0 && !isJsonValue(field["defaultValue"])) reject("Form field defaultValue must be JSON data");
-		if (field["options"] !== void 0) {
-			if (!Array.isArray(field["options"]) || field["options"].length > MAX_OPTIONS) reject(`Form field options must contain at most ${MAX_OPTIONS} items`);
-			for (const option of field["options"]) {
-				if (!isRecord$1(option)) reject("A form option must be an object");
-				requireString(option["label"], "Form option label");
-				if (!isJsonValue(option["value"])) reject("Form option value must be JSON data");
-			}
-		}
-	}
-	assertActions(surface["actions"]);
-}
-function assertChart(surface) {
-	const chart = surface["chart"];
-	if (!isRecord$1(chart)) reject("A chart surface requires a chart object");
-	if (chart["kind"] !== "bar" && chart["kind"] !== "line" && chart["kind"] !== "pie") reject("Chart kind is invalid");
-	if (!Array.isArray(chart["labels"]) || !chart["labels"].every((label) => typeof label === "string")) reject("Chart labels must be an array of strings");
-	if (!Array.isArray(chart["series"])) reject("Chart series must be an array");
-	let points = 0;
-	for (const series of chart["series"]) {
-		if (!isRecord$1(series) || !Array.isArray(series["data"]) || !series["data"].every((point) => typeof point === "number" && Number.isFinite(point))) reject("Chart series data must be finite numbers");
-		if (series["name"] !== void 0 && typeof series["name"] !== "string") reject("Chart series name must be a string");
-		points += series["data"].length;
-	}
-	if (points > MAX_CHART_POINTS) reject(`Chart data exceeds the ${MAX_CHART_POINTS}-point limit`);
-	assertActions(surface["actions"]);
-}
-function assertTable(surface) {
-	if (!Array.isArray(surface["columns"]) || surface["columns"].length > MAX_TABLE_COLUMNS || !surface["columns"].every((column) => typeof column === "string")) reject(`Table columns must be strings and contain at most ${MAX_TABLE_COLUMNS} items`);
-	if (!Array.isArray(surface["rows"]) || surface["rows"].length > MAX_TABLE_ROWS) reject(`Table rows must contain at most ${MAX_TABLE_ROWS} items`);
-	for (const row of surface["rows"]) if (!Array.isArray(row) || row.length > surface["columns"].length || !row.every((cell) => isJsonValue(cell))) reject("Table rows must contain JSON cells within the declared column count");
-	assertActions(surface["actions"]);
-}
-/** Validates the allowlisted, data-only shape accepted by a UI surface renderer. @experimental */
-function validateUiSurface(value) {
-	if (!isRecord$1(value)) reject("A UI surface must be an object");
-	requireString(value["id"], "UI surface ID");
-	if (value["title"] !== void 0 && typeof value["title"] !== "string") reject("UI surface title must be a string");
-	switch (value["kind"]) {
-		case "form":
-			assertForm(value);
-			break;
-		case "chart":
-			assertChart(value);
-			break;
-		case "table":
-			assertTable(value);
-			break;
-		case "metric":
-			requireString(value["label"], "Metric label");
-			if (typeof value["value"] !== "string" && (typeof value["value"] !== "number" || !Number.isFinite(value["value"]))) reject("Metric value must be a string or finite number");
-			if (value["trend"] !== void 0 && value["trend"] !== "up" && value["trend"] !== "down" && value["trend"] !== "neutral") reject("Metric trend is invalid");
-			break;
-		case "file": {
-			requireString(value["path"], "File path");
-			if (value["mimeType"] !== void 0 && typeof value["mimeType"] !== "string") reject("File mimeType must be a string");
-			const fileSize = value["size"];
-			if (fileSize !== void 0 && (typeof fileSize !== "number" || !Number.isSafeInteger(fileSize) || fileSize < 0)) reject("File size must be a non-negative integer");
-			assertActions(value["actions"]);
-			break;
-		}
-		case "custom":
-			requireString(value["component"], "Custom surface component");
-			if (!isJsonValue(value["props"])) reject("Custom surface props must be JSON data");
-			assertActions(value["actions"]);
-			break;
-		default: reject("UI surface kind is invalid");
-	}
-	if (!isJsonValue(value)) reject("A UI surface must contain JSON data only");
-	if (JSON.stringify(value).length > MAX_SURFACE_BYTES) reject(`A UI surface exceeds the ${MAX_SURFACE_BYTES}-byte limit`);
+/** Validates the allowlisted, data-only node tree accepted by a UI surface renderer. @experimental */
+function validateUiSpecNode(value) {
+	assertNode(value, "root", 0, { nodes: 0 });
+	if (!isJsonValue(value)) reject("A UI spec tree must contain JSON data only");
+	if (JSON.stringify(value).length > MAX_SURFACE_BYTES) reject(`A UI spec tree exceeds the ${MAX_SURFACE_BYTES}-byte limit`);
 	return structuredClone(value);
 }
 function assertPatch(value) {
@@ -1084,15 +1120,20 @@ function assertPatch(value) {
 	if (!isJsonValue(value["value"])) reject("Surface patch value must be JSON data");
 }
 /** Validates an individual event in the framework-neutral surface stream. @experimental */
-function validateUiSurfaceEvent(value) {
+function validateUiSpecEvent(value) {
 	if (!isRecord$1(value) || typeof value["type"] !== "string") reject("A UI surface event must have a type");
 	if (value["runId"] !== void 0) requireString(value["runId"], "Surface event run ID");
 	switch (value["type"]) {
-		case "open": return {
-			type: "open",
-			...value["runId"] ? { runId: value["runId"] } : {},
-			surface: validateUiSurface(value["surface"])
-		};
+		case "open":
+			requireString(value["id"], "UI surface ID");
+			assertActions(value["actions"]);
+			return {
+				type: "open",
+				...value["runId"] ? { runId: value["runId"] } : {},
+				id: value["id"],
+				node: validateUiSpecNode(value["node"]),
+				...value["actions"] ? { actions: structuredClone(value["actions"]) } : {}
+			};
 		case "patch":
 			requireString(value["id"], "Surface patch ID");
 			requireNonNegativeInteger(value["revision"], "Surface patch revision");
@@ -1137,10 +1178,10 @@ function validateUiSurfaceEvent(value) {
 	}
 }
 /** Extracts validated surface stream events from structured tool output. @experimental */
-function extractUiSurfaceEvents(data) {
+function extractUiSpecEvents(data) {
 	if (!isRecord$1(data) || data["$surface"] === void 0) return [];
 	const raw = data["$surface"];
-	return (Array.isArray(raw) ? raw : [raw]).map((event) => validateUiSurfaceEvent(event));
+	return (Array.isArray(raw) ? raw : [raw]).map((event) => validateUiSpecEvent(event));
 }
 /**
 * JsonSchema → 表单模型：按 properties 生成字段，required 标记必填；
@@ -1287,6 +1328,148 @@ var TraceRecorder = class {
 		return [...this.#events];
 	}
 };
+const RUN_SNAPSHOT_SCHEMA_VERSION = 2;
+/** @experimental */
+function isUnsupportedRunSnapshot(entry) {
+	return entry.unsupported === true;
+}
+const SNAPSHOT_SUFFIX = ".snapshot.json";
+/**
+* FileSystemProvider 后端的快照存储：<root>/<runId>.snapshot.json。
+* 坏 JSON → RUN_SNAPSHOT_INCOMPATIBLE 并自动清理坏文件；runId 过路径安全校验。
+* save/list 时顺带清理已过 interactionExpiresAt 的过期快照。
+*
+* 数据敏感性说明：快照含完整对话历史（用户输入、工具结果、可能的凭据片段），
+* 以明文 JSON 落盘于宿主提供的 fs；宿主应将其视为会话数据同等保护。
+* @experimental
+*/
+var FsRunSnapshotStore = class {
+	#root;
+	#fs;
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+	}
+	#path(runId) {
+		return resolveInsideRoot(this.#root, `${runId}${SNAPSHOT_SUFFIX}`);
+	}
+	async save(snapshot) {
+		await this.#fs.writeText(this.#path(snapshot.runId), JSON.stringify(snapshot, null, 2));
+		await this.#pruneExpired();
+	}
+	async load(runId) {
+		const path = this.#path(runId);
+		if (!await this.#fs.exists(path)) return void 0;
+		let parsed;
+		try {
+			parsed = JSON.parse(await this.#fs.readText(path));
+		} catch (e) {
+			await this.#fs.remove(path).catch(() => void 0);
+			throw new WebSkillError("RUN_SNAPSHOT_INCOMPATIBLE", `Snapshot for run "${runId}" is corrupted and was deleted: ${e instanceof Error ? e.message : String(e)}`, e);
+		}
+		const snapshot = parsed;
+		if (typeof snapshot !== "object" || snapshot === null) {
+			await this.#fs.remove(path).catch(() => void 0);
+			throw new WebSkillError("RUN_SNAPSHOT_INCOMPATIBLE", `Snapshot for run "${runId}" has an unexpected shape and was deleted`);
+		}
+		const schemaVersion = typeof snapshot.schemaVersion === "number" ? snapshot.schemaVersion : 0;
+		if (schemaVersion !== 2) throw new WebSkillError("RUN_SNAPSHOT_SCHEMA_UNSUPPORTED", `Snapshot for run "${runId}" uses schema version ${schemaVersion}; this runtime reads version 2. The file was kept for read-only inspection.`);
+		if (snapshot.runId !== runId) {
+			await this.#fs.remove(path).catch(() => void 0);
+			throw new WebSkillError("RUN_SNAPSHOT_INCOMPATIBLE", `Snapshot for run "${runId}" has an unexpected shape and was deleted`);
+		}
+		return snapshot;
+	}
+	async delete(runId) {
+		const path = this.#path(runId);
+		if (await this.#fs.exists(path)) await this.#fs.remove(path);
+	}
+	async list() {
+		await this.#pruneExpired();
+		if (!await this.#fs.exists(this.#root)) return [];
+		const out = [];
+		for (const entry of await this.#fs.list(this.#root)) {
+			if (entry.type !== "file" || !entry.path.endsWith(SNAPSHOT_SUFFIX)) continue;
+			try {
+				const parsed = JSON.parse(await this.#fs.readText(entry.path));
+				const schemaVersion = typeof parsed.schemaVersion === "number" ? parsed.schemaVersion : 0;
+				if (schemaVersion === 2) {
+					out.push(parsed);
+					continue;
+				}
+				out.push({
+					unsupported: true,
+					schemaVersion,
+					runId: String(parsed.runId ?? entry.path),
+					snapshotAt: typeof parsed.snapshotAt === "string" ? parsed.snapshotAt : "",
+					...typeof parsed.sessionId === "string" ? { sessionId: parsed.sessionId } : {},
+					...typeof parsed.userPrompt === "string" ? { userPrompt: parsed.userPrompt } : {},
+					...typeof parsed.interactionExpiresAt === "string" ? { interactionExpiresAt: parsed.interactionExpiresAt } : {}
+				});
+			} catch {}
+		}
+		return out.sort((a, b) => a.snapshotAt.localeCompare(b.snapshotAt));
+	}
+	/** 过期快照清理（save/list 时顺带；失败静默不阻断主流程） */
+	async #pruneExpired() {
+		try {
+			if (!await this.#fs.exists(this.#root)) return;
+			const now = Date.now();
+			for (const entry of await this.#fs.list(this.#root)) {
+				if (entry.type !== "file" || !entry.path.endsWith(SNAPSHOT_SUFFIX)) continue;
+				try {
+					const parsed = JSON.parse(await this.#fs.readText(entry.path));
+					if (parsed.interactionExpiresAt !== void 0 && Date.parse(parsed.interactionExpiresAt) < now) await this.#fs.remove(entry.path);
+				} catch {}
+			}
+		} catch {}
+	}
+};
+/**
+* LLM 可见名 → 作者在 SKILL.md 里写的形态。
+* `<已激活技能>__<脚本>` 保持原样（裸标识符按技能作用域单独匹配），
+* `mcp__x` → `mcp#x`，其余 `a__b` → `endpoint:a/b`。
+*/
+function canonicalToolName(llmToolName, activated) {
+	const sep = llmToolName.indexOf("__");
+	if (sep > 0 && activated.has(llmToolName.slice(0, sep))) return llmToolName;
+	if (llmToolName.startsWith("mcp__")) return `mcp#${llmToolName.slice(5)}`;
+	if (sep > 0) return `endpoint:${llmToolName.slice(0, sep)}/${llmToolName.slice(sep + 2)}`;
+	return llmToolName;
+}
+/**
+* 只支持整段匹配与尾部 `/*`。通配符越自由，作者越容易写出一个自以为很窄、实际很宽的规则；
+* 裸 `endpoint:github`（不带 `/*`）判为未匹配——含糊写法应当报警而不是被善意解释。
+*/
+function matchesPattern(pattern, declaringSkill, llmToolName, canonical) {
+	if (!pattern.includes(":") && !pattern.includes("#")) return llmToolName === `${declaringSkill}__${pattern}`;
+	if (pattern === canonical) return true;
+	if (pattern.endsWith("/*")) {
+		const prefix = pattern.slice(0, -1);
+		return canonical.startsWith(prefix) && canonical.length > prefix.length;
+	}
+	return false;
+}
+function denialReason(state, canonical) {
+	const skills = [...state.skillAllowedTools.keys()].sort().map((s) => `"${s}"`);
+	const subject = skills.length === 1 ? `Skill ${skills[0]} declares` : `Skills ${skills.join(", ")} declare`;
+	const slash = canonical.lastIndexOf("/");
+	return `${subject} allowed-tools, but tool "${canonical}" is not listed and was rejected. Add "${canonical}"${slash > 0 ? ` or "${canonical.slice(0, slash)}/*"` : ""} to allowed-tools.`;
+}
+/**
+* 多技能语义：无人声明 → 不受限；有人声明 → 命中任一清单，
+* 或存在一个**未声明**清单的激活技能（否则就是把 A 的声明施加到 B 头上）。
+*/
+function evaluateToolAccess(state, llmToolName) {
+	if (state.skillAllowedTools.size === 0) return { allowed: true };
+	for (const skill of state.activated) if (!state.skillAllowedTools.has(skill)) return { allowed: true };
+	const canonical = canonicalToolName(llmToolName, state.activated);
+	for (const [skill, patterns] of state.skillAllowedTools) for (const pattern of patterns) if (matchesPattern(pattern, skill, llmToolName, canonical)) return { allowed: true };
+	return {
+		allowed: false,
+		reason: denialReason(state, canonical)
+	};
+}
 const MAX_SURFACE_PATCHES_PER_SECOND = 240;
 /** 交互终态（取消/超时）：从工具执行深处直接终止 run */
 var RunTerminated = class extends Error {
@@ -1312,7 +1495,6 @@ const summarizeArgs = (args) => {
 	const json = JSON.stringify(args);
 	return json.length > 100 ? `${json.slice(0, 100)}…` : json;
 };
-const surfaceActions = (surface) => "actions" in surface ? surface.actions ?? [] : [];
 /**
 * 多轮 Agent 循环。
 * 工具失败一律转为 ToolResult{ok:false} 回喂 LLM 继续循环；
@@ -1381,6 +1563,9 @@ var AgentLoop = class {
 			reader: new SkillReader(this.#deps.fs, this.#deps.skillIndex),
 			activated: /* @__PURE__ */ new Set(),
 			activatedTools: /* @__PURE__ */ new Map(),
+			skillAllowedTools: /* @__PURE__ */ new Map(),
+			warnedDeniedTools: /* @__PURE__ */ new Set(),
+			integrityVerdicts: /* @__PURE__ */ new Map(),
 			toolTimeoutMs: this.#config.toolTimeoutMs,
 			now,
 			interactionSeq: 0,
@@ -1392,6 +1577,7 @@ var AgentLoop = class {
 			surfacePatchWindowStartedAt: Date.now(),
 			surfacePatchCount: 0,
 			processedSurfaceActionNonces: /* @__PURE__ */ new Set(),
+			emittedToolEvents: /* @__PURE__ */ new Set(),
 			startMs,
 			pausedMs: 0,
 			maxTurns: this.#config.maxTurns,
@@ -1408,7 +1594,13 @@ var AgentLoop = class {
 			strategy: route.strategy,
 			skillCount: route.catalog.entries.length
 		} });
-		await this.#lifecycle("route", state, { strategy: route.strategy });
+		await this.#lifecycle({
+			phase: "route",
+			data: {
+				strategy: route.strategy,
+				candidates: route.catalog.entries.map((e) => e.name)
+			}
+		}, state);
 		const externalSpecs = (await Promise.all((this.#deps.externalTools ?? []).map(async (source) => {
 			try {
 				return await source.listToolSpecs();
@@ -1417,15 +1609,25 @@ var AgentLoop = class {
 				return [];
 			}
 		}))).flat();
+		const externalSystemPrompts = [];
+		for (const source of this.#deps.externalTools ?? []) {
+			if (source.systemPrompt === void 0) continue;
+			try {
+				const text = (await source.systemPrompt())?.trim();
+				if (text !== void 0 && text !== "") externalSystemPrompts.push(text);
+			} catch (e) {
+				trace.record("run.warning", { message: `External tool source "${source.kind}" failed to build a system prompt: ${messageOf(e)}` });
+			}
+		}
 		state.messages = [
 			{
 				role: "system",
-				content: route.systemPrompt
+				content: textParts([route.systemPrompt, ...externalSystemPrompts].join("\n\n"))
 			},
 			...(input.history ?? []).map((m) => ({ ...m })),
 			{
 				role: "user",
-				content: input.userPrompt
+				content: textParts(input.userPrompt)
 			}
 		];
 		try {
@@ -1455,6 +1657,27 @@ var AgentLoop = class {
 			state.timer = void 0;
 		}
 	}
+	/**
+	* D10 判定的唯一出口（暴露点 + 分发点共用）。
+	* 0.4.0（D1）起两个调用点都看返回值：暴露点过滤、分发点回喂 TOOL_NOT_ALLOWED。
+	* 判定语义与 0.3.0 一致，改的只是调用点与 trace 事件类型（warning → denied）。
+	*/
+	#checkToolAccess(state, toolName) {
+		const verdict = evaluateToolAccess(state, toolName);
+		if (verdict.allowed) return true;
+		if (!state.warnedDeniedTools.has(toolName)) {
+			state.warnedDeniedTools.add(toolName);
+			state.trace.record("tool.denied", {
+				message: verdict.reason ?? `Tool "${toolName}" is not allowed`,
+				data: { name: toolName }
+			});
+		}
+		return false;
+	}
+	/** 分发点被拒时回喂给模型的结构化错误（不抛异常：模型造名字是常态，抛异常会终止整个 run） */
+	#deniedToolError(state, toolName) {
+		return toolError("TOOL_NOT_ALLOWED", evaluateToolAccess(state, toolName).reason ?? `Tool "${toolName}" is not allowed`);
+	}
 	/** 主循环（run 从第 1 轮、resume 从快照轮次续跑；totalTimeout 以 startedAt 续算） */
 	async #turnLoop(state, startTurn, externalSpecs) {
 		const finish = (status, reason, output, errorCode) => this.#finish(state, status, reason, output, errorCode);
@@ -1466,11 +1689,11 @@ 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 toolSpecs = [
 					toLlmToolSpec(READ_SKILL_FILE_TOOL),
 					...this.#deps.uiBridge ? [toLlmToolSpec(ASK_USER_TOOL)] : [],
-					...[...state.activatedTools.values()].map(toLlmToolSpec),
-					...externalSpecs
+					...skillToolSpecs
 				];
 				trace.record("llm.request", { data: {
 					turn,
@@ -1500,22 +1723,29 @@ var AgentLoop = class {
 					const code = e instanceof WebSkillError && (e.code === "LLM_UNAVAILABLE" || e.code === "LLM_REQUEST_FAILED") ? e.code : "LLM_REQUEST_FAILED";
 					return finish("failed", "llm-error", messageOf(e), code);
 				}
+				const responseText = partsToText(response.content);
 				trace.record("llm.response", { data: {
 					turn,
 					hasToolCalls: Boolean(response.toolCalls?.length),
-					contentLength: response.content?.length ?? 0
+					contentLength: responseText.length
 				} });
 				if (!response.toolCalls?.length) {
 					messages.push({
 						role: "assistant",
-						content: response.content ?? ""
+						content: response.content ?? []
 					});
-					return finish("completed", "final-answer", response.content ?? "");
+					return finish("completed", "final-answer", responseText);
 				}
-				await this.#lifecycle("execute", state, { turn });
+				await this.#lifecycle({
+					phase: "execute",
+					data: {
+						kind: "turn",
+						turn
+					}
+				}, state);
 				messages.push({
 					role: "assistant",
-					content: response.content ?? "",
+					content: response.content ?? [],
 					toolCalls: response.toolCalls
 				});
 				for (const call of response.toolCalls) {
@@ -1529,7 +1759,7 @@ var AgentLoop = class {
 					messages.push({
 						role: "tool",
 						toolCallId: call.id,
-						content: await this.#serializeToolResult(call, result, state)
+						content: textParts(await this.#serializeToolResult(call, result, state))
 					});
 					await this.#drainSurfaceAction(state);
 				}
@@ -1575,7 +1805,10 @@ var AgentLoop = class {
 			trace.record("run.warning", { message: `Failed to delete run snapshot: ${messageOf(e)}` });
 		}
 		try {
-			await this.#lifecycle(status === "completed" ? "complete" : "fail", state, { reason });
+			await this.#lifecycle({
+				phase: status === "completed" ? "complete" : "fail",
+				data: { reason }
+			}, state);
 		} catch (e) {
 			trace.record("run.warning", { message: `Terminal lifecycle hook failed: ${messageOf(e)}` });
 		}
@@ -1591,7 +1824,7 @@ var AgentLoop = class {
 		const store = this.#deps.snapshotStore;
 		if (!store) return;
 		const snapshot = {
-			schemaVersion: 1,
+			schemaVersion: 2,
 			runId: state.runId,
 			sessionId: state.run.sessionId,
 			userPrompt: state.run.userPrompt,
@@ -1600,6 +1833,7 @@ var AgentLoop = class {
 			turn: state.turn,
 			activeSkillNames: [...state.activated].sort(),
 			activatedTools: [...state.activatedTools.values()],
+			...state.skillAllowedTools.size > 0 ? { skillAllowedTools: Object.fromEntries([...state.skillAllowedTools].map(([k, v]) => [k, [...v]])) } : {},
 			...pending.interaction ? { pendingInteraction: pending.interaction } : {},
 			...pending.surfaceAction ? { pendingSurfaceAction: pending.surfaceAction } : {},
 			interactionExpiresAt: state.run.interruptExpiresAt,
@@ -1649,6 +1883,9 @@ var AgentLoop = class {
 			reader: new SkillReader(this.#deps.fs, this.#deps.skillIndex),
 			activated: new Set(snapshot.activeSkillNames),
 			activatedTools: new Map(snapshot.activatedTools.map((d) => [d.name, d])),
+			skillAllowedTools: new Map(Object.entries(snapshot.skillAllowedTools ?? {})),
+			warnedDeniedTools: /* @__PURE__ */ new Set(),
+			integrityVerdicts: /* @__PURE__ */ new Map(),
 			toolTimeoutMs: snapshot.config.toolTimeoutMs,
 			now,
 			interactionSeq: snapshot.interactionSeq ?? 0,
@@ -1660,6 +1897,7 @@ var AgentLoop = class {
 			surfacePatchWindowStartedAt: Date.now(),
 			surfacePatchCount: 0,
 			processedSurfaceActionNonces: new Set(snapshot.processedSurfaceActionNonces ?? []),
+			emittedToolEvents: /* @__PURE__ */ new Set(),
 			startMs,
 			pausedMs: snapshot.pausedMs ?? 0,
 			maxTurns: snapshot.config.maxTurns,
@@ -1696,7 +1934,7 @@ var AgentLoop = class {
 				state.messages.push({
 					role: "tool",
 					toolCallId: pendingCall.id,
-					content: await this.#serializeToolResult(pendingCall, result, state)
+					content: textParts(await this.#serializeToolResult(pendingCall, result, state))
 				});
 				await this.#drainSurfaceAction(state);
 			} else if (pending?.type === "ask" && pendingCall) {
@@ -1718,7 +1956,7 @@ var AgentLoop = class {
 				state.messages.push({
 					role: "tool",
 					toolCallId: pendingCall.id,
-					content: await this.#serializeToolResult(pendingCall, result, state)
+					content: textParts(await this.#serializeToolResult(pendingCall, result, state))
 				});
 				await this.#drainSurfaceAction(state);
 			} else if (pendingCall) {
@@ -1726,7 +1964,7 @@ var AgentLoop = class {
 				state.messages.push({
 					role: "tool",
 					toolCallId: pendingCall.id,
-					content: await this.#serializeToolResult(pendingCall, result, state)
+					content: textParts(await this.#serializeToolResult(pendingCall, result, state))
 				});
 				await this.#drainSurfaceAction(state);
 			}
@@ -1737,7 +1975,7 @@ var AgentLoop = class {
 				state.messages.push({
 					role: "tool",
 					toolCallId: next.id,
-					content: await this.#serializeToolResult(next, result, state)
+					content: textParts(await this.#serializeToolResult(next, result, state))
 				});
 				await this.#drainSurfaceAction(state);
 			}
@@ -1780,7 +2018,7 @@ var AgentLoop = class {
 				sessionId: state.run.sessionId,
 				ts: state.now(),
 				data: {
-					type: "llm.delta",
+					kind: "llm-delta",
 					delta
 				}
 			});
@@ -1794,23 +2032,23 @@ var AgentLoop = class {
 			emitDelta(event.delta);
 		} else if (event.type === "tool-calls") toolCalls.push(...event.toolCalls);
 		else if (event.type === "done") doneContent = event.content;
+		const text = doneContent ?? content;
 		return {
-			content: doneContent ?? (content === "" ? void 0 : content),
+			content: text === "" ? void 0 : textParts(text),
 			toolCalls: toolCalls.length > 0 ? toolCalls : void 0
 		};
 	}
 	/** 生命周期接线：更新 phase、发事件、跑钩子 */
-	async #lifecycle(phase, state, data) {
-		state.run.phase = phase;
+	async #lifecycle(init, state) {
+		state.run.phase = init.phase;
 		const event = {
-			phase,
+			...init,
 			runId: state.runId,
 			sessionId: state.run.sessionId,
-			ts: state.now(),
-			...data ? { data } : {}
+			ts: state.now()
 		};
 		this.#deps.eventBus?.emit(event);
-		if (this.#deps.hooks) await this.#deps.hooks.run(phase, {
+		if (this.#deps.hooks) await this.#deps.hooks.run(init.phase, {
 			event,
 			run: state.run
 		});
@@ -1837,10 +2075,14 @@ var AgentLoop = class {
 		run.status = "interrupted";
 		run.interruptExpiresAt = new Date(Date.parse(state.now()) + this.#policy.interactionTimeoutMs).toISOString();
 		await this.#saveSnapshot(state, { interaction: request });
-		await this.#lifecycle("interact", state, {
-			interactionId: request.id,
-			type: request.type
-		});
+		await this.#lifecycle({
+			phase: "interact",
+			data: {
+				kind: "interaction",
+				interactionId: request.id,
+				interactionType: request.type
+			}
+		}, state);
 		state.trace.record("ui.requested", { data: {
 			interactionId: request.id,
 			type: request.type,
@@ -1873,7 +2115,13 @@ var AgentLoop = class {
 			interactionId: request.id,
 			type: request.type
 		} });
-		await this.#lifecycle("execute", state, { resumed: request.id });
+		await this.#lifecycle({
+			phase: "execute",
+			data: {
+				kind: "interaction-resumed",
+				interactionId: request.id
+			}
+		}, state);
 		await this.#appendParamHistory(state, request, response.value);
 		return response.value;
 	}
@@ -1907,6 +2155,7 @@ var AgentLoop = class {
 		if (call.argumentsParseError) result = toolError("VALIDATION_FAILED", `Tool arguments were not valid JSON: ${call.argumentsParseError}`);
 		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 (!this.#checkToolAccess(state, call.name)) result = this.#deniedToolError(state, call.name);
 		else {
 			const resolution = resolveToolName(call.name, state.activated);
 			if (resolution.kind === "script") result = await this.#handleScriptTool(call, resolution.skillName, resolution.scriptName, state);
@@ -1932,7 +2181,7 @@ var AgentLoop = class {
 					chart
 				});
 				try {
-					for (const event of extractUiSurfaceEvents(item.data)) await this.#renderSurface(state, event);
+					for (const event of extractUiSpecEvents(item.data)) await this.#renderSurface(state, event);
 				} catch (e) {
 					state.trace.record("run.warning", {
 						message: `UI surface rejected: ${messageOf(e)}`,
@@ -1971,14 +2220,14 @@ var AgentLoop = class {
 		await bridge.renderSurface(attributed);
 		state.surfaceEvents.push(structuredClone(attributed));
 		if (attributed.type === "open") {
-			const waiting = surfaceActions(attributed.surface).filter((action) => action.awaitResponse);
+			const waiting = (attributed.actions ?? []).filter((action) => action.awaitResponse);
 			if (waiting.length > 1) throw new WebSkillError("VALIDATION_FAILED", "A UI surface can wait for only one action");
 			const action = waiting[0];
 			if (action?.nonce) if (!bridge.requestSurfaceAction) state.trace.record("run.warning", { message: "UiBridge does not support requestSurfaceAction; UI surface action will not pause the run" });
 			else if (state.pendingSurfaceAction) throw new WebSkillError("VALIDATION_FAILED", "Only one UI surface action can be pending at a time");
 			else state.pendingSurfaceAction = {
 				runId: state.runId,
-				surfaceId: attributed.surface.id,
+				surfaceId: attributed.id,
 				actionId: action.id,
 				intent: action.intent,
 				nonce: action.nonce
@@ -1996,21 +2245,17 @@ var AgentLoop = class {
 	}
 	/** Assigns unforgeable action nonces after model output has passed structural validation. */
 	#attributeSurfaceEvent(state, event) {
-		const actions = event.type === "open" ? surfaceActions(event.surface) : [];
-		if (event.type !== "open" || actions.length === 0) return {
+		if (event.type !== "open" || (event.actions ?? []).length === 0) return {
 			...event,
 			runId: state.runId
 		};
 		return {
-			type: "open",
+			...event,
 			runId: state.runId,
-			surface: {
-				...event.surface,
-				actions: actions.map((action) => ({
-					...action,
-					nonce: `surface-${state.runId}-${++state.surfaceActionSeq}`
-				}))
-			}
+			actions: (event.actions ?? []).map((action) => ({
+				...action,
+				nonce: `surface-${state.runId}-${++state.surfaceActionSeq}`
+			}))
 		};
 	}
 	/** Awaits the single action emitted with the most recently persisted tool result. */
@@ -2037,13 +2282,13 @@ var AgentLoop = class {
 		state.processedSurfaceActionNonces.add(response.nonce);
 		state.messages.push({
 			role: "user",
-			content: JSON.stringify({
+			content: textParts(JSON.stringify({
 				type: "webskill_surface_action",
 				surfaceId: response.surfaceId,
 				actionId: response.actionId,
 				intent: response.intent,
 				value: response.value ?? null
-			})
+			}))
 		});
 	}
 	async #interactSurfaceAction(state, request, resumed) {
@@ -2055,20 +2300,26 @@ var AgentLoop = class {
 			const { run } = state;
 			run.status = "interrupted";
 			run.interruptExpiresAt = new Date(Date.parse(state.now()) + this.#policy.interactionTimeoutMs).toISOString();
+			const pendingResponse = bridge.requestSurfaceAction(request);
+			pendingResponse.catch(() => void 0);
 			await this.#saveSnapshot(state, { surfaceAction: request });
-			await this.#lifecycle("interact", state, {
-				surfaceId: request.surfaceId,
-				actionId: request.actionId,
-				nonce: request.nonce,
-				...resumed ? { resumed: true } : {}
-			});
+			await this.#lifecycle({
+				phase: "interact",
+				data: {
+					kind: "surface-action",
+					surfaceId: request.surfaceId,
+					actionId: request.actionId,
+					nonce: request.nonce,
+					resumed
+				}
+			}, state);
 			state.trace.record("ui.surface-action.requested", { data: {
 				surfaceId: request.surfaceId,
 				actionId: request.actionId,
 				nonce: request.nonce,
 				...resumed ? { resumed: true } : {}
 			} });
-			const response = await this.#withInteractionTimeout(bridge.requestSurfaceAction(request), this.#policy.interactionTimeoutMs, () => bridge.cancelSurfaceAction?.(request.nonce));
+			const response = await this.#withInteractionTimeout(pendingResponse, this.#policy.interactionTimeoutMs, () => bridge.cancelSurfaceAction?.(request.nonce));
 			run.status = "running";
 			run.interruptExpiresAt = void 0;
 			state.trace.record("ui.surface-action.resolved", { data: {
@@ -2076,9 +2327,17 @@ var AgentLoop = class {
 				actionId: request.actionId,
 				nonce: request.nonce
 			} });
-			await this.#lifecycle("execute", state, { surfaceAction: request.actionId });
+			await this.#lifecycle({
+				phase: "execute",
+				data: {
+					kind: "surface-action-resumed",
+					surfaceId: request.surfaceId,
+					actionId: request.actionId
+				}
+			}, state);
 			return response;
 		} catch (e) {
+			bridge.cancelSurfaceAction?.(request.nonce);
 			state.run.status = "running";
 			state.run.interruptExpiresAt = void 0;
 			if (e instanceof WebSkillError && e.code === "RUN_INTERACTION_TIMEOUT") throw new RunTerminated({
@@ -2108,15 +2367,25 @@ var AgentLoop = class {
 	* 逐工具实时事件（execute 相位，data.type='tool'）：chatbot 思维链工具行等的 live 状态源；
 	* 与既有 execute 相位事件（{turn}）并存，监听方按 data.type 区分。
 	* data.args 为参数摘要（JSON 截断 100 字符，展开详情用）。
+	*
+	* 幂等：同一 run 内每个 `(callId, status)` 至多投递一次。
+	* 模型在不同轮次重发同一个 tool call id 是真实发生的，消费侧本来各自
+	* 建去重表兑付；幂等是事件流自己的语义，不应该要求每个订阅者重建一次。
+	*
+	* 集合挂在 LoopState 上、**不写进快照**：写进快照会让跨进程恢复的
+	* 消费者永远收不到它本来就没见过的事件。
 	*/
 	#emitTool(state, status, call) {
+		const key = `${call.id}:${status}`;
+		if (state.emittedToolEvents.has(key)) return;
+		state.emittedToolEvents.add(key);
 		this.#deps.eventBus?.emit({
 			phase: "execute",
 			runId: state.runId,
 			sessionId: state.run.sessionId,
 			ts: state.now(),
 			data: {
-				type: "tool",
+				kind: "tool",
 				status,
 				name: call.name,
 				callId: call.id,
@@ -2186,7 +2455,13 @@ var AgentLoop = class {
 						skillName: name,
 						source: "external"
 					} });
-					await this.#lifecycle("activate", state, { skillName: name });
+					await this.#lifecycle({
+						phase: "activate",
+						data: {
+							skillName: name,
+							source: "external"
+						}
+					}, state);
 					await this.#writeActivationMemory(name, state);
 				}
 				return {
@@ -2240,18 +2515,62 @@ var AgentLoop = class {
 		if (!check) return false;
 		return await check(skillName) === false;
 	}
+	/**
+	* D3 激活期完整性校验。结论按技能名在 run 内缓存，**失败也缓存**：
+	* 校验失败的技能不会进 `activated` 集合，不缓存的话同一个坏技能每尝试激活一次
+	* 就要把它的文件全扫一遍——成本随文件数线性放大，正是需求 §3 验收 3 要防的。
+	*
+	* 设计 §3.5 写的缓存键是 `(skillName, manifest.integrity.digest)`，但 digest 只有
+	* **调用之后**才知道；runtime 读不到 manifest，两元组键在这一层无法实现。
+	* 实际键是技能名，digest 作为结论的一部分留在 trace 里供事后对账。
+	*
+	* 失败不抛错：抛错会终止整个 run，而「某个技能被改过」不该让其余技能一起停摆。
+	*/
+	async #integrityOk(skillName, state) {
+		const guard = this.#deps.skillIntegrityGuard;
+		if (!guard?.verifyOnActivate) return true;
+		let verdict = state.integrityVerdicts.get(skillName);
+		if (verdict === void 0) {
+			try {
+				verdict = await guard.verifyOnActivate(skillName);
+			} catch (e) {
+				verdict = {
+					ok: false,
+					reason: `the integrity guard threw: ${messageOf(e)}`
+				};
+			}
+			state.integrityVerdicts.set(skillName, verdict);
+		}
+		if (verdict.ok) return true;
+		state.trace.record("skill.integrity-failed", {
+			message: `Skill "${skillName}" failed integrity verification on activation: ${verdict.reason ?? "no reason given"}`,
+			data: {
+				skillName,
+				...verdict.digest !== void 0 ? { digest: verdict.digest } : {}
+			}
+		});
+		return false;
+	}
 	/** 首次读到 SKILL.md 时激活技能：加载其 scripts 工具定义，供后续轮次使用；dependencies 级联激活（via 记录来源） */
 	async #activateSkill(skillName, state, via, skillMdText) {
 		if (await this.#guardDenied("canActivate", skillName)) {
 			state.trace.record("run.warning", { message: `Skill "${skillName}" is blocked by the skill state guard (activate)` });
 			return "";
 		}
+		if (!await this.#integrityOk(skillName, state)) return "";
 		state.activated.add(skillName);
 		state.trace.record("skill.activated", { data: {
 			skillName,
 			...via ? { via } : {}
 		} });
-		await this.#lifecycle("activate", state, { skillName });
+		await this.#lifecycle({
+			phase: "activate",
+			data: {
+				skillName,
+				source: "local",
+				...via ? { via } : {}
+			}
+		}, state);
 		await this.#writeActivationMemory(skillName, state);
 		const root = this.#deps.skillIndex.get(skillName);
 		if (!root) return "";
@@ -2262,8 +2581,10 @@ var AgentLoop = class {
 			const rawDeps = metadata["dependencies"];
 			if (Array.isArray(rawDeps)) dependencies = rawDeps.filter((d) => typeof d === "string");
 			const rawAllowed = metadata["allowed-tools"];
-			if (rawAllowed !== void 0) if (Array.isArray(rawAllowed)) allowedTools = rawAllowed.filter((e) => typeof e === "string");
-			else state.trace.record("run.warning", { message: `Skill "${skillName}" has a non-array "allowed-tools" metadata entry; ignored` });
+			if (rawAllowed !== void 0) if (Array.isArray(rawAllowed)) {
+				allowedTools = rawAllowed.filter((e) => typeof e === "string");
+				state.skillAllowedTools.set(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)}` });
 		}
@@ -2280,7 +2601,10 @@ var AgentLoop = class {
 			for (const file of scriptFiles) {
 				const match = /^(.*)\.(ts|js)$/.exec(file);
 				if (!match?.[1]) continue;
-				if (allowedTools && !allowedTools.includes(match[1])) continue;
+				if (allowedTools && !allowedTools.includes(match[1])) {
+					state.trace.record("run.warning", { message: `Skill "${skillName}" declares allowed-tools, so its script "${match[1]}" is not registered as a tool. Add "${match[1]}" to allowed-tools if that was not intended.` });
+					continue;
+				}
 				try {
 					const def = await executor.loadDefinition(root, match[1]);
 					await this.#enrichDefinition(root, match[1], def, state);
@@ -2380,11 +2704,41 @@ var AgentLoop = class {
 				if (fresh.length > 0) result.artifacts = [...result.artifacts ?? [], ...fresh];
 			}
 			await this.#bumpSkillStat(skillName, result.ok ? "successes" : "failures", state);
+			if (!result.ok) await this.#reportSkillFailure(skillName, state, {
+				code: result.error?.code ?? "TOOL_EXECUTION_FAILED",
+				message: result.error?.message ?? `Tool "${call.name}" returned a failure result`
+			});
 			return result;
 		} catch (e) {
 			if (e instanceof RunTerminated) throw e;
 			await this.#bumpSkillStat(skillName, "failures", state);
-			return toolError(e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", `Tool "${call.name}" failed: ${messageOf(e)}`);
+			const code = e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED";
+			const message = `Tool "${call.name}" failed: ${messageOf(e)}`;
+			await this.#reportSkillFailure(skillName, state, {
+				code,
+				message
+			});
+			return toolError(code, message);
+		}
+	}
+	/**
+	* F1 技能失败上报：喂给治理的失败计数器（`SkillStatePolicy.recordFailure`），
+	* 达阈值即自动隔离。无注入即整段跳过（默认关闭）。
+	*
+	* 上报方抛错降级为 `run.warning`：治理写盘失败不该把一次「工具出错但已回喂给 LLM」
+	* 的 run 变成崩溃——那会让引入治理反而降低可用性。
+	*/
+	async #reportSkillFailure(skillName, state, detail) {
+		const report = this.#deps.skillOutcomeReporter?.onSkillFailed;
+		if (report === void 0) return;
+		try {
+			await report.call(this.#deps.skillOutcomeReporter, {
+				skillName,
+				runId: state.runId,
+				...detail
+			});
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Skill failure report for "${skillName}" was not recorded: ${messageOf(e)}` });
 		}
 	}
 	/** context.confirm 触发点：默认真实询问；auto-approve 直通；无 bridge 降级直通 + warning */
@@ -2494,79 +2848,6 @@ function mergeCatalogEntries(localEntries, providerEntries) {
 	for (const entry of providerEntries) if (!byName.has(entry.name)) byName.set(entry.name, entry);
 	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-const RUN_SNAPSHOT_SCHEMA_VERSION = 1;
-const SNAPSHOT_SUFFIX = ".snapshot.json";
-/**
-* FileSystemProvider 后端的快照存储：<root>/<runId>.snapshot.json。
-* 坏 JSON → RUN_SNAPSHOT_INCOMPATIBLE 并自动清理坏文件；runId 过路径安全校验。
-* save/list 时顺带清理已过 interactionExpiresAt 的过期快照。
-*
-* 数据敏感性说明：快照含完整对话历史（用户输入、工具结果、可能的凭据片段），
-* 以明文 JSON 落盘于宿主提供的 fs；宿主应将其视为会话数据同等保护。
-* @experimental
-*/
-var FsRunSnapshotStore = class {
-	#root;
-	#fs;
-	constructor(deps) {
-		this.#root = deps.root.replace(/\/+$/, "");
-		this.#fs = deps.fs;
-	}
-	#path(runId) {
-		return resolveInsideRoot(this.#root, `${runId}${SNAPSHOT_SUFFIX}`);
-	}
-	async save(snapshot) {
-		await this.#fs.writeText(this.#path(snapshot.runId), JSON.stringify(snapshot, null, 2));
-		await this.#pruneExpired();
-	}
-	async load(runId) {
-		const path = this.#path(runId);
-		if (!await this.#fs.exists(path)) return void 0;
-		let parsed;
-		try {
-			parsed = JSON.parse(await this.#fs.readText(path));
-		} catch (e) {
-			await this.#fs.remove(path).catch(() => void 0);
-			throw new WebSkillError("RUN_SNAPSHOT_INCOMPATIBLE", `Snapshot for run "${runId}" is corrupted and was deleted: ${e instanceof Error ? e.message : String(e)}`, e);
-		}
-		const snapshot = parsed;
-		if (typeof snapshot !== "object" || snapshot === null || snapshot.runId !== runId) {
-			await this.#fs.remove(path).catch(() => void 0);
-			throw new WebSkillError("RUN_SNAPSHOT_INCOMPATIBLE", `Snapshot for run "${runId}" has an unexpected shape and was deleted`);
-		}
-		return snapshot;
-	}
-	async delete(runId) {
-		const path = this.#path(runId);
-		if (await this.#fs.exists(path)) await this.#fs.remove(path);
-	}
-	async list() {
-		await this.#pruneExpired();
-		if (!await this.#fs.exists(this.#root)) return [];
-		const out = [];
-		for (const entry of await this.#fs.list(this.#root)) {
-			if (entry.type !== "file" || !entry.path.endsWith(SNAPSHOT_SUFFIX)) continue;
-			try {
-				out.push(JSON.parse(await this.#fs.readText(entry.path)));
-			} catch {}
-		}
-		return out.sort((a, b) => a.snapshotAt.localeCompare(b.snapshotAt));
-	}
-	/** 过期快照清理（save/list 时顺带；失败静默不阻断主流程） */
-	async #pruneExpired() {
-		try {
-			if (!await this.#fs.exists(this.#root)) return;
-			const now = Date.now();
-			for (const entry of await this.#fs.list(this.#root)) {
-				if (entry.type !== "file" || !entry.path.endsWith(SNAPSHOT_SUFFIX)) continue;
-				try {
-					const parsed = JSON.parse(await this.#fs.readText(entry.path));
-					if (parsed.interactionExpiresAt !== void 0 && Date.parse(parsed.interactionExpiresAt) < now) await this.#fs.remove(entry.path);
-				} catch {}
-			}
-		} catch {}
-	}
-};
 /**
 * session history 滚动裁剪：超出预算时裁掉中段，保留首尾。
 * 边界对齐 LLM tool 契约：head 不以未应答的 assistant toolCalls 结尾，
@@ -2700,7 +2981,9 @@ var WebSkillRuntime = class {
 			skillProviders: this.#deps.skillProviders,
 			catalogFilter: this.#deps.catalogFilter,
 			snapshotStore: this.#deps.snapshotStore,
-			skillStateGuard: this.#deps.skillStateGuard
+			skillStateGuard: this.#deps.skillStateGuard,
+			skillIntegrityGuard: this.#deps.skillIntegrityGuard,
+			skillOutcomeReporter: this.#deps.skillOutcomeReporter
 		}, this.#deps.config);
 		const runId = `run-${Math.random().toString(36).slice(2, 10)}`;
 		this.#loops.set(runId, loop);
@@ -2737,14 +3020,14 @@ var WebSkillRuntime = class {
 		});
 		return result;
 	}
-	/** D3：列出可恢复的 interrupted run（供 UI 展示"未完成任务"） */
+	/** D3：列出 interrupted run（供 UI 展示"未完成任务"）；版本不受支持的项带 unsupported 标记 */
 	async listInterruptedRuns() {
 		if (!this.#deps.snapshotStore) return [];
 		return this.#deps.snapshotStore.list();
 	}
 	/**
 	* D3 恢复 interrupted run：
-	* 不存在 → RUN_SNAPSHOT_NOT_FOUND；schemaVersion 不匹配 → 删除 + RUN_SNAPSHOT_INCOMPATIBLE；
+	* 不存在 → RUN_SNAPSHOT_NOT_FOUND；schema 版本不受支持 → RUN_SNAPSHOT_SCHEMA_UNSUPPORTED（由 store 抛出，不删文件）；
 	* 已过期 → interaction-timeout 终态并删快照；否则重建 LoopState 重新发起交互续跑。
 	* @experimental
 	*/
@@ -2752,10 +3035,6 @@ var WebSkillRuntime = class {
 		const store = this.#deps.snapshotStore;
 		const snapshot = store ? await store.load(runId) : void 0;
 		if (!snapshot) throw new WebSkillError("RUN_SNAPSHOT_NOT_FOUND", `No snapshot found for run "${runId}"`);
-		if (snapshot.schemaVersion !== 1) {
-			await store.delete(runId);
-			throw new WebSkillError("RUN_SNAPSHOT_INCOMPATIBLE", `Snapshot for run "${runId}" has incompatible schemaVersion ${String(snapshot.schemaVersion)}`);
-		}
 		if (Date.now() > Date.parse(snapshot.interactionExpiresAt)) {
 			await store.delete(runId);
 			const endedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -2808,7 +3087,9 @@ var WebSkillRuntime = class {
 			skillProviders: this.#deps.skillProviders,
 			catalogFilter: this.#deps.catalogFilter,
 			snapshotStore: store,
-			skillStateGuard: this.#deps.skillStateGuard
+			skillStateGuard: this.#deps.skillStateGuard,
+			skillIntegrityGuard: this.#deps.skillIntegrityGuard,
+			skillOutcomeReporter: this.#deps.skillOutcomeReporter
 		}, this.#deps.config);
 		this.#loops.set(runId, loop);
 		try {
@@ -2927,6 +3208,7 @@ function sourceFromUrl(url) {
 /** 受控钩子执行器：逐个执行，超时/异常默认降级为 warning，可切严格模式 */
 var HookRunner = class {
 	#hooks = /* @__PURE__ */ new Map();
+	/** 宿主可在装配后按 RuntimeConfig 调整（console Settings › Agent Runtime 即经此生效） */
 	timeoutMs;
 	failOnHookError;
 	onWarning;
@@ -2942,6 +3224,15 @@ var HookRunner = class {
 		this.#hooks.set(key, list);
 		return this;
 	}
+	/**
+	* 已注册钩子的**计数**，按注册相位分组（`'*'` 为全相位钩子）。
+	* 刻意不返回函数引用：那会给 UI 一条调用宿主钩子的执行路径，而面板只需要「装没装上」。
+	*/
+	listRegisteredHooks() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const [phase, hooks] of this.#hooks) counts.set(phase, hooks.length);
+		return counts;
+	}
 	async run(phase, ctx) {
 		const hooks = [...this.#hooks.get(phase) ?? [], ...this.#hooks.get("*") ?? []];
 		for (const hook of hooks) try {
@@ -3046,7 +3337,7 @@ var FsMemoryStore = class {
 		for (const entry of await this.#fs.list(this.#root)) await this.#fs.remove(entry.path, { recursive: true });
 	}
 };
-const INDEX_FILE = "index.json";
+const INDEX_FILE$1 = "index.json";
 /**
 * 基于 FileSystemProvider 的 ArtifactStore：产物落盘 <root>/<runId>/<path>，
 * 每次写入同步更新 <root>/<runId>/index.json，新实例可凭索引恢复列表。
@@ -3080,7 +3371,7 @@ var FsArtifactStore = class {
 	}
 	async listArtifacts(runId) {
 		assertSafePathSegment(runId, "runId");
-		const indexPath = `${this.#root}/${runId}/${INDEX_FILE}`;
+		const indexPath = `${this.#root}/${runId}/${INDEX_FILE$1}`;
 		if (!await this.#fs.exists(indexPath)) return [];
 		const raw = await this.#fs.readText(indexPath);
 		try {
@@ -3113,7 +3404,7 @@ var FsArtifactStore = class {
 			metadata: input.metadata
 		};
 		const next = [...(await this.listArtifacts(input.runId)).filter((a) => a.id !== artifact.id), artifact];
-		await this.#fs.writeText(`${this.#root}/${input.runId}/${INDEX_FILE}`, JSON.stringify({ artifacts: next }, null, 2));
+		await this.#fs.writeText(`${this.#root}/${input.runId}/${INDEX_FILE$1}`, JSON.stringify({ artifacts: next }, null, 2));
 		return artifact;
 	}
 };
@@ -3332,6 +3623,417 @@ var CapabilityApproval = class CapabilityApproval {
 		return "allowed";
 	}
 };
+const RUN_TRACE_SCHEMA_VERSION = 1;
+/** 终止原因：取最后一条 run.completed/cancelled/failed 事件的 data.reason */
+function extractEndReason(events) {
+	for (let i = events.length - 1; i >= 0; i--) {
+		const event = events[i];
+		if (event.type === "run.completed" || event.type === "run.cancelled" || event.type === "run.failed") {
+			const reason = event.data?.["reason"];
+			return typeof reason === "string" ? reason : void 0;
+		}
+	}
+}
+function summarize(trace) {
+	const endReason = extractEndReason(trace.events);
+	const durationMs = trace.endedAt === void 0 ? void 0 : Date.parse(trace.endedAt) - Date.parse(trace.startedAt);
+	return {
+		runId: trace.runId,
+		startedAt: trace.startedAt,
+		status: trace.status,
+		activeSkills: trace.activeSkills,
+		eventCount: trace.events.length,
+		turnCount: trace.events.filter((e) => e.type === "llm.request").length,
+		...trace.sessionId !== void 0 ? { sessionId: trace.sessionId } : {},
+		...trace.endedAt !== void 0 ? { endedAt: trace.endedAt } : {},
+		...endReason !== void 0 ? { endReason } : {},
+		...durationMs !== void 0 && Number.isFinite(durationMs) && durationMs >= 0 ? { durationMs } : {}
+	};
+}
+function parseTraceFile(raw, path) {
+	let data;
+	try {
+		data = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (typeof data !== "object" || data === null) return void 0;
+	if (typeof data.runId !== "string" || typeof data.startedAt !== "string") return void 0;
+	const schemaVersion = typeof data.schemaVersion === "number" ? data.schemaVersion : 0;
+	if (schemaVersion > 1) throw new WebSkillError("RUN_TRACE_INCOMPATIBLE", `Run trace "${path}" declares schemaVersion ${schemaVersion}, which is newer than the supported 1`);
+	return {
+		schemaVersion,
+		runId: data.runId,
+		...typeof data.sessionId === "string" ? { sessionId: data.sessionId } : {},
+		startedAt: data.startedAt,
+		...typeof data.endedAt === "string" ? { endedAt: data.endedAt } : {},
+		status: typeof data.status === "string" ? data.status : "unknown",
+		activeSkills: Array.isArray(data.activeSkills) ? data.activeSkills.filter((s) => typeof s === "string") : [],
+		events: Array.isArray(data.events) ? data.events : []
+	};
+}
+const INDEX_FILE = "index.jsonl";
+/**
+* `FileSystemProvider` 后端：`<root>/<runId>.json` 存全量 trace，
+* `<root>/index.jsonl` 是 append-only 的摘要旁路索引。
+*
+* 索引存在的唯一理由是**读次数**：0.0.1 的实现为了拼一份列表要整读每个 trace
+* 文件，点一次指标再来一遍。有了索引，`list()` 与 `metrics()` 各只读一个文件。
+*
+* 索引与 trace 目录发散（写完 trace 崩在追加前）的检测不引入新的读放大：
+* 目录列举本来就要做，比较 `*.json` 个数与索引行数即可；不等则整体重建。
+* @stable
+*/
+var FsRunTraceStore = class {
+	#root;
+	#fs;
+	#onError;
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+		this.#onError = deps.onError ?? ((error, run) => {
+			console.warn(`Failed to persist run trace "${run.id}": ${messageOf(error)}`);
+		});
+	}
+	#path(runId) {
+		return resolveInsideRoot(this.#root, `${runId}.json`);
+	}
+	async put(run) {
+		const trace = {
+			schemaVersion: 1,
+			runId: run.id,
+			sessionId: run.sessionId,
+			startedAt: run.startedAt,
+			...run.endedAt !== void 0 ? { endedAt: run.endedAt } : {},
+			status: run.status === "completed" || run.status === "cancelled" ? run.status : "failed",
+			activeSkills: run.activeSkillNames,
+			events: run.trace
+		};
+		try {
+			await this.#fs.writeText(this.#path(run.id), JSON.stringify(trace, null, 2));
+			await this.#fs.appendText(`${this.#root}/${INDEX_FILE}`, `${JSON.stringify(summarize(trace))}\n`);
+		} catch (e) {
+			this.#onError(e, run);
+		}
+	}
+	async get(runId) {
+		assertSafePathSegment(runId, "run id");
+		const path = this.#path(runId);
+		let raw;
+		try {
+			raw = await this.#fs.readText(path);
+		} catch (e) {
+			if (e instanceof WebSkillError) throw e;
+			throw new WebSkillError("FS_NOT_FOUND", `Trace not found for run ${JSON.stringify(runId)}: ${path}`);
+		}
+		const trace = parseTraceFile(raw, path);
+		if (!trace) throw new WebSkillError("VALIDATION_FAILED", `Trace file is corrupted or malformed: ${path}`);
+		return trace;
+	}
+	async list(filter = {}) {
+		const { summaries } = await this.#readIndex();
+		const matched = applyFilter(summaries, filter);
+		const offset = Math.max(0, filter.offset ?? 0);
+		const sliced = matched.slice(offset);
+		return filter.limit !== void 0 ? sliced.slice(0, Math.max(0, filter.limit)) : sliced;
+	}
+	async metrics(filter = {}) {
+		const { summaries, skipped } = await this.#readIndex();
+		const runs = applyFilter(summaries, filter);
+		const succeeded = runs.filter((r) => r.status === "completed").length;
+		const failedRuns = runs.filter((r) => r.status === "failed");
+		const durations = runs.map((r) => r.durationMs).filter((ms) => ms !== void 0);
+		return {
+			totalRuns: runs.length,
+			succeeded,
+			failed: failedRuns.length,
+			successRate: runs.length === 0 ? 0 : succeeded / runs.length,
+			avgTurns: runs.length === 0 ? 0 : runs.reduce((sum, r) => sum + r.turnCount, 0) / runs.length,
+			skippedRuns: skipped,
+			avgDurationMs: durations.length === 0 ? 0 : durations.reduce((a, b) => a + b, 0) / durations.length,
+			recentFailures: failedRuns.slice(0, 5)
+		};
+	}
+	/** 健康路径恒为「一次目录列举 + 一次索引读」，与 run 数无关。 */
+	async #readIndex() {
+		if (!await this.#fs.exists(this.#root)) return {
+			summaries: [],
+			skipped: 0
+		};
+		const traceCount = (await this.#fs.list(this.#root)).filter((f) => f.type === "file" && f.path.endsWith(".json")).length;
+		const indexPath = `${this.#root}/${INDEX_FILE}`;
+		let lines = [];
+		if (await this.#fs.exists(indexPath)) lines = (await this.#fs.readText(indexPath)).split("\n").filter((line) => line.trim() !== "");
+		if (lines.length !== traceCount) return {
+			summaries: await this.#rebuildIndex(),
+			skipped: 0
+		};
+		const summaries = [];
+		let skipped = 0;
+		for (const line of lines) try {
+			summaries.push(JSON.parse(line));
+		} catch {
+			skipped += 1;
+		}
+		if (skipped > 0) return {
+			summaries: await this.#rebuildIndex(),
+			skipped
+		};
+		return {
+			summaries: sortByStartedAtDesc(summaries),
+			skipped: 0
+		};
+	}
+	/** 异常路径，允许 O(N)：整读全部 trace 文件后用 temp + rename 原子替换索引 */
+	async #rebuildIndex() {
+		const summaries = [];
+		for (const entry of await this.#fs.list(this.#root)) {
+			if (entry.type !== "file" || !entry.path.endsWith(".json")) continue;
+			let trace;
+			try {
+				trace = parseTraceFile(await this.#fs.readText(entry.path), entry.path);
+			} catch {
+				continue;
+			}
+			if (!trace) continue;
+			summaries.push(summarize(trace));
+		}
+		const sorted = sortByStartedAtDesc(summaries);
+		const indexPath = `${this.#root}/${INDEX_FILE}`;
+		const tempPath = `${this.#root}/${INDEX_FILE}.rebuilding`;
+		try {
+			await this.#fs.writeText(tempPath, sorted.map((s) => `${JSON.stringify(s)}\n`).join(""));
+			await this.#fs.rename(tempPath, indexPath);
+		} catch {
+			await this.#fs.remove(tempPath).catch(() => void 0);
+		}
+		return sorted;
+	}
+};
+/** ISO 时间戳可按字典序比较 */
+function sortByStartedAtDesc(summaries) {
+	return [...summaries].sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+function applyFilter(summaries, filter) {
+	let runs = summaries;
+	if (filter.status !== void 0 && filter.status !== "") runs = runs.filter((r) => r.status === filter.status);
+	const q = filter.search?.trim().toLowerCase();
+	if (q !== void 0 && q !== "") runs = runs.filter((r) => r.runId.toLowerCase().includes(q) || r.activeSkills.some((s) => s.toLowerCase().includes(q)));
+	return runs;
+}
+/**
+* 从 run 的 trace 推导终态工具调用列表。
+*
+* 消费者过去要靠自己遍历 trace 才能拿到这份列表，而遍历 trace 的同一段代码
+* 又顺手承担了「补发漏掉的 live 事件」的职责——两件事绑在一起，谁也删不掉。
+* 幂等归 runtime（见 `AgentLoop` 的 per-run 已发集合）之后，
+* 推导终态列表就是纯函数，独立导出。
+* @stable
+*/
+function summarizeToolCalls(run) {
+	const calls = [];
+	for (const event of run.trace) {
+		if (event.type !== "tool.completed" && event.type !== "tool.failed") continue;
+		const name = event.data?.["name"];
+		const callId = event.data?.["callId"];
+		if (typeof name !== "string" || typeof callId !== "string") continue;
+		const args = event.data?.["args"];
+		const durationMs = event.data?.["durationMs"];
+		calls.push({
+			callId,
+			name,
+			status: event.type === "tool.completed" ? "completed" : "failed",
+			...typeof args === "string" ? { args } : {},
+			...typeof durationMs === "number" ? { durationMs } : {}
+		});
+	}
+	return calls;
+}
+const SESSION_SCHEMA_VERSION = 1;
+/** `FsSessionStore` 的缺省页长。缺省值属于实现，不属于调用方——否则「下推」只推了一半 */
+const FS_SESSION_PAGE_SIZE = 50;
+const toMeta = (record) => ({
+	id: record.id,
+	createdAt: record.createdAt,
+	...record.title !== void 0 ? { title: record.title } : {},
+	...record.titleLocked === true ? { titleLocked: true } : {},
+	...record.archived === true ? { archived: true } : {},
+	messageCount: record.messages.length
+});
+const newSessionId = () => `session-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+/**
+* 从新到旧的一页：无游标取末尾 `limit` 条，有游标取该位置**之前**的 `limit` 条。
+* 游标编码成「本页起点下标」——对会话文件这种整体重写的存储来说下标是稳定的，
+* 但它是不透明串，调用方不得自己构造（构造出来的越界值一律按 `VALIDATION_FAILED` 拒绝）。
+*/
+function takeTailPage(all, options, what) {
+	const limit = options.limit ?? 50;
+	if (!Number.isInteger(limit) || limit <= 0) throw new WebSkillError("VALIDATION_FAILED", `Page limit must be a positive integer, received ${String(limit)}`);
+	let end = all.length;
+	if (options.cursor !== void 0) {
+		end = Number(options.cursor);
+		if (!Number.isInteger(end) || end < 0 || end > all.length) throw new WebSkillError("VALIDATION_FAILED", `Invalid ${what} cursor: ${JSON.stringify(options.cursor)}`);
+	}
+	const start = Math.max(0, end - limit);
+	return {
+		items: all.slice(start, end),
+		...start > 0 ? { nextCursor: String(start) } : {}
+	};
+}
+/**
+* 解析会话文件。缺 `schemaVersion` 视为 0（0.0.1 时代文件，兼容读）；
+* 高于当前版本拒绝读，避免新版写的字段被旧版静默丢弃。
+*/
+function parseSessionFile(raw, path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (e) {
+		throw new WebSkillError("VALIDATION_FAILED", `Session file is not valid JSON: ${path}`, e);
+	}
+	if (typeof parsed !== "object" || parsed === null) throw new WebSkillError("VALIDATION_FAILED", `Session file is not an object: ${path}`);
+	const file = parsed;
+	const schemaVersion = typeof file.schemaVersion === "number" ? file.schemaVersion : 0;
+	if (schemaVersion > 1) throw new WebSkillError("SESSION_INCOMPATIBLE", `Session file at ${path} has schemaVersion ${schemaVersion}, but this build understands at most 1`);
+	if (typeof file.id !== "string" || typeof file.createdAt !== "string") throw new WebSkillError("VALIDATION_FAILED", `Session file is missing "id" or "createdAt": ${path}`);
+	return {
+		schemaVersion,
+		id: file.id,
+		createdAt: file.createdAt,
+		...typeof file.title === "string" ? { title: file.title } : {},
+		...file.titleLocked === true ? { titleLocked: true } : {},
+		...file.archived === true ? { archived: true } : {},
+		messages: Array.isArray(file.messages) ? file.messages : [],
+		messageCount: Array.isArray(file.messages) ? file.messages.length : 0
+	};
+}
+/**
+* `FileSystemProvider` 后端的会话存储：`<root>/<id>.json`。
+*
+* 所有变更操作按 id 串到一条 promise 链上：会话文件是整读整写的，
+* 两个并发 `appendMessages` 若都先读后写，后写的会覆盖先写的那条消息。
+*/
+var FsSessionStore = class {
+	#root;
+	#fs;
+	/** id → 该 id 上最后一次变更的完成时点，用于串行化读改写 */
+	#writes = /* @__PURE__ */ new Map();
+	constructor(deps) {
+		this.#root = deps.root.replace(/\/+$/, "");
+		this.#fs = deps.fs;
+	}
+	#path(id) {
+		assertSafePathSegment(id, "session id");
+		return resolveInsideRoot(this.#root, `${id}.json`);
+	}
+	/** 把 mutation 排到该 id 的队尾；前一个失败不阻塞后一个 */
+	async #serialize(id, work) {
+		const next = (this.#writes.get(id) ?? Promise.resolve()).catch(() => void 0).then(work);
+		this.#writes.set(id, next);
+		try {
+			return await next;
+		} finally {
+			if (this.#writes.get(id) === next) this.#writes.delete(id);
+		}
+	}
+	async #write(record) {
+		const file = {
+			schemaVersion: 1,
+			id: record.id,
+			createdAt: record.createdAt,
+			...record.title !== void 0 ? { title: record.title } : {},
+			...record.titleLocked === true ? { titleLocked: true } : {},
+			...record.archived === true ? { archived: true } : {},
+			messages: record.messages
+		};
+		await this.#fs.writeText(this.#path(record.id), JSON.stringify(file, null, 2));
+	}
+	async #require(id) {
+		const record = await this.get(id);
+		if (!record) throw new WebSkillError("FS_NOT_FOUND", `Session "${id}" not found under ${this.#root}`);
+		return record;
+	}
+	async list(options = {}) {
+		if (!await this.#fs.exists(this.#root)) return { items: [] };
+		const metas = [];
+		for (const entry of await this.#fs.list(this.#root)) {
+			if (entry.type !== "file" || !entry.path.endsWith(".json")) continue;
+			let record;
+			try {
+				record = parseSessionFile(await this.#fs.readText(entry.path), entry.path);
+			} catch (e) {
+				console.warn(`Skipping unreadable session file "${entry.path}": ${e instanceof Error ? e.message : String(e)}`);
+				continue;
+			}
+			if (record.archived === true && options.includeArchived !== true) continue;
+			metas.push(toMeta(record));
+		}
+		metas.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+		return takeTailPage(metas, options, "session");
+	}
+	/**
+	* 整文件读后切片。磁盘 I/O 复杂度没有改善（备案 D25），
+	* 但**跨出端口的记录数**已是常量——这正是分页对上层的意义。
+	*/
+	async listMessages(id, options = {}) {
+		return takeTailPage((await this.#require(id)).messages, options, "message");
+	}
+	async get(id) {
+		const path = this.#path(id);
+		if (!await this.#fs.exists(path)) return void 0;
+		return parseSessionFile(await this.#fs.readText(path), path);
+	}
+	async create(init = {}) {
+		const record = {
+			schemaVersion: 1,
+			id: init.id ?? newSessionId(),
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...init.title !== void 0 ? { title: init.title } : {},
+			messages: [],
+			messageCount: 0
+		};
+		return this.#serialize(record.id, async () => {
+			await this.#write(record);
+			return toMeta(record);
+		});
+	}
+	async appendMessages(id, messages) {
+		if (messages.length === 0) return;
+		await this.#serialize(id, async () => {
+			const record = await this.#require(id);
+			record.messages.push(...messages);
+			await this.#write(record);
+		});
+	}
+	async replaceMessages(id, messages) {
+		await this.#serialize(id, async () => {
+			const record = await this.#require(id);
+			record.messages = [...messages];
+			await this.#write(record);
+		});
+	}
+	async setTitle(id, title, options = {}) {
+		await this.#serialize(id, async () => {
+			const record = await this.#require(id);
+			record.title = title;
+			if (options.lock === true) record.titleLocked = true;
+			await this.#write(record);
+		});
+	}
+	async setArchived(id, archived) {
+		await this.#serialize(id, async () => {
+			const record = await this.#require(id);
+			record.archived = archived;
+			await this.#write(record);
+		});
+	}
+	async delete(id) {
+		await this.#serialize(id, async () => {
+			const path = this.#path(id);
+			if (await this.#fs.exists(path)) await this.#fs.remove(path);
+		});
+	}
+};
 
 //#endregion
-export { fromVercelStreamPart as A, schemaToForm as B, bridgeError as C, extractChartSpec as D, createWebSkillApi as E, normalizeErrorCode as F, toVercelToolSpecs as H, normalizeToolContent as I, normalizeToolError as L, mergeCatalogEntries as M, networkPolicyLibSource as N, extractUiSurfaceEvents as O, networkUrlHost as P, parseBridgeRequest as R, WebSkillRuntime as S, createScriptContext as T, validateUiSurface as U, toLlmToolSpec as V, validateUiSurfaceEvent as W, READ_SKILL_FILE_TOOL as _, AnthropicClient as a, SerializingMemoryStore as b, FsArtifactStore as c, FullDisclosureRouter as d, GoogleGenAiClient as f, READ_SKILL_FILE_INPUT_SCHEMA as g, ProgressiveRouter as h, AgentLoop as i, isNetworkAllowed as j, fromVercelResult as k, FsMemoryStore as l, OpenAiCompatibleClient as m, ASK_USER_TOOL as n, CapabilityApproval as o, HookRunner as p, ASK_USER_TOOL_NAME as r, EventBus as s, ASK_USER_INPUT_SCHEMA as t, FsRunSnapshotStore as u, READ_SKILL_FILE_TOOL_NAME as v, buildRenderResult as w, TraceRecorder as x, RUN_SNAPSHOT_SCHEMA_VERSION as y, resolveToolName as z };
+export { createScriptContext as A, networkUrlHost as B, RUN_TRACE_SCHEMA_VERSION as C, WebSkillRuntime as D, TraceRecorder as E, fromVercelStreamPart as F, resolveToolName as G, normalizeToolContent as H, isNetworkAllowed as I, toLlmToolSpec as J, schemaToForm as K, isUnsupportedRunSnapshot as L, extractChartSpec as M, extractUiSpecEvents as N, bridgeError as O, fromVercelResult as P, mergeCatalogEntries as R, RUN_SNAPSHOT_SCHEMA_VERSION as S, SerializingMemoryStore as T, normalizeToolError as U, normalizeErrorCode as V, parseBridgeRequest as W, validateUiSpecEvent as X, toVercelToolSpecs as Y, validateUiSpecNode as Z, OpenAiCompatibleClient as _, AnthropicClient as a, READ_SKILL_FILE_TOOL as b, FS_SESSION_PAGE_SIZE as c, FsRunSnapshotStore as d, FsRunTraceStore as f, HookRunner as g, GoogleGenAiClient as h, AgentLoop as i, createWebSkillApi as j, buildRenderResult as k, FsArtifactStore as l, FullDisclosureRouter as m, ASK_USER_TOOL as n, CapabilityApproval as o, FsSessionStore as p, summarizeToolCalls as q, ASK_USER_TOOL_NAME as r, EventBus as s, ASK_USER_INPUT_SCHEMA as t, FsMemoryStore as u, ProgressiveRouter as v, SESSION_SCHEMA_VERSION as w, READ_SKILL_FILE_TOOL_NAME as x, READ_SKILL_FILE_INPUT_SCHEMA as y, networkPolicyLibSource as z };