emdash 0.29.0 → 0.30.0

package/src/emdash-runtime.ts

@@ -7,9 +7,11 @@
  * Created once per worker lifetime, cached and reused across requests.
  */
 
+import { Permissions } from "@emdash-cms/auth";
 import type { Element } from "@emdash-cms/blocks";
 import { Kysely, sql, type Dialect } from "kysely";
 import virtualConfig from "virtual:emdash/config";
+import { z } from "zod";
 
 import { validateRev } from "./api/rev.js";
 import type {
@@ -27,6 +29,7 @@ import {
 	MIGRATION_RACE_WAIT_MS,
 	runMigrations,
 } from "./database/migrations/runner.js";
+import { AuditRepository } from "./database/repositories/audit.js";
 import { RevisionRepository } from "./database/repositories/revision.js";
 import type {
 	ContentItem as ContentItemInternal,
@@ -41,18 +44,25 @@ import {
 	markContentMediaUsageCollectionStale,
 	refreshContentMediaUsageAfterWrite,
 } from "./media/usage/content-refresh.js";
-import type { SandboxedPluginInstance, SandboxRunner } from "./plugins/sandbox/types.js";
+import { createSandboxRunnerOptions } from "./plugins/sandbox/runner-options.js";
+import type {
+	SandboxedPluginInstance,
+	SandboxRunner,
+	SandboxRunnerFactory,
+} from "./plugins/sandbox/types.js";
 import type {
 	ResolvedPlugin,
 	MediaItem,
 	PluginManifest,
 	PluginCapability,
 	PluginStorageConfig,
+	PluginMcpManifestConfig,
 	PublicPageContext,
 	PageMetadataContribution,
 	PageFragmentContribution,
 	PortableTextBlockConfig,
 	FieldWidgetConfig,
+	SettingField,
 } from "./plugins/types.js";
 import type { FieldType } from "./schema/types.js";
 import { hashString } from "./utils/hash.js";
@@ -121,6 +131,7 @@ function isValidMetadataContribution(c: unknown): c is PageMetadataContribution
 }
 
 import { after } from "./after.js";
+import { maybeRunScheduledBackup } from "./api/handlers/backup.js";
 import { loadBundleFromR2 } from "./api/handlers/marketplace.js";
 import { runSystemCleanup } from "./cleanup.js";
 import {
@@ -174,7 +185,7 @@ import {
 } from "./plugins/hooks.js";
 import { normalizeManifestRoute } from "./plugins/manifest-schema.js";
 import { extractRequestMeta, sanitizeHeadersForSandbox } from "./plugins/request-meta.js";
-import { PluginRouteRegistry, type RouteMeta } from "./plugins/routes.js";
+import { buildRouteMeta, PluginRouteRegistry, type RouteMeta } from "./plugins/routes.js";
 import type { CronScheduler } from "./plugins/scheduler/types.js";
 import { PluginStateRepository } from "./plugins/state.js";
 import { normalizeRegistryConfig } from "./registry/config.js";
@@ -220,10 +231,14 @@ export interface SandboxedPluginEntry {
 	allowedHosts: string[];
 	/** Declared storage collections */
 	storage: PluginStorageConfig;
+	/** Serialized MCP declarations emitted at plugin build time. */
+	mcp?: PluginMcpManifestConfig;
 	/** Admin pages */
 	adminPages?: Array<{ path: string; label?: string; icon?: string }>;
 	/** Dashboard widgets */
 	adminWidgets?: Array<{ id: string; title?: string; size?: string }>;
+	/** Settings schema for the auto-generated admin settings form */
+	settingsSchema?: Record<string, SettingField>;
 	/** Portable Text block types contributed to the editor (declarative Block Kit) */
 	portableTextBlocks?: PortableTextBlockConfig[];
 	/** Field widget types contributed for schema-field editing UIs */
@@ -309,16 +324,8 @@ export interface RuntimeDependencies {
 	/** Media provider entries from virtual module */
 	mediaProviderEntries?: MediaProviderEntry[];
 	sandboxedPluginEntries: SandboxedPluginEntry[];
-	/** Factory function matching SandboxRunnerFactory signature */
-	createSandboxRunner:
-		| ((opts: {
-				db: Kysely<Database>;
-				mediaStorage?: {
-					upload(options: { key: string; body: Uint8Array; contentType: string }): Promise<unknown>;
-					delete(key: string): Promise<unknown>;
-				};
-		  }) => SandboxRunner)
-		| null;
+	/** Factory function supplied by the active platform adapter. */
+	createSandboxRunner: SandboxRunnerFactory | null;
 }
 
 /**
@@ -354,7 +361,12 @@ export interface EmDashRuntimeParts {
 		db: Kysely<Database>;
 		getDb?: () => Kysely<Database>;
 		storage?: Storage;
-		siteInfo?: { siteName?: string; siteUrl?: string; locale?: string };
+		siteInfo?: {
+			siteName?: string;
+			siteUrl?: string;
+			locale?: string;
+			trailingSlash?: "always" | "never" | "ignore";
+		};
 	};
 	runtimeDeps: RuntimeDependencies;
 	pipelineRef: { current: HookPipeline };
@@ -469,7 +481,9 @@ const marketplaceManifestCache = new Map<
 		admin?: {
 			pages?: PluginAdminPage[];
 			widgets?: PluginDashboardWidget[];
+			settingsSchema?: Record<string, SettingField>;
 		};
+		mcp?: PluginMcpManifestConfig;
 	}
 >();
 /** Route metadata for sandboxed plugins: pluginId -> routeName -> RouteMeta */
@@ -536,7 +550,12 @@ export class EmDashRuntime {
 		db: Kysely<Database>;
 		getDb?: () => Kysely<Database>;
 		storage?: Storage;
-		siteInfo?: { siteName?: string; siteUrl?: string; locale?: string };
+		siteInfo?: {
+			siteName?: string;
+			siteUrl?: string;
+			locale?: string;
+			trailingSlash?: "always" | "never" | "ignore";
+		};
 	};
 	/** Dependencies needed for exclusive hook resolution */
 	private runtimeDeps: RuntimeDependencies;
@@ -656,6 +675,9 @@ export class EmDashRuntime {
 			console.error("[cleanup] System cleanup failed:", error);
 		}
 
+		// Never throws; no-op unless scheduled backups are enabled and due.
+		await maybeRunScheduledBackup(this.db, this.storage ?? undefined);
+
 		return { published };
 	}
 
@@ -714,12 +736,11 @@ export class EmDashRuntime {
 			// pipelineFactoryOptions), so the merge only adds emailPipeline.
 			newPipeline.setContextFactory({ emailPipeline: this.email });
 		}
-		if (this.cronScheduler) {
-			const scheduler = this.cronScheduler;
-			newPipeline.setContextFactory({
-				cronReschedule: () => scheduler.reschedule(),
-			});
-		}
+		newPipeline.setContextFactory({
+			// Plugin schedules remain database-backed when no in-process scheduler
+			// exists; an external trigger is responsible for invoking due tasks.
+			cronReschedule: () => this.cronScheduler?.reschedule(),
+		});
 
 		// Update the email pipeline to use the new hook pipeline
 		if (this.email) {
@@ -866,6 +887,7 @@ export class EmDashRuntime {
 					id: bundle.manifest.id,
 					version: bundle.manifest.version,
 					admin: bundle.manifest.admin,
+					mcp: bundle.manifest.mcp,
 				});
 
 				// Cache route metadata from manifest for auth decisions
@@ -873,7 +895,7 @@ export class EmDashRuntime {
 					const routeMetaMap = new Map<string, RouteMeta>();
 					for (const entry of bundle.manifest.routes) {
 						const normalized = normalizeManifestRoute(entry);
-						routeMetaMap.set(normalized.name, { public: normalized.public === true });
+						routeMetaMap.set(normalized.name, buildRouteMeta(normalized));
 					}
 					sandboxedRouteMetaCache.set(pluginId, routeMetaMap);
 				} else {
@@ -980,12 +1002,13 @@ export class EmDashRuntime {
 					id: bundle.manifest.id,
 					version: bundle.manifest.version,
 					admin: bundle.manifest.admin,
+					mcp: bundle.manifest.mcp,
 				});
 				if (bundle.manifest.routes.length > 0) {
 					const routeMetaMap = new Map<string, RouteMeta>();
 					for (const entry of bundle.manifest.routes) {
 						const normalized = normalizeManifestRoute(entry);
-						routeMetaMap.set(normalized.name, { public: normalized.public === true });
+						routeMetaMap.set(normalized.name, buildRouteMeta(normalized));
 					}
 					sandboxedRouteMetaCache.set(pluginId, routeMetaMap);
 				} else {
@@ -1029,6 +1052,7 @@ export class EmDashRuntime {
 							size:
 								w.size === "full" || w.size === "half" || w.size === "third" ? w.size : undefined,
 						})),
+						settingsSchema: bundle.manifest.admin?.settingsSchema,
 					});
 					newPlugins.push(adapted);
 					this.allPipelinePlugins.push(adapted);
