@webskill/sdk 0.2.4 → 0.2.6

package/dist/{dist-CV64gN62.js → dist-BXpDDZpR.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
@@ -40,7 +40,7 @@ var OpenAiCompatibleClient = class {
 	#fetch;
 	constructor(config) {
 		this.#config = config;
-		this.#fetch = config.fetchImpl ?? fetch;
+		this.#fetch = config.fetchImpl ?? ((input, init) => fetch(input, init));
 	}
 	#requireConfig() {
 		const { baseUrl, apiKey, model } = this.#config;
@@ -262,7 +262,7 @@ var AnthropicClient = class {
 	#fetch;
 	constructor(config) {
 		this.#config = config;
-		this.#fetch = config.fetchImpl ?? fetch;
+		this.#fetch = config.fetchImpl ?? ((input, init) => fetch(input, init));
 	}
 	#baseUrl() {
 		return (this.#config.baseUrl ?? "https://api.anthropic.com").replace(/\/+$/, "");
@@ -491,7 +491,7 @@ var GoogleGenAiClient = class {
 	#fetch;
 	constructor(config) {
 		this.#config = config;
-		this.#fetch = config.fetchImpl ?? fetch;
+		this.#fetch = config.fetchImpl ?? ((input, init) => fetch(input, init));
 	}
 	#baseUrl() {
 		return (this.#config.baseUrl ?? "https://generativelanguage.googleapis.com").replace(/\/+$/, "");
@@ -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: [],
@@ -1071,6 +1092,11 @@ const toolError = (code, message) => ({
 		message
 	}
 });
+/** 工具参数摘要（JSON 截断 100 字符；trace 与实时事件同一口径，ToolCallCard 展开详情用） */
+const summarizeArgs = (args) => {
+	const json = JSON.stringify(args);
+	return json.length > 100 ? `${json.slice(0, 100)}…` : json;
+};
 /**
 * 多轮 Agent 循环。
 * 工具失败一律转为 ToolResult{ok:false} 回喂 LLM 继续循环；
@@ -1080,6 +1106,10 @@ var AgentLoop = class {
 	#deps;
 	#config;
 	#policy;
+	/** 活跃 run 的 AbortController（cancel(runId) 触发；终态清理） */
+	#controllers = /* @__PURE__ */ new Map();
+	/** 经 cancel() 主动取消的 run（aborted 分支据此区分 cancelled 与 timeout） */
+	#cancelled = /* @__PURE__ */ new Set();
 	constructor(deps, config = {}) {
 		this.#deps = {
 			...deps,
@@ -1090,6 +1120,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
 		};
@@ -1099,6 +1130,18 @@ var AgentLoop = class {
 			interactionTimeoutMs: deps.interaction?.interactionTimeoutMs ?? 3e5
 		};
 	}
+	/**
+	* 取消进行中的 run：触发该 run 的 AbortController（与 totalTimeout 硬期限同一通道），
+	* run 以 cancelled（RUN_CANCELLED）终止；未找到（已终态或不属于本实例）返回 false。
+	* 取消在下一个中断点生效（LLM complete/stream 调用；交互等待不强制中断）。
+	*/
+	cancel(runId) {
+		const controller = this.#controllers.get(runId);
+		if (!controller) return false;
+		this.#cancelled.add(runId);
+		controller.abort();
+		return true;
+	}
 	async run(input) {
 		const now = this.#deps.clock?.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
 		const runId = input.runId ?? `run-${Math.random().toString(36).slice(2, 10)}`;
@@ -1134,6 +1177,7 @@ var AgentLoop = class {
 			totalTimeoutMs: this.#config.totalTimeoutMs,
 			controller: new AbortController()
 		};
+		this.#controllers.set(runId, state.controller);
 		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
 		const route = this.#deps.catalogFilter ? {
 			...input.route,
@@ -1148,7 +1192,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 +1210,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,78 +1240,87 @@ 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) {
+						if (this.#cancelled.has(state.runId)) return finish("cancelled", "user-cancelled", "Run cancelled by user", "RUN_CANCELLED");
+						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；终态即删快照（快照是续命机制，审计归治理） */
 	async #finish(state, status, reason, output, errorCode) {
 		this.#disarmDeadline(state);
+		this.#controllers.delete(state.runId);
+		this.#cancelled.delete(state.runId);
 		const { run, trace } = state;
 		run.status = status;
 		run.terminationReason = reason;
@@ -1292,17 +1345,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 +1382,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 +1394,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,11 +1430,12 @@ 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()
 		};
+		this.#controllers.set(runId, state.controller);
 		if (this.#deps.hooks && !this.#deps.hooks.onWarning) this.#deps.hooks.onWarning = (message) => trace.record("run.warning", { message });
 		trace.record("run.resumed", { data: {
 			snapshotAt: snapshot.snapshotAt,
@@ -1455,14 +1510,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 +1619,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",
@@ -1601,10 +1656,14 @@ var AgentLoop = class {
 		});
 	}
 	async #executeCall(call, state) {
+		const argsSummary = summarizeArgs(call.arguments);
+		const callStartMs = Date.parse(state.now());
 		state.trace.record("tool.started", { data: {
 			name: call.name,
-			callId: call.id
+			callId: call.id,
+			args: argsSummary
 		} });
+		this.#emitTool(state, "started", call);
 		let result;
 		if (call.name === "read_skill_file") result = await this.#handleReadSkillFile(call, state);
 		else if (call.name === "ask_user") result = await this.#handleAskUser(call, state);
@@ -1616,11 +1675,15 @@ var AgentLoop = class {
 				result = source ? await source.call(call.name, call.arguments) : toolError(resolution.code, resolution.message);
 			}
 		}
+		const durationMs = Date.parse(state.now()) - callStartMs;
 		if (result.ok) {
 			state.trace.record("tool.completed", { data: {
 				name: call.name,
-				callId: call.id
+				callId: call.id,
+				args: argsSummary,
+				durationMs
 			} });
+			this.#emitTool(state, "completed", call);
 			for (const item of result.content) {
 				if (item.type !== "json") continue;
 				const chart = extractChartSpec(item.data);
@@ -1629,20 +1692,45 @@ var AgentLoop = class {
 					chart
 				});
 			}
-		} else state.trace.record("tool.failed", {
-			message: result.error?.message,
-			data: {
-				name: call.name,
-				callId: call.id,
-				code: result.error?.code
-			}
-		});
+		} else {
+			state.trace.record("tool.failed", {
+				message: result.error?.message,
+				data: {
+					name: call.name,
+					callId: call.id,
+					code: result.error?.code,
+					args: argsSummary,
+					durationMs
+				}
+			});
+			this.#emitTool(state, "failed", call);
+		}
 		for (const artifact of result.artifacts ?? []) state.trace.record("artifact.created", { data: {
 			artifactId: artifact.id,
 			path: artifact.path
 		} });
 		return result;
 	}
+	/**
+	* 逐工具实时事件（execute 相位，data.type='tool'）：chatbot ToolCallCard 等的 live 状态源；
+	* 与既有 execute 相位事件（{turn}）并存，监听方按 data.type 区分。
+	* data.args 为参数摘要（JSON 截断 100 字符，卡片展开详情用）。
+	*/
+	#emitTool(state, status, call) {
+		this.#deps.eventBus?.emit({
+			phase: "execute",
+			runId: state.runId,
+			sessionId: state.run.sessionId,
+			ts: state.now(),
+			data: {
+				type: "tool",
+				status,
+				name: call.name,
+				callId: call.id,
+				args: summarizeArgs(call.arguments)
+			}
+		});
+	}
 	async #handleAskUser(call, state) {
 		const question = call.arguments["question"];
 		if (typeof question !== "string" || question === "") return toolError("TOOL_EXECUTION_FAILED", "ask_user requires a non-empty \"question\" string argument");
