@webskill/sdk 0.2.3 → 0.2.5

package/dist/{dist-D0saNPi_.js → dist-BQzncxXg.js}

@@ -16,6 +16,10 @@ var WebSkillError = class extends Error {
 		this.details = details;
 	}
 };
+/** unknown 异常取消息文本（全仓单一来源，勿再本地重复定义） */
+function messageOf(e) {
+	return e instanceof Error ? e.message : String(e);
+}
 /** 技能目录内的安装清单文件名（不参与 files 列表与 digest） */
 const SKILL_MANIFEST_FILE = "webskill.skill-manifest.json";
 /** managed root 下的锁定文件名（不参与 files 列表与 digest） */
@@ -111,6 +115,18 @@ var MemoryFS = class {
 	async writeText(path, content) {
 		await this.writeBinary(path, new TextEncoder().encode(content));
 	}
+	async appendText(path, content) {
+		const key = this.#normalize(path);
+		const existing = this.#entries.get(key);
+		if (existing && existing.type !== "file") throw new WebSkillError("FS_PERMISSION_DENIED", `Cannot append to a directory: ${key}`);
+		const prior = existing ? new TextDecoder().decode(existing.content) : "";
+		this.#ensureParents(key);
+		this.#entries.set(key, {
+			type: "file",
+			content: new TextEncoder().encode(prior + content),
+			mtimeMs: Date.now()
+		});
+	}
 	async readBinary(path) {
 		return this.#getFile(this.#normalize(path)).content;
 	}
@@ -188,7 +204,12 @@ var MemoryFS = class {
 		this.#entries.delete(src);
 	}
 };
