vidspotai-shared 1.0.85 → 1.0.87

package/lib/services/agent/planner/plannerMessages.js

@@ -119,6 +119,13 @@ function buildPlannerMessages(brief, persona, brandKit, styleMemory, bible, last
         bibleSection,
         brandKitSection,
         styleMemorySection,
+        "",
+        "Title — set plan.title to a concise, human-friendly name for the whole",
+        "video (≤ 8 words, Title Case, no trailing punctuation, no surrounding",
+        "quotes). It should read like a video/episode title a creator would use,",
+        "derived from the brief's subject and angle — NOT a restatement of the raw",
+        "prompt. Examples: \"5 Morning Habits That Boost Focus\", \"Meet the New",
+        "Aurora Smartwatch\", \"Why Your Plants Keep Dying\".",
     ]
         .filter(Boolean)
         .join("\n");

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

@@ -50,6 +50,8 @@ export interface VideoCapabilityRequest {
     hasInputImage?: boolean;
 }
 export declare function isVideoModelCapable(model: EVideoGenModels, req: VideoCapabilityRequest): boolean;
+/** Reduce a "W:H" or "WxH" ratio to lowest terms, e.g. "1280:720" → "16:9". */
+export declare function normalizeAspect(a: string): string;
 /**
  * Build a chain that puts the planner's pick first, then the rest of the
  * tier-appropriate chain (deduped). Honors the planner's intent while still

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

@@ -1 +1 @@
-{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/providerFallback/chains.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EACf,eAAe,EACf,aAAa,EAEb,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;;;;;GAYG;AAGH,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAM5D,CAAC;AAKF,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAQ5D,CAAC;AAQF,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAQ7D,CAAC;AAKF,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAM7D,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAExD,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,SAAS,eAAe,EAGjD,CAAC;AAGF,eAAO,MAAM,SAAS,EAAE,SAAS,aAAa,EAE7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAuCT;AAyDD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,eAAe,EAC5B,aAAa,EAAE,SAAS,eAAe,EAAE,GACxC,eAAe,EAAE,CAMnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,eAAe,EAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,mBAAwB,GAC7B,kBAAkB,GAAG,IAAI,CAyB3B"}
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/providerFallback/chains.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EACf,eAAe,EACf,aAAa,EAEb,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;;;;;GAYG;AAGH,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAM5D,CAAC;AAKF,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAQ5D,CAAC;AAQF,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAQ7D,CAAC;AAKF,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAM7D,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAExD,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,SAAS,eAAe,EAGjD,CAAC;AAGF,eAAO,MAAM,SAAS,EAAE,SAAS,aAAa,EAE7C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAuCT;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CASjD;AA6CD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,eAAe,EAC5B,aAAa,EAAE,SAAS,eAAe,EAAE,GACxC,eAAe,EAAE,CAMnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GAAG,eAAe,EAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,mBAAwB,GAC7B,kBAAkB,GAAG,IAAI,CAyB3B"}

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SFX_CHAIN = exports.MUSIC_CHAIN = exports.AVATAR_VIDEO_CHAIN = exports.T3_IMAGE_TO_VIDEO_CHAIN = exports.T2_IMAGE_TO_VIDEO_CHAIN = exports.T2_TEXT_TO_VIDEO_CHAIN = exports.T3_TEXT_TO_VIDEO_CHAIN = void 0;
 exports.isVideoModelCapable = isVideoModelCapable;
+exports.normalizeAspect = normalizeAspect;
 exports.buildVideoChain = buildVideoChain;
 exports.snapDurationForModel = snapDurationForModel;
 const aiModels_1 = require("../../../globals/aiModels");

package/lib/services/agent/recovery/degradeLadder.d.ts

@@ -0,0 +1,74 @@
+import { SceneAssetStrategy, VideoPlan } from "../../../schemas/videoPlan.schema";
+import { FailureClass } from "../repair/types";
+export declare function isStockStrategy(strategy: SceneAssetStrategy): boolean;
+/**
+ * The ordered list of fallback strategies to try for a scene that failed, most
+ * intent-preserving first. Empty when nothing sensible exists (already stock /
+ * avatar).
+ *
+ * Failure-class aware: a `safety` (content-moderation) block came from the
+ * GENERATIVE step, so any remaining AI rung would just be blocked again — skip
+ * straight to the non-generative stock rungs (stock search has no prompt to
+ * moderate). All other classes step down the full ladder.
+ */
+export declare function degradeLadderFor(strategy: SceneAssetStrategy, failureClass: FailureClass | undefined): SceneAssetStrategy[];
+/**
+ * Produce a copy of `plan` with exactly one scene's strategy changed. Pure — no
+ * mutation of the input. The rest of the scene (prompt, duration, bible refs) is
+ * preserved so the degraded render still reflects the planned content.
+ */
+export declare function planWithDegradedScene(plan: VideoPlan, sceneIndex: number, newStrategy: SceneAssetStrategy): VideoPlan;
+/**
+ * Phase 2b — a proposed scene-recovery, computed WITHOUT executing it. The
+ * autonomous path (`recoverFailedScenes`) walks the ladder and re-runs each
+ * rung; in `manual` autonomy we instead surface this proposal on the approval
+ * card and pause. `toStrategy` is the most intent-preserving rung; `ladder`
+ * is the full remaining fallback chain (shown as "what happens if this also
+ * fails").
+ */
+export interface RecoveryProposal {
+    sceneIndex: number;
+    fromStrategy: SceneAssetStrategy;
+    toStrategy: SceneAssetStrategy;
+    ladder: SceneAssetStrategy[];
+    failureClass: FailureClass | undefined;
+    reason: string;
+}
+/**
+ * Minimal structural view of a failed scene outcome. Kept structural (rather
+ * than importing `SceneOutcome` from the executor) so this pure module stays
+ * free of the executor import graph — `SceneOutcome` is assignable to it.
+ */
+export interface FailedSceneLike {
+    scene: {
+        sceneIndex: number;
+        strategy: SceneAssetStrategy;
+    };
+    error?: {
+        classification?: FailureClass;
+    };
+}
+/**
+ * PURE — compute the recovery proposal for each failed scene without running
+ * anything. One proposal per scene that HAS a (failure-class-aware) degrade
+ * path; scenes whose ladder is empty (already stock / avatar / terminal) are
+ * omitted — there is nothing to approve, so the run just hard-fails them.
+ *
+ * This is the data the worker persists onto `run.pendingApproval` when it
+ * pauses for sign-off, and the basis the approve path mutates the plan with.
+ */
+export declare function planSceneRecovery(failed: FailedSceneLike[]): RecoveryProposal[];
+/**
+ * PURE — apply a set of approved recovery proposals to a plan, returning a new
+ * plan with each proposal's scene degraded to its `toStrategy`. Used on the
+ * approval-resume pass: the resumed executor then regenerates exactly those
+ * scenes with the new strategy while every already-succeeded scene replays
+ * from the providerTaskCache. No mutation of the input.
+ */
+export declare function applyRecoveryProposals(plan: VideoPlan, proposals: Array<{
+    sceneIndex: number;
+    toStrategy: string;
+}>): VideoPlan;
+/** Human-readable one-liner for trace + the approval card. */
+export declare function describeDegrade(sceneIndex: number, from: SceneAssetStrategy, to: SceneAssetStrategy, failureClass: FailureClass | undefined): string;
+//# sourceMappingURL=degradeLadder.d.ts.map

