vidspotai-shared 1.0.82 → 1.0.84

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"}

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

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planScriptFirst = planScriptFirst;
+const brief_schema_1 = require("../../../schemas/brief.schema");
+const videoPlan_schema_1 = require("../../../schemas/videoPlan.schema");
+const logger_1 = require("../../../utils/logger");
+const costPreflight_1 = require("../costPreflight");
+const generateScript_tool_1 = require("../tools/generateScript.tool");
+const chapterOutline_tool_1 = require("../tools/chapterOutline.tool");
+const matchBrollToScript_tool_1 = require("../tools/matchBrollToScript.tool");
+const validators_1 = require("./validators");
+const TIER_ORDER = ["T0", "T1", "T2", "T3"];
+/** The lower (cheaper) of two tiers. */
+function tierMin(a, b) {
+    return TIER_ORDER.indexOf(a) <= TIER_ORDER.indexOf(b) ? a : b;
+}
+async function planScriptFirst(deps, brief, opts = {}) {
+    const { llm } = deps;
+    const lengthTier = brief.lengthTier ?? (0, brief_schema_1.deriveLengthTier)(brief.durationSec);
+    // Long-form defaults to landscape (YouTube) unless the brief says otherwise.
+    const aspect = brief.aspect ?? "16:9";
+    const persona = opts.persona ?? "faceless-yt";
+    // Stream L (L-6) lower-tier defaults: long-form B-roll defaults to the cheaper
+    // of the budget and T1; only the hero/intro scene (global sceneIndex 0) gets
+    // the full budget tier. Keeps an L2 (10-60min) plan from defaulting every one
+    // of 100+ scenes to T2/T3.
+    const budgetTier = brief.tierBudget;
+    const bodyTier = tierMin(budgetTier, "T1");
+    // Pass 1 — full narration.
+    const { script } = await (0, generateScript_tool_1.generateScriptCore)(llm, brief);
+    const wpm = script.wpm;
+    // Pass 2 — chapters (verbatim slices of the script).
+    const { chapters } = await (0, chapterOutline_tool_1.chapterOutlineCore)(llm, {
+        script: script.fullText,
+        wpm,
+    });
+    // Pass 3 — explode each chapter into B-roll scenes, keeping sceneIndex
+    // globally contiguous and back-filling chapter.sceneIndices.
+    const scenes = [];
+    const finalChapters = [];
+    let cursor = 0;
+    for (const ch of chapters) {
+        const narration = ch.narration?.trim();
+        if (!narration) {
+            // A chapter with no narration can't be exploded; keep it as a marker
+            // with no scenes rather than dropping it (preserves the outline).
+            finalChapters.push({ ...ch, sceneIndices: [] });
+            continue;
+        }
+        const { scenes: broll } = await (0, matchBrollToScript_tool_1.matchBrollToScriptCore)(llm, {
+            narration,
+            aspect,
+            niche: brief.niche,
+            startSceneIndex: cursor,
+            wpm,
+        });
+        const sceneIndices = [];
+        for (const bs of broll) {
+            scenes.push({
+                sceneIndex: bs.sceneIndex,
+                intent: bs.intent,
+                strategy: bs.strategy,
+                tier: bs.sceneIndex === 0 ? budgetTier : bodyTier,
+                prompt: bs.prompt,
+                durationMs: bs.durationMs,
+                voiceoverLine: bs.voiceoverLine,
+                transitionIn: "cut",
+                estimatedCredits: 0, // stamped below
+                bibleEntityIds: [],
+            });
+            sceneIndices.push(bs.sceneIndex);
+        }
+        finalChapters.push({ ...ch, sceneIndices });
+        cursor += broll.length;
+    }
+    if (scenes.length === 0) {
+        throw new Error("planScriptFirst: produced zero scenes — generate_script / chapter_outline / match_broll_to_script returned no usable narration.");
+    }
+    // Stamp per-scene + total credits (same helpers the scene-first finalize uses).
+    for (const s of scenes)
+        s.estimatedCredits = (0, costPreflight_1.estimateSceneCredits)(s);
+    // Stream L (L-6): hard spend cap. If the lower-tier defaults still blow the
+    // cap (sheer length), downgrade EVERY scene to T0 and re-stamp. If even an
+    // all-T0 plan is over budget, the cap is unachievable at this duration —
+    // throw with concrete guidance rather than silently overspending.
+    if (brief.maxSpendUSD != null) {
+        const usd = () => (0, costPreflight_1.creditsToUsd)(scenes.reduce((s, sc) => s + (0, costPreflight_1.estimateSceneCredits)(sc), 0));
+        if (usd() > brief.maxSpendUSD) {
+            for (const s of scenes) {
+                s.tier = "T0";
+                s.estimatedCredits = (0, costPreflight_1.estimateSceneCredits)(s);
+            }
+            logger_1.logger.warn("agent.plan.scriptFirst.budgetDowngrade", {
+                maxSpendUSD: brief.maxSpendUSD,
+                usdAfterDowngrade: Number(usd().toFixed(2)),
+                scenes: scenes.length,
+            });
+        }
+        if (usd() > brief.maxSpendUSD) {
+            throw new Error(`planScriptFirst: even an all-T0 plan ($${usd().toFixed(2)}) exceeds ` +
+                `maxSpendUSD=$${brief.maxSpendUSD.toFixed(2)} for ${scenes.length} scenes ` +
+                `(~${Math.round(scenes.reduce((sum, s) => sum + s.durationMs, 0) / 1000)}s). ` +
+                `Reduce the requested duration or raise the budget.`);
+        }
+    }
+    const totalDurationMs = scenes.reduce((sum, s) => sum + s.durationMs, 0);
+    const plan = {
+        persona,
+        aspect,
+        totalDurationMs,
+        totalEstimatedCredits: 0,
+        lengthTier,
+        scenes,
+        chapters: finalChapters,
+        script,
+        // voiceId/voiceStyle flow brief → plan deterministically (AG-31/37), same
+        // as the scene-first path; the LLM never authors them here.
+        voiceId: brief.voice?.voiceId,
+        voiceStyle: brief.voice?.style,
+        warnings: [],
+        ...(opts.bible ? { bible: opts.bible } : {}),
+    };
+    plan.totalEstimatedCredits = (0, costPreflight_1.estimatePlanCost)(plan).totalCredits;
+    plan.warnings = (0, validators_1.collectPlanWarnings)(plan);
+    const parsed = videoPlan_schema_1.VideoPlanSchema.safeParse(plan);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        throw new Error(`planScriptFirst: assembled plan failed validation: ${issues}`);
+    }
+    logger_1.logger.info("agent.plan.scriptFirst", {
+        lengthTier,
+        chapters: finalChapters.length,
+        scenes: scenes.length,
+        words: script.wordCount,
+        totalDurationMs,
+    });
+    return parsed.data;
+}

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