-/** 原子写文本：先写临时文件再 rename（进程崩溃不留下半写文件；lockfile 等账本场景） */
+/**
+* 原子写文本：先写临时文件再 rename（进程崩溃不留下半写文件；lockfile 等账本场景）。
+* 原子性强弱取决于 provider 的 rename 实现：NodeFS/MemoryFS 为真 rename；
+* OPFS 无原生 move，rename 是 copy+delete（非原子，崩溃可能残留双份），
+* 对崩溃一致性要求极高的场景在浏览器侧需知悉此前提。
+*/
 async function atomicWriteText(fs, path, content) {
 	const tmp = `${path}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
 	await fs.writeText(tmp, content);
@@ -203,7 +224,9 @@ function normalizePath(path) {
 * 拒绝空串、`.`、`..`、含 `/` 或 `\`、含 `:`（Windows 盘符/ADS）。
 * 违规抛 FS_PATH_OUTSIDE_ROOT（kind 用于错误消息定位，如 "runId"）。
 */
+const CONTROL_CHARS_RE = /[\x00-\x1f\x7f]/;
 function assertSafePathSegment(segment, kind) {
+	if (CONTROL_CHARS_RE.test(segment)) throw new WebSkillError("FS_PATH_OUTSIDE_ROOT", `Invalid ${kind} (control characters including NUL are not allowed): ${JSON.stringify(segment)}`);
 	if (segment === "" || segment === "." || segment === ".." || segment.includes("/") || segment.includes("\\") || segment.includes(":")) throw new WebSkillError("FS_PATH_OUTSIDE_ROOT", `Invalid ${kind} (must be a single safe path segment): ${JSON.stringify(segment)}`);
 }
 /**
@@ -221,6 +244,7 @@ function resolveInsideRoot(root, relativePath) {
 	if (relativePath.trim() === "") fail("empty path");
 	if (relativePath.startsWith("/") || relativePath.startsWith("\\") || /^[a-zA-Z]:[\\/]/.test(relativePath)) fail("absolute paths not allowed");
 	const segments = relativePath.replace(/\\/g, "/").split("/");
+	if (CONTROL_CHARS_RE.test(relativePath)) fail("control characters including NUL are not allowed");
 	if (segments.some((s) => s === "..")) fail("`..` segments not allowed");
 	const clean = segments.filter((s) => s !== "" && s !== ".");
 	if (clean.length === 0) fail("path resolves to empty");
@@ -228,6 +252,65 @@ function resolveInsideRoot(root, relativePath) {
 	const joined = normalizedRoot === "" ? clean.join("/") : `${normalizedRoot}/${clean.join("/")}`;
 	return root.startsWith("/") || root.startsWith("\\") ? `/${joined}` : joined;
 }
+const LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "localhost."]);
+function ipv4Octets(host) {
+	const parts = host.split(".");
+	if (parts.length !== 4) return void 0;
+	const octets = parts.map((p) => /^\d{1,3}$/.test(p) ? Number(p) : NaN);
+	return octets.every((n) => n >= 0 && n <= 255) ? octets : void 0;
+}
+function isPrivateIpv4(octets) {
+	const [a, b] = octets;
+	return a === 0 || a === 10 || a === 127 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254;
+}
+function isPrivateIpv6(host) {
+	const h = host.toLowerCase();
+	if (h === "::1" || h === "::") return true;
+	const mapped = h.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+	if (mapped) {
+		const octets = ipv4Octets(mapped[1]);
+		return octets !== void 0 && isPrivateIpv4(octets);
+	}
+	const mappedHex = h.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+	if (mappedHex) {
+		const hi = parseInt(mappedHex[1], 16);
+		const lo = parseInt(mappedHex[2], 16);
+		return isPrivateIpv4([
+			hi >> 8,
+			hi & 255,
+			lo >> 8,
+			lo & 255
+		]);
+	}
+	const first = h.split(":")[0];
+	if (/^[0-9a-f]{1,4}$/.test(first)) {
+		const n = parseInt(first, 16);
+		if ((n & 65472) === 65152) return true;
+		if ((n & 65024) === 64512) return true;
+	}
+	return false;
+}
+function isPrivateHost(hostname) {
+	const host = hostname.toLowerCase();
+	if (LOOPBACK_HOSTNAMES.has(host) || host.endsWith(".localhost")) return true;
+	const v4 = ipv4Octets(host);
+	if (v4) return isPrivateIpv4(v4);
+	if (host.startsWith("[") && host.endsWith("]")) return isPrivateIpv6(host.slice(1, -1));
+	if (host.includes(":")) return isPrivateIpv6(host);
+	return false;
+}
+/**
+* 校验远程 URL 是否允许连接；违规抛 NETWORK_BLOCKED。
+* rawUrl 非合法 URL 时抛 TypeError（由调用方按自身错误码包装）。
+*/
+function assertRemoteUrlAllowed(rawUrl, policy = {}) {
+	const url = new URL(rawUrl);
+	if (url.protocol === "http:") {
+		if (!policy.allowHttp) throw new WebSkillError("NETWORK_BLOCKED", `Insecure URL scheme "http:" is not allowed (opt in via allowHttp): ${url.href}`);
+	} else if (url.protocol !== "https:") throw new WebSkillError("NETWORK_BLOCKED", `URL scheme "${url.protocol}" is not allowed (https only): ${url.href}`);
+	if (!policy.allowPrivateHosts && isPrivateHost(url.hostname)) throw new WebSkillError("NETWORK_BLOCKED", `Refusing to connect to a private/loopback/link-local address: ${url.hostname}`);
+	return url;
+}
 const FRONTMATTER_RE = /^---[^\S\r\n]*\r?\n([\s\S]*?)\r?\n---[^\S\r\n]*(?:\r?\n|$)([\s\S]*)$/;
 const invalid = (message, details) => {
 	throw new WebSkillError("SKILL_INVALID_METADATA", message, details);
@@ -368,7 +451,6 @@ function checkDependencyCycles(adjacency) {
 */
 /** 包级清单文件名（位于 zip 根，不参与各技能 digest） */
 const SKILL_PACK_FILE = "webskill.skill-pack.json";
-const messageOf = (e) => e instanceof Error ? e.message : String(e);
 const baseName$1 = (p) => p.split("/").pop() ?? p;
 async function listFilesRecursive(fs, root, prefix = "") {
 	const out = [];
@@ -392,6 +474,7 @@ async function exportSkills(fs, input) {
 		for (const root of input.roots) {
 			const base = root.replace(/\/+$/, "");
 			const manifest = await input.manifestBuilder(base);
+			if (!isValidSkillName(manifest.name)) throw new WebSkillError("EXPORT_FAILED", `Skill "${manifest.name}" has an invalid name and cannot be exported to a skill pack`);
 			skills.push({
 				name: manifest.name,
 				digest: manifest.integrity.digest
@@ -427,7 +510,7 @@ function parseSkillPackManifest(text) {
 	for (const entry of record["skills"]) {
 		if (typeof entry !== "object" || entry === null) invalid("skill entry is not an object");
 		const { name, digest } = entry;
-		if (typeof name !== "string" || name === "") invalid("skill entry missing a valid \"name\"");
+		if (typeof name !== "string" || name === "" || !isValidSkillName(name)) invalid(`skill entry has an invalid name: ${JSON.stringify(name)}`);
 		if (typeof digest !== "string" || digest === "") invalid(`skill "${name}" missing a valid "digest"`);
 	}
 	return raw;
@@ -468,6 +551,14 @@ async function unzipWithLimits(data, limits) {
 	const unzip = new Unzip();
 	unzip.register(UnzipInflate);
 	unzip.onfile = (file) => {
+		if (file.name.startsWith("/") || file.name.startsWith("\\") || /^[a-zA-Z]:[\\/]/.test(file.name)) {
+			failure = new WebSkillError("INSTALL_FAILED", `Archive entry escapes the destination root: ${file.name}`);
+			return;
+		}
+		if (file.name.replace(/\\/g, "/").split("/").some((s) => s === "..") || /[\x00-\x1f\x7f]/.test(file.name)) {
+			failure = new WebSkillError("INSTALL_FAILED", `Archive entry escapes the destination root: ${file.name}`);
+			return;
+		}
 		if (file.name.endsWith("/")) {
 			entries.push([file.name, /* @__PURE__ */ new Uint8Array(0)]);
 			return;
@@ -579,7 +670,7 @@ var SkillDiscovery = class {
 		const candidates = [];
 		const knownSkillNames = /* @__PURE__ */ new Set();
 		const adjacency = /* @__PURE__ */ new Map();
-		for (const root of this.#roots) {
+		for (const [rootIndex, root] of this.#roots.entries()) {
 			if (!await this.#fs.exists(root)) {
 				issues.push({
 					code: "FS_NOT_FOUND",
@@ -604,6 +695,7 @@ var SkillDiscovery = class {
 				candidates.push({
 					dirName,
 					skillRoot,
+					rootIndex,
 					hasSkillMd,
 					metadata,
 					parseError,
@@ -616,6 +708,7 @@ var SkillDiscovery = class {
 				}
 			}));
 		}
+		candidates.sort((a, b) => a.rootIndex - b.rootIndex || a.dirName.localeCompare(b.dirName));
 		const cycles = checkDependencyCycles(adjacency);
 		const claimedNames = /* @__PURE__ */ new Set();
 		for (const candidate of candidates) {
@@ -743,4 +836,4 @@ const xmlRenderer = {
 };
 
 //#endregion
-export { unzipWithLimits as A, parseSkillMarkdown as C, renderCatalogJson as D, renderAvailableSkillsXml as E, verifyManifest as M, xmlRenderer as N, resolveArchiveLimits as O, normalizePath as S, readResponseWithLimit as T, computeDigest as _, SKILL_NAME_MAX_LENGTH as a, isValidSkillName as b, SkillDiscovery as c, assertSafePathSegment as d, atomicWriteText as f, checkSkillRules as g, checkDependencyCycles as h, SKILL_MANIFEST_FILE as i, validateSkills as j, resolveInsideRoot as k, SkillReader as l, buildManifest as m, MemoryFS as n, SKILL_NAME_PATTERN as o, buildCatalog as p, SKILLS_LOCKFILE as r, SKILL_PACK_FILE as s, DEFAULT_ARCHIVE_LIMITS as t, WebSkillError as u, escapeXml as v, parseSkillPackManifest as w, jsonRenderer as x, exportSkills as y };
+export { resolveArchiveLimits as A, messageOf as C, readResponseWithLimit as D, parseSkillPackManifest as E, xmlRenderer as F, unzipWithLimits as M, validateSkills as N, renderAvailableSkillsXml as O, verifyManifest as P, jsonRenderer as S, parseSkillMarkdown as T, checkSkillRules as _, SKILL_NAME_MAX_LENGTH as a, exportSkills as b, SkillDiscovery as c, assertRemoteUrlAllowed as d, assertSafePathSegment as f, checkDependencyCycles as g, buildManifest as h, SKILL_MANIFEST_FILE as i, resolveInsideRoot as j, renderCatalogJson as k, SkillReader as l, buildCatalog as m, MemoryFS as n, SKILL_NAME_PATTERN as o, atomicWriteText as p, SKILLS_LOCKFILE as r, SKILL_PACK_FILE as s, DEFAULT_ARCHIVE_LIMITS as t, WebSkillError as u, computeDigest as v, normalizePath as w, isValidSkillName as x, escapeXml as y };

package/dist/{dist-CvIMVwr3.js → dist-Chk8iB-E.js}

@@ -1,5 +1,5 @@
-import { A as unzipWithLimits, C as parseSkillMarkdown, M as verifyManifest, O as resolveArchiveLimits, T as readResponseWithLimit, b as isValidSkillName, f as atomicWriteText, i as SKILL_MANIFEST_FILE, j as validateSkills, k as resolveInsideRoot, m as buildManifest, r as SKILLS_LOCKFILE, s as SKILL_PACK_FILE, u as WebSkillError, w as parseSkillPackManifest, y as exportSkills } from "./dist-D0saNPi_.js";
-import { A as isNetworkAllowed, C as bridgeError, M as networkUrlHost, N as normalizeToolContent, P as parseBridgeRequest, c as FsArtifactStore, l as FsMemoryStore, o as CapabilityApproval } from "./dist-NM4Mylx4.js";
+import { A as resolveArchiveLimits, C as messageOf, D as readResponseWithLimit, E as parseSkillPackManifest, M as unzipWithLimits, N as validateSkills, P as verifyManifest, T as parseSkillMarkdown, b as exportSkills, d as assertRemoteUrlAllowed, h as buildManifest, i as SKILL_MANIFEST_FILE, j as resolveInsideRoot, 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, F as normalizeToolError, I as parseBridgeRequest, M as networkUrlHost, P as normalizeToolContent, c as FsArtifactStore, l as FsMemoryStore, o as CapabilityApproval } from "./dist-B77plHjw.js";
 import { createRequire } from "node:module";
 import { unzipSync, zipSync } from "fflate";
 import { existsSync, promises, realpathSync } from "node:fs";
@@ -37,13 +37,16 @@ async function realpathNearest(platformPath) {
 * 可选 root 模式：构造传入 root 后，read/write 操作先做 realpath 包含校验
 * （root 与目标都 realpath 后前缀比对），经符号链接逃逸 root → FS_PATH_OUTSIDE_ROOT。
 */
-var NodeFS = class {
+var NodeFS = class NodeFS {
 	kind = "node";
 	#root;
 	constructor(deps = {}) {
 		this.#root = deps.root;
 	}
-	/** root 模式：目标 realpath 必须落在 root realpath 前缀内（符号链接逃逸防护） */
+	/** root 模式：全部方法（read/write/exists/stat/list/mkdir/remove/rename）目标 realpath 必须落在 root realpath 前缀内 */
+	withRoot(root) {
+		return new NodeFS({ root });
+	}
 	async #assertContained(p) {
 		if (!this.#root) return;
 		const rootReal = await promises.realpath(toPlatform$4(this.#root));
@@ -64,6 +67,12 @@ var NodeFS = class {
 		await promises.mkdir(path.dirname(target), { recursive: true });
 		await promises.writeFile(target, content, "utf8");
 	}
+	async appendText(p, content) {
+		await this.#assertContained(p);
+		const target = toPlatform$4(p);
+		await promises.mkdir(path.dirname(target), { recursive: true });
+		await promises.appendFile(target, content, "utf8");
+	}
 	async readBinary(p) {
 		await this.#assertContained(p);
 		try {
@@ -79,6 +88,7 @@ var NodeFS = class {
 		await promises.writeFile(target, content);
 	}
 	async exists(p) {
+		await this.#assertContained(p);
 		try {
 			await promises.access(toPlatform$4(p));
 			return true;
@@ -87,6 +97,7 @@ var NodeFS = class {
 		}
 	}
 	async stat(p) {
+		await this.#assertContained(p);
 		try {
 			const s = await promises.stat(toPlatform$4(p));
 			return {
@@ -100,6 +111,7 @@ var NodeFS = class {
 		}
 	}
 	async list(p) {
+		await this.#assertContained(p);
 		let dirents;
 		try {
 			dirents = await promises.readdir(toPlatform$4(p), { withFileTypes: true });
@@ -112,9 +124,11 @@ var NodeFS = class {
 		}));
 	}
 	async mkdir(p) {
+		await this.#assertContained(p);
 		await promises.mkdir(toPlatform$4(p), { recursive: true });
 	}
 	async remove(p, options) {
+		await this.#assertContained(p);
 		try {
 			await promises.rm(toPlatform$4(p), { recursive: options?.recursive ?? false });
 		} catch (e) {
@@ -122,6 +136,8 @@ var NodeFS = class {
 		}
 	}
 	async rename(from, to) {
+		await this.#assertContained(from);
+		await this.#assertContained(to);
 		await promises.mkdir(path.dirname(toPlatform$4(to)), { recursive: true });
 		try {
 			await promises.rename(toPlatform$4(from), toPlatform$4(to));
@@ -279,7 +295,6 @@ var NodeScriptExecutor = class {
 };
 const baseName$1 = (p) => p.split("/").pop() ?? p;
 const toPlatform$3 = (p) => p.split("/").join(path.sep);
-const messageOf$6 = (e) => e instanceof Error ? e.message : String(e);
 /**
 * 网络策略判定函数源码（注入 Worker；匹配逻辑单一来源在
 * runtime/sandbox/networkPolicy.ts，Worker 线程不走 vitest 别名故注入而非 import）
@@ -365,7 +380,7 @@ var SandboxedScriptExecutor = class {
 				content: [],
 				error: {
 					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-					message: messageOf$6(e)
+					message: messageOf(e)
 				}
 			};
 		}
@@ -381,12 +396,13 @@ var SandboxedScriptExecutor = class {
 			}, timeoutMs, (request) => this.#handleBridge(request, context), (host) => context.onWarning?.(`Network request blocked by sandbox network policy: ${host}`));
 			if (!result.ok) {
 				const stderrSummary = result.stderr?.length ? ` | stderr: ${result.stderr.join(" | ").slice(0, 500)}` : "";
+				const normalized = normalizeToolError(result.error?.code, result.error?.message ?? "script execution failed");
 				return {
 					ok: false,
 					content: [],
 					error: {
-						code: result.error?.code ?? "TOOL_EXECUTION_FAILED",
-						message: `${result.error?.message ?? "script execution failed"}${stderrSummary}`
+						code: normalized.code,
+						message: `${normalized.message}${stderrSummary}`
 					}
 				};
 			}
@@ -405,7 +421,7 @@ var SandboxedScriptExecutor = class {
 				content: [],
 				error: {
 					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-					message: messageOf$6(e)
+					message: messageOf(e)
 				}
 			};
 		}
@@ -456,14 +472,14 @@ var SandboxedScriptExecutor = class {
 						respond(bridgeError("unknown", "TOOL_EXECUTION_FAILED", "invalid bridge request"));
 						return;
 					}
-					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf$6(e))));
+					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf(e))));
 					return;
 				}
 				if (msg?.type === "load-result" || msg?.type === "execute-result") done(() => resolve(msg));
 			});
 			worker.on("error", (e) => done(() => reject(e)));
 			worker.on("exit", (code) => {
-				if (code !== 0) done(() => reject(new WebSkillError("TOOL_EXECUTION_FAILED", `Sandbox worker exited with code ${code}`)));
+				if (!settled) done(() => reject(new WebSkillError("TOOL_EXECUTION_FAILED", `Sandbox worker exited ${code === null ? "by signal" : `with code ${code}`} without producing a result`)));
 			});
 		});
 	}
@@ -517,13 +533,12 @@ var SandboxedScriptExecutor = class {
 				}
 			}
 		} catch (e) {
-			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf$6(e));
+			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf(e));
 		}
 	}
 };
 const baseName = (p) => p.split("/").pop() ?? p;
 const toPlatform$2 = (p) => p.split("/").join(path.sep);
-const messageOf$5 = (e) => e instanceof Error ? e.message : String(e);
 const NETWORK_POLICY_LIB = `${isNetworkAllowed.toString()}\n${networkUrlHost.toString()}`;
 const readAllow = (p) => [`--allow-fs-read=${p}`, `--allow-fs-read=${realpathSync(p)}`];
 const writeAllow = (p) => [`--allow-fs-write=${p}`, `--allow-fs-write=${realpathSync(p)}`];
@@ -555,6 +570,7 @@ var ProcessSandboxExecutor = class {
 	#approval;
 	#slots = [];
 	#waiters = [];
+	#disposed = false;
 	constructor(fs, options = {}) {
 		this.#fs = fs;
 		this.#options = options;
@@ -572,8 +588,9 @@ var ProcessSandboxExecutor = class {
 	get poolSize() {
 		return this.#options.poolSize ?? 2;
 	}
-	/** 池全部子进程销毁（测试收尾/进程退出前调用） */
+	/** 池全部子进程销毁（测试收尾/进程退出前调用）；排队中的 acquire 一律 reject（不悬挂） */
 	async dispose() {
+		this.#disposed = true;
 		for (const slot of this.#slots) {
 			slot.child.kill();
 			await rm(slot.artifactDir, {
@@ -582,7 +599,8 @@ var ProcessSandboxExecutor = class {
 			}).catch(() => void 0);
 		}
 		this.#slots = [];
-		this.#waiters = [];
+		const waiters = this.#waiters.splice(0);
+		for (const waiter of waiters) waiter.reject(new WebSkillError("TOOL_EXECUTION_FAILED", "Process sandbox executor disposed while a caller was waiting for a pool slot"));
 	}
 	async #locateScript(skillRoot, scriptName) {
 		const tsPath = `${skillRoot}/scripts/${scriptName}.ts`;
@@ -595,6 +613,7 @@ var ProcessSandboxExecutor = class {
 	/** 取一个可用子进程（同 key 复用 / 淘汰 idle 重生 / 扩容 / 排队） */
 	async #acquire(key) {
 		for (;;) {
+			if (this.#disposed) throw new WebSkillError("TOOL_EXECUTION_FAILED", "Process sandbox executor is disposed");
 			const idle = this.#slots.filter((s) => !s.busy);
 			const match = idle.find((s) => s.key === key);
 			if (match) {
@@ -616,7 +635,10 @@ var ProcessSandboxExecutor = class {
 				this.#slots.push(slot);
 				return slot;
 			}
-			await new Promise((resolve) => this.#waiters.push(resolve));
+			await new Promise((resolve, reject) => this.#waiters.push({
+				resolve,
+				reject
+			}));
 		}
 	}
 	/** 执行后回收：kill 旧子进程，补位重生同 key 新子进程（温池保持），唤醒排队 */
@@ -628,13 +650,27 @@ var ProcessSandboxExecutor = class {
 			recursive: true,
 			force: true
 		}).catch(() => void 0);
-		this.#spawnSlot(slot.key).then((fresh) => {
+		this.#spawnSlot(slot.key).then(async (fresh) => {
+			if (this.#disposed) {
+				fresh.child.kill();
+				await rm(fresh.artifactDir, {
+					recursive: true,
+					force: true
+				}).catch(() => void 0);
+				return;
+			}
 			this.#slots.push(fresh);
-		}).catch(() => void 0).finally(() => {
+		}).catch((e) => {
+			this.#warn(`Failed to respawn sandbox child for pool maintenance: ${messageOf(e)}`);
+		}).finally(() => {
 			const waiter = this.#waiters.shift();
-			if (waiter) waiter();
+			if (waiter) waiter.resolve();
 		});
 	}
+	#warn(message) {
+		if (this.#options.onWarning) this.#options.onWarning(message);
+		else console.warn(message);
+	}
 	async #spawnSlot(key) {
 		const artifactDir = await mkdtemp(path.join(tmpdir(), "webskill-psbx-out-")).then((d) => d.split(path.sep).join("/"));
 		const entry = processEntryPath();
@@ -695,7 +731,7 @@ var ProcessSandboxExecutor = class {
 				content: [],
 				error: {
 					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-					message: messageOf$5(e)
+					message: messageOf(e)
 				}
 			};
 		}
@@ -713,12 +749,13 @@ var ProcessSandboxExecutor = class {
 			}, timeoutMs, (request) => this.#handleBridge(request, context), (host) => context.onWarning?.(`Network request blocked by sandbox network policy: ${host}`));
 			if (!result.ok) {
 				const stderrSummary = result.stderr?.length ? ` | stderr: ${result.stderr.join(" | ").slice(0, 500)}` : "";
+				const normalized = normalizeToolError(result.error?.code, result.error?.message ?? "script execution failed");
 				return {
 					ok: false,
 					content: [],
 					error: {
-						code: result.error?.code ?? "TOOL_EXECUTION_FAILED",
-						message: `${result.error?.message ?? "script execution failed"}${stderrSummary}`
+						code: normalized.code,
+						message: `${normalized.message}${stderrSummary}`
 					}
 				};
 			}
@@ -737,7 +774,7 @@ var ProcessSandboxExecutor = class {
 				content: [],
 				error: {
 					code: e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED",
-					message: messageOf$5(e)
+					message: messageOf(e)
 				}
 			};
 		} finally {
@@ -776,7 +813,7 @@ var ProcessSandboxExecutor = class {
 						respond(bridgeError("unknown", "TOOL_EXECUTION_FAILED", "invalid bridge request"));
 						return;
 					}
-					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf$5(e))));
+					onBridge(request).then(respond, (e) => respond(bridgeError(request.id, "TOOL_EXECUTION_FAILED", messageOf(e))));
 					return;
 				}
 				if (msg?.type === "load-result" || msg?.type === "execute-result") done(() => resolve(msg));
@@ -845,7 +882,7 @@ var ProcessSandboxExecutor = class {
 				}
 			}
 		} catch (e) {
-			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf$5(e));
+			return bridgeError(request.id, e instanceof WebSkillError ? e.code : "TOOL_EXECUTION_FAILED", messageOf(e));
 		}
 	}
 };
@@ -1177,7 +1214,6 @@ var CliUiBridge = class {
 		return new Promise((resolve) => this.#waiters.push(resolve));
 	}
 };
-const messageOf$4 = (e) => e instanceof Error ? e.message : String(e);
 const toPlatform$1 = (p) => p.split("/").join(path.sep);
 const isZipArchive = (data) => data.length > 1 && data[0] === 80 && data[1] === 75;
 let tarModule$1;
@@ -1226,7 +1262,7 @@ async function extractTarFile(archivePath, destRoot, limits) {
 		});
 	} catch (e) {
 		if (e instanceof WebSkillError) throw e;
-		throw new WebSkillError("INSTALL_FAILED", `Failed to extract tar archive: ${messageOf$4(e)}`, e);
+		throw new WebSkillError("INSTALL_FAILED", `Failed to extract tar archive: ${messageOf(e)}`, e);
 	}
 }
 /** 递归列出目录内全部文件（相对路径，posix 分隔，不含目录条目） */
@@ -1270,7 +1306,6 @@ async function removeDirQuiet(fs, dir) {
 		if (await fs.exists(dir)) await fs.remove(dir, { recursive: true });
 	} catch {}
 }
-const messageOf$3 = (e) => e instanceof Error ? e.message : String(e);
 let tarModule;
 async function loadTar() {
 	tarModule ??= await import("tar").catch((e) => {
@@ -1292,7 +1327,7 @@ async function exportArchive(fs, skillRoot, options) {
 		return options.outPath;
 	} catch (e) {
 		if (e instanceof WebSkillError) throw e;
-		throw new WebSkillError("EXPORT_FAILED", `Failed to export ${options.format} archive: ${messageOf$3(e)}`, e);
+		throw new WebSkillError("EXPORT_FAILED", `Failed to export ${options.format} archive: ${messageOf(e)}`, e);
 	}
 }
 /** 只解出归档中的 webskill.skill-manifest.json 条目（安装前预览） */
@@ -1320,13 +1355,12 @@ async function readArchiveManifest(fs, archivePath) {
 			}
 		});
 	} catch (e) {
-		throw new WebSkillError("EXPORT_FAILED", `Failed to read tar archive: ${messageOf$3(e)}`, e);
+		throw new WebSkillError("EXPORT_FAILED", `Failed to read tar archive: ${messageOf(e)}`, e);
 	}
 	if (manifestText === void 0) throw notFound();
 	return JSON.parse(manifestText);
 }
 const _execFileP = promisify(execFile);
-const messageOf$2 = (e) => e instanceof Error ? e.message : String(e);
 /**
 * 跨平台执行命令：Windows 下对 npm 等 cmd 包装的命令通过 cmd.exe 代理执行，
 * git 等原生 exe 不受影响。默认 120s 超时（防挂死安装管线）。
@@ -1342,7 +1376,7 @@ async function execFileP(command, args, options = {}) {
 }
 /** 命令缺失/失败 → INSTALL_FAILED 结构化诊断 */
 function commandFailed(command, e) {
-	return new WebSkillError("INSTALL_FAILED", `Failed to run ${command}: ${e?.code === "ENOENT" ? `command "${command}" not found on this system` : messageOf$2(e)}`, e);
+	return new WebSkillError("INSTALL_FAILED", `Failed to run ${command}: ${e?.code === "ENOENT" ? `command "${command}" not found on this system` : messageOf(e)}`, e);
 }
 /** git url 协议白名单：https:// 与 git@ SCP 形式；无 scheme 的本地路径放行（dev 工作流）；
 * 其余显式协议（ext::/file:// 等）一律拒绝 */
@@ -1391,15 +1425,38 @@ async function stageGit(source, ctx) {
 function sha256Hex(data) {
 	return createHash("sha256").update(data).digest("hex");
 }
-const messageOf$1 = (e) => e instanceof Error ? e.message : String(e);
-/** http 源：下载归档（Content-Length + 流式累计上限；可选 expectedSha256 校验包体）→ 解包 → 定位技能根/包集 */
+/** 重定向跳数上限（SSRF 防护：逐跳重新校验目标 URL） */
+const MAX_REDIRECT_HOPS = 3;
+/**
+* 带 SSRF 防护的下载：手动跟随重定向（默认 ≤3 跳），初始 URL 与每一跳目标
+* 都过 assertRemoteUrlAllowed（https 默认；私有/环回/链路本地默认拒绝）。
+*/
+async function fetchWithSsrfGuard(source, fetchImpl) {
+	const policy = {
+		allowHttp: source.allowHttp ?? false,
+		allowPrivateHosts: source.allowPrivateHosts ?? false
+	};
+	let url = assertRemoteUrlAllowed(source.url, policy);
+	for (let hop = 0;; hop++) {
+		const res = await fetchImpl(url.href, { redirect: "manual" });
+		const location = res.headers.get("location");
+		if (res.status >= 300 && res.status < 400 && location) {
+			if (hop >= MAX_REDIRECT_HOPS) throw new WebSkillError("INSTALL_FAILED", `Download exceeded the redirect limit of ${MAX_REDIRECT_HOPS} hops`);
+			url = assertRemoteUrlAllowed(new URL(location, url).href, policy);
+			continue;
+		}
+		return res;
+	}
+}
+/** http 源：下载归档（SSRF 防护 + Content-Length/流式上限；可选 expectedSha256 校验包体）→ 解包 → 定位技能根/包集 */
 async function stageHttp(source, ctx, expectedSha256) {
 	const fetchImpl = ctx.fetchImpl ?? fetch;
 	let res;
 	try {
-		res = await fetchImpl(source.url);
+		res = await fetchWithSsrfGuard(source, fetchImpl);
 	} 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}`);
 	const data = await readResponseWithLimit(res, ctx.archiveLimits);
