emdash 0.29.0 → 0.30.0

package/src/astro/integration/runtime.ts

@@ -13,8 +13,10 @@ import type { MediaProviderDescriptor } from "../../media/types.js";
 import type { ObjectCacheDescriptor } from "../../object-cache/types.js";
 import type {
 	FieldWidgetConfig,
+	PluginMcpManifestConfig,
 	PortableTextBlockConfig,
 	ResolvedPlugin,
+	SettingField,
 } from "../../plugins/types.js";
 import type { ExperimentalConfig } from "../../registry/types.js";
 import type { StorageDescriptor } from "../storage/types.js";
@@ -103,6 +105,8 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
 	adminPages?: PluginAdminPage[];
 	/** Dashboard widgets */
 	adminWidgets?: PluginDashboardWidget[];
+	/** Settings schema for the auto-generated admin settings form */
+	settingsSchema?: Record<string, SettingField>;
 	/**
 	 * Portable Text block types this plugin contributes to the editor.
 	 * Declarative (Block Kit) — surfaced in the admin slash menu and consumed
@@ -131,6 +135,8 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
 	 * Sandboxed plugins can only access declared collections.
 	 */
 	storage?: Record<string, StorageCollectionDeclaration>;
+	/** Serialized MCP declarations emitted by the plugin build. */
+	mcp?: PluginMcpManifestConfig;
 }
 
 /**

package/src/astro/integration/virtual-modules.ts

@@ -69,6 +69,9 @@ export const RESOLVED_VIRTUAL_WAIT_UNTIL_ID = "\0" + VIRTUAL_WAIT_UNTIL_ID;
 export const VIRTUAL_SCHEDULER_ID = "virtual:emdash/scheduler";
 export const RESOLVED_VIRTUAL_SCHEDULER_ID = "\0" + VIRTUAL_SCHEDULER_ID;
 
+export const VIRTUAL_ENV_ID = "virtual:emdash/env";
+export const RESOLVED_VIRTUAL_ENV_ID = "\0" + VIRTUAL_ENV_ID;
+
 /**
  * Generates the config virtual module.
  */
