vidspotai-shared 1.0.68 → 1.0.69-dev.0

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

@@ -0,0 +1,284 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDurationContract = checkDurationContract;
+exports.checkCaptionsContract = checkCaptionsContract;
+exports.checkNarrationDensityContract = checkNarrationDensityContract;
+exports.checkSceneTtsBudget = checkSceneTtsBudget;
+exports.checkSceneDurationCapability = checkSceneDurationCapability;
+exports.collectSceneVoClipWarnings = collectSceneVoClipWarnings;
+exports.collectSceneTrailingSilenceWarnings = collectSceneTrailingSilenceWarnings;
+exports.collectPlanWarnings = collectPlanWarnings;
+const tierHelpers_1 = require("../../../globals/aiModels/tierHelpers");
+const ttsDuration_1 = require("../ttsDuration");
+/**
+ * Single threshold for the trailing-silence warning. The executor pads
+ * scene-tail audio with a brief release (≈250ms); anything beyond ~1200ms
+ * of empty audio over a continuing visual reads as dead air on UGC, social,
+ * and explainer formats. Visual-led moments (real-estate panning, product
+ * close-ups) can opt out per-scene via `allowTrailingSilence`.
+ *
+ * Tunable. Not niche-gated by design — single threshold per the OD note.
+ */
+const TRAILING_SILENCE_WARN_MS = 1200;
+/**
+ * AG-9: hard duration contract. Returns null if the plan honours the brief's
+ * requested duration within 10%, otherwise returns a correction message to
+ * feed back to the planner on retry.
+ */
+function checkDurationContract(plan, brief) {
+    if (!brief.durationSec)
+        return null;
+    const target = brief.durationSec * 1000;
+    const actual = plan.scenes.reduce((sum, s) => sum + s.durationMs, 0);
+    const ratio = actual / target;
+    if (ratio >= 0.9 && ratio <= 1.1)
+        return null;
+    const direction = ratio < 0.9 ? "under" : "over";
+    if (direction === "under") {
+        // Math hint: at the chosen pacing band, suggest the per-scene avg the
+        // planner should target so it doesn't keep shipping the same N-scene plan
+        // on retry. Mirrors the bands in buildStructuralRulesSection.
+        const missingMs = target - actual;
+        const fastCutNiches = ["ugc-ad", "social-recap", "fitness"];
+        const effectivePacing = brief.pacing ??
+            ((brief.niche && fastCutNiches.includes(brief.niche)) ? "fast" : "medium");
+        const avgMsByPacing = {
+            "very-fast": 2500,
+            fast: 3500,
+            medium: 5000,
+            slow: 8000,
+        };
+        const perSceneMs = avgMsByPacing[effectivePacing];
+        const extraScenes = Math.max(1, Math.ceil(missingMs / perSceneMs));
+        return `Plan duration ${Math.round(actual / 1000)}s under-delivers vs brief.durationSec=${brief.durationSec}s (ratio ${ratio.toFixed(2)}). You currently have ${plan.scenes.length} scenes; ADD approximately ${extraScenes} more scenes (B-roll, transitions, product close-ups, lifestyle inserts) at ~${perSceneMs}ms each (pacing="${effectivePacing}"). Do NOT shorten existing scenes below the pacing band — add new scenes OR extend existing scenes within the band instead.`;
+    }
+    return `Plan duration ${Math.round(actual / 1000)}s over-delivers vs brief.durationSec=${brief.durationSec}s (ratio ${ratio.toFixed(2)}). Drop low-value scenes or shorten the hook to land within ±10% of ${brief.durationSec}s.`;
+}
+/**
+ * Captions contract. Faceless-YT explainers / TikTok shorts / any brief that
+ * mentions "captions" or "subtitles" MUST ship with at least one overlay per
+ * scene (the audience is sound-off by default). Returns a correction directive
+ * when the contract is broken; null when satisfied or N/A.
+ *
+ * Talking-head-avatar scenes are exempt — the avatar IS the on-screen text
+ * substitute and burned-in captions on top of a presenter feel cluttered.
+ */
+function checkCaptionsContract(plan, brief) {
+    const captionRequiredNiches = new Set(["faceless-yt", "social-recap", "fitness"]);
+    const mentionsCaptions = /\b(caption|subtitle|on-screen text|burned-in text)\b/i.test(brief.rawPrompt ?? "");
+    const required = (brief.niche && captionRequiredNiches.has(brief.niche)) || mentionsCaptions;
+    if (!required)
+        return null;
+    const missing = [];
+    for (const s of plan.scenes) {
+        if (s.strategy === "talking-head-avatar")
+            continue;
+        const hasOverlay = (s.overlays?.length ?? 0) > 0;
+        const hasLegacyText = !!s.onScreenText?.trim();
+        if (!hasOverlay && !hasLegacyText)
+            missing.push(s.sceneIndex);
+    }
+    if (missing.length === 0)
+        return null;
+    return (`Captions contract violation: brief requires burned-in captions ` +
+        `(niche=${brief.niche ?? "?"}, mentionsCaptions=${mentionsCaptions}) but ` +
+        `${missing.length} scene(s) ship with no overlays AND no onScreenText: ` +
+        `sceneIndex ${missing.join(", ")}. For EACH missing scene, add an overlays[] ` +
+        `entry: usually role='headline' (max 6 words, the literal key phrase) or ` +
+        `role='body' (max 14 words, the literal supporting sentence). The overlay ` +
+        `text field is what users will read on screen — NOT a description of font/ ` +
+        `color/position. The last scene MUST also include role='cta'. Watermark on ` +
+        `scene 0 only with persistAcrossScenes:true. Do NOT ship a faceless-YT ` +
+        `plan with empty overlays.`);
+}
+/**
+ * Narration-density contract. When a plan is narration-driven (>50% of scenes
+ * carry a voiceoverLine) AND brief.pacing is "medium" or "slow", every scene
+ * MUST be >= 3500ms. Sub-3.5s narration scenes produce telegraphic 3-4 word
+ * lines that read like a TikTok listicle instead of an informational explainer
+ * — the failure mode the user hit with 15×2s scenes for a 30s faceless-yt
+ * brief at medium pacing. Returns null when the plan satisfies the contract
+ * or the contract doesn't apply (fast/very-fast pacing, or VO-light plans).
+ */
+function checkNarrationDensityContract(plan, brief) {
+    if (brief.pacing !== "medium" && brief.pacing !== "slow")
+        return null;
+    const scenesWithVo = plan.scenes.filter((s) => !!s.voiceoverLine?.trim());
+    if (scenesWithVo.length <= plan.scenes.length / 2)
+        return null; // not narration-driven
+    const tooShort = plan.scenes
+        .filter((s) => !!s.voiceoverLine?.trim() && s.durationMs < 3500)
+        .map((s) => ({ sceneIndex: s.sceneIndex, durationMs: s.durationMs }));
+    if (tooShort.length === 0)
+        return null;
+    const list = tooShort
+        .map((s) => `scene ${s.sceneIndex} (${s.durationMs}ms)`)
+        .join(", ");
+    return (`Narration-density violation: brief.pacing="${brief.pacing}" with a ` +
+        `narration-driven plan (${scenesWithVo.length}/${plan.scenes.length} ` +
+        `scenes carry voiceoverLine), but ${tooShort.length} scene(s) are ` +
+        `shorter than 3500ms: ${list}. At medium/slow pacing each narrated ` +
+        `scene needs at least one full sentence (~3.5s minimum) — telegraphic ` +
+        `2-3s cuts feel like a TikTok listicle, not an informational explainer. ` +
+        `CONSOLIDATE: merge consecutive short scenes into longer ones (each ` +
+        `4000-6000ms for medium, 6000-10000ms for slow) and keep one full ` +
+        `sentence of voiceover per scene. Fewer scenes is correct here — aim ` +
+        `for ${Math.max(1, Math.round((brief.durationSec ?? 30) * 1000 / (brief.pacing === "slow" ? 8000 : 5000)))} scenes total at this pacing.`);
+}
+/**
+ * AG-28: per-scene voiceover-budget validator. Estimates TTS duration from the
+ * VO line's word count + punctuation. If the estimate exceeds the scene's
+ * durationMs by >10%, return a correction directive listing the offending
+ * scenes + the max word count that would fit. The planner can either shorten
+ * the line or merge with the next scene on retry.
+ */
+function checkSceneTtsBudget(plan) {
+    const offending = [];
+    for (const s of plan.scenes) {
+        if (!s.voiceoverLine)
+            continue;
+        if (s.strategy === "talking-head-avatar")
+            continue; // avatar bakes VO into the clip
+        const estMs = (0, ttsDuration_1.estimateTtsMs)(s.voiceoverLine);
+        if (estMs <= s.durationMs * 1.1)
+            continue;
+        const words = s.voiceoverLine.trim().split(/\s+/).filter(Boolean).length;
+        offending.push({
+            sceneIndex: s.sceneIndex,
+            durationMs: s.durationMs,
+            estimateMs: estMs,
+            words,
+            maxWords: (0, ttsDuration_1.maxVoWordsForMs)(s.durationMs),
+            line: s.voiceoverLine,
+        });
+    }
+    if (offending.length === 0)
+        return null;
+    const details = offending
+        .map((o) => `scene ${o.sceneIndex} (${o.durationMs}ms): "${o.line}" — ${o.words} words ≈ ${o.estimateMs}ms VO (max ${o.maxWords} words for this scene duration)`)
+        .join("; ");
+    return `Voiceover budget violation on ${offending.length} scene(s): ${details}. Either (a) shorten each offending voiceoverLine to <= the listed max-word count, or (b) extend scene.durationMs to >= the estimated VO ms (respecting the duration contract — if that pushes you over total, drop another scene's VO entirely or shorten a different scene). Do NOT ship the plan as-is — the audio will be clipped mid-sentence.`;
+}
+/**
+ * AG-15: per-scene duration-capability validator. For each scene using an AI
+ * video provider (ai-image-to-video / ai-text-to-video), confirm that
+ * scene.durationMs/1000 is in the preferredModel's allowed-durations list. On
+ * mismatch, build a directive correction the planner can act on: name the
+ * offending scenes + suggest a model whose `dur:` range actually accepts the
+ * requested duration. Root cause for Test-1 burning $0 of useful work: planner
+ * picked minimax-hailuo-02 (6s / 10s only) for 1.7s scenes — fallback chain
+ * exhausted because every fallback was also a ≥6s model.
+ */
+function checkSceneDurationCapability(plan) {
+    const offending = [];
+    const aiVideoStrategies = new Set(["ai-image-to-video", "ai-text-to-video"]);
+    for (const scene of plan.scenes) {
+        if (!aiVideoStrategies.has(scene.strategy))
+            continue;
+        if (!scene.preferredModel)
+            continue;
+        const allowed = (0, tierHelpers_1.getModelAllowedDurations)(scene.preferredModel);
+        if (!allowed)
+            continue; // model has no declared constraint
+        const seconds = scene.durationMs / 1000;
+        // Allow ±0.25s wiggle so 1.8s → 2 floor doesn't trip on rounding.
+        const matches = allowed.some((v) => Math.abs(v - seconds) < 0.25);
+        if (!matches) {
+            offending.push({
+                sceneIndex: scene.sceneIndex,
+                seconds: Math.round(seconds * 100) / 100,
+                modelKey: scene.preferredModel,
+                allowed,
+            });
+        }
+    }
+    if (offending.length === 0)
+        return null;
+    const details = offending
+        .map((o) => `scene ${o.sceneIndex} (${o.seconds}s) → ${o.modelKey} only accepts [${o.allowed.join(", ")}]s`)
+        .join("; ");
+    return (`AG-15 duration-capability mismatch: ${details}. ` +
+        `Fix BY EITHER: (a) merging too-short scenes into a single ≥${offending[0].allowed[0]}s clip so the cut count drops but the total duration stays the same, OR ` +
+        `(b) re-picking preferredModel from a provider whose dur: range INCLUDES the scene's duration. ` +
+        `Short-duration capable models: bytedance-seedance-1.0-pro-fast (2-12s), bytedance-seedance-1.0-pro (2-12s), runway-gen4.5 (2-10s), kling-v3.0 (3-15s), google-veo-3.1-lite (4-8s). ` +
+        `Do NOT pick minimax-hailuo for any scene shorter than 6s.`);
+}
+/**
+ * Warning-channel siblings of the rejection validators above. These run on
+ * an already-approved plan (or after a sceneEdit patch) and produce
+ * PlannerWarning entries the UI can surface — never rejection strings.
+ */
+/** Demote vo-clip rejections to warnings after the planner has exhausted retries. */
+function collectSceneVoClipWarnings(plan) {
+    const warnings = [];
+    for (const s of plan.scenes) {
+        if (!s.voiceoverLine)
+            continue;
+        if (s.strategy === "talking-head-avatar")
+            continue;
+        const estMs = (0, ttsDuration_1.estimateTtsMs)(s.voiceoverLine);
+        // Mirror executor's 1.15× speedup cap: VO actually clips only when
+        // est / 1.15 still exceeds scene.durationMs * 1.05.
+        const adjustedEstMs = estMs / 1.15;
+        const budgetMs = s.durationMs * 1.05;
+        if (adjustedEstMs <= budgetMs)
+            continue;
+        const overrunMs = Math.round(adjustedEstMs - budgetMs);
+        warnings.push({
+            sceneIndex: s.sceneIndex,
+            kind: "vo-clip",
+            message: `Voiceover will overrun this scene by ~${overrunMs}ms even after the ` +
+                `1.15× speedup. Audio will clip mid-sentence. Extend the scene ` +
+                `duration or shorten the voiceover line (max ~${(0, ttsDuration_1.maxVoWordsForMs)(s.durationMs)} words).`,
+            meta: {
+                voEstimateMs: Math.round(estMs),
+                sceneDurationMs: s.durationMs,
+                overrunMs,
+            },
+        });
+    }
+    return warnings;
+}
+/**
+ * Warn when a scene's VO ends notably before the scene itself ends — that
+ * extra time renders as silence over a continuing visual, which reads as
+ * dead air on most formats. Suppressed when `scene.allowTrailingSilence`
+ * is set (visual-led moments). Scenes without VO are exempt (silence by
+ * design — handled by music / ambience tracks).
+ */
+function collectSceneTrailingSilenceWarnings(plan) {
+    const warnings = [];
+    for (const s of plan.scenes) {
+        if (!s.voiceoverLine?.trim())
+            continue;
+        if (s.strategy === "talking-head-avatar")
+            continue; // VO is baked into avatar clip
+        if (s.allowTrailingSilence)
+            continue;
+        const estMs = (0, ttsDuration_1.estimateTtsMs)(s.voiceoverLine);
+        const silenceMs = s.durationMs - estMs;
+        if (silenceMs <= TRAILING_SILENCE_WARN_MS)
+            continue;
+        warnings.push({
+            sceneIndex: s.sceneIndex,
+            kind: "trailing-silence",
+            message: `Voiceover ends ~${Math.round(silenceMs / 100) / 10}s before this ` +
+                `scene ends — the visual will play in silence. Shorten the scene ` +
+                `duration, lengthen the voiceover, or toggle "Allow trailing silence" ` +
+                `if this is an intentional showcase moment.`,
+            meta: {
+                voEstimateMs: Math.round(estMs),
+                sceneDurationMs: s.durationMs,
+                silenceMs: Math.round(silenceMs),
+            },
+        });
+    }
+    return warnings;
+}
+/** One-shot helper: returns the full warning set for a plan + scene overrides. */
+function collectPlanWarnings(plan) {
+    return [
+        ...collectSceneVoClipWarnings(plan),
+        ...collectSceneTrailingSilenceWarnings(plan),
+    ];
+}

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