@@ -5,6 +5,16 @@ import { VideoBrief } from "../../../schemas/brief.schema";
  * under-delivered, CTA caption order wrong. Spelled out as hard contracts in
  * the planner prompt rather than soft hints, plus AG-9 also has a post-plan
  * validator (checkDurationContract) so the planner can't silently miss it.
+ *
+ * Stream L (L-2) — per-tier branches. The rules above were authored for
+ * short-form (S1/S2) and still apply verbatim there. For M1+ the pacing band,
+ * scene-count cap, and chapter requirements diverge:
+ *   - S1/S2: unchanged short-form rules.
+ *   - M1 (60s–3min): mixed pacing — wider per-scene band, chapters recommended.
+ *   - L1/L2 (3min+): per-scene band relaxed to 3–8s, MANY scenes expected, and
+ *     a chapter structure is REQUIRED. (L-3 layers script-first authoring on
+ *     top; this branch just sets the structural contract.)
+ *   - L3: edit-existing, not planner-driven (routed to L-5) — never reaches here.
  */
 export declare function buildStructuralRulesSection(brief: VideoBrief): string;
 //# sourceMappingURL=structuralRules.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"structuralRules.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/structuralRules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAkJrE"}
+{"version":3,"file":"structuralRules.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/planner/structuralRules.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoB,MAAM,+BAA+B,CAAC;AAE7E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAsOrE"}