@avocadostudio-ai/orchestrator-core 0.9.0 → 0.11.0

package/dist/chat/chat-pipeline.js

@@ -8,7 +8,7 @@ import { getSiteAssets } from "../state/site-assets.js";
 import { loadPendingPlan, savePendingPlan, clearPendingPlan } from "../durable/pending-plan-store.js";
 import { toErrorDetail, isNoEffectiveChangeError, isAlreadyCurrentError, classifyGuardrailError, formatValidationError, isRepairEligibleCategory, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
 import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
-import { clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, withKeylessNotice, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
+import { clarificationSuggestions, postEditSuggestions, keepDemoExecutable, demoPlanFromMessage, withKeylessNotice, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
 import { generatePlanWithOpenAI, isPlannerOutputError, isStrictJsonResponseEnabled, parseIntentWithOpenAI } from "./planner.js";
 import { isDemoModeEnabled, splitDemoOps, getDemoAllowedBlockTypes } from "../demo-mode.js";
 import { isCancelError as _isCancelError, OperationError, OrchestrationError } from "../errors.js";
@@ -52,7 +52,7 @@ import { planTranslationChunks, shouldChunkTranslation, generateChunkedTranslati
 import { shouldPreferFastModelForMessage, shouldUseLlmIntentRouter, compactPlannerContextPack, minimalPlannerContextPack, shouldUseMinimalPlannerContext, shouldPreferFocusedTranslation, classifyMessageComplexity, isRouterPlanTooShallow, shouldEnableReasoningForMessage } from "./chat-pipeline-context.js";
 import { buildAiInsightChanges, buildMetaChangeLogEntries, buildOpChangeLogEntries, deterministicCreatePagePlan, deterministicDuplicatePagePlan, shouldReturnDeterministicClarification, fmtSlug } from "./chat-pipeline-deterministic.js";
 import { getValueAtPath, setValueAtPath, deleteValueAtPath, blockSupportsImageAtPath, detectImageOps, rewriteAddBlockToChildImageUpdate, withUnsplashHeroImage, resolveHeroImageForCreatePage } from "./chat-pipeline-image.js";
-import { resolveEffectiveProvider, resolveModelKeyForProvider, resolvePlannerSource } from "./provider-routing.js";
+import { resolveEffectiveProvider, resolveModelKeyForProvider, resolvePlannerSource, DEMO_MODEL_LABEL } from "./provider-routing.js";
 import { runVariationPipeline, getCachedVariations } from "./variation-pipeline.js";
 import { validateAndStripHallucinatedProps } from "./hallucination-validator.js";
 import { validateChangelogCoverage } from "./changelog-coverage-validator.js";
@@ -183,6 +183,19 @@ let generatePlanWithAnthropicImpl = generatePlanWithAnthropic;
 export function setGeneratePlanWithAnthropicForTests(fn) {
     generatePlanWithAnthropicImpl = fn ?? generatePlanWithAnthropic;
 }
+/**
+ * Suggestions, narrowed to what will answer when there is no key.
+ *
+ * A no-op the moment any provider is configured — with a model behind the chat,
+ * every phrasing these generators produce is answerable, which is what they
+ * were written against. Without one the answer comes from a substring matcher
+ * that knows a handful of literal phrases, and the rest are dead buttons.
+ */
+function usableSuggestions(suggestions, source, slug, body) {
+    if (source !== "demo")
+        return suggestions;
+    return keepDemoExecutable(suggestions, slug, body.activeBlockId, body.activeBlockType);
+}
 let demoPlanFromMessageImpl = demoPlanFromMessage;
 export function setDemoPlanFromMessageForTests(fn) {
     demoPlanFromMessageImpl = fn ?? demoPlanFromMessage;
@@ -275,7 +288,9 @@ export async function runChatPipeline(ctx, body, options) {
                     changes: [],
                     previewVersion: versions.get(body.session) ?? 0,
                     plannerSource: ctx.availableProviders.length > 0 ? ctx.availableProviders[0] : "demo",
-                    modelUsed: ctx.modelLookup[defaultProvider][defaultModelKey],
+                    modelUsed: ctx.availableProviders.length > 0
+                        ? ctx.modelLookup[defaultProvider][defaultModelKey]
+                        : DEMO_MODEL_LABEL,
                     modelKey: defaultModelKey
                 }
             };
@@ -481,8 +496,23 @@ export async function runChatPipeline(ctx, body, options) {
             shouldPreferFastModelForMessage(plannerMessage)
             ? "fast"
             : baseModelKey;
-    const modelUsed = ctx.modelLookup[provider][modelKey];
     const plannerSource = resolvePlannerSource(provider);
+    /*
+     * What actually answered, not what would have.
+     *
+     * `plannerSource === "demo"` means no provider key of any kind is
+     * configured, so no model can run — yet this reported the configured
+     * lookup's default anyway, and every keyless reply came back
+     * `"modelUsed":"gpt-4o"`. The editor renders a per-message model chip from
+     * this, so someone who had deliberately not signed up for anything watched
+     * an OpenAI model take credit for nine words of regex output.
+     *
+     * Narrower than it looks: a *deterministic* plan produced while a key IS
+     * configured keeps naming the model, because that model would genuinely have
+     * run had the rules not matched first — see `plannerTier` below. The case
+     * being corrected is the one where there is nothing to name.
+     */
+    const modelUsed = plannerSource === "demo" ? DEMO_MODEL_LABEL : ctx.modelLookup[provider][modelKey];
     // Auto-escalate to extended thinking for complex/ambiguous Anthropic prompts.
     // Only applies when provider = anthropic (other providers ignore `thinking`).
     // User can disable with CHAT_AUTO_REASONING=0.
@@ -1095,7 +1125,7 @@ export async function runChatPipeline(ctx, body, options) {
                     summary: "I need one more detail before applying this safely.",
                     changes: [],
                     mentionedSlugs: [effectiveSlug],
-                    suggestions: clarificationSuggestions({ body, current, selected }),
+                    suggestions: usableSuggestions(clarificationSuggestions({ body, current, selected }), args.source, effectiveSlug, body),
                     previewVersion: versions.get(body.session) ?? 0,
                     plannerSource: args.source,
                     modelUsed,
@@ -1719,7 +1749,7 @@ export async function runChatPipeline(ctx, body, options) {
                         summary: resolvedPlan.summary_for_user,
                         changes: resolvedPlan.change_log,
                         mentionedSlugs: collectMentionedSlugsFromPlan(resolvedPlan, effectiveSlug),
-                        suggestions: resolvedPlan.suggested_next_actions ?? clarificationSuggestions({ body, current, selected }),
+                        suggestions: usableSuggestions(resolvedPlan.suggested_next_actions ?? clarificationSuggestions({ body, current, selected }), source, effectiveSlug, body),
                         previewVersion: versions.get(body.session) ?? 0,
                         plannerSource: source,
                         modelUsed,
@@ -2623,7 +2653,7 @@ export async function runChatPipeline(ctx, body, options) {
                         summary: futureToPastTense(resolvedPlan.summary_for_user),
                         changes: [...opChangeLogEntries, ...metaChangeLogEntries, ...aiInsightChanges, ...skippedSummary],
                         mentionedSlugs: collectMentionedSlugsFromPlan(resolvedPlan, updatedSlug ?? effectiveSlug),
-                        suggestions: resolvedPlan.suggested_next_actions ?? postEditSuggestions({ plan: resolvedPlan, current, body }),
+                        suggestions: usableSuggestions(resolvedPlan.suggested_next_actions ?? postEditSuggestions({ plan: resolvedPlan, current, body }), plannerSource, updatedSlug ?? effectiveSlug, body),
                         previewVersion,
                         focusBlockId,
                         updatedSlug,

package/dist/chat/prompts.js

@@ -134,7 +134,7 @@ function buildLightweightPlannerPrompt(opts) {
         RULE_ICON_FORMAT,
         "Use future tense in summary_for_user and change_log — your output streams to the user while the plan is still being generated, before any ops have been applied. Say 'Will update the heading…' or 'Will replace the Hero image…', never 'Updated…' or 'Updating…'. The system flips to past tense automatically once ops are applied.",
         "For edit_plan: summary_for_user must be ONE short sentence (max ~20 words).",
-        "After planning ops, include suggested_next_actions: 2-4 short imperative phrases the user could type next (max 6 words each). Every suggestion must be an action the user can perform inside this editor (editing content, adding/removing sections, changing images, rewriting copy) — restricted to the block types listed in the block catalogue provided in context (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video). NEVER suggest unsupported features like forms, email capture, contact forms, subscribe boxes, newsletter signups, popups, modals, or anything requiring custom code. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy. When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). Remaining suggestions can target neighboring fields or blocks.",
+        "After planning ops, include suggested_next_actions: 2-4 short imperative phrases the user could type next (max 6 words each). Every suggestion must be an action the user can perform inside this editor (editing content, adding/removing sections, changing images, rewriting copy) — restricted to the block types listed in the block catalogue provided in context (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video). NEVER suggest unsupported features like forms, email capture, contact forms, subscribe boxes, newsletter signups, popups, modals, or anything requiring custom code. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy. When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Use a warmer opening'). Remaining suggestions can target neighboring fields or blocks. NEVER suggest undoing, reverting, or restoring earlier content. You cannot read the undo history, so such a suggestion resolves to either a refusal or an invented replacement presented as the original — the editor's own Undo button is the affordance for that, and it already works.",
         opts.selectedBlockId.length > 0
             ? `Selected block is ${opts.selectedBlockId}. Target only this block in ops when the request edits the current page. IGNORE this selection when the request operates on a different scope — creating, duplicating, renaming, removing, or moving a page; editing site config; or naming a different page — and emit ops only for the requested scope. Never add bonus ops on the selected block to satisfy this rule.`
             : "Respect explicit user target references when present.",
@@ -250,7 +250,7 @@ function sectionVoice(opts, hasNativeTools) {
     if (hasNativeTools) {
         lines.push("For edit_plan intent: summary_for_user must be ONE short sentence (max ~20 words) describing what the plan will do. Do NOT elaborate, explain why, or describe the content being added — let change_log carry the detail. Bad: 'Updated the hero heading with a punchier tone.' Good: 'Will add a **text section** about blueberry varieties after the features grid.'", "change_log coverage is MANDATORY: emit exactly one change_log entry per op, in the same order as ops[], describing what that specific op does. If ops has N entries, change_log must have N entries — never cluster multiple ops into one entry, never skip an op, never leave an op undescribed. The user reads change_log to decide whether to approve; a missing entry is a silent bait-and-switch.", "change_log entries should add specific detail NOT already in summary_for_user — e.g. list the actual content, items, or values being set. Do not paraphrase the summary.");
     }
-    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types listed in blockContracts / blockCatalogue for THIS site, or SEO/site-config edits. Never suggest adding a section this site has no block for; the catalogue is the whole list, not a sample of a larger one. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Use a warmer opening'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types listed in blockContracts / blockCatalogue for THIS site, or SEO/site-config edits. Never suggest adding a section this site has no block for; the catalogue is the whole list, not a sample of a larger one. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy. NEVER suggest undoing, reverting, or restoring earlier content. You cannot read the undo history, so such a suggestion resolves to either a refusal or an invented replacement presented as the original — the editor's own Undo button is the affordance for that, and it already works.");
     return lines;
 }
 /*

package/dist/chat/provider-routing.d.ts

@@ -12,3 +12,14 @@ export declare function resolveModelKeyForProvider(args: {
     defaultModelKey?: ModelKey;
 }): ModelKey;
 export declare function resolvePlannerSource(provider: AIProvider): PlannerSource;
+/**
+ * What to report as the model when `resolvePlannerSource` said `"demo"`.
+ *
+ * A string rather than `undefined` because every consumer of `modelUsed` — the
+ * editor's per-message chip, the telemetry row, the debug panel — already
+ * treats absence as "unknown" and renders nothing. "Unknown" is not what this
+ * is. The reply came from a named thing that is not a model, and saying so is
+ * the whole point: it is the one place a keyless session is told, in passing,
+ * what it is running on.
+ */
+export declare const DEMO_MODEL_LABEL = "demo planner (no API key)";

package/dist/chat/provider-routing.js

@@ -25,3 +25,14 @@ export function resolvePlannerSource(provider) {
                             ? "gemini"
                             : "demo";
 }
+/**
+ * What to report as the model when `resolvePlannerSource` said `"demo"`.
+ *
+ * A string rather than `undefined` because every consumer of `modelUsed` — the
+ * editor's per-message chip, the telemetry row, the debug panel — already
+ * treats absence as "unknown" and renders nothing. "Unknown" is not what this
+ * is. The reply came from a named thing that is not a model, and saying so is
+ * the whole point: it is the one place a keyless session is told, in passing,
+ * what it is running on.
+ */
+export const DEMO_MODEL_LABEL = "demo planner (no API key)";

package/dist/chat/variation-pipeline.js

@@ -10,7 +10,7 @@ import { openAIChatOptionsForModel } from "./planner.js";
 import { extractJsonObject } from "../nlp/plan-normalizer.js";
 import { extractUsage, estimateUsd } from "../telemetry/usage.js";
 import { anthropicSystemPromptWithCache } from "./anthropic-cache.js";
-import { resolveEffectiveProvider, resolveModelKeyForProvider, resolvePlannerSource } from "./provider-routing.js";
+import { resolveEffectiveProvider, resolveModelKeyForProvider, resolvePlannerSource, DEMO_MODEL_LABEL } from "./provider-routing.js";
 import { deriveVariationImageIntent, buildVariationImageQuery, buildVariationImagePrompt, generateVariationImageWithOpenAI, generateVariationImageWithGemini, resolveUnsplashImage } from "../image/image-helpers.js";
 import { firstUrlFromText, resolveEffectiveSlug } from "./chat-pipeline.js";
 import { resolveDistinctUnsplashImage } from "../variation-images.js";
@@ -656,9 +656,11 @@ async function prepareTextVariations(ctx, body) {
         modelLookup: ctx.modelLookup,
         defaultModelKey: process.env.OPENAI_MODEL_KEY ?? "balanced"
     });
-    const modelUsed = ctx.modelLookup[provider][modelKey];
     const count = requestedVariationCount(contextualMessage);
     const plannerSource = resolvePlannerSource(provider);
+    /* Same correction as the chat pipeline: with no key, nothing in the lookup
+     * ran, so naming one credits a model for a deterministic result. */
+    const modelUsed = plannerSource === "demo" ? DEMO_MODEL_LABEL : ctx.modelLookup[provider][modelKey];
     let variations = [];
     let generatorUsage;
     if (plannerSource === "anthropic") {

package/dist/handler/auth.d.ts

@@ -59,8 +59,28 @@ export declare function hasConfiguredCredential(): boolean;
  * captured at module load is a value from before the host configured anything.
  */
 export declare function resolveAuth(auth: OrchestratorAuth | undefined): ResolvedAuth;
-/** The one body shape the editor's fetch shim recognises as "re-prompt". */
-export declare function unauthorizedResponse(cors: Record<string, string>): Response;
+/**
+ * The reason a `closed` mount refuses, in the 401 itself.
+ *
+ * Refusing anonymously is right when a credential exists and the caller did
+ * not present it — "which header did I get wrong" is not the server's to
+ * answer. `closed` is not that case. Nobody holds a credential because none was
+ * configured, so there is no attacker to withhold this from: the only person
+ * who can act on it is the operator, staring at a 401 on their own deployment.
+ *
+ * Withholding it cost a clean-room run its whole production evaluation. Every
+ * route answered `{"error":"unauthorized"}`, `/auth/status` answered
+ * `gateEnabled: false`, and nothing anywhere named an environment variable.
+ */
+export declare const CLOSED_HINT: string;
+/**
+ * The one body shape the editor's fetch shim recognises as "re-prompt".
+ *
+ * `reason` is additive and present only for a misconfiguration the caller
+ * cannot have caused; `error` keeps its exact value either way, because that
+ * is the field the shim matches on.
+ */
+export declare function unauthorizedResponse(cors: Record<string, string>, reason?: string): Response;
 export interface AuthCheckResult {
     /** Non-null means refuse and return this. */
     response: Response | null;

package/dist/handler/auth.js

@@ -76,9 +76,30 @@ export function resolveAuth(auth) {
     }
     return { mode: "open-dev", reason: "no credential configured and NODE_ENV is not production — open" };
 }
-/** The one body shape the editor's fetch shim recognises as "re-prompt". */
-export function unauthorizedResponse(cors) {
-    return new Response(JSON.stringify({ error: "unauthorized" }), {
+/**
+ * The reason a `closed` mount refuses, in the 401 itself.
+ *
+ * Refusing anonymously is right when a credential exists and the caller did
+ * not present it — "which header did I get wrong" is not the server's to
+ * answer. `closed` is not that case. Nobody holds a credential because none was
+ * configured, so there is no attacker to withhold this from: the only person
+ * who can act on it is the operator, staring at a 401 on their own deployment.
+ *
+ * Withholding it cost a clean-room run its whole production evaluation. Every
+ * route answered `{"error":"unauthorized"}`, `/auth/status` answered
+ * `gateEnabled: false`, and nothing anywhere named an environment variable.
+ */
+export const CLOSED_HINT = "This orchestrator is running with NODE_ENV=production and no credential, so every request is refused. " +
+    "Set ACCESS_PASSWORD_HASH or ORCHESTRATOR_ACCESS_TOKEN, or pass config.auth to createOrchestrator().";
+/**
+ * The one body shape the editor's fetch shim recognises as "re-prompt".
+ *
+ * `reason` is additive and present only for a misconfiguration the caller
+ * cannot have caused; `error` keeps its exact value either way, because that
+ * is the field the shim matches on.
+ */
+export function unauthorizedResponse(cors, reason) {
+    return new Response(JSON.stringify({ error: "unauthorized", ...(reason ? { reason } : {}) }), {
         status: 401,
         headers: { "content-type": "application/json", ...cors }
     });
@@ -95,7 +116,7 @@ export async function checkAuth(args) {
         return { response: null, context: null };
     if (resolved.mode === "closed") {
         log.error({ path }, `[auth] refused — ${resolved.reason}`);
-        return { response: unauthorizedResponse(cors), context: null };
+        return { response: unauthorizedResponse(cors, CLOSED_HINT), context: null };
     }
     if (resolved.mode === "token") {
         if (isValidAccessToken(extractAccessToken(request)))

package/dist/handler/create-orchestrator.js

@@ -52,7 +52,7 @@ 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 { checkAuth, resolveAuth, CLOSED_HINT } from "./auth.js";
 import { setSiteAssetLister, invalidateSiteAssets } from "../state/site-assets.js";
 const defaultModelLookup = () => ({
     openai: {
@@ -533,8 +533,27 @@ export function createOrchestrator(config = {}) {
              * editor to prompt for one it cannot verify would trap the user in a form
              * that never succeeds. Such a host authenticates the browser its own way,
              * before the editor ever loads.
+             *
+             * `mode` answers the question `gateEnabled` was being made to stand in
+             * for, and could not: "will my requests be accepted?". The two come apart
+             * in exactly one state, and it is the worst one. A `closed` mount — built
+             * for production with no credential — has no password gate, so
+             * `gateEnabled` is false and the editor opens without prompting, while
+             * every route behind this one answers 401. The editor then renders itself
+             * around a site it cannot read, with no password box and no way to reach
+             * one; a clean-room run hit exactly that and had nothing to go on.
+             *
+             * So the state is named. `/auth/status` is public precisely so a client
+             * can ask before it holds a credential, and `closed` is a misconfiguration
+             * rather than a secret — nobody holds a credential for this mount, so
+             * there is no one to withhold it from.
              */
-            return jsonResponse({ gateEnabled: isAccessGateEnabled() }, { cors });
+            const resolvedAuth = resolveAuth(config.auth);
+            return jsonResponse({
+                gateEnabled: isAccessGateEnabled(),
+                mode: resolvedAuth.mode,
+                ...(resolvedAuth.mode === "closed" ? { reason: CLOSED_HINT } : {})
+            }, { cors });
         }
         if (request.method === "POST" && path === "/auth/verify") {
             if (!isAccessGateEnabled()) {
@@ -948,10 +967,19 @@ export function createOrchestrator(config = {}) {
                 }
             };
             if (!runtime.adapter?.onPublish) {
+                /*
+                 * Two audiences, and they had been given the same sentence. `reason` is
+                 * for whatever called the API; `message` is what the editor prints as
+                 * the summary under a green tick, so a first-run user read the words
+                 * "adapter has no onPublish; publish is a no-op" as the report on the
+                 * button they had just pressed.
+                 */
                 const reason = "adapter has no onPublish; publish is a no-op";
+                const message = "Nothing was written — this site's content adapter is read-only. Your edits are " +
+                    "still here as a draft; to publish them, give the adapter somewhere to write.";
                 record(true, "Nothing written — the adapter has no onPublish");
                 return jsonResponse({
-                    ...publishEnvelope(body.session, slugs, reason),
+                    ...publishEnvelope(body.session, slugs, message),
                     ok: true,
                     written: false,
                     count: pages.length,

package/dist/http/image-generate-actions.js

@@ -27,7 +27,7 @@ import { randomUUID } from "node:crypto";
 import { mkdir, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import OpenAI from "openai";
-import { getGeminiClient, getGeminiImageModel, saveGeneratedImage, GEMINI_ASPECT_RATIOS } from "../image/image-helpers.js";
+import { getGeminiClient, getGeminiImageModel, resolveImageProvider, saveGeneratedImage, GEMINI_ASPECT_RATIOS } from "../image/image-helpers.js";
 import { openAIChatOptionsForModel } from "../chat/planner.js";
 import { toErrorDetail } from "../errors.js";
 /**
@@ -120,12 +120,14 @@ export async function generateImageAction(body, deps) {
         return { code: 400, body: { error: "prompt is required" } };
     const requestedProvider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
     const requestedModel = typeof body.model === "string" ? body.model.trim() : "";
-    const envProvider = process.env.IMAGE_GEN_PROVIDER?.trim().toLowerCase() || "openai";
-    const provider = requestedProvider || envProvider;
+    /* Resolved against the keys this process holds, not just against what was
+     * asked for — see resolveImageProvider. `hasOpenAI || hasGemini` is checked
+     * above, so this is non-null here. */
+    const provider = resolveImageProvider(requestedProvider) ?? "openai";
     const alt = prompt.slice(0, 200);
     const store = storeOf(deps);
     try {
-        if (provider === "gemini" && hasGemini) {
+        if (provider === "gemini") {
             const url = await generateWithGemini({ prompt, aspectRatio: body.aspectRatio, model: requestedModel || undefined }, deps, store);
             if (!url)
                 return { code: 502, body: { error: "Gemini image generation returned no data" } };

package/dist/image/image-helpers.d.ts

@@ -73,6 +73,23 @@ export declare function saveGeminiInlineImage(parts: Array<{
 } | null>;
 export declare const GEMINI_ASPECT_RATIOS: Record<string, string>;
 export declare function getGeminiClient(): Promise<any>;
+export type ImageProvider = "openai" | "gemini";
+/**
+ * Which image backend this process can actually reach, given the keys it holds.
+ *
+ * `IMAGE_GEN_PROVIDER` (and a per-request hint) says which backend is *wanted*;
+ * this says which one can answer. The two were previously conflated, and the
+ * fallback ran in one direction only — a gemini request without a Google key
+ * fell through to OpenAI, but an OpenAI request without an OpenAI key did not
+ * fall through to Gemini. Since `IMAGE_GEN_PROVIDER` defaults to `openai`, a
+ * deployment funding only `GOOGLE_GENAI_API_KEY` took that second branch on
+ * every request: `/status/planner` advertised `imageGenerate: true` (it is true
+ * for *either* key), the editor showed the Generate tab, and every generation
+ * came back "OPENAI_API_KEY not configured".
+ *
+ * Returns null when neither key is set, which is the caller's 503.
+ */
+export declare function resolveImageProvider(requested?: string): ImageProvider | null;
 export declare function getGeminiImageModel(): string;
 export declare function generateVariationImageWithGemini(args: {
     prompt: string;

package/dist/image/image-helpers.js

@@ -310,6 +310,31 @@ export async function getGeminiClient() {
     _geminiClient = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENAI_API_KEY });
     return _geminiClient;
 }
+/**
+ * Which image backend this process can actually reach, given the keys it holds.
+ *
+ * `IMAGE_GEN_PROVIDER` (and a per-request hint) says which backend is *wanted*;
+ * this says which one can answer. The two were previously conflated, and the
+ * fallback ran in one direction only — a gemini request without a Google key
+ * fell through to OpenAI, but an OpenAI request without an OpenAI key did not
+ * fall through to Gemini. Since `IMAGE_GEN_PROVIDER` defaults to `openai`, a
+ * deployment funding only `GOOGLE_GENAI_API_KEY` took that second branch on
+ * every request: `/status/planner` advertised `imageGenerate: true` (it is true
+ * for *either* key), the editor showed the Generate tab, and every generation
+ * came back "OPENAI_API_KEY not configured".
+ *
+ * Returns null when neither key is set, which is the caller's 503.
+ */
+export function resolveImageProvider(requested) {
+    const hasOpenAI = Boolean(process.env.OPENAI_API_KEY);
+    const hasGemini = Boolean(process.env.GOOGLE_GENAI_API_KEY);
+    if (!hasOpenAI && !hasGemini)
+        return null;
+    const want = (requested?.trim().toLowerCase() || process.env.IMAGE_GEN_PROVIDER?.trim().toLowerCase() || "openai");
+    if (want === "gemini")
+        return hasGemini ? "gemini" : "openai";
+    return hasOpenAI ? "openai" : "gemini";
+}
 export function getGeminiImageModel() {
     return process.env.GOOGLE_GENAI_IMAGE_MODEL?.trim() || "gemini-3.1-flash-lite-image";
 }

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

@@ -75,4 +75,26 @@ export declare function blockContractsSummary(manifest?: BlockManifest): Record<
  */
 export declare const KEYLESS_PLANNER_NOTICE: string;
 export declare function withKeylessNotice(plan: EditPlan): EditPlan;
+/**
+ * Drop the suggestions this planner could not act on.
+ *
+ * `postEditSuggestions` and `clarificationSuggestions` are written against the
+ * product — "Edit Banner", "Move FAQ", "Add author photos" — because with a key
+ * configured a model answers them, and it can. With no key the answer comes
+ * from `demoPlanFromMessage`, a short list of English substring matchers, and
+ * almost none of those phrasings is on it. A clean-room first run clicked six
+ * follow-up chips against a keyless scaffold; five produced zero operations and
+ * the same paragraph about adding a key.
+ *
+ * A suggestion chip is sent verbatim on click, so an unanswerable one is a
+ * button that does nothing. The filter is the matcher itself rather than a
+ * second list of blessed phrasings — a list would be one more thing to drift,
+ * and this cannot: if `demoPlanFromMessage` stops answering something, the chip
+ * for it stops being offered in the same commit.
+ *
+ * Returning fewer chips, or none, is the intended outcome. Three real ones beat
+ * six of which one works, and no chips at all leaves the keyless notice to say
+ * the thing that actually needs saying.
+ */
+export declare function keepDemoExecutable(suggestions: string[], slug: string, activeBlockId?: string, activeBlockType?: string): string[];
 export {};

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

@@ -393,13 +393,18 @@ export function demoPlanFromMessage(message, slug, activeBlockId, activeBlockTyp
     if (lower.includes("add testimonials")) {
         return {
             intent: "edit_plan",
-            summary_for_user: "Added a testimonials section below the hero.",
-            change_log: ["Inserted Testimonials block after the hero section."],
+            summary_for_user: "Added a testimonials section.",
+            change_log: ["Inserted a Testimonials block at the end of the page."],
             ops: [
                 {
                     op: "add_block",
                     pageSlug: slug,
-                    afterBlockId: "b_hero_home",
+                    /* No `afterBlockId`. It used to name `b_hero_home`, a block id that
+                     * exists on no page in the shipped demo — the home hero is
+                     * `b_hero_1772138902220_copy` — so the anchor silently missed and the
+                     * block landed whereever the fallback put it, while the summary
+                     * promised "below the hero". Appending is the honest version of what
+                     * it already did, and it cannot point at a block that is not there. */
                     block: {
                         id: `b_testimonials_${Date.now()}`,
                         type: "Testimonials",
@@ -627,3 +632,34 @@ export function withKeylessNotice(plan) {
         return plan;
     return { ...plan, summary_for_user: KEYLESS_PLANNER_NOTICE };
 }
+/**
+ * Drop the suggestions this planner could not act on.
+ *
+ * `postEditSuggestions` and `clarificationSuggestions` are written against the
+ * product — "Edit Banner", "Move FAQ", "Add author photos" — because with a key
+ * configured a model answers them, and it can. With no key the answer comes
+ * from `demoPlanFromMessage`, a short list of English substring matchers, and
+ * almost none of those phrasings is on it. A clean-room first run clicked six
+ * follow-up chips against a keyless scaffold; five produced zero operations and
+ * the same paragraph about adding a key.
+ *
+ * A suggestion chip is sent verbatim on click, so an unanswerable one is a
+ * button that does nothing. The filter is the matcher itself rather than a
+ * second list of blessed phrasings — a list would be one more thing to drift,
+ * and this cannot: if `demoPlanFromMessage` stops answering something, the chip
+ * for it stops being offered in the same commit.
+ *
+ * Returning fewer chips, or none, is the intended outcome. Three real ones beat
+ * six of which one works, and no chips at all leaves the keyless notice to say
+ * the thing that actually needs saying.
+ */
+export function keepDemoExecutable(suggestions, slug, activeBlockId, activeBlockType) {
+    return suggestions.filter((suggestion) => {
+        try {
+            return demoPlanFromMessage(suggestion, slug, activeBlockId, activeBlockType).ops.length > 0;
+        }
+        catch {
+            return false;
+        }
+    });
+}

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

@@ -78,7 +78,7 @@ export declare function compileDeterministicPlan(args: {
     locale?: string;
 }): EditPlan | null;
 export { extractAudienceTarget, extractAudienceTargets, titleCaseWords, addAudienceSuffix, audiencePatchForBlock, coercePatchForBlock, parseIndexedPath, inferSimpleFieldPatchFromMessage, isRewriteRequest, isTranslationRequest, shouldKeepRichTextTitleOnTranslate, inferFieldHintFromMessage, rewriteFromExisting, coercePatchForEditablePath, quotedText, buildListAppendPatch } from "./deterministic-planner-patches.ts";
-export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, withKeylessNotice, KEYLESS_PLANNER_NOTICE, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.ts";
+export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, keepDemoExecutable, withKeylessNotice, KEYLESS_PLANNER_NOTICE, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.ts";
 export { nextAvailableSlug, createPageBlocks, buildCreatePagePlan, isPageRouteRenameRequest } from "./deterministic-planner-pages.ts";
 export { readPathValue, resolveImageUrlForAltField, fetchImageAsBase64, resolveAttachmentsForLlm, selectedBlockSnapshot, arrayPropLengths, pageIntentSummary, plannerContextPack } from "./deterministic-planner-context.ts";
 export type { ResolvedLlmAttachment } from "./deterministic-planner-context.ts";

package/dist/nlp/deterministic-planner.js

@@ -1628,7 +1628,7 @@ export function compileDeterministicPlan(args) {
 // Re-exports from split files (preserve public API)
 // ---------------------------------------------------------------------------
 export { extractAudienceTarget, extractAudienceTargets, titleCaseWords, addAudienceSuffix, audiencePatchForBlock, coercePatchForBlock, parseIndexedPath, inferSimpleFieldPatchFromMessage, isRewriteRequest, isTranslationRequest, shouldKeepRichTextTitleOnTranslate, inferFieldHintFromMessage, rewriteFromExisting, coercePatchForEditablePath, quotedText, buildListAppendPatch } from "./deterministic-planner-patches.js";
-export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, withKeylessNotice, KEYLESS_PLANNER_NOTICE, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.js";
+export { editablePropsFromBlock, promptFromPropKey, userFacingPropNames, ORDINALS, humanizeArrayPath, childSuggestions, clarificationSuggestions, postEditSuggestions, demoPlanFromMessage, keepDemoExecutable, withKeylessNotice, KEYLESS_PLANNER_NOTICE, titleCaseSentence, pageMetaContractSummary, blockContractsSummary } from "./deterministic-planner-suggestions.js";
 export { nextAvailableSlug, createPageBlocks, buildCreatePagePlan, isPageRouteRenameRequest } from "./deterministic-planner-pages.js";
 export { readPathValue, resolveImageUrlForAltField, fetchImageAsBase64, resolveAttachmentsForLlm, selectedBlockSnapshot, arrayPropLengths, pageIntentSummary, plannerContextPack } from "./deterministic-planner-context.js";
 export { inferAddedBlockTypeFromMessage, resolveBlockRef, ordinalToIndex, resolveByDescriptor, resolveReferencesFromMessage } from "./deterministic-planner-refs.js";

package/dist/tools/builtins/image-generate.js

@@ -1,4 +1,4 @@
-import { generateVariationImageWithOpenAI, generateVariationImageWithGemini, recordImageGenDuration, estimatedImageGenMs } from "../../image/image-helpers.js";
+import { generateVariationImageWithOpenAI, generateVariationImageWithGemini, recordImageGenDuration, estimatedImageGenMs, resolveImageProvider } from "../../image/image-helpers.js";
 import { getPage } from "../../state/session-state.js";
 const ASPECT_RATIO_TO_SIZE = {
     landscape: "1536x1024",
@@ -170,7 +170,9 @@ export const imageGenerateHandler = async ({ input, context, signal }) => {
         const pct = Math.min(Math.round(cur.pct + stageProgress * (next.pct - cur.pct)), 95);
         onProgress({ percent: pct, stage: cur.label });
     }, 500) : null;
-    const provider = (process.env.IMAGE_GEN_PROVIDER?.trim().toLowerCase()) || "openai";
+    /* Key-aware, not just env-aware: a deployment holding only
+     * GOOGLE_GENAI_API_KEY used to land on the OpenAI branch here and fail. */
+    const provider = resolveImageProvider();
     const genStart = Date.now();
     let result = null;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -22,8 +22,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.35.4",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/shared": "^0.9.0",
-    "@avocadostudio-ai/migration-sdk": "^0.9.0"
+    "@avocadostudio-ai/shared": "^0.11.0",
+    "@avocadostudio-ai/migration-sdk": "^0.11.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",