@avocadostudio-ai/orchestrator-core 0.5.0 → 0.6.0

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

@@ -44,8 +44,21 @@ export function buildBlockCatalog() {
             continue; // skip chrome blocks
         const guide = BLOCK_VISUAL_GUIDE[type];
         // Compact: Type — description | props | list fields
+        /*
+         * An `internal` field is dropped for a stronger reason than either: it is
+         * the CMS's own bookkeeping — a `_uid`, a revision stamp — and the site
+         * has said outright that it is not content. Naming it invites an edit to
+         * it.
+         *
+         * `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" && !fm.internal;
         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 +67,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/chat-pipeline-translation.js

@@ -232,6 +232,17 @@ export function findExplicitCtaTargetCoverageGap(args) {
 function isTranslatableKind(kind) {
     return kind === "text" || kind === "richtext" || kind === "imageAlt";
 }
+/**
+ * Prose, and meant for a reader.
+ *
+ * A CMS's `_uid` is typed `text` and holds a string, so a translation
+ * checklist built on kind alone demands a French version of a UUID — and then
+ * reports the page as incompletely translated forever, because the planner
+ * quite rightly never produces one.
+ */
+function isTranslatableField(fm) {
+    return !fm.internal && isTranslatableKind(fm.kind);
+}
 /**
  * The translatable surface of one block: which top-level props and which
  * list-child fields carry prose. One definition, used both to tell the planner
@@ -239,13 +250,13 @@ function isTranslatableKind(kind) {
  */
 function translatableFieldKeys(meta) {
     const topLevel = Object.entries(meta?.fields ?? {})
-        .filter(([, fm]) => isTranslatableKind(fm.kind))
+        .filter(([, fm]) => isTranslatableField(fm))
         .map(([key]) => key);
     const lists = Object.entries(meta?.listFields ?? {})
         .map(([listKey, listMeta]) => [
         listKey,
         Object.entries(listMeta.itemFields ?? {})
-            .filter(([, fm]) => isTranslatableKind(fm.kind))
+            .filter(([, fm]) => isTranslatableField(fm))
             .map(([key]) => key)
     ])
         .filter(([, itemFields]) => itemFields.length > 0);

package/dist/chat/hallucination-validator.js

@@ -26,6 +26,45 @@ 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;
+}
+/**
+ * Props the site has declared as its own bookkeeping.
+ *
+ * A `_uid`, a revision stamp, a `__source` snapshot. They are in the schema —
+ * the publisher needs them — so every check above passes them, and the planner
+ * never sees them in the block summary. A plan that names one therefore did
+ * not read it anywhere; it invented a plausible key, which for identity fields
+ * is exactly the kind of key that is easy to invent. Writing it would corrupt
+ * the CMS's own link between the draft and the document it came from.
+ */
+function internalPropKeysForBlockType(blockType) {
+    const meta = getBlockMeta(blockType);
+    const keys = new Set();
+    for (const [key, field] of Object.entries(meta?.fields ?? {})) {
+        if (field.internal)
+            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 +117,8 @@ function humanBlockName(blockType) {
 export function validateAndStripHallucinatedProps(args) {
     const { plan, draft } = args;
     const hallucinatedProps = [];
+    const referenceProps = [];
+    const internalProps = [];
     for (const op of plan.ops) {
         if (op.op !== "update_props")
             continue;
@@ -93,7 +134,19 @@ export function validateAndStripHallucinatedProps(args) {
         const patchCandidate = rawPatch.props && typeof rawPatch.props === "object" && !Array.isArray(rawPatch.props)
             ? rawPatch.props
             : rawPatch;
+        const referenceKeys = referencePropKeysForBlockType(blockType);
+        const internalKeys = internalPropKeysForBlockType(blockType);
         for (const key of Object.keys(patchCandidate)) {
+            if (referenceKeys.has(key)) {
+                delete patchCandidate[key];
+                referenceProps.push({ blockType, propName: key });
+                continue;
+            }
+            if (internalKeys.has(key)) {
+                delete patchCandidate[key];
+                internalProps.push({ blockType, propName: key });
+                continue;
+            }
             if (allowedKeys.has(key))
                 continue;
             delete patchCandidate[key];
@@ -105,7 +158,49 @@ 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.`);
+            }
+        }
+    }
+    /*
+     * An internal prop is the quietest of the three and gets the shortest
+     * sentence. The person did not ask for it — no request mentions a `_uid` —
+     * so the note exists to explain why one op did less than the plan said, not
+     * to teach them anything about the field.
+     */
+    const internalNoteParts = [];
+    if (internalProps.length > 0) {
+        const byBlock = new Map();
+        for (const entry of internalProps) {
+            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) {
+                internalNoteParts.push(`“${prop}” on the ${name} block is managed by your site, not edited here, so it was left alone.`);
+            }
+        }
+    }
+    if (hallucinatedProps.length > 0 || referenceNoteParts.length > 0 || internalNoteParts.length > 0) {
         /*
          * Two different events used to share one sentence, and the wrong one was
          * the default.
@@ -130,7 +225,7 @@ export function validateAndStripHallucinatedProps(args) {
             bucket.add(entry.propName);
             byBlockType.set(entry.blockType, bucket);
         }
-        const noteParts = [];
+        const noteParts = [...referenceNoteParts, ...internalNoteParts];
         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,28 +35,56 @@ 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";
  * an explicit `{ ok: false, error }` lets the adapter surface a per-publish
- * error message that the orchestrator returns to the client.
+ * error message that the orchestrator returns to the client, and `notes` lets
+ * a *successful* one say what it did.
  */
 export type CmsPublishResult = void | {
     ok: true;
     written?: boolean;
     unsupported?: string[];
+    notes?: string[];
 } | {
     ok: false;
     error?: string;
     unsupported?: string[];
+    notes?: string[];
 };
 /**
  * One asset from a CMS's media library, in the shape the editor's image picker

package/dist/handler/create-orchestrator.js

@@ -344,6 +344,52 @@ function stripBasePath(pathname, basePath) {
         return pathname.slice(basePath.length) || "/";
     return pathname || "/";
 }
+/** One note may not be longer than this, and a publish may not carry more. */
+const PUBLISH_NOTE_MAX_LENGTH = 500;
+const PUBLISH_NOTE_MAX_COUNT = 20;
+/**
+ * An adapter's notes are prose from another codebase, and they end up in a
+ * SQLite row and in the editor's chat transcript. Keep what is readable and
+ * drop the rest rather than trusting the shape.
+ */
+function sanitizePublishNotes(notes) {
+    const kept = [];
+    for (const note of notes) {
+        if (typeof note !== "string")
+            continue;
+        const trimmed = note.trim();
+        if (trimmed === "")
+            continue;
+        kept.push(trimmed.length > PUBLISH_NOTE_MAX_LENGTH ? `${trimmed.slice(0, PUBLISH_NOTE_MAX_LENGTH - 1)}…` : trimmed);
+        if (kept.length === PUBLISH_NOTE_MAX_COUNT)
+            break;
+    }
+    return kept;
+}
+/**
+ * The fields the editor reads off a publish response.
+ *
+ * Library mode answered a successful publish with `{ ok: true, written, count }`
+ * and no `status`, and the editor's one check is
+ * `data.status !== "triggered" && data.status !== "ready"` — so every
+ * successful CMS publish was announced to the person who pressed the button as
+ * "Failed to trigger publish." The HTTP status was 200 and the CMS had the
+ * writes; only the sentence was wrong, which is the worst way for it to be
+ * wrong: it invites a second publish, and then a third.
+ *
+ * `ok`/`written`/`count` stay exactly as they were — an integration reading
+ * them is not disturbed by the additions. This mirrors the shape the
+ * site-contract target already returns, which is why the editor can read it.
+ */
+function publishEnvelope(session, slugs, message) {
+    return {
+        status: "ready",
+        ...(session ? { session } : {}),
+        slugs,
+        vercelState: "READY",
+        message
+    };
+}
 /**
  * Build a Web-standard request handler that wraps the orchestrator brain.
  *
@@ -902,14 +948,32 @@ export function createOrchestrator(config = {}) {
                 }
             };
             if (!runtime.adapter?.onPublish) {
+                const reason = "adapter has no onPublish; publish is a no-op";
                 record(true, "Nothing written — the adapter has no onPublish");
-                return jsonResponse({ ok: true, written: false, count: pages.length, reason: "adapter has no onPublish; publish is a no-op" }, { status: 200, cors });
+                return jsonResponse({
+                    ...publishEnvelope(body.session, slugs, reason),
+                    ok: true,
+                    written: false,
+                    count: pages.length,
+                    reason
+                }, { 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 = [];
+            let notes = [];
             // Default true: an adapter that does not mention `written` means what
             // every adapter written before the field existed meant.
             let written = true;
@@ -918,6 +982,9 @@ export function createOrchestrator(config = {}) {
                 if (result && typeof result === "object" && Array.isArray(result.unsupported)) {
                     unsupported = result.unsupported;
                 }
+                if (result && typeof result === "object" && Array.isArray(result.notes)) {
+                    notes = sanitizePublishNotes(result.notes);
+                }
                 if (result && typeof result === "object" && result.ok === true && result.written === false) {
                     written = false;
                 }
@@ -926,11 +993,13 @@ export function createOrchestrator(config = {}) {
                     runtime.log.warn({ session: scopedSession, adapter: runtime.adapter.id, error: result.error }, "library-publish: adapter.onPublish() returned not-ok");
                     record(false, message, message);
                     return jsonResponse({
+                        status: "failed",
                         ok: false,
                         written: false,
                         count: pages.length,
                         error: message,
-                        ...(unsupported.length > 0 ? { unsupported } : {})
+                        ...(unsupported.length > 0 ? { unsupported } : {}),
+                        ...(notes.length > 0 ? { notes } : {})
                     }, { status: 502, cors });
                 }
             }
@@ -949,14 +1018,29 @@ export function createOrchestrator(config = {}) {
             const summary = written
                 ? buildPublishSummary({ changedSlugs: [], removedSlugs: [], totalPages: pages.length, hasDiff: false })
                 : `Computed ${pages.length} ${pages.length === 1 ? "page" : "pages"} — nothing written`;
-            record(true, unsupported.length > 0
-                ? `${summary} ${unsupported.length} change${unsupported.length === 1 ? "" : "s"} could not be published.`
-                : summary);
+            /*
+             * The adapter's own sentences go in the log row too. A publish log that
+             * records "Published 12 pages" for a run that wrote nothing because the
+             * queue was paused is worse than no log: it is a record of something
+             * that did not happen.
+             */
+            const logged = [
+                summary,
+                unsupported.length > 0
+                    ? `${unsupported.length} change${unsupported.length === 1 ? "" : "s"} could not be published.`
+                    : "",
+                ...notes
+            ]
+                .filter((part) => part !== "")
+                .join(" ");
+            record(true, logged);
             return jsonResponse({
+                ...publishEnvelope(body.session, slugs, logged),
                 ok: true,
                 written,
                 count: pages.length,
-                ...(unsupported.length > 0 ? { unsupported } : {})
+                ...(unsupported.length > 0 ? { unsupported } : {}),
+                ...(notes.length > 0 ? { notes } : {})
             }, { status: 200, cors });
         }
         // The editor polls this on boot to populate its model selector and the

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.6.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -16,17 +16,29 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.220",
     "@anthropic-ai/sdk": "^0.115.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
     "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.6.0",
+    "@avocadostudio-ai/shared": "^0.6.0"
+  },
+  "peerDependencies": {
+    "googleapis": "^171.4.0",
+    "@google/genai": "^1.46.0"
+  },
+  "peerDependenciesMeta": {
+    "googleapis": {
+      "optional": true
+    },
+    "@google/genai": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.220",
     "@google/genai": "^1.46.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.13.10",
@@ -65,18 +77,6 @@
     "url": "https://github.com/avocadostudio-ai/avocado.git",
     "directory": "packages/orchestrator-core"
   },
-  "peerDependencies": {
-    "googleapis": "^171.4.0",
-    "@google/genai": "^1.46.0"
-  },
-  "peerDependenciesMeta": {
-    "googleapis": {
-      "optional": true
-    },
-    "@google/genai": {
-      "optional": true
-    }
-  },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json && node ./scripts/copy-assets.mjs",