@webskill/sdk 0.2.4 → 0.2.5

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-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-CKm5G_eQ-BqyXnvoR.js";
-import { Et as parseBridgeRequest, N as NetworkPolicy, Q as ScriptExecutor, Z as ScriptExecutionContext, d as BridgeCapabilities, it as ToolResult, m as BridgeResponse, nt as ToolDefinition, p as BridgeRequest, pt as bridgeError, u as ApprovalScope, ut as WebSkillApi, v as ExternalSkillProvider, y as ExternalToolSource } from "./index-DZShzhon.js";
+import { B as SkillManifest, C as FileStat, G as SkillsLockfile, L as SkillInstallSource, _ as RenderResultRequest, a as InteractionPolicy, c as LlmClient, d as LlmResponse, f as LlmStreamEvent, o as InteractionRequest, q as VerifyResult, s as InteractionResponse, v as UiBridge, w as FileSystemProvider, y as ArchiveLimits } from "./types-CKm5G_eQ-krKWW8WV.js";
+import { Et as parseBridgeRequest, N as NetworkPolicy, Q as ScriptExecutor, Z as ScriptExecutionContext, d as BridgeCapabilities, it as ToolResult, m as BridgeResponse, nt as ToolDefinition, p as BridgeRequest, pt as bridgeError, u as ApprovalScope, ut as WebSkillApi, v as ExternalSkillProvider, y as ExternalToolSource } from "./index-DfINBEOy.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */

package/dist/browser.js

@@ -1,6 +1,6 @@
-import { A as unzipWithLimits, C as parseSkillMarkdown, M as verifyManifest, T as readResponseWithLimit, b as isValidSkillName, c as SkillDiscovery, f as atomicWriteText, i as SKILL_MANIFEST_FILE, j as validateSkills, k as resolveInsideRoot, m as buildManifest, p as buildCatalog, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, w as parseSkillPackManifest, y as exportSkills } from "./dist-D7MsoMPx.js";
-import { A as isNetworkAllowed, C as bridgeError, E as createWebSkillApi, F as normalizeToolError, I as parseBridgeRequest, M as networkUrlHost, P as normalizeToolContent, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as mergeCatalogEntries, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-CV64gN62.js";
-import { n as MockLlmClient } from "./testing-BN18eqbD.js";
+import { C as messageOf, D as readResponseWithLimit, E as parseSkillPackManifest, M as unzipWithLimits, N as validateSkills, P as verifyManifest, T as parseSkillMarkdown, b as exportSkills, c as SkillDiscovery, d as assertRemoteUrlAllowed, h as buildManifest, i as SKILL_MANIFEST_FILE, j as resolveInsideRoot, m as buildCatalog, p as atomicWriteText, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, x as isValidSkillName } from "./dist-BQzncxXg.js";
+import { A as isNetworkAllowed, C as bridgeError, E as createWebSkillApi, F as normalizeToolError, I as parseBridgeRequest, M as networkUrlHost, P as normalizeToolContent, c as FsArtifactStore, h as ProgressiveRouter, i as AgentLoop, j as mergeCatalogEntries, l as FsMemoryStore, m as OpenAiCompatibleClient, o as CapabilityApproval, u as FsRunSnapshotStore, y as RUN_SNAPSHOT_SCHEMA_VERSION } from "./dist-B77plHjw.js";
+import { n as MockLlmClient } from "./testing-BUoXvm1u.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -462,8 +462,7 @@ async function extractZipWeb(fs, data, destRoot, limits) {
 		else await fs.writeBinary(target, content);
 	}
 }
