vidspotai-shared 1.0.84 → 1.0.86

package/lib/services/agent/runPlanning.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeBibleCacheKey = computeBibleCacheKey;
+exports.getBibleWithCache = getBibleWithCache;
+exports.recordPlanTimings = recordPlanTimings;
+exports.runPlanning = runPlanning;
+const crypto_1 = require("crypto");
+const logger_1 = require("../../utils/logger");
+const firestore_service_1 = require("../firestore.service");
+const brief_schema_1 = require("../../schemas/brief.schema");
+const llmCallerRegistry_1 = require("./llmCallerRegistry");
+const bibleBuilder_1 = require("./bibleBuilder");
+const bibleImageVision_1 = require("./bibleImageVision");
+const planner_1 = require("./planner");
+const musicSelect_1 = require("./musicSelect");
+const beatSnap_1 = require("./beatSnap");
+/**
+ * plan-B — the single source of truth for "build a plan from a brief".
+ *
+ * Extracted out of the Cloud Function (plan.controller.ts) so BOTH the
+ * AGENT_PLAN_JOBS worker (the async primary path) and the blocking
+ * `planProject` Function call run the IDENTICAL bible→planner→music→snap
+ * pipeline + emit the IDENTICAL latency telemetry. Two callers, one routine,
+ * no drift.
+ *
+ * The caller owns persistence (writing `.plan` / `previewPlan` / `bibleCache`);
+ * this routine is pure compute + telemetry. Progress is surfaced through the
+ * optional `onStage` callback so the worker can mirror each sub-step onto
+ * `agentProjects.planRun.stage`.
+ */
+const isoNow = () => new Date().toISOString();
+/**
+ * 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.
+ */
+function computeBibleCacheKey(brief, brandKit) {
+    if ((brief.consistencyTier ?? "C1") === "C0")
+        return "";
+    return (0, crypto_1.createHash)("sha256")
+        .update(JSON.stringify({
+        brief,
+        bku: brandKit?.updatedAt ?? null,
+    }))
+        .digest("hex");
+}
+/**
+ * AG-12 — soft-fail wrapper around BibleBuilder. A bible LLM failure must not
+ * block planning; the planner degrades to AG-11's per-scene re-state when no
+ * bible is passed. C0 briefs skip the builder entirely.
+ */
+async function safeBuildBible(llm, args) {
+    const tier = args.brief.consistencyTier ?? "C1";
+    if (tier === "C0")
+        return undefined;
+    try {
+        const builder = new bibleBuilder_1.BibleBuilder({ llm });
+        return await builder.build({
+            brief: args.brief,
+            persona: args.persona,
+            brandKit: args.brandKit,
+            consistencyTier: tier === "C2" ? "C2" : "C1",
+        });
+    }
+    catch (err) {
+        logger_1.logger.warn("agent.bibleBuilder failed — degrading to AG-11", {
+            err: err.message,
+        });
+        return undefined;
+    }
+}
+/**
+ * OD-T6 — image-vision pass that rewrites bible.entity.description from the
+ * entity's referenceImageUrl. Runs between bible-build and planner so the
+ * planner composes scene prompts from what the IMAGE shows (color, material,
+ * finish, label text) rather than what the brief text invented. Skips
+ * entities without a referenceImageUrl. Per-entity soft-fail; vision outage
+ * leaves descriptions intact. Cost ~$0.0001/entity.
+ */
+async function safeBibleImageVision(bible) {
+    if (!bible)
+        return bible;
+    const apiKey = process.env.GOOGLE_API_KEY;
+    if (!apiKey) {
+        logger_1.logger.warn("agent.bibleImageVision skipped — no GOOGLE_API_KEY");
+        return bible;
+    }
+    const haveRefs = bible.characters.some((e) => e.referenceImageUrl) ||
+        bible.objects.some((e) => e.referenceImageUrl) ||
+        bible.environments.some((e) => e.referenceImageUrl);
+    if (!haveRefs)
+        return bible;
+    try {
+        return await (0, bibleImageVision_1.runBibleImageVision)(bible, { apiKey });
+    }
+    catch (err) {
+        logger_1.logger.warn("agent.bibleImageVision failed — keeping text descriptions", {
+            err: err.message,
+        });
+        return bible;
+    }
+}
+/**
+ * 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.
+ */
+async function getBibleWithCache(args) {
+    const key = computeBibleCacheKey(args.brief, args.brandKit);
+    const cached = args.project.bibleCache;
+    if (key && cached?.key === key) {
+        args.onStage?.("bible_cached");
+        logger_1.logger.info("agent.bibleCache hit", {
+            projectId: args.project.id,
+            builtAt: cached.builtAt,
+        });
+        return { bible: cached.bible, fresh: false, key };
+    }
+    args.onStage?.("building_bible");
+    const built = await safeBuildBible(args.llm, {
+        brief: args.brief,
+        persona: args.persona,
+        brandKit: args.brandKit,
+    });
+    args.onStage?.("aligning_bible_with_images");
+    const bible = await safeBibleImageVision(built);
+    return { bible, fresh: true, key };
+}
+/**
+ * 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.
+ */
+function recordPlanTimings(args) {
+    const meta = (args.plan.meta ?? {});
+    const record = {
+        projectId: args.projectId,
+        userId: args.userId,
+        createdAt: isoNow(),
+        streaming: args.streaming,
+        dryRun: args.dryRun,
+        // shape signals — what makes a plan slow varies by these
+        durationSec: args.brief.durationSec ?? null,
+        lengthTier: args.brief.lengthTier ?? (0, brief_schema_1.deriveLengthTier)(args.brief.durationSec),
+        tierBudget: args.brief.tierBudget ?? null,
+        consistencyTier: args.brief.consistencyTier ?? null,
+        sceneCount: Array.isArray(args.plan.scenes) ? args.plan.scenes.length : null,
+        // cost-path flags (the prime suspects for short-form latency)
+        bibleCacheHit: args.bibleCacheHit,
+        bibleBuilt: meta.bibleBuilt ?? null,
+        usedWebResearch: meta.usedWebResearch ?? null,
+        usedThinking: meta.usedThinking ?? null,
+        // per-stage wall-clock
+        ...args.timings,
+    };
+    logger_1.logger.info("agent.planTimings", record);
+    // Durable, queryable copy. `.firestore` off any CollectionReference yields
+    // the admin Firestore instance, so we can write a new collection without a
+    // typed accessor in the shared package.
+    void firestore_service_1.FirestoreService.agentProjectsCol.firestore
+        .collection("agentPlanTimings")
+        .add(record)
+        .catch((err) => logger_1.logger.warn("agent.planTimings: firestore write failed", {
+        err: err.message,
+    }));
+}
+/**
+ * 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).
+ */
+async function runPlanning(args) {
+    const llm = (0, llmCallerRegistry_1.getLlmCaller)();
+    const tStart = Date.now();
+    const { bible, fresh: bibleFresh, key: bibleKey } = await getBibleWithCache({
+        project: args.project,
+        brief: args.brief,
+        persona: args.persona,
+        brandKit: args.brandKit,
+        llm,
+        onStage: args.onStage,
+    });
+    const tBible = Date.now();
+    args.onStage?.("planning");
+    const planner = new planner_1.Planner({ llm });
+    const rawPlan = await planner.plan(args.brief, {
+        persona: args.persona,
+        brandKit: args.brandKit,
+        styleMemory: args.styleMemory,
+        bible,
+        useWebResearch: args.useWebResearch ?? "auto",
+    });
+    const tPlanner = Date.now();
+    // Stamp the bible-build flag onto plan.meta so /execute charges the bible
+    // overhead only when this run actually built one (cache hits cost nothing).
+    // Planner already stamped usedWebResearch / usedThinking.
+    rawPlan.meta = { ...(rawPlan.meta ?? {}), bibleBuilt: bibleFresh && !!bible };
+    const planWithMusic = await (0, musicSelect_1.selectMusicForPlan)(rawPlan);
+    const tMusic = Date.now();
+    const plan = (0, beatSnap_1.snapPlanToBeats)(planWithMusic);
+    const tSnap = Date.now();
+    recordPlanTimings({
+        projectId: args.project.id,
+        userId: args.project.userId,
+        brief: args.brief,
+        plan,
+        // The async worker path is non-streaming (progress comes from `onStage`,
+        // not token deltas), so `streaming: false` here. The kept legacy SSE
+        // endpoint still records `streaming: true` itself.
+        streaming: false,
+        dryRun: args.dryRun ?? false,
+        bibleCacheHit: !bibleFresh,
+        timings: {
+            bibleMs: tBible - tStart,
+            plannerMs: tPlanner - tBible,
+            musicMs: tMusic - tPlanner,
+            beatSnapMs: tSnap - tMusic,
+            totalMs: tSnap - tStart,
+        },
+    });
+    return { plan, bible, bibleFresh, bibleKey };
+}