@@ -1106,7 +1130,14 @@ export class EmDashRuntime {
 		const storage = EmDashRuntime.getStorage(deps);
 
 		let pluginStates: Map<string, string> = new Map();
-		let siteInfo: { siteName?: string; siteUrl?: string; locale?: string } | undefined;
+		let siteInfo:
+			| {
+					siteName?: string;
+					siteUrl?: string;
+					locale?: string;
+					trailingSlash?: "always" | "never" | "ignore";
+			  }
+			| undefined;
 		// "Already set up" by default so a read failure (e.g. tables absent on a
 		// pre-migration db) skips seeding rather than seeding a half-built db.
 		let seedGate = { collectionCount: 1, setupDone: true };
@@ -1149,6 +1180,10 @@ export class EmDashRuntime {
 				siteName: siteOpts.get("emdash:site_title") ?? undefined,
 				siteUrl: siteOpts.get("emdash:site_url") ?? undefined,
 				locale: siteOpts.get("emdash:locale") ?? undefined,
+				// trailingSlash is a build-time Astro routing decision, not a
+				// user-editable setting, so it comes from the Astro config
+				// (virtual:emdash/config), not the options table.
+				trailingSlash: virtualConfig?.trailingSlash,
 			};
 		};
 
@@ -1386,7 +1421,7 @@ export class EmDashRuntime {
 
 		// Load sandboxed plugins (build-time, sandbox runner path)
 		const sandboxedPlugins = await phase("rt.sandbox", "Sandboxed plugins", () =>
-			EmDashRuntime.loadSandboxedPlugins(deps, db, storage),
+			EmDashRuntime.loadSandboxedPlugins(deps, db, storage, siteInfo),
 		);
 
 		// Cold-start: load marketplace- and registry-installed plugins from
@@ -1404,6 +1439,7 @@ export class EmDashRuntime {
 						storage,
 						deps,
 						sandboxedPlugins,
+						siteInfo,
 					),
 				),
 			);
