@xopcai/xopc 0.0.396 → 0.0.398

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,20 @@ export declare function agentPluginInventoryRow(plugin: InstalledAgentPlugin): {
     version: string;
     description: string;
     source: string;
+    localizations: {
+        [k: string]: {
+            description?: string;
+            displayName: 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 +119,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 +208,20 @@ export declare function listAgentPluginInventory(): {
     version: string;
     description: string;
     source: string;
+    localizations: {
+        [k: string]: {
+            description?: string;
+            displayName: 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,36 @@
+import { pluginAuthorizations } from "./setup-contract.js";
 import { pluginServerId } from "./validation.js";
 import { AgentPluginStore } from "./store.js";
+import { pluginBranding, pluginLocalizations } 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" || !!value.issues?.length));
 	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",
+		localizations: pluginLocalizations(plugin.manifest),
+		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 +41,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;

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

@@ -0,0 +1,112 @@
+import { createPluginSourceFetch } from "./source-http-fetch.js";
+import { containedPath } from "./validation.js";
+import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/extensions/agent-plugins/resources.ts
+const resourceVariant = z.strictObject({
+	url: z.string().url(),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/),
+	maxBytes: z.number().int().positive().max(50 * 1024 * 1024).default(50 * 1024 * 1024),
+	executable: z.boolean().default(false),
+	platform: z.enum([
+		"darwin",
+		"linux",
+		"win32"
+	]).optional(),
+	arch: z.enum(["arm64", "x64"]).optional()
+});
+const resourceId = z.string().min(1).max(64).regex(/^[a-z][a-z0-9]*(?:[-.][a-z0-9]+)*$/);
+const resourcesSchema = z.array(z.union([resourceVariant.extend({ id: resourceId }).strict(), z.strictObject({
+	id: resourceId,
+	variants: z.array(resourceVariant).min(1).max(6)
+})])).max(20);
+function pluginResources(plugin) {
+	const extension = plugin.manifest.extensions?.["ai.xopc"];
+	if (extension?.setup?.version !== void 0 && extension.setup.version !== 1) throw new Error("Unsupported plugin setup protocol version");
+	const ids = /* @__PURE__ */ new Set();
+	return resourcesSchema.parse(extension?.setup?.resources ?? []).map((resource) => {
+		if (ids.has(resource.id)) throw new Error("Duplicate plugin resource");
+		ids.add(resource.id);
+		if (!("variants" in resource)) return resource;
+		const matches = resource.variants.filter((value) => (!value.platform || value.platform === process.platform) && (!value.arch || value.arch === process.arch));
+		if (matches.length !== 1) throw new Error(`Expected one resource variant for this platform: ${resource.id}`);
+		return {
+			...matches[0],
+			id: resource.id
+		};
+	});
+}
+function verified(path, sha256, maxBytes) {
+	if (!existsSync(path)) return;
+	const stat = statSync(path);
+	if (!stat.isFile() || stat.size > maxBytes) return;
+	const data = readFileSync(path);
+	return createHash("sha256").update(data).digest("hex") === sha256 ? data : void 0;
+}
+function atomicFile(path, data, mode) {
+	mkdirSync(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	const pending = `${path}.${randomUUID()}.tmp`;
+	try {
+		writeFileSync(pending, data, {
+			mode,
+			flag: "wx"
+		});
+		renameSync(pending, path);
+	} finally {
+		rmSync(pending, { force: true });
+	}
+}
+/** Download pinned files; execute them only later through an explicitly reviewed MCP process. */
+async function preparePluginResources(store, plugin, signal) {
+	const dataRoot = store.dataDir(plugin.id), cacheRoot = join(store.stateDir, "plugin-resource-cache");
+	for (const resource of pluginResources(plugin)) {
+		signal.throwIfAborted();
+		if (resource.platform && resource.platform !== process.platform || resource.arch && resource.arch !== process.arch) throw new Error(`Resource is unavailable for this platform: ${resource.id}`);
+		const target = containedPath(dataRoot, join(dataRoot, "resources", plugin.receipt.revision, resource.id));
+		if (verified(target, resource.sha256, resource.maxBytes) && (!resource.executable || (statSync(target).mode & 73) !== 0)) continue;
+		const cached = containedPath(cacheRoot, join(cacheRoot, resource.sha256));
+		let data = verified(cached, resource.sha256, resource.maxBytes);
+		if (!data) {
+			const url = new URL(resource.url);
+			const response = await createPluginSourceFetch(url, {})(url, { signal: AbortSignal.any([signal, AbortSignal.timeout(6e4)]) });
+			if (!response.ok || !response.body) throw new Error(`Resource download failed: ${resource.id}`);
+			const chunks = [];
+			let bytes = 0;
+			const reader = response.body.getReader();
+			try {
+				for (;;) {
+					const part = await reader.read();
+					if (part.done) break;
+					bytes += part.value.length;
+					if (bytes > resource.maxBytes) throw new Error("Resource exceeds size limit");
+					chunks.push(part.value);
+				}
+			} finally {
+				await reader.cancel();
+			}
+			data = Buffer.concat(chunks);
+			if (createHash("sha256").update(data).digest("hex") !== resource.sha256) throw new Error(`Resource integrity failed: ${resource.id}`);
+		}
+		signal.throwIfAborted();
+		const content = data;
+		store.withRevision(plugin.id, plugin.receipt.revision, () => {
+			atomicFile(cached, content, 384);
+			atomicFile(containedPath(dataRoot, target), content, resource.executable ? 448 : 384);
+		});
+	}
+}
+/** Derive ownership from retained revisions, including rollback and staged packages. */
+function prunePluginResourceCache(store) {
+	const cacheRoot = join(store.stateDir, "plugin-resource-cache");
+	if (!existsSync(cacheRoot)) return;
+	const referenced = /* @__PURE__ */ new Set();
+	for (const plugin of store.list()) for (const revision of store.history(plugin.id)) if (existsSync(revision.rootDir)) for (const hash of revision.receipt.resourceHashes ?? []) referenced.add(hash);
+	for (const name of readdirSync(cacheRoot)) if (/^[a-f0-9]{64}$/.test(name) && !referenced.has(name)) rmSync(join(cacheRoot, name), { force: true });
+}
+//#endregion
+export { pluginResources, preparePluginResources, prunePluginResourceCache };

package/dist/src/extensions/agent-plugins/setup-contract.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+export declare const setupCommandSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const pluginAuthorizationSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    servers: z.ZodArray<z.ZodString>;
+    methods: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        server: z.ZodString;
+        id: z.ZodString;
+        title: z.ZodString;
+        instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        helpUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"form">;
+        fields: z.ZodArray<z.ZodString>;
+        id: z.ZodString;
+        title: z.ZodString;
+        instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        helpUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"cli">;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        login: z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        check: z.ZodObject<{
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            cwd: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        id: z.ZodString;
+        title: z.ZodString;
+        instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        helpUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>>;
+export type PluginAuthorization = z.infer<typeof pluginAuthorizationSchema>[number];
+export type SetupCommand = z.infer<typeof setupCommandSchema>;
+export declare function pluginAuthorizations(manifest: {
+    extensions?: Record<string, unknown>;
+}): PluginAuthorization[];
+export declare function safeAuthorizationUrl(value: string): string;
+export declare const pluginPermissionIssueSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    instructions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    method: z.ZodOptional<z.ZodString>;
+    helpUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PluginPermissionIssue = z.infer<typeof pluginPermissionIssueSchema>;
+export declare function parsePluginAuthorizationCheck(output: string, methodIds: string[]): {
+    authenticated: boolean;
+    issues: {
+        id: string;
+        title: string;
+        scopes: string[];
+        instructions: string[];
+        method?: string;
+        helpUrl?: string;
+    }[];
+};