@@ -84,13 +87,18 @@ export function generateConfigModule(serializableConfig: Record<string, unknown>
  * the generator re-exports it so middleware can ask for a per-request Kysely
  * (used for D1 Sessions API, bookmark cookies, read-replica routing). Other
  * adapters get a stub that returns null.
+ *
+ * Adapters independently opt into the cold-start coalescing dialect. Keeping
+ * this capability explicit prevents bundlers from probing exports that do not
+ * exist on SQLite, libSQL, PostgreSQL, or other adapters.
  */
 export function generateDialectModule(opts: {
 	entrypoint?: string;
 	type?: string;
 	supportsRequestScope: boolean;
+	supportsCoalescing: boolean;
 }): string {
-	const { entrypoint, supportsRequestScope } = opts;
+	const { entrypoint, supportsRequestScope, supportsCoalescing } = opts;
 	if (!entrypoint) {
 		return [
 			`export const createDialect = undefined;`,
@@ -101,16 +109,16 @@ export function generateDialectModule(opts: {
 	}
 	const type = opts.type ?? "sqlite";
 
-	// Namespace access (not a named re-export) so backends that don't export
-	// createCoalescingDialect yield `undefined` rather than a build error.
-	const coalescingReExport = `import * as _dialectModule from "${entrypoint}";
-export const createCoalescingDialect = _dialectModule.createCoalescingDialect;`;
+	const coalescingExport = supportsCoalescing
+		? `import { createCoalescingDialect as _createCoalescingDialect } from "${entrypoint}";
+export const createCoalescingDialect = _createCoalescingDialect;`
+		: `export const createCoalescingDialect = undefined;`;
 
 	if (supportsRequestScope) {
 		return `
 import { createDialect as _createDialect } from "${entrypoint}";
 export { createRequestScopedDb } from "${entrypoint}";
-${coalescingReExport}
+${coalescingExport}
 export const createDialect = _createDialect;
 export const dialectType = ${JSON.stringify(type)};
 `;
@@ -118,7 +126,7 @@ export const dialectType = ${JSON.stringify(type)};
 
 	return `
 import { createDialect as _createDialect } from "${entrypoint}";
-${coalescingReExport}
+${coalescingExport}
 export const createDialect = _createDialect;
 export const dialectType = ${JSON.stringify(type)};
 export const createRequestScopedDb = (_opts) => null;
@@ -271,6 +279,7 @@ export function generatePluginsModule(descriptors: PluginDescriptor[]): string {
 					storage: descriptor.storage,
 					adminPages: descriptor.adminPages,
 					adminWidgets: descriptor.adminWidgets,
+					settingsSchema: descriptor.settingsSchema,
 					portableTextBlocks: descriptor.portableTextBlocks,
 					fieldWidgets: descriptor.fieldWidgets,
 				})})`,
@@ -469,6 +478,25 @@ export function generateWaitUntilModule(adapterName: string | undefined): string
 	return `export const waitUntil = undefined;`;
 }
 
+/**
+ * Generates the env virtual module.
+ *
+ * Under @astrojs/cloudflare, re-exports `env` from `cloudflare:workers` so
+ * routes can read Worker bindings/secrets without touching
+ * `Astro.locals.runtime.env`, which Astro 6+ removed (accessing it throws
+ * rather than returning undefined, so `locals.runtime?.env` optional-chaining
+ * doesn't help -- see #1736). For any other adapter, exports `undefined` so
+ * callers fall back to `import.meta.env`. Mirrors generateWaitUntilModule:
+ * core stays adapter-agnostic, with no direct `cloudflare:workers` import
+ * that would fail to resolve under a Node build.
+ */
+export function generateEnvModule(adapterName: string | undefined): string {
+	if (adapterName === "@astrojs/cloudflare") {
+		return `export { env } from "cloudflare:workers";`;
+	}
+	return `export const env = undefined;`;
+}
+
 /**
  * Generates the scheduler virtual module.
  *
@@ -598,12 +626,14 @@ function resolveModulePathFromProject(specifier: string, projectRoot: string): s
 /**
  * Generates the sandboxed plugins module.
  * Resolves plugin entrypoints to files, reads them, and embeds the code.
+ * Notifies the caller about each resolved entry so build tools can watch it.
  *
  * At runtime, middleware uses SandboxRunner to load these into isolates.
  */
 export function generateSandboxedPluginsModule(
 	sandboxed: PluginDescriptor[],
 	projectRoot: string,
+	onEntryResolved?: (filePath: string) => void,
 ): string {
 	if (sandboxed.length === 0) {
 		return `
@@ -630,6 +660,8 @@ export const sandboxedPlugins = [];
 			);
 		}
 
+		onEntryResolved?.(filePath);
+
 		const code = readFileSync(filePath, "utf-8");
 
 		// Create the plugin entry with embedded code and sandbox config
@@ -640,8 +672,10 @@ export const sandboxedPlugins = [];
     capabilities: ${JSON.stringify(descriptor.capabilities ?? [])},
     allowedHosts: ${JSON.stringify(descriptor.allowedHosts ?? [])},
     storage: ${JSON.stringify(descriptor.storage ?? {})},
+    mcp: ${JSON.stringify(descriptor.mcp)},
     adminPages: ${JSON.stringify(descriptor.adminPages ?? [])},
     adminWidgets: ${JSON.stringify(descriptor.adminWidgets ?? [])},
+    settingsSchema: ${JSON.stringify(descriptor.settingsSchema)},
     portableTextBlocks: ${JSON.stringify(descriptor.portableTextBlocks ?? [])},
     fieldWidgets: ${JSON.stringify(descriptor.fieldWidgets ?? [])},
     adminEntry: ${JSON.stringify(descriptor.adminEntry)},

package/src/astro/integration/vite-config.ts

@@ -46,9 +46,12 @@ import {
 	RESOLVED_VIRTUAL_WAIT_UNTIL_ID,
 	VIRTUAL_SCHEDULER_ID,
 	RESOLVED_VIRTUAL_SCHEDULER_ID,
+	VIRTUAL_ENV_ID,
+	RESOLVED_VIRTUAL_ENV_ID,
 	generateSeedModule,
 	generateWaitUntilModule,
 	generateSchedulerModule,
+	generateEnvModule,
 	generateConfigModule,
 	generateDialectModule,
 	generateStorageModule,
@@ -227,6 +230,9 @@ export function createVirtualModulesPlugin(
 			if (id === VIRTUAL_SCHEDULER_ID) {
 				return RESOLVED_VIRTUAL_SCHEDULER_ID;
 			}
+			if (id === VIRTUAL_ENV_ID) {
+				return RESOLVED_VIRTUAL_ENV_ID;
+			}
 		},
 		load(id: string) {
 			if (id === RESOLVED_VIRTUAL_CONFIG_ID) {
@@ -239,6 +245,7 @@ export function createVirtualModulesPlugin(
 					entrypoint: resolvedConfig.database?.entrypoint,
 					type: resolvedConfig.database?.type,
 					supportsRequestScope: resolvedConfig.database?.supportsRequestScope ?? false,
+					supportsCoalescing: resolvedConfig.database?.supportsCoalescing ?? false,
 				});
 			}
 			// Generate a module that statically imports the configured storage
@@ -271,7 +278,11 @@ export function createVirtualModulesPlugin(
 			if (id === RESOLVED_VIRTUAL_SANDBOXED_PLUGINS_ID) {
 				// Pass project root for proper module resolution
 				const projectRoot = fileURLToPath(astroConfig.root);
-				return generateSandboxedPluginsModule(resolvedConfig.sandboxed ?? [], projectRoot);
+				return generateSandboxedPluginsModule(
+					resolvedConfig.sandboxed ?? [],
+					projectRoot,
+					(filePath) => this.addWatchFile(filePath),
+				);
 			}
 			// Generate auth module that statically imports the configured auth provider
 			if (id === RESOLVED_VIRTUAL_AUTH_ID) {
@@ -317,6 +328,11 @@ export function createVirtualModulesPlugin(
 				const schedulerCommand = astroCommand === "dev" ? "serve" : "build";
 				return generateSchedulerModule(astroConfig.adapter?.name, schedulerCommand);
 			}
+			// Generate env module — re-exports cloudflare:workers' env under
+			// the Cloudflare adapter, undefined otherwise (#1736).
+			if (id === RESOLVED_VIRTUAL_ENV_ID) {
+				return generateEnvModule(astroConfig.adapter?.name);
+			}
 		},
 	};
 }

package/src/astro/middleware/auth.ts

@@ -60,13 +60,7 @@ function isUnsafeMethod(method: string): boolean {
 }
 
 function csrfRejectedResponse(): Response {
-	return new Response(
-		JSON.stringify({ error: { code: "CSRF_REJECTED", message: "Missing required header" } }),
-		{
-			status: 403,
-			headers: { "Content-Type": "application/json", ...MW_CACHE_HEADERS },
-		},
-	);
+	return apiError("CSRF_REJECTED", "Missing required header", 403);
 }
 
 function mcpUnauthorizedResponse(
@@ -74,16 +68,13 @@ function mcpUnauthorizedResponse(
 	config?: Parameters<typeof getPublicOrigin>[1],
 ): Response {
 	const origin = getPublicOrigin(url, config);
-	return Response.json(
-		{ error: { code: "NOT_AUTHENTICATED", message: "Not authenticated" } },
-		{
-			status: 401,
-			headers: {
-				"WWW-Authenticate": `Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
-				...MW_CACHE_HEADERS,
-			},
-		},
+	const response = apiError("NOT_AUTHENTICATED", "Not authenticated", 401);
+	// Preserve the OAuth discovery header so MCP clients can find the auth server.
+	response.headers.set(
+		"WWW-Authenticate",
+		`Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
 	);
+	return response;
 }
 
 /**
@@ -224,15 +215,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 		if (method !== "GET" && method !== "HEAD" && method !== "OPTIONS") {
 			const csrfHeader = context.request.headers.get("X-EmDash-Request");
 			if (csrfHeader !== "1") {
-				return new Response(
-					JSON.stringify({
-						error: { code: "CSRF_REJECTED", message: "Missing required header" },
-					}),
-					{
-						status: 403,
-						headers: { "Content-Type": "application/json", ...MW_CACHE_HEADERS },
-					},
-				);
+				return apiError("CSRF_REJECTED", "Missing required header", 403);
 			}
 		}
 		return next();
@@ -250,20 +233,16 @@ export const onRequest = defineMiddleware(async (context, next) => {
 	const bearerResult = await handleBearerAuth(context);
 
 	if (bearerResult === "invalid") {
-		const headers: Record<string, string> = {
-			"Content-Type": "application/json",
-			...MW_CACHE_HEADERS,
-		};
+		const response = apiError("INVALID_TOKEN", "Invalid or expired token", 401);
 		// Add WWW-Authenticate header on MCP endpoint 401s to trigger OAuth discovery
 		if (url.pathname === "/_emdash/api/mcp") {
 			const origin = getPublicOrigin(url, context.locals.emdash?.config);
-			headers["WWW-Authenticate"] =
-				`Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`;
+			response.headers.set(
+				"WWW-Authenticate",
+				`Bearer resource_metadata="${origin}/.well-known/oauth-protected-resource"`,
+			);
 		}
-		return new Response(
-			JSON.stringify({ error: { code: "INVALID_TOKEN", message: "Invalid or expired token" } }),
-			{ status: 401, headers },
-		);
+		return response;
 	}
 
 	const isTokenAuth = bearerResult === "authenticated";
@@ -308,7 +287,10 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				"Content-Security-Policy",
 				buildEmDashCsp(
 					context.locals.emdash?.config.experimental?.registry,
-					getConfiguredStorageEndpoint(context.locals.emdash?.config.storage),
+					getConfiguredStorageEndpoint(
+						context.locals.emdash?.config.storage,
+						context.locals.emdash?.storage,
+					),
 				),
 			);
 		}
@@ -323,7 +305,10 @@ export const onRequest = defineMiddleware(async (context, next) => {
 			"Content-Security-Policy",
 			buildEmDashCsp(
 				context.locals.emdash?.config.experimental?.registry,
-				getConfiguredStorageEndpoint(context.locals.emdash?.config.storage),
+				getConfiguredStorageEndpoint(
+					context.locals.emdash?.config.storage,
+					context.locals.emdash?.storage,
+				),
 			),
 		);
 	}
@@ -378,15 +363,28 @@ async function handleEmDashAuth(
 }
 
 /**
- * Soft auth for plugin routes: resolve user from Bearer token or session if present,
- * but never block unauthenticated requests. The catch-all handler checks route
- * metadata to decide whether auth is required (public vs private routes).
+ * Plugin-route auth. Resolves the user in three steps, stopping at the first that
+ * applies:
+ *
+ * 1. Bearer token (all modes). A valid token authenticates; an invalid/expired one
+ *    returns 401 (we never silently downgrade a bad token to anonymous).
+ * 2. External provider — only for a *private* route in production external-auth
+ *    mode. Here `handleExternalAuth` is the sole authority: the provider (e.g.
+ *    Cloudflare Access) is re-verified on every request, so it hard-blocks with
+ *    401 on failure. It does persist an EmDash session (so public pages can
+ *    identify the user), but on these routes that session is deliberately NOT
+ *    consulted as a fallback — the provider check is authoritative every time.
+ * 3. Session — everything else (non-external mode, DEV, and all public routes).
+ *    This is soft: it sets `locals.user` if a session exists but never blocks.
+ *
+ * Public routes are always allowed through. The catch-all handler still enforces
+ * the `plugins:manage` permission and CSRF for private invocations.
  */
 async function handlePluginRouteAuth(
 	context: Parameters<Parameters<typeof defineMiddleware>[0]>[0],
 	next: Parameters<Parameters<typeof defineMiddleware>[0]>[1],
 ): Promise<Response> {
-	const { locals } = context;
+	const { locals, url } = context;
 	const { emdash } = locals;
 
 	try {
@@ -399,19 +397,22 @@ async function handlePluginRouteAuth(
 		if (bearerResult === "invalid") {
 			// A token was presented but is invalid/expired — return 401 so the
 			// caller knows their token is bad (don't silently downgrade to no-auth).
-			return new Response(
-				JSON.stringify({ error: { code: "INVALID_TOKEN", message: "Invalid or expired token" } }),
-				{
-					status: 401,
-					headers: { "Content-Type": "application/json", ...MW_CACHE_HEADERS },
-				},
-			);
+			return apiError("INVALID_TOKEN", "Invalid or expired token", 401);
 		}
-		// "none" — no token presented, try session auth below.
+		// "none" — no token presented, try external/session auth below.
 	} catch (error) {
 		console.error("Plugin route bearer auth error:", error);
 	}
 
+	const authMode = getAuthMode(emdash?.config);
+	if (
+		authMode.type === "external" &&
+		!import.meta.env.DEV &&
+		!isPublicPluginApiRoute(url.pathname, emdash)
+	) {
+		return handleExternalAuth(context, next, authMode, true);
+	}
+
 	try {
 		// Try session auth (sets locals.user if session exists)
 		const { session } = context;
@@ -431,6 +432,17 @@ async function handlePluginRouteAuth(
 	return next();
 }
 
+function isPublicPluginApiRoute(pathname: string, emdash: EmDashHandlers | undefined): boolean {
+	const prefix = "/_emdash/api/plugins/";
+	const route = pathname.slice(prefix.length);
+	const slashIndex = route.indexOf("/");
+	if (slashIndex <= 0 || !emdash?.getPluginRouteMeta) return false;
+
+	return (
+		emdash.getPluginRouteMeta(route.slice(0, slashIndex), route.slice(slashIndex))?.public === true
+	);
+}
+
 /**
  * Soft auth check for public routes with edit mode cookie.
  * Checks the session and sets locals.user if valid, but never blocks the request.
@@ -662,10 +674,7 @@ async function handlePasskeyAuth(
 
 		if (!sessionUser?.id) {
 			if (isApiRoute) {
-				return Response.json(
-					{ error: { code: "NOT_AUTHENTICATED", message: "Not authenticated" } },
-					{ status: 401, headers: MW_CACHE_HEADERS },
-				);
+				return apiError("NOT_AUTHENTICATED", "Not authenticated", 401);
 			}
 			const loginUrl = new URL("/_emdash/admin/login", getPublicOrigin(url, emdash?.config));
 			loginUrl.searchParams.set("redirect", url.pathname);
@@ -680,10 +689,7 @@ async function handlePasskeyAuth(
 			// User no longer exists - clear session
 			session?.destroy();
 			if (isApiRoute) {
-				return Response.json(
-					{ error: { code: "NOT_FOUND", message: "User not found" } },
-					{ status: 401, headers: MW_CACHE_HEADERS },
-				);
+				return apiError("NOT_FOUND", "User not found", 401);
 			}
 			const loginUrl = new URL("/_emdash/admin/login", getPublicOrigin(url, emdash?.config));
 			return context.redirect(loginUrl.toString());
@@ -764,9 +770,6 @@ const SCOPE_RULES: Array<[prefix: string, method: string, scope: string]> = [
 	// settings:manage are not rejected at the middleware level.
 	["/_emdash/api/settings", "GET", "settings:read"],
 	["/_emdash/api/settings", "WRITE", "settings:manage"],
-
-	// MCP endpoint — scopes enforced per-tool inside mcp/server.ts
-	["/_emdash/api/mcp", "*", "content:read"],
 ];
 
 const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
@@ -785,6 +788,11 @@ function enforceTokenScope(
 	// Session auth — implicit full access, no scope restrictions
 	if (!tokenScopes) return null;
 
+	// MCP is authenticated here, but each tool enforces its own scope. A
+	// blanket content:read/admin requirement would prevent plugin-scoped tokens
+	// from reaching `mcp/server.ts`, where the actual tool policy lives.
+	if (pathname === MCP_ENDPOINT_PATH) return null;
+
 	const isWrite = WRITE_METHODS.has(method);
 
 	for (const [prefix, ruleMethod, scope] of SCOPE_RULES) {
@@ -795,28 +803,12 @@ function enforceTokenScope(
 		if (ruleMethod === "*" || (ruleMethod === "WRITE" && isWrite) || ruleMethod === method) {
 			if (hasScope(tokenScopes, scope)) return null;
 
-			return new Response(
-				JSON.stringify({
-					error: {
-						code: "INSUFFICIENT_SCOPE",
-						message: `Token lacks required scope: ${scope}`,
-					},
-				}),
-				{ status: 403, headers: { "Content-Type": "application/json", ...MW_CACHE_HEADERS } },
-			);
+			return apiError("INSUFFICIENT_SCOPE", `Token lacks required scope: ${scope}`, 403);
 		}
 	}
 
 	// No rule matched — default to admin scope (fail-closed)
 	if (hasScope(tokenScopes, "admin")) return null;
 
-	return new Response(
-		JSON.stringify({
-			error: {
-				code: "INSUFFICIENT_SCOPE",
-				message: "Token lacks required scope: admin",
-			},
-		}),
-		{ status: 403, headers: { "Content-Type": "application/json", ...MW_CACHE_HEADERS } },
-	);
+	return apiError("INSUFFICIENT_SCOPE", "Token lacks required scope: admin", 403);
 }

package/src/astro/middleware/csp.ts

@@ -13,6 +13,7 @@
  * are configured, in which case those origins are allowed too.
  */
 import type { RegistryConfigInput } from "../../registry/types.js";
+import type { Storage } from "../../storage/types.js";
 import type { StorageDescriptor } from "../storage/types.js";
 
 /** Entrypoint constant used by the `s3()` adapter (see `astro/storage/adapters.ts`). */
@@ -28,10 +29,12 @@ const S3_ADAPTER_ENTRYPOINT = "emdash/storage/s3";
  * `endpoint` -- from the matching `S3_*` env var at runtime (see
  * `storage/s3.ts`'s `resolveS3Config`). A site configured as `s3({ ... })`
  * with only `S3_ENDPOINT` set has no `endpoint` in the descriptor's config,
- * so fall back to that env var for S3-adapter storage before giving up.
+ * so fall back to that env var for S3-adapter storage. Custom adapters can
+ * expose their runtime upload origin through `getClientUploadOrigin()`.
  */
 export function getConfiguredStorageEndpoint(
 	storage: StorageDescriptor | undefined,
+	runtimeStorage?: Pick<Storage, "getClientUploadOrigin"> | null,
 ): string | undefined {
 	const config = storage?.config;
 	if (typeof config === "object" && config !== null && "endpoint" in config) {
@@ -45,7 +48,7 @@ export function getConfiguredStorageEndpoint(
 		if (envEndpoint) return envEndpoint;
 	}
 
-	return undefined;
+	return runtimeStorage?.getClientUploadOrigin?.();
 }
 
 function getRegistryAggregatorOrigin(

package/src/astro/middleware.ts

@@ -47,7 +47,7 @@ import {
 import { setI18nConfig } from "../i18n/config.js";
 import type { Database, Storage } from "../index.js";
 import { createPublicMediaUrlResolver } from "../media/url.js";
-import type { SandboxRunner } from "../plugins/sandbox/types.js";
+import type { SandboxRunnerFactory } from "../plugins/sandbox/types.js";
 import type { ResolvedPlugin } from "../plugins/types.js";
 import { invalidateUrlPatternCache } from "../query.js";
 import {
@@ -67,6 +67,9 @@ import { createPublicPluginApiRouteHandler } from "./public-plugin-api-routes.js
 import { resolveSessionUser } from "./session-user.js";
 import type { EmDashHandlers } from "./types.js";
 
+// Public type for withEmDashRuntime() consumers (queue/scheduled handlers).
+export type { EmDashRuntime } from "../emdash-runtime.js";
+
 /**
  * Runtime init lock reclaim deadline. Must be strictly larger than the db
  * init deadline: this lock wraps EmDashRuntime.create() → getDatabase() →
@@ -200,19 +203,7 @@ function buildDependencies(config: EmDashConfig): RuntimeDependencies {
 		sandboxEnabled: sandboxModule.sandboxEnabled as boolean,
 		sandboxBypassed: (sandboxModule.sandboxBypassed as boolean) ?? false,
 		sandboxedPluginEntries: (virtualSandboxedPlugins as SandboxedPluginEntry[]) || [],
-		createSandboxRunner: sandboxModule.createSandboxRunner as
-			| ((opts: {
-					db: Kysely<Database>;
-					mediaStorage?: {
-						upload(options: {
-							key: string;
-							body: Uint8Array;
-							contentType: string;
-						}): Promise<unknown>;
-						delete(key: string): Promise<unknown>;
-					};
-			  }) => SandboxRunner)
-			| null,
+		createSandboxRunner: sandboxModule.createSandboxRunner as SandboxRunnerFactory | null,
 		mediaProviderEntries: (virtualMediaProviders as MediaProviderEntry[]) || [],
 	};
 	/* eslint-enable typescript-eslint/no-unsafe-type-assertion */
@@ -285,22 +276,81 @@ export async function runScheduledTasks(
 ): Promise<{ published: PublishedRef[] }> {
 	const config = getConfig();
 	if (!config) return { published: [] };
+	return runOutsideRequest(config, (runtime) => runtime.runScheduledTasks(options));
+}
+
+/**
+ * Run a callback against the EmDash runtime outside any HTTP request — from a
+ * Cloudflare Queue consumer, a `scheduled()` handler, or any other
+ * platform-event handler that has no request and therefore no `locals.emdash`.
+ *
+ * Resolves the same cached runtime singleton request handlers use, so hooks,
+ * plugin state, and storage all behave exactly as they do during a request.
+ * A typical queue consumer finishes a job by calling back into a plugin route:
+ *
+ * ```ts
+ * import { withEmDashRuntime } from "emdash/middleware";
+ *
+ * async function queue(batch: MessageBatch) {
+ * 	await withEmDashRuntime(async (runtime) => {
+ * 		for (const message of batch.messages) {
+ * 			await runtime.handlePluginApiRoute(
+ * 				"my-plugin",
+ * 				"POST",
+ * 				"/finishJob",
+ * 				new Request("https://internal/", {
+ * 					method: "POST",
+ * 					body: JSON.stringify(message.body),
+ * 				}),
+ * 			);
+ * 		}
+ * 	});
+ * }
+ * ```
+ *
+ * Server-only and fully trusted: the callback gets the raw runtime with no
+ * auth or CSRF checks, same trust level as plugin cron. Never expose it to
+ * user input without validating that input yourself.
+ *
+ * Throws when EmDash is not configured (no `emdash()` Astro integration).
+ */
+export async function withEmDashRuntime<T>(
+	run: (runtime: EmDashRuntime) => T | Promise<T>,
+): Promise<T> {
+	const config = getConfig();
+	if (!config) {
+		throw new Error(
+			"EmDash is not configured — withEmDashRuntime() requires the emdash() Astro integration.",
+		);
+	}
+	return runOutsideRequest(config, async (runtime) => run(runtime));
+}
+
+/**
+ * Shared plumbing for request-free entry points (`runScheduledTasks`,
+ * `withEmDashRuntime`): resolve the runtime singleton, then run the callback
+ * under an event-scoped db connection when the adapter needs one.
+ *
+ * Connection-backed adapters (e.g. Postgres over Hyperdrive) cannot reuse
+ * the per-isolate singleton from a platform event: its socket belongs to the
+ * request that opened it, and workerd rejects cross-event I/O. Open an
+ * event-scoped connection and run the callback under it in ALS — the
+ * runtime's db getter, the cron executor, and plugin contexts all resolve
+ * the connection from ALS — then close it. Gated on the adapter being
+ * connection-backed (it exposes `close()`); stateless adapters (D1, Node
+ * SQLite) return null or a close-less scope and keep using the singleton.
+ */
+async function runOutsideRequest<T>(
+	config: EmDashConfig,
+	fn: (runtime: EmDashRuntime) => Promise<T>,
+): Promise<T> {
 	const runtime = await getRuntime(config);
 
-	// Connection-backed adapters (e.g. Postgres over Hyperdrive) cannot reuse
-	// the per-isolate singleton from a Cron Trigger: its socket belongs to the
-	// request that opened it, and workerd rejects cross-event I/O. Open an
-	// event-scoped connection for the sweep and run the batch under it in ALS —
-	// the runtime's db getter, the cron executor, and plugin cron contexts all
-	// resolve the connection from ALS — then close it. Gated on the adapter
-	// being connection-backed (it exposes `close()`); stateless adapters (D1,
-	// Node SQLite) return null or a close-less scope and keep using the
-	// singleton, so their cron path is unchanged.
 	const scoped = createRequestScopedDb({
 		config: config.database?.config,
 		isAuthenticated: false,
-		// The sweep publishes and cleans up — a write workload — so a
-		// connection-backed adapter routes it to the primary.
+		// Event handlers publish, clean up, or run jobs — a write workload —
+		// so a connection-backed adapter routes them to the primary.
 		isWrite: true,
 		cookies: NOOP_COOKIE_JAR,
 		url: CRON_EVENT_URL,
@@ -308,7 +358,7 @@ export async function runScheduledTasks(
 	if (!scoped?.close) {
 		// Stateless adapter (or no per-request scoping): the singleton is safe
 		// outside a request. Any close-less scope created above is discarded.
-		return runtime.runScheduledTasks(options);
+		return fn(runtime);
 	}
 
 	const parent = getRequestContext();
@@ -316,19 +366,19 @@ export async function runScheduledTasks(
 		? { ...parent, db: scoped.db }
 		: { editMode: false, db: scoped.db, metrics: createRequestMetrics(performance.now()) };
 	try {
-		return await runWithContext(ctx, () => runtime.runScheduledTasks(options));
+		return await runWithContext(ctx, () => fn(runtime));
 	} finally {
-		// Guard both so a throw in teardown can't mask the sweep result or skip
-		// close() and leak the connection. Mirrors closeSafely() in scoped-db.ts.
+		// Guard both so a throw in teardown can't mask the callback result or
+		// skip close() and leak the connection. Mirrors closeSafely() in scoped-db.ts.
 		try {
 			scoped.commit();
 		} catch (error) {
-			console.error("[scheduled] request-scoped db commit failed:", error);
+			console.error("[emdash] event-scoped db commit failed:", error);
 		}
 		try {
 			scoped.close();
 		} catch (error) {
-			console.error("[scheduled] request-scoped db close failed:", error);
+			console.error("[emdash] event-scoped db close failed:", error);
 		}
 	}
 }
@@ -734,6 +784,11 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					handlePluginApiRoute: runtime.handlePluginApiRoute.bind(runtime),
 					handlePublicPluginApiRoute: createPublicPluginApiRouteHandler(runtime),
 					getPluginRouteMeta: runtime.getPluginRouteMeta.bind(runtime),
+					getPluginMcpTools: runtime.getPluginMcpTools.bind(runtime),
+					getEnabledPluginMcpTools: runtime.getEnabledPluginMcpTools.bind(runtime),
+					serializePluginMcpConsent: runtime.serializePluginMcpConsent.bind(runtime),
+					handlePluginMcpTool: runtime.handlePluginMcpTool.bind(runtime),
+					handlePluginMcpDenied: runtime.handlePluginMcpDenied.bind(runtime),
 
 					// Media provider methods
 					getMediaProvider: runtime.getMediaProvider.bind(runtime),