@xopcai/xopc 0.0.320 → 0.0.323

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

@@ -0,0 +1,305 @@
+import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
+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 { containedPath, inspectAgentPlugin, pluginName } from "./validation.js";
+import { readPluginMcpHealth } from "./health.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 { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import AdmZip from "adm-zip";
+import lockfile from "proper-lockfile";
+//#region src/extensions/agent-plugins/store.ts
+init_paths_state();
+init_write_file_atomic();
+init_logger();
+const receiptFields = z.object({
+	id: pluginName,
+	revision: z.string().uuid(),
+	source: z.string(),
+	installedAt: z.string(),
+	enabled: z.boolean(),
+	integrity: z.string(),
+	capabilities: z.array(z.string())
+});
+const receiptSchema = receiptFields.extend({ previous: receiptFields.optional() });
+const log = createLogger("AgentPlugins");
+var AgentPluginStore = class {
+	constructor(stateDir = resolveStateDir()) {
+		this.stateDir = stateDir;
+	}
+	receiptsDir() {
+		return join(this.stateDir, "plugin-receipts");
+	}
+	revisionKey() {
+		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}`;
+			} catch {
+				return "";
+			}
+		}).join("|");
+	}
+	dataDir(id) {
+		return containedPath(this.stateDir, join(this.stateDir, "plugin-data", pluginName.parse(id)));
+	}
+	revisionDir(id, revision) {
+		return join(this.stateDir, "plugins", pluginName.parse(id), z.string().uuid().parse(revision));
+	}
+	receiptPath(id) {
+		return join(this.receiptsDir(), `${pluginName.parse(id)}.json`);
+	}
+	receipt(id) {
+		const path = this.receiptPath(id);
+		if (!existsSync(path)) return void 0;
+		const receipt = receiptSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+		if (receipt.id !== id) throw new Error("Plugin receipt identity mismatch");
+		return receipt;
+	}
+	write(receipt) {
+		writeTextAtomicSync(this.receiptPath(receipt.id), JSON.stringify(receipt));
+	}
+	mutate(fn) {
+		mkdirSync(this.receiptsDir(), {
+			recursive: true,
+			mode: 448
+		});
+		const release = lockfile.lockSync(this.receiptsDir());
+		try {
+			return fn();
+		} finally {
+			release();
+		}
+	}
+	get(id) {
+		const receipt = this.receipt(id);
+		if (!receipt) return void 0;
+		const rootDir = this.revisionDir(id, receipt.revision);
+		try {
+			validatePackageTree(rootDir);
+			const inspection = inspectAgentPlugin(rootDir, this.dataDir(id));
+			const valid = computeExtensionDirectoryIntegrity(rootDir) === receipt.integrity;
+			if (!valid) inspection.diagnostics.push({
+				component: "package",
+				message: "Installed files differ from the reviewed package"
+			});
+			const health = Object.keys(inspection.servers).map((name) => readPluginMcpHealth(id, name, receipt.revision, this.stateDir));
+			const readiness = !valid ? "blocked" : inspection.diagnostics.length || health.includes("error") ? "degraded" : health.some((status) => status !== "ready") ? "setup_required" : "ready";
+			return {
+				...inspection,
+				id,
+				receipt,
+				format: "agent-plugin",
+				readiness
+			};
+		} catch (error) {
+			return {
+				id,
+				receipt,
+				format: "agent-plugin",
+				readiness: "blocked",
+				rootDir,
+				manifest: {
+					$schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+					name: id
+				},
+				skills: [],
+				servers: {},
+				capabilities: [],
+				diagnostics: [{
+					component: "package",
+					message: error instanceof Error ? error.message : String(error)
+				}]
+			};
+		}
+	}
+	list() {
+		if (!existsSync(this.receiptsDir())) return [];
+		return readdirSync(this.receiptsDir()).filter((name) => name.endsWith(".json")).sort().flatMap((name) => {
+			const id = name.slice(0, -5);
+			if (!pluginName.safeParse(id).success) return [];
+			try {
+				const plugin = this.get(id);
+				return plugin ? [plugin] : [];
+			} catch (error) {
+				log.warn({
+					err: error,
+					pluginId: id
+				}, "Invalid Agent Plugin receipt; package disabled");
+				return [];
+			}
+		});
+	}
+	active() {
+		if (["1", "true"].includes(process.env.XOPC_SKIP_EXTENSIONS ?? "")) return [];
+		return this.list().filter((p) => p.receipt.enabled && p.readiness !== "blocked");
+	}
+	inspect(source) {
+		return this.withSource(source, (root) => this.plan(root));
+	}
+	plan(root) {
+		validatePackageTree(root);
+		const initial = inspectAgentPlugin(root);
+		const inspection = inspectAgentPlugin(root, this.dataDir(initial.manifest.name));
+		const integrity = computeExtensionDirectoryIntegrity(root);
+		const current = this.receipt(inspection.manifest.name);
+		const addedCapabilities = inspection.capabilities.filter((c) => !current?.capabilities.includes(c));
+		const reviewHash = createHash("sha256").update(JSON.stringify([integrity, inspection.capabilities])).digest("hex");
+		return {
+			...inspection,
+			integrity,
+			reviewHash,
+			addedCapabilities,
+			installed: !!current
+		};
+	}
+	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 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");
+			if (options.reviewHash && options.reviewHash !== plan.reviewHash) throw new Error("Package changed after review; inspect again");
+			validatePackageTree(root);
+			const revision = randomUUID();
+			const target = this.revisionDir(id, revision);
+			mkdirSync(dirname(target), { recursive: true });
+			try {
+				cpSync(root, target, {
+					recursive: true,
+					dereference: false,
+					verbatimSymlinks: true
+				});
+				validatePackageTree(target);
+				const installed = inspectAgentPlugin(target, this.dataDir(id));
+				const integrity = computeExtensionDirectoryIntegrity(target);
+				if (integrity !== plan.integrity) throw new Error("Package changed during installation");
+				const label = options.sourceLabel ?? source;
+				this.write({
+					id,
+					revision,
+					source: /^(https:\/\/|store:)/.test(label) ? label : resolve(label),
+					installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					enabled: current?.enabled ?? false,
+					integrity,
+					capabilities: installed.capabilities,
+					previous: current ? receiptFields.parse(current) : void 0
+				});
+			} catch (error) {
+				rmSync(target, {
+					recursive: true,
+					force: true
+				});
+				throw error;
+			}
+			return this.get(id);
+		}));
+	}
+	setEnabled(id, enabled) {
+		return this.mutate(() => {
+			const plugin = this.get(id);
+			if (!plugin) throw new Error("Plugin not installed");
+			if (enabled && plugin.readiness === "blocked") throw new Error("Repair the plugin before enabling it");
+			this.write({
+				...plugin.receipt,
+				enabled
+			});
+			return this.get(id);
+		});
+	}
+	rollback(id) {
+		return this.mutate(() => {
+			const receipt = this.receipt(id);
+			const previous = receipt?.previous;
+			if (!receipt || !previous || previous.id !== id) throw new Error("No rollback revision available");
+			if (computeExtensionDirectoryIntegrity(this.revisionDir(id, previous.revision)) !== previous.integrity) throw new Error("Rollback revision integrity failed");
+			this.write({
+				...previous,
+				enabled: receipt.enabled,
+				previous: receiptFields.parse(receipt)
+			});
+			return this.get(id);
+		});
+	}
+	remove(id, removeData = false) {
+		this.mutate(() => {
+			if (!this.receipt(id)) throw new Error("Plugin not installed");
+			rmSync(this.receiptPath(id));
+			rmSync(join(this.stateDir, "plugins", pluginName.parse(id)), {
+				recursive: true,
+				force: true
+			});
+			rmSync(join(this.stateDir, "plugin-health", id), {
+				recursive: true,
+				force: true
+			});
+			if (removeData) rmSync(this.dataDir(id), {
+				recursive: true,
+				force: true
+			});
+		});
+	}
+	withSource(source, fn) {
+		const path = resolve(source);
+		if (statSync(path).isDirectory()) return fn(path);
+		if (statSync(path).size > 50 * 1024 * 1024) throw new Error("Plugin archive exceeds 50 MiB");
+		const temp = mkdtempSync(join(tmpdir(), "xopc-agent-plugin-"));
+		try {
+			const entries = new AdmZip(path).getEntries();
+			if (entries.length > 1e4) throw new Error("Too many archive entries");
+			let bytes = 0;
+			const paths = /* @__PURE__ */ new Set();
+			for (const entry of entries) {
+				if (entry.entryName.includes("\\") || entry.entryName.startsWith("/") || /^[a-z]:/i.test(entry.entryName)) throw new Error("Unsafe archive path");
+				const target = containedPath(temp, join(temp, entry.entryName));
+				if (paths.has(target)) throw new Error("Duplicate archive path");
+				paths.add(target);
+				const mode = entry.attr >>> 16 & 65535;
+				if ((mode & 61440) === 40960) throw new Error("Archive symlinks are not supported");
+				bytes += entry.header.size;
+				if (bytes > 100 * 1024 * 1024) throw new Error("Expanded archive exceeds 100 MiB");
+				if (entry.isDirectory) mkdirSync(target, { recursive: true });
+				else {
+					mkdirSync(dirname(target), { recursive: true });
+					const data = entry.getData();
+					if (data.length !== entry.header.size) throw new Error("Archive size mismatch");
+					writeFileSync(target, data, {
+						mode: mode & 73 ? 493 : 420,
+						flag: "wx"
+					});
+				}
+			}
+			const children = readdirSync(temp);
+			return fn(existsSync(join(temp, "plugin.json")) ? temp : children.length === 1 ? join(temp, children[0]) : temp);
+		} finally {
+			rmSync(temp, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+function validatePackageTree(root) {
+	let files = 0;
+	let bytes = 0;
+	const visit = (path, ancestors) => {
+		const safe = containedPath(root, path);
+		if (ancestors.has(safe)) throw new Error("Cyclic package symlink");
+		const stat = statSync(safe);
+		if (++files > 1e4 || (bytes += stat.isFile() ? stat.size : 0) > 100 * 1024 * 1024) throw new Error("Package exceeds limits");
+		if (stat.isDirectory()) {
+			const next = new Set([...ancestors, safe]);
+			for (const name of readdirSync(safe)) visit(join(path, name), next);
+		} else if (!stat.isFile()) throw new Error("Unsupported package file type");
+		if (lstatSync(path).isFile() && stat.nlink > 1) throw new Error("Package hardlinks are not supported");
+	};
+	visit(root, /* @__PURE__ */ new Set());
+}
+//#endregion
+export { AgentPluginStore };

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

@@ -0,0 +1,59 @@
+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";
+export declare const pluginName: z.ZodString;
+declare const manifestSchema: z.ZodObject<{
+    $schema: z.ZodLiteral<"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json">;
+    name: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    homepage: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    license: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const serverSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"stdio">;
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"streamable-http">;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"sse">;
+    url: z.ZodString;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>], "type">;
+export type PluginManifest = z.infer<typeof manifestSchema>;
+export type PluginServer = z.infer<typeof serverSchema>;
+export interface PluginDiagnostic {
+    component: string;
+    message: string;
+}
+export interface PluginInspection {
+    manifest: PluginManifest;
+    rootDir: string;
+    skills: Array<{
+        name: string;
+        filePath: string;
+    }>;
+    servers: Record<string, PluginServer>;
+    capabilities: string[];
+    diagnostics: PluginDiagnostic[];
+}
+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 pluginServerId(pluginId: string, serverName: string): string;
+export {};

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

@@ -0,0 +1,211 @@
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { z } from "zod";
+import { validateHeaderName, validateHeaderValue } from "node:http";
+import yaml from "js-yaml";
+//#region src/extensions/agent-plugins/validation.ts
+const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const pluginName = z.string().min(1).max(64).regex(/^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/);
+const manifestSchema = z.object({
+	$schema: z.literal(PLUGIN_SCHEMA),
+	name: pluginName,
+	version: z.string().optional(),
+	description: z.string().optional(),
+	author: z.strictObject({
+		name: z.string().optional(),
+		email: z.string().optional(),
+		url: z.string().optional()
+	}).optional(),
+	homepage: z.string().optional(),
+	repository: z.string().optional(),
+	license: z.string().optional(),
+	keywords: z.array(z.string()).optional(),
+	extensions: z.record(z.string(), z.unknown()).optional()
+});
+const strings = z.record(z.string(), z.string());
+const serverSchema = z.discriminatedUnion("type", [
+	z.strictObject({
+		type: z.literal("stdio"),
+		command: z.string().min(1),
+		args: z.array(z.string()).optional(),
+		env: strings.optional(),
+		cwd: z.string().optional()
+	}),
+	z.strictObject({
+		type: z.literal("streamable-http"),
+		url: z.string().min(1),
+		headers: strings.optional()
+	}),
+	z.strictObject({
+		type: z.literal("sse"),
+		url: z.string().min(1),
+		headers: strings.optional()
+	})
+]);
+function containedPath(root, path) {
+	const base = resolve(root);
+	const target = resolve(path);
+	const rel = relative(base, target);
+	if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) throw new Error("Path escapes package boundary");
+	let ancestor = target;
+	while (!existsSync(ancestor)) {
+		try {
+			lstatSync(ancestor);
+			throw new Error("Broken package symlink");
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		if (dirname(ancestor) === ancestor) break;
+		ancestor = dirname(ancestor);
+	}
+	let baseAncestor = base;
+	while (!existsSync(baseAncestor)) baseAncestor = dirname(baseAncestor);
+	const canonicalBase = resolve(realpathSync(baseAncestor), relative(baseAncestor, base));
+	const canonicalTarget = resolve(realpathSync(ancestor), relative(ancestor, target));
+	const resolvedRelative = relative(canonicalBase, canonicalTarget);
+	if (resolvedRelative === ".." || resolvedRelative.startsWith("../") || resolvedRelative.startsWith("..\\") || isAbsolute(resolvedRelative)) throw new Error("Resolved path escapes package boundary");
+	return canonicalTarget;
+}
+function readPackageFile(root, path) {
+	const safe = containedPath(root, path);
+	const stat = statSync(safe);
+	if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error("Expected a regular file of at most 1 MiB");
+	return readFileSync(safe, "utf8");
+}
+function expandPluginVariables(value, root, data) {
+	return value.replace(/\$\{PLUGIN_(ROOT|DATA)\}/g, (_, key) => key === "ROOT" ? root : data);
+}
+function resolvePluginCwd(cwd, root, data) {
+	if (cwd === void 0) return root;
+	const dataRooted = /^\$\{PLUGIN_DATA\}(?:\/|$)/.test(cwd);
+	if (!dataRooted && !/^(?:\.\/|\$\{PLUGIN_ROOT\}(?:\/|$))/.test(cwd)) throw new Error("Invalid MCP cwd");
+	return containedPath(dataRooted ? data : root, resolve(root, expandPluginVariables(cwd, root, data)));
+}
+function validatePluginServer(raw, root, data) {
+	const server = serverSchema.parse(raw);
+	if (server.type === "stdio") {
+		if (server.command.startsWith("./")) {
+			if (!statSync(containedPath(root, resolve(root, server.command))).isFile()) throw new Error("MCP command must be a file");
+		} else if (!/^[^\s/\\:;|&<>`$\x00-\x1f]+$/.test(server.command)) throw new Error("MCP command must be one bare executable or ./package-path");
+		for (const key of Object.keys(server.env ?? {})) {
+			if (["PLUGIN_ROOT", "PLUGIN_DATA"].includes(process.platform === "win32" ? key.toUpperCase() : key)) throw new Error("Reserved plugin environment variable");
+			if (!key || /[=\0]/.test(key)) throw new Error("Invalid environment name");
+		}
+		if ([
+			...server.args ?? [],
+			...Object.values(server.env ?? {}),
+			server.command,
+			server.cwd ?? ""
+		].some((value) => value.includes("\0"))) throw new Error("NUL in process configuration");
+		resolvePluginCwd(server.cwd, root, data);
+	} else {
+		const url = new URL(server.url);
+		const loopback = url.hostname === "localhost" || url.hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
+		if (!["https:", "http:"].includes(url.protocol) || url.protocol === "http:" && !loopback || url.username || url.password || server.url.includes("#")) throw new Error("Remote MCP requires HTTPS (HTTP is allowed on loopback), without user information or fragments");
+		const names = /* @__PURE__ */ new Set();
+		for (const [key, value] of Object.entries(server.headers ?? {})) {
+			validateHeaderName(key);
+			validateHeaderValue(key, value);
+			if (names.has(key.toLowerCase())) throw new Error("Duplicate case-insensitive header");
+			names.add(key.toLowerCase());
+		}
+	}
+	return server;
+}
+function inspectAgentPlugin(rootDir, dataDir = join(rootDir, ".inspection-data")) {
+	const root = realpathSync(rootDir);
+	if (existsSync(join(root, "xopc.extension.json"))) throw new Error("This package is a native xopc extension");
+	if (existsSync(join(root, "package.json"))) {
+		if (JSON.parse(readPackageFile(root, join(root, "package.json")))?.xopc?.extension) throw new Error("This package is a native xopc extension");
+	}
+	const raw = JSON.parse(readPackageFile(root, join(root, "plugin.json")));
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("Plugin manifest must be an object");
+	const diagnostics = [];
+	const cleaned = { ...raw };
+	for (const key of Object.keys(cleaned)) if (!Object.hasOwn(manifestSchema.shape, key)) {
+		diagnostics.push({
+			component: "manifest",
+			message: `Ignored unknown field: ${key}`
+		});
+		delete cleaned[key];
+	}
+	if ("extensions" in cleaned && (!cleaned.extensions || typeof cleaned.extensions !== "object" || Array.isArray(cleaned.extensions))) {
+		diagnostics.push({
+			component: "manifest",
+			message: "Ignored non-object extensions field"
+		});
+		delete cleaned.extensions;
+	}
+	const result = {
+		manifest: manifestSchema.parse(cleaned),
+		rootDir: root,
+		skills: [],
+		servers: Object.create(null),
+		capabilities: [],
+		diagnostics
+	};
+	const attempt = (component, fn) => {
+		try {
+			fn();
+		} catch (error) {
+			diagnostics.push({
+				component,
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	};
+	const present = (path) => {
+		try {
+			lstatSync(path);
+			return true;
+		} catch (error) {
+			if (error.code === "ENOENT") return false;
+			throw error;
+		}
+	};
+	const skillsDir = join(root, "skills");
+	if (present(skillsDir)) attempt("skills", () => {
+		const safe = containedPath(root, skillsDir);
+		if (!statSync(safe).isDirectory()) throw new Error("skills must be a directory");
+		for (const name of readdirSync(safe).sort()) attempt(`skill:${name}`, () => {
+			const dir = containedPath(root, join(safe, name));
+			if (!statSync(dir).isDirectory() || !present(join(dir, "SKILL.md"))) return;
+			const filePath = containedPath(root, join(dir, "SKILL.md"));
+			const match = readPackageFile(root, filePath).match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+			if (!match) throw new Error("Skill requires YAML frontmatter");
+			const metadata = z.object({
+				name: z.string().min(1).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+				description: z.string().min(1).max(1024),
+				license: z.string().optional(),
+				compatibility: z.string().min(1).max(500).optional(),
+				metadata: strings.optional(),
+				"allowed-tools": z.string().optional()
+			}).parse(yaml.load(match[1], { schema: yaml.JSON_SCHEMA }));
+			if (metadata.name !== name || !metadata.description.trim()) throw new Error("Skill name must match its directory and description must not be blank");
+			result.skills.push({
+				name,
+				filePath
+			});
+		});
+	});
+	const mcpPath = join(root, "mcp.json");
+	if (present(mcpPath)) attempt("mcp", () => {
+		const mcp = z.strictObject({
+			$schema: z.literal(MCP_SCHEMA),
+			mcpServers: z.record(z.string(), z.unknown())
+		}).parse(JSON.parse(readPackageFile(root, mcpPath)));
+		for (const [name, rawServer] of Object.entries(mcp.mcpServers)) attempt(`mcp:${name}`, () => {
+			result.servers[name] = validatePluginServer(rawServer, root, dataDir);
+		});
+	});
+	for (const skill of result.skills) result.capabilities.push(`content.skills:${skill.name}`);
+	for (const [name, server] of Object.entries(result.servers)) result.capabilities.push(server.type === "stdio" ? `runtime.mcp.stdio:${name}:${JSON.stringify(server)}` : `network.mcp:${name}:${server.type}:${server.url}:${JSON.stringify(server.headers ?? {})}`);
+	result.capabilities.sort();
+	return result;
+}
+function pluginServerId(pluginId, serverName) {
+	return `plugin/${encodeURIComponent(pluginId)}/${encodeURIComponent(serverName)}`;
+}
+//#endregion
+export { MCP_SCHEMA, PLUGIN_SCHEMA, containedPath, expandPluginVariables, inspectAgentPlugin, pluginName, pluginServerId, resolvePluginCwd, validatePluginServer };

package/dist/src/extensions/lockfile.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
 import { init_paths, resolveExtensionsDir, resolveExtensionsLockPath } from "../config/paths.js";
+import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
 import { dirname, join } from "path";
 import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "fs";
 import { mkdir, readFile } from "fs/promises";

package/dist/src/extensions/update.js

@@ -2,8 +2,8 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { init_paths, resolveBundledExtensionsDir, resolveExtensionsDir } from "../config/paths.js";
 import { init_loader, loadConfig } from "../config/loader.js";
-import { downloadExtensionStoreZipBuffer, resolveExtensionZipDownloadUrl, resolveExtensionsStoreBaseUrl, verifyStoreArtifactSha256 } from "../agent/skills/marketplace/adapters/store/store-api-client.js";
 import { computeExtensionDirectoryIntegrity, getExtensionLockfileManager } from "./lockfile.js";
+import { downloadExtensionStoreZipBuffer, resolveExtensionZipDownloadUrl, resolveExtensionsStoreBaseUrl, verifyStoreArtifactSha256 } from "../agent/skills/marketplace/adapters/store/store-api-client.js";
 import { commitStagedExtensionInstall, finalizeStagedExtensionInstall, rollbackStagedExtensionInstall, stageExtensionNpm, stageExtensionStoreZip } from "./install-transaction.js";
 import { findExtension } from "./marketplace.js";
 import { join } from "node:path";

package/dist/src/gateway/agents-admin.js

@@ -1,6 +1,6 @@
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentDir, resolveAgentProfileDir, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath, validateAgentIdForNewAgent } from "../agent/agent-scope.js";
-import { WORKSPACE_FILES, init_paths } from "../config/paths.js";
 import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
+import { WORKSPACE_FILES, init_paths } from "../config/paths.js";
 import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
 import { seedAgentProfileMarkdownFiles } from "../agent/context/workspace-seed.js";

package/dist/src/gateway/chat-stream/mapper.js

@@ -1,5 +1,6 @@
 import { parseTurnOutcome } from "../../../packages/gateway-contract/src/turn-outcome.js";
 import { resolveToolActivity } from "../../../packages/gateway-contract/src/tool-activity.js";
+import { isUserTurnDocument } from "../../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { createPetFeedback } from "./pet-feedback.js";
 //#region src/gateway/chat-stream/mapper.ts
@@ -446,12 +447,15 @@ function userMessageFromEvent(event, turnId) {
 	};
 }
 function userMessageDisplayMetadata(value) {
-	const rows = asRecord(value)?.sourceContexts;
-	if (!Array.isArray(rows)) return void 0;
+	const metadata = asRecord(value);
+	const rows = metadata?.sourceContexts;
+	const userTurnDocument = isUserTurnDocument(metadata?.userTurnDocument) ? metadata.userTurnDocument : void 0;
+	if (!Array.isArray(rows)) return userTurnDocument ? { userTurnDocument } : void 0;
 	const sourceContexts = rows.flatMap((value) => {
 		const row = asRecord(value);
 		if (row?.kind !== "note" && row?.kind !== "task" && row?.kind !== "file" && row?.kind !== "session" && row?.kind !== "browser_tab" && row?.kind !== "mcp_resource" || typeof row.sourceId !== "string" || typeof row.version !== "string" || typeof row.title !== "string") return [];
 		return [{
+			...typeof row.refId === "string" ? { refId: row.refId } : {},
 			kind: row.kind,
 			sourceId: row.sourceId,
 			version: row.version,
@@ -461,7 +465,10 @@ function userMessageDisplayMetadata(value) {
 			...row.kind === "file" && (row.fileKind === "file" || row.fileKind === "directory") ? { fileKind: row.fileKind } : {}
 		}];
 	});
-	return sourceContexts.length > 0 ? { sourceContexts } : void 0;
+	return sourceContexts.length > 0 || userTurnDocument ? {
+		...sourceContexts.length > 0 ? { sourceContexts } : {},
+		...userTurnDocument ? { userTurnDocument } : {}
+	} : void 0;
 }
 function extractTextFromMessage(message) {
 	return extractText(message.content);

package/dist/src/gateway/file-path-classifier.js

@@ -1,7 +1,7 @@
 import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
 import { init_agent_scope, resolveAgentProfileDir } from "../agent/agent-scope.js";
-import { init_paths, resolveConfigPath, resolveSkillsDir } from "../config/paths.js";
 import { extractProfileAgentId } from "../config/agent-profile.js";
+import { init_paths, resolveConfigPath, resolveSkillsDir } from "../config/paths.js";
 import { isBareProfileMarkdownFileName, resolveProfileMarkdownPathIfBareName } from "../agent/tools/tool-paths.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
 import { basename, isAbsolute, resolve } from "node:path";

package/dist/src/gateway/hono/lib/config-payload.js

@@ -1,9 +1,9 @@
 import { ContextPlanningConfigSchema, KnowledgeMemoryConfigSchema, UserModelConfigSchema, init_config } from "../../../user-context/config.js";
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
+import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, getChannelSetupStatus, init_channel_catalog_service } from "../../../channels/catalog/channel-catalog-service.js";
 import { init_models_json, loadModelsJson } from "../../../config/models-json.js";
 import { CredentialResolver, init_credentials } from "../../../auth/credentials.js";
-import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, getChannelSetupStatus, init_channel_catalog_service } from "../../../channels/catalog/channel-catalog-service.js";
 import { getProviderRegistry, init_plugin_registry } from "../../../providers/plugin-registry.js";
 import { getAllProviders, init_providers, isProviderConfigured } from "../../../providers/index.js";
 import { normalizeConfiguredMcpServers } from "../../../config/mcp-config-normalize.js";

package/dist/src/gateway/hono/routes/agent-plugins.d.ts

@@ -0,0 +1,3 @@
+import type { Hono } from 'hono';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function registerAgentPluginRoutes(app: Hono, deps: AuthenticatedRouteDeps): void;