@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/chat/planner.js

@@ -0,0 +1,1361 @@
+import OpenAI from "openai";
+import { z } from "zod";
+import { allowedBlockTypes, blockSchemas, editPlanSchema } from "@avocadostudio-ai/shared";
+import { buildIntentParserSystemPrompt, buildPlannerSystemPrompt } from "./prompts.js";
+// ---------------------------------------------------------------------------
+// Singleton OpenAI client — reuses connection pool across requests.
+// ---------------------------------------------------------------------------
+const LLM_TIMEOUT_MS = 120_000;
+let _openaiSingleton = null;
+function getOpenAIClient() {
+    if (!_openaiSingleton) {
+        _openaiSingleton = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    }
+    return _openaiSingleton;
+}
+/** Reset the singleton (useful for tests that swap API keys). */
+export function resetOpenAIClient() {
+    _openaiSingleton = null;
+}
+import { extractAudienceTarget, blockContractsSummary, fetchImageAsBase64, resolveAttachmentsForLlm, pageMetaContractSummary, intentSchema } from "../nlp/deterministic-planner.js";
+import { isBatchAddRequest, isBatchRemoveRequest, isBatchReorderRequest, isPageWideRewriteRequest, isDuplicateAndModifyRequest, requestsPlanFirst } from "../nlp/intent-detection.js";
+import { extractJsonObject, inferBlockTypeFromText, normalizePlanCandidate, repairAndParseJsonWithMeta } from "../nlp/plan-normalizer.js";
+import { extractUsage, ZERO_USAGE } from "../telemetry/usage.js";
+import { intentJsonSchema } from "./plan-json-schema.js";
+import { PlannerError, isPlannerError } from "../errors.js";
+// Re-export for backward compatibility
+export { PlannerError, isPlannerError };
+/** @deprecated Use `PlannerError` instead. */
+export const PlannerOutputError = PlannerError;
+/** @deprecated Use `isPlannerError` instead. */
+export const isPlannerOutputError = isPlannerError;
+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 asObject(value) {
+    return value && typeof value === "object" ? value : null;
+}
+function toPlannerError(category, message, retryable = false) {
+    return new PlannerError(message, { reasonCategory: category, retryable });
+}
+function extractCompletionRefusal(completion) {
+    const choices = asObject(completion)?.choices;
+    if (!Array.isArray(choices) || choices.length === 0)
+        return null;
+    const choice = asObject(choices[0]);
+    const message = asObject(choice?.message);
+    const refusal = message?.refusal;
+    return typeof refusal === "string" && refusal.trim().length > 0 ? refusal.trim() : null;
+}
+function extractResponsesOutcome(response) {
+    const directRefusal = asObject(response)?.refusal;
+    if (typeof directRefusal === "string" && directRefusal.trim().length > 0) {
+        return { refusal: directRefusal.trim(), incomplete: false };
+    }
+    const status = asObject(response)?.status;
+    if (status === "incomplete")
+        return { refusal: null, incomplete: true };
+    const output = asObject(response)?.output;
+    if (Array.isArray(output)) {
+        for (const item of output) {
+            const refusal = asObject(item)?.refusal;
+            if (typeof refusal === "string" && refusal.trim().length > 0)
+                return { refusal: refusal.trim(), incomplete: false };
+            const itemStatus = asObject(item)?.status;
+            if (itemStatus === "incomplete")
+                return { refusal: null, incomplete: true };
+        }
+    }
+    return { refusal: null, incomplete: false };
+}
+export function isChatStrictPrimaryOpMode() {
+    return /^(1|true|yes|on)$/i.test((process.env.CHAT_STRICT_PRIMARY_OP_MODE ?? "").trim());
+}
+export function isPageWideTranslationRequest(message) {
+    const lower = message.toLowerCase();
+    const asksTranslation = /\btranslate\b/.test(lower) ||
+        /\btranslation\b/.test(lower) ||
+        /\blocaliz/.test(lower) ||
+        /\bgerman\b/.test(lower) ||
+        /\bdeutsch\b/.test(lower);
+    if (!asksTranslation)
+        return false;
+    return (/\b(this|the|entire|whole|full)\s+(\w+\s+)*page\b/.test(lower) ||
+        /\bwhole\s+site\b/.test(lower) ||
+        /\ball\s+sections?\b/.test(lower) ||
+        /\btranslate\s+(\w+\s+)*page\b/.test(lower));
+}
+const EDIT_PLAN_SHAPE_HINT = {
+    intent: "edit_plan | needs_clarification",
+    summary_for_user: "string",
+    change_log: ["string"],
+    ops: ["Operation[]"],
+    suggested_next_actions: ["string (optional, 2-4 items)"]
+};
+export function isStrictJsonResponseEnabled() {
+    return /^(1|true|yes|on)$/i.test((process.env.CHAT_STRICT_JSON_RESPONSE ?? "").trim());
+}
+export function isAdaptiveSchemaContextEnabled() {
+    return /^(1|true|yes|on)$/i.test((process.env.CHAT_ADAPTIVE_SCHEMA_CONTEXT ?? "").trim());
+}
+function schemaBudgetBytes() {
+    const parsed = Number(process.env.CHAT_SCHEMA_BUDGET_BYTES ?? "9000");
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return 9000;
+    return Math.max(512, Math.trunc(parsed));
+}
+function bytesForPayload(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf8");
+    }
+    catch {
+        return Number.MAX_SAFE_INTEGER;
+    }
+}
+function uniqueBlockTypes(values) {
+    const known = new Set(allowedBlockTypes.map((type) => type.toLowerCase()));
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        const normalized = value.toLowerCase();
+        if (!known.has(normalized) || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        const canonical = allowedBlockTypes.find((type) => type.toLowerCase() === normalized);
+        if (canonical)
+            out.push(canonical);
+    }
+    return out;
+}
+function pickTargetBlockTypes(args) {
+    const selectedType = typeof args.contextPack.selected.blockType === "string" ? args.contextPack.selected.blockType : null;
+    const inferredFromMessage = inferBlockTypeFromText(args.message);
+    const referencedTypes = [
+        args.contextPack.resolvedReferences.target?.type,
+        args.contextPack.resolvedReferences.anchor?.type,
+        ...args.contextPack.resolvedReferences.mentionedBlocks.map((item) => item.type)
+    ];
+    return uniqueBlockTypes([selectedType, inferredFromMessage, ...referencedTypes]);
+}
+function shouldUseMinimalContracts(message) {
+    const lower = message.toLowerCase();
+    if (/\b(seo|meta|metadata|og\s*image|open\s*graph)\b/.test(lower))
+        return false;
+    if (/\b(translate|translation|localiz)\b/.test(lower))
+        return false;
+    if (/\b(create|add|insert|build|generate|update|change|edit|rewrite|rephrase)\b/.test(lower))
+        return false;
+    return (/\b(remove|delete|move|reorder|rename)\b/.test(lower) ||
+        /\b(remove|delete|move|reorder|rename)\b.*\bpage\b/.test(lower));
+}
+function shouldUseFullContracts(args) {
+    if (args.forceFullContracts)
+        return true;
+    if (args.pageWideTranslation || args.batchOverride)
+        return true;
+    const lower = args.message.toLowerCase();
+    const structuralGeneration = /\b(create|add|insert|build|generate)\b/.test(lower) &&
+        !/\b(page|meta|seo)\b/.test(lower) &&
+        args.targetBlockTypes.length === 0;
+    if (structuralGeneration)
+        return true;
+    return false;
+}
+function buildContractsForMode(args) {
+    const payload = {
+        knownBlockTypes: args.knownBlockTypes,
+        editPlanShape: EDIT_PLAN_SHAPE_HINT
+    };
+    const allContracts = args.allContracts;
+    if (args.mode === "full") {
+        payload.blockContracts = allContracts;
+    }
+    else if (args.mode === "targeted") {
+        const filtered = {};
+        for (const type of args.targetBlockTypes) {
+            if (type in allContracts)
+                filtered[type] = allContracts[type];
+        }
+        if (Object.keys(filtered).length > 0)
+            payload.blockContracts = filtered;
+    }
+    if (args.includePageMetaContract)
+        payload.pageMetaContract = pageMetaContractSummary();
+    return payload;
+}
+export function buildPlannerSchemaContext(args) {
+    const strictJsonEnabled = isStrictJsonResponseEnabled();
+    const targetBlockTypes = pickTargetBlockTypes({ message: args.message, contextPack: args.contextPack });
+    const includePageMetaContract = /\b(seo|meta|metadata|og\s*image|open\s*graph|description|structured\s*data|schema\.org)\b/i.test(args.message) || /\d{2,3}\s*char/i.test(args.message);
+    const knownTypes = args.effectiveBlockTypes
+        ?? (args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : Object.keys(blockSchemas));
+    const allContracts = blockContractsSummary(args.componentsManifest);
+    if (!isAdaptiveSchemaContextEnabled()) {
+        const payload = args.legacyIncludeContracts
+            ? {
+                blockContracts: allContracts,
+                pageMetaContract: pageMetaContractSummary(),
+                knownBlockTypes: knownTypes,
+                editPlanShape: EDIT_PLAN_SHAPE_HINT
+            }
+            : {};
+        const contractBlockCount = payload.blockContracts ? Object.keys(payload.blockContracts).length : 0;
+        return {
+            payload,
+            meta: {
+                contractMode: args.legacyIncludeContracts ? "full" : "minimal",
+                contractBytes: bytesForPayload(payload),
+                contractBlockCount,
+                targetBlockTypes,
+                strictJsonEnabled
+            }
+        };
+    }
+    const forceFullContracts = args.forceFullContracts === true;
+    const preferredMode = shouldUseFullContracts({
+        message: args.message,
+        batchOverride: args.batchOverride,
+        pageWideTranslation: args.pageWideTranslation,
+        forceFullContracts,
+        targetBlockTypes
+    })
+        ? "full"
+        : shouldUseMinimalContracts(args.message)
+            ? "minimal"
+            : "targeted";
+    const fallbackOrder = preferredMode === "full"
+        ? ["full", "targeted", "minimal"]
+        : preferredMode === "targeted"
+            ? ["targeted", "minimal"]
+            : ["minimal"];
+    const budget = schemaBudgetBytes();
+    let selectedMode = fallbackOrder[0];
+    let selectedPayload = buildContractsForMode({
+        mode: selectedMode,
+        targetBlockTypes,
+        includePageMetaContract,
+        allContracts,
+        knownBlockTypes: knownTypes
+    });
+    let selectedBytes = bytesForPayload(selectedPayload);
+    for (const mode of fallbackOrder) {
+        const payload = buildContractsForMode({ mode, targetBlockTypes, includePageMetaContract, allContracts, knownBlockTypes: knownTypes });
+        const bytes = bytesForPayload(payload);
+        selectedMode = mode;
+        selectedPayload = payload;
+        selectedBytes = bytes;
+        if (bytes <= budget)
+            break;
+    }
+    const contractBlockCount = selectedPayload.blockContracts ? Object.keys(selectedPayload.blockContracts).length : 0;
+    return {
+        payload: selectedPayload,
+        meta: {
+            contractMode: selectedMode,
+            contractBytes: selectedBytes,
+            contractBlockCount,
+            targetBlockTypes,
+            strictJsonEnabled
+        }
+    };
+}
+export function openAIChatOptionsForModel(model) {
+    // o-series and gpt-5 family reject temperature in chat.completions; omit to use model default.
+    const lower = model.toLowerCase();
+    if (lower.startsWith("o1") || lower.startsWith("o3") || lower.startsWith("o4") || lower.startsWith("gpt-5"))
+        return {};
+    return { temperature: 0 };
+}
+export function isResponsesOnlyModel(_model) {
+    // No current OpenAI model requires the Responses API exclusively; all supported models
+    // use chat.completions. Update this if a future model mandates the Responses API.
+    return false;
+}
+export function openAiModelSupportsPdfFiles(model) {
+    // chat.completions accepts PDF `file` content parts on the gpt-4o / gpt-4.1 /
+    // gpt-5 families. Other models (o-series reasoning, legacy) reject them and
+    // would fail the planning call — callers drop PDF parts for those.
+    return /gpt-4o|gpt-4\.1|gpt-5/i.test(model);
+}
+export function extractResponsesOutputText(response) {
+    const direct = response?.output_text;
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    const output = response?.output;
+    if (!Array.isArray(output))
+        return "";
+    const chunks = [];
+    for (const item of output) {
+        if (!item || typeof item !== "object")
+            continue;
+        const content = item.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const part of content) {
+            if (!part || typeof part !== "object")
+                continue;
+            if (part.type === "output_text" && typeof part.text === "string")
+                chunks.push(part.text);
+        }
+    }
+    return chunks.join("");
+}
+export function extractSummaryFromPlanBuffer(raw) {
+    // Extract summary_for_user value (may be partial if string is still open)
+    let summary = null;
+    const summaryKey = '"summary_for_user"';
+    const summaryKeyIdx = raw.indexOf(summaryKey);
+    if (summaryKeyIdx >= 0) {
+        const afterKey = raw.indexOf(":", summaryKeyIdx + summaryKey.length);
+        if (afterKey >= 0) {
+            const quoteStart = raw.indexOf('"', afterKey + 1);
+            if (quoteStart >= 0) {
+                // Scan for closing quote respecting escapes
+                let escape = false;
+                let closeIdx = -1;
+                for (let i = quoteStart + 1; i < raw.length; i++) {
+                    const ch = raw[i];
+                    if (escape) {
+                        escape = false;
+                        continue;
+                    }
+                    if (ch === "\\") {
+                        escape = true;
+                        continue;
+                    }
+                    if (ch === '"') {
+                        closeIdx = i;
+                        break;
+                    }
+                }
+                if (closeIdx >= 0) {
+                    // Closed string — use JSON.parse for correct decoding (handles \uXXXX etc.)
+                    try {
+                        summary = JSON.parse(raw.slice(quoteStart, closeIdx + 1));
+                    }
+                    catch {
+                        // Fallback: return raw content without quotes
+                        summary = raw.slice(quoteStart + 1, closeIdx);
+                    }
+                }
+                else {
+                    // Still open (partial/streaming) — manual decode is acceptable
+                    let value = "";
+                    let esc = false;
+                    for (let i = quoteStart + 1; i < raw.length; i++) {
+                        const ch = raw[i];
+                        if (esc) {
+                            if (ch === "n")
+                                value += "\n";
+                            else if (ch === "t")
+                                value += "\t";
+                            else if (ch === "r")
+                                value += "\r";
+                            else
+                                value += ch;
+                            esc = false;
+                            continue;
+                        }
+                        if (ch === "\\") {
+                            esc = true;
+                            continue;
+                        }
+                        value += ch;
+                    }
+                    if (value.length > 0)
+                        summary = value;
+                }
+            }
+        }
+    }
+    // Extract change_log string entries
+    const changeLog = [];
+    const clKey = '"change_log"';
+    const clKeyIdx = raw.indexOf(clKey);
+    if (clKeyIdx >= 0) {
+        const arrStart = raw.indexOf("[", clKeyIdx + clKey.length);
+        if (arrStart >= 0) {
+            let inString = false;
+            let escape = false;
+            let strStart = -1;
+            let depth = 0;
+            for (let i = arrStart; i < raw.length; i++) {
+                const ch = raw[i];
+                if (inString) {
+                    if (escape) {
+                        escape = false;
+                        continue;
+                    }
+                    if (ch === "\\") {
+                        escape = true;
+                        continue;
+                    }
+                    if (ch === '"') {
+                        inString = false;
+                        if (depth === 1 && strStart >= 0) {
+                            try {
+                                const parsed = JSON.parse(raw.slice(strStart, i + 1));
+                                changeLog.push(parsed);
+                            }
+                            catch { /* partial */ }
+                            strStart = -1;
+                        }
+                    }
+                    continue;
+                }
+                if (ch === '"') {
+                    inString = true;
+                    strStart = i;
+                    continue;
+                }
+                if (ch === "[") {
+                    depth++;
+                    continue;
+                }
+                if (ch === "]") {
+                    if (--depth <= 0)
+                        break;
+                    continue;
+                }
+            }
+        }
+    }
+    return { summary, changeLog };
+}
+export function extractOpsFromPlanBuffer(raw, emittedCount) {
+    const opsKeyIdx = raw.indexOf('"ops"');
+    if (opsKeyIdx < 0)
+        return { nextEmittedCount: emittedCount, newOps: [] };
+    const arrStart = raw.indexOf("[", opsKeyIdx);
+    if (arrStart < 0)
+        return { nextEmittedCount: emittedCount, newOps: [] };
+    const extracted = [];
+    let inString = false;
+    let escape = false;
+    let arrDepth = 0;
+    let objDepth = 0;
+    let objStart = -1;
+    for (let i = arrStart; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === "\\") {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "[") {
+            arrDepth += 1;
+            continue;
+        }
+        if (ch === "]") {
+            if (arrDepth > 0)
+                arrDepth -= 1;
+            if (arrDepth === 0)
+                break;
+            continue;
+        }
+        if (arrDepth !== 1)
+            continue;
+        if (ch === "{") {
+            if (objDepth === 0)
+                objStart = i;
+            objDepth += 1;
+            continue;
+        }
+        if (ch === "}") {
+            if (objDepth > 0)
+                objDepth -= 1;
+            if (objDepth === 0 && objStart >= 0) {
+                const json = raw.slice(objStart, i + 1);
+                try {
+                    const parsed = JSON.parse(json);
+                    extracted.push(parsed);
+                }
+                catch {
+                    // Ignore partial/invalid object fragments while streaming.
+                }
+                objStart = -1;
+            }
+        }
+    }
+    if (extracted.length <= emittedCount) {
+        return { nextEmittedCount: emittedCount, newOps: [] };
+    }
+    return {
+        nextEmittedCount: extracted.length,
+        newOps: extracted.slice(emittedCount)
+    };
+}
+function decodeJsonStringFragment(fragment) {
+    let out = "";
+    for (let i = 0; i < fragment.length; i += 1) {
+        const ch = fragment[i];
+        if (ch !== "\\") {
+            out += ch;
+            continue;
+        }
+        const next = fragment[i + 1];
+        if (!next)
+            break;
+        i += 1;
+        if (next === "n")
+            out += "\n";
+        else if (next === "t")
+            out += "\t";
+        else if (next === "r")
+            out += "\r";
+        else if (next === "b")
+            out += "\b";
+        else if (next === "f")
+            out += "\f";
+        else if (next === '"' || next === "\\" || next === "/")
+            out += next;
+        else if (next === "u") {
+            const hex = fragment.slice(i + 1, i + 5);
+            if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+                out += String.fromCharCode(Number.parseInt(hex, 16));
+                i += 4;
+            }
+        }
+        else {
+            out += next;
+        }
+    }
+    return out;
+}
+function parseJsonStringValueFragment(rawValue, closed) {
+    if (closed) {
+        try {
+            return JSON.parse(`"${rawValue}"`);
+        }
+        catch {
+            // Fall through to permissive decoder for malformed edge fragments.
+        }
+    }
+    return decodeJsonStringFragment(rawValue);
+}
+function findFirstObjectLiteral(raw, fromIndex) {
+    let inString = false;
+    let escape = false;
+    let depth = 0;
+    let objStart = -1;
+    for (let i = fromIndex; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (inString) {
+            if (escape)
+                escape = false;
+            else if (ch === "\\")
+                escape = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0)
+                objStart = i;
+            depth += 1;
+            continue;
+        }
+        if (ch === "}") {
+            if (depth > 0)
+                depth -= 1;
+            if (depth === 0 && objStart >= 0) {
+                return { body: raw.slice(objStart + 1, i), closed: true };
+            }
+            continue;
+        }
+    }
+    if (objStart >= 0) {
+        return { body: raw.slice(objStart + 1), closed: false };
+    }
+    return null;
+}
+function extractUpdatePropsDraftsFromPartialOp(raw, opIndex) {
+    // Primary path: lenient-parse the in-flight op and scope it exactly like a
+    // complete op, so nested fields (cards[i].title …) STREAM incrementally as the
+    // model types them instead of bursting all at once when the op's closing brace
+    // lands. flattenPatchToScopedDrafts owns the path scoping (the part that once
+    // drifted), so a lenient mis-parse can only DROP fields — never mis-scope them —
+    // and the strict complete-op extractor corrects everything at op-close.
+    const parsed = parsePartialJson(raw);
+    if (parsed && typeof parsed === "object") {
+        const op = parsed;
+        if (op.op === undefined || op.op === "") {
+            // "op" key not streamed yet: assume update_props unless it looks like an
+            // update_item (listKey/index present), which can't be scoped without the op
+            // type — matching the pre-existing "ignore update_item-like prefix" rule.
+            if (!("listKey" in op) && !("index" in op))
+                op.op = "update_props";
+        }
+        const drafts = scopeOpDrafts(op, opIndex);
+        if (drafts.length > 0)
+            return drafts;
+    }
+    // Fallback: the original depth-0 regex extractor — defensive, for any prefix the
+    // lenient parser can't turn into a usable op (guarantees no regression).
+    return extractDepth0DraftsFromPartialOp(raw, opIndex);
+}
+function extractDepth0DraftsFromPartialOp(raw, opIndex) {
+    let isUpdateItem = false;
+    const opMatch = /"op"\s*:\s*"((?:\\.|[^"\\])*)(?:"|$)/.exec(raw);
+    if (opMatch) {
+        const opClosed = opMatch[0].endsWith('"');
+        const opName = parseJsonStringValueFragment(opMatch[1] ?? "", opClosed).trim();
+        if (opName && opName !== "update_props" && opName !== "update_item")
+            return [];
+        isUpdateItem = opName === "update_item";
+    }
+    else if (/"(?:listKey|index)"\s*:/.test(raw)) {
+        // Ignore update_item-like partial ops before "op" arrives — we can't scope
+        // their fields (or even confirm the op type) until the "op" key lands.
+        return [];
+    }
+    const blockIdMatch = /"blockId"\s*:\s*"((?:\\.|[^"\\])*)(?:"|$)/.exec(raw);
+    if (!blockIdMatch)
+        return [];
+    const blockIdClosed = blockIdMatch[0].endsWith('"');
+    const blockId = parseJsonStringValueFragment(blockIdMatch[1] ?? "", blockIdClosed).trim();
+    if (!blockId)
+        return [];
+    const pageSlugMatch = /"pageSlug"\s*:\s*"((?:\\.|[^"\\])*)"/.exec(raw);
+    const pageSlug = pageSlugMatch
+        ? parseJsonStringValueFragment(pageSlugMatch[1] ?? "", true).trim() || undefined
+        : undefined;
+    const patchKeyIdx = raw.indexOf('"patch"');
+    if (patchKeyIdx < 0)
+        return [];
+    const patchObj = findFirstObjectLiteral(raw, patchKeyIdx);
+    if (!patchObj)
+        return [];
+    // For update_item, scope the streamed patch fields under the addressed list item
+    // (cards[0].title …) so each card field types into its own renderer node. Read
+    // listKey/index from the op HEADER only (before "patch") so a stray "index" key
+    // inside the patch can't be mistaken for the item position. Both must be present
+    // and the index positional — an itemId-only op has no resolvable DOM target.
+    let pathPrefix = "";
+    if (isUpdateItem) {
+        const header = raw.slice(0, patchKeyIdx);
+        const listKeyMatch = /"listKey"\s*:\s*"((?:\\.|[^"\\])*)"/.exec(header);
+        const indexMatch = /"index"\s*:\s*(\d+)/.exec(header);
+        if (!listKeyMatch || !indexMatch)
+            return [];
+        const listKey = parseJsonStringValueFragment(listKeyMatch[1] ?? "", true).trim();
+        if (!listKey)
+            return [];
+        pathPrefix = `${listKey}[${Number(indexMatch[1])}]`;
+    }
+    // Only stream TOP-LEVEL scalar props from the still-incomplete op. For an
+    // update_props op, nested fields (a card's title inside `cards: [...]`) can't be
+    // given their scoped editablePath ("cards[0].title") reliably from truncated
+    // JSON, and the old flat regex emitted them as bare keys — colliding with the
+    // block's own top-level "title" node and misplacing the overlay. The scoped
+    // nested drafts are emitted by the complete-op extractor the moment this op's
+    // closing brace arrives (still mid-stream). An update_item's patch keys ARE the
+    // item's own scalar fields, so prefixing them with `cards[0]` is unambiguous and
+    // they stream progressively, field by field.
+    return extractTopLevelStringDraftsFromBody(patchObj.body, opIndex, blockId, pageSlug, pathPrefix);
+}
+/**
+ * Emit `"key":"value"` drafts only at the top level (depth 0) of a possibly
+ * truncated patch-object body. Anything inside a nested object or array is
+ * skipped — see {@link flattenPatchToScopedDrafts} for how nested list fields get
+ * their scoped paths once the op fully parses.
+ */
+function extractTopLevelStringDraftsFromBody(body, opIndex, blockId, pageSlug, pathPrefix = "") {
+    const base = pageSlug ? { pageSlug } : {};
+    const drafts = [];
+    const n = body.length;
+    let i = 0;
+    let depth = 0;
+    const readString = (start) => {
+        let j = start;
+        let esc = false;
+        while (j < n) {
+            const c = body[j];
+            if (esc)
+                esc = false;
+            else if (c === "\\")
+                esc = true;
+            else if (c === '"')
+                return { raw: body.slice(start, j), end: j, closed: true };
+            j++;
+        }
+        return { raw: body.slice(start, n), end: n, closed: false };
+    };
+    while (i < n) {
+        const ch = body[i];
+        if (ch === "{" || ch === "[") {
+            depth += 1;
+            i += 1;
+            continue;
+        }
+        if (ch === "}" || ch === "]") {
+            depth = Math.max(0, depth - 1);
+            i += 1;
+            continue;
+        }
+        if (ch !== '"') {
+            i += 1;
+            continue;
+        }
+        const key = readString(i + 1);
+        if (depth !== 0) {
+            // Nested string (key or value) — skip it wholesale.
+            if (!key.closed)
+                break;
+            i = key.end + 1;
+            continue;
+        }
+        if (!key.closed)
+            break; // truncated key — no value yet
+        const editablePath = parseJsonStringValueFragment(key.raw, true).trim();
+        i = key.end + 1;
+        while (i < n && /\s/.test(body[i]))
+            i += 1;
+        if (body[i] !== ":")
+            continue;
+        i += 1;
+        while (i < n && /\s/.test(body[i]))
+            i += 1;
+        if (i >= n)
+            break;
+        if (body[i] === '"') {
+            const val = readString(i + 1);
+            const value = parseJsonStringValueFragment(val.raw, val.closed);
+            if (editablePath) {
+                const scopedPath = pathPrefix ? `${pathPrefix}.${editablePath}` : editablePath;
+                drafts.push({ opIndex, blockId, editablePath: scopedPath, value, ...base });
+            }
+            i = val.closed ? val.end + 1 : n;
+        }
+        // Non-string values (objects, arrays, numbers) are left for the main loop to
+        // walk: `{`/`[` bump depth so their contents are skipped here.
+    }
+    return drafts;
+}
+/**
+ * Flatten an update_props patch into field drafts whose `editablePath` matches the
+ * renderer's `data-editable-target` attributes, so the live-draft overlay writes
+ * each value onto the right node:
+ *   - top-level string prop      → bare key            ("title")
+ *   - string field of an         → scoped index path   ("cards[0].title")
+ *     array-of-objects prop        (matches CardGrid/Tabs/Footer renderers)
+ * Plain nested objects (e.g. "meta") and arrays of primitives have no editable
+ * targets and are skipped. Without scoping, every card's bare "title" collapsed
+ * onto the grid's own "title" node and the card translations were misplaced.
+ *
+ * `pathPrefix` scopes the whole patch under an addressed list item — passed as
+ * `cards[0]` for an `update_item` op so its bare `title`/`description` patch keys
+ * become `cards[0].title` etc. (an update_props patch passes "" → unscoped).
+ */
+function flattenPatchToScopedDrafts(patch, opIndex, blockId, pageSlug, pathPrefix = "") {
+    const base = pageSlug ? { pageSlug } : {};
+    const drafts = [];
+    // Walk an object's fields, emitting a draft per string value with a path that
+    // mirrors the renderer's data-editable-target. We descend ARRAYS (and their
+    // element objects, recursively — e.g. site-header links[i].children[j].label),
+    // and arrays of strings keep the bare index form (table headers[i]). We never
+    // descend a plain object value (e.g. "meta"): those carry no editable targets.
+    const emitObject = (obj, prefix) => {
+        for (const [key, value] of Object.entries(obj)) {
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (typeof value === "string") {
+                drafts.push({ opIndex, blockId, editablePath: path, value, ...base });
+            }
+            else if (Array.isArray(value)) {
+                value.forEach((item, idx) => {
+                    const itemPath = `${path}[${idx}]`;
+                    if (typeof item === "string") {
+                        drafts.push({ opIndex, blockId, editablePath: itemPath, value: item, ...base });
+                    }
+                    else if (item && typeof item === "object" && !Array.isArray(item)) {
+                        emitObject(item, itemPath);
+                    }
+                });
+            }
+            // non-string scalars and plain nested objects have no editable target → skip
+        }
+    };
+    emitObject(patch, pathPrefix);
+    return drafts;
+}
+/**
+ * Lenient recursive-descent JSON parser for a TRUNCATED stream prefix.
+ *
+ * Returns the largest valid prefix as a JS value: a trailing in-flight string is
+ * kept as its decoded-so-far value (so the field still streams), while a dangling
+ * key (no colon/value yet) is dropped. Used only on the still-incomplete op so its
+ * nested fields can be scoped via flattenPatchToScopedDrafts as they arrive. It
+ * never throws — worst case it returns less, and the strict complete-op parser
+ * corrects everything the moment the op's closing brace lands.
+ */
+function parsePartialJson(text) {
+    let i = 0;
+    const n = text.length;
+    const skipWs = () => { while (i < n && /\s/.test(text[i]))
+        i += 1; };
+    const parseString = () => {
+        i += 1; // consume opening quote
+        let out = "";
+        while (i < n) {
+            const c = text[i];
+            if (c === "\\") {
+                if (i + 1 >= n) {
+                    i = n;
+                    return { value: out, complete: false };
+                }
+                const esc = text[i + 1];
+                if (esc === "u") {
+                    if (i + 6 > n) {
+                        i = n;
+                        return { value: out, complete: false };
+                    }
+                    const code = parseInt(text.slice(i + 2, i + 6), 16);
+                    if (!Number.isNaN(code))
+                        out += String.fromCharCode(code);
+                    i += 6;
+                    continue;
+                }
+                const map = { '"': '"', "\\": "\\", "/": "/", n: "\n", t: "\t", r: "\r", b: "\b", f: "\f" };
+                out += map[esc] ?? esc;
+                i += 2;
+                continue;
+            }
+            if (c === '"') {
+                i += 1;
+                return { value: out, complete: true };
+            }
+            out += c;
+            i += 1;
+        }
+        return { value: out, complete: false }; // truncated string — keep what we have
+    };
+    const parseValue = () => {
+        skipWs();
+        if (i >= n)
+            return null;
+        const ch = text[i];
+        if (ch === '"')
+            return parseString();
+        if (ch === "{")
+            return parseObject();
+        if (ch === "[")
+            return parseArray();
+        // literal: number / true / false / null
+        const start = i;
+        while (i < n && !/[\s,}\]]/.test(text[i]))
+            i += 1;
+        const token = text.slice(start, i);
+        const atEof = i >= n;
+        if (token === "true")
+            return { value: true, complete: true };
+        if (token === "false")
+            return { value: false, complete: true };
+        if (token === "null")
+            return { value: null, complete: true };
+        if (token.length > 0 && !Number.isNaN(Number(token)))
+            return { value: Number(token), complete: !atEof };
+        return null; // unrecognized garbage
+    };
+    function parseObject() {
+        i += 1; // consume {
+        const obj = {};
+        while (true) {
+            skipWs();
+            if (i >= n)
+                return { value: obj, complete: false };
+            if (text[i] === "}") {
+                i += 1;
+                return { value: obj, complete: true };
+            }
+            if (text[i] === ",") {
+                i += 1;
+                continue;
+            }
+            if (text[i] !== '"')
+                return { value: obj, complete: false }; // unexpected
+            const key = parseString();
+            if (!key.complete)
+                return { value: obj, complete: false }; // dangling key → drop
+            skipWs();
+            if (i >= n || text[i] !== ":")
+                return { value: obj, complete: false }; // key w/o value → drop
+            i += 1; // consume :
+            const val = parseValue();
+            if (val === null)
+                return { value: obj, complete: false }; // value not started → drop key
+            obj[key.value] = val.value;
+            if (!val.complete)
+                return { value: obj, complete: false }; // value truncated → keep, stop
+        }
+    }
+    function parseArray() {
+        i += 1; // consume [
+        const arr = [];
+        while (true) {
+            skipWs();
+            if (i >= n)
+                return { value: arr, complete: false };
+            if (text[i] === "]") {
+                i += 1;
+                return { value: arr, complete: true };
+            }
+            if (text[i] === ",") {
+                i += 1;
+                continue;
+            }
+            const val = parseValue();
+            if (val === null)
+                return { value: arr, complete: false };
+            arr.push(val.value);
+            if (!val.complete)
+                return { value: arr, complete: false };
+        }
+    }
+    const result = parseValue();
+    return result ? result.value : null;
+}
+/**
+ * Scope a parsed update_props / update_item op into field drafts whose paths match
+ * the renderer's data-editable-target. Shared by the complete-op (strict parse) and
+ * partial-op (lenient parse) extractors so both produce identical scoping.
+ *
+ * update_item gets the same scoped treatment as a nested update_props array field:
+ * a single-item edit streamed as `update_item{listKey:"cards",index:0,patch:{…}}`
+ * lights up cards[0].title / cards[0].description. Only a positional `index` maps
+ * to a DOM node — an itemId-only op can't be resolved without the page doc, so it
+ * emits nothing (the final apply still translates it correctly).
+ */
+function scopeOpDrafts(parsed, opIndex) {
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    const op = parsed;
+    if (op.op !== "update_props" && op.op !== "update_item")
+        return [];
+    const blockId = String(op.blockId ?? "").trim();
+    if (!blockId)
+        return [];
+    const patch = op.patch && typeof op.patch === "object" && !Array.isArray(op.patch)
+        ? op.patch
+        : null;
+    if (!patch)
+        return [];
+    const pageSlug = typeof op.pageSlug === "string" && op.pageSlug.trim().length > 0 ? op.pageSlug.trim() : undefined;
+    if (op.op === "update_item") {
+        const listKey = String(op.listKey ?? "").trim();
+        const index = op.index;
+        if (!listKey || typeof index !== "number" || !Number.isInteger(index) || index < 0)
+            return [];
+        return flattenPatchToScopedDrafts(patch, opIndex, blockId, pageSlug, `${listKey}[${index}]`);
+    }
+    return flattenPatchToScopedDrafts(patch, opIndex, blockId, pageSlug);
+}
+function extractUpdatePropsDraftsFromCompleteOp(raw, opIndex) {
+    try {
+        return scopeOpDrafts(JSON.parse(raw), opIndex);
+    }
+    catch {
+        return [];
+    }
+}
+export function extractUpdatePropsFieldDraftsFromPlanBuffer(raw) {
+    const opsKeyIdx = raw.indexOf('"ops"');
+    if (opsKeyIdx < 0)
+        return [];
+    const arrStart = raw.indexOf("[", opsKeyIdx);
+    if (arrStart < 0)
+        return [];
+    const objectSnippets = [];
+    let inString = false;
+    let escape = false;
+    let arrDepth = 0;
+    let objDepth = 0;
+    let objStart = -1;
+    let objectCount = 0;
+    let arrayClosed = false;
+    for (let i = arrStart; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === "\\") {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "[") {
+            arrDepth += 1;
+            continue;
+        }
+        if (ch === "]") {
+            if (arrDepth > 0)
+                arrDepth -= 1;
+            if (arrDepth === 0) {
+                arrayClosed = true;
+                break;
+            }
+            continue;
+        }
+        if (arrDepth !== 1)
+            continue;
+        if (ch === "{") {
+            if (objDepth === 0)
+                objStart = i;
+            objDepth += 1;
+            continue;
+        }
+        if (ch === "}") {
+            if (objDepth > 0)
+                objDepth -= 1;
+            if (objDepth === 0 && objStart >= 0) {
+                objectCount += 1;
+                objectSnippets.push({ opIndex: objectCount, snippet: raw.slice(objStart, i + 1), complete: true });
+                objStart = -1;
+            }
+        }
+    }
+    if (!arrayClosed && arrDepth >= 1 && objDepth > 0 && objStart >= 0) {
+        objectCount += 1;
+        objectSnippets.push({ opIndex: objectCount, snippet: raw.slice(objStart), complete: false });
+    }
+    const drafts = [];
+    for (const entry of objectSnippets) {
+        if (entry.complete) {
+            drafts.push(...extractUpdatePropsDraftsFromCompleteOp(entry.snippet, entry.opIndex));
+        }
+        else {
+            drafts.push(...extractUpdatePropsDraftsFromPartialOp(entry.snippet, entry.opIndex));
+        }
+    }
+    return drafts;
+}
+export async function parseIntentWithOpenAI(args) {
+    const client = args.client ?? getOpenAIClient();
+    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 completion = await client.chat.completions.create({
+        model: args.model,
+        ...openAIChatOptionsForModel(args.model),
+        response_format: {
+            type: "json_schema",
+            json_schema: { name: "IntentResult", schema: intentJsonSchema, strict: true }
+        },
+        messages: [
+            { role: "system", content: system },
+            { role: "user", content: JSON.stringify(user) }
+        ]
+    }, { signal: AbortSignal.timeout(LLM_TIMEOUT_MS) });
+    const raw = completion.choices[0]?.message?.content ?? "";
+    if (!raw.trim())
+        throw new Error("Intent parser did not return JSON");
+    // json_schema strict mode guarantees valid JSON matching our schema
+    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;
+}
+export async function generatePlanWithOpenAI(args) {
+    const client = args.client ?? getOpenAIClient();
+    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) || isDuplicateAndModifyRequest(args.message);
+    const pageWideRewrite = isPageWideRewriteRequest(args.message);
+    const planFirstMode = requestsPlanFirst(args.message);
+    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: "openai",
+        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 lowerMsg = args.message.toLowerCase();
+    const includeContracts = !args.lightweight && (batchOverride ||
+        pageWideTranslation ||
+        /\b(create|add|insert|build|generate)\b/.test(lowerMsg) ||
+        /\b(seo|meta|metadata|og\s*image|open\s*graph|description|structured\s*data|schema\.org)\b/.test(lowerMsg) ||
+        /\d{2,3}\s*char/i.test(args.message) ||
+        // Multi-field updates need block contracts to know valid prop names
+        (lowerMsg.match(/['''"""\u201C\u201D\u2018\u2019]/g)?.length ?? 0) >= 4);
+    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 user = {
+        request: args.message,
+        audienceHint: audienceHint ?? null,
+        slug: args.slug,
+        contextPack: args.contextPack,
+        ...schemaContext.payload,
+        feedback: args.feedback ?? null
+    };
+    const imageUrlForVision = typeof args.contextPack.selected?.imageUrlForVision === "string"
+        ? args.contextPack.selected.imageUrlForVision
+        : null;
+    const imageBase64 = imageUrlForVision ? await fetchImageAsBase64(imageUrlForVision) : null;
+    const visionImageUrl = imageBase64
+        ? `data:${imageBase64.mediaType};base64,${imageBase64.base64}`
+        : imageUrlForVision;
+    // User-attached files: images as image_url parts, PDFs as `file` parts with
+    // inline base64 data. The `file` content part is only accepted by the gpt-4o /
+    // gpt-4.1 / gpt-5 families on chat.completions; sending it to other models
+    // fails the whole call, so we drop PDF parts (images still go through) when
+    // the active model isn't known to support file inputs.
+    const resolvedAttachments = await resolveAttachmentsForLlm(args.contextPack.attachments);
+    const allowPdfFileParts = openAiModelSupportsPdfFiles(args.model);
+    const attachmentParts = resolvedAttachments
+        .filter((attachment) => attachment.kind !== "pdf" || allowPdfFileParts)
+        .map((attachment) => attachment.kind === "pdf"
+        ? { type: "file", file: { filename: attachment.name ?? "document.pdf", file_data: `data:application/pdf;base64,${attachment.base64}` } }
+        : { type: "image_url", image_url: { url: `data:${attachment.mediaType};base64,${attachment.base64}`, detail: "auto" } });
+    const visionParts = visionImageUrl
+        ? [{ type: "image_url", image_url: { url: visionImageUrl, detail: "low" } }]
+        : [];
+    const openaiUserContent = visionParts.length > 0 || attachmentParts.length > 0
+        ? [...visionParts, ...attachmentParts, { type: "text", text: JSON.stringify(user) }]
+        : JSON.stringify(user);
+    let raw = "";
+    let usage = { ...ZERO_USAGE };
+    let streamedOpsCount = 0;
+    let lastSummaryLen = 0;
+    let emittedChangeLogCount = 0;
+    const emittedFieldDraftByKey = new Map();
+    if (isResponsesOnlyModel(args.model)) {
+        const response = await client.responses.create({
+            model: args.model,
+            instructions: system,
+            input: JSON.stringify(user)
+        }, { signal: effectiveSignal });
+        const responsesOutcome = extractResponsesOutcome(response);
+        if (responsesOutcome.refusal) {
+            throw toPlannerError("planner_refusal", `Model refused planning output: ${responsesOutcome.refusal}`);
+        }
+        if (responsesOutcome.incomplete) {
+            throw toPlannerError("incomplete_output", "Model returned incomplete planning output");
+        }
+        raw = extractResponsesOutputText(response);
+        usage = extractUsage(response);
+        if (args.onToken && raw.length > 0)
+            args.onToken(raw);
+    }
+    else if (args.onToken) {
+        const stream = await client.chat.completions.create({
+            model: args.model,
+            ...openAIChatOptionsForModel(args.model),
+            stream: true,
+            response_format: { type: "json_object" },
+            messages: [
+                { role: "system", content: system },
+                ...(args.history ?? []),
+                { role: "user", content: openaiUserContent }
+            ],
+        }, { signal: effectiveSignal });
+        let sawRefusal = false;
+        for await (const chunk of stream) {
+            const deltaRefusal = chunk?.choices?.[0]?.delta?.refusal;
+            if (typeof deltaRefusal === "string" && deltaRefusal.trim().length > 0) {
+                sawRefusal = true;
+                raw += deltaRefusal;
+                continue;
+            }
+            const delta = chunk.choices[0]?.delta?.content;
+            if (typeof delta !== "string" || delta.length === 0)
+                continue;
+            raw += delta;
+            args.onToken(delta);
+            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 } : {}) });
+                }
+            }
+            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;
+            }
+            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);
+                }
+            }
+        }
+        if (sawRefusal) {
+            throw toPlannerError("planner_refusal", `Model refused planning output: ${raw.slice(0, 300)}`);
+        }
+        if (raw.trim().length === 0) {
+            throw toPlannerError("incomplete_output", "Model returned no planning output");
+        }
+        // Streaming doesn't return per-chunk usage; leave as zero
+    }
+    else {
+        const completion = await client.chat.completions.create({
+            model: args.model,
+            ...openAIChatOptionsForModel(args.model),
+            response_format: { type: "json_object" },
+            messages: [
+                { role: "system", content: system },
+                ...(args.history ?? []),
+                { role: "user", content: openaiUserContent }
+            ],
+        }, { signal: effectiveSignal });
+        const refusal = extractCompletionRefusal(completion);
+        if (refusal) {
+            throw toPlannerError("planner_refusal", `Model refused planning output: ${refusal}`);
+        }
+        raw = completion.choices[0]?.message?.content ?? "";
+        if (raw.trim().length === 0) {
+            throw toPlannerError("incomplete_output", "Model returned no planning output");
+        }
+        usage = extractUsage(completion);
+    }
+    const jsonText = extractJsonObject(raw);
+    if (!jsonText) {
+        throw toPlannerError("malformed_output", "Model did not return JSON", true);
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(jsonText);
+    }
+    catch (err) {
+        // Attempt multiple repair strategies before giving up
+        try {
+            const meta = repairAndParseJsonWithMeta(jsonText);
+            parsedJson = meta.parsed;
+            if (meta.strategy !== "none") {
+                console.warn(`[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 };
+}