-const messageOf$1 = (e) => e instanceof Error ? e.message : String(e);
-const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED") ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf$1(e)}`, e);
+const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED") ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
 const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
 /**
 * D5：浏览器技能安装（http(s) zip / ArrayBuffer；tar/git/npm → TOOL_UNSUPPORTED）。
@@ -494,9 +493,15 @@ var BrowserSkillManager = class {
 			if (source.type === "http") {
 				let res;
 				try {
-					res = await (this.#fetchImpl ?? fetch)(source.url);
+					const absolute = new URL(source.url, typeof location !== "undefined" ? location.href : void 0).href;
+					const url = assertRemoteUrlAllowed(absolute, {
+						allowHttp: source.allowHttp ?? false,
+						allowPrivateHosts: source.allowPrivateHosts ?? false
+					});
+					res = await (this.#fetchImpl ?? fetch)(url.href);
 				} catch (e) {
-					throw new WebSkillError("INSTALL_FAILED", `Download failed: ${messageOf$1(e)}`, e);
+					if (e instanceof WebSkillError) throw e;
+					throw new WebSkillError("INSTALL_FAILED", `Download failed: ${messageOf(e)}`, e);
 				}
 				if (!res.ok) throw new WebSkillError("INSTALL_FAILED", `Download failed with HTTP ${res.status}`);
 				data = await readResponseWithLimit(res, this.#archiveLimits);
@@ -526,7 +531,7 @@ var BrowserSkillManager = class {
 				name = metadata.name;
 				version = typeof metadata["version"] === "string" ? metadata["version"] : void 0;
 			} catch (e) {
-				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf$1(e)}`, e);
+				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf(e)}`, e);
 			}
 			if (!isValidSkillName(name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in SKILL.md (path traversal rejected): ${JSON.stringify(name)}`);
 			const finalRoot = `${stagingRoot}/final`;
@@ -592,7 +597,7 @@ var BrowserSkillManager = class {
 					name = metadata.name;
 					versions.set(name, typeof metadata["version"] === "string" ? metadata["version"] : void 0);
 				} catch (e) {
-					throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md of pack entry "${entry.name}": ${messageOf$1(e)}`, e);
+					throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md of pack entry "${entry.name}": ${messageOf(e)}`, e);
 				}
 				if (name !== entry.name) throw new WebSkillError("INSTALL_FAILED", `Skill pack entry "${entry.name}" does not match the SKILL.md name "${name}"`);
 				await copyDir(fs, skillDir, `${finalRoot}/${name}`);
@@ -674,7 +679,7 @@ var BrowserSkillManager = class {
 			await this.#removeLockEntry(name);
 			this.#onChanged?.();
 		} catch (e) {
-			throw new WebSkillError("UNINSTALL_FAILED", `Failed to uninstall "${name}": ${messageOf$1(e)}`, e);
+			throw new WebSkillError("UNINSTALL_FAILED", `Failed to uninstall "${name}": ${messageOf(e)}`, e);
 		}
 	}
 	async verifyIntegrity(name) {
@@ -694,7 +699,7 @@ var BrowserSkillManager = class {
 		try {
 			return JSON.parse(await this.#fs.readText(path));
 		} catch (e) {
-			throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${messageOf$1(e)}`, e);
+			throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${messageOf(e)}`, e);
 		}
 	}
 	async #createManifest(skillRoot, input) {
@@ -726,7 +731,7 @@ var BrowserSkillManager = class {
 		try {
 			return JSON.parse(await this.#fs.readText(path));
 		} catch (e) {
-			throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest at ${path} is corrupted: ${messageOf$1(e)}`, e);
+			throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest at ${path} is corrupted: ${messageOf(e)}`, e);
 		}
 	}
 	async #upsertLockEntry(name, entry) {
@@ -864,7 +869,6 @@ const resolveWorkerFactory = (mode) => {
 	return blobWorkerFactory;
 };
 const baseName = (p) => p.split("/").pop() ?? p;
-const messageOf = (e) => e instanceof Error ? e.message : String(e);
 /**
 * Web Worker 脚本沙箱执行器：loadDefinition 与 execute 都在 Worker 内完成，
 * 主线程从不 import 技能脚本；每次执行独立 Worker；超时 terminate 强杀。

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

@@ -1,4 +1,4 @@
-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-D7MsoMPx.js";
+import { C as messageOf, N as validateSkills, O as renderAvailableSkillsXml, T as parseSkillMarkdown, c as SkillDiscovery, f as assertSafePathSegment, j as resolveInsideRoot, l as SkillReader, m as buildCatalog, u as WebSkillError } from "./dist-BQzncxXg.js";
 import { t as MemoryArtifactStore } from "./memoryArtifactStore-C9lFVqPF-yFz6yJj0.js";
 
 //#region ../runtime/dist/index.js
@@ -967,6 +967,13 @@ function mapFieldType(prop) {
 /** 生命周期事件总线：只读观测，支持按阶段或通配订阅 */
 var EventBus = class {
 	#listeners = /* @__PURE__ */ new Map();
+	/** 监听器异常出口（默认 console.warn；单个监听器抛错不影响其他监听器与 emit 调用方） */
+	#onListenerError;
+	constructor(onListenerError) {
+		this.#onListenerError = onListenerError ?? ((error, event) => {
+			console.warn(`EventBus listener threw on phase "${event.phase}": ${error instanceof Error ? error.message : String(error)}`);
+		});
+	}
 	/** 返回取消订阅函数 */
 	on(phase, listener) {
 		const key = phase;
@@ -986,8 +993,15 @@ var EventBus = class {
 	}
 	emit(event) {
 		const frozen = Object.freeze(event);
-		for (const listener of this.#listeners.get(event.phase) ?? []) listener(frozen);
-		for (const listener of this.#listeners.get("*") ?? []) listener(frozen);
+		for (const listener of this.#listeners.get(event.phase) ?? []) this.#dispatch(listener, frozen);
+		for (const listener of this.#listeners.get("*") ?? []) this.#dispatch(listener, frozen);
+	}
+	#dispatch(listener, event) {
+		try {
+			listener(event);
+		} catch (e) {
+			this.#onListenerError(e, event);
+		}
 	}
 };
 /**
@@ -1000,9 +1014,17 @@ var SerializingMemoryStore = class {
 	constructor(inner) {
 		this.#inner = inner;
 	}
+	/** 当前链上的 scope 数（监控/测试用；空闲时应回落到 0） */
+	get trackedScopeCount() {
+		return this.#chains.size;
+	}
 	#serialize(scope, fn) {
 		const next = (this.#chains.get(scope) ?? Promise.resolve()).then(fn, fn);
-		this.#chains.set(scope, next.catch(() => void 0));
+		const guarded = next.catch(() => void 0);
+		this.#chains.set(scope, guarded);
+		guarded.then(() => {
+			if (this.#chains.get(scope) === guarded) this.#chains.delete(scope);
+		});
 		return next;
 	}
 	get(scope, key) {
@@ -1062,7 +1084,6 @@ var RunTerminated = class extends Error {
 /** bridge.request 自身异常（非超时）：恢复 running 后转为工具错误回喂 */
 var BridgeRequestError = class extends Error {};
 const baseName = (p) => p.split("/").pop() ?? p;
-const messageOf$1 = (e) => e instanceof Error ? e.message : String(e);
 const toolError = (code, message) => ({
 	ok: false,
 	content: [],
@@ -1090,6 +1111,7 @@ var AgentLoop = class {
 			totalTimeoutMs: config.totalTimeoutMs ?? 12e4,
 			toolTimeoutMs: config.toolTimeoutMs ?? 3e4,
 			toolResultMaxBytes: config.toolResultMaxBytes ?? 1e5,
+			paramHistoryLimit: config.paramHistoryLimit ?? 50,
 			temperature: config.temperature,
 			renderResult: config.renderResult
 		};
@@ -1148,7 +1170,7 @@ var AgentLoop = class {
 			try {
 				return await source.listToolSpecs();
 			} catch (e) {
-				trace.record("run.warning", { message: `External tool source "${source.kind}" failed to list specs: ${messageOf$1(e)}` });
+				trace.record("run.warning", { message: `External tool source "${source.kind}" failed to list specs: ${messageOf(e)}` });
 				return [];
 			}
 		}))).flat();
@@ -1166,7 +1188,7 @@ var AgentLoop = class {
 		try {
 			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");
+			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return this.#finish(state, "failed", "hook-error", messageOf(e), "RUN_FAILED");
 			throw e;
 		}
 	}
@@ -1196,73 +1218,77 @@ var AgentLoop = class {
 		const { llm } = this.#deps;
 		const { trace, messages } = state;
 		this.#armDeadline(state);
-		for (let turn = startTurn;; turn++) {
-			state.turn = turn;
-			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)] : [],
-				...[...state.activatedTools.values()].map(toLlmToolSpec),
-				...externalSpecs
-			];
-			trace.record("llm.request", { data: {
-				turn,
-				messageCount: messages.length,
-				toolCount: toolSpecs.length
-			} });
-			let response;
-			try {
-				response = llm.stream ? await this.#completeStreaming(llm, state, {
-					model: this.#deps.model,
-					messages,
-					tools: toolSpecs,
-					temperature: this.#config.temperature,
-					signal: state.controller.signal
-				}) : await llm.complete({
-					model: this.#deps.model,
-					messages,
-					tools: toolSpecs,
-					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);
-			}
-			trace.record("llm.response", { data: {
-				turn,
-				hasToolCalls: Boolean(response.toolCalls?.length),
-				contentLength: response.content?.length ?? 0
-			} });
-			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",
-				content: response.content ?? "",
-				toolCalls: response.toolCalls
-			});
-			for (const call of response.toolCalls) {
-				let result;
+		try {
+			for (let turn = startTurn;; turn++) {
+				state.turn = turn;
+				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)] : [],
+					...[...state.activatedTools.values()].map(toLlmToolSpec),
+					...externalSpecs
+				];
+				trace.record("llm.request", { data: {
+					turn,
+					messageCount: messages.length,
+					toolCount: toolSpecs.length
+				} });
+				let response;
 				try {
-					result = await this.#executeCall(call, state);
+					response = llm.stream ? await this.#completeStreaming(llm, state, {
+						model: this.#deps.model,
+						messages,
+						tools: toolSpecs,
+						temperature: this.#config.temperature,
+						signal: state.controller.signal
+					}) : await llm.complete({
+						model: this.#deps.model,
+						messages,
+						tools: toolSpecs,
+						temperature: this.#config.temperature,
+						signal: state.controller.signal
+					});
 				} catch (e) {
-					if (e instanceof RunTerminated) return finish(e.outcome.status, e.outcome.reason, e.outcome.message, e.outcome.code);
-					throw 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(e), code);
 				}
