@avocadostudio-ai/orchestrator-core 0.5.1 → 0.6.0

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

@@ -45,13 +45,18 @@ export function buildBlockCatalog() {
         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";
+        const writable = ([, fm]) => fm.kind !== "headingLevel" && fm.kind !== "reference" && !fm.internal;
         const fieldParts = Object.entries(meta.fields)
             .filter(writable) // headingLevel is always optional noise
             .map(([key, fm]) => {

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

@@ -46,6 +46,25 @@ function referencePropKeysForBlockType(blockType) {
     }
     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.
@@ -99,6 +118,7 @@ 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;
@@ -115,12 +135,18 @@ export function validateAndStripHallucinatedProps(args) {
             ? 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];
@@ -153,7 +179,28 @@ export function validateAndStripHallucinatedProps(args) {
             }
         }
     }
-    if (hallucinatedProps.length > 0 || referenceNoteParts.length > 0) {
+    /*
+     * 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.
@@ -178,7 +225,7 @@ export function validateAndStripHallucinatedProps(args) {
             bucket.add(entry.propName);
             byBlockType.set(entry.blockType, bucket);
         }
-        const noteParts = [...referenceNoteParts];
+        const noteParts = [...referenceNoteParts, ...internalNoteParts];
         for (const [blockType, props] of byBlockType) {
             const name = humanBlockName(blockType);
             const visual = [...props].filter(isVisualPropName);

package/dist/cms/adapter.d.ts

@@ -72,16 +72,19 @@ export interface CmsPublishContext {
 /**
  * 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,8 +948,15 @@ 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;
             /*
@@ -920,6 +973,7 @@ export function createOrchestrator(config = {}) {
                 }
                 : 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;
@@ -928,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;
                 }
@@ -936,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 });
                 }
             }
@@ -959,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.5.1",
+  "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.1",
-    "@avocadostudio-ai/shared": "^0.5.1"
+    "@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",