@webskill/sdk 0.1.4 → 0.2.0

package/dist/{dist-DAn07zHu.js → dist-BS5OpedX.js}

@@ -1,4 +1,4 @@
-import { C as renderAvailableSkillsXml, E as validateSkills, T as resolveInsideRoot, c as SkillReader, d as buildCatalog, l as WebSkillError, s as SkillDiscovery, u as assertSafePathSegment, x as parseSkillMarkdown } from "./dist-DvoBsChX.js";
+import { C as parseSkillMarkdown, E as renderAvailableSkillsXml, c as SkillDiscovery, d as assertSafePathSegment, j as validateSkills, k as resolveInsideRoot, l as SkillReader, p as buildCatalog, u as WebSkillError } from "./dist-D0saNPi_.js";
 import { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.js";
 
 //#region ../runtime/dist/index.js
@@ -986,6 +986,41 @@ var EventBus = class {
 		for (const listener of this.#listeners.get("*") ?? []) listener(frozen);
 	}
 };
+/**
+* per-scope 串行化 MemoryStore 装饰器：同一 scope 的 get/set/delete/list
+* 按 promise 链串行（并发 run 的 read-modify-write 不丢计数）。
+*/
+var SerializingMemoryStore = class {
+	#inner;
+	#chains = /* @__PURE__ */ new Map();
+	constructor(inner) {
+		this.#inner = inner;
+	}
+	#serialize(scope, fn) {
+		const next = (this.#chains.get(scope) ?? Promise.resolve()).then(fn, fn);
+		this.#chains.set(scope, next.catch(() => void 0));
+		return next;
+	}
+	get(scope, key) {
+		return this.#serialize(scope, () => this.#inner.get(scope, key));
+	}
+	set(scope, key, value) {
+		return this.#serialize(scope, () => this.#inner.set(scope, key, value));
+	}
+	delete(scope, key) {
+		return this.#serialize(scope, () => this.#inner.delete(scope, key));
+	}
+	list(scope) {
+		return this.#serialize(scope, () => this.#inner.list(scope));
+	}
+	clear(scope) {
+		return this.#serialize(scope ?? "", () => this.#inner.clear(scope));
+	}
+	/** scope 级原子段：read-modify-write 全段在 promise 链内串行执行（fn 收到底层 store） */
+	transaction(scope, fn) {
+		return this.#serialize(scope, () => fn(this.#inner));
+	}
+};
 /** 结构化 trace 记录器；时钟与 id 工厂可注入（golden trace 用固定值保证确定性） */
 var TraceRecorder = class {
 	#runId;
@@ -1050,6 +1085,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
 		};
@@ -1060,8 +1096,6 @@ var AgentLoop = class {
 		};
 	}
 	async run(input) {
-		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);
@@ -1089,7 +1123,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 ? {
@@ -1109,29 +1148,54 @@ var AgentLoop = class {
 				return [];
 			}
 		}))).flat();
-		state.messages = [{
-			role: "system",
-			content: route.systemPrompt
-		}, {
-			role: "user",
-			content: input.userPrompt
-		}];
+		state.messages = [
+			{
+				role: "system",
+				content: route.systemPrompt
+			},
+			...(input.history ?? []).map((m) => ({ ...m })),
+			{
+				role: "user",
+				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 +1213,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);
 			}
@@ -1165,7 +1232,13 @@ var AgentLoop = class {
 				hasToolCalls: Boolean(response.toolCalls?.length),
 				contentLength: response.content?.length ?? 0
 			} });
