vidspotai-shared 1.0.68 → 1.0.69-dev.0

package/lib/services/agent/providerFallback/classifier.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyProviderError = classifyProviderError;
+exports.shouldFallback = shouldFallback;
+const errors_1 = require("../../../utils/errors");
+/** Match raw provider error messages to a class. Lowercase, regex-free where possible. */
+function classifyByMessage(msg) {
+    const m = msg.toLowerCase();
+    // Auth / config
+    if (/\b(401|403)\b|unauthori[sz]ed|forbidden|invalid api key|missing api key/.test(m)) {
+        return "auth";
+    }
+    // Safety / content policy
+    if (/content[ _-]?policy|safety|moderation|nsfw|violates? .* polic|prohibited|inappropriate|blocked by safety/.test(m)) {
+        return "safety";
+    }
+    // Quota (account-level) — explicit "quota exceeded" / "billing"
+    if (/quota exceeded|billing|insufficient (credits|balance)|account .* limit/.test(m)) {
+        return "quota";
+    }
+    // Rate limit (short window)
+    if (/\b429\b|rate ?limit|too many requests|throttl/.test(m)) {
+        return "rate_limit";
+    }
+    // Capability mismatch. AG-23: also catch Runway-style "Invalid value for
+    // aspectRatio" / "Validation failed: Invalid value for duration" — these mean
+    // the provider can't do this aspect/duration, not that the user's prompt is
+    // bad. Treating them as `capability` lets the chain walk to a model that can.
+    if (/unsupported|not supported|invalid aspect|invalid duration|invalid resolution|cannot generate audio|model does not support|invalid value for (aspect ?ratio|duration|resolution|ratio)|validation failed.*(aspect ?ratio|duration|resolution|ratio)/.test(m)) {
+        return "capability";
+    }
+    // Input
+    if (/prompt (too long|invalid)|invalid prompt|image rejected|invalid image|invalid input|invalid parameter|bad request|\b400\b/.test(m)) {
+        return "input";
+    }
+    // Transient / network / 5xx
+    if (/\b(408|425|500|502|503|504)\b|timeout|timed out|socket|econnreset|econnrefused|etimedout|eai_again|fetch failed|network|temporarily unavailable|high demand|service unavailable/.test(m)) {
+        return "transient";
+    }
+    return "unknown";
+}
+/** Map a known UserFacingError code to our classification. */
+function classifyByCode(code) {
+    switch (code) {
+        case errors_1.USER_FACING_ERROR_CODES.VIDEO_PROVIDER_RATE_LIMITED:
+            return "rate_limit";
+        case errors_1.USER_FACING_ERROR_CODES.VIDEO_PROVIDER_HIGH_DEMAND:
+        case errors_1.USER_FACING_ERROR_CODES.VIDEO_PROVIDER_TIMEOUT:
+        case errors_1.USER_FACING_ERROR_CODES.TTS_PROVIDER_TIMEOUT:
+        case errors_1.USER_FACING_ERROR_CODES.TTS_PROVIDER_UNAVAILABLE:
+        case errors_1.USER_FACING_ERROR_CODES.PROVIDER_UNAVAILABLE:
+            return "transient";
+        case errors_1.USER_FACING_ERROR_CODES.PROMPT_TOO_LONG:
+        case errors_1.USER_FACING_ERROR_CODES.PROMPT_INVALID:
+        case errors_1.USER_FACING_ERROR_CODES.INPUT_IMAGE_REJECTED:
+            return "input";
+        case errors_1.USER_FACING_ERROR_CODES.CONTENT_POLICY_VIOLATION:
+            return "safety";
+        case errors_1.USER_FACING_ERROR_CODES.PROVIDER_AUTH_ERROR:
+            return "auth";
+        case errors_1.USER_FACING_ERROR_CODES.ACCOUNT_QUOTA_EXCEEDED:
+            return "quota";
+        case errors_1.USER_FACING_ERROR_CODES.CAPABILITY_MISMATCH:
+            return "capability";
+        default:
+            return undefined;
+    }
+}
+const TERMINAL_CLASSES = new Set([
+    "auth",
+    "safety",
+    "input",
+]);
+const REPLAN_CLASSES = new Set([
+    "safety",
+    "input",
+]);
+function classifyProviderError(err) {
+    const rawMsg = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+    const message = rawMsg.slice(0, 500);
+    let classification = "unknown";
+    let originalCode;
+    if (err instanceof errors_1.UserFacingError && err.code) {
+        originalCode = err.code;
+        classification = classifyByCode(err.code) ?? classifyByMessage(rawMsg);
+    }
+    else {
+        classification = classifyByMessage(rawMsg);
+    }
+    return {
+        classification,
+        isTerminal: TERMINAL_CLASSES.has(classification),
+        needsReplan: REPLAN_CLASSES.has(classification),
+        originalCode,
+        message,
+    };
+}
+/** Decide whether to try the next provider in a chain for a given class. */
+function shouldFallback(c) {
+    // transient / rate_limit / capability / quota / unknown → try next provider
+    // auth / safety / input → terminal, no fallback
+    return !TERMINAL_CLASSES.has(c);
+}

