@webskill/sdk 0.0.3 → 0.0.5

package/dist/{dist-hMMxARXK.js → dist-D405AlPD.js}

@@ -259,6 +259,15 @@ function checkSkillRules(input) {
 		severity: "error",
 		message: `Unsupported script file in scripts/ of directory ${dirName}: ${fileName} (only .ts/.js and .schema.json sidecars allowed)`
 	});
+	const allowedTools = metadata?.["allowed-tools"];
+	if (Array.isArray(allowedTools)) {
+		const scriptNames = new Set((input.scriptFileNames ?? []).filter((f) => SCRIPT_EXTENSION_RE.test(f)).map((f) => f.replace(SCRIPT_EXTENSION_RE, "")));
+		for (const entry of allowedTools) if (typeof entry === "string" && !scriptNames.has(entry)) issues.push({
+			code: "SKILL_UNKNOWN_ALLOWED_TOOL",
+			severity: "warning",
+			message: `allowed-tools entry ${JSON.stringify(entry)} of directory ${dirName} does not match any script in scripts/`
+		});
+	}
 	return issues;
 }
 /** 由条目列表构建 Catalog，保证按名称排序 */
@@ -908,7 +917,7 @@ const ASK_USER_TOOL = {
 * 不暴露 fs 本体（沙箱语义，对齐 deferred-items D1）。
 */
 function createScriptContext(deps) {
-	const { fs, artifactStore, skillName, skillRoot, runId, confirm } = deps;
+	const { fs, artifactStore, skillName, skillRoot, runId, confirm, onWarning } = deps;
 	return {
 		skillName,
 		runId,
@@ -928,7 +937,8 @@ function createScriptContext(deps) {
 				mimeType: options?.mimeType
 			});
 		},
-		...confirm ? { confirm } : {}
+		...confirm ? { confirm } : {},
+		...onWarning ? { onWarning } : {}
 	};
 }
 /**
@@ -1310,6 +1320,91 @@ function bridgeError(id, code, message) {
 		}
 	};
 }
+/**
+* 判定 URL 是否被策略放行：
+* - 'deny-all'（默认）全拒；'allow-all' 全放
+* - { allow } 条目支持三种写法：
+*   - 精确域名 'api.example.com'（忽略端口与路径）
+*   - 通配 '*.example.com'（含 apex 与任意深度子域）
+*   - 源 'http://localhost:3000'（协议 + host + port 全等）
+* - URL 解析失败一律拒绝
+*/
+function isNetworkAllowed(policy, url) {
+	if (policy === "allow-all") return true;
+	if (policy === "deny-all" || !policy || typeof policy !== "object") return false;
+	var allow = policy.allow;
+	if (!Array.isArray(allow)) return false;
+	var parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return false;
+	}
+	var host = parsed.hostname.toLowerCase();
+	for (var i = 0; i < allow.length; i++) {
+		var entry = allow[i];
+		if (typeof entry !== "string" || entry === "") continue;
+		if (entry.indexOf("://") !== -1) {
+			try {
+				if (new URL(entry).origin === parsed.origin) return true;
+			} catch {}
+			continue;
+		}
+		var rule = entry.toLowerCase();
+		if (rule.indexOf("*.") === 0) {
+			var suffix = rule.slice(2);
+			if (host === suffix || host.endsWith("." + suffix)) return true;
+		} else if (host === rule) return true;
+	}
+	return false;
+}
+/** 阻断 trace 用的脱敏 host（解析失败返回占位，不记录完整 URL） */
+function networkUrlHost(url) {
+	try {
+		return new URL(url).hostname;
+	} catch {
+		return "(unparseable-url)";
+	}
+}
+/**
+* Per-capability 强制授权判定（宿主侧，browser/node 执行器共用单一来源）。
+* 'require-approval' 模式下经注入的 UiBridge 发 authorize 交互；
+* once-per-run（默认）在 run 内记忆已批准能力，every-call 每次调用都问。
+*/
+var CapabilityApproval = class {
+	#uiBridge;
+	#scope;
+	/** runId → 已批准能力集合（once-per-run 记忆） */
+	#approved = /* @__PURE__ */ new Map();
+	#seq = 0;
+	constructor(deps = {}) {
+		this.#uiBridge = deps.uiBridge;
+		this.#scope = deps.scope ?? "once-per-run";
+	}
+	async authorize(input) {
+		const { runId, capability, mode } = input;
+		if (mode === false) return "disabled";
+		if (mode !== "require-approval") return "allowed";
+		if (this.#scope === "once-per-run" && this.#approved.get(runId)?.has(capability)) return "allowed";
+		if (!this.#uiBridge) return "denied";
+		if ((await this.#uiBridge.request({
+			type: "authorize",
+			id: `authorize-${runId}-${capability}-${++this.#seq}`,
+			capability,
+			message: input.message,
+			...input.details !== void 0 ? { details: input.details } : {}
+		})).value !== true) return "denied";
+		if (this.#scope === "once-per-run") {
+			let set = this.#approved.get(runId);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				this.#approved.set(runId, set);
+			}
+			set.add(capability);
+		}
+		return "allowed";
+	}
+};
 /** 结构化 trace 记录器；时钟与 id 工厂可注入（golden trace 用固定值保证确定性） */
 var TraceRecorder = class {
 	#runId;
@@ -1384,34 +1479,35 @@ var AgentLoop = class {
 		};
 	}
 	async run(input) {
-		const llm = this.#deps.llm;
-		const artifactStore = this.#deps.artifactStore;
+		this.#deps.llm;
+		this.#deps.artifactStore;
 		const now = this.#deps.clock?.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
 		const runId = input.runId ?? `run-${Math.random().toString(36).slice(2, 10)}`;
 		const trace = new TraceRecorder(runId, this.#deps.clock);
 		const startedAt = now();
 		const startMs = Date.parse(startedAt);
-		const run = {
-			id: runId,
-			sessionId: input.sessionId,
-			status: "running",
-			phase: "route",
-			userPrompt: input.userPrompt,
-			startedAt,
-			activeSkillNames: [],
-			artifacts: [],
-			trace: []
-		};
 		const state = {
 			runId,
-			run,
+			run: {
+				id: runId,
+				sessionId: input.sessionId,
+				status: "running",
+				phase: "route",
+				userPrompt: input.userPrompt,
+				startedAt,
+				activeSkillNames: [],
+				artifacts: [],
+				trace: []
+			},
 			trace,
 			reader: new SkillReader(this.#deps.fs, this.#deps.skillIndex),
 			activated: /* @__PURE__ */ new Set(),
 			activatedTools: /* @__PURE__ */ new Map(),
 			toolTimeoutMs: this.#config.toolTimeoutMs,
 			now,
-			interactionSeq: 0
+			interactionSeq: 0,
+			messages: [],
+			turn: 0
 		};
 		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
 		const route = this.#deps.catalogFilter ? {
@@ -1431,114 +1527,273 @@ var AgentLoop = class {
 				return [];
 			}
 		}))).flat();