@@ -0,0 +1,3 @@
+export { Planner, type PlannerOptions } from "./planner/Planner";
+export { checkSceneTtsBudget, checkSceneDurationCapability, collectPlanWarnings, collectSceneVoClipWarnings, collectSceneTrailingSilenceWarnings, } from "./planner/validators";
+//# sourceMappingURL=planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../../src/services/agent/planner.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,mBAAmB,EACnB,0BAA0B,EAC1B,mCAAmC,GACpC,MAAM,sBAAsB,CAAC"}

package/lib/services/agent/planner.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSceneTrailingSilenceWarnings = exports.collectSceneVoClipWarnings = exports.collectPlanWarnings = exports.checkSceneDurationCapability = exports.checkSceneTtsBudget = exports.Planner = void 0;
+// Barrel — planner was split into per-concern modules under `planner/`.
+// Public surface (`Planner`, `PlannerOptions`) is preserved byte-for-byte
+// for npm consumers of `vidspotai-shared`.
+var Planner_1 = require("./planner/Planner");
+Object.defineProperty(exports, "Planner", { enumerable: true, get: function () { return Planner_1.Planner; } });
+var validators_1 = require("./planner/validators");
+Object.defineProperty(exports, "checkSceneTtsBudget", { enumerable: true, get: function () { return validators_1.checkSceneTtsBudget; } });
+Object.defineProperty(exports, "checkSceneDurationCapability", { enumerable: true, get: function () { return validators_1.checkSceneDurationCapability; } });
+Object.defineProperty(exports, "collectPlanWarnings", { enumerable: true, get: function () { return validators_1.collectPlanWarnings; } });
+Object.defineProperty(exports, "collectSceneVoClipWarnings", { enumerable: true, get: function () { return validators_1.collectSceneVoClipWarnings; } });
+Object.defineProperty(exports, "collectSceneTrailingSilenceWarnings", { enumerable: true, get: function () { return validators_1.collectSceneTrailingSilenceWarnings; } });

