vidspotai-shared 1.0.82 → 1.0.83

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; } });

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