vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/tools/generateAvatarVideo.tool.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAvatarVideoTool = void 0;
+const zod_1 = require("zod");
+const aiModels_1 = require("../../../globals/aiModels");
+const firebase_1 = require("../../../libs/firebase");
+const aiGenFactory_service_1 = require("../../aiGen/aiGenFactory.service");
+const types_1 = require("../../aiGen/types");
+const rateLimiter_1 = require("../../rateLimiter");
+const ttsFactory_service_1 = require("../../tts/ttsFactory.service");
+const toolRegistry_1 = require("../toolRegistry");
+/**
+ * generate_avatar_video — wraps the existing kling-avatar pipeline so the
+ * planner's `talking-head-avatar` scene strategy is executable. Accepts a
+ * presenter face image URL plus either a pre-uploaded audio URL or raw TTS
+ * text (in which case the tool synthesizes via ElevenLabs and uploads to GCS
+ * before handing off, since Kling avatar requires a public sound_file URL).
+ *
+ * Returns a provider task id; the executor / monitor layer polls completion
+ * exactly as it does for generate_video.
+ */
+const InputSchema = zod_1.z
+    .object({
+    inputImageUrl: zod_1.z
+        .string()
+        .url()
+        .describe("Presenter face still — Kling animates this image to lipsync the audio."),
+    ttsText: zod_1.z
+        .string()
+        .min(1)
+        .optional()
+        .describe("VO line to synthesize. Either ttsText or inputAudioUrl must be set; if both are set, inputAudioUrl wins."),
+    inputAudioUrl: zod_1.z
+        .string()
+        .url()
+        .optional()
+        .describe("Pre-uploaded audio URL (mp3/wav). Skips internal TTS+upload."),
+    voiceId: zod_1.z.string().optional(),
+    languageCode: zod_1.z.string().optional(),
+    mode: zod_1.z.enum(["std", "pro"]).default("std"),
+    prompt: zod_1.z
+        .string()
+        .optional()
+        .describe("Optional motion/emotion hint passed through to Kling."),
+})
+    .superRefine((v, ctx) => {
+    if (!v.ttsText && !v.inputAudioUrl) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: "Either ttsText or inputAudioUrl is required.",
+        });
+    }
+});
+const OutputSchema = zod_1.z.object({
+    status: zod_1.z.literal("triggered"),
+    taskId: zod_1.z.string(),
+    audioUrl: zod_1.z.string().url().describe("Audio URL fed to Kling — host can reuse for caption sync."),
+});
+exports.generateAvatarVideoTool = {
+    name: "generate_avatar_video",
+    description: [
+        "Generate a talking-head avatar video by animating a presenter face still",
+        "to lipsync a voiceover. Wraps the kling-avatar provider.",
+        "Use this for the `talking-head-avatar` scene strategy. Do NOT use it for",
+        "general motion shots — generate_video is cheaper and more flexible there.",
+        "Examples:",
+        '  { inputImageUrl: "https://.../face.png", ttsText: "Hi, today we\'re testing the new serum." }',
+        '  { inputImageUrl: "https://.../face.png", inputAudioUrl: "https://.../vo.mp3", mode: "pro" }',
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    idempotent: false,
+    estimateCost: async (input) => {
+        // Kling avatar bills per audio second. Without a length we assume 6s (typical scene).
+        const approxSec = input.ttsText ? Math.max(2, Math.ceil(input.ttsText.length / 15)) : 6;
+        const perSec = input.mode === "pro" ? 0.028 : 0.014;
+        return Math.ceil(approxSec * perSec * 100); // rough credit conversion
+    },
+    handler: async (input, ctx) => {
+        let audioUrl = input.inputAudioUrl;
+        if (!audioUrl) {
+            const ttsLimiter = (0, rateLimiter_1.getTtsProviderRateLimiter)("elevenlabs");
+            await ttsLimiter.waitUntilAvailable();
+            let ttsResult;
+            try {
+                const tts = (0, ttsFactory_service_1.getTtsProviderService)("elevenlabs");
+                ttsResult = await tts.generate({
+                    text: input.ttsText,
+                    voiceId: input.voiceId,
+                    languageCode: input.languageCode,
+                });
+            }
+            finally {
+                // Sync call — slot freed immediately on return (success or throw).
+                ttsLimiter.releaseSlot();
+            }
+            const filePath = `agent-avatar-audio/${ctx.userId}/${ctx.agentRunId}-${Date.now()}.${ttsResult.extension}`;
+            const file = (0, firebase_1.getBucket)().file(filePath);
+            await file.save(ttsResult.audioBuffer, { contentType: ttsResult.mimeType });
+            const [signedUrl] = await file.getSignedUrl({ action: "read", expires: "03-09-2491" });
+            audioUrl = signedUrl;
+        }
+        // Hold the Kling-avatar slot through return — host's TaskPoller releases
+        // when the task settles. Release here on submit error.
+        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(aiModels_1.EVideoGenModels.KLING_AVATAR);
+        await limiter.waitUntilAvailable();
+        let heldSlot = true;
+        try {
+            const provider = (0, aiGenFactory_service_1.getAiGenProviderService)(aiModels_1.EVideoGenModels.KLING_AVATAR);
+            // No `type` — kling-avatar's modelConfig.type is ["avatar-video"], which is
+            // outside the VideoGenerationParams.type union. Setting type:"image-to-video"
+            // here trips validateParams (image-to-video branch requires the model's
+            // config.type to include "image-to-video", which avatar's doesn't). The
+            // kling provider routes by modelKey === "kling-avatar" before any
+            // type-based dispatch, so omitting type is correct.
+            const result = await provider.generateVideo({
+                modelKey: aiModels_1.EVideoGenModels.KLING_AVATAR,
+                prompt: input.prompt,
+                inputImageUrl: input.inputImageUrl,
+                inputAudioUrl: audioUrl,
+                mode: input.mode === "pro" ? types_1.EVideoMode.PROFESSIONAL : types_1.EVideoMode.STANDARD,
+            });
+            const taskId = result.task?.taskId ??
+                result.task?.id ??
+                (typeof result.task === "string" ? result.task : "unknown");
+            if (taskId === "unknown") {
+                limiter.releaseSlot();
+                heldSlot = false;
+            }
+            return {
+                status: "triggered",
+                taskId,
+                audioUrl: audioUrl,
+            };
+        }
+        catch (err) {
+            if (heldSlot)
+                limiter.releaseSlot();
+            throw err;
+        }
+    },
+};
+(0, toolRegistry_1.registerTool)(exports.generateAvatarVideoTool);

package/lib/services/agent/tools/generateCaptions.tool.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { ToolDefinition } from "../toolRegistry";
+declare const InputSchema: z.ZodObject<{
+    audioUrl: z.ZodString;
+    provider: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        whisper: "whisper";
+        assemblyai: "assemblyai";
+    }>>;
+    languageCode: z.ZodOptional<z.ZodString>;
+    wordTimestamps: z.ZodDefault<z.ZodBoolean>;
+    speakerLabels: z.ZodDefault<z.ZodBoolean>;
+    redactPii: z.ZodDefault<z.ZodBoolean>;
+    maxInlinePollMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const OutputSchema: z.ZodObject<{
+    text: z.ZodString;
+    audioDurationSec: z.ZodOptional<z.ZodNumber>;
+    words: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        speaker: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    utterances: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        speaker: z.ZodString;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    providerUsed: z.ZodEnum<{
+        whisper: "whisper";
+        assemblyai: "assemblyai";
+    }>;
+    pending: z.ZodOptional<z.ZodBoolean>;
+    pendingId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const generateCaptionsTool: ToolDefinition<typeof InputSchema, typeof OutputSchema>;
+export {};
+//# sourceMappingURL=generateCaptions.tool.d.ts.map

package/lib/services/agent/tools/generateCaptions.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateCaptions.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateCaptions.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAS/D,QAAA,MAAM,WAAW;;;;;;;;;;;;iBAuCf,CAAC;AAkBH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;iBAShB,CAAC;AAIH,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAC/C,OAAO,WAAW,EAClB,OAAO,YAAY,CAsEpB,CAAC"}

package/lib/services/agent/tools/generateCaptions.tool.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateCaptionsTool = void 0;
+const zod_1 = require("zod");
+const assemblyai_service_1 = require("../../asr/assemblyai.service");
+const whisper_service_1 = require("../../asr/whisper.service");
+const assetCache_service_1 = require("../../assetCache.service");
+const logger_1 = require("../../../utils/logger");
+const toolRegistry_1 = require("../toolRegistry");
+/**
+ * Caption transcripts are deterministic per (audio bytes, params), so we
+ * cache by the input URL. Long enough to outlive a multi-scene render
+ * (~30 min) without keeping stale transcripts forever.
+ */
+const CAPTIONS_CACHE_TTL_MS = 60 * 60 * 1000;
+const InputSchema = zod_1.z.object({
+    audioUrl: zod_1.z.string().url().describe("HTTPS URL of the audio (or audio-track-on-video) to transcribe."),
+    provider: zod_1.z
+        .enum(["assemblyai", "whisper", "auto"])
+        .default("auto")
+        .describe("Primary ASR provider. 'auto' tries assemblyai first then falls back to whisper on failure (recommended). " +
+        "'assemblyai' = highest quality, diarization, ~$0.15/hr, async. " +
+        "'whisper' = OpenAI fallback, no diarization, ~$0.36/hr, sync, 25 MB cap."),
+    languageCode: zod_1.z
+        .string()
+        .optional()
+        .describe('Locale hint, e.g. "en", "fr". Omit to let the provider auto-detect.'),
+    wordTimestamps: zod_1.z
+        .boolean()
+        .default(true)
+        .describe("Return per-word start/end timestamps. Required for karaoke-style caption tracks."),
+    speakerLabels: zod_1.z
+        .boolean()
+        .default(false)
+        .describe("Diarization (speaker labels). AssemblyAI-only — Whisper fallback ignores this and logs a warning."),
+    redactPii: zod_1.z
+        .boolean()
+        .default(false)
+        .describe("Redact PII (SSN, credit cards, email, phone). AssemblyAI-only — Whisper fallback returns unredacted text."),
+    maxInlinePollMs: zod_1.z
+        .number()
+        .int()
+        .min(10000)
+        .max(180000)
+        .default(120000)
+        .describe("Inline-poll budget for AssemblyAI submit→complete (ms). Longer media should be routed through the BullMQ async path by the caller."),
+});
+const WordSchema = zod_1.z.object({
+    text: zod_1.z.string(),
+    start: zod_1.z.number().describe("Word start in milliseconds."),
+    end: zod_1.z.number().describe("Word end in milliseconds."),
+    confidence: zod_1.z.number().optional(),
+    speaker: zod_1.z.string().optional(),
+});
+const UtteranceSchema = zod_1.z.object({
+    text: zod_1.z.string(),
+    start: zod_1.z.number(),
+    end: zod_1.z.number(),
+    speaker: zod_1.z.string(),
+    confidence: zod_1.z.number().optional(),
+});
+const OutputSchema = zod_1.z.object({
+    text: zod_1.z.string().describe("Plain-text transcript."),
+    audioDurationSec: zod_1.z.number().optional(),
+    words: zod_1.z.array(WordSchema).describe("Word-level timing for karaoke / caption rendering."),
+    utterances: zod_1.z.array(UtteranceSchema).describe("Per-utterance segments when diarization was requested."),
+    providerUsed: zod_1.z.enum(["assemblyai", "whisper"]).describe("Which provider actually fulfilled the request."),
+    /** True when the call ran past the inline-poll budget and the caller must re-fetch by id later. */
+    pending: zod_1.z.boolean().optional(),
+    pendingId: zod_1.z.string().optional(),
+});
+exports.generateCaptionsTool = {
+    name: "generate_captions",
+    description: [
+        "Transcribe an audio (or audio-from-video) URL into word-timed captions for overlay on a render.",
+        "Default provider is AssemblyAI (best quality + diarization + PII redaction); on transient failure",
+        "or unavailability the tool auto-falls-back to OpenAI Whisper. Use this whenever the brief calls",
+        "for on-screen captions, subtitle tracks, or per-word karaoke effects — NOT for in-scene voiceover",
+        "(use generate_voiceover for that).",
+        "Examples:",
+        '  { audioUrl: "https://storage/.../vo.mp3" }',
+        '  { audioUrl: "https://storage/.../interview.mp3", speakerLabels: true, languageCode: "en" }',
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    idempotent: true,
+    estimateCost: async () => 1,
+    handler: async (input, ctx) => {
+        // Cache key intentionally excludes maxInlinePollMs — it changes polling
+        // behaviour but not the transcript.
+        const cacheParts = {
+            provider: `asr:${input.provider}`,
+            kind: "captions",
+            input: {
+                audioUrl: input.audioUrl,
+                languageCode: input.languageCode,
+                wordTimestamps: input.wordTimestamps,
+                speakerLabels: input.speakerLabels,
+                redactPii: input.redactPii,
+            },
+        };
+        const hit = await assetCache_service_1.RawAssetCacheService.lookup(cacheParts);
+        if (hit)
+            return hit;
+        const wantPrimary = input.provider === "assemblyai" || input.provider === "auto";
+        const wantFallback = input.provider === "whisper" || input.provider === "auto";
+        let primaryErr;
+        if (wantPrimary) {
+            try {
+                const out = await runAssemblyAI(input);
+                await cacheIfComplete(cacheParts, out);
+                return out;
+            }
+            catch (err) {
+                primaryErr = err;
+                logger_1.logger.warn("generate_captions: AssemblyAI failed, evaluating fallback", {
+                    agentRunId: ctx?.agentRunId,
+                    audioUrl: input.audioUrl,
+                    err: err instanceof Error ? err.stack ?? err.message : String(err),
+                });
+                if (!wantFallback)
+                    throw err;
+            }
+        }
+        try {
+            const out = await runWhisper(input);
+            await cacheIfComplete(cacheParts, out);
+            return out;
+        }
+        catch (err) {
+            logger_1.logger.error("generate_captions: both providers failed", {
+                agentRunId: ctx?.agentRunId,
+                audioUrl: input.audioUrl,
+                primary: primaryErr?.message,
+                fallback: err instanceof Error ? err.stack ?? err.message : String(err),
+            });
+            throw new Error(`generate_captions failed on all providers. primary=${primaryErr?.message ?? "n/a"} fallback=${err?.message ?? "n/a"}`);
+        }
+    },
+};
+async function runAssemblyAI(input) {
+    const asr = new assemblyai_service_1.AssemblyAIService();
+    const result = await asr.transcribe({
+        audioUrl: input.audioUrl,
+        languageCode: input.languageCode,
+        speakerLabels: input.speakerLabels,
+        redactPii: input.redactPii,
+        wordTimestamps: input.wordTimestamps,
+    }, { timeoutMs: input.maxInlinePollMs });
+    return toCaptionsOutput(result, "assemblyai");
+}
+async function runWhisper(input) {
+    const asr = new whisper_service_1.WhisperAsrService();
+    const result = await asr.transcribe({
+        audioUrl: input.audioUrl,
+        languageCode: input.languageCode,
+        speakerLabels: input.speakerLabels,
+        redactPii: input.redactPii,
+        wordTimestamps: input.wordTimestamps,
+    });
+    return toCaptionsOutput(result, "whisper");
+}
+function toCaptionsOutput(result, providerUsed) {
+    if (result.status === "error") {
+        throw new Error(`ASR provider returned error: ${result.errorMessage ?? "unknown"}`);
+    }
+    const pending = result.status !== "completed";
+    return {
+        text: result.text ?? "",
+        audioDurationSec: result.audioDuration,
+        words: (result.words ?? []).map((w) => ({
+            text: w.text,
+            start: w.start,
+            end: w.end,
+            confidence: w.confidence,
+            speaker: w.speaker,
+        })),
+        utterances: (result.utterances ?? []).map((u) => ({
+            text: u.text,
+            start: u.start,
+            end: u.end,
+            speaker: u.speaker,
+            confidence: u.confidence,
+        })),
+        providerUsed,
+        ...(pending ? { pending: true, pendingId: result.id } : {}),
+    };
+}
+async function cacheIfComplete(cacheParts, out) {
+    if (out.pending)
+        return; // never cache a partial result
+    void assetCache_service_1.RawAssetCacheService.store(cacheParts, out, {
+        ttlMs: CAPTIONS_CACHE_TTL_MS,
+    }).catch(() => undefined);
+}
+(0, toolRegistry_1.registerTool)(exports.generateCaptionsTool);

package/lib/services/agent/tools/generateImage.tool.d.ts

@@ -0,0 +1,74 @@
+/**
+ * generate_image agent tool.
+ *
+ * Re-enabled 2026-05-17 (was previously fenced when only the disabled FAL
+ * provider existed). Now dispatches via getAiGenProviderService() so it works
+ * against every image model registered in imageServicesMap (Google Imagen +
+ * Nano Banana, OpenAI gpt-image, ByteDance Seedream, Kling Kolors, Alibaba
+ * Qwen, MiniMax image-01, Runway Gen-4 Image).
+ *
+ * Defaults to google-nano-banana — cheapest image-gen we have that ALSO
+ * supports multi-image reference inputs (key requirement for AG-13 / C2
+ * reference-image anchoring). Switch via modelKey when a higher tier is
+ * worth it (gpt-image-1 for hero shots, runwayml-gen4-image for cinematic).
+ *
+ * Supports image-to-image / instruction edits via `inputImageUrl` (single
+ * ref, legacy) or `inputImageUrls` (multi-ref — used by AG-13 to thread the
+ * character + product reference images into every scene's image gen).
+ */
+import { z } from "zod";
+import { ToolDefinition } from "../toolRegistry";
+declare const InputSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    modelKey: z.ZodDefault<z.ZodEnum<{
+        "google-imagen-4-ultra": "google-imagen-4-ultra";
+        "google-imagen-4": "google-imagen-4";
+        "google-imagen-4-fast": "google-imagen-4-fast";
+        "google-nano-banana-pro": "google-nano-banana-pro";
+        "google-nano-banana": "google-nano-banana";
+        "openai-gpt-image-2": "openai-gpt-image-2";
+        "openai-gpt-image-1.5": "openai-gpt-image-1.5";
+        "openai-gpt-image-1": "openai-gpt-image-1";
+        "openai-gpt-image-1-mini": "openai-gpt-image-1-mini";
+        "bytedance-seedream-5-lite": "bytedance-seedream-5-lite";
+        "kling-kolors": "kling-kolors";
+        "alibaba-qwen-image-2.0-pro": "alibaba-qwen-image-2.0-pro";
+        "alibaba-qwen-image-2.0": "alibaba-qwen-image-2.0";
+        "alibaba-qwen-image-edit-max": "alibaba-qwen-image-edit-max";
+        "alibaba-qwen-image-edit-plus": "alibaba-qwen-image-edit-plus";
+        "alibaba-qwen-image-edit": "alibaba-qwen-image-edit";
+        "minimax-image-01": "minimax-image-01";
+        "runwayml-gen4-image": "runwayml-gen4-image";
+        "runwayml-gen4-image-turbo": "runwayml-gen4-image-turbo";
+    }>>;
+    aspectRatio: z.ZodDefault<z.ZodEnum<{
+        "9:16": "9:16";
+        "1:1": "1:1";
+        "4:5": "4:5";
+        "16:9": "16:9";
+        "4:3": "4:3";
+        "3:4": "3:4";
+    }>>;
+    dimensions: z.ZodOptional<z.ZodString>;
+    inputImageUrl: z.ZodOptional<z.ZodString>;
+    inputImageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    negativePrompt: z.ZodOptional<z.ZodString>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    numImages: z.ZodDefault<z.ZodNumber>;
+    outputFormat: z.ZodOptional<z.ZodEnum<{
+        png: "png";
+        jpeg: "jpeg";
+        webp: "webp";
+    }>>;
+}, z.core.$strip>;
+declare const OutputSchema: z.ZodObject<{
+    imageUrl: z.ZodString;
+    imageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    modelKeyUsed: z.ZodString;
+    seed: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const generateImageTool: ToolDefinition<typeof InputSchema, typeof OutputSchema>;
+export {};
+//# sourceMappingURL=generateImage.tool.d.ts.map

package/lib/services/agent/tools/generateImage.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateImage.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateImage.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAwB/D,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkCf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;;iBAOhB,CAAC;AA2BH,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAC5C,OAAO,WAAW,EAClB,OAAO,YAAY,CAuGpB,CAAC"}

package/lib/services/agent/tools/generateImage.tool.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateImageTool = void 0;
+/**
+ * generate_image agent tool.
+ *
+ * Re-enabled 2026-05-17 (was previously fenced when only the disabled FAL
+ * provider existed). Now dispatches via getAiGenProviderService() so it works
+ * against every image model registered in imageServicesMap (Google Imagen +
+ * Nano Banana, OpenAI gpt-image, ByteDance Seedream, Kling Kolors, Alibaba
+ * Qwen, MiniMax image-01, Runway Gen-4 Image).
+ *
+ * Defaults to google-nano-banana — cheapest image-gen we have that ALSO
+ * supports multi-image reference inputs (key requirement for AG-13 / C2
+ * reference-image anchoring). Switch via modelKey when a higher tier is
+ * worth it (gpt-image-1 for hero shots, runwayml-gen4-image for cinematic).
+ *
+ * Supports image-to-image / instruction edits via `inputImageUrl` (single
+ * ref, legacy) or `inputImageUrls` (multi-ref — used by AG-13 to thread the
+ * character + product reference images into every scene's image gen).
+ */
+const zod_1 = require("zod");
+const enums_1 = require("../../../globals/aiModels/enums");
+const assetCache_service_1 = require("../../assetCache.service");
+const aiGenFactory_service_1 = require("../../aiGen/aiGenFactory.service");
+const rateLimiter_1 = require("../../rateLimiter");
+const toolRegistry_1 = require("../toolRegistry");
+const ModelKeyEnum = zod_1.z.enum([
+    enums_1.EImageGenModels.GOOGLE_NANO_BANANA,
+    enums_1.EImageGenModels.GOOGLE_NANO_BANANA_PRO,
+    enums_1.EImageGenModels.GOOGLE_IMAGEN_4_FAST,
+    enums_1.EImageGenModels.GOOGLE_IMAGEN_4,
+    enums_1.EImageGenModels.GOOGLE_IMAGEN_4_ULTRA,
+    enums_1.EImageGenModels.OPENAI_GPT_IMAGE_1_MINI,
+    enums_1.EImageGenModels.OPENAI_GPT_IMAGE_1,
+    enums_1.EImageGenModels.OPENAI_GPT_IMAGE_1_5,
+    enums_1.EImageGenModels.OPENAI_GPT_IMAGE_2,
+    enums_1.EImageGenModels.BYTEDANCE_SEEDREAM_5_LITE,
+    enums_1.EImageGenModels.KLING_KOLORS,
+    enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_2,
+    enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_2_PRO,
+    enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_EDIT,
+    enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_EDIT_PLUS,
+    enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_EDIT_MAX,
+    enums_1.EImageGenModels.MINIMAX_IMAGE_01,
+    enums_1.EImageGenModels.RUNWAYML_GEN4_IMAGE_TURBO,
+    enums_1.EImageGenModels.RUNWAYML_GEN4_IMAGE,
+]);
+const InputSchema = zod_1.z.object({
+    prompt: zod_1.z
+        .string()
+        .min(1)
+        .describe("Detailed visual prompt. Lighting, lens, camera angle, mood, subject identity — more specific = more on-brief."),
+    modelKey: ModelKeyEnum.default(enums_1.EImageGenModels.GOOGLE_NANO_BANANA).describe("Image model. Default google-nano-banana — cheap, fast, supports multi-image refs (used for character/object anchoring). Use gpt-image-1 or runwayml-gen4-image for premium hero shots."),
+    aspectRatio: zod_1.z.enum(["9:16", "1:1", "4:5", "16:9", "3:4", "4:3"]).default("9:16"),
+    dimensions: zod_1.z
+        .string()
+        .regex(/^\d+x\d+$/)
+        .optional()
+        .describe('Explicit "WxH" override. Overrides aspectRatio.'),
+    inputImageUrl: zod_1.z
+        .string()
+        .url()
+        .optional()
+        .describe("Optional source image for image-to-image edits. Single-ref (legacy) — prefer inputImageUrls for multi-ref."),
+    inputImageUrls: zod_1.z
+        .array(zod_1.z.string().url())
+        .max(16)
+        .optional()
+        .describe("Multi-image references for identity transfer / composition. Used by AG-13 to thread character + product reference images into scene-level image gens. Per-provider caps: OpenAI ≤16, Nano Banana ≤14, Seedream ≤10, Qwen 1–3, MiniMax 1."),
+    negativePrompt: zod_1.z.string().optional(),
+    seed: zod_1.z.number().int().optional(),
+    numImages: zod_1.z.number().int().min(1).max(4).default(1),
+    outputFormat: zod_1.z.enum(["png", "jpeg", "webp"]).optional(),
+});
+const OutputSchema = zod_1.z.object({
+    imageUrl: zod_1.z.string().url(),
+    imageUrls: zod_1.z.array(zod_1.z.string().url()).optional(),
+    width: zod_1.z.number().optional(),
+    height: zod_1.z.number().optional(),
+    modelKeyUsed: zod_1.z.string(),
+    seed: zod_1.z.number().optional(),
+});
+// Indicative credit estimates (per single image, 1024x1024-ish output). Real
+// cost comes from provider response when available; this is for pre-spend
+// budgeting in estimate_cost. Order roughly cheapest → most expensive.
+const COST_BY_MODEL = {
+    [enums_1.EImageGenModels.GOOGLE_NANO_BANANA]: 1,
+    [enums_1.EImageGenModels.GOOGLE_IMAGEN_4_FAST]: 1,
+    [enums_1.EImageGenModels.OPENAI_GPT_IMAGE_1_MINI]: 1,
+    [enums_1.EImageGenModels.GOOGLE_NANO_BANANA_PRO]: 2,
+    [enums_1.EImageGenModels.GOOGLE_IMAGEN_4]: 2,
+    [enums_1.EImageGenModels.BYTEDANCE_SEEDREAM_5_LITE]: 2,
+    [enums_1.EImageGenModels.KLING_KOLORS]: 2,
+    [enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_2]: 2,
+    [enums_1.EImageGenModels.MINIMAX_IMAGE_01]: 2,
+    [enums_1.EImageGenModels.GOOGLE_IMAGEN_4_ULTRA]: 4,
+    [enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_2_PRO]: 4,
+    [enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_EDIT]: 4,
+    [enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_EDIT_PLUS]: 4,
+    [enums_1.EImageGenModels.ALIBABA_QWEN_IMAGE_EDIT_MAX]: 5,
+    [enums_1.EImageGenModels.RUNWAYML_GEN4_IMAGE_TURBO]: 3,
+    [enums_1.EImageGenModels.RUNWAYML_GEN4_IMAGE]: 5,
+    [enums_1.EImageGenModels.OPENAI_GPT_IMAGE_1]: 4,
+    [enums_1.EImageGenModels.OPENAI_GPT_IMAGE_1_5]: 5,
+    [enums_1.EImageGenModels.OPENAI_GPT_IMAGE_2]: 6,
+};
+exports.generateImageTool = {
+    name: "generate_image",
+    description: [
+        "Generate a still image from a text prompt (T1 tier — costs credits but much",
+        "cheaper than video generation). Use for scene b-roll, product shots, or as",
+        "the source frame for animate_image / animate-to-video (T2 indirect path).",
+        "Supports image-to-image edits and multi-image identity transfer via",
+        "inputImageUrl / inputImageUrls — pass the character or product reference",
+        "image(s) to keep visual identity locked across scenes.",
+        "Do NOT use for: stock-grade generic visuals (use search_stock — free) or",
+        "scenes that fundamentally need motion (use generate_video / animate_image).",
+        "Examples:",
+        '  { prompt: "cinematic golden-hour ocean cliff", aspectRatio: "9:16" }',
+        '  { prompt: "the same woman, holding the product, kitchen", inputImageUrls: ["https://char-ref.png", "https://product-ref.png"], modelKey: "google-nano-banana" }',
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    idempotent: true,
+    estimateCost: async (input) => (COST_BY_MODEL[input.modelKey] ?? 2) * input.numImages,
+    handler: async (input, ctx) => {
+        // AG-29: brand text degraded across reference-anchored scenes (Test 1 had
+        // "HydraPure" rendered as "Hydropure" / "HydrraPure" / mirrored text). The
+        // image-gen models accept negativePrompt; default a text-fidelity clause
+        // when the caller didn't provide one. Cheap insurance against the most
+        // common product-ad failure mode.
+        const TEXT_FIDELITY_NEGATIVE = "distorted text, misspelled words, illegible letters, garbled typography, mangled brand names, mirrored letters, jumbled lettering, deformed logo, extra letters, missing letters, blurry text, watermark";
+        const effectiveNegativePrompt = input.negativePrompt
+            ? `${input.negativePrompt}, ${TEXT_FIDELITY_NEGATIVE}`
+            : TEXT_FIDELITY_NEGATIVE;
+        const cacheParts = {
+            provider: `image:${input.modelKey}`,
+            input: {
+                prompt: input.prompt,
+                aspectRatio: input.aspectRatio,
+                dimensions: input.dimensions,
+                inputImageUrl: input.inputImageUrl,
+                inputImageUrls: input.inputImageUrls,
+                negativePrompt: effectiveNegativePrompt,
+                seed: input.seed,
+                numImages: input.numImages,
+            },
+        };
+        const hit = await assetCache_service_1.AssetCacheService.lookup(cacheParts);
+        if (hit) {
+            return {
+                imageUrl: hit.url,
+                width: hit.width,
+                height: hit.height,
+                modelKeyUsed: input.modelKey,
+            };
+        }
+        const provider = (0, aiGenFactory_service_1.getAiGenProviderService)(input.modelKey);
+        if (!provider.generateImage) {
+            throw new Error(`Provider for ${input.modelKey} does not implement generateImage().`);
+        }
+        // Synchronous provider call — slot released on return (try/finally).
+        // Per-min + per-day are consumed atomically inside waitUntilAvailable
+        // and auto-expire in Redis; only the in-process concurrent counter
+        // needs an explicit release.
+        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(input.modelKey);
+        await limiter.waitUntilAvailable();
+        let result;
+        try {
+            result = await provider.generateImage({
+                prompt: input.prompt,
+                modelKey: input.modelKey,
+                aspectRatio: input.aspectRatio,
+                dimensions: input.dimensions,
+                inputImageUrl: input.inputImageUrl,
+                inputImageUrls: input.inputImageUrls,
+                negativePrompt: effectiveNegativePrompt,
+                seed: input.seed,
+                numImages: input.numImages,
+                outputFormat: input.outputFormat,
+                idempotencyKey: ctx.idempotencyKey,
+            });
+        }
+        finally {
+            limiter.releaseSlot();
+        }
+        await assetCache_service_1.AssetCacheService.store(cacheParts, {
+            provider: `image:${input.modelKey}`,
+            kind: "image",
+            url: result.imageUrl,
+            width: result.width,
+            height: result.height,
+            originalCreditsSpent: (COST_BY_MODEL[input.modelKey] ?? 2) * input.numImages,
+        });
+        return {
+            imageUrl: result.imageUrl,
+            imageUrls: result.imageUrls,
+            width: result.width,
+            height: result.height,
+            modelKeyUsed: input.modelKey,
+            seed: result.seed,
+        };
+    },
+};
+(0, toolRegistry_1.registerTool)(exports.generateImageTool);