@avocadostudio-ai/orchestrator-core 0.4.0 → 0.5.1

package/dist/agent/agent-logger.js

@@ -4,7 +4,8 @@
  */
 import { appendFileSync } from "node:fs";
 import { resolve } from "node:path";
-const LOG_PATH = resolve(process.cwd(), "../../.data/agent-log.ndjson");
+import { resolveDataDir } from "../state/data-dir.js";
+const LOG_PATH = resolve(resolveDataDir(), "agent-log.ndjson");
 export function logAgent(streamId, event, detail, startedAt) {
     const entry = {
         ts: Date.now(),

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

@@ -51,6 +51,7 @@ 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 { declareLibraryMount, observeLibraryMount } from "./library-mount.js";
 import { checkAuth, resolveAuth } from "./auth.js";
 import { setSiteAssetLister, invalidateSiteAssets } from "../state/site-assets.js";
 const defaultModelLookup = () => ({
@@ -416,16 +417,40 @@ export function createOrchestrator(config = {}) {
     const gateLogger = config.logger ?? consoleLogger();
     {
         const resolved = resolveAuth(config.auth);
-        const line = `[auth] library mode: ${resolved.mode} — ${resolved.reason}`;
+        /*
+         * `next build` evaluates this route module to collect its exports, with
+         * `NODE_ENV=production` and none of the deployment's environment. With no
+         * credential configured the gate resolves to `closed` and this printed a
+         * red `[error]` in the middle of an otherwise clean, *successful* build —
+         * about a request that is not being served, on a machine that is not the
+         * deployment.
+         *
+         * It is still the only notice anyone gets of a real problem, so it is not
+         * silenced: during a build it is a warning that says which state it is
+         * describing. At runtime it stays an error, because then it means every
+         * request is actually being refused.
+         */
+        const building = process.env.NEXT_PHASE === "phase-production-build";
+        const line = building
+            ? `[auth] library mode: ${resolved.mode} — ${resolved.reason} ` +
+                `(evaluated during the build; set ACCESS_PASSWORD_HASH or ` +
+                `ORCHESTRATOR_ACCESS_TOKEN in the deployment's environment, not here)`
+            : `[auth] library mode: ${resolved.mode} — ${resolved.reason}`;
         if (resolved.mode === "closed")
-            gateLogger.error(line);
+            building ? gateLogger.warn(line) : gateLogger.error(line);
         else if (resolved.mode === "open-dev")
             gateLogger.warn(line);
         else
             gateLogger.info(line);
     }
+    // Tell the SDK's draft fetch where we are, so it stops defaulting to the
+    // standalone orchestrator on :4200 that a library-mode site does not run.
+    // See `library-mount.ts` for why this is not simply a config value.
+    if (config.previewUrl)
+        declareLibraryMount(`${config.previewUrl.replace(/\/+$/, "")}${basePath}`);
     const handler = async function handler(request) {
         const url = new URL(request.url);
+        observeLibraryMount(`${url.origin}${basePath}`);
         const path = stripBasePath(url.pathname, basePath);
         const cors = corsHeadersFor(request, config);
         if (request.method === "OPTIONS") {
@@ -881,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/handler/library-mount.d.ts

@@ -0,0 +1,6 @@
+export declare const LIBRARY_MOUNT_KEY = "__avocado_library_mount__";
+/** Called at construction, from `previewUrl` + `basePath`. */
+export declare function declareLibraryMount(url: string): void;
+/** Called on each request, from the URL the runtime actually received. */
+export declare function observeLibraryMount(url: string): void;
+export declare function getLibraryMount(): string | null;

package/dist/handler/library-mount.js

@@ -0,0 +1,45 @@
+/*
+ * Where this process's own orchestrator is mounted, if it has one.
+ *
+ * In library mode the orchestrator is a route inside the site's own Next app,
+ * and the SDK's draft fetch had no way to know that: with `ORCHESTRATOR_URL`
+ * unset it fell back to `http://127.0.0.1:4200`, the *standalone* orchestrator,
+ * which a library-mode site by definition does not run. The failure is silent
+ * when nothing is listening there (the draft fetch fails, the preview falls back
+ * to published content, and every edit appears to do nothing) and worse when
+ * something is — the fetch succeeds against a foreign process and the preview
+ * renders another project's pages. Anyone integrating is likely to have a :4200
+ * up, because that is what the standalone stack runs on.
+ *
+ * So the handler records its own address, and `getOrchestratorUrl()` in the SDK
+ * reads it through the same `globalThis` key. The key is a string on both sides
+ * rather than an import because `@avocadostudio-ai/orchestrator-core` is an
+ * *optional* peer of the SDK — a site that is not in library mode does not have
+ * it installed, and neither package may require the other.
+ *
+ * Two sources, in order of trust:
+ *   - the origin of a real request this handler served, which cannot be wrong;
+ *   - `config.previewUrl + basePath` at construction time, which is available
+ *     before any request and is what covers a preview page that renders before
+ *     the orchestrator route module has ever been evaluated.
+ */
+export const LIBRARY_MOUNT_KEY = "__avocado_library_mount__";
+function slot() {
+    const g = globalThis;
+    return g[LIBRARY_MOUNT_KEY] ?? (g[LIBRARY_MOUNT_KEY] = {});
+}
+/** Called at construction, from `previewUrl` + `basePath`. */
+export function declareLibraryMount(url) {
+    slot().declared = url.replace(/\/+$/, "");
+}
+/** Called on each request, from the URL the runtime actually received. */
+export function observeLibraryMount(url) {
+    const s = slot();
+    const next = url.replace(/\/+$/, "");
+    if (s.observed !== next)
+        s.observed = next;
+}
+export function getLibraryMount() {
+    const s = slot();
+    return s.observed ?? s.declared ?? null;
+}

package/dist/image/image-helpers.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import OpenAI from "openai";
+import { resolveDataDir } from "../state/data-dir.js";
 import { listImages, fileNameToAlt, resolveGdriveFolderId } from "./gdrive-client.js";
 // ---------------------------------------------------------------------------
 // Image generation timing — rolling average for progress estimation
@@ -218,7 +219,7 @@ export async function generateVariationImageWithOpenAI(args) {
     const background = args.background ?? "auto";
     const outputFormat = args.outputFormat ?? "png";
     const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-    const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ?? resolve(process.cwd(), "../../.data/generated-images");
+    const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ?? resolve(resolveDataDir(), "generated-images");
     const orchestratorPublicOrigin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
     args.log?.info({ event: "openai_image_start", model, size, background, outputFormat, promptLength: args.prompt.length }, "Starting OpenAI image generation");
     const genStartMs = Date.now();
@@ -270,7 +271,7 @@ export async function generateVariationImageWithOpenAI(args) {
 // Shared image save utility
 // ---------------------------------------------------------------------------
 export async function saveGeneratedImage(bytes, prefix = "gen", ext = "png") {
-    const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ?? resolve(process.cwd(), "../../.data/generated-images");
+    const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ?? resolve(resolveDataDir(), "generated-images");
     const orchestratorPublicOrigin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
     const fileName = `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
     await mkdir(generatedImageDir, { recursive: true });

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/publish/publish-helpers.js

@@ -4,6 +4,7 @@ import { existsSync } from "node:fs";
 import { copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { resolve } from "node:path";
+import { resolveDataDir } from "../state/data-dir.js";
 import { pageDocSchema } from "@avocadostudio-ai/shared";
 import { draftPages, versions, ensureHeroImageProps, persistStateNow, getSessionPages, getSiteConfig, isLegacySiteId } from "../state/session-state.js";
 import { toErrorDetail } from "../ops/ops-engine.js";
@@ -413,7 +414,7 @@ export async function publishViaGit(session, content) {
     let copiedImages = false;
     if (imageUrlMap.size > 0) {
         const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ??
-            resolve(process.cwd(), "../../.data/generated-images");
+            resolve(resolveDataDir(), "generated-images");
         await mkdir(imageDestDir, { recursive: true });
         for (const [, fileName] of imageUrlMap) {
             const src = resolve(generatedImageDir, fileName);

package/dist/state/data-dir.d.ts

@@ -0,0 +1,6 @@
+export declare function isLegacyMonorepoLayout(cwd?: string): boolean;
+/**
+ * The `.data` directory for this process, or the legacy monorepo one when this
+ * really is a package inside the monorepo and that directory already exists.
+ */
+export declare function resolveDataDir(cwd?: string): string;

package/dist/state/data-dir.js

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/*
+ * Where this process keeps its own files: the database, generated images, the
+ * agent log.
+ *
+ * The answer is `<cwd>/.data`. It used to be `<cwd>/../../.data`, which is
+ * `apps/orchestrator`'s position in *this* repo and nobody else's — a
+ * library-mode host runs from its own project root, so it wrote two directories
+ * above itself, outside the project and outside version control, into a
+ * directory shared with every sibling checkout that made the same mistake.
+ *
+ * The legacy location is still honoured for an existing monorepo checkout, but
+ * only on proof of workspace membership. The first version of that back-compat
+ * check asked `existsSync(legacy)` alone — "has anyone ever created that file",
+ * not "am I a package in the workspace that owns it" — so one mistaken write
+ * captured every unrelated project under that parent, permanently, because the
+ * bug is what created the file that re-triggered it.
+ */
+export function isLegacyMonorepoLayout(cwd = process.cwd()) {
+    return (existsSync(resolve(cwd, "../../pnpm-workspace.yaml")) &&
+        existsSync(resolve(cwd, "package.json")));
+}
+/**
+ * The `.data` directory for this process, or the legacy monorepo one when this
+ * really is a package inside the monorepo and that directory already exists.
+ */
+export function resolveDataDir(cwd = process.cwd()) {
+    if (isLegacyMonorepoLayout(cwd)) {
+        const legacy = resolve(cwd, "../../.data");
+        if (existsSync(legacy))
+            return legacy;
+    }
+    return resolve(cwd, ".data");
+}

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/dist/state/sqlite-store-singleton.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { rename, readFile, readdir, stat, unlink } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { SqliteStore } from "./sqlite-store.js";
+import { resolveDataDir } from "./data-dir.js";
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
@@ -17,23 +18,8 @@ export function resolveDbFile() {
         return ":memory:";
     if (process.env.NODE_ENV === "test")
         return ":memory:";
-    /*
-     * `../../.data` is this monorepo's shape, not a general default.
-     *
-     * It is right for `apps/orchestrator`, whose cwd is two levels under the repo
-     * root, and wrong for everyone else: a library-mode host running from its own
-     * project root writes two directories *above* itself. PBA's landed in
-     * `~/Projects/.data` — outside the project, outside version control, and
-     * shared with any sibling checkout that made the same mistake.
-     *
-     * The default is now the host's own `.data/`. The legacy path still wins when
-     * a database is already sitting there, so an existing monorepo checkout keeps
-     * its state without an env var and without a migration step.
-     */
-    const legacy = resolve(process.cwd(), "../../.data/orchestrator.db");
-    if (existsSync(legacy))
-        return legacy;
-    return resolve(process.cwd(), ".data/orchestrator.db");
+    // `resolveDataDir` carries the whole story of why this is not `../../.data`.
+    return resolve(resolveDataDir(), "orchestrator.db");
 }
 export function resolveJsonMigrationTtlDays() {
     const raw = Number(process.env.ORCHESTRATOR_JSON_MIGRATION_TTL_DAYS ?? 14);

package/package.json

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