@webskill/sdk 0.2.5 → 0.2.7

package/dist/{dist-B77plHjw.js → dist-BdOW8N4V.js}

@@ -40,7 +40,7 @@ var OpenAiCompatibleClient = class {
 	#fetch;
 	constructor(config) {
 		this.#config = config;
-		this.#fetch = config.fetchImpl ?? fetch;
+		this.#fetch = config.fetchImpl ?? ((input, init) => fetch(input, init));
 	}
 	#requireConfig() {
 		const { baseUrl, apiKey, model } = this.#config;
@@ -262,7 +262,7 @@ var AnthropicClient = class {
 	#fetch;
 	constructor(config) {
 		this.#config = config;
-		this.#fetch = config.fetchImpl ?? fetch;
+		this.#fetch = config.fetchImpl ?? ((input, init) => fetch(input, init));
 	}
 	#baseUrl() {
 		return (this.#config.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
@@ -491,7 +491,7 @@ var GoogleGenAiClient = class {
 	#fetch;
 	constructor(config) {
 		this.#config = config;
-		this.#fetch = config.fetchImpl ?? fetch;
+		this.#fetch = config.fetchImpl ?? ((input, init) => fetch(input, init));
 	}
 	#baseUrl() {
 		return (this.#config.baseUrl ?? "https://generativelanguage.googleapis.com").replace(/\/+$/, "");
@@ -875,22 +875,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 +928,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 +1279,7 @@ var TraceRecorder = class {
 		return [...this.#events];
 	}
 };
+const MAX_SURFACE_PATCHES_PER_SECOND = 240;
 /** 交互终态（取消/超时）：从工具执行深处直接终止 run */
 var RunTerminated = class extends Error {
 	outcome;
@@ -1092,6 +1299,12 @@ const toolError = (code, message) => ({
 		message
 	}
 });
+/** 工具参数摘要（JSON 截断 100 字符；trace 与实时事件同一口径，ToolCallCard 展开详情用） */
+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 继续循环；
@@ -1101,6 +1314,10 @@ var AgentLoop = class {
 	#deps;
 	#config;
 	#policy;
+	/** 活跃 run 的 AbortController（cancel(runId) 触发；终态清理） */
+	#controllers = /* @__PURE__ */ new Map();
+	/** 经 cancel() 主动取消的 run（aborted 分支据此区分 cancelled 与 timeout） */
+	#cancelled = /* @__PURE__ */ new Set();
 	constructor(deps, config = {}) {
 		this.#deps = {
 			...deps,
@@ -1121,6 +1338,18 @@ var AgentLoop = class {
 			interactionTimeoutMs: deps.interaction?.interactionTimeoutMs ?? 3e5
 		};
 	}
+	/**
+	* 取消进行中的 run：触发该 run 的 AbortController（与 totalTimeout 硬期限同一通道），
+	* run 以 cancelled（RUN_CANCELLED）终止；未找到（已终态或不属于本实例）返回 false。
+	* 取消在下一个中断点生效（LLM complete/stream 调用；交互等待不强制中断）。
+	*/
+	cancel(runId) {
+		const controller = this.#controllers.get(runId);
+		if (!controller) return false;
+		this.#cancelled.add(runId);
+		controller.abort();
+		return true;
+	}
 	async run(input) {
 		const now = this.#deps.clock?.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
 		const runId = input.runId ?? `run-${Math.random().toString(36).slice(2, 10)}`;
@@ -1147,15 +1376,21 @@ 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,
 			totalTimeoutMs: this.#config.totalTimeoutMs,
 			controller: new AbortController()
 		};
+		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 route = this.#deps.catalogFilter ? {
 			...input.route,
@@ -1250,7 +1485,10 @@ var AgentLoop = class {
 						signal: state.controller.signal
 					});
 				} catch (e) {
-					if (state.controller.signal.aborted) return finish("failed", "timeout", `Agent loop exceeded the total timeout of ${state.totalTimeoutMs}ms`, "RUN_TIMEOUT");
+					if (state.controller.signal.aborted) {
+						if (this.#cancelled.has(state.runId)) return finish("cancelled", "user-cancelled", "Run cancelled by user", "RUN_CANCELLED");
+						return finish("failed", "timeout", `Agent loop exceeded the total timeout of ${state.totalTimeoutMs}ms`, "RUN_TIMEOUT");
+					}
 					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);
 				}
@@ -1285,6 +1523,7 @@ var AgentLoop = class {
 						toolCallId: call.id,
 						content: await this.#serializeToolResult(call, result, state)
 					});
+					await this.#drainSurfaceAction(state);
 				}
 			}
 		} finally {
@@ -1294,6 +1533,8 @@ var AgentLoop = class {
 	/** 统一终态处理：completed/failed/cancelled；终态即删快照（快照是续命机制，审计归治理） */
 	async #finish(state, status, reason, output, errorCode) {
 		this.#disarmDeadline(state);
+		this.#controllers.delete(state.runId);
+		this.#cancelled.delete(state.runId);
 		const { run, trace } = state;
 		run.status = status;
 		run.terminationReason = reason;
@@ -1338,7 +1579,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 = {
@@ -1351,10 +1592,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,
@@ -1399,25 +1644,35 @@ 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,
 			totalTimeoutMs: snapshot.config.totalTimeoutMs,
 			controller: new AbortController()
 		};
+		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
@@ -1435,7 +1690,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
@@ -1456,6 +1712,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({
@@ -1463,6 +1720,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);
@@ -1473,6 +1731,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);
@@ -1569,7 +1828,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
@@ -1628,10 +1887,14 @@ var AgentLoop = class {
 		});
 	}
 	async #executeCall(call, state) {