@@ -1419,6 +1455,7 @@ export class EmDashRuntime {
 						storage,
 						deps,
 						sandboxedPlugins,
+						siteInfo,
 					),
 				),
 			);
@@ -1487,6 +1524,12 @@ export class EmDashRuntime {
 		await phase("rt.cron", "Cron init (recovery deferred post-response)", async () => {
 			try {
 				cronExecutor = new CronExecutor(resolveDb, invokeCronHook);
+				// Plugin schedules are always database-backed. On long-lived runtimes this
+				// callback also wakes the timer; on Cloudflare the external Cron Trigger
+				// drives execution, so rescheduling is intentionally a no-op.
+				pipeline.setContextFactory({
+					cronReschedule: () => cronScheduler?.reschedule(),
+				});
 
 				// Recover stale locks from previous crashes. Pure bookkeeping
 				// against the _emdash_cron_tasks table — no request needs the
@@ -1541,11 +1584,8 @@ export class EmDashRuntime {
 							// by runSystemCleanup. This catches unexpected errors.
 							console.error("[cleanup] System cleanup failed:", error);
 						}
-					});
-
-					// Add cron reschedule callback (merges with existing factory options)
-					pipeline.setContextFactory({
-						cronReschedule: () => cronScheduler?.reschedule(),
+						// Never throws; no-op unless scheduled backups are enabled and due.
+						await maybeRunScheduledBackup(db, storage ?? undefined);
 					});
 
 					// start() is void on the timer scheduler but the interface
@@ -1805,6 +1845,7 @@ export class EmDashRuntime {
 					storage: entry.storage as never,
 					adminPages,
 					adminWidgets,
+					settingsSchema: entry.settingsSchema,
 					portableTextBlocks: entry.portableTextBlocks,
 					fieldWidgets: entry.fieldWidgets,
 				});
@@ -1826,6 +1867,12 @@ export class EmDashRuntime {
 		deps: RuntimeDependencies,
 		db: Kysely<Database>,
 		mediaStorage?: Storage | null,
+		siteInfo?: {
+			siteName?: string;
+			siteUrl?: string;
+			locale?: string;
+			trailingSlash?: "always" | "never" | "ignore";
+		},
 	): Promise<Map<string, SandboxedPluginInstance>> {
 		// Return cached plugins if already loaded
 		if (sandboxedPluginCache.size > 0) {
@@ -1839,20 +1886,25 @@ export class EmDashRuntime {
 
 		// Create sandbox runner if not exists
 		if (!sandboxRunner && deps.createSandboxRunner) {
-			sandboxRunner = deps.createSandboxRunner({
-				db,
-				mediaStorage: mediaStorage
-					? {
-							upload: (opts) =>
-								mediaStorage.upload({
-									key: opts.key,
-									body: opts.body,
-									contentType: opts.contentType,
-								}),
-							delete: (key) => mediaStorage.delete(key),
-						}
-					: undefined,
-			});
+			sandboxRunner = deps.createSandboxRunner(
+				createSandboxRunnerOptions(
+					{
+						db,
+						mediaStorage: mediaStorage
+							? {
+									upload: (opts) =>
+										mediaStorage.upload({
+											key: opts.key,
+											body: opts.body,
+											contentType: opts.contentType,
+										}),
+									delete: (key) => mediaStorage.delete(key),
+								}
+							: undefined,
+					},
+					siteInfo,
+				),
+			);
 		}
 
 		if (!sandboxRunner) {
@@ -1900,6 +1952,7 @@ export class EmDashRuntime {
 					hooks: [],
 					routes: [],
 					admin: {},
+					mcp: entry.mcp,
 				};
 
 				const plugin = await sandboxRunner.load(manifest, entry.code);
@@ -1935,22 +1988,33 @@ export class EmDashRuntime {
 		storage: Storage,
 		deps: RuntimeDependencies,
 		cache: Map<string, SandboxedPluginInstance>,
+		siteInfo?: {
+			siteName?: string;
+			siteUrl?: string;
+			locale?: string;
+			trailingSlash?: "always" | "never" | "ignore";
+		},
 	): Promise<void> {
 		// Ensure sandbox runner exists with media storage wired up.
 		// (storage here is the media Storage adapter from the runtime.)
 		if (!sandboxRunner && deps.createSandboxRunner) {
-			sandboxRunner = deps.createSandboxRunner({
-				db,
-				mediaStorage: {
-					upload: (opts) =>
-						storage.upload({
-							key: opts.key,
-							body: opts.body,
-							contentType: opts.contentType,
-						}),
-					delete: (key) => storage.delete(key),
-				},
-			});
+			sandboxRunner = deps.createSandboxRunner(
+				createSandboxRunnerOptions(
+					{
+						db,
+						mediaStorage: {
+							upload: (opts) =>
+								storage.upload({
+									key: opts.key,
+									body: opts.body,
+									contentType: opts.contentType,
+								}),
+							delete: (key) => storage.delete(key),
+						},
+					},
+					siteInfo,
+				),
+			);
 		}
 		// In sandbox bypass mode, marketplace plugins are loaded in-process
 		// BEFORE pipeline creation by EmDashRuntime.create(). Skip here.
@@ -1997,6 +2061,7 @@ export class EmDashRuntime {
 						id: bundle.manifest.id,
 						version: bundle.manifest.version,
 						admin: bundle.manifest.admin,
+						mcp: bundle.manifest.mcp,
 					});
 
 					// Cache route metadata from manifest for auth decisions
@@ -2004,7 +2069,7 @@ export class EmDashRuntime {
 						const routeMeta = new Map<string, RouteMeta>();
 						for (const entry of bundle.manifest.routes) {
 							const normalized = normalizeManifestRoute(entry);
-							routeMeta.set(normalized.name, { public: normalized.public === true });
+							routeMeta.set(normalized.name, buildRouteMeta(normalized));
 						}
 						sandboxedRouteMetaCache.set(plugin.pluginId, routeMeta);
 					}
@@ -2068,12 +2133,13 @@ export class EmDashRuntime {
 						id: bundle.manifest.id,
 						version: bundle.manifest.version,
 						admin: bundle.manifest.admin,
+						mcp: bundle.manifest.mcp,
 					});
 					if (bundle.manifest.routes.length > 0) {
 						const routeMeta = new Map<string, RouteMeta>();
 						for (const entry of bundle.manifest.routes) {
 							const normalized = normalizeManifestRoute(entry);
-							routeMeta.set(normalized.name, { public: normalized.public === true });
+							routeMeta.set(normalized.name, buildRouteMeta(normalized));
 						}
 						sandboxedRouteMetaCache.set(plugin.pluginId, routeMeta);
 					}
@@ -2103,6 +2169,7 @@ export class EmDashRuntime {
 							size:
 								w.size === "full" || w.size === "half" || w.size === "third" ? w.size : undefined,
 						})),
+						settingsSchema: bundle.manifest.admin?.settingsSchema,
 					});
 					resolved.push(adapted);
 					console.log(
@@ -2781,13 +2848,14 @@ export class EmDashRuntime {
 								authorId: bodyWithoutRev.authorId ?? undefined,
 							});
 