package/lib/services/agent/providerFallback/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./classifier";
+export * from "./withFallback";
+export * from "./chains";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/agent/providerFallback/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/providerFallback/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC"}

package/lib/services/agent/providerFallback/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./classifier"), exports);
+__exportStar(require("./withFallback"), exports);
+__exportStar(require("./chains"), exports);

package/lib/services/agent/providerFallback/withFallback.d.ts

@@ -0,0 +1,60 @@
+import { ProviderFailureClass, ProviderFailureClassification } from "./classifier";
+/**
+ * Thrown by tool handlers after `withProviderFallback` returns ok:false.
+ * The tool-registry layer translates this into a rich `ToolError` so the
+ * executor can decide whether to escalate to the agent for re-plan.
+ */
+export declare class ProviderFallbackExhaustedError extends Error {
+    readonly classification: ProviderFailureClass;
+    readonly needsReplan: boolean;
+    readonly attemptedProviders: string[];
+    readonly isProviderFallbackExhaustedError = true;
+    constructor(classification: ProviderFailureClass, needsReplan: boolean, attemptedProviders: string[], message: string);
+}
+/**
+ * Generic provider-fallback wrapper. Given an ordered chain of providers and
+ * a `call(provider)` function, walks the chain on recoverable failures and
+ * returns a structured outcome. The agent / executor uses the outcome to
+ * decide whether to re-plan, degrade, or fail the scene.
+ *
+ * Each provider's OWN internal transient retries (already implemented in
+ * Google/Kling/MiniMax services) run before we move to the next provider.
+ * That is intentional — short network blips are handled at the provider
+ * layer; this wrapper only swaps providers on harder failures.
+ */
+export interface ProviderAttempt<P> {
+    provider: P;
+    startedAt: number;
+    durationMs: number;
+    classification?: ProviderFailureClassification;
+    error?: string;
+}
+export type FallbackOutcome<P, T> = {
+    ok: true;
+    value: T;
+    provider: P;
+    attempts: ProviderAttempt<P>[];
+    usedFallback: boolean;
+} | {
+    ok: false;
+    classification: ProviderFailureClassification;
+    attempts: ProviderAttempt<P>[];
+    /** True when the agent should re-plan the scene (safety / input class). */
+    needsReplan: boolean;
+};
+export interface WithFallbackOptions<P, T> {
+    /** Ordered provider chain — primary first, fallbacks after. */
+    providers: readonly P[];
+    /** Function that runs the actual call against one provider. */
+    call: (provider: P) => Promise<T>;
+    /**
+     * Optional pre-flight filter: skip providers in the chain that cannot
+     * fulfil this request (e.g. wrong aspect ratio). Returning false skips
+     * the provider without an attempt entry.
+     */
+    capable?: (provider: P) => boolean;
+    /** Trace hook — fires once per attempt (success or failure). */
+    onAttempt?: (attempt: ProviderAttempt<P>) => void;
+}
+export declare function withProviderFallback<P, T>(opts: WithFallbackOptions<P, T>): Promise<FallbackOutcome<P, T>>;
+//# sourceMappingURL=withFallback.d.ts.map

