vidspotai-shared 1.0.68 → 1.0.69-dev.0

package/lib/services/agent/runHelpers.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outcomeToRenderOutcome = outcomeToRenderOutcome;
+exports.resolveVoiceoverUrl = resolveVoiceoverUrl;
+exports.writeAgentProjectShell = writeAgentProjectShell;
+exports.writeAgentProjectIncremental = writeAgentProjectIncremental;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const planToProject_1 = require("../editor/planToProject");
+const uploadAudioBuffer_1 = require("../gcp/uploadAudioBuffer");
+const firestore_service_1 = require("../firestore.service");
+const costPreflight_1 = require("./costPreflight");
+const logger_1 = require("../../utils/logger");
+/**
+ * Probe an audio buffer's actual playback duration via ffprobe. Writes the
+ * buffer to a temp file because ffprobe over stdin is finicky with mp3
+ * containers that lack a leading frame header. Returns ms (rounded), or
+ * undefined if ffprobe isn't available or the buffer is unreadable —
+ * callers fall back to the wpm estimate in that case.
+ */
+async function probeAudioBufferMs(buffer, extension) {
+    const dir = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vo-probe-"));
+    const file = (0, node_path_1.join)(dir, `vo.${extension.replace(/^\./, "") || "mp3"}`);
+    try {
+        (0, node_fs_1.writeFileSync)(file, buffer);
+        const seconds = await new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)("ffprobe", [
+                "-v", "error",
+                "-show_entries", "format=duration",
+                "-of", "csv=p=0",
+                file,
+            ]);
+            let out = "";
+            let err = "";
+            child.stdout.on("data", (d) => (out += d.toString()));
+            child.stderr.on("data", (d) => (err += d.toString()));
+            child.on("error", reject);
+            child.on("exit", (code) => code === 0
+                ? resolve(parseFloat(out.trim()))
+                : reject(new Error(`ffprobe exited ${code}: ${err.slice(0, 120)}`)));
+        });
+        if (!Number.isFinite(seconds) || seconds <= 0)
+            return undefined;
+        return Math.round(seconds * 1000);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+    }
+}
+const isoNow = () => new Date().toISOString();
+/**
+ * Map an Executor SceneOutcome to the SceneRenderOutcome shape planToProject
+ * expects. Reads `voiceoverUrl` (set by resolveVoiceoverUrl before this
+ * runs) — not the base64, which would blow Firestore's 1 MiB doc cap.
+ *
+ * Lifted from agent.controller.ts so both the slimmed controller and the
+ * Stage 1 agentRunWorker can import it.
+ */
+function outcomeToRenderOutcome(outcome) {
+    if (!outcome.ok || !outcome.result)
+        return undefined;
+    return {
+        visualUrl: outcome.result.visualUrl,
+        voiceoverUrl: outcome.result.voiceoverUrl,
+        // Prefer probed actual ms (stamped in resolveVoiceoverUrl) over the
+        // wpm estimate — the estimate undershoots emotive/punctuated lines by
+        // 400–900ms and the editor's Remotion Audio hard-truncates at endAt.
+        voiceoverDurationMs: outcome.result.voiceoverActualMs ?? outcome.result.voiceoverEstimateMs,
+        modelKey: outcome.result.pendingModelKey ?? outcome.scene.preferredModel,
+        attemptedProviders: outcome.result.attemptedProviders,
+        generationId: outcome.result.idempotencyKey,
+        // Symmetric with plan-side `estimatePlanCost`: T0 scenes that emit
+        // estimatedCredits=0 from the planner fall back to the per-second
+        // tier curve so the editor's cost chip + agent reconciliation match.
+        creditsSpent: (0, costPreflight_1.estimateSceneCredits)(outcome.scene),
+    };
+}
+/**
+ * Stage 6.e — voiceover persistence. If the scene's executor outcome has
+ * base64 audio (ElevenLabs / generate_voiceover tool output), upload it to
+ * Firebase Storage and mutate the outcome in place so downstream
+ * planToProject calls see a real URL. Idempotent: a second call with the
+ * same outcome (already URL-resolved) is a no-op. Cleans the base64 off
+ * the outcome after upload so the Firestore write doesn't ship the buffer.
+ *
+ * C14: critical for keeping the agentRuns doc under the 1 MiB limit.
+ */
+async function resolveVoiceoverUrl(outcome, projectId) {
+    if (!outcome.ok || !outcome.result)
+        return;
+    const result = outcome.result;
+    if (!result.voiceoverAudioBase64 || result.voiceoverUrl)
+        return;
+    const buffer = Buffer.from(result.voiceoverAudioBase64, "base64");
+    // Probe BEFORE we discard the buffer. Soft-fails: if ffprobe isn't on the
+    // worker (shouldn't happen — stitcher needs it too) the wpm estimate is
+    // still on result.voiceoverEstimateMs and planToProject falls back to it.
+    try {
+        const actualMs = await probeAudioBufferMs(buffer, "mp3");
+        if (actualMs && actualMs > 0) {
+            result.voiceoverActualMs = actualMs;
+            const estimate = result.voiceoverEstimateMs ?? 0;
+            const drift = actualMs - estimate;
+            if (Math.abs(drift) > 250) {
+                logger_1.logger.info("agent.vo.durationDrift", {
+                    projectId,
+                    sceneIndex: outcome.scene.sceneIndex,
+                    estimateMs: estimate,
+                    actualMs,
+                    driftMs: drift,
+                });
+            }
+        }
+    }
+    catch (err) {
+        logger_1.logger.warn("agent.vo.probeFailed", {
+            projectId,
+            sceneIndex: outcome.scene.sceneIndex,
+            err: err.message,
+        });
+    }
+    const destination = `agent-projects/${projectId}/vo/scene-${outcome.scene.sceneIndex}-${Date.now()}.mp3`;
+    const url = await (0, uploadAudioBuffer_1.uploadAudioBufferToGcs)(buffer, destination);
+    result.voiceoverUrl = url;
+    // Drop base64 once URL is stamped so the Firestore write stays small.
+    result.voiceoverAudioBase64 = undefined;
+}
+/**
+ * Stage 3 — write the initial Project shell after the planner approves a
+ * plan. All scene clips exist with placeholder URLs so editor + drawer
+ * surfaces light up immediately; the executor will fill in real URLs
+ * scene-by-scene via the incremental write below.
+ *
+ * C23: critical for keeping the editor / drawer from sitting on an empty
+ * timeline for 20+ minutes while the worker runs.
+ */
+async function writeAgentProjectShell(projectId, plan, agentRunId) {
+    try {
+        const shell = (0, planToProject_1.planToProject)({
+            plan,
+            outcomes: {},
+            projectId,
+            name: `Agent project ${projectId.slice(0, 8)}`,
+            agentRunId,
+        });
+        await firestore_service_1.FirestoreService.agentProjectsCol.doc(projectId).update({
+            projectJson: shell,
+            updatedAt: isoNow(),
+        });
+    }
+    catch (err) {
+        // C25: shell write is best-effort. If it fails, the final write at end
+        // of the worker still produces a valid Project; this just delays the
+        // UI lighting up.
+        logger_1.logger.warn("agent.run.shellWrite", {
+            projectId,
+            err: err.message,
+        });
+    }
+}
+/**
+ * Stage 3 — write a partially-completed Project after each scene
+ * finishes. Rebuilds the full Project from plan + accumulated outcomes
+ * so far (planToProject is pure + cheap), then writes once. Best-effort:
+ * errors logged but not propagated so a Firestore blip doesn't crash
+ * the worker mid-run.
+ *
+ * C24 / C25: per-scene incremental update + soft-fail behavior.
+ */
+async function writeAgentProjectIncremental(projectId, plan, outcomesSoFar, agentRunId) {
+    try {
+        const renderOutcomes = {};
+        for (const [k, o] of Object.entries(outcomesSoFar)) {
+            renderOutcomes[Number(k)] = outcomeToRenderOutcome(o);
+        }
+        const projectJson = (0, planToProject_1.planToProject)({
+            plan,
+            outcomes: renderOutcomes,
+            projectId,
+            name: `Agent project ${projectId.slice(0, 8)}`,
+            agentRunId,
+        });
+        await firestore_service_1.FirestoreService.agentProjectsCol.doc(projectId).update({
+            projectJson,
+            updatedAt: isoNow(),
+        });
+    }
+    catch (err) {
+        logger_1.logger.warn("agent.run.incrementalWrite", {
+            projectId,
+            err: err.message,
+        });
+    }
+}

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

