vidspotai-shared 1.0.82 → 1.0.83

package/lib/services/agent/repurpose/repurpose.schema.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/**
+ * X8 Social Suite · Phase 6 · E3 — "auto-repurpose" schemas.
+ *
+ * One long source video → an LLM picks the strongest STANDALONE moments → each
+ * becomes an independent, platform-native vertical short (its own title + hook
+ * + score). This is opus.pro's core loop; we can do it AND host the source
+ * generation, so the long-form and its shorts share one brain + one bill.
+ *
+ * Deliberately a sibling of L-5 (edit-existing), not a fork of it. L-5 picks N
+ * segments and CONCATENATES them into ONE tighter recut; E3 picks N
+ * INDEPENDENT spans and emits N separate shorts. They share the ffmpeg
+ * primitives (cut/probe/upload) and the ASR transcript shape, but the
+ * selection brain and the output shape are different — so E3 gets its own pure
+ * picker (shortsPicker.ts) and its own worker, leaving the proven L-5 path
+ * untouched.
+ *
+ * As with the rest of the agent surface, the PURE logic (span selection,
+ * clamping, scoring, credit math) lives in `shared` so it is unit-/eval-able;
+ * the IO-heavy stages (download → ASR → ffmpeg cut → B2 reframe → upload) run
+ * in the node-express worker where ffmpeg already is.
+ */
+export declare const RepurposeRequestSchema: z.ZodObject<{
+    sourceVideoUrl: z.ZodString;
+    sourceDurationSec: z.ZodNumber;
+    maxShorts: z.ZodOptional<z.ZodNumber>;
+    targetShortSec: 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";
+    }>>;
+    language: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RepurposeRequest = z.infer<typeof RepurposeRequestSchema>;
+/** Bounds for a single short, enforced after the LLM picks (see clampShorts). */
+export declare const MIN_SHORT_MS = 3000;
+export declare const MAX_SHORT_MS = 180000;
+export declare const SHORT_TITLE_MAX = 100;
+export declare const SHORT_HOOK_MAX = 280;
+export declare const SHORT_REASON_MAX = 500;
+export declare const SHORT_LABEL_MAX = 120;
+/**
+ * One standalone short: a single contiguous span of the source plus the copy
+ * needed to post it. (v1 is one span per short — a jump-cut micro-montage per
+ * short is a deferred enhancement; the shape stays span-based so it's easy to
+ * extend later.) Per-platform caption variants are NOT produced here — the E1
+ * caption generator can enrich each short downstream from `title`/`hook`.
+ */
+export declare const ShortCandidateSchema: z.ZodObject<{
+    startMs: z.ZodNumber;
+    endMs: z.ZodNumber;
+    title: z.ZodString;
+    hook: z.ZodString;
+    reason: z.ZodString;
+    score: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ShortCandidate = z.infer<typeof ShortCandidateSchema>;
+export declare const ShortPlanSchema: z.ZodObject<{
+    shorts: z.ZodArray<z.ZodObject<{
+        startMs: z.ZodNumber;
+        endMs: z.ZodNumber;
+        title: z.ZodString;
+        hook: z.ZodString;
+        reason: z.ZodString;
+        score: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ShortPlan = z.infer<typeof ShortPlanSchema>;
+/**
+ * Tiny job envelope — same design rule as EditJobPayload: the full request
+ * lives on `agentProjects/{projectId}.repurposeRequest`, the worker reads it at
+ * job start. Keeps the Redis stream light.
+ */
+export declare const RepurposeJobPayloadSchema: z.ZodObject<{
+    runId: z.ZodString;
+    projectId: z.ZodString;
+    userId: z.ZodString;
+    enqueuedAt: z.ZodNumber;
+}, z.core.$strict>;
+export type RepurposeJobPayload = z.infer<typeof RepurposeJobPayloadSchema>;
+/**
+ * A finished short on `agentProjects/{projectId}.shorts[]`. Carries the copy
+ * the composer needs (title/hook) plus the reframed MP4 and its source span so
+ * the user can trace / re-edit it.
+ */
+export interface ProducedShort {
+    index: number;
+    title: string;
+    hook: string;
+    reason: string;
+    score: number;
+    /** Source span this short was cut from, ms. */
+    sourceStartMs: number;
+    sourceEndMs: number;
+    /** Output aspect (the requested target, e.g. "9:16"). */
+    aspect: string;
+    /** Long-lived signed URL of the reframed short MP4. */
+    mp4Url: string;
+    durationMs: number;
+    width: number;
+    height: number;
+}
+/**
+ * Flat USD overheads beyond the per-second ASR cost:
+ *   - the shorts-picker LLM call (one structured call over the transcript), and
+ *   - our ffmpeg compute per short (cut + B2 reframe + upload — our own metal,
+ *     priced so the op isn't free).
+ */
+export declare const REPURPOSE_PICKER_LLM_USD = 0.05;
+export declare const REPURPOSE_COMPUTE_PER_SHORT_USD = 0.03;
+/** Default shorts assumed for the upfront estimate when maxShorts is omitted. */
+export declare const DEFAULT_MAX_SHORTS = 5;
+/**
+ * Pure upfront credit estimate for a repurpose job. The controller deducts this
+ * before enqueue; the worker reconciles against the REAL ASR duration and the
+ * actual number of shorts produced, refunding any overcharge. 1 credit = $0.10.
+ * Shorts picking needs no diarization (no speaker-aware Q→A constraint), so no
+ * diarization surcharge — unlike L-5's podcast/interview goals.
+ */
+export declare function estimateRepurposeCredits(args: {
+    sourceDurationSec: number;
+    maxShorts?: number;
+}): number;
+//# sourceMappingURL=repurpose.schema.d.ts.map

package/lib/services/agent/repurpose/repurpose.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repurpose.schema.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/repurpose/repurpose.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;kBA4BxB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,iFAAiF;AACjF,eAAO,MAAM,YAAY,OAAQ,CAAC;AAClC,eAAO,MAAM,YAAY,SAAU,CAAC;AACpC,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;kBAqB7B,CAAC;AACL,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,eAAe;;;;;;;;;;;kBAMjB,CAAC;AACZ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;kBAO3B,CAAC;AACZ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAI5E;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAGpD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAQT"}

package/lib/services/agent/repurpose/repurpose.schema.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_SHORTS = exports.REPURPOSE_COMPUTE_PER_SHORT_USD = exports.REPURPOSE_PICKER_LLM_USD = exports.RepurposeJobPayloadSchema = exports.ShortPlanSchema = exports.ShortCandidateSchema = exports.SHORT_LABEL_MAX = exports.SHORT_REASON_MAX = exports.SHORT_HOOK_MAX = exports.SHORT_TITLE_MAX = exports.MAX_SHORT_MS = exports.MIN_SHORT_MS = exports.RepurposeRequestSchema = void 0;
+exports.estimateRepurposeCredits = estimateRepurposeCredits;
+const zod_1 = require("zod");
+const project_schema_1 = require("../../../schemas/project.schema");
+const helpers_1 = require("../../../utils/helpers");
+/**
+ * X8 Social Suite · Phase 6 · E3 — "auto-repurpose" schemas.
+ *
+ * One long source video → an LLM picks the strongest STANDALONE moments → each
+ * becomes an independent, platform-native vertical short (its own title + hook
+ * + score). This is opus.pro's core loop; we can do it AND host the source
+ * generation, so the long-form and its shorts share one brain + one bill.
+ *
+ * Deliberately a sibling of L-5 (edit-existing), not a fork of it. L-5 picks N
+ * segments and CONCATENATES them into ONE tighter recut; E3 picks N
+ * INDEPENDENT spans and emits N separate shorts. They share the ffmpeg
+ * primitives (cut/probe/upload) and the ASR transcript shape, but the
+ * selection brain and the output shape are different — so E3 gets its own pure
+ * picker (shortsPicker.ts) and its own worker, leaving the proven L-5 path
+ * untouched.
+ *
+ * As with the rest of the agent surface, the PURE logic (span selection,
+ * clamping, scoring, credit math) lives in `shared` so it is unit-/eval-able;
+ * the IO-heavy stages (download → ASR → ffmpeg cut → B2 reframe → upload) run
+ * in the node-express worker where ffmpeg already is.
+ */
+// ─── request (the controller body) ───────────────────────────────────────────
+exports.RepurposeRequestSchema = zod_1.z
+    .object({
+    /** Publicly-fetchable URL of the long source video (Firebase Storage / signed). */
+    sourceVideoUrl: zod_1.z.string().url(),
+    /**
+     * Source duration in seconds — the uploader knows it, and we need it for the
+     * UPFRONT credit estimate (ASR is billed per second). The worker reconciles
+     * against the real ASR `audioDuration` after transcription.
+     */
+    sourceDurationSec: zod_1.z.number().positive(),
+    /** Hard cap on how many shorts to produce. Picker default is 5 if omitted. */
+    maxShorts: zod_1.z.number().int().positive().max(20).optional(),
+    /**
+     * Target length of EACH short in seconds. The picker treats this as a soft
+     * aim (it won't pad weak material to hit it). Omitted → ~30s default.
+     */
+    targetShortSec: zod_1.z.number().positive().max(180).optional(),
+    /** Output aspect for the shorts. Default 9:16 (Reels/Shorts/TikTok). */
+    aspect: project_schema_1.AspectSchema.optional(),
+    /** ASR language hint (e.g. "en", "es"). Omitted → AssemblyAI autodetect. */
+    language: zod_1.z.string().min(2).max(10).optional(),
+    /** Free-form steering for the picker ("focus on the product demo", etc.). */
+    instructions: zod_1.z.string().max(2000).optional(),
+    /** Tone hint for the generated hooks ("energetic", "professional"). */
+    tone: zod_1.z.string().max(200).optional(),
+    /** Display title prefix for the produced shorts / project. */
+    title: zod_1.z.string().max(200).optional(),
+})
+    .strict();
+// ─── short candidates (LLM output) ───────────────────────────────────────────
+/** Bounds for a single short, enforced after the LLM picks (see clampShorts). */
+exports.MIN_SHORT_MS = 3000;
+exports.MAX_SHORT_MS = 180000;
+exports.SHORT_TITLE_MAX = 100;
+exports.SHORT_HOOK_MAX = 280;
+exports.SHORT_REASON_MAX = 500;
+exports.SHORT_LABEL_MAX = 120;
+/**
+ * One standalone short: a single contiguous span of the source plus the copy
+ * needed to post it. (v1 is one span per short — a jump-cut micro-montage per
+ * short is a deferred enhancement; the shape stays span-based so it's easy to
+ * extend later.) Per-platform caption variants are NOT produced here — the E1
+ * caption generator can enrich each short downstream from `title`/`hook`.
+ */
+exports.ShortCandidateSchema = zod_1.z
+    .object({
+    /** Inclusive start in the SOURCE timeline, ms. */
+    startMs: zod_1.z.number().nonnegative(),
+    /** Exclusive end in the SOURCE timeline, ms. Must be > startMs (refined below). */
+    endMs: zod_1.z.number().positive(),
+    /** Short, scroll-stopping title (used by YouTube Shorts). */
+    title: zod_1.z.string().max(exports.SHORT_TITLE_MAX),
+    /** First-line caption hook — the opening line that earns the watch. */
+    hook: zod_1.z.string().max(exports.SHORT_HOOK_MAX),
+    /** Why this moment stands alone as a short — surfaced in the UI + eval. */
+    reason: zod_1.z.string().max(exports.SHORT_REASON_MAX),
+    /** Predicted engagement 0–100 (used to rank when more are picked than the cap). */
+    score: zod_1.z.number().min(0).max(100),
+    /** Optional short human label (e.g. "The pricing reveal"). */
+    label: zod_1.z.string().max(exports.SHORT_LABEL_MAX).optional(),
+})
+    .strict()
+    .refine((s) => s.endMs > s.startMs, {
+    message: "endMs must be greater than startMs",
+    path: ["endMs"],
+});
+exports.ShortPlanSchema = zod_1.z
+    .object({
+    shorts: zod_1.z.array(exports.ShortCandidateSchema).min(1),
+    /** One-line description of the repurpose run (optional; shown in UI). */
+    summary: zod_1.z.string().max(500).optional(),
+})
+    .strict();
+// ─── BullMQ envelope ─────────────────────────────────────────────────────────
+/**
+ * Tiny job envelope — same design rule as EditJobPayload: the full request
+ * lives on `agentProjects/{projectId}.repurposeRequest`, the worker reads it at
+ * job start. Keeps the Redis stream light.
+ */
+exports.RepurposeJobPayloadSchema = zod_1.z
+    .object({
+    runId: zod_1.z.string().min(1),
+    projectId: zod_1.z.string().min(1),
+    userId: zod_1.z.string().min(1),
+    enqueuedAt: zod_1.z.number().int().nonnegative(),
+})
+    .strict();
+// ─── cost ────────────────────────────────────────────────────────────────────
+/**
+ * Flat USD overheads beyond the per-second ASR cost:
+ *   - the shorts-picker LLM call (one structured call over the transcript), and
+ *   - our ffmpeg compute per short (cut + B2 reframe + upload — our own metal,
+ *     priced so the op isn't free).
+ */
+exports.REPURPOSE_PICKER_LLM_USD = 0.05;
+exports.REPURPOSE_COMPUTE_PER_SHORT_USD = 0.03;
+/** AssemblyAI Universal-2 base rate, $/hr (mirrors AssemblyAIService / L-5). */
+const ASR_USD_PER_HOUR = 0.15;
+/** Default shorts assumed for the upfront estimate when maxShorts is omitted. */
+exports.DEFAULT_MAX_SHORTS = 5;
+/**
+ * Pure upfront credit estimate for a repurpose job. The controller deducts this
+ * before enqueue; the worker reconciles against the REAL ASR duration and the
+ * actual number of shorts produced, refunding any overcharge. 1 credit = $0.10.
+ * Shorts picking needs no diarization (no speaker-aware Q→A constraint), so no
+ * diarization surcharge — unlike L-5's podcast/interview goals.
+ */
+function estimateRepurposeCredits(args) {
+    const shorts = args.maxShorts ?? exports.DEFAULT_MAX_SHORTS;
+    const asrUsd = (ASR_USD_PER_HOUR / 3600) * Math.max(0, args.sourceDurationSec);
+    const totalUsd = asrUsd +
+        exports.REPURPOSE_PICKER_LLM_USD +
+        exports.REPURPOSE_COMPUTE_PER_SHORT_USD * Math.max(1, shorts);
+    return (0, helpers_1.getCreditsFromCost)(totalUsd);
+}

package/lib/services/agent/repurpose/shortsPicker.d.ts

@@ -0,0 +1,25 @@
+import { LlmCaller } from "../llmCaller";
+import { TranscriptForPicking } from "../editExisting/highlightPicker";
+import { RepurposeRequest, ShortCandidate } from "./repurpose.schema";
+/**
+ * Clamp shorts into [0, sourceDurationMs], cap each to MAX_SHORT_MS, drop
+ * slivers below MIN_SHORT_MS, sort chronologically, and remove overlaps (a
+ * later span starting before the previous one ended is pushed forward; if that
+ * collapses it below the minimum, it's dropped). Also clamps the copy fields
+ * and score. Pure + idempotent — safe on already-clean input.
+ */
+export declare function clampShorts(shorts: ShortCandidate[], sourceDurationMs: number): ShortCandidate[];
+/**
+ * Pick standalone shorts from a transcript. Retries up to `maxRetries` times,
+ * feeding the model its previous problems. Throws only if every attempt yields
+ * zero usable shorts.
+ */
+export declare function pickShortsCore(llm: LlmCaller, args: {
+    request: RepurposeRequest;
+    transcript: TranscriptForPicking;
+    maxRetries?: number;
+}): Promise<{
+    shorts: ShortCandidate[];
+    summary?: string;
+}>;
+//# sourceMappingURL=shortsPicker.d.ts.map

package/lib/services/agent/repurpose/shortsPicker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortsPicker.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/repurpose/shortsPicker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAEL,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAIL,gBAAgB,EAChB,cAAc,EAKf,MAAM,oBAAoB,CAAC;AAwG5B;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EAAE,EACxB,gBAAgB,EAAE,MAAM,GACvB,cAAc,EAAE,CA4BlB;AAmDD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;IACJ,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,oBAAoB,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,OAAO,CAAC;IAAE,MAAM,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0DzD"}

package/lib/services/agent/repurpose/shortsPicker.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampShorts = clampShorts;
+exports.pickShortsCore = pickShortsCore;
+const zod_1 = require("zod");
+const logger_1 = require("../../../utils/logger");
+const modelRouter_1 = require("../modelRouter");
+const highlightPicker_1 = require("../editExisting/highlightPicker");
+const repurpose_schema_1 = require("./repurpose.schema");
+/**
+ * X8 Social Suite · Phase 6 · E3 — shorts picker. The reasoning core of the
+ * auto-repurpose pipeline: given an ASR transcript of a LONG video, an LLM
+ * selects the strongest STANDALONE spans, each of which becomes an independent
+ * vertical short with its own title, hook, and predicted-engagement score.
+ *
+ * Pure (injected LlmCaller), so the worker, scripts, and a no-spend eval can
+ * all drive it. Reuses L-5's transcript shape + `buildTranscriptLines` (same
+ * AssemblyAI output), but the selection bias is the opposite: L-5 keeps a
+ * continuous "best of" recut; here every pick must work ALONE as a clip.
+ */
+const DEFAULT_TARGET_SHORT_SEC = 30;
+/**
+ * The raw LLM output. Looser than ShortCandidateSchema (no refine / max) on
+ * purpose — we bounds-check + clamp afterwards so a slightly-off model answer
+ * is repaired rather than rejected.
+ */
+const LlmShortsSchema = zod_1.z.object({
+    shorts: zod_1.z
+        .array(zod_1.z.object({
+        startMs: zod_1.z.number(),
+        endMs: zod_1.z.number(),
+        title: zod_1.z.string(),
+        hook: zod_1.z.string(),
+        reason: zod_1.z.string(),
+        score: zod_1.z.number(),
+        label: zod_1.z.string().optional(),
+    }))
+        .min(1),
+    summary: zod_1.z.string().optional(),
+});
+function fmtTs(ms) {
+    const totalSec = Math.floor(ms / 1000);
+    const m = Math.floor(totalSec / 60);
+    const s = totalSec % 60;
+    return `${m}:${String(s).padStart(2, "0")}`;
+}
+function buildMessages(request, transcript, feedback) {
+    const targetSec = request.targetShortSec ?? DEFAULT_TARGET_SHORT_SEC;
+    const maxShorts = request.maxShorts ?? repurpose_schema_1.DEFAULT_MAX_SHORTS;
+    const system = [
+        "You are a short-form video strategist (think the editor behind a viral",
+        "Reels/TikTok/Shorts channel). You are given a timestamped transcript of a",
+        "LONG source video and must choose the spans that would each become the",
+        "BEST STANDALONE vertical short. Output only spans that exist in the",
+        "transcript, using millisecond start/end times taken from the bracketed",
+        "timestamps.",
+        "",
+        "Each short MUST work on its own with no other context:",
+        "- It opens on a strong hook and resolves a complete thought (never cut",
+        "  mid-sentence).",
+        "- It is self-contained: a viewer who never saw the rest still gets value.",
+        `- Aim for roughly ${Math.round(targetSec)}s each (a tight ${repurpose_schema_1.MIN_SHORT_MS / 1000}–${repurpose_schema_1.MAX_SHORT_MS / 1000}s is the hard range); shorter & punchier beats padded.`,
+        "- Spans must NOT overlap each other and must lie within the video bounds.",
+        `- Every span must lie within [0, ${transcript.audioDurationMs}] ms.`,
+        "",
+        "For each short also write:",
+        "- `title`: a scroll-stopping title (≤ ~10 words) for YouTube Shorts.",
+        "- `hook`: the first-line caption that earns the watch (curiosity / payoff /",
+        "  bold claim) — one or two sentences.",
+        "- `reason`: why this moment stands alone as a short.",
+        "- `score`: 0–100 predicted engagement; reserve 80+ for genuinely strong picks.",
+        "Pick QUALITY over quantity — only spans that are actually share-worthy.",
+    ].join("\n");
+    const langLine = request.language
+        ? `Write the title and hook in this language (BCP-47 "${request.language}").`
+        : "Write the title and hook in the same language the transcript is spoken in.";
+    const toneLine = request.tone
+        ? `Tone for the title/hook: ${request.tone}.`
+        : "";
+    const user = [
+        `GOAL: repurpose this long video into up to ${maxShorts} standalone vertical shorts.`,
+        langLine,
+        toneLine,
+        request.instructions ? `ADDITIONAL INSTRUCTIONS: ${request.instructions}` : "",
+        feedback ? `\nYOUR PREVIOUS ANSWER HAD PROBLEMS — FIX THESE:\n${feedback}` : "",
+        "",
+        `TRANSCRIPT (total ${fmtTs(transcript.audioDurationMs)}):`,
+        (0, highlightPicker_1.buildTranscriptLines)(transcript),
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return [
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ];
+}
+/**
+ * Clamp shorts into [0, sourceDurationMs], cap each to MAX_SHORT_MS, drop
+ * slivers below MIN_SHORT_MS, sort chronologically, and remove overlaps (a
+ * later span starting before the previous one ended is pushed forward; if that
+ * collapses it below the minimum, it's dropped). Also clamps the copy fields
+ * and score. Pure + idempotent — safe on already-clean input.
+ */
+function clampShorts(shorts, sourceDurationMs) {
+    const bounded = shorts
+        .map((s) => {
+        const startMs = Math.max(0, Math.min(s.startMs, sourceDurationMs));
+        let endMs = Math.max(0, Math.min(s.endMs, sourceDurationMs));
+        if (endMs - startMs > repurpose_schema_1.MAX_SHORT_MS)
+            endMs = startMs + repurpose_schema_1.MAX_SHORT_MS;
+        return {
+            startMs,
+            endMs,
+            title: (s.title ?? "").slice(0, repurpose_schema_1.SHORT_TITLE_MAX),
+            hook: (s.hook ?? "").slice(0, repurpose_schema_1.SHORT_HOOK_MAX),
+            reason: (s.reason ?? "").slice(0, repurpose_schema_1.SHORT_REASON_MAX),
+            score: Math.max(0, Math.min(100, Number.isFinite(s.score) ? s.score : 0)),
+            ...(s.label ? { label: s.label.slice(0, repurpose_schema_1.SHORT_LABEL_MAX) } : {}),
+        };
+    })
+        .filter((s) => s.endMs - s.startMs >= repurpose_schema_1.MIN_SHORT_MS)
+        .sort((a, b) => a.startMs - b.startMs);
+    const out = [];
+    let prevEnd = 0;
+    for (const s of bounded) {
+        const start = Math.max(s.startMs, prevEnd);
+        if (s.endMs - start < repurpose_schema_1.MIN_SHORT_MS)
+            continue; // collapsed by overlap removal
+        out.push({ ...s, startMs: start });
+        prevEnd = s.endMs;
+    }
+    return out;
+}
+/**
+ * Validate + repair a raw LLM selection against the transcript bounds and the
+ * request constraints. Returns cleaned shorts (top-`maxShorts` by score, then
+ * re-sorted chronologically) and human-readable problems used as retry feedback.
+ */
+function validateSelection(raw, request, audioDurationMs) {
+    const problems = [];
+    const maxShorts = request.maxShorts ?? repurpose_schema_1.DEFAULT_MAX_SHORTS;
+    const mapped = raw.shorts.map((s) => ({
+        startMs: s.startMs,
+        endMs: s.endMs,
+        title: s.title ?? "",
+        hook: s.hook ?? "",
+        reason: s.reason ?? "",
+        score: s.score ?? 0,
+        ...(s.label ? { label: s.label } : {}),
+    }));
+    const outOfBounds = mapped.filter((s) => s.startMs < 0 || s.endMs > audioDurationMs + 250 || s.endMs <= s.startMs);
+    if (outOfBounds.length > 0) {
+        problems.push(`${outOfBounds.length} short(s) were out of bounds or had endMs ≤ startMs (video is ${audioDurationMs}ms). Keep every span inside [0, ${audioDurationMs}] with endMs > startMs.`);
+    }
+    let cleaned = clampShorts(mapped, audioDurationMs);
+    if (cleaned.length === 0) {
+        return { shorts: [], problems };
+    }
+    if (cleaned.length > maxShorts) {
+        // Keep the strongest by score, then restore chronological order.
+        cleaned = [...cleaned]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, maxShorts)
+            .sort((a, b) => a.startMs - b.startMs);
+    }
+    return { shorts: cleaned, problems };
+}
+/**
+ * Pick standalone shorts from a transcript. Retries up to `maxRetries` times,
+ * feeding the model its previous problems. Throws only if every attempt yields
+ * zero usable shorts.
+ */
+async function pickShortsCore(llm, args) {
+    const router = new modelRouter_1.ModelRouter();
+    const maxRetries = args.maxRetries ?? 2;
+    const { request, transcript } = args;
+    let feedback;
+    let lastProblems = [];
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const res = await llm.structured({
+            model: router.pickFor("planner"),
+            fallbackModel: router.fallbackFor("planner"),
+            schema: LlmShortsSchema,
+            schemaName: "ShortPlan",
+            messages: buildMessages(request, transcript, feedback),
+            temperature: 0.4,
+            maxTokens: 8000,
+        });
+        const { shorts, problems } = validateSelection(res.data, request, transcript.audioDurationMs);
+        lastProblems = problems;
+        if (shorts.length > 0 && problems.length === 0) {
+            logger_1.logger.info("repurpose.picker: selection accepted", {
+                attempt,
+                shorts: shorts.length,
+                audioDurationMs: transcript.audioDurationMs,
+            });
+            return { shorts, ...(res.data.summary ? { summary: res.data.summary } : {}) };
+        }
+        // Usable-but-imperfect on the final attempt: accept rather than throw — a
+        // few good shorts beat failing the whole job.
+        if (shorts.length > 0 && attempt === maxRetries) {
+            logger_1.logger.warn("repurpose.picker: accepting imperfect selection on last attempt", {
+                shorts: shorts.length,
+                problems,
+            });
+            return { shorts, ...(res.data.summary ? { summary: res.data.summary } : {}) };
+        }
+        feedback =
+            problems.join("\n") ||
+                "Your previous answer returned no usable shorts. Select at least one strong, self-contained span with valid timestamps.";
+        logger_1.logger.warn("repurpose.picker: retrying", {
+            attempt,
+            problems,
+            durationMs: transcript.audioDurationMs,
+        });
+    }
+    throw new Error(`repurpose.picker: no usable shorts after ${maxRetries + 1} attempts (${lastProblems.join("; ")})`);
+}

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

@@ -1,4 +1,5 @@
 import { VideoPlan } from "../../schemas/videoPlan.schema";
+import { Clip } from "../../schemas/project.schema";
 import { SceneRenderOutcome } from "../editor/planToProject";
 import { SceneOutcome } from "./executor";
 /**
@@ -21,6 +22,24 @@ export declare function outcomeToRenderOutcome(outcome: SceneOutcome): SceneRend
  * C14: critical for keeping the agentRuns doc under the 1 MiB limit.
  */
 export declare function resolveVoiceoverUrl(outcome: SceneOutcome, projectId: string): Promise<void>;
+/**
+ * AG-3 — auto-captions. Runs AFTER resolveVoiceoverUrl (needs the uploaded
+ * voiceoverUrl, which the executor never has — it only produces base64). When
+ * the scene opted in via plan (scene.autoCaptions) AND a VO actually landed,
+ * transcribe the VO with the generate_captions tool (AssemblyAI → Whisper
+ * fallback, cached) and stamp word-level timing onto the outcome so
+ * planToProject renders a CaptionClip. ASR word times are ms from the audio
+ * start, which equals scene start, so they're already scene-relative.
+ *
+ * Idempotent (skips if captionWords already set). Best-effort: a transcription
+ * failure or an over-budget pending result just leaves the scene caption-less
+ * rather than failing the run — the host swallows the throw.
+ */
+export declare function resolveSceneCaptions(outcome: SceneOutcome, ctx: {
+    userId: string;
+    agentRunId: string;
+    projectId: string;
+}): Promise<void>;
 /**
  * Stage 3 — write the initial Project shell after the planner approves a
  * plan. All scene clips exist with placeholder URLs so editor + drawer
@@ -30,7 +49,7 @@ export declare function resolveVoiceoverUrl(outcome: SceneOutcome, projectId: st
  * C23: critical for keeping the editor / drawer from sitting on an empty
  * timeline for 20+ minutes while the worker runs.
  */
-export declare function writeAgentProjectShell(projectId: string, plan: VideoPlan, agentRunId: string): Promise<void>;
+export declare function writeAgentProjectShell(projectId: string, plan: VideoPlan, agentRunId: string, preserveClips?: Clip[], frozenVisualScenes?: ReadonlySet<number>): Promise<void>;
 /**
  * Stage 3 — write a partially-completed Project after each scene
  * finishes. Rebuilds the full Project from plan + accumulated outcomes
@@ -40,5 +59,5 @@ export declare function writeAgentProjectShell(projectId: string, plan: VideoPla
  *
  * C24 / C25: per-scene incremental update + soft-fail behavior.
  */
-export declare function writeAgentProjectIncremental(projectId: string, plan: VideoPlan, outcomesSoFar: Record<number, SceneOutcome>, agentRunId: string): Promise<void>;
+export declare function writeAgentProjectIncremental(projectId: string, plan: VideoPlan, outcomesSoFar: Record<number, SceneOutcome>, agentRunId: string, preserveClips?: Clip[], frozenVisualScenes?: ReadonlySet<number>): Promise<void>;
 //# sourceMappingURL=runHelpers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"runHelpers.d.ts","sourceRoot":"","sources":["../../../src/services/agent/runHelpers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAE3D,OAAO,EAAiB,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAI5E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA6C1C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,GACpB,kBAAkB,GAAG,SAAS,CAkBhC;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,EACf,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC3C,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAuBf"}
+{"version":3,"file":"runHelpers.d.ts","sourceRoot":"","sources":["../../../src/services/agent/runHelpers.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AAEpD,OAAO,EAAiB,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAI5E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8C1C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,GACpB,kBAAkB,GAAG,SAAS,CA2BhC;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,IAAI,EAAE,EACtB,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAwBf;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,SAAS,EACf,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC3C,UAAU,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,IAAI,EAAE,EACtB,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,CAyBf"}