+				trace.record("llm.response", { data: {
+					turn,
+					hasToolCalls: Boolean(response.toolCalls?.length),
+					contentLength: response.content?.length ?? 0
+				} });
+				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: "tool",
-					toolCallId: call.id,
-					content: await this.#serializeToolResult(call, result, state)
+					role: "assistant",
+					content: response.content ?? "",
+					toolCalls: response.toolCalls
 				});
+				for (const call of response.toolCalls) {
+					let result;
+					try {
+						result = await this.#executeCall(call, state);
+					} catch (e) {
+						if (e instanceof RunTerminated) return finish(e.outcome.status, e.outcome.reason, e.outcome.message, e.outcome.code);
+						throw e;
+					}
+					messages.push({
+						role: "tool",
+						toolCallId: call.id,
+						content: await this.#serializeToolResult(call, result, state)
+					});
+				}
 			}
+		} finally {
+			this.#disarmDeadline(state);
 		}
 	}
 	/** 统一终态处理：completed/failed/cancelled；终态即删快照（快照是续命机制，审计归治理） */
@@ -1292,17 +1318,17 @@ var AgentLoop = class {
 			await bridge.renderResult(request);
 			trace.record("ui.rendered", { data: { blockCount: request.blocks.length } });
 		} catch (e) {
-			trace.record("run.warning", { message: `renderResult failed: ${messageOf$1(e)}` });
+			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$1(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$1(e)}` });
+			trace.record("run.warning", { message: `Terminal lifecycle hook failed: ${messageOf(e)}` });
 		}
 		run.trace = trace.list();
 		return {
@@ -1329,6 +1355,7 @@ var AgentLoop = class {
 			interactionExpiresAt: state.run.interruptExpiresAt,
 			renderBlocks: [...state.renderBlocks],
 			interactionSeq: state.interactionSeq,
+			pausedMs: state.pausedMs,
 			config: {
 				maxTurns: state.maxTurns,
 				totalTimeoutMs: state.totalTimeoutMs,
@@ -1340,7 +1367,7 @@ var AgentLoop = class {
 		try {
 			await store.save(snapshot);
 		} catch (e) {
-			state.trace.record("run.warning", { message: `Failed to save run snapshot: ${messageOf$1(e)}` });
+			state.trace.record("run.warning", { message: `Failed to save run snapshot: ${messageOf(e)}` });
 		}
 	}
 	/**
@@ -1376,7 +1403,7 @@ var AgentLoop = class {
 			turn: snapshot.turn,
 			renderBlocks: (snapshot.renderBlocks ?? []).map((b) => ({ ...b })),
 			startMs,
-			pausedMs: 0,
+			pausedMs: snapshot.pausedMs ?? 0,
 			maxTurns: snapshot.config.maxTurns,
 			totalTimeoutMs: snapshot.config.totalTimeoutMs,
 			controller: new AbortController()
@@ -1455,14 +1482,14 @@ var AgentLoop = class {
 			try {
 				return await source.listToolSpecs();
 			} catch (e) {
-				trace.record("run.warning", { message: `External tool source "${source.kind}" failed to list specs: ${messageOf$1(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, 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");
+			if (e instanceof WebSkillError && e.code === "RUN_FAILED") return this.#finish(state, "failed", "hook-error", messageOf(e), "RUN_FAILED");
 			throw e;
 		}
 	}
@@ -1564,8 +1591,8 @@ var AgentLoop = class {
 				message: e.message,
 				code: "RUN_INTERACTION_TIMEOUT"
 			});