package/lib/services/aiGen/providers/runway/types.d.ts

@@ -10,5 +10,19 @@ export declare const GEN4_ALEPH_RATIOS: string[];
 export declare const TGEN4_ALEPH_DURATIONS: readonly [5];
 export type Gen4AlephDuration = (typeof TGEN4_ALEPH_DURATIONS)[number];
 export declare const GEN4_ALEPH_DURATIONS: number[];
+/**
+ * Canonical aspect ratios the Runway VIDEO models accept from the agent / UI
+ * layer. This is the CONTRACT `validateParams` checks the incoming canonical
+ * `aspectRatio` against — every other provider's config lists canonical ratios
+ * here too. The service then translates canonical → Runway pixel ratio at
+ * request time via `mapAspectToRunwayVideoRatio`. The pixel-ratio constants
+ * above (`GEN4_TURBO_RATIOS` / `GEN4_ALEPH_RATIOS`) describe the NATIVE values
+ * the Runway API accepts and back the `Gen4TurboRatio` / `Gen4AlephRatio` types
+ * used at that boundary — they are intentionally NOT the validation set.
+ *
+ * AG-16: keep this in lockstep with `mapAspectToRunwayVideoRatio`'s switch —
+ * every value listed here must map to a valid pixel ratio for all flavors.
+ */
+export declare const RUNWAY_VIDEO_CANONICAL_RATIOS: string[];
 export {};
 //# sourceMappingURL=types.d.ts.map