package/lib/services/agent/providerFallback/chains.d.ts

@@ -0,0 +1,100 @@
+import { EVideoGenModels, EMusicGenModels, ESfxGenModels, type GenerationType } from "../../../globals/aiModels";
+/**
+ * Provider-chain configuration per modality (F3.3).
+ * Ordered primary → fallback. The wrapper walks the chain on recoverable
+ * failures (transient / rate-limit / capability / quota / unknown).
+ *
+ * Ordering rationale: perceived quality + reliability first. Tier downgrades
+ * happen at the AGENT layer (re-plan), not at the chain layer — within a
+ * single chain we stay at the same tier.
+ *
+ * Capability matrix (`videoCapabilities`) filters chains pre-flight so we
+ * don't fall back to a model that physically can't do the requested
+ * aspect / duration / lastFrame / etc.
+ */
+export declare const T3_TEXT_TO_VIDEO_CHAIN: readonly EVideoGenModels[];
+export declare const T2_TEXT_TO_VIDEO_CHAIN: readonly EVideoGenModels[];
+export declare const T2_IMAGE_TO_VIDEO_CHAIN: readonly EVideoGenModels[];
+export declare const T3_IMAGE_TO_VIDEO_CHAIN: readonly EVideoGenModels[];
+export declare const AVATAR_VIDEO_CHAIN: readonly EVideoGenModels[];
+export declare const MUSIC_CHAIN: readonly EMusicGenModels[];
+export declare const SFX_CHAIN: readonly ESfxGenModels[];
+/**
+ * AG-16: schema-driven capability gate. We no longer maintain a parallel
+ * `VIDEO_CAPABILITIES` table — that drifted from the actual model schemas
+ * (e.g. it set `maxDurationSec` but had no concept of a *minimum*, so a 2s
+ * request for minimax-hailuo-02 (allowed [6,10]) passed the gate, the call
+ * fired, the provider rejected, and the fallback chain wasted attempts on
+ * five more models that all had the same minimum). Source of truth is now
+ * `aiModelConfigs[modelKey].fields` + `.type`. Pixel-format aspect ratios
+ * (Runway's "1280:720" etc.) are normalised to canonical "W:H" before
+ * comparison so callers can always pass "9:16" / "16:9" / etc.
+ */
+export interface VideoCapabilityRequest {
+    aspect: string;
+    durationSec: number;
+    /** Generation type the chain is being walked for. */
+    type?: GenerationType;
+    /** Caller wants last-frame anchoring (gen4_turbo / Kling / Veo support it). */
+    lastFrame?: boolean;
+    /** Caller wants native audio output. */
+    audio?: boolean;
+    /**
+     * AG-21: whether the caller is supplying a source still. Used to filter out
+     * providers whose schema marks `inputImageUrl: { required: true }` from a
+     * text-to-video chain (e.g. runway-gen4-turbo) — otherwise the call would
+     * fire and the provider would reject for missing input image, wasting a
+     * fallback slot. Default false (text-to-video assumption); animate_image /
+     * image-to-video tools pass true.
+     */
+    hasInputImage?: boolean;
+}
+export declare function isVideoModelCapable(model: EVideoGenModels, req: VideoCapabilityRequest): boolean;
+/**
+ * Build a chain that puts the planner's pick first, then the rest of the
+ * tier-appropriate chain (deduped). Honors the planner's intent while still
+ * providing fallback when the pick fails.
+ */
+export declare function buildVideoChain(plannerPick: EVideoGenModels, fallbackChain: readonly EVideoGenModels[]): EVideoGenModels[];
+/**
+ * OD-T7 / AG-42 — snap-or-throw resolver for `preferredModel` duration
+ * conflicts.
+ *
+ * Today the chain layer silently drops a planner-picked model when its
+ * duration constraint doesn't match the scene (e.g. pixverse-v6 wants
+ * [5, 8, 10, 15]s, scene is 2s → model dropped, fallback picks a different
+ * provider, planner intent lost). This helper gives the executor a chance
+ * to RESCUE the planner's pick by snapping the scene duration to the
+ * nearest legal value when the drift is small.
+ *
+ * Semantics:
+ *   - Already legal (±0.25s):      return { snapped: durationSec, drift: 0 }
+ *   - No duration constraint:      return { snapped: durationSec, drift: 0 }
+ *   - Within tolerance:            return { snapped: nearest, drift: |Δ| }
+ *   - Outside tolerance:           return null — caller falls back per chain
+ *
+ * Default tolerance: snap is accepted if the nearest legal value is within
+ * ±2s AND within ±50% of the requested duration. The 50% cap protects
+ * short clips (1.5s asking for 5s would be a >3x stretch — too much). The
+ * 2s cap protects long clips (12s asking for 15s is +25% but only 3s of
+ * absolute drift — borderline; rejected by 2s cap which is the stricter
+ * one for long values). Callers can tune via `maxDriftSec` / `maxDriftRel`.
+ */
+export interface SnapDurationOptions {
+    /** Absolute cap in seconds. Default 2.0. */
+    maxDriftSec?: number;
+    /** Relative cap (fraction of requested duration). Default 0.5 (50%). */
+    maxDriftRel?: number;
+}
+export interface SnapDurationResult {
+    /** Original requested duration in seconds. */
+    requestedSec: number;
+    /** Duration to use for the actual provider call (snapped if needed). */
+    snappedSec: number;
+    /** |snappedSec - requestedSec|. 0 when already legal. */
+    driftSec: number;
+    /** True when the model declared no duration constraint (anything goes). */
+    unconstrained: boolean;
+}
+export declare function snapDurationForModel(model: string | EVideoGenModels, durationSec: number, opts?: SnapDurationOptions): SnapDurationResult | null;
+//# sourceMappingURL=chains.d.ts.map

