@jshookmcp/jshook 0.2.5 → 0.2.7

package/dist/ExtensionManager-CZ6IveoV.mjs

@@ -0,0 +1,707 @@
+import { t as logger } from "./logger-BmWzC2lM.mjs";
+import { f as INSTALLED_EXTENSION_METADATA_FILENAME, t as allTools } from "./ToolCatalog-CnwmMIw3.mjs";
+import { readFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { glob } from "tinyglobby";
+//#region src/server/extensions/ExtensionManager.roots.ts
+/**
+* Extension path resolution — root directories for plugins and workflows.
+*/
+/**
+* Walk up the directory tree from the given start to find the project root
+* (the nearest ancestor that contains a package.json).
+*
+* This is robust across both dev (`src/server/extensions/`) and production
+* (`dist/src/server/extensions/`) layouts — no hard-coded level count needed.
+*/
+function findProjectRoot(startDir) {
+	let dir = startDir;
+	while (true) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return resolve(startDir, "..", "..", "..", "..");
+}
+const EXTENSION_INSTALL_ROOT = findProjectRoot(fileURLToPath(new URL(".", import.meta.url)));
+const DEFAULT_PLUGIN_ROOTS = [join(EXTENSION_INSTALL_ROOT, "plugins")];
+const DEFAULT_WORKFLOW_ROOTS = [join(EXTENSION_INSTALL_ROOT, "workflows")];
+function parseRoots(raw, fallback) {
+	const value = raw?.trim();
+	if (!value) return fallback;
+	const roots = value.split(",").map((item) => item.trim()).filter(Boolean);
+	return roots.length > 0 ? [...new Set(roots)] : fallback;
+}
+function resolveRoots(roots, baseDir = EXTENSION_INSTALL_ROOT) {
+	const resolved = roots.map((root) => isAbsolute(root) ? root : resolve(baseDir, root));
+	return [...new Set(resolved)].toSorted((a, b) => a.localeCompare(b));
+}
+//#endregion
+//#region src/server/extensions/ExtensionManager.version.ts
+/**
+* Semver parsing and compatibility checks for extension version constraints.
+*/
+function parseVersionParts(version) {
+	const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+	if (!match) return null;
+	return [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+}
+function compareVersion(a, b) {
+	const aa = parseVersionParts(a);
+	const bb = parseVersionParts(b);
+	if (!aa || !bb) return null;
+	const [aMajor, aMinor, aPatch] = aa;
+	const [bMajor, bMinor, bPatch] = bb;
+	if (aMajor > bMajor) return 1;
+	if (aMajor < bMajor) return -1;
+	if (aMinor > bMinor) return 1;
+	if (aMinor < bMinor) return -1;
+	if (aPatch > bPatch) return 1;
+	if (aPatch < bPatch) return -1;
+	return 0;
+}
+function isCompatibleVersion(range, currentVersion) {
+	const input = range.trim();
+	if (!input || input === "*") return true;
+	if (input.startsWith(">=")) {
+		const cmp = compareVersion(currentVersion, input.slice(2).trim());
+		return cmp !== null && cmp >= 0;
+	}
+	if (input.startsWith("^")) {
+		const base = input.slice(1).trim();
+		const cc = parseVersionParts(currentVersion);
+		const bb = parseVersionParts(base);
+		if (!cc || !bb) return false;
+		const cmp = compareVersion(currentVersion, base);
+		return cmp !== null && cmp >= 0 && cc[0] === bb[0];
+	}
+	if (input.startsWith("~")) {
+		const base = input.slice(1).trim();
+		const cc = parseVersionParts(currentVersion);
+		const bb = parseVersionParts(base);
+		if (!cc || !bb) return false;
+		const cmp = compareVersion(currentVersion, base);
+		return cmp !== null && cmp >= 0 && cc[0] === bb[0] && cc[1] === bb[1];
+	}
+	const cmp = compareVersion(currentVersion, input);
+	return cmp !== null && cmp === 0;
+}
+//#endregion
+//#region src/server/extensions/ExtensionManager.integrity.ts
+/**
+* Plugin integrity verification — digest allowlists, env guards, compatibility checks.
+*/
+async function sha256Hex(filePath) {
+	const content = await readFile(filePath);
+	return createHash("sha256").update(content).digest("hex");
+}
+function normalizeHex(value) {
+	return value.trim().toLowerCase().replace(/^0x/, "");
+}
+function isTruthyEnv(value) {
+	return ["1", "true"].includes(value.toLowerCase());
+}
+function isPluginSignatureRequired() {
+	const raw = process.env.MCP_PLUGIN_SIGNATURE_REQUIRED;
+	if (raw === void 0 || raw.trim() === "") return process.env.NODE_ENV === "production";
+	return isTruthyEnv(raw);
+}
+function isPluginStrictLoad() {
+	const raw = process.env.MCP_PLUGIN_STRICT_LOAD;
+	if (raw === void 0 || raw.trim() === "") return isPluginSignatureRequired();
+	return isTruthyEnv(raw) || isPluginSignatureRequired();
+}
+function parseDigestAllowlist(raw) {
+	const value = raw?.trim();
+	if (!value) return /* @__PURE__ */ new Set();
+	return new Set(value.split(",").map((item) => normalizeHex(item)).filter((item) => item.length > 0));
+}
+async function verifyPluginIntegrity(plugin, currentVersion) {
+	const errors = [];
+	const warnings = [];
+	if (!isCompatibleVersion(plugin.compatibleCoreRange, currentVersion)) errors.push(`Plugin ${plugin.id} incompatible with core ${currentVersion}; requires ${plugin.compatibleCoreRange}`);
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+//#endregion
+//#region src/server/extensions/ExtensionManager.guards.ts
+function isExtensionBuilder(value) {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value;
+	return !!(typeof candidate.id === "string" && typeof candidate.version === "string" && Array.isArray(candidate.tools) && (candidate.workflows === void 0 || Array.isArray(candidate.workflows)));
+}
+function isWorkflowContract(value) {
+	if (!value || typeof value !== "object") return false;
+	const candidate = value;
+	return !!(candidate.kind === "workflow-contract" && candidate.version === 1 && typeof candidate.id === "string" && typeof candidate.displayName === "string" && typeof candidate.build === "function");
+}
+//#endregion
+//#region src/server/extensions/ExtensionManager.discovery.ts
+/**
+* Extension file discovery — prefers installed registry metadata, then falls back
+* to scanning plugin/workflow roots for legacy manifest files.
+*/
+async function collectMatchingFiles(roots, matcher) {
+	const files = /* @__PURE__ */ new Set();
+	for (const root of roots) {
+		let matchedPaths;
+		try {
+			matchedPaths = await glob("**/*", {
+				cwd: root,
+				absolute: true,
+				onlyFiles: true,
+				ignore: [
+					"**/node_modules/**",
+					"**/.git/**",
+					"**/.pnpm/**"
+				]
+			});
+		} catch {
+			continue;
+		}
+		for (const file of matchedPaths) if (matcher(basename(file))) files.add(file);
+	}
+	return [...files].toSorted((a, b) => a.localeCompare(b));
+}
+function normalizeExtensionCandidateKey(root, file) {
+	const normalizedRoot = root.replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\/+|\/+$/g, "").toLowerCase();
+	const relDir = relative(root, dirname(file)).replace(/^[/\\]+/, "").replace(/\\/g, "/").replace(/\/+/g, "/").replace(/^\/+|\/+$/g, "").toLowerCase();
+	if (!relDir || relDir === "dist") return `${normalizedRoot}::`;
+	return `${normalizedRoot}::${relDir.endsWith("/dist") ? relDir.slice(0, -5) : relDir}`;
+}
+function extensionRank(candidate) {
+	if (candidate.isJs) return 0;
+	if (candidate.isTs) return 1;
+	return 2;
+}
+function isInstalledExtensionMetadata(value, kind) {
+	if (!value || typeof value !== "object") return false;
+	const record = value;
+	if (record.version !== 1 || record.kind !== kind) return false;
+	if (typeof record.slug !== "string" || typeof record.id !== "string") return false;
+	if (!record.source || typeof record.source !== "object") return false;
+	const source = record.source;
+	return typeof source.type === "string" && typeof source.repo === "string" && typeof source.ref === "string" && typeof source.commit === "string" && typeof source.subpath === "string" && typeof source.entry === "string";
+}
+async function collectInstalledEntryCandidates(roots, kind) {
+	const candidates = [];
+	for (const [rootIndex, root] of roots.entries()) {
+		const metadataFiles = await collectMatchingFiles([root], (filename) => filename === INSTALLED_EXTENSION_METADATA_FILENAME);
+		for (const metadataFile of metadataFiles) {
+			let metadataRaw;
+			try {
+				metadataRaw = JSON.parse(await readFile(metadataFile, "utf8"));
+			} catch {
+				continue;
+			}
+			if (!isInstalledExtensionMetadata(metadataRaw, kind)) continue;
+			const entryPath = metadataRaw.source.entry.trim();
+			if (!entryPath) continue;
+			const file = resolve(dirname(metadataFile), entryPath);
+			if (!existsSync(file)) continue;
+			candidates.push({
+				file,
+				key: normalizeExtensionCandidateKey(root, file),
+				isJs: file.endsWith(".js"),
+				isTs: file.endsWith(".ts"),
+				rootIndex,
+				priority: 0
+			});
+		}
+	}
+	return candidates;
+}
+function deduplicateCandidates(candidates) {
+	const byKey = /* @__PURE__ */ new Map();
+	for (const candidate of candidates.toSorted((a, b) => a.file.localeCompare(b.file))) {
+		const existing = byKey.get(candidate.key);
+		if (!existing) {
+			byKey.set(candidate.key, candidate);
+			continue;
+		}
+		const existingRoot = existing.rootIndex;
+		const candidateRoot = candidate.rootIndex;
+		const existingPriority = existing.priority;
+		const candidatePriority = candidate.priority;
+		const existingExtRank = extensionRank(existing);
+		const candidateExtRank = extensionRank(candidate);
+		if (candidateRoot < existingRoot || candidateRoot === existingRoot && candidatePriority < existingPriority || candidateRoot === existingRoot && candidatePriority === existingPriority && candidateExtRank < existingExtRank || candidateRoot === existingRoot && candidatePriority === existingPriority && candidateExtRank === existingExtRank && candidate.file.localeCompare(existing.file) < 0) byKey.set(candidate.key, candidate);
+	}
+	return [...byKey.values()].map((item) => item.file).toSorted((a, b) => a.localeCompare(b));
+}
+async function discoverPluginFiles(pluginRoots) {
+	const candidates = await collectInstalledEntryCandidates(pluginRoots, "plugin");
+	for (const [rootIndex, root] of pluginRoots.entries()) {
+		const files = await collectMatchingFiles([root], (filename) => filename === "manifest.js" || filename === "manifest.ts");
+		for (const file of files) candidates.push({
+			file,
+			key: normalizeExtensionCandidateKey(root, file),
+			isJs: file.endsWith(".js"),
+			isTs: file.endsWith(".ts"),
+			rootIndex,
+			priority: 1
+		});
+	}
+	return deduplicateCandidates(candidates);
+}
+async function discoverWorkflowFiles(workflowRoots) {
+	const candidates = await collectInstalledEntryCandidates(workflowRoots, "workflow");
+	for (const [rootIndex, root] of workflowRoots.entries()) {
+		const files = await collectMatchingFiles([root], (filename) => filename.endsWith(".workflow.js") || filename.endsWith(".workflow.ts") || filename === "workflow.js" || filename === "workflow.ts");
+		for (const file of files) candidates.push({
+			file,
+			key: normalizeExtensionCandidateKey(root, file),
+			isJs: file.endsWith(".js"),
+			isTs: file.endsWith(".ts"),
+			rootIndex,
+			priority: 1
+		});
+	}
+	return deduplicateCandidates(candidates);
+}
+//#endregion
+//#region src/server/extensions/ExtensionManager.lifecycle.ts
+/**
+* Extension lifecycle helpers — import, cleanup, config extraction, list building.
+*/
+function extractConfigValue(ctx, path, fallback) {
+	const segments = path.split(".").filter(Boolean);
+	let current = ctx.config;
+	for (const segment of segments) {
+		if (!current || typeof current !== "object") return fallback;
+		current = current[segment];
+	}
+	return current ?? fallback;
+}
+function createFreshImportUrl(modulePath, kind) {
+	const moduleUrl = new URL(pathToFileURL(modulePath).href);
+	moduleUrl.searchParams.set("reloadTs", String(Date.now()));
+	logger.debug(`[extensions] Loading fresh ${kind} module: ${modulePath}`);
+	return moduleUrl.href;
+}
+async function clearLoadedExtensionTools(ctx) {
+	let removed = 0;
+	for (const [pluginId, runtime] of ctx.extensionPluginRuntimeById.entries()) {
+		try {
+			if (runtime.plugin.onDeactivateHandler && runtime.state === "activated") {
+				await runtime.plugin.onDeactivateHandler(runtime.lifecycleContext);
+				runtime.state = "deactivated";
+			}
+		} catch (error) {
+			logger.warn(`Plugin onDeactivate failed for "${pluginId}":`, error);
+		}
+		try {
+			if (runtime.plugin.onDeactivateHandler) runtime.state = "unloaded";
+		} catch (error) {
+			logger.warn(`Plugin onUnload failed for "${pluginId}":`, error);
+		}
+	}
+	for (const record of ctx.extensionToolsByName.values()) {
+		try {
+			record.registeredTool?.remove();
+		} catch (error) {
+			logger.warn(`Failed to remove extension tool "${record.name}":`, error);
+		}
+		ctx.router.removeHandler(record.name);
+		ctx.activatedToolNames.delete(record.name);
+		ctx.activatedRegisteredTools.delete(record.name);
+		removed++;
+	}
+	ctx.extensionToolsByName.clear();
+	ctx.extensionPluginsById.clear();
+	ctx.extensionPluginRuntimeById.clear();
+	ctx.extensionWorkflowsById.clear();
+	ctx.extensionWorkflowRuntimeById.clear();
+	return removed;
+}
+function buildListResult(ctx, pluginRoots, workflowRoots) {
+	return {
+		pluginRoots,
+		workflowRoots,
+		pluginCount: ctx.extensionPluginsById.size,
+		workflowCount: ctx.extensionWorkflowsById.size,
+		toolCount: ctx.extensionToolsByName.size,
+		lastReloadAt: ctx.lastExtensionReloadAt,
+		plugins: [...ctx.extensionPluginsById.values()],
+		workflows: [...ctx.extensionWorkflowsById.values()],
+		tools: [...ctx.extensionToolsByName.values()].map((record) => ({
+			name: record.name,
+			domain: record.domain,
+			source: record.source
+		}))
+	};
+}
+//#endregion
+//#region src/server/extensions/ExtensionManager.ts
+function listExtensions(ctx) {
+	return buildListResult(ctx, resolveRoots(parseRoots(process.env.MCP_PLUGIN_ROOTS, DEFAULT_PLUGIN_ROOTS)), resolveRoots(parseRoots(process.env.MCP_WORKFLOW_ROOTS, DEFAULT_WORKFLOW_ROOTS)));
+}
+/**
+* Parse a flat key: value YAML file (no nesting, no arrays).
+* Returns a Record<string, string> of trimmed key/value pairs.
+* Returns empty object on any error (file missing, malformed, etc.).
+*/
+function parseSimpleYaml(filePath) {
+	try {
+		const text = readFileSync(filePath, "utf-8");
+		const result = {};
+		for (const line of text.split(/\r?\n/)) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) continue;
+			const colonIdx = trimmed.indexOf(":");
+			if (colonIdx < 1) continue;
+			const key = trimmed.slice(0, colonIdx).trim();
+			const value = trimmed.slice(colonIdx + 1).trim();
+			if (key) result[key] = value;
+		}
+		return result;
+	} catch {
+		return {};
+	}
+}
+function findInstalledMetadataRoot(startDir) {
+	let currentDir = startDir;
+	while (true) {
+		if (existsSync(join(currentDir, ".jshook-install.json"))) return currentDir;
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+function resolvePluginProjectRoot(pluginFile) {
+	const entryDir = dirname(pluginFile);
+	const metadataRoot = findInstalledMetadataRoot(entryDir);
+	if (metadataRoot) return metadataRoot;
+	if (basename(entryDir).toLowerCase() === "dist") return dirname(entryDir);
+	return entryDir;
+}
+let reloadMutex = Promise.resolve();
+const lazyWorkflowLoadAttempted = /* @__PURE__ */ new WeakSet();
+const STRICT_PLUGIN_ALLOWLIST_ERROR = "MCP_PLUGIN_ALLOWED_DIGESTS is required when MCP_PLUGIN_SIGNATURE_REQUIRED=true or MCP_PLUGIN_STRICT_LOAD=true. The digest allowlist is the only pre-import trust boundary — without it, plugin code executes before integrity verification. No plugins will be loaded.";
+const MISSING_PLUGIN_ALLOWLIST_WARNING = "[extensions] Loading plugins WITHOUT MCP_PLUGIN_ALLOWED_DIGESTS allowlist. Plugin code will execute on import() before post-load integrity checks. Set MCP_PLUGIN_STRICT_LOAD=true to enforce allowlist requirement.";
+async function withReloadMutex(operation) {
+	const prev = reloadMutex;
+	let resolve;
+	reloadMutex = new Promise((r) => {
+		resolve = r;
+	});
+	await prev;
+	try {
+		return await operation();
+	} finally {
+		resolve();
+	}
+}
+async function reloadExtensions(ctx) {
+	return withReloadMutex(() => reloadExtensionsInner(ctx));
+}
+async function ensureWorkflowsLoaded(ctx) {
+	if (ctx.extensionWorkflowRuntimeById.size > 0 || lazyWorkflowLoadAttempted.has(ctx)) return;
+	await withReloadMutex(async () => {
+		if (ctx.extensionWorkflowRuntimeById.size > 0 || lazyWorkflowLoadAttempted.has(ctx)) return;
+		lazyWorkflowLoadAttempted.add(ctx);
+		const warnings = [];
+		const errors = [];
+		const pluginRoots = resolveRoots(parseRoots(process.env.MCP_PLUGIN_ROOTS, DEFAULT_PLUGIN_ROOTS));
+		const workflowRoots = resolveRoots(parseRoots(process.env.MCP_WORKFLOW_ROOTS, DEFAULT_WORKFLOW_ROOTS));
+		await loadPluginWorkflowContributions(ctx, pluginRoots, warnings, errors);
+		await loadWorkflows(ctx, await discoverWorkflowFiles(workflowRoots), warnings, errors);
+		for (const warning of warnings) logger.warn(`[extensions] ${warning}`);
+		for (const error of errors) logger.error(`[extensions] ${error}`);
+	});
+}
+async function loadWorkflows(ctx, workflowFiles, warnings, errors) {
+	for (const workflowFile of workflowFiles) try {
+		const mod = await import(createFreshImportUrl(workflowFile, "workflow"));
+		const candidate = mod.default ?? mod;
+		if (!isWorkflowContract(candidate)) {
+			warnings.push(`Skip workflow file without valid WorkflowContract: ${workflowFile}`);
+			continue;
+		}
+		registerWorkflowContract(ctx, candidate, workflowFile, warnings);
+	} catch (error) {
+		errors.push(`Failed to import workflow file ${workflowFile}: ${String(error)}`);
+	}
+}
+function registerWorkflowContract(ctx, workflow, source, warnings) {
+	if (ctx.extensionWorkflowsById.has(workflow.id)) {
+		warnings.push(`Skip workflow "${workflow.id}" from ${source}: duplicate id`);
+		return false;
+	}
+	const record = {
+		id: workflow.id,
+		displayName: workflow.displayName,
+		source,
+		description: workflow.description,
+		tags: workflow.tags,
+		timeoutMs: workflow.timeoutMs,
+		defaultMaxConcurrency: workflow.defaultMaxConcurrency,
+		route: workflow.route
+	};
+	ctx.extensionWorkflowsById.set(record.id, record);
+	const runtimeRecord = {
+		workflow,
+		source,
+		route: workflow.route
+	};
+	ctx.extensionWorkflowRuntimeById.set(record.id, runtimeRecord);
+	return true;
+}
+function buildPluginRecord(plugin, pluginFile, loadedTools, loadedWorkflows) {
+	return {
+		id: plugin.id,
+		name: plugin.pluginName,
+		source: pluginFile,
+		author: plugin.pluginAuthor || void 0,
+		sourceRepo: plugin.pluginSourceRepo || void 0,
+		domains: [],
+		workflows: loadedWorkflows,
+		tools: loadedTools
+	};
+}
+async function loadPluginWorkflowContributions(ctx, pluginRoots, warnings, errors) {
+	const allowedDigests = parseDigestAllowlist(process.env.MCP_PLUGIN_ALLOWED_DIGESTS);
+	if (isPluginStrictLoad() && allowedDigests.size === 0) {
+		errors.push(STRICT_PLUGIN_ALLOWLIST_ERROR);
+		logger.error("[extensions] " + STRICT_PLUGIN_ALLOWLIST_ERROR);
+		return;
+	}
+	if (allowedDigests.size === 0) logger.warn(MISSING_PLUGIN_ALLOWLIST_WARNING);
+	const pluginFiles = await discoverPluginFiles(pluginRoots);
+	const coreVersion = ctx.config?.mcp?.version ?? "0.0.0";
+	for (const pluginFile of pluginFiles) {
+		let fileDigest;
+		try {
+			fileDigest = normalizeHex(await sha256Hex(pluginFile));
+			if (allowedDigests.size > 0 && !allowedDigests.has(fileDigest)) {
+				warnings.push(`Skip plugin file not in MCP_PLUGIN_ALLOWED_DIGESTS allowlist: ${pluginFile}`);
+				continue;
+			}
+		} catch (error) {
+			errors.push(`Failed to hash plugin file ${pluginFile}: ${String(error)}`);
+			continue;
+		}
+		let plugin;
+		try {
+			const mod = await import(createFreshImportUrl(pluginFile, "plugin"));
+			const candidate = mod.default ?? mod;
+			if (!isExtensionBuilder(candidate)) {
+				warnings.push(`Skip plugin file without valid ExtensionBuilder: ${pluginFile}`);
+				continue;
+			}
+			plugin = candidate;
+		} catch (error) {
+			errors.push(`Failed to import plugin file ${pluginFile}: ${String(error)}`);
+			continue;
+		}
+		const meta = parseSimpleYaml(join(resolvePluginProjectRoot(pluginFile), "meta.yaml"));
+		plugin.mergeMetadata(meta);
+		if (ctx.extensionPluginsById.has(plugin.id)) {
+			warnings.push(`Skip plugin "${plugin.id}" from ${pluginFile}: duplicate plugin id`);
+			continue;
+		}
+		try {
+			const verification = await verifyPluginIntegrity(plugin, coreVersion);
+			warnings.push(...verification.warnings);
+			if (!verification.ok) {
+				errors.push(...verification.errors);
+				continue;
+			}
+		} catch (error) {
+			errors.push(`Failed to verify plugin ${plugin.id}: ${String(error)}`);
+			continue;
+		}
+		const loadedWorkflows = [];
+		const pluginWorkflows = Array.isArray(plugin.workflows) ? plugin.workflows : [];
+		for (const candidate of pluginWorkflows) {
+			if (!isWorkflowContract(candidate)) {
+				warnings.push(`Skip invalid workflow contribution from plugin "${plugin.id}" in ${pluginFile}`);
+				continue;
+			}
+			if (registerWorkflowContract(ctx, candidate, `${pluginFile}#workflow:${candidate.id}`, warnings)) loadedWorkflows.push(candidate.id);
+		}
+		if (loadedWorkflows.length === 0) continue;
+		ctx.extensionPluginsById.set(plugin.id, buildPluginRecord(plugin, pluginFile, [], loadedWorkflows));
+	}
+}
+async function reloadExtensionsInner(ctx) {
+	const warnings = [];
+	const errors = [];
+	const removedTools = await clearLoadedExtensionTools(ctx);
+	const pluginRoots = resolveRoots(parseRoots(process.env.MCP_PLUGIN_ROOTS, DEFAULT_PLUGIN_ROOTS));
+	const workflowRoots = resolveRoots(parseRoots(process.env.MCP_WORKFLOW_ROOTS, DEFAULT_WORKFLOW_ROOTS));
+	const allowedDigests = parseDigestAllowlist(process.env.MCP_PLUGIN_ALLOWED_DIGESTS);
+	if (isPluginStrictLoad() && allowedDigests.size === 0) {
+		const msg = STRICT_PLUGIN_ALLOWLIST_ERROR;
+		errors.push(msg);
+		logger.error("[extensions] " + msg);
+		await loadWorkflows(ctx, await discoverWorkflowFiles(workflowRoots), warnings, errors);
+		ctx.lastExtensionReloadAt = (/* @__PURE__ */ new Date()).toISOString();
+		return {
+			...buildListResult(ctx, pluginRoots, workflowRoots),
+			addedTools: 0,
+			removedTools,
+			warnings,
+			errors
+		};
+	}
+	if (allowedDigests.size === 0) logger.warn(MISSING_PLUGIN_ALLOWLIST_WARNING);
+	const baseToolNames = new Set(allTools.map((tool) => tool.name));
+	const pluginFiles = await discoverPluginFiles(pluginRoots);
+	const coreVersion = ctx.config?.mcp?.version ?? "0.0.0";
+	for (const pluginFile of pluginFiles) {
+		let fileDigest;
+		try {
+			fileDigest = normalizeHex(await sha256Hex(pluginFile));
+			if (allowedDigests.size > 0 && !allowedDigests.has(fileDigest)) {
+				warnings.push(`Skip plugin file not in MCP_PLUGIN_ALLOWED_DIGESTS allowlist: ${pluginFile}`);
+				continue;
+			}
+		} catch (error) {
+			errors.push(`Failed to hash plugin file ${pluginFile}: ${String(error)}`);
+			continue;
+		}
+		let plugin;
+		try {
+			const mod = await import(createFreshImportUrl(pluginFile, "plugin"));
+			const candidate = mod.default ?? mod;
+			if (!isExtensionBuilder(candidate)) {
+				warnings.push(`Skip plugin file without valid ExtensionBuilder: ${pluginFile}`);
+				continue;
+			}
+			plugin = candidate;
+		} catch (error) {
+			errors.push(`Failed to import plugin file ${pluginFile}: ${String(error)}`);
+			continue;
+		}
+		const pluginProjectRoot = resolvePluginProjectRoot(pluginFile);
+		const meta = parseSimpleYaml(join(pluginProjectRoot, "meta.yaml"));
+		plugin.mergeMetadata(meta);
+		if (ctx.extensionPluginsById.has(plugin.id)) {
+			warnings.push(`Skip plugin "${plugin.id}" from ${pluginFile}: duplicate plugin id`);
+			continue;
+		}
+		try {
+			const verification = await verifyPluginIntegrity(plugin, coreVersion);
+			warnings.push(...verification.warnings);
+			if (!verification.ok) {
+				errors.push(...verification.errors);
+				continue;
+			}
+		} catch (error) {
+			errors.push(`Failed to verify plugin ${plugin.id}: ${String(error)}`);
+			continue;
+		}
+		const runtimeData = /* @__PURE__ */ new Map();
+		const metrics = /* @__PURE__ */ new Set();
+		let pluginState = "loaded";
+		const allowInvokeAll = plugin.allowedTools.includes("*");
+		const lifecycleContext = {
+			pluginId: plugin.id,
+			pluginRoot: pluginProjectRoot,
+			config: ctx.config,
+			get state() {
+				return pluginState;
+			},
+			registerMetric(metricName) {
+				metrics.add(metricName);
+			},
+			async invokeTool(name, args = {}) {
+				if (typeof name !== "string" || name.length === 0) throw new Error("invokeTool requires a non-empty tool name");
+				if (!allowInvokeAll && !plugin.allowedTools.includes(name)) throw new Error(`Plugin "${plugin.id}" is not allowed to invoke "${name}". Declare it in allowTool calls.`);
+				if (!baseToolNames.has(name)) throw new Error(`Plugin "${plugin.id}" can only invoke built-in tools. "${name}" is not built-in.`);
+				if (!ctx.router.has(name)) throw new Error(`Tool "${name}" is not available in the current active profile.`);
+				return ctx.executeToolWithTracking(name, args ?? {});
+			},
+			hasPermission(_capability) {
+				return true;
+			},
+			getConfig(path, fallback) {
+				return extractConfigValue(ctx, path, fallback);
+			},
+			setRuntimeData(key, value) {
+				runtimeData.set(key, value);
+			},
+			getRuntimeData(key) {
+				return runtimeData.get(key);
+			}
+		};
+		const runtimeRecord = {
+			plugin,
+			lifecycleContext,
+			state: pluginState,
+			source: pluginFile
+		};
+		try {
+			if (plugin.onLoadHandler) await plugin.onLoadHandler(lifecycleContext);
+			pluginState = "loaded";
+			runtimeRecord.state = pluginState;
+			if (plugin.onValidateHandler) {
+				const validation = await plugin.onValidateHandler(lifecycleContext);
+				if (!validation.valid) {
+					warnings.push(`Plugin ${plugin.id} validation failed: ${validation.errors.join("; ")}`);
+					continue;
+				}
+				pluginState = "validated";
+				runtimeRecord.state = pluginState;
+			}
+			if (plugin.onActivateHandler) {
+				await plugin.onActivateHandler(lifecycleContext);
+				pluginState = "activated";
+				runtimeRecord.state = pluginState;
+			}
+			ctx.extensionPluginRuntimeById.set(plugin.id, runtimeRecord);
+		} catch (error) {
+			try {
+				if (plugin.onDeactivateHandler && pluginState === "activated") {
+					await plugin.onDeactivateHandler(lifecycleContext);
+					pluginState = "deactivated";
+					runtimeRecord.state = pluginState;
+				}
+			} catch (deactivateError) {
+				logger.warn(`Plugin onDeactivate failed during rollback for ${plugin.id}:`, deactivateError);
+			}
+			errors.push(`Plugin lifecycle failed for ${plugin.id}: ${String(error)}`);
+			continue;
+		}
+		const loadedTools = plugin.tools.map((t) => t.name);
+		const loadedWorkflows = [];
+		const pluginWorkflows = Array.isArray(plugin.workflows) ? plugin.workflows : [];
+		for (const candidate of pluginWorkflows) {
+			if (!isWorkflowContract(candidate)) {
+				warnings.push(`Skip invalid workflow contribution from plugin "${plugin.id}" in ${pluginFile}`);
+				continue;
+			}
+			if (registerWorkflowContract(ctx, candidate, `${pluginFile}#workflow:${candidate.id}`, warnings)) loadedWorkflows.push(candidate.id);
+		}
+		const record = buildPluginRecord(plugin, pluginFile, loadedTools, loadedWorkflows);
+		ctx.extensionPluginsById.set(record.id, record);
+	}
+	await loadWorkflows(ctx, await discoverWorkflowFiles(workflowRoots), warnings, errors);
+	if (ctx.extensionToolsByName.size > 0 || removedTools > 0) try {
+		await ctx.server.sendToolListChanged();
+	} catch (error) {
+		logger.warn("sendToolListChanged failed after extension reload:", error);
+	}
+	ctx.lastExtensionReloadAt = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		...buildListResult(ctx, pluginRoots, workflowRoots),
+		addedTools: ctx.extensionToolsByName.size,
+		removedTools,
+		warnings,
+		errors
+	};
+}
+//#endregion
+export { listExtensions as n, reloadExtensions as r, ensureWorkflowsLoaded as t };