@webskill/sdk 0.2.3 → 0.2.5

package/dist/{dist-NM4Mylx4.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-D0saNPi_.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
@@ -272,7 +272,7 @@ var AnthropicClient = class {
 			"content-type": "application/json",
 			"x-api-key": this.#config.apiKey,
 			"anthropic-version": ANTHROPIC_VERSION,
-			"anthropic-dangerous-direct-browser-access": "true"
+			...this.#config.dangerouslyAllowDirectBrowserAccess ? { "anthropic-dangerous-direct-browser-access": "true" } : {}
 		};
 	}
 	async complete(input) {
@@ -571,7 +571,7 @@ var GoogleGenAiClient = class {
 	}
 	async #post(input, stream) {
 		const model = input.model ?? this.#config.model;
-		const action = stream ? `:streamGenerateContent?alt=sse&key=${encodeURIComponent(this.#config.apiKey)}` : `:generateContent?key=${encodeURIComponent(this.#config.apiKey)}`;
+		const action = stream ? ":streamGenerateContent?alt=sse" : ":generateContent";
 		const { systemInstruction, contents } = toGenAiContents(input.messages);
 		const body = { contents };
 		if (systemInstruction) body["systemInstruction"] = systemInstruction;
@@ -581,7 +581,10 @@ var GoogleGenAiClient = class {
 		try {
 			res = await this.#fetch(`${this.#baseUrl()}/v1beta/models/${encodeURIComponent(model)}${action}`, {
 				method: "POST",
-				headers: { "content-type": "application/json" },
+				headers: {
+					"content-type": "application/json",
+					"x-goog-api-key": this.#config.apiKey
+				},
 				body: JSON.stringify(body),
 				signal: input.signal ?? (this.#config.requestTimeoutMs ? AbortSignal.timeout(this.#config.requestTimeoutMs) : null)
 			});
@@ -597,7 +600,7 @@ var GoogleGenAiClient = class {
 	/** 轻量探测（GET /v1beta/models），集成测试据此决定 skip */
 	async checkAvailability() {
 		try {
-			return (await this.#fetch(`${this.#baseUrl()}/v1beta/models?key=${encodeURIComponent(this.#config.apiKey)}`)).ok;
+			return (await this.#fetch(`${this.#baseUrl()}/v1beta/models`, { headers: { "x-goog-api-key": this.#config.apiKey } })).ok;
 		} catch {
 			return false;
 		}
@@ -846,11 +849,12 @@ const ASK_USER_TOOL = {
 */
 function createScriptContext(deps) {
 	const { fs, artifactStore, skillName, skillRoot, runId, confirm, onWarning, onArtifactCreated } = deps;
+	const readFs = fs.withRoot?.(skillRoot) ?? fs;
 	return {
 		skillName,
 		runId,
 		async readReference(relativePath) {
-			return fs.readText(resolveInsideRoot(skillRoot, `references/${relativePath}`));
+			return readFs.readText(resolveInsideRoot(skillRoot, `references/${relativePath}`));
 		},
 		async writeArtifact(path, content, options) {
 			const artifact = typeof content === "string" ? await artifactStore.createTextArtifact({
@@ -963,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;
@@ -982,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);
+		}
 	}
 };
 /**
@@ -996,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) {
@@ -1058,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: [],
@@ -1086,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
 		};
@@ -1144,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();
@@ -1162,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;
 		}
 	}
@@ -1192,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；终态即删快照（快照是续命机制，审计归治理） */
@@ -1288,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 {
@@ -1325,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,
@@ -1336,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)}` });
 		}
 	}
 	/**
@@ -1372,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()
@@ -1451,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;
 		}
 	}
@@ -1560,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",
@@ -1680,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 */
@@ -1720,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("; ")})` : "";
@@ -1734,14 +1765,20 @@ var AgentLoop = class {
 		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
-		});
+		let note;
+		try {
+			note = `full tool result saved as artifact "${(await this.#deps.artifactStore.createTextArtifact({
+				runId: state.runId,
+				path: `tool-results/${call.id}.json`,
+				content: text
+			})).id}"`;
+		} catch (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));
 		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}`;
+		return `${head}\n...[truncated ${text.length - head.length - tail.length} chars; ${note}]...\n${tail}`;
 	}
 	/** SkillStateGuard 判定（无注入默认全放行；仅显式 false 拦截） */
 	async #guardDenied(kind, skillName) {
@@ -1774,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 = [];
@@ -1795,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)}` });
 				}
 			}
 		}
@@ -1821,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"]) {
@@ -1831,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;
 		}
@@ -1892,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 */
@@ -1931,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 原子段内执行（并发不丢计数），否则顺序执行 */
@@ -1944,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;
 		}
@@ -1979,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({
@@ -1987,7 +2025,7 @@ var AgentLoop = class {
 				type: request.type,
 				value
 			});
-			return history;
+			return history.slice(-limit);
 		});
 	}
 };
@@ -2074,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
 */
@@ -2118,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;
 			}
 		};