package/lib/services/agent/providerFallback/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/providerFallback/chains.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EACf,eAAe,EACf,aAAa,EAEb,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;GAYG;AAGH,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAM5D,CAAC;AAKF,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAQ5D,CAAC;AAQF,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAQ7D,CAAC;AAKF,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAM7D,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAExD,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,SAAS,eAAe,EAGjD,CAAC;AAGF,eAAO,MAAM,SAAS,EAAE,SAAS,aAAa,EAE7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAuCT;AA8CD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,eAAe,EAC5B,aAAa,EAAE,SAAS,eAAe,EAAE,GACxC,eAAe,EAAE,CAMnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,eAAe,EAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,mBAAwB,GAC7B,kBAAkB,GAAG,IAAI,CAyB3B"}

package/lib/services/agent/providerFallback/chains.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SFX_CHAIN = exports.MUSIC_CHAIN = exports.AVATAR_VIDEO_CHAIN = exports.T3_IMAGE_TO_VIDEO_CHAIN = exports.T2_IMAGE_TO_VIDEO_CHAIN = exports.T2_TEXT_TO_VIDEO_CHAIN = exports.T3_TEXT_TO_VIDEO_CHAIN = void 0;
+exports.isVideoModelCapable = isVideoModelCapable;
+exports.buildVideoChain = buildVideoChain;
+exports.snapDurationForModel = snapDurationForModel;
+const aiModels_1 = require("../../../globals/aiModels");
+/**
+ * Provider-chain configuration per modality (F3.3).
+ * Ordered primary → fallback. The wrapper walks the chain on recoverable
+ * failures (transient / rate-limit / capability / quota / unknown).
+ *
+ * Ordering rationale: perceived quality + reliability first. Tier downgrades
+ * happen at the AGENT layer (re-plan), not at the chain layer — within a
+ * single chain we stay at the same tier.
+ *
+ * Capability matrix (`videoCapabilities`) filters chains pre-flight so we
+ * don't fall back to a model that physically can't do the requested
+ * aspect / duration / lastFrame / etc.
+ */
+// ── Video: text-to-video, T3 (cinematic) ──────────────────────────────
+exports.T3_TEXT_TO_VIDEO_CHAIN = [
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1,
+    aiModels_1.EVideoGenModels.KLING_V2_6,
+    aiModels_1.EVideoGenModels.RUNWAY_GEN4_5,
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_2_0,
+    aiModels_1.EVideoGenModels.MINIMAX_HAILUO_2_3,
+];
+// ── Video: text-to-video, T2 (balanced) ───────────────────────────────
+// AG-16: seedance-1.0-pro-fast added to cover 2-3s clips; pixverse-v6 added
+// for 15s coverage (rest of T2 T2V tops out at 12s).
+exports.T2_TEXT_TO_VIDEO_CHAIN = [
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_1_0_PRO_FAST,
+    aiModels_1.EVideoGenModels.KLING_V2_5_TURBO,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1_FAST,
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_1_5_PRO,
+    aiModels_1.EVideoGenModels.PIXVERSE_V6,
+    aiModels_1.EVideoGenModels.PIXVERSE_V5_6,
+    aiModels_1.EVideoGenModels.MINIMAX_HAILUO_2_3_FAST,
+];
+// ── Video: image-to-video, T2 (most common path) ──────────────────────
+// AG-16: bytedance-seedance-1.0-pro-fast prepended — only T2 I2V model that
+// accepts sub-4s clips (2-12s range). Without it, any short-clip plan (e.g.
+// 2s scenes for a fast-cut 10s UGC) has zero capable fallbacks and the chain
+// exhausts when the primary fails. pixverse-v6 added for 15s long-clip
+// coverage (rest of T2 I2V tops out at 12s).
+exports.T2_IMAGE_TO_VIDEO_CHAIN = [
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_1_0_PRO_FAST,
+    aiModels_1.EVideoGenModels.KLING_V2_5_TURBO,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1_FAST,
+    aiModels_1.EVideoGenModels.RUNWAY_GEN4_TURBO,
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_1_5_PRO,
+    aiModels_1.EVideoGenModels.PIXVERSE_V6,
+    aiModels_1.EVideoGenModels.MINIMAX_HAILUO_02,
+];
+// ── Video: image-to-video, T3 (premium) ───────────────────────────────
+// AG-16: kling-v3.0 added (broadest I2V range 3-15s in T3 tier). runway-gen4.5
+// kept — I2V branch in runway.service.ts now implemented per Runway docs.
+exports.T3_IMAGE_TO_VIDEO_CHAIN = [
+    aiModels_1.EVideoGenModels.KLING_V2_6,
+    aiModels_1.EVideoGenModels.KLING_V3_0,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1,
+    aiModels_1.EVideoGenModels.RUNWAY_GEN4_5,
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_2_0,
+];
+// ── Video: avatar / talking-head (Kling-only today) ───────────────────
+exports.AVATAR_VIDEO_CHAIN = [
+    aiModels_1.EVideoGenModels.KLING_AVATAR,
+];
+// ── Music: search/gen ─────────────────────────────────────────────────
+exports.MUSIC_CHAIN = [
+    aiModels_1.EMusicGenModels.GOOGLE_LYRIA_2,
+    aiModels_1.EMusicGenModels.MINIMAX_MUSIC_1_5,
+];
+// ── SFX: ElevenLabs only ──────────────────────────────────────────────
+exports.SFX_CHAIN = [
+    aiModels_1.ESfxGenModels.ELEVENLABS_SOUND_EFFECTS,
+];
+function isVideoModelCapable(model, req) {
+    const cfg = aiModels_1.aiModelConfigs[model];
+    if (!cfg)
+        return true; // unknown model → optimistic
+    // Type gate (text-to-video vs image-to-video).
+    if (req.type && cfg.type && !cfg.type.includes(req.type))
+        return false;
+    // AG-21: required-field gate. If the model schema marks `inputImageUrl` as
+    // required and the caller isn't supplying one (text-to-video without source
+    // still), this model cannot serve the request — skip rather than burning a
+    // chain slot and getting rejected.
+    const requiresInputImage = cfg.fields?.inputImageUrl?.required === true;
+    if (requiresInputImage && req.hasInputImage === false)
+        return false;
+    // Duration gate: exact match (±0.25s rounding) against allowedValues.
+    const allowedDur = cfg.fields?.duration?.allowedValues;
+    if (allowedDur?.length && allowedDur.every((v) => typeof v === "number")) {
+        const match = allowedDur.some((v) => Math.abs(v - req.durationSec) < 0.25);
+        if (!match)
+            return false;
+    }
+    // Aspect gate: normalise both sides to canonical "W:H" reduced form so
+    // Runway-style "1280:720" matches a request for "16:9".
+    const allowedAspects = cfg.fields?.aspectRatio?.allowedValues;
+    if (allowedAspects?.length) {
+        const normReq = normalizeAspect(req.aspect);
+        const normAllowed = allowedAspects.map(normalizeAspect);
+        if (!normAllowed.includes(normReq))
+            return false;
+    }
+    // lastFrame / audio support is currently encoded ad-hoc per provider; treat
+    // as optimistic until we surface those flags on the schema. Most models
+    // either support both or neither, so a wrong-positive is rare and the
+    // provider will reject + reclassify as capability.
+    if (req.lastFrame && !supportsEndFrame(model))
+        return false;
+    if (req.audio && !supportsAudio(model))
+        return false;
+    return true;
+}
+/** Reduce a "W:H" or "WxH" ratio to lowest terms, e.g. "1280:720" → "16:9". */
+function normalizeAspect(a) {
+    if (!a)
+        return a;
+    const m = a.match(/^(\d+)[:x](\d+)$/);
+    if (!m)
+        return a;
+    const w = parseInt(m[1], 10);
+    const h = parseInt(m[2], 10);
+    if (!w || !h)
+        return a;
+    const g = gcd(w, h);
+    return `${w / g}:${h / g}`;
+}
+function gcd(a, b) {
+    return b === 0 ? a : gcd(b, a % b);
+}
+// AG-16: small allow-lists for capabilities not yet on the schema. Conservative
+// — extend as we wire native audio / lastFrame as proper schema fields.
+const END_FRAME_MODELS = new Set([
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1_FAST,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1_LITE,
+    aiModels_1.EVideoGenModels.KLING_V2_6,
+    aiModels_1.EVideoGenModels.KLING_V2_5_TURBO,
+    aiModels_1.EVideoGenModels.KLING_V3_0,
+    aiModels_1.EVideoGenModels.RUNWAY_GEN4_TURBO,
+    aiModels_1.EVideoGenModels.RUNWAY_GEN4_5,
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_2_0,
+    aiModels_1.EVideoGenModels.PIXVERSE_V5_6,
+]);
+const AUDIO_MODELS = new Set([
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1_FAST,
+    aiModels_1.EVideoGenModels.GOOGLE_VEO_3_1_LITE,
+    aiModels_1.EVideoGenModels.BYTEDANCE_SEEDANCE_2_0,
+    aiModels_1.EVideoGenModels.KLING_AVATAR,
+]);
+function supportsEndFrame(m) {
+    return END_FRAME_MODELS.has(m);
+}
+function supportsAudio(m) {
+    return AUDIO_MODELS.has(m);
+}
+/**
+ * Build a chain that puts the planner's pick first, then the rest of the
+ * tier-appropriate chain (deduped). Honors the planner's intent while still
+ * providing fallback when the pick fails.
+ */
+function buildVideoChain(plannerPick, fallbackChain) {
+    const chain = [plannerPick];
+    for (const m of fallbackChain) {
+        if (m !== plannerPick)
+            chain.push(m);
+    }
+    return chain;
+}
+function snapDurationForModel(model, durationSec, opts = {}) {
+    const allowed = (0, aiModels_1.getModelAllowedDurations)(model);
+    if (!allowed) {
+        return { requestedSec: durationSec, snappedSec: durationSec, driftSec: 0, unconstrained: true };
+    }
+    // Already within rounding tolerance of a legal value.
+    const inRange = allowed.some((v) => Math.abs(v - durationSec) < 0.25);
+    if (inRange) {
+        const exact = allowed.reduce((best, v) => Math.abs(v - durationSec) < Math.abs(best - durationSec) ? v : best, allowed[0]);
+        return { requestedSec: durationSec, snappedSec: exact, driftSec: Math.abs(exact - durationSec), unconstrained: false };
+    }
+    // Find the nearest legal value and see whether the drift is acceptable.
+    const nearest = allowed.reduce((best, v) => Math.abs(v - durationSec) < Math.abs(best - durationSec) ? v : best, allowed[0]);
+    const driftSec = Math.abs(nearest - durationSec);
+    const maxDriftSec = opts.maxDriftSec ?? 2.0;
+    const maxDriftRel = opts.maxDriftRel ?? 0.5;
+    const driftRel = durationSec > 0 ? driftSec / durationSec : Infinity;
+    if (driftSec <= maxDriftSec && driftRel <= maxDriftRel) {
+        return { requestedSec: durationSec, snappedSec: nearest, driftSec, unconstrained: false };
+    }
+    return null;
+}