-			if (!response.toolCalls?.length) return finish("completed", "final-answer", response.content ?? "");
+			if (!response.toolCalls?.length) {
+				messages.push({
+					role: "assistant",
+					content: response.content ?? ""
+				});
+				return finish("completed", "final-answer", response.content ?? "");
+			}
 			await this.#lifecycle("execute", state, { turn });
 			messages.push({
 				role: "assistant",
@@ -1183,13 +1256,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;
@@ -1229,7 +1303,8 @@ var AgentLoop = class {
 		run.trace = trace.list();
 		return {
 			output,
-			run
+			run,
+			messages: state.messages.map((m) => ({ ...m }))
 		};
 	}
 	/** D3 快照写入（含 pendingInteraction 与过期时间；写失败降级 run.warning） */
@@ -1248,10 +1323,12 @@ var AgentLoop = class {
 			activatedTools: [...state.activatedTools.values()],
 			pendingInteraction: request,
 			interactionExpiresAt: state.run.interruptExpiresAt,
+			renderBlocks: [...state.renderBlocks],
+			interactionSeq: state.interactionSeq,
 			config: {
-				maxTurns: this.#config.maxTurns,
-				totalTimeoutMs: this.#config.totalTimeoutMs,
-				toolTimeoutMs: this.#config.toolTimeoutMs,
+				maxTurns: state.maxTurns,
+				totalTimeoutMs: state.totalTimeoutMs,
+				toolTimeoutMs: state.toolTimeoutMs,
 				...this.#config.temperature !== void 0 ? { temperature: this.#config.temperature } : {}
 			},
 			snapshotAt: state.now()
@@ -1290,10 +1367,15 @@ var AgentLoop = class {
 			activatedTools: new Map(snapshot.activatedTools.map((d) => [d.name, d])),
 			toolTimeoutMs: snapshot.config.toolTimeoutMs,
 			now,
-			interactionSeq: 0,
+			interactionSeq: snapshot.interactionSeq ?? 0,
 			messages: snapshot.messages.map((m) => ({ ...m })),
 			turn: snapshot.turn,
-			renderBlocks: []
+			renderBlocks: (snapshot.renderBlocks ?? []).map((b) => ({ ...b })),
+			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 +1446,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 +1513,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();
@@ -1448,7 +1540,7 @@ var AgentLoop = class {
 		} });
 		let response;
 		try {
-			response = await this.#withInteractionTimeout(bridge.request(request), this.#policy.interactionTimeoutMs);
+			response = await this.#withInteractionTimeout(bridge.request(request), this.#policy.interactionTimeoutMs, () => bridge.cancel?.(request.id));
 		} catch (e) {
 			run.status = "running";
 			run.interruptExpiresAt = void 0;
@@ -1477,9 +1569,14 @@ var AgentLoop = class {
 		await this.#appendParamHistory(state, request, response.value);
 		return response.value;
 	}
-	#withInteractionTimeout(promise, timeoutMs) {
+	#withInteractionTimeout(promise, timeoutMs, onTimeout) {
 		return new Promise((resolve, reject) => {
-			const timer = setTimeout(() => reject(new WebSkillError("RUN_INTERACTION_TIMEOUT", `Interaction timed out after ${timeoutMs}ms`)), timeoutMs);
+			const timer = setTimeout(() => {
+				try {
+					onTimeout?.();
+				} catch {}
+				reject(new WebSkillError("RUN_INTERACTION_TIMEOUT", `Interaction timed out after ${timeoutMs}ms`));
+			}, timeoutMs);
 			promise.then((v) => {
 				clearTimeout(timer);
 				resolve(v);
@@ -1560,6 +1657,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);
@@ -1618,8 +1716,35 @@ var AgentLoop = class {
 		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,
@@ -1644,7 +1769,7 @@ var AgentLoop = class {
 		const executor = this.#deps.executor;
 		const loaded = [];
 		if (executor) {
-			let scriptFiles = [];
+			let scriptFiles;
 			try {
 				scriptFiles = (await this.#deps.fs.list(`${root}/scripts`)).filter((s) => s.type === "file").map((s) => baseName(s.path));
 			} catch {
@@ -1692,8 +1817,12 @@ var AgentLoop = class {
 		for (const ext of ["ts", "js"]) {
 			const scriptPath = `${skillRoot}/scripts/${scriptName}.${ext}`;
 			if (!await this.#deps.fs.exists(scriptPath)) continue;
-			const inferred = this.#deps.schemaInferer.inferSchemaFromSource(await this.#deps.fs.readText(scriptPath), { fileName: `${scriptName}.${ext}` });
-			if (inferred) def.inputSchema = inferred;
+			try {
+				const inferred = this.#deps.schemaInferer.inferSchemaFromSource(await this.#deps.fs.readText(scriptPath), { fileName: `${scriptName}.${ext}` });
+				if (inferred) def.inputSchema = inferred;
+			} catch (e) {
+				state.trace.record("run.warning", { message: `Schema inference failed for ${scriptPath}: ${messageOf$1(e)}` });
+			}
 			return;
 		}
 	}
@@ -1735,12 +1864,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));
@@ -1793,6 +1924,22 @@ var AgentLoop = class {
 			state.trace.record("run.warning", { message: `Memory write failed: ${messageOf$1(e)}` });
 		}
 	}
+	/** read-modify-write：有 transaction 实现在 scope 原子段内执行（并发不丢计数），否则顺序执行 */
+	async #memoryMutate(scope, key, state, mutate) {
+		const memory = this.#deps.memory;
+		if (!memory) return;
+		if (memory.transaction) {
+			try {
+				await memory.transaction(scope, async (inner) => {
+					await inner.set(scope, key, mutate(await inner.get(scope, key)));
+				});
+			} catch (e) {
+				state.trace.record("run.warning", { message: `Memory write failed: ${messageOf$1(e)}` });
+			}
+			return;
+		}
+		await this.#memorySet(scope, key, mutate(await this.#memoryGet(scope, key)), state);
+	}
 	async #writeActivationMemory(skillName, state) {
 		if (!this.#deps.memory) return;
 		const sessionScope = `session:${state.run.sessionId}`;
@@ -1800,33 +1947,38 @@ var AgentLoop = class {
 		await this.#bumpSkillStat(skillName, "activations", state);
 		if (this.#deps.longTerm?.enabled) {
 			const userScope = `user:${this.#deps.longTerm.userId}`;
-			const usage = await this.#memoryGet(userScope, "skillUsage") ?? {};
-			usage[skillName] = (usage[skillName] ?? 0) + 1;
-			await this.#memorySet(userScope, "skillUsage", usage, state);
+			await this.#memoryMutate(userScope, "skillUsage", state, (current) => {
+				const usage = current ?? {};
+				usage[skillName] = (usage[skillName] ?? 0) + 1;
+				return usage;
+			});
 		}
 	}
 	async #bumpSkillStat(skillName, field, state) {
 		if (!this.#deps.memory) return;
-		const scope = `skill:${skillName}`;
-		const stats = await this.#memoryGet(scope, "stats") ?? {
-			activations: 0,
-			successes: 0,
-			failures: 0
-		};
-		stats[field] = (stats[field] ?? 0) + 1;
-		await this.#memorySet(scope, "stats", stats, state);
+		await this.#memoryMutate(`skill:${skillName}`, "stats", state, (current) => {
+			const stats = current ?? {
+				activations: 0,
+				successes: 0,
+				failures: 0
+			};
+			stats[field] = (stats[field] ?? 0) + 1;
+			return stats;
+		});
 	}
 	async #appendParamHistory(state, request, value) {
 		if (!this.#deps.memory) return;
 		const scope = `session:${state.run.sessionId}`;
-		const history = await this.#memoryGet(scope, "paramHistory") ?? [];
-		history.push({
-			ts: state.now(),
-			interactionId: request.id,
-			type: request.type,
-			value
+		await this.#memoryMutate(scope, "paramHistory", state, (current) => {
+			const history = current ?? [];
+			history.push({
+				ts: state.now(),
+				interactionId: request.id,
+				type: request.type,
+				value
+			});
+			return history;
 		});
-		await this.#memorySet(scope, "paramHistory", history, state);
 	}
 };
 /**
@@ -1843,6 +1995,10 @@ const SNAPSHOT_SUFFIX = ".snapshot.json";
 /**
 * FileSystemProvider 后端的快照存储：<root>/<runId>.snapshot.json。
 * 坏 JSON → RUN_SNAPSHOT_INCOMPATIBLE 并自动清理坏文件；runId 过路径安全校验。
+* save/list 时顺带清理已过 interactionExpiresAt 的过期快照。
+*
+* 数据敏感性说明：快照含完整对话历史（用户输入、工具结果、可能的凭据片段），
+* 以明文 JSON 落盘于宿主提供的 fs；宿主应将其视为会话数据同等保护。
 * @experimental
 */
 var FsRunSnapshotStore = class {
@@ -1857,6 +2013,7 @@ var FsRunSnapshotStore = class {
 	}
 	async save(snapshot) {
 		await this.#fs.writeText(this.#path(snapshot.runId), JSON.stringify(snapshot, null, 2));
+		await this.#pruneExpired();
 	}
 	async load(runId) {
 		const path = this.#path(runId);
@@ -1880,6 +2037,7 @@ var FsRunSnapshotStore = class {
 		if (await this.#fs.exists(path)) await this.#fs.remove(path);
 	}
 	async list() {
+		await this.#pruneExpired();
 		if (!await this.#fs.exists(this.#root)) return [];
 		const out = [];
 		for (const entry of await this.#fs.list(this.#root)) {
@@ -1890,6 +2048,20 @@ var FsRunSnapshotStore = class {
 		}
 		return out.sort((a, b) => a.snapshotAt.localeCompare(b.snapshotAt));
 	}
+	/** 过期快照清理（save/list 时顺带；失败静默不阻断主流程） */
+	async #pruneExpired() {
+		try {
+			if (!await this.#fs.exists(this.#root)) return;
+			const now = Date.now();
+			for (const entry of await this.#fs.list(this.#root)) {
+				if (entry.type !== "file" || !entry.path.endsWith(SNAPSHOT_SUFFIX)) continue;
+				try {
+					const parsed = JSON.parse(await this.#fs.readText(entry.path));
+					if (parsed.interactionExpiresAt !== void 0 && Date.parse(parsed.interactionExpiresAt) < now) await this.#fs.remove(entry.path);
+				} catch {}
+			}
+		} catch {}
+	}
 };
 /**
 * runtime 门面：组合 discovery / router / agent loop / lifecycle
@@ -1903,7 +2075,10 @@ var WebSkillRuntime = class {
 	#events;
 	#catalogCache;
 	constructor(deps) {
-		this.#deps = deps;
+		this.#deps = {
+			...deps,
+			...deps.memory ? { memory: new SerializingMemoryStore(deps.memory) } : {}
+		};
 		this.#discovery = new SkillDiscovery(deps.fs, deps.roots);
 		this.#router = deps.router ?? new ProgressiveRouter();
 		this.#events = deps.eventBus ?? new EventBus();
@@ -1919,6 +2094,34 @@ var WebSkillRuntime = class {
 	get events() {
 		return this.#events;
 	}
+	/**
+	* Catalog 缓存失效：下次 run/discover 重新扫描技能目录。
+	* 与 SkillManager onChanged 接线：`new SkillManager({ ..., onChanged: () => runtime.invalidate() })`。
+	*/
+	invalidate() {
+		this.#catalogCache = void 0;
+	}
+	/**
+	* 多会话：session 对象的 run(prompt) 跨 run 延续消息历史（同一 session 对话上下文连续）。
+	* 既有 runtime.run(prompt) 保持无状态单次语义不变。
+	*/
+	createSession(options = {}) {
+		const sessionId = options.sessionId ?? `session-${Math.random().toString(36).slice(2, 10)}`;
+		const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+		let history = [];
+		return {
+			id: sessionId,
+			createdAt,
+			run: async (prompt) => {
+				const result = await this.run(prompt, {
+					sessionId,
+					history
+				});
+				history = result.messages.slice(1);
+				return result;
+			}
+		};
+	}
 	async discover() {
 		const result = await this.#discovery.discover();
 		this.#catalogCache = {
@@ -1927,7 +2130,7 @@ var WebSkillRuntime = class {
 		};
 		return result;
 	}
-	async run(userPrompt) {
+	async run(userPrompt, options = {}) {
 		if (!this.#catalogCache) await this.discover();
 		const cache = this.#catalogCache;
 		if (!cache) throw new Error("discover() did not populate the catalog cache");
@@ -1960,11 +2163,13 @@ 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,
+			sessionId: options.sessionId ?? this.#session.id,
 			userPrompt,
-			route
+			route,
+			...options.history ? { history: options.history } : {}
 		});
 		for (const failure of providerFailures) result.run.trace.push({
 			id: `evt-provider-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
@@ -2033,7 +2238,8 @@ var WebSkillRuntime = class {
 							code: "RUN_INTERACTION_TIMEOUT"
 						}
 					}]
-				}
+				},
+				messages: []
 			};
 		}
 		if (!this.#catalogCache) await this.discover();
@@ -2056,7 +2262,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);
 	}
 };
@@ -2134,7 +2341,7 @@ function createWebSkillApi(deps) {
 		}
 	};
 }
-/** install URL 分派：http(s)…​.zip → http；…​.git → git（无 git 能力的 manager 自行 TOOL_UNSUPPORTED）；
+/** install URL 分派：http(s) .zip → http；.git → git（无 git 能力的 manager 自行 TOOL_UNSUPPORTED）；
 * 其余 http(s) URL → INSTALL_FAILED（不静默当 local）；非 URL → local */
 function sourceFromUrl(url) {
 	const bare = url.split("?")[0] ?? url;
@@ -2422,16 +2629,21 @@ function networkUrlHost(url) {
 * once-per-run（默认）在 run 内记忆已批准能力，every-call 每次调用都问。
 * @stable
 */
-var CapabilityApproval = class {
+var CapabilityApproval = class CapabilityApproval {
 	#uiBridge;
 	#scope;
-	/** runId → 已批准能力集合（once-per-run 记忆） */
+	/** runId → 已批准能力集合（once-per-run 记忆；LRU 上限防长跑进程膨胀） */
 	#approved = /* @__PURE__ */ new Map();
 	#seq = 0;
+	static #MAX_RUNS = 128;
 	constructor(deps = {}) {
 		this.#uiBridge = deps.uiBridge;
 		this.#scope = deps.scope ?? "once-per-run";
 	}
+	/** run 终态清理授权记录（宿主在 run 结束后调用；同时有 LRU 上限兜底） */
+	clearRun(runId) {
+		this.#approved.delete(runId);
+	}
 	async authorize(input) {
 		const { runId, capability, mode } = input;
 		if (mode === false) return "disabled";
@@ -2452,10 +2664,14 @@ var CapabilityApproval = class {
 				this.#approved.set(runId, set);
 			}
 			set.add(capability);
+			if (this.#approved.size > CapabilityApproval.#MAX_RUNS) {
+				const oldest = this.#approved.keys().next().value;
+				if (oldest !== void 0) this.#approved.delete(oldest);
+			}
 		}
 		return "allowed";
 	}
 };
 
 //#endregion
-export { mergeCatalogEntries as A, buildRenderResult as C, fromVercelResult as D, extractChartSpec as E, schemaToForm as F, toLlmToolSpec as I, toVercelToolSpecs as L, normalizeToolContent as M, parseBridgeRequest as N, fromVercelStreamPart as O, resolveToolName as P, bridgeError as S, createWebSkillApi as T, READ_SKILL_FILE_TOOL as _, AnthropicClient as a, TraceRecorder as b, FsArtifactStore as c, FullDisclosureRouter as d, GoogleGenAiClient as f, READ_SKILL_FILE_INPUT_SCHEMA as g, ProgressiveRouter as h, AgentLoop as i, networkUrlHost as j, isNetworkAllowed 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, createScriptContext as w, WebSkillRuntime as x, RUN_SNAPSHOT_SCHEMA_VERSION as y };
+export { isNetworkAllowed as A, bridgeError as C, extractChartSpec as D, createWebSkillApi as E, resolveToolName as F, schemaToForm as I, toLlmToolSpec as L, networkUrlHost as M, normalizeToolContent as N, fromVercelResult as O, parseBridgeRequest as P, toVercelToolSpecs 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 };