@avocadostudio-ai/site-sdk 0.1.0

package/dist/server/orchestrator.js

@@ -0,0 +1,733 @@
+// createOrchestrator — Web-standard handler that wraps @avocadostudio-ai/orchestrator-core.
+//
+// PoC scope (feat/library-mode):
+//   - POST /chat            → JSON in / JSON out (planner pipeline, non-streaming)
+//   - POST /chat/stream     → SSE response via ReadableStream
+//   - everything else       → 405 with a helpful pointer
+//
+// What's deliberately out of scope here:
+//   - Audio transcribe (multipart) and the AI image-gen / Unsplash / gdrive
+//     picker sources (those live in apps/orchestrator)
+//   - All other route plugins (sites, sessions, history, jira, agent, etc.)
+//
+// In scope as of library mode: image upload to local disk (POST /image/upload
+// + GET /generated-images/:fileName) — POC-grade storage, see config.imageDir.
+//
+// The point is to feel the friction at the brain ↔ Web-handler boundary for the
+// hardest endpoint family (streaming chat). If that holds, porting the
+// remaining ~13 route plugins is mechanical. See EVAL.md in orchestrator-core.
+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 } from "@avocadostudio-ai/shared";
+import { chatRequestBodySchema } from "@avocadostudio-ai/orchestrator-core/nlp/intent-detection.js";
+import { applyOpsAtomically, pickFocusBlockId, pickUpdatedSlug, toErrorDetail, classifyGuardrailError } from "@avocadostudio-ai/orchestrator-core/ops/ops-engine.js";
+import { runChatStream, formatSseFrame } from "@avocadostudio-ai/orchestrator-core/http/chat-stream.js";
+import { ResumableStreamStore, runResumableChatStream, TooManyPendingStreamsError, isTerminalState } from "@avocadostudio-ai/orchestrator-core/http/chat-stream-resumable.js";
+import { runChatPipeline } from "@avocadostudio-ai/orchestrator-core/chat/chat-pipeline.js";
+import { createChatTelemetryStore } from "@avocadostudio-ai/orchestrator-core/telemetry/chat-telemetry.js";
+import { createToolRuntime } from "@avocadostudio-ai/orchestrator-core/tools/runtime.js";
+import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState } from "@avocadostudio-ai/orchestrator-core/state/session-state.js";
+import { consoleLogger } from "@avocadostudio-ai/orchestrator-core/logger.js";
+import { createCmsBootstrapCache } from "@avocadostudio-ai/orchestrator-core/cms/bootstrap.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("@avocadostudio-ai/orchestrator-core/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();
+    const bootstrapCache = createCmsBootstrapCache();
+    return {
+        pipelineCtx,
+        ready,
+        resumableStore,
+        log,
+        adapter: config.adapter ?? null,
+        bootstrapCache
+    };
+}
+const SSE_HEADERS = (origin) => ({
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache, no-transform",
+    "connection": "keep-alive",
+    "x-accel-buffering": "no",
+    "access-control-allow-origin": origin,
+    "vary": "Origin"
+});
+function corsHeadersFor(request, config) {
+    if (config.corsOrigins === null)
+        return {};
+    const origin = request.headers.get("origin") ?? "*";
+    if (config.corsOrigins === undefined || config.corsOrigins === "*") {
+        return { "access-control-allow-origin": origin, "vary": "Origin" };
+    }
+    return config.corsOrigins.includes(origin)
+        ? { "access-control-allow-origin": origin, "vary": "Origin" }
+        : {};
+}
+function jsonResponse(body, init = {}) {
+    return new Response(JSON.stringify(body), {
+        status: init.status ?? 200,
+        headers: { "content-type": "application/json", ...(init.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 } from "@avocadostudio-ai/orchestrator-core/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;
+    const scope = (session, bodySiteId) => scopedSessionKey(session, effectiveSiteId ?? bodySiteId);
+    const imageDir = config.imageDir ?? resolve(process.cwd(), ".data/generated-images");
+    let runtimePromise = null;
+    const getRuntime = () => {
+        if (!runtimePromise)
+            runtimePromise = buildRuntime(config);
+        return runtimePromise;
+    };
+    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,
+                    "access-control-allow-methods": "GET, POST, PUT, OPTIONS",
+                    "access-control-allow-headers": "content-type"
+                }
+            });
+        }
+        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 origin = request.headers.get("origin") ?? "*";
+            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(origin) });
+        }
+        // ---- 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();
+            const streamOrigin = entry.origin !== "*" ? entry.origin : reqOrigin;
+            // 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(streamOrigin) });
+            }
+            // 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(streamOrigin) });
+        }
+        // ---- 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);
+            const pages = getSessionPages(scopedSession);
+            if (!runtime.adapter?.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);
+            const context = body.assets ? { assets: body.assets } : undefined;
+            try {
+                const result = await runtime.adapter.onPublish(pages, config, context);
+                if (result && typeof result === "object" && result.ok === false) {
+                    runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, error: result.error }, "library-publish: adapter.onPublish() returned not-ok");
+                    return jsonResponse({ ok: false, written: false, count: pages.length, error: result.error ?? "adapter.onPublish returned not-ok" }, { status: 502, cors });
+                }
+            }
+            catch (err) {
+                runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, err: err instanceof Error ? err.stack ?? err.message : String(err) }, "library-publish: adapter.onPublish() threw");
+                return jsonResponse({ ok: false, error: err instanceof Error ? err.message : "adapter.onPublish failed" }, { status: 502, cors });
+            }
+            return jsonResponse({ ok: true, written: true, count: pages.length }, { 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
+                }
+            }, { 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,
+                    title: p.title ?? "",
+                    updatedAt: p.updatedAt ?? "",
+                    blockCount: p.blocks?.length ?? 0
+                }))
+            }, { 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;
+                }
+            }
+            // 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);
+            }
+            try {
+                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: [],
+                    previewVersion,
+                    focusBlockId: pickFocusBlockId(parsedOps.data),
+                    updatedSlug
+                }, { status: 200, cors });
+            }
+            catch (error) {
+                const reason = toErrorDetail(error);
+                return jsonResponse({ error: reason, errorCode: classifyGuardrailError(reason) }, { status: 400, 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.
+        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: POST /chat, POST /chat/stream, POST /chat/start, GET /chat/stream, POST /chat/cancel, POST /publish, GET /status/planner, GET /draft/pages, GET /draft/slugs, POST /draft/bootstrap, GET+PUT /draft/site-config, POST /ops, POST /image/upload, GET /generated-images/:fileName. Use the Fastify orchestrator at apps/orchestrator for the full surface (sites, sessions, agent, 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;
+}