@webskill/sdk 0.2.6 → 0.2.8

package/dist/{dist-BXpDDZpR.js → dist-B9VLwOME.js}

@@ -125,13 +125,17 @@ var OpenAiCompatibleClient = class {
 			type: "tool-calls",
 			toolCalls: [...toolCallsByIndex.entries()].sort(([a], [b]) => a - b).map(([index, acc]) => {
 				let args = {};
+				let parseError;
 				try {
 					args = JSON.parse(acc.arguments || "{}");
-				} catch {}
+				} catch (e) {
+					parseError = e instanceof Error ? e.message : String(e);
+				}
 				return {
 					id: acc.id || `call-${index}`,
 					name: acc.name,
-					arguments: args
+					arguments: args,
+					...parseError ? { argumentsParseError: parseError } : {}
 				};
 			})
 		};
@@ -358,13 +362,17 @@ var AnthropicClient = class {
 			type: "tool-calls",
 			toolCalls: [...toolCallsByIndex.entries()].sort(([a], [b]) => a - b).map(([index, acc]) => {
 				let args = {};
+				let parseError;
 				try {
 					args = JSON.parse(acc.arguments || "{}");
-				} catch {}
+				} catch (e) {
+					parseError = e instanceof Error ? e.message : String(e);
+				}
 				return {
 					id: acc.id || `call-${index}`,
 					name: acc.name,
-					arguments: args
+					arguments: args,
+					...parseError ? { argumentsParseError: parseError } : {}
 				};
 			})
 		};
@@ -875,22 +883,22 @@ function createScriptContext(deps) {
 		...onWarning ? { onWarning } : {}
 	};
 }
