@xopcai/xopc 0.0.395 → 0.0.397

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

@@ -14,4 +14,4 @@ export interface AgentPluginSourceProvenance {
 export declare function isAgentPluginArchive(buffer: Buffer): boolean;
 export declare function withAgentPluginArchive<T>(buffer: Buffer, fn: (local: string) => T): T;
 /** Resolve remote artifacts only for explicit inspect/install requests, never during discovery. */
-export declare function withAgentPluginSource<T>(source: string, config: Config | undefined, fn: (local: string, provenance?: AgentPluginSourceProvenance) => T): Promise<T>;
+export declare function withAgentPluginSource<T>(source: string, config: Config | undefined, fn: (local: string, provenance?: AgentPluginSourceProvenance, resolvedCommit?: string, importManifest?: Record<string, unknown>) => T, depth?: number): Promise<T>;

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

@@ -1,4 +1,6 @@
 import { createPluginSourceFetch } from "./source-http-fetch.js";
+import { PLUGIN_MANIFEST_PATHS } from "./formats.js";
+import { PluginSourceRedirect, isGitPluginSource, withCatalogSource } from "./source-catalog.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -14,11 +16,11 @@ function isAgentPluginArchive(buffer) {
 		return Boolean(JSON.parse(entry.getData().toString("utf8"))?.xopc?.extension);
 	};
 	if (paths.includes("xopc.extension.json")) return false;
-	if (paths.includes("plugin.json")) return !nativeMetadata("package.json");
+	if (PLUGIN_MANIFEST_PATHS.some((path) => paths.includes(path))) return !nativeMetadata("package.json");
 	const first = new Set(paths.map((path) => path.split("/")[0]));
 	if (first.size !== 1) return false;
 	const root = [...first][0];
-	return paths.includes(`${root}/plugin.json`) && !paths.includes(`${root}/xopc.extension.json`) && !nativeMetadata(`${root}/package.json`);
+	return PLUGIN_MANIFEST_PATHS.some((path) => paths.includes(`${root}/${path}`)) && !paths.includes(`${root}/xopc.extension.json`) && !nativeMetadata(`${root}/package.json`);
 }
 function withAgentPluginArchive(buffer, fn) {
 	const dir = mkdtempSync(join(tmpdir(), "xopc-plugin-download-"));
@@ -34,7 +36,14 @@ function withAgentPluginArchive(buffer, fn) {
 	}
 }
 /** Resolve remote artifacts only for explicit inspect/install requests, never during discovery. */
-async function withAgentPluginSource(source, config, fn) {
+async function withAgentPluginSource(source, config, fn, depth = 0) {
+	if (depth > 4) throw new Error("Marketplace source nesting exceeds limits");
+	if (isGitPluginSource(source) || !source.startsWith("https://") && !source.startsWith("store:") && (!source.toLowerCase().endsWith(".zip") || source.includes("#"))) try {
+		return await withCatalogSource(source, (local, metadata) => fn(local, void 0, metadata.commit, metadata.importManifest));
+	} catch (error) {
+		if (error instanceof PluginSourceRedirect) return withAgentPluginSource(error.source, config, fn, depth + 1);
+		throw error;
+	}
 	if (!source.startsWith("https://") && !source.startsWith("store:")) return fn(source);
 	let buffer;
 	let provenance;

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

@@ -31,6 +31,14 @@ declare const receiptSchema: z.ZodObject<{
             "local-exec": "local-exec";
         }>>;
     }, z.core.$strict>>;
+    adapterVersion: z.ZodOptional<z.ZodString>;
+    credentialScope: z.ZodOptional<z.ZodLiteral<"revision">>;
+    workspacePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resourceHashes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    oauthServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    importManifest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    resolvedCommit: z.ZodOptional<z.ZodString>;
+    declaredName: z.ZodOptional<z.ZodString>;
     previous: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         revision: z.ZodString;
@@ -61,6 +69,14 @@ declare const receiptSchema: z.ZodObject<{
                 "local-exec": "local-exec";
             }>>;
         }, z.core.$strict>>;