package/lib/services/agent/recovery/degradeLadder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradeLadder.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/recovery/degradeLadder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA4C/C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,EAC5B,YAAY,EAAE,YAAY,GAAG,SAAS,GACrC,kBAAkB,EAAE,CAItB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,kBAAkB,GAC9B,SAAS,CAOX;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,kBAAkB,CAAC;IACjC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAC5D,KAAK,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,gBAAgB,EAAE,CAkB/E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3D,SAAS,CASX;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,kBAAkB,EACxB,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,YAAY,GAAG,SAAS,GACrC,MAAM,CAUR"}

package/lib/services/agent/recovery/degradeLadder.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStockStrategy = isStockStrategy;
+exports.degradeLadderFor = degradeLadderFor;
+exports.planWithDegradedScene = planWithDegradedScene;
+exports.planSceneRecovery = planSceneRecovery;
+exports.applyRecoveryProposals = applyRecoveryProposals;
+exports.describeDegrade = describeDegrade;
+/**
+ * PLAN-LEVEL recovery — scene-strategy degrade.
+ *
+ * The tool-level repair engine reworks a single tool's INPUT (param/prompt/model)
+ * and re-runs the SAME tool. When that's exhausted — every video model failed,
+ * the prompt is unfixably blocked, the provider can't do it at all — the only
+ * remaining move is to change the scene's STRATEGY: render it a cheaper way that
+ * still fills the slot (AI video → stock footage → ken-burns still) rather than
+ * letting one scene fail the whole video.
+ *
+ * This is intentionally a PLAN mutation, not a tool-input repair, so it lives at
+ * the orchestrator layer (the worker), not inside the per-tool repair loop. A
+ * strategy change always materially alters the scene, so it is classified as a
+ * `significant` decision — exactly the kind the human-in-the-loop approval gate
+ * (Phase 2b) pauses on when autonomy is set to manual.
+ */
+/** Ordered fallbacks for each strategy, most-intent-preserving first. */
+const DEGRADE_LADDER = {
+    // Pure text-to-video has no source still to fall back on → go to motion stock,
+    // then a static stock image with ken-burns motion.
+    "ai-text-to-video": ["stock-video", "stock-image-ken-burns"],
+    // Image-to-video: first drop the (failed) animation but keep the AI still,
+    // then fall back to stock footage, then a stock still.
+    "ai-image-to-video": ["ai-image-static", "stock-video", "stock-image-ken-burns"],
+    "ai-image-motion": ["ai-image-static", "stock-image-ken-burns", "stock-video"],
+    "ai-image-static": ["stock-image-ken-burns", "stock-video"],
+    "stock-video": ["stock-image-ken-burns"],
+    // Already the cheapest visual — nothing left to degrade to.
+    "stock-image-ken-burns": [],
+    // The executor already self-falls-back user-asset → stock; mirror it here.
+    "user-asset": ["stock-video", "stock-image-ken-burns"],
+    // Avatar needs a face + VO; there is no sensible automatic substitute.
+    "talking-head-avatar": [],
+};
+const STOCK_STRATEGIES = new Set([
+    "stock-video",
+    "stock-image-ken-burns",
+    "user-asset",
+]);
+function isStockStrategy(strategy) {
+    return STOCK_STRATEGIES.has(strategy);
+}
+/**
+ * The ordered list of fallback strategies to try for a scene that failed, most
+ * intent-preserving first. Empty when nothing sensible exists (already stock /
+ * avatar).
+ *
+ * Failure-class aware: a `safety` (content-moderation) block came from the
+ * GENERATIVE step, so any remaining AI rung would just be blocked again — skip
+ * straight to the non-generative stock rungs (stock search has no prompt to
+ * moderate). All other classes step down the full ladder.
+ */
+function degradeLadderFor(strategy, failureClass) {
+    const base = DEGRADE_LADDER[strategy] ?? [];
+    if (failureClass === "safety")
+        return base.filter(isStockStrategy);
+    return base;
+}
+/**
+ * Produce a copy of `plan` with exactly one scene's strategy changed. Pure — no
+ * mutation of the input. The rest of the scene (prompt, duration, bible refs) is
+ * preserved so the degraded render still reflects the planned content.
+ */
+function planWithDegradedScene(plan, sceneIndex, newStrategy) {
+    return {
+        ...plan,
+        scenes: plan.scenes.map((s) => s.sceneIndex === sceneIndex ? { ...s, strategy: newStrategy } : s),
+    };
+}
+/**
+ * PURE — compute the recovery proposal for each failed scene without running
+ * anything. One proposal per scene that HAS a (failure-class-aware) degrade
+ * path; scenes whose ladder is empty (already stock / avatar / terminal) are
+ * omitted — there is nothing to approve, so the run just hard-fails them.
+ *
+ * This is the data the worker persists onto `run.pendingApproval` when it
+ * pauses for sign-off, and the basis the approve path mutates the plan with.
+ */
+function planSceneRecovery(failed) {
+    const proposals = [];
+    for (const outcome of failed) {
+        const fromStrategy = outcome.scene.strategy;
+        const failureClass = outcome.error?.classification;
+        const ladder = degradeLadderFor(fromStrategy, failureClass);
+        if (!ladder.length)
+            continue; // terminal — nothing to propose
+        const toStrategy = ladder[0];
+        proposals.push({
+            sceneIndex: outcome.scene.sceneIndex,
+            fromStrategy,
+            toStrategy,
+            ladder,
+            failureClass,
+            reason: describeDegrade(outcome.scene.sceneIndex, fromStrategy, toStrategy, failureClass),
+        });
+    }
+    return proposals;
+}
+/**
+ * PURE — apply a set of approved recovery proposals to a plan, returning a new
+ * plan with each proposal's scene degraded to its `toStrategy`. Used on the
+ * approval-resume pass: the resumed executor then regenerates exactly those
+ * scenes with the new strategy while every already-succeeded scene replays
+ * from the providerTaskCache. No mutation of the input.
+ */
+function applyRecoveryProposals(plan, proposals) {
+    if (!proposals.length)
+        return plan;
+    const target = new Map(proposals.map((p) => [p.sceneIndex, p.toStrategy]));
+    return {
+        ...plan,
+        scenes: plan.scenes.map((s) => target.has(s.sceneIndex) ? { ...s, strategy: target.get(s.sceneIndex) } : s),
+    };
+}
+/** Human-readable one-liner for trace + the approval card. */
+function describeDegrade(sceneIndex, from, to, failureClass) {
+    const why = failureClass === "safety"
+        ? "content was blocked by the provider's moderation"
+        : failureClass === "capability"
+            ? "no available model could generate it"
+            : failureClass === "quota"
+                ? "provider quota was exhausted"
+                : "generation failed after retries";
+    return `Scene ${sceneIndex}: ${why} — fall back from "${from}" to "${to}".`;
+}

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