-			state.trace.record("run.warning", { message: `UiBridge request failed: ${messageOf$1(e)}` });
-			throw new BridgeRequestError(messageOf$1(e));
+			state.trace.record("run.warning", { message: `UiBridge request failed: ${messageOf(e)}` });
+			throw new BridgeRequestError(messageOf(e));
 		}
 		if (response.cancelled) throw new RunTerminated({
 			status: "cancelled",
@@ -1684,7 +1711,7 @@ var AgentLoop = class {
 			};
 		} catch (e) {
 			if (e instanceof WebSkillError && e.code === "SKILL_NOT_FOUND" && (this.#deps.skillProviders?.length ?? 0) > 0) return this.#handleReadExternalSkill(skillName, pathArg, state);
-			return toolError(e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", `read_skill_file failed: ${messageOf$1(e)}`);
+			return toolError(e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", `read_skill_file failed: ${messageOf(e)}`);
 		}
 	}
 	/** 经外部技能提供者读取技能文档/资源；skillKey 为技能名或 mcp:// URI */
@@ -1724,7 +1751,7 @@ var AgentLoop = class {
 				}]
 			};
 		} catch (e) {
-			failures.push(messageOf$1(e));
+			failures.push(messageOf(e));
 			continue;
 		}
 		const detail = failures.length > 0 ? ` (provider errors: ${failures.join("; ")})` : "";
@@ -1746,7 +1773,7 @@ var AgentLoop = class {
 				content: text
 			})).id}"`;
 		} catch (e) {
-			state.trace.record("run.warning", { message: `Failed to persist oversized tool result artifact for "${call.name}": ${messageOf$1(e)}` });
+			state.trace.record("run.warning", { message: `Failed to persist oversized tool result artifact for "${call.name}": ${messageOf(e)}` });
 			note = "full result discarded (artifact store unavailable)";
 		}
 		const head = text.slice(0, Math.floor(max * .6));
