vidspotai-shared 1.0.82-dev.0 → 1.0.83

package/lib/services/agent/eval/types.d.ts

@@ -75,6 +75,14 @@ export declare const EvalBriefSchema: z.ZodObject<{
             "4:5": "4:5";
             "16:9": "16:9";
         }>>;
+        lengthTier: z.ZodOptional<z.ZodEnum<{
+            S1: "S1";
+            S2: "S2";
+            M1: "M1";
+            L1: "L1";
+            L2: "L2";
+            L3: "L3";
+        }>>;
         voice: z.ZodOptional<z.ZodObject<{
             gender: z.ZodOptional<z.ZodEnum<{
                 male: "male";
@@ -134,12 +142,14 @@ export declare const EvalBriefSchema: z.ZodObject<{
                 transcriptExcerpt: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>>;
+        preferredModelKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
         tierBudget: z.ZodDefault<z.ZodEnum<{
             T0: "T0";
             T1: "T1";
             T2: "T2";
             T3: "T3";
         }>>;
+        maxSpendUSD: z.ZodOptional<z.ZodNumber>;
         videoStrategy: z.ZodOptional<z.ZodEnum<{
             auto: "auto";
             direct: "direct";

package/lib/services/agent/eval/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/eval/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;GAUG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB;;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;iBAY9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;iBAQ1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/eval/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;GAUG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB;;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;iBAY9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;iBAQ1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/lib/services/agent/executor/core.d.ts

@@ -0,0 +1,70 @@
+import { VideoPlan } from "../../../schemas/videoPlan.schema";
+import { ToolContext } from "../toolRegistry";
+import { ExecutorOptions, SceneOutcome } from "./types";
+/**
+ * Executor — turns an approved VideoPlan into per-scene asset results.
+ *
+ * Plan-then-execute split (not free-form ReAct): the executor does NOT pick
+ * tools. The plan dictates which tool runs per scene; the executor only does
+ * the dispatch + per-scene parallelism + idempotency-key generation.
+ *
+ * Returns a SceneOutcome per scene, leaving composition (compose_scene),
+ * critique (Critic.review), and render to the orchestrator above. The
+ * per-scene VISUAL strategy switch lives in ./visual (runVisual); the voice
+ * resolution helpers in ./voice; the public types in ./types.
+ */
+export declare class Executor {
+    private readonly concurrency;
+    private readonly runTool;
+    private readonly onSceneComplete?;
+    private readonly taskCache?;
+    private readonly onTaskMint?;
+    private readonly frozenVisualScenes?;
+    private readonly frozenVoiceoverScenes?;
+    /**
+     * AG-11b: per-run registry of each scene's generated identity still image,
+     * keyed by sceneIndex. One deferred per scene, created in run() before the
+     * worker pool starts. A scene that produces an identity image (image-* and
+     * the i2v first frame) resolves its own entry as soon as the image lands; a
+     * dependent scene (scene.characterAnchorSceneIndex set) awaits its anchor's
+     * entry and threads the URL in as an inputImage for image-to-image identity
+     * transfer. Every entry is settled (→ undefined if no image) when the scene
+     * completes, so a dependent never hangs on a stock/t2v/avatar/failed anchor.
+     *
+     * Deadlock-free: anchors point to EARLIER scenes (first appearance) and the
+     * queue is pulled in sceneIndex order, so a dependent's anchor is always
+     * already in-flight or done by the time the dependent is picked up.
+     */
+    private identityImages?;
+    constructor(opts?: ExecutorOptions);
+    /**
+     * AG-11b: publish a scene's generated identity image so dependent scenes can
+     * anchor off it. Idempotent — first call wins (the still image is produced
+     * once per scene). No-op when the registry isn't initialised (e.g. runVisual
+     * driven outside run(), such as single-scene regen).
+     */
+    private publishIdentityImage;
+    /**
+     * AG-11b: resolve the generated identity image of this scene's character
+     * anchor, or undefined when there's no anchor / no registry / the anchor
+     * produced no usable still (stock, pure t2v, avatar, or a failed scene).
+     * Self-references are ignored.
+     */
+    private resolveAnchorIdentityImage;
+    /**
+     * Stage 7 slice 1 helper. Returns cached pending-task output if the
+     * upstream input hash matches and entry is within TTL; null otherwise.
+     * Logs the hit so trace shows where $$ was saved.
+     */
+    private checkTaskCache;
+    /**
+     * Best-effort mint. Swallows callback errors — a Firestore blip must not
+     * fail the scene (the tool already succeeded and produced a real taskId).
+     */
+    private mintTaskCache;
+    /** Bundle the bound helpers runVisual needs (see VisualDeps). */
+    private visualDeps;
+    run(plan: VideoPlan, ctx: ToolContext): Promise<SceneOutcome[]>;
+    private runScene;
+}
+//# sourceMappingURL=core.d.ts.map

package/lib/services/agent/executor/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/executor/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAE5E,OAAO,EAA6B,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAczE,OAAO,EAAE,eAAe,EAAa,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnE;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAsB;IAE7D;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,cAAc,CAAC,CAGrB;gBAEU,IAAI,GAAE,eAAoB;IAUtC;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;;;OAKG;YACW,0BAA0B;IAiBxC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;YACW,aAAa;IAe3B,iEAAiE;IACjE,OAAO,CAAC,UAAU;IAcZ,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAiDvD,QAAQ;CA+GvB"}

package/lib/services/agent/executor/core.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Executor = void 0;
+const logger_1 = require("../../../utils/logger");
+const toolRegistry_1 = require("../toolRegistry");
+const ttsDuration_1 = require("../ttsDuration");
+const providerTaskCache_1 = require("../providerTaskCache");
+const voice_1 = require("./voice");
+const visual_1 = require("./visual");
+/**
+ * Executor — turns an approved VideoPlan into per-scene asset results.
+ *
+ * Plan-then-execute split (not free-form ReAct): the executor does NOT pick
+ * tools. The plan dictates which tool runs per scene; the executor only does
+ * the dispatch + per-scene parallelism + idempotency-key generation.
+ *
+ * Returns a SceneOutcome per scene, leaving composition (compose_scene),
+ * critique (Critic.review), and render to the orchestrator above. The
+ * per-scene VISUAL strategy switch lives in ./visual (runVisual); the voice
+ * resolution helpers in ./voice; the public types in ./types.
+ */
+class Executor {
+    constructor(opts = {}) {
+        this.concurrency = opts.concurrency ?? 4;
+        this.runTool = opts.runTool ?? toolRegistry_1.runTool;
+        this.onSceneComplete = opts.onSceneComplete;
+        this.taskCache = opts.taskCache;
+        this.onTaskMint = opts.onTaskMint;
+        this.frozenVisualScenes = opts.frozenVisualScenes;
+        this.frozenVoiceoverScenes = opts.frozenVoiceoverScenes;
+    }
+    /**
+     * AG-11b: publish a scene's generated identity image so dependent scenes can
+     * anchor off it. Idempotent — first call wins (the still image is produced
+     * once per scene). No-op when the registry isn't initialised (e.g. runVisual
+     * driven outside run(), such as single-scene regen).
+     */
+    publishIdentityImage(sceneIndex, url) {
+        this.identityImages?.get(sceneIndex)?.resolve(url);
+    }
+    /**
+     * AG-11b: resolve the generated identity image of this scene's character
+     * anchor, or undefined when there's no anchor / no registry / the anchor
+     * produced no usable still (stock, pure t2v, avatar, or a failed scene).
+     * Self-references are ignored.
+     */
+    async resolveAnchorIdentityImage(scene) {
+        const anchorIdx = scene.characterAnchorSceneIndex;
+        if (anchorIdx == null || anchorIdx === scene.sceneIndex)
+            return undefined;
+        const entry = this.identityImages?.get(anchorIdx);
+        if (!entry)
+            return undefined;
+        const url = await entry.promise;
+        if (url) {
+            logger_1.logger.info("executor: AG-11b anchoring scene to character reference", {
+                sceneIndex: scene.sceneIndex,
+                anchorSceneIndex: anchorIdx,
+            });
+        }
+        return url;
+    }
+    /**
+     * Stage 7 slice 1 helper. Returns cached pending-task output if the
+     * upstream input hash matches and entry is within TTL; null otherwise.
+     * Logs the hit so trace shows where $$ was saved.
+     */
+    checkTaskCache(clipId, tool, input) {
+        const inputsHash = (0, providerTaskCache_1.hashTaskInputs)(input);
+        const hit = (0, providerTaskCache_1.getCachedTask)(this.taskCache, clipId, inputsHash);
+        if (hit) {
+            logger_1.logger.info("executor: task-cache hit", {
+                clipId,
+                tool,
+                modelKey: hit.modelKey,
+                taskId: hit.taskId,
+                ageMs: Date.now() - hit.createdAt,
+            });
+        }
+        return { hit, inputsHash };
+    }
+    /**
+     * Best-effort mint. Swallows callback errors — a Firestore blip must not
+     * fail the scene (the tool already succeeded and produced a real taskId).
+     */
+    async mintTaskCache(clipId, entry) {
+        if (!this.onTaskMint)
+            return;
+        try {
+            await this.onTaskMint(clipId, entry);
+        }
+        catch (err) {
+            logger_1.logger.warn("executor: onTaskMint callback threw — swallowed", {
+                clipId,
+                err: err.message,
+            });
+        }
+    }
+    /** Bundle the bound helpers runVisual needs (see VisualDeps). */
+    visualDeps() {
+        return {
+            runTool: this.runTool,
+            frozenVisualScenes: this.frozenVisualScenes,
+            checkTaskCache: (clipId, tool, input) => this.checkTaskCache(clipId, tool, input),
+            mintTaskCache: (clipId, entry) => this.mintTaskCache(clipId, entry),
+            publishIdentityImage: (sceneIndex, url) => this.publishIdentityImage(sceneIndex, url),
+            resolveAnchorIdentityImage: (scene) => this.resolveAnchorIdentityImage(scene),
+        };
+    }
+    async run(plan, ctx) {
+        const queue = [...plan.scenes];
+        const results = new Array(plan.scenes.length);
+        const workers = [];
+        let cursor = 0;
+        // AG-11b: stand up one identity-image deferred per scene before the workers
+        // start, so a dependent scene can await its anchor's still even if the
+        // anchor hasn't produced it yet.
+        this.identityImages = new Map();
+        for (const scene of queue) {
+            let resolve;
+            const promise = new Promise((r) => {
+                resolve = r;
+            });
+            this.identityImages.set(scene.sceneIndex, { promise, resolve });
+        }
+        const worker = async () => {
+            while (true) {
+                const i = cursor++;
+                if (i >= queue.length)
+                    return;
+                const scene = queue[i];
+                const outcome = await this.runScene(scene, ctx, plan.aspect, plan);
+                // AG-11b: ensure this scene's identity deferred is settled (→ undefined
+                // for strategies that never published an image) so dependents on it
+                // never hang.
+                this.publishIdentityImage(scene.sceneIndex, undefined);
+                results[i] = outcome;
+                if (this.onSceneComplete) {
+                    try {
+                        await this.onSceneComplete(scene.sceneIndex, outcome);
+                    }
+                    catch (err) {
+                        logger_1.logger.warn("executor: onSceneComplete callback threw — swallowed", {
+                            sceneIndex: scene.sceneIndex,
+                            err: err.message,
+                        });
+                    }
+                }
+            }
+        };
+        for (let i = 0; i < Math.min(this.concurrency, queue.length); i++) {
+            workers.push(worker());
+        }
+        await Promise.all(workers);
+        return results;
+    }
+    async runScene(scene, ctx, aspect, plan) {
+        const start = Date.now();
+        const idempotencyKey = `${ctx.agentRunId}:scene-${scene.sceneIndex}`;
+        const sceneCtx = { ...ctx, idempotencyKey };
+        const visualOutcome = await (0, visual_1.runVisual)(this.visualDeps(), scene, sceneCtx, aspect, plan);
+        if (!visualOutcome.ok) {
+            return {
+                scene,
+                ok: false,
+                error: visualOutcome.error,
+                durationMs: Date.now() - start,
+            };
+        }
+        let voiceoverAudioBase64;
+        let voiceoverEstimateMs;
+        let voiceoverOverBudget = false;
+        // Gap #1 follow-up — skip-generation. VO preserved verbatim from a prior
+        // run: planToProject injects the frozen audio clip, so re-running TTS here
+        // just burns ElevenLabs credits for a result we discard.
+        const voiceoverFrozen = this.frozenVoiceoverScenes?.has(scene.sceneIndex) ?? false;
+        if (voiceoverFrozen) {
+            logger_1.logger.info("executor: skip-gen — voiceover frozen (preserved), no TTS call", {
+                sceneIndex: scene.sceneIndex,
+            });
+        }
+        // talking-head-avatar bakes the VO into the rendered MP4; running TTS again
+        // here would just waste credits and create a duplicate audio track.
+        if (scene.voiceoverLine && scene.strategy !== "talking-head-avatar" && !voiceoverFrozen) {
+            // AG-31: brief.voice.style → ElevenLabs voice_settings.
+            // AG-28: if estimated VO > scene.durationMs, speed up TTS within natural
+            // limits (≤1.15× extra over style.speed) before falling back to a
+            // freeze-frame-pad signal for the stitcher.
+            // AG-44: per-scene voiceStyle wins over plan-level when present, so the
+            // emotional arc can shift across the timeline (frustrated → curious → excited).
+            // AG-4: normalize freeform adjectives ('whispered', 'frustrated', …) onto
+            // the canonical VoiceStyle set before mapping to voice_settings, so the
+            // planned emotional arc isn't silently dropped on synonym drift.
+            const effectiveVoiceStyle = (0, voice_1.normalizeVoiceStyle)(scene.voiceStyle ?? plan.voiceStyle);
+            const baseSettings = (0, voice_1.resolveVoiceSettings)(effectiveVoiceStyle);
+            const baseSpeed = baseSettings.speed ?? 1.0;
+            const rawEstMs = (0, ttsDuration_1.estimateTtsMs)(scene.voiceoverLine);
+            const budgetMs = scene.durationMs * 1.05;
+            // Adjusted speed: only kick in if natural speech would overrun. Cap the
+            // speedup multiplier at 1.15× style-base; faster than that sounds rushed.
+            let speed = baseSpeed;
+            if (rawEstMs > budgetMs) {
+                const needed = rawEstMs / budgetMs;
+                const cappedMultiplier = Math.min(1.15, needed);
+                speed = +(baseSpeed * cappedMultiplier).toFixed(2);
+            }
+            const adjustedEstMs = rawEstMs * (baseSpeed / speed);
+            voiceoverEstimateMs = Math.round(adjustedEstMs);
+            voiceoverOverBudget = adjustedEstMs > budgetMs;
+            const voInput = {
+                text: scene.voiceoverLine,
+                ...baseSettings,
+                // Override speed when AG-28 budget forced an adjustment.
+                speed: +Math.max(0.7, Math.min(1.2, speed)).toFixed(2),
+            };
+            const sanitized = (0, voice_1.sanitizeVoiceId)(plan.voiceId);
+            if (sanitized)
+                voInput.voiceId = sanitized;
+            const voOutcome = await this.runTool("generate_voiceover", voInput, { ...sceneCtx, idempotencyKey: `${idempotencyKey}:vo` });
+            if (voOutcome.ok) {
+                voiceoverAudioBase64 = voOutcome.output.audioBase64;
+            }
+            else {
+                // AG-37: don't swallow silently — final video shipping muted with no
+                // log was the original bug. Surface the error in the result so the
+                // trace shows WHY VO is missing.
+                logger_1.logger.warn("executor: voiceover tool failed", {
+                    sceneIndex: scene.sceneIndex,
+                    error: voOutcome.error,
+                    voiceIdRequested: plan.voiceId,
+                    voiceIdSent: sanitized,
+                });
+            }
+            // Don't fail the whole scene on VO miss — host can re-run just the VO.
+        }
+        return {
+            scene,
+            ok: true,
+            result: {
+                ...visualOutcome.output,
+                voiceoverAudioBase64,
+                voiceoverEstimateMs,
+                voiceoverOverBudget,
+                idempotencyKey,
+            },
+            durationMs: Date.now() - start,
+        };
+    }
+}
+exports.Executor = Executor;

package/lib/services/agent/executor/duration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OD-T7 / AG-42 — give the planner's `preferredModel` a chance to actually run
+ * when the scene duration is just slightly off from what the model accepts.
+ *
+ * Decision tree:
+ *   1. Model has no duration constraint            → use planned duration
+ *   2. Planned duration already legal              → use planned duration
+ *   3. Nearest legal is within snap tolerance      → snap, log info
+ *   4. Outside tolerance + explicit preferredModel → log warn ("dropping
+ *      planner pick — too far from any allowed value"); use planned duration
+ *      anyway so the capability filter drops it and the chain fallback runs
+ *      (the withFallback warn AG-42 also logs there now)
+ *
+ * We intentionally do NOT throw — throwing would crash a scene mid-run and
+ * lose all the other planner output. The graceful fallback chain already
+ * exists; this helper just keeps the planner's pick alive when the drift is
+ * small, and makes the drop visible when it isn't.
+ */
+export declare function resolveDurationForPreferredModel(modelKey: string, plannedDurationSec: number, explicit: boolean, sceneIndex: number): number;
+//# sourceMappingURL=duration.d.ts.map

package/lib/services/agent/executor/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/executor/duration.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAsBR"}

package/lib/services/agent/executor/duration.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDurationForPreferredModel = resolveDurationForPreferredModel;
+const logger_1 = require("../../../utils/logger");
+const chains_1 = require("../providerFallback/chains");
+/**
+ * OD-T7 / AG-42 — give the planner's `preferredModel` a chance to actually run
+ * when the scene duration is just slightly off from what the model accepts.
+ *
+ * Decision tree:
+ *   1. Model has no duration constraint            → use planned duration
+ *   2. Planned duration already legal              → use planned duration
+ *   3. Nearest legal is within snap tolerance      → snap, log info
+ *   4. Outside tolerance + explicit preferredModel → log warn ("dropping
+ *      planner pick — too far from any allowed value"); use planned duration
+ *      anyway so the capability filter drops it and the chain fallback runs
+ *      (the withFallback warn AG-42 also logs there now)
+ *
+ * We intentionally do NOT throw — throwing would crash a scene mid-run and
+ * lose all the other planner output. The graceful fallback chain already
+ * exists; this helper just keeps the planner's pick alive when the drift is
+ * small, and makes the drop visible when it isn't.
+ */
+function resolveDurationForPreferredModel(modelKey, plannedDurationSec, explicit, sceneIndex) {
+    const snap = (0, chains_1.snapDurationForModel)(modelKey, plannedDurationSec);
+    if (!snap) {
+        if (explicit) {
+            logger_1.logger.warn("executor: preferredModel duration outside snap tolerance — chain fallback will pick", {
+                sceneIndex,
+                modelKey,
+                plannedDurationSec,
+            });
+        }
+        return plannedDurationSec;
+    }
+    if (snap.driftSec > 0.01) {
+        logger_1.logger.info("executor: snapped duration to fit preferredModel", {
+            sceneIndex,
+            modelKey,
+            from: snap.requestedSec,
+            to: snap.snappedSec,
+            driftSec: Number(snap.driftSec.toFixed(2)),
+        });
+    }
+    return snap.snappedSec;
+}

package/lib/services/agent/executor/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Executor — turns an approved VideoPlan into per-scene asset results. Split:
+ *   - core.ts     — the Executor class (run loop, scene dispatch, task cache,
+ *                   AG-11b identity-image registry)
+ *   - visual.ts   — runVisual: the per-scene VISUAL strategy switch
+ *   - voice.ts    — TTS voice-id sanitising + voice-style → voice_settings
+ *   - duration.ts — preferredModel duration snapping
+ *   - types.ts    — SceneAssetResult / SceneOutcome / ExecutorOptions /
+ *                   RunToolFn / classifySceneFailure
+ *
+ * Public surface is unchanged from the former single-file module.
+ */
+export * from "./types";
+export { Executor } from "./core";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/agent/executor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/executor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC"}

package/lib/services/agent/executor/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Executor = void 0;
+/**
+ * Executor — turns an approved VideoPlan into per-scene asset results. Split:
+ *   - core.ts     — the Executor class (run loop, scene dispatch, task cache,
+ *                   AG-11b identity-image registry)
+ *   - visual.ts   — runVisual: the per-scene VISUAL strategy switch
+ *   - voice.ts    — TTS voice-id sanitising + voice-style → voice_settings
+ *   - duration.ts — preferredModel duration snapping
+ *   - types.ts    — SceneAssetResult / SceneOutcome / ExecutorOptions /
+ *                   RunToolFn / classifySceneFailure
+ *
+ * Public surface is unchanged from the former single-file module.
+ */
+__exportStar(require("./types"), exports);
+var core_1 = require("./core");
+Object.defineProperty(exports, "Executor", { enumerable: true, get: function () { return core_1.Executor; } });