@@ -1684,7 +1772,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 +1812,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 +1834,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 +1872,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 +1893,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 +1919,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 +1929,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 +1990,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 +2029,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 +2042,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 +2077,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 +2086,7 @@ var AgentLoop = class {
 				type: request.type,
 				value
 			});
-			return history;
+			return history.slice(-limit);
 		});
 	}
 };
@@ -2084,6 +2173,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
 */
@@ -2094,6 +2201,8 @@ var WebSkillRuntime = class {
 	#session;
 	#events;
 	#catalogCache;
+	/** 活跃 run 的 loop 实例（cancel(runId) 路由；终态清理） */
+	#loops = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.#deps = {
 			...deps,
@@ -2128,20 +2237,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;
 			}
 		};
@@ -2170,7 +2287,7 @@ var WebSkillRuntime = class {
 		const catalog = providerEntries.length > 0 ? { entries: mergeCatalogEntries(cache.catalog.entries, providerEntries) } : cache.catalog;
 		const filteredCatalog = this.#deps.catalogFilter ? { entries: await this.#deps.catalogFilter(catalog.entries) } : catalog;
 		const route = await this.#router.route(filteredCatalog);
-		const result = await new AgentLoop({
+		const loop = new AgentLoop({
 			llm: this.#deps.llm,
 			executor: this.#deps.executor,
 			schemaInferer: this.#deps.schemaInferer,
@@ -2189,12 +2306,21 @@ var WebSkillRuntime = class {
 			catalogFilter: this.#deps.catalogFilter,
 			snapshotStore: this.#deps.snapshotStore,
 			skillStateGuard: this.#deps.skillStateGuard
-		}, this.#deps.config).run({
-			sessionId: options.sessionId ?? this.#session.id,
-			userPrompt,
-			route,
-			...options.history ? { history: options.history } : {}
-		});
+		}, this.#deps.config);
+		const runId = `run-${Math.random().toString(36).slice(2, 10)}`;
+		this.#loops.set(runId, loop);
+		let result;
+		try {
+			result = await loop.run({
+				sessionId: options.sessionId ?? this.#session.id,
+				userPrompt,
+				route,
+				runId,
+				...options.history ? { history: options.history } : {}
+			});
+		} finally {
+			this.#loops.delete(runId);
+		}
 		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,
@@ -2269,7 +2395,7 @@ var WebSkillRuntime = class {
 		if (!this.#catalogCache) await this.discover();
 		const cache = this.#catalogCache;
 		if (!cache) throw new WebSkillError("RUN_FAILED", "discover() did not populate the catalog cache");
-		return new AgentLoop({
+		const loop = new AgentLoop({
 			llm: this.#deps.llm,
 			executor: this.#deps.executor,
 			schemaInferer: this.#deps.schemaInferer,
@@ -2288,7 +2414,21 @@ var WebSkillRuntime = class {
 			catalogFilter: this.#deps.catalogFilter,
 			snapshotStore: store,
 			skillStateGuard: this.#deps.skillStateGuard
-		}, this.#deps.config).resume(snapshot);
+		}, this.#deps.config);
+		this.#loops.set(runId, loop);
+		try {
+			return await loop.resume(snapshot);
+		} finally {
+			this.#loops.delete(runId);
+		}
+	}
+	/**
+	* 取消进行中的 run（chatbot Stop 按钮等）：触发该 run 的 AbortController，
+	* run 以 cancelled（RUN_CANCELLED）终止；未找到活跃 run 返回 false。
+	* 取消在下一个中断点生效（LLM complete/stream；交互等待不强制中断）。
+	*/
+	cancel(runId) {
+		return this.#loops.get(runId)?.cancel(runId) ?? false;
 	}
 };
 /**
@@ -2389,7 +2529,6 @@ function sourceFromUrl(url) {
 		path: url
 	};
 }
-const messageOf = (e) => e instanceof Error ? e.message : String(e);
 /** 受控钩子执行器：逐个执行，超时/异常默认降级为 warning，可切严格模式 */
 var HookRunner = class {
 	#hooks = /* @__PURE__ */ new Map();