@xopcai/xopc 0.0.395 → 0.0.397

package/dist/src/extensions/agent-plugins/formats.js

@@ -0,0 +1,208 @@
+import { basename, join } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+//#region src/extensions/agent-plugins/formats.ts
+const PLUGIN_MANIFEST_PATHS = [
+	"plugin.json",
+	".codex-plugin/plugin.json",
+	".claude-plugin/plugin.json"
+];
+/** Interpret each dialect before applying the common package and execution checks. */
+function readPluginLayout(root, read, safe, importManifest) {
+	const has = (path) => existsSync(join(root, path));
+	const json = (path) => {
+		const value = JSON.parse(read(join(root, path)));
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Expected an object: ${path}`);
+		return value;
+	};
+	const path = PLUGIN_MANIFEST_PATHS.find(has);
+	if (!path && !importManifest) throw new Error("No supported plugin manifest found");
+	const dialect = path === "plugin.json" ? "portable" : path?.startsWith(".codex") ? "codex" : "claude";
+	const raw = path ? json(path) : importManifest;
+	const compatibility = [];
+	if (dialect !== "portable" && has(".codex-plugin/plugin.json") && has(".claude-plugin/plugin.json")) compatibility.push({
+		component: "manifest:claude",
+		support: "unsupported",
+		message: "Codex dialect selected; the separate Claude manifest is not applied."
+	});
+	const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	const overlay = dialect === "portable" ? object(object(raw.extensions)["com.openai"] ?? (has(".codex-plugin/plugin.json") ? json(".codex-plugin/plugin.json") : {})) : raw;
+	const manifest = dialect === "portable" ? raw : {
+		$schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+		...Object.fromEntries([
+			"name",
+			"version",
+			"description",
+			"homepage",
+			"repository",
+			"license",
+			"keywords",
+			"extensions"
+		].filter((key) => raw[key] !== void 0).map((key) => [key, raw[key]])),
+		...raw.author ? { author: typeof raw.author === "string" ? { name: raw.author } : raw.author } : {}
+	};
+	const paths = (value, component) => {
+		if (value === void 0) return [];
+		const values = typeof value === "string" ? [value] : Array.isArray(value) ? value : [];
+		if (!values.length || values.some((v) => typeof v !== "string" || !v.startsWith("./"))) {
+			compatibility.push({
+				component,
+				support: "invalid",
+				message: "Expected package-relative paths beginning with ./"
+			});
+			return [];
+		}
+		return values.map((v) => safe(join(root, v)));
+	};
+	const guarded = (component, fn, fallback) => {
+		try {
+			return fn();
+		} catch (error) {
+			compatibility.push({
+				component,
+				support: "invalid",
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return fallback;
+		}
+	};
+	const defaults = has("skills") ? guarded("skills", () => [safe(join(root, "skills"))], []) : [];
+	const declared = paths(overlay.skills, "skills");
+	const skillRoots = [...new Set(dialect === "portable" ? defaults : dialect === "claude" ? [...defaults, ...declared] : overlay.skills === void 0 ? defaults : declared)];
+	const mcpConfigs = [];
+	if (dialect === "portable" && has("mcp.json")) {
+		const config = guarded("mcp", () => json("mcp.json"), void 0);
+		if (config) mcpConfigs.push(config);
+	}
+	const legacyDefault = has(".mcp.json");
+	if (dialect !== "portable" && legacyDefault && (dialect === "claude" || overlay.mcpServers === void 0)) {
+		const config = guarded("mcp", () => json(".mcp.json"), void 0);
+		if (config) mcpConfigs.push(config);
+	}
+	if (dialect !== "portable" || !has("mcp.json")) {
+		if (overlay.mcpServers !== void 0) for (const item of Array.isArray(overlay.mcpServers) ? overlay.mcpServers : [overlay.mcpServers]) if (typeof item === "string") for (const file of paths(item, "mcp")) {
+			const config = guarded("mcp", () => JSON.parse(read(file)), void 0);
+			if (config) mcpConfigs.push(config);
+		}
+		else if (item && typeof item === "object") mcpConfigs.push({ mcpServers: item });
+		else compatibility.push({
+			component: "mcp",
+			support: "invalid",
+			message: "Expected an MCP configuration object or package path."
+		});
+	}
+	for (const [key, conventional] of Object.entries({
+		apps: ".app.json",
+		hooks: "hooks/hooks.json",
+		agents: "agents",
+		commands: "commands",
+		lspServers: ".lsp.json",
+		outputStyles: "output-styles",
+		settings: "settings.json",
+		workflows: "workflows",
+		monitors: "monitors",
+		channels: "channels",
+		themes: "themes"
+	})) if (overlay[key] !== void 0 || has(conventional)) compatibility.push({
+		component: key,
+		support: key === "apps" ? "needs_adapter" : "unsupported",
+		message: key === "apps" ? "Platform application tools require a host capability adapter; accounts are not inherited." : `${key} is not executed by this compatibility version.`
+	});
+	const userConfig = Object.create(null);
+	for (const [key, value] of Object.entries(object(overlay.userConfig))) {
+		const field = object(value);
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || ![
+			"string",
+			"number",
+			"boolean"
+		].includes(String(field.type))) {
+			compatibility.push({
+				component: `config:${key}`,
+				support: "unsupported",
+				message: "Unsupported configuration field."
+			});
+			continue;
+		}
+		userConfig[key] = {
+			type: field.type,
+			title: String(field.title ?? key),
+			required: field.required === true,
+			sensitive: field.sensitive === true,
+			...[
+				"string",
+				"number",
+				"boolean"
+			].includes(typeof field.default) ? { default: field.default } : {}
+		};
+	}
+	const tasks = [object(overlay.interface).defaultPrompt].flat().filter((v) => typeof v === "string");
+	if (overlay.onboardingSkill !== void 0) compatibility.push({
+		component: "onboardingSkill",
+		support: "unsupported",
+		message: "Automatic onboarding skill execution is not supported; use the host setup flow."
+	});
+	const known = new Set([
+		"$schema",
+		"name",
+		"version",
+		"description",
+		"author",
+		"homepage",
+		"repository",
+		"license",
+		"keywords",
+		"extensions",
+		"displayName",
+		"skills",
+		"mcpServers",
+		"interface",
+		"userConfig",
+		"onboardingSkill",
+		"apps",
+		"hooks",
+		"agents",
+		"commands",
+		"lspServers",
+		"outputStyles",
+		"settings",
+		"workflows",
+		"monitors",
+		"channels",
+		"themes"
+	]);
+	for (const key of Object.keys(overlay)) if (!known.has(key)) compatibility.push({
+		component: key,
+		support: "unsupported",
+		message: "Unrecognized platform declaration."
+	});
+	return {
+		descriptorVersion: 1,
+		adapterVersion: "xopc-plugin-v1",
+		dialect,
+		manifest,
+		skillRoots,
+		mcpConfigs,
+		compatibility,
+		userConfig,
+		tasks
+	};
+}
+function collectPluginSkillFiles(root, safe) {
+	const result = [];
+	const visit = (path, depth) => {
+		const target = safe(path);
+		if (depth > 16) throw new Error("Skill directory nesting exceeds limits");
+		if (statSync(target).isFile()) {
+			if (basename(target) === "SKILL.md") result.push(target);
+			return;
+		}
+		if (existsSync(join(target, "SKILL.md"))) {
+			result.push(safe(join(target, "SKILL.md")));
+			return;
+		}
+		for (const name of readdirSync(target).sort()) visit(join(target, name), depth + 1);
+	};
+	visit(root, 0);
+	return result;
+}
+//#endregion
+export { PLUGIN_MANIFEST_PATHS, collectPluginSkillFiles, readPluginLayout };

package/dist/src/extensions/agent-plugins/inventory.d.ts

@@ -1,15 +1,79 @@
-import { type InstalledAgentPlugin } from './store.js';
-export declare function agentPluginInventoryRow(plugin: InstalledAgentPlugin): {
+import { AgentPluginStore, type InstalledAgentPlugin } from './store.js';
+export declare function agentPluginInventoryRow(plugin: InstalledAgentPlugin, store?: AgentPluginStore): {
     components: {
         skills: {
             name: string;
         }[];
         mcp: {
+            connectionAuth?: {
+                mode: "none" | "oauth" | "api-key";
+                headerName?: string;
+                prefix?: string;
+            };
             name: string;
             id: string;
             type: "stdio" | "streamable-http";
         }[];
     };
+    installationSource: string;
+    resolvedCommit: string;
+    dialect: import("./formats.js").PluginDialect;
+    verification: string;
+    compatibility: import("./formats.js").CompatibilityItem[];
+    workspacePaths: string[];
+    setup: {
+        authorizations: {
+            id: string;
+            title: string;
+            servers: string[];
+            methods: ({
+                type: "oauth";
+                server: string;
+                id: string;
+                title: string;
+                instructions: string[];
+                helpUrl?: string;
+            } | {
+                type: "form";
+                fields: string[];
+                id: string;
+                title: string;
+                instructions: string[];
+                helpUrl?: string;
+            } | {
+                type: "cli";
+                fields: string[];
+                login: {
+                    command: string;
+                    args: string[];
+                    env: Record<string, string>;
+                    cwd?: string;
+                };
+                check: {
+                    command: string;
+                    args: string[];
+                    env: Record<string, string>;
+                    cwd?: string;
+                };
+                timeoutSeconds: number;
+                id: string;
+                title: string;
+                instructions: string[];
+                helpUrl?: string;
+            })[];
+            description?: string;
+        }[];
+        userConfig: {
+            [k: string]: {
+                default: string | number | boolean;
+                type: "string" | "number" | "boolean";
+                title: string;
+                required: boolean;
+                sensitive: boolean;
+            };
+        };
+        tasks: string[];
+    };
     diagnostics: import("./validation.js").PluginDiagnostic[];
     provenance?: {
         kind: "store";
@@ -30,8 +94,14 @@ export declare function agentPluginInventoryRow(plugin: InstalledAgentPlugin): {
     version: string;
     description: string;
     source: string;
+    branding: {
+        iconUrl: string;
+        iconSha256: string;
+    };
     active: boolean;
     activationEligible: boolean;
+    installationState: string;
+    authorizationStatus: string;
     readiness: "ready" | "blocked" | "degraded" | "setup_required";
     hasUi: boolean;
     hasConfigSchema: boolean;
@@ -43,11 +113,75 @@ export declare function listAgentPluginInventory(): {
             name: string;
         }[];
         mcp: {
+            connectionAuth?: {
+                mode: "none" | "oauth" | "api-key";
+                headerName?: string;
+                prefix?: string;
+            };
             name: string;
             id: string;
             type: "stdio" | "streamable-http";
         }[];
     };
+    installationSource: string;
+    resolvedCommit: string;
+    dialect: import("./formats.js").PluginDialect;
+    verification: string;
+    compatibility: import("./formats.js").CompatibilityItem[];
+    workspacePaths: string[];
+    setup: {
+        authorizations: {
+            id: string;
+            title: string;
+            servers: string[];
+            methods: ({
+                type: "oauth";
+                server: string;
+                id: string;
+                title: string;
+                instructions: string[];
+                helpUrl?: string;
+            } | {
+                type: "form";
+                fields: string[];
+                id: string;
+                title: string;
+                instructions: string[];
+                helpUrl?: string;
+            } | {
+                type: "cli";
+                fields: string[];
+                login: {
+                    command: string;
+                    args: string[];
+                    env: Record<string, string>;
+                    cwd?: string;
+                };
+                check: {
+                    command: string;
+                    args: string[];
+                    env: Record<string, string>;
+                    cwd?: string;
+                };
+                timeoutSeconds: number;
+                id: string;
+                title: string;
+                instructions: string[];
+                helpUrl?: string;
+            })[];
+            description?: string;
+        }[];
+        userConfig: {
+            [k: string]: {
+                default: string | number | boolean;
+                type: "string" | "number" | "boolean";
+                title: string;
+                required: boolean;
+                sensitive: boolean;
+            };
+        };
+        tasks: string[];
+    };
     diagnostics: import("./validation.js").PluginDiagnostic[];
     provenance?: {
         kind: "store";
@@ -68,8 +202,14 @@ export declare function listAgentPluginInventory(): {
     version: string;
     description: string;
     source: string;
+    branding: {
+        iconUrl: string;
+        iconSha256: string;
+    };
     active: boolean;
     activationEligible: boolean;
+    installationState: string;
+    authorizationStatus: string;
     readiness: "ready" | "blocked" | "degraded" | "setup_required";
     hasUi: boolean;
     hasConfigSchema: boolean;

package/dist/src/extensions/agent-plugins/inventory.js

@@ -1,17 +1,35 @@
+import { pluginAuthorizations } from "./setup-contract.js";
 import { pluginServerId } from "./validation.js";
 import { AgentPluginStore } from "./store.js";
+import { pluginBranding } from "./branding.js";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 //#region src/extensions/agent-plugins/inventory.ts
-function agentPluginInventoryRow(plugin) {
+function agentPluginInventoryRow(plugin, store = new AgentPluginStore()) {
+	const setupPath = join(store.stateDir, "plugin-setup", `${plugin.id}.json`);
+	let saved;
+	try {
+		saved = existsSync(setupPath) ? JSON.parse(readFileSync(setupPath, "utf8")) : void 0;
+	} catch {}
+	const job = saved?.packageRevision === plugin.receipt.revision ? saved : void 0;
+	let authorizations = [];
+	try {
+		authorizations = pluginAuthorizations(plugin.manifest);
+	} catch {}
+	const needsAuthorization = !!job && ((job.missingConfig?.length ?? 0) > 0 || job.connections?.some((value) => value.state !== "connected") || job.authorizations?.some((value) => value.state !== "connected"));
 	return {
 		id: `plugin:${plugin.id}`,
 		pluginId: plugin.id,
 		format: plugin.format,
 		name: plugin.manifest.name,
-		version: plugin.manifest.version,
+		version: plugin.manifest.version ?? plugin.receipt.provenance?.version,
 		description: plugin.manifest.description,
 		source: "agent-plugin",
-		active: plugin.receipt.enabled && plugin.readiness !== "blocked",
+		branding: pluginBranding(plugin.rootDir, plugin.manifest),
+		active: plugin.receipt.enabled && plugin.readiness !== "blocked" && plugin.readiness !== "setup_required",
 		activationEligible: plugin.receipt.enabled,
+		installationState: job?.installed || job?.state === "completed" ? "installed" : job ? "preparing" : "installed",
+		authorizationStatus: needsAuthorization ? "required" : job?.connections?.length || authorizations.length ? "connected" : "not_required",
 		readiness: plugin.readiness,
 		hasUi: false,
 		hasConfigSchema: false,
@@ -22,14 +40,30 @@ function agentPluginInventoryRow(plugin) {
 			mcp: Object.entries(plugin.servers).map(([name, server]) => ({
 				name,
 				id: pluginServerId(plugin.id, name),
-				type: server.type
+				type: server.type,
+				...server.type !== "stdio" ? { connectionAuth: server.connectionAuth } : {}
 			}))
 		},
+		installationSource: plugin.receipt.source,
+		resolvedCommit: plugin.receipt.resolvedCommit,
+		dialect: plugin.layout?.dialect ?? "portable",
+		verification: "unverified",
+		compatibility: plugin.layout?.compatibility ?? [],
+		workspacePaths: plugin.receipt.workspacePaths ?? null,
+		setup: {
+			authorizations,
+			userConfig: Object.fromEntries(Object.entries(plugin.layout?.userConfig ?? {}).map(([key, field]) => [key, {
+				...field,
+				default: field.sensitive ? void 0 : field.default
+			}])),
+			tasks: plugin.layout?.tasks ?? []
+		},
 		diagnostics: plugin.diagnostics
 	};
 }
 function listAgentPluginInventory() {
-	return new AgentPluginStore().list().map(agentPluginInventoryRow);
+	const store = new AgentPluginStore();
+	return store.list().map((plugin) => agentPluginInventoryRow(plugin, store));
 }
 //#endregion
 export { agentPluginInventoryRow, listAgentPluginInventory };

package/dist/src/extensions/agent-plugins/mcp-adapter.d.ts

@@ -1,3 +1,4 @@
 import { AgentPluginStore, type InstalledAgentPlugin } from './store.js';
 import { type PluginDiagnostic } from './validation.js';
-export declare function materializePluginServers(plugin: InstalledAgentPlugin, store?: AgentPluginStore, diagnostics?: PluginDiagnostic[]): Record<string, Record<string, unknown>>;
+export declare function pluginOAuthCredentialId(pluginId: string, revision: string, serverName: string): string;
+export declare function materializePluginServers(plugin: InstalledAgentPlugin, store?: AgentPluginStore, diagnostics?: PluginDiagnostic[], setup?: boolean): Record<string, Record<string, unknown>>;

package/dist/src/extensions/agent-plugins/mcp-adapter.js

@@ -1,13 +1,37 @@
 import { containedPath, expandPluginVariables, pluginServerId, resolvePluginCwd } from "./validation.js";
 import { AgentPluginStore } from "./store.js";
 import { applyPluginAuthBinding, readPluginAuthBinding } from "./auth.js";
-import { resolve } from "node:path";
+import { expandUserConfig, readPluginUserConfig } from "./user-config.js";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 //#region src/extensions/agent-plugins/mcp-adapter.ts
-function materializePluginServers(plugin, store = new AgentPluginStore(), diagnostics = []) {
+function pluginOAuthCredentialId(pluginId, revision, serverName) {
+	return `mcp_draft_${createHash("sha256").update(JSON.stringify([
+		"plugin",
+		pluginId,
+		revision,
+		serverName
+	])).digest("hex").slice(0, 32)}`;
+}
+function materializePluginServers(plugin, store = new AgentPluginStore(), diagnostics = [], setup = false) {
 	const root = plugin.rootDir;
 	const data = store.dataDir(plugin.id);
+	mkdirSync(data, {
+		recursive: true,
+		mode: 448
+	});
+	const values = {
+		...Object.fromEntries(Object.entries(plugin.layout?.userConfig ?? {}).filter(([, field]) => field.default !== void 0).map(([key, field]) => [key, field.default])),
+		...readPluginUserConfig(store, plugin.id, plugin.receipt.revision)
+	};
+	const expand = (value) => expandUserConfig(expandPluginVariables(value.replace(/\$\{PLUGIN_ACCOUNTS\}/g, join(data, "accounts", plugin.receipt.revision)).replace(/\$\{PLUGIN_RESOURCES\}/g, join(data, "resources", plugin.receipt.revision)), root, data), values);
 	const servers = Object.create(null);
+	const setupPath = join(store.stateDir, "plugin-setup", `${plugin.id}.json`);
+	const job = !setup && existsSync(setupPath) ? JSON.parse(readFileSync(setupPath, "utf8")) : void 0;
 	for (const [name, server] of Object.entries(plugin.servers)) try {
+		if (job?.packageRevision === plugin.receipt.revision && (job.state !== "completed" && !job.installed || job.connections.find((c) => c.name === name)?.state !== "connected")) continue;
 		const origin = {
 			id: plugin.id,
 			serverName: name,
@@ -17,20 +41,30 @@ function materializePluginServers(plugin, store = new AgentPluginStore(), diagno
 		};
 		const raw = server.type !== "stdio" ? {
 			...server,
+			...plugin.receipt.credentialScope === "revision" ? { xopcOAuthCredentialId: pluginOAuthCredentialId(plugin.id, plugin.receipt.revision, name) } : {},
+			...server.headers ? { headers: Object.fromEntries(Object.entries(server.headers).map(([key, value]) => [key, expand(value)])) } : {},
 			xopcPlugin: origin
 		} : {
 			type: "stdio",
 			xopcPlugin: origin,
-			command: server.command.startsWith("./") ? containedPath(root, resolve(root, server.command)) : server.command,
-			args: server.args?.map((value) => expandPluginVariables(value, root, data)),
+			command: server.command.startsWith("./") ? containedPath(root, resolve(root, server.command)) : server.command.startsWith("${PLUGIN_RESOURCES}/") ? containedPath(data, join(data, "resources", plugin.receipt.revision, server.command.slice(20))) : server.command,
+			args: server.args?.map((value) => {
+				const expanded = expand(value);
+				if (typeof expanded !== "string") throw new Error("Sensitive arguments are not supported; use environment variables");
+				return expanded;
+			}),
 			env: {
-				...Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expandPluginVariables(value, root, data)])),
+				...Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(value)])),
+				PLUGIN_HOST_HOME: homedir(),
 				PLUGIN_ROOT: root,
-				PLUGIN_DATA: data
+				PLUGIN_DATA: data,
+				PLUGIN_RESOURCES: join(data, "resources", plugin.receipt.revision),
+				CLAUDE_PLUGIN_ROOT: root,
+				CLAUDE_PLUGIN_DATA: data
 			},
 			cwd: resolvePluginCwd(server.cwd, root, data)
 		};
-		servers[pluginServerId(plugin.id, name)] = applyPluginAuthBinding(raw, readPluginAuthBinding(store, plugin.id, name, server));
+		servers[pluginServerId(plugin.id, name)] = applyPluginAuthBinding(raw, readPluginAuthBinding(store, plugin.id, name, server, plugin.receipt.revision));
 	} catch (error) {
 		diagnostics.push({
 			component: `mcp:${name}`,
@@ -40,4 +74,4 @@ function materializePluginServers(plugin, store = new AgentPluginStore(), diagno
 	return servers;
 }
 //#endregion
-export { materializePluginServers };
+export { materializePluginServers, pluginOAuthCredentialId };

package/dist/src/extensions/agent-plugins/mcp-format.d.ts

@@ -0,0 +1,2 @@
+/** Only map authentication settings that native pi can represent without semantic loss. */
+export declare function normalizePluginMcpServer(input: unknown, legacy: boolean, warn: (message: string) => void): unknown;

package/dist/src/extensions/agent-plugins/mcp-format.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+//#region src/extensions/agent-plugins/mcp-format.ts
+const oauthClient = z.discriminatedUnion("mode", [z.strictObject({
+	mode: z.literal("provided"),
+	clientId: z.string().min(1),
+	tokenEndpointAuthMethod: z.literal("none").optional()
+}), z.strictObject({ mode: z.enum(["dcr", "cimd"]) })]);
+const scope = z.string().trim().min(1);
+const authSchema = z.discriminatedUnion("type", [
+	z.strictObject({
+		type: z.enum(["oauth", "mixed"]),
+		client: oauthClient.optional(),
+		baseScopes: z.array(scope).optional(),
+		defaultScopes: z.array(scope).optional()
+	}),
+	z.strictObject({ type: z.literal("none") }),
+	z.strictObject({
+		type: z.literal("api_key"),
+		headerScheme: z.enum([
+			"bearer",
+			"basic",
+			"custom_header"
+		]),
+		headerName: z.string().optional()
+	})
+]);
+/** Only map authentication settings that native pi can represent without semantic loss. */
+function normalizePluginMcpServer(input, legacy, warn) {
+	const value = { ...z.record(z.string(), z.unknown()).parse(input) };
+	const extensions = value.extensions;
+	if (extensions !== void 0) {
+		const ext = z.record(z.string(), z.unknown()).parse(extensions);
+		for (const key of Object.keys(ext)) if (key !== "com.openai") warn(`Unrecognized MCP extension: ${key}`);
+		const openai = ext["com.openai"] === void 0 ? {} : z.record(z.string(), z.unknown()).parse(ext["com.openai"]);
+		for (const key of Object.keys(openai)) if (key !== "auth") warn(`Unrecognized OpenAI MCP declaration: ${key}`);
+		if (openai.auth !== void 0) {
+			const auth = authSchema.parse(openai.auth);
+			if (auth.type === "oauth" || auth.type === "mixed") {
+				if (auth.baseScopes?.length && auth.defaultScopes === void 0) throw new Error("OAuth base scopes with discovered defaults require an adapter");
+				value.oauth = {
+					...auth.client?.mode === "provided" ? { clientId: auth.client.clientId } : auth.client ? { clientRegistration: auth.client.mode } : {},
+					...auth.defaultScopes !== void 0 ? { scope: [...new Set([...auth.baseScopes ?? [], ...auth.defaultScopes])].join(" ") } : {}
+				};
+				value.connectionAuth = { mode: "oauth" };
+			} else if (auth.type === "api_key") {
+				if (auth.headerScheme === "custom_header" && !auth.headerName || auth.headerScheme !== "custom_header" && auth.headerName) throw new Error("Invalid API key header declaration");
+				value.connectionAuth = {
+					mode: "api-key",
+					headerName: auth.headerName ?? "Authorization",
+					prefix: auth.headerScheme === "bearer" ? "Bearer " : auth.headerScheme === "basic" ? "Basic " : ""
+				};
+			} else value.connectionAuth = { mode: "none" };
+		}
+		delete value.extensions;
+	}
+	if (legacy) {
+		const allowed = new Set([
+			"type",
+			"command",
+			"args",
+			"env",
+			"cwd",
+			"url",
+			"headers",
+			"oauth_resource",
+			"oauth",
+			"connectionAuth"
+		]);
+		for (const key of Object.keys(value)) if (!allowed.has(key)) {
+			warn(`Unsupported MCP field: ${key}`);
+			delete value[key];
+		}
+		if (value.oauth_resource !== void 0 && value.oauth_resource !== value.url) throw new Error("A distinct OAuth resource requires an adapter");
+		delete value.oauth_resource;
+		value.type = value.type === "http" ? "streamable-http" : value.type ?? (value.command ? "stdio" : "streamable-http");
+		if (typeof value.command === "string") value.command = value.command.replace(/^\$\{(?:CLAUDE_)?PLUGIN_ROOT\}\//, "./");
+		if (typeof value.cwd === "string") value.cwd = value.cwd.replace(/^\$\{CLAUDE_PLUGIN_(ROOT|DATA)\}/, "${PLUGIN_$1}");
+	}
+	return value;
+}
+//#endregion
+export { normalizePluginMcpServer };

package/dist/src/extensions/agent-plugins/resources.d.ts

@@ -0,0 +1,14 @@
+import type { AgentPluginStore, InstalledAgentPlugin } from './store.js';
+export declare function pluginResources(plugin: Pick<InstalledAgentPlugin, 'manifest'>): {
+    url: string;
+    sha256: string;
+    maxBytes: number;
+    executable: boolean;
+    id: string;
+    platform?: "darwin" | "linux" | "win32";
+    arch?: "arm64" | "x64";
+}[];
+/** Download pinned files; execute them only later through an explicitly reviewed MCP process. */
+export declare function preparePluginResources(store: AgentPluginStore, plugin: InstalledAgentPlugin, signal: AbortSignal): Promise<void>;
+/** Derive ownership from retained revisions, including rollback and staged packages. */
+export declare function prunePluginResourceCache(store: AgentPluginStore): void;