+        adapterVersion: z.ZodOptional<z.ZodString>;
+        credentialScope: z.ZodOptional<z.ZodLiteral<"revision">>;
+        workspacePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        resourceHashes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        oauthServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        importManifest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        resolvedCommit: z.ZodOptional<z.ZodString>;
+        declaredName: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PluginReceipt = z.infer<typeof receiptSchema>;
@@ -71,6 +87,7 @@ export interface InstalledAgentPlugin extends PluginInspection {
     readiness: 'ready' | 'setup_required' | 'degraded' | 'blocked';
 }
 export interface PluginInstallPlan extends PluginInspection {
+    installId: string;
     integrity: string;
     reviewHash: string;
     addedCapabilities: string[];
@@ -88,9 +105,11 @@ export declare class AgentPluginStore {
     private write;
     private mutate;
     get(id: string): InstalledAgentPlugin | undefined;
+    private fromReceipt;
     list(): InstalledAgentPlugin[];
-    active(): InstalledAgentPlugin[];
-    inspect(source: string): PluginInstallPlan;
+    active(_agentId?: string, workspaceDir?: string): InstalledAgentPlugin[];
+    private setupReady;
+    inspect(source: string, sourceLabel?: string, importManifest?: Record<string, unknown>): PluginInstallPlan;
     private plan;
     install(source: string, options?: {
         reviewHash?: string;
@@ -98,8 +117,20 @@ export declare class AgentPluginStore {
         expectedId?: string;
         sourceLabel?: string;
         provenance?: AgentPluginSourceProvenance;
+        stage?: boolean;
+        resolvedCommit?: string;
+        importManifest?: Record<string, unknown>;
     }): InstalledAgentPlugin;
+    history(id: string): InstalledAgentPlugin[];
+    /** Publish synchronous resource changes while the package lifecycle lock is held. */
+    withRevision<T>(id: string, revision: string, fn: () => T): T;
+    private pendingPath;
+    pendingReceipt(id: string): PluginReceipt | undefined;
+    pending(id: string): InstalledAgentPlugin | undefined;
+    commitPending(id: string): void;
+    discardPending(id: string): void;
     setEnabled(id: string, enabled: boolean): InstalledAgentPlugin;
+    setWorkspaceScope(id: string, workspacePaths?: string[] | null): InstalledAgentPlugin;
     rollback(id: string): InstalledAgentPlugin;
     remove(id: string, removeData?: boolean): void;
     private withSource;

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

@@ -3,10 +3,13 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { computeExtensionDirectoryIntegrity } from "../lockfile.js";
+import { prunePluginResourceCache } from "./resources.js";
+import { PLUGIN_MANIFEST_PATHS } from "./formats.js";
 import { containedPath, inspectAgentPlugin, pluginName } from "./validation.js";
+import { pluginSourceKey } from "./source-catalog.js";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
 import AdmZip from "adm-zip";
@@ -39,7 +42,15 @@ const receiptFields = z.object({
 	enabled: z.boolean(),
 	integrity: z.string(),
 	capabilities: z.array(z.string()),
-	provenance: provenanceSchema.optional()
+	provenance: provenanceSchema.optional(),
+	adapterVersion: z.string().min(1).max(64).optional(),
+	credentialScope: z.literal("revision").optional(),
+	workspacePaths: z.array(z.string()).max(100).optional(),
+	resourceHashes: z.array(z.string()).optional(),
+	oauthServers: z.record(z.string(), z.string()).optional(),
+	importManifest: z.record(z.string(), z.unknown()).optional(),
+	resolvedCommit: z.string().regex(/^[a-f0-9]{40,64}$/).optional(),
+	declaredName: pluginName.optional()
 });
 const receiptSchema = receiptFields.extend({ previous: receiptFields.optional() });
 const log = createLogger("AgentPlugins");
@@ -54,7 +65,8 @@ var AgentPluginStore = class {
 		if (!existsSync(this.receiptsDir())) return "";
 		return readdirSync(this.receiptsDir()).filter((name) => name.endsWith(".json")).sort().map((name) => {
 			try {
-				return `${name}:${statSync(join(this.receiptsDir(), name)).mtimeMs}`;
+				const setupPath = join(this.stateDir, "plugin-setup", name);
+				return createHash("sha256").update(readFileSync(join(this.receiptsDir(), name))).update(existsSync(setupPath) ? readFileSync(setupPath) : "").digest("hex");
 			} catch {
 				return "";
 			}
@@ -93,17 +105,29 @@ var AgentPluginStore = class {
 	}
 	get(id) {
 		const receipt = this.receipt(id);
-		if (!receipt) return void 0;
+		return receipt ? this.fromReceipt(receipt) : void 0;
+	}
+	fromReceipt(receipt) {
+		const id = receipt.id;
 		const rootDir = this.revisionDir(id, receipt.revision);
 		try {
 			validatePackageTree(rootDir);
-			const inspection = inspectAgentPlugin(rootDir, this.dataDir(id));
+			const inspection = inspectAgentPlugin(rootDir, this.dataDir(id), receipt.importManifest);
 			const valid = computeExtensionDirectoryIntegrity(rootDir) === receipt.integrity;
 			if (!valid) inspection.diagnostics.push({
 				component: "package",
 				message: "Installed files differ from the reviewed package"
 			});
-			const readiness = !valid ? "blocked" : inspection.diagnostics.length ? "degraded" : "ready";
+			const previouslyReviewed = new Set(receipt.capabilities);
+			const adapterChanged = receipt.adapterVersion !== void 0 && receipt.adapterVersion !== inspection.layout?.adapterVersion;
+			const capabilityChanged = inspection.capabilities.some((capability) => !previouslyReviewed.has(capability) && !(receipt.adapterVersion === void 0 && previouslyReviewed.has(capability.replace(/:\{\}:\{\}$/, ""))));
+			if (adapterChanged || capabilityChanged) inspection.diagnostics.push({
+				component: "review",
+				message: "Adapter interpretation changed capabilities. Inspect and review this package again."
+			});
+			const setupPath = join(this.stateDir, "plugin-setup", `${id}.json`);
+			const setup = existsSync(setupPath) ? JSON.parse(readFileSync(setupPath, "utf8")) : void 0;
+			const readiness = !valid || adapterChanged || capabilityChanged || inspection.layout?.compatibility.some((item) => item.component === "hooks" || item.component === "authorizations" && item.support === "invalid") ? "blocked" : setup?.packageRevision === receipt.revision && setup.state !== "completed" && !setup.installed ? "setup_required" : inspection.diagnostics.length || setup?.packageRevision === receipt.revision && (setup.partial || setup.installed && (setup.missingConfig?.length || setup.connections?.some((value) => value.state !== "connected") || setup.authorizations?.some((value) => value.state !== "connected"))) ? "degraded" : "ready";
 			return {
 				...inspection,
 				id,
@@ -149,23 +173,43 @@ var AgentPluginStore = class {
 			}
 		});
 	}
-	active() {
+	active(_agentId, workspaceDir) {
 		if (["1", "true"].includes(process.env.XOPC_SKIP_EXTENSIONS ?? "")) return [];
-		return this.list().filter((p) => p.receipt.enabled && p.readiness !== "blocked");
+		return this.list().filter((p) => p.receipt.enabled && p.readiness !== "blocked" && (p.receipt.workspacePaths === void 0 || workspaceDir !== void 0 && p.receipt.workspacePaths.includes(existsSync(workspaceDir) ? realpathSync(workspaceDir) : resolve(workspaceDir))) && this.setupReady(p));
+	}
+	setupReady(plugin) {
+		const path = join(this.stateDir, "plugin-setup", `${plugin.id}.json`);
+		if (!existsSync(path)) return true;
+		try {
+			const job = JSON.parse(readFileSync(path, "utf8"));
+			return job.packageRevision !== plugin.receipt.revision || job.state === "completed" || job.installed === true;
+		} catch {
+			return false;
+		}
 	}
-	inspect(source) {
-		return this.withSource(source, (root) => this.plan(root));
+	inspect(source, sourceLabel = source, importManifest) {
+		return this.withSource(source, (root) => this.plan(root, sourceLabel, importManifest));
 	}
-	plan(root) {
+	plan(root, sourceLabel, importManifest) {
 		validatePackageTree(root);
-		const initial = inspectAgentPlugin(root);
-		const inspection = inspectAgentPlugin(root, this.dataDir(initial.manifest.name));
+		const initial = inspectAgentPlugin(root, void 0, importManifest);
+		const existing = this.list().find((p) => p.receipt.source === sourceLabel && p.manifest.name === initial.manifest.name);
+		const scoped = initial.layout?.dialect !== "portable" || /^(?:git\+|github:|https:\/\/github\.com\/)/.test(sourceLabel) || sourceLabel.includes("#plugin=");
+		const installId = existing?.id ?? (scoped ? `${initial.manifest.name.slice(0, 48).replace(/[.-]+$/, "")}-${pluginSourceKey(sourceLabel)}` : initial.manifest.name);
+		const inspection = inspectAgentPlugin(root, this.dataDir(installId), importManifest);
 		const integrity = computeExtensionDirectoryIntegrity(root);
-		const current = this.receipt(inspection.manifest.name);
+		const current = this.receipt(installId);
 		const addedCapabilities = inspection.capabilities.filter((c) => !current?.capabilities.includes(c));
-		const reviewHash = createHash("sha256").update(JSON.stringify([integrity, inspection.capabilities])).digest("hex");
+		const reviewHash = createHash("sha256").update(JSON.stringify([
+			"plugin-adapter-v1",
+			integrity,
+			inspection.capabilities,
+			installId,
+			importManifest
+		])).digest("hex");
 		return {
 			...inspection,
+			installId,
 			integrity,
 			reviewHash,
 			addedCapabilities,
@@ -174,12 +218,15 @@ var AgentPluginStore = class {
 	}
 	install(source, options = {}) {
 		return this.mutate(() => this.withSource(source, (root) => {
-			const plan = this.plan(root);
-			const id = plan.manifest.name;
-			if (options.expectedId && options.expectedId !== id) throw new Error("Update package identity does not match installed plugin");
+			const plan = this.plan(root, options.sourceLabel ?? source, options.importManifest);
+			const id = options.expectedId ?? plan.installId;
+			const expected = this.receipt(id);
+			if (expected && (expected.declaredName ?? expected.id) !== plan.manifest.name) throw new Error("Update package identity does not match installed plugin");
+			if (options.expectedId && !expected) throw new Error("Update package identity does not match installed plugin");
 			const current = this.receipt(id);
 			if (current && !options.replace) throw new Error("Plugin already installed; use update");
-			if ((!current || plan.addedCapabilities.length > 0) && options.reviewHash !== plan.reviewHash) throw new Error("Package capability review is required");
+			const changedExecutable = current && current.integrity !== plan.integrity && (plan.capabilities.some((capability) => capability.startsWith("runtime.")) || current.capabilities.some((capability) => capability.startsWith("runtime.")));
+			if ((!current || plan.addedCapabilities.length > 0 || changedExecutable) && options.reviewHash !== plan.reviewHash) throw new Error("Package capability review is required");
 			if (options.reviewHash && options.reviewHash !== plan.reviewHash) throw new Error("Package changed after review; inspect again");
 			validatePackageTree(root);
 			const revision = randomUUID();
@@ -192,35 +239,119 @@ var AgentPluginStore = class {
 					verbatimSymlinks: true
 				});
 				validatePackageTree(target);
-				const installed = inspectAgentPlugin(target, this.dataDir(id));
+				const installed = inspectAgentPlugin(target, this.dataDir(id), options.importManifest);
 				const integrity = computeExtensionDirectoryIntegrity(target);
 				if (integrity !== plan.integrity) throw new Error("Package changed during installation");
 				const label = options.sourceLabel ?? source;
-				this.write({
+				const receipt = {
 					id,
 					revision,
-					source: /^(https:\/\/|store:)/.test(label) ? label : resolve(label),
+					source: /^(https:\/\/|store:|git\+|github:)/.test(label) ? label : resolve(label),
 					installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					declaredName: installed.manifest.name,
+					adapterVersion: installed.layout?.adapterVersion,
+					credentialScope: "revision",
+					oauthServers: Object.fromEntries(Object.entries(installed.servers).filter(([, server]) => server.type !== "stdio").map(([name, server]) => [name, server.type !== "stdio" ? server.url : ""])),
+					importManifest: options.importManifest,
+					resolvedCommit: options.resolvedCommit,
+					workspacePaths: current?.workspacePaths,
+					resourceHashes: plan.resources?.map((resource) => resource.sha256),
 					enabled: current?.enabled ?? false,
 					integrity,
 					capabilities: installed.capabilities,
 					...options.provenance ? { provenance: provenanceSchema.parse(options.provenance) } : {},
 					previous: current ? receiptFields.parse(current) : void 0
-				});
+				};
+				writeTextAtomicSync(join(this.stateDir, "plugin-revisions", id, `${revision}.json`), JSON.stringify(receiptFields.parse(receipt)));
+				if (options.stage && current) writeTextAtomicSync(this.pendingPath(id), JSON.stringify(receipt));
+				else this.write(receipt);
 			} catch (error) {
 				rmSync(target, {
 					recursive: true,
 					force: true
 				});
+				rmSync(join(this.stateDir, "plugin-revisions", id, `${revision}.json`), { force: true });
 				throw error;
 			}
-			return this.get(id);
+			return options.stage && current ? this.pending(id) : this.get(id);
 		}));
 	}
+	history(id) {
+		const current = this.receipt(id), pending = this.pending(id);
+		const receipts = /* @__PURE__ */ new Map();
+		for (const receipt of [
+			current,
+			current?.previous,
+			pending?.receipt
+		]) if (receipt) receipts.set(receipt.revision, receipt);
+		const directory = join(this.stateDir, "plugin-revisions", pluginName.parse(id));
+		if (existsSync(directory)) for (const name of readdirSync(directory)) {
+			if (!name.endsWith(".json")) continue;
+			const receipt = receiptFields.parse(JSON.parse(readFileSync(join(directory, name), "utf8")));
+			if (receipt.id !== id) throw new Error("Plugin history identity mismatch");
+			receipts.set(receipt.revision, receipt);
+		}
+		return [...receipts.values()].map((receipt) => this.fromReceipt(receipt));
+	}
+	/** Publish synchronous resource changes while the package lifecycle lock is held. */
+	withRevision(id, revision, fn) {
+		return this.mutate(() => {
+			if (this.receipt(id)?.revision !== revision && this.pending(id)?.receipt.revision !== revision) throw new Error("Plugin revision changed or was removed");
+			return fn();
+		});
+	}
+	pendingPath(id) {
+		return join(this.stateDir, "plugin-pending", `${pluginName.parse(id)}.json`);
+	}
+	pendingReceipt(id) {
+		const path = this.pendingPath(id);
+		if (!existsSync(path)) return void 0;
+		const receipt = receiptSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+		if (receipt.id !== id) throw new Error("Staged plugin identity mismatch");
+		return receipt;
+	}
+	pending(id) {
+		const receipt = this.pendingReceipt(id);
+		return receipt ? this.fromReceipt(receipt) : void 0;
+	}
+	commitPending(id) {
+		this.mutate(() => {
+			const pending = this.pending(id);
+			if (!pending) return;
+			if (pending.readiness === "blocked" || pending.receipt.previous?.revision !== this.receipt(id)?.revision) throw new Error("Staged update changed; inspect again");
+			this.write(pending.receipt);
+			rmSync(this.pendingPath(id), { force: true });
+		});
+	}
+	discardPending(id) {
+		this.mutate(() => {
+			const pending = this.pending(id);
+			if (!pending) return;
+			rmSync(this.pendingPath(id), { force: true });
+			rmSync(pending.rootDir, {
+				recursive: true,
+				force: true
+			});
+			try {
+				const data = this.dataDir(id);
+				rmSync(containedPath(data, join(data, "resources", pending.receipt.revision)), {
+					recursive: true,
+					force: true
+				});
+			} catch (err) {
+				log.warn({
+					err,
+					pluginId: id
+				}, "Could not clean staged plugin resources");
+			}
+			prunePluginResourceCache(this);
+		});
+	}
 	setEnabled(id, enabled) {
 		return this.mutate(() => {
 			const plugin = this.get(id);
 			if (!plugin) throw new Error("Plugin not installed");
+			if (enabled && plugin.layout?.compatibility.some((item) => item.component === "hooks")) throw new Error("This plugin requires unsupported lifecycle hooks and cannot be enabled by this compatibility version");
 			if (enabled && plugin.readiness === "blocked") throw new Error("Repair the plugin before enabling it");
 			this.write({
 				...plugin.receipt,
@@ -229,6 +360,17 @@ var AgentPluginStore = class {
 			return this.get(id);
 		});
 	}
+	setWorkspaceScope(id, workspacePaths) {
+		return this.mutate(() => {
+			const plugin = this.get(id);
+			if (!plugin) throw new Error("Plugin not installed");
+			this.write({
+				...plugin.receipt,
+				workspacePaths: workspacePaths === void 0 ? plugin.receipt.workspacePaths : workspacePaths === null ? void 0 : [...new Set(workspacePaths.map((path) => existsSync(path) ? realpathSync(path) : resolve(path)))]
+			});
+			return this.get(id);
+		});
+	}
 	rollback(id) {
 		return this.mutate(() => {
 			const receipt = this.receipt(id);
@@ -238,6 +380,7 @@ var AgentPluginStore = class {
 			this.write({
 				...previous,
 				enabled: receipt.enabled,
+				workspacePaths: receipt.workspacePaths,
 				previous: receiptFields.parse(receipt)
 			});
 			return this.get(id);
@@ -251,14 +394,21 @@ var AgentPluginStore = class {
 				recursive: true,
 				force: true
 			});
+			rmSync(join(this.stateDir, "plugin-revisions", id), {
+				recursive: true,
+				force: true
+			});
 			rmSync(join(this.stateDir, "plugin-health", id), {
 				recursive: true,
 				force: true
 			});
+			rmSync(this.pendingPath(id), { force: true });
+			rmSync(join(this.stateDir, "plugin-setup", `${id}.json`), { force: true });
 			if (removeData) rmSync(this.dataDir(id), {
 				recursive: true,
 				force: true
 			});
+			prunePluginResourceCache(this);
 		});
 	}
 	withSource(source, fn) {
@@ -292,7 +442,7 @@ var AgentPluginStore = class {
 				}
 			}
 			const children = readdirSync(temp);
-			return fn(existsSync(join(temp, "plugin.json")) ? temp : children.length === 1 ? join(temp, children[0]) : temp);
+			return fn(PLUGIN_MANIFEST_PATHS.some((path) => existsSync(join(temp, path))) ? temp : children.length === 1 ? join(temp, children[0]) : temp);
 		} finally {
 			rmSync(temp, {
 				recursive: true,

package/dist/src/extensions/agent-plugins/user-config.d.ts

@@ -0,0 +1,5 @@
+import type { AgentPluginStore, InstalledAgentPlugin } from './store.js';
+export declare function readPluginUserConfig(store: AgentPluginStore, id: string, revision: string): Record<string, unknown>;
+export declare function savePluginUserConfig(store: AgentPluginStore, plugin: InstalledAgentPlugin, input: Record<string, unknown>): Promise<void>;
+export declare function pluginConfigMissing(store: AgentPluginStore, plugin: InstalledAgentPlugin): string[];
+export declare function expandUserConfig(value: string, values: Record<string, unknown>): unknown;

package/dist/src/extensions/agent-plugins/user-config.js

@@ -0,0 +1,49 @@
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
+import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
+import { pluginAuthorizations } from "./setup-contract.js";
+import { pluginName } from "./validation.js";
+import { pluginCredentialProviderPrefix } from "./auth.js";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/extensions/agent-plugins/user-config.ts
+init_credentials();
+init_write_file_atomic();
+function readPluginUserConfig(store, id, revision) {
+	const path = join(store.stateDir, "plugin-config", `${pluginName.parse(id)}-${revision}.json`);
+	return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+}
+async function savePluginUserConfig(store, plugin, input) {
+	const fields = plugin.layout?.userConfig ?? {};
+	const values = readPluginUserConfig(store, plugin.id, plugin.receipt.revision);
+	for (const [key, value] of Object.entries(input)) {
+		const field = fields[key];
+		if (!field || typeof value !== field.type || typeof value === "string" && (value.length > 16384 || value.includes("\0"))) throw new Error(`Invalid configuration: ${key}`);
+		if (field.sensitive) {
+			const provider = `${pluginCredentialProviderPrefix(plugin.id)}config-${createHash("sha256").update(`${plugin.receipt.revision}:${key}`).digest("hex")}`;
+			await new CredentialResolver({ stateDir: store.stateDir }).saveApiKey(provider, String(value));
+			values[key] = { xopcSecretRef: {
+				provider,
+				fieldKey: key,
+				prefix: ""
+			} };
+		} else values[key] = value;
+	}
+	writeTextAtomicSync(join(store.stateDir, "plugin-config", `${plugin.id}-${plugin.receipt.revision}.json`), JSON.stringify(values));
+}
+function pluginConfigMissing(store, plugin) {
+	const saved = readPluginUserConfig(store, plugin.id, plugin.receipt.revision);
+	const accountFields = new Set(pluginAuthorizations(plugin.manifest).flatMap((value) => value.methods.flatMap((method) => method.type === "form" || method.type === "cli" ? method.fields : [])));
+	return Object.entries(plugin.layout?.userConfig ?? {}).filter(([key, field]) => !accountFields.has(key) && field.required && (saved[key] === void 0 || saved[key] === "") && field.default === void 0).map(([key]) => key);
+}
+function expandUserConfig(value, values) {
+	const exact = value.match(/^\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}$/);
+	if (exact && typeof values[exact[1]] === "object") return values[exact[1]];
+	return value.replace(/\$\{user_config\.([A-Za-z_][A-Za-z0-9_]*)\}/g, (_all, key) => {
+		if (values[key] === void 0) throw new Error(`Configure ${key} before starting tools`);
+		if (typeof values[key] === "object") throw new Error("Sensitive configuration must occupy an entire environment/header value");
+		return String(values[key]);
+	});
+}
+//#endregion
+export { expandUserConfig, pluginConfigMissing, readPluginUserConfig, savePluginUserConfig };

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

@@ -1,3 +1,5 @@
+import { pluginResources } from './resources.js';
+import { type PluginLayout } from './formats.js';
 import { z } from 'zod';
 export declare const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 export declare const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
@@ -28,6 +30,27 @@ declare const serverSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"streamable-http">;
     url: z.ZodString;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    oauth: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodOptional<z.ZodString>;
+        callbackPort: z.ZodOptional<z.ZodNumber>;
+        callbackUrl: z.ZodOptional<z.ZodString>;
+        clientName: z.ZodOptional<z.ZodString>;
+        clientRegistration: z.ZodOptional<z.ZodEnum<{
+            dcr: "dcr";
+            cimd: "cimd";
+        }>>;
+        authServerMetadataUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    connectionAuth: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            none: "none";
+            oauth: "oauth";
+            "api-key": "api-key";
+        }>;
+        headerName: z.ZodOptional<z.ZodString>;
+        prefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strict>], "type">;
 export type PluginManifest = z.infer<typeof manifestSchema>;
 export type PluginServer = z.infer<typeof serverSchema>;
@@ -36,6 +59,8 @@ export interface PluginDiagnostic {
     message: string;
 }
 export interface PluginInspection {
+    resources?: ReturnType<typeof pluginResources>;
+    layout?: PluginLayout;
     manifest: PluginManifest;
     rootDir: string;
     skills: Array<{
@@ -50,6 +75,6 @@ export declare function containedPath(root: string, path: string): string;
 export declare function expandPluginVariables(value: string, root: string, data: string): string;
 export declare function resolvePluginCwd(cwd: string | undefined, root: string, data: string): string;
 export declare function validatePluginServer(raw: unknown, root: string, data: string): PluginServer;
-export declare function inspectAgentPlugin(rootDir: string, dataDir?: string): PluginInspection;
+export declare function inspectAgentPlugin(rootDir: string, dataDir?: string, importManifest?: Record<string, unknown>): PluginInspection;
 export declare function pluginServerId(pluginId: string, serverName: string): string;
 export {};