+		const argsSummary = summarizeArgs(call.arguments);
+		const callStartMs = Date.parse(state.now());
 		state.trace.record("tool.started", { data: {
 			name: call.name,
-			callId: call.id
+			callId: call.id,
+			args: argsSummary
 		} });
+		this.#emitTool(state, "started", call);
 		let result;
 		if (call.name === "read_skill_file") result = await this.#handleReadSkillFile(call, state);
 		else if (call.name === "ask_user") result = await this.#handleAskUser(call, state);
@@ -1643,11 +1906,15 @@ var AgentLoop = class {
 				result = source ? await source.call(call.name, call.arguments) : toolError(resolution.code, resolution.message);
 			}
 		}
+		const durationMs = Date.parse(state.now()) - callStartMs;
 		if (result.ok) {
 			state.trace.record("tool.completed", { data: {
 				name: call.name,
-				callId: call.id
+				callId: call.id,
+				args: argsSummary,
+				durationMs
 			} });
+			this.#emitTool(state, "completed", call);
 			for (const item of result.content) {
 				if (item.type !== "json") continue;
 				const chart = extractChartSpec(item.data);
@@ -1655,21 +1922,199 @@ 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", {
-			message: result.error?.message,
-			data: {
-				name: call.name,
-				callId: call.id,
-				code: result.error?.code
-			}
-		});
+		} else {
+			state.trace.record("tool.failed", {
+				message: result.error?.message,
+				data: {
+					name: call.name,
+					callId: call.id,
+					code: result.error?.code,
+					args: argsSummary,
+					durationMs
+				}
+			});
+			this.#emitTool(state, "failed", call);
+		}
 		for (const artifact of result.artifacts ?? []) state.trace.record("artifact.created", { data: {
 			artifactId: artifact.id,
 			path: artifact.path
 		} });
 		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 思维链工具行等的 live 状态源；
+	* 与既有 execute 相位事件（{turn}）并存，监听方按 data.type 区分。
+	* data.args 为参数摘要（JSON 截断 100 字符，展开详情用）。
+	*/
+	#emitTool(state, status, call) {
+		this.#deps.eventBus?.emit({
+			phase: "execute",
+			runId: state.runId,
+			sessionId: state.run.sessionId,
+			ts: state.now(),
+			data: {
+				type: "tool",
+				status,
+				name: call.name,
+				callId: call.id,
+				args: summarizeArgs(call.arguments)
+			}
+		});
+	}
 	async #handleAskUser(call, state) {
 		const question = call.arguments["question"];
 		if (typeof question !== "string" || question === "") return toolError("TOOL_EXECUTION_FAILED", "ask_user requires a non-empty \"question\" string argument");