@@ -0,0 +1,90 @@
+/**
+ * Text-layout v1 — per-scene asset vision pass.
+ *
+ * Background: text-layout-spike.md proposes per-scene composition decisions
+ * (full-bleed / blur-fill / split / pip) driven by what's actually in the
+ * scene asset — center-framed subject, talking head, b-roll, etc. The
+ * planner can guess from intent text, but the only way to know reliably is
+ * to look at the rendered first frame.
+ *
+ * This service classifies one image URL using Gemini-2.5-Flash and returns
+ * a structured signal the layout decision tree can consume:
+ *   - contentType: "center" | "edges" | "face" | "broll"
+ *   - focalPoint: normalized {x, y} pointing at the subject's center
+ *
+ * Cost: ~$0.002 per scene (1024×1024 image ≈ 258 tokens × $0.075/1M for
+ * Gemini Flash). Folded into the existing per-scene cost note in
+ * agent-billing.md.
+ *
+ * Mirrors the structure of bibleImageVision.ts — same auth, same MIME
+ * handling, same per-scene isolation: a failure leaves layout unset so the
+ * planner's text-based guess wins.
+ */
+export type SceneContentType = "center" | "edges" | "face" | "broll";
+/**
+ * Luminance band per region of the frame. Drives the auto-contrast pass that
+ * picks a per-overlay bgStyle (shadow / pill / bar) based on where the
+ * overlay sits and how busy that region is.
+ *
+ *  bright = mean luminance > 0.55 → dark text or solid bg needed
+ *  dark   = mean luminance < 0.4  → white text fine, light shadow optional
+ *  mid    = in between           → solid bg recommended (pill or bar)
+ *  busy   = high variance        → solid bg required regardless of luminance
+ */
+export type LuminanceBand = "bright" | "dark" | "mid" | "busy";
+export interface SceneLayoutVisionResult {
+    contentType: SceneContentType;
+    focalPoint: {
+        x: number;
+        y: number;
+    };
+    /** Luminance per region; keys correspond to text-position families. */
+    regions: {
+        top: LuminanceBand;
+        center: LuminanceBand;
+        bottom: LuminanceBand;
+    };
+    /** Raw model text, retained for debugging. */
+    raw: string;
+}
+export interface SceneLayoutVisionConfig {
+    apiKey: string;
+    model?: string;
+    timeoutMs?: number;
+}
+/**
+ * Classify one scene asset. Returns null on any error — caller treats null
+ * as "no vision signal" and falls back to planner-emitted layout or default.
+ */
+export declare function classifySceneLayout(imageUrl: string, config: SceneLayoutVisionConfig): Promise<SceneLayoutVisionResult | null>;
+/**
+ * Pick a `composition` value from a vision signal + source/target aspects.
+ * Mirrors the decision tree in text-layout-spike.md. The planner may have
+ * already set scene.layout.composition; treat that as the prior and only
+ * override here when (a) the planner left it unset, or (b) the vision
+ * classification clearly contradicts the planner choice.
+ *
+ * `sourceAspect` / `targetAspect` are width / height ratios (e.g. 16/9 = 1.78).
+ */
+export declare function pickCompositionFromVision(vision: SceneLayoutVisionResult, sourceAspectRatio: number, targetAspectRatio: number): "full-bleed" | "letterbox" | "blur-fill" | "split-top" | "split-bottom" | "pip-bottom-right";
+/**
+ * Map a TextPosition to the luminance region that sits under it. Used by
+ * the auto-contrast pass to pick a per-overlay bgStyle / color.
+ */
+export declare function regionForPosition(position: string | undefined): "top" | "center" | "bottom";
+/**
+ * Pick a (bgStyle, color) pair for an overlay sitting on a given luminance
+ * region. The four bands map to clear treatments:
+ *   bright  → dark text + pill bg (white text would vanish)
+ *   dark    → white text + shadow (cheap, doesn't fight content)
+ *   mid     → white text + pill bg (uniform tone reads fine with chrome)
+ *   busy    → white text + bar bg (only solid fill kills the noise)
+ *
+ * Returns `null` when the overlay already has an explicit bgStyle from the
+ * planner — auto-contrast is a fallback, never overrides intentional choices.
+ */
+export declare function autoContrastFor(band: LuminanceBand): {
+    bgStyle: "shadow" | "pill" | "bar";
+    color: string;
+};
+//# sourceMappingURL=sceneLayoutVision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sceneLayoutVision.d.ts","sourceRoot":"","sources":["../../../src/services/agent/sceneLayoutVision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/D,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,UAAU,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,uEAAuE;IACvE,OAAO,EAAE;QACP,GAAG,EAAE,aAAa,CAAC;QACnB,MAAM,EAAE,aAAa,CAAC;QACtB,MAAM,EAAE,aAAa,CAAC;KACvB,CAAC;IACF,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgCD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAuDzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,uBAAuB,EAC/B,iBAAiB,EAAE,MAAM,EACzB,iBAAiB,EAAE,MAAM,GACxB,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,kBAAkB,CAqB9F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAkB7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,GAClB;IAAE,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAWvD"}

