vidspotai-shared 1.0.82 → 1.0.83

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

@@ -0,0 +1,400 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runVisual = runVisual;
+const logger_1 = require("../../../utils/logger");
+const referenceImageRenderer_1 = require("../referenceImageRenderer");
+const extendChain_1 = require("../extendChain");
+const helpers_1 = require("../../aiGen/helpers");
+const unsplash_service_1 = require("../../aiGen/providers/unsplash/unsplash.service");
+const duration_1 = require("./duration");
+async function runVisual(deps, scene, ctx, aspect, plan) {
+    // Gap #1 follow-up — skip-generation. The user froze this scene's visual in
+    // a prior run; planToProject reproduces the preserved clip verbatim, so any
+    // gen we ran here would be discarded. Return a no-op outcome (no visualUrl,
+    // no pendingTaskId) BEFORE any provider call: no task minted, no $$ spent.
+    if (deps.frozenVisualScenes?.has(scene.sceneIndex)) {
+        logger_1.logger.info("executor: skip-gen — visual frozen (preserved), no provider call", {
+            sceneIndex: scene.sceneIndex,
+            strategy: scene.strategy,
+        });
+        return { ok: true, output: { tool: "frozen" } };
+    }
+    const durationSec = Math.max(2, Math.round(scene.durationMs / 1000));
+    // AG-13: collect reference images for this scene's bible entities. Empty
+    // array when bible is C0/C1 or no entities are tagged — image-gen falls
+    // back to pure text prompt.
+    const referenceImageUrls = (0, referenceImageRenderer_1.collectReferenceImageUrls)(plan.bible, scene.bibleEntityIds ?? []);
+    // AG-11b: if this scene reuses a character from an earlier scene, prepend
+    // that anchor's generated still as an inputImage for image-to-image
+    // identity transfer. The Visual Bible (C2) is the primary consistency
+    // signal; this is the backup signal (characterAnchorSceneIndex) made real
+    // on the executor side. Merge ahead of bible refs and de-dupe.
+    const anchorImageUrl = await deps.resolveAnchorIdentityImage(scene);
+    const identityRefs = anchorImageUrl
+        ? Array.from(new Set([anchorImageUrl, ...referenceImageUrls]))
+        : referenceImageUrls;
+    const wrap = (tool, outcome) => outcome.ok
+        ? { ok: true, output: { tool, ...outcome.output } }
+        : { ok: false, error: outcome.error };
+    switch (scene.strategy) {
+        case "stock-video":
+        case "stock-image-ken-burns": {
+            const out = await deps.runTool("search_stock", {
+                query: scene.prompt,
+                kind: scene.strategy === "stock-video" ? "video" : "image",
+                aspectRatio: aspect,
+                minDurationSec: scene.strategy === "stock-video" ? durationSec : undefined,
+            }, ctx);
+            if (!out.ok)
+                return wrap("search_stock", out);
+            const stockAsset = out.output.assets[0];
+            const url = stockAsset?.url;
+            if (!url)
+                return {
+                    ok: false,
+                    error: {
+                        code: "NO_STOCK_RESULTS",
+                        message: `No stock results for: ${scene.prompt}`,
+                        attemptedProviders: out.output.attemptedProviders,
+                    },
+                };
+            // P-UNS-1: Unsplash API ToS requires firing the provider's
+            // download-tracking endpoint when an asset is actually USED in a render
+            // (not at search time). runVisual runs once per scene at execution, so
+            // this is exactly the commit point. Unsplash-only — Pexels/Pixabay omit
+            // trackingUrl, and pingDownload() self-guards when the key is unset.
+            // Fire-and-forget: a tracking hiccup must never fail the scene.
+            if (stockAsset?.trackingUrl) {
+                void new unsplash_service_1.UnsplashProviderService()
+                    .pingDownload(stockAsset.trackingUrl)
+                    .catch((err) => logger_1.logger.warn("unsplash pingDownload failed (non-fatal)", {
+                    error: err instanceof Error ? err.message : String(err),
+                    sceneIndex: scene.sceneIndex,
+                    agentRunId: ctx.agentRunId,
+                }));
+            }
+            return {
+                ok: true,
+                output: {
+                    tool: "search_stock",
+                    visualUrl: url,
+                    attemptedProviders: out.output.attemptedProviders,
+                    // P-UNS-2: carry stock attribution to the clip provenance (Unsplash
+                    // requires visible credit; Pexels/Pixabay leave it undefined).
+                    attribution: stockAsset.attribution,
+                },
+            };
+        }
+        case "ai-image-static":
+        case "ai-image-motion": {
+            const out = await deps.runTool("generate_image", {
+                prompt: scene.prompt,
+                modelKey: scene.preferredModel ?? "google-nano-banana",
+                aspectRatio: aspect,
+                ...(identityRefs.length
+                    ? { inputImageUrls: identityRefs }
+                    : {}),
+            }, ctx);
+            if (!out.ok)
+                return wrap("generate_image", out);
+            // AG-11b: this generated still is the scene's identity frame — publish
+            // it so later same-character scenes can anchor off it.
+            deps.publishIdentityImage(scene.sceneIndex, out.output.imageUrl);
+            return { ok: true, output: { tool: "generate_image", visualUrl: out.output.imageUrl } };
+        }
+        case "ai-image-to-video": {
+            const animateModelKey = scene.preferredModel ?? "kling-v2.6";
+            // AG-2 / L-4: if the scene wants more seconds than this model emits in
+            // one clip and the model supports native extension, build the initial
+            // clip at the model's max length and emit the rest as extension steps
+            // (resolved sequentially host-side). Otherwise fall back to the snap
+            // path, which clamps to the nearest legal value.
+            const chain = (0, extendChain_1.planExtendChain)(animateModelKey, durationSec);
+            const extendChain = chain?.segments;
+            const animateDurationSec = chain
+                ? chain.initialDurationSec
+                : (0, duration_1.resolveDurationForPreferredModel)(animateModelKey, durationSec, !!scene.preferredModel, scene.sceneIndex);
+            if (chain) {
+                logger_1.logger.info("executor: scene needs extend chain", {
+                    sceneIndex: scene.sceneIndex,
+                    modelKey: animateModelKey,
+                    targetSec: durationSec,
+                    initialSec: chain.initialDurationSec,
+                    extensions: chain.segments.length,
+                });
+            }
+            // AG-1 Phase 2 — first-last-frame (FLF) interpolation. Only honour
+            // scene.lastFramePrompt when the chosen model actually accepts an end
+            // frame (capability gate reads `lastFrameImageUrl` from its config).
+            // On a non-FLF model the field is silently ignored so a stray planner
+            // value never breaks the scene — it just renders as plain i2v.
+            const useFlf = !!scene.lastFramePrompt && (0, helpers_1.modelSupportsLastFrame)(animateModelKey);
+            if (scene.lastFramePrompt && !useFlf) {
+                logger_1.logger.warn("executor: ignoring lastFramePrompt — model is not FLF-capable", { sceneIndex: scene.sceneIndex, modelKey: animateModelKey });
+            }
+            // Stage 7 slice 1: cache key spans the WHOLE strategy (both image-gen
+            // + animate). Hashing only upstream-stable inputs — prompt, model,
+            // duration, aspect, reference images — lets a re-execute skip BOTH
+            // tool calls, replaying the cached animate taskId through the poller.
+            // AG-1: the end-frame prompt is part of the cache identity so toggling
+            // FLF on a scene re-generates rather than replaying the old single-frame task.
+            const clipId = `scene-${scene.sceneIndex}-visual`;
+            const cacheInput = {
+                strategy: "ai-image-to-video",
+                prompt: scene.prompt,
+                modelKey: animateModelKey,
+                durationSec: animateDurationSec,
+                aspect,
+                // AG-11b: intentionally keys on referenceImageUrls (bible), NOT
+                // identityRefs. The anchor still is generated per-run and is absent
+                // on a cache-hit re-execute (the anchor scene replays without
+                // re-generating its image); including it would bust the cache every
+                // re-execute and re-submit gen tasks. The anchored identity is
+                // already baked into the minted animate task, so a plain replay
+                // preserves consistency. Do NOT add identityRefs here.
+                referenceImageUrls,
+                extendSegments: extendChain?.length ?? 0,
+                ...(useFlf ? { lastFramePrompt: scene.lastFramePrompt } : {}),
+            };
+            const { hit, inputsHash } = deps.checkTaskCache(clipId, "animate_image", cacheInput);
+            if (hit) {
+                return {
+                    ok: true,
+                    output: {
+                        tool: "animate_image",
+                        pendingTaskId: hit.taskId,
+                        pendingModelKey: hit.modelKey,
+                        // Re-emit the chain on cache replay so the host still resolves the
+                        // extensions from the cached source task (extensions aren't cached).
+                        ...(extendChain ? { extendChain } : {}),
+                    },
+                };
+            }
+            const img = await deps.runTool("generate_image", {
+                prompt: scene.prompt,
+                modelKey: "google-nano-banana",
+                aspectRatio: aspect,
+                ...(identityRefs.length
+                    ? { inputImageUrls: identityRefs }
+                    : {}),
+            }, { ...ctx, idempotencyKey: `${ctx.idempotencyKey}:img` });
+            if (!img.ok)
+                return wrap("generate_image", img);
+            // AG-11b: publish the i2v first frame as this scene's identity still so
+            // later same-character scenes can anchor off it.
+            deps.publishIdentityImage(scene.sceneIndex, img.output.imageUrl);
+            // AG-1: generate the END composition for FLF. Same reference images as
+            // the first frame so identity stays locked across the interpolation.
+            let lastFrameImageUrl;
+            if (useFlf) {
+                const endImg = await deps.runTool("generate_image", {
+                    prompt: scene.lastFramePrompt,
+                    modelKey: "google-nano-banana",
+                    aspectRatio: aspect,
+                    ...(identityRefs.length
+                        ? { inputImageUrls: identityRefs }
+                        : {}),
+                }, { ...ctx, idempotencyKey: `${ctx.idempotencyKey}:imgEnd` });
+                if (!endImg.ok)
+                    return wrap("generate_image", endImg);
+                lastFrameImageUrl = endImg.output.imageUrl;
+            }
+            const animate = await deps.runTool("animate_image", {
+                imageUrl: img.output.imageUrl,
+                motionHint: scene.prompt,
+                durationSec: animateDurationSec,
+                modelKey: animateModelKey,
+                ...(lastFrameImageUrl ? { lastFrameImageUrl } : {}),
+            }, ctx);
+            if (!animate.ok)
+                return wrap("animate_image", animate);
+            const mintedModelKey = animate.output.modelKeyUsed ?? animateModelKey;
+            await deps.mintTaskCache(clipId, {
+                tool: "animate_image",
+                taskId: animate.output.taskId,
+                modelKey: mintedModelKey,
+                inputsHash,
+                createdAt: Date.now(),
+            });
+            return {
+                ok: true,
+                output: {
+                    tool: "animate_image",
+                    pendingTaskId: animate.output.taskId,
+                    pendingModelKey: mintedModelKey,
+                    attemptedProviders: animate.output.attemptedProviders,
+                    ...(extendChain ? { extendChain } : {}),
+                },
+            };
+        }
+        case "ai-text-to-video": {
+            const t2vModelKey = scene.preferredModel ?? "kling-v2.6";
+            // AG-2 / L-4: same extend-chain decision as ai-image-to-video.
+            const chain = (0, extendChain_1.planExtendChain)(t2vModelKey, durationSec);
+            const extendChain = chain?.segments;
+            const t2vDurationSec = chain
+                ? chain.initialDurationSec
+                : (0, duration_1.resolveDurationForPreferredModel)(t2vModelKey, durationSec, !!scene.preferredModel, scene.sceneIndex);
+            if (chain) {
+                logger_1.logger.info("executor: scene needs extend chain", {
+                    sceneIndex: scene.sceneIndex,
+                    modelKey: t2vModelKey,
+                    targetSec: durationSec,
+                    initialSec: chain.initialDurationSec,
+                    extensions: chain.segments.length,
+                });
+            }
+            const clipId = `scene-${scene.sceneIndex}-visual`;
+            const cacheInput = {
+                strategy: "ai-text-to-video",
+                prompt: scene.prompt,
+                modelKey: t2vModelKey,
+                durationSec: t2vDurationSec,
+                extendSegments: extendChain?.length ?? 0,
+            };
+            const { hit, inputsHash } = deps.checkTaskCache(clipId, "generate_video", cacheInput);
+            if (hit) {
+                return {
+                    ok: true,
+                    output: {
+                        tool: "generate_video",
+                        pendingTaskId: hit.taskId,
+                        pendingModelKey: hit.modelKey,
+                        ...(extendChain ? { extendChain } : {}),
+                    },
+                };
+            }
+            const out = await deps.runTool("generate_video", {
+                prompt: scene.prompt,
+                modelKey: t2vModelKey,
+                durationSec: t2vDurationSec,
+            }, ctx);
+            if (!out.ok)
+                return wrap("generate_video", out);
+            const mintedModelKey = out.output.modelKeyUsed ?? t2vModelKey;
+            await deps.mintTaskCache(clipId, {
+                tool: "generate_video",
+                taskId: out.output.taskId,
+                modelKey: mintedModelKey,
+                inputsHash,
+                createdAt: Date.now(),
+            });
+            return {
+                ok: true,
+                output: {
+                    tool: "generate_video",
+                    pendingTaskId: out.output.taskId,
+                    pendingModelKey: mintedModelKey,
+                    attemptedProviders: out.output.attemptedProviders,
+                    ...(extendChain ? { extendChain } : {}),
+                },
+            };
+        }
+        case "user-asset": {
+            // Per-user library search. The host injects the searcher at boot
+            // (see userLibrarySearcher bootstrap); if no match, fall back to
+            // stock so the scene still renders rather than failing hard.
+            const out = await deps.runTool("search_user_library", { query: scene.prompt, limit: 5 }, ctx);
+            if (out.ok) {
+                const first = out.output.assets[0];
+                if (first) {
+                    return { ok: true, output: { tool: "search_user_library", visualUrl: first.url } };
+                }
+            }
+            // No hits or searcher missing — fall back to stock-video as the
+            // closest cheap substitute so the executor still produces an asset.
+            const stock = await deps.runTool("search_stock", {
+                query: scene.prompt,
+                kind: "video",
+                aspectRatio: aspect,
+                minDurationSec: durationSec,
+            }, ctx);
+            if (!stock.ok)
+                return wrap("search_stock", stock);
+            const fallbackUrl = stock.output.assets[0]?.url;
+            if (!fallbackUrl) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "USER_ASSET_NO_MATCH",
+                        message: `No user-library match for "${scene.prompt}" and no stock fallback.`,
+                        attemptedProviders: stock.output.attemptedProviders,
+                    },
+                };
+            }
+            return {
+                ok: true,
+                output: {
+                    tool: "search_user_library",
+                    visualUrl: fallbackUrl,
+                    attemptedProviders: stock.output.attemptedProviders,
+                },
+            };
+        }
+        case "talking-head-avatar": {
+            if (!scene.avatarFaceUrl) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "AVATAR_FACE_REQUIRED",
+                        message: "talking-head-avatar requires scene.avatarFaceUrl (set on the user's brand kit).",
+                    },
+                };
+            }
+            if (!scene.voiceoverLine) {
+                return {
+                    ok: false,
+                    error: {
+                        code: "AVATAR_VO_REQUIRED",
+                        message: "talking-head-avatar requires scene.voiceoverLine for the lipsync audio.",
+                    },
+                };
+            }
+            const avatarMode = scene.tier === "T3" ? "pro" : "std";
+            const clipId = `scene-${scene.sceneIndex}-visual`;
+            const cacheInput = {
+                strategy: "talking-head-avatar",
+                inputImageUrl: scene.avatarFaceUrl,
+                ttsText: scene.voiceoverLine,
+                mode: avatarMode,
+            };
+            const { hit, inputsHash } = deps.checkTaskCache(clipId, "generate_avatar_video", cacheInput);
+            if (hit) {
+                return {
+                    ok: true,
+                    output: {
+                        tool: "generate_avatar_video",
+                        pendingTaskId: hit.taskId,
+                        pendingModelKey: hit.modelKey,
+                    },
+                };
+            }
+            const out = await deps.runTool("generate_avatar_video", {
+                inputImageUrl: scene.avatarFaceUrl,
+                ttsText: scene.voiceoverLine,
+                mode: avatarMode,
+            }, ctx);
+            if (!out.ok)
+                return wrap("generate_avatar_video", out);
+            await deps.mintTaskCache(clipId, {
+                tool: "generate_avatar_video",
+                taskId: out.output.taskId,
+                // Avatar tool hardcodes Kling Avatar internally; poller needs the
+                // actual model key to route via getAiGenProviderService (no special
+                // resolver exists). AG-20: was "generate_avatar_video" which would
+                // throw at factory lookup the moment the avatar path was polled.
+                modelKey: "kling-avatar",
+                inputsHash,
+                createdAt: Date.now(),
+            });
+            return {
+                ok: true,
+                output: {
+                    tool: "generate_avatar_video",
+                    pendingTaskId: out.output.taskId,
+                    pendingModelKey: "kling-avatar",
+                },
+            };
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+import { VoiceStyle } from "../../../schemas/brief.schema";
+export declare function sanitizeVoiceId(voiceId: string | undefined): string | undefined;
+/**
+ * AG-31: map a brief-level voice style adjective to ElevenLabs voice_settings.
+ * `style` is the exaggeration param (use sparingly above 0.5 — artifacts);
+ * `stability` is the consistency knob (low = more emotive, high = monotone);
+ * `speed` is rate (0.7-1.2). Defaults match ElevenLabs' own (style=0,
+ * stability=0.5, speed=1.0). Tuning per persona is conservative — we'd rather
+ * be slightly flat than artifact-laden.
+ */
+export declare function resolveVoiceSettings(style: VoiceStyle | undefined): {
+    style?: number;
+    stability?: number;
+    speed?: number;
+};
+export declare function normalizeVoiceStyle(raw: string | undefined): VoiceStyle | undefined;
+//# sourceMappingURL=voice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/executor/voice.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAkB3D,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAU/E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,GAAG,SAAS,GAC5B;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAyBxD;AAgDD,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,UAAU,GAAG,SAAS,CAKxB"}

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

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeVoiceId = sanitizeVoiceId;
+exports.resolveVoiceSettings = resolveVoiceSettings;
+exports.normalizeVoiceStyle = normalizeVoiceStyle;
+const voices_1 = require("../../../globals/ttsModels/voices");
+const logger_1 = require("../../../utils/logger");
+/**
+ * Voice resolution helpers for the executor's TTS step: strip hallucinated
+ * voice IDs, map a (normalized) voice-style adjective onto ElevenLabs
+ * voice_settings, and canonicalise freeform style synonyms.
+ */
+/**
+ * AG-37: planners (LLMs) keep inventing voice IDs like "female-young-adult-en"
+ * or "narrator-1" that look reasonable but don't exist in any catalog. When
+ * those flow into ElevenLabs the API returns a 400 and the silent-fail VO
+ * outcome path drops the VO entirely — final video ships muted. Strip
+ * unknown IDs here so the provider falls back to its default voice instead.
+ */
+const ELEVENLABS_VOICE_IDS = new Set(voices_1.ELEVENLABS_VOICES.map((v) => v.id));
+function sanitizeVoiceId(voiceId) {
+    if (!voiceId)
+        return undefined;
+    if (ELEVENLABS_VOICE_IDS.has(voiceId))
+        return voiceId;
+    // Heuristic for non-ElevenLabs providers (openai = "alloy"/"echo"/..., minimax = "male-qn-qingse").
+    // Only strip strings that look like LLM-invented descriptive labels (contain a hyphen + recognisable word).
+    if (/^(female|male|narrator|presenter|voice)[-_]/i.test(voiceId)) {
+        logger_1.logger.warn("executor: stripping invalid voiceId (LLM hallucination)", { voiceId });
+        return undefined;
+    }
+    return voiceId;
+}
+/**
+ * AG-31: map a brief-level voice style adjective to ElevenLabs voice_settings.
+ * `style` is the exaggeration param (use sparingly above 0.5 — artifacts);
+ * `stability` is the consistency knob (low = more emotive, high = monotone);
+ * `speed` is rate (0.7-1.2). Defaults match ElevenLabs' own (style=0,
+ * stability=0.5, speed=1.0). Tuning per persona is conservative — we'd rather
+ * be slightly flat than artifact-laden.
+ */
+function resolveVoiceSettings(style) {
+    switch (style) {
+        case "calm":
+            return { style: 0.15, stability: 0.7, speed: 0.95 };
+        case "warm":
+            return { style: 0.25, stability: 0.6, speed: 1.0 };
+        case "casual":
+            return { style: 0.3, stability: 0.5, speed: 1.0 };
+        case "excited":
+            return { style: 0.55, stability: 0.35, speed: 1.05 };
+        case "energetic":
+            return { style: 0.6, stability: 0.35, speed: 1.08 };
+        case "happy":
+            return { style: 0.5, stability: 0.4, speed: 1.05 };
+        case "serious":
+            return { style: 0.2, stability: 0.75, speed: 0.95 };
+        case "dramatic":
+            return { style: 0.65, stability: 0.4, speed: 0.95 };
+        case "whisper":
+            return { style: 0.2, stability: 0.85, speed: 0.9 };
+        case "neutral":
+        case undefined:
+        default:
+            return {};
+    }
+}
+/**
+ * AG-4: canonical VoiceStyle values that resolveVoiceSettings actually maps.
+ * Anything outside this set falls through to `{}` (flat delivery).
+ */
+const CANONICAL_VOICE_STYLES = new Set([
+    "neutral", "calm", "warm", "casual", "excited",
+    "energetic", "happy", "serious", "dramatic", "whisper",
+]);
+/**
+ * AG-4: map a freeform voice-style adjective onto the canonical VoiceStyle
+ * vocabulary so per-scene emotional beats actually reach voice_settings.
+ * The planner is prompted to emit canonical values, but LLMs drift toward
+ * synonyms ('whispered', 'authoritative', 'frustrated', 'curious'); without
+ * this they silently no-op to default delivery. Unknown words → undefined
+ * (same as today). Case/whitespace-insensitive.
+ */
+const VOICE_STYLE_SYNONYMS = {
+    // whisper
+    whispered: "whisper", hushed: "whisper", soft: "whisper",
+    quiet: "whisper", intimate: "whisper", reflective: "whisper",
+    // calm
+    thoughtful: "calm", curious: "calm", intrigued: "calm", sad: "calm",
+    somber: "calm", melancholy: "calm", contemplative: "calm", gentle: "calm",
+    // warm
+    reassuring: "warm", friendly: "warm", soothing: "warm", inviting: "warm",
+    // casual
+    conversational: "casual", relaxed: "casual", chill: "casual",
+    informal: "casual", "laid-back": "casual",
+    // serious
+    authoritative: "serious", confident: "serious", assertive: "serious",
+    skeptical: "serious", professional: "serious", commanding: "serious",
+    // dramatic
+    frustrated: "dramatic", urgent: "dramatic", intense: "dramatic",
+    tense: "dramatic", angry: "dramatic",
+    // energetic
+    enthusiastic: "energetic", hyped: "energetic", lively: "energetic",
+    upbeat: "energetic", peppy: "energetic",
+    // happy
+    joyful: "happy", playful: "happy", cheerful: "happy", delighted: "happy",
+    // excited
+    thrilled: "excited", eager: "excited", animated: "excited",
+    // neutral
+    monotone: "neutral", deadpan: "neutral", flat: "neutral", robotic: "neutral",
+};
+function normalizeVoiceStyle(raw) {
+    if (!raw)
+        return undefined;
+    const key = raw.trim().toLowerCase();
+    if (CANONICAL_VOICE_STYLES.has(key))
+        return key;
+    return VOICE_STYLE_SYNONYMS[key];
+}

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

