@avocadostudio-ai/orchestrator-core 0.5.0 → 0.5.1

package/dist/agent/sites-agent-context.js

@@ -44,8 +44,16 @@ export function buildBlockCatalog() {
             continue; // skip chrome blocks
         const guide = BLOCK_VISUAL_GUIDE[type];
         // Compact: Type — description | props | list fields
+        /*
+         * `reference` is dropped rather than annotated. It is a pointer the CMS
+         * owns — a story link, an entry link — and a model handed the prop name
+         * will eventually write a string into it, which replaces the pointer with a
+         * hard-coded URL that stops following renames. A prop that must never be
+         * written is not a prop worth naming.
+         */
+        const writable = ([, fm]) => fm.kind !== "headingLevel" && fm.kind !== "reference";
         const fieldParts = Object.entries(meta.fields)
-            .filter(([, fm]) => fm.kind !== "headingLevel") // skip headingLevel — always optional noise
+            .filter(writable) // headingLevel is always optional noise
             .map(([key, fm]) => {
             const req = fm.required ? "" : "?";
             const opts = fm.kind === "enum" && fm.options ? `(${fm.options.join("|")})` : "";
@@ -54,7 +62,7 @@ export function buildBlockCatalog() {
         const listParts = meta.listFields
             ? Object.entries(meta.listFields).map(([listKey, listMeta]) => {
                 const items = Object.entries(listMeta.itemFields)
-                    .filter(([, fm]) => fm.kind !== "headingLevel")
+                    .filter(writable)
                     .map(([k, fm]) => `${k}${fm.required ? "" : "?"}`);
                 return `${listKey}[]{${items.join(",")}}`;
             })

package/dist/chat/anthropic-planner.js

@@ -336,13 +336,19 @@ export async function generatePlanWithAnthropic(args) {
     const attachmentBlocks = resolvedAttachments.map((attachment) => attachment.kind === "pdf"
         ? { type: "document", source: { type: "base64", media_type: "application/pdf", data: attachment.base64 } }
         : { type: "image", source: { type: "base64", media_type: attachment.mediaType, data: attachment.base64 } });
-    const visionBlocks = imageUrlForVision
-        ? [
-            imageBase64
-                ? { type: "image", source: { type: "base64", media_type: imageBase64.mediaType, data: imageBase64.base64 } }
-                : { type: "image", source: { type: "url", url: imageUrlForVision } }
-        ]
-        : [];
+    /*
+     * A URL source is only ever https. Anthropic rejects anything else with
+     * `400 … Only HTTPS URLs are supported`, and it rejects the *request*, not the
+     * block — so one http image on a selected block failed the whole turn, and the
+     * user saw a raw provider error in place of their answer. `fetchImageAsBase64`
+     * inlines the loopback case; an image we can neither inline nor link is simply
+     * not shown to the model, which costs this turn its vision and nothing else.
+     */
+    const visionBlocks = imageBase64
+        ? [{ type: "image", source: { type: "base64", media_type: imageBase64.mediaType, data: imageBase64.base64 } }]
+        : imageUrlForVision && /^https:\/\//i.test(imageUrlForVision)
+            ? [{ type: "image", source: { type: "url", url: imageUrlForVision } }]
+            : [];
     const userContent = visionBlocks.length > 0 || attachmentBlocks.length > 0
         ? [...visionBlocks, ...attachmentBlocks, { type: "text", text: JSON.stringify(user) }]
         : JSON.stringify(user);

package/dist/chat/hallucination-validator.js

@@ -26,6 +26,26 @@ function allowedPropKeysForBlockType(blockType) {
         return null;
     return new Set(Object.keys(shape));
 }
+/**
+ * Props that hold a pointer the CMS owns.
+ *
+ * These are in the schema and therefore survive every check above, which is the
+ * problem: a Storyblok story link is `{ linktype, id, cached_url }`, a model
+ * writes the rendered href it saw, and the CMS ends up holding a hard-coded URL
+ * where a reference was. It renders identically and silently stops following
+ * renames — the one thing the reference was for. There is no valid value a
+ * planner can produce here, because constructing one needs the CMS's own
+ * document ids, so the op is dropped rather than repaired.
+ */
+function referencePropKeysForBlockType(blockType) {
+    const meta = getBlockMeta(blockType);
+    const keys = new Set();
+    for (const [key, field] of Object.entries(meta?.fields ?? {})) {
+        if (field.kind === "reference")
+            keys.add(key);
+    }
+    return keys;
+}
 /**
  * Look up the current block by id across all pages in the draft. Preferring
  * the targeted page when supplied avoids cross-page collisions on id reuse.
@@ -78,6 +98,7 @@ function humanBlockName(blockType) {
 export function validateAndStripHallucinatedProps(args) {
     const { plan, draft } = args;
     const hallucinatedProps = [];
+    const referenceProps = [];
     for (const op of plan.ops) {
         if (op.op !== "update_props")
             continue;
@@ -93,7 +114,13 @@ export function validateAndStripHallucinatedProps(args) {
         const patchCandidate = rawPatch.props && typeof rawPatch.props === "object" && !Array.isArray(rawPatch.props)
             ? rawPatch.props
             : rawPatch;
+        const referenceKeys = referencePropKeysForBlockType(blockType);
         for (const key of Object.keys(patchCandidate)) {
+            if (referenceKeys.has(key)) {
+                delete patchCandidate[key];
+                referenceProps.push({ blockType, propName: key });
+                continue;
+            }
             if (allowedKeys.has(key))
                 continue;
             delete patchCandidate[key];
@@ -105,7 +132,28 @@ export function validateAndStripHallucinatedProps(args) {
             });
         }
     }
-    if (hallucinatedProps.length > 0) {
+    /*
+     * Said separately from the hallucinated-prop note below, because it is a
+     * different fact about a different kind of field. "The block has no such
+     * field" is false here — the field exists, it is on the page, and the person
+     * can see what it points at. What they cannot do is change it from here.
+     */
+    const referenceNoteParts = [];
+    if (referenceProps.length > 0) {
+        const byBlock = new Map();
+        for (const entry of referenceProps) {
+            const bucket = byBlock.get(entry.blockType) ?? new Set();
+            bucket.add(entry.propName);
+            byBlock.set(entry.blockType, bucket);
+        }
+        for (const [blockType, props] of byBlock) {
+            const name = humanBlockName(blockType);
+            for (const prop of props) {
+                referenceNoteParts.push(`“${prop}” on the ${name} block points at a document in your CMS, so it is changed there rather than here.`);
+            }
+        }
+    }
+    if (hallucinatedProps.length > 0 || referenceNoteParts.length > 0) {
         /*
          * Two different events used to share one sentence, and the wrong one was
          * the default.
@@ -130,7 +178,7 @@ export function validateAndStripHallucinatedProps(args) {
             bucket.add(entry.propName);
             byBlockType.set(entry.blockType, bucket);
         }
-        const noteParts = [];
+        const noteParts = [...referenceNoteParts];
         for (const [blockType, props] of byBlockType) {
             const name = humanBlockName(blockType);
             const visual = [...props].filter(isVisualPropName);

package/dist/chat/planner.js

@@ -1190,9 +1190,18 @@ export async function generatePlanWithOpenAI(args) {
         ? args.contextPack.selected.imageUrlForVision
         : null;
     const imageBase64 = imageUrlForVision ? await fetchImageAsBase64(imageUrlForVision) : null;
+    /*
+     * Same rule as the Anthropic path: a bare URL goes to the provider only when
+     * it is https. A root-relative `/media/...` — which is what a site most often
+     * writes in an image prop — is not a URL any provider can fetch, and sending
+     * it fails the whole call rather than the image. Inline it when we can reach
+     * it, drop it when we cannot.
+     */
     const visionImageUrl = imageBase64
         ? `data:${imageBase64.mediaType};base64,${imageBase64.base64}`
-        : imageUrlForVision;
+        : imageUrlForVision && /^https:\/\//i.test(imageUrlForVision)
+            ? imageUrlForVision
+            : null;
     // User-attached files: images as image_url parts, PDFs as `file` parts with
     // inline base64 data. The `file` content part is only accepted by the gpt-4o /
     // gpt-4.1 / gpt-5 families on chat.completions; sending it to other models

package/dist/cms/adapter.d.ts

@@ -35,14 +35,39 @@ export interface CmsPublishContext {
      * destroys what it was projected from. A publisher has to diff, and it cannot
      * diff against nothing.
      *
+     * **This is the CMS's draft, not the live site**, and the distinction decides
+     * whether a publish is correct. `getPages({ perspective: "draft" })` is what
+     * seeded the session, and the baseline is that same list, so the diff
+     * compares like with like and reports what *this session* changed. Diff
+     * against the live site instead and the difference includes every
+     * unpublished edit anybody made in the CMS — an Avocado publish then ships
+     * all of it, from a button whose label says nothing about that. An adapter
+     * that does not declare `perspectives` ignores the argument and answers with
+     * whatever it has, in which case the two are the same thing anyway.
+     *
      * Absent when the session was never bootstrapped from the adapter, so treat
      * `undefined` as "no baseline available" and not as "the site was empty" —
      * publishing every field on that assumption is the overwrite this exists to
      * prevent. An integration that embeds its own source snapshot in block props
      * (the more precise approach, since only it knows what it projected) can
      * ignore this.
+     *
+     * Prefer `baseline`. This field holds the same array and is kept because
+     * adapters are written against it.
+     *
+     * @deprecated Misnamed — read `baseline`.
      */
     published?: PageDoc[];
+    /**
+     * The same array as `published`, under the name that says what it holds.
+     *
+     * The old name taught the opposite of the truth: an integrator reading
+     * "published" reasons that the baseline is the live site, concludes the diff
+     * would carry colleagues' unpublished work, and designs around a problem the
+     * orchestrator does not have — or, worse, does a second read of the published
+     * perspective and creates it.
+     */
+    baseline?: PageDoc[];
 }
 /**
  * Result of an `onPublish` call. `void` means "success, nothing to report";

package/dist/handler/create-orchestrator.js

@@ -906,8 +906,18 @@ export function createOrchestrator(config = {}) {
                 return jsonResponse({ ok: true, written: false, count: pages.length, reason: "adapter has no onPublish; publish is a no-op" }, { status: 200, cors });
             }
             const config = selection.siteConfig;
+            /*
+             * `baseline` and `published` are the same array. The second name is what
+             * adapters were written against and the first is what it actually holds
+             * — the CMS's *draft*, read with `perspective: "draft"` when the adapter
+             * declares one, which is the only baseline that makes a publish mean
+             * "what this session changed".
+             */
             const context = body.assets || published
-                ? { ...(body.assets ? { assets: body.assets } : {}), ...(published ? { published } : {}) }
+                ? {
+                    ...(body.assets ? { assets: body.assets } : {}),
+                    ...(published ? { published, baseline: published } : {})
+                }
                 : undefined;
             let unsupported = [];
             // Default true: an adapter that does not mention `written` means what

package/dist/nlp/deterministic-planner-context.d.ts

@@ -11,6 +11,25 @@ export declare function readPathValue(root: unknown, path: string): unknown;
  *  - "items[0].image.alt" → props.items[0].image.src
  */
 export declare function resolveImageUrlForAltField(blockProps: Record<string, unknown>, editablePath: string): string | undefined;
+/**
+ * Turn whatever the page wrote in an image prop into a URL something can
+ * actually fetch, or nothing at all.
+ *
+ * `resolveImageUrlForAltField` reads its answer straight out of block props, so
+ * it is whatever the site put there — and a site most often puts a root-relative
+ * path (`/media/pool.webp`), which names a file on the *site* and is not a URL
+ * any model, or this process, can resolve on its own. It went to the provider
+ * verbatim, and Anthropic answered `400 … Only HTTPS URLs are supported` for the
+ * whole request: selecting a hero image and asking an unrelated question failed
+ * the turn outright, over the least important thing it was carrying.
+ *
+ * `previewUrl` is the site's own origin — the same value `/preview/screenshot`
+ * resolves a page path against — so a relative path becomes an absolute one the
+ * loopback fetch below can turn into base64. A site that never declared one
+ * gets `undefined` and loses vision for that turn, which is the correct trade:
+ * the alt text is a nicety, the answer is the request.
+ */
+export declare function absolutizeVisionImageUrl(raw: string, previewUrl?: unknown): string | undefined;
 /**
  * Fetch an image URL and return base64 + media type.
  * For localhost URLs the AI APIs can't reach, we fetch locally.

package/dist/nlp/deterministic-planner-context.js

@@ -1,4 +1,5 @@
 import { getSessionDraft, getRecentEdits, getSiteConfig, orderSlugsHomeFirst } from "../state/session-state.js";
+import { getLibraryMount } from "../handler/library-mount.js";
 import { resolveReferencesFromMessage } from "./deterministic-planner-refs.js";
 // ---------------------------------------------------------------------------
 // Path traversal
@@ -58,6 +59,71 @@ export function resolveImageUrlForAltField(blockProps, editablePath) {
     const value = readPathValue(blockProps, companionPath);
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+/**
+ * Turn whatever the page wrote in an image prop into a URL something can
+ * actually fetch, or nothing at all.
+ *
+ * `resolveImageUrlForAltField` reads its answer straight out of block props, so
+ * it is whatever the site put there — and a site most often puts a root-relative
+ * path (`/media/pool.webp`), which names a file on the *site* and is not a URL
+ * any model, or this process, can resolve on its own. It went to the provider
+ * verbatim, and Anthropic answered `400 … Only HTTPS URLs are supported` for the
+ * whole request: selecting a hero image and asking an unrelated question failed
+ * the turn outright, over the least important thing it was carrying.
+ *
+ * `previewUrl` is the site's own origin — the same value `/preview/screenshot`
+ * resolves a page path against — so a relative path becomes an absolute one the
+ * loopback fetch below can turn into base64. A site that never declared one
+ * gets `undefined` and loses vision for that turn, which is the correct trade:
+ * the alt text is a nicety, the answer is the request.
+ */
+export function absolutizeVisionImageUrl(raw, previewUrl) {
+    if (!raw)
+        return undefined;
+    if (/^data:/i.test(raw))
+        return undefined;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(raw))
+        return raw;
+    // Protocol-relative (`//host/x.png`) has an origin already; anything else
+    // relative needs one, and only the site can supply it.
+    if (raw.startsWith("//"))
+        return `https:${raw}`;
+    if (typeof previewUrl !== "string" || previewUrl.trim() === "")
+        return undefined;
+    try {
+        return new URL(raw, previewUrl.replace(/\/+$/, "") + "/").toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The origin a relative image path belongs to: this site's own.
+ *
+ * Two sources, because neither covers both modes. `previewUrl` is what
+ * `/sites/register` writes and what `/preview/screenshot` resolves page paths
+ * against — but library mode passes it to `createOrchestrator()` rather than
+ * registering it, so it is absent from the config of the very sites whose
+ * content is most likely to be relative. The library mount is that site's own
+ * address, observed from a request it actually served, so its origin is the
+ * site: exactly the base a `/media/...` path is written against.
+ */
+function siteOriginForVision(session) {
+    // `previewUrl` is not in `siteConfigSchema` — `/sites/register` merges it in
+    // as an unvalidated extra, so it can only be read off the config as unknown.
+    const registered = getSiteConfig(session).previewUrl;
+    if (typeof registered === "string" && registered.trim() !== "")
+        return registered;
+    const mount = getLibraryMount();
+    if (!mount)
+        return undefined;
+    try {
+        return new URL(mount).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
 function isLocalUrl(url) {
     try {
         const parsed = new URL(url);
@@ -302,6 +368,12 @@ export function plannerContextPack(args) {
     const { session, slug, message, currentPage, activeBlockId, activeBlockType, activeEditablePath } = args;
     const pageRoutes = orderSlugsHomeFirst(Array.from(getSessionDraft(session).keys()));
     const siteConfigSummary = summarizeSiteConfigForPlanner(getSiteConfig(session), pageRoutes);
+    const rawVisionImageUrl = activeBlockId && activeEditablePath
+        ? resolveImageUrlForAltField((currentPage.blocks.find((b) => b.id === activeBlockId)?.props ?? {}), activeEditablePath)
+        : undefined;
+    const visionImageUrl = rawVisionImageUrl
+        ? absolutizeVisionImageUrl(rawVisionImageUrl, siteOriginForVision(session))
+        : undefined;
     const selectedIdx = activeBlockId ? currentPage.blocks.findIndex((b) => b.id === activeBlockId) : -1;
     const neighbors = selectedIdx >= 0
         ? {
@@ -320,9 +392,7 @@ export function plannerContextPack(args) {
             blockType: activeBlockType ?? null,
             editablePath: activeEditablePath ?? null,
             block: selectedBlockSnapshot({ currentPage, activeBlockId, activeEditablePath }),
-            imageUrlForVision: activeBlockId && activeEditablePath
-                ? resolveImageUrlForAltField((currentPage.blocks.find((b) => b.id === activeBlockId)?.props ?? {}), activeEditablePath) ?? null
-                : null
+            imageUrlForVision: visionImageUrl ?? null
         },
         neighbors: {
             previous: neighbors.previous ? { id: neighbors.previous.id, type: neighbors.previous.type } : null,

package/dist/state/session-state.d.ts

@@ -252,6 +252,27 @@ export declare function publishedPageCountGlobal(): number;
 export declare function markRecentlyRestored(session: string): void;
 export declare function consumeRecentlyRestored(session: string): boolean;
 export declare const toErrorDetail: typeof _unifiedToErrorDetail;
+/**
+ * Fill in the props Avocado's own Hero and TwoColumn need but a stored page may
+ * predate.
+ *
+ * **Only for blocks Avocado defines.** Both halves are keyed on a type *name*,
+ * and a name is all a site's own `Hero` shares with ours. Run them against one
+ * and they invent content: a `Hero` whose image lives in `backgroundAsset` is
+ * given an `imageUrl` pointing at our placeholder and an English alt string on
+ * a German page; a `TwoColumn` with its own `variant` has it rewritten to
+ * `"default"`, and its `heading`/`body` are copied into a `left`/`right` pair
+ * it does not render. Nothing is lost visibly, because the site renders its own
+ * props and ignores the additions — but they land in the draft, the publish
+ * baseline is the un-mutated page the adapter returned, so the diff attributes
+ * every one of them to the session, and a publish writes them into the CMS.
+ * This ran on the CMS seed path, which is where a page nobody edited picks them
+ * up.
+ *
+ * `isBuiltinBlock` is written at registration, so a site that registers over
+ * `Hero` turns both halves off for its own blocks and leaves them on for any
+ * built-in it still uses.
+ */
 export declare function ensureHeroImageProps(page: PageDoc): void;
 export declare function orderSlugsHomeFirst(slugs: string[]): string[];
 /**

package/dist/state/session-state.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { demoPublishedPages, demoSiteConfig, ensureItemIds, IMAGE_PLACEHOLDER } from "@avocadostudio-ai/shared";
+import { demoPublishedPages, demoSiteConfig, ensureItemIds, IMAGE_PLACEHOLDER, isBuiltinBlock } from "@avocadostudio-ai/shared";
 import { toErrorDetail as _unifiedToErrorDetail } from "../errors.js";
 import { archiveMigratedJson, getStore, notePersistenceFailure, notePersistenceSuccess, readLegacyJson, resolveDbFile, resolveJsonMigrationTtlDays, sweepStaleMigrations, } from "./sqlite-store-singleton.js";
 import { discardPendingProposalsForSession, sweepExpiredProposals } from "../durable/durable-store-singleton.js";
@@ -255,9 +255,32 @@ export const toErrorDetail = _unifiedToErrorDetail;
 // ---------------------------------------------------------------------------
 // Hero image prop guard (needed by getSessionDraft, setPage, applyPersistedState)
 // ---------------------------------------------------------------------------
+/**
+ * Fill in the props Avocado's own Hero and TwoColumn need but a stored page may
+ * predate.
+ *
+ * **Only for blocks Avocado defines.** Both halves are keyed on a type *name*,
+ * and a name is all a site's own `Hero` shares with ours. Run them against one
+ * and they invent content: a `Hero` whose image lives in `backgroundAsset` is
+ * given an `imageUrl` pointing at our placeholder and an English alt string on
+ * a German page; a `TwoColumn` with its own `variant` has it rewritten to
+ * `"default"`, and its `heading`/`body` are copied into a `left`/`right` pair
+ * it does not render. Nothing is lost visibly, because the site renders its own
+ * props and ignores the additions — but they land in the draft, the publish
+ * baseline is the un-mutated page the adapter returned, so the diff attributes
+ * every one of them to the session, and a publish writes them into the CMS.
+ * This ran on the CMS seed path, which is where a page nobody edited picks them
+ * up.
+ *
+ * `isBuiltinBlock` is written at registration, so a site that registers over
+ * `Hero` turns both halves off for its own blocks and leaves them on for any
+ * built-in it still uses.
+ */
 export function ensureHeroImageProps(page) {
     for (const block of page.blocks) {
         const props = block.props;
+        if (!isBuiltinBlock(block.type))
+            continue;
         if (block.type === "Hero") {
             // Skip imageUrl fallback if the block uses carouselImages instead
             if (typeof props.imageUrl !== "string" || props.imageUrl.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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.5.0",
-    "@avocadostudio-ai/shared": "^0.5.0"
+    "@avocadostudio-ai/migration-sdk": "^0.5.1",
+    "@avocadostudio-ai/shared": "^0.5.1"
   },
   "devDependencies": {
     "@google/genai": "^1.46.0",