@webskill/sdk 0.1.3 → 0.1.5

package/README.md

@@ -16,8 +16,11 @@ governance.
   (missing-parameter forms, confirmations, authorization prompts), and
   resumable interrupted runs.
 - **Script sandbox** — `worker_threads` sandbox for Node, Web Worker sandbox for
-  the browser. Deny-by-default network policy, per-capability forced approval,
-  timeouts kill runaway scripts.
+  the browser. Deny-by-default network policy, deny-by-default builtin-module
+  allowlist, per-capability forced approval, timeouts kill runaway scripts.
+  **Honest note:** these executors reduce the capability surface — they are NOT
+  a security boundary. Scripts share the host process/origin and bypasses
+  exist; never rely on them to isolate untrusted scripts.
 - **`navigator.webskill`** — a browser facade (`discover` / `read` / `validate` /
   `run` / `install` / `uninstall`) assembled explicitly in one call.
 - **MCP** — call page-provided tools and consume page-declared dynamic skills

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { H as SkillsLockfile, L as SkillManifest, P as SkillInstallSource, S as FileSystemProvider, W as VerifyResult, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, s as InteractionResponse, v as UiBridge, x as FileStat } from "./types-CgNC-oQu-Dq_A1yA-.js";
-import { $ as ToolDefinition, N as NetworkPolicy, X as ScriptExecutionContext, Z as ScriptExecutor, d as BridgeCapabilities, m as BridgeResponse, p as BridgeRequest, st as WebSkillApi, tt as ToolResult, u as ApprovalScope, ut as bridgeError, v as ExternalSkillProvider, xt as parseBridgeRequest, y as ExternalToolSource } from "./index-CqMuvcb2.js";
+import { C as FileStat, I as SkillInstallSource, K as VerifyResult, W as SkillsLockfile, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, s as InteractionResponse, v as UiBridge, w as FileSystemProvider, y as ArchiveLimits, z as SkillManifest } from "./types-CgNC-oQu-DEcIBJKG.js";
+import { N as NetworkPolicy, St as parseBridgeRequest, X as ScriptExecutionContext, Z as ScriptExecutor, ct as WebSkillApi, d as BridgeCapabilities, dt as bridgeError, et as ToolDefinition, m as BridgeResponse, nt as ToolResult, p as BridgeRequest, u as ApprovalScope, v as ExternalSkillProvider, y as ExternalToolSource } from "./index-COuOu6gw.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -83,6 +83,10 @@ declare class BrowserSkillManager {
     fs: FileSystemProvider;
     managedRoot: string;
     fetchImpl?: typeof fetch;