@@ -2140,6 +2585,8 @@ var WebSkillRuntime = class {
 	#session;
 	#events;
 	#catalogCache;
+	/** 活跃 run 的 loop 实例（cancel(runId) 路由；终态清理） */
+	#loops = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.#deps = {
 			...deps,
@@ -2224,7 +2671,7 @@ var WebSkillRuntime = class {
 		const catalog = providerEntries.length > 0 ? { entries: mergeCatalogEntries(cache.catalog.entries, providerEntries) } : cache.catalog;
 		const filteredCatalog = this.#deps.catalogFilter ? { entries: await this.#deps.catalogFilter(catalog.entries) } : catalog;
 		const route = await this.#router.route(filteredCatalog);
-		const result = await new AgentLoop({
+		const loop = new AgentLoop({
 			llm: this.#deps.llm,
 			executor: this.#deps.executor,
 			schemaInferer: this.#deps.schemaInferer,
@@ -2243,12 +2690,21 @@ var WebSkillRuntime = class {
 			catalogFilter: this.#deps.catalogFilter,
 			snapshotStore: this.#deps.snapshotStore,
 			skillStateGuard: this.#deps.skillStateGuard
-		}, this.#deps.config).run({
-			sessionId: options.sessionId ?? this.#session.id,
-			userPrompt,
-			route,
-			...options.history ? { history: options.history } : {}
-		});
+		}, this.#deps.config);
+		const runId = `run-${Math.random().toString(36).slice(2, 10)}`;
+		this.#loops.set(runId, loop);
+		let result;
+		try {
+			result = await loop.run({
+				sessionId: options.sessionId ?? this.#session.id,
+				userPrompt,
+				route,
+				runId,
+				...options.history ? { history: options.history } : {}
+			});
+		} finally {
+			this.#loops.delete(runId);
+		}
 		for (const failure of providerFailures) result.run.trace.push({
 			id: `evt-provider-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
 			runId: result.run.id,
@@ -2323,7 +2779,7 @@ var WebSkillRuntime = class {
 		if (!this.#catalogCache) await this.discover();
 		const cache = this.#catalogCache;
 		if (!cache) throw new WebSkillError("RUN_FAILED", "discover() did not populate the catalog cache");
-		return new AgentLoop({
+		const loop = new AgentLoop({
 			llm: this.#deps.llm,
 			executor: this.#deps.executor,
 			schemaInferer: this.#deps.schemaInferer,
@@ -2342,7 +2798,21 @@ var WebSkillRuntime = class {
 			catalogFilter: this.#deps.catalogFilter,
 			snapshotStore: store,
 			skillStateGuard: this.#deps.skillStateGuard
-		}, this.#deps.config).resume(snapshot);
+		}, this.#deps.config);
+		this.#loops.set(runId, loop);
+		try {
+			return await loop.resume(snapshot);
+		} finally {
+			this.#loops.delete(runId);
+		}
+	}
+	/**
+	* 取消进行中的 run（chatbot Stop 按钮等）：触发该 run 的 AbortController，
+	* run 以 cancelled（RUN_CANCELLED）终止；未找到活跃 run 返回 false。
+	* 取消在下一个中断点生效（LLM complete/stream；交互等待不强制中断）。
+	*/
+	cancel(runId) {
+		return this.#loops.get(runId)?.cancel(runId) ?? false;
 	}
 };
 /**
@@ -2813,4 +3283,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, toLlmToolSpec as B, bridgeError as C, extractChartSpec as D, createWebSkillApi as E, normalizeToolContent as F, validateUiSurface as H, normalizeToolError as I, parseBridgeRequest as L, mergeCatalogEntries as M, networkUrlHost as N, extractUiSurfaceEvents as O, normalizeErrorCode as P, resolveToolName as R, WebSkillRuntime as S, createScriptContext as T, validateUiSurfaceEvent as U, toVercelToolSpecs as V, 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, schemaToForm as z };