@agimon-ai/po-config 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/agentPluginMcp.mjs

@@ -1,12 +1,19 @@
-import { createHash, randomUUID } from "node:crypto";
-import fs from "node:fs";
-import { validateHeaderName, validateHeaderValue } from "node:http";
-import { isIP } from "node:net";
 import path from "node:path";
+import { getOrThrow, nodeHost, writeFileAtomic } from "@agimon-ai/po-core/platform";
+import { createHash, randomUUID } from "node:crypto";
 import { AGENT_PLUGIN_MCP_SCHEMA_URL } from "@agimon-ai/po-core/mcpProjection";
-//#region src/services/agentPluginMcp/index.ts
-const PRIVATE_FILE_MODE = 384;
-const PRIVATE_DIRECTORY_MODE = 448;
+import fs from "node:fs";
+//#region src/services/agentPluginMcp/normalize.ts
+/** Pure Agent Plugin MCP normalisation shared by the async API and the deprecated Node-only sync shim. */
+/** Same token grammar as node:http `validateHeaderName` (RFC 9110 tchar). */
+const HTTP_TOKEN = /^[\^_`a-zA-Z\-0-9!#$%&'*+.|~]+$/u;
+/** Same rejected characters as node:http `validateHeaderValue`. */
+const INVALID_HEADER_VALUE_CHARACTER = /[^\t\x20-\x7e\x80-\xff]/u;
+const IPV4_OCTET = "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)";
+const IPV4_ADDRESS = new RegExp(`^${IPV4_OCTET}(?:\\.${IPV4_OCTET}){3}$`, "u");
+function isIPv4(value) {
+	return IPV4_ADDRESS.test(value);
+}
 const RESERVED_ENVIRONMENT_KEYS = /* @__PURE__ */ new Set(["PLUGIN_ROOT", "PLUGIN_DATA"]);
 const PROXY_SERVER_ALIASES = /* @__PURE__ */ new Set(["mcp-proxy", "agiflow-proxy"]);
 function isObject(value) {
@@ -43,49 +50,6 @@ function isInside(root, candidate) {
 	const relative = path.relative(root, candidate);
 	return relative === "" || !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative);
 }
-function realContainedPath(root, candidate, label) {
-	let realCandidate;
-	try {
-		realCandidate = fs.realpathSync(candidate);
-	} catch {
-		throw new Error(`${label} does not exist`);
-	}
-	if (!isInside(root, realCandidate)) throw new Error(`${label} escapes its allowed plugin directory`);
-	return realCandidate;
-}
-function normalizeCommand(command, pluginRoot) {
-	if (command.startsWith("./")) {
-		const resolved = realContainedPath(pluginRoot, path.resolve(pluginRoot, command), "command");
-		if (!fs.statSync(resolved).isFile()) throw new Error("command must resolve to a regular file");
-		try {
-			fs.accessSync(resolved, fs.constants.X_OK);
-		} catch {
-			throw new Error("command must resolve to an executable file");
-		}
-		return resolved;
-	}
-	if (command === "." || command === ".." || /[\s/\\]/u.test(command)) throw new Error("command must be a bare executable name or a ./ path inside the plugin");
-	return command;
-}
-function normalizeWorkingDirectory(declared, pluginRoot, pluginDataDirectory) {
-	if (declared === void 0) return pluginRoot;
-	const cwd = nonEmptyString(declared, "cwd");
-	let base;
-	let expanded;
-	if (cwd.startsWith("./")) {
-		base = pluginRoot;
-		expanded = path.resolve(pluginRoot, cwd);
-	} else if (cwd === "${PLUGIN_ROOT}" || cwd.startsWith("${PLUGIN_ROOT}/")) {
-		base = pluginRoot;
-		expanded = expandPluginPlaceholders(cwd, pluginRoot, pluginDataDirectory);
-	} else if (cwd === "${PLUGIN_DATA}" || cwd.startsWith("${PLUGIN_DATA}/")) {
-		base = pluginDataDirectory;
-		expanded = expandPluginPlaceholders(cwd, pluginRoot, pluginDataDirectory);
-	} else throw new Error("cwd must start with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA}");
-	const resolved = realContainedPath(base, path.resolve(expanded), "cwd");
-	if (!fs.statSync(resolved).isDirectory()) throw new Error("cwd must resolve to a directory");
-	return resolved;
-}
 function normalizeEnvironment(value, pluginRoot, pluginDataDirectory) {
 	const declared = optionalStringRecord(value, "env") ?? {};
 	for (const key of Object.keys(declared)) {
@@ -101,9 +65,8 @@ function normalizeEnvironment(value, pluginRoot, pluginDataDirectory) {
 function isLoopbackHost(hostname) {
 	const bareHostname = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
 	if (bareHostname.toLowerCase() === "localhost") return true;
-	const family = isIP(bareHostname);
-	if (family === 4) return bareHostname.split(".")[0] === "127";
-	return family === 6 && bareHostname === "::1";
+	if (isIPv4(bareHostname)) return bareHostname.split(".")[0] === "127";
+	return bareHostname === "::1";
 }
 function normalizeUrl(value) {
 	const raw = nonEmptyString(value, "url");
@@ -127,48 +90,89 @@ function normalizeHeaders(value) {
 		const canonical = name.toLowerCase();
 		if (seen.has(canonical)) throw new Error(`headers contain duplicate name "${name}"`);
 		seen.add(canonical);
-		try {
-			validateHeaderName(name);
-			validateHeaderValue(name, item);
-		} catch {
-			throw new Error(`header "${name}" is invalid`);
-		}
+		if (!HTTP_TOKEN.test(name) || INVALID_HEADER_VALUE_CHARACTER.test(item)) throw new Error(`header "${name}" is invalid`);
 	}
 	return headers;
 }
-function normalizeServer(raw, pluginRoot, pluginDataDirectory, name) {
+function stagedInternalPath(source, contents, stagingDirectory) {
+	const digest = createHash("sha256").update(source.sourceId).update("\0").update(source.contentDigest).update("\0").update(contents).digest("hex").slice(0, 20);
+	return path.join(stagingDirectory, `agent-plugin-mcp-${digest}.internal.json`);
+}
+function emptyResult(diagnostic) {
+	return {
+		claudeConfig: { mcpServers: {} },
+		serverNames: [],
+		droppedServers: [],
+		diagnostics: [diagnostic]
+	};
+}
+function sourceLabel(source) {
+	return `Agent Plugin MCP source "${source.sourceId}"`;
+}
+/** Checks the projection identity before any file is touched. */
+function assertProjectionSource(source) {
+	if (source.mcpSchemaUrl !== AGENT_PLUGIN_MCP_SCHEMA_URL) throw new Error(`unsupported schema "${String(source.mcpSchemaUrl)}"`);
+	if (!path.isAbsolute(source.pluginRoot) || !path.isAbsolute(source.pluginDataDirectory)) throw new Error("pluginRoot and pluginDataDirectory must be absolute");
+}
+function assertRootConfigPath(configPath, pluginRoot) {
+	if (path.dirname(configPath) !== pluginRoot || path.basename(configPath) !== "mcp.json") throw new Error("portable plugin config must be root mcp.json");
+}
+/** Verifies the digest and document shape of the raw mcp.json bytes; returns its server map. */
+function parseMcpDocument(source, bytes, label) {
+	if (createHash("sha256").update(bytes).digest("hex") !== source.contentDigest) throw new Error("content digest does not match the projection");
+	const parsed = JSON.parse(new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes));
+	if (!isObject(parsed)) throw new Error("document must be an object");
+	onlyKeys(parsed, ["$schema", "mcpServers"], label);
+	if (parsed.$schema !== source.mcpSchemaUrl) throw new Error("$schema does not match the projected schema");
+	if (!isObject(parsed.mcpServers)) throw new Error("mcpServers must be an object");
+	return parsed.mcpServers;
+}
+/** Whether a declared server is skipped (empty name), dropped by the allowlist or wrapper rule, or normalised. */
+function serverDisposition(name, options) {
+	if (!name) return "empty";
+	const allowed = options.allowedServers;
+	const keepAll = !allowed || allowed.length === 0;
+	const stripProxyWrappers = options.stripProxyWrappers ?? true;
+	if (!keepAll && !allowed.includes(name) || stripProxyWrappers && PROXY_SERVER_ALIASES.has(name)) return "dropped";
+	return "keep";
+}
+function emptyServerDiagnostic(label) {
+	return `${label} contains an empty server name; that entry was skipped.`;
+}
+function skippedServerDiagnostic(label, name, error) {
+	return `${label} skipped server "${name}": ${error instanceof Error ? error.message : String(error)}`;
+}
+function disabledResult(label, error) {
+	return emptyResult(`${label} was disabled: ${error instanceof Error ? error.message : String(error)}`);
+}
+/** The declared transport of one server; stdio declarations are also checked for unsupported fields. */
+function serverType(raw, name) {
 	if (!isObject(raw)) throw new Error("definition must be an object");
 	const type = nonEmptyString(raw.type, "type");
-	if (type === "stdio") {
-		onlyKeys(raw, [
-			"type",
-			"command",
-			"args",
-			"env",
-			"cwd"
-		], `server "${name}"`);
-		const command = normalizeCommand(nonEmptyString(raw.command, "command"), pluginRoot);
-		const args = optionalStringArray(raw.args, "args")?.map((item) => expandPluginPlaceholders(item, pluginRoot, pluginDataDirectory));
-		const env = normalizeEnvironment(raw.env, pluginRoot, pluginDataDirectory);
-		const cwd = normalizeWorkingDirectory(raw.cwd, pluginRoot, pluginDataDirectory);
-		const config = {
-			command,
-			...args ? { args } : {},
-			env,
-			cwd
-		};
-		return {
-			internal: {
-				name,
-				transport: "stdio",
-				config
-			},
-			claude: {
-				type: "stdio",
-				...config
-			}
-		};
-	}
+	if (type === "stdio") onlyKeys(raw, [
+		"type",
+		"command",
+		"args",
+		"env",
+		"cwd"
+	], `server "${name}"`);
+	return type;
+}
+function stdioServer(name, config) {
+	return {
+		internal: {
+			name,
+			transport: "stdio",
+			config
+		},
+		claude: {
+			type: "stdio",
+			...config
+		}
+	};
+}
+/** A streamable-http or sse server; any other type is unsupported. */
+function remoteServer(raw, name, type) {
 	if (type === "streamable-http" || type === "sse") {
 		onlyKeys(raw, [
 			"type",
@@ -196,21 +200,93 @@ function normalizeServer(raw, pluginRoot, pluginDataDirectory, name) {
 	}
 	throw new Error(`unsupported transport type "${type}"`);
 }
-function stagedInternalPath(source, contents, stagingDirectory) {
-	const digest = createHash("sha256").update(source.sourceId).update("\0").update(source.contentDigest).update("\0").update(contents).digest("hex").slice(0, 20);
-	return path.join(stagingDirectory, `agent-plugin-mcp-${digest}.internal.json`);
+function stagedContents(internalServers) {
+	return `${JSON.stringify({ mcpServers: internalServers }, null, 2)}\n`;
+}
+function stagedCacheKey(source, configPath, contents) {
+	return createHash("sha256").update("agent-plugin-v1\0").update(source.sourceId).update("\0").update(source.contentDigest).update("\0").update(configPath).update("\0").update(contents).digest("hex");
 }
-function writeStagedInternalConfig(target, contents, stagingDirectory) {
+/** The containment base and expanded path of a declared cwd, or undefined when the plugin root is the default. */
+function workingDirectoryCandidate(declared, pluginRoot, pluginDataDirectory) {
+	if (declared === void 0) return void 0;
+	const cwd = nonEmptyString(declared, "cwd");
+	if (cwd.startsWith("./")) return {
+		base: pluginRoot,
+		candidate: path.resolve(pluginRoot, cwd)
+	};
+	const expanded = expandPluginPlaceholders(cwd, pluginRoot, pluginDataDirectory);
+	if (cwd === "${PLUGIN_ROOT}" || cwd.startsWith("${PLUGIN_ROOT}/")) return {
+		base: pluginRoot,
+		candidate: path.resolve(expanded)
+	};
+	if (cwd === "${PLUGIN_DATA}" || cwd.startsWith("${PLUGIN_DATA}/")) return {
+		base: pluginDataDirectory,
+		candidate: path.resolve(expanded)
+	};
+	throw new Error("cwd must start with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA}");
+}
+/** Rejects a command that is neither a bare executable name nor a ./ path; true when it must be resolved. */
+function isPluginRelativeCommand(command) {
+	if (command.startsWith("./")) return true;
+	if (command === "." || command === ".." || /[\s/\\]/u.test(command)) throw new Error("command must be a bare executable name or a ./ path inside the plugin");
+	return false;
+}
+//#endregion
+//#region src/services/agentPluginMcp/sync.ts
+function realContainedPath$1(root, candidate, label) {
+	let realCandidate;
+	try {
+		realCandidate = fs.realpathSync(candidate);
+	} catch {
+		throw new Error(`${label} does not exist`);
+	}
+	if (!isInside(root, realCandidate)) throw new Error(`${label} escapes its allowed plugin directory`);
+	return realCandidate;
+}
+function normalizeCommand$1(command, pluginRoot) {
+	if (!isPluginRelativeCommand(command)) return command;
+	const resolved = realContainedPath$1(pluginRoot, path.resolve(pluginRoot, command), "command");
+	if (!fs.statSync(resolved).isFile()) throw new Error("command must resolve to a regular file");
+	try {
+		fs.accessSync(resolved, fs.constants.X_OK);
+	} catch {
+		throw new Error("command must resolve to an executable file");
+	}
+	return resolved;
+}
+function normalizeWorkingDirectory$1(declared, pluginRoot, pluginDataDirectory) {
+	const declaredCwd = workingDirectoryCandidate(declared, pluginRoot, pluginDataDirectory);
+	if (!declaredCwd) return pluginRoot;
+	const resolved = realContainedPath$1(declaredCwd.base, declaredCwd.candidate, "cwd");
+	if (!fs.statSync(resolved).isDirectory()) throw new Error("cwd must resolve to a directory");
+	return resolved;
+}
+function normalizeServer$1(raw, pluginRoot, pluginDataDirectory, name) {
+	const type = serverType(raw, name);
+	const declaration = raw;
+	if (type !== "stdio") return remoteServer(declaration, name, type);
+	const command = normalizeCommand$1(nonEmptyString(declaration.command, "command"), pluginRoot);
+	const args = optionalStringArray(declaration.args, "args")?.map((item) => expandPluginPlaceholders(item, pluginRoot, pluginDataDirectory));
+	const env = normalizeEnvironment(declaration.env, pluginRoot, pluginDataDirectory);
+	const cwd = normalizeWorkingDirectory$1(declaration.cwd, pluginRoot, pluginDataDirectory);
+	return stdioServer(name, {
+		command,
+		...args ? { args } : {},
+		env,
+		cwd
+	});
+}
+function writeStagedInternalConfig$1(target, contents, stagingDirectory) {
 	fs.mkdirSync(stagingDirectory, {
-		mode: PRIVATE_DIRECTORY_MODE,
+		mode: 448,
 		recursive: true
 	});
-	fs.chmodSync(stagingDirectory, PRIVATE_DIRECTORY_MODE);
+	fs.chmodSync(stagingDirectory, 448);
 	const temporaryPath = `${target}.${process.pid}-${randomUUID()}.tmp`;
 	try {
 		fs.writeFileSync(temporaryPath, contents, {
 			flag: "wx",
-			mode: PRIVATE_FILE_MODE
+			mode: 384
 		});
 		try {
 			fs.renameSync(temporaryPath, target);
@@ -220,19 +296,11 @@ function writeStagedInternalConfig(target, contents, stagingDirectory) {
 			const stat = fs.lstatSync(target);
 			if (stat.isSymbolicLink() || !stat.isFile() || fs.readFileSync(target, "utf8") !== contents) throw new Error("content-addressed staging path is occupied by different content");
 		}
-		fs.chmodSync(target, PRIVATE_FILE_MODE);
+		fs.chmodSync(target, 384);
 	} finally {
 		fs.rmSync(temporaryPath, { force: true });
 	}
 }
-function emptyResult(diagnostic) {
-	return {
-		claudeConfig: { mcpServers: {} },
-		serverNames: [],
-		droppedServers: [],
-		diagnostics: [diagnostic]
-	};
-}
 /**
 * Validates one Agent Plugins v1 `mcp.json` and stages a native mcp-proxy layer.
 *
@@ -240,12 +308,13 @@ function emptyResult(diagnostic) {
 * Document/schema, source identity, or plugin-boundary failures reject the whole
 * source. Only the two portable plugin placeholders are expanded; the staged
 * layer is tagged `internal`, so legacy `${ENV}` interpolation cannot run again.
+*
+* @deprecated Node-only sync shim; use normalizeAgentPluginMcpSourceAsync. Removed in M2.
 */
 function normalizeAgentPluginMcpSource(source, options) {
-	const label = `Agent Plugin MCP source "${source.sourceId}"`;
+	const label = sourceLabel(source);
 	try {
-		if (source.mcpSchemaUrl !== AGENT_PLUGIN_MCP_SCHEMA_URL) throw new Error(`unsupported schema "${String(source.mcpSchemaUrl)}"`);
-		if (!path.isAbsolute(source.pluginRoot) || !path.isAbsolute(source.pluginDataDirectory)) throw new Error("pluginRoot and pluginDataDirectory must be absolute");
+		assertProjectionSource(source);
 		const pluginRoot = fs.realpathSync(source.pluginRoot);
 		try {
 			const dataStat = fs.lstatSync(source.pluginDataDirectory);
@@ -253,55 +322,164 @@ function normalizeAgentPluginMcpSource(source, options) {
 		} catch (error) {
 			if (error.code !== "ENOENT") throw error;
 			fs.mkdirSync(source.pluginDataDirectory, {
-				mode: PRIVATE_DIRECTORY_MODE,
+				mode: 448,
 				recursive: true
 			});
 		}
-		fs.chmodSync(source.pluginDataDirectory, PRIVATE_DIRECTORY_MODE);
+		fs.chmodSync(source.pluginDataDirectory, 448);
 		fs.accessSync(source.pluginDataDirectory, fs.constants.W_OK);
 		const pluginDataDirectory = fs.realpathSync(source.pluginDataDirectory);
-		const configPath = realContainedPath(pluginRoot, source.configPath, "mcp.json");
-		if (path.dirname(configPath) !== pluginRoot || path.basename(configPath) !== "mcp.json") throw new Error("portable plugin config must be root mcp.json");
-		const bytes = fs.readFileSync(configPath);
-		if (createHash("sha256").update(bytes).digest("hex") !== source.contentDigest) throw new Error("content digest does not match the projection");
-		const parsed = JSON.parse(bytes.toString("utf8"));
-		if (!isObject(parsed)) throw new Error("document must be an object");
-		onlyKeys(parsed, ["$schema", "mcpServers"], label);
-		if (parsed.$schema !== source.mcpSchemaUrl) throw new Error("$schema does not match the projected schema");
-		if (!isObject(parsed.mcpServers)) throw new Error("mcpServers must be an object");
-		const allowed = options.allowedServers;
-		const keepAll = !allowed || allowed.length === 0;
-		const stripProxyWrappers = options.stripProxyWrappers ?? true;
+		const configPath = realContainedPath$1(pluginRoot, source.configPath, "mcp.json");
+		assertRootConfigPath(configPath, pluginRoot);
+		const servers = parseMcpDocument(source, fs.readFileSync(configPath), label);
+		const internalServers = Object.create(null);
+		const claudeServers = Object.create(null);
+		const droppedServers = [];
+		const diagnostics = [];
+		for (const [name, rawServer] of Object.entries(servers)) {
+			const disposition = serverDisposition(name, options);
+			if (disposition === "empty") {
+				diagnostics.push(emptyServerDiagnostic(label));
+				continue;
+			}
+			if (disposition === "dropped") {
+				droppedServers.push(name);
+				continue;
+			}
+			try {
+				const normalized = normalizeServer$1(rawServer, pluginRoot, pluginDataDirectory, name);
+				internalServers[name] = normalized.internal;
+				claudeServers[name] = normalized.claude;
+			} catch (error) {
+				droppedServers.push(name);
+				diagnostics.push(skippedServerDiagnostic(label, name, error));
+			}
+		}
+		const contents = stagedContents(internalServers);
+		const target = stagedInternalPath(source, contents, options.stagingDirectory);
+		writeStagedInternalConfig$1(target, contents, options.stagingDirectory);
+		return {
+			configSource: {
+				path: target,
+				format: "internal",
+				cacheKey: stagedCacheKey(source, configPath, contents)
+			},
+			claudeConfig: { mcpServers: claudeServers },
+			serverNames: Object.keys(internalServers),
+			droppedServers,
+			diagnostics
+		};
+	} catch (error) {
+		return disabledResult(label, error);
+	}
+}
+//#endregion
+//#region src/services/agentPluginMcp/index.ts
+async function realContainedPath(fs, root, candidate, label, context) {
+	const real = await fs.canonicalPath(candidate, context);
+	if (!real.ok) throw new Error(`${label} does not exist`);
+	if (!isInside(root, real.value)) throw new Error(`${label} escapes its allowed plugin directory`);
+	return real.value;
+}
+async function normalizeCommand(fs, command, pluginRoot, context) {
+	if (!isPluginRelativeCommand(command)) return command;
+	const resolved = await realContainedPath(fs, pluginRoot, path.resolve(pluginRoot, command), "command", context);
+	if (getOrThrow(await fs.fileInfo(resolved, context)).kind !== "file") throw new Error("command must resolve to a regular file");
+	const mode = await nodeHost.fileMode(resolved);
+	if (mode !== void 0 && (mode & 73) === 0) throw new Error("command must resolve to an executable file");
+	return resolved;
+}
+async function normalizeWorkingDirectory(fs, declared, pluginRoot, pluginDataDirectory, context) {
+	const declaredCwd = workingDirectoryCandidate(declared, pluginRoot, pluginDataDirectory);
+	if (!declaredCwd) return pluginRoot;
+	const resolved = await realContainedPath(fs, declaredCwd.base, declaredCwd.candidate, "cwd", context);
+	if (getOrThrow(await fs.fileInfo(resolved, context)).kind !== "directory") throw new Error("cwd must resolve to a directory");
+	return resolved;
+}
+async function normalizeServer(fs, raw, pluginRoot, pluginDataDirectory, name, context) {
+	const type = serverType(raw, name);
+	const declaration = raw;
+	if (type !== "stdio") return remoteServer(declaration, name, type);
+	const command = await normalizeCommand(fs, nonEmptyString(declaration.command, "command"), pluginRoot, context);
+	const args = optionalStringArray(declaration.args, "args")?.map((item) => expandPluginPlaceholders(item, pluginRoot, pluginDataDirectory));
+	const env = normalizeEnvironment(declaration.env, pluginRoot, pluginDataDirectory);
+	const cwd = await normalizeWorkingDirectory(fs, declaration.cwd, pluginRoot, pluginDataDirectory, context);
+	return stdioServer(name, {
+		command,
+		...args ? { args } : {},
+		env,
+		cwd
+	});
+}
+/** Owner-only plugin data directory; a symbolic link or non-directory rejects the source. */
+async function preparePluginDataDirectory(fs, directory, context) {
+	const info = await fs.fileInfo(directory, context);
+	if (info.ok) {
+		if (info.value.kind !== "directory") throw new Error("pluginDataDirectory must be a real directory");
+	} else if (info.error.code === "not_found") getOrThrow(await fs.createDir(directory, { recursive: true }, context));
+	else throw info.error;
+	await nodeHost.setMode(directory, 448);
+	return getOrThrow(await fs.canonicalPath(directory, context));
+}
+/**
+* Content-addressed and owner-only. The name hashes the contents, so replacing an
+* existing staged file through a uniquely named temporary file never changes what it holds.
+*/
+async function writeStagedInternalConfig(fs, target, contents, stagingDirectory, context) {
+	getOrThrow(await fs.createDir(stagingDirectory, { recursive: true }, context));
+	await nodeHost.setMode(stagingDirectory, 448);
+	await writeFileAtomic(fs, target, contents, context);
+	await nodeHost.setMode(target, 384);
+}
+/**
+* Validates one Agent Plugins v1 `mcp.json` and stages a native mcp-proxy layer,
+* reading and writing through the injected file system.
+*
+* Server validation is isolated: one malformed server is diagnosed and skipped.
+* Document/schema, source identity, or plugin-boundary failures reject the whole
+* source. Only the two portable plugin placeholders are expanded; the staged
+* layer is tagged `internal`, so legacy `${ENV}` interpolation cannot run again.
+*/
+async function normalizeAgentPluginMcpSourceAsync(fs, source, options, context) {
+	const label = sourceLabel(source);
+	try {
+		assertProjectionSource(source);
+		const pluginRoot = getOrThrow(await fs.canonicalPath(source.pluginRoot, context));
+		const pluginDataDirectory = await preparePluginDataDirectory(fs, source.pluginDataDirectory, context);
+		const configPath = await realContainedPath(fs, pluginRoot, source.configPath, "mcp.json", context);
+		assertRootConfigPath(configPath, pluginRoot);
+		const servers = parseMcpDocument(source, getOrThrow(await fs.readBinaryFile(configPath, context)), label);
 		const internalServers = Object.create(null);
 		const claudeServers = Object.create(null);
 		const droppedServers = [];
 		const diagnostics = [];
-		for (const [name, rawServer] of Object.entries(parsed.mcpServers)) {
-			if (!name) {
-				diagnostics.push(`${label} contains an empty server name; that entry was skipped.`);
+		for (const [name, rawServer] of Object.entries(servers)) {
+			const disposition = serverDisposition(name, options);
+			if (disposition === "empty") {
+				diagnostics.push(emptyServerDiagnostic(label));
 				continue;
 			}
-			if (!keepAll && !allowed.includes(name) || stripProxyWrappers && PROXY_SERVER_ALIASES.has(name)) {
+			if (disposition === "dropped") {
 				droppedServers.push(name);
 				continue;
 			}
 			try {
-				const normalized = normalizeServer(rawServer, pluginRoot, pluginDataDirectory, name);
+				const normalized = await normalizeServer(fs, rawServer, pluginRoot, pluginDataDirectory, name, context);
 				internalServers[name] = normalized.internal;
 				claudeServers[name] = normalized.claude;
 			} catch (error) {
 				droppedServers.push(name);
-				diagnostics.push(`${label} skipped server "${name}": ${error instanceof Error ? error.message : String(error)}`);
+				diagnostics.push(skippedServerDiagnostic(label, name, error));
 			}
 		}
-		const contents = `${JSON.stringify({ mcpServers: internalServers }, null, 2)}\n`;
+		const contents = stagedContents(internalServers);
 		const target = stagedInternalPath(source, contents, options.stagingDirectory);
-		writeStagedInternalConfig(target, contents, options.stagingDirectory);
+		await writeStagedInternalConfig(fs, target, contents, options.stagingDirectory, context);
 		return {
 			configSource: {
 				path: target,
 				format: "internal",
-				cacheKey: createHash("sha256").update("agent-plugin-v1\0").update(source.sourceId).update("\0").update(source.contentDigest).update("\0").update(configPath).update("\0").update(contents).digest("hex")
+				cacheKey: stagedCacheKey(source, configPath, contents)
 			},
 			claudeConfig: { mcpServers: claudeServers },
 			serverNames: Object.keys(internalServers),
@@ -309,10 +487,10 @@ function normalizeAgentPluginMcpSource(source, options) {
 			diagnostics
 		};
 	} catch (error) {
-		return emptyResult(`${label} was disabled: ${error instanceof Error ? error.message : String(error)}`);
+		return disabledResult(label, error);
 	}
 }
 //#endregion
-export { normalizeAgentPluginMcpSource };
+export { normalizeAgentPluginMcpSource, normalizeAgentPluginMcpSourceAsync };
 
 //# sourceMappingURL=agentPluginMcp.mjs.map