@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/chat/gemini-planner.js

@@ -0,0 +1,541 @@
+import { z } from "zod";
+import { allowedBlockTypes, editPlanSchema } from "@avocadostudio-ai/shared";
+import { buildIntentParserSystemPrompt, buildPlannerSystemPrompt } from "./prompts.js";
+import { extractAudienceTarget, fetchImageAsBase64, resolveAttachmentsForLlm, intentSchema } from "../nlp/deterministic-planner.js";
+import { isBatchAddRequest, isBatchRemoveRequest, isBatchReorderRequest, isPageWideRewriteRequest, requestsPlanFirst } from "../nlp/intent-detection.js";
+import { extractJsonObject, normalizePlanCandidate, repairAndParseJsonWithMeta } from "../nlp/plan-normalizer.js";
+import { ZERO_USAGE } from "../telemetry/usage.js";
+import { buildEditPlanJsonSchema, intentJsonSchema } from "./plan-json-schema.js";
+import { executeToolCall } from "../tools/runtime.js";
+import { PlannerError } from "../errors.js";
+import { extractSummaryFromPlanBuffer, extractOpsFromPlanBuffer, extractUpdatePropsFieldDraftsFromPlanBuffer, isChatStrictPrimaryOpMode, isPageWideTranslationRequest, buildPlannerSchemaContext } from "./planner.js";
+import { getGeminiClient } from "../image/image-helpers.js";
+import { GENERATING_IMAGE_PLACEHOLDER, SEARCHING_IMAGE_PLACEHOLDER, DEFERRABLE_IMAGE_TOOLS } from "./chat-pipeline-shared.js";
+const LLM_TIMEOUT_MS = 120_000;
+function raceWithAbort(promise, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+        promise.then(resolve, reject);
+    });
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+// Lenient: change_log can be string or array (Gemini returns string per schema,
+// normalizePlanCandidate converts it downstream).
+const rawPlanCandidateSchema = z.looseObject({
+    intent: z.enum(["edit_plan", "needs_clarification", "content_answer"]).optional().catch(undefined),
+    summary_for_user: z.string().optional(),
+    change_log: z.union([z.array(z.string()), z.string()]).optional(),
+    ops: z.array(z.record(z.string(), z.unknown())).optional(),
+    suggested_next_actions: z.union([z.array(z.string()), z.string()]).optional()
+});
+function toPlannerError(category, message, retryable = false) {
+    return new PlannerError(message, { reasonCategory: category, retryable });
+}
+function extractGeminiUsage(response) {
+    const meta = response?.usageMetadata;
+    if (!meta)
+        return { ...ZERO_USAGE };
+    const inputTokens = typeof meta.promptTokenCount === "number" ? meta.promptTokenCount : 0;
+    const outputTokens = typeof meta.candidatesTokenCount === "number" ? meta.candidatesTokenCount : 0;
+    return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+function extractGeminiText(response) {
+    const candidates = response?.candidates;
+    if (!Array.isArray(candidates) || candidates.length === 0)
+        return "";
+    const parts = candidates[0]?.content?.parts;
+    if (!Array.isArray(parts))
+        return "";
+    return parts.map((p) => p.text ?? "").join("");
+}
+function extractGeminiFunctionCalls(response) {
+    const candidates = response?.candidates;
+    if (!Array.isArray(candidates) || candidates.length === 0)
+        return [];
+    const parts = candidates[0]?.content?.parts;
+    if (!Array.isArray(parts))
+        return [];
+    return parts
+        .filter((p) => !!p.functionCall)
+        .map((p) => ({ name: p.functionCall.name, args: p.functionCall.args }));
+}
+function toGeminiHistory(history) {
+    // Drop blank turns — an empty/whitespace text part is invalid and can fail the
+    // request, so one stray turn must not break the whole plan (#33, mirrors Anthropic).
+    return history
+        .filter((h) => typeof h.content === "string" && h.content.trim().length > 0)
+        .map((h) => ({
+        role: h.role === "assistant" ? "model" : "user",
+        parts: [{ text: h.content }]
+    }));
+}
+/** Relaxed safety settings — users are editing their own site content */
+const PERMISSIVE_SAFETY_SETTINGS = [
+    { category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_ONLY_HIGH" },
+    { category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_ONLY_HIGH" },
+];
+// ---------------------------------------------------------------------------
+// Intent parsing
+// ---------------------------------------------------------------------------
+export async function parseIntentWithGemini(args) {
+    const ai = await getGeminiClient();
+    const system = buildIntentParserSystemPrompt();
+    const user = {
+        request: args.message,
+        slug: args.slug,
+        activeBlockId: args.activeBlockId ?? null,
+        activeBlockType: args.activeBlockType ?? null,
+        activeEditablePath: args.activeEditablePath ?? null,
+        availableBlockTypes: allowedBlockTypes,
+        blocks: args.currentPage.blocks.map((b) => ({ id: b.id, type: b.type, props: Object.keys(b.props) }))
+    };
+    const response = await raceWithAbort(ai.models.generateContent({
+        model: args.model,
+        contents: JSON.stringify(user),
+        config: {
+            systemInstruction: system,
+            responseMimeType: "application/json",
+            responseJsonSchema: intentJsonSchema,
+            temperature: 0,
+            safetySettings: PERMISSIVE_SAFETY_SETTINGS,
+        }
+    }), AbortSignal.timeout(LLM_TIMEOUT_MS));
+    const raw = extractGeminiText(response);
+    if (!raw.trim())
+        throw new Error("Intent parser did not return JSON");
+    const normalized = JSON.parse(raw);
+    // Nulls from the schema become undefined for Zod optional fields
+    for (const key of Object.keys(normalized)) {
+        if (normalized[key] === null)
+            delete normalized[key];
+    }
+    const parsed = intentSchema.safeParse(normalized);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const detail = issue?.message ?? "Invalid intent parser output";
+        const at = issue?.path?.length ? ` at ${issue.path.join(".")}` : "";
+        throw new Error(`${detail}${at}`);
+    }
+    return parsed.data;
+}
+// ---------------------------------------------------------------------------
+// Plan generation
+// ---------------------------------------------------------------------------
+export async function generatePlanWithGemini(args) {
+    const ai = await getGeminiClient();
+    const effectiveSignal = args.signal
+        ? AbortSignal.any([args.signal, AbortSignal.timeout(LLM_TIMEOUT_MS)])
+        : AbortSignal.timeout(LLM_TIMEOUT_MS);
+    const effectiveBlockTypes = args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : allowedBlockTypes;
+    const batchOverride = isBatchAddRequest(args.message) || isBatchRemoveRequest(args.message) || isBatchReorderRequest(args.message) || isPageWideRewriteRequest(args.message);
+    const pageWideRewrite = isPageWideRewriteRequest(args.message);
+    const planFirstMode = requestsPlanFirst(args.message);
+    // In plan-first mode the intent enum is narrowed so the model can't bail to
+    // needs_clarification — it must produce a reviewable plan (see buildEditPlanJsonSchema).
+    const requestEditPlanSchema = buildEditPlanJsonSchema({ planFirstMode });
+    const requestGeminiEditPlanSchema = {
+        ...requestEditPlanSchema,
+        propertyOrdering: ["intent", "summary_for_user", "change_log", "ops", "suggested_next_actions"]
+    };
+    const pageWideTranslation = isPageWideTranslationRequest(args.message);
+    const chatStrictPrimaryOpMode = isChatStrictPrimaryOpMode() && !batchOverride && !pageWideTranslation;
+    const selectedBlockId = String(args.contextPack.selected.blockId ?? "");
+    const audienceHint = extractAudienceTarget(args.message);
+    const explicitOtherReference = selectedBlockId.length > 0 &&
+        Array.isArray(args.contextPack.resolvedReferences.mentionedBlocks) &&
+        args.contextPack.resolvedReferences.mentionedBlocks.some((entry) => entry && typeof entry === "object" && "id" in entry && entry.id !== selectedBlockId);
+    const system = buildPlannerSystemPrompt({
+        provider: "gemini",
+        lightweight: !!args.lightweight,
+        selectedBlockId,
+        explicitOtherReference: !!explicitOtherReference,
+        chatStrictPrimaryOpMode,
+        pageWideTranslation,
+        pageWideRewrite,
+        planFirstMode,
+        effectiveBlockTypes,
+        siteContextBlock: args.siteContextBlock,
+        imageUrlForVision: args.contextPack.selected?.imageUrlForVision,
+        editablePath: args.contextPack.selected?.editablePath,
+        blockId: args.contextPack.selected?.blockId,
+        locale: args.locale,
+        imageSourceChoiceOpen: args.imageSourceChoiceOpen,
+        attachmentCount: args.contextPack.attachments?.length,
+    });
+    const includeContracts = !args.lightweight && (batchOverride ||
+        pageWideTranslation ||
+        /\b(create|add|insert|build|generate)\b/.test(args.message.toLowerCase()) ||
+        /\b(seo|meta|metadata|og\s*image|open\s*graph|description|structured\s*data|schema\.org)\b/.test(args.message.toLowerCase()) ||
+        /\d{2,3}\s*char/i.test(args.message));
+    const schemaContext = args.lightweight
+        ? {
+            payload: {},
+            meta: {
+                contractMode: "minimal",
+                contractBytes: 0,
+                contractBlockCount: 0,
+                targetBlockTypes: [],
+                strictJsonEnabled: false
+            }
+        }
+        : buildPlannerSchemaContext({
+            message: args.message,
+            contextPack: args.contextPack,
+            batchOverride,
+            pageWideTranslation,
+            legacyIncludeContracts: includeContracts,
+            forceFullContracts: args.forceFullSchemaContracts,
+            componentsManifest: args.componentsManifest
+        });
+    const userPayload = {
+        request: args.message,
+        audienceHint: audienceHint ?? null,
+        slug: args.slug,
+        contextPack: args.contextPack,
+        ...schemaContext.payload,
+        feedback: args.feedback ?? null
+    };
+    // Vision support
+    const imageUrlForVision = typeof args.contextPack.selected?.imageUrlForVision === "string"
+        ? args.contextPack.selected.imageUrlForVision
+        : null;
+    const imageBase64 = imageUrlForVision ? await fetchImageAsBase64(imageUrlForVision) : null;
+    // User-attached files (images + PDFs) as inline data — Gemini reads both natively.
+    const resolvedAttachments = await resolveAttachmentsForLlm(args.contextPack.attachments);
+    // Build user content parts
+    const userParts = [];
+    if (imageBase64) {
+        userParts.push({ inlineData: { mimeType: imageBase64.mediaType, data: imageBase64.base64 } });
+    }
+    for (const attachment of resolvedAttachments) {
+        userParts.push({ inlineData: { mimeType: attachment.mediaType, data: attachment.base64 } });
+    }
+    userParts.push({ text: JSON.stringify(userPayload) });
+    // Build contents array (history + current message)
+    const contents = [
+        ...toGeminiHistory(args.history ?? []),
+        { role: "user", parts: userParts }
+    ];
+    // -----------------------------------------------------------------------
+    // Tool runtime path — function calling with agentic loop
+    // -----------------------------------------------------------------------
+    const hasRuntimeTools = args.toolRuntime && args.toolCallContext;
+    const deferredNativeImageCalls = [];
+    if (hasRuntimeTools) {
+        const raw = await runToolLoop({
+            ai,
+            model: args.model,
+            system,
+            contents,
+            toolRuntime: args.toolRuntime,
+            toolCallContext: args.toolCallContext,
+            planSchema: requestEditPlanSchema,
+            onToken: args.onToken,
+            onToolExecution: args.onToolExecution,
+            onStatusUpdate: args.onStatusUpdate,
+            onImageProgress: args.onImageProgress,
+            deferredNativeImageCalls,
+            log: args.log,
+            signal: effectiveSignal,
+        });
+        const result = parseAndValidatePlan(raw, args, chatStrictPrimaryOpMode, schemaContext);
+        return {
+            ...result,
+            deferredNativeImageCalls: deferredNativeImageCalls.length > 0 ? deferredNativeImageCalls : undefined
+        };
+    }
+    // -----------------------------------------------------------------------
+    // JSON mode path — streaming or non-streaming (like OpenAI planner)
+    // -----------------------------------------------------------------------
+    let raw = "";
+    let usage = { ...ZERO_USAGE };
+    if (args.onToken) {
+        // Streaming path
+        let streamedOpsCount = 0;
+        let lastSummaryLen = 0;
+        let emittedChangeLogCount = 0;
+        const emittedFieldDraftByKey = new Map();
+        const stream = await raceWithAbort(ai.models.generateContentStream({
+            model: args.model,
+            contents,
+            config: {
+                systemInstruction: system,
+                responseMimeType: "application/json",
+                responseJsonSchema: requestGeminiEditPlanSchema,
+                temperature: 0,
+                safetySettings: PERMISSIVE_SAFETY_SETTINGS,
+            }
+        }), effectiveSignal);
+        for await (const chunk of stream) {
+            const text = extractGeminiText(chunk);
+            if (!text)
+                continue;
+            raw += text;
+            args.onToken(text);
+            // Progressive field draft extraction
+            if (args.onFieldDraft) {
+                const fieldDrafts = extractUpdatePropsFieldDraftsFromPlanBuffer(raw);
+                for (const draft of fieldDrafts) {
+                    const key = `${draft.opIndex}:${draft.blockId}:${draft.editablePath}`;
+                    const prev = emittedFieldDraftByKey.get(key);
+                    if (prev === draft.value)
+                        continue;
+                    emittedFieldDraftByKey.set(key, draft.value);
+                    args.onFieldDraft({ blockId: draft.blockId, editablePath: draft.editablePath, value: draft.value, ...(draft.pageSlug ? { pageSlug: draft.pageSlug } : {}) });
+                }
+            }
+            // Progressive summary + change log extraction
+            if (args.onSummaryChunk || args.onChangeLogEntry) {
+                const extracted = extractSummaryFromPlanBuffer(raw);
+                if (extracted.summary && extracted.summary.length > lastSummaryLen) {
+                    args.onSummaryChunk?.(extracted.summary.slice(lastSummaryLen));
+                    lastSummaryLen = extracted.summary.length;
+                }
+                for (let i = emittedChangeLogCount; i < extracted.changeLog.length; i++) {
+                    args.onChangeLogEntry?.(extracted.changeLog[i]);
+                }
+                emittedChangeLogCount = extracted.changeLog.length;
+            }
+            // Progressive ops extraction
+            if (args.onPlannedOp) {
+                const next = extractOpsFromPlanBuffer(raw, streamedOpsCount);
+                streamedOpsCount = next.nextEmittedCount;
+                for (let idx = 0; idx < next.newOps.length; idx += 1) {
+                    args.onPlannedOp(next.newOps[idx], streamedOpsCount - next.newOps.length + idx + 1);
+                }
+            }
+            // Extract usage from last chunk
+            const chunkUsage = extractGeminiUsage(chunk);
+            if (chunkUsage.totalTokens > 0)
+                usage = chunkUsage;
+        }
+        if (raw.trim().length === 0) {
+            throw toPlannerError("incomplete_output", "Model returned no planning output");
+        }
+    }
+    else {
+        // Non-streaming path
+        const response = await raceWithAbort(ai.models.generateContent({
+            model: args.model,
+            contents,
+            config: {
+                systemInstruction: system,
+                responseMimeType: "application/json",
+                responseJsonSchema: requestGeminiEditPlanSchema,
+                temperature: 0,
+                safetySettings: PERMISSIVE_SAFETY_SETTINGS,
+            }
+        }), effectiveSignal);
+        raw = extractGeminiText(response);
+        usage = extractGeminiUsage(response);
+        if (raw.trim().length === 0) {
+            throw toPlannerError("incomplete_output", "Model returned no planning output");
+        }
+    }
+    return parseAndValidatePlan(raw, args, chatStrictPrimaryOpMode, schemaContext, usage);
+}
+// ---------------------------------------------------------------------------
+// Tool loop — agentic function calling for image gen, unsplash, etc.
+// ---------------------------------------------------------------------------
+const MAX_TOOL_TURNS = 6;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function runToolLoop(args) {
+    // Build function declarations from tool registry + submit_edit_plan
+    const runtimeManifests = args.toolRuntime.registry.listManifests();
+    const functionDeclarations = [
+        {
+            name: "submit_edit_plan",
+            description: "Submit the structured EditPlan JSON.",
+            parameters: args.planSchema
+        },
+        ...runtimeManifests.map((m) => ({
+            name: m.name.replace(/\./g, "_"), // Gemini requires alphanumeric + underscore
+            description: m.description,
+            parameters: m.inputSchema
+        }))
+    ];
+    // Map aliased names back to runtime names
+    const aliasToRuntimeName = new Map();
+    for (const m of runtimeManifests) {
+        aliasToRuntimeName.set(m.name.replace(/\./g, "_"), m.name);
+    }
+    const messages = [...args.contents];
+    let submitPlanJson = "";
+    for (let turn = 0; turn < MAX_TOOL_TURNS; turn++) {
+        const callSignal = args.signal ?? AbortSignal.timeout(LLM_TIMEOUT_MS);
+        const response = await raceWithAbort(args.ai.models.generateContent({
+            model: args.model,
+            contents: messages,
+            config: {
+                systemInstruction: args.system,
+                temperature: 0,
+                safetySettings: PERMISSIVE_SAFETY_SETTINGS,
+                tools: [{ functionDeclarations }],
+                toolConfig: { functionCallingConfig: { mode: "ANY" } },
+            }
+        }), callSignal);
+        const text = extractGeminiText(response);
+        if (text && args.onToken)
+            args.onToken(text);
+        const functionCalls = extractGeminiFunctionCalls(response);
+        if (functionCalls.length === 0) {
+            // Model returned text instead of function call — treat as plan JSON
+            return text || submitPlanJson;
+        }
+        // Process function calls
+        const toolResults = [];
+        for (const fc of functionCalls) {
+            if (fc.name === "submit_edit_plan") {
+                submitPlanJson = JSON.stringify(fc.args);
+                toolResults.push({
+                    functionResponse: { name: fc.name, response: { ok: true } }
+                });
+                continue;
+            }
+            const runtimeName = aliasToRuntimeName.get(fc.name) ?? fc.name;
+            const input = fc.args ?? {};
+            // Defer image tools
+            if (DEFERRABLE_IMAGE_TOOLS.has(runtimeName)) {
+                const placeholder = runtimeName === "image.generate"
+                    ? GENERATING_IMAGE_PLACEHOLDER
+                    : SEARCHING_IMAGE_PLACEHOLDER;
+                const placeholderData = runtimeName === "image.generate"
+                    ? { imageUrl: placeholder, alt: String(input.prompt ?? "Generating image…"), width: 768, height: 512 }
+                    : { items: [{ id: "placeholder", imageUrl: placeholder, thumbUrl: placeholder, alt: String(input.query ?? "Searching…"), author: "Placeholder", sourceUrl: "" }] };
+                args.deferredNativeImageCalls.push({
+                    toolName: runtimeName,
+                    input,
+                    placeholderUrl: placeholder
+                });
+                toolResults.push({
+                    functionResponse: { name: fc.name, response: placeholderData }
+                });
+                args.onToolExecution?.({
+                    toolName: runtimeName,
+                    ok: true,
+                    latencyMs: 0,
+                    attempts: 0,
+                    traceId: args.toolCallContext.traceId,
+                    sessionId: args.toolCallContext.sessionId,
+                    siteId: args.toolCallContext.siteId,
+                    plannerProvider: "gemini",
+                    deferred: true
+                });
+                continue;
+            }
+            // Execute runtime tool
+            const startMs = Date.now();
+            const result = await executeToolCall({
+                runtime: args.toolRuntime,
+                toolName: runtimeName,
+                input,
+                context: {
+                    siteId: args.toolCallContext.siteId,
+                    sessionId: args.toolCallContext.sessionId,
+                    userId: args.toolCallContext.userId,
+                    traceId: args.toolCallContext.traceId,
+                    plannerProvider: "gemini",
+                    gdriveFolderId: args.toolCallContext.gdriveFolderId,
+                    onStatusUpdate: args.onStatusUpdate,
+                    onImageProgress: args.onImageProgress,
+                },
+                policy: args.toolRuntime.defaultPolicy
+            });
+            const latencyMs = Date.now() - startMs;
+            args.onToolExecution?.({
+                toolName: runtimeName,
+                ok: result.ok,
+                latencyMs,
+                attempts: result.attempts,
+                traceId: args.toolCallContext.traceId,
+                sessionId: args.toolCallContext.sessionId,
+                siteId: args.toolCallContext.siteId,
+                plannerProvider: "gemini",
+                ...(result.ok ? {} : { errorCode: result.error?.code })
+            });
+            toolResults.push({
+                functionResponse: {
+                    name: fc.name,
+                    response: result.ok
+                        ? (typeof result.data === "object" && result.data !== null ? result.data : { result: result.data })
+                        : { error: String(result.error?.message ?? "Tool execution failed") }
+                }
+            });
+        }
+        // If we got submit_edit_plan, we're done
+        if (submitPlanJson)
+            return submitPlanJson;
+        // Add model response + tool results to conversation
+        const modelParts = functionCalls.map((fc) => ({ functionCall: { name: fc.name, args: fc.args } }));
+        messages.push({ role: "model", parts: modelParts });
+        messages.push({ role: "user", parts: toolResults });
+    }
+    // Exhausted max turns — return whatever we have
+    if (submitPlanJson)
+        return submitPlanJson;
+    throw toPlannerError("incomplete_output", `Gemini tool loop exhausted ${MAX_TOOL_TURNS} turns without submitting a plan`);
+}
+// ---------------------------------------------------------------------------
+// Shared parse + validate
+// ---------------------------------------------------------------------------
+function parseAndValidatePlan(raw, args, chatStrictPrimaryOpMode, schemaContext, usage = { ...ZERO_USAGE }) {
+    const jsonText = extractJsonObject(raw) ?? raw;
+    if (!jsonText.trim()) {
+        throw toPlannerError("malformed_output", "Model did not return JSON", true);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(jsonText);
+    }
+    catch (err) {
+        try {
+            const meta = repairAndParseJsonWithMeta(jsonText);
+            parsedJson = meta.parsed;
+            if (meta.strategy !== "none") {
+                console.warn(`[gemini-planner] JSON repaired via ${meta.strategy}${meta.mutationCount ? ` (${meta.mutationCount} mutations)` : ""}${meta.discardedBytes ? ` (${meta.discardedBytes}B discarded)` : ""}`);
+            }
+        }
+        catch {
+            const posMatch = err instanceof SyntaxError ? /position (\d+)/i.exec(err.message) : null;
+            const pos = posMatch?.[1];
+            const snippet = pos ? jsonText.slice(Math.max(0, Number(pos) - 30), Number(pos) + 30) : jsonText.slice(0, 200);
+            throw toPlannerError("malformed_output", `Model returned malformed JSON: ${err.message}. Near: …${snippet}…`, true);
+        }
+    }
+    const rawCandidateResult = rawPlanCandidateSchema.safeParse(parsedJson);
+    if (!rawCandidateResult.success) {
+        const first = rawCandidateResult.error.issues[0];
+        const at = first?.path?.length ? ` at ${first.path.join(".")}` : "";
+        const detail = first?.message ?? "Raw planner output shape is invalid";
+        throw toPlannerError("malformed_output", `${detail}${at}`, true);
+    }
+    const parsed = normalizePlanCandidate(rawCandidateResult.data, {
+        defaultSlug: args.slug,
+        currentPage: args.currentPage,
+        userMessage: args.message
+    });
+    const planResult = editPlanSchema.safeParse(parsed);
+    if (!planResult.success) {
+        const first = planResult.error.issues[0];
+        const message = first?.message ?? "Invalid model output";
+        const path = first?.path?.length ? ` at ${first.path.join(".")}` : "";
+        const sample = JSON.stringify(parsed).slice(0, 700);
+        throw toPlannerError("schema_violation", `${message}${path}. Parsed sample: ${sample}`, true);
+    }
+    if (chatStrictPrimaryOpMode && planResult.data.intent === "edit_plan" && planResult.data.ops.length > 1) {
+        return {
+            plan: { ...planResult.data, ops: [planResult.data.ops[0]] },
+            usage,
+            schemaContext: schemaContext.meta
+        };
+    }
+    return { plan: planResult.data, usage, schemaContext: schemaContext.meta };
+}

package/dist/chat/hallucination-validator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Post-plan hallucination validator.
+ *
+ * Catches planner-generated `update_props` ops whose patches contain keys
+ * that aren't in the target block's schema — typically when the planner
+ * promises visual changes (colors, animations, gradients) that the block
+ * doesn't support. Strips the unsupported keys, appends a user-facing note
+ * to `summary_for_user`, and emits a telemetry signal for later analysis.
+ *
+ * Complements the STRICT SCHEMA DISCIPLINE prompt rule: defense in depth
+ * against LLMs that paper over schema limits in their summary text.
+ */
+import { type EditPlan, type PageDoc } from "@avocadostudio-ai/shared";
+export type HallucinatedProp = {
+    blockId: string;
+    blockType: string;
+    propName: string;
+};
+export type HallucinationValidationResult = {
+    plan: EditPlan;
+    hallucinatedProps: HallucinatedProp[];
+};
+/**
+ * Scan every `update_props` op in the plan, strip patch keys that are not
+ * in the block's schema, collect the removed (blockType, propName) pairs,
+ * and append a single merged note to `summary_for_user` when anything was
+ * stripped.
+ *
+ * Mutates `plan` in place (strips keys, appends the summary note, appends
+ * change_log entries) and returns the updated plan alongside the list of
+ * stripped props for logging.
+ */
+export declare function validateAndStripHallucinatedProps(args: {
+    plan: EditPlan;
+    draft: Map<string, PageDoc>;
+}): HallucinationValidationResult;

package/dist/chat/hallucination-validator.js

@@ -0,0 +1,110 @@
+/**
+ * Post-plan hallucination validator.
+ *
+ * Catches planner-generated `update_props` ops whose patches contain keys
+ * that aren't in the target block's schema — typically when the planner
+ * promises visual changes (colors, animations, gradients) that the block
+ * doesn't support. Strips the unsupported keys, appends a user-facing note
+ * to `summary_for_user`, and emits a telemetry signal for later analysis.
+ *
+ * Complements the STRICT SCHEMA DISCIPLINE prompt rule: defense in depth
+ * against LLMs that paper over schema limits in their summary text.
+ */
+import { blockSchemas, getBlockMeta } from "@avocadostudio-ai/shared";
+/**
+ * Return the set of top-level prop keys allowed by a block type's registered
+ * schema. Returns null when the block type is unregistered (e.g. custom
+ * blocks from an external manifest) — in that case we cannot validate and
+ * skip the check.
+ */
+function allowedPropKeysForBlockType(blockType) {
+    const schema = blockSchemas[blockType];
+    if (!schema)
+        return null;
+    const shape = schema.shape;
+    if (!shape || typeof shape !== "object")
+        return null;
+    return new Set(Object.keys(shape));
+}
+/**
+ * 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.
+ */
+function findBlockType(args) {
+    const { blockId, pageSlug, draft } = args;
+    if (pageSlug) {
+        const page = draft.get(pageSlug);
+        const hit = page?.blocks.find((b) => b.id === blockId);
+        if (hit)
+            return hit.type;
+    }
+    for (const page of draft.values()) {
+        const hit = page.blocks.find((b) => b.id === blockId);
+        if (hit)
+            return hit.type;
+    }
+    return undefined;
+}
+function humanBlockName(blockType) {
+    const meta = getBlockMeta(blockType);
+    return meta?.displayName ?? blockType;
+}
+/**
+ * Scan every `update_props` op in the plan, strip patch keys that are not
+ * in the block's schema, collect the removed (blockType, propName) pairs,
+ * and append a single merged note to `summary_for_user` when anything was
+ * stripped.
+ *
+ * Mutates `plan` in place (strips keys, appends the summary note, appends
+ * change_log entries) and returns the updated plan alongside the list of
+ * stripped props for logging.
+ */
+export function validateAndStripHallucinatedProps(args) {
+    const { plan, draft } = args;
+    const hallucinatedProps = [];
+    for (const op of plan.ops) {
+        if (op.op !== "update_props")
+            continue;
+        const blockType = findBlockType({ blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        if (!blockType)
+            continue;
+        const allowedKeys = allowedPropKeysForBlockType(blockType);
+        if (!allowedKeys)
+            continue;
+        const rawPatch = op.patch;
+        if (!rawPatch || typeof rawPatch !== "object")
+            continue;
+        const patchCandidate = rawPatch.props && typeof rawPatch.props === "object" && !Array.isArray(rawPatch.props)
+            ? rawPatch.props
+            : rawPatch;
+        for (const key of Object.keys(patchCandidate)) {
+            if (allowedKeys.has(key))
+                continue;
+            delete patchCandidate[key];
+            hallucinatedProps.push({ blockId: op.blockId, blockType, propName: key });
+        }
+    }
+    if (hallucinatedProps.length > 0) {
+        // Merge duplicates into a single readable note keyed by blockType. We
+        // intentionally avoid echoing the raw prop name back to the user —
+        // doing so is (a) jargon-y (users don't think in prop keys), and (b)
+        // makes the note trivially collide with eval banned-word checks that
+        // try to prove the planner didn't promise the unsupported behavior.
+        const byBlockType = new Map();
+        for (const entry of hallucinatedProps) {
+            const bucket = byBlockType.get(entry.blockType) ?? new Set();
+            bucket.add(entry.propName);
+            byBlockType.set(entry.blockType, bucket);
+        }
+        const noteParts = [];
+        for (const [blockType] of byBlockType) {
+            const name = humanBlockName(blockType);
+            noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+        }
+        const note = noteParts.join(" ");
+        const summary = plan.summary_for_user?.trimEnd() ?? "";
+        plan.summary_for_user = summary.length > 0 ? `${summary}\n\n${note}` : note;
+        plan.change_log = [...plan.change_log, note];
+    }
+    return { plan, hallucinatedProps };
+}