@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

package/dist/handler/create-orchestrator.js

@@ -0,0 +1,1599 @@
+// createOrchestrator — the Web-standard `(Request) => Promise<Response>` face of
+// this package, for mounting the orchestrator at a route in someone else's
+// Next.js app (`app/api/avocado/[[...path]]/route.ts`). apps/orchestrator is the
+// same brain behind Fastify; the two wrappers are peers.
+//
+// It lived in packages/site-sdk until the package boundary was drawn. It never
+// touched anything else in that package — no React, no Next — so all it did
+// there was make a published package reach 78 symbols across 25 internal
+// modules of another published package, through orchestrator-core's
+// `"./*": "./src/*.ts"` wildcard. Next to the code it wraps, those are relative
+// imports, and core can publish two subpaths instead of 110. Reached by
+// integrators as `@avocadostudio-ai/site-sdk/server`, which is now a re-export.
+//
+// Routes answered: see SUPPORTED_ROUTES below, which is the 405 body and is
+// kept honest by library-mode-routes.test.ts — it parses the branches out of
+// this file and diffs them against the endpoints apps/editor actually calls.
+//
+// Storage note: image upload writes to local disk (POST /image/upload + GET
+// /generated-images/:fileName) — POC-grade, see config.imageDir.
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import { resolve, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { operationSchema, blockManifestSchema, siteConfigSchema, declareBlockCatalogue, undeclaredBlockTypes } from "@avocadostudio-ai/shared";
+import { chatRequestBodySchema } from "../nlp/intent-detection.js";
+import { applyOpsAtomically, pickFocusBlockId, pickUpdatedSlug, toErrorDetail, classifyGuardrailError } from "../ops/ops-engine.js";
+import { runChatStream, formatSseFrame } from "../http/chat-stream.js";
+import { ResumableStreamStore, runResumableChatStream, TooManyPendingStreamsError, isTerminalState } from "../http/chat-stream-resumable.js";
+import { runChatPipeline, collectMentionedSlugsFromOps } from "../chat/chat-pipeline.js";
+import { createChatTelemetryStore } from "../telemetry/chat-telemetry.js";
+import { createToolRuntime } from "../tools/runtime.js";
+import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState, normalizeSiteId, publishStatusBySession, pushPublishLogEntry, persistenceHealth, persistenceWarning } from "../state/session-state.js";
+import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction } from "../http/history-actions.js";
+import { whoamiAction } from "../http/session-actions.js";
+import { blocksManifestAction } from "../http/blocks-actions.js";
+import { screenshotAction } from "../http/screenshot-actions.js";
+import { fileImageStore, formatImageChatFrame, generateImageAction, imageChatAction, imageChatStreamAction, interpretImageAction, validateImageChatRequest } from "../http/image-generate-actions.js";
+import { transcribeAudioAction, transcriptionUnavailable, validateAudioInput } from "../http/audio-actions.js";
+import { formatVariationFrame, parseVariationRequest, scopeVariationSession, variationsAction, variationsStreamAction } from "../http/variations-actions.js";
+import { opsDryRunAction, describeAppliedOps } from "../http/ops-actions.js";
+import { describeDraft } from "../http/draft-provenance.js";
+import { buildPublishSummary, publishDiffAction, publishLogAction, publishStatusAction } from "../http/publish-actions.js";
+import { restoreSnapshotApply, restoreSnapshotDelete, restoreSnapshotsList } from "../http/restore-actions.js";
+import { unsplashSearchAction } from "../http/unsplash-actions.js";
+import { telemetryFeedbackListAction, telemetryFeedbackSubmitAction } from "../http/telemetry-feedback-actions.js";
+import { createFeedbackStore } from "../telemetry/feedback-store.js";
+import { consoleLogger } from "../logger.js";
+import { createCmsBootstrapCache } from "../cms/bootstrap.js";
+import { resolveCapabilities } from "../cms/adapter.js";
+import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../http/access-tokens.js";
+import { checkAuth, resolveAuth } from "./auth.js";
+const defaultModelLookup = () => ({
+    openai: {
+        fast: process.env.OPENAI_MODEL_FAST ?? "gpt-4o-mini",
+        balanced: process.env.OPENAI_MODEL_BALANCED ?? "gpt-4o",
+        reasoning: process.env.OPENAI_MODEL_REASONING ?? "o1",
+        codex: process.env.OPENAI_MODEL_CODEX ?? "o3"
+    },
+    anthropic: {
+        fast: process.env.ANTHROPIC_MODEL_FAST ?? "claude-haiku-4-5-20251001",
+        balanced: process.env.ANTHROPIC_MODEL_BALANCED ?? "claude-sonnet-5",
+        reasoning: process.env.ANTHROPIC_MODEL_REASONING ?? "claude-sonnet-5",
+        codex: process.env.ANTHROPIC_MODEL_CODEX ?? "claude-opus-4-8"
+    },
+    gemini: {
+        fast: process.env.GOOGLE_GENAI_MODEL_FAST ?? "gemini-2.5-flash",
+        balanced: process.env.GOOGLE_GENAI_MODEL_BALANCED ?? "gemini-2.5-flash",
+        reasoning: process.env.GOOGLE_GENAI_MODEL_REASONING ?? "gemini-2.5-pro",
+        codex: process.env.GOOGLE_GENAI_MODEL_CODEX ?? "gemini-2.5-pro"
+    }
+});
+const defaultProviders = () => [
+    ...(process.env.OPENAI_API_KEY ? ["openai"] : []),
+    ...(process.env.ANTHROPIC_API_KEY ? ["anthropic"] : []),
+    ...(process.env.GOOGLE_GENAI_API_KEY ? ["gemini"] : [])
+];
+async function buildRuntime(config) {
+    const log = config.logger ?? consoleLogger();
+    // Register host-app block schemas BEFORE the planner ever validates ops.
+    // Done here rather than at module load so the host's overrides land on the
+    // shared globalThis registry after any transitive canonical re-registration
+    // from @avocadostudio-ai/shared has already fired.
+    if (config.registerBlocks) {
+        try {
+            config.registerBlocks();
+        }
+        catch (err) {
+            log.warn({ err: err instanceof Error ? err.message : String(err) }, "registerBlocks() threw — continuing with whatever was already registered");
+        }
+    }
+    const chatTelemetry = createChatTelemetryStore({
+        filePath: process.env.CHAT_TELEMETRY_FILE ?? "./.data/chat-telemetry.ndjson",
+        limit: Number(process.env.CHAT_TELEMETRY_LIMIT ?? 500),
+        persistEnabled: !/^(0|false|no|off)$/i.test((process.env.CHAT_TELEMETRY_PERSIST ?? "1").trim()),
+        logger: log
+    });
+    const toolRuntime = await createToolRuntime({ logger: log });
+    if (config.builtinTools) {
+        // Dynamic import so the builtins module (and its image/ + googleapis +
+        // sharp transitive deps) isn't pulled into the bundle when the consumer
+        // doesn't opt in.
+        const { registerDefaultBuiltins } = await import("../tools/builtin-registrations.js");
+        registerDefaultBuiltins(toolRuntime.registry, Array.isArray(config.builtinTools) ? { include: config.builtinTools } : {});
+    }
+    const pipelineCtx = {
+        log,
+        chatTelemetry,
+        modelLookup: config.modelLookup ?? defaultModelLookup(),
+        availableProviders: config.availableProviders ?? defaultProviders(),
+        toolRuntime
+    };
+    const ready = (async () => {
+        await loadStateFromDisk(log);
+        await chatTelemetry.loadFromDisk();
+    })();
+    const resumableStore = new ResumableStreamStore();
+    // Resolved once, here, so `/whoami` and `/status/planner` cannot answer the
+    // same question differently.
+    const capabilities = resolveCapabilities(config.adapter, config.capabilities);
+    const bootstrapCache = createCmsBootstrapCache({ capabilities: config.capabilities });
+    /*
+     * Start the adapter's page read now rather than on the first request.
+     *
+     * `ensure()` is lazy, so without this the first caller pays for the whole
+     * CMS read: Paintball Arena Bern's adapter is 45 sequential Sanity reads
+     * behind a dev-server compile, and the `whoami` an MCP agent opens with took
+     * four minutes — long enough that the host times out and the agent reports
+     * the site as down. Fire-and-forget by contract: a failed warm logs and is
+     * forgotten, and `ensure()` still does its own fetch.
+     */
+    bootstrapCache.warm(config.adapter ?? null, log);
+    return {
+        pipelineCtx,
+        ready,
+        resumableStore,
+        log,
+        adapter: config.adapter ?? null,
+        capabilities,
+        bootstrapCache
+    };
+}
+/*
+ * Takes the *resolved* CORS map rather than the raw Origin header. It used to
+ * echo the origin directly, which meant every SSE response granted a
+ * cross-origin read that `corsHeadersFor` would have refused — the allow-list
+ * governed the JSON routes and the streaming ones ignored it.
+ */
+const SSE_HEADERS = (cors) => ({
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache, no-transform",
+    "connection": "keep-alive",
+    "x-accel-buffering": "no",
+    ...cors
+});
+function corsHeadersFor(request, config) {
+    if (config.corsOrigins === null)
+        return {};
+    const origin = request.headers.get("origin") ?? "*";
+    if (config.corsOrigins === "*") {
+        return { "access-control-allow-origin": origin, "vary": "Origin" };
+    }
+    if (config.corsOrigins === undefined) {
+        /*
+         * Unset used to mean "reflect anything", which on a production domain hands
+         * every other site on the web a cross-origin read of this orchestrator. In
+         * production, unset now means *no* CORS headers: a same-origin editor mount
+         * still works (the browser never asks), and a cross-origin one has to be
+         * named. Outside production it keeps reflecting, because the editor runs on
+         * :4100 against a site on :3000 and making every developer configure that is
+         * how a safe default gets set to "*" in a hurry.
+         */
+        return isProductionEnv() ? {} : { "access-control-allow-origin": origin, "vary": "Origin" };
+    }
+    return config.corsOrigins.includes(origin)
+        ? { "access-control-allow-origin": origin, "vary": "Origin" }
+        : {};
+}
+function isProductionEnv() {
+    return (process.env.NODE_ENV ?? "").trim() === "production";
+}
+function jsonResponse(body, init = {}) {
+    return new Response(JSON.stringify(body), {
+        status: init.status ?? 200,
+        headers: { "content-type": "application/json", ...(init.cors ?? {}) }
+    });
+}
+/** Send an `ActionResult` from orchestrator-core as a `Response`. */
+/**
+ * Every path this handler answers, for the 405 body.
+ *
+ * A hand-written list of what is supported is a list of what is silently
+ * broken as soon as it drifts, and this one had already drifted: it never
+ * learned about `/history/*`, so an integrator reading the error was told undo
+ * was unavailable on a build that served it. `library-mode-routes.test.ts`
+ * parses the branches below and fails if they and this disagree, which is the
+ * only thing that keeps a list like this honest.
+ */
+const SUPPORTED_ROUTES = [
+    "GET /auth/status",
+    "POST /auth/verify",
+    "POST /chat",
+    "POST /chat/stream",
+    "POST /chat/start",
+    "GET /chat/stream",
+    "POST /chat/cancel",
+    "POST /chat/variations",
+    "POST /chat/variations/stream",
+    "POST /publish",
+    "GET /status/planner",
+    "GET /draft/pages",
+    "GET /draft/slugs",
+    "POST /draft/bootstrap",
+    "GET+PUT /draft/site-config",
+    "POST /ops",
+    "GET /history/status",
+    "GET /history/log",
+    "POST /history/undo",
+    "POST /history/redo",
+    "POST /history/restore",
+    "GET /whoami",
+    "GET /blocks/manifest",
+    "GET /sites",
+    "POST /sites/register",
+    "GET /publish/log",
+    "GET /publish/status",
+    "GET /publish/diff",
+    "GET /restore/snapshots",
+    "POST /restore/snapshot",
+    "DELETE /restore/snapshot",
+    "GET /unsplash/search",
+    "GET+POST /telemetry/chat/feedback",
+    "POST /preview/screenshot",
+    "POST /audio/transcribe",
+    "POST /image/generate",
+    "POST /image/generate/chat",
+    "POST /image/interpret",
+    "POST /image/upload",
+    "GET /generated-images/:fileName"
+];
+/**
+ * Send an ActionResult from an `http/*-actions` module as a Response.
+ *
+ * The parameter used to be typed structurally, because importing the type
+ * across the package boundary was more ceremony than restating it. From inside
+ * the package it is just a sibling import, so this is the real type now.
+ */
+function actionResponse(result, cors) {
+    return jsonResponse(result.body, { status: result.code, cors });
+}
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024; // 10 MB
+// MIME ⇄ extension for the local image store. Kept narrow on purpose: only the
+// formats a browser <img>/Next <Image> renders. Unknown types are rejected.
+const MIME_TO_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/webp": "webp",
+    "image/gif": "gif",
+    "image/avif": "avif",
+    "image/svg+xml": "svg"
+};
+const EXT_TO_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    webp: "image/webp",
+    gif: "image/gif",
+    avif: "image/avif",
+    svg: "image/svg+xml"
+};
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "../cms/index.js";
+function stripBasePath(pathname, basePath) {
+    if (!basePath)
+        return pathname || "/";
+    if (pathname === basePath)
+        return "/";
+    if (pathname.startsWith(basePath + "/"))
+        return pathname.slice(basePath.length) || "/";
+    return pathname || "/";
+}
+/**
+ * Build a Web-standard request handler that wraps the orchestrator brain.
+ *
+ * Usage in Next.js App Router (`app/api/avocado/[[...path]]/route.ts`):
+ *
+ *     export const runtime = "nodejs"
+ *     const handler = createOrchestrator()
+ *     export const POST = handler
+ *     export const OPTIONS = handler
+ */
+export function createOrchestrator(config = {}) {
+    const basePath = config.basePath ?? "/api/avocado";
+    // When an adapter is configured, force-scope sessions so the orchestrator's
+    // built-in demo-content seed path (triggered when a session key has no `::`)
+    // doesn't fire ahead of the adapter. Without this, the first chat turn ends
+    // up editing the bundled demo pages instead of the site's real content.
+    const effectiveSiteId = config.adapter ? (config.siteId ?? "library") : config.siteId;
+    /*
+     * Declared at mount, before any request can build a manifest. The registry
+     * holds this on `globalThis`, so it survives Next duplicating these modules
+     * across the RSC / SSR / route-handler layers — the declaration made here has
+     * to be visible to `/api/editor/blocks` in another copy.
+     */
+    if (config.blockTypes)
+        declareBlockCatalogue(config.blockTypes);
+    const scope = (session, bodySiteId) => scopedSessionKey(session, effectiveSiteId ?? bodySiteId);
+    const imageDir = config.imageDir ?? resolve(process.cwd(), ".data/generated-images");
+    /*
+     * Built on first use rather than at mount: the store opens an append-only
+     * file, and a site that never receives a rating should not create one.
+     */
+    let feedbackStore = null;
+    const getFeedbackStore = (logger) => {
+        if (!feedbackStore) {
+            feedbackStore = createFeedbackStore({
+                filePath: process.env.FEEDBACK_FILE ?? resolve(process.cwd(), ".data/chat-feedback.ndjson"),
+                limit: Number(process.env.FEEDBACK_LIMIT ?? 1000),
+                logger
+            });
+        }
+        return feedbackStore;
+    };
+    let runtimePromise = null;
+    const getRuntime = () => {
+        if (!runtimePromise)
+            runtimePromise = buildRuntime(config);
+        return runtimePromise;
+    };
+    /*
+     * The gate has to be able to speak before `buildRuntime` has run — it refuses
+     * requests that never reach the runtime — so it gets its own logger rather
+     * than waiting for `runtime.log`.
+     */
+    const gateLogger = config.logger ?? consoleLogger();
+    {
+        const resolved = resolveAuth(config.auth);
+        const line = `[auth] library mode: ${resolved.mode} — ${resolved.reason}`;
+        if (resolved.mode === "closed")
+            gateLogger.error(line);
+        else if (resolved.mode === "open-dev")
+            gateLogger.warn(line);
+        else
+            gateLogger.info(line);
+    }
+    const handler = async function handler(request) {
+        const url = new URL(request.url);
+        const path = stripBasePath(url.pathname, basePath);
+        const cors = corsHeadersFor(request, config);
+        if (request.method === "OPTIONS") {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    ...cors,
+                    /*
+                     * DELETE is here because /restore/snapshot needs it, and the header
+                     * list because the editor's fetch shim attaches `x-access-token` to
+                     * every orchestrator request. Advertising only `content-type` meant a
+                     * browser refused the preflight the moment auth existed — the gate
+                     * would have been unreachable from the very client it is for.
+                     */
+                    "access-control-allow-methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+                    "access-control-allow-headers": "content-type, x-access-token, authorization",
+                    "access-control-max-age": "600"
+                }
+            });
+        }
+        /*
+         * The gate, before anything reads a body or touches the store. Public paths
+         * (the /auth exchange itself, and image reads an <img> tag cannot
+         * authenticate) pass through inside checkAuth.
+         */
+        const gate = await checkAuth({ request, path, auth: config.auth, cors, log: gateLogger });
+        if (gate.response)
+            return gate.response;
+        if (request.method === "GET" && path === "/auth/status") {
+            /*
+             * `gateEnabled` answers one question for the editor's PasswordGate: "do I
+             * prompt for a password?". Only the built-in password gate can say yes —
+             * a host's own `auth` hook has no password to collect, and telling the
+             * editor to prompt for one it cannot verify would trap the user in a form
+             * that never succeeds. Such a host authenticates the browser its own way,
+             * before the editor ever loads.
+             */
+            return jsonResponse({ gateEnabled: isAccessGateEnabled() }, { cors });
+        }
+        if (request.method === "POST" && path === "/auth/verify") {
+            if (!isAccessGateEnabled()) {
+                // Open by choice, or gated by something other than a password. Hand back
+                // a token anyway so the client's code path is identical either way; if a
+                // token gate is running, this one is not valid for it.
+                return jsonResponse({ ok: true, accessToken: mintAccessToken() }, { cors });
+            }
+            let body = {};
+            try {
+                body = (await request.json());
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            if (!body.password)
+                return jsonResponse({ error: "password is required" }, { status: 400, cors });
+            if (!verifyAccessPassword(body.password)) {
+                return jsonResponse({ error: "incorrect password" }, { status: 401, cors });
+            }
+            return jsonResponse({ ok: true, accessToken: mintAccessToken() }, { cors });
+        }
+        if (request.method === "POST" && path === "/chat") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const parsed = chatRequestBodySchema.safeParse(raw);
+            if (!parsed.success)
+                return jsonResponse({ error: "invalid request body", details: parsed.error.issues }, { status: 400, cors });
+            const body = parsed.data;
+            const scopedSession = scope(body.session, body.siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const result = await runChatPipeline(runtime.pipelineCtx, {
+                ...body,
+                session: scopedSession
+            });
+            return jsonResponse(result.payload, { status: result.code, cors });
+        }
+        if (request.method === "POST" && path === "/chat/stream") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const parsed = chatRequestBodySchema.safeParse(raw);
+            if (!parsed.success)
+                return jsonResponse({ error: "invalid request body", details: parsed.error.issues }, { status: 400, cors });
+            const body = parsed.data;
+            const scoped = { ...body, session: scope(body.session, body.siteId) };
+            await runtime.bootstrapCache.ensure(scoped.session, runtime.adapter, runtime.log);
+            const encoder = new TextEncoder();
+            const stream = new ReadableStream({
+                async start(controller) {
+                    const emit = (event) => {
+                        try {
+                            controller.enqueue(encoder.encode(formatSseFrame(event)));
+                        }
+                        catch { /* controller closed early (client disconnected) */ }
+                    };
+                    // SSE retry hint (60s) — matches the Fastify route's behavior.
+                    try {
+                        controller.enqueue(encoder.encode("retry: 60000\n\n"));
+                    }
+                    catch { /* */ }
+                    try {
+                        await runChatStream(runtime.pipelineCtx, scoped, { emit, signal: request.signal });
+                    }
+                    finally {
+                        try {
+                            controller.close();
+                        }
+                        catch { /* */ }
+                    }
+                },
+                cancel() {
+                    // Client disconnect — request.signal fires automatically, and
+                    // runChatPipeline observes it. Nothing else to do here.
+                }
+            });
+            return new Response(stream, { status: 200, headers: SSE_HEADERS(cors) });
+        }
+        // ---- Resumable streaming triplet -----------------------------------
+        // POST /chat/start    → allocate streamId
+        // GET  /chat/stream   → run the pipeline (or replay+subscribe on reconnect)
+        // POST /chat/cancel   → abort an active run
+        if (request.method === "POST" && path === "/chat/start") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const parsed = chatRequestBodySchema.safeParse(raw);
+            if (!parsed.success)
+                return jsonResponse({ error: "invalid request body", details: parsed.error.issues }, { status: 400, cors });
+            const body = parsed.data;
+            if (!body.session)
+                return jsonResponse({ error: "session is required" }, { status: 400, cors });
+            const origin = request.headers.get("origin") ?? "*";
+            try {
+                const entry = runtime.resumableStore.allocate({
+                    body,
+                    session: body.session,
+                    siteId: body.siteId ?? "",
+                    origin
+                });
+                return jsonResponse({ streamId: entry.streamId }, { status: 200, cors });
+            }
+            catch (err) {
+                if (err instanceof TooManyPendingStreamsError) {
+                    return jsonResponse({ error: "Too many pending streams for this session" }, { status: 429, cors });
+                }
+                throw err;
+            }
+        }
+        if (request.method === "POST" && path === "/chat/cancel") {
+            const runtime = await getRuntime();
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            const result = runtime.resumableStore.cancel(body);
+            if (result.status === "not_found")
+                return jsonResponse({ status: "not_found" }, { status: 404, cors });
+            if (result.status === "already_terminal")
+                return jsonResponse({ status: "already_terminal" }, { status: 200, cors });
+            return jsonResponse({ status: "cancel_requested" }, { status: 200, cors });
+        }
+        if (request.method === "GET" && path === "/chat/stream") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const streamId = url.searchParams.get("streamId");
+            const afterSeqRaw = url.searchParams.get("afterSeq");
+            const afterSeq = afterSeqRaw === null ? 0 : Number(afterSeqRaw) || 0;
+            const isReconnect = afterSeqRaw !== null;
+            const reqOrigin = request.headers.get("origin") ?? "*";
+            if (!streamId) {
+                return jsonResponse({ error: "streamId query param required (use POST /chat/start to allocate one)" }, { status: 400, cors });
+            }
+            const entry = runtime.resumableStore.get(streamId);
+            if (!entry)
+                return jsonResponse({ error: "Stream context expired or not found" }, { status: 410, cors });
+            // Origin check
+            if (entry.origin !== "*" && reqOrigin !== "*" && entry.origin !== reqOrigin) {
+                return jsonResponse({ error: "Origin mismatch" }, { status: 403, cors });
+            }
+            const encoder = new TextEncoder();
+            // Reconnect: replay + subscribe (don't kick off a new run)
+            if (isReconnect) {
+                const sseStream = new ReadableStream({
+                    start(controller) {
+                        try {
+                            controller.enqueue(encoder.encode("retry: 60000\n\n"));
+                        }
+                        catch { /* */ }
+                        const subscriber = {
+                            emit: (envelope) => {
+                                try {
+                                    controller.enqueue(encoder.encode(formatSseFrame(envelope)));
+                                }
+                                catch { /* */ }
+                            },
+                            close: () => { try {
+                                controller.close();
+                            }
+                            catch { /* */ } }
+                        };
+                        const unsubscribe = runtime.resumableStore.subscribe(streamId, subscriber, afterSeq);
+                        request.signal.addEventListener("abort", () => unsubscribe());
+                    },
+                    cancel() { }
+                });
+                return new Response(sseStream, { status: 200, headers: SSE_HEADERS(cors) });
+            }
+            // First connection: only valid for pending streams
+            if (entry.state === "active")
+                return jsonResponse({ error: "Pipeline already running" }, { status: 409, cors });
+            if (isTerminalState(entry.state))
+                return jsonResponse({ error: "Stream already completed" }, { status: 410, cors });
+            const scoped = { ...entry.body, session: scope(entry.body.session, entry.body.siteId) };
+            await runtime.bootstrapCache.ensure(scoped.session, runtime.adapter, runtime.log);
+            const sseStream = new ReadableStream({
+                async start(controller) {
+                    try {
+                        controller.enqueue(encoder.encode("retry: 60000\n\n"));
+                    }
+                    catch { /* */ }
+                    const subscriber = {
+                        emit: (envelope) => {
+                            try {
+                                controller.enqueue(encoder.encode(formatSseFrame(envelope)));
+                            }
+                            catch { /* */ }
+                        },
+                        close: () => { try {
+                            controller.close();
+                        }
+                        catch { /* */ } }
+                    };
+                    // Subscribe BEFORE starting the pipeline so we don't miss early events.
+                    const unsubscribe = runtime.resumableStore.subscribe(streamId, subscriber, 0);
+                    request.signal.addEventListener("abort", () => unsubscribe());
+                    await runResumableChatStream(runtime.pipelineCtx, runtime.resumableStore, streamId, scoped);
+                    // closeAllSubscribers in runResumableChatStream closes the controller.
+                },
+                cancel() { }
+            });
+            return new Response(sseStream, { status: 200, headers: SSE_HEADERS(cors) });
+        }
+        // ---- Variations ----------------------------------------------------
+        /*
+         * "Show me three ways to word this hero." Both halves answered 405 here,
+         * so on an embedded site the Variations panel opened onto an error — and
+         * the editor renders that control unconditionally, off no capability flag.
+         *
+         * The two paths share everything up to the response because they share
+         * every way of being wrong: same body, same scoping, same bootstrap. Only
+         * the last step differs, and splitting them earlier is what let the
+         * Fastify copy validate one of them slightly differently for a while.
+         *
+         * `scopeVariationSession` gets this mount's own siteId rather than the
+         * body's for the same reason every route here calls `scope()`: the
+         * bootstrap below fills exactly one key and the pipeline has to read the
+         * one that was filled.
+         */
+        if (request.method === "POST" && (path === "/chat/variations" || path === "/chat/variations/stream")) {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const parsed = parseVariationRequest(raw);
+            if (!parsed.ok)
+                return actionResponse(parsed.result, cors);
+            const session = scopeVariationSession(parsed.body, effectiveSiteId);
+            await runtime.bootstrapCache.ensure(session, runtime.adapter, runtime.log);
+            if (path === "/chat/variations") {
+                return actionResponse(await variationsAction(runtime.pipelineCtx, parsed.body, session), cors);
+            }
+            const encoder = new TextEncoder();
+            const stream = new ReadableStream({
+                async start(controller) {
+                    const emit = (frame) => {
+                        try {
+                            controller.enqueue(encoder.encode(formatVariationFrame(frame)));
+                        }
+                        catch { /* controller closed early (client disconnected) */ }
+                    };
+                    try {
+                        // Never rejects: the action turns a thrown pipeline into an
+                        // `error` frame, because the 200 was committed with the headers.
+                        await variationsStreamAction(runtime.pipelineCtx, parsed.body, session, emit);
+                    }
+                    finally {
+                        try {
+                            controller.close();
+                        }
+                        catch { /* */ }
+                    }
+                }
+            });
+            return new Response(stream, { status: 200, headers: SSE_HEADERS(cors) });
+        }
+        // ---- Library-mode publish ------------------------------------------
+        // Minimal: takes the current draft pages for {session, siteId} and hands
+        // them to the configured adapter's onPublish() if present. No git/deploy
+        // wiring — that lives in apps/orchestrator. The adapter IS the destination.
+        if (request.method === "POST" && path === "/publish") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            const scopedSession = scope(body.session, body.siteId);
+            /*
+             * Seed the draft before reading it. `onPublish(pages)` is a snapshot
+             * contract, and under a snapshot contract "this process has never loaded
+             * the draft" and "the user deleted every page" are the same request:
+             * both arrive as `[]`. A cold publish therefore asked the adapter to
+             * make the site match nothing. PBA survived it only because its writer
+             * computes patches and found none; an adapter that reads the contract
+             * literally would empty the CMS.
+             *
+             * This narrows the window rather than closing it — `ensure` swallows a
+             * failing `getPages()` by design, so an adapter that is down still
+             * leaves an empty draft here. The structural answer is a diff-shaped
+             * publish (LM-04).
+             */
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const pages = getSessionPages(scopedSession);
+            const slugs = pages.map((p) => p.slug);
+            /*
+             * Every exit below records what happened, because the alternative was a
+             * lie by omission: `publishStatusBySession` was written in exactly one
+             * place, the standalone server's publishing route, so in library mode
+             * `GET /publish/status` answered "no publish status for session" forever
+             * rather than only before the first publish, and `/publish/log` was
+             * always empty. An agent reads that 404 as a broken session.
+             *
+             * The row is born resolved, which the Vercel path cannot do and this one
+             * must. There, a build is still running when POST returns, so the row
+             * says "triggered" and a later `GET /publish/status` is the only thing
+             * that ever learns the outcome. Here the adapter's `onPublish` has
+             * already written or thrown by the time control reaches this line —
+             * there is no deployment to poll, so a row left "triggered" would be a
+             * promise of news that never arrives. `vercelState` is not a claim about
+             * Vercel; it is the token `publishStatusFromVercelState` reads, and the
+             * way the other synchronous targets (site-contract, git) already say
+             * "finished". A later poll is harmless: it only matures rows still
+             * marked "triggered".
+             *
+             * The summary is deliberately diff-free. The standalone route can afford
+             * `loadPublishedForDiff` before publishing; here that would be a second
+             * `adapter.getPages()` on the publish path — for PBA, 45 sequential
+             * Sanity reads (PI-08) bought for one line of prose.
+             */
+            const record = (ok, summary, error) => {
+                const now = new Date().toISOString();
+                const target = `cms:${runtime.adapter?.id ?? "none"}`;
+                const tracker = {
+                    session: scopedSession,
+                    status: ok ? "triggered" : "failed",
+                    startedAt: now,
+                    updatedAt: now,
+                    slugs,
+                    vercelState: ok ? "READY" : "ERROR",
+                    deployResponse: target
+                };
+                publishStatusBySession.set(scopedSession, tracker);
+                try {
+                    pushPublishLogEntry({
+                        session: scopedSession,
+                        siteId: normalizeSiteId(effectiveSiteId ?? body.siteId),
+                        target,
+                        status: ok ? "success" : "failed",
+                        summary,
+                        pageCount: pages.length,
+                        slugs,
+                        ...(error ? { error } : {})
+                    });
+                }
+                catch (logErr) {
+                    runtime.log.warn({ session: scopedSession, err: logErr instanceof Error ? logErr.message : String(logErr) }, "library-publish: failed to record publish-log row");
+                }
+            };
+            if (!runtime.adapter?.onPublish) {
+                record(true, "Nothing written — the adapter has no onPublish");
+                return jsonResponse({ ok: true, written: false, count: pages.length, reason: "adapter has no onPublish; publish is a no-op" }, { status: 200, cors });
+            }
+            const config = getSiteConfig(scopedSession);
+            /*
+             * Hand the adapter the baseline it needs to diff.
+             *
+             * `onPublish(pages)` alone is a snapshot contract, and a snapshot is not
+             * invertible: every CMS read is a projection, so writing the projection
+             * back replaces an asset reference with a URL and a document reference
+             * with a dead href. A publisher has to compare against what it read, and
+             * it cannot compare against nothing.
+             *
+             * This is the copy the bootstrap already took, not a fresh read — a
+             * second `getPages()` here is 45 sequential Sanity calls on the
+             * integration that motivated it. It is therefore absent after a restart
+             * that reloaded the draft from SQLite, which is why the contract says to
+             * treat undefined as "no baseline" and never as "the site was empty".
+             */
+            const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
+            const context = body.assets || published
+                ? { ...(body.assets ? { assets: body.assets } : {}), ...(published ? { published } : {}) }
+                : undefined;
+            let unsupported = [];
+            try {
+                const result = await runtime.adapter.onPublish(pages, config, context);
+                if (result && typeof result === "object" && Array.isArray(result.unsupported)) {
+                    unsupported = result.unsupported;
+                }
+                if (result && typeof result === "object" && result.ok === false) {
+                    const message = result.error ?? "adapter.onPublish returned not-ok";
+                    runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, error: result.error }, "library-publish: adapter.onPublish() returned not-ok");
+                    record(false, message, message);
+                    return jsonResponse({
+                        ok: false,
+                        written: false,
+                        count: pages.length,
+                        error: message,
+                        ...(unsupported.length > 0 ? { unsupported } : {})
+                    }, { status: 502, cors });
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : "adapter.onPublish failed";
+                runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, err: err instanceof Error ? err.stack ?? err.message : String(err) }, "library-publish: adapter.onPublish() threw");
+                record(false, message, message);
+                return jsonResponse({ ok: false, error: message }, { status: 502, cors });
+            }
+            /*
+             * Success with something to report is the third answer publishing needs.
+             * A field-level publisher routinely writes the text and cannot write the
+             * image beside it — that is neither a plain success, which claims the
+             * whole edit shipped, nor an error, which claims none of it did.
+             */
+            const summary = buildPublishSummary({ changedSlugs: [], removedSlugs: [], totalPages: pages.length, hasDiff: false });
+            record(true, unsupported.length > 0
+                ? `${summary} ${unsupported.length} change${unsupported.length === 1 ? "" : "s"} could not be published.`
+                : summary);
+            return jsonResponse({
+                ok: true,
+                written: true,
+                count: pages.length,
+                ...(unsupported.length > 0 ? { unsupported } : {})
+            }, { status: 200, cors });
+        }
+        // The editor polls this on boot to populate its model selector and the
+        // planner-source badge. Without it, availableProviders stays empty and the
+        // selector falls back to its built-in default (OpenAI), hiding Claude even
+        // when only "anthropic" is configured.
+        if (request.method === "GET" && path === "/status/planner") {
+            const runtime = await getRuntime();
+            const providers = runtime.pipelineCtx.availableProviders;
+            const hasImageBackend = Boolean(process.env.OPENAI_API_KEY || process.env.GOOGLE_GENAI_API_KEY);
+            return jsonResponse({
+                plannerSource: providers[0] ?? "demo",
+                availableProviders: providers,
+                features: {
+                    googleDrive: false,
+                    unsplash: Boolean(process.env.UNSPLASH_ACCESS_KEY),
+                    imageGenerate: hasImageBackend,
+                    imageGenerateChat: hasImageBackend,
+                    agentMode: false
+                },
+                /*
+                 * The capability probe lives here rather than on `/whoami` because
+                 * `/whoami` awaits the adapter bootstrap — the cold CMS read that
+                 * ME-06 exists to hide — and a client asking "what may I do?" must
+                 * not be made to wait on "what is in the draft?". This route reads
+                 * no adapter and is not blocked in demo mode.
+                 */
+                capabilities: runtime.capabilities,
+                /*
+                 * Whether a write survives a restart. A library-mode host that cannot
+                 * open its store still answers every request normally, so without this
+                 * the only symptom is edits quietly reverting to CMS content one
+                 * module reload later.
+                 */
+                persistence: persistenceHealth()
+            }, { status: 200, cors });
+        }
+        // ---- Draft read + edit surface (the editor's property panel) -------
+        // The editor needs these to display and edit a site's draft content.
+        // Each seeds the draft from the adapter first (bootstrapCache.ensure is
+        // idempotent) so they work before any chat turn has run.
+        // The editor fetches the selected block's props from here (useBlockProps).
+        // Without it the property panel can never reach `ready` — it shows the
+        // block breadcrumb but no editable fields.
+        if (request.method === "GET" && path === "/draft/pages") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const session = url.searchParams.get("session") ?? undefined;
+            const siteId = url.searchParams.get("siteId") ?? undefined;
+            const slug = url.searchParams.get("slug") ?? undefined;
+            if (!session || !slug) {
+                return jsonResponse({ error: "session and slug are required" }, { status: 400, cors });
+            }
+            const scopedSession = scope(session, siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const page = getPage(scopedSession, slug);
+            if (!page)
+                return jsonResponse({ error: "not found" }, { status: 404, cors });
+            return jsonResponse(structuredClone(page), { status: 200, cors });
+        }
+        // Page list. Also flips the editor's `hasBootstrapped` gate — until this
+        // returns a non-empty list, the property panel never enables its fetch.
+        if (request.method === "GET" && path === "/draft/slugs") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const session = url.searchParams.get("session") ?? undefined;
+            const siteId = url.searchParams.get("siteId") ?? undefined;
+            const scopedSession = scope(session, siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const pages = getSessionPages(scopedSession);
+            return jsonResponse({
+                slugs: pages.map((p) => p.slug),
+                pages: pages.map((p) => ({
+                    slug: p.slug,
+                    // The URL, when the site says it differs from the slug. A client
+                    // that navigates has to be told; it cannot infer a locale prefix.
+                    ...(p.meta?.path ? { path: p.meta.path } : {}),
+                    title: p.title ?? "",
+                    updatedAt: p.updatedAt ?? "",
+                    blockCount: p.blocks?.length ?? 0
+                })),
+                // Which content this is — see orchestrator-core/http/draft-provenance.ts.
+                ...describeDraft({
+                    requestedSiteId: siteId ?? effectiveSiteId,
+                    scopedSession,
+                    pageCount: pages.length,
+                    hasAdapter: Boolean(runtime.adapter)
+                })
+            }, { status: 200, cors });
+        }
+        // Editor bootstrap probe. In library mode the adapter is the source of
+        // truth (already seeded by ensure), so this is effectively a confirm — we
+        // don't clobber the draft with the posted pages.
+        if (request.method === "POST" && path === "/draft/bootstrap") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                raw = {};
+            }
+            const body = (raw ?? {});
+            const scopedSession = scope(body.session, body.siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const pages = getSessionPages(scopedSession);
+            return jsonResponse({ status: "bootstrapped", count: pages.length, slugs: pages.map((p) => p.slug) }, { status: 200, cors });
+        }
+        // Site config — drives the page-level nav-label + SEO fields shown in the
+        // property panel when no block is selected.
+        if (request.method === "GET" && path === "/draft/site-config") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const session = url.searchParams.get("session") ?? undefined;
+            const siteId = url.searchParams.get("siteId") ?? undefined;
+            if (!session)
+                return jsonResponse({ error: "session is required" }, { status: 400, cors });
+            const scopedSession = scope(session, siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            return jsonResponse(getSiteConfig(scopedSession), { status: 200, cors });
+        }
+        if (request.method === "PUT" && path === "/draft/site-config") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            if (!body.session)
+                return jsonResponse({ error: "session is required" }, { status: 400, cors });
+            const parsed = siteConfigSchema.safeParse(body.config);
+            if (!parsed.success)
+                return jsonResponse({ error: "invalid config", details: parsed.error.issues }, { status: 400, cors });
+            const scopedSession = scope(body.session, body.siteId);
+            setSiteConfig(scopedSession, parsed.data);
+            schedulePersistState(runtime.log);
+            return jsonResponse({ status: "ok", config: getSiteConfig(scopedSession) }, { status: 200, cors });
+        }
+        // Apply operations — the editor's property-panel field edits, page-meta
+        // edits, and structural edits all POST here. This is the write path that
+        // makes the draft (and therefore the live preview + publish) reflect edits.
+        if (request.method === "POST" && path === "/ops") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            const scopedSession = scope(body.session, body.siteId);
+            await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
+            const parsedOps = z.array(operationSchema).safeParse(body.ops);
+            if (!parsedOps.success)
+                return jsonResponse({ error: "invalid ops payload", details: parsedOps.error.issues }, { status: 400, cors });
+            if (parsedOps.data.length === 0)
+                return jsonResponse({ error: "ops must not be empty" }, { status: 400, cors });
+            let manifest;
+            if (body.componentsManifest) {
+                const payload = typeof body.componentsManifest === "string"
+                    ? (() => { try {
+                        return JSON.parse(body.componentsManifest);
+                    }
+                    catch {
+                        return "__invalid__";
+                    } })()
+                    : body.componentsManifest;
+                if (payload !== "__invalid__") {
+                    const pm = blockManifestSchema.safeParse(payload);
+                    if (pm.success)
+                        manifest = pm.data;
+                }
+            }
+            /*
+             * Validate-only, before anything is snapshotted or bumped. This branch
+             * did not exist: `dryRun` was parsed out of the body by nobody and the
+             * operations were applied for real, so an agent asking "what would this
+             * do?" was told "applied" — the exact opposite of what it asked for.
+             */
+            if (body.dryRun)
+                return actionResponse(await opsDryRunAction(scopedSession, parsedOps.data, manifest), cors);
+            // Snapshot touched pages for undo + verify they exist.
+            const snapshots = new Map();
+            const createPageSlugs = [];
+            for (const op of parsedOps.data) {
+                if (op.op === "create_page") {
+                    createPageSlugs.push(op.page.slug);
+                    continue;
+                }
+                if (op.op === "update_site_config")
+                    continue;
+                if (!("pageSlug" in op) || typeof op.pageSlug !== "string")
+                    continue;
+                if (snapshots.has(op.pageSlug))
+                    continue;
+                const current = getPage(scopedSession, op.pageSlug);
+                if (!current)
+                    return jsonResponse({ error: `page not found: ${op.pageSlug}` }, { status: 404, cors });
+                snapshots.set(op.pageSlug, current);
+            }
+            // Pre-apply block types: a removed block cannot be named afterwards.
+            const blockTypeBeforeApply = (slug, blockId) => snapshots.get(slug)?.blocks?.find((b) => b.id === blockId)?.type ??
+                getPage(scopedSession, slug)?.blocks?.find((b) => b.id === blockId)?.type;
+            try {
+                const applyResult = await applyOpsAtomically(scopedSession, parsedOps.data, { componentsManifest: manifest });
+                for (const [slug, snapshot] of snapshots)
+                    pushUndo(scopedSession, slug, snapshot);
+                for (const slug of createPageSlugs)
+                    pushUndo(scopedSession, slug, null);
+                const firstSlugOp = parsedOps.data.find((op) => "pageSlug" in op && typeof op.pageSlug === "string");
+                const firstSlug = firstSlugOp && "pageSlug" in firstSlugOp && typeof firstSlugOp.pageSlug === "string" ? firstSlugOp.pageSlug : undefined;
+                const updatedSlug = firstSlug ? pickUpdatedSlug(scopedSession, firstSlug, parsedOps.data) : undefined;
+                if (firstSlug) {
+                    pushRecentEdit(scopedSession, { slug: updatedSlug ?? firstSlug, summary: "Applied operations.", ops: parsedOps.data });
+                }
+                const previewVersion = bumpVersion(scopedSession);
+                const versionEntrySlug = updatedSlug ?? firstSlug ?? "/";
+                const versionSnapshot = getPage(scopedSession, versionEntrySlug);
+                pushVersionEntry(scopedSession, {
+                    version: previewVersion,
+                    slug: versionEntrySlug,
+                    summary: "Applied operations.",
+                    opTypes: parsedOps.data.map((op) => op.op),
+                    opCount: parsedOps.data.length,
+                    source: "direct",
+                    snapshot: versionSnapshot ? structuredClone(versionSnapshot) : null
+                });
+                schedulePersistState(runtime.log);
+                return jsonResponse({
+                    status: "applied",
+                    summary: "Applied operations.",
+                    changes: describeAppliedOps(parsedOps.data, {
+                        getBlockType: blockTypeBeforeApply,
+                        skippedOps: applyResult.skippedOps
+                    }),
+                    mentionedSlugs: collectMentionedSlugsFromOps(parsedOps.data, updatedSlug ?? firstSlug),
+                    previewVersion,
+                    focusBlockId: pickFocusBlockId(parsedOps.data),
+                    updatedSlug,
+                    /*
+                     * A duplicated page's blocks get fresh ids, and this table is the
+                     * only place they are reported. Without it a caller that duplicates
+                     * a page cannot address the copy's blocks without re-reading it —
+                     * and library mode was throwing the whole apply result away.
+                     */
+                    ...(applyResult.duplicatedPages.length > 0
+                        ? { duplicatedPages: applyResult.duplicatedPages }
+                        : {}),
+                    ...persistenceWarning()
+                }, { status: 200, cors });
+            }
+            catch (error) {
+                const reason = toErrorDetail(error);
+                return jsonResponse({ error: reason, errorCode: classifyGuardrailError(reason) }, { status: 400, cors });
+            }
+        }
+        /*
+         * ---- History: undo, redo, the version log --------------------------
+         *
+         * `/ops` above has always called `pushUndo`, so the stack was being kept
+         * correctly and nothing could pop it: the editor shows an Undo button
+         * unconditionally, and pressing it answered "POST /history/undo not
+         * handled by createOrchestrator()".
+         *
+         * The bodies are the same functions the Fastify app calls, so undo means
+         * the same thing in both. See orchestrator-core/http/history-actions.ts.
+         */
+        if (request.method === "GET" && path === "/history/status") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            return actionResponse(historyStatus(query), cors);
+        }
+        if (request.method === "GET" && path === "/history/log") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            return actionResponse(historyLog(query), cors);
+        }
+        if (request.method === "POST" && (path === "/history/undo" || path === "/history/redo" || path === "/history/restore")) {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            // The session has to exist before its history can be read, exactly as in
+            // /ops — a cold library-mode process has no draft until this runs.
+            const scoped = scope(body.session, body.siteId);
+            await runtime.bootstrapCache.ensure(scoped, runtime.adapter, runtime.log);
+            const action = path === "/history/undo" ? historyUndoAction
+                : path === "/history/redo" ? historyRedoAction
+                    : null;
+            if (action)
+                return actionResponse(action(body, runtime.log), cors);
+            return actionResponse(historyRestoreAction(body, runtime.log), cors);
+        }
+        /*
+         * The MCP server's first call. Each install is bound to one
+         * (session, siteId) pair and asks this before a destructive edit, so a
+         * library-mode site that cannot answer it cannot be edited by an agent at
+         * all — the tools refuse before they start.
+         */
+        /*
+         * The block vocabulary of THIS process, which in library mode is the host
+         * site's own — `registerBlocks` ran at runtime build. An MCP agent reads
+         * this instead of its own module scope, which held Avocado's built-ins and
+         * none of the site's custom types.
+         *
+         * No runtime needed for the manifest itself, but the runtime is what calls
+         * `registerBlocks()`, so build it first or a cold process answers with the
+         * built-ins alone — the exact wrong answer this route exists to replace.
+         */
+        /*
+         * The one site this process serves.
+         *
+         * `GET /sites` answered 405 here, so `avocado-list-sites` failed against
+         * every embedded site, and `POST /sites/register` — the only way to tell
+         * the orchestrator where the site is reachable — was missing too, which is
+         * what left `/preview/screenshot` with no `previewUrl` it could ever have
+         * been given.
+         *
+         * A monorepo orchestrator hosts many sites and has a registry to list. A
+         * library-mode one is mounted inside a single site and already knows which,
+         * so this reports that site whether or not anyone registered it: an empty
+         * list would read as "no sites here" about the site asking the question.
+         */
+        if (request.method === "GET" && path === "/sites") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            const scoped = scope(query.session, query.siteId);
+            const stored = getSiteConfig(scoped);
+            return jsonResponse({
+                sites: [
+                    {
+                        id: effectiveSiteId ?? normalizeSiteId(query.siteId),
+                        mode: "library",
+                        ...(config.previewUrl ? { previewUrl: config.previewUrl } : {}),
+                        ...(config.draftPath ? { draftPath: config.draftPath } : {}),
+                        // A registration is more specific than a build-time default, so
+                        // it goes on top.
+                        ...stored
+                    }
+                ]
+            }, { cors });
+        }
+        if (request.method === "POST" && path === "/sites/register") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            const scoped = scope(body.session, body.siteId);
+            const parsed = siteConfigSchema.safeParse(body.config ?? {});
+            if (!parsed.success) {
+                return jsonResponse({ error: "invalid config", details: parsed.error.issues }, { status: 400, cors });
+            }
+            const extras = {};
+            if (body.name)
+                extras.name = body.name;
+            if (body.purpose)
+                extras.purpose = body.purpose;
+            if (body.previewUrl)
+                extras.previewUrl = body.previewUrl;
+            if (body.draftPath)
+                extras.draftPath = body.draftPath;
+            if (typeof body.port === "number") {
+                extras.port = body.port;
+                if (!body.previewUrl)
+                    extras.previewUrl = `http://localhost:${body.port}`;
+            }
+            /*
+             * Merged over what is already stored, not substituted for it. The
+             * monorepo route replaces the config wholesale, which is survivable there
+             * because registration happens before anything else. Here the same object
+             * also holds everything `update_site_config` writes — the site name, nav
+             * labels, theme overrides — and a later `avocado-register-site` call
+             * setting only a preview URL would silently delete all of it.
+             */
+            const existing = getSiteConfig(scoped);
+            const merged = { ...existing, ...parsed.data, ...extras };
+            const unchanged = JSON.stringify(existing) === JSON.stringify(merged);
+            if (!unchanged) {
+                setSiteConfig(scoped, merged);
+                schedulePersistState(runtime.log);
+            }
+            const siteId = effectiveSiteId ?? normalizeSiteId(body.siteId);
+            return jsonResponse({
+                status: unchanged ? "unchanged" : "registered",
+                siteId,
+                session: scoped,
+                config: { id: siteId, ...merged }
+            }, { cors });
+        }
+        if (request.method === "GET" && path === "/blocks/manifest") {
+            const runtime = await getRuntime();
+            /*
+             * A declared type with no `registerBlock` behind it has no schema, so it
+             * silently does not reach the manifest — the site asks for fourteen blocks
+             * and the agent is shown eleven, with nothing anywhere saying why. Usually
+             * a typo or a missing import in the site's own `blocks/register.ts`.
+             * Checked here rather than at mount because registration order is not ours
+             * to depend on; by the time anyone asks for the manifest it has settled.
+             */
+            const missing = undeclaredBlockTypes();
+            if (missing.length > 0) {
+                runtime.log.warn({ types: missing }, "Declared block types have no registered schema and are missing from the manifest");
+            }
+            return actionResponse(blocksManifestAction(), cors);
+        }
+        if (request.method === "GET" && path === "/whoami") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            await runtime.bootstrapCache.ensure(scope(query.session, query.siteId), runtime.adapter, runtime.log);
+            return actionResponse(whoamiAction(query, url.origin, { hasAdapter: Boolean(runtime.adapter) }), cors);
+        }
+        /*
+         * Publishing status, history and preview.
+         *
+         * The three are read-only and were the loudest gap: the editor renders a
+         * Publish button unconditionally, and the dialog behind it could not say
+         * what would change, whether the last attempt worked, or what had been
+         * published before.
+         *
+         * All three drop `siteId` on the way in. `scope()` has already answered
+         * the question these actions re-ask, and each of them calls
+         * `scopedSessionKey(session, siteId)` again on whatever it is handed — so
+         * passing the caller's raw `siteId` alongside an already-scoped session
+         * scoped it twice, and a caller that sends one (the MCP server and the
+         * editor both always do) read `pba::library::s1`, a key nothing has ever
+         * written to. That was a second, independent cause of the all-pages-
+         * removed diff and of the permanent 404 from /publish/status: fixing only
+         * the missing bootstrap would have seeded `library::s1` while these kept
+         * reading the double-scoped key. `normalizeSiteId(undefined)` is the
+         * legacy id, so the key passes through untouched.
+         */
+        if (request.method === "GET" && path === "/publish/log") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            return actionResponse(publishLogAction({ ...query, session: scope(query.session, query.siteId), siteId: undefined }), cors);
+        }
+        if (request.method === "GET" && path === "/publish/status") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            return actionResponse(await publishStatusAction({ ...query, session: scope(query.session, query.siteId), siteId: undefined }), cors);
+        }
+        if (request.method === "GET" && path === "/publish/diff") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            const scoped = scope(query.session, query.siteId);
+            /*
+             * Both sides of the diff have to be read from the same era. Without this
+             * seed a cold process compares an empty draft against everything the
+             * adapter reports as live, and `computePublishDiff` faithfully calls the
+             * difference a deletion — the "45 pages removed, 0 added, 0 modified"
+             * an agent session reported as a destructive plan.
+             */
+            await runtime.bootstrapCache.ensure(scoped, runtime.adapter, runtime.log);
+            /*
+             * The published side comes from the adapter, not from the monorepo's
+             * `published-content.json` — the CMS is what is actually live for an
+             * embedded site, and `getPages()` is the only thing that knows it.
+             *
+             * `siteConfig` is deliberately omitted rather than passed as null: the
+             * adapter contract has no way to report the live header, so "cannot
+             * tell" is the truth. Passing null would claim the live site has no
+             * header and open every preview with a phantom "header added".
+             */
+            const source = {
+                load: async () => ({
+                    /*
+                     * `published`, and the word is load-bearing. The session was seeded
+                     * from the draft side, so reading the same side here would diff a
+                     * working copy against itself and report every pending CMS edit as
+                     * already live. An adapter that reads only one perspective answers
+                     * the same list to both calls, which is the pre-existing behaviour
+                     * and is why `readsDraftPerspective` is reported: it is the only way
+                     * a caller can tell "nothing is pending" from "nothing is visible".
+                     */
+                    pages: runtime.adapter ? await runtime.adapter.getPages({ perspective: "published" }) : []
+                })
+            };
+            return actionResponse(await publishDiffAction({ ...query, session: scoped, siteId: undefined }, runtime.log, source), cors);
+        }
+        /*
+         * Snapshot restore. The git helpers underneath read the repository the
+         * process was started in, which for an embedded site is the host's own
+         * checkout rather than a store of published snapshots — so these answer an
+         * empty list rather than an error, and the panel renders as "nothing to
+         * restore" instead of failing.
+         */
+        if (request.method === "GET" && path === "/restore/snapshots") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            return actionResponse(await restoreSnapshotsList(Object.fromEntries(url.searchParams)), cors);
+        }
+        if (request.method === "POST" && path === "/restore/snapshot") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            const scoped = scope(body.session, body.siteId);
+            await runtime.bootstrapCache.ensure(scoped, runtime.adapter, runtime.log);
+            return actionResponse(await restoreSnapshotApply({ ...body, session: scoped }, runtime.log), cors);
+        }
+        if (request.method === "DELETE" && path === "/restore/snapshot") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            return actionResponse(await restoreSnapshotDelete((raw ?? {})), cors);
+        }
+        /* The Unsplash tab of the image picker. Unconfigured answers 404, not an
+         * empty result set — "no key" and "no matches" are different answers. */
+        if (request.method === "GET" && path === "/unsplash/search") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            return actionResponse(await unsplashSearchAction(Object.fromEntries(url.searchParams), { log: runtime.log }), cors);
+        }
+        /* Thumbs up / down under every assistant reply. Fired and forgotten by the
+         * editor, so a malformed payload is rejected rather than half-stored. */
+        if (path === "/telemetry/chat/feedback" && (request.method === "POST" || request.method === "GET")) {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const store = getFeedbackStore(runtime.log);
+            if (request.method === "GET") {
+                return actionResponse(telemetryFeedbackListAction(Object.fromEntries(url.searchParams), store), cors);
+            }
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            return actionResponse(telemetryFeedbackSubmitAction(raw, store), cors);
+        }
+        // ---- Image upload (local disk, POC-grade) --------------------------
+        // The editor's ImagePicker "Upload" tab POSTs a multipart form here and
+        // expects `{ url }` back. Bytes land in `imageDir`; the URL points at the
+        // sibling GET route below, relative to this handler's basePath so it
+        // resolves against the host site's own origin. No CDN / transforms — see
+        // docs/image-storage-options.md for the blob-backend swap.
+        /*
+         * An agent's only way to see what it just edited.
+         *
+         * Both of these are reached only by the MCP server, which is why neither
+         * showed up while the editor was the only client library mode was diffed
+         * against — and why the agent's visual feedback loop was missing from
+         * exactly the mode that an integrated site runs.
+         */
+        if (request.method === "POST" && path === "/preview/screenshot") {
+            const runtime = await getRuntime();
+            const params = (await request.json().catch(() => ({})));
+            const scoped = scope(params.session, params.siteId);
+            // The screenshot is of the DRAFT, so the draft has to exist first. A
+            // cold session photographs an empty page and reports success otherwise.
+            await runtime.bootstrapCache.ensure(scoped, runtime.adapter, runtime.log);
+            return actionResponse(await screenshotAction(params, runtime.log, {
+                takeScreenshot: config.screenshot,
+                fallbackPreviewUrl: config.previewUrl,
+                fallbackDraftPath: config.draftPath,
+                // Same key the bootstrap above seeded, and the same one /sites/register
+                // wrote the preview URL under.
+                scopedSession: scoped
+            }), cors);
+        }
+        // ---- Voice input ---------------------------------------------------
+        /*
+         * The mic button reads `features.audioTranscription` off /status/planner,
+         * which reports on the *keys* — so a host that had funded an
+         * `OPENAI_API_KEY` rendered the button and got "not handled" on click.
+         *
+         * The 503 comes before `formData()` deliberately: an unconfigured
+         * deployment should not be made to upload 25MB to be told there is no
+         * provider. After that the two transports diverge only in how they read
+         * the bytes — Fastify streams the part and aborts mid-upload at the cap,
+         * this buffers and checks afterwards — and agree on every answer, because
+         * both ask the same validator.
+         */
+        if (request.method === "POST" && path === "/audio/transcribe") {
+            const unavailable = transcriptionUnavailable();
+            if (unavailable)
+                return actionResponse(unavailable, cors);
+            let form;
+            try {
+                form = await request.formData();
+            }
+            catch {
+                return jsonResponse({ error: "expected multipart/form-data body" }, { status: 400, cors });
+            }
+            const file = form.get("audio") ?? form.get("file");
+            if (!(file instanceof File)) {
+                return jsonResponse({ error: "missing 'audio' file field" }, { status: 400, cors });
+            }
+            const bytes = new Uint8Array(await file.arrayBuffer());
+            const invalid = validateAudioInput({ mimeType: file.type, byteLength: bytes.byteLength });
+            if (invalid)
+                return actionResponse(invalid, cors);
+            return actionResponse(await transcribeAudioAction({ bytes, mimeType: file.type, filename: file.name || undefined }), cors);
+        }
+        // ---- AI image generation -------------------------------------------
+        /*
+         * Both of these write bytes, and where those bytes land is the whole
+         * reason `ImageStore` exists. The core helpers resolve a directory and a
+         * public origin from the environment, which is right for the standalone
+         * server and wrong here: an embedded mount has its own `imageDir` and
+         * serves the files back under its own `basePath`. Left on the default,
+         * generation would appear to work and hand the editor a URL that 404s —
+         * the failure that is hardest to see from a test, since every assertion
+         * about the action itself still passes.
+         */
+        const imageStore = () => fileImageStore({ dir: imageDir, publicBaseUrl: `${basePath}/generated-images` });
+        if (request.method === "POST" && path === "/image/generate") {
+            const runtime = await getRuntime();
+            const body = ((await request.json().catch(() => ({}))) ?? {});
+            return actionResponse(await generateImageAction(body, { log: runtime.log, store: imageStore() }), cors);
+        }
+        if (request.method === "POST" && path === "/image/generate/chat") {
+            const runtime = await getRuntime();
+            const body = ((await request.json().catch(() => ({}))) ?? {});
+            /*
+             * Validated before the branch, not inside each arm: once the streaming
+             * arm writes SSE headers the status code is spent, and a missing Google
+             * key would have to be reported as an `error` frame the client would
+             * need a special case for. As a 503 it reuses the path every other
+             * unconfigured route already takes.
+             */
+            const invalid = validateImageChatRequest(body);
+            if (invalid)
+                return actionResponse(invalid, cors);
+            const deps = { log: runtime.log, store: imageStore() };
+            if (!body.stream)
+                return actionResponse(await imageChatAction(body, deps), cors);
+            const encoder = new TextEncoder();
+            const stream = new ReadableStream({
+                async start(controller) {
+                    const emit = (frame) => {
+                        try {
+                            controller.enqueue(encoder.encode(formatImageChatFrame(frame)));
+                        }
+                        catch { /* controller closed early (client disconnected) */ }
+                    };
+                    try {
+                        await imageChatStreamAction(body, deps, emit);
+                    }
+                    finally {
+                        try {
+                            controller.close();
+                        }
+                        catch { /* */ }
+                    }
+                }
+            });
+            return new Response(stream, { status: 200, headers: SSE_HEADERS(cors) });
+        }
+        if (request.method === "POST" && path === "/image/interpret") {
+            const runtime = await getRuntime();
+            let form;
+            try {
+                form = await request.formData();
+            }
+            catch {
+                return jsonResponse({ error: "expected multipart/form-data body" }, { status: 400, cors });
+            }
+            // Fastify's copy reads the first file part whatever it is named; a Web
+            // FormData has no such notion, so accept either field name the callers
+            // use rather than making the MCP tool and the composer disagree.
+            const file = form.get("image") ?? form.get("file");
+            if (!(file instanceof File)) {
+                return jsonResponse({ error: "missing 'image' file field" }, { status: 400, cors });
+            }
+            const bytes = Buffer.from(await file.arrayBuffer());
+            return actionResponse(await interpretImageAction({ bytes, byteLength: bytes.byteLength, mimeType: file.type }, { log: runtime.log }), cors);
+        }
+        if (request.method === "POST" && path === "/image/upload") {
+            let form;
+            try {
+                form = await request.formData();
+            }
+            catch {
+                return jsonResponse({ error: "expected multipart/form-data body" }, { status: 400, cors });
+            }
+            const file = form.get("image");
+            if (!(file instanceof File)) {
+                return jsonResponse({ error: "missing 'image' file field" }, { status: 400, cors });
+            }
+            const ext = MIME_TO_EXT[file.type];
+            if (!ext) {
+                return jsonResponse({ error: `unsupported image type: ${file.type || "unknown"}` }, { status: 415, cors });
+            }
+            if (file.size > MAX_UPLOAD_BYTES) {
+                return jsonResponse({ error: `image exceeds ${MAX_UPLOAD_BYTES} byte limit` }, { status: 413, cors });
+            }
+            const fileName = `upload_${Date.now()}_${randomUUID().slice(0, 8)}.${ext}`;
+            try {
+                await mkdir(imageDir, { recursive: true });
+                await writeFile(resolve(imageDir, fileName), Buffer.from(await file.arrayBuffer()));
+            }
+            catch (err) {
+                return jsonResponse({ error: "image upload failed", detail: err instanceof Error ? err.message : String(err) }, { status: 500, cors });
+            }
+            return jsonResponse({ url: `${basePath}/generated-images/${fileName}`, bytes: file.size, mimeType: file.type }, { status: 200, cors });
+        }
+        // Serve a previously-uploaded image off local disk. `basename` collapses
+        // any path-traversal attempt to a bare filename before it touches the FS.
+        if (request.method === "GET" && path.startsWith("/generated-images/")) {
+            const fileName = basename(path.slice("/generated-images/".length));
+            if (!fileName || !/^[A-Za-z0-9._-]+$/.test(fileName)) {
+                return jsonResponse({ error: "invalid file name" }, { status: 400, cors });
+            }
+            const ext = fileName.split(".").pop()?.toLowerCase() ?? "";
+            const mime = EXT_TO_MIME[ext];
+            if (!mime)
+                return jsonResponse({ error: "unsupported file type" }, { status: 415, cors });
+            let bytes;
+            try {
+                bytes = await readFile(resolve(imageDir, fileName));
+            }
+            catch {
+                return jsonResponse({ error: "not found" }, { status: 404, cors });
+            }
+            return new Response(new Uint8Array(bytes), {
+                status: 200,
+                headers: {
+                    "content-type": mime,
+                    "cache-control": "public, max-age=31536000, immutable",
+                    ...cors
+                }
+            });
+        }
+        return jsonResponse({
+            error: `Method ${request.method} ${path} not handled by createOrchestrator()`,
+            hint: `Supported: ${SUPPORTED_ROUTES.join(", ")}. ` +
+                "Use the Fastify orchestrator at apps/orchestrator for the full surface (sites, the session directory, the agent surface, etc.)."
+        }, { status: 405, cors });
+    };
+    handler.dispose = async () => {
+        if (!runtimePromise)
+            return;
+        try {
+            const runtime = await runtimePromise;
+            runtime.resumableStore.dispose();
+        }
+        catch { /* runtime never built; nothing to dispose */ }
+        runtimePromise = null;
+    };
+    return handler;
+}