vidspotai-shared 1.0.84 → 1.0.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vidspotai-shared",
-  "version": "1.0.84",
+  "version": "1.0.85",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {

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

@@ -1,141 +0,0 @@
-import { PlannedScene, VideoPlan } from "../../schemas/videoPlan.schema";
-import { ToolContext, ToolOutcome } from "./toolRegistry";
-import { ProviderTaskCache, ProviderTaskCacheEntry } from "./providerTaskCache";
-export type RunToolFn = <O = unknown>(name: string, input: unknown, ctx: ToolContext) => Promise<ToolOutcome<O>>;
-/**
- * Executor — turns an approved VideoPlan into per-scene asset results.
- *
- * Plan-then-execute split (not free-form ReAct): the executor does NOT pick
- * tools. The plan dictates which tool runs per scene; the executor only does
- * the dispatch + per-scene parallelism + idempotency-key generation.
- *
- * Returns a SceneOutcome per scene, leaving composition (compose_scene),
- * critique (Critic.review), and render to the orchestrator above.
- */
-export interface SceneAssetResult {
-    /** Concrete asset URL for the visual track (image or video). */
-    visualUrl?: string;
-    /** Voiceover audio (base64 or url depending on host policy). */
-    voiceoverAudioBase64?: string;
-    /**
-     * Resolved voiceover URL once the host has uploaded the base64 buffer to
-     * its asset store (GCS / Firebase Storage). The agent.controller flow
-     * sets this in `onSceneComplete` so `planToProject` can render a real VO
-     * clip on `track-vo`. When unset, planToProject skips the VO clip.
-     */
-    voiceoverUrl?: string;
-    /** Provider task id for async generations the host still needs to poll. */
-    pendingTaskId?: string;
-    /** Model key the pending task was triggered on — the poller needs this to pick the provider. */
-    pendingModelKey?: string;
-    /** AG-22: provider chain the tool walked (in order, primary first). For trace + post-mortem. */
-    attemptedProviders?: string[];
-    /** Tool name used. */
-    tool: string;
-    /** Idempotency key the executor minted; useful for retries. */
-    idempotencyKey: string;
-    /**
-     * AG-28: estimated VO duration (ms) from the wpm heuristic. Set when
-     * voiceoverAudioBase64 is set. Used pre-upload for budget math; the
-     * editor-side display window prefers voiceoverActualMs when available.
-     */
-    voiceoverEstimateMs?: number;
-    /**
-     * Probed actual mp3 duration (ms). Stamped by `resolveVoiceoverUrl` after
-     * generation, before the buffer is discarded. Reflects real playback
-     * length — required to size the editor VO clip's display window so
-     * Remotion's `endAt` doesn't truncate emotive/punctuated deliveries that
-     * the wpm estimate undershoots. Falls back to `voiceoverEstimateMs` when
-     * ffprobe is unavailable.
-     */
-    voiceoverActualMs?: number;
-    /**
-     * AG-28: TTS over-budget signal. True when the line + style produces audio
-     * longer than scene.durationMs * 1.05 even after the executor's atempo
-     * adjustment. Stitcher should freeze-frame-pad rather than clip.
-     */
-    voiceoverOverBudget?: boolean;
-}
-export interface SceneOutcome {
-    scene: PlannedScene;
-    ok: boolean;
-    result?: SceneAssetResult;
-    error?: {
-        code: string;
-        message: string;
-        /**
-         * Set when the failure came from a provider-fallback-wrapped tool whose
-         * entire chain exhausted (or terminated on auth/safety/input). Used by
-         * the orchestrator to decide between agent re-plan / scene degrade /
-         * hard fail.
-         */
-        classification?: "transient" | "rate_limit" | "capability" | "safety" | "auth" | "quota" | "input" | "unknown";
-        needsReplan?: boolean;
-        attemptedProviders?: string[];
-    };
-    durationMs: number;
-}
-/**
- * Inspect a failed scene to decide the next orchestration step.
- *
- *   - "replan"  : agent should re-plan the scene (safety / bad input)
- *   - "degrade" : try a cheaper strategy (e.g. T2/T3 chain exhausted on quota)
- *   - "fail"    : terminal — surface to user (auth / chain-exhausted-unknown)
- *   - "retry"   : transient — caller may re-run the scene as-is later
- */
-export declare function classifySceneFailure(outcome: SceneOutcome): "replan" | "degrade" | "fail" | "retry" | null;
-export interface ExecutorOptions {
-    /** Max scenes to run in parallel. Generation providers rate-limit themselves; this guards on top. */
-    concurrency?: number;
-    /** Inject a recording wrapper (e.g. runToolRecorded) for eval / replay. */
-    runTool?: RunToolFn;
-    /**
-     * Stage 3 hook: invoked after each scene finishes (success OR failure).
-     * Lets the orchestrator stream incremental Project updates into Firestore
-     * so the editor + agent drawer surfaces light up as scenes complete,
-     * rather than waiting for the whole executor to finish. Errors thrown
-     * from the callback are swallowed (logged) so a Firestore blip can't
-     * crash the executor.
-     */
-    onSceneComplete?: (sceneIndex: number, outcome: SceneOutcome) => Promise<void>;
-    /**
-     * Stage 7 slice 1: provider task-id cache (read side). When the upstream
-     * inputs for animate_image / generate_video / generate_avatar_video hash
-     * to the same value as a cached entry (and entry is within TTL), the
-     * executor returns the cached taskId + modelKey and skips the tool call.
-     * /execute passes the project's cache here so re-runs after downstream
-     * (poll/stitch/critic) bugs reuse the prior $$ gens. /regenerate-scene
-     * deliberately omits this (user wants a fresh gen) but still mints.
-     */
-    taskCache?: ProviderTaskCache;
-    /**
-     * Stage 7 slice 1: cache write side. Invoked after a successful tool call
-     * that produced a pendingTaskId. Orchestrator persists the entry on the
-     * AgentProject doc so the NEXT execute can replay. Errors swallowed —
-     * cache is best-effort optimisation, not correctness.
-     */
-    onTaskMint?: (clipId: string, entry: ProviderTaskCacheEntry) => Promise<void>;
-}
-export declare class Executor {
-    private readonly concurrency;
-    private readonly runTool;
-    private readonly onSceneComplete?;
-    private readonly taskCache?;
-    private readonly onTaskMint?;
-    constructor(opts?: ExecutorOptions);
-    /**
-     * Stage 7 slice 1 helper. Returns cached pending-task output if the
-     * upstream input hash matches and entry is within TTL; null otherwise.
-     * Logs the hit so trace shows where $$ was saved.
-     */
-    private checkTaskCache;
-    /**
-     * Best-effort mint. Swallows callback errors — a Firestore blip must not
-     * fail the scene (the tool already succeeded and produced a real taskId).
-     */
-    private mintTaskCache;
-    run(plan: VideoPlan, ctx: ToolContext): Promise<SceneOutcome[]>;
-    private runScene;
-    private runVisual;
-}
-//# sourceMappingURL=executor.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/services/agent/executor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAIzE,OAAO,EAA6B,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGrF,OAAO,EAGL,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AA2D7B,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,OAAO,EAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7B;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gGAAgG;IAChG,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB;;;;;WAKG;QACH,cAAc,CAAC,EACX,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,GACP,SAAS,CAAC;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC/B,CAAC;IACF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,YAAY,GACpB,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAUhD;AAED,MAAM,WAAW,eAAe;IAC9B,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAiDD,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAgC;gBAEhD,IAAI,GAAE,eAAoB;IAQtC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;OAGG;YACW,aAAa;IAerB,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAiCvD,QAAQ;YA4FR,SAAS;CAsVxB"}

package/lib/services/agent/executor.js

@@ -1,561 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Executor = void 0;
-exports.classifySceneFailure = classifySceneFailure;
-const voices_1 = require("../../globals/ttsModels/voices");
-const logger_1 = require("../../utils/logger");
-const referenceImageRenderer_1 = require("./referenceImageRenderer");
-const toolRegistry_1 = require("./toolRegistry");
-const ttsDuration_1 = require("./ttsDuration");
-const chains_1 = require("./providerFallback/chains");
-const providerTaskCache_1 = require("./providerTaskCache");
-/**
- * AG-37: planners (LLMs) keep inventing voice IDs like "female-young-adult-en"
- * or "narrator-1" that look reasonable but don't exist in any catalog. When
- * those flow into ElevenLabs the API returns a 400 and the silent-fail VO
- * outcome path drops the VO entirely — final video ships muted. Strip
- * unknown IDs here so the provider falls back to its default voice instead.
- */
-const ELEVENLABS_VOICE_IDS = new Set(voices_1.ELEVENLABS_VOICES.map((v) => v.id));
-function sanitizeVoiceId(voiceId) {
-    if (!voiceId)
-        return undefined;
-    if (ELEVENLABS_VOICE_IDS.has(voiceId))
-        return voiceId;
-    // Heuristic for non-ElevenLabs providers (openai = "alloy"/"echo"/..., minimax = "male-qn-qingse").
-    // Only strip strings that look like LLM-invented descriptive labels (contain a hyphen + recognisable word).
-    if (/^(female|male|narrator|presenter|voice)[-_]/i.test(voiceId)) {
-        logger_1.logger.warn("executor: stripping invalid voiceId (LLM hallucination)", { voiceId });
-        return undefined;
-    }
-    return voiceId;
-}
-/**
- * AG-31: map a brief-level voice style adjective to ElevenLabs voice_settings.
- * `style` is the exaggeration param (use sparingly above 0.5 — artifacts);
- * `stability` is the consistency knob (low = more emotive, high = monotone);
- * `speed` is rate (0.7-1.2). Defaults match ElevenLabs' own (style=0,
- * stability=0.5, speed=1.0). Tuning per persona is conservative — we'd rather
- * be slightly flat than artifact-laden.
- */
-function resolveVoiceSettings(style) {
-    switch (style) {
-        case "calm":
-            return { style: 0.15, stability: 0.7, speed: 0.95 };
-        case "warm":
-            return { style: 0.25, stability: 0.6, speed: 1.0 };
-        case "casual":
-            return { style: 0.3, stability: 0.5, speed: 1.0 };
-        case "excited":
-            return { style: 0.55, stability: 0.35, speed: 1.05 };
-        case "energetic":
-            return { style: 0.6, stability: 0.35, speed: 1.08 };
-        case "happy":
-            return { style: 0.5, stability: 0.4, speed: 1.05 };
-        case "serious":
-            return { style: 0.2, stability: 0.75, speed: 0.95 };
-        case "dramatic":
-            return { style: 0.65, stability: 0.4, speed: 0.95 };
-        case "whisper":
-            return { style: 0.2, stability: 0.85, speed: 0.9 };
-        case "neutral":
-        case undefined:
-        default:
-            return {};
-    }
-}
-/**
- * Inspect a failed scene to decide the next orchestration step.
- *
- *   - "replan"  : agent should re-plan the scene (safety / bad input)
- *   - "degrade" : try a cheaper strategy (e.g. T2/T3 chain exhausted on quota)
- *   - "fail"    : terminal — surface to user (auth / chain-exhausted-unknown)
- *   - "retry"   : transient — caller may re-run the scene as-is later
- */
-function classifySceneFailure(outcome) {
-    if (outcome.ok)
-        return null;
-    const c = outcome.error?.classification;
-    if (!c)
-        return "fail";
-    if (outcome.error?.needsReplan)
-        return "replan"; // safety / input
-    if (c === "auth")
-        return "fail";
-    if (c === "quota")
-        return "degrade";
-    if (c === "rate_limit" || c === "transient")
-        return "retry";
-    if (c === "capability")
-        return "degrade";
-    return "fail";
-}
-/**
- * OD-T7 / AG-42 — give the planner's `preferredModel` a chance to actually run
- * when the scene duration is just slightly off from what the model accepts.
- *
- * Decision tree:
- *   1. Model has no duration constraint            → use planned duration
- *   2. Planned duration already legal              → use planned duration
- *   3. Nearest legal is within snap tolerance      → snap, log info
- *   4. Outside tolerance + explicit preferredModel → log warn ("dropping
- *      planner pick — too far from any allowed value"); use planned duration
- *      anyway so the capability filter drops it and the chain fallback runs
- *      (the withFallback warn AG-42 also logs there now)
- *
- * We intentionally do NOT throw — throwing would crash a scene mid-run and
- * lose all the other planner output. The graceful fallback chain already
- * exists; this helper just keeps the planner's pick alive when the drift is
- * small, and makes the drop visible when it isn't.
- */
-function resolveDurationForPreferredModel(modelKey, plannedDurationSec, explicit, sceneIndex) {
-    const snap = (0, chains_1.snapDurationForModel)(modelKey, plannedDurationSec);
-    if (!snap) {
-        if (explicit) {
-            logger_1.logger.warn("executor: preferredModel duration outside snap tolerance — chain fallback will pick", {
-                sceneIndex,
-                modelKey,
-                plannedDurationSec,
-            });
-        }
-        return plannedDurationSec;
-    }
-    if (snap.driftSec > 0.01) {
-        logger_1.logger.info("executor: snapped duration to fit preferredModel", {
-            sceneIndex,
-            modelKey,
-            from: snap.requestedSec,
-            to: snap.snappedSec,
-            driftSec: Number(snap.driftSec.toFixed(2)),
-        });
-    }
-    return snap.snappedSec;
-}
-class Executor {
-    constructor(opts = {}) {
-        this.concurrency = opts.concurrency ?? 4;
-        this.runTool = opts.runTool ?? toolRegistry_1.runTool;
-        this.onSceneComplete = opts.onSceneComplete;
-        this.taskCache = opts.taskCache;
-        this.onTaskMint = opts.onTaskMint;
-    }
-    /**
-     * Stage 7 slice 1 helper. Returns cached pending-task output if the
-     * upstream input hash matches and entry is within TTL; null otherwise.
-     * Logs the hit so trace shows where $$ was saved.
-     */
-    checkTaskCache(clipId, tool, input) {
-        const inputsHash = (0, providerTaskCache_1.hashTaskInputs)(input);
-        const hit = (0, providerTaskCache_1.getCachedTask)(this.taskCache, clipId, inputsHash);
-        if (hit) {
-            logger_1.logger.info("executor: task-cache hit", {
-                clipId,
-                tool,
-                modelKey: hit.modelKey,
-                taskId: hit.taskId,
-                ageMs: Date.now() - hit.createdAt,
-            });
-        }
-        return { hit, inputsHash };
-    }
-    /**
-     * Best-effort mint. Swallows callback errors — a Firestore blip must not
-     * fail the scene (the tool already succeeded and produced a real taskId).
-     */
-    async mintTaskCache(clipId, entry) {
-        if (!this.onTaskMint)
-            return;
-        try {
-            await this.onTaskMint(clipId, entry);
-        }
-        catch (err) {
-            logger_1.logger.warn("executor: onTaskMint callback threw — swallowed", {
-                clipId,
-                err: err.message,
-            });
-        }
-    }
-    async run(plan, ctx) {
-        const queue = [...plan.scenes];
-        const results = new Array(plan.scenes.length);
-        const workers = [];
-        let cursor = 0;
-        const worker = async () => {
-            while (true) {
-                const i = cursor++;
-                if (i >= queue.length)
-                    return;
-                const scene = queue[i];
-                const outcome = await this.runScene(scene, ctx, plan.aspect, plan);
-                results[i] = outcome;
-                if (this.onSceneComplete) {
-                    try {
-                        await this.onSceneComplete(scene.sceneIndex, outcome);
-                    }
-                    catch (err) {
-                        logger_1.logger.warn("executor: onSceneComplete callback threw — swallowed", {
-                            sceneIndex: scene.sceneIndex,
-                            err: err.message,
-                        });
-                    }
-                }
-            }
-        };
-        for (let i = 0; i < Math.min(this.concurrency, queue.length); i++) {
-            workers.push(worker());
-        }
-        await Promise.all(workers);
-        return results;
-    }
-    async runScene(scene, ctx, aspect, plan) {
-        const start = Date.now();
-        const idempotencyKey = `${ctx.agentRunId}:scene-${scene.sceneIndex}`;
-        const sceneCtx = { ...ctx, idempotencyKey };
-        const visualOutcome = await this.runVisual(scene, sceneCtx, aspect, plan);
-        if (!visualOutcome.ok) {
-            return {
-                scene,
-                ok: false,
-                error: visualOutcome.error,
-                durationMs: Date.now() - start,
-            };
-        }
-        let voiceoverAudioBase64;
-        let voiceoverEstimateMs;
-        let voiceoverOverBudget = false;
-        // talking-head-avatar bakes the VO into the rendered MP4; running TTS again
-        // here would just waste credits and create a duplicate audio track.
-        if (scene.voiceoverLine && scene.strategy !== "talking-head-avatar") {
-            // AG-31: brief.voice.style → ElevenLabs voice_settings.
-            // AG-28: if estimated VO > scene.durationMs, speed up TTS within natural
-            // limits (≤1.15× extra over style.speed) before falling back to a
-            // freeze-frame-pad signal for the stitcher.
-            // AG-44: per-scene voiceStyle wins over plan-level when present, so the
-            // emotional arc can shift across the timeline (frustrated → curious → excited).
-            const effectiveVoiceStyle = (scene.voiceStyle ?? plan.voiceStyle);
-            const baseSettings = resolveVoiceSettings(effectiveVoiceStyle);
-            const baseSpeed = baseSettings.speed ?? 1.0;
-            const rawEstMs = (0, ttsDuration_1.estimateTtsMs)(scene.voiceoverLine);
-            const budgetMs = scene.durationMs * 1.05;
-            // Adjusted speed: only kick in if natural speech would overrun. Cap the
-            // speedup multiplier at 1.15× style-base; faster than that sounds rushed.
-            let speed = baseSpeed;
-            if (rawEstMs > budgetMs) {
-                const needed = rawEstMs / budgetMs;
-                const cappedMultiplier = Math.min(1.15, needed);
-                speed = +(baseSpeed * cappedMultiplier).toFixed(2);
-            }
-            const adjustedEstMs = rawEstMs * (baseSpeed / speed);
-            voiceoverEstimateMs = Math.round(adjustedEstMs);
-            voiceoverOverBudget = adjustedEstMs > budgetMs;
-            const voInput = {
-                text: scene.voiceoverLine,
-                ...baseSettings,
-                // Override speed when AG-28 budget forced an adjustment.
-                speed: +Math.max(0.7, Math.min(1.2, speed)).toFixed(2),
-            };
-            const sanitized = sanitizeVoiceId(plan.voiceId);
-            if (sanitized)
-                voInput.voiceId = sanitized;
-            const voOutcome = await this.runTool("generate_voiceover", voInput, { ...sceneCtx, idempotencyKey: `${idempotencyKey}:vo` });
-            if (voOutcome.ok) {
-                voiceoverAudioBase64 = voOutcome.output.audioBase64;
-            }
-            else {
-                // AG-37: don't swallow silently — final video shipping muted with no
-                // log was the original bug. Surface the error in the result so the
-                // trace shows WHY VO is missing.
-                logger_1.logger.warn("executor: voiceover tool failed", {
-                    sceneIndex: scene.sceneIndex,
-                    error: voOutcome.error,
-                    voiceIdRequested: plan.voiceId,
-                    voiceIdSent: sanitized,
-                });
-            }
-            // Don't fail the whole scene on VO miss — host can re-run just the VO.
-        }
-        return {
-            scene,
-            ok: true,
-            result: {
-                ...visualOutcome.output,
-                voiceoverAudioBase64,
-                voiceoverEstimateMs,
-                voiceoverOverBudget,
-                idempotencyKey,
-            },
-            durationMs: Date.now() - start,
-        };
-    }
-    async runVisual(scene, ctx, aspect, plan) {
-        const durationSec = Math.max(2, Math.round(scene.durationMs / 1000));
-        // AG-13: collect reference images for this scene's bible entities. Empty
-        // array when bible is C0/C1 or no entities are tagged — image-gen falls
-        // back to pure text prompt.
-        const referenceImageUrls = (0, referenceImageRenderer_1.collectReferenceImageUrls)(plan.bible, scene.bibleEntityIds ?? []);
-        const wrap = (tool, outcome) => outcome.ok
-            ? { ok: true, output: { tool, ...outcome.output } }
-            : { ok: false, error: outcome.error };
-        switch (scene.strategy) {
-            case "stock-video":
-            case "stock-image-ken-burns": {
-                const out = await this.runTool("search_stock", {
-                    query: scene.prompt,
-                    kind: scene.strategy === "stock-video" ? "video" : "image",
-                    aspectRatio: aspect,
-                    minDurationSec: scene.strategy === "stock-video" ? durationSec : undefined,
-                }, ctx);
-                if (!out.ok)
-                    return wrap("search_stock", out);
-                const url = out.output.assets[0]?.url;
-                if (!url)
-                    return {
-                        ok: false,
-                        error: {
-                            code: "NO_STOCK_RESULTS",
-                            message: `No stock results for: ${scene.prompt}`,
-                            attemptedProviders: out.output.attemptedProviders,
-                        },
-                    };
-                return {
-                    ok: true,
-                    output: {
-                        tool: "search_stock",
-                        visualUrl: url,
-                        attemptedProviders: out.output.attemptedProviders,
-                    },
-                };
-            }
-            case "ai-image-static":
-            case "ai-image-motion": {
-                const out = await this.runTool("generate_image", {
-                    prompt: scene.prompt,
-                    modelKey: scene.preferredModel ?? "google-nano-banana",
-                    aspectRatio: aspect,
-                    ...(referenceImageUrls.length
-                        ? { inputImageUrls: referenceImageUrls }
-                        : {}),
-                }, ctx);
-                if (!out.ok)
-                    return wrap("generate_image", out);
-                return { ok: true, output: { tool: "generate_image", visualUrl: out.output.imageUrl } };
-            }
-            case "ai-image-to-video": {
-                const animateModelKey = scene.preferredModel ?? "kling-v2.6";
-                const animateDurationSec = resolveDurationForPreferredModel(animateModelKey, durationSec, !!scene.preferredModel, scene.sceneIndex);
-                // Stage 7 slice 1: cache key spans the WHOLE strategy (both image-gen
-                // + animate). Hashing only upstream-stable inputs — prompt, model,
-                // duration, aspect, reference images — lets a re-execute skip BOTH
-                // tool calls, replaying the cached animate taskId through the poller.
-                const clipId = `scene-${scene.sceneIndex}-visual`;
-                const cacheInput = {
-                    strategy: "ai-image-to-video",
-                    prompt: scene.prompt,
-                    modelKey: animateModelKey,
-                    durationSec: animateDurationSec,
-                    aspect,
-                    referenceImageUrls,
-                };
-                const { hit, inputsHash } = this.checkTaskCache(clipId, "animate_image", cacheInput);
-                if (hit) {
-                    return {
-                        ok: true,
-                        output: {
-                            tool: "animate_image",
-                            pendingTaskId: hit.taskId,
-                            pendingModelKey: hit.modelKey,
-                        },
-                    };
-                }
-                const img = await this.runTool("generate_image", {
-                    prompt: scene.prompt,
-                    modelKey: "google-nano-banana",
-                    aspectRatio: aspect,
-                    ...(referenceImageUrls.length
-                        ? { inputImageUrls: referenceImageUrls }
-                        : {}),
-                }, { ...ctx, idempotencyKey: `${ctx.idempotencyKey}:img` });
-                if (!img.ok)
-                    return wrap("generate_image", img);
-                const animate = await this.runTool("animate_image", {
-                    imageUrl: img.output.imageUrl,
-                    motionHint: scene.prompt,
-                    durationSec: animateDurationSec,
-                    modelKey: animateModelKey,
-                }, ctx);
-                if (!animate.ok)
-                    return wrap("animate_image", animate);
-                const mintedModelKey = animate.output.modelKeyUsed ?? animateModelKey;
-                await this.mintTaskCache(clipId, {
-                    tool: "animate_image",
-                    taskId: animate.output.taskId,
-                    modelKey: mintedModelKey,
-                    inputsHash,
-                    createdAt: Date.now(),
-                });
-                return {
-                    ok: true,
-                    output: {
-                        tool: "animate_image",
-                        pendingTaskId: animate.output.taskId,
-                        pendingModelKey: mintedModelKey,
-                        attemptedProviders: animate.output.attemptedProviders,
-                    },
-                };
-            }
-            case "ai-text-to-video": {
-                const t2vModelKey = scene.preferredModel ?? "kling-v2.6";
-                const t2vDurationSec = resolveDurationForPreferredModel(t2vModelKey, durationSec, !!scene.preferredModel, scene.sceneIndex);
-                const clipId = `scene-${scene.sceneIndex}-visual`;
-                const cacheInput = {
-                    strategy: "ai-text-to-video",
-                    prompt: scene.prompt,
-                    modelKey: t2vModelKey,
-                    durationSec: t2vDurationSec,
-                };
-                const { hit, inputsHash } = this.checkTaskCache(clipId, "generate_video", cacheInput);
-                if (hit) {
-                    return {
-                        ok: true,
-                        output: {
-                            tool: "generate_video",
-                            pendingTaskId: hit.taskId,
-                            pendingModelKey: hit.modelKey,
-                        },
-                    };
-                }
-                const out = await this.runTool("generate_video", {
-                    prompt: scene.prompt,
-                    modelKey: t2vModelKey,
-                    durationSec: t2vDurationSec,
-                }, ctx);
-                if (!out.ok)
-                    return wrap("generate_video", out);
-                const mintedModelKey = out.output.modelKeyUsed ?? t2vModelKey;
-                await this.mintTaskCache(clipId, {
-                    tool: "generate_video",
-                    taskId: out.output.taskId,
-                    modelKey: mintedModelKey,
-                    inputsHash,
-                    createdAt: Date.now(),
-                });
-                return {
-                    ok: true,
-                    output: {
-                        tool: "generate_video",
-                        pendingTaskId: out.output.taskId,
-                        pendingModelKey: mintedModelKey,
-                        attemptedProviders: out.output.attemptedProviders,
-                    },
-                };
-            }
-            case "user-asset": {
-                // Per-user library search. The host injects the searcher at boot
-                // (see userLibrarySearcher bootstrap); if no match, fall back to
-                // stock so the scene still renders rather than failing hard.
-                const out = await this.runTool("search_user_library", { query: scene.prompt, limit: 5 }, ctx);
-                if (out.ok) {
-                    const first = out.output.assets[0];
-                    if (first) {
-                        return { ok: true, output: { tool: "search_user_library", visualUrl: first.url } };
-                    }
-                }
-                // No hits or searcher missing — fall back to stock-video as the
-                // closest cheap substitute so the executor still produces an asset.
-                const stock = await this.runTool("search_stock", {
-                    query: scene.prompt,
-                    kind: "video",
-                    aspectRatio: aspect,
-                    minDurationSec: durationSec,
-                }, ctx);
-                if (!stock.ok)
-                    return wrap("search_stock", stock);
-                const fallbackUrl = stock.output.assets[0]?.url;
-                if (!fallbackUrl) {
-                    return {
-                        ok: false,
-                        error: {
-                            code: "USER_ASSET_NO_MATCH",
-                            message: `No user-library match for "${scene.prompt}" and no stock fallback.`,
-                            attemptedProviders: stock.output.attemptedProviders,
-                        },
-                    };
-                }
-                return {
-                    ok: true,
-                    output: {
-                        tool: "search_user_library",
-                        visualUrl: fallbackUrl,
-                        attemptedProviders: stock.output.attemptedProviders,
-                    },
-                };
-            }
-            case "talking-head-avatar": {
-                if (!scene.avatarFaceUrl) {
-                    return {
-                        ok: false,
-                        error: {
-                            code: "AVATAR_FACE_REQUIRED",
-                            message: "talking-head-avatar requires scene.avatarFaceUrl (set on the user's brand kit).",
-                        },
-                    };
-                }
-                if (!scene.voiceoverLine) {
-                    return {
-                        ok: false,
-                        error: {
-                            code: "AVATAR_VO_REQUIRED",
-                            message: "talking-head-avatar requires scene.voiceoverLine for the lipsync audio.",
-                        },
-                    };
-                }
-                const avatarMode = scene.tier === "T3" ? "pro" : "std";
-                const clipId = `scene-${scene.sceneIndex}-visual`;
-                const cacheInput = {
-                    strategy: "talking-head-avatar",
-                    inputImageUrl: scene.avatarFaceUrl,
-                    ttsText: scene.voiceoverLine,
-                    mode: avatarMode,
-                };
-                const { hit, inputsHash } = this.checkTaskCache(clipId, "generate_avatar_video", cacheInput);
-                if (hit) {
-                    return {
-                        ok: true,
-                        output: {
-                            tool: "generate_avatar_video",
-                            pendingTaskId: hit.taskId,
-                            pendingModelKey: hit.modelKey,
-                        },
-                    };
-                }
-                const out = await this.runTool("generate_avatar_video", {
-                    inputImageUrl: scene.avatarFaceUrl,
-                    ttsText: scene.voiceoverLine,
-                    mode: avatarMode,
-                }, ctx);
-                if (!out.ok)
-                    return wrap("generate_avatar_video", out);
-                await this.mintTaskCache(clipId, {
-                    tool: "generate_avatar_video",
-                    taskId: out.output.taskId,
-                    // Avatar tool hardcodes Kling Avatar internally; poller needs the
-                    // actual model key to route via getAiGenProviderService (no special
-                    // resolver exists). AG-20: was "generate_avatar_video" which would
-                    // throw at factory lookup the moment the avatar path was polled.
-                    modelKey: "kling-avatar",
-                    inputsHash,
-                    createdAt: Date.now(),
-                });
-                return {
-                    ok: true,
-                    output: {
-                        tool: "generate_avatar_video",
-                        pendingTaskId: out.output.taskId,
-                        pendingModelKey: "kling-avatar",
-                    },
-                };
-            }
-        }
-    }
-}
-exports.Executor = Executor;

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

@@ -1,61 +0,0 @@
-import { z } from "zod";
-import { ChatRequest, ChatResponse, LlmCaller, StructuredRequest, StructuredResponse } from "./llmCaller";
-/**
- * Vercel AI Gateway LlmCaller — OpenAI-compatible /v1/chat/completions surface.
- * Single endpoint, multi-provider routing via "{provider}/{modelId}" model id.
- *
- * No SDK dependency: pure fetch keeps the shared package light. Structured
- * output uses JSON-schema response_format (supported by gateway across
- * Anthropic / OpenAI / Google providers — gateway normalises it).
- *
- * Reliability features (added Phase 1 of AGENT_TEST_PLAN):
- *   - F1 transport-level retry: each HTTP call retries 3× with exp backoff
- *     (250 / 1000 / 4000ms) on transient errors (network drops, 408/429/5xx).
- *   - F2 model fallback: when a request supplies `fallbackModel` and the
- *     primary exhausts retries on a transient error, we attempt the fallback
- *     once (also with its own retry budget). Schema-validation failures and
- *     other deterministic errors do NOT trigger fallback.
- */
-export interface GatewayConfig {
-    /** Full base url, e.g. "https://ai-gateway.vercel.sh/v1". */
-    baseUrl: string;
-    /** Bearer token. */
-    apiKey: string;
-    /** Default request timeout in ms. */
-    timeoutMs?: number;
-    /** Optional fetch impl override (tests). */
-    fetchImpl?: typeof fetch;
-    /** Max retry attempts per model on transient errors. Default 3. */
-    maxRetries?: number;
-    /** Base backoff in ms (exponential: base, base*4, base*16). Default 250. */
-    retryBaseMs?: number;
-}
-export declare class GatewayLlmCaller implements LlmCaller {
-    private readonly cfg;
-    private readonly fetchImpl;
-    private readonly timeoutMs;
-    private readonly maxRetries;
-    private readonly retryBaseMs;
-    constructor(cfg: GatewayConfig);
-    chat(req: ChatRequest): Promise<ChatResponse>;
-    structured<T extends z.ZodTypeAny>(req: StructuredRequest<T>): Promise<StructuredResponse<T>>;
-    structuredStream<T extends z.ZodTypeAny>(req: StructuredRequest<T>): {
-        tokens: AsyncIterable<string>;
-        result: Promise<StructuredResponse<T>>;
-    };
-    private createStreamingIterator;
-    private modelId;
-    private encodeMessage;
-    private toDataUri;
-    private usage;
-    /**
-     * POST /chat/completions with transient-error retry (F1).
-     * Throws TransientLlmError after exhausting retries on transient failures —
-     * caller catches it to trigger model fallback (F2). Non-transient errors
-     * (4xx other than 408/425/429, malformed responses) propagate as plain Error.
-     */
-    private postWithRetry;
-    private withRetry;
-    private postOnce;
-}
-//# sourceMappingURL=llmCallerGateway.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"llmCallerGateway.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmCallerGateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2CD,qBAAa,gBAAiB,YAAW,SAAS;IAMpC,OAAO,CAAC,QAAQ,CAAC,GAAG;IALhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAER,GAAG,EAAE,aAAa;IAOzC,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAkC7C,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAgEjC,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB;QACD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC9B,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;KACxC;YAqBc,uBAAuB;IA4ItC,OAAO,CAAC,OAAO;YAID,aAAa;YAqBb,SAAS;IAcvB,OAAO,CAAC,KAAK;IAQb;;;;;OAKG;YACW,aAAa;YAIb,SAAS;YA+BT,QAAQ;CA6BvB"}

package/lib/services/agent/llmCallerGateway.js

@@ -1,368 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayLlmCaller = void 0;
-const zod_1 = require("zod");
-/**
- * Marks a transient error that should trigger HTTP retry (and, when exhausted,
- * model fallback). Non-transient errors (4xx other than 408/429, schema
- * validation, malformed JSON) are NOT wrapped and propagate immediately.
- */
-class TransientLlmError extends Error {
-    constructor(message, cause) {
-        super(message);
-        this.cause = cause;
-        this.name = "TransientLlmError";
-    }
-}
-const TRANSIENT_HTTP_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
-function isTransientNetworkError(err) {
-    if (!err || typeof err !== "object")
-        return false;
-    const e = err;
-    const code = e.code ?? e.cause?.code;
-    if (code && /^(ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|EPIPE|UND_ERR_.*)$/.test(code)) {
-        return true;
-    }
-    // Our own per-request timeout (ctrl.abort() in postOnce / structuredStream)
-    // surfaces as AbortError "This operation was aborted". Treat as transient so
-    // the retry loop (and then the fallback model) gets a chance — otherwise a
-    // single slow Gemini Flash vision call sinks the entire critic stage with
-    // no recovery.
-    if (e.name === "AbortError")
-        return true;
-    const msg = String(e.message ?? "");
-    return /fetch failed|socket hang up|other side closed|network|timeout|operation was aborted/i.test(msg);
-}
-class GatewayLlmCaller {
-    constructor(cfg) {
-        this.cfg = cfg;
-        this.fetchImpl = cfg.fetchImpl ?? fetch;
-        this.timeoutMs = cfg.timeoutMs ?? 60000;
-        this.maxRetries = cfg.maxRetries ?? 3;
-        this.retryBaseMs = cfg.retryBaseMs ?? 250;
-    }
-    async chat(req) {
-        const attempted = [];
-        const run = async (model) => {
-            attempted.push(model);
-            const messages = await Promise.all(req.messages.map((m) => this.encodeMessage(m)));
-            const raw = await this.postWithRetry({
-                model: this.modelId(model),
-                messages,
-                temperature: req.temperature,
-                max_tokens: req.maxTokens,
-                stop: req.stop,
-            });
-            const text = raw.choices?.[0]?.message?.content ?? "";
-            return {
-                text: typeof text === "string" ? text : JSON.stringify(text),
-                usage: this.usage(raw),
-                requestId: raw.id,
-            };
-        };
-        try {
-            const out = await run(req.model);
-            return { ...out, attemptedModels: attempted, usedFallback: false };
-        }
-        catch (err) {
-            if (req.fallbackModel && err instanceof TransientLlmError) {
-                const out = await run(req.fallbackModel);
-                return { ...out, attemptedModels: attempted, usedFallback: true };
-            }
-            throw err;
-        }
-    }
-    async structured(req) {
-        const attempted = [];
-        const jsonSchema = zod_1.z.toJSONSchema(req.schema, { target: "draft-7" });
-        const run = async (model) => {
-            attempted.push(model);
-            const messages = await Promise.all(req.messages.map((m) => this.encodeMessage(m)));
-            const raw = await this.postWithRetry({
-                model: this.modelId(model),
-                messages,
-                temperature: req.temperature,
-                max_tokens: req.maxTokens,
-                response_format: {
-                    type: "json_schema",
-                    json_schema: {
-                        name: req.schemaName,
-                        schema: jsonSchema,
-                        strict: true,
-                    },
-                },
-            });
-            const txt = raw.choices?.[0]?.message?.content ?? "";
-            if (!txt || typeof txt !== "string") {
-                // Empty body from the model is not retryable across providers —
-                // surface immediately; planner-level retry can re-prompt.
-                throw new Error(`GatewayLlmCaller.structured: empty response for schema ${req.schemaName}`);
-            }
-            let parsed;
-            try {
-                parsed = JSON.parse(txt);
-            }
-            catch {
-                throw new Error(`GatewayLlmCaller.structured: model returned non-JSON for schema ${req.schemaName}: ${txt.slice(0, 200)}`);
-            }
-            const result = req.schema.safeParse(parsed);
-            if (!result.success) {
-                throw new Error(`GatewayLlmCaller.structured: schema validation failed for ${req.schemaName}: ${result.error.message}`);
-            }
-            return {
-                data: result.data,
-                usage: this.usage(raw),
-                requestId: raw.id,
-            };
-        };
-        try {
-            const out = await run(req.model);
-            return { ...out, attemptedModels: attempted, usedFallback: false };
-        }
-        catch (err) {
-            if (req.fallbackModel && err instanceof TransientLlmError) {
-                const out = await run(req.fallbackModel);
-                return { ...out, attemptedModels: attempted, usedFallback: true };
-            }
-            throw err;
-        }
-    }
-    structuredStream(req) {
-        // Streaming: fall back is NOT applied mid-stream (would confuse UI
-        // chunks). Transport retry IS applied on the initial connect; once
-        // bytes start flowing, a mid-stream drop propagates as an error and
-        // the caller (planner) handles it via its own retry loop.
-        let resolveResult;
-        let rejectResult;
-        const result = new Promise((resolve, reject) => {
-            resolveResult = resolve;
-            rejectResult = reject;
-        });
-        const self = this;
-        const tokens = {
-            [Symbol.asyncIterator]() {
-                return self.createStreamingIterator(req, resolveResult, rejectResult);
-            },
-        };
-        return { tokens, result };
-    }
-    async *createStreamingIterator(req, resolveResult, rejectResult) {
-        const jsonSchema = zod_1.z.toJSONSchema(req.schema, { target: "draft-7" });
-        const messages = await Promise.all(req.messages.map((m) => this.encodeMessage(m)));
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
-        let accumulated = "";
-        let requestId;
-        let usage;
-        try {
-            // Connect attempt with retry on transient connect failures (pre-stream).
-            const res = await this.withRetry(() => this.fetchImpl(`${this.cfg.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    authorization: `Bearer ${this.cfg.apiKey}`,
-                },
-                body: JSON.stringify({
-                    model: this.modelId(req.model),
-                    messages,
-                    temperature: req.temperature,
-                    max_tokens: req.maxTokens,
-                    stream: true,
-                    response_format: {
-                        type: "json_schema",
-                        json_schema: {
-                            name: req.schemaName,
-                            schema: jsonSchema,
-                            strict: true,
-                        },
-                    },
-                }),
-                signal: ctrl.signal,
-            }).then((r) => {
-                if (!r.ok && TRANSIENT_HTTP_STATUSES.has(r.status)) {
-                    throw new TransientLlmError(`GatewayLlmCaller.structuredStream: ${r.status} ${r.statusText}`);
-                }
-                return r;
-            }));
-            if (!res.ok || !res.body) {
-                const text = await res.text().catch(() => "");
-                const err = new Error(`GatewayLlmCaller.structuredStream: ${res.status} ${res.statusText} — ${text.slice(0, 500)}`);
-                rejectResult(err);
-                throw err;
-            }
-            const reader = res.body.getReader();
-            const decoder = new TextDecoder();
-            let buf = "";
-            while (true) {
-                const { value, done } = await reader.read();
-                if (done)
-                    break;
-                buf += decoder.decode(value, { stream: true });
-                let nl;
-                while ((nl = buf.indexOf("\n")) !== -1) {
-                    const line = buf.slice(0, nl).trim();
-                    buf = buf.slice(nl + 1);
-                    if (!line || !line.startsWith("data:"))
-                        continue;
-                    const payload = line.slice(5).trim();
-                    if (payload === "[DONE]")
-                        break;
-                    try {
-                        const obj = JSON.parse(payload);
-                        if (obj.id)
-                            requestId = obj.id;
-                        if (obj.usage) {
-                            usage = {
-                                promptTokens: obj.usage.prompt_tokens,
-                                completionTokens: obj.usage.completion_tokens,
-                            };
-                        }
-                        const delta = obj.choices?.[0]?.delta?.content ?? "";
-                        if (delta) {
-                            accumulated += delta;
-                            yield delta;
-                        }
-                    }
-                    catch {
-                        // skip malformed line
-                    }
-                }
-            }
-            // Post-stream failures (bad JSON / schema mismatch) reject the RESULT
-            // promise but must NOT throw out of this generator. The tokens already
-            // streamed fine; throwing here would propagate into the caller's
-            // `for await (...stream.tokens)` loop and abort it before the caller can
-            // reach `await stream.result` — which is exactly where the planner's
-            // non-streaming retry fallback lives (Planner.planStream). Returning
-            // cleanly lets the token loop complete, then the rejected result drives
-            // the retry. See plan.controller.ts:planProjectStream.
-            let parsed;
-            try {
-                parsed = JSON.parse(accumulated);
-            }
-            catch {
-                const err = new Error(`GatewayLlmCaller.structuredStream: model returned non-JSON for ${req.schemaName}: ${accumulated.slice(0, 200)}`);
-                rejectResult(err);
-                return;
-            }
-            const validated = req.schema.safeParse(parsed);
-            if (!validated.success) {
-                const err = new Error(`GatewayLlmCaller.structuredStream: schema validation failed for ${req.schemaName}: ${validated.error.message}`);
-                rejectResult(err);
-                return;
-            }
-            resolveResult({
-                data: validated.data,
-                usage,
-                requestId,
-                attemptedModels: [req.model],
-                usedFallback: false,
-            });
-        }
-        catch (e) {
-            rejectResult(e);
-            throw e;
-        }
-        finally {
-            clearTimeout(t);
-        }
-    }
-    modelId(m) {
-        return `${m.provider}/${m.modelId}`;
-    }
-    async encodeMessage(m) {
-        if (!m.imageUrls?.length) {
-            return { role: m.role, content: m.content };
-        }
-        // Fetch + base64-encode each URL into a data URI. The gateway's Anthropic
-        // translator rejects raw https URLs ("URL sources are not supported"); data
-        // URIs round-trip through every provider's OpenAI-compat shim correctly.
-        const dataUris = await Promise.all(m.imageUrls.map((u) => this.toDataUri(u)));
-        return {
-            role: m.role,
-            content: [
-                { type: "text", text: m.content },
-                ...dataUris.map((url) => ({ type: "image_url", image_url: { url } })),
-            ],
-        };
-    }
-    async toDataUri(url) {
-        if (url.startsWith("data:"))
-            return url;
-        const res = await this.fetchImpl(url);
-        if (!res.ok) {
-            throw new Error(`GatewayLlmCaller.toDataUri: ${res.status} ${res.statusText} fetching ${url}`);
-        }
-        const contentType = res.headers.get("content-type")?.split(";")[0]?.trim() || "image/jpeg";
-        const buf = Buffer.from(await res.arrayBuffer());
-        return `data:${contentType};base64,${buf.toString("base64")}`;
-    }
-    usage(raw) {
-        if (!raw.usage)
-            return undefined;
-        return {
-            promptTokens: raw.usage.prompt_tokens,
-            completionTokens: raw.usage.completion_tokens,
-        };
-    }
-    /**
-     * POST /chat/completions with transient-error retry (F1).
-     * Throws TransientLlmError after exhausting retries on transient failures —
-     * caller catches it to trigger model fallback (F2). Non-transient errors
-     * (4xx other than 408/425/429, malformed responses) propagate as plain Error.
-     */
-    async postWithRetry(body) {
-        return this.withRetry(() => this.postOnce(body));
-    }
-    async withRetry(fn) {
-        let lastErr;
-        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
-            try {
-                return await fn();
-            }
-            catch (err) {
-                lastErr = err;
-                const transient = err instanceof TransientLlmError || isTransientNetworkError(err);
-                if (!transient || attempt === this.maxRetries - 1) {
-                    if (transient) {
-                        // Wrap so the fallback-model path can catch it explicitly.
-                        throw err instanceof TransientLlmError
-                            ? err
-                            : new TransientLlmError(`transient LLM error after ${attempt + 1} attempts: ${String(err?.message ?? err)}`, err);
-                    }
-                    throw err;
-                }
-                await new Promise((r) => setTimeout(r, this.retryBaseMs * Math.pow(4, attempt)));
-            }
-        }
-        throw lastErr;
-    }
-    async postOnce(body) {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
-        try {
-            const res = await this.fetchImpl(`${this.cfg.baseUrl.replace(/\/$/, "")}/chat/completions`, {
-                method: "POST",
-                headers: {
-                    "content-type": "application/json",
-                    authorization: `Bearer ${this.cfg.apiKey}`,
-                },
-                body: JSON.stringify(body),
-                signal: ctrl.signal,
-            });
-            if (!res.ok) {
-                const text = await res.text().catch(() => "");
-                const msg = `GatewayLlmCaller: ${res.status} ${res.statusText} — ${text.slice(0, 500)}`;
-                if (TRANSIENT_HTTP_STATUSES.has(res.status)) {
-                    throw new TransientLlmError(msg);
-                }
-                throw new Error(msg);
-            }
-            return (await res.json());
-        }
-        finally {
-            clearTimeout(t);
-        }
-    }
-}
-exports.GatewayLlmCaller = GatewayLlmCaller;