@@ -2379,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();
@@ -2637,6 +2700,67 @@ function networkUrlHost(url) {
 		return "(unparseable-url)";
 	}
 }
+/** WebSkillErrorCode 全量白名单（错误码归一用；与 core errors.ts 保持同步） */
+const WHITELIST = /* @__PURE__ */ new Set([
+	"FS_NOT_FOUND",
+	"FS_PATH_OUTSIDE_ROOT",
+	"SKILL_NOT_FOUND",
+	"SKILL_INVALID_METADATA",
+	"SKILL_INVALID_NAME",
+	"SKILL_DUPLICATE_NAME",
+	"SKILL_UNSUPPORTED_SCRIPT",
+	"VALIDATION_FAILED",
+	"TOOL_NOT_FOUND",
+	"TOOL_EXECUTION_FAILED",
+	"NETWORK_BLOCKED",
+	"TOOL_UNSUPPORTED",
+	"TOOL_SCHEMA_UNAVAILABLE",
+	"RUN_TIMEOUT",
+	"RUN_MAX_TURNS_EXCEEDED",
+	"RUN_FAILED",
+	"RUN_CANCELLED",
+	"RUN_INTERACTION_TIMEOUT",
+	"UI_UNAVAILABLE",
+	"LLM_UNAVAILABLE",
+	"LLM_REQUEST_FAILED",
+	"INSTALL_FAILED",
+	"UNINSTALL_FAILED",
+	"EXPORT_FAILED",
+	"INTEGRITY_FAILED",
+	"FS_PERMISSION_DENIED",
+	"MCP_ENDPOINT_UNAVAILABLE",
+	"MCP_TOOL_NOT_FOUND",
+	"CANDIDATE_INVALID",
+	"APPROVAL_REQUIRED",
+	"SKILL_QUARANTINED",
+	"SKILL_DISABLED",
+	"SKILL_UNKNOWN_ALLOWED_TOOL",
+	"SKILL_UNKNOWN_DEPENDENCY",
+	"SKILL_CIRCULAR_DEPENDENCY",
+	"GOVERNANCE_FAILED",
+	"RUN_SNAPSHOT_NOT_FOUND",
+	"RUN_SNAPSHOT_EXPIRED",
+	"RUN_SNAPSHOT_INCOMPATIBLE"
+]);
+/**
+* 错误码白名单归一：沙箱/桥消息里出现的非白名单码（DOMException 数值码、
+* Node 任意 ERR_* 码等）一律归为 TOOL_EXECUTION_FAILED。
+*/
+function normalizeErrorCode(code) {
+	return typeof code === "string" && WHITELIST.has(code) ? code : "TOOL_EXECUTION_FAILED";
+}
+/** 归一化后的 (code, message)：非白名单码保留在 message 尾部（[original code: X]） */
+function normalizeToolError(code, message) {
+	const normalized = normalizeErrorCode(code);
+	if (typeof code === "string" && normalized === code) return {
+		code: normalized,
+		message
+	};
+	return {
+		code: normalized,
+		message: `${message} [original code: ${String(code)}]`
+	};
+}
 /**
 * Per-capability 强制授权判定（宿主侧，browser/node 执行器共用单一来源）。
 * 'require-approval' 模式下经注入的 UiBridge 发 authorize 交互；
@@ -2661,6 +2785,7 @@ var CapabilityApproval = class CapabilityApproval {
 	async authorize(input) {
 		const { runId, capability, mode } = input;
 		if (mode === false) return "disabled";
+		if (mode !== true && mode !== "require-approval") 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";
@@ -2688,4 +2813,4 @@ var CapabilityApproval = class CapabilityApproval {
 };
 
 //#endregion
-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 };
+export { isNetworkAllowed as A, toVercelToolSpecs as B, bridgeError as C, extractChartSpec as D, createWebSkillApi as E, normalizeToolError as F, parseBridgeRequest as I, resolveToolName as L, networkUrlHost as M, normalizeErrorCode as N, fromVercelResult as O, normalizeToolContent as P, schemaToForm as R, WebSkillRuntime as S, createScriptContext as T, READ_SKILL_FILE_TOOL as _, AnthropicClient as a, SerializingMemoryStore as b, FsArtifactStore as c, FullDisclosureRouter as d, GoogleGenAiClient as f, READ_SKILL_FILE_INPUT_SCHEMA as g, ProgressiveRouter as h, AgentLoop as i, mergeCatalogEntries as j, fromVercelStreamPart as k, FsMemoryStore as l, OpenAiCompatibleClient as m, ASK_USER_TOOL as n, CapabilityApproval as o, HookRunner as p, ASK_USER_TOOL_NAME as r, EventBus as s, ASK_USER_INPUT_SCHEMA as t, FsRunSnapshotStore as u, READ_SKILL_FILE_TOOL_NAME as v, buildRenderResult as w, TraceRecorder as x, RUN_SNAPSHOT_SCHEMA_VERSION as y, toLlmToolSpec as z };