vidspotai-shared 1.0.82 → 1.0.84

package/lib/services/agent/chatAgent.js

@@ -3,11 +3,105 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = defineTool;
 exports.runChatTurn = runChatTurn;
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const zod_1 = require("zod");
 const logger_1 = require("../../utils/logger");
+/** Strip JSON-Schema keys Anthropic's tool `input_schema` doesn't want. */
+function toAnthropicInputSchema(schema) {
+    const json = zod_1.z.toJSONSchema(schema);
+    // Anthropic's input_schema is a plain object schema; the `$schema` dialect
+    // marker is noise (and the top-level `description` is redundant with the
+    // tool's own description). Drop both; keep everything else verbatim.
+    delete json.$schema;
+    delete json.description;
+    return json;
+}
+function defineTool(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        inputSchema: toAnthropicInputSchema(spec.schema),
+        schema: spec.schema,
+        run: spec.run,
+    };
+}
 const DEFAULT_MAX_ROUNDS = 6;
 const DEFAULT_MAX_TOKENS = 4096;
+// ─────────────────── context compaction ───────────────────
+//
+// A multi-round tool-use turn accumulates every tool_result into the running
+// `convo`. Some results are large (a full-plan get_project_state, a 30-item
+// list_user_assets), and six rounds of them can crowd the model's context
+// window — degrading or eventually erroring the next round. We bound the
+// tool-result transcript with two structure-preserving levers (we only ever
+// shrink the *content string* of a tool_result, never drop the block, so every
+// tool_use keeps its matching tool_result and the request stays well-formed):
+//
+//   1. Hard-cap each individual tool_result (head+tail kept, middle elided).
+//   2. If the transcript still exceeds budget, elide the OLDEST results to a
+//      stub (oldest-first), always preserving the newest few verbatim — by the
+//      time we're several rounds deep the model rarely needs round-1 output.
+//
+// Chars (not tokens) are the unit: cheap to measure, ~4 chars/token, and the
+// caps are deliberately generous so this only fires on genuinely large turns.
+const DEFAULT_MAX_RESULT_CHARS = 12000; // per single tool_result
+const DEFAULT_MAX_TRANSCRIPT_CHARS = 90000; // ~22k tokens across all tool_results
+const DEFAULT_KEEP_RECENT_RESULTS = 2; // newest N never elided past the per-result cap
+function isToolResultBlock(b) {
+    return b.type === "tool_result";
+}
+/** Keep the head and tail, elide the middle with a byte-count marker. */
+function elideMiddle(s, cap) {
+    if (s.length <= cap)
+        return s;
+    const head = Math.ceil(cap * 0.6);
+    const tail = Math.max(0, Math.floor(cap * 0.25));
+    const removed = s.length - head - tail;
+    return `${s.slice(0, head)}\n…[${removed} chars elided to save context]…\n${s.slice(s.length - tail)}`;
+}
+/**
+ * Bound the running tool-result transcript in place. Mutates the `content` of
+ * `tool_result` blocks within `convo` (never removes a block) and reports how
+ * many characters were shed so the caller can log when compaction fired.
+ */
+function compactConversation(convo, opts) {
+    // Collect every string-bodied tool_result, in chronological order.
+    const results = [];
+    for (const msg of convo) {
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (isToolResultBlock(block) && typeof block.content === "string") {
+                results.push(block);
+            }
+        }
+    }
+    let removed = 0;
+    // Pass 1 — hard-cap each result so one pathological payload can't dominate.
+    for (const block of results) {
+        const content = block.content;
+        if (content.length > opts.maxResultChars) {
+            const next = elideMiddle(content, opts.maxResultChars);
+            removed += content.length - next.length;
+            block.content = next;
+        }
+    }
+    const transcriptChars = () => results.reduce((n, b) => n + (typeof b.content === "string" ? b.content.length : 0), 0);
+    // Pass 2 — if still over budget, stub the oldest results, preserving newest K.
+    const elidable = results.slice(0, Math.max(0, results.length - opts.keepRecentResults));
+    for (let i = 0; i < elidable.length && transcriptChars() > opts.maxTranscriptChars; i++) {
+        const block = elidable[i];
+        const content = block.content;
+        const stub = `[earlier tool result elided to save context — was ${content.length} chars]`;
+        if (content.length > stub.length) {
+            removed += content.length - stub.length;
+            block.content = stub;
+        }
+    }
+    return { compacted: removed > 0, removedChars: removed };
+}
 /**
  * Drive one chat turn. Yields events as they happen so the caller can
  * forward straight to SSE; the final event is always `final` (success)
@@ -30,6 +124,19 @@ async function* runChatTurn(req) {
     ];
     const maxRounds = req.maxRounds ?? DEFAULT_MAX_ROUNDS;
     for (let round = 0; round < maxRounds; round++) {
+        // Bound the tool-result transcript before each round so a long, tool-heavy
+        // turn can't overflow the context window. No-op on round 0 (no results yet).
+        const compaction = compactConversation(convo, {
+            maxResultChars: DEFAULT_MAX_RESULT_CHARS,
+            maxTranscriptChars: DEFAULT_MAX_TRANSCRIPT_CHARS,
+            keepRecentResults: DEFAULT_KEEP_RECENT_RESULTS,
+        });
+        if (compaction.compacted) {
+            logger_1.logger.info("chatAgent: compacted tool-result transcript", {
+                round,
+                removedChars: compaction.removedChars,
+            });
+        }
         yield { kind: "status", phase: "thinking" };
         // Per-round stream. We accumulate text and tool_use blocks; if the
         // stop_reason is tool_use we execute and loop, else we yield the
@@ -108,16 +215,45 @@ async function* runChatTurn(req) {
                 result = { error: `unknown tool: ${use.name}` };
             }
             else {
-                try {
-                    result = await tool.run(use.input);
+                // Validate the model's raw args against the tool's Zod schema (when it
+                // has one) BEFORE dispatch. On failure we hand the model a structured
+                // error rather than letting bad input reach `run` or hard-failing the
+                // turn — it can correct itself on the next round. On success `run`
+                // receives the parsed, typed value (unknown keys stripped).
+                let input = use.input;
+                let valid = true;
+                if (tool.schema) {
+                    const parsed = tool.schema.safeParse(use.input);
+                    if (parsed.success) {
+                        input = parsed.data;
+                    }
+                    else {
+                        valid = false;
+                        result = {
+                            error: "invalid tool arguments",
+                            issues: parsed.error.issues.map((i) => ({
+                                path: i.path.join(".") || "(root)",
+                                message: i.message,
+                            })),
+                        };
+                        logger_1.logger.warn("chatAgent: tool args failed schema validation", {
+                            tool: use.name,
+                            toolUseId: use.id,
+                        });
+                    }
                 }
-                catch (err) {
-                    logger_1.logger.error("chatAgent: tool execution failed", {
-                        tool: use.name,
-                        toolUseId: use.id,
-                        err: err instanceof Error ? err.stack ?? err.message : String(err),
-                    });
-                    result = { error: err.message };
+                if (valid) {
+                    try {
+                        result = await tool.run(input);
+                    }
+                    catch (err) {
+                        logger_1.logger.error("chatAgent: tool execution failed", {
+                            tool: use.name,
+                            toolUseId: use.id,
+                            err: err instanceof Error ? err.stack ?? err.message : String(err),
+                        });
+                        result = { error: err.message };
+                    }
                 }
             }
             yield { kind: "tool_result", id: use.id, result };

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

@@ -31,7 +31,7 @@ export declare function estimateSceneCredits(scene: {
  * spent (no refund delta), so we don't have to track per-call actuals.
  *
  * Pass `bibleBuilt: false` for cache hits to skip the bible charge. Pass
- * `usedWebResearch: false` when the planner ran the gateway path (no
+ * `usedWebResearch: false` when the planner ran the non-research path (no
  * Anthropic web_search). `usedThinking` mirrors T3 premium briefs.
  */
 export declare function estimatePlanOverheadCredits(opts: {
@@ -58,4 +58,14 @@ export declare function estimateProjectCost(project: Project): CostBreakdown;
  * when a scene omits its own estimate.
  */
 export declare function estimatePlanCost(plan: VideoPlan): CostBreakdown;
+/**
+ * Stream L (L-6) — credit↔USD conversion. The whole codebase prices 1 credit
+ * at $0.10 (see TTS / overhead comments above); this is the single source for
+ * that rate so the long-form budget guard and any UI USD display agree.
+ */
+export declare const CREDIT_USD_RATE = 0.1;
+/** Convert a credit amount to USD at the platform rate. */
+export declare function creditsToUsd(credits: number): number;
+/** Convert a USD amount to credits at the platform rate. */
+export declare function usdToCredits(usd: number): number;
 //# sourceMappingURL=costPreflight.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"costPreflight.d.ts","sourceRoot":"","sources":["../../../src/services/agent/costPreflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAmD3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CAQT;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,IAAI,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAKD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAuBnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAoB/D"}
+{"version":3,"file":"costPreflight.d.ts","sourceRoot":"","sources":["../../../src/services/agent/costPreflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,OAAO,EAAE,IAAI,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAmD3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAOT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,CAQT;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,KAAK,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,IAAI,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAKD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAuBnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAoB/D;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/lib/services/agent/costPreflight.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREDIT_USD_RATE = void 0;
 exports.estimateSceneCredits = estimateSceneCredits;
 exports.estimatePlanOverheadCredits = estimatePlanOverheadCredits;
 exports.estimateProjectCost = estimateProjectCost;
 exports.estimatePlanCost = estimatePlanCost;
+exports.creditsToUsd = creditsToUsd;
+exports.usdToCredits = usdToCredits;
 /**
  * Cost preflight — sums credits over a Project JSON's clips by their
  * provenance.creditsSpent. For clips not yet generated, falls back to a
@@ -81,7 +84,7 @@ function estimateSceneCredits(scene) {
  * spent (no refund delta), so we don't have to track per-call actuals.
  *
  * Pass `bibleBuilt: false` for cache hits to skip the bible charge. Pass
- * `usedWebResearch: false` when the planner ran the gateway path (no
+ * `usedWebResearch: false` when the planner ran the non-research path (no
  * Anthropic web_search). `usedThinking` mirrors T3 premium briefs.
  */
 function estimatePlanOverheadCredits(opts) {
@@ -141,3 +144,17 @@ function estimatePlanCost(plan) {
     const totalCredits = perClip.reduce((s, x) => s + x.credits, 0);
     return { totalCredits, byTier, perClip };
 }
+/**
+ * Stream L (L-6) — credit↔USD conversion. The whole codebase prices 1 credit
+ * at $0.10 (see TTS / overhead comments above); this is the single source for
+ * that rate so the long-form budget guard and any UI USD display agree.
+ */
+exports.CREDIT_USD_RATE = 0.1;
+/** Convert a credit amount to USD at the platform rate. */
+function creditsToUsd(credits) {
+    return credits * exports.CREDIT_USD_RATE;
+}
+/** Convert a USD amount to credits at the platform rate. */
+function usdToCredits(usd) {
+    return usd / exports.CREDIT_USD_RATE;
+}

package/lib/services/agent/covers/coverPlanner.d.ts

@@ -0,0 +1,41 @@
+import { LlmCaller } from "../llmCaller";
+import { TranscriptForPicking } from "../editExisting/highlightPicker";
+import { CoverCandidate, CoverRequest, CoverVisionReport, CoverVisionVerdict } from "./covers.schema";
+export declare function clampCovers(covers: CoverCandidate[], sourceDurationMs: number): CoverCandidate[];
+/**
+ * Pass 1 — pick cover moments + copy from a transcript. Retries up to
+ * `maxRetries`, feeding the model its previous problems. Throws only if every
+ * attempt yields zero usable covers.
+ */
+export declare function planCoversCore(llm: LlmCaller, args: {
+    request: CoverRequest;
+    transcript: TranscriptForPicking;
+    maxRetries?: number;
+}): Promise<{
+    covers: CoverCandidate[];
+    summary?: string;
+}>;
+/**
+ * Pass 2 — VISION re-score. Shows the model the extracted candidate frames (in
+ * candidate order) and asks how good each looks as a thumbnail still. Returns a
+ * verdict per frame index. No retry/repair loop: this pass is best-effort
+ * polish on top of the planner's picks, so the worker treats a thrown error as
+ * "skip vision, keep planner scores" rather than a job failure.
+ */
+export declare function rankCoversCore(llm: LlmCaller, args: {
+    request: CoverRequest;
+    frames: Array<{
+        index: number;
+        imageUrl: string;
+        headline: string;
+        angle: string;
+    }>;
+}): Promise<CoverVisionReport>;
+/**
+ * Pure score blend used by the worker: combine the planner's click-through
+ * prediction with the vision frame-quality score. A frame flagged `isPoor` is
+ * penalised hard (it can sink an otherwise-clickable concept). When no vision
+ * verdict exists, the planner score stands. Returns 0–100 (rounded).
+ */
+export declare function blendCoverScore(plannerScore: number, verdict?: CoverVisionVerdict): number;
+//# sourceMappingURL=coverPlanner.d.ts.map

package/lib/services/agent/covers/coverPlanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverPlanner.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/covers/coverPlanner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAEL,oBAAoB,EACrB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAML,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,iBAAiB,CAAC;AAuHzB,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EAAE,EACxB,gBAAgB,EAAE,MAAM,GACvB,cAAc,EAAE,CAoBlB;AAsCD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;IACJ,OAAO,EAAE,YAAY,CAAC;IACtB,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,CAyDzD;AAgBD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;IACJ,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrF,GACA,OAAO,CAAC,iBAAiB,CAAC,CA4C5B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,MAAM,CAKR"}

package/lib/services/agent/covers/coverPlanner.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampCovers = clampCovers;
+exports.planCoversCore = planCoversCore;
+exports.rankCoversCore = rankCoversCore;
+exports.blendCoverScore = blendCoverScore;
+const zod_1 = require("zod");
+const logger_1 = require("../../../utils/logger");
+const modelRouter_1 = require("../modelRouter");
+const highlightPicker_1 = require("../editExisting/highlightPicker");
+const covers_schema_1 = require("./covers.schema");
+/**
+ * X8 Social Suite · Phase 6 · E2 — cover planner. The reasoning core of the
+ * AI-covers pipeline. Two pure passes, both driven by an injected LlmCaller so
+ * the worker, scripts, and a no-spend eval can all drive them:
+ *
+ *   1. planCoversCore  (TEXT, planner role) — read the ASR transcript and pick N
+ *      cover MOMENTS spread across distinct A/B angles, each with overlay copy +
+ *      a predicted click-through score.
+ *   2. rankCoversCore  (VISION, critic role) — actually LOOK at the extracted
+ *      frames and re-score them on FRAME quality (sharp / well-framed / a face),
+ *      flagging blurry or transition-smear stills the transcript couldn't catch.
+ *
+ * Reuses E3/L-5's transcript shape + `buildTranscriptLines`. The worker blends
+ * the two scores; the vision pass is best-effort (a vision outage falls back to
+ * planner scores), so the feature still ships covers if pass 2 fails.
+ */
+/**
+ * The raw planner output. Looser than CoverCandidateSchema (no max) on purpose —
+ * we clamp/repair afterwards so a slightly-off model answer is fixed, not rejected.
+ */
+const LlmCoversSchema = zod_1.z.object({
+    covers: zod_1.z
+        .array(zod_1.z.object({
+        atMs: zod_1.z.number(),
+        headline: zod_1.z.string(),
+        subtext: zod_1.z.string().optional(),
+        angle: zod_1.z.string(),
+        reason: zod_1.z.string(),
+        score: zod_1.z.number(),
+    }))
+        .min(1),
+    summary: zod_1.z.string().optional(),
+});
+/** Loose vision output (clamped after). */
+const LlmVisionSchema = zod_1.z.object({
+    verdicts: zod_1.z
+        .array(zod_1.z.object({
+        index: zod_1.z.number(),
+        visualScore: zod_1.z.number(),
+        isPoor: zod_1.z.boolean().optional(),
+        note: zod_1.z.string().optional(),
+    }))
+        .min(0),
+});
+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 buildPlannerMessages(request, transcript, feedback) {
+    const maxCovers = request.maxCovers ?? covers_schema_1.DEFAULT_MAX_COVERS;
+    const system = [
+        "You are a thumbnail / cover strategist for short-form video (the person",
+        "who decides the frame + the few words of overlay text that win the click).",
+        "You are given a timestamped transcript of a source video and must choose",
+        "the strongest STILL MOMENTS to use as cover images, and write the overlay",
+        "copy for each. Use millisecond timestamps taken from the bracketed times.",
+        "",
+        "Pick distinct moments that would make a compelling freeze-frame: a reveal,",
+        "a peak-emotion beat, a result/payoff, a surprising visual. Spread your picks",
+        "across DIFFERENT A/B ANGLES so the set is a real test, not variations of one",
+        `idea. Prefer these angles where they fit: ${covers_schema_1.COVER_ANGLES.join(", ")}.`,
+        "",
+        "For each cover write:",
+        `- \`atMs\`: the source timestamp to grab the still from (within [0, ${transcript.audioDurationMs}] ms).`,
+        `- \`headline\`: the big overlay text — punchy, ≤ ~8 words, ≤ ${covers_schema_1.COVER_HEADLINE_MAX} chars.`,
+        `- \`subtext\`: optional smaller supporting line (≤ ${covers_schema_1.COVER_SUBTEXT_MAX} chars). Omit if the headline stands alone.`,
+        "- `angle`: which A/B angle this variant tests.",
+        "- `reason`: why this frame + copy earns the click.",
+        "- `score`: 0–100 predicted click-through; reserve 80+ for genuinely strong picks.",
+        "Pick QUALITY over quantity, and never invent moments that aren't in the transcript.",
+    ].join("\n");
+    const langLine = request.language
+        ? `Write the headline and subtext in this language (BCP-47 "${request.language}").`
+        : "Write the headline and subtext in the same language the transcript is spoken in.";
+    const toneLine = request.tone ? `Tone for the copy: ${request.tone}.` : "";
+    const user = [
+        `GOAL: produce up to ${maxCovers} cover variants for A/B testing this video.`,
+        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 covers into the source bounds, clamp copy lengths + score, de-duplicate
+ * near-identical timestamps (within DEDUPE_WINDOW_MS — two covers from the same
+ * frame add no A/B value), and sort by score desc. Pure + idempotent.
+ */
+const DEDUPE_WINDOW_MS = 1000;
+function clampCovers(covers, sourceDurationMs) {
+    const bounded = covers
+        .map((c) => ({
+        atMs: Math.max(0, Math.min(c.atMs, Math.max(0, sourceDurationMs - 1))),
+        headline: (c.headline ?? "").slice(0, covers_schema_1.COVER_HEADLINE_MAX),
+        angle: (c.angle ?? "").slice(0, covers_schema_1.COVER_ANGLE_MAX) || "curiosity",
+        reason: (c.reason ?? "").slice(0, covers_schema_1.COVER_REASON_MAX),
+        score: Math.max(0, Math.min(100, Number.isFinite(c.score) ? c.score : 0)),
+        ...(c.subtext ? { subtext: c.subtext.slice(0, covers_schema_1.COVER_SUBTEXT_MAX) } : {}),
+    }))
+        .filter((c) => c.headline.trim().length > 0)
+        .sort((a, b) => b.score - a.score);
+    // Drop later picks that land on essentially the same frame as a kept one.
+    const out = [];
+    for (const c of bounded) {
+        if (out.some((k) => Math.abs(k.atMs - c.atMs) < DEDUPE_WINDOW_MS))
+            continue;
+        out.push(c);
+    }
+    return out;
+}
+function validatePlan(raw, request, audioDurationMs) {
+    const problems = [];
+    const maxCovers = request.maxCovers ?? covers_schema_1.DEFAULT_MAX_COVERS;
+    const mapped = raw.covers.map((c) => ({
+        atMs: c.atMs,
+        headline: c.headline ?? "",
+        angle: c.angle ?? "curiosity",
+        reason: c.reason ?? "",
+        score: c.score ?? 0,
+        ...(c.subtext ? { subtext: c.subtext } : {}),
+    }));
+    const outOfBounds = mapped.filter((c) => c.atMs < 0 || c.atMs > audioDurationMs + 250);
+    if (outOfBounds.length > 0) {
+        problems.push(`${outOfBounds.length} cover(s) had a timestamp outside the video (${audioDurationMs}ms). Keep every atMs inside [0, ${audioDurationMs}].`);
+    }
+    const empties = mapped.filter((c) => !c.headline.trim());
+    if (empties.length > 0) {
+        problems.push(`${empties.length} cover(s) had an empty headline. Every cover needs overlay text.`);
+    }
+    let cleaned = clampCovers(mapped, audioDurationMs);
+    if (cleaned.length > maxCovers)
+        cleaned = cleaned.slice(0, maxCovers);
+    return { covers: cleaned, problems };
+}
+/**
+ * Pass 1 — pick cover moments + copy from a transcript. Retries up to
+ * `maxRetries`, feeding the model its previous problems. Throws only if every
+ * attempt yields zero usable covers.
+ */
+async function planCoversCore(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: LlmCoversSchema,
+            schemaName: "CoverPlan",
+            messages: buildPlannerMessages(request, transcript, feedback),
+            temperature: 0.5,
+            maxTokens: 6000,
+        });
+        const { covers, problems } = validatePlan(res.data, request, transcript.audioDurationMs);
+        lastProblems = problems;
+        if (covers.length > 0 && problems.length === 0) {
+            logger_1.logger.info("covers.planner: plan accepted", {
+                attempt,
+                covers: covers.length,
+                audioDurationMs: transcript.audioDurationMs,
+            });
+            return { covers, ...(res.data.summary ? { summary: res.data.summary } : {}) };
+        }
+        // Usable-but-imperfect on the final attempt: accept rather than throw.
+        if (covers.length > 0 && attempt === maxRetries) {
+            logger_1.logger.warn("covers.planner: accepting imperfect plan on last attempt", {
+                covers: covers.length,
+                problems,
+            });
+            return { covers, ...(res.data.summary ? { summary: res.data.summary } : {}) };
+        }
+        feedback =
+            problems.join("\n") ||
+                "Your previous answer returned no usable covers. Pick at least one strong still moment with overlay copy and a valid timestamp.";
+        logger_1.logger.warn("covers.planner: retrying", {
+            attempt,
+            problems,
+            durationMs: transcript.audioDurationMs,
+        });
+    }
+    throw new Error(`covers.planner: no usable covers after ${maxRetries + 1} attempts (${lastProblems.join("; ")})`);
+}
+function clampVerdicts(raw, frameCount) {
+    return raw.verdicts
+        .filter((v) => Number.isInteger(v.index) && v.index >= 0 && v.index < frameCount)
+        .map((v) => ({
+        index: v.index,
+        visualScore: Math.max(0, Math.min(100, Number.isFinite(v.visualScore) ? v.visualScore : 0)),
+        isPoor: Boolean(v.isPoor),
+        ...(v.note ? { note: v.note.slice(0, 200) } : {}),
+    }));
+}
+/**
+ * Pass 2 — VISION re-score. Shows the model the extracted candidate frames (in
+ * candidate order) and asks how good each looks as a thumbnail still. Returns a
+ * verdict per frame index. No retry/repair loop: this pass is best-effort
+ * polish on top of the planner's picks, so the worker treats a thrown error as
+ * "skip vision, keep planner scores" rather than a job failure.
+ */
+async function rankCoversCore(llm, args) {
+    const router = new modelRouter_1.ModelRouter();
+    const { frames } = args;
+    if (frames.length === 0)
+        return { verdicts: [] };
+    const system = [
+        "You are a thumbnail-quality judge. You are shown candidate still frames",
+        "grabbed from a video to use as social covers, in order. For EACH frame,",
+        "judge ONLY how good it looks as a still thumbnail — not the wording:",
+        "- High score: sharp, well-composed, a clear subject or expressive face,",
+        "  good contrast, leaves room for overlay text.",
+        "- Low score / isPoor=true: blurry, motion-smear, mid-blink, a transition",
+        "  frame, near-blank, or too busy to read.",
+        "Return one verdict per frame, referencing it by its 0-based `index` in the",
+        "order shown. Be decisive; reserve 80+ for genuinely strong stills.",
+    ].join("\n");
+    const ordered = [...frames].sort((a, b) => a.index - b.index);
+    const manifest = ordered
+        .map((f, i) => `Frame ${i}: angle="${f.angle}", overlay="${f.headline}"`)
+        .join("\n");
+    const res = await llm.structured({
+        model: router.pickFor("critic"),
+        fallbackModel: router.fallbackFor("critic"),
+        schema: LlmVisionSchema,
+        schemaName: "CoverVisionReport",
+        temperature: 0.2,
+        maxTokens: 2000,
+        messages: [
+            { role: "system", content: system },
+            {
+                role: "user",
+                content: [
+                    `Judge these ${ordered.length} candidate cover frames as stills.`,
+                    "They are attached in this order:",
+                    manifest,
+                ].join("\n"),
+                imageUrls: ordered.map((f) => f.imageUrl),
+            },
+        ],
+    });
+    return { verdicts: clampVerdicts(res.data, ordered.length) };
+}
+/**
+ * Pure score blend used by the worker: combine the planner's click-through
+ * prediction with the vision frame-quality score. A frame flagged `isPoor` is
+ * penalised hard (it can sink an otherwise-clickable concept). When no vision
+ * verdict exists, the planner score stands. Returns 0–100 (rounded).
+ */
+function blendCoverScore(plannerScore, verdict) {
+    if (!verdict)
+        return Math.round(plannerScore);
+    const base = 0.5 * plannerScore + 0.5 * verdict.visualScore;
+    const penalised = verdict.isPoor ? base * 0.4 : base;
+    return Math.round(Math.max(0, Math.min(100, penalised)));
+}