+    /** 归档体积三重上限（缺省 DEFAULT_ARCHIVE_LIMITS） */
+    archiveLimits?: ArchiveLimits;
+    /** install/uninstall 成功后的变更回调（宿主接线缓存失效，如 WebSkillRuntime.invalidate） */
+    onChanged?: () => void;
   });
   install(source: SkillInstallSource, options?: {
     expectedSha256?: string;
@@ -99,10 +103,10 @@ declare class BrowserSkillManager {
 //#endregion
 //#region src/skillManagement/zipExtract.d.ts
 /**
- * zip 解包（fflate，浏览器无依赖）。
+ * zip 解包（fflate 流式，单条目/总解压体积上限，浏览器无依赖）。
  * 每个条目路径过 resolveInsideRoot：拒绝 `..` 段、绝对路径、反斜杠穿越（与 node 规则一致）。
  */
-declare function extractZipWeb(fs: FileSystemProvider, data: Uint8Array, destRoot: string): Promise<void>;
+declare function extractZipWeb(fs: FileSystemProvider, data: Uint8Array, destRoot: string, limits?: ArchiveLimits): Promise<void>;
 //#endregion
 //#region src/skillManagement/checksumWeb.d.ts
 /** WebCrypto sha256（浏览器/Worker 通用；Node 20+ 全局 crypto 同样可用） */

package/dist/browser.js

@@ -1,7 +1,6 @@
-import { E as verifyManifest, T as validateSkills, _ as isValidSkillName, b as parseSkillMarkdown, d as buildManifest, g as exportSkills, l as WebSkillError, n as SKILLS_LOCKFILE, o as SKILL_PACK_FILE, r as SKILL_MANIFEST_FILE, s as SkillDiscovery, u as buildCatalog, w as resolveInsideRoot, x as parseSkillPackManifest } from "./dist-DS1sfgHa.js";
-import { A as mergeCatalogEntries, M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, T as createWebSkillApi, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-DZobLFh6.js";
-import { n as MockLlmClient } from "./testing-CbM6rJ-E.js";
-import { unzipSync } from "fflate";
+import { A as validateSkills, C as parseSkillPackManifest, O as resolveInsideRoot, S as parseSkillMarkdown, c as SkillDiscovery, f as buildCatalog, i as SKILL_MANIFEST_FILE, j as verifyManifest, k as unzipWithLimits, p as buildManifest, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, v as exportSkills, w as readResponseWithLimit, y as isValidSkillName } from "./dist-fZFZaf43.js";
+import { A as mergeCatalogEntries, M as normalizeToolContent, N as parseBridgeRequest, S as bridgeError, T as createWebSkillApi, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as networkUrlHost, k as isNetworkAllowed, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-DuGN5x0v.js";
+import { n as MockLlmClient } from "./testing-BmR48Pn1.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -421,17 +420,11 @@ async function removeDirQuiet(fs, dir) {
 	} catch {}
 }
 /**
-* zip 解包（fflate，浏览器无依赖）。
+* zip 解包（fflate 流式，单条目/总解压体积上限，浏览器无依赖）。
 * 每个条目路径过 resolveInsideRoot：拒绝 `..` 段、绝对路径、反斜杠穿越（与 node 规则一致）。
 */
-async function extractZipWeb(fs, data, destRoot) {
-	let entries;
-	try {
-		entries = unzipSync(data);
-	} catch (e) {
-		throw new WebSkillError("INSTALL_FAILED", `Failed to read zip archive: ${e instanceof Error ? e.message : String(e)}`, e);
-	}
-	for (const [entryPath, content] of Object.entries(entries)) {
+async function extractZipWeb(fs, data, destRoot, limits) {
+	for (const [entryPath, content] of await unzipWithLimits(data, limits)) {
 		const target = resolveInsideRoot(destRoot, entryPath);
 		if (entryPath.endsWith("/")) await fs.mkdir(target);
 		else await fs.writeBinary(target, content);
@@ -450,10 +443,14 @@ var BrowserSkillManager = class {
 	#fs;
 	#managedRoot;
 	#fetchImpl;
+	#archiveLimits;
+	#onChanged;
 	constructor(deps) {
 		this.#fs = deps.fs;
 		this.#managedRoot = deps.managedRoot.replace(/\/+$/, "");
 		this.#fetchImpl = deps.fetchImpl;
+		this.#archiveLimits = deps.archiveLimits;
+		this.#onChanged = deps.onChanged;
 	}
 	async install(source, options) {
 		const fs = this.#fs;
@@ -470,7 +467,7 @@ var BrowserSkillManager = class {
 					throw new WebSkillError("INSTALL_FAILED", `Download failed: ${messageOf$1(e)}`, e);
 				}
 				if (!res.ok) throw new WebSkillError("INSTALL_FAILED", `Download failed with HTTP ${res.status}`);
-				data = new Uint8Array(await res.arrayBuffer());
+				data = await readResponseWithLimit(res, this.#archiveLimits);
 			} else data = new Uint8Array(source.data);
 			if (options?.expectedSha256 !== void 0) {
 				const actual = await sha256HexWeb(data);
@@ -478,7 +475,7 @@ var BrowserSkillManager = class {
 			}
 			const contentDir = `${stagingRoot}/content`;
 			await fs.mkdir(contentDir);
-			await extractZipWeb(fs, data, contentDir);
+			await extractZipWeb(fs, data, contentDir, this.#archiveLimits);
 			const packFilePath = `${contentDir}/${SKILL_PACK_FILE}`;
 			if (await fs.exists(packFilePath)) return (await this.#installPack({
 				contentDir,
@@ -508,20 +505,33 @@ var BrowserSkillManager = class {
 				const errors = report.issues.filter((i) => i.severity === "error");
 				throw new WebSkillError("INSTALL_FAILED", `Skill "${name}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
 			}
-			targetDir = `${this.#managedRoot}/${name}`;
-			if (await fs.exists(targetDir)) await fs.remove(targetDir, { recursive: true });
-			await copyDir(fs, finalDir, targetDir);
-			const manifest = await this.#createManifest(targetDir, {
+			const manifest = await this.#createManifest(finalDir, {
 				name,
 				...version ? { version } : {},
 				source
 			});
-			await this.#upsertLockEntry(name, {
-				digest: manifest.integrity.digest,
-				installedAt: manifest.installedAt,
-				source
-			});
+			targetDir = `${this.#managedRoot}/${name}`;
+			const backupDir = `${stagingRoot}/backup`;
+			const hadPrevious = await fs.exists(targetDir);
+			if (hadPrevious) await copyDir(fs, targetDir, backupDir);
+			let committed = false;
+			try {
+				if (hadPrevious) await fs.remove(targetDir, { recursive: true });
+				await copyDir(fs, finalDir, targetDir);
+				committed = true;
+				await this.#upsertLockEntry(name, {
+					digest: manifest.integrity.digest,
+					installedAt: manifest.installedAt,
+					source
+				});
+			} catch (e) {
+				if (committed) await removeDirQuiet(fs, targetDir);
+				if (hadPrevious) await copyDir(fs, backupDir, targetDir);
+				targetDir = void 0;
+				throw e;
+			}
 			targetDir = void 0;
+			this.#onChanged?.();
 			return manifest;
 		} catch (e) {
 			if (targetDir) await removeDirQuiet(fs, targetDir);
@@ -562,11 +572,7 @@ var BrowserSkillManager = class {
 			}
 			const manifests = [];
 			for (const entry of pack.manifest.skills) {
-				const targetDir = `${this.#managedRoot}/${entry.name}`;
-				if (await fs.exists(targetDir)) await fs.remove(targetDir, { recursive: true });
-				await copyDir(fs, `${finalRoot}/${entry.name}`, targetDir);
-				installed.push(targetDir);
-				const manifest = await this.#createManifest(targetDir, {
+				const manifest = await this.#createManifest(`${finalRoot}/${entry.name}`, {
 					name: entry.name,
 					...versions.get(entry.name) ? { version: versions.get(entry.name) } : {},
 					source
@@ -574,11 +580,36 @@ var BrowserSkillManager = class {
 				if (manifest.integrity.digest !== entry.digest) throw new WebSkillError("INSTALL_FAILED", `Skill "${entry.name}" digest mismatch: expected ${entry.digest}, got ${manifest.integrity.digest}`);
 				manifests.push(manifest);
 			}
-			for (const manifest of manifests) await this.#upsertLockEntry(manifest.name, {
-				digest: manifest.integrity.digest,
-				installedAt: manifest.installedAt,
-				source
-			});
+			const swapped = [];
+			try {
+				for (const manifest of manifests) {
+					const targetDir = `${this.#managedRoot}/${manifest.name}`;
+					const backupDir = `${stagingRoot}/backup/${manifest.name}`;
+					if (await fs.exists(targetDir)) {
+						await copyDir(fs, targetDir, backupDir);
+						await fs.remove(targetDir, { recursive: true });
+					}
+					await copyDir(fs, `${finalRoot}/${manifest.name}`, targetDir);
+					installed.push(targetDir);
+					swapped.push({
+						targetDir,
+						backupDir
+					});
+				}
+				for (const manifest of manifests) await this.#upsertLockEntry(manifest.name, {
+					digest: manifest.integrity.digest,
+					installedAt: manifest.installedAt,
+					source
+				});
+			} catch (e) {
+				for (const { targetDir, backupDir } of swapped) {
+					await removeDirQuiet(fs, targetDir);
+					if (await fs.exists(backupDir)) await copyDir(fs, backupDir, targetDir);
+				}
+				installed.length = 0;
+				throw e;
+			}
+			this.#onChanged?.();
 			return manifests;
 		} catch (e) {
 			for (const targetDir of installed) await removeDirQuiet(fs, targetDir);
@@ -609,6 +640,7 @@ var BrowserSkillManager = class {
 		try {
 			await this.#fs.remove(targetDir, { recursive: true });
 			await this.#removeLockEntry(name);
+			this.#onChanged?.();
 		} catch (e) {
 			throw new WebSkillError("UNINSTALL_FAILED", `Failed to uninstall "${name}": ${messageOf$1(e)}`, e);
 		}
@@ -617,11 +649,9 @@ var BrowserSkillManager = class {
 		if (!isValidSkillName(name)) throw new WebSkillError("INTEGRITY_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
 		const manifest = await this.#readManifest(`${this.#managedRoot}/${name}`);
 		const actualHashes = /* @__PURE__ */ new Map();
-		for (const file of manifest.files) {
-			const path = `${this.#managedRoot}/${name}/${file.path}`;
-			if (await this.#fs.exists(path)) actualHashes.set(file.path, await sha256HexWeb(await this.#fs.readBinary(path)));
-		}
-		return verifyManifest(manifest, actualHashes);
+		const actualFiles = await listFiles(this.#fs, `${this.#managedRoot}/${name}`);
+		for (const rel of actualFiles) actualHashes.set(rel, await sha256HexWeb(await this.#fs.readBinary(`${this.#managedRoot}/${name}/${rel}`)));
+		return verifyManifest(manifest, actualHashes, actualFiles);
 	}
 	async listInstalled() {
 		const path = lockfilePath(this.#managedRoot);

package/dist/{dist-DxGyAznR.js → dist-CfBOjJ4p.js}

@@ -1,4 +1,4 @@
-import { l as WebSkillError } from "./dist-DS1sfgHa.js";
+import { u as WebSkillError } from "./dist-fZFZaf43.js";
 
 //#region ../ui/dist/index.js
 /** 提交值按请求类型归形（WebFormBridge 与框架组件库共享单一来源） */
@@ -1040,8 +1040,7 @@ var LitRendererBridge = class {
 						values: formValues
 					}
 				});
-				if (input.type === "authorize" && !response.cancelled) response.value = true;
-				resolve(response);
+				resolve(this.#decodeValue(input, response));
 			}, { version: "v0.9.1" });
 			processor.onSurfaceCreated((surface) => {
 				const el = this.#doc.createElement("a2ui-surface");
@@ -1052,6 +1051,50 @@ var LitRendererBridge = class {
 			processor.processMessages(messages);
 		});
 	}
+	/**
+	* 按 InteractionRequest.type 解码提交值（绑定模型原样回传的是表单对象）：
+	* confirm 仅 confirmed===true 批准；select 还原原始 option 值（非字符串值经 JSON 编码比对）；
+	* form 的 number 字段转 number；ask 取 answer；authorize 提交即批准。
+	*/
+	#decodeValue(input, response) {
+		if (response.cancelled) return response;
+		const values = response.value;
+		switch (input.type) {
+			case "confirm": return {
+				...response,
+				value: values?.confirmed === true
+			};
+			case "ask": return {
+				...response,
+				value: values?.answer
+			};
+			case "select": {
+				const raw = values?.selected;
+				const option = input.options.find((o) => o.value === raw || JSON.stringify(o.value) === raw);
+				return {
+					...response,
+					value: option ? option.value : raw
+				};
+			}
+			case "form": {
+				if (typeof values !== "object" || values === null) return response;
+				const out = { ...values };
+				for (const field of input.fields) if (field.type === "number" && out[field.name] !== void 0) {
+					const n = Number(out[field.name]);
+					if (!Number.isNaN(n)) out[field.name] = n;
+				}
+				return {
+					...response,
+					value: out
+				};
+			}
+			case "authorize": return {
+				...response,
+				value: true
+			};
+			default: return response;
+		}
+	}
 };
 
 //#endregion

package/dist/{dist-DZobLFh6.js → dist-DuGN5x0v.js}

@@ -1,4 +1,4 @@
-import { S as renderAvailableSkillsXml, T as validateSkills, b as parseSkillMarkdown, c as SkillReader, l as WebSkillError, s as SkillDiscovery, u as buildCatalog, w as resolveInsideRoot } from "./dist-DS1sfgHa.js";
+import { A as validateSkills, O as resolveInsideRoot, S as parseSkillMarkdown, T as renderAvailableSkillsXml, c as SkillDiscovery, d as assertSafePathSegment, f as buildCatalog, l as SkillReader, u as WebSkillError } from "./dist-fZFZaf43.js";
 import { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.js";
 
 //#region ../runtime/dist/index.js
@@ -1050,6 +1050,7 @@ var AgentLoop = class {
 			maxTurns: config.maxTurns ?? 10,
 			totalTimeoutMs: config.totalTimeoutMs ?? 12e4,
 			toolTimeoutMs: config.toolTimeoutMs ?? 3e4,
+			toolResultMaxBytes: config.toolResultMaxBytes ?? 1e5,
 			temperature: config.temperature,
 			renderResult: config.renderResult
 		};
@@ -1089,7 +1090,12 @@ var AgentLoop = class {
 			interactionSeq: 0,
 			messages: [],
 			turn: 0,
-			renderBlocks: []
+			renderBlocks: [],
+			startMs,
+			pausedMs: 0,
+			maxTurns: this.#config.maxTurns,
+			totalTimeoutMs: this.#config.totalTimeoutMs,
+			controller: new AbortController()
 		};
 		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
 		const route = this.#deps.catalogFilter ? {
@@ -1117,21 +1123,42 @@ var AgentLoop = class {
 			content: input.userPrompt
 		}];
 		try {
-			return await this.#turnLoop(state, startMs, 1, externalSpecs);
+			return await this.#turnLoop(state, 1, externalSpecs);
 		} catch (e) {
 			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return this.#finish(state, "failed", "hook-error", messageOf$1(e), "RUN_FAILED");
 			throw e;
 		}
 	}
+	/** 总时长消耗（wall - 交互等待）；交互期间不计入 totalTimeout */
+	#elapsed(state) {
+		return Date.parse(state.now()) - state.startMs - state.pausedMs;
+	}
+	/** 重设硬期限定时器（剩余 = totalTimeoutMs - 已消耗；耗尽立即 abort） */
+	#armDeadline(state) {
+		if (state.timer) clearTimeout(state.timer);
+		const remaining = state.totalTimeoutMs - this.#elapsed(state);
+		if (remaining <= 0) {
+			state.controller.abort();
+			return;
+		}
+		state.timer = setTimeout(() => state.controller.abort(), remaining);
+	}
+	#disarmDeadline(state) {
+		if (state.timer) {
+			clearTimeout(state.timer);
+			state.timer = void 0;
+		}
+	}
 	/** 主循环（run 从第 1 轮、resume 从快照轮次续跑；totalTimeout 以 startedAt 续算） */
-	async #turnLoop(state, startMs, startTurn, externalSpecs) {
+	async #turnLoop(state, startTurn, externalSpecs) {
 		const finish = (status, reason, output, errorCode) => this.#finish(state, status, reason, output, errorCode);
 		const { llm } = this.#deps;
 		const { trace, messages } = state;
+		this.#armDeadline(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");
+			if (turn > state.maxTurns) return finish("failed", "max-turns", `Agent loop exceeded the maximum of ${state.maxTurns} turns`, "RUN_MAX_TURNS_EXCEEDED");
+			if (this.#elapsed(state) > state.totalTimeoutMs) return finish("failed", "timeout", `Agent loop exceeded the total timeout of ${state.totalTimeoutMs}ms`, "RUN_TIMEOUT");
 			const toolSpecs = [
 				toLlmToolSpec(READ_SKILL_FILE_TOOL),
 				...this.#deps.uiBridge ? [toLlmToolSpec(ASK_USER_TOOL)] : [],
@@ -1149,14 +1176,17 @@ var AgentLoop = class {
 					model: this.#deps.model,
 					messages,
 					tools: toolSpecs,
-					temperature: this.#config.temperature
+					temperature: this.#config.temperature,
+					signal: state.controller.signal
 				}) : await llm.complete({
 					model: this.#deps.model,
 					messages,
 					tools: toolSpecs,
-					temperature: this.#config.temperature
+					temperature: this.#config.temperature,
+					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");
 				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$1(e), code);
 			}
@@ -1183,13 +1213,14 @@ var AgentLoop = class {
 				messages.push({
 					role: "tool",
 					toolCallId: call.id,
-					content: JSON.stringify(result)
+					content: await this.#serializeToolResult(call, result, state)
 				});
 			}
 		}
 	}
 	/** 统一终态处理：completed/failed/cancelled；终态即删快照（快照是续命机制，审计归治理） */
 	async #finish(state, status, reason, output, errorCode) {
+		this.#disarmDeadline(state);
 		const { run, trace } = state;
 		run.status = status;
 		run.terminationReason = reason;
@@ -1293,7 +1324,12 @@ var AgentLoop = class {
 			interactionSeq: 0,
 			messages: snapshot.messages.map((m) => ({ ...m })),
 			turn: snapshot.turn,
-			renderBlocks: []
+			renderBlocks: [],
+			startMs,
+			pausedMs: 0,
+			maxTurns: snapshot.config.maxTurns,
+			totalTimeoutMs: snapshot.config.totalTimeoutMs,
+			controller: new AbortController()
 		};
 		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
 		trace.record("run.resumed", { data: {
@@ -1364,7 +1400,7 @@ var AgentLoop = class {
 			}
 		}))).flat();
 		try {
-			return await this.#turnLoop(state, startMs, snapshot.turn + 1, externalSpecs);
+			return await this.#turnLoop(state, snapshot.turn + 1, externalSpecs);
 		} catch (e) {
 			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return this.#finish(state, "failed", "hook-error", messageOf$1(e), "RUN_FAILED");
 			throw e;
@@ -1431,8 +1467,18 @@ var AgentLoop = class {
 	* 取消 → RunTerminated(cancelled)；超时 → RunTerminated(interaction-timeout)。
 	*/
 	async #interact(state, request, traceData) {
+		if (!this.#deps.uiBridge) throw new Error("interact() requires a UiBridge");
+		this.#disarmDeadline(state);
+		const waitStartMs = Date.parse(state.now());
+		try {
+			return await this.#interactInner(state, request, traceData);
+		} finally {
+			state.pausedMs += Date.parse(state.now()) - waitStartMs;
+			this.#armDeadline(state);
+		}
+	}
+	async #interactInner(state, request, traceData) {
 		const bridge = this.#deps.uiBridge;
-		if (!bridge) throw new Error("interact() requires a UiBridge");
 		const { run } = state;
 		run.status = "interrupted";
 		run.interruptExpiresAt = new Date(Date.parse(state.now()) + this.#policy.interactionTimeoutMs).toISOString();
@@ -1560,6 +1606,7 @@ var AgentLoop = class {
 		if (typeof pathArg !== "string") return toolError("TOOL_EXECUTION_FAILED", "read_skill_file \"path\" must be a string");
 		if (skillName.startsWith("mcp://")) return this.#handleReadExternalSkill(skillName, pathArg, state);
 		try {
+			if (await this.#guardDenied("canRead", skillName)) return toolError("SKILL_DISABLED", `Skill "${skillName}" is blocked by the skill state guard (read)`);
 			const text = await state.reader.readSkillFile(skillName, pathArg);
 			let note = "";
 			if (pathArg === "SKILL.md" && !state.activated.has(skillName)) note = await this.#activateSkill(skillName, state, void 0, text);
@@ -1577,6 +1624,7 @@ var AgentLoop = class {
 	}
 	/** 经外部技能提供者读取技能文档/资源；skillKey 为技能名或 mcp:// URI */
 	async #handleReadExternalSkill(skillKey, pathArg, state) {
+		const failures = [];
 		for (const provider of this.#deps.skillProviders ?? []) try {
 			let name = skillKey;
 			if (skillKey.startsWith("mcp://")) {
@@ -1610,13 +1658,42 @@ var AgentLoop = class {
 					text: await provider.readFile(name, pathArg)
 				}]
 			};
-		} catch {
+		} catch (e) {
+			failures.push(messageOf$1(e));
 			continue;
 		}
-		return toolError("SKILL_NOT_FOUND", `Skill not found via external providers: ${skillKey}`);
+		const detail = failures.length > 0 ? ` (provider errors: ${failures.join("; ")})` : "";
+		return toolError("SKILL_NOT_FOUND", `Skill not found via external providers: ${skillKey}${detail}`);
+	}
+	/**
+	* 工具结果回喂序列化：超过 toolResultMaxBytes（默认 100KB）时头尾保留截断，
+	* 完整内容经 artifactStore 落 artifact，回喂摘要含 artifact id。
+	*/
+	async #serializeToolResult(call, result, state) {
+		const text = JSON.stringify(result);
+		const max = this.#config.toolResultMaxBytes;
+		if (text.length <= max) return text;
+		const artifact = await this.#deps.artifactStore.createTextArtifact({
+			runId: state.runId,
+			path: `tool-results/${call.id}.json`,
+			content: text
+		});
+		const head = text.slice(0, Math.floor(max * .6));
+		const tail = text.slice(-Math.floor(max * .3));
+		return `${head}\n...[truncated ${text.length - head.length - tail.length} chars; full tool result saved as artifact "${artifact.id}"]...\n${tail}`;
+	}
+	/** SkillStateGuard 判定（无注入默认全放行；仅显式 false 拦截） */
+	async #guardDenied(kind, skillName) {
+		const check = this.#deps.skillStateGuard?.[kind];
+		if (!check) return false;
+		return await check(skillName) === false;
 	}
 	/** 首次读到 SKILL.md 时激活技能：加载其 scripts 工具定义，供后续轮次使用；dependencies 级联激活（via 记录来源） */
 	async #activateSkill(skillName, state, via, skillMdText) {
+		if (await this.#guardDenied("canActivate", skillName)) {
+			state.trace.record("run.warning", { message: `Skill "${skillName}" is blocked by the skill state guard (activate)` });
+			return "";
+		}
 		state.activated.add(skillName);
 		state.trace.record("skill.activated", { data: {
 			skillName,
@@ -1635,7 +1712,9 @@ var AgentLoop = class {
 			const rawAllowed = metadata["allowed-tools"];
 			if (rawAllowed !== void 0) if (Array.isArray(rawAllowed)) allowedTools = rawAllowed.filter((e) => typeof e === "string");
 			else state.trace.record("run.warning", { message: `Skill "${skillName}" has a non-array "allowed-tools" metadata entry; ignored` });
-		} catch {}
+		} catch (e) {
+			state.trace.record("run.warning", { message: `Failed to read or parse SKILL.md of skill "${skillName}": ${messageOf$1(e)}` });
+		}
 		const executor = this.#deps.executor;
 		const loaded = [];
 		if (executor) {
@@ -1654,7 +1733,9 @@ var AgentLoop = class {
 					await this.#enrichDefinition(root, match[1], def, state);
 					state.activatedTools.set(def.name, def);
 					loaded.push(def.name);
-				} catch {}
+				} catch (e) {
+					state.trace.record("run.warning", { message: `Failed to load definition of script "${match[1]}" for skill "${skillName}": ${messageOf$1(e)}` });
+				}
 			}
 		}
 		let note = loaded.length ? `\n\nActivated tools: ${loaded.join(", ")}` : "";
@@ -1728,12 +1809,14 @@ var AgentLoop = class {
 			onArtifactCreated: (artifact) => createdIds.add(artifact.id)
 		});
 		try {
+			if (await this.#guardDenied("canExecute", skillName)) return toolError("SKILL_DISABLED", `Skill "${skillName}" is blocked by the skill state guard (execute)`);
+			const remainingMs = state.totalTimeoutMs - this.#elapsed(state);
 			const result = await this.#deps.executor.execute({
 				skillRoot: root,
 				scriptName,
 				args,
 				context,
-				timeoutMs: state.toolTimeoutMs
+				timeoutMs: Math.max(1, Math.min(state.toolTimeoutMs, remainingMs))
 			});
 			if (createdIds.size > 0) {
 				const fresh = (await this.#deps.artifactStore.listArtifacts(state.runId)).filter((a) => createdIds.has(a.id));
@@ -1912,6 +1995,13 @@ var WebSkillRuntime = class {
 	get events() {
 		return this.#events;
 	}
+	/**
+	* Catalog 缓存失效：下次 run/discover 重新扫描技能目录。
+	* 与 SkillManager onChanged 接线：`new SkillManager({ ..., onChanged: () => runtime.invalidate() })`。
+	*/
+	invalidate() {
+		this.#catalogCache = void 0;
+	}
 	async discover() {
 		const result = await this.#discovery.discover();
 		this.#catalogCache = {
@@ -1924,10 +2014,12 @@ var WebSkillRuntime = class {
 		if (!this.#catalogCache) await this.discover();
 		const cache = this.#catalogCache;
 		if (!cache) throw new Error("discover() did not populate the catalog cache");
+		const providerFailures = [];
 		const providerEntries = (await Promise.all((this.#deps.skillProviders ?? []).map(async (p) => {
 			try {
 				return await p.listSkills();
-			} catch {
+			} catch (e) {
+				providerFailures.push(e instanceof Error ? e.message : String(e));
 				return [];
 			}
 		}))).flat();
@@ -1951,12 +2043,20 @@ var WebSkillRuntime = class {
 			externalTools: this.#deps.externalTools,
 			skillProviders: this.#deps.skillProviders,
 			catalogFilter: this.#deps.catalogFilter,
-			snapshotStore: this.#deps.snapshotStore
+			snapshotStore: this.#deps.snapshotStore,
+			skillStateGuard: this.#deps.skillStateGuard
 		}, this.#deps.config).run({
 			sessionId: this.#session.id,
 			userPrompt,
 			route
 		});
+		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,
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			type: "run.warning",
+			message: `Skill provider listSkills() failed: ${failure}`
+		});
 		if (this.#deps.onSkillMiss && result.run.activeSkillNames.length === 0) this.#deps.onSkillMiss({
 			prompt: userPrompt,
 			run: result.run
@@ -2040,7 +2140,8 @@ var WebSkillRuntime = class {
 			externalTools: this.#deps.externalTools,
 			skillProviders: this.#deps.skillProviders,
 			catalogFilter: this.#deps.catalogFilter,
-			snapshotStore: store
+			snapshotStore: store,
+			skillStateGuard: this.#deps.skillStateGuard
 		}, this.#deps.config).resume(snapshot);
 	}
 };
@@ -2279,6 +2380,7 @@ var FsArtifactStore = class {
 		});
 	}
 	async listArtifacts(runId) {
+		assertSafePathSegment(runId, "runId");
 		const indexPath = `${this.#root}/${runId}/${INDEX_FILE}`;
 		if (!await this.#fs.exists(indexPath)) return [];
 		const raw = await this.#fs.readText(indexPath);
@@ -2290,6 +2392,7 @@ var FsArtifactStore = class {
 		}
 	}
 	#artifactPath(runId, artifactPath) {
+		assertSafePathSegment(runId, "runId");
 		return resolveInsideRoot(`${this.#root}/${runId}`, artifactPath);
 	}
 	async #persist(input) {