@xopcai/xopc 0.0.396 → 0.0.398

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

@@ -0,0 +1,496 @@
+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 { pluginAuthorizations, pluginPermissionIssueSchema } from "./setup-contract.js";
+import { preparePluginResources } from "./resources.js";
+import { pluginName, pluginServerId } from "./validation.js";
+import { AgentPluginStore } from "./store.js";
+import { connectionFingerprint, matchingReusableConnection } from "./connection-reuse.js";
+import { createNativeMcpCredentials } from "../../agent/mcp/credential-store.js";
+import { readPluginAuthBinding, savePluginAuthBinding, savePluginOAuthReference } from "./auth.js";
+import { pluginConfigMissing, readPluginUserConfig, savePluginUserConfig } from "./user-config.js";
+import { materializePluginServers } from "./mcp-adapter.js";
+import { getNativePiAgentDir } from "../../agent/mcp/native-mcp.js";
+import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "../../agent/mcp/connection-setup.js";
+import { cancelPluginCliAuthorizations, getPluginCliAuthorization, inspectPluginCliAuthorization, startPluginCliAuthorization } from "./cli-authorization.js";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import lockfile from "proper-lockfile";
+//#region src/extensions/agent-plugins/setup.ts
+init_logger();
+init_write_file_atomic();
+const connection = z.object({
+	name: z.string(),
+	state: z.enum([
+		"pending",
+		"connected",
+		"oauth_required",
+		"token_required",
+		"error",
+		"skipped"
+	]),
+	toolCount: z.number().optional(),
+	authorizationId: z.string().optional()
+});
+const schema = z.object({
+	id: z.string().uuid(),
+	pluginId: pluginName,
+	owner: z.string(),
+	packageRevision: z.string().uuid(),
+	revision: z.number().int(),
+	state: z.enum([
+		"pending",
+		"running",
+		"action_required",
+		"completed",
+		"cancelled",
+		"interrupted",
+		"failed"
+	]),
+	resources: z.enum([
+		"pending",
+		"running",
+		"ready",
+		"error"
+	]),
+	connections: z.array(connection),
+	installed: z.boolean().default(false),
+	deferred: z.boolean().default(false),
+	authorizations: z.array(z.object({
+		id: z.string(),
+		state: z.enum([
+			"pending",
+			"connected",
+			"skipped",
+			"error"
+		]),
+		issues: z.array(pluginPermissionIssueSchema).max(20).default([]),
+		method: z.string().optional(),
+		attemptId: z.string().optional()
+	})).default([]),
+	operations: z.array(z.object({
+		key: z.string().uuid(),
+		action: z.string()
+	})).max(100).default([]),
+	missingConfig: z.array(z.string()).default([]),
+	partial: z.boolean(),
+	updatedAt: z.string(),
+	error: z.string().optional()
+});
+const actionRevision = {
+	expectedRevision: z.number().int(),
+	idempotencyKey: z.string().uuid().optional()
+};
+const setupActionSchema = z.discriminatedUnion("action", [
+	z.strictObject({
+		action: z.literal("prepare"),
+		...actionRevision
+	}),
+	z.strictObject({
+		action: z.literal("reuse"),
+		...actionRevision,
+		server: z.string(),
+		sourceServerId: z.string()
+	}),
+	z.strictObject({
+		action: z.literal("authorize"),
+		...actionRevision,
+		server: z.string(),
+		method: z.string().optional()
+	}),
+	z.strictObject({
+		action: z.literal("configure"),
+		...actionRevision,
+		values: z.record(z.string(), z.unknown()),
+		authorization: z.string().optional(),
+		method: z.string().optional()
+	}),
+	z.strictObject({
+		action: z.literal("complete"),
+		...actionRevision,
+		workspacePaths: z.array(z.string().min(1)).max(100).nullable().optional(),
+		allowPartial: z.boolean().default(false)
+	}),
+	z.strictObject({
+		action: z.literal("defer"),
+		...actionRevision
+	}),
+	z.strictObject({
+		action: z.literal("cancel"),
+		...actionRevision
+	})
+]);
+const log = createLogger("PluginSetup");
+const running = /* @__PURE__ */ new Map();
+var PluginSetupService = class {
+	constructor(store = new AgentPluginStore()) {
+		this.store = store;
+	}
+	path(id) {
+		return join(this.store.stateDir, "plugin-setup", `${pluginName.parse(id)}.json`);
+	}
+	key(id) {
+		return this.path(id);
+	}
+	write(job) {
+		job.revision++;
+		job.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		writeTextAtomicSync(this.path(job.pluginId), JSON.stringify(schema.parse(job)));
+	}
+	get(id, owner) {
+		if (!existsSync(this.path(id))) return;
+		const job = schema.parse(JSON.parse(readFileSync(this.path(id), "utf8")));
+		if (job.owner !== owner) throw new Error("Setup belongs to another principal");
+		if (job.state === "running" && !running.has(this.key(id)) && !lockfile.checkSync(this.path(id), { realpath: false })) {
+			job.state = "interrupted";
+			job.error = "Preparation was interrupted. Retry to continue.";
+			this.write(job);
+		}
+		return job;
+	}
+	create(id, owner) {
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		if (!plugin || plugin.readiness === "blocked") throw new Error("Plugin unavailable");
+		const previous = this.get(id, owner);
+		if (previous?.packageRevision === plugin.receipt.revision && previous.state !== "cancelled") return previous;
+		if (running.has(this.key(id)) || lockfile.checkSync(this.path(id), { realpath: false })) throw new Error("Preparation is already running");
+		const job = {
+			id: randomUUID(),
+			pluginId: id,
+			owner,
+			packageRevision: plugin.receipt.revision,
+			revision: 0,
+			state: "pending",
+			resources: "pending",
+			connections: Object.keys(plugin.servers).map((name) => ({
+				name,
+				state: "pending"
+			})),
+			installed: false,
+			deferred: false,
+			authorizations: pluginAuthorizations(plugin.manifest).map((value) => ({
+				id: value.id,
+				state: "pending",
+				issues: []
+			})),
+			operations: [],
+			missingConfig: pluginConfigMissing(this.store, plugin),
+			partial: plugin.diagnostics.length > 0,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		this.write(job);
+		return job;
+	}
+	invalidateConnection(id, owner, name) {
+		const job = this.get(id, owner);
+		if (!job) return;
+		running.get(this.key(id))?.abort();
+		const server = job.connections.find((value) => value.name === name);
+		if (server) {
+			if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+			server.state = "pending";
+			delete server.authorizationId;
+		}
+		job.state = "action_required";
+		this.write(job);
+	}
+	async reusableConnections(id, owner, config) {
+		if (!this.get(id, owner)) return {};
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		if (!plugin) return {};
+		getNativePiAgentDir();
+		const credentials = await createNativeMcpCredentials();
+		const result = {};
+		for (const [name, target] of Object.entries(plugin.servers)) {
+			result[name] = [];
+			for (const [sourceId, source] of Object.entries(config.mcp?.servers ?? {})) {
+				if (!matchingReusableConnection(target, source) || !source.url || !source.xopcOAuthCredentialId) continue;
+				if (await credentials.tokens(source.xopcOAuthCredentialId, source.url)) result[name].push({
+					id: sourceId,
+					name: source.displayName ?? sourceId
+				});
+			}
+		}
+		return result;
+	}
+	async authorization(id, owner, server, config) {
+		const job = this.get(id, owner);
+		if (!job) throw new Error("Setup not found");
+		const declared = pluginAuthorizations((this.store.pending(id) ?? this.store.get(id)).manifest).find((value) => value.id === server);
+		const selected = job.authorizations.find((value) => value.id === server);
+		const method = declared?.methods.find((value) => value.id === selected?.method);
+		if (method?.type === "cli") return selected?.attemptId ? getPluginCliAuthorization(selected.attemptId, owner, job.packageRevision) : void 0;
+		const target = job.connections.find((c) => c.name === (method?.type === "oauth" ? method.server : server));
+		if (!target?.authorizationId) return void 0;
+		const effective = this.config(id, job.packageRevision, config);
+		return getMcpAuthorization(target.authorizationId, owner, effective);
+	}
+	redirect(id, owner, server, url, config) {
+		const job = this.get(id, owner);
+		const declaration = pluginAuthorizations((this.store.pending(id) ?? this.store.get(id)).manifest).find((value) => value.id === server);
+		const selected = job?.authorizations.find((value) => value.id === server);
+		const method = declaration?.methods.find((value) => value.id === selected?.method);
+		const attempt = job?.connections.find((c) => c.name === (method?.type === "oauth" ? method.server : server))?.authorizationId;
+		return !!job && !!attempt && submitMcpRedirect(attempt, owner, url, this.config(id, job.packageRevision, config));
+	}
+	config(id, revision, config) {
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		if (!plugin || plugin.receipt.revision !== revision || plugin.readiness === "blocked") throw new Error("Plugin revision changed; restart setup");
+		const servers = materializePluginServers(plugin, this.store, [], true);
+		return {
+			...config,
+			mcp: {
+				...config.mcp,
+				servers: {
+					...config.mcp?.servers,
+					...servers
+				}
+			}
+		};
+	}
+	startPrepare(id, owner, revision, config, workspace, idempotencyKey) {
+		const current = this.get(id, owner);
+		if (idempotencyKey && current?.operations.some((op) => op.key === idempotencyKey && op.action === "prepare")) return current;
+		if (!current || current.revision !== revision) throw new Error("Setup changed. Refresh and retry.");
+		if (current.state === "running") return current;
+		if (lockfile.checkSync(this.path(id), { realpath: false })) throw new Error("Preparation is already running");
+		this.act(id, owner, {
+			action: "prepare",
+			expectedRevision: revision,
+			idempotencyKey
+		}, config, workspace).catch(() => {
+			log.warn({ pluginId: id }, "Plugin preparation could not continue");
+		});
+		return this.get(id, owner);
+	}
+	async act(id, owner, input, config, workspace) {
+		const current = this.get(id, owner);
+		const previous = input.idempotencyKey && current?.operations.find((op) => op.key === input.idempotencyKey);
+		if (previous) {
+			if (previous.action !== input.action) throw new Error("Idempotency key belongs to another action");
+			return current;
+		}
+		const remember = (job) => {
+			if (input.idempotencyKey && (job.state !== "cancelled" || input.action === "cancel")) {
+				job.operations = [...job.operations, {
+					key: input.idempotencyKey,
+					action: input.action
+				}].slice(-100);
+				this.write(job);
+			}
+			return job;
+		};
+		if (input.action === "cancel") return remember(await this.perform(id, owner, input, config, workspace));
+		const release = lockfile.lockSync(this.path(id), { realpath: false });
+		try {
+			return remember(await this.perform(id, owner, input, config, workspace));
+		} finally {
+			release();
+		}
+	}
+	async perform(id, owner, input, config, workspace) {
+		const job = this.get(id, owner);
+		if (!job) throw new Error("Setup not found");
+		if (job.revision !== input.expectedRevision) throw new Error("Setup changed. Refresh and retry.");
+		if (input.action === "cancel") {
+			running.get(this.key(id))?.abort();
+			cancelPluginCliAuthorizations(id, owner);
+			for (const server of job.connections) if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+			job.state = "cancelled";
+			this.write(job);
+			this.store.discardPending(id);
+			return job;
+		}
+		if (running.has(this.key(id))) throw new Error("Preparation is already running");
+		if (job.state === "cancelled") throw new Error("Restart setup before continuing");
+		const effective = this.config(id, job.packageRevision, config);
+		const plugin = this.store.pending(id) ?? this.store.get(id);
+		const declarations = pluginAuthorizations(plugin.manifest);
+		if (input.action === "configure") {
+			const controller = new AbortController();
+			running.set(this.key(id), controller);
+			try {
+				if (input.authorization || input.method) {
+					const declaration = declarations.find((value) => value.id === input.authorization);
+					const method = declaration?.methods.find((value) => value.id === input.method);
+					if (!method || !("fields" in method) || Object.keys(input.values).some((key) => !method.fields.includes(key))) throw new Error("Invalid credential form");
+					const saved = readPluginUserConfig(this.store, id, plugin.receipt.revision);
+					if (method.fields.some((key) => input.values[key] === void 0 && saved[key] === void 0 || typeof input.values[key] === "string" && !input.values[key].trim())) throw new Error("Complete the required credential fields");
+					const target = job.authorizations.find((value) => value.id === declaration.id);
+					target.method = method.id;
+					target.state = "pending";
+					delete target.attemptId;
+				}
+				cancelPluginCliAuthorizations(id, owner);
+				await savePluginUserConfig(this.store, plugin, input.values);
+				controller.signal.throwIfAborted();
+				this.config(id, job.packageRevision, config);
+				for (const server of job.connections) {
+					if (input.authorization && !declarations.find((value) => value.id === input.authorization)?.servers.includes(server.name)) continue;
+					if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+					server.state = "pending";
+					delete server.authorizationId;
+				}
+				job.missingConfig = pluginConfigMissing(this.store, plugin);
+				job.state = "action_required";
+				this.write(job);
+				return job;
+			} finally {
+				running.delete(this.key(id));
+			}
+		}
+		if (input.action === "reuse") {
+			const source = config.mcp?.servers?.[input.sourceServerId];
+			const candidates = await this.reusableConnections(id, owner, config);
+			if (!source?.xopcOAuthCredentialId || !candidates[input.server]?.some((value) => value.id === input.sourceServerId)) throw new Error("This connection is unavailable or has different endpoint or OAuth scopes");
+			if (this.get(id, owner)?.revision !== job.revision) throw new Error("Setup changed. Refresh and retry.");
+			savePluginOAuthReference(this.store, id, input.server, {
+				sourceServerId: input.sourceServerId,
+				credentialId: source.xopcOAuthCredentialId,
+				fingerprint: connectionFingerprint(source)
+			});
+			const server = job.connections.find((value) => value.name === input.server);
+			if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+			server.state = "pending";
+			delete server.authorizationId;
+			job.state = "action_required";
+			this.write(job);
+			return job;
+		}
+		if (input.action === "authorize") {
+			const declaration = declarations.find((value) => value.id === input.server);
+			const method = declaration?.methods.find((value) => value.id === input.method);
+			if (declaration && !method) throw new Error("Choose an authorization method");
+			if (method?.type === "form") throw new Error("Complete this method using its credential form");
+			if (declaration && method) {
+				if (job.resources !== "ready") throw new Error("Prepare resources before signing in");
+				const target = job.authorizations.find((value) => value.id === declaration.id);
+				target.method = method.id;
+				target.state = "pending";
+				for (const server of job.connections) if (declaration.servers.includes(server.name)) {
+					if (server.authorizationId) cancelMcpAuthorization(server.authorizationId, owner);
+					server.state = "pending";
+					delete server.authorizationId;
+				}
+				if (method.type === "cli") {
+					target.attemptId = startPluginCliAuthorization(this.store, plugin, declaration.id, method, owner).id;
+					job.state = "action_required";
+					this.write(job);
+					return job;
+				}
+			}
+			const server = job.connections.find((c) => c.name === (method?.type === "oauth" ? method.server : input.server));
+			if (!server) throw new Error("Unknown setup connection");
+			const target = plugin.servers[server.name];
+			if (target && readPluginAuthBinding(this.store, id, server.name, target, plugin.receipt.revision)?.oauthReference) await savePluginAuthBinding(this.store, id, server.name, { mode: "auto" });
+			if (this.get(id, owner)?.revision !== job.revision) throw new Error("Setup changed. Refresh and retry.");
+			server.authorizationId = startMcpAuthorization(this.config(id, job.packageRevision, config), workspace, pluginServerId(id, server.name), owner, { authorizationScope: `${job.id}:${server.name}` }).id;
+			job.state = "action_required";
+			this.write(job);
+			return job;
+		}
+		if (input.action === "complete" || input.action === "defer") {
+			const deferred = input.action === "defer";
+			if (job.resources !== "ready" || !deferred && pluginConfigMissing(this.store, plugin).length) throw new Error("Prepare resources and configuration first");
+			const partial = plugin.diagnostics.length > 0 || job.connections.some((c) => c.state !== "connected") || job.authorizations.some((value) => value.state !== "connected") || pluginConfigMissing(this.store, plugin).length > 0;
+			if (partial && !deferred && !("allowPartial" in input && input.allowPartial)) throw new Error("Some capabilities are unavailable. Review before enabling partially.");
+			if (plugin.layout?.compatibility.some((item) => item.component === "hooks")) throw new Error("Lifecycle hooks are not supported; keep this plugin installed and disabled until a compatible adapter is available");
+			this.store.commitPending(id);
+			this.store.setWorkspaceScope(id, "workspacePaths" in input ? input.workspacePaths : void 0);
+			this.store.setEnabled(id, true);
+			if (deferred) {
+				delete job.error;
+				cancelPluginCliAuthorizations(id, owner);
+				for (const server of job.connections) if (server.authorizationId && server.state !== "connected") cancelMcpAuthorization(server.authorizationId, owner);
+			}
+			job.installed = true;
+			job.deferred = deferred && partial;
+			job.partial = partial;
+			job.state = "completed";
+			this.write(job);
+			return job;
+		}
+		const controller = new AbortController();
+		running.set(this.key(id), controller);
+		const cancellationPoll = setInterval(() => {
+			try {
+				const current = this.get(id, owner);
+				if (!current || current.id !== job.id || current.revision !== job.revision || current.state === "cancelled" || !this.store.receipt(id)) controller.abort();
+			} catch {
+				controller.abort();
+			}
+		}, 500);
+		cancellationPoll.unref();
+		job.state = "running";
+		job.resources = "running";
+		delete job.error;
+		this.write(job);
+		try {
+			await preparePluginResources(this.store, plugin, controller.signal);
+			job.resources = "ready";
+			job.missingConfig = pluginConfigMissing(this.store, plugin);
+			if (job.missingConfig.length) {
+				job.state = "action_required";
+				job.error = "Complete the required configuration fields.";
+			} else {
+				for (const target of job.authorizations) {
+					const method = declarations.find((value) => value.id === target.id).methods.find((value) => value.id === target.method);
+					if (method?.type === "cli") {
+						const check = await inspectPluginCliAuthorization(this.store, plugin, target.id, method, controller.signal);
+						target.state = check.authenticated ? "connected" : "pending";
+						target.issues = check.issues;
+					} else if (method?.type === "form") {
+						const values = readPluginUserConfig(this.store, id, plugin.receipt.revision);
+						target.state = method.fields.every((key) => values[key] !== void 0 && values[key] !== "") ? "connected" : "pending";
+					}
+				}
+				for (const server of job.connections) {
+					controller.signal.throwIfAborted();
+					if (declarations.filter((value) => value.servers.includes(server.name)).some((gate) => {
+						const target = job.authorizations.find((value) => value.id === gate.id);
+						const method = gate.methods.find((value) => value.id === target.method);
+						return !method || method.type !== "oauth" && target.state !== "connected";
+					})) {
+						server.state = "skipped";
+						delete server.toolCount;
+						continue;
+					}
+					const result = await probeMcpConnection(effective, workspace, pluginServerId(id, server.name), { signal: controller.signal });
+					controller.signal.throwIfAborted();
+					server.state = result.state;
+					server.toolCount = result.toolCount;
+					const persisted = this.get(id, owner);
+					if (!persisted || persisted.id !== job.id || persisted.revision !== job.revision || persisted.state === "cancelled" || !this.store.receipt(id)) throw new Error("Setup changed");
+					this.config(id, job.packageRevision, config);
+					this.write(job);
+				}
+				for (const target of job.authorizations) target.state = declarations.find((value) => value.id === target.id).servers.every((name) => job.connections.find((value) => value.name === name)?.state === "connected") ? "connected" : "pending";
+				job.partial = plugin.diagnostics.length > 0;
+				if (job.connections.some((value) => value.state === "error")) job.error = "Connection verification failed. Check the credentials or login status and try again.";
+				job.state = "action_required";
+			}
+			this.config(id, job.packageRevision, config);
+			controller.signal.throwIfAborted();
+			if (this.get(id, owner)?.id !== job.id || this.get(id, owner)?.state === "cancelled") throw new Error("Setup changed");
+			this.write(job);
+		} catch {
+			const current = this.get(id, owner);
+			if (!controller.signal.aborted && current?.id === job.id && current.revision === job.revision && current.state !== "cancelled" && (this.store.pending(id) ?? this.store.get(id))?.receipt.revision === job.packageRevision) {
+				job.state = "failed";
+				if (job.resources !== "ready") job.resources = "error";
+				job.error = "Preparation failed. Retry after checking resources and connections.";
+				this.write(job);
+			}
+		} finally {
+			clearInterval(cancellationPoll);
+			running.delete(this.key(id));
+		}
+		const latest = this.get(id, owner);
+		if (!latest) throw new Error("Setup was removed");
+		return latest;
+	}
+};
+//#endregion
+export { PluginSetupService, setupActionSchema };

package/dist/src/extensions/agent-plugins/skill-catalog.d.ts

@@ -0,0 +1,14 @@
+import type { SkillCatalogEntry } from '../../agent/agent-manager.js';
+import { AgentPluginStore } from './store.js';
+export declare function pluginSkillName(plugin: ReturnType<AgentPluginStore['list']>[number], name: string): string;
+/** Browse installed content without enabling it in the Agent runtime. */
+export declare function withPluginSkillCatalog(catalog: SkillCatalogEntry[], store?: AgentPluginStore): SkillCatalogEntry[];
+export declare function pluginSkillPreview(name: string, store?: AgentPluginStore): {
+    name: string;
+    description: string;
+    bodyMarkdown: string;
+    disableModelInvocation: boolean;
+    metadata: import("../../agent/skills/types.js").SkillMetadata;
+    toolConditions?: import("../../agent/skills/types.js").SkillToolConditions;
+    requiredEnvVarNames?: string[];
+};

package/dist/src/extensions/agent-plugins/skill-catalog.js

@@ -0,0 +1,95 @@
+import { parseFrontmatter } from "../../markdown/frontmatter.js";
+import { createSkillConfigManager } from "../../agent/skills/config.js";
+import { parseSkillLocalizations } from "../../agent/skills/parse-skill-metadata.js";
+import { containedPath } from "./validation.js";
+import { AgentPluginStore } from "./store.js";
+import { buildSkillMarkdownPreviewFromRaw } from "../../agent/skills/skill-markdown-preview-from-raw.js";
+import { agentPluginInventoryRow } from "./inventory.js";
+import { basename, dirname } from "node:path";
+import { readFileSync } from "node:fs";
+//#region src/extensions/agent-plugins/skill-catalog.ts
+function pluginSkillName(plugin, name) {
+	return plugin.layout?.dialect !== "portable" ? `${plugin.id}.${name}` : name;
+}
+/** Browse installed content without enabling it in the Agent runtime. */
+function withPluginSkillCatalog(catalog, store = new AgentPluginStore()) {
+	const rows = [...catalog];
+	const config = createSkillConfigManager(store.stateDir).load();
+	for (const plugin of store.list()) {
+		const inventory = agentPluginInventoryRow(plugin, store);
+		const owner = {
+			id: plugin.id,
+			name: plugin.manifest.name,
+			title: inventory.setup.authorizations.length === 1 ? inventory.setup.authorizations[0].title : plugin.manifest.name,
+			authorizationStatus: inventory.authorizationStatus,
+			active: inventory.active,
+			readiness: plugin.readiness
+		};
+		for (const skill of plugin.skills) {
+			const name = pluginSkillName(plugin, skill.name);
+			const index = rows.findIndex((row) => row.origin === `plugin:${plugin.id}` && row.name === name);
+			try {
+				const raw = readFileSync(containedPath(plugin.rootDir, skill.filePath), "utf8");
+				const preview = buildSkillMarkdownPreviewFromRaw(raw, {
+					name,
+					description: ""
+				});
+				const { frontmatter } = parseFrontmatter(raw);
+				const fm = frontmatter;
+				const localizations = parseSkillLocalizations(fm).localizations ?? {
+					en: {
+						displayName: skill.name,
+						description: preview.description
+					},
+					"zh-CN": {
+						displayName: typeof fm.displayName === "string" ? fm.displayName : skill.name,
+						description: typeof fm.displayDescription === "string" ? fm.displayDescription : preview.description
+					}
+				};
+				if (index >= 0) {
+					rows[index] = {
+						...rows[index],
+						localizations,
+						plugin: owner
+					};
+					continue;
+				}
+				rows.push({
+					localizations,
+					directoryId: basename(dirname(skill.filePath)),
+					name,
+					description: preview.description,
+					source: "global",
+					origin: `plugin:${plugin.id}`,
+					path: dirname(skill.filePath),
+					managed: false,
+					writable: false,
+					enabled: config.entries?.[name]?.enabled !== false,
+					disableModelInvocation: preview.disableModelInvocation,
+					plugin: owner
+				});
+			} catch {}
+		}
+	}
+	return rows;
+}
+function pluginSkillPreview(name, store = new AgentPluginStore()) {
+	for (const plugin of store.list()) {
+		const skill = plugin.skills.find((skill) => pluginSkillName(plugin, skill.name) === name);
+		if (!skill) continue;
+		try {
+			return {
+				...buildSkillMarkdownPreviewFromRaw(readFileSync(containedPath(plugin.rootDir, skill.filePath), "utf8"), {
+					name,
+					description: ""
+				}),
+				name
+			};
+		} catch {
+			return null;
+		}
+	}
+	return null;
+}
+//#endregion
+export { pluginSkillName, pluginSkillPreview, withPluginSkillCatalog };

package/dist/src/extensions/agent-plugins/source-catalog.d.ts

@@ -0,0 +1,21 @@
+export interface PluginCandidate {
+    name: string;
+    source: string;
+    description?: string;
+}
+export declare class PluginSourceRedirect extends Error {
+    readonly source: string;
+    constructor(source: string);
+}
+export declare class PluginSelectionRequired extends Error {
+    readonly candidates: PluginCandidate[];
+    constructor(candidates: PluginCandidate[]);
+}
+export declare const isGitPluginSource: (source: string) => boolean;
+/** Fetch and validate a fixed tree without running hooks, submodules or package scripts. */
+export declare function withCatalogSource<T>(source: string, fn: (local: string, metadata: {
+    origin: string;
+    commit?: string;
+    importManifest?: Record<string, unknown>;
+}) => T | Promise<T>): Promise<T>;
+export declare const pluginSourceKey: (source: string) => string;