package/lib/services/aiGen/providers/runway/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/runway/types.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,kBAAkB,kFAOd,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA4B,CAAC;AAEnE,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AACzD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,eAAO,MAAM,oBAAoB,EAAE,MAAM,EAA+B,CAAC;AAEzE,QAAA,MAAM,kBAAkB,wGASd,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA4B,CAAC;AAEnE,eAAO,MAAM,qBAAqB,cAAe,CAAC;AAClD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,eAAO,MAAM,oBAAoB,EAAE,MAAM,EAA+B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/services/aiGen/providers/runway/types.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,kBAAkB,kFAOd,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA4B,CAAC;AAEnE,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AACzD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,eAAO,MAAM,oBAAoB,EAAE,MAAM,EAA+B,CAAC;AAEzE,QAAA,MAAM,kBAAkB,wGASd,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AACjE,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAA4B,CAAC;AAEnE,eAAO,MAAM,qBAAqB,cAAe,CAAC;AAClD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,eAAO,MAAM,oBAAoB,EAAE,MAAM,EAA+B,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,EAOjD,CAAC"}

package/lib/services/aiGen/providers/runway/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GEN4_ALEPH_DURATIONS = exports.TGEN4_ALEPH_DURATIONS = exports.GEN4_ALEPH_RATIOS = exports.GEN4_TURBO_DURATIONS = exports.TGEN4_TURBO_DURATIONS = exports.GEN4_TURBO_RATIOS = void 0;
+exports.RUNWAY_VIDEO_CANONICAL_RATIOS = exports.GEN4_ALEPH_DURATIONS = exports.TGEN4_ALEPH_DURATIONS = exports.GEN4_ALEPH_RATIOS = exports.GEN4_TURBO_DURATIONS = exports.TGEN4_TURBO_DURATIONS = exports.GEN4_TURBO_RATIOS = void 0;
 const TGEN4_TURBO_RATIOS = [
     "1280:720", // default
     "1584:672",
@@ -25,3 +25,24 @@ const TGEN4_ALEPH_RATIOS = [
 exports.GEN4_ALEPH_RATIOS = [...TGEN4_ALEPH_RATIOS];
 exports.TGEN4_ALEPH_DURATIONS = [5];
 exports.GEN4_ALEPH_DURATIONS = [...exports.TGEN4_ALEPH_DURATIONS];
+/**
+ * Canonical aspect ratios the Runway VIDEO models accept from the agent / UI
+ * layer. This is the CONTRACT `validateParams` checks the incoming canonical
+ * `aspectRatio` against — every other provider's config lists canonical ratios
+ * here too. The service then translates canonical → Runway pixel ratio at
+ * request time via `mapAspectToRunwayVideoRatio`. The pixel-ratio constants
+ * above (`GEN4_TURBO_RATIOS` / `GEN4_ALEPH_RATIOS`) describe the NATIVE values
+ * the Runway API accepts and back the `Gen4TurboRatio` / `Gen4AlephRatio` types
+ * used at that boundary — they are intentionally NOT the validation set.
+ *
+ * AG-16: keep this in lockstep with `mapAspectToRunwayVideoRatio`'s switch —
+ * every value listed here must map to a valid pixel ratio for all flavors.
+ */
+exports.RUNWAY_VIDEO_CANONICAL_RATIOS = [
+    "16:9",
+    "9:16",
+    "1:1",
+    "4:3",
+    "3:4",
+    "21:9",
+];

package/lib/services/firestore.service.d.ts

@@ -1,5 +1,5 @@
 import { DocumentData, OrderByDirection, WhereFilterOp } from "@google-cloud/firestore";
-import { CollectionReference, DocumentReference } from "firebase-admin/firestore";
+import { CollectionReference, DocumentReference, FieldValue } from "firebase-admin/firestore";
 import { DeepPartial } from "../globals/types";
 import { IAgentProjectModel, IAgentRunModel, IBrandKitModel, IStyleMemoryModel } from "../models/agent.model";
 import { ICachedAssetModel } from "../models/cachedAsset.model";
@@ -55,6 +55,12 @@ export declare class FirestoreService {
     static socialPostsCol: CollectionReference<ISocialPostModel, DocumentData>;
     static socialAnalyticsCol: CollectionReference<ISocialAnalyticsModel, DocumentData>;
     static socialInboxCol: CollectionReference<ISocialInboxItemModel, DocumentData>;
+    /**
+     * Sentinel for `.update()` that removes a field from a doc (wraps
+     * `FieldValue.delete()`). Use to clear a transient field — e.g. plan-B's
+     * `planRun` once a live plan lands — without reading the doc first.
+     */
+    static deleteField(): FieldValue;
     /** Add new document with generated ID */
     static appendNewRecord<T>(collectionRef: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
     /** Add or overwrite a document with a specific ID */

package/lib/services/firestore.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"firestore.service.d.ts","sourceRoot":"","sources":["../../src/services/firestore.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"firestore.service.d.ts","sourceRoot":"","sources":["../../src/services/firestore.service.ts"],"names":[],"mappings":"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"}

package/lib/services/firestore.service.js

@@ -22,6 +22,14 @@ function collectionConverter() {
  */
 class FirestoreService {
     // 🔹 CRUD / Utility methods
+    /**
+     * Sentinel for `.update()` that removes a field from a doc (wraps
+     * `FieldValue.delete()`). Use to clear a transient field — e.g. plan-B's
+     * `planRun` once a live plan lands — without reading the doc first.
+     */
+    static deleteField() {
+        return firestore_1.FieldValue.delete();
+    }
     /** Add new document with generated ID */
     static async appendNewRecord(collectionRef, data) {
         const docRef = collectionRef.doc();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vidspotai-shared",
-  "version": "1.0.84",
+  "version": "1.0.86",
   "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":"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"}