package/lib/services/agent/providerFallback/withFallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withFallback.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/providerFallback/withFallback.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,oBAAoB,EACpB,6BAA6B,EAE9B,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;IAGrD,QAAQ,CAAC,cAAc,EAAE,oBAAoB;IAC7C,QAAQ,CAAC,WAAW,EAAE,OAAO;IAC7B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE;IAJvC,QAAQ,CAAC,gCAAgC,QAAQ;gBAEtC,cAAc,EAAE,oBAAoB,EACpC,WAAW,EAAE,OAAO,EACpB,kBAAkB,EAAE,MAAM,EAAE,EACrC,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,6BAA6B,CAAC;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,IAC5B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,CAAC,CAAC;IACT,QAAQ,EAAE,CAAC,CAAC;IACZ,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/B,YAAY,EAAE,OAAO,CAAC;CACvB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,cAAc,EAAE,6BAA6B,CAAC;IAC9C,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEN,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC;IACvC,+DAA+D;IAC/D,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;IACxB,+DAA+D;IAC/D,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,OAAO,CAAC;IACnC,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACnD;AAED,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EAC7C,IAAI,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAyEhC"}

package/lib/services/agent/providerFallback/withFallback.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderFallbackExhaustedError = void 0;
+exports.withProviderFallback = withProviderFallback;
+const logger_1 = require("../../../utils/logger");
+const classifier_1 = require("./classifier");
+/**
+ * Thrown by tool handlers after `withProviderFallback` returns ok:false.
+ * The tool-registry layer translates this into a rich `ToolError` so the
+ * executor can decide whether to escalate to the agent for re-plan.
+ */
+class ProviderFallbackExhaustedError extends Error {
+    constructor(classification, needsReplan, attemptedProviders, message) {
+        super(message);
+        this.classification = classification;
+        this.needsReplan = needsReplan;
+        this.attemptedProviders = attemptedProviders;
+        this.isProviderFallbackExhaustedError = true;
+        this.name = "ProviderFallbackExhaustedError";
+    }
+}
+exports.ProviderFallbackExhaustedError = ProviderFallbackExhaustedError;
+async function withProviderFallback(opts) {
+    const attempts = [];
+    let lastClassification;
+    for (let i = 0; i < opts.providers.length; i++) {
+        const provider = opts.providers[i];
+        if (opts.capable && !opts.capable(provider)) {
+            // AG-42: previously skipped silently — when the planner-picked primary
+            // (index 0) gets filtered out, callers couldn't tell why a different
+            // provider ended up running. Log enough for grep + trace.
+            logger_1.logger.warn("providerFallback: filtered out by capability gate", {
+                provider: String(provider),
+                position: i,
+                isPrimary: i === 0,
+            });
+            continue;
+        }
+        const startedAt = Date.now();
+        try {
+            const value = await opts.call(provider);
+            const attempt = {
+                provider,
+                startedAt,
+                durationMs: Date.now() - startedAt,
+            };
+            attempts.push(attempt);
+            opts.onAttempt?.(attempt);
+            return { ok: true, value, provider, attempts, usedFallback: i > 0 };
+        }
+        catch (err) {
+            const classification = (0, classifier_1.classifyProviderError)(err);
+            lastClassification = classification;
+            const attempt = {
+                provider,
+                startedAt,
+                durationMs: Date.now() - startedAt,
+                classification,
+                error: classification.message,
+            };
+            attempts.push(attempt);
+            opts.onAttempt?.(attempt);
+            // Terminal class (auth / safety / input) — stop the chain immediately.
+            if (!(0, classifier_1.shouldFallback)(classification.classification)) {
+                return {
+                    ok: false,
+                    classification,
+                    attempts,
+                    needsReplan: classification.needsReplan,
+                };
+            }
+            // Otherwise loop to next provider in chain.
+        }
+    }
+    // Chain exhausted.
+    logger_1.logger.error("providerFallback: chain exhausted", {
+        providers: opts.providers.map((p) => String(p)),
+        classification: lastClassification?.classification,
+        attempts: attempts.length,
+        lastErr: lastClassification?.message ?? null,
+    });
+    return {
+        ok: false,
+        classification: lastClassification ?? {
+            classification: "unknown",
+            isTerminal: false,
+            needsReplan: false,
+            message: "No providers in chain were attempted (all filtered).",
+        },
+        attempts,
+        needsReplan: lastClassification?.needsReplan ?? false,
+    };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Stage 7 slice 1 — provider task-id cache.
+ *
+ * Background: every debug rerun of an agent project re-submits the same AI
+ * gen tasks (animate_image, generate_video, generate_avatar_video) for the
+ * same scene inputs, burning $0.50-$3 per scene with no new signal. The
+ * providers retain task results for 14-30 days, so when the upstream inputs
+ * are unchanged we can replay the prior taskId through the poller and skip
+ * the gen call entirely.
+ *
+ * The cache lives on AgentProject.providerTaskCache (Firestore map) keyed by
+ * canonical clip id (e.g. "scene-3-visual"). The executor checks it before
+ * the three task-id-producing tool calls; on hit it short-circuits with the
+ * cached taskId + modelKey. On miss it runs the tool, then mints a fresh
+ * entry via the onTaskMint callback.
+ */
+export declare const TASK_CACHE_TTL_MS: number;
+export interface ProviderTaskCacheEntry {
+    /** Tool that minted this task — animate_image | generate_video | generate_avatar_video. */
+    tool: string;
+    /** Provider task id; poller resolves this to the final MP4. */
+    taskId: string;
+    /** Model the task was minted on; poller needs this to route via getAiGenProviderService. */
+    modelKey: string;
+    /** Optional friendly provider name for logs/trace. */
+    providerName?: string;
+    /** Deterministic hash of the upstream inputs the executor would send. */
+    inputsHash: string;
+    /** Mint timestamp (ms epoch). Compared against TASK_CACHE_TTL_MS. */
+    createdAt: number;
+}
+export type ProviderTaskCache = Record<string, ProviderTaskCacheEntry>;
+/**
+ * Deterministic hash of executor tool inputs. Used as the cache key tiebreaker:
+ * a cache entry is only reused when its hash matches the would-be input hash.
+ * Returns first 16 hex chars of sha256 — collision space ~2^64, plenty for
+ * a per-project clip-id-scoped cache.
+ */
+export declare function hashTaskInputs(input: Record<string, unknown>): string;
+/**
+ * Return the cached entry for clipId iff it exists, its inputsHash matches,
+ * and it has not exceeded the TTL. Returns null on miss, mismatch, or expiry.
+ */
+export declare function getCachedTask(cache: ProviderTaskCache | undefined, clipId: string, inputsHash: string, now?: number): ProviderTaskCacheEntry | null;
+/**
+ * Drop entries older than TTL. Used by callers that snapshot the cache before
+ * passing it to the executor so we don't carry stale hashes around in memory.
+ */
+export declare function pruneExpiredCache(cache: ProviderTaskCache | undefined, now?: number): ProviderTaskCache;
+//# sourceMappingURL=providerTaskCache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"providerTaskCache.d.ts","sourceRoot":"","sources":["../../../src/services/agent/providerTaskCache.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,MAAM,WAAW,sBAAsB;IACrC,2FAA2F;IAC3F,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;AAmCvE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAGrE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,iBAAiB,GAAG,SAAS,EACpC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,MAAmB,GACvB,sBAAsB,GAAG,IAAI,CAO/B;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,GAAG,SAAS,EACpC,GAAG,GAAE,MAAmB,GACvB,iBAAiB,CASnB"}

package/lib/services/agent/providerTaskCache.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_CACHE_TTL_MS = void 0;
+exports.hashTaskInputs = hashTaskInputs;
+exports.getCachedTask = getCachedTask;
+exports.pruneExpiredCache = pruneExpiredCache;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Stage 7 slice 1 — provider task-id cache.
+ *
+ * Background: every debug rerun of an agent project re-submits the same AI
+ * gen tasks (animate_image, generate_video, generate_avatar_video) for the
+ * same scene inputs, burning $0.50-$3 per scene with no new signal. The
+ * providers retain task results for 14-30 days, so when the upstream inputs
+ * are unchanged we can replay the prior taskId through the poller and skip
+ * the gen call entirely.
+ *
+ * The cache lives on AgentProject.providerTaskCache (Firestore map) keyed by
+ * canonical clip id (e.g. "scene-3-visual"). The executor checks it before
+ * the three task-id-producing tool calls; on hit it short-circuits with the
+ * cached taskId + modelKey. On miss it runs the tool, then mints a fresh
+ * entry via the onTaskMint callback.
+ */
+exports.TASK_CACHE_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * Canonicalize a record into a stable string for hashing. Keys sorted at
+ * every depth; arrays preserve order (order matters semantically for things
+ * like inputImageUrls). undefined values dropped; null preserved. NaN/Infinity
+ * collapse to null (matches JSON.stringify behavior).
+ */
+function canonicalize(value) {
+    if (value === undefined)
+        return "null";
+    if (value === null)
+        return "null";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return "null";
+        return JSON.stringify(value);
+    }
+    if (typeof value === "string" || typeof value === "boolean") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonicalize).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+        return ("{" +
+            keys
+                .map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]))
+                .join(",") +
+            "}");
+    }
+    return "null";
+}
+/**
+ * Deterministic hash of executor tool inputs. Used as the cache key tiebreaker:
+ * a cache entry is only reused when its hash matches the would-be input hash.
+ * Returns first 16 hex chars of sha256 — collision space ~2^64, plenty for
+ * a per-project clip-id-scoped cache.
+ */
+function hashTaskInputs(input) {
+    const canonical = canonicalize(input);
+    return (0, node_crypto_1.createHash)("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+/**
+ * Return the cached entry for clipId iff it exists, its inputsHash matches,
+ * and it has not exceeded the TTL. Returns null on miss, mismatch, or expiry.
+ */
+function getCachedTask(cache, clipId, inputsHash, now = Date.now()) {
+    if (!cache)
+        return null;
+    const entry = cache[clipId];
+    if (!entry)
+        return null;
+    if (entry.inputsHash !== inputsHash)
+        return null;
+    if (now - entry.createdAt > exports.TASK_CACHE_TTL_MS)
+        return null;
+    return entry;
+}
+/**
+ * Drop entries older than TTL. Used by callers that snapshot the cache before
+ * passing it to the executor so we don't carry stale hashes around in memory.
+ */
+function pruneExpiredCache(cache, now = Date.now()) {
+    if (!cache)
+        return {};
+    const out = {};
+    for (const [clipId, entry] of Object.entries(cache)) {
+        if (now - entry.createdAt <= exports.TASK_CACHE_TTL_MS) {
+            out[clipId] = entry;
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,82 @@
+/**
+ * AG-45 — quality gate. Decides whether a generated video (per-scene or
+ * stitched) is ship-worthy, needs a cheap re-mux, needs a surgical re-gen on
+ * specific scenes, or needs a full replan.
+ *
+ * Why this exists: the original critic-driven loop in `repairTrace.ts` treated
+ * any `severity: 'fail'` finding as a regen trigger. That cost Test 1 4×
+ * scene regenerations (~16 credits) over a SINGLE prompt-vs-reference-image
+ * misalignment that didn't actually break the video — the bottle was just a
+ * different shade of green than the brief said. The user's point was sharp:
+ * "if the result was too bad then only regenerate", and the natural rule is
+ * a score band + severity floor:
+ *
+ *   per-scene score
+ *     ≥ 7        ship as-is
+ *     5.0–6.9    ship-with-caveats (no auto-regen)
+ *     3.0–4.9    surgical regen (scenes the critic flagged)
+ *     < 3.0      critical — bypass cost-confirmation if cheap
+ *
+ *   stitched score
+ *     ≥ 7 + shippable   deliver
+ *     5.0–6.9 no FAIL   text/music re-mux only ($0)
+ *     < 5.0 or FAIL     surgical regen on flagged scenes
+ *     < 3.0             replan (very rare; last resort)
+ *
+ *   guardrails (orthogonal to score):
+ *     - WARN severity is informational; only FAIL counts toward actions
+ *     - actionPlausibility FAIL is always actionable, regardless of score —
+ *       sealed-cap-while-drinking type errors break user trust at any score
+ *     - max 2 regen attempts per scene per run (`scene.regenCount`)
+ *     - cumulative cost budget: stop retrying when retry $ > 1.5× original $
+ *
+ * Every decision is returned as a structured object so the caller (repairTrace,
+ * videoJobProcessor, or any future UI) can log it to trace under
+ * `qualityGate: GateDecision[]` and let us tune the thresholds from data.
+ */
+import type { PerSceneReview } from "./perSceneCritic";
+import type { StitchedVideoReview } from "./stitchedVideoCritic";
+export interface BudgetState {
+    /** Sum of credits already spent on this run (initial + retries). */
+    totalCreditsSpent: number;
+    /** Credits estimated for the original generation. Used as the budget anchor. */
+    originalCreditsBudget: number;
+    /** Per-scene regen attempts so far (sceneIndex -> count). */
+    regenCountByScene: Record<number, number>;
+    /** Hard cap on retries per scene. Default 2 in factory below. */
+    maxRegenPerScene: number;
+    /** Multiplier on originalCreditsBudget that caps retry cost. Default 1.5. */
+    retryBudgetMultiplier: number;
+}
+export declare function makeBudgetState(initial: Partial<BudgetState> & {
+    originalCreditsBudget: number;
+}): BudgetState;
+export type GateAction = "ship" | "ship-with-caveats" | "remix" | "regen-scenes" | "replan";
+export interface GateDecision {
+    action: GateAction;
+    /** Score at the gate (0–10), preserved for telemetry / dashboards. */
+    score: number;
+    /** Human-readable why; surfaced in trace + (eventually) UI. */
+    reason: string;
+    /** When action = regen-scenes / remix: the affected scene indices. */
+    sceneIndices?: number[];
+    /** When action = regen-scenes: estimated retry cost in credits. */
+    estimatedRegenCredits?: number;
+    /** Notable findings that drove the decision; for telemetry / debugging. */
+    drivingFindings?: Array<{
+        sceneIndex?: number;
+        dimension: string;
+        severity: "warn" | "fail";
+        message: string;
+    }>;
+    /** Caveats to surface to the user when action = ship-with-caveats. */
+    caveats?: string[];
+}
+export declare function decidePerSceneAction(review: PerSceneReview, budget: BudgetState, opts?: {
+    perSceneRegenCostCredits?: number;
+}): GateDecision;
+export declare function decideStitchedAction(stitched: StitchedVideoReview, perScene: PerSceneReview[], budget: BudgetState, opts?: {
+    perSceneRegenCostCredits?: number;
+    userIntentScope?: number[];
+}): GateDecision;
+//# sourceMappingURL=qualityGate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"qualityGate.d.ts","sourceRoot":"","sources":["../../../src/services/agent/qualityGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;IAAE,qBAAqB,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAQ9G;AAED,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,mBAAmB,GACnB,OAAO,GACP,cAAc,GACd,QAAQ,CAAC;AAEb,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,KAAK,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAyBD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,wBAAwB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,YAAY,CAiEd;AAMD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,cAAc,EAAE,EAC1B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3E,YAAY,CA8Fd"}