@webskill/sdk 0.3.0 → 0.5.0

package/dist/{dist-rorEJsNi.js → dist-6C03DShK.js}

@@ -1,5 +1,5 @@
 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 { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.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() {
@@ -47,27 +47,65 @@ function createSseFrameReader() {
 		}
 	};
 }
+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) => ({
@@ -181,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)
@@ -234,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
 			};
@@ -245,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;
@@ -255,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);
@@ -266,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,
@@ -285,7 +352,7 @@ function toAnthropicMessages(messages) {
 		}
 		out.push({
 			role: msg.role,
-			content: msg.content
+			content: toAnthropicBlocks(msg.content, msg.role)
 		});
 	}
 	return system === "" ? { messages: out } : {
@@ -409,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,
@@ -455,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
 			};
@@ -465,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 {
@@ -475,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 = [];
@@ -485,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);
@@ -496,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
@@ -510,7 +595,7 @@ function toGenAiContents(messages) {
 		}
 		out.push({
 			role: "user",
-			parts: [{ text: msg.content }]
+			parts: toGenAiParts(msg.content, msg.role)
 		});
 	}
 	return system === "" ? { contents: out } : {
@@ -546,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
 		};
@@ -602,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;
@@ -677,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
 	};
@@ -905,22 +991,22 @@ function createScriptContext(deps) {
 		...onWarning ? { onWarning } : {}
 	};
 }