@@ -0,0 +1,101 @@
+import type { RunToolFn } from "./executor";
+import { ToolContext } from "./toolRegistry";
+/** One extension step in a chain (the source clip is implicit / step 0). */
+export interface ExtendChainStep {
+    /**
+     * Seconds to extend by. The provider clamps to its native increment, so this
+     * drives cost + the time-window split, not a frame-exact length.
+     */
+    extraDurationSec: number;
+    /**
+     * Optional continuation prompt. Omitted by default so the provider continues
+     * the source clip's motion naturally (a fresh prompt risks a visible cut).
+     */
+    prompt?: string;
+}
+/** Output of `planExtendChain` — how to build a too-long scene's visual. */
+export interface ExtendChainPlan {
+    /** Seconds for the initial clip (the model's max legal single-clip length). */
+    initialDurationSec: number;
+    /** Ordered extension segments fired after the initial clip completes. */
+    segments: ExtendChainStep[];
+}
+/** A resolved visual sub-clip (source or one extension), in render order. */
+export interface SceneClip {
+    /** Final asset URL for this sub-clip. */
+    visualUrl: string;
+    /** Provider task id this clip came from (trace / reuse). */
+    taskId?: string;
+    /** Nominal seconds for this sub-clip; drives the planToProject window split. */
+    durationSec: number;
+}
+/**
+ * Decide whether a video scene needs an extend chain, and slice the extra
+ * seconds into provider-legal extension steps. Returns `null` when:
+ *   - the model has no declared duration constraint (unconstrained → one clip),
+ *   - the target already fits one clip (within snap tolerance), or
+ *   - the model has no native extension endpoint (caller clamps as before — a
+ *     non-extend model can't continue a clip, so the extra seconds are dropped
+ *     by the existing capability/snap path).
+ *
+ * `targetDurationSec` is the scene's full requested length (scene.durationMs/1000).
+ */
+export declare function planExtendChain(modelKey: string, targetDurationSec: number): ExtendChainPlan | null;
+/** Poll result shape the host's TaskPoller wrapper returns. */
+export interface ExtendPollResult {
+    status: "completed" | "failed" | "timed-out";
+    videoUrl?: string;
+    errorMessage?: string;
+}
+/** Injected capabilities resolveExtendChain needs (host wires real impls). */
+export interface ExtendChainDeps {
+    /** Tool dispatcher (same one the executor uses) — runs `extend_video`. */
+    runTool: RunToolFn;
+    /** Polls a single provider task to completion (TaskPoller wrapper host-side). */
+    pollTask: (args: {
+        ref: string;
+        taskId: string;
+        modelKey: string;
+        outputFilename?: string;
+    }) => Promise<ExtendPollResult>;
+}
+export interface ResolveExtendChainArgs {
+    sceneIndex: number;
+    /** Extend-capable model the whole chain runs on (no cross-provider fallback). */
+    modelKey: string;
+    /** Task id of the already-triggered initial clip. */
+    initialTaskId: string;
+    /** Nominal seconds of the initial clip (from planExtendChain.initialDurationSec). */
+    initialDurationSec: number;
+    /** Ordered extension segments (from planExtendChain.segments). */
+    segments: ExtendChainStep[];
+    /** Tool context for the extend_video calls. */
+    ctx: ToolContext;
+    /** Filename hint prefix for the poller (e.g. `${projectId}-scene${i}`). */
+    outputFilenamePrefix?: string;
+}
+export type ResolveExtendChainResult = {
+    ok: true;
+    clips: SceneClip[];
+} | {
+    ok: false;
+    /** Clips that DID resolve before the failure (may be empty). */
+    clips: SceneClip[];
+    error: {
+        code: string;
+        message: string;
+        failedTaskId?: string;
+    };
+};
+/**
+ * Run an extend chain to completion, enforcing source-task ordering: poll the
+ * current task → on completion, fire the next extension → poll that → repeat.
+ * Returns the source + extension clips in render order.
+ *
+ * Failure is partial-tolerant: if a mid-chain task fails/times out we stop and
+ * return the clips resolved so far with ok:false, so the caller can decide to
+ * ship a shorter scene rather than lose the whole thing. A failed SOURCE clip
+ * (no clips resolved) is a hard scene failure.
+ */
+export declare function resolveExtendChain(deps: ExtendChainDeps, args: ResolveExtendChainArgs): Promise<ResolveExtendChainResult>;
+//# sourceMappingURL=extendChain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extendChain.d.ts","sourceRoot":"","sources":["../../../src/services/agent/extendChain.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAgD7C,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,GACxB,eAAe,GAAG,IAAI,CA2BxB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,OAAO,EAAE,SAAS,CAAC;IACnB,iFAAiF;IACjF,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,+CAA+C;IAC/C,GAAG,EAAE,WAAW,CAAC;IACjB,2EAA2E;IAC3E,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,GAChC;IACE,EAAE,EAAE,KAAK,CAAC;IACV,gEAAgE;IAChE,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE,CAAC;AAEN;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,wBAAwB,CAAC,CAiFnC"}