vidspotai-shared 1.0.85 → 1.0.86

package/lib/services/agent/repair/strategies/llmRepair.strategy.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.llmWideRepairStrategy = exports.llmNarrowRepairStrategy = void 0;
+const zod_1 = require("zod");
+const aiModels_1 = require("../../../../globals/aiModels");
+const logger_1 = require("../../../../utils/logger");
+const llmCallerRegistry_1 = require("../../llmCallerRegistry");
+const modelRouter_1 = require("../../modelRouter");
+const toolRegistry_1 = require("../../toolRegistry");
+/**
+ * Tiers 1 & 2 — the AGENTIC repair brain.
+ *
+ * When the deterministic micro-fix can't help (moderation block, an
+ * unrecognised provider rejection, a request that no single param snap can
+ * satisfy), an LLM looks at the failure the way a human operator would: it
+ * decides WHETHER the issue is fixable and HOW, then returns a reworked tool
+ * input. Two scopes, registered as two strategies so the engine escalates
+ * least-invasive-first:
+ *
+ *   - "narrow" (rank 10): fix ONLY the offending thing — minimally rewrite a
+ *     moderation-flagged prompt, correct a bad param — WITHOUT changing the
+ *     model or the overall approach. Declines if that can't be done without
+ *     significant quality loss.
+ *   - "wide"   (rank 20): may swap to another capable model, adjust the prompt
+ *     more substantially, or restructure params — whatever best preserves the
+ *     user's intent. The last resort before a hard fail.
+ *
+ * Reuses the host-wired `getLlmCaller()` singleton (same as every other agent
+ * tool). When no caller is configured (offline / unit tests), every call here
+ * throws and the strategy gracefully DECLINES — deterministic repair still works.
+ */
+const RepairDecisionSchema = zod_1.z.object({
+    fixable: zod_1.z
+        .boolean()
+        .describe("True only if you can produce a reworked input that should succeed."),
+    repairedInput: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.unknown())
+        .nullable()
+        .describe("The complete reworked tool input to retry with (all fields, not a diff). Null when not fixable."),
+    qualityImpact: zod_1.z
+        .enum(["none", "minor", "significant"])
+        .describe("How much your fix changes the result vs the user's original intent."),
+    rationale: zod_1.z
+        .string()
+        .describe("One sentence: what you changed and why it should now pass."),
+});
+function summarizeModel(modelKey) {
+    const cfg = aiModels_1.aiModelConfigs[modelKey];
+    if (!cfg)
+        return null;
+    const allowed = (field) => {
+        const v = cfg.fields?.[field]?.allowedValues;
+        return Array.isArray(v) ? v : undefined;
+    };
+    return {
+        modelKey,
+        type: cfg.type,
+        aspectRatio: allowed("aspectRatio")?.filter((x) => typeof x === "string"),
+        duration: allowed("duration")?.filter((x) => typeof x === "number"),
+        resolution: allowed("resolution")?.filter((x) => typeof x === "string"),
+    };
+}
+/** Other models that share at least one generation `type` with the current one —
+ *  the candidate set for a wide-scope model swap. Capped to keep the prompt tight. */
+function alternativeModels(currentModelKey, limit = 14) {
+    const current = summarizeModel(currentModelKey);
+    const currentTypes = new Set(current?.type ?? []);
+    const out = [];
+    for (const key of Object.keys(aiModels_1.aiModelConfigs)) {
+        if (key === currentModelKey)
+            continue;
+        const summary = summarizeModel(key);
+        if (!summary?.type)
+            continue;
+        if (currentTypes.size && !summary.type.some((t) => currentTypes.has(t)))
+            continue;
+        out.push(summary);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+function systemPrompt(scope) {
+    const common = "You are the repair operator for an AI video-generation agent. A tool call just " +
+        "failed at a provider. Decide whether the failure is fixable by reworking the tool " +
+        "input, and if so, return the COMPLETE reworked input. Preserve the user's creative " +
+        "intent as much as possible. Never invent URLs or ids — keep any imageUrl/inputImageUrl/" +
+        "videoUrl fields exactly as given unless the error is about them.";
+    if (scope === "narrow") {
+        return (common +
+            " SCOPE: NARROW. Fix ONLY the specific thing the provider rejected. Do NOT change " +
+            "`modelKey`. Do NOT change the overall approach. For a content-moderation/safety block, " +
+            "minimally reword the prompt to remove the flagged element while keeping the scene's " +
+            "meaning. If the issue cannot be fixed this narrowly, or the only narrow fix would " +
+            "SIGNIFICANTLY degrade quality, set fixable=false (a wider repair will be tried).");
+    }
+    return (common +
+        " SCOPE: WIDE. The narrow fix already failed or wasn't possible. You MAY change `modelKey` " +
+        "to a different model that supports the request, adjust the prompt more substantially, or " +
+        "restructure parameters. Prefer switching to a model whose constraints natively fit the " +
+        "request over distorting the request. Pick the option that best preserves the user's intent.");
+}
+function userPrompt(rc, scope) {
+    const modelKey = typeof rc.input.modelKey === "string" ? rc.input.modelKey : undefined;
+    const current = modelKey ? summarizeModel(modelKey) : null;
+    const lines = [];
+    lines.push(`TOOL: ${rc.toolName}`);
+    lines.push(`FAILED INPUT:\n${JSON.stringify(rc.input, null, 2)}`);
+    lines.push(`FAILURE: classification=${rc.failure.classification ?? "unknown"} code=${rc.failure.code}\n${rc.failure.message}`);
+    if (rc.failure.attemptedProviders?.length) {
+        lines.push(`PROVIDERS ALREADY TRIED (all failed): ${rc.failure.attemptedProviders.join(", ")}`);
+    }
+    if (current) {
+        lines.push(`CURRENT MODEL CONSTRAINTS:\n${JSON.stringify(current, null, 2)}`);
+    }
+    if (rc.history.length) {
+        const prior = rc.history
+            .map((h, i) => `  ${i + 1}. ${JSON.stringify(h.input)} → ${h.failure.message}`)
+            .join("\n");
+        lines.push(`REPAIRS ALREADY TRIED THIS RUN (do not repeat):\n${prior}`);
+    }
+    if (scope === "wide" && modelKey) {
+        const alts = alternativeModels(modelKey);
+        if (alts.length) {
+            lines.push(`ALTERNATIVE MODELS YOU MAY SWITCH TO (modelKey + constraints):\n${JSON.stringify(alts, null, 2)}`);
+        }
+    }
+    return lines.join("\n\n");
+}
+function makeLlmRepairStrategy(scope, rank) {
+    return {
+        name: `llm-repair-${scope}`,
+        rank,
+        applies(rc) {
+            // The LLM can reason about any non-auth failure. Auth is a deploy bug,
+            // already short-circuited by the engine, but guard here too.
+            return rc.failure.classification !== "auth";
+        },
+        async propose(rc) {
+            const caller = (0, llmCallerRegistry_1.getLlmCaller)();
+            const model = new modelRouter_1.ModelRouter(modelRouter_1.DEFAULT_MODEL_ROUTING).pickFor("planner");
+            const messages = [
+                { role: "system", content: systemPrompt(scope) },
+                { role: "user", content: userPrompt(rc, scope) },
+            ];
+            let decision;
+            try {
+                const res = await caller.structured({
+                    model,
+                    messages,
+                    schema: RepairDecisionSchema,
+                    schemaName: "RepairDecision",
+                    temperature: 0.2,
+                    maxTokens: 1500,
+                });
+                decision = res.data;
+            }
+            catch (err) {
+                // Unconfigured caller (tests/offline) or LLM/transport error → decline.
+                logger_1.logger.warn(`repair: ${scope} LLM strategy unavailable — declining`, {
+                    toolName: rc.toolName,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+                return null;
+            }
+            if (!decision.fixable || !decision.repairedInput)
+                return null;
+            // Narrow scope must not change the model — enforce structurally even if
+            // the model ignored the instruction.
+            if (scope === "narrow" &&
+                typeof rc.input.modelKey === "string" &&
+                decision.repairedInput.modelKey !== undefined &&
+                decision.repairedInput.modelKey !== rc.input.modelKey) {
+                return null;
+            }
+            // A "significant" narrow fix should defer to the wide tier.
+            if (scope === "narrow" && decision.qualityImpact === "significant")
+                return null;
+            // Validate the reworked input against the tool's own schema before we
+            // trust it — a malformed proposal must never reach the provider.
+            const tool = (0, toolRegistry_1.getTool)(rc.toolName);
+            if (tool) {
+                const parsed = tool.inputSchema.safeParse(decision.repairedInput);
+                if (!parsed.success) {
+                    logger_1.logger.warn(`repair: ${scope} LLM proposal failed tool schema — declining`, {
+                        toolName: rc.toolName,
+                        issues: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+                    });
+                    return null;
+                }
+                return {
+                    strategy: this.name,
+                    repairedInput: parsed.data,
+                    rationale: decision.rationale,
+                    qualityImpact: decision.qualityImpact,
+                };
+            }
+            return {
+                strategy: this.name,
+                repairedInput: decision.repairedInput,
+                rationale: decision.rationale,
+                qualityImpact: decision.qualityImpact,
+            };
+        },
+    };
+}
+/** Tier 1 — narrow agentic fix (offending field only, no model change). */
+exports.llmNarrowRepairStrategy = makeLlmRepairStrategy("narrow", 10);
+/** Tier 2 — wide agentic fix (may swap model / restructure). */
+exports.llmWideRepairStrategy = makeLlmRepairStrategy("wide", 20);

package/lib/services/agent/repair/strategies/paramRepair.strategy.d.ts

@@ -0,0 +1,3 @@
+import { RepairStrategy } from "../types";
+export declare const paramRepairStrategy: RepairStrategy;
+//# sourceMappingURL=paramRepair.strategy.d.ts.map

package/lib/services/agent/repair/strategies/paramRepair.strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paramRepair.strategy.d.ts","sourceRoot":"","sources":["../../../../../src/services/agent/repair/strategies/paramRepair.strategy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiC,cAAc,EAAE,MAAM,UAAU,CAAC;AA0FzE,eAAO,MAAM,mBAAmB,EAAE,cA+DjC,CAAC"}

package/lib/services/agent/repair/strategies/paramRepair.strategy.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paramRepairStrategy = void 0;
+const aiModels_1 = require("../../../../globals/aiModels");
+const chains_1 = require("../../providerFallback/chains");
+/**
+ * Tier 0 — deterministic, narrow, config-driven micro-fix.
+ *
+ * "The agent should read the model config and substitute a valid value." This
+ * strategy does exactly that, deterministically and for free: when a provider
+ * rejected a single constrained parameter (aspect ratio / duration / resolution
+ * mismatch), it reads `aiModelConfigs[modelKey]` and snaps ONLY the offending
+ * field to the nearest value that model actually supports.
+ *
+ * It is deliberately conservative — it fixes a field only when the substitution
+ * is lossless or a minor adjustment (an aspect of the SAME orientation, a small
+ * duration snap). If the only legal value would meaningfully change the result
+ * (flip portrait↔landscape, snap 5s→20s), it DECLINES so the engine escalates
+ * to an agentic strategy that can make a smarter call (e.g. pick a different
+ * model that natively supports the request rather than distorting it).
+ */
+/** Only capability/input class errors are param-shaped. */
+function isParamClass(rc) {
+    const c = rc.failure.classification;
+    return c === "capability" || c === "input";
+}
+/** Which constrained field the provider complained about, if the message says so. */
+function offendingField(message) {
+    const m = message.toLowerCase();
+    if (/aspect ?ratio/.test(m))
+        return "aspectRatio";
+    if (/duration/.test(m))
+        return "duration";
+    if (/resolution/.test(m))
+        return "resolution";
+    return null;
+}
+function aspectRatioValue(canonical) {
+    const match = canonical.match(/^(\d+)[:x](\d+)$/);
+    if (!match)
+        return null;
+    const w = parseInt(match[1], 10);
+    const h = parseInt(match[2], 10);
+    if (!w || !h)
+        return null;
+    return w / h;
+}
+function aspectClass(ratio) {
+    if (Math.abs(ratio - 1) < 0.02)
+        return "square";
+    return ratio > 1 ? "landscape" : "portrait";
+}
+/**
+ * Nearest supported canonical aspect of the SAME orientation as `requested`.
+ * Returns the picked value + quality impact, or null when there's no
+ * same-orientation candidate (→ decline, an orientation flip is not "minor").
+ */
+function nearestSupportedAspect(requested, allowedCanonical) {
+    const reqRatio = aspectRatioValue(requested);
+    if (reqRatio == null)
+        return null;
+    const normReq = (0, chains_1.normalizeAspect)(requested);
+    // Exact (normalized) match already supported → nothing to fix here.
+    if (allowedCanonical.some((a) => (0, chains_1.normalizeAspect)(a) === normReq)) {
+        return { value: requested, impact: "none" };
+    }
+    const reqClass = aspectClass(reqRatio);
+    let best = null;
+    for (const candidate of allowedCanonical) {
+        const candRatio = aspectRatioValue(candidate);
+        if (candRatio == null)
+            continue;
+        if (aspectClass(candRatio) !== reqClass)
+            continue; // orientation-preserving only
+        const dist = Math.abs(Math.log(reqRatio) - Math.log(candRatio));
+        if (!best || dist < best.dist)
+            best = { value: candidate, dist };
+    }
+    if (!best)
+        return null; // no same-orientation option → not a minor fix
+    return { value: best.value, impact: "minor" };
+}
+function allowedAspectRatios(modelKey) {
+    const cfg = aiModels_1.aiModelConfigs[modelKey];
+    const allowed = cfg?.fields?.aspectRatio?.allowedValues;
+    if (!Array.isArray(allowed) || !allowed.length)
+        return null;
+    return allowed.filter((v) => typeof v === "string");
+}
+exports.paramRepairStrategy = {
+    name: "param-repair",
+    rank: 0,
+    applies(rc) {
+        if (!isParamClass(rc))
+            return false;
+        return typeof rc.input.modelKey === "string";
+    },
+    async propose(rc) {
+        const modelKey = rc.input.modelKey;
+        const field = offendingField(rc.failure.message);
+        const changes = [];
+        let impact = "none";
+        const repaired = { ...rc.input };
+        // ── Aspect ratio ──────────────────────────────────────────────────────
+        // Repair when the message points at aspect, OR when no field was named and
+        // an aspectRatio is present (some providers throw an opaque capability error).
+        const aspectCandidate = (field === "aspectRatio" || (field === null && typeof rc.input.aspectRatio === "string"))
+            ? rc.input.aspectRatio
+            : undefined;
+        if (aspectCandidate) {
+            const allowed = allowedAspectRatios(modelKey);
+            if (allowed) {
+                const snap = nearestSupportedAspect(aspectCandidate, allowed);
+                if (!snap)
+                    return null; // orientation flip needed → escalate (decline)
+                if (snap.value !== aspectCandidate) {
+                    repaired.aspectRatio = snap.value;
+                    changes.push(`aspectRatio ${aspectCandidate}→${snap.value}`);
+                    if (snap.impact === "minor")
+                        impact = "minor";
+                }
+            }
+        }
+        // ── Duration ──────────────────────────────────────────────────────────
+        const durationCandidate = (field === "duration" || (field === null && typeof rc.input.durationSec === "number"))
+            ? rc.input.durationSec
+            : undefined;
+        if (typeof durationCandidate === "number") {
+            const snap = (0, chains_1.snapDurationForModel)(modelKey, durationCandidate);
+            // null = drift too large to call "minor"; unconstrained = nothing to fix.
+            if (snap === null) {
+                // Duration is the offender and can't be snapped cheaply → decline.
+                if (field === "duration")
+                    return null;
+            }
+            else if (!snap.unconstrained && snap.snappedSec !== durationCandidate) {
+                repaired.durationSec = snap.snappedSec;
+                changes.push(`durationSec ${durationCandidate}→${snap.snappedSec}`);
+                impact = "minor";
+            }
+        }
+        if (!changes.length)
+            return null; // nothing this strategy can safely fix
+        return {
+            strategy: this.name,
+            repairedInput: repaired,
+            rationale: `Snapped to ${modelKey}'s supported values: ${changes.join(", ")}`,
+            qualityImpact: impact,
+        };
+    },
+};

package/lib/services/agent/repair/types.d.ts

@@ -0,0 +1,92 @@
+import { ToolContext, ToolOutcome } from "../toolRegistry";
+/**
+ * Self-healing repair subsystem — REACTIVE, GENERIC, ESCALATING.
+ *
+ * Contract (per the design constraints):
+ *   1. REACTIVE — a repair is only ever proposed AFTER a tool call has actually
+ *      failed. Nothing here touches the happy path; we never pre-flight-mutate
+ *      a request that would have succeeded.
+ *   2. GENERIC — the engine knows nothing about aspect ratios, moderation, or
+ *      any specific failure. It walks an ordered list of `RepairStrategy`s and
+ *      retries with the first proposal. New failure classes are handled by
+ *      adding a strategy, never by editing the loop.
+ *   3. ESCALATING (least-invasive first) — strategies carry an invasiveness
+ *      `rank`; the engine consults them in ascending order. The narrowest fix
+ *      that targets ONLY the rejected thing is tried first; a strategy DECLINES
+ *      (returns null) when it can't fix the issue without widening scope or
+ *      degrading quality, which escalates to the next, wider strategy.
+ *
+ * The agentic strategies (LLM-backed) live alongside the deterministic ones and
+ * are just higher-ranked entries — the engine treats them identically.
+ */
+export type FailureClass = "transient" | "rate_limit" | "capability" | "safety" | "auth" | "quota" | "input" | "unknown";
+/** The structured error a failed `runTool` returned (subset of ToolError.error). */
+export interface RepairFailure {
+    code: string;
+    message: string;
+    classification?: FailureClass;
+    attemptedProviders?: string[];
+}
+/** One prior failed (strategy, input, failure) triple — fed back so a strategy
+ *  (and the LLM) can see what's already been tried and not repeat it. */
+export interface RepairAttemptRecord {
+    /** Strategy that produced the input that then failed; "original" for attempt 0. */
+    strategy: string;
+    input: Record<string, unknown>;
+    failure: RepairFailure;
+}
+export interface RepairContext {
+    /** Tool whose call failed (e.g. "generate_video"). */
+    toolName: string;
+    /** The exact input that just failed. */
+    input: Record<string, unknown>;
+    /** The failure that input produced. */
+    failure: RepairFailure;
+    /** 1-based index of the repair attempt about to be proposed. */
+    attempt: number;
+    /** Prior failed attempts this run, oldest first (attempt 0 = the original call). */
+    history: RepairAttemptRecord[];
+    /** Tool context — agentRunId / projectId / trace logger. */
+    ctx: ToolContext;
+}
+export interface RepairProposal {
+    /** Strategy that produced this proposal (trace). */
+    strategy: string;
+    /** The repaired tool input to retry with. Must satisfy the tool's input schema. */
+    repairedInput: Record<string, unknown>;
+    /** One-line reason, for trace + post-mortem. */
+    rationale: string;
+    /**
+     * The strategy's own estimate of how much this repair degrades the result vs.
+     * the user's original intent. The engine prefers lower-impact proposals (they
+     * come from lower-ranked strategies first); a strategy that can only fix the
+     * issue at "significant" cost should usually DECLINE and let a wider strategy
+     * find a better path (e.g. swap to a model that natively supports the request
+     * rather than distorting the request to fit the current model).
+     */
+    qualityImpact: "none" | "minor" | "significant";
+}
+export interface RepairStrategy {
+    /** Stable identifier, surfaced in trace. */
+    name: string;
+    /**
+     * Invasiveness rank — the engine sorts ascending and consults in that order,
+     * so the narrowest fix is always tried first. Convention:
+     *   0–9   micro-fix: mutate ONLY the rejected field, deterministically.
+     *   10–19 narrow agentic: LLM edits only the offending field(s), no model/strategy change.
+     *   20+   wide agentic: LLM may swap model, change strategy, restructure.
+     */
+    rank: number;
+    /** Cheap synchronous relevance gate — skip strategies that can't apply. */
+    applies(rc: RepairContext): boolean;
+    /** Propose a repair, or null to DECLINE (engine escalates to the next strategy). */
+    propose(rc: RepairContext): Promise<RepairProposal | null>;
+}
+/** The function the engine wraps — same signature as toolRegistry.runTool.
+ *  (Named distinctly from executor's RunToolFn to keep the barrel unambiguous.) */
+export type RepairableRunToolFn = <O = unknown>(name: string, input: unknown, ctx: ToolContext) => Promise<ToolOutcome<O>>;
+export interface RunWithRepairOptions {
+    /** Max repair RETRIES after the first failure (each may run a fresh tool call). Default 3. */
+    maxRepairs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/services/agent/repair/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/repair/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,OAAO,GACP,OAAO,GACP,SAAS,CAAC;AAEd,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,YAAY,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED;yEACyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,uCAAuC;IACvC,OAAO,EAAE,aAAa,CAAC;IACvB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,4DAA4D;IAC5D,GAAG,EAAE,WAAW,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;CACjD;AAED,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC;IACpC,oFAAoF;IACpF,OAAO,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED;mFACmF;AACnF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,GAAG,OAAO,EAC5C,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,WAAW,KACb,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7B,MAAM,WAAW,oBAAoB;IACnC,8FAA8F;IAC9F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/lib/services/agent/repair/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,96 @@
+import { VideoBrief } from "../../schemas/brief.schema";
+import { AgentVisualBible, VideoPlan } from "../../schemas/videoPlan.schema";
+import { AgentPersona } from "../../schemas/agentPersona.schema";
+import { IAgentProjectModel, IBrandKitModel, IStyleMemoryModel, PlanStage } from "../../models/agent.model";
+import { getLlmCaller } from "./llmCallerRegistry";
+/**
+ * Stable cache key for the Visual Bible. Bible content is a pure function of
+ * (brief, brandKit) — same inputs ⇒ same bible. We key on the brief object
+ * plus `brandKit.updatedAt` (cheap version proxy) so any brand-kit edit
+ * invalidates without re-hashing the kit body. C0 (no bible) returns "" so
+ * we never cache nothing as something.
+ */
+export declare function computeBibleCacheKey(brief: VideoBrief, brandKit: IBrandKitModel | null): string;
+/**
+ * Returns the bible to thread into the planner, using the project-level cache
+ * when the key matches. On miss runs the full BibleBuilder + image-vision
+ * pipeline (both soft-fail per their wrappers). Returns the bible and a
+ * `fresh` flag so the caller can decide to persist on cache miss only.
+ */
+export declare function getBibleWithCache(args: {
+    project: IAgentProjectModel;
+    brief: VideoBrief;
+    persona: AgentPersona | undefined;
+    brandKit: IBrandKitModel | null;
+    llm: ReturnType<typeof getLlmCaller>;
+    onStage?: (stage: PlanStage) => void;
+}): Promise<{
+    bible: AgentVisualBible | undefined;
+    fresh: boolean;
+    key: string;
+}>;
+/** Per-stage wall-clock for one planning run (ms). */
+export interface PlanStageTimings {
+    bibleMs: number;
+    plannerMs: number;
+    musicMs: number;
+    beatSnapMs: number;
+    totalMs: number;
+}
+/**
+ * Latency telemetry — emits ONE structured record per planning run, two ways:
+ *  1) `logger.info("agent.planTimings", …)` → Console + Grafana Loki (the
+ *     existing winston pipeline; no parallel reporter).
+ *  2) a durable doc in the `agentPlanTimings` Firestore collection → queryable
+ *     for aggregate analysis (p50/p95 per stage, web-research/cache incidence)
+ *     via scripts/analyze-plan-timings.mjs — no per-run guesswork.
+ *
+ * Fire-and-forget: never on the critical path, and a write failure is swallowed
+ * (warn only) so telemetry can't break planning.
+ */
+export declare function recordPlanTimings(args: {
+    projectId: string;
+    userId: string;
+    brief: VideoBrief;
+    plan: {
+        meta?: Record<string, unknown>;
+        scenes?: unknown[];
+    };
+    timings: PlanStageTimings;
+    bibleCacheHit: boolean;
+    streaming: boolean;
+    dryRun: boolean;
+}): void;
+/** Result of a planning run — caller persists these. */
+export interface RunPlanningResult {
+    /** Final musicked + beat-snapped plan. */
+    plan: VideoPlan;
+    /** The bible threaded into the planner (or undefined for C0 / soft-fail). */
+    bible: AgentVisualBible | undefined;
+    /** True when the bible was freshly built this run (cache miss). Persist `bibleCache` only when true. */
+    bibleFresh: boolean;
+    /** Cache key for the bible — persist alongside the bible when `bibleFresh`. */
+    bibleKey: string;
+}
+/**
+ * Run the full planning pipeline: bible (cache-or-build) → planner →
+ * music-select → beat-snap, stamping `plan.meta.bibleBuilt` and emitting
+ * latency telemetry. Pure compute — does NOT write the plan to Firestore;
+ * the caller decides where it lands (`.plan` for a live plan, `previewPlan`
+ * for a dry-run).
+ */
+export declare function runPlanning(args: {
+    /** Project doc (needs `id`, `bibleCache`). */
+    project: IAgentProjectModel;
+    brief: VideoBrief;
+    persona?: AgentPersona;
+    brandKit: IBrandKitModel | null;
+    styleMemory: IStyleMemoryModel | null;
+    /** `true`/`false`/`"auto"` (default) — forwarded to Planner.plan. */
+    useWebResearch?: boolean | "auto";
+    /** Dry-run flag — telemetry only (caller decides where the plan lands). */
+    dryRun?: boolean;
+    /** Mirrors each sub-step so the worker can write `planRun.stage`. */
+    onStage?: (stage: PlanStage) => void;
+}): Promise<RunPlanningResult>;
+//# sourceMappingURL=runPlanning.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runPlanning.d.ts","sourceRoot":"","sources":["../../../src/services/agent/runPlanning.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAoB,MAAM,4BAA4B,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAwBnD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,GAAG,IAAI,GAC9B,MAAM,CAUR;AAiED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,GAAG,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBhF;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC7D,OAAO,EAAE,gBAAgB,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,IAAI,CAkCP;AAED,wDAAwD;AACxD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;IAChB,6EAA6E;IAC7E,KAAK,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpC,wGAAwG;IACxG,UAAU,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,8CAA8C;IAC9C,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACtC,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CACtC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuD7B"}