-const isRecord$1 = (v) => typeof v === "object" && v !== null;
+const isRecord$2 = (v) => typeof v === "object" && v !== null;
 /**
 * $chart 约定的形状校验：JSON content 的 data 含 $chart 键且形状合法 → ChartSpec；
 * 任何畸形（kind 非法 / labels 非字符串数组 / series 项缺数值 data）→ undefined（忽略不炸）。
 */
 function extractChartSpec(data) {
-	if (!isRecord$1(data)) return void 0;
+	if (!isRecord$2(data)) return void 0;
 	const raw = data["$chart"];
-	if (!isRecord$1(raw)) return void 0;
+	if (!isRecord$2(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$1(item) || !Array.isArray(item["data"]) || !item["data"].every((n) => typeof n === "number")) return;
+		if (!isRecord$2(item) || !Array.isArray(item["data"]) || !item["data"].every((n) => typeof n === "number")) return;
 		const name = item["name"];
 		validSeries.push({
 			...typeof name === "string" ? { name } : {},
@@ -928,6 +936,212 @@ function buildRenderResult(run, output, renderBlocks = []) {
 		artifacts: run.artifacts
 	};
 }
+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_JSON_DEPTH = 16;
+const MAX_PATCH_OPERATIONS = 128;
+const actionIntents = /* @__PURE__ */ new Set([
+	"submit",
+	"cancel",
+	"select",
+	"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);
+}
+function reject(message) {
+	throw new WebSkillError("VALIDATION_FAILED", message);
+}
+function requireString(value, name) {
+	if (typeof value !== "string" || value.trim() === "") reject(`${name} must be a non-empty string`);
+}
+function requireNonNegativeInteger(value, name) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) reject(`${name} must be a non-negative integer`);
+}
+function isJsonValue(value, depth = 0) {
+	if (depth > MAX_JSON_DEPTH || value === void 0 || typeof value === "function" || typeof value === "symbol") return false;
+	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;
+	return Object.keys(value).every((key) => key !== "__proto__" && key !== "constructor" && isJsonValue(value[key], depth + 1));
+}
+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");
+		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`);
+	return structuredClone(value);
+}
+function assertPatch(value) {
+	if (!isRecord$1(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");
+	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 "patch":
+			requireString(value["id"], "Surface patch ID");
+			requireNonNegativeInteger(value["revision"], "Surface patch revision");
+			if (!Array.isArray(value["operations"]) || value["operations"].length === 0) reject("A surface patch requires operations");
+			if (value["operations"].length > MAX_PATCH_OPERATIONS) reject(`A surface patch must contain at most ${MAX_PATCH_OPERATIONS} operations`);
+			for (const operation of value["operations"]) assertPatch(operation);
+			return {
+				type: "patch",
+				...value["runId"] ? { runId: value["runId"] } : {},
+				id: value["id"],
+				revision: value["revision"],
+				operations: structuredClone(value["operations"])
+			};
+		case "complete":
+			requireString(value["id"], "Surface completion ID");
+			requireNonNegativeInteger(value["revision"], "Surface completion revision");
+			return {
+				type: "complete",
+				...value["runId"] ? { runId: value["runId"] } : {},
+				id: value["id"],
+				revision: value["revision"]
+			};
+		case "error":
+			requireString(value["id"], "Surface error ID");
+			requireString(value["code"], "Surface error code");
+			requireString(value["message"], "Surface error message");
+			return {
+				type: "error",
+				...value["runId"] ? { runId: value["runId"] } : {},
+				id: value["id"],
+				code: value["code"],
+				message: value["message"]
+			};
+		case "cancel":
+			requireString(value["id"], "Surface cancellation ID");
+			return {
+				type: "cancel",
+				...value["runId"] ? { runId: value["runId"] } : {},
+				id: value["id"]
+			};
+		default: return reject("UI surface event type is invalid");
+	}
+}
+/** Extracts validated surface stream events from structured tool output. @experimental */
+function extractUiSurfaceEvents(data) {
+	if (!isRecord$1(data) || data["$surface"] === void 0) return [];
+	const raw = data["$surface"];
+	return (Array.isArray(raw) ? raw : [raw]).map((event) => validateUiSurfaceEvent(event));
+}
 /**
 * JsonSchema → 表单模型：按 properties 生成字段，required 标记必填；
 * providedArgs 已有的值作为 defaultValue 预填（表单只为补齐缺失项服务）。
@@ -1073,6 +1287,7 @@ var TraceRecorder = class {
 		return [...this.#events];
 	}
 };
+const MAX_SURFACE_PATCHES_PER_SECOND = 240;
 /** 交互终态（取消/超时）：从工具执行深处直接终止 run */
 var RunTerminated = class extends Error {
 	outcome;
@@ -1097,6 +1312,7 @@ 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 继续循环；
@@ -1168,9 +1384,14 @@ var AgentLoop = class {
 			toolTimeoutMs: this.#config.toolTimeoutMs,
 			now,
 			interactionSeq: 0,
+			surfaceActionSeq: 0,
 			messages: [],
 			turn: 0,
 			renderBlocks: [],
+			surfaceEvents: [],
+			surfacePatchWindowStartedAt: Date.now(),
+			surfacePatchCount: 0,
+			processedSurfaceActionNonces: /* @__PURE__ */ new Set(),
 			startMs,
 			pausedMs: 0,
 			maxTurns: this.#config.maxTurns,
@@ -1310,6 +1531,7 @@ var AgentLoop = class {
 						toolCallId: call.id,
 						content: await this.#serializeToolResult(call, result, state)
 					});
+					await this.#drainSurfaceAction(state);
 				}
 			}
 		} finally {
@@ -1365,7 +1587,7 @@ var AgentLoop = class {
 		};
 	}
 	/** D3 快照写入（含 pendingInteraction 与过期时间；写失败降级 run.warning） */
-	async #saveSnapshot(state, request) {
+	async #saveSnapshot(state, pending) {
 		const store = this.#deps.snapshotStore;
 		if (!store) return;
 		const snapshot = {
@@ -1378,10 +1600,14 @@ var AgentLoop = class {
 			turn: state.turn,
 			activeSkillNames: [...state.activated].sort(),
 			activatedTools: [...state.activatedTools.values()],
-			pendingInteraction: request,
+			...pending.interaction ? { pendingInteraction: pending.interaction } : {},
+			...pending.surfaceAction ? { pendingSurfaceAction: pending.surfaceAction } : {},
 			interactionExpiresAt: state.run.interruptExpiresAt,
 			renderBlocks: [...state.renderBlocks],
+			surfaceEvents: state.surfaceEvents.map((event) => structuredClone(event)),
 			interactionSeq: state.interactionSeq,
+			surfaceActionSeq: state.surfaceActionSeq,
+			processedSurfaceActionNonces: [...state.processedSurfaceActionNonces],
 			pausedMs: state.pausedMs,
 			config: {
 				maxTurns: state.maxTurns,
@@ -1426,9 +1652,14 @@ var AgentLoop = class {
 			toolTimeoutMs: snapshot.config.toolTimeoutMs,
 			now,
 			interactionSeq: snapshot.interactionSeq ?? 0,
+			surfaceActionSeq: snapshot.surfaceActionSeq ?? 0,
 			messages: snapshot.messages.map((m) => ({ ...m })),
 			turn: snapshot.turn,
 			renderBlocks: (snapshot.renderBlocks ?? []).map((b) => ({ ...b })),
+			surfaceEvents: (snapshot.surfaceEvents ?? []).map((event) => structuredClone(event)),
+			surfacePatchWindowStartedAt: Date.now(),
+			surfacePatchCount: 0,
+			processedSurfaceActionNonces: new Set(snapshot.processedSurfaceActionNonces ?? []),
 			startMs,
 			pausedMs: snapshot.pausedMs ?? 0,
 			maxTurns: snapshot.config.maxTurns,
@@ -1437,15 +1668,19 @@ var AgentLoop = class {
 		};
 		this.#controllers.set(runId, state.controller);
 		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
+		const pendingInteraction = snapshot.pendingInteraction;
+		const pendingSurfaceAction = snapshot.pendingSurfaceAction;
 		trace.record("run.resumed", { data: {
 			snapshotAt: snapshot.snapshotAt,
 			turn: snapshot.turn,
-			interactionType: snapshot.pendingInteraction.type
+			interactionType: pendingSurfaceAction ? "surface-action" : pendingInteraction?.type
 		} });
-		const pending = snapshot.pendingInteraction;
+		const pending = pendingInteraction;
 		const pendingCall = this.#findPendingToolCall(state.messages);
 		try {
-			if ((pending.type === "form" || pending.type === "select") && pendingCall) {
+			await this.#replaySurfaceEvents(state);
+			if (pendingSurfaceAction) await this.#resumeSurfaceAction(state, pendingSurfaceAction);
+			else if ((pending?.type === "form" || pending?.type === "select") && pendingCall) {
 				const value = await this.#interact(state, pending, {
 					tool: pendingCall.name,
 					resumed: true
@@ -1463,7 +1698,8 @@ var AgentLoop = class {
 					toolCallId: pendingCall.id,
 					content: await this.#serializeToolResult(pendingCall, result, state)
 				});
-			} else if (pending.type === "ask" && pendingCall) {
+				await this.#drainSurfaceAction(state);
+			} else if (pending?.type === "ask" && pendingCall) {
 				const value = await this.#interact(state, pending, {
 					tool: pendingCall.name,
 					resumed: true
@@ -1484,6 +1720,7 @@ var AgentLoop = class {
 					toolCallId: pendingCall.id,
 					content: await this.#serializeToolResult(pendingCall, result, state)
 				});
+				await this.#drainSurfaceAction(state);
 			} else if (pendingCall) {
 				const result = await this.#executeCall(pendingCall, state);
 				state.messages.push({
@@ -1491,6 +1728,7 @@ var AgentLoop = class {
 					toolCallId: pendingCall.id,
 					content: await this.#serializeToolResult(pendingCall, result, state)
 				});
+				await this.#drainSurfaceAction(state);
 			}
 			for (;;) {
 				const next = this.#findPendingToolCall(state.messages);
@@ -1501,6 +1739,7 @@ var AgentLoop = class {
 					toolCallId: next.id,
 					content: await this.#serializeToolResult(next, result, state)
 				});
+				await this.#drainSurfaceAction(state);
 			}
 		} catch (e) {
 			if (e instanceof RunTerminated) return this.#finish(state, e.outcome.status, e.outcome.reason, e.outcome.message, e.outcome.code);
@@ -1597,7 +1836,7 @@ var AgentLoop = class {
 		const { run } = state;
 		run.status = "interrupted";
 		run.interruptExpiresAt = new Date(Date.parse(state.now()) + this.#policy.interactionTimeoutMs).toISOString();
-		await this.#saveSnapshot(state, request);
+		await this.#saveSnapshot(state, { interaction: request });
 		await this.#lifecycle("interact", state, {
 			interactionId: request.id,
 			type: request.type
@@ -1665,7 +1904,8 @@ var AgentLoop = class {
 		} });
 		this.#emitTool(state, "started", call);
 		let result;
-		if (call.name === "read_skill_file") result = await this.#handleReadSkillFile(call, state);
+		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 {
 			const resolution = resolveToolName(call.name, state.activated);
@@ -1691,6 +1931,14 @@ var AgentLoop = class {
 					type: "chart",
 					chart
 				});
+				try {
+					for (const event of extractUiSurfaceEvents(item.data)) await this.#renderSurface(state, event);
+				} catch (e) {
+					state.trace.record("run.warning", {
+						message: `UI surface rejected: ${messageOf(e)}`,
+						data: e instanceof WebSkillError ? { code: e.code } : void 0
+					});
+				}
 			}
 		} else {
 			state.trace.record("tool.failed", {
@@ -1711,10 +1959,155 @@ var AgentLoop = class {
 		} });
 		return result;
 	}
+	/** Attaches trusted run provenance, then records only events accepted by the configured bridge. */
+	async #renderSurface(state, event) {
+		const bridge = this.#deps.uiBridge;
+		if (!bridge?.renderSurface) {
+			state.trace.record("run.warning", { message: "UiBridge does not support renderSurface; UI surface was not rendered" });
+			return;
+		}
+		const attributed = this.#attributeSurfaceEvent(state, event);
+		if (attributed.type === "patch") this.#consumeSurfacePatchBudget(state);
+		await bridge.renderSurface(attributed);
+		state.surfaceEvents.push(structuredClone(attributed));
+		if (attributed.type === "open") {
+			const waiting = surfaceActions(attributed.surface).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,
+				actionId: action.id,
+				intent: action.intent,
+				nonce: action.nonce
+			};
+		}
+	}
+	#consumeSurfacePatchBudget(state) {
+		const now = Date.now();
+		if (now - state.surfacePatchWindowStartedAt >= 1e3) {
+			state.surfacePatchWindowStartedAt = now;
+			state.surfacePatchCount = 0;
+		}
+		state.surfacePatchCount += 1;
+		if (state.surfacePatchCount > MAX_SURFACE_PATCHES_PER_SECOND) throw new WebSkillError("VALIDATION_FAILED", `UI surface patch rate exceeds ${MAX_SURFACE_PATCHES_PER_SECOND} events per second`);
+	}
+	/** 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 {
+			...event,
+			runId: state.runId
+		};
+		return {
+			type: "open",
+			runId: state.runId,
+			surface: {
+				...event.surface,
+				actions: actions.map((action) => ({
+					...action,
+					nonce: `surface-${state.runId}-${++state.surfaceActionSeq}`
+				}))
+			}
+		};
+	}
+	/** Awaits the single action emitted with the most recently persisted tool result. */
+	async #drainSurfaceAction(state) {
+		const request = state.pendingSurfaceAction;
+		if (!request) return;
+		state.pendingSurfaceAction = void 0;
+		await this.#acceptSurfaceAction(state, request);
+	}
+	/** Restores a checkpointed action wait without re-running the tool that emitted its surface. */
+	async #resumeSurfaceAction(state, request) {
+		await this.#acceptSurfaceAction(state, request, true);
+	}
+	async #acceptSurfaceAction(state, request, resumed = false) {
+		const response = await this.#interactSurfaceAction(state, request, resumed);
+		if (response.cancelled) throw new RunTerminated({
+			status: "cancelled",
+			reason: "user-cancelled",
+			message: "Surface action cancelled by user",
+			code: "RUN_CANCELLED"
+		});
+		if (response.runId !== request.runId || response.surfaceId !== request.surfaceId || response.actionId !== request.actionId || response.nonce !== request.nonce) throw new BridgeRequestError("UiBridge returned a surface action response with an invalid capability nonce");
+		if (state.processedSurfaceActionNonces.has(response.nonce)) throw new BridgeRequestError("UiBridge returned a surface action response with an already consumed capability nonce");
+		state.processedSurfaceActionNonces.add(response.nonce);
+		state.messages.push({
+			role: "user",
+			content: JSON.stringify({
+				type: "webskill_surface_action",
+				surfaceId: response.surfaceId,
+				actionId: response.actionId,
+				intent: response.intent,
+				value: response.value ?? null
+			})
+		});
+	}
+	async #interactSurfaceAction(state, request, resumed) {
+		const bridge = this.#deps.uiBridge;
+		if (!bridge?.requestSurfaceAction) throw new BridgeRequestError("UiBridge does not support requestSurfaceAction");
+		this.#disarmDeadline(state);
+		const waitStartMs = Date.parse(state.now());
+		try {
+			const { run } = state;
+			run.status = "interrupted";
+			run.interruptExpiresAt = new Date(Date.parse(state.now()) + this.#policy.interactionTimeoutMs).toISOString();
+			await this.#saveSnapshot(state, { surfaceAction: request });
+			await this.#lifecycle("interact", state, {
+				surfaceId: request.surfaceId,
+				actionId: request.actionId,
+				nonce: request.nonce,
+				...resumed ? { resumed: true } : {}
+			});
+			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));
+			run.status = "running";
+			run.interruptExpiresAt = void 0;
+			state.trace.record("ui.surface-action.resolved", { data: {
+				surfaceId: request.surfaceId,
+				actionId: request.actionId,
+				nonce: request.nonce
+			} });
+			await this.#lifecycle("execute", state, { surfaceAction: request.actionId });
+			return response;
+		} catch (e) {
+			state.run.status = "running";
+			state.run.interruptExpiresAt = void 0;
+			if (e instanceof WebSkillError && e.code === "RUN_INTERACTION_TIMEOUT") throw new RunTerminated({
+				status: "failed",
+				reason: "interaction-timeout",
+				message: e.message,
+				code: "RUN_INTERACTION_TIMEOUT"
+			});
+			if (e instanceof RunTerminated || e instanceof BridgeRequestError) throw e;
+			throw new BridgeRequestError(messageOf(e));
+		} finally {
+			state.pausedMs += Date.parse(state.now()) - waitStartMs;
+			this.#armDeadline(state);
+		}
+	}
+	/** Replays the persisted stream before an interrupted interaction is rendered again. */
+	async #replaySurfaceEvents(state) {
+		const bridge = this.#deps.uiBridge;
+		if (!bridge?.renderSurface || state.surfaceEvents.length === 0) return;
+		try {
+			for (const event of state.surfaceEvents) await bridge.renderSurface(structuredClone(event));
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Failed to replay UI surfaces: ${messageOf(e)}` });
+		}
+	}
 	/**
-	* 逐工具实时事件（execute 相位，data.type='tool'）：chatbot ToolCallCard 等的 live 状态源；
+	* 逐工具实时事件（execute 相位，data.type='tool'）：chatbot 思维链工具行等的 live 状态源；
 	* 与既有 execute 相位事件（{turn}）并存，监听方按 data.type 区分。
-	* data.args 为参数摘要（JSON 截断 100 字符，卡片展开详情用）。
+	* data.args 为参数摘要（JSON 截断 100 字符，展开详情用）。
 	*/
 	#emitTool(state, status, call) {
 		this.#deps.eventBus?.emit({