package/lib/services/agent/providerFallback/classifier.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Classifies a provider error into one of these classes to drive the
+ * `withProviderFallback` decision tree:
+ *
+ *   - "transient"    : retry / fall back (network blip, 5xx, generic timeout)
+ *   - "rate_limit"   : fall back (429, quota-on-window)
+ *   - "capability"   : fall back (provider can't do this aspect/duration/feature)
+ *   - "safety"       : DO NOT fall back; escalate to agent (next provider will also block)
+ *   - "auth"         : DO NOT fall back; fail fast (deploy bug, missing key)
+ *   - "quota"        : fall back; account-level quota exhausted for this provider
+ *   - "input"        : DO NOT fall back; bad user input (prompt invalid, image rejected)
+ *   - "unknown"      : treat as transient — better to try next provider than fail
+ *
+ * Inputs:
+ *   - structured `UserFacingError` (preferred — read `.code`)
+ *   - raw `Error` — regex-match common provider error message patterns
+ *
+ * F3.6 (not in this pass) standardizes raw-throwing providers to use
+ * `UserFacingError` so the regex path becomes unnecessary.
+ */
+export type ProviderFailureClass = "transient" | "rate_limit" | "capability" | "safety" | "auth" | "quota" | "input" | "unknown";
+export interface ProviderFailureClassification {
+    classification: ProviderFailureClass;
+    /** True if no provider fallback should be tried (auth / safety / input). */
+    isTerminal: boolean;
+    /** True if this is a recoverable failure the AGENT should re-plan (safety/input). */
+    needsReplan: boolean;
+    /** Original UserFacingError code, if present, for tracing. */
+    originalCode?: string;
+    /** Original error message, truncated. */
+    message: string;
+}
+export declare function classifyProviderError(err: unknown): ProviderFailureClassification;
+/** Decide whether to try the next provider in a chain for a given class. */
+export declare function shouldFallback(c: ProviderFailureClass): boolean;
+//# sourceMappingURL=classifier.d.ts.map

package/lib/services/agent/providerFallback/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/providerFallback/classifier.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,GACP,SAAS,CAAC;AAEd,MAAM,WAAW,6BAA6B;IAC5C,cAAc,EAAE,oBAAoB,CAAC;IACrC,4EAA4E;IAC5E,UAAU,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,WAAW,EAAE,OAAO,CAAC;IACrB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;CACjB;AA8FD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,6BAA6B,CAsBjF;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAI/D"}