@avocadostudio-ai/orchestrator-core 0.2.1 → 0.3.0

package/README.md

@@ -0,0 +1,102 @@
+# @avocadostudio-ai/orchestrator-core
+
+The Avocado Studio orchestrator as a library: session state, AI planning, the
+operations engine, and publishing, behind one Web-standard
+`(Request) => Promise<Response>`.
+
+This is the package **library mode is built on**. If you are integrating a
+Next.js site you almost certainly want
+[`@avocadostudio-ai/site-sdk`](https://www.npmjs.com/package/@avocadostudio-ai/site-sdk)
+instead — it re-exports everything below from
+`@avocadostudio-ai/site-sdk/server` and adds the Next-specific pieces (draft
+mode, the page factory, the editor API route). Reach for this package directly
+only when your host is not Next.
+
+## Install
+
+```bash
+npm install @avocadostudio-ai/orchestrator-core
+```
+
+`better-sqlite3` is a real dependency, not optional: session state — draft
+pages, undo/redo, the version log, chat history — lives in SQLite. Prebuilt
+binaries ship for linux-x64 (glibc 2.28+), darwin-arm64 and darwin-x64 on
+Node 22.
+
+Two peers are **optional**: `googleapis` and `@google/genai`. They are reached
+through `await import(...)` so a deployment that uses neither need not install
+them — but a bundler resolves dynamic imports statically and will fail the build
+over a package that is deliberately absent. Mark them external. On Next,
+`withAvocado` from `@avocadostudio-ai/site-sdk/next-config` does it for you.
+
+## Mount it
+
+```ts
+import { createOrchestrator } from "@avocadostudio-ai/orchestrator-core"
+
+const handler = createOrchestrator({
+  basePath: "/api/avocado",
+  adapter: myAdapter,
+  auth: async (request) => Boolean(await getSession(request)),
+})
+
+// Any host that speaks Request/Response
+export { handler as GET, handler as POST, handler as OPTIONS }
+```
+
+`createOrchestrator` gates **every** route. With neither an `auth` hook nor a
+credential (`ACCESS_PASSWORD_HASH` or `ORCHESTRATOR_ACCESS_TOKEN`) it refuses
+all requests under `NODE_ENV=production` rather than serving your content
+openly. Only `/auth/status` and `/auth/verify` are public.
+
+## The adapter
+
+`adapter` is your content store. SQLite is the working copy; the adapter is the
+source of truth, read on a cold session and written on publish.
+
+```ts
+import type { CmsAdapter } from "@avocadostudio-ai/orchestrator-core/cms"
+
+const myAdapter: CmsAdapter = {
+  id: "my-cms",
+  perspectives: true,                       // does getPages honour options.perspective?
+  getPages: (options) => fetchPages(options),
+  onPublish: (pages, config, context) => writeBack(pages, context?.published),
+  capabilities: { createPage: false },      // static — /whoami answers it offline
+}
+```
+
+`jsonFileAdapter` and `editorApiAdapter` are bundled from the same subpath. The
+full contract — including why `perspectives` defaults to *no* while capabilities
+default to *yes*, and why `onPublish` has to diff rather than overwrite — is
+documented in
+[the site-sdk README](https://www.npmjs.com/package/@avocadostudio-ai/site-sdk#the-adapter-contract).
+
+## What it does not do
+
+It serves the API. It does not serve the editor UI — that is
+`@avocadostudio-ai/cli` or your own deployment of the Studio — and it does not
+render your pages.
+
+`/health` is **not** a route, so a client that probes it to check compatibility
+gets a 405. The body lists every route that does exist.
+
+## Persistence
+
+| variable | meaning |
+|---|---|
+| `ORCHESTRATOR_DB_FILE` | Path to the SQLite file. Empty for the default; `:memory:` to force ephemeral. Auto-`:memory:` under `NODE_ENV=test` |
+| `ORCHESTRATOR_DB_BACKUP_INTERVAL_HOURS` | Periodic `VACUUM INTO` snapshot interval (default 24) |
+| `ORCHESTRATOR_DB_BACKUP_LIMIT` | Rolling snapshots to keep (default 14) |
+
+Undo/redo is capped at 50 entries per slug per direction, the version log at
+100, recent edits at 10, chat history at 6 messages.
+
+## Providers
+
+At least one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GOOGLE_GENAI_API_KEY`
+is required for planning. Keys never leave the process that holds them.
+
+## License
+
+Apache-2.0

package/dist/chat/changelog-coverage-validator.d.ts

@@ -34,4 +34,16 @@ export type ChangelogCoverageResult = {
 export declare function validateChangelogCoverage(args: {
     plan: EditPlan;
     draft: Map<string, PageDoc>;
+    /**
+     * Trailing `change_log` entries that describe the turn rather than an op —
+     * currently just the note the hallucination validator appends when it strips
+     * a prop the block does not have.
+     *
+     * They are neither counted against `ops.length` nor trimmed. Without this the
+     * arithmetic below sees N ops and N+1 entries, calls the note the planner
+     * over-describing itself, and deletes it — and that note is the only place
+     * the user is told a field they asked for does not exist. Two validators
+     * twenty lines apart, one erasing the other's output.
+     */
+    notes?: string[];
 }): ChangelogCoverageResult;

package/dist/chat/changelog-coverage-validator.js

@@ -156,6 +156,22 @@ function describeOp(op, draft) {
  */
 export function validateChangelogCoverage(args) {
     const { plan, draft } = args;
+    /*
+     * Split the notes off the tail, run the op-vs-narration arithmetic on what is
+     * left, and put them back. `notes` are appended last by construction, so this
+     * is a suffix check rather than a search.
+     */
+    const notes = [];
+    for (const note of [...(args.notes ?? [])].reverse()) {
+        if (plan.change_log[plan.change_log.length - 1] !== note)
+            continue;
+        plan.change_log = plan.change_log.slice(0, -1);
+        notes.unshift(note);
+    }
+    const restoreNotes = () => {
+        if (notes.length > 0)
+            plan.change_log = [...plan.change_log, ...notes];
+    };
     const empty = {
         plan,
         missingCount: 0,
@@ -165,8 +181,10 @@ export function validateChangelogCoverage(args) {
         fieldMislabelCount: 0,
         relabeledEntries: []
     };
-    if (plan.intent !== "edit_plan")
+    if (plan.intent !== "edit_plan") {
+        restoreNotes();
         return empty;
+    }
     const opCount = plan.ops.length;
     // Field-level pass (#13): an update_props entry can be the right COUNT yet name
     // the wrong field. Relabel each mislabeled update_props entry from the op's
@@ -190,13 +208,16 @@ export function validateChangelogCoverage(args) {
     }
     const changeCount = plan.change_log.length;
     if (changeCount === opCount) {
+        restoreNotes();
         return { ...empty, fieldMislabelCount: relabeledEntries.length, relabeledEntries };
     }
     // Empty ops list with non-empty change_log is almost always a planner
     // confusion (intent should have been content_answer). Leave it for
     // higher-level handling rather than wiping the user-facing copy here.
-    if (opCount === 0)
+    if (opCount === 0) {
+        restoreNotes();
         return empty;
+    }
     if (changeCount < opCount) {
         const missingCount = opCount - changeCount;
         const synthesizedEntries = [];
@@ -204,6 +225,7 @@ export function validateChangelogCoverage(args) {
             synthesizedEntries.push(describeOp(plan.ops[i], draft));
         }
         plan.change_log = [...plan.change_log, ...synthesizedEntries];
+        restoreNotes();
         return { plan, missingCount, synthesizedEntries, extraCount: 0, droppedEntries: [], fieldMislabelCount: relabeledEntries.length, relabeledEntries };
     }
     // changeCount > opCount: planner described more changes than it emitted ops
@@ -211,5 +233,6 @@ export function validateChangelogCoverage(args) {
     const extraCount = changeCount - opCount;
     const droppedEntries = plan.change_log.slice(opCount);
     plan.change_log = plan.change_log.slice(0, opCount);
+    restoreNotes();
     return { plan, missingCount: 0, synthesizedEntries: [], extraCount, droppedEntries, fieldMislabelCount: relabeledEntries.length, relabeledEntries };
 }

package/dist/chat/chat-pipeline.js

@@ -4,7 +4,7 @@ import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER, isGenerating
 import { siteCapabilitiesSchema, isBatchAddRequest, isDuplicateBlockRequest, isBlockCatalogQuery, isInfoQuery, isAdviceQuery, adviceResponse, isContentQuery, isPageListQuery, requestsPlanFirst, plannerMessageWithPendingContext, buildSiteContextBlock, infoResponse } from "../nlp/intent-detection.js";
 import { isLikelyClarificationFollowUp } from "../nlp/intent-helpers.js";
 import { versions, pendingClarificationBySession, chatHistoryBySession, pendingApprovalPlanBySession, continuationChainBySession, imageSourcePreferenceBySession, getSessionDraft, getPage, setPage, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, pushChatHistory, schedulePersistState, removePage } from "../state/session-state.js";
-import { toErrorDetail, isNoEffectiveChangeError, classifyGuardrailError, formatValidationError, isDeterministicRepairEligible, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
+import { toErrorDetail, isNoEffectiveChangeError, isAlreadyCurrentError, classifyGuardrailError, formatValidationError, isDeterministicRepairEligible, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
 import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
 import { clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
 import { generatePlanWithOpenAI, isPlannerOutputError, isStrictJsonResponseEnabled, parseIntentWithOpenAI } from "./planner.js";
@@ -1101,6 +1101,14 @@ export async function runChatPipeline(ctx, body, options) {
     const respondFromPlan = async (plan, source, applyMode = "apply_now", optionsOverride, plannerTier) => {
         if (plannerTier)
             activePlannerTier = plannerTier;
+        /*
+         * The note the hallucination validator writes when it strips a prop the
+         * block does not have, hoisted so the no-effective-change handler far below
+         * can reach it. That handler replaces `summary_for_user` wholesale, and a
+         * plan whose every prop was stripped lands there — so without this the one
+         * true sentence written about the turn is the one the user never sees.
+         */
+        let strippedPropsNote;
         const usageFields = planUsage ? {
             inputTokens: planUsage.inputTokens,
             outputTokens: planUsage.outputTokens,
@@ -1152,6 +1160,7 @@ export async function runChatPipeline(ctx, body, options) {
                 plan: resolvedPlan,
                 draft: getSessionDraft(body.session)
             });
+            strippedPropsNote = hallucinationResult.note;
             if (hallucinationResult.hallucinatedProps.length > 0) {
                 for (const entry of hallucinationResult.hallucinatedProps) {
                     ctx.log.warn({
@@ -1173,7 +1182,9 @@ export async function runChatPipeline(ctx, body, options) {
             // sees the correct count instead of silently approving uncovered ops.
             const changelogResult = validateChangelogCoverage({
                 plan: resolvedPlan,
-                draft: getSessionDraft(body.session)
+                draft: getSessionDraft(body.session),
+                // Not an op narration, so not something to trim for over-describing.
+                notes: hallucinationResult.note ? [hallucinationResult.note] : undefined
             });
             if (changelogResult.missingCount > 0) {
                 ctx.log.warn({
@@ -2540,13 +2551,47 @@ export async function runChatPipeline(ctx, body, options) {
                     ...plannerContextTelemetryFields,
                     ...timingFields()
                 });
+                /*
+                 * Two facts arrive here and only one of them is "your content is
+                 * already correct".
+                 *
+                 * The engine throws "All update patches matched existing values" when
+                 * the values genuinely matched, and "Edit plan produced no changes"
+                 * when the plan had nothing left to apply — which is what a plan looks
+                 * like after every prop in it was stripped as unsupported by the block.
+                 * Answering both with `status: "applied"` and "already up to date"
+                 * tells an author their content is fine when their request was in fact
+                 * dropped, and it is the shape of failure nobody reports, because the
+                 * product said it worked.
+                 *
+                 * The two sibling branches in this file already draw this line — the
+                 * approval-gate no-op at `planPreview.appliedCount === 0` and the
+                 * empty-plan branch that refuses to claim up-to-date-ness for an
+                 * `edit_plan` intent. This was the third one, and it was the one an
+                 * adopter hit.
+                 */
+                /*
+                 * A note from the hallucination validator outranks both engine
+                 * messages. It means this turn asked for a field the block does not
+                 * have, which is a better answer than either of them and the only one
+                 * that names the block — and it is true whichever message the engine
+                 * happened to throw, since an op stripped to an empty patch can land in
+                 * `skippedOps` and read as "matched existing values".
+                 */
+                const noopSummary = strippedPropsNote ??
+                    (isAlreadyCurrentError(reason)
+                        ? "No changes needed — that content is already set."
+                        : "I couldn't make that change — it isn't supported on this block. Try a different field or wording.");
                 return {
                     done: true,
                     response: {
                         code: 200,
                         payload: withDebugPayload({
-                            status: "applied",
-                            summary: "No changes needed. That content is already up to date.",
+                            // `info`, not `applied`: nothing was applied either way, and the
+                            // approval-gate branch above has answered `info` for the same
+                            // fact since it was written.
+                            status: "info",
+                            summary: noopSummary,
                             changes: [],
                             mentionedSlugs: [effectiveSlug],
                             previewVersion: versions.get(body.session) ?? 0,

package/dist/chat/hallucination-validator.d.ts

@@ -19,6 +19,11 @@ export type HallucinatedProp = {
 export type HallucinationValidationResult = {
     plan: EditPlan;
     hallucinatedProps: HallucinatedProp[];
+    /**
+     * The user-facing note appended to `summary_for_user` and `change_log`,
+     * when props were stripped. Absent when nothing was.
+     */
+    note?: string;
 };
 /**
  * Scan every `update_props` op in the plan, strip patch keys that are not

package/dist/chat/hallucination-validator.js

@@ -105,6 +105,19 @@ export function validateAndStripHallucinatedProps(args) {
         const summary = plan.summary_for_user?.trimEnd() ?? "";
         plan.summary_for_user = summary.length > 0 ? `${summary}\n\n${note}` : note;
         plan.change_log = [...plan.change_log, note];
+        /*
+         * Returned as well as appended, for two callers that both need it back.
+         *
+         * The changelog-coverage validator runs next and trims trailing entries
+         * when there are more of them than ops — and this note is always the last
+         * entry, so it was always the one trimmed. It has to be told which entry is
+         * a note rather than an op narration.
+         *
+         * And the no-effective-change handler replaces `summary_for_user` wholesale
+         * with a canned line, which is exactly the case where this note is the only
+         * true thing anyone wrote about the turn.
+         */
+        return { plan, hallucinatedProps, note };
     }
     return { plan, hallucinatedProps };
 }

package/dist/cms/adapter.d.ts

@@ -57,6 +57,41 @@ export type CmsPublishResult = void | {
     error?: string;
     unsupported?: string[];
 };
+/**
+ * One asset from a CMS's media library, in the shape the editor's image picker
+ * renders. Deliberately the smallest projection that a picker needs: an
+ * identity, something to show, something to insert, and something to put in an
+ * `alt`. Anything richer would be a per-CMS shape again.
+ */
+export interface CmsMediaItem {
+    /** Stable id in the source store. Used as the picker's selection key. */
+    id: string;
+    /** Human-facing filename or title, if the store has one. */
+    name?: string;
+    /** Full-size URL to insert into the page. Omitted only if the store has none. */
+    imageUrl?: string;
+    /** Grid thumbnail. May be the same URL as `imageUrl` when no derivative exists. */
+    thumbUrl: string;
+    /** Alt text the store already holds, so the editor does not invent one. */
+    alt?: string;
+}
+/** One page of a media-library search. */
+export interface CmsMediaQuery {
+    /** Free-text filter. Empty or absent means "everything, newest first". */
+    query?: string;
+    /** 1-based page number. */
+    page: number;
+    /** Items per page. */
+    limit: number;
+}
+/** What `getMedia` returns: the page, and how many there are in total. */
+export interface CmsMediaPage {
+    items: CmsMediaItem[];
+    /** Total pages for this query, so the picker knows whether to offer "load more". */
+    totalPages: number;
+    /** Display name for the tab, e.g. "Sanity". Defaults to the adapter's `id`. */
+    label?: string;
+}
 /**
  * Which side of a CMS's draft/published split a read wants.
  *
@@ -146,6 +181,24 @@ export interface CmsAdapter {
      * unreachable, so it cannot be a method that reads upstream.
      */
     readonly capabilities?: CmsCapabilities;
+    /**
+     * Optional media-library read, for the editor's image picker.
+     *
+     * The picker used to reach the CMS from the browser, over a closed union of
+     * three providers compiled into the editor app. That made the image picker
+     * the one part of an integration that could not be integrated: a site could
+     * bring its own adapter, its own blocks and its own publish handler, and
+     * still had no way to bring its own images short of a change to Avocado.
+     *
+     * Implement it and the tab appears. Leave it off and it does not — silence
+     * means no here, the same way it does for `perspectives`, because a picker
+     * that offers a tab it cannot fill is worse than no tab.
+     *
+     * `cmsMediaSource()` in `./media-sources.ts` implements this for Contentful,
+     * Sanity and Strapi if one of those is what you have; it is a helper, not a
+     * requirement, and nothing in the route path knows it exists.
+     */
+    getMedia?(query: CmsMediaQuery): Promise<CmsMediaPage>;
 }
 /**
  * Per-operation capability declaration. Every field is tri-state, and the
@@ -203,6 +256,15 @@ export interface ResolvedCapabilities {
      * knows not to conclude "nothing is pending" from an empty diff.
      */
     readsDraftPerspective: boolean;
+    /**
+     * True when the adapter can list the CMS's media library; derived from the
+     * presence of `getMedia`, never declared as a capability.
+     *
+     * The editor reads it to decide whether to offer a CMS tab in the image
+     * picker at all, which is why it is derived rather than declared: a tab that
+     * opens onto a method nobody implemented is a worse answer than no tab.
+     */
+    readsMedia: boolean;
     /**
      * The subset the adapter actually declared. A caller that needs to
      * distinguish "this site says no" from "nobody said" reads this; everything

package/dist/cms/adapter.js

@@ -14,6 +14,7 @@ export function resolveCapabilities(adapter, override) {
         publishesUpstream: typeof adapter?.onPublish === "function",
         // `=== true`, not truthiness: an adapter that says nothing has not said yes.
         readsDraftPerspective: adapter?.perspectives === true,
+        readsMedia: typeof adapter?.getMedia === "function",
         declared
     };
 }

package/dist/cms/index.d.ts

@@ -1,5 +1,6 @@
-export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./adapter.ts";
+export type { CmsAdapter, CmsMediaItem, CmsMediaPage, CmsMediaQuery, 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, warmSessionBootstrap } from "./bootstrap.ts";
+export { cmsMediaSource, cmsMediaLabel, mediaSourceFromUnknown, type CmsMediaSource, type CmsMediaSourceConfig } from "./media-sources.ts";

package/dist/cms/index.js

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

package/dist/cms/media-sources.d.ts

@@ -0,0 +1,49 @@
+import type { CmsMediaPage, CmsMediaQuery } from "./adapter.ts";
+/** Connection details for one of the built-in media readers. */
+export type CmsMediaSourceConfig = {
+    provider: "contentful";
+    spaceId: string;
+    deliveryToken: string;
+    environment?: string;
+} | {
+    provider: "sanity";
+    projectId: string;
+    dataset?: string;
+    token?: string;
+} | {
+    provider: "strapi";
+    url: string;
+    token?: string;
+};
+/** A media reader: the exact shape of `CmsAdapter.getMedia`. */
+export type CmsMediaSource = (query: CmsMediaQuery) => Promise<CmsMediaPage>;
+/** Display name for a provider id, for the picker's tab. */
+export declare function cmsMediaLabel(provider: CmsMediaSourceConfig["provider"]): string;
+/**
+ * Build a media reader from connection details.
+ *
+ * ```ts
+ * export function sanityAdapter(): CmsAdapter {
+ *   return {
+ *     id: "sanity",
+ *     getPages: …,
+ *     getMedia: cmsMediaSource({ provider: "sanity", projectId, dataset })
+ *   }
+ * }
+ * ```
+ *
+ * Every reader answers an empty page rather than throwing when the upstream
+ * call fails: a picker tab that renders nothing is recoverable, and a rejected
+ * promise inside a modal is not.
+ */
+export declare function cmsMediaSource(config: CmsMediaSourceConfig): CmsMediaSource;
+/**
+ * Build a reader from an untrusted object, or `null` if it is not one of the
+ * three shapes.
+ *
+ * The editor sends this over the wire, so every field is checked rather than
+ * asserted. A partially-filled form — the drawer creates `{ provider:
+ * "sanity", projectId: "" }` the moment the provider is picked — must read as
+ * "not configured" and not as a reader that will 404 on every request.
+ */
+export declare function mediaSourceFromUnknown(raw: unknown): CmsMediaSource | null;

package/dist/cms/media-sources.js

@@ -0,0 +1,182 @@
+const LABELS = {
+    contentful: "Contentful",
+    sanity: "Sanity",
+    strapi: "Strapi"
+};
+/** Display name for a provider id, for the picker's tab. */
+export function cmsMediaLabel(provider) {
+    return LABELS[provider];
+}
+const EMPTY = (label) => ({ items: [], totalPages: 0, label });
+/**
+ * Build a media reader from connection details.
+ *
+ * ```ts
+ * export function sanityAdapter(): CmsAdapter {
+ *   return {
+ *     id: "sanity",
+ *     getPages: …,
+ *     getMedia: cmsMediaSource({ provider: "sanity", projectId, dataset })
+ *   }
+ * }
+ * ```
+ *
+ * Every reader answers an empty page rather than throwing when the upstream
+ * call fails: a picker tab that renders nothing is recoverable, and a rejected
+ * promise inside a modal is not.
+ */
+export function cmsMediaSource(config) {
+    switch (config.provider) {
+        case "contentful": return (q) => contentfulMedia(config, q);
+        case "sanity": return (q) => sanityMedia(config, q);
+        case "strapi": return (q) => strapiMedia(config, q);
+    }
+}
+// ---------------------------------------------------------------------------
+// Contentful — Delivery API, `skip`/`limit` paging, `total` in the envelope.
+// ---------------------------------------------------------------------------
+async function contentfulMedia(config, { query, page, limit }) {
+    const label = LABELS.contentful;
+    const env = config.environment ?? "master";
+    const params = new URLSearchParams({
+        access_token: config.deliveryToken,
+        limit: String(limit),
+        skip: String((page - 1) * limit),
+        mimetype_group: "image"
+    });
+    if (query)
+        params.set("query", query);
+    const res = await fetch(`https://cdn.contentful.com/spaces/${config.spaceId}/environments/${env}/assets?${params}`);
+    if (!res.ok)
+        return EMPTY(label);
+    const data = (await res.json());
+    const items = (data.items ?? [])
+        .filter((item) => item.sys?.id && item.fields?.file?.url)
+        .map((item) => {
+        const url = item.fields.file.url;
+        // Contentful returns protocol-relative asset URLs.
+        const fullUrl = url.startsWith("//") ? `https:${url}` : url;
+        return {
+            id: item.sys.id,
+            name: item.fields?.title,
+            alt: item.fields?.description ?? item.fields?.title,
+            imageUrl: fullUrl,
+            thumbUrl: `${fullUrl}?w=200&h=200&fit=thumb`
+        };
+    });
+    return { items, totalPages: Math.ceil((data.total ?? 0) / limit), label };
+}
+// ---------------------------------------------------------------------------
+// Sanity — GROQ, slice paging, a second query for the count.
+// ---------------------------------------------------------------------------
+async function sanityMedia(config, { query, page, limit }) {
+    const label = LABELS.sanity;
+    const dataset = config.dataset ?? "production";
+    const offset = (page - 1) * limit;
+    const end = offset + limit - 1;
+    // GROQ is interpolated, so the filter term is stripped of the two characters
+    // that could close the string literal it lands inside.
+    const safeQuery = (query ?? "").replace(/["\\]/g, "");
+    const filter = safeQuery
+        ? `_type == "sanity.imageAsset" && originalFilename match "*${safeQuery}*"`
+        : `_type == "sanity.imageAsset"`;
+    const groq = `*[${filter}] | order(_createdAt desc) [${offset}..${end}] { _id, url, originalFilename, metadata { dimensions } }`;
+    const countGroq = `count(*[${filter}])`;
+    const base = `https://${config.projectId}.api.sanity.io/v2024-01-01/data/query/${dataset}`;
+    const headers = {};
+    if (config.token)
+        headers.authorization = `Bearer ${config.token}`;
+    const [assetsRes, countRes] = await Promise.all([
+        fetch(`${base}?query=${encodeURIComponent(groq)}`, { headers }),
+        fetch(`${base}?query=${encodeURIComponent(countGroq)}`, { headers })
+    ]);
+    if (!assetsRes.ok)
+        return EMPTY(label);
+    const assets = (await assetsRes.json());
+    const count = countRes.ok ? (await countRes.json()).result ?? 0 : 0;
+    return {
+        items: (assets.result ?? []).map((asset) => ({
+            id: asset._id,
+            name: asset.originalFilename,
+            alt: asset.originalFilename,
+            imageUrl: asset.url,
+            thumbUrl: `${asset.url}?w=200&h=200&fit=crop`
+        })),
+        totalPages: Math.ceil(count / limit),
+        label
+    };
+}
+// ---------------------------------------------------------------------------
+// Strapi — upload plugin, page/pageSize paging, count in a response header.
+// ---------------------------------------------------------------------------
+async function strapiMedia(config, { query, page, limit }) {
+    const label = LABELS.strapi;
+    const baseUrl = config.url.replace(/\/+$/, "");
+    const params = new URLSearchParams({
+        "filters[mime][$startsWith]": "image",
+        "pagination[page]": String(page),
+        "pagination[pageSize]": String(limit),
+        sort: "createdAt:desc"
+    });
+    if (query)
+        params.set("filters[name][$containsi]", query);
+    const headers = {};
+    if (config.token)
+        headers.authorization = `Bearer ${config.token}`;
+    const res = await fetch(`${baseUrl}/api/upload/files?${params}`, { headers });
+    if (!res.ok)
+        return EMPTY(label);
+    const data = (await res.json());
+    const absolute = (u) => (u.startsWith("http") ? u : `${baseUrl}${u}`);
+    // The upload endpoint returns a bare array; the count is a header.
+    const totalCount = Number(res.headers.get("x-total-count") ?? data.length);
+    return {
+        items: data.map((file) => ({
+            id: file.documentId ?? String(file.id),
+            name: file.name,
+            alt: file.name,
+            imageUrl: absolute(file.url),
+            thumbUrl: file.formats?.thumbnail?.url ? absolute(file.formats.thumbnail.url) : absolute(file.url)
+        })),
+        totalPages: Math.ceil(totalCount / limit),
+        label
+    };
+}
+/**
+ * Build a reader from an untrusted object, or `null` if it is not one of the
+ * three shapes.
+ *
+ * The editor sends this over the wire, so every field is checked rather than
+ * asserted. A partially-filled form — the drawer creates `{ provider:
+ * "sanity", projectId: "" }` the moment the provider is picked — must read as
+ * "not configured" and not as a reader that will 404 on every request.
+ */
+export function mediaSourceFromUnknown(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    const str = (v) => typeof v === "string" && v.trim() ? v.trim() : undefined;
+    switch (obj.provider) {
+        case "contentful": {
+            const spaceId = str(obj.spaceId);
+            const deliveryToken = str(obj.deliveryToken);
+            if (!spaceId || !deliveryToken)
+                return null;
+            return cmsMediaSource({ provider: "contentful", spaceId, deliveryToken, environment: str(obj.environment) });
+        }
+        case "sanity": {
+            const projectId = str(obj.projectId);
+            if (!projectId)
+                return null;
+            return cmsMediaSource({ provider: "sanity", projectId, dataset: str(obj.dataset), token: str(obj.token) });
+        }
+        case "strapi": {
+            const url = str(obj.url);
+            if (!url)
+                return null;
+            return cmsMediaSource({ provider: "strapi", url, token: str(obj.token) });
+        }
+        default:
+            return null;
+    }
+}

package/dist/handler/auth.js

@@ -29,7 +29,13 @@ import { isAccessGateEnabled, isValidAccessToken, extractAccessToken } from "../
  * 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"]);
+/*
+ * `/health` is here because a probe that needs a credential is not a probe. The
+ * CLI calls it before it has one, to compare protocol versions, and it answers
+ * nothing about the site's content — only that this is an Avocado orchestrator
+ * and which protocol it speaks.
+ */
+const PUBLIC_PATHS = new Set(["/auth/status", "/auth/verify", "/health"]);
 export function isPublicPath(path, method) {
     if (method === "OPTIONS")
         return true;

package/dist/handler/create-orchestrator.js

@@ -21,7 +21,7 @@ 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 { operationSchema, blockManifestSchema, siteConfigSchema, declareBlockCatalogue, undeclaredBlockTypes, EDITOR_PROTOCOL_VERSION } 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";
@@ -47,6 +47,7 @@ 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 { mediaSourceFromUnknown } from "../cms/media-sources.js";
 import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../http/access-tokens.js";
 import { checkAuth, resolveAuth } from "./auth.js";
 const defaultModelLookup = () => ({
@@ -196,6 +197,7 @@ function jsonResponse(body, init = {}) {
  * only thing that keeps a list like this honest.
  */
 const SUPPORTED_ROUTES = [
+    "GET /health",
     "GET /auth/status",
     "POST /auth/verify",
     "POST /chat",
@@ -228,6 +230,7 @@ const SUPPORTED_ROUTES = [
     "POST /restore/snapshot",
     "DELETE /restore/snapshot",
     "GET /unsplash/search",
+    "POST /media/cms",
     "GET+POST /telemetry/chat/feedback",
     "POST /preview/screenshot",
     "POST /audio/transcribe",
@@ -834,6 +837,10 @@ export function createOrchestrator(config = {}) {
                     unsplash: Boolean(process.env.UNSPLASH_ACCESS_KEY),
                     imageGenerate: hasImageBackend,
                     imageGenerateChat: hasImageBackend,
+                    /* Whether this mount's adapter can list a media library. The
+                     * editor offers the picker's CMS tab on it, so silence hides the
+                     * tab rather than opening one onto a method nobody implemented. */
+                    cmsMedia: runtime.capabilities.readsMedia,
                     agentMode: false
                 },
                 /*
@@ -899,7 +906,9 @@ export function createOrchestrator(config = {}) {
                 })),
                 // Which content this is — see orchestrator-core/http/draft-provenance.ts.
                 ...describeDraft({
-                    requestedSiteId: siteId ?? effectiveSiteId,
+                    // Config first, matching every other route: a mount that names its
+                    // site knows better than a request that forgot to.
+                    requestedSiteId: effectiveSiteId ?? siteId,
                     scopedSession,
                     pageCount: pages.length,
                     hasAdapter: Boolean(runtime.adapter)
@@ -1243,12 +1252,38 @@ export function createOrchestrator(config = {}) {
             }
             return actionResponse(blocksManifestAction(), cors);
         }
+        /*
+         * Liveness and protocol version, for a client deciding whether it can talk
+         * to this build at all.
+         *
+         * The standalone orchestrator has always answered this; library mode never
+         * did, so `avocado-cli start` probed it, got a 405, and printed
+         * "Orchestrator /health returned 405. CLI started anyway." on every start —
+         * a warning that means nothing, from the CLI's only compatibility check,
+         * which could therefore never pass against an embedded mount.
+         *
+         * Deliberately before the auth gate (see `PUBLIC_PATHS`) and deliberately
+         * content-free: it says what this process is, never what it holds.
+         */
+        if (request.method === "GET" && path === "/health") {
+            return jsonResponse({ ok: true, mode: "library", protocolVersion: EDITOR_PROTOCOL_VERSION }, { 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);
+            /*
+             * `scope()` resolves the site the mount serves; `whoamiAction` re-derives
+             * the session key from what it is handed. Handing it the raw query meant
+             * the two disagreed whenever the caller omitted `siteId` — the bootstrap
+             * seeded `library::default` and the answer was read from the legacy key,
+             * so a correctly configured mount reported Avocado's bundled demo
+             * content, `source: "demo"`, and all-true capabilities in place of the
+             * adapter's own. The note even said "No siteId was supplied", which was
+             * true of the request and false of the configuration.
+             */
+            return actionResponse(whoamiAction({ ...query, siteId: effectiveSiteId ?? query.siteId }, url.origin, { hasAdapter: Boolean(runtime.adapter) }), cors);
         }
         /*
          * Publishing status, history and preview.
@@ -1360,6 +1395,53 @@ export function createOrchestrator(config = {}) {
             }
             return actionResponse(await restoreSnapshotDelete((raw ?? {})), cors);
         }
+        /*
+         * The CMS tab of the image picker.
+         *
+         * Two callers, one route. A library-mode site whose adapter implements
+         * `getMedia` needs to send nothing: the credentials are already in the
+         * process serving this request. The standalone multi-site orchestrator
+         * wires no adapter at all, so the editor sends the per-site connection
+         * details it holds and the route builds a reader from them.
+         *
+         * The adapter wins when both are available — a site that implemented the
+         * seam meant it, and its own reader can see things a generic one cannot.
+         *
+         * POST rather than GET because the second form carries a token, and a
+         * token in a query string is a token in every access log between here and
+         * the browser.
+         */
+        if (request.method === "POST" && path === "/media/cms") {
+            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 query = typeof body.query === "string" ? body.query.trim() : "";
+            const page = Math.max(1, Math.trunc(Number(body.page) || 1));
+            const limit = Math.min(50, Math.max(1, Math.trunc(Number(body.limit) || 20)));
+            const source = typeof runtime.adapter?.getMedia === "function"
+                ? runtime.adapter.getMedia.bind(runtime.adapter)
+                : mediaSourceFromUnknown(body.config);
+            /* No adapter method and no usable config is "this site has no media
+             * library", which is a 404 and not an empty page — the editor hides the
+             * tab on the former and renders an empty grid on the latter. */
+            if (!source)
+                return jsonResponse({ error: "CMS media not configured" }, { status: 404, cors });
+            try {
+                const result = await source({ query: query || undefined, page, limit });
+                return jsonResponse(result, { cors });
+            }
+            catch (error) {
+                runtime.log.warn?.({ err: error }, "[avocado] CMS media read failed");
+                return jsonResponse({ items: [], totalPages: 0 }, { 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") {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createOrchestrator, type CreateOrchestratorConfig, type OrchestratorHandler } from "./handler/create-orchestrator.ts";
 export type { OrchestratorAuth, AuthContext } from "./handler/auth.ts";
-export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, ResolvedCapabilities } from "./cms/adapter.ts";
-export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, type JsonFileAdapterOptions, type EditorApiAdapterOptions } from "./cms/index.ts";
+export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, CmsMediaItem, CmsMediaPage, CmsMediaQuery, ResolvedCapabilities } from "./cms/adapter.ts";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel, type JsonFileAdapterOptions, type EditorApiAdapterOptions, type CmsMediaSource, type CmsMediaSourceConfig } from "./cms/index.ts";

package/dist/index.js

@@ -18,4 +18,4 @@
 //
 // The Fastify HTTP wrapper lives in apps/orchestrator and imports from here.
 export { createOrchestrator } from "./handler/create-orchestrator.js";
-export { jsonFileAdapter, editorApiAdapter, resolveCapabilities } from "./cms/index.js";
+export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaLabel } from "./cms/index.js";

package/dist/ops/ops-engine.d.ts

@@ -4,6 +4,23 @@ import type { ContentSource } from "../state/content-source.ts";
 import type { PublishDiff } from "@avocadostudio-ai/shared";
 export declare const toErrorDetail: typeof _unifiedToErrorDetail;
 export declare function isNoEffectiveChangeError(reason: string): boolean;
+/**
+ * Within a no-effective-change, did the stored values already match?
+ *
+ * The engine throws two different things and they are not the same fact:
+ *
+ *   "No effective prop change across plan. All update patches matched
+ *    existing values."   → the content really was already what was asked for
+ *   "Edit plan produced no changes"
+ *                        → the plan had nothing left to apply, which is what
+ *                          happens when every prop in it was stripped as
+ *                          unsupported by the block
+ *
+ * Reporting the second as the first tells the author their content is up to
+ * date when their request was in fact dropped. Both messages are pinned by
+ * `isNoEffectiveChangeError` above, so they are already load-bearing strings.
+ */
+export declare function isAlreadyCurrentError(reason: string): boolean;
 export declare function classifyGuardrailError(reason: string): GuardrailErrorCategory;
 export declare function formatValidationError(reason: string): string;
 export declare function isDeterministicRepairEligible(reason: string): boolean;

package/dist/ops/ops-engine.js

@@ -159,6 +159,25 @@ export function isNoEffectiveChangeError(reason) {
     //   "No effective meta change for…"          /  "Edit plan produced no changes"
     return /no effective \w+ change/i.test(reason) || /produced no changes/i.test(reason);
 }
+/**
+ * Within a no-effective-change, did the stored values already match?
+ *
+ * The engine throws two different things and they are not the same fact:
+ *
+ *   "No effective prop change across plan. All update patches matched
+ *    existing values."   → the content really was already what was asked for
+ *   "Edit plan produced no changes"
+ *                        → the plan had nothing left to apply, which is what
+ *                          happens when every prop in it was stripped as
+ *                          unsupported by the block
+ *
+ * Reporting the second as the first tells the author their content is up to
+ * date when their request was in fact dropped. Both messages are pinned by
+ * `isNoEffectiveChangeError` above, so they are already load-bearing strings.
+ */
+export function isAlreadyCurrentError(reason) {
+    return /no effective \w+ change/i.test(reason);
+}
 export function classifyGuardrailError(reason) {
     const lower = reason.toLowerCase();
     if (isNoEffectiveChangeError(reason))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -23,8 +23,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.34.5",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "0.2.1",
-    "@avocadostudio-ai/shared": "0.2.1"
+    "@avocadostudio-ai/migration-sdk": "^0.3.0",
+    "@avocadostudio-ai/shared": "^0.3.0"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",
@@ -44,6 +44,17 @@
     "dist"
   ],
   "description": "Core Avocado Studio orchestrator — session state, AI planning, operations engine, publishing",
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "cms",
+    "ai",
+    "llm",
+    "content-editor",
+    "page-builder",
+    "headless-cms",
+    "visual-editing"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/orchestrator-core#readme",
   "bugs": {