vidspotai-shared 1.0.82 → 1.0.83

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.estimateCostTool = void 0;
 const zod_1 = require("zod");
+const aiModels_1 = require("../../../globals/aiModels");
 const project_schema_1 = require("../../../schemas/project.schema");
 const toolRegistry_1 = require("../toolRegistry");
 const InputSchema = zod_1.z.object({
@@ -13,16 +14,27 @@ const OutputSchema = zod_1.z.object({
         clipId: zod_1.z.string(),
         tier: zod_1.z.string(),
         source: zod_1.z.string(),
+        /** Model the clip was (or will be) generated with, when known. */
+        modelKey: zod_1.z.string().optional(),
         credits: zod_1.z.number().nonnegative(),
+        /**
+         * How `credits` was derived:
+         *   actual — clip already generated; provenance.creditsSpent is exact.
+         *   model  — AG-6 real per-model rate from aiModelConfigs[modelKey].
+         *   tier   — coarse per-tier coefficient (no/unknown modelKey or no cost block).
+         */
+        basis: zod_1.z.enum(["actual", "model", "tier"]),
     })),
 });
 exports.estimateCostTool = {
     name: "estimate_cost",
     description: [
         "Estimate the credit cost of rendering a Project JSON without spending any",
-        "credits. Reads each clip's provenance.creditsSpent (if already generated)",
-        "or estimates from tier when not yet generated. Always call before",
-        "executing a plan so the planner can stay within budget.",
+        "credits. Per clip, in order: uses provenance.creditsSpent if already",
+        "generated (exact); else the real per-model rate from the clip's",
+        "provenance.modelKey (AG-6); else a coarse per-tier coefficient when the",
+        "model is unknown. Always call before executing a plan so the planner can",
+        "stay within budget.",
     ].join(" "),
     inputSchema: InputSchema,
     outputSchema: OutputSchema,
@@ -31,8 +43,42 @@ exports.estimateCostTool = {
         const breakdown = project.clips.map((clip) => {
             const tier = clip.provenance?.tier ?? "T0";
             const source = clip.provenance?.source ?? "user-upload";
-            const credits = clip.provenance?.creditsSpent ?? estimateFromTier(tier, clip.display);
-            return { clipId: clip.id, tier, source, credits };
+            const modelKey = clip.provenance?.modelKey;
+            // 1. Already generated → provenance.creditsSpent is the exact charge.
+            if (clip.provenance?.creditsSpent != null) {
+                return {
+                    clipId: clip.id,
+                    tier,
+                    source,
+                    modelKey,
+                    credits: clip.provenance.creditsSpent,
+                    basis: "actual",
+                };
+            }
+            // 2. AG-6: real per-model rate keyed on the planned modelKey.
+            const seconds = Math.max(0, (clip.display.to - clip.display.from) / 1000);
+            if (modelKey) {
+                const modelCredits = (0, aiModels_1.estimateModelCredits)(modelKey, seconds);
+                if (modelCredits != null) {
+                    return {
+                        clipId: clip.id,
+                        tier,
+                        source,
+                        modelKey,
+                        credits: modelCredits,
+                        basis: "model",
+                    };
+                }
+            }
+            // 3. Fall back to the coarse per-tier coefficient.
+            return {
+                clipId: clip.id,
+                tier,
+                source,
+                modelKey,
+                credits: estimateFromTier(tier, clip.display),
+                basis: "tier",
+            };
         });
         return {
             totalCredits: breakdown.reduce((s, b) => s + b.credits, 0),
@@ -41,8 +87,10 @@ exports.estimateCostTool = {
     },
 };
 /**
- * Rough per-second per-tier estimate, in credits. Refined later via aiModelConfigs
- * lookups once tier annotations are backfilled across providers.
+ * Coarse per-second per-tier estimate, in credits. Fallback ONLY — used when a
+ * clip has no modelKey or the model has no usable cost block. Generated clips
+ * with a known modelKey now go through estimateModelCredits() (AG-6) for real
+ * per-model rates.
  */
 function estimateFromTier(tier, display) {
     const seconds = Math.max(0, (display.to - display.from) / 1000);

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

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { EVideoGenModels } from "../../../globals/aiModels";
+import { ToolDefinition } from "../toolRegistry";
+/** Whether a model key can be extended via its provider's extend endpoint. */
+export declare function modelSupportsExtend(modelKey: string): boolean;
+declare const InputSchema: z.ZodObject<{
+    previousTaskId: z.ZodString;
+    modelKey: z.ZodEnum<typeof EVideoGenModels>;
+    extraDurationSec: z.ZodDefault<z.ZodNumber>;
+    prompt: z.ZodOptional<z.ZodString>;
+    negativePrompt: z.ZodOptional<z.ZodString>;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        "720p": "720p";
+        "1080p": "1080p";
+        "4k": "4k";
+    }>>;
+}, z.core.$strip>;
+declare const OutputSchema: z.ZodObject<{
+    status: z.ZodLiteral<"triggered">;
+    taskId: z.ZodString;
+    raw: z.ZodUnknown;
+    modelKeyUsed: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const extendVideoTool: ToolDefinition<typeof InputSchema, typeof OutputSchema>;
+export {};
+//# sourceMappingURL=extendVideo.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extendVideo.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/extendVideo.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAyB/D,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,QAAA,MAAM,WAAW;;;;;;;;;;;iBAsCf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;iBAMhB,CAAC;AAEH,eAAO,MAAM,eAAe,EAAE,cAAc,CAC1C,OAAO,WAAW,EAClB,OAAO,YAAY,CA6EpB,CAAC"}

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

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extendVideoTool = void 0;
+exports.modelSupportsExtend = modelSupportsExtend;
+const zod_1 = require("zod");
+const aiModels_1 = require("../../../globals/aiModels");
+const logger_1 = require("../../../utils/logger");
+const aiGenFactory_service_1 = require("../../aiGen/aiGenFactory.service");
+const rateLimiter_1 = require("../../rateLimiter");
+const toolRegistry_1 = require("../toolRegistry");
+/**
+ * AG-2: models whose provider exposes a native video-extension endpoint
+ * (`endpoint: "extend"` + `sourceTaskId`). Extension continues a SPECIFIC prior
+ * provider task, so — unlike generate_video — there is NO cross-provider
+ * fallback: the source clip physically lives on the originating provider's
+ * account. Kling video-extend (/v1/videos/video-extend) and Pixverse
+ * (/video/extend/generate) are the two implemented today. Special-endpoint
+ * Kling variants (avatar, omni-video, motion-control, lip-sync) are excluded —
+ * the generic video-extend endpoint does not accept their tasks.
+ */
+const EXTEND_CAPABLE_MODELS = new Set([
+    aiModels_1.EVideoGenModels.KLING_V2_MASTER,
+    aiModels_1.EVideoGenModels.KLING_V2_1,
+    aiModels_1.EVideoGenModels.KLING_V2_1_MASTER,
+    aiModels_1.EVideoGenModels.KLING_V2_5_TURBO,
+    aiModels_1.EVideoGenModels.KLING_V2_6,
+    aiModels_1.EVideoGenModels.KLING_V3_0,
+    aiModels_1.EVideoGenModels.PIXVERSE_V5,
+    aiModels_1.EVideoGenModels.PIXVERSE_V5_5,
+    aiModels_1.EVideoGenModels.PIXVERSE_V5_6,
+    aiModels_1.EVideoGenModels.PIXVERSE_V6,
+]);
+/** Whether a model key can be extended via its provider's extend endpoint. */
+function modelSupportsExtend(modelKey) {
+    return EXTEND_CAPABLE_MODELS.has(modelKey);
+}
+const InputSchema = zod_1.z.object({
+    previousTaskId: zod_1.z
+        .string()
+        .min(1)
+        .describe("Provider task id of the clip to continue FROM — the taskId returned by a " +
+        "prior generate_video/animate_image call on the SAME provider/model. " +
+        "Extension physically continues that clip; it cannot reference a task " +
+        "from a different provider."),
+    modelKey: zod_1.z
+        .nativeEnum(aiModels_1.EVideoGenModels)
+        .describe("MUST be the same extend-capable model that produced previousTaskId. " +
+        "Only Kling (v2-master/v2.1/v2.1-master/v2.5-turbo/v2.6/v3.0) and " +
+        "Pixverse (v5/v5.5/v5.6/v6) support extension."),
+    extraDurationSec: zod_1.z
+        .number()
+        .int()
+        .min(2)
+        .max(10)
+        .default(5)
+        .describe("Requested additional seconds. NOTE: providers extend by a fixed native " +
+        "increment (Kling ~4-5s, Pixverse ~5-8s) and may not honour an arbitrary " +
+        "value exactly — this drives cost estimation and the provider's quality " +
+        "tier, not a precise cut length."),
+    prompt: zod_1.z
+        .string()
+        .optional()
+        .describe("Optional motion/visual prompt for the continuation. Omit to let the " +
+        "extension continue the source clip's motion naturally."),
+    negativePrompt: zod_1.z.string().optional(),
+    resolution: zod_1.z.enum(["720p", "1080p", "4k"]).optional(),
+});
+const OutputSchema = zod_1.z.object({
+    status: zod_1.z.literal("triggered"),
+    taskId: zod_1.z.string().describe("New provider task id for the extension clip — poll like any other."),
+    raw: zod_1.z.unknown(),
+    /** Echoes the model used (extension never falls back, so == input.modelKey). */
+    modelKeyUsed: zod_1.z.string().optional(),
+});
+exports.extendVideoTool = {
+    name: "extend_video",
+    description: [
+        "Continue an EXISTING video clip past a model's per-clip max by calling the",
+        "provider's native extension endpoint, instead of falling back to a different",
+        "provider (which would visibly change look/identity). Returns a new provider",
+        "task id for the continuation clip — poll it like any other; the stitcher",
+        "concatenates the source clip + extension(s) in order.",
+        "Use when a single scene needs more seconds than the chosen model allows:",
+        "first generate_video/animate_image for the initial clip, then N extend_video",
+        "calls each continuing the PREVIOUS task. Only Kling and Pixverse video models",
+        "support this; the same model that produced previousTaskId must be passed.",
+        "Example:",
+        '  { previousTaskId: "<kling task id>", modelKey: "kling-v2.6", extraDurationSec: 5 }',
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    idempotent: false,
+    estimateCost: async (input) => {
+        // Same per-second tier coefficient as generate_video; extension is billed
+        // per added second at the base model's rate.
+        const isPremium = input.modelKey === aiModels_1.EVideoGenModels.KLING_V3_0 ||
+            input.modelKey === aiModels_1.EVideoGenModels.KLING_V2_6;
+        return Math.ceil(input.extraDurationSec * (isPremium ? 12 : 4));
+    },
+    handler: async (input) => {
+        if (!modelSupportsExtend(input.modelKey)) {
+            throw new Error(`extend_video: model "${input.modelKey}" has no extension endpoint. ` +
+                "Extend-capable: Kling (v2-master/v2.1/v2.1-master/v2.5-turbo/v2.6/v3.0), " +
+                "Pixverse (v5/v5.5/v5.6/v6).");
+        }
+        // No provider fallback: the source task lives on this provider only. Hold a
+        // rate-limit slot through return (the host's TaskPoller releases it when the
+        // task settles); release here on submit error / missing taskId.
+        const limiter = (0, rateLimiter_1.getAiGenModelRateLimiter)(input.modelKey);
+        await limiter.waitUntilAvailable();
+        let heldSlot = true;
+        try {
+            const provider = (0, aiGenFactory_service_1.getAiGenProviderService)(input.modelKey);
+            const result = await provider.generateVideo({
+                modelKey: input.modelKey,
+                endpoint: "extend",
+                sourceTaskId: input.previousTaskId,
+                duration: input.extraDurationSec,
+                prompt: input.prompt,
+                negativePrompt: input.negativePrompt,
+                resolution: input.resolution,
+            });
+            const taskId = result.task?.taskId ??
+                result.task?.id ??
+                (typeof result.task === "string" ? result.task : "unknown");
+            if (taskId === "unknown") {
+                limiter.releaseSlot();
+                heldSlot = false;
+            }
+            logger_1.logger.info("extend_video: extension submitted", {
+                modelKey: input.modelKey,
+                previousTaskId: input.previousTaskId,
+                taskId,
+            });
+            return {
+                status: "triggered",
+                taskId,
+                raw: result.task,
+                modelKeyUsed: input.modelKey,
+            };
+        }
+        catch (err) {
+            if (heldSlot)
+                limiter.releaseSlot();
+            throw err;
+        }
+    },
+};
+(0, toolRegistry_1.registerTool)(exports.extendVideoTool);

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

@@ -0,0 +1,184 @@
+import { z } from "zod";
+import { VideoBrief } from "../../../schemas/brief.schema";
+import { Script } from "../../../schemas/videoPlan.schema";
+import { LlmCaller } from "../llmCaller";
+import { ToolDefinition } from "../toolRegistry";
+/**
+ * Stream L (L-4) — generate_script. Script-first authoring for long-form (L1+):
+ * the FIRST pass of L-3's two-pass flow. Produces the full spoken narration for
+ * the whole video as ONE coherent piece of writing, before any scenes exist.
+ *
+ * Why script-first: long-form (3-60min) authored scene-by-scene drifts — each
+ * scene's voiceoverLine is written in isolation and the through-line is lost.
+ * Writing the whole narration first keeps argument flow, callbacks, and pacing
+ * coherent; chapter_outline then segments it (L-4) and match_broll_to_script
+ * explodes each segment into scenes (L-4) whose voiceoverLines are slices of
+ * THIS text.
+ *
+ * The LLM returns prose only; word count + duration estimate are computed
+ * deterministically (estimateTtsMs) rather than trusted from the model, mirror-
+ * ing how the planner stamps credit estimates rather than believing the LLM.
+ */
+declare const InputSchema: z.ZodObject<{
+    brief: z.ZodObject<{
+        rawPrompt: z.ZodString;
+        goal: z.ZodOptional<z.ZodString>;
+        niche: z.ZodOptional<z.ZodEnum<{
+            other: "other";
+            news: "news";
+            "ugc-ad": "ugc-ad";
+            "faceless-yt": "faceless-yt";
+            "product-demo": "product-demo";
+            "talking-head": "talking-head";
+            "social-recap": "social-recap";
+            "real-estate": "real-estate";
+            recipe: "recipe";
+            travel: "travel";
+            fitness: "fitness";
+            "podcast-clip": "podcast-clip";
+            education: "education";
+        }>>;
+        audience: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            professional: "professional";
+            energetic: "energetic";
+            calm: "calm";
+            cinematic: "cinematic";
+            casual: "casual";
+            playful: "playful";
+            edgy: "edgy";
+            warm: "warm";
+            informational: "informational";
+        }>>;
+        hookStyle: z.ZodOptional<z.ZodEnum<{
+            question: "question";
+            "bold-claim": "bold-claim";
+            "pattern-interrupt": "pattern-interrupt";
+            story: "story";
+            stat: "stat";
+            demo: "demo";
+            "voiceover-only": "voiceover-only";
+        }>>;
+        pacing: z.ZodOptional<z.ZodEnum<{
+            medium: "medium";
+            fast: "fast";
+            slow: "slow";
+            "very-fast": "very-fast";
+        }>>;
+        durationSec: z.ZodOptional<z.ZodNumber>;
+        aspect: z.ZodOptional<z.ZodEnum<{
+            "9:16": "9:16";
+            "1:1": "1:1";
+            "4:5": "4:5";
+            "16:9": "16:9";
+        }>>;
+        lengthTier: z.ZodOptional<z.ZodEnum<{
+            S1: "S1";
+            S2: "S2";
+            M1: "M1";
+            L1: "L1";
+            L2: "L2";
+            L3: "L3";
+        }>>;
+        voice: z.ZodOptional<z.ZodObject<{
+            gender: z.ZodOptional<z.ZodEnum<{
+                male: "male";
+                female: "female";
+                neutral: "neutral";
+            }>>;
+            ageRange: z.ZodOptional<z.ZodEnum<{
+                child: "child";
+                teen: "teen";
+                "young-adult": "young-adult";
+                adult: "adult";
+                senior: "senior";
+            }>>;
+            accent: z.ZodOptional<z.ZodString>;
+            language: z.ZodDefault<z.ZodString>;
+            voiceId: z.ZodOptional<z.ZodString>;
+            style: z.ZodOptional<z.ZodEnum<{
+                energetic: "energetic";
+                calm: "calm";
+                casual: "casual";
+                warm: "warm";
+                neutral: "neutral";
+                excited: "excited";
+                happy: "happy";
+                serious: "serious";
+                dramatic: "dramatic";
+                whisper: "whisper";
+            }>>;
+        }, z.core.$strip>>;
+        music: z.ZodOptional<z.ZodObject<{
+            moods: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                energetic: "energetic";
+                calm: "calm";
+                cinematic: "cinematic";
+                playful: "playful";
+                uplifting: "uplifting";
+                tense: "tense";
+                dreamy: "dreamy";
+                dark: "dark";
+            }>>>;
+            bpmMin: z.ZodOptional<z.ZodNumber>;
+            bpmMax: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        cta: z.ZodOptional<z.ZodString>;
+        claims: z.ZodDefault<z.ZodObject<{
+            allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            block: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        references: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            analyzed: z.ZodOptional<z.ZodObject<{
+                durationMs: z.ZodNumber;
+                sceneCount: z.ZodNumber;
+                hookMs: z.ZodNumber;
+                cutsPerSecond: z.ZodNumber;
+                bpm: z.ZodOptional<z.ZodNumber>;
+                transcriptExcerpt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        preferredModelKeys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tierBudget: z.ZodDefault<z.ZodEnum<{
+            T0: "T0";
+            T1: "T1";
+            T2: "T2";
+            T3: "T3";
+        }>>;
+        maxSpendUSD: z.ZodOptional<z.ZodNumber>;
+        videoStrategy: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            direct: "direct";
+            indirect: "indirect";
+        }>>;
+        consistencyTier: z.ZodOptional<z.ZodEnum<{
+            C0: "C0";
+            C1: "C1";
+            C2: "C2";
+        }>>;
+        confidence: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>;
+    wpm: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const OutputSchema: z.ZodObject<{
+    script: z.ZodObject<{
+        fullText: z.ZodString;
+        wordCount: z.ZodOptional<z.ZodNumber>;
+        estimatedDurationMs: z.ZodOptional<z.ZodNumber>;
+        wpm: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    suggestedTitle: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Pure core, shared by the tool handler and the script-first planner (L-3).
+ * Takes an explicit LlmCaller so the planner can pass its own injected caller
+ * rather than relying on the global registry. Returns the script + title.
+ */
+export declare function generateScriptCore(llm: LlmCaller, brief: VideoBrief, wpmOverride?: number): Promise<{
+    script: Script;
+    suggestedTitle?: string;
+}>;
+export declare const generateScriptTool: ToolDefinition<typeof InputSchema, typeof OutputSchema>;
+export {};
+//# sourceMappingURL=generateScript.tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"generateScript.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateScript.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAoB,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,MAAM,EAAgB,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AAEH,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAUf,CAAC;AAeH,QAAA,MAAM,YAAY;;;;;;;;iBAGhB,CAAC;AAEH;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyDtD;AAED,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAC7C,OAAO,WAAW,EAClB,OAAO,YAAY,CAcpB,CAAC"}

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

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateScriptTool = void 0;
+exports.generateScriptCore = generateScriptCore;
+const zod_1 = require("zod");
+const brief_schema_1 = require("../../../schemas/brief.schema");
+const videoPlan_schema_1 = require("../../../schemas/videoPlan.schema");
+const llmCallerRegistry_1 = require("../llmCallerRegistry");
+const modelRouter_1 = require("../modelRouter");
+const ttsDuration_1 = require("../ttsDuration");
+const toolRegistry_1 = require("../toolRegistry");
+/**
+ * Stream L (L-4) — generate_script. Script-first authoring for long-form (L1+):
+ * the FIRST pass of L-3's two-pass flow. Produces the full spoken narration for
+ * the whole video as ONE coherent piece of writing, before any scenes exist.
+ *
+ * Why script-first: long-form (3-60min) authored scene-by-scene drifts — each
+ * scene's voiceoverLine is written in isolation and the through-line is lost.
+ * Writing the whole narration first keeps argument flow, callbacks, and pacing
+ * coherent; chapter_outline then segments it (L-4) and match_broll_to_script
+ * explodes each segment into scenes (L-4) whose voiceoverLines are slices of
+ * THIS text.
+ *
+ * The LLM returns prose only; word count + duration estimate are computed
+ * deterministically (estimateTtsMs) rather than trusted from the model, mirror-
+ * ing how the planner stamps credit estimates rather than believing the LLM.
+ */
+const InputSchema = zod_1.z.object({
+    brief: brief_schema_1.VideoBriefSchema.describe("Structured brief. durationSec drives the target word count; tone / audience / niche steer the writing."),
+    /**
+     * Override the words-per-minute used to size the script against durationSec.
+     * Defaults to the TTS calibration (150 wpm). Lower for slow/contemplative
+     * narration, higher for energetic delivery.
+     */
+    wpm: zod_1.z.number().int().positive().optional(),
+});
+/** What we ask the LLM for — prose + an optional working title only. */
+const LlmScriptSchema = zod_1.z.object({
+    fullText: zod_1.z
+        .string()
+        .describe("The complete spoken narration for the entire video, as flowing prose with normal sentence punctuation. No scene markers, no '[VISUAL]' directions, no headings — just what the narrator says, start to finish."),
+    suggestedTitle: zod_1.z
+        .string()
+        .optional()
+        .describe("A working title for the video (used for chapter UI / file naming)."),
+});
+const OutputSchema = zod_1.z.object({
+    script: videoPlan_schema_1.ScriptSchema,
+    suggestedTitle: zod_1.z.string().optional(),
+});
+/**
+ * Pure core, shared by the tool handler and the script-first planner (L-3).
+ * Takes an explicit LlmCaller so the planner can pass its own injected caller
+ * rather than relying on the global registry. Returns the script + title.
+ */
+async function generateScriptCore(llm, brief, wpmOverride) {
+    const router = new modelRouter_1.ModelRouter();
+    const wpm = wpmOverride ?? ttsDuration_1.TTS_DEFAULT_WPM;
+    // Target word count from requested duration at the chosen wpm. Gives the
+    // model a concrete length budget so it doesn't under/over-write.
+    const durationSec = brief.durationSec ?? 300;
+    const targetWords = Math.max(80, Math.round((durationSec / 60) * wpm));
+    const system = [
+        "You are a senior long-form video scriptwriter (YouTube essays, explainers,",
+        "documentaries). Write spoken narration that one narrator reads start to",
+        "finish: a strong hook, a clear through-line, signposted transitions between",
+        "ideas, and a payoff/CTA at the end. Use natural spoken rhythm and normal",
+        "punctuation. Do NOT write scene directions, shot lists, headings, or",
+        "bracketed visual notes — ONLY the words spoken aloud.",
+    ].join(" ");
+    const user = [
+        `Topic / request: ${brief.rawPrompt}`,
+        brief.goal ? `Goal: ${brief.goal}` : "",
+        brief.audience ? `Audience: ${brief.audience}` : "",
+        brief.tone ? `Tone: ${brief.tone}` : "",
+        brief.niche ? `Niche: ${brief.niche}` : "",
+        brief.cta ? `Call to action to land at the end: ${brief.cta}` : "",
+        `Target length: ~${durationSec}s of speech ≈ ${targetWords} words at ${wpm} wpm. Stay within ±15% of that word count.`,
+        brief.claims?.block?.length
+            ? `NEVER use these phrases (compliance): ${brief.claims.block.join("; ")}.`
+            : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const res = await llm.structured({
+        model: router.pickFor("planner", { premium: brief.tierBudget === "T3" }),
+        fallbackModel: router.fallbackFor("planner"),
+        schema: LlmScriptSchema,
+        schemaName: "Script",
+        messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ],
+        temperature: 0.7,
+        maxTokens: 8000,
+    });
+    const fullText = res.data.fullText.trim();
+    const wordCount = fullText.split(/\s+/).filter(Boolean).length;
+    return {
+        script: {
+            fullText,
+            wordCount,
+            estimatedDurationMs: (0, ttsDuration_1.estimateTtsMs)(fullText, wpm),
+            wpm,
+        },
+        suggestedTitle: res.data.suggestedTitle,
+    };
+}
+exports.generateScriptTool = {
+    name: "generate_script",
+    description: [
+        "Write the full spoken narration for a long-form (L1+) video as one coherent",
+        "script BEFORE planning scenes. First pass of script-first authoring: the",
+        "output feeds chapter_outline (to segment) then match_broll_to_script (to",
+        "explode each segment into scenes). Only for M1+/L1+ tiers — short-form",
+        "(S1/S2) stays scene-first via plan_video.",
+    ].join(" "),
+    inputSchema: InputSchema,
+    outputSchema: OutputSchema,
+    idempotent: false,
+    handler: async (input) => generateScriptCore((0, llmCallerRegistry_1.getLlmCaller)(), input.brief, input.wpm),
+};
+(0, toolRegistry_1.registerTool)(exports.generateScriptTool);

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

@@ -16,6 +16,7 @@ declare const InputSchema: z.ZodObject<{
         "4k": "4k";
     }>>;
     inputImageUrl: z.ZodOptional<z.ZodString>;
+    lastFrameImageUrl: z.ZodOptional<z.ZodString>;
     audio: z.ZodOptional<z.ZodBoolean>;
     negativePrompt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

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

@@ -1 +1 @@
-{"version":3,"file":"generateVideo.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateVideo.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA4B/D,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;iBA+Bf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;iBAOhB,CAAC;AAEH,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAC5C,OAAO,WAAW,EAClB,OAAO,YAAY,CA0GpB,CAAC"}
+{"version":3,"file":"generateVideo.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/generateVideo.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAI5D,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA4B/D,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;iBA4Cf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;iBAOhB,CAAC;AAEH,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAC5C,OAAO,WAAW,EAClB,OAAO,YAAY,CAqHpB,CAAC"}

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

@@ -42,6 +42,17 @@ const InputSchema = zod_1.z.object({
         .url()
         .optional()
         .describe("Source image for image-to-video. If set, this is an animate_image-style call."),
+    lastFrameImageUrl: zod_1.z
+        .string()
+        .url()
+        .optional()
+        .describe("AG-1: last/end frame for first-last-frame (FLF) interpolation — the model " +
+        "animates FROM inputImageUrl (first frame) TO this image (last frame), the " +
+        "cleanest way to get reliable directed motion between two specific " +
+        "compositions. REQUIRES inputImageUrl (the first frame). Only " +
+        "FLF-capable models accept it (google-veo-3.1/-fast, kling, runway-gen4-turbo, " +
+        "alibaba-wan); the capability gate skips models that don't, and the chain " +
+        "falls back. Omit for normal single-image animation."),
     audio: zod_1.z.boolean().optional().describe("Whether the model should generate audio."),
     negativePrompt: zod_1.z.string().optional(),
 });
@@ -78,6 +89,13 @@ exports.generateVideoTool = {
     },
     handler: async (input) => {
         const isI2V = Boolean(input.inputImageUrl);
+        // AG-1: FLF needs a first frame to interpolate FROM. A last frame without an
+        // inputImageUrl is meaningless, so ignore it (and warn) rather than passing
+        // it to a text-to-video chain that would dead-end on the capability gate.
+        if (input.lastFrameImageUrl && !isI2V) {
+            logger_1.logger.warn("generate_video: lastFrameImageUrl ignored — no inputImageUrl (first frame) supplied", { modelKey: input.modelKey });
+        }
+        const lastFrameImageUrl = isI2V ? input.lastFrameImageUrl : undefined;
         const chain = (0, chains_1.buildVideoChain)(input.modelKey, pickChain(input.modelKey, isI2V));
         const outcome = await (0, withFallback_1.withProviderFallback)({
             providers: chain,
@@ -85,7 +103,7 @@ exports.generateVideoTool = {
                 aspect: input.aspectRatio,
                 durationSec: input.durationSec,
                 type: isI2V ? "image-to-video" : "text-to-video",
-                lastFrame: false,
+                lastFrame: Boolean(lastFrameImageUrl),
                 audio: input.audio,
                 hasInputImage: isI2V,
             }),
@@ -118,6 +136,7 @@ exports.generateVideoTool = {
                         aspectRatio: input.aspectRatio,
                         resolution: input.resolution,
                         inputImageUrl: input.inputImageUrl,
+                        lastFrameImageUrl,
                         audio: input.audio,
                         negativePrompt: input.negativePrompt,
                         type: isI2V ? "image-to-video" : "text-to-video",