vidspotai-shared 1.0.82-dev.0 → 1.0.83

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

@@ -0,0 +1,183 @@
+import { PlannedScene } from "../../../schemas/videoPlan.schema";
+import { ToolContext, ToolOutcome } from "../toolRegistry";
+import { ExtendChainStep, SceneClip } from "../extendChain";
+import { ProviderTaskCache, ProviderTaskCacheEntry } from "../providerTaskCache";
+/**
+ * Executor public types: the per-scene asset/outcome shapes, the run options,
+ * the injectable runTool signature, and the failure classifier. Kept separate
+ * from the Executor class so tool/host modules can import these without pulling
+ * in the class (and its provider deps).
+ */
+export type RunToolFn = <O = unknown>(name: string, input: unknown, ctx: ToolContext) => Promise<ToolOutcome<O>>;
+export interface SceneAssetResult {
+    /** Concrete asset URL for the visual track (image or video). */
+    visualUrl?: string;
+    /** P-UNS-2: stock attribution for the visual, when the provider requires credit (Unsplash). */
+    attribution?: {
+        name: string;
+        url?: string;
+    };
+    /** Voiceover audio (base64 or url depending on host policy). */
+    voiceoverAudioBase64?: string;
+    /**
+     * Resolved voiceover URL once the host has uploaded the base64 buffer to
+     * its asset store (GCS / Firebase Storage). The agent.controller flow
+     * sets this in `onSceneComplete` so `planToProject` can render a real VO
+     * clip on `track-vo`. When unset, planToProject skips the VO clip.
+     */
+    voiceoverUrl?: string;
+    /** Provider task id for async generations the host still needs to poll. */
+    pendingTaskId?: string;
+    /** Model key the pending task was triggered on — the poller needs this to pick the provider. */
+    pendingModelKey?: string;
+    /**
+     * AG-2 / L-4 extend chain. Set when the scene's requested duration exceeds the
+     * chosen model's max single clip AND the model supports native extension: the
+     * executor triggers the initial clip (at the model's max legal length, its id
+     * in `pendingTaskId`) and lists the remaining length here as ordered extension
+     * segments. The host runs them SEQUENTIALLY via `resolveExtendChain` (each
+     * extend continues the previous provider task, so each waits for that task to
+     * COMPLETE) and fills `clips`. Absent on the common path (scene fits one clip).
+     */
+    extendChain?: ExtendChainStep[];
+    /**
+     * AG-2 / L-4. Resolved visual sub-clips (source + extensions) in render order,
+     * filled by the host's `resolveExtendChain` after sequential polling.
+     * planToProject lays these out as adjacent video clips across the scene's
+     * time window. When unset, the single `visualUrl` is used.
+     */
+    clips?: SceneClip[];
+    /** AG-22: provider chain the tool walked (in order, primary first). For trace + post-mortem. */
+    attemptedProviders?: string[];
+    /** Tool name used. */
+    tool: string;
+    /** Idempotency key the executor minted; useful for retries. */
+    idempotencyKey: string;
+    /**
+     * AG-28: estimated VO duration (ms) from the wpm heuristic. Set when
+     * voiceoverAudioBase64 is set. Used pre-upload for budget math; the
+     * editor-side display window prefers voiceoverActualMs when available.
+     */
+    voiceoverEstimateMs?: number;
+    /**
+     * Probed actual mp3 duration (ms). Stamped by `resolveVoiceoverUrl` after
+     * generation, before the buffer is discarded. Reflects real playback
+     * length — required to size the editor VO clip's display window so
+     * Remotion's `endAt` doesn't truncate emotive/punctuated deliveries that
+     * the wpm estimate undershoots. Falls back to `voiceoverEstimateMs` when
+     * ffprobe is unavailable.
+     */
+    voiceoverActualMs?: number;
+    /**
+     * AG-28: TTS over-budget signal. True when the line + style produces audio
+     * longer than scene.durationMs * 1.05 even after the executor's atempo
+     * adjustment. Stitcher should freeze-frame-pad rather than clip.
+     */
+    voiceoverOverBudget?: boolean;
+    /**
+     * AG-3: word-level captions transcribed from the resolved VO audio. Stamped
+     * host-side by `resolveSceneCaptions` (NOT the executor — captions need the
+     * uploaded voiceoverUrl, which only exists post-resolveVoiceoverUrl). Times
+     * are ms relative to scene start (== VO audio start). planToProject turns
+     * this into a CaptionClip on the caption track.
+     */
+    captionWords?: Array<{
+        word: string;
+        start: number;
+        end: number;
+    }>;
+}
+export interface SceneOutcome {
+    scene: PlannedScene;
+    ok: boolean;
+    result?: SceneAssetResult;
+    error?: {
+        code: string;
+        message: string;
+        /**
+         * Set when the failure came from a provider-fallback-wrapped tool whose
+         * entire chain exhausted (or terminated on auth/safety/input). Used by
+         * the orchestrator to decide between agent re-plan / scene degrade /
+         * hard fail.
+         */
+        classification?: "transient" | "rate_limit" | "capability" | "safety" | "auth" | "quota" | "input" | "unknown";
+        needsReplan?: boolean;
+        attemptedProviders?: string[];
+    };
+    durationMs: number;
+}
+/**
+ * Inspect a failed scene to decide the next orchestration step.
+ *
+ *   - "replan"  : agent should re-plan the scene (safety / bad input)
+ *   - "degrade" : try a cheaper strategy (e.g. T2/T3 chain exhausted on quota)
+ *   - "fail"    : terminal — surface to user (auth / chain-exhausted-unknown)
+ *   - "retry"   : transient — caller may re-run the scene as-is later
+ */
+export declare function classifySceneFailure(outcome: SceneOutcome): "replan" | "degrade" | "fail" | "retry" | null;
+export interface ExecutorOptions {
+    /** Max scenes to run in parallel. Generation providers rate-limit themselves; this guards on top. */
+    concurrency?: number;
+    /** Inject a recording wrapper (e.g. runToolRecorded) for eval / replay. */
+    runTool?: RunToolFn;
+    /**
+     * Stage 3 hook: invoked after each scene finishes (success OR failure).
+     * Lets the orchestrator stream incremental Project updates into Firestore
+     * so the editor + agent drawer surfaces light up as scenes complete,
+     * rather than waiting for the whole executor to finish. Errors thrown
+     * from the callback are swallowed (logged) so a Firestore blip can't
+     * crash the executor.
+     */
+    onSceneComplete?: (sceneIndex: number, outcome: SceneOutcome) => Promise<void>;
+    /**
+     * Stage 7 slice 1: provider task-id cache (read side). When the upstream
+     * inputs for animate_image / generate_video / generate_avatar_video hash
+     * to the same value as a cached entry (and entry is within TTL), the
+     * executor returns the cached taskId + modelKey and skips the tool call.
+     * /execute passes the project's cache here so re-runs after downstream
+     * (poll/stitch/critic) bugs reuse the prior $$ gens. /regenerate-scene
+     * deliberately omits this (user wants a fresh gen) but still mints.
+     */
+    taskCache?: ProviderTaskCache;
+    /**
+     * Stage 7 slice 1: cache write side. Invoked after a successful tool call
+     * that produced a pendingTaskId. Orchestrator persists the entry on the
+     * AgentProject doc so the NEXT execute can replay. Errors swallowed —
+     * cache is best-effort optimisation, not correctness.
+     */
+    onTaskMint?: (clipId: string, entry: ProviderTaskCacheEntry) => Promise<void>;
+    /**
+     * Gap #1 follow-up (skip-generation). Scene indices whose VISUAL is preserved
+     * verbatim from a prior run (locked / user-placed, unapproved for mutation).
+     * runVisual returns a no-op "frozen" outcome for these — no provider call, no
+     * task minted, no $$ — and planToProject injects the real clip instead of a
+     * placeholder twin. Without this the lock guarantee held but we still PAID to
+     * regenerate footage we immediately discarded.
+     */
+    frozenVisualScenes?: ReadonlySet<number>;
+    /** Gap #1 follow-up. Scene indices whose VOICEOVER is preserved — skip TTS. */
+    frozenVoiceoverScenes?: ReadonlySet<number>;
+}
+/**
+ * Visual outcome shape returned by runVisual — either a resolved visual
+ * (URL or pending task) or a structured scene error.
+ */
+export type VisualOutcome = {
+    ok: true;
+    output: {
+        tool: string;
+        visualUrl?: string;
+        pendingTaskId?: string;
+        pendingModelKey?: string;
+        attemptedProviders?: string[];
+        extendChain?: ExtendChainStep[];
+        attribution?: {
+            name: string;
+            url?: string;
+        };
+    };
+} | {
+    ok: false;
+    error: SceneOutcome["error"];
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/executor/types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySceneFailure = classifySceneFailure;
+/**
+ * Inspect a failed scene to decide the next orchestration step.
+ *
+ *   - "replan"  : agent should re-plan the scene (safety / bad input)
+ *   - "degrade" : try a cheaper strategy (e.g. T2/T3 chain exhausted on quota)
+ *   - "fail"    : terminal — surface to user (auth / chain-exhausted-unknown)
+ *   - "retry"   : transient — caller may re-run the scene as-is later
+ */
+function classifySceneFailure(outcome) {
+    if (outcome.ok)
+        return null;
+    const c = outcome.error?.classification;
+    if (!c)
+        return "fail";
+    if (outcome.error?.needsReplan)
+        return "replan"; // safety / input
+    if (c === "auth")
+        return "fail";
+    if (c === "quota")
+        return "degrade";
+    if (c === "rate_limit" || c === "transient")
+        return "retry";
+    if (c === "capability")
+        return "degrade";
+    return "fail";
+}

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

@@ -0,0 +1,32 @@
+import { PlannedScene, VideoPlan } from "../../../schemas/videoPlan.schema";
+import { ToolContext } from "../toolRegistry";
+import { ProviderTaskCacheEntry } from "../providerTaskCache";
+import { RunToolFn, VisualOutcome } from "./types";
+/**
+ * Per-scene VISUAL resolution — the strategy switch that the Executor delegates
+ * to. Extracted as a free function so the Executor class stays a thin
+ * orchestrator. It receives a `VisualDeps` bundle (the bound Executor helpers
+ * it needs: runTool, the task-cache read/write, and the AG-11b identity-image
+ * publish/resolve) rather than `this`, keeping it independently testable.
+ */
+export interface VisualDeps {
+    runTool: RunToolFn;
+    /**
+     * Gap #1 follow-up — scene indices whose visual is preserved verbatim; a
+     * match returns a no-op "frozen" outcome before any provider call.
+     */
+    frozenVisualScenes?: ReadonlySet<number>;
+    /** Stage 7 slice 1 — task-cache read: cached pending-task or null + the input hash. */
+    checkTaskCache(clipId: string, tool: string, input: Record<string, unknown>): {
+        hit: ProviderTaskCacheEntry | null;
+        inputsHash: string;
+    };
+    /** Stage 7 slice 1 — best-effort task-cache write. */
+    mintTaskCache(clipId: string, entry: ProviderTaskCacheEntry): Promise<void>;
+    /** AG-11b — publish this scene's generated identity still for dependents. */
+    publishIdentityImage(sceneIndex: number, url: string | undefined): void;
+    /** AG-11b — resolve this scene's character-anchor identity still (or undefined). */
+    resolveAnchorIdentityImage(scene: PlannedScene): Promise<string | undefined>;
+}
+export declare function runVisual(deps: VisualDeps, scene: PlannedScene, ctx: ToolContext, aspect: VideoPlan["aspect"], plan: VideoPlan): Promise<VisualOutcome>;
+//# sourceMappingURL=visual.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/executor/visual.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAG5E,OAAO,EAAE,WAAW,EAAe,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,uFAAuF;IACvF,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B;QAAE,GAAG,EAAE,sBAAsB,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,sDAAsD;IACtD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,6EAA6E;IAC7E,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACxE,oFAAoF;IACpF,0BAA0B,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9E;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,EAC3B,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,aAAa,CAAC,CAkdxB"}

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",
+                },
+            };
+        }
+    }
+}