@@ -1880,8 +2273,9 @@ var AgentLoop = class {
 			let scriptFiles;
 			try {
 				scriptFiles = (await this.#deps.fs.list(`${root}/scripts`)).filter((s) => s.type === "file").map((s) => baseName(s.path));
-			} catch {
+			} catch (e) {
 				scriptFiles = [];
+				if (!(e instanceof WebSkillError && e.code === "FS_NOT_FOUND")) state.trace.record("run.warning", { message: `Failed to list scripts of skill "${skillName}": ${messageOf(e)}` });
 			}
 			for (const file of scriptFiles) {
 				const match = /^(.*)\.(ts|js)$/.exec(file);
@@ -2018,10 +2412,11 @@ var AgentLoop = class {
 	#nextInteractionId(state) {
 		return `int-${++state.interactionSeq}`;
 	}
-	async #memoryGet(scope, key) {
+	async #memoryGet(scope, key, state) {
 		try {
 			return await this.#deps.memory?.get(scope, key);
-		} catch {
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Memory read failed: ${messageOf(e)}` });
 			return;
 		}
 	}
@@ -2046,7 +2441,7 @@ var AgentLoop = class {
 			}
 			return;
 		}
-		await this.#memorySet(scope, key, mutate(await this.#memoryGet(scope, key)), state);
+		await this.#memorySet(scope, key, mutate(await this.#memoryGet(scope, key, state)), state);
 	}
 	async #writeActivationMemory(skillName, state) {
 		if (!this.#deps.memory) return;
@@ -2578,9 +2973,26 @@ const encode = (s) => encodeURIComponent(s);
 var FsMemoryStore = class {
 	#root;
 	#fs;
+	#onWarning;
 	constructor(deps) {
 		this.#root = deps.root.replace(/\/+$/, "");
 		this.#fs = deps.fs;
+		this.#onWarning = deps.onWarning ?? ((message) => console.warn(message));
+	}
+	/**
+	* 0.2.8 G2：损坏条目此前直接 remove——静默销毁用户数据，且对调用方伪装成「没有这条记忆」。
+	* 改为隔离到 .corrupt 并告警：run 照常继续，但数据留存、故障可见。
+	*/
+	async #quarantine(path, error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		const target = `${path}.corrupt`;
+		try {
+			await this.#fs.rename(path, target);
+			this.#onWarning(`[webskill] Corrupted memory entry quarantined to ${target}: ${reason}`);
+		} catch (renameError) {
+			const detail = renameError instanceof Error ? renameError.message : String(renameError);
+			this.#onWarning(`[webskill] Corrupted memory entry at ${path} could not be quarantined (${detail}): ${reason}`);
+		}
 	}
 	#scopeDir(scope) {
 		return `${this.#root}/${encode(scope)}`;
@@ -2593,8 +3005,8 @@ var FsMemoryStore = class {
 		if (!await this.#fs.exists(path)) return void 0;
 		try {
 			return JSON.parse(await this.#fs.readText(path));
-		} catch {
-			await this.#fs.remove(path);
+		} catch (e) {
+			await this.#quarantine(path, e);
 			return;
 		}
 	}
@@ -2618,8 +3030,8 @@ var FsMemoryStore = class {
 					key,
 					value: JSON.parse(await this.#fs.readText(entry.path))
 				});
-			} catch {
-				await this.#fs.remove(entry.path);
+			} catch (e) {
+				await this.#quarantine(entry.path, e);
 			}
 		}
 		return out.sort((a, b) => a.key.localeCompare(b.key));
@@ -2643,9 +3055,11 @@ const INDEX_FILE = "index.json";
 var FsArtifactStore = class {
 	#root;
 	#fs;
+	#onWarning;
 	constructor(deps) {
 		this.#root = deps.root.replace(/\/+$/, "");
 		this.#fs = deps.fs;
+		this.#onWarning = deps.onWarning ?? ((message) => console.warn(message));
 	}
 	async createTextArtifact(input) {
 		const size = new TextEncoder().encode(input.content).length;
@@ -2671,8 +3085,15 @@ var FsArtifactStore = class {
 		const raw = await this.#fs.readText(indexPath);
 		try {
 			return JSON.parse(raw).artifacts ?? [];
-		} catch {
-			await this.#fs.remove(indexPath);
+		} catch (e) {
+			const reason = e instanceof Error ? e.message : String(e);
+			try {
+				await this.#fs.rename(indexPath, `${indexPath}.corrupt`);
+				this.#onWarning(`[webskill] Corrupted artifact index for run ${runId} quarantined to ${indexPath}.corrupt: ${reason}`);
+			} catch (renameError) {
+				const detail = renameError instanceof Error ? renameError.message : String(renameError);
+				this.#onWarning(`[webskill] Corrupted artifact index for run ${runId} could not be quarantined (${detail}): ${reason}`);
+			}
 			return [];
 		}
 	}
@@ -2786,6 +3207,20 @@ function networkUrlHost(url) {
 		return "(unparseable-url)";
 	}
 }
+/**
+* 网络策略判定逻辑的可注入源码（单一来源）。
+*
+* 0.2.8 C4：此前各注入点直接拼 `isNetworkAllowed.toString()`，依赖**函数名在产物里保持不变**。
+* SDK 自身不压缩，但消费方一旦跑生产构建，打包器会把导出函数改名（`function Ke(...)`），
+* 注入后的沙箱里 `isNetworkAllowed` 就是 undefined —— 沙箱内任何 fetch 直接
+* TOOL_EXECUTION_FAILED，网络白名单形同虚设。dev server 不压缩，所以只在真实产物上暴露。
+*
+* 因此改为把函数源码绑定到**固定的变量名**上：`var isNetworkAllowed = function Ke(...) {…};`
+* ——名字随便压缩，绑定名恒定。两个函数都自包含（不引用模块内其它符号），故可独立绑定。
+*/
+function networkPolicyLibSource() {
+	return `var isNetworkAllowed = ${isNetworkAllowed.toString()};\nvar networkUrlHost = ${networkUrlHost.toString()};`;
+}
 /** WebSkillErrorCode 全量白名单（错误码归一用；与 core errors.ts 保持同步） */
 const WHITELIST = /* @__PURE__ */ new Set([
 	"FS_NOT_FOUND",
@@ -2899,4 +3334,4 @@ var CapabilityApproval = class CapabilityApproval {
 };
 
 //#endregion
-export { isNetworkAllowed as A, toVercelToolSpecs as B, bridgeError as C, extractChartSpec as D, createWebSkillApi as E, normalizeToolError as F, parseBridgeRequest as I, resolveToolName as L, networkUrlHost as M, normalizeErrorCode as N, fromVercelResult as O, normalizeToolContent as P, schemaToForm as R, WebSkillRuntime as S, createScriptContext as T, 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, mergeCatalogEntries as j, fromVercelStreamPart 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, toLlmToolSpec as z };
+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 };