-							// Update entry to point to new draft (metadata only, not data columns)
+							// Update entry to point to new draft (metadata only, not data columns).
+							// No updated_at stamp: draft staging leaves live content untouched,
+							// so public "last modified" consumers must not see a change (#2143).
 							validateIdentifier(collection, "collection");
 							const tableName = `ec_${collection}`;
 							await sql`
 								UPDATE ${sql.ref(tableName)}
-								SET draft_revision_id = ${revision.id},
-									updated_at = ${new Date().toISOString()}
+								SET draft_revision_id = ${revision.id}
 								WHERE id = ${resolvedId}
 							`.execute(this.db);
 							draftStorageChanged = true;
@@ -3179,7 +3247,10 @@ export class EmDashRuntime {
 
 		// Revision-capable collections: restore is "make this revision the
 		// current draft". The live row's data columns are left untouched
-		// (only `draft_revision_id` and `updated_at` change). The caller
+		// (only `draft_revision_id` changes — no `updated_at` stamp, since
+		// restoring to draft is the same kind of draft-only staging as
+		// Save/Autosave and must not register a phantom modification for
+		// sitemap <lastmod> / JSON-LD dateModified, #2143). The caller
 		// must then `content_publish` to promote the restored draft to
 		// live, matching the documented tool contract.
 		try {
@@ -3194,8 +3265,7 @@ export class EmDashRuntime {
 			const tableName = `ec_${revision.collection}`;
 			await sql`
 				UPDATE ${sql.ref(tableName)}
-				SET draft_revision_id = ${newDraft.id},
-					updated_at = ${new Date().toISOString()}
+				SET draft_revision_id = ${newDraft.id}
 				WHERE id = ${revision.entryId}
 			`.execute(this.db);
 
@@ -3280,7 +3350,7 @@ export class EmDashRuntime {
 		if (trustedPlugin) {
 			const route = trustedPlugin.routes[routeKey];
 			if (!route) return null;
-			return { public: route.public === true };
+			return buildRouteMeta(route);
 		}
 
 		// Check sandboxed plugin route metadata cache
@@ -3314,6 +3384,18 @@ export class EmDashRuntime {
 		return null;
 	}
 
+	/**
+	 * Resolve the settings schema for a runtime-installed (marketplace or
+	 * registry) plugin from its cached manifest. Returns `{}` for a known
+	 * plugin without a schema and `null` for unknown plugins, matching the
+	 * contract of `getPluginSettingsSchema` for build-time plugins.
+	 */
+	getRuntimePluginSettingsSchema(pluginId: string): Record<string, SettingField> | null {
+		const meta = marketplaceManifestCache.get(pluginId);
+		if (!meta) return null;
+		return meta.admin?.settingsSchema ?? {};
+	}
+
 	async handlePluginApiRoute(pluginId: string, _method: string, path: string, request: Request) {
 		if (!this.isPluginEnabled(pluginId)) {
 			return {
@@ -3327,9 +3409,9 @@ export class EmDashRuntime {
 		const trustedPlugin = this.configuredPlugins.find((p) => p.id === pluginId);
 		if (trustedPlugin && this.enabledPlugins.has(trustedPlugin.id)) {
 			const routeRegistry = new PluginRouteRegistry({
-				db: this.db,
-				storage: this.storage ?? undefined,
+				...this.pipelineFactoryOptions,
 				emailPipeline: this.email ?? undefined,
+				cronReschedule: () => this.cronScheduler?.reschedule(),
 				trustedProxyHeaders: getTrustedProxyHeaders(this.config),
 			});
 			routeRegistry.register(trustedPlugin);
@@ -3358,6 +3440,168 @@ export class EmDashRuntime {
 		};
 	}
 
+	async getPluginMcpTools(pluginId?: string) {
+		const tools: Array<{
+			pluginId: string;
+			name: string;
+			description: string;
+			route: string;
+			permission: string;
+			destructive: boolean;
+			inputSchema: z.ZodType;
+			outputSchema?: z.ZodType;
+		}> = [];
+		const seen = new Set<string>();
+
+		for (const plugin of this.configuredPlugins) {
+			if (pluginId && plugin.id !== pluginId) continue;
+			for (const [name, tool] of Object.entries(plugin.mcp?.tools ?? {})) {
+				const route = plugin.routes[tool.route];
+				if (!route || route.public || !route.permission || !(route.permission in Permissions))
+					continue;
+				const key = `${plugin.id}__${name}`;
+				if (seen.has(key)) continue;
+				seen.add(key);
+				tools.push({
+					pluginId: plugin.id,
+					name,
+					description: tool.description,
+					route: tool.route,
+					permission: route.permission,
+					destructive: tool.destructive ?? false,
+					inputSchema: tool.input,
+					outputSchema: tool.output,
+				});
+			}
+		}
+
+		const addManifestTools = (id: string, mcp: PluginMcpManifestConfig | undefined) => {
+			if (pluginId && id !== pluginId) return;
+			for (const tool of mcp?.tools ?? []) {
+				const key = `${id}__${tool.name}`;
+				const routeMeta = this.getPluginRouteMeta(id, tool.route);
+				if (
+					seen.has(key) ||
+					!routeMeta ||
+					routeMeta.public ||
+					routeMeta.permission !== tool.permission ||
+					!(tool.permission in Permissions)
+				) {
+					continue;
+				}
+				seen.add(key);
+				tools.push({
+					pluginId: id,
+					name: tool.name,
+					description: tool.description,
+					route: tool.route,
+					permission: tool.permission,
+					destructive: tool.destructive,
+					inputSchema: z.fromJSONSchema({ ...tool.inputSchema }),
+					outputSchema: tool.outputSchema ? z.fromJSONSchema({ ...tool.outputSchema }) : undefined,
+				});
+			}
+		};
+
+		for (const entry of this.sandboxedPluginEntries) addManifestTools(entry.id, entry.mcp);
+		for (const [id, manifest] of marketplaceManifestCache) addManifestTools(id, manifest.mcp);
+
+		return tools;
+	}
+
+	async getEnabledPluginMcpTools() {
+		const [tools, states] = await Promise.all([
+			this.getPluginMcpTools(),
+			new PluginStateRepository(this.db).getAll(),
+		]);
+		const stateByPlugin = new Map(states.map((state) => [state.pluginId, state]));
+		return tools.filter((tool) => {
+			const state = stateByPlugin.get(tool.pluginId);
+			if (
+				!state?.mcpToolsEnabled ||
+				state.status !== "active" ||
+				!this.isPluginEnabled(tool.pluginId)
+			) {
+				return false;
+			}
+			const consented = state.mcpToolsConsent;
+			return consented === this.serializePluginMcpConsent(tools, tool.pluginId);
+		});
+	}
+
+	serializePluginMcpConsent(
+		tools: Awaited<ReturnType<EmDashRuntime["getPluginMcpTools"]>>,
+		pluginId: string,
+	): string {
+		return JSON.stringify(
+			tools
+				.filter((tool) => tool.pluginId === pluginId)
+				.map((tool) => ({
+					name: tool.name,
+					description: tool.description,
+					route: tool.route,
+					permission: tool.permission,
+					destructive: tool.destructive,
+					inputSchema: z.toJSONSchema(tool.inputSchema, { target: "draft-7" }),
+					...(tool.outputSchema
+						? { outputSchema: z.toJSONSchema(tool.outputSchema, { target: "draft-7" }) }
+						: {}),
+				}))
+				.toSorted((a, b) => a.name.localeCompare(b.name)),
+		);
+	}
+
+	async handlePluginMcpTool(
+		pluginId: string,
+		toolName: string,
+		route: string,
+		input: unknown,
+		actorId: string,
+		request: Request,
+	) {
+		const requestMeta = extractRequestMeta(request, getTrustedProxyHeaders(this.config));
+		const audit = new AuditRepository(this.db);
+		const headers = new Headers(request.headers);
+		headers.delete("content-length");
+		headers.delete("content-encoding");
+		const internalRequest = new Request(request.url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(input),
+		});
+		const result = await this.handlePluginApiRoute(pluginId, "POST", route, internalRequest);
+		await audit.log({
+			actorId,
+			actorIp: requestMeta.ip ?? undefined,
+			action: "plugin_tool_invoke",
+			resourceType: "plugin_mcp_tool",
+			resourceId: `${pluginId}__${toolName}`,
+			details: { pluginId, tool: toolName, route },
+			status: result.success ? "success" : "failure",
+		});
+		return result;
+	}
+
+	async handlePluginMcpDenied(
+		pluginId: string,
+		toolName: string,
+		route: string,
+		actorId: string,
+		request: Request,
+		reason: string,
+	): Promise<void> {
+		const requestMeta = extractRequestMeta(request, getTrustedProxyHeaders(this.config));
+		await new AuditRepository(this.db).log({
+			actorId,
+			actorIp: requestMeta.ip ?? undefined,
+			action: "plugin_tool_invoke",
+			resourceType: "plugin_mcp_tool",
+			resourceId: `${pluginId}__${toolName}`,
+			details: { pluginId, tool: toolName, route, reason },
+			status: "denied",
+		});
+	}
+
 	// =========================================================================
 	// Sandboxed Plugin Helpers
 	// =========================================================================