-		const messages = [{
+		state.messages = [{
 			role: "system",
 			content: route.systemPrompt
 		}, {
 			role: "user",
 			content: input.userPrompt
 		}];
-		const finish = async (status, reason, output, errorCode) => {
-			run.status = status;
-			run.terminationReason = reason;
-			run.endedAt = now();
-			run.activeSkillNames = [...state.activated].sort();
-			run.artifacts = await artifactStore.listArtifacts(runId);
-			if (status === "completed") trace.record("run.completed", { data: { reason } });
-			else if (status === "cancelled") trace.record("run.cancelled", {
-				message: output,
-				data: { reason }
-			});
-			else trace.record("run.failed", {
-				message: output,
-				data: {
-					reason,
-					...errorCode ? { code: errorCode } : {}
-				}
-			});
-			const bridge = this.#deps.uiBridge;
-			if (status === "completed" && bridge?.renderResult && this.#config.renderResult !== "off") try {
-				const request = buildRenderResult(run, output);
-				await bridge.renderResult(request);
-				trace.record("ui.rendered", { data: { blockCount: request.blocks.length } });
-			} catch (e) {
-				trace.record("run.warning", { message: `renderResult failed: ${messageOf(e)}` });
-			}
+		try {
+			return await this.#turnLoop(state, startMs, 1, externalSpecs);
+		} catch (e) {
+			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return this.#finish(state, "failed", "hook-error", messageOf(e), "RUN_FAILED");
+			throw e;
+		}
+	}
+	/** 主循环（run 从第 1 轮、resume 从快照轮次续跑；totalTimeout 以 startedAt 续算） */
+	async #turnLoop(state, startMs, startTurn, externalSpecs) {
+		const finish = (status, reason, output, errorCode) => this.#finish(state, status, reason, output, errorCode);
+		const { llm } = this.#deps;
+		const { trace, messages } = state;
+		for (let turn = startTurn;; turn++) {
+			state.turn = turn;
+			if (turn > this.#config.maxTurns) return finish("failed", "max-turns", `Agent loop exceeded the maximum of ${this.#config.maxTurns} turns`, "RUN_MAX_TURNS_EXCEEDED");
+			if (Date.parse(state.now()) - startMs > this.#config.totalTimeoutMs) return finish("failed", "timeout", `Agent loop exceeded the total timeout of ${this.#config.totalTimeoutMs}ms`, "RUN_TIMEOUT");
+			const toolSpecs = [
+				toLlmToolSpec(READ_SKILL_FILE_TOOL),
+				...this.#deps.uiBridge ? [toLlmToolSpec(ASK_USER_TOOL)] : [],
+				...[...state.activatedTools.values()].map(toLlmToolSpec),
+				...externalSpecs
+			];
+			trace.record("llm.request", { data: {
+				turn,
+				messageCount: messages.length,
+				toolCount: toolSpecs.length
+			} });
+			let response;
 			try {
-				await this.#lifecycle(status === "completed" ? "complete" : "fail", state, { reason });
+				response = llm.stream ? await this.#completeStreaming(llm, state, {
+					model: this.#deps.model,
+					messages,
+					tools: toolSpecs,
+					temperature: this.#config.temperature
+				}) : await llm.complete({
+					model: this.#deps.model,
+					messages,
+					tools: toolSpecs,
+					temperature: this.#config.temperature
+				});
 			} catch (e) {
-				trace.record("run.warning", { message: `Terminal lifecycle hook failed: ${messageOf(e)}` });
+				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);
 			}
-			run.trace = trace.list();
-			return {
-				output,
-				run
-			};
-		};
-		try {
-			for (let turn = 1;; turn++) {
-				if (turn > this.#config.maxTurns) return await finish("failed", "max-turns", `Agent loop exceeded the maximum of ${this.#config.maxTurns} turns`, "RUN_MAX_TURNS_EXCEEDED");
-				if (Date.parse(now()) - startMs > this.#config.totalTimeoutMs) return await finish("failed", "timeout", `Agent loop exceeded the total timeout of ${this.#config.totalTimeoutMs}ms`, "RUN_TIMEOUT");
-				const toolSpecs = [
-					toLlmToolSpec(READ_SKILL_FILE_TOOL),
-					...this.#deps.uiBridge ? [toLlmToolSpec(ASK_USER_TOOL)] : [],
-					...[...state.activatedTools.values()].map(toLlmToolSpec),
-					...externalSpecs
-				];
-				trace.record("llm.request", { data: {
-					turn,
-					messageCount: messages.length,
-					toolCount: toolSpecs.length
-				} });
-				let response;
+			trace.record("llm.response", { data: {
+				turn,
+				hasToolCalls: Boolean(response.toolCalls?.length),
+				contentLength: response.content?.length ?? 0
+			} });
+			if (!response.toolCalls?.length) return finish("completed", "final-answer", response.content ?? "");
+			await this.#lifecycle("execute", state, { turn });
+			messages.push({
+				role: "assistant",
+				content: response.content ?? "",
+				toolCalls: response.toolCalls
+			});
+			for (const call of response.toolCalls) {
+				let result;
 				try {
-					response = llm.stream ? await this.#completeStreaming(llm, state, {
-						model: this.#deps.model,
-						messages,
-						tools: toolSpecs,
-						temperature: this.#config.temperature
-					}) : await llm.complete({
-						model: this.#deps.model,
-						messages,
-						tools: toolSpecs,
-						temperature: this.#config.temperature
-					});
+					result = await this.#executeCall(call, state);
 				} catch (e) {
-					const code = e instanceof WebSkillError && (e.code === "LLM_UNAVAILABLE" || e.code === "LLM_REQUEST_FAILED") ? e.code : "LLM_REQUEST_FAILED";
-					return await finish("failed", "llm-error", messageOf(e), code);
+					if (e instanceof RunTerminated) return finish(e.outcome.status, e.outcome.reason, e.outcome.message, e.outcome.code);
+					throw e;
 				}
-				trace.record("llm.response", { data: {
-					turn,
-					hasToolCalls: Boolean(response.toolCalls?.length),
-					contentLength: response.content?.length ?? 0
-				} });
-				if (!response.toolCalls?.length) return await finish("completed", "final-answer", response.content ?? "");
-				await this.#lifecycle("execute", state, { turn });
 				messages.push({
-					role: "assistant",
-					content: response.content ?? "",
-					toolCalls: response.toolCalls
+					role: "tool",
+					toolCallId: call.id,
+					content: JSON.stringify(result)
 				});
-				for (const call of response.toolCalls) {
-					let result;
-					try {
-						result = await this.#executeCall(call, state);
-					} catch (e) {
-						if (e instanceof RunTerminated) return await finish(e.outcome.status, e.outcome.reason, e.outcome.message, e.outcome.code);
-						throw e;
-					}
-					messages.push({
-						role: "tool",
-						toolCallId: call.id,
-						content: JSON.stringify(result)
-					});
-				}
 			}
+		}
+	}
+	/** 统一终态处理：completed/failed/cancelled；终态即删快照（快照是续命机制，审计归治理） */
+	async #finish(state, status, reason, output, errorCode) {
+		const { run, trace } = state;
+		run.status = status;
+		run.terminationReason = reason;
+		run.endedAt = state.now();
+		run.activeSkillNames = [...state.activated].sort();
+		run.artifacts = await this.#deps.artifactStore.listArtifacts(state.runId);
+		if (status === "completed") trace.record("run.completed", { data: { reason } });
+		else if (status === "cancelled") trace.record("run.cancelled", {
+			message: output,
+			data: { reason }
+		});
+		else trace.record("run.failed", {
+			message: output,
+			data: {
+				reason,
+				...errorCode ? { code: errorCode } : {}
+			}
+		});
+		const bridge = this.#deps.uiBridge;
+		if (status === "completed" && bridge?.renderResult && this.#config.renderResult !== "off") try {
+			const request = buildRenderResult(run, output);
+			await bridge.renderResult(request);
+			trace.record("ui.rendered", { data: { blockCount: request.blocks.length } });
 		} catch (e) {
-			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return await finish("failed", "hook-error", messageOf(e), "RUN_FAILED");
+			trace.record("run.warning", { message: `renderResult failed: ${messageOf(e)}` });
+		}
+		if (this.#deps.snapshotStore) try {
+			await this.#deps.snapshotStore.delete(state.runId);
+		} catch (e) {
+			trace.record("run.warning", { message: `Failed to delete run snapshot: ${messageOf(e)}` });
+		}
+		try {
+			await this.#lifecycle(status === "completed" ? "complete" : "fail", state, { reason });
+		} catch (e) {
+			trace.record("run.warning", { message: `Terminal lifecycle hook failed: ${messageOf(e)}` });
+		}
+		run.trace = trace.list();
+		return {
+			output,
+			run
+		};
+	}
+	/** D3 快照写入（含 pendingInteraction 与过期时间；写失败降级 run.warning） */
+	async #saveSnapshot(state, request) {
+		const store = this.#deps.snapshotStore;
+		if (!store) return;
+		const snapshot = {
+			schemaVersion: 1,
+			runId: state.runId,
+			sessionId: state.run.sessionId,
+			userPrompt: state.run.userPrompt,
+			startedAt: state.run.startedAt,
+			messages: state.messages.map((m) => ({ ...m })),
+			turn: state.turn,
+			activeSkillNames: [...state.activated].sort(),
+			activatedTools: [...state.activatedTools.values()],
+			pendingInteraction: request,
+			interactionExpiresAt: state.run.interruptExpiresAt,
+			config: {
+				maxTurns: this.#config.maxTurns,
+				totalTimeoutMs: this.#config.totalTimeoutMs,
+				toolTimeoutMs: this.#config.toolTimeoutMs,
+				...this.#config.temperature !== void 0 ? { temperature: this.#config.temperature } : {}
+			},
+			snapshotAt: state.now()
+		};
+		try {
+			await store.save(snapshot);
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Failed to save run snapshot: ${messageOf(e)}` });
+		}
+	}
+	/**
+	* D3 恢复：以快照重建 LoopState，重新发起等待中的交互（表单重新渲染），
+	* 应答后从快照轮次续跑主循环；totalTimeout 以快照 startedAt 续算。
+	*/
+	async resume(snapshot) {
+		const now = this.#deps.clock?.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+		const runId = snapshot.runId;
+		const trace = new TraceRecorder(runId, this.#deps.clock);
+		const startMs = Date.parse(snapshot.startedAt);
+		const state = {
+			runId,
+			run: {
+				id: runId,
+				sessionId: snapshot.sessionId,
+				status: "running",
+				phase: "execute",
+				userPrompt: snapshot.userPrompt,
+				startedAt: snapshot.startedAt,
+				activeSkillNames: snapshot.activeSkillNames,
+				artifacts: [],
+				trace: []
+			},
+			trace,
+			reader: new SkillReader(this.#deps.fs, this.#deps.skillIndex),
+			activated: new Set(snapshot.activeSkillNames),
+			activatedTools: new Map(snapshot.activatedTools.map((d) => [d.name, d])),
+			toolTimeoutMs: snapshot.config.toolTimeoutMs,
+			now,
+			interactionSeq: 0,
+			messages: snapshot.messages.map((m) => ({ ...m })),
+			turn: snapshot.turn
+		};
+		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
+		trace.record("run.resumed", { data: {
+			snapshotAt: snapshot.snapshotAt,
+			turn: snapshot.turn,
+			interactionType: snapshot.pendingInteraction.type
+		} });
+		const pending = snapshot.pendingInteraction;
+		const pendingCall = this.#findPendingToolCall(state.messages);
+		try {
+			if ((pending.type === "form" || pending.type === "select") && pendingCall) {
+				const value = await this.#interact(state, pending, {
+					tool: pendingCall.name,
+					resumed: true
+				});
+				const args = {
+					...pendingCall.arguments,
+					...typeof value === "object" && value !== null ? value : {}
+				};
+				const result = await this.#executeCall({
+					...pendingCall,
+					arguments: args
+				}, state);
+				state.messages.push({
+					role: "tool",
+					toolCallId: pendingCall.id,
+					content: JSON.stringify(result)
+				});
+			} else if (pending.type === "ask" && pendingCall) {
+				const value = await this.#interact(state, pending, {
+					tool: pendingCall.name,
+					resumed: true
+				});
+				const result = {
+					ok: true,
+					content: [{
+						type: "text",
+						text: typeof value === "string" ? value : JSON.stringify(value ?? "")
+					}]
+				};
+				state.trace.record("tool.completed", { data: {
+					name: pendingCall.name,
+					callId: pendingCall.id
+				} });
+				state.messages.push({
+					role: "tool",
+					toolCallId: pendingCall.id,
+					content: JSON.stringify(result)
+				});
+			} else if (pendingCall) {
+				const result = await this.#executeCall(pendingCall, state);
+				state.messages.push({
+					role: "tool",
+					toolCallId: pendingCall.id,
+					content: JSON.stringify(result)
+				});
+			}
+		} catch (e) {
+			if (e instanceof RunTerminated) return this.#finish(state, e.outcome.status, e.outcome.reason, e.outcome.message, e.outcome.code);
+			throw e;
+		}
+		const externalSpecs = (await Promise.all((this.#deps.externalTools ?? []).map(async (source) => {
+			try {
+				return await source.listToolSpecs();
+			} catch (e) {
+				trace.record("run.warning", { message: `External tool source "${source.kind}" failed to list specs: ${messageOf(e)}` });
+				return [];
+			}
+		}))).flat();
+		try {
+			return await this.#turnLoop(state, startMs, snapshot.turn + 1, externalSpecs);
+		} catch (e) {
+			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return this.#finish(state, "failed", "hook-error", messageOf(e), "RUN_FAILED");
 			throw e;
 		}
 	}
+	/** 最后一条 assistant 消息里第一个尚无 tool 响应的工具调用（即中断时正在处理的那个） */
+	#findPendingToolCall(messages) {
+		const lastAssistant = [...messages].reverse().find((m) => m.role === "assistant" && m.toolCalls?.length);
+		if (!lastAssistant?.toolCalls) return void 0;
+		const answered = new Set(messages.filter((m) => m.role === "tool").map((m) => m.toolCallId));
+		return lastAssistant.toolCalls.find((call) => !answered.has(call.id));
+	}
 	/**
 	* 流式 LLM 调用：text-delta 仅在 EventBus 有订阅者时发射 llm.delta 事件，
 	* 并同步转发 uiBridge.onTextDelta；tool-calls/done 组装为 LlmResponse 走原有分支。
@@ -1598,6 +1853,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.#lifecycle("interact", state, {
 			interactionId: request.id,
 			type: request.type
@@ -1777,6 +2033,13 @@ var AgentLoop = class {
 		if (!root) return "";
 		const executor = this.#deps.executor;
 		if (!executor) return "";
+		let allowedTools;
+		try {
+			const { metadata } = parseSkillMarkdown(await this.#deps.fs.readText(`${root}/SKILL.md`));
+			const raw = metadata["allowed-tools"];
+			if (raw !== void 0) if (Array.isArray(raw)) allowedTools = raw.filter((e) => typeof e === "string");
+			else state.trace.record("run.warning", { message: `Skill "${skillName}" has a non-array "allowed-tools" metadata entry; ignored` });
+		} catch {}
 		const loaded = [];
 		let scriptFiles = [];
 		try {
@@ -1787,6 +2050,7 @@ var AgentLoop = class {
 		for (const file of scriptFiles) {
 			const match = /^(.*)\.(ts|js)$/.exec(file);
 			if (!match?.[1]) continue;
+			if (allowedTools && !allowedTools.includes(match[1])) continue;
 			try {
 				const def = await executor.loadDefinition(root, match[1]);
 				await this.#enrichDefinition(root, match[1], def, state);
@@ -1821,10 +2085,12 @@ var AgentLoop = class {
 	async #handleScriptTool(call, skillName, scriptName, state) {
 		const root = this.#deps.skillIndex.get(skillName);
 		if (!root) return toolError("TOOL_NOT_FOUND", `Skill "${skillName}" is not in the catalog`);
-		let args = call.arguments;
+		if (!this.#deps.executor) return toolError("TOOL_UNSUPPORTED", `No script executor is configured; script tool "${call.name}" cannot run`);
 		const def = state.activatedTools.get(call.name);
-		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 {
+		if (!def) return toolError("TOOL_NOT_FOUND", `Tool "${call.name}" is not available for skill "${skillName}"`);
+		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 value = await this.#interact(state, {
 				type: "form",
 				id: this.#nextInteractionId(state),
@@ -1842,14 +2108,14 @@ var AgentLoop = class {
 			if (e instanceof BridgeRequestError) return toolError("UI_UNAVAILABLE", `Parameter form failed: ${e.message}`);
 			throw e;
 		}
-		if (!this.#deps.executor) return toolError("TOOL_UNSUPPORTED", `No script executor is configured; script tool "${call.name}" cannot run`);
 		const context = createScriptContext({
 			fs: this.#deps.fs,
 			artifactStore: this.#deps.artifactStore,
 			skillName,
 			skillRoot: root,
 			runId: state.runId,
-			confirm: (message) => this.#confirm(message, state)
+			confirm: (message) => this.#confirm(message, state),
+			onWarning: (message) => state.trace.record("run.warning", { message })
 		});
 		try {
 			const before = new Set((await this.#deps.artifactStore.listArtifacts(state.runId)).map((a) => a.id));
@@ -1954,6 +2220,58 @@ 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 过路径安全校验。
+*/
+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));
+	}
+	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() {
+		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));
+	}
+};
 /** runtime 门面：组合 discovery / router / agent loop / lifecycle */
 var WebSkillRuntime = class {
 	#deps;
@@ -2017,7 +2335,8 @@ var WebSkillRuntime = class {
 			longTerm: this.#deps.longTerm,
 			externalTools: this.#deps.externalTools,
 			skillProviders: this.#deps.skillProviders,
-			catalogFilter: this.#deps.catalogFilter
+			catalogFilter: this.#deps.catalogFilter,
+			snapshotStore: this.#deps.snapshotStore
 		}, this.#deps.config).run({
 			sessionId: this.#session.id,
 			userPrompt,
@@ -2037,7 +2356,78 @@ var WebSkillRuntime = class {
 		});
 		return result;
 	}
+	/** D3：列出可恢复的 interrupted run（供 UI 展示"未完成任务"） */
+	async listInterruptedRuns() {
+		if (!this.#deps.snapshotStore) return [];
+		return this.#deps.snapshotStore.list();
+	}
+	/**
+	* D3 恢复 interrupted run：
+	* 不存在 → RUN_SNAPSHOT_NOT_FOUND；schemaVersion 不匹配 → 删除 + RUN_SNAPSHOT_INCOMPATIBLE；
+	* 已过期 → interaction-timeout 终态并删快照；否则重建 LoopState 重新发起交互续跑。
+	*/
+	async resumeRun(runId) {
+		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();
+			return {
+				output: "Interaction timed out before the run was resumed",
+				run: {
+					id: runId,
+					sessionId: snapshot.sessionId,
+					status: "failed",
+					phase: "fail",
+					userPrompt: snapshot.userPrompt,
+					startedAt: snapshot.startedAt,
+					endedAt,
+					terminationReason: "interaction-timeout",
+					activeSkillNames: snapshot.activeSkillNames,
+					artifacts: [],
+					trace: [{
+						id: `evt-expired-${runId}`,
+						runId,
+						ts: endedAt,
+						type: "run.failed",
+						message: `Interaction timed out before the run was resumed (expired at ${snapshot.interactionExpiresAt})`,
+						data: {
+							reason: "interaction-timeout",
+							code: "RUN_INTERACTION_TIMEOUT"
+						}
+					}]
+				}
+			};
+		}
+		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({
+			llm: this.#deps.llm,
+			executor: this.#deps.executor,
+			schemaInferer: this.#deps.schemaInferer,
+			artifactStore: this.#deps.artifactStore,
+			fs: this.#deps.fs,
+			skillIndex: cache.index,
+			model: this.#deps.model,
+			uiBridge: this.#deps.uiBridge,
+			interaction: this.#deps.interaction,
+			memory: this.#deps.memory,
+			hooks: this.#deps.hooks,
+			eventBus: this.#events,
+			longTerm: this.#deps.longTerm,
+			externalTools: this.#deps.externalTools,
+			skillProviders: this.#deps.skillProviders,
+			catalogFilter: this.#deps.catalogFilter,
+			snapshotStore: store
+		}, this.#deps.config).resume(snapshot);
+	}
 };
 
 //#endregion
-export { validateSkills as $, schemaToForm as A, WebSkillError as B, createScriptContext as C, normalizeToolContent as D, mergeCatalogEntries as E, SKILL_MANIFEST_FILE as F, escapeXml as G, buildManifest as H, SKILL_NAME_MAX_LENGTH as I, normalizePath as J, isValidSkillName as K, SKILL_NAME_PATTERN as L, toVercelToolSpecs as M, MemoryFS as N, parseBridgeRequest as O, SKILLS_LOCKFILE as P, resolveInsideRoot as Q, SkillDiscovery as R, buildRenderResult as S, fromVercelStreamPart as T, checkSkillRules as U, buildCatalog as V, computeDigest as W, renderAvailableSkillsXml as X, parseSkillMarkdown as Y, renderCatalogJson as Z, READ_SKILL_FILE_TOOL as _, EventBus as a, WebSkillRuntime as b, FullDisclosureRouter as c, MemoryArtifactStore as d, verifyManifest as et, MockLlmClient as f, READ_SKILL_FILE_INPUT_SCHEMA as g, ProgressiveRouter as h, AgentLoop as i, toLlmToolSpec as j, resolveToolName as k, HookRunner as l, OpenAiCompatibleClient as m, ASK_USER_TOOL as n, FsArtifactStore as o, MockUiBridge as p, jsonRenderer as q, ASK_USER_TOOL_NAME as r, FsMemoryStore as s, ASK_USER_INPUT_SCHEMA as t, xmlRenderer as tt, InMemoryStore as u, READ_SKILL_FILE_TOOL_NAME as v, fromVercelResult as w, bridgeError as x, TraceRecorder as y, SkillReader as z };
+export { normalizePath as $, mergeCatalogEntries as A, SKILL_MANIFEST_FILE as B, WebSkillRuntime as C, fromVercelResult as D, createScriptContext as E, schemaToForm as F, WebSkillError as G, SKILL_NAME_PATTERN as H, toLlmToolSpec as I, checkSkillRules as J, buildCatalog as K, toVercelToolSpecs as L, normalizeToolContent as M, parseBridgeRequest as N, fromVercelStreamPart as O, resolveToolName as P, jsonRenderer as Q, MemoryFS as R, TraceRecorder as S, buildRenderResult as T, SkillDiscovery as U, SKILL_NAME_MAX_LENGTH as V, SkillReader as W, escapeXml as X, computeDigest as Y, isValidSkillName as Z, ProgressiveRouter as _, CapabilityApproval as a, verifyManifest as at, READ_SKILL_FILE_TOOL_NAME as b, FsMemoryStore as c, HookRunner as d, parseSkillMarkdown as et, InMemoryStore as f, OpenAiCompatibleClient as g, MockUiBridge as h, AgentLoop as i, validateSkills as it, networkUrlHost as j, isNetworkAllowed as k, FsRunSnapshotStore as l, MockLlmClient as m, ASK_USER_TOOL as n, renderCatalogJson as nt, EventBus as o, xmlRenderer as ot, MemoryArtifactStore as p, buildManifest as q, ASK_USER_TOOL_NAME as r, resolveInsideRoot as rt, FsArtifactStore as s, ASK_USER_INPUT_SCHEMA as t, renderAvailableSkillsXml as tt, FullDisclosureRouter as u, READ_SKILL_FILE_INPUT_SCHEMA as v, bridgeError as w, RUN_SNAPSHOT_SCHEMA_VERSION as x, READ_SKILL_FILE_TOOL as y, SKILLS_LOCKFILE as z };