vidspotai-shared 1.0.68 → 1.0.69-dev.0

package/lib/services/agent/planner/Planner.js

@@ -0,0 +1,591 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Planner = void 0;
+exports.briefNeedsWebResearch = briefNeedsWebResearch;
+const zod_1 = require("zod");
+const videoPlan_schema_1 = require("../../../schemas/videoPlan.schema");
+const llmCallerAnthropic_1 = require("../llmCallerAnthropic");
+const llmCallerRegistry_1 = require("../llmCallerRegistry");
+const modelRouter_1 = require("../modelRouter");
+const personas_1 = require("../personas");
+const modelQualityNotes_1 = require("../modelQualityNotes");
+const promptSections_1 = require("./promptSections");
+const structuralRules_1 = require("./structuralRules");
+const repair_1 = require("./repair");
+const overlaySanity_1 = require("./overlaySanity");
+const costPreflight_1 = require("../costPreflight");
+const validators_1 = require("./validators");
+class Planner {
+    constructor(opts) {
+        this.opts = opts;
+        this.router = opts.router ?? new modelRouter_1.ModelRouter();
+        this.maxRetries = opts.maxRetries ?? 2;
+    }
+    async plan(brief, opts = {}) {
+        const model = this.router.pickFor("planner", {
+            premium: brief.tierBudget === "T3",
+        });
+        const fallbackModel = this.router.fallbackFor("planner");
+        // Resolve research flag. We only use research when the Anthropic caller
+        // is wired AND the brief implies real-world subjects — otherwise the
+        // gateway path (provider-portable) is preferred.
+        const anthropic = (0, llmCallerRegistry_1.getAnthropicCaller)();
+        const wantsResearch = opts.useWebResearch === true ||
+            (opts.useWebResearch !== false && briefNeedsWebResearch(brief));
+        let useResearchCall = wantsResearch &&
+            anthropic !== null &&
+            typeof anthropic.structuredWithTools === "function" &&
+            model.provider === "anthropic";
+        // T3 = premium → enable extended thinking on the Anthropic path. Budget
+        // sized for planner: 4K tokens covers multi-scene reasoning + research
+        // synthesis without bloating cost. We don't enable thinking on T0–T2
+        // because the planner's job there is mostly mechanical scene-spec
+        // emission and thinking would add ~$0.02 per call with no quality lift.
+        const premium = brief.tierBudget === "T3";
+        const thinkingBudget = premium ? 4096 : undefined;
+        let lastErrors;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const messages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null, lastErrors, useResearchCall);
+            let result;
+            try {
+                if (useResearchCall && anthropic?.structuredWithTools) {
+                    // Research path: route through AnthropicLlmCaller so the model
+                    // can invoke `web_search` server-side before emitting the plan.
+                    // - `cachePrompt`: 90% discount on cache hits — every retry within
+                    //   5 minutes pays ~10% of the system + tools tokens.
+                    // - `thinking`: enabled on T3 premium briefs only.
+                    // - Transient Anthropic errors fall through to the gateway path
+                    //   below via the catch — better to ship a non-researched plan
+                    //   than to 500 the whole /plan endpoint on an outage.
+                    try {
+                        result = await anthropic.structuredWithTools({
+                            model,
+                            messages,
+                            schema: videoPlan_schema_1.VideoPlanSchema,
+                            schemaName: "VideoPlan",
+                            temperature: attempt === 0 ? 0.4 : 0.2,
+                            serverTools: [{ type: "web_search", maxUses: 5 }],
+                            maxToolRounds: 6,
+                            cachePrompt: true,
+                            ...(thinkingBudget ? { thinking: { budgetTokens: thinkingBudget } } : {}),
+                        });
+                    }
+                    catch (anthErr) {
+                        if ((0, llmCallerAnthropic_1.isTransientLlmError)(anthErr)) {
+                            // Downgrade: disable research for the rest of this plan call
+                            // so we don't keep retrying the failing Anthropic path on
+                            // subsequent attempts. The plan we produce won't be grounded,
+                            // but it'll exist — and the warning flag tells the UI.
+                            useResearchCall = false;
+                            const fallbackMessages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null, lastErrors, false);
+                            result = await this.opts.llm.structured({
+                                model,
+                                fallbackModel,
+                                messages: fallbackMessages,
+                                schema: videoPlan_schema_1.VideoPlanSchema,
+                                schemaName: "VideoPlan",
+                                temperature: attempt === 0 ? 0.4 : 0.2,
+                            });
+                        }
+                        else {
+                            throw anthErr;
+                        }
+                    }
+                }
+                else {
+                    result = await this.opts.llm.structured({
+                        model,
+                        fallbackModel,
+                        messages,
+                        schema: videoPlan_schema_1.VideoPlanSchema,
+                        schemaName: "VideoPlan",
+                        temperature: attempt === 0 ? 0.4 : 0.2,
+                    });
+                }
+            }
+            catch (e) {
+                // AG-25: the gateway throws on schema-validation failures. Without this
+                // catch the planner's correction-retry loop never fires — a single
+                // sub-1ms scene duration from the LLM would crash the whole agent.
+                // Capture the error as correction context and let the loop retry.
+                const msg = e instanceof Error ? e.message : String(e);
+                if (/schema validation failed|non-JSON|empty response/i.test(msg)) {
+                    lastErrors = `Previous attempt failed validation: ${msg.slice(0, 600)}. Ensure every scene has durationMs > 0, all required fields are populated, and the JSON parses cleanly.`;
+                    continue;
+                }
+                throw e;
+            }
+            // Defense-in-depth: re-validate even though structured() should have.
+            const reparsed = videoPlan_schema_1.VideoPlanSchema.safeParse(result.data);
+            if (reparsed.success) {
+                // AG-9: duration contract. Brief.durationSec is the user's ask; if the
+                // plan under-delivers by >10%, re-prompt with an explicit correction.
+                const durationGap = (0, validators_1.checkDurationContract)(reparsed.data, brief);
+                if (durationGap) {
+                    lastErrors = durationGap;
+                    continue;
+                }
+                // AG-33: last-mile auto-correct — swap a known-bad preferredModel for
+                // a known-good one BEFORE we even run the validator. The planner
+                // sometimes can't break out of picking the same wrong model across
+                // retries (Test 1 picked runway-gen4-turbo for 2s scenes 3 times in
+                // a row). The retry loop still runs for genuinely ambiguous cases,
+                // but mechanical fixes (model X doesn't do duration Y → swap to model Z
+                // that does) shouldn't burn LLM cycles.
+                (0, repair_1.autoCorrectPreferredModels)(reparsed.data);
+                // AG-15: per-scene duration must be accepted by the picked model.
+                const capabilityGap = (0, validators_1.checkSceneDurationCapability)(reparsed.data);
+                if (capabilityGap) {
+                    lastErrors = capabilityGap;
+                    continue;
+                }
+                // AG-28: per-scene VO must fit inside scene.durationMs (at default
+                // TTS speed). Without this the voiceover gets clipped mid-sentence
+                // when the stitcher renders. Test 1 had every line 1-1.8s over.
+                //
+                // Downgrade-on-last-attempt: if we've already burned every retry and
+                // the planner still can't produce a fit, ship the plan with a
+                // warning rather than throwing. The executor will still try the 1.15×
+                // speedup at render-time, and the UI surfaces the warning so the
+                // user can extend duration / shorten line / accept clipping.
+                const ttsGap = (0, validators_1.checkSceneTtsBudget)(reparsed.data);
+                if (ttsGap && attempt < this.maxRetries) {
+                    lastErrors = ttsGap;
+                    continue;
+                }
+                // Captions contract: faceless-yt and any brief that mentions captions
+                // MUST ship with at least one overlay per scene (either overlays[] or
+                // legacy onScreenText). Test 3 shipped 15 scenes with no captions
+                // despite the brief explicitly asking for "burned-in captions" — the
+                // planner happily emitted overlays:[] across the board.
+                const captionsGap = (0, validators_1.checkCaptionsContract)(reparsed.data, brief);
+                if (captionsGap) {
+                    lastErrors = captionsGap;
+                    continue;
+                }
+                // Overlay-content sanity: the planner sometimes copies the prompt's
+                // styling description verbatim into overlay.text (e.g. "Bold white
+                // sans-serif subtitle text in the lower third"). That string then
+                // gets burned onto the screen instead of the actual headline. Reject
+                // any overlay whose text reads like a typography/layout directive.
+                const overlaySanityGap = (0, overlaySanity_1.checkOverlayContentSanity)(reparsed.data);
+                if (overlaySanityGap) {
+                    lastErrors = overlaySanityGap;
+                    continue;
+                }
+                // Narration-density contract: for medium/slow pacing on a
+                // narration-driven plan (>50% of scenes carry a voiceoverLine),
+                // each scene must be >= 3500ms. Without this the planner happily
+                // ships 15 telegraphic 2-second scenes for a 30s "calm informational"
+                // brief, which reads like a TikTok listicle instead of an explainer.
+                const narrationGap = (0, validators_1.checkNarrationDensityContract)(reparsed.data, brief);
+                if (narrationGap) {
+                    lastErrors = narrationGap;
+                    continue;
+                }
+                // Persist the bible on the plan so downstream (executor / AG-13)
+                // has it without a second read. Planner doesn't author the bible.
+                if (opts.bible)
+                    reparsed.data.bible = opts.bible;
+                // AG-31: voice style flows brief → plan. Don't trust the LLM to
+                // copy it through faithfully; overlay deterministically here.
+                if (brief.voice?.style && !reparsed.data.voiceStyle) {
+                    reparsed.data.voiceStyle = brief.voice.style;
+                }
+                // AG-37 (rev 2): never trust planner-emitted voiceId — even with an
+                // explicit "ORCHESTRATOR-ONLY" docstring + system-prompt forbid line,
+                // GPT/Gemini occasionally invent a descriptive label like
+                // "female-young-adult-excited". That triggers the executor's strip-and-
+                // warn on every regen of the same trace, so kill it here once.
+                reparsed.data.voiceId = brief.voice?.voiceId;
+                // Soft-validation pass: vo-clip (if we downgraded after maxRetries)
+                // + trailing-silence. These ship with the plan; the UI surfaces them.
+                reparsed.data.warnings = (0, validators_1.collectPlanWarnings)(reparsed.data);
+                // Stamp credit estimates from estimateSceneCredits / estimatePlanCost
+                // so the storyboard chip + budget guard see real numbers. The LLM
+                // routinely emits estimatedCredits=0 for T0 scenes and a fabricated
+                // totalEstimatedCredits (observed: 0.72 cr for a 13-scene mixed plan
+                // that actually costs ~18 cr), which rounds to "1 cr" in the UI.
+                for (const s of reparsed.data.scenes) {
+                    s.estimatedCredits = (0, costPreflight_1.estimateSceneCredits)(s);
+                }
+                reparsed.data.totalEstimatedCredits = (0, costPreflight_1.estimatePlanCost)(reparsed.data).totalCredits;
+                // Stamp billing-meta so /execute can charge for the right overhead
+                // bundle (web_search / extended-thinking). bibleBuilt is filled in by
+                // plan.controller after this returns — it knows cache-hit vs fresh.
+                reparsed.data.meta = {
+                    ...(reparsed.data.meta ?? {}),
+                    usedWebResearch: useResearchCall,
+                    usedThinking: !!thinkingBudget,
+                };
+                return reparsed.data;
+            }
+            lastErrors = reparsed.error.issues
+                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                .join("; ");
+        }
+        throw new Error(`Planner failed to produce a valid VideoPlan after ${this.maxRetries + 1} attempts. Last errors: ${lastErrors}`);
+    }
+    /**
+     * Streaming variant of `plan()`. Yields raw token chunks from the model so
+     * the host (SSE endpoint) can forward them to the drawer for token-by-token
+     * rendering, then resolves to the validated VideoPlan once the structured
+     * payload is complete. Falls back to a single-shot call (one chunk = full
+     * text) when the LLM caller doesn't implement `structuredStream`.
+     *
+     * Retries are NOT streamed: only the first attempt is exposed to the UI;
+     * if validation fails we re-call `plan()` (non-streaming) and emit the
+     * final retry as a single chunk. Streaming retries would confuse callers
+     * who already painted partial JSON for the first attempt.
+     */
+    planStream(brief, opts = {}) {
+        const model = this.router.pickFor("planner", {
+            premium: brief.tierBudget === "T3",
+        });
+        const messages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, opts.bible ?? null);
+        if (!this.opts.llm.structuredStream) {
+            // Fallback path — emit the whole plan as one chunk after non-streaming call.
+            const result = this.plan(brief, opts);
+            const tokens = {
+                async *[Symbol.asyncIterator]() {
+                    const plan = await result;
+                    yield JSON.stringify(plan);
+                },
+            };
+            return { tokens, result };
+        }
+        const stream = this.opts.llm.structuredStream({
+            model,
+            fallbackModel: this.router.fallbackFor("planner"),
+            messages,
+            schema: videoPlan_schema_1.VideoPlanSchema,
+            schemaName: "VideoPlan",
+            temperature: 0.4,
+        });
+        const planner = this;
+        const result = (async () => {
+            try {
+                const r = await stream.result;
+                const reparsed = videoPlan_schema_1.VideoPlanSchema.safeParse(r.data);
+                if (reparsed.success) {
+                    // Stream path skipped the validators loop; still attach soft warnings.
+                    reparsed.data.warnings = (0, validators_1.collectPlanWarnings)(reparsed.data);
+                    return reparsed.data;
+                }
+                // Validation tripped on a streamed payload — fall back to retry pass.
+                return planner.plan(brief, opts);
+            }
+            catch {
+                return planner.plan(brief, opts);
+            }
+        })();
+        return { tokens: stream.tokens, result };
+    }
+    /**
+     * Stage 6 slice 4 — focused overlay regeneration for a single scene. The
+     * full `plan()` path is too expensive (and too lossy) for "I just want
+     * different headline / CTA copy on scene 3": it would re-validate every
+     * structural rule (duration / pacing / model capability / VO budget /
+     * narration density) against the unchanged scenes, then re-emit the
+     * whole plan — burning planner tokens and risking drift on fields the
+     * caller didn't ask to change.
+     *
+     * Instead we run a small structured-output call that ONLY emits
+     * `{ overlays: TextOverlay[] }` for one scene, keeping the prompt tight
+     * (just the scene context + the overlay-content rules + a free-form
+     * `instruction`) and the validator surface tiny (TextOverlaySchema +
+     * the style-leak sanity check). Caller is responsible for splicing the
+     * returned overlays into projectJson — this method is pure, no I/O
+     * beyond the LLM call.
+     */
+    async regenerateOverlaysForScene(scene, brief, opts = {}) {
+        const model = this.router.pickFor("planner", {
+            premium: brief.tierBudget === "T3",
+        });
+        const fallbackModel = this.router.fallbackFor("planner");
+        const FocusedOverlaySchema = zod_1.z.object({
+            overlays: zod_1.z.array(videoPlan_schema_1.TextOverlaySchema).max(4),
+        });
+        const personaPack = opts.persona ? personas_1.PERSONA_PACKS[opts.persona] : null;
+        const brandKitSection = (0, promptSections_1.buildBrandKitSection)(opts.brandKit ?? null);
+        const bibleSection = (0, promptSections_1.buildBibleSection)(opts.bible ?? null);
+        const closingHint = opts.isClosingScene
+            ? "  - This IS the CLOSING scene — you MUST include role='cta' (max 5 words, brand + verb, e.g. 'Get HydraPure Today')."
+            : "  - This is NOT the closing scene — do NOT emit role='cta' (CTA belongs only on the final scene).";
+        const watermarkHint = scene.sceneIndex === 0
+            ? "  - This IS scene 0 — you MAY include exactly one role='watermark' overlay with persistAcrossScenes:true (max 2 words, brand name)."
+            : "  - This is NOT scene 0 — do NOT emit role='watermark' (watermark is emitted once on scene 0 and auto-carries forward).";
+        const overlayContract = [
+            "Emit ONLY this scene's overlays (array of TextOverlay, max 4 entries).",
+            "Each overlay = { text, role, position?, persistAcrossScenes?, emphasis?, animation?, startMs?, endMs? }.",
+            "CRITICAL: `text` is the LITERAL on-screen copy users will read — NOT a description of how it should look. Styling (font, color, position, drop-shadow) is applied automatically from the role.",
+            "  GOOD: text:\"Your eyes lie to you\"",
+            "  BAD:  text:\"Bold white sans-serif subtitle in the lower third of a 9:16 frame\"  (REJECTED as styling description)",
+            "Roles + word limits:",
+            "  headline    — top, big-bold, max 6 words (the hook).",
+            "  subheadline — lower-third, medium, max 8 words.",
+            "  body        — lower-third, small, max 14 words (a supporting line of actual copy).",
+            "  cta         — bottom pill, bold, max 5 words, MUST combine brand + verb.",
+            "  watermark   — bottom-right tiny, max 2 words, just the brand name.",
+            "  disclaimer  — tiny bottom legal copy.",
+            "  label       — in-frame object/person label, max 3 words.",
+            "Max 4 overlays per scene. Don't emit two headlines on the same scene.",
+            "Emojis are OK — the renderer supports color glyphs natively.",
+            closingHint,
+            watermarkHint,
+        ].join("\n");
+        const personaLine = personaPack
+            ? `Persona: ${opts.persona} — ${personaPack.plannerPrompt.split("\n")[0]}`
+            : "";
+        const system = [
+            "You are a video-overlay copywriter.",
+            "Given ONE scene from a VideoPlan, emit a fresh `overlays[]` for that scene.",
+            "The rest of the plan (other scenes, VO, visuals, music) is fixed — do not comment on it, do not return it.",
+            "",
+            overlayContract,
+            personaLine,
+            brandKitSection,
+            bibleSection,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const sceneContext = {
+            sceneIndex: scene.sceneIndex,
+            intent: scene.intent,
+            prompt: scene.prompt,
+            voiceoverLine: scene.voiceoverLine,
+            onScreenText: scene.onScreenText,
+            durationMs: scene.durationMs,
+            currentOverlays: scene.overlays ?? [],
+        };
+        const userParts = [
+            `Brief context:\n${JSON.stringify({
+                rawPrompt: brief.rawPrompt,
+                tone: brief.tone,
+                niche: brief.niche,
+            }, null, 2)}`,
+            `Scene:\n${JSON.stringify(sceneContext, null, 2)}`,
+        ];
+        if (opts.instruction?.trim()) {
+            userParts.push(`Caller instruction: ${opts.instruction.trim()}`);
+        }
+        else {
+            userParts.push("No specific instruction — produce a fresh, on-brand overlay set that fits the scene's intent and voiceoverLine.");
+        }
+        const user = userParts.join("\n\n");
+        let lastErrors;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const messages = [
+                { role: "system", content: system },
+                {
+                    role: "user",
+                    content: lastErrors
+                        ? `${user}\n\nPrevious attempt failed validation: ${lastErrors}\nFix and try again.`
+                        : user,
+                },
+            ];
+            try {
+                const result = await this.opts.llm.structured({
+                    model,
+                    fallbackModel,
+                    messages,
+                    schema: FocusedOverlaySchema,
+                    schemaName: "SceneOverlays",
+                    temperature: attempt === 0 ? 0.6 : 0.3,
+                });
+                const overlays = result.data.overlays;
+                // Re-use the same style-leak validator the full-plan path uses by
+                // wrapping the overlays in a single-scene VideoPlan-shaped object.
+                // Cheaper than re-implementing the regex set here.
+                const probe = {
+                    scenes: [{ ...scene, overlays }],
+                };
+                const leak = (0, overlaySanity_1.checkOverlayContentSanity)(probe);
+                if (leak) {
+                    lastErrors = leak;
+                    continue;
+                }
+                return overlays;
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (/schema validation failed|non-JSON|empty response/i.test(msg)) {
+                    lastErrors = `Previous attempt failed validation: ${msg.slice(0, 400)}.`;
+                    continue;
+                }
+                throw e;
+            }
+        }
+        throw new Error(`Planner failed to produce valid overlays for scene ${scene.sceneIndex} after ${this.maxRetries + 1} attempts. Last errors: ${lastErrors}`);
+    }
+    buildMessages(brief, persona, brandKit, styleMemory, bible, lastErrors, useResearchCall = false) {
+        const structuralRulesSection = (0, structuralRules_1.buildStructuralRulesSection)(brief);
+        const personaSection = persona
+            ? [
+                "",
+                `Selected persona: ${persona}.`,
+                `Set plan.persona to "${persona}" in the output.`,
+                "Persona-specific structural rules (apply on top of the global tier rules):",
+                personas_1.PERSONA_PACKS[persona].plannerPrompt,
+            ].join("\n")
+            : "";
+        const brandKitSection = (0, promptSections_1.buildBrandKitSection)(brandKit);
+        const styleMemorySection = (0, promptSections_1.buildStyleMemorySection)(styleMemory);
+        const bibleSection = (0, promptSections_1.buildBibleSection)(bible);
+        const modelCatalogSection = (0, promptSections_1.buildModelCatalogSection)();
+        const videoStrategySection = (0, promptSections_1.buildVideoStrategySection)(brief.videoStrategy);
+        // AG-39: warn the planner away from models with known capability gaps for
+        // dimensions this brief signals it cares about (brand text on product
+        // labels is the immediate driver). Empty string when nothing rated.
+        const modelQualitySection = (0, modelQualityNotes_1.renderModelQualityHintsForSystemPrompt)({
+            needsBrandText: (0, promptSections_1.briefMentionsBrandText)(brief),
+            needsCharacterContinuity: persona === "ugc-ad" || persona === "talking-head",
+            needsFastMotion: brief.tone?.toLowerCase()?.includes("energetic") || brief.tone?.toLowerCase()?.includes("action"),
+            needsCinematic: brief.tone?.toLowerCase()?.includes("cinematic"),
+        });
+        const researchSection = useResearchCall
+            ? [
+                "",
+                "RESEARCH MODE — `web_search` is enabled. The brief mentions real-world",
+                "subjects (products, companies, people, places, events, or statistics).",
+                "Before planning, run targeted `web_search` calls (max 5) to ground the",
+                "plan in real facts: real product names, real feature lists, real logos,",
+                "real statistics, real quotes. Use the results to populate scene prompts,",
+                "voiceover lines, and overlay copy — NEVER fabricate company names,",
+                "product specs, or numbers. Cite findings implicitly via accurate copy;",
+                "do not embed raw URLs in the plan. When done researching, call the",
+                "`submit_VideoPlan` tool with the final plan.",
+                "",
+            ].join("\n")
+            : "";
+        const system = [
+            "You are a video-production planner.",
+            "Given a VideoBrief, produce a VideoPlan: an ordered list of scenes",
+            "with per-scene asset strategy, tier, prompt, duration, and voiceover.",
+            researchSection,
+            "",
+            "Tier rules — respect brief.tierBudget as the maximum tier:",
+            "  T0: stock footage / image with Ken-Burns motion.",
+            "  T1: AI-generated still + camera motion.",
+            "  T2: AI image-to-video on key frames only.",
+            "  T3: full text-to-video (most expensive — use sparingly).",
+            "",
+            "Stock strategy bias — when budget is T0 and the scene depicts something",
+            "with natural motion (skies, light, water, traffic, hands at work,",
+            "animals, machinery, weather, crowds), prefer strategy='stock-video' over",
+            "'stock-image-ken-burns'. Static images with synthesized zoom feel like",
+            "a slideshow when chained for >3 cuts; real stock clips give the same",
+            "T0 cost with genuine motion. Only fall back to stock-image-ken-burns",
+            "when the subject is inherently still (diagrams, infographics, single",
+            "objects on a table, frozen moments) OR when the brief explicitly asks",
+            "for a poster/title-card feel.",
+            "",
+            videoStrategySection,
+            "",
+            "talking-head-avatar is wired and runs the kling-avatar pipeline (face",
+            "still + TTS lipsync). Pick it ONLY when the brand kit exposes a",
+            "presenterFaceUrl — set scene.avatarFaceUrl to that URL on every avatar",
+            "scene. If no presenter face is available, fall back to ai-image-to-video",
+            "or stock-video of a presenter instead.",
+            "",
+            "user-asset is wired and reuses the requesting user's existing library",
+            "(their previously generated images / videos / audio) instead of spending",
+            "credits to make a new asset. Pick user-asset when the brief mentions a",
+            "recurring brand subject (their product photo, spokesperson, b-roll) —",
+            "the executor falls back to stock-video if no library match scores high",
+            "enough, so picking it is safe.",
+            "",
+            "Keep total estimated credits as low as possible while honoring the",
+            "brief. Mix tiers within a single video where it helps cost without",
+            "harming quality (e.g. T2 hero shot + T0 b-roll between).",
+            "",
+            "Smart model routing — set preferredModel per scene from the catalog:",
+            "  - Hero / opening-hook / product-reveal scenes: pick the highest-",
+            "    quality model in the chosen tier (most expensive in that tier).",
+            "  - B-roll / filler / transition scenes: pick the cheapest model in",
+            "    the chosen tier — the audience won't notice the difference and",
+            "    cost drops 3–5x.",
+            "  - When in doubt for a non-hero scene, pick the median-cost model.",
+            "  - preferredModel must match a key from the catalog below; the",
+            "    executor will swap on rate-limit, so picking is best-effort, not",
+            "    a hard contract.",
+            modelCatalogSection,
+            modelQualitySection,
+            // AG-14 fix: persona section moved above structuralRulesSection and
+            // bibleSection. The bible block has multiple "MUST" rules that were
+            // crowding out persona.hookStyle when persona was the last item before
+            // brandKit; on `seed-ugc-skincare` this regressed hookStrength to 0.4
+            // (planner picked a generic "Wait…" opener instead of the brief's
+            // problem-statement hook). Order is now: persona (voice + hookStyle) →
+            // structural rules → bible (entity verbatim re-statement).
+            personaSection,
+            structuralRulesSection,
+            bibleSection,
+            brandKitSection,
+            styleMemorySection,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const user = [
+            `Brief:\n${JSON.stringify(brief, null, 2)}`,
+            lastErrors
+                ? `\nYour previous attempt failed validation: ${lastErrors}\nFix the structure and try again.`
+                : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ];
+    }
+}
+exports.Planner = Planner;
+/**
+ * Heuristic — does the brief mention real-world entities that benefit from
+ * web grounding? A planner without research will happily invent fake app
+ * names, fabricate statistics, and miss real-world brand details. Triggers
+ * when the brief contains:
+ *   - explicit "top N / best / popular / list of" framings
+ *   - proper-noun-heavy briefs (≥2 capitalized non-sentence-start words)
+ *   - listicle/comparison/news/review keywords
+ *   - explicit time markers ("2026", "latest", "this year", "recent")
+ *   - statistics signals ("statistics", "data", "percent", "study")
+ *
+ * Deliberately conservative — false negatives are fine (we just skip the
+ * search), false positives waste $0.01 per planner call. Override via
+ * `useWebResearch: true|false` when the caller knows better.
+ */
+function briefNeedsWebResearch(brief) {
+    const text = [
+        brief.rawPrompt ?? "",
+        brief.tone ?? "",
+        brief.niche ?? "",
+    ]
+        .filter(Boolean)
+        .join(" ");
+    if (!text.trim())
+        return false;
+    const lower = text.toLowerCase();
+    const listicleSignals = /\b(top\s+\d+|best\s+\d*\s*\w+|popular|list\s+of|review|comparison|vs\.?|versus|trending|latest|recent|news|breaking|study|statistics?|data|percent|%|million|billion|industry|market|report)\b/;
+    if (listicleSignals.test(lower))
+        return true;
+    const yearMarker = /\b(20\d{2}|this\s+year|last\s+year)\b/;
+    if (yearMarker.test(lower))
+        return true;
+    // Count proper nouns that aren't sentence-starters — heuristic for
+    // "specific brands / people / places".
+    const words = text.split(/\s+/);
+    let properNouns = 0;
+    for (let i = 0; i < words.length; i++) {
+        const w = words[i] ?? "";
+        const prev = i > 0 ? words[i - 1] ?? "" : "";
+        const isSentenceStart = i === 0 || /[.!?]$/.test(prev);
+        if (!isSentenceStart && /^[A-Z][a-zA-Z0-9]{2,}/.test(w)) {
+            properNouns++;
+            if (properNouns >= 2)
+                return true;
+        }
+    }
+    return false;
+}

package/lib/services/agent/planner/overlaySanity.d.ts

@@ -0,0 +1,7 @@
+import { VideoPlan } from "../../../schemas/videoPlan.schema";
+export declare function isStyleLeakText(text: string): {
+    leak: boolean;
+    reasons: string[];
+};
+export declare function checkOverlayContentSanity(plan: VideoPlan): string | null;
+//# sourceMappingURL=overlaySanity.d.ts.map

package/lib/services/agent/planner/overlaySanity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlaySanity.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/overlaySanity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAuB9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBlF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAmDxE"}