-const isRecord$2 = (v) => typeof v === "object" && v !== null;
+const isRecord$3 = (v) => typeof v === "object" && v !== null;
 /**
 * $chart 约定的形状校验：JSON content 的 data 含 $chart 键且形状合法 → ChartSpec；
 * 任何畸形（kind 非法 / labels 非字符串数组 / series 项缺数值 data）→ undefined（忽略不炸）。
 */
 function extractChartSpec(data) {
-	if (!isRecord$2(data)) return void 0;
+	if (!isRecord$3(data)) return void 0;
 	const raw = data["$chart"];
-	if (!isRecord$2(raw)) return void 0;
+	if (!isRecord$3(raw)) return void 0;
 	const { kind, labels, series } = raw;
 	if (kind !== "bar" && kind !== "line" && kind !== "pie") return void 0;
 	if (!Array.isArray(labels) || !labels.every((l) => typeof l === "string")) return void 0;
 	if (!Array.isArray(series)) return void 0;
 	const validSeries = [];
 	for (const item of series) {
-		if (!isRecord$2(item) || !Array.isArray(item["data"]) || !item["data"].every((n) => typeof n === "number")) return;
+		if (!isRecord$3(item) || !Array.isArray(item["data"]) || !item["data"].every((n) => typeof n === "number")) return;
 		const name = item["name"];
 		validSeries.push({
 			...typeof name === "string" ? { name } : {},
@@ -960,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([
@@ -974,17 +1057,7 @@ 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) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function reject(message) {
@@ -1001,120 +1074,66 @@ function isJsonValue(value, depth = 0) {
 	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
 	if (typeof value === "number") return Number.isFinite(value);
 	if (Array.isArray(value)) return value.every((item) => isJsonValue(item, depth + 1));
-	if (!isRecord$1(value)) return false;
+	if (!isRecord$2(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$2(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$2(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");
+		if (!isRecord$2(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) {
-	if (!isRecord$1(value)) reject("A surface patch operation must be an object");
+	if (!isRecord$2(value)) reject("A surface patch operation must be an object");
 	if (value["op"] !== "replace" && value["op"] !== "merge" && value["op"] !== "append") reject("Surface patch operation is invalid");
 	requireString(value["path"], "Surface patch path");
 	if (!value["path"].startsWith("/")) reject("Surface patch path must be a JSON pointer");
 	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) {
-	if (!isRecord$1(value) || typeof value["type"] !== "string") reject("A UI surface event must have a type");
+function validateUiSpecEvent(value) {
+	if (!isRecord$2(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");
@@ -1159,17 +1178,75 @@ function validateUiSurfaceEvent(value) {
 	}
 }
 /** Extracts validated surface stream events from structured tool output. @experimental */
-function extractUiSurfaceEvents(data) {
-	if (!isRecord$1(data) || data["$surface"] === void 0) return [];
+function extractUiSpecEvents(data) {
+	if (!isRecord$2(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));
+}
+/** 跨会话表单填写值在 `user:{userId}` scope 下的 key（FR-5.7） @experimental */
+const FORM_VALUES_KEY = "formValues";
+/**
+* 跨会话稳定的字段标识（FR-5.6）。必须带技能名：
+* 只有字段名时，两个技能各自的 `email` 会互相串号。
+* @experimental
+*/
+function formFieldKey(skillName, fieldName) {
+	return `${skillName}#${fieldName}`;
+}
+/** memory 里的原始值形状不受控（宿主可能手改文件），逐条过滤而不是整体信任 @experimental */
+function readFormValues(raw) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
+	const out = {};
+	for (const [key, entry] of Object.entries(raw)) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const record = entry;
+		if (typeof record.ts !== "number" || !("value" in record)) continue;
+		out[key] = {
+			value: record.value,
+			ts: record.ts
+		};
+	}
+	return out;
+}
+/** 合并本次提交并按上限裁剪最旧（FR-5.12） @experimental */
+function putFormValues(current, updates, limit) {
+	const merged = {
+		...current,
+		...updates
+	};
+	const keys = Object.keys(merged);
+	if (limit <= 0) return {};
+	if (keys.length <= limit) return merged;
+	const kept = keys.sort((a, b) => merged[a].ts - merged[b].ts).slice(keys.length - limit);
+	return Object.fromEntries(kept.map((key) => [key, merged[key]]));
+}
+/** 清除单个字段；不传 fieldKey 即全部清除（FR-5.11） @experimental */
+function clearFormValues(current, fieldKey) {
+	if (fieldKey === void 0) return {};
+	const { [fieldKey]: _removed, ...rest } = current;
+	return rest;
+}
+/**
+* 宿主侧的清除入口（FR-5.11）：设置面板的「清除填写历史」直接调它，
+* 不必自己知道 scope 与 key 的约定。
+* @experimental
+*/
+async function clearStoredFormValues(memory, userId, fieldKey) {
+	const scope = `user:${userId}`;
+	if (fieldKey === void 0) {
+		await memory.delete(scope, FORM_VALUES_KEY);
+		return;
+	}
+	const next = clearFormValues(readFormValues(await memory.get(scope, FORM_VALUES_KEY)), fieldKey);
+	await memory.set(scope, FORM_VALUES_KEY, next);
 }
 /**
 * JsonSchema → 表单模型：按 properties 生成字段，required 标记必填；
 * providedArgs 已有的值作为 defaultValue 预填（表单只为补齐缺失项服务）。
 * type 映射：string→text、number/integer→number、boolean→boolean、enum→select、其余→textarea。
+* 传入 skillName 时给每个字段带上跨会话稳定的 `fieldKey`（FR-5.6）。
 */
-function schemaToForm(schema, providedArgs) {
+function schemaToForm(schema, providedArgs, options) {
 	const required = new Set(Array.isArray(schema.required) ? schema.required : []);
 	const fields = [];
 	for (const [name, prop] of Object.entries(schema.properties ?? {})) {
@@ -1180,6 +1257,7 @@ function schemaToForm(schema, providedArgs) {
 			type: mapFieldType(prop),
 			...required.has(name) ? { required: true } : {},
 			...typeof prop.description === "string" ? { description: prop.description } : {},
+			...options?.skillName !== void 0 ? { fieldKey: formFieldKey(options.skillName, name) } : {},
 			...provided !== void 0 ? { defaultValue: provided } : prop.default !== void 0 ? { defaultValue: prop.default } : {}
 		};
 		if (Array.isArray(prop.enum)) field.options = prop.enum.map((v) => ({
@@ -1309,6 +1387,133 @@ var TraceRecorder = class {
 		return [...this.#events];
 	}
 };
+const isRecord$1 = (v) => typeof v === "object" && v !== null;
+/** 工具结果可经 `$todo` 标记记入 trace 的事件类型；其余类型不接受，防止工具源伪造 run.* */
+const TODO_TRACE_TYPES = /* @__PURE__ */ new Set([
+	"todo.created",
+	"todo.updated",
+	"todo.cleared"
+]);
+/**
+* `$todo` 约定的形状校验：JSON content 的 data 含 `$todo` 键（单条或数组）→ trace 事件。
+*
+* 与 `$chart` / `$surface` 同一条既有通道——待办清单的状态机全部在 `@webskill/agent`，
+* runtime 只认这三个事件类型名，不含任何计划态逻辑。畸形条目忽略不炸。
+* @experimental
+*/
+function extractTodoTraceEvents(data) {
+	if (!isRecord$1(data) || data["$todo"] === void 0) return [];
+	const raw = data["$todo"];
+	const entries = Array.isArray(raw) ? raw : [raw];
+	const events = [];
+	for (const entry of entries) {
+		if (!isRecord$1(entry)) continue;
+		const { type, ...rest } = entry;
+		if (typeof type !== "string" || !TODO_TRACE_TYPES.has(type)) continue;
+		events.push({
+			type,
+			data: rest
+		});
+	}
+	return 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 里写的形态。
 * `<已激活技能>__<脚本>` 保持原样（裸标识符按技能作用域单独匹配），
@@ -1338,7 +1543,7 @@ 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. It is still available in 0.3.0 but WILL BE REJECTED in 0.4.0. Add "${canonical}"${slash > 0 ? ` or "${canonical.slice(0, slash)}/*"` : ""} to allowed-tools.`;
+	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.`;
 }
 /**
 * 多技能语义：无人声明 → 不受限；有人声明 → 命中任一清单，
@@ -1379,7 +1584,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 继续循环；
@@ -1404,6 +1608,7 @@ var AgentLoop = class {
 			toolTimeoutMs: config.toolTimeoutMs ?? 3e4,
 			toolResultMaxBytes: config.toolResultMaxBytes ?? 1e5,
 			paramHistoryLimit: config.paramHistoryLimit ?? 50,
+			formValueLimit: config.formValueLimit ?? 100,
 			temperature: config.temperature,
 			renderResult: config.renderResult
 		};
@@ -1450,6 +1655,7 @@ var AgentLoop = class {
 			activatedTools: /* @__PURE__ */ new Map(),
 			skillAllowedTools: /* @__PURE__ */ new Map(),
 			warnedDeniedTools: /* @__PURE__ */ new Set(),
+			integrityVerdicts: /* @__PURE__ */ new Map(),
 			toolTimeoutMs: this.#config.toolTimeoutMs,
 			now,
 			interactionSeq: 0,
@@ -1478,7 +1684,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();
@@ -1487,15 +1699,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 {
@@ -1527,17 +1749,25 @@ var AgentLoop = class {
 	}
 	/**
 	* D10 判定的唯一出口（暴露点 + 分发点共用）。
-	* 0.3.0 只记警告并返回 false，调用点照常放行；0.4.0 收紧时改的是调用点对返回值的处理。
+	* 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("run.warning", { message: verdict.reason ?? `Tool "${toolName}" is not allowed` });
+			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);
@@ -1549,8 +1779,7 @@ 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];
-				for (const spec of skillToolSpecs) this.#checkToolAccess(state, spec.name);
+				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)] : [],
@@ -1584,22 +1813,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) {
@@ -1613,7 +1849,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);
 				}
@@ -1659,7 +1895,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)}` });
 		}
@@ -1675,7 +1914,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,
@@ -1736,6 +1975,7 @@ var AgentLoop = class {
 			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,
@@ -1784,7 +2024,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) {
@@ -1806,7 +2046,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) {
@@ -1814,7 +2054,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);
 			}
@@ -1825,7 +2065,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);
 			}
@@ -1868,7 +2108,7 @@ var AgentLoop = class {
 				sessionId: state.run.sessionId,
 				ts: state.now(),
 				data: {
-					type: "llm.delta",
+					kind: "llm-delta",
 					delta
 				}
 			});
@@ -1882,23 +2122,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
 		});
@@ -1925,10 +2165,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,
@@ -1961,7 +2205,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;
 	}
@@ -1995,8 +2245,8 @@ 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 {
-			this.#checkToolAccess(state, call.name);
 			const resolution = resolveToolName(call.name, state.activated);
 			if (resolution.kind === "script") result = await this.#handleScriptTool(call, resolution.skillName, resolution.scriptName, state);
 			else {
@@ -2020,8 +2270,9 @@ var AgentLoop = class {
 					type: "chart",
 					chart
 				});
+				for (const todo of extractTodoTraceEvents(item.data)) state.trace.record(todo.type, { data: todo.data });
 				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)}`,
@@ -2040,7 +2291,7 @@ var AgentLoop = class {
 					durationMs
 				}
 			});
-			this.#emitTool(state, "failed", call);
+			this.#emitTool(state, "failed", call, result.error?.code);
 		}
 		for (const artifact of result.artifacts ?? []) state.trace.record("artifact.created", { data: {
 			artifactId: artifact.id,
@@ -2060,14 +2311,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
@@ -2085,21 +2336,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. */
@@ -2126,13 +2373,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) {
@@ -2144,20 +2391,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: {
@@ -2165,9 +2418,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({
@@ -2205,7 +2466,7 @@ var AgentLoop = class {
 	* 集合挂在 LoopState 上、**不写进快照**：写进快照会让跨进程恢复的
 	* 消费者永远收不到它本来就没见过的事件。
 	*/
-	#emitTool(state, status, call) {
+	#emitTool(state, status, call, errorCode) {
 		const key = `${call.id}:${status}`;
 		if (state.emittedToolEvents.has(key)) return;
 		state.emittedToolEvents.add(key);
@@ -2215,11 +2476,12 @@ var AgentLoop = class {
 			sessionId: state.run.sessionId,
 			ts: state.now(),
 			data: {
-				type: "tool",
+				kind: "tool",
 				status,
 				name: call.name,
 				callId: call.id,
-				args: summarizeArgs(call.arguments)
+				args: summarizeArgs(call.arguments),
+				...errorCode !== void 0 ? { errorCode } : {}
 			}
 		});
 	}
@@ -2285,7 +2547,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 {
@@ -2339,18 +2607,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 "";
@@ -2441,11 +2753,13 @@ var AgentLoop = class {
 		let args = call.arguments;
 		const missing = (def.inputSchema?.required ?? []).filter((key) => args[key] === void 0);
 		if (missing.length > 0 && this.#deps.uiBridge && this.#policy.missingParams === "user" && def.inputSchema) try {
+			const fields = schemaToForm(def.inputSchema, args, { skillName });
+			await this.#attachFormSuggestions(fields, state);
 			const value = await this.#interact(state, {
 				type: "form",
 				id: this.#nextInteractionId(state),
 				title: `Missing parameters for ${call.name}`,
-				fields: schemaToForm(def.inputSchema, args)
+				fields
 			}, {
 				tool: call.name,
 				missing
@@ -2484,11 +2798,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 */
@@ -2587,6 +2931,47 @@ var AgentLoop = class {
 			});
 			return history.slice(-limit);
 		});
+		await this.#rememberFormValues(state, request, value);
+	}
+	/**
+	* 跨会话字段值的写入（FR-5.6/5.12）。与 `paramHistory` 双写而不是合并：
+	* 那边是按时间的追加序列（运行观测），这边是按字段的最新值（召回），形态不同。
+	*/
+	async #rememberFormValues(state, request, value) {
+		const autofill = this.#deps.formAutofill;
+		if (!autofill || request.type !== "form") return;
+		if (typeof value !== "object" || value === null) return;
+		const submitted = value;
+		const ts = Date.parse(state.now());
+		const updates = {};
+		for (const field of request.fields) {
+			if (field.fieldKey === void 0) continue;
+			const next = submitted[field.name];
+			if (next === void 0 || next === "") continue;
+			updates[field.fieldKey] = {
+				value: next,
+				ts
+			};
+		}
+		if (Object.keys(updates).length === 0) return;
+		await this.#memoryMutate(`user:${autofill.userId}`, FORM_VALUES_KEY, state, (current) => putFormValues(readFormValues(current), updates, this.#config.formValueLimit));
+	}
+	/**
+	* 召回（FR-5.8）：命中的历史值挂在 `suggestion` 上，**绝不写进 `defaultValue`**——
+	* 后者会被渲染器直接填进控件，等于静默预填（AC-5.6 禁止）。
+	*/
+	async #attachFormSuggestions(fields, state) {
+		const autofill = this.#deps.formAutofill;
+		if (!autofill) return;
+		const stored = readFormValues(await this.#memoryGet(`user:${autofill.userId}`, FORM_VALUES_KEY, state));
+		for (const field of fields) {
+			if (field.fieldKey === void 0 || field.defaultValue !== void 0) continue;
+			const hit = stored[field.fieldKey];
+			if (hit !== void 0) field.suggestion = {
+				value: hit.value,
+				ts: hit.ts
+			};
+		}
 	}
 };
 /**
@@ -2598,79 +2983,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 结尾，
@@ -2800,11 +3112,14 @@ var WebSkillRuntime = class {
 			hooks: this.#deps.hooks,
 			eventBus: this.#events,
 			longTerm: this.#deps.longTerm,
+			formAutofill: this.#deps.formAutofill,
 			externalTools: this.#deps.externalTools,
 			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);
@@ -2841,14 +3156,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
 	*/
@@ -2856,10 +3171,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();
@@ -2908,11 +3219,14 @@ var WebSkillRuntime = class {
 			hooks: this.#deps.hooks,
 			eventBus: this.#events,
 			longTerm: this.#deps.longTerm,
+			formAutofill: this.#deps.formAutofill,
 			externalTools: this.#deps.externalTools,
 			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 {
@@ -3031,6 +3345,7 @@ function sourceFromUrl(url) {
 /** 受控钩子执行器：逐个执行，超时/异常默认降级为 warning，可切严格模式 */
 var HookRunner = class {
 	#hooks = /* @__PURE__ */ new Map();
+	/** 宿主可在装配后按 RuntimeConfig 调整（console Settings › Agent Runtime 即经此生效） */
 	timeoutMs;
 	failOnHookError;
 	onWarning;
@@ -3046,6 +3361,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 {
@@ -3652,17 +3976,22 @@ function summarizeToolCalls(run) {
 		if (typeof name !== "string" || typeof callId !== "string") continue;
 		const args = event.data?.["args"];
 		const durationMs = event.data?.["durationMs"];
+		const errorCode = event.data?.["code"];
 		calls.push({
 			callId,
 			name,
 			status: event.type === "tool.completed" ? "completed" : "failed",
 			...typeof args === "string" ? { args } : {},
-			...typeof durationMs === "number" ? { durationMs } : {}
+			...typeof durationMs === "number" ? { durationMs } : {},
+			...typeof errorCode === "string" ? { errorCode } : {},
+			...event.type === "tool.failed" && typeof event.message === "string" ? { errorMessage: event.message } : {}
 		});
 	}
 	return calls;
 }
 const SESSION_SCHEMA_VERSION = 1;
+/** `FsSessionStore` 的缺省页长。缺省值属于实现，不属于调用方——否则「下推」只推了一半 */
+const FS_SESSION_PAGE_SIZE = 50;
 const toMeta = (record) => ({
 	id: record.id,
 	createdAt: record.createdAt,
@@ -3673,6 +4002,25 @@ const toMeta = (record) => ({
 });
 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 时代文件，兼容读）；
 * 高于当前版本拒绝读，避免新版写的字段被旧版静默丢弃。
 */
@@ -3746,7 +4094,7 @@ var FsSessionStore = class {
 		return record;
 	}
 	async list(options = {}) {
-		if (!await this.#fs.exists(this.#root)) return [];
+		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;
@@ -3760,7 +4108,15 @@ var FsSessionStore = class {
 			if (record.archived === true && options.includeArchived !== true) continue;
 			metas.push(toMeta(record));
 		}
-		return metas.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+		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);
@@ -3820,4 +4176,4 @@ var FsSessionStore = class {
 };
 
 //#endregion
-export { createWebSkillApi as A, normalizeToolContent as B, SESSION_SCHEMA_VERSION as C, bridgeError as D, WebSkillRuntime as E, isNetworkAllowed as F, summarizeToolCalls as G, parseBridgeRequest as H, mergeCatalogEntries as I, validateUiSurface as J, toLlmToolSpec as K, networkPolicyLibSource as L, extractUiSurfaceEvents as M, fromVercelResult as N, buildRenderResult as O, fromVercelStreamPart as P, networkUrlHost as R, RUN_TRACE_SCHEMA_VERSION as S, TraceRecorder as T, resolveToolName as U, normalizeToolError as V, schemaToForm as W, validateUiSurfaceEvent as Y, ProgressiveRouter as _, AnthropicClient as a, READ_SKILL_FILE_TOOL_NAME as b, FsArtifactStore as c, FsRunTraceStore as d, FsSessionStore as f, OpenAiCompatibleClient as g, HookRunner as h, AgentLoop as i, extractChartSpec as j, createScriptContext as k, FsMemoryStore as l, GoogleGenAiClient as m, ASK_USER_TOOL as n, CapabilityApproval as o, FullDisclosureRouter as p, toVercelToolSpecs as q, ASK_USER_TOOL_NAME as r, EventBus as s, ASK_USER_INPUT_SCHEMA as t, FsRunSnapshotStore as u, READ_SKILL_FILE_INPUT_SCHEMA as v, SerializingMemoryStore as w, RUN_SNAPSHOT_SCHEMA_VERSION as x, READ_SKILL_FILE_TOOL as y, normalizeErrorCode as z };
+export { schemaToForm as $, buildRenderResult as A, fromVercelStreamPart as B, RUN_SNAPSHOT_SCHEMA_VERSION as C, TraceRecorder as D, SerializingMemoryStore as E, extractChartSpec as F, networkUrlHost as G, isUnsupportedRunSnapshot as H, extractTodoTraceEvents as I, normalizeToolError as J, normalizeErrorCode as K, extractUiSpecEvents as L, clearStoredFormValues as M, createScriptContext as N, WebSkillRuntime as O, createWebSkillApi as P, resolveToolName as Q, formFieldKey as R, READ_SKILL_FILE_TOOL_NAME as S, SESSION_SCHEMA_VERSION as T, mergeCatalogEntries as U, isNetworkAllowed as V, networkPolicyLibSource as W, putFormValues as X, parseBridgeRequest as Y, readFormValues as Z, HookRunner as _, AnthropicClient as a, READ_SKILL_FILE_INPUT_SCHEMA as b, FORM_VALUES_KEY as c, FsMemoryStore as d, summarizeToolCalls as et, FsRunSnapshotStore as f, GoogleGenAiClient as g, FullDisclosureRouter as h, AgentLoop as i, validateUiSpecNode as it, clearFormValues as j, bridgeError as k, FS_SESSION_PAGE_SIZE as l, FsSessionStore as m, ASK_USER_TOOL as n, toVercelToolSpecs as nt, CapabilityApproval as o, FsRunTraceStore as p, normalizeToolContent as q, ASK_USER_TOOL_NAME as r, validateUiSpecEvent as rt, EventBus as s, ASK_USER_INPUT_SCHEMA as t, toLlmToolSpec as tt, FsArtifactStore as u, OpenAiCompatibleClient as v, RUN_TRACE_SCHEMA_VERSION as w, READ_SKILL_FILE_TOOL as x, ProgressiveRouter as y, fromVercelResult as z };