@@ -1448,13 +1505,19 @@ async function stageLocal(source, ctx) {
 /** npm 包名（@scope/name 或 name，小写字母数字 . _ - /）与版本（semver 或 dist-tag）正则 */
 const PACKAGE_NAME_RE = /^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/;
 const VERSION_RE = /^[a-z0-9._~^>=<x*+-]+$/i;
+/**
+* 本地路径字符白名单（Windows 下 npm 经 cmd /c 代理二次解析，
+* `& | < > ^ " ' % ! ;` 与空格一律拒绝；允许 Windows 盘符 `C:\` 与正/反斜杠）
+*/
+const LOCAL_PATH_RE = /^[A-Za-z0-9._~+@/\\:-]+$/;
 function assertNpmSpecSafe(source) {
 	const name = source.packageName;
 	const isLocalPath = name.startsWith("/") || name.startsWith("./") || name.startsWith("../");
 	if (name.startsWith("--") || !PACKAGE_NAME_RE.test(name) && !isLocalPath) throw new WebSkillError("INSTALL_FAILED", `Invalid npm package name: ${JSON.stringify(name)}`);
+	if (isLocalPath && !LOCAL_PATH_RE.test(name)) throw new WebSkillError("INSTALL_FAILED", `Local npm path contains characters outside the safe whitelist: ${JSON.stringify(name)}`);
 	if (source.version !== void 0 && (!VERSION_RE.test(source.version) || source.version.startsWith("--"))) throw new WebSkillError("INSTALL_FAILED", `Invalid npm package version: ${JSON.stringify(source.version)}`);
 }
-/** npm 源：npm pack → 解 tar.gz；技能根取包的 skill/ 子目录（存在时）否则包根；spec 前插 `--` 防选项注入 */
+/** npm 源：npm pack --ignore-scripts → 解 tar.gz；技能根取包的 skill/ 子目录（存在时）否则包根；spec 前插 `--` 防选项注入 */
 async function stageNpm(source, ctx) {
 	assertNpmSpecSafe(source);
 	const spec = source.version ? `${source.packageName}@${source.version}` : source.packageName;
@@ -1462,6 +1525,7 @@ async function stageNpm(source, ctx) {
 	try {
 		({stdout} = await execFileP("npm", [
 			"pack",
+			"--ignore-scripts",
 			"--pack-destination",
 			ctx.stagingRoot,
 			"--",
@@ -1578,7 +1642,6 @@ async function verifyIntegrity(fs, skillRoot) {
 	for (const rel of actualFiles) actualHashes.set(rel, sha256Hex(await fs.readBinary(`${skillRoot}/${rel}`)));
 	return verifyManifest(manifest, actualHashes, actualFiles);
 }
-const messageOf = (e) => e instanceof Error ? e.message : String(e);
 const asInstallFailed = (e) => e instanceof WebSkillError && e.code === "INSTALL_FAILED" ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
 /**
 * 技能管理门面：统一安装管线（staging → 解析 name → 校验 → 拷贝 → manifest → lockfile），