@@ -0,0 +1,38 @@
+import { ToolContext, ToolOutcome } from "../toolRegistry";
+import { RepairContext, RepairProposal, RepairStrategy, RepairableRunToolFn, RunWithRepairOptions } from "./types";
+/**
+ * RepairEngine — the generic, reactive, escalating retry brain.
+ *
+ * It owns an ordered set of strategies and a single loop, `runWithRepair`,
+ * that the executor uses in place of a raw `runTool`. The loop:
+ *
+ *   run tool → ok? return it.
+ *   else → ask strategies (narrowest first) for a repaired input → retry.
+ *   repeat until ok, no strategy can help, or the retry budget is spent.
+ *
+ * Everything specific (which field to snap, whether moderation is fixable,
+ * whether to swap models) lives in the strategies. The engine only sequences
+ * them, guards against repeating an input, and records history.
+ */
+export declare class RepairEngine {
+    private readonly strategies;
+    constructor(strategies: RepairStrategy[]);
+    /** Strategies, narrowest-first (read-only view, for trace/introspection). */
+    get strategyNames(): string[];
+    /**
+     * Walk strategies in ascending rank; the first that `applies` and returns a
+     * non-null proposal wins. A strategy that throws is logged and skipped (a
+     * broken strategy must never sink the whole repair — the next one still runs).
+     */
+    diagnose(rc: RepairContext): Promise<RepairProposal | null>;
+    /**
+     * Reactive bounded retry loop. Runs the tool; on failure, escalates through
+     * the strategies and retries with the repaired input. Returns the first OK
+     * outcome, or the LAST failure once the budget is spent / nothing can help.
+     *
+     * Terminal `auth` failures short-circuit immediately — a missing/invalid key
+     * is a deploy bug, not something a different input can fix.
+     */
+    runWithRepair<O = unknown>(runTool: RepairableRunToolFn, toolName: string, input: Record<string, unknown>, ctx: ToolContext, opts?: RunWithRepairOptions): Promise<ToolOutcome<O>>;
+}
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/repair/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,EAEL,aAAa,EAEb,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;gBAElC,UAAU,EAAE,cAAc,EAAE;IAKxC,6EAA6E;IAC7E,IAAI,aAAa,IAAI,MAAM,EAAE,CAE5B;IAED;;;;OAIG;IACG,QAAQ,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA2BjE;;;;;;;OAOG;IACG,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7B,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CAyF3B"}

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

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepairEngine = void 0;
+const logger_1 = require("../../../utils/logger");
+const providerTaskCache_1 = require("../providerTaskCache");
+/**
+ * RepairEngine — the generic, reactive, escalating retry brain.
+ *
+ * It owns an ordered set of strategies and a single loop, `runWithRepair`,
+ * that the executor uses in place of a raw `runTool`. The loop:
+ *
+ *   run tool → ok? return it.
+ *   else → ask strategies (narrowest first) for a repaired input → retry.
+ *   repeat until ok, no strategy can help, or the retry budget is spent.
+ *
+ * Everything specific (which field to snap, whether moderation is fixable,
+ * whether to swap models) lives in the strategies. The engine only sequences
+ * them, guards against repeating an input, and records history.
+ */
+class RepairEngine {
+    constructor(strategies) {
+        // Ascending invasiveness — narrowest fix consulted first.
+        this.strategies = [...strategies].sort((a, b) => a.rank - b.rank);
+    }
+    /** Strategies, narrowest-first (read-only view, for trace/introspection). */
+    get strategyNames() {
+        return this.strategies.map((s) => s.name);
+    }
+    /**
+     * Walk strategies in ascending rank; the first that `applies` and returns a
+     * non-null proposal wins. A strategy that throws is logged and skipped (a
+     * broken strategy must never sink the whole repair — the next one still runs).
+     */
+    async diagnose(rc) {
+        for (const strategy of this.strategies) {
+            let relevant = false;
+            try {
+                relevant = strategy.applies(rc);
+            }
+            catch (err) {
+                logger_1.logger.warn("repair: strategy.applies threw — skipping", {
+                    strategy: strategy.name,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+                continue;
+            }
+            if (!relevant)
+                continue;
+            try {
+                const proposal = await strategy.propose(rc);
+                if (proposal)
+                    return proposal;
+            }
+            catch (err) {
+                logger_1.logger.warn("repair: strategy.propose threw — escalating to next", {
+                    strategy: strategy.name,
+                    toolName: rc.toolName,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return null;
+    }
+    /**
+     * Reactive bounded retry loop. Runs the tool; on failure, escalates through
+     * the strategies and retries with the repaired input. Returns the first OK
+     * outcome, or the LAST failure once the budget is spent / nothing can help.
+     *
+     * Terminal `auth` failures short-circuit immediately — a missing/invalid key
+     * is a deploy bug, not something a different input can fix.
+     */
+    async runWithRepair(runTool, toolName, input, ctx, opts = {}) {
+        const maxRepairs = opts.maxRepairs ?? 3;
+        const log = ctx.log ?? (() => { });
+        let currentInput = input;
+        let outcome = await runTool(toolName, currentInput, ctx);
+        if (outcome.ok)
+            return outcome;
+        const history = [];
+        // Guard against proposing an input we've already run (incl. the original).
+        const tried = new Set([safeHash(currentInput)]);
+        for (let attempt = 1; attempt <= maxRepairs; attempt++) {
+            const failure = toRepairFailure(outcome);
+            // Unfixable-by-input class — bail without burning the LLM budget.
+            if (failure.classification === "auth") {
+                log("repair_skip", { reason: "auth_class_terminal", toolName });
+                break;
+            }
+            const rc = {
+                toolName,
+                input: currentInput,
+                failure,
+                attempt,
+                history: [...history],
+                ctx,
+            };
+            const proposal = await this.diagnose(rc);
+            if (!proposal) {
+                log("repair_exhausted", {
+                    toolName,
+                    attempt,
+                    classification: failure.classification,
+                    reason: "no_strategy_could_repair",
+                });
+                break;
+            }
+            const proposedHash = safeHash(proposal.repairedInput);
+            if (tried.has(proposedHash)) {
+                // A strategy re-proposed something already attempted — stop rather than
+                // spin. (Distinct from maxRepairs: this catches a 2-cycle early.)
+                log("repair_loop_guard", {
+                    toolName,
+                    attempt,
+                    strategy: proposal.strategy,
+                    reason: "duplicate_input_proposed",
+                });
+                break;
+            }
+            tried.add(proposedHash);
+            history.push({ strategy: "original", input: currentInput, failure });
+            logger_1.logger.info("repair: retrying with repaired input", {
+                toolName,
+                attempt,
+                strategy: proposal.strategy,
+                qualityImpact: proposal.qualityImpact,
+                rationale: proposal.rationale,
+                priorClassification: failure.classification,
+                agentRunId: ctx.agentRunId,
+            });
+            log("repair_attempt", {
+                toolName,
+                attempt,
+                strategy: proposal.strategy,
+                qualityImpact: proposal.qualityImpact,
+                rationale: proposal.rationale,
+            });
+            currentInput = proposal.repairedInput;
+            outcome = await runTool(toolName, currentInput, ctx);
+            if (outcome.ok) {
+                logger_1.logger.info("repair: succeeded", {
+                    toolName,
+                    attempt,
+                    strategy: proposal.strategy,
+                    agentRunId: ctx.agentRunId,
+                });
+                log("repair_success", { toolName, attempt, strategy: proposal.strategy });
+                return outcome;
+            }
+        }
+        return outcome;
+    }
+}
+exports.RepairEngine = RepairEngine;
+function toRepairFailure(outcome) {
+    if (outcome.ok) {
+        // Defensive — callers only pass failures here.
+        return { code: "UNKNOWN", message: "no error" };
+    }
+    return {
+        code: outcome.error.code,
+        message: outcome.error.message,
+        classification: outcome.error.classification,
+        attemptedProviders: outcome.error.attemptedProviders,
+    };
+}
+function safeHash(input) {
+    try {
+        return (0, providerTaskCache_1.hashTaskInputs)(input);
+    }
+    catch {
+        // Non-canonicalizable input (shouldn't happen for tool inputs) — fall back
+        // to a best-effort string so the loop guard still functions.
+        return JSON.stringify(input).slice(0, 64);
+    }
+}

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

@@ -0,0 +1,20 @@
+import { RepairEngine } from "./engine";
+export * from "./types";
+export { RepairEngine } from "./engine";
+export { paramRepairStrategy } from "./strategies/paramRepair.strategy";
+export { llmNarrowRepairStrategy, llmWideRepairStrategy, } from "./strategies/llmRepair.strategy";
+/**
+ * The default escalation ladder, narrowest-first:
+ *   rank 0  param-repair      — deterministic single-field snap (free, instant)
+ *   rank 10 llm-repair-narrow — agentic, fix the offending field only
+ *   rank 20 llm-repair-wide   — agentic, may swap model / restructure
+ *
+ * Engine sorts by rank, so registration order here is cosmetic.
+ */
+export declare function createDefaultRepairEngine(): RepairEngine;
+/**
+ * Process-wide default engine. The Executor uses this when the host doesn't
+ * inject its own, so self-healing is on by default everywhere the executor runs.
+ */
+export declare const defaultRepairEngine: RepairEngine;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/repair/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAOxC,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EACL,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,YAAY,CAMxD;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,YAA0C,CAAC"}

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

@@ -0,0 +1,49 @@
+"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 });
+exports.defaultRepairEngine = exports.llmWideRepairStrategy = exports.llmNarrowRepairStrategy = exports.paramRepairStrategy = exports.RepairEngine = void 0;
+exports.createDefaultRepairEngine = createDefaultRepairEngine;
+const engine_1 = require("./engine");
+const paramRepair_strategy_1 = require("./strategies/paramRepair.strategy");
+const llmRepair_strategy_1 = require("./strategies/llmRepair.strategy");
+__exportStar(require("./types"), exports);
+var engine_2 = require("./engine");
+Object.defineProperty(exports, "RepairEngine", { enumerable: true, get: function () { return engine_2.RepairEngine; } });
+var paramRepair_strategy_2 = require("./strategies/paramRepair.strategy");
+Object.defineProperty(exports, "paramRepairStrategy", { enumerable: true, get: function () { return paramRepair_strategy_2.paramRepairStrategy; } });
+var llmRepair_strategy_2 = require("./strategies/llmRepair.strategy");
+Object.defineProperty(exports, "llmNarrowRepairStrategy", { enumerable: true, get: function () { return llmRepair_strategy_2.llmNarrowRepairStrategy; } });
+Object.defineProperty(exports, "llmWideRepairStrategy", { enumerable: true, get: function () { return llmRepair_strategy_2.llmWideRepairStrategy; } });
+/**
+ * The default escalation ladder, narrowest-first:
+ *   rank 0  param-repair      — deterministic single-field snap (free, instant)
+ *   rank 10 llm-repair-narrow — agentic, fix the offending field only
+ *   rank 20 llm-repair-wide   — agentic, may swap model / restructure
+ *
+ * Engine sorts by rank, so registration order here is cosmetic.
+ */
+function createDefaultRepairEngine() {
+    return new engine_1.RepairEngine([
+        paramRepair_strategy_1.paramRepairStrategy,
+        llmRepair_strategy_1.llmNarrowRepairStrategy,
+        llmRepair_strategy_1.llmWideRepairStrategy,
+    ]);
+}
+/**
+ * Process-wide default engine. The Executor uses this when the host doesn't
+ * inject its own, so self-healing is on by default everywhere the executor runs.
+ */
+exports.defaultRepairEngine = createDefaultRepairEngine();

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

@@ -0,0 +1,6 @@
+import { RepairStrategy } from "../types";
+/** Tier 1 — narrow agentic fix (offending field only, no model change). */
+export declare const llmNarrowRepairStrategy: RepairStrategy;
+/** Tier 2 — wide agentic fix (may swap model / restructure). */
+export declare const llmWideRepairStrategy: RepairStrategy;
+//# sourceMappingURL=llmRepair.strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmRepair.strategy.d.ts","sourceRoot":"","sources":["../../../../../src/services/agent/repair/strategies/llmRepair.strategy.ts"],"names":[],"mappings":"AAOA,OAAO,EAAiC,cAAc,EAAE,MAAM,UAAU,CAAC;AAwOzE,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,gBAAsC,CAAC;AAC3E,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,gBAAoC,CAAC"}