package/lib/services/agent/sceneLayoutVision.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Text-layout v1 — per-scene asset vision pass.
+ *
+ * Background: text-layout-spike.md proposes per-scene composition decisions
+ * (full-bleed / blur-fill / split / pip) driven by what's actually in the
+ * scene asset — center-framed subject, talking head, b-roll, etc. The
+ * planner can guess from intent text, but the only way to know reliably is
+ * to look at the rendered first frame.
+ *
+ * This service classifies one image URL using Gemini-2.5-Flash and returns
+ * a structured signal the layout decision tree can consume:
+ *   - contentType: "center" | "edges" | "face" | "broll"
+ *   - focalPoint: normalized {x, y} pointing at the subject's center
+ *
+ * Cost: ~$0.002 per scene (1024×1024 image ≈ 258 tokens × $0.075/1M for
+ * Gemini Flash). Folded into the existing per-scene cost note in
+ * agent-billing.md.
+ *
+ * Mirrors the structure of bibleImageVision.ts — same auth, same MIME
+ * handling, same per-scene isolation: a failure leaves layout unset so the
+ * planner's text-based guess wins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifySceneLayout = classifySceneLayout;
+exports.pickCompositionFromVision = pickCompositionFromVision;
+exports.regionForPosition = regionForPosition;
+exports.autoContrastFor = autoContrastFor;
+const genai_1 = require("@google/genai");
+const logger_1 = require("../../utils/logger");
+const DEFAULT_MODEL = "gemini-2.5-flash";
+const CLASSIFY_PROMPT = [
+    "Classify this image for video composition.",
+    "Reply in this EXACT format on a single line, nothing else:",
+    "contentType=<center|edges|face|broll>; focal=<x>,<y>; lum=<top>,<center>,<bottom>",
+    "",
+    "Where contentType is:",
+    "- center: the main subject is centered and crop-safe",
+    "- edges: the key elements sit near the edges (wide scene, text/logos at margins)",
+    "- face: a person's face is the subject (talking head, portrait)",
+    "- broll: abstract / b-roll / no key subject (pattern, landscape, generic motion)",
+    "",
+    "focal is the (x,y) of the subject's center, normalized 0.0–1.0 where",
+    "(0,0)=top-left and (1,1)=bottom-right. For broll/no subject, use 0.5,0.5.",
+    "",
+    "lum reports the brightness/busyness of three horizontal bands (top third,",
+    "middle third, bottom third). Each band is ONE of: bright, dark, mid, busy.",
+    "- bright: predominantly light (white/pale)",
+    "- dark: predominantly dark",
+    "- mid: medium tone, fairly uniform",
+    "- busy: high contrast variation (a mix of light and dark with detail) —",
+    "  text without a solid background would be unreadable here",
+    "",
+    'Example: "contentType=face; focal=0.5,0.35; lum=mid,bright,dark"',
+].join("\n");
+const RESPONSE_RE = /contentType\s*=\s*(center|edges|face|broll)\s*;\s*focal\s*=\s*([\d.]+)\s*,\s*([\d.]+)\s*;\s*lum\s*=\s*(bright|dark|mid|busy)\s*,\s*(bright|dark|mid|busy)\s*,\s*(bright|dark|mid|busy)/i;
+/**
+ * Classify one scene asset. Returns null on any error — caller treats null
+ * as "no vision signal" and falls back to planner-emitted layout or default.
+ */
+async function classifySceneLayout(imageUrl, config) {
+    const model = config.model ?? DEFAULT_MODEL;
+    const timeoutMs = config.timeoutMs ?? 20000;
+    const ai = new genai_1.GoogleGenAI({ apiKey: config.apiKey });
+    try {
+        const controller = new AbortController();
+        const t = setTimeout(() => controller.abort(), timeoutMs);
+        let bytes;
+        let mimeType;
+        try {
+            const r = await fetch(imageUrl, { signal: controller.signal });
+            if (!r.ok)
+                throw new Error(`fetch ${r.status} ${r.statusText}`);
+            bytes = Buffer.from(await r.arrayBuffer());
+            mimeType = pickImageMimeType(r.headers.get("content-type"), imageUrl);
+        }
+        finally {
+            clearTimeout(t);
+        }
+        const resp = await ai.models.generateContent({
+            model,
+            contents: [
+                {
+                    role: "user",
+                    parts: [
+                        { text: CLASSIFY_PROMPT },
+                        { inlineData: { mimeType, data: bytes.toString("base64") } },
+                    ],
+                },
+            ],
+            config: { temperature: 0 },
+        });
+        const raw = (resp.text ?? "").trim();
+        const m = RESPONSE_RE.exec(raw);
+        if (!m) {
+            logger_1.logger.warn("sceneLayoutVision: unparseable response", { raw, imageUrl });
+            return null;
+        }
+        const contentType = m[1].toLowerCase();
+        const fx = clamp01(Number(m[2]));
+        const fy = clamp01(Number(m[3]));
+        const regions = {
+            top: m[4].toLowerCase(),
+            center: m[5].toLowerCase(),
+            bottom: m[6].toLowerCase(),
+        };
+        return { contentType, focalPoint: { x: fx, y: fy }, regions, raw };
+    }
+    catch (err) {
+        logger_1.logger.warn("sceneLayoutVision: failed", {
+            imageUrl,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}
+/**
+ * Pick a `composition` value from a vision signal + source/target aspects.
+ * Mirrors the decision tree in text-layout-spike.md. The planner may have
+ * already set scene.layout.composition; treat that as the prior and only
+ * override here when (a) the planner left it unset, or (b) the vision
+ * classification clearly contradicts the planner choice.
+ *
+ * `sourceAspect` / `targetAspect` are width / height ratios (e.g. 16/9 = 1.78).
+ */
+function pickCompositionFromVision(vision, sourceAspectRatio, targetAspectRatio) {
+    const sameAspect = Math.abs(sourceAspectRatio - targetAspectRatio) < 0.05;
+    if (sameAspect)
+        return "full-bleed";
+    // Source is wider than target (e.g. 16:9 stock on 9:16 TikTok).
+    if (sourceAspectRatio > targetAspectRatio + 0.1) {
+        switch (vision.contentType) {
+            case "center":
+                return "full-bleed"; // safe to crop sides
+            case "face":
+                return "blur-fill"; // keep whole face in frame
+            case "edges":
+                return "blur-fill"; // crop would lose key elements
+            case "broll":
+                return "split-bottom"; // good for caption-strip overlays on bottom
+        }
+    }
+    // Source is taller than target (e.g. 9:16 on 16:9 desktop).
+    // Vertical assets on horizontal targets can't fill cleanly — PIP it.
+    return "pip-bottom-right";
+}
+/**
+ * Map a TextPosition to the luminance region that sits under it. Used by
+ * the auto-contrast pass to pick a per-overlay bgStyle / color.
+ */
+function regionForPosition(position) {
+    switch (position) {
+        case "top":
+        case "top-left":
+        case "top-right":
+        case "top-banner":
+            return "top";
+        case "center":
+        case "left-rail":
+            return "center";
+        case "lower-third":
+        case "bottom":
+        case "bottom-left":
+        case "bottom-right":
+        case "caption-strip":
+        default:
+            return "bottom";
+    }
+}
+/**
+ * Pick a (bgStyle, color) pair for an overlay sitting on a given luminance
+ * region. The four bands map to clear treatments:
+ *   bright  → dark text + pill bg (white text would vanish)
+ *   dark    → white text + shadow (cheap, doesn't fight content)
+ *   mid     → white text + pill bg (uniform tone reads fine with chrome)
+ *   busy    → white text + bar bg (only solid fill kills the noise)
+ *
+ * Returns `null` when the overlay already has an explicit bgStyle from the
+ * planner — auto-contrast is a fallback, never overrides intentional choices.
+ */
+function autoContrastFor(band) {
+    switch (band) {
+        case "bright":
+            return { bgStyle: "pill", color: "#0b1220" };
+        case "dark":
+            return { bgStyle: "shadow", color: "#ffffff" };
+        case "mid":
+            return { bgStyle: "pill", color: "#ffffff" };
+        case "busy":
+            return { bgStyle: "bar", color: "#ffffff" };
+    }
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0.5;
+    return Math.max(0, Math.min(1, n));
+}
+function pickImageMimeType(headerType, url) {
+    const hdr = (headerType ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+    if (hdr.startsWith("image/"))
+        return hdr;
+    const lower = url.toLowerCase();
+    if (lower.includes(".png"))
+        return "image/png";
+    if (lower.includes(".webp"))
+        return "image/webp";
+    if (lower.includes(".gif"))
+        return "image/gif";
+    if (lower.includes(".heic"))
+        return "image/heic";
+    return "image/jpeg";
+}

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

@@ -0,0 +1,136 @@
+import { VideoPlan } from "../../schemas/videoPlan.schema";
+/**
+ * AG-26: Stitched-video critic — the gate that catches everything the
+ * per-scene critic misses.
+ *
+ * The existing `Critic` operates on per-scene asset URLs + the plan. That
+ * misses anything that only becomes visible once the scenes are concatenated:
+ *   - voiceover clipped / cut off / audibly truncated
+ *   - jarring cuts (no rhythm, no music bed to disguise it)
+ *   - character drift visible only when scenes play back-to-back
+ *   - brand text degradation across cuts (the human eye notices "Hydropure
+ *     → HydraPure → HydrraPure" instantly when watching; per-frame critique
+ *     gives each scene a pass)
+ *   - missing or 404 music track
+ *   - overall pacing / hook → reveal → CTA arc as a viewer experiences it
+ *
+ * Implementation: call Gemini 2.5 Flash with the stitched MP4 file_uri.
+ * Gemini accepts video + audio natively, tokenizes ~258 tok/sec of video,
+ * so a 15s clip is ~4k input tokens → ~$0.0003 / critique. Essentially free.
+ *
+ * Returns structured findings in the same shape as the per-scene Critic so
+ * the orchestrator can merge both into a single review.
+ */
+import { z } from "zod";
+export declare const StitchedVideoFindingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        fail: "fail";
+        warn: "warn";
+        pass: "pass";
+    }>;
+    dimension: z.ZodEnum<{
+        hookStrength: "hookStrength";
+        pacingFit: "pacingFit";
+        characterContinuity: "characterContinuity";
+        brandTextLegibility: "brandTextLegibility";
+        cutRhythm: "cutRhythm";
+        voiceoverClarity: "voiceoverClarity";
+        voiceoverEmotionMatch: "voiceoverEmotionMatch";
+        voiceoverPacing: "voiceoverPacing";
+        audioMixBalance: "audioMixBalance";
+        musicPresence: "musicPresence";
+        ctaPresence: "ctaPresence";
+        overallImpression: "overallImpression";
+        actionPlausibility: "actionPlausibility";
+    }>;
+    message: z.ZodString;
+    sceneIndexHint: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type StitchedVideoFinding = z.infer<typeof StitchedVideoFindingSchema>;
+export declare const StitchedVideoReviewSchema: z.ZodObject<{
+    score: z.ZodNumber;
+    shippable: z.ZodBoolean;
+    summary: z.ZodString;
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            fail: "fail";
+            warn: "warn";
+            pass: "pass";
+        }>;
+        dimension: z.ZodEnum<{
+            hookStrength: "hookStrength";
+            pacingFit: "pacingFit";
+            characterContinuity: "characterContinuity";
+            brandTextLegibility: "brandTextLegibility";
+            cutRhythm: "cutRhythm";
+            voiceoverClarity: "voiceoverClarity";
+            voiceoverEmotionMatch: "voiceoverEmotionMatch";
+            voiceoverPacing: "voiceoverPacing";
+            audioMixBalance: "audioMixBalance";
+            musicPresence: "musicPresence";
+            ctaPresence: "ctaPresence";
+            overallImpression: "overallImpression";
+            actionPlausibility: "actionPlausibility";
+        }>;
+        message: z.ZodString;
+        sceneIndexHint: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type StitchedVideoReview = z.infer<typeof StitchedVideoReviewSchema>;
+export interface StitchedVideoCriticInput {
+    /** Public/signed URL to the stitched MP4 (with audio). */
+    videoUrl: string;
+    /** Plan that produced the video — gives the critic the spec to grade against. */
+    plan: VideoPlan;
+    /**
+     * Optional Whisper transcript of the voiceover (audio-only diff against the
+     * planner's voiceoverLine values). When supplied, the critic uses it as
+     * ground truth instead of trying to lip-read.
+     */
+    whisperTranscript?: string;
+    /**
+     * Optional ffmpeg-derived audio stats so the critic doesn't have to
+     * re-derive them: { meanDb, maxDb, longestSilenceMs }. Cheap pre-pass.
+     */
+    audioStats?: {
+        meanDb?: number;
+        maxDb?: number;
+        longestSilenceMs?: number;
+    };
+    /**
+     * AG-35: Ground-truth flags from the stitcher so the critic can't
+     * hallucinate audio elements that were never rendered. Gemini was
+     * confidently describing "calm piano music" on a track where the music
+     * URL 404'd and was dropped — feeding the actual stitch outcome in
+     * forces it to grade what was shipped, not what was planned.
+     */
+    groundTruth?: {
+        hasVoiceover?: boolean;
+        hasMusic?: boolean;
+        /** Total audio track present on the muxed file (voice OR music). */
+        hasAudio?: boolean;
+        /** Notes about scenes that fell back, models that were skipped, etc. */
+        notes?: string[];
+    };
+}
+/**
+ * Build the rubric prompt the Gemini call receives alongside the video. Kept
+ * outside the API caller so unit tests can snapshot it.
+ */
+export declare function buildStitchedCriticPrompt(input: StitchedVideoCriticInput): string;
+/**
+ * Run the critic. Caller passes an `invokeGemini` function so this module
+ * stays decoupled from the LLM gateway. Real wiring lives in
+ * `agent/stitchedVideoCritic.gemini.ts` (added separately so tests can mock
+ * the boundary).
+ *
+ * Soft-fails: on any error returns a single warn finding with the error
+ * message so the orchestrator can still surface "we couldn't auto-review"
+ * to the user without crashing the run.
+ */
+export declare function runStitchedVideoCritic(input: StitchedVideoCriticInput, invokeGemini: (args: {
+    prompt: string;
+    videoUrl: string;
+    responseSchema: z.ZodType<StitchedVideoReview>;
+}) => Promise<StitchedVideoReview>): Promise<StitchedVideoReview>;
+//# sourceMappingURL=stitchedVideoCritic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stitchedVideoCritic.d.ts","sourceRoot":"","sources":["../../../src/services/agent/stitchedVideoCritic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;iBAqBrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,MAAM,WAAW,wBAAwB;IACvC,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,IAAI,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF;;;;;;OAMG;IACH,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,oEAAoE;QACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,wEAAwE;QACxE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAmEjF;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,wBAAwB,EAC/B,YAAY,EAAE,CAAC,IAAI,EAAE;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChD,KAAK,OAAO,CAAC,mBAAmB,CAAC,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAwB9B"}

package/lib/services/agent/stitchedVideoCritic.gemini.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { StitchedVideoReview } from "./stitchedVideoCritic";
+import { PerSceneReview } from "./perSceneCritic";
+export interface GeminiCriticConfig {
+    apiKey: string;
+    model?: string;
+    /** Cap total wait for download + upload + analyse. */
+    timeoutMs?: number;
+}
+export declare function buildGeminiCriticInvoker(config: GeminiCriticConfig): (args: {
+    prompt: string;
+    videoUrl: string;
+    responseSchema: z.ZodType<StitchedVideoReview>;
+}) => Promise<StitchedVideoReview>;
+/**
+ * AG-43: Gemini invoker for the per-scene critic. Same upload/poll/generate
+ * flow as the stitched-critic invoker; differs only in the response schema
+ * (PerSceneReviewSchema). Kept as a separate factory so the typing stays
+ * tight at the call site.
+ */
+export declare function buildGeminiPerSceneCriticInvoker(config: GeminiCriticConfig): (args: {
+    prompt: string;
+    videoUrl: string;
+    responseSchema: z.ZodType<PerSceneReview>;
+}) => Promise<PerSceneReview>;
+//# sourceMappingURL=stitchedVideoCritic.gemini.d.ts.map

package/lib/services/agent/stitchedVideoCritic.gemini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stitchedVideoCritic.gemini.d.ts","sourceRoot":"","sources":["../../../src/services/agent/stitchedVideoCritic.gemini.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,mBAAmB,EAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAwB,MAAM,kBAAkB,CAAC;AAwBxE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAOD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,IAKnD,MAAM;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAChD,KAAG,OAAO,CAAC,mBAAmB,CAAC,CA+FjC;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,kBAAkB,IAK3D,MAAM;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3C,KAAG,OAAO,CAAC,cAAc,CAAC,CAwD5B"}