@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.0

package/dist/cms/bootstrap.js

@@ -1,10 +1,39 @@
-import { getSessionDraft, ensureHeroImageProps, bumpVersion, schedulePersistState } from "../state/session-state.js";
+import { resolveCapabilities } from "./adapter.js";
+import { setSessionCapabilities, getSessionDraft, ensureHeroImageProps, bumpVersion, schedulePersistState } from "../state/session-state.js";
 const DEFAULT_MAX_ATTEMPTED = 5000;
+// One site, a handful of sessions, is the shape a library-mode process has. The
+// cap is only here so a long-lived multi-site host cannot accumulate page sets
+// without bound.
+const DEFAULT_MAX_BASELINES = 50;
+// A warmed page list is a cold-start bridge, not a cache. It only has to cover
+// the gap between "the runtime mounted" and "the first tool call lands", which
+// is seconds for an MCP host attaching to a running process. One minute is
+// generous enough that even a pathologically slow adapter finishes inside the
+// window and the first agent call still gets the benefit, and short enough that
+// a session created later never gets seeded from a page list the CMS has since
+// moved past — a warm-once-at-boot process serving an hour-old page list to a
+// fresh session would hand out content someone has already edited upstream.
+const DEFAULT_WARM_TTL_MS = 60_000;
 export function createCmsBootstrapCache(opts = {}) {
     const inFlight = new Map();
     // Set is insertion-ordered, so FIFO eviction is just "delete the first key".
     const attempted = new Set();
     const maxAttempted = Math.max(1, opts.maxAttempted ?? DEFAULT_MAX_ATTEMPTED);
+    const warmTtlMs = Math.max(0, opts.warmTtlMs ?? DEFAULT_WARM_TTL_MS);
+    const capabilityOverride = opts.capabilities;
+    // Map is insertion-ordered, so FIFO eviction is "delete the first key".
+    const baselines = new Map();
+    const maxBaselines = Math.max(1, opts.maxBaselines ?? DEFAULT_MAX_BASELINES);
+    let warmEntry = null;
+    function rememberBaseline(session, pages) {
+        baselines.set(session, pages);
+        while (baselines.size > maxBaselines) {
+            const oldest = baselines.keys().next().value;
+            if (oldest === undefined)
+                break;
+            baselines.delete(oldest);
+        }
+    }
     function markAttempted(session) {
         attempted.add(session);
         while (attempted.size > maxAttempted) {
@@ -14,9 +43,85 @@ export function createCmsBootstrapCache(opts = {}) {
             attempted.delete(oldest);
         }
     }
+    // Staleness is measured from the moment the fetch *settled*, not from when it
+    // started: a fetch still in flight is about to produce a fresh read, however
+    // long it has been running, so it is always worth awaiting.
+    function isExpired(entry) {
+        return entry.settledAt !== null && Date.now() - entry.settledAt > warmTtlMs;
+    }
+    function warm(adapter, log) {
+        if (!adapter)
+            return;
+        // Adapter identity, not `adapter.id`: two runtimes in one process can share
+        // an adapter id while pointing at different sites, and serving one site's
+        // pages to the other's sessions is the one failure this must never cause.
+        if (warmEntry && warmEntry.adapter === adapter && !isExpired(warmEntry))
+            return;
+        const entry = {
+            adapter,
+            settledAt: null,
+            // Replaced on the next statement. The placeholder exists only because the
+            // fetch's own callbacks have to reach back into `entry` to stamp it.
+            promise: Promise.resolve(null)
+        };
+        entry.promise = Promise.resolve()
+            /*
+             * `draft`, because this list seeds a session and a session is a working
+             * copy: the pages someone is about to edit should include the edits they
+             * have already made in the CMS and not published. An adapter that does
+             * not distinguish ignores the argument and answers exactly as before.
+             *
+             * Note what this does *not* change: the baseline `ensure` keeps for the
+             * publish diff is still this same list, because that baseline's job is
+             * "what the adapter last handed us", so the round-trip diff compares
+             * like with like. Only `/publish/diff`, which asks what is live, reads
+             * the other side.
+             */
+            .then(() => adapter.getPages({ perspective: "draft" }))
+            .then((pages) => {
+            entry.settledAt = Date.now();
+            log.info({ adapter: adapter.id, count: pages.length }, "cms-bootstrap: warmed adapter page list");
+            return pages;
+        })
+            .catch((err) => {
+            // Forget the failure entirely so the first session's ensure() gets a
+            // clean retry instead of inheriting a dead prefetch.
+            if (warmEntry === entry)
+                warmEntry = null;
+            log.warn({
+                adapter: adapter.id,
+                err: err instanceof Error ? err.stack ?? err.message : String(err)
+            }, "cms-bootstrap: warm fetch failed; first session will retry");
+            return null;
+        });
+        warmEntry = entry;
+    }
+    /** The warmed page list if one applies to this adapter and is still fresh. */
+    function warmedPages(adapter) {
+        const entry = warmEntry;
+        if (!entry || entry.adapter !== adapter)
+            return null;
+        if (isExpired(entry)) {
+            if (warmEntry === entry)
+                warmEntry = null;
+            return null;
+        }
+        return entry.promise;
+    }
     async function ensure(session, adapter, log) {
         if (!adapter)
             return;
+        /*
+         * Record what this adapter can honour before anything else, on every call
+         * rather than once: this is the one place that knows both a session key
+         * and the adapter behind it, and the ops engine reads it by session key to
+         * refuse an operation the site cannot publish. Behind the `attempted`
+         * early-return it would be written for the first request of a session and
+         * lost to a process restart that reloaded the draft from SQLite — the
+         * draft survives, so `ensure` returns early, so the capabilities never
+         * land, so the engine silently reverts to permitting everything.
+         */
+        setSessionCapabilities(session, resolveCapabilities(adapter, capabilityOverride));
         if (attempted.has(session))
             return;
         const existing = inFlight.get(session);
@@ -27,11 +132,20 @@ export function createCmsBootstrapCache(opts = {}) {
             if (draft.size > 0)
                 return; // finally-block records the attempt
             try {
-                const pages = await adapter.getPages();
+                const warmed = warmedPages(adapter);
+                const pages = (warmed ? await warmed : null) ?? (await adapter.getPages({ perspective: "draft" }));
                 if (pages.length === 0) {
                     log.info({ session, adapter: adapter.id }, "cms-bootstrap: adapter returned no pages");
                     return;
                 }
+                /*
+                 * Keep the pre-edit copy. The pages are already being cloned into the
+                 * draft, so a baseline for the eventual publish diff costs one more
+                 * clone and — the point — no second adapter read. Re-reading upstream
+                 * at publish time is 45 sequential CMS calls on the integration that
+                 * motivated this.
+                 */
+                rememberBaseline(session, pages.map((page) => structuredClone(page)));
                 for (const page of pages) {
                     const copy = structuredClone(page);
                     ensureHeroImageProps(copy);
@@ -62,9 +176,15 @@ export function createCmsBootstrapCache(opts = {}) {
     }
     return {
         ensure,
+        warm,
+        baselineFor(session) {
+            return baselines.get(session) ?? null;
+        },
         reset() {
             inFlight.clear();
             attempted.clear();
+            baselines.clear();
+            warmEntry = null;
         },
         get attemptedSize() {
             return attempted.size;
@@ -79,6 +199,10 @@ const defaultCache = createCmsBootstrapCache();
 export async function ensureSessionBootstrapped(session, adapter, log) {
     return defaultCache.ensure(session, adapter, log);
 }
+/** Warm the process-default cache. Runtime-scoped caches own their own `warm()`. */
+export function warmSessionBootstrap(adapter, log) {
+    defaultCache.warm(adapter, log);
+}
 /** Test helper — clears the default process cache. Runtime-scoped caches own their own `reset()`. */
 export function _resetCmsBootstrapCache() {
     defaultCache.reset();

package/dist/cms/index.d.ts

@@ -1,4 +1,5 @@
-export type { CmsAdapter, CmsInlineAsset, CmsPublishContext, CmsPublishResult } from "./adapter.ts";
+export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./adapter.ts";
+export { resolveCapabilities } from "./adapter.ts";
 export { jsonFileAdapter, type JsonFileAdapterOptions } from "./json-file-adapter.ts";
 export { editorApiAdapter, type EditorApiAdapterOptions } from "./editor-api-adapter.ts";
-export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, type CmsBootstrapCache, type CmsBootstrapCacheOptions } from "./bootstrap.ts";
+export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, type CmsBootstrapCache, type CmsBootstrapCacheOptions, warmSessionBootstrap } from "./bootstrap.ts";

package/dist/cms/index.js

@@ -1,3 +1,4 @@
+export { resolveCapabilities } from "./adapter.js";
 export { jsonFileAdapter } from "./json-file-adapter.js";
 export { editorApiAdapter } from "./editor-api-adapter.js";
-export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache } from "./bootstrap.js";
+export { ensureSessionBootstrapped, createCmsBootstrapCache, _resetCmsBootstrapCache, warmSessionBootstrap } from "./bootstrap.js";

package/dist/errors.d.ts

@@ -3,7 +3,15 @@
  * operational validation. Superset of the former `GuardrailErrorCategory`
  * and `PlannerFailureReasonCategory` types.
  */
-export type ErrorCategory = "schema_violation" | "ambiguity" | "not_found" | "no_effective_change" | "planner_refusal" | "incomplete_output" | "malformed_output" | "internal_error" | "canceled" | "operation_failed";
+export type ErrorCategory = "schema_violation" | "ambiguity" | "not_found" | "no_effective_change" | "planner_refusal" | "incomplete_output" | "malformed_output" | "internal_error" | "canceled" | "operation_failed"
+/**
+ * The operation is well-formed and would apply, but the site behind this
+ * session has declared it cannot honour it — see `CmsCapabilities`. Distinct
+ * from `schema_violation` (the request is wrong) and from
+ * `operation_failed` (it was attempted and did not work): nothing here is
+ * wrong and nothing was attempted.
+ */
+ | "unsupported_by_site";
 export type GuardrailErrorCategory = ErrorCategory;
 export type PlannerFailureReasonCategory = Extract<ErrorCategory, "schema_violation" | "planner_refusal" | "incomplete_output" | "malformed_output" | "internal_error">;
 /**

package/dist/handler/auth.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The credential gate for library mode.
+ *
+ * `createOrchestrator` mounts on the customer's own production domain and can
+ * edit and publish their content. Until this module existed it did so with no
+ * credential check of any kind: `grep -n 'auth' orchestrator.ts` returned
+ * nothing, and every route was reachable by anyone who guessed the path.
+ *
+ * The shape is deliberately the agent surface's, which faced the same question
+ * a year earlier and answered it by refusing to mount rather than by hoping:
+ *
+ *   - a host that supplies `config.auth` owns the decision entirely;
+ *   - a host that configures `ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`
+ *     gets the same token gate the standalone server enforces, minted and
+ *     validated by the same module, so one editor build talks to both;
+ *   - a host that configured neither is open in development and **closed in
+ *     production**. Not warned about — closed. A default that is convenient in
+ *     dev and catastrophic in prod has to pick prod.
+ *
+ * The escape hatch from that last rule is one line, `auth: () => true`, which
+ * is a thing somebody types on purpose and cannot arrive at by omission.
+ */
+import type { Logger } from "../logger.ts";
+/**
+ * Whatever the host's `auth` hook wants to hand downstream — a user id, a role,
+ * a tenant. Nothing in the orchestrator reads it yet; it is threaded through so
+ * that when a route needs "who is this", the hook does not have to be rewritten.
+ */
+export type AuthContext = Record<string, unknown>;
+/**
+ * Decide whether a request may proceed.
+ *
+ * Return `false` (or `null`/`undefined`) to refuse, `true` to allow, or an
+ * object to allow and attach context. Throwing is treated as a refusal, so a
+ * hook that awaits a session lookup does not have to catch its own errors.
+ */
+export type OrchestratorAuth = (request: Request) => boolean | AuthContext | null | undefined | Promise<boolean | AuthContext | null | undefined>;
+export type AuthMode = 
+/** `config.auth` supplied — the host decides. */
+"hook"
+/** `ACCESS_PASSWORD_HASH` and/or `ORCHESTRATOR_ACCESS_TOKEN` configured. */
+ | "token"
+/** Nothing configured, not production. Open, and says so at mount. */
+ | "open-dev"
+/** Nothing configured, production. Everything is refused. */
+ | "closed";
+export interface ResolvedAuth {
+    mode: AuthMode;
+    /** One line, for the mount-time log. Never sent to a caller. */
+    reason: string;
+}
+export declare function isPublicPath(path: string, method: string): boolean;
+/** True when either credential is configured, i.e. the built-in gate can run. */
+export declare function hasConfiguredCredential(): boolean;
+/**
+ * Resolved per request rather than once at mount. `NODE_ENV` and the credential
+ * env vars are read at call time everywhere else in this codebase for the same
+ * reason: route modules are imported before `dotenv.config()` runs, and a value
+ * captured at module load is a value from before the host configured anything.
+ */
+export declare function resolveAuth(auth: OrchestratorAuth | undefined): ResolvedAuth;
+/** The one body shape the editor's fetch shim recognises as "re-prompt". */
+export declare function unauthorizedResponse(cors: Record<string, string>): Response;
+export interface AuthCheckResult {
+    /** Non-null means refuse and return this. */
+    response: Response | null;
+    /** Whatever the hook attached, for a route that wants to know who called. */
+    context: AuthContext | null;
+}
+/**
+ * Run the gate for one request. `path` is already base-path-stripped.
+ */
+export declare function checkAuth(args: {
+    request: Request;
+    path: string;
+    auth: OrchestratorAuth | undefined;
+    cors: Record<string, string>;
+    log: Logger;
+}): Promise<AuthCheckResult>;

package/dist/handler/auth.js

@@ -0,0 +1,113 @@
+/**
+ * The credential gate for library mode.
+ *
+ * `createOrchestrator` mounts on the customer's own production domain and can
+ * edit and publish their content. Until this module existed it did so with no
+ * credential check of any kind: `grep -n 'auth' orchestrator.ts` returned
+ * nothing, and every route was reachable by anyone who guessed the path.
+ *
+ * The shape is deliberately the agent surface's, which faced the same question
+ * a year earlier and answered it by refusing to mount rather than by hoping:
+ *
+ *   - a host that supplies `config.auth` owns the decision entirely;
+ *   - a host that configures `ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`
+ *     gets the same token gate the standalone server enforces, minted and
+ *     validated by the same module, so one editor build talks to both;
+ *   - a host that configured neither is open in development and **closed in
+ *     production**. Not warned about — closed. A default that is convenient in
+ *     dev and catastrophic in prod has to pick prod.
+ *
+ * The escape hatch from that last rule is one line, `auth: () => true`, which
+ * is a thing somebody types on purpose and cannot arrive at by omission.
+ */
+import { isAccessGateEnabled, isValidAccessToken, extractAccessToken } from "../http/access-tokens.js";
+/**
+ * Paths that answer before a caller could possibly hold a credential.
+ *
+ * `/auth/*` is the exchange that produces one. `GET /generated-images/*` is
+ * fetched by `<img src>` on the rendered page, which cannot attach a header —
+ * gating it would blank every uploaded image in the live site, not just in the
+ * editor. Both are read-only and neither reveals session content.
+ */
+const PUBLIC_PATHS = new Set(["/auth/status", "/auth/verify"]);
+export function isPublicPath(path, method) {
+    if (method === "OPTIONS")
+        return true;
+    if (PUBLIC_PATHS.has(path))
+        return true;
+    if (method === "GET" && path.startsWith("/generated-images/"))
+        return true;
+    return false;
+}
+function isProduction() {
+    return (process.env.NODE_ENV ?? "").trim() === "production";
+}
+/** True when either credential is configured, i.e. the built-in gate can run. */
+export function hasConfiguredCredential() {
+    return isAccessGateEnabled() || Boolean(process.env.ORCHESTRATOR_ACCESS_TOKEN?.trim());
+}
+/**
+ * Resolved per request rather than once at mount. `NODE_ENV` and the credential
+ * env vars are read at call time everywhere else in this codebase for the same
+ * reason: route modules are imported before `dotenv.config()` runs, and a value
+ * captured at module load is a value from before the host configured anything.
+ */
+export function resolveAuth(auth) {
+    if (auth)
+        return { mode: "hook", reason: "config.auth supplied — the host decides" };
+    if (hasConfiguredCredential()) {
+        return {
+            mode: "token",
+            reason: `built-in token gate (${isAccessGateEnabled() ? "password" : "static token"})`
+        };
+    }
+    if (isProduction()) {
+        return {
+            mode: "closed",
+            reason: "NODE_ENV=production with no credential — every request is refused. " +
+                "Set ACCESS_PASSWORD_HASH or ORCHESTRATOR_ACCESS_TOKEN, or pass config.auth."
+        };
+    }
+    return { mode: "open-dev", reason: "no credential configured and NODE_ENV is not production — open" };
+}
+/** The one body shape the editor's fetch shim recognises as "re-prompt". */
+export function unauthorizedResponse(cors) {
+    return new Response(JSON.stringify({ error: "unauthorized" }), {
+        status: 401,
+        headers: { "content-type": "application/json", ...cors }
+    });
+}
+/**
+ * Run the gate for one request. `path` is already base-path-stripped.
+ */
+export async function checkAuth(args) {
+    const { request, path, auth, cors, log } = args;
+    if (isPublicPath(path, request.method))
+        return { response: null, context: null };
+    const resolved = resolveAuth(auth);
+    if (resolved.mode === "open-dev")
+        return { response: null, context: null };
+    if (resolved.mode === "closed") {
+        log.error({ path }, `[auth] refused — ${resolved.reason}`);
+        return { response: unauthorizedResponse(cors), context: null };
+    }
+    if (resolved.mode === "token") {
+        if (isValidAccessToken(extractAccessToken(request)))
+            return { response: null, context: null };
+        return { response: unauthorizedResponse(cors), context: null };
+    }
+    // mode === "hook"
+    let verdict;
+    try {
+        verdict = await auth(request);
+    }
+    catch (err) {
+        // A hook that threw has not said yes. Refuse, and say why in the log rather
+        // than in the response — the caller does not get to learn how it failed.
+        log.warn({ err: err instanceof Error ? err.message : String(err), path }, "[auth] hook threw — refusing");
+        return { response: unauthorizedResponse(cors), context: null };
+    }
+    if (!verdict)
+        return { response: unauthorizedResponse(cors), context: null };
+    return { response: null, context: verdict === true ? null : verdict };
+}

package/dist/handler/create-orchestrator.d.ts

@@ -0,0 +1,205 @@
+import { type AIProvider, type ModelKey } from "../state/session-state.ts";
+import { type ScreenshotCapture } from "../http/screenshot-actions.ts";
+import { type Logger } from "../logger.ts";
+import type { CmsAdapter, CmsCapabilities } from "../cms/adapter.ts";
+import { type OrchestratorAuth, type AuthContext } from "./auth.ts";
+export type { OrchestratorAuth, AuthContext };
+export interface CreateOrchestratorConfig {
+    /**
+     * Provider model overrides. Defaults to env vars (OPENAI_MODEL_*, ANTHROPIC_MODEL_*,
+     * GOOGLE_GENAI_MODEL_*). Pass an explicit object to override per-tier model names.
+     */
+    modelLookup?: Record<AIProvider, Record<ModelKey, string>>;
+    /**
+     * Override available providers. Defaults to whichever API keys are present in
+     * process.env (OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_GENAI_API_KEY).
+     */
+    availableProviders?: AIProvider[];
+    /** Pino-shaped logger. Defaults to a console-backed implementation. */
+    logger?: Logger;
+    /**
+     * Allowed CORS origins.
+     *
+     * Unset, this reflected whatever `Origin` arrived — every site on the web
+     * was allowed to read the response. It now reflects only outside production;
+     * under `NODE_ENV=production` an unset value sends no CORS headers at all,
+     * which permits same-origin callers and nobody else. Pass an explicit
+     * allow-list to open it back up, `"*"` to reflect deliberately, or `null` to
+     * turn the SDK's CORS handling off entirely and let Next middleware own it.
+     */
+    corsOrigins?: string[] | "*" | null;
+    /**
+     * Decide whether a request may proceed.
+     *
+     * A library-mode mount can edit and publish the site it is embedded in, so it
+     * needs a credential. There are three ways to give it one, in precedence
+     * order:
+     *
+     *  1. **This hook.** Return `true`, or an object to attach context; return
+     *     `false` to refuse. Use it to reuse the session the rest of your app
+     *     already has — read a cookie, check a header, call your own auth.
+     *  2. **`ACCESS_PASSWORD_HASH` / `ORCHESTRATOR_ACCESS_TOKEN`.** With either
+     *     set and no hook, the built-in gate runs: `/auth/verify` exchanges the
+     *     password for a token, and every other route requires it as
+     *     `x-access-token`, `Authorization: Bearer`, or `?accessToken=`. This is
+     *     the same gate the standalone orchestrator enforces, minted by the same
+     *     module — one editor build talks to both.
+     *  3. **Neither.** Open in development. **Closed in production** — every
+     *     request is refused, because an unauthenticated publish endpoint on a
+     *     customer's own domain is not a default anybody should be able to reach
+     *     by forgetting something.
+     *
+     * To run open in production on purpose, say so: `auth: () => true`.
+     */
+    auth?: OrchestratorAuth;
+    /**
+     * Register the default builtin tools (unsplash-search, image-generate,
+     * gdrive-browse). Defaults to `false` — opt in only if you want those
+     * features, since registering them pulls in sharp + googleapis + image-gen
+     * SDKs at module load. Pass `true` for env-gated defaults, or an explicit
+     * subset like `["unsplash-search"]`.
+     */
+    builtinTools?: boolean | Array<"unsplash-search" | "image-generate" | "gdrive-browse">;
+    /**
+     * URL path prefix the handler is mounted under. Everything matching this
+     * prefix is stripped off `url.pathname` before route matching, so the rest
+     * of the handler can reason in terms of `/chat`, `/chat/stream`, etc.
+     *
+     * Defaults to `/api/avocado` (the catch-all path used in the Next.js
+     * example app). Set to `""` if you want to match against the full pathname
+     * yourself, or override to e.g. `/api/orchestrator` if you mount the
+     * catch-all there.
+     */
+    basePath?: string;
+    /**
+     * Source-of-truth adapter for the site's existing content. Called once per
+     * session on the first chat request to seed SQLite with the site's pages.
+     * Without an adapter the orchestrator starts with an empty draft, which
+     * means the planner has no pages to edit — every "edit the homepage" turn
+     * returns `page not found`.
+     *
+     * Provided implementations:
+     *  - `jsonFileAdapter({ path })` — read PageDoc[] from a JSON file
+     *  - `editorApiAdapter({ origin })` — fetch from `${origin}/api/editor/pages`
+     *
+     * Import from `@avocadostudio-ai/orchestrator-core/cms`.
+     */
+    adapter?: CmsAdapter;
+    /**
+     * Site identifier used to scope session state in SQLite. When `adapter` is
+     * set, defaults to `"library"` so the demo-content seed path is bypassed
+     * (an unscoped session falls back to the orchestrator's bundled demo pages).
+     * Override if you want to run multiple distinct sites against one process.
+     *
+     * Precedence on incoming requests:
+     *   - adapter configured: `siteId` (or its `"library"` default) ALWAYS wins
+     *     over `body.siteId`. The library-mode orchestrator owns its identity.
+     *   - no adapter: explicit `siteId` wins; otherwise `body.siteId` is used.
+     */
+    siteId?: string;
+    /**
+     * Register the site's block schemas before the orchestrator's first chat
+     * request. Use this instead of relying on side-effect import order: in
+     * library mode, the orchestrator's transitive imports of
+     * `@avocadostudio-ai/shared` re-register canonical Hero/CTA/etc. on the
+     * shared globalThis registry, often AFTER the host app's overrides.
+     *
+     * **Fires once per orchestrator runtime** — at `buildRuntime` time, not
+     * per-request. For long-lived production processes this is fine, but if
+     * the host re-builds the runtime on hot-reload, ensure the schemas survive
+     * (registerBlock is idempotent — calling again is safe). Pair this with
+     * the same `registerBlocks` passed to `createEditorApiHandler`, which
+     * re-runs on every `/blocks` request, to cover request-time too.
+     */
+    registerBlocks?: () => void;
+    /**
+     * Local directory where `POST /image/upload` writes uploaded files and
+     * `GET /generated-images/:fileName` reads them back. Defaults to
+     * `.data/generated-images` under the host process CWD.
+     *
+     * **POC-grade storage.** Files live on the orchestrator host's local disk
+     * with no CDN, no image transforms, and no durability guarantee — on an
+     * ephemeral filesystem (e.g. a container without a mounted volume) uploads
+     * vanish on redeploy. See `docs/image-storage-options.md` for the path to a
+     * blob/CDN backend; that swap is contained to these two routes.
+     */
+    imageDir?: string;
+    /**
+     * Capture backend for `POST /preview/screenshot` — an agent's only way to
+     * see what it just edited.
+     *
+     * Left unset, the route resolves `@avocadostudio-ai/migration-sdk` at call
+     * time. That package carries Playwright and a browser binary, so it is
+     * deliberately not a dependency of your site: install it yourself if you
+     * want screenshots, or pass a function here to use a capture service you
+     * already run. Without either, the route answers 503 and says so — it never
+     * pretends to have photographed anything.
+     */
+    screenshot?: ScreenshotCapture;
+    /**
+     * Where this site is reachable, e.g. `http://localhost:3000`. Used by
+     * `POST /preview/screenshot` as the base of the URL it photographs.
+     *
+     * Without it the route can only work after somebody calls
+     * `POST /sites/register` — a call an embedded site has no reason to make
+     * about itself, and which the MCP `avocado-register-site` tool could not make
+     * either, because library mode did not serve that route.
+     */
+    previewUrl?: string;
+    /**
+     * The route this site renders orchestrator drafts on. Either a prefix the
+     * page slug is appended to (`/avocado`) or a template naming where the slug
+     * goes (`/preview/{slug}/draft`). Defaults to `/preview-draft`, which is what
+     * `create-ai-site-editor` scaffolds.
+     *
+     * A site that wired Avocado into its own app almost certainly has its own
+     * route here — declare it, or every draft screenshot photographs a 404.
+     */
+    draftPath?: string;
+    /**
+     * The block types this site actually renders.
+     *
+     * Importing anything from `@avocadostudio-ai/shared` registers Avocado's 18
+     * built-ins transitively, so a site that brought its own blocks advertises
+     * both sets — and an agent reading `/blocks/manifest` could add a `Hero` that
+     * applies cleanly and renders nothing. Declare your own list and the manifest,
+     * the planner and `add_block` all narrow to it.
+     *
+     * Omit it if you render Avocado's blocks (a scaffolded site does). The
+     * declaration is exclusive: nothing outside the list is offered or accepted.
+     */
+    blockTypes?: readonly string[];
+    /**
+     * What this site can honour, for sites using a stock adapter that has no
+     * declaration of its own. Merged over `adapter.capabilities`, so a host can
+     * override one field without writing an adapter class.
+     *
+     * Every field is optional and unset means permitted — see `CmsCapabilities`.
+     * Declaring `createPages: false` makes the ops engine refuse `create_page`
+     * and `duplicate_page` on every write path, and makes the MCP server stop
+     * offering the matching tools.
+     */
+    capabilities?: CmsCapabilities;
+}
+/**
+ * A handler returned by {@link createOrchestrator}. Callable like the bare
+ * Web `(Request) => Promise<Response>` it always was, with an extra
+ * `dispose()` method to release the resumable-stream sweep timer (call this
+ * during dev hot-reload or test teardown).
+ */
+export type OrchestratorHandler = ((request: Request) => Promise<Response>) & {
+    dispose(): Promise<void>;
+};
+export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, ResolvedCapabilities } from "../cms/adapter.ts";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "../cms/index.ts";
+/**
+ * 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 declare function createOrchestrator(config?: CreateOrchestratorConfig): OrchestratorHandler;