@@ -1784,7 +1811,7 @@ var AgentLoop = class {
 			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 (e) {
-			state.trace.record("run.warning", { message: `Failed to read or parse SKILL.md of skill "${skillName}": ${messageOf$1(e)}` });
+			state.trace.record("run.warning", { message: `Failed to read or parse SKILL.md of skill "${skillName}": ${messageOf(e)}` });
 		}
 		const executor = this.#deps.executor;
 		const loaded = [];
@@ -1805,7 +1832,7 @@ var AgentLoop = class {
 					state.activatedTools.set(def.name, def);
 					loaded.push(def.name);
 				} catch (e) {
-					state.trace.record("run.warning", { message: `Failed to load definition of script "${match[1]}" for skill "${skillName}": ${messageOf$1(e)}` });
+					state.trace.record("run.warning", { message: `Failed to load definition of script "${match[1]}" for skill "${skillName}": ${messageOf(e)}` });
 				}
 			}
 		}
@@ -1831,7 +1858,7 @@ var AgentLoop = class {
 			def.inputSchema = JSON.parse(await this.#deps.fs.readText(sidecar));
 			return;
 		} catch (e) {
-			state.trace.record("run.warning", { message: `Failed to parse schema sidecar ${sidecar}: ${messageOf$1(e)}` });
+			state.trace.record("run.warning", { message: `Failed to parse schema sidecar ${sidecar}: ${messageOf(e)}` });
 		}
 		if (!this.#deps.schemaInferer) return;
 		for (const ext of ["ts", "js"]) {
@@ -1841,7 +1868,7 @@ var AgentLoop = class {
 				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)}` });
+				state.trace.record("run.warning", { message: `Schema inference failed for ${scriptPath}: ${messageOf(e)}` });
 			}
 			return;
 		}
@@ -1902,7 +1929,7 @@ var AgentLoop = class {
 		} catch (e) {
 			if (e instanceof RunTerminated) throw e;
 			await this.#bumpSkillStat(skillName, "failures", state);
-			return toolError(e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", `Tool "${call.name}" failed: ${messageOf$1(e)}`);
+			return toolError(e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", `Tool "${call.name}" failed: ${messageOf(e)}`);
 		}
 	}
 	/** context.confirm 触发点：默认真实询问；auto-approve 直通；无 bridge 降级直通 + warning */
@@ -1941,7 +1968,7 @@ var AgentLoop = class {
 		try {
 			await this.#deps.memory?.set(scope, key, value);
 		} catch (e) {
-			state.trace.record("run.warning", { message: `Memory write failed: ${messageOf$1(e)}` });
+			state.trace.record("run.warning", { message: `Memory write failed: ${messageOf(e)}` });
 		}
 	}
 	/** read-modify-write：有 transaction 实现在 scope 原子段内执行（并发不丢计数），否则顺序执行 */
@@ -1954,7 +1981,7 @@ var AgentLoop = class {
 					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)}` });
+				state.trace.record("run.warning", { message: `Memory write failed: ${messageOf(e)}` });
 			}
 			return;
 		}
@@ -1989,6 +2016,7 @@ var AgentLoop = class {
 	async #appendParamHistory(state, request, value) {
 		if (!this.#deps.memory) return;
 		const scope = `session:${state.run.sessionId}`;
+		const limit = this.#config.paramHistoryLimit;
 		await this.#memoryMutate(scope, "paramHistory", state, (current) => {
 			const history = current ?? [];
 			history.push({
@@ -1997,7 +2025,7 @@ var AgentLoop = class {
 				type: request.type,
 				value
 			});
-			return history;
+			return history.slice(-limit);
 		});
 	}
 };
@@ -2084,6 +2112,24 @@ var FsRunSnapshotStore = class {
 	}
 };
 /**
+* session history 滚动裁剪：超出预算时裁掉中段，保留首尾。
+* 边界对齐 LLM tool 契约：head 不以未应答的 assistant toolCalls 结尾，
+* tail 不以孤儿 tool 消息开头（其 assistant 调用已随中段裁掉）。
+*/
+function trimSessionHistory(messages, max) {
+	if (max < 2 || messages.length <= max) return messages;
+	let head = Math.ceil(max / 2);
+	while (head > 0) {
+		const last = messages[head - 1];
+		if (last.role === "assistant" && last.toolCalls?.length) head -= 1;
+		else break;
+	}
+	let tailStart = Math.max(head, messages.length - (max - head));
+	while (tailStart < messages.length && messages[tailStart].role === "tool") tailStart += 1;
+	if (tailStart >= messages.length) return messages.slice(-max);
+	return [...messages.slice(0, head), ...messages.slice(tailStart)];
+}
+/**
 * runtime 门面：组合 discovery / router / agent loop / lifecycle
 * @stable
 */
@@ -2128,20 +2174,28 @@ var WebSkillRuntime = class {
 	/**
 	* 多会话：session 对象的 run(prompt) 跨 run 延续消息历史（同一 session 对话上下文连续）。
 	* 既有 runtime.run(prompt) 保持无状态单次语义不变。
+	* 同 handle 并发 run 经 per-handle 队列串行化（防历史 last-writer-wins 丢轮次）；
+	* maxHistoryMessages（默认 100）超出时滚动裁剪中段（保留首尾；边界对齐 tool 契约）。
 	*/
 	createSession(options = {}) {
 		const sessionId = options.sessionId ?? `session-${Math.random().toString(36).slice(2, 10)}`;
 		const createdAt = (/* @__PURE__ */ new Date()).toISOString();
+		const maxHistory = options.maxHistoryMessages ?? 100;
 		let history = [];
+		let queue = Promise.resolve();
 		return {
 			id: sessionId,
 			createdAt,
-			run: async (prompt) => {
-				const result = await this.run(prompt, {
-					sessionId,
-					history
+			run: (prompt) => {
+				const result = queue.then(async () => {
+					const r = await this.run(prompt, {
+						sessionId,
+						history
+					});
+					history = trimSessionHistory(r.messages.slice(1), maxHistory);
+					return r;
 				});
-				history = result.messages.slice(1);
+				queue = result.then(() => void 0, () => void 0);
 				return result;
 			}
 		};
@@ -2389,7 +2443,6 @@ function sourceFromUrl(url) {
 		path: url
 	};
 }
-const messageOf = (e) => e instanceof Error ? e.message : String(e);
 /** 受控钩子执行器：逐个执行，超时/异常默认降级为 warning，可切严格模式 */
 var HookRunner = class {
 	#hooks = /* @__PURE__ */ new Map();