vidspotai-shared 1.0.82-dev.0 → 1.0.83

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

@@ -0,0 +1,38 @@
+import { AgentPersona } from "../../../schemas/agentPersona.schema";
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { AgentVisualBible, PlannedScene, TextOverlay } from "../../../schemas/videoPlan.schema";
+import { IBrandKitModel } from "../../../models/agent.model";
+import { LlmCaller } from "../llmCaller";
+import { ModelRouter } from "../modelRouter";
+/** Bound Planner helpers needed to regenerate a single scene's overlays. */
+export interface OverlayRegenDeps {
+    llm: LlmCaller;
+    router: ModelRouter;
+    maxRetries: number;
+}
+/**
+ * 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 is pure, no I/O beyond the
+ * LLM call.
+ */
+export declare function regenerateOverlaysForScene(deps: OverlayRegenDeps, scene: PlannedScene, brief: VideoBrief, opts?: {
+    persona?: AgentPersona;
+    brandKit?: IBrandKitModel | null;
+    bible?: AgentVisualBible | null;
+    isClosingScene?: boolean;
+    /** Free-form caller hint, e.g. "punchier CTA" or "drop the watermark". */
+    instruction?: string;
+}): Promise<TextOverlay[]>;
+//# sourceMappingURL=overlayRegen.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlayRegen.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/overlayRegen.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAGZ,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAK7C,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IACJ,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,OAAO,CAAC,WAAW,EAAE,CAAC,CAwIxB"}

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

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regenerateOverlaysForScene = regenerateOverlaysForScene;
+const zod_1 = require("zod");
+const videoPlan_schema_1 = require("../../../schemas/videoPlan.schema");
+const personas_1 = require("../personas");
+const promptSections_1 = require("./promptSections");
+const overlaySanity_1 = require("./overlaySanity");
+/**
+ * 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 is pure, no I/O beyond the
+ * LLM call.
+ */
+async function regenerateOverlaysForScene(deps, scene, brief, opts = {}) {
+    const model = deps.router.pickFor("planner", {
+        premium: brief.tierBudget === "T3",
+    });
+    const fallbackModel = deps.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 <= deps.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 deps.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 ${deps.maxRetries + 1} attempts. Last errors: ${lastErrors}`);
+}

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

@@ -0,0 +1,34 @@
+import { AgentPersona } from "../../../schemas/agentPersona.schema";
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { AgentVisualBible } from "../../../schemas/videoPlan.schema";
+import { IBrandKitModel, IStyleMemoryModel } from "../../../models/agent.model";
+/**
+ * Planner prompt assembly + the web-research heuristic. Pure functions (no LLM
+ * call, no class state) so the Planner class stays focused on the
+ * call/validate/retry loop. buildPlannerMessages is shared by plan() and
+ * planStream().
+ */
+export declare function buildPlannerMessages(brief: VideoBrief, persona: AgentPersona | undefined, brandKit: IBrandKitModel | null, styleMemory: IStyleMemoryModel | null, bible: AgentVisualBible | null, lastErrors?: string, useResearchCall?: boolean): ({
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string;
+})[];
+/**
+ * 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.
+ */
+export declare function briefNeedsWebResearch(brief: VideoBrief): boolean;
+//# sourceMappingURL=plannerMessages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plannerMessages.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/plannerMessages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAchF;;;;;GAKG;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,YAAY,GAAG,SAAS,EACjC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,WAAW,EAAE,iBAAiB,GAAG,IAAI,EACrC,KAAK,EAAE,gBAAgB,GAAG,IAAI,EAC9B,UAAU,CAAC,EAAE,MAAM,EACnB,eAAe,UAAQ;;;;;;KAmIxB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAiChE"}

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

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPlannerMessages = buildPlannerMessages;
+exports.briefNeedsWebResearch = briefNeedsWebResearch;
+const personas_1 = require("../personas");
+const modelQualityNotes_1 = require("../modelQualityNotes");
+const promptSections_1 = require("./promptSections");
+const structuralRules_1 = require("./structuralRules");
+/**
+ * Planner prompt assembly + the web-research heuristic. Pure functions (no LLM
+ * call, no class state) so the Planner class stays focused on the
+ * call/validate/retry loop. buildPlannerMessages is shared by plan() and
+ * planStream().
+ */
+function buildPlannerMessages(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 preferredModelsSection = (0, promptSections_1.buildPreferredModelsSection)(brief.preferredModelKeys);
+    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,
+        preferredModelsSection,
+        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 },
+    ];
+}
+/**
+ * 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/promptSections.d.ts

@@ -12,6 +12,18 @@ export declare function briefMentionsBrandText(brief: VideoBrief): boolean;
  */
 export declare function buildVideoStrategySection(strategy: "direct" | "indirect" | "auto" | undefined): string;
 export declare function buildModelCatalogSection(): string;
+/**
+ * Render the user's soft model preference (`brief.preferredModelKeys`, fed by
+ * the composer's "@Models" mention category) into a planner-readable rule.
+ *
+ * Each key is annotated with its REAL modality from the catalog so the planner
+ * can tell a video model from an image-generation-only one. The instruction
+ * makes the preference advisory: favor a preferred model when it can produce
+ * the scene, and gracefully fall back (same provider first) when it can't —
+ * which is exactly the "user @-mentioned an image-gen model for a video"
+ * false-request case. Returns "" when the user expressed no preference.
+ */
+export declare function buildPreferredModelsSection(preferredModelKeys: string[] | undefined): string;
 export declare function buildBrandKitSection(brandKit: IBrandKitModel | null): string;
 /**
  * AG-12 — render the Visual Bible into the planner system prompt. When a

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

@@ -1 +1 @@
-{"version":3,"file":"promptSections.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/promptSections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAQhF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GACnD,MAAM,CAkCR;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAWjD;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAgC5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM,CAsBhF"}
+{"version":3,"file":"promptSections.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/promptSections.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAShF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAGjE;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GACnD,MAAM,CAkCR;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAWjD;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,kBAAkB,EAAE,MAAM,EAAE,GAAG,SAAS,GACvC,MAAM,CAmCR;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAgC5E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,MAAM,CAqCxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM,CAsBhF"}

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

@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.briefMentionsBrandText = briefMentionsBrandText;
 exports.buildVideoStrategySection = buildVideoStrategySection;
 exports.buildModelCatalogSection = buildModelCatalogSection;
+exports.buildPreferredModelsSection = buildPreferredModelsSection;
 exports.buildBrandKitSection = buildBrandKitSection;
 exports.buildBibleSection = buildBibleSection;
 exports.buildStyleMemorySection = buildStyleMemorySection;
 const tierHelpers_1 = require("../../../globals/aiModels/tierHelpers");
+const aiModels_1 = require("../../../globals/aiModels");
 // AG-39: heuristic — does the brief signal that the planner should care
 // about on-screen brand text (so scenes get steered away from models
 // known to mangle text)? Looks at brief.brandName, brief.productName,
@@ -73,6 +75,61 @@ function buildModelCatalogSection() {
         sections.push("", "Image-to-video models by tier (cheapest first):", i2v);
     return sections.join("\n");
 }
+const VIDEO_MODALITIES = new Set([
+    "text-to-video",
+    "image-to-video",
+    "video-to-video",
+    "audio-to-video",
+    "avatar-video",
+    "motion-control",
+    "lip-sync",
+]);
+/**
+ * Render the user's soft model preference (`brief.preferredModelKeys`, fed by
+ * the composer's "@Models" mention category) into a planner-readable rule.
+ *
+ * Each key is annotated with its REAL modality from the catalog so the planner
+ * can tell a video model from an image-generation-only one. The instruction
+ * makes the preference advisory: favor a preferred model when it can produce
+ * the scene, and gracefully fall back (same provider first) when it can't —
+ * which is exactly the "user @-mentioned an image-gen model for a video"
+ * false-request case. Returns "" when the user expressed no preference.
+ */
+function buildPreferredModelsSection(preferredModelKeys) {
+    if (!preferredModelKeys || preferredModelKeys.length === 0)
+        return "";
+    const lines = preferredModelKeys.map((key) => {
+        const config = aiModels_1.aiModelConfigs[key];
+        if (!config) {
+            return `  - ${key} (unknown model — ignore unless it matches a catalog key)`;
+        }
+        const modality = config.type.join(", ");
+        const videoCapable = config.type.some((t) => VIDEO_MODALITIES.has(t));
+        const note = videoCapable
+            ? ""
+            : "  ← image-generation only, cannot produce a video scene";
+        return `  - ${key} (modality: ${modality})${note}`;
+    });
+    return [
+        "",
+        "User model preference (SOFT hint — NOT a hard constraint):",
+        "The user @-mentioned the following generation model(s), strongest first:",
+        ...lines,
+        "Apply this preference as follows:",
+        "  - For each AI video scene, if a preferred model's modality supports the",
+        "    scene's strategy (text-to-video → ai-text-to-video; image-to-video →",
+        "    ai-image-to-video), set scene.preferredModel to it — favor the",
+        "    earliest-listed compatible one.",
+        "  - If NONE of the preferred models can produce a given scene (e.g. the",
+        "    user only named an image-generation model but the scene needs video),",
+        "    DO NOT force it. Prefer the closest model from the SAME provider/family",
+        "    that can (e.g. a Kling image model → a Kling video model), otherwise",
+        "    fall back to the best catalog model per the routing rules above.",
+        "  - NEVER set scene.preferredModel to a model that can't output the scene's",
+        "    required modality. The preference improves model choice; it must not",
+        "    break the plan.",
+    ].join("\n");
+}
 function buildBrandKitSection(brandKit) {
     if (!brandKit)
         return "";

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

@@ -0,0 +1,35 @@
+import { AgentPersona } from "../../../schemas/agentPersona.schema";
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { AgentVisualBible, VideoPlan } from "../../../schemas/videoPlan.schema";
+import { LlmCaller } from "../llmCaller";
+/**
+ * Stream L (L-3) — script-first authoring pipeline for long-form (L1/L2) plans.
+ *
+ * The scene-first Planner (single structured LLM call → VideoPlan) is tuned for
+ * shorts; on a 3-60min video its per-scene voiceoverLines drift because each is
+ * written in isolation and the through-line is lost. Script-first fixes that
+ * with three passes (the L-4 tool cores):
+ *
+ *   1. generate_script      — brief → full coherent narration (one writer pass)
+ *   2. chapter_outline      — script → titled chapters (verbatim slices)
+ *   3. match_broll_to_script — per chapter: narration → B-roll scenes whose
+ *                              voiceoverLines are verbatim sentence slices
+ *
+ * The scenes are concatenated in chapter order (sceneIndex contiguous from 0),
+ * each chapter's sceneIndices back-filled, and the result assembled + validated
+ * into a VideoPlan that already satisfies the L-2 chapter contract by
+ * construction. Credit/duration/warning stamps mirror the scene-first finalize.
+ *
+ * Note: this path does NOT use the LLM to author scene durations or pick
+ * preferredModel — durations come from TTS length (3-8s band, in the core) and
+ * model selection is left to the executor's default + autoCorrectPreferredModels
+ * at execute time, same as a scene-first plan that omits preferredModel.
+ */
+export interface ScriptFirstDeps {
+    llm: LlmCaller;
+}
+export declare function planScriptFirst(deps: ScriptFirstDeps, brief: VideoBrief, opts?: {
+    persona?: AgentPersona;
+    bible?: AgentVisualBible | null;
+}): Promise<VideoPlan>;
+//# sourceMappingURL=scriptFirstPlanner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scriptFirstPlanner.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/scriptFirstPlanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAoB,MAAM,+BAA+B,CAAC;AAE7E,OAAO,EACL,gBAAgB,EAGhB,SAAS,EAEV,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAYzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,SAAS,CAAC;CAChB;AAQD,wBAAsB,eAAe,CACnC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAAO,GACrE,OAAO,CAAC,SAAS,CAAC,CAuIpB"}