vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/personas.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersonaRouter = exports.PERSONA_PACKS = exports.AgentPersonaSchema = void 0;
+exports.resolveConsistencyTier = resolveConsistencyTier;
+const zod_1 = require("zod");
+const agentPersona_schema_1 = require("../../schemas/agentPersona.schema");
+Object.defineProperty(exports, "AgentPersonaSchema", { enumerable: true, get: function () { return agentPersona_schema_1.AgentPersonaSchema; } });
+const modelRouter_1 = require("./modelRouter");
+exports.PERSONA_PACKS = {
+    "ugc-ad": {
+        id: "ugc-ad",
+        label: "UGC Ad",
+        blurb: "Hook-first 9:16 ads with creator energy and punchy product reveals.",
+        defaults: {
+            aspect: "9:16",
+            durationSec: 30,
+            tone: "warm",
+            pacing: "fast",
+            hookStyle: "pattern-interrupt",
+            tierBudget: "T2",
+        },
+        plannerPrompt: [
+            "UGC ad rules:",
+            "- First 3s MUST be a problem-statement or pattern-interrupt hook (no logos, no slow b-roll).",
+            "- Cut every 1.5–2.5s after the hook.",
+            "- Voiceover or talking-head drives the script; visuals support, not lead.",
+            "- End with a one-sentence CTA + product name burned in.",
+            "- Avoid medical / unverifiable claims (legal risk).",
+        ].join("\n"),
+        defaultBpm: 110,
+        criticEmphasis: { hookStrength: 0.3, brandSafety: 0.2 },
+        recommendedConsistencyTier: "C2",
+    },
+    "faceless-yt": {
+        id: "faceless-yt",
+        label: "Faceless YouTube",
+        blurb: "Educational 16:9 explainers built mostly from cheap stock + voiceover.",
+        defaults: {
+            aspect: "16:9",
+            durationSec: 60,
+            tone: "informational",
+            pacing: "medium",
+            hookStyle: "bold-claim",
+            tierBudget: "T0",
+        },
+        plannerPrompt: [
+            "Faceless YouTube rules:",
+            "- Mostly T0 (stock + Ken Burns) to keep cost <$0.10/video.",
+            "- Hook = counter-intuitive claim or surprising stat in first 8s.",
+            "- Captions burned in; assume sound-off viewing.",
+            "- 1 voiceover line per scene; visuals illustrate the line literally.",
+            "- Avoid copyrighted footage; prefer stock and AI-generated stills.",
+        ].join("\n"),
+        criticEmphasis: { costVsTier: 0.25, voVisualSync: 0.25 },
+        recommendedConsistencyTier: "C1",
+    },
+    "product-demo": {
+        id: "product-demo",
+        label: "Product Demo",
+        blurb: "Square e-comm demos with hero shot first and crisp end-cards.",
+        defaults: {
+            aspect: "1:1",
+            durationSec: 20,
+            tone: "energetic",
+            pacing: "fast",
+            hookStyle: "demo",
+            tierBudget: "T2",
+        },
+        plannerPrompt: [
+            "Product demo rules:",
+            "- Hero product shot in first 3s (T2 image-to-video on the hero only).",
+            "- T0 stock or T1 AI image+motion for filler scenes between.",
+            "- Background music ducked under voiceover; no music-only sections.",
+            "- End-card with logo + CTA; aspect MUST match brief (default 1:1).",
+        ].join("\n"),
+        criticEmphasis: { intentMatch: 0.3, brandSafety: 0.15 },
+        recommendedConsistencyTier: "C2",
+    },
+    "talking-head": {
+        id: "talking-head",
+        label: "Talking-Head Educator",
+        blurb: "Authority-driven explainers using a presenter avatar + b-roll cutaways.",
+        defaults: {
+            aspect: "16:9",
+            durationSec: 45,
+            tone: "professional",
+            pacing: "medium",
+            hookStyle: "question",
+            tierBudget: "T1",
+        },
+        plannerPrompt: [
+            "Talking-head educator rules:",
+            "- Persona is on-camera (avatar or stock talking-head); cut to b-roll for emphasis only.",
+            "- Open with a question the viewer has googled.",
+            "- One key insight per 10s; recap at end.",
+            "- Prefer T1 (image+motion) for b-roll; T0 stock fallbacks if budget tight.",
+        ].join("\n"),
+        criticEmphasis: { intentMatch: 0.25, voVisualSync: 0.25 },
+        recommendedConsistencyTier: "C2",
+    },
+    "social-recap": {
+        id: "social-recap",
+        label: "Social Recap",
+        blurb: "Fast multi-clip recaps for news, sports, listicles — beat-cut energy.",
+        defaults: {
+            aspect: "9:16",
+            durationSec: 30,
+            tone: "energetic",
+            pacing: "very-fast",
+            hookStyle: "stat",
+            tierBudget: "T0",
+        },
+        plannerPrompt: [
+            "Social recap rules:",
+            "- Cuts on the music beat; assume an upbeat track at 110–130 BPM.",
+            "- 1 sentence per clip max; on-screen text mirrors voice.",
+            "- Mostly T0 stock; use AI generation sparingly for transitions.",
+            "- Hook = the most surprising stat or the punchline up front.",
+        ].join("\n"),
+        defaultBpm: 120,
+        criticEmphasis: { pacingFit: 0.3, costVsTier: 0.2 },
+        recommendedConsistencyTier: "C1",
+    },
+};
+/**
+ * AG-30: resolve the consistency tier for an agent run. Brief wins when set
+ * explicitly; otherwise fall back to the persona's recommendation; otherwise
+ * the safe global default of C1. UGC / talking-head / product-demo
+ * recommend C2 because the same presenter/product needs to look identical
+ * across cuts — text descriptions alone produce a different actor every
+ * scene (Test 1 had 5 different women in 5 scenes on C1).
+ */
+function resolveConsistencyTier(persona, briefTier) {
+    if (briefTier)
+        return briefTier;
+    const personaTier = persona ? exports.PERSONA_PACKS[persona]?.recommendedConsistencyTier : undefined;
+    return personaTier ?? "C1";
+}
+const RoutedPersonaSchema = zod_1.z.object({
+    persona: agentPersona_schema_1.AgentPersonaSchema,
+    confidence: zod_1.z.number().min(0).max(1),
+    reason: zod_1.z.string(),
+});
+class PersonaRouter {
+    constructor(llm, router = new modelRouter_1.ModelRouter()) {
+        this.llm = llm;
+        this.router = router;
+    }
+    async route(rawPrompt) {
+        const model = this.router.pickFor("router");
+        const personaList = Object.values(exports.PERSONA_PACKS)
+            .map((p) => `- ${p.id}: ${p.blurb}`)
+            .join("\n");
+        const result = await this.llm.structured({
+            model,
+            fallbackModel: this.router.fallbackFor("router"),
+            schema: RoutedPersonaSchema,
+            schemaName: "RoutedPersona",
+            temperature: 0,
+            messages: [
+                {
+                    role: "system",
+                    content: [
+                        "Classify the user's video request into ONE persona.",
+                        "Personas:",
+                        personaList,
+                        "",
+                        "Pick the closest fit. confidence 0..1; reason in <20 words.",
+                    ].join("\n"),
+                },
+                { role: "user", content: rawPrompt },
+            ],
+        });
+        return result.data;
+    }
+}
+exports.PersonaRouter = PersonaRouter;

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

@@ -0,0 +1,76 @@
+import { VideoPlan } from "../../schemas/videoPlan.schema";
+import type { RegenComponent } from "../credits/pricing";
+/**
+ * Stage 7 slice 2 — plan diff engine.
+ *
+ * Computes a structured changeset between two VideoPlans and derives which
+ * per-scene components (visual / voiceover / overlays / captions) and which
+ * top-level singletons (music) would need to be regenerated to materialize
+ * the new plan from the old project.
+ *
+ * Pure / no I/O. Feeds slice 3's bulk-regen endpoint: the endpoint takes the
+ * `regenTargets` array and fans out to the existing per-component regen
+ * handlers (regenerateScene / regenerateVoiceover / regenerateOverlays /
+ * regenerateCaptions / regenerateMusic).
+ *
+ * Why a separate helper and not just "regen everything that's different":
+ * each regen costs money. The user might edit only scene 3's voiceoverLine
+ * — we'd waste $0.30+ on visual regens if we naively reflowed every scene.
+ * The diff makes the actual change-set explicit.
+ *
+ * Field → component mapping:
+ *   prompt, strategy, preferredModel, preferredProvider, durationMs,
+ *   tier, bibleEntityIds, characterAnchorSceneIndex, avatarFaceUrl
+ *                                                               → visual
+ *   voiceoverLine, voiceStyle                                   → voiceover
+ *                                                                 + captions (derived from VO audio)
+ *   overlays, onScreenText                                      → overlays
+ *   transitionIn                                                → none (stitch-time)
+ *   estimatedCredits, intent                                    → none (derived / informational)
+ *
+ * Plan-level cascades:
+ *   aspect change           → all scenes' visual
+ *   voiceId / voiceStyle    → all scenes' voiceover + captions
+ *   bible.*                 → all scenes' visual (bible drives reference images)
+ *   music.*                 → music singleton
+ */
+export interface RegenTarget {
+    component: RegenComponent;
+    /** Omitted for "music" — there is one music clip per project. */
+    sceneIndex?: number;
+}
+export interface SceneDiff {
+    sceneIndex: number;
+    kind: "added" | "removed" | "modified";
+    /** Names of scene fields that differ. Empty for "removed" (nothing to regen). */
+    changedFields: string[];
+    /** Derived from changedFields via the mapping above. */
+    affectedComponents: RegenComponent[];
+}
+export interface PlanLevelChanges {
+    aspectChanged: boolean;
+    voiceIdChanged: boolean;
+    voiceStyleChanged: boolean;
+    bibleChanged: boolean;
+    musicChanged: boolean;
+}
+export interface PlanDiff {
+    hasChanges: boolean;
+    sceneChanges: SceneDiff[];
+    planLevel: PlanLevelChanges;
+    /**
+     * Deduplicated list of components × scenes that need regen. Already
+     * accounts for plan-level cascades — if aspect changed, every existing
+     * scene's visual is included here even if its own fields didn't change.
+     * Stable order: scene 0 first (visual → voiceover → overlays → captions),
+     * then scene 1, ..., then "music" last.
+     */
+    regenTargets: RegenTarget[];
+}
+/**
+ * Diff two plans. Both args required — fresh-project bootstrap should call
+ * /execute, not /regenerate-bulk, so there's no "old plan is undefined" case
+ * to support here.
+ */
+export declare function diffPlans(oldPlan: VideoPlan, newPlan: VideoPlan): PlanDiff;
+//# sourceMappingURL=planDiff.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planDiff.d.ts","sourceRoot":"","sources":["../../../src/services/agent/planDiff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,SAAS,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,cAAc,CAAC;IAC1B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IACvC,iFAAiF;IACjF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,wDAAwD;IACxD,kBAAkB,EAAE,cAAc,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,SAAS,EAAE,CAAC;IAC1B,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;OAMG;IACH,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAoGD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,GAAG,QAAQ,CAwF1E"}

package/lib/services/agent/planDiff.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffPlans = diffPlans;
+/**
+ * Per-component mapping. Some fields fan out to multiple components (e.g.
+ * voiceoverLine drives both VO audio AND its caption transcript).
+ */
+const SCENE_FIELD_TO_COMPONENTS = {
+    prompt: ["visual"],
+    strategy: ["visual"],
+    preferredModel: ["visual"],
+    preferredProvider: ["visual"],
+    durationMs: ["visual"],
+    tier: ["visual"],
+    bibleEntityIds: ["visual"],
+    characterAnchorSceneIndex: ["visual"],
+    avatarFaceUrl: ["visual"],
+    voiceoverLine: ["voiceover", "captions"],
+    voiceStyle: ["voiceover", "captions"],
+    overlays: ["overlays"],
+    onScreenText: ["overlays"],
+};
+const SCENE_FIELDS_TO_DIFF = [
+    "prompt",
+    "strategy",
+    "preferredModel",
+    "preferredProvider",
+    "durationMs",
+    "tier",
+    "bibleEntityIds",
+    "characterAnchorSceneIndex",
+    "avatarFaceUrl",
+    "voiceoverLine",
+    "voiceStyle",
+    "overlays",
+    "onScreenText",
+];
+function stableStringify(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return "[" + value.map(stableStringify).join(",") + "]";
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        return ("{" +
+            keys
+                .map((k) => JSON.stringify(k) + ":" + stableStringify(obj[k]))
+                .join(",") +
+            "}");
+    }
+    return "null";
+}
+function fieldChanged(a, b) {
+    return stableStringify(a) !== stableStringify(b);
+}
+function diffScene(oldScene, newScene) {
+    const changedFields = [];
+    for (const field of SCENE_FIELDS_TO_DIFF) {
+        if (fieldChanged(oldScene[field], newScene[field])) {
+            changedFields.push(field);
+        }
+    }
+    if (changedFields.length === 0)
+        return null;
+    const affected = new Set();
+    for (const field of changedFields) {
+        const mapped = SCENE_FIELD_TO_COMPONENTS[field];
+        if (mapped) {
+            for (const c of mapped)
+                affected.add(c);
+        }
+    }
+    return {
+        sceneIndex: newScene.sceneIndex,
+        kind: "modified",
+        changedFields,
+        affectedComponents: Array.from(affected),
+    };
+}
+function diffPlanLevel(oldPlan, newPlan) {
+    return {
+        aspectChanged: oldPlan.aspect !== newPlan.aspect,
+        voiceIdChanged: (oldPlan.voiceId ?? null) !== (newPlan.voiceId ?? null),
+        voiceStyleChanged: (oldPlan.voiceStyle ?? null) !== (newPlan.voiceStyle ?? null),
+        bibleChanged: fieldChanged(oldPlan.bible, newPlan.bible),
+        musicChanged: fieldChanged(oldPlan.music, newPlan.music),
+    };
+}
+/**
+ * Diff two plans. Both args required — fresh-project bootstrap should call
+ * /execute, not /regenerate-bulk, so there's no "old plan is undefined" case
+ * to support here.
+ */
+function diffPlans(oldPlan, newPlan) {
+    // Index scenes by sceneIndex (NOT array position — planners may reorder).
+    const oldByIdx = new Map(oldPlan.scenes.map((s) => [s.sceneIndex, s]));
+    const newByIdx = new Map(newPlan.scenes.map((s) => [s.sceneIndex, s]));
+    const sceneChanges = [];
+    // Added or modified — iterate the new plan so order matches scene order.
+    for (const newScene of newPlan.scenes) {
+        const oldScene = oldByIdx.get(newScene.sceneIndex);
+        if (!oldScene) {
+            // Brand new scene — every component needs to be produced.
+            const affected = ["visual"];
+            if (newScene.voiceoverLine) {
+                affected.push("voiceover", "captions");
+            }
+            if (newScene.overlays?.length || newScene.onScreenText) {
+                affected.push("overlays");
+            }
+            sceneChanges.push({
+                sceneIndex: newScene.sceneIndex,
+                kind: "added",
+                changedFields: [],
+                affectedComponents: affected,
+            });
+            continue;
+        }
+        const modDiff = diffScene(oldScene, newScene);
+        if (modDiff)
+            sceneChanges.push(modDiff);
+    }
+    // Removed.
+    for (const oldScene of oldPlan.scenes) {
+        if (!newByIdx.has(oldScene.sceneIndex)) {
+            sceneChanges.push({
+                sceneIndex: oldScene.sceneIndex,
+                kind: "removed",
+                changedFields: [],
+                affectedComponents: [],
+            });
+        }
+    }
+    const planLevel = diffPlanLevel(oldPlan, newPlan);
+    // Build deduplicated regen targets in stable order.
+    // 1) Per-scene targets, scene order, component order (visual → vo → overlays → captions).
+    const componentOrder = ["visual", "voiceover", "overlays", "captions"];
+    const seen = new Set();
+    const regenTargets = [];
+    // Per-scene targets from the diff (covers added + modified).
+    for (const newScene of newPlan.scenes) {
+        const change = sceneChanges.find((c) => c.sceneIndex === newScene.sceneIndex && c.kind !== "removed");
+        const componentsForScene = new Set(change?.affectedComponents ?? []);
+        // Plan-level cascades — only apply to scenes that still exist in newPlan.
+        if (planLevel.aspectChanged || planLevel.bibleChanged) {
+            componentsForScene.add("visual");
+        }
+        if ((planLevel.voiceIdChanged || planLevel.voiceStyleChanged) &&
+            newScene.voiceoverLine) {
+            componentsForScene.add("voiceover");
+            componentsForScene.add("captions");
+        }
+        for (const c of componentOrder) {
+            if (!componentsForScene.has(c))
+                continue;
+            const key = `${c}:${newScene.sceneIndex}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            regenTargets.push({ component: c, sceneIndex: newScene.sceneIndex });
+        }
+    }
+    // Music — singleton, no sceneIndex.
+    if (planLevel.musicChanged) {
+        regenTargets.push({ component: "music" });
+    }
+    const hasChanges = sceneChanges.length > 0 || regenTargets.length > 0;
+    return {
+        hasChanges,
+        sceneChanges,
+        planLevel,
+        regenTargets,
+    };
+}

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

@@ -0,0 +1,46 @@
+import type { Project } from "../../schemas/project.schema";
+/**
+ * planMutations — Stage 7-prep helper for the agent permission flow.
+ *
+ * When the agent is asked to (re)generate against an existing Project, the
+ * controller calls `findClipsNeedingPermission(currentProject)` BEFORE
+ * enqueuing the run. Any clip that is `locked === true` OR has a
+ * user-placed provenance source is surfaced as a `MutationProposal` so the
+ * drawer can prompt the user with a per-clip yes/no modal.
+ *
+ * v0 contract (this file): coarse — we list every protected clip in the
+ * current project. We don't yet diff against the new plan to determine
+ * which protected clips it would actually displace (that's Stage 7's diff
+ * engine). Over-prompting is acceptable for v0; under-prompting is not.
+ *
+ * Provenance sources considered "user-placed" (the agent should ask before
+ * touching them) are listed in USER_PLACED_PROVENANCE_SOURCES below.
+ */
+/** Provenance.source strings that mark a clip as user-placed (not agent-generated). */
+export declare const USER_PLACED_PROVENANCE_SOURCES: ReadonlySet<string>;
+export type MutationReason = "locked" | "user-placed";
+export interface MutationProposal {
+    /** Existing clip id in `currentProject.clips`. */
+    clipId: string;
+    /** The clip's track kind (visual / voiceover / music / text / caption / unknown). */
+    clipKind: "visual" | "voiceover" | "music" | "text" | "caption" | "unknown";
+    /** Human-readable label for the modal row, e.g. "Scene 3 — voiceover". */
+    currentLabel: string;
+    /** Why the agent must ask. */
+    reason: MutationReason;
+    /** Original provenance source if known (e.g. "user-upload"). */
+    provenanceSource?: string;
+}
+/**
+ * Returns the list of clips in `currentProject` that the agent must obtain
+ * user permission for before touching. Returns `[]` if there's no current
+ * project (first run on an empty canvas) or no protected clips.
+ */
+export declare function findClipsNeedingPermission(currentProject: Project | null | undefined): MutationProposal[];
+/**
+ * Convenience predicate used by the controller before enqueueing a run.
+ * Returns true if the user must be prompted; false if the run can proceed
+ * straight through.
+ */
+export declare function requiresUserConfirmation(currentProject: Project | null | undefined): boolean;
+//# sourceMappingURL=planMutations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planMutations.d.ts","sourceRoot":"","sources":["../../../src/services/agent/planMutations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAQ,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAGlE;;;;;;;;;;;;;;;;GAgBG;AAEH,uFAAuF;AACvF,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAG7D,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,QAAQ,EAAE,QAAQ,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5E,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAyDD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GACzC,gBAAgB,EAAE,CAgBpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GACzC,OAAO,CAET"}

package/lib/services/agent/planMutations.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_PLACED_PROVENANCE_SOURCES = void 0;
+exports.findClipsNeedingPermission = findClipsNeedingPermission;
+exports.requiresUserConfirmation = requiresUserConfirmation;
+const planToProject_1 = require("../editor/planToProject");
+/**
+ * planMutations — Stage 7-prep helper for the agent permission flow.
+ *
+ * When the agent is asked to (re)generate against an existing Project, the
+ * controller calls `findClipsNeedingPermission(currentProject)` BEFORE
+ * enqueuing the run. Any clip that is `locked === true` OR has a
+ * user-placed provenance source is surfaced as a `MutationProposal` so the
+ * drawer can prompt the user with a per-clip yes/no modal.
+ *
+ * v0 contract (this file): coarse — we list every protected clip in the
+ * current project. We don't yet diff against the new plan to determine
+ * which protected clips it would actually displace (that's Stage 7's diff
+ * engine). Over-prompting is acceptable for v0; under-prompting is not.
+ *
+ * Provenance sources considered "user-placed" (the agent should ask before
+ * touching them) are listed in USER_PLACED_PROVENANCE_SOURCES below.
+ */
+/** Provenance.source strings that mark a clip as user-placed (not agent-generated). */
+exports.USER_PLACED_PROVENANCE_SOURCES = new Set([
+    "user-upload",
+    "user-library",
+]);
+/**
+ * Maps a clip to its track kind based on the project's track list. Falls
+ * back to "unknown" when the track id isn't declared (defensive — every
+ * clip's track should appear in project.tracks, but the schema doesn't
+ * enforce referential integrity yet).
+ */
+function clipKindFor(clip, project) {
+    // TRACK_ID values are the canonical track handles emitted by planToProject;
+    // checking them first cleanly separates voiceover from music (both have
+    // Track.kind === "audio") without depending on a free-form Track.name.
+    if (clip.trackId === planToProject_1.TRACK_ID.voiceover)
+        return "voiceover";
+    if (clip.trackId === planToProject_1.TRACK_ID.music)
+        return "music";
+    if (clip.trackId === planToProject_1.TRACK_ID.visual)
+        return "visual";
+    if (clip.trackId === planToProject_1.TRACK_ID.text)
+        return "text";
+    if (clip.trackId === planToProject_1.TRACK_ID.caption)
+        return "caption";
+    const track = project.tracks.find((t) => t.id === clip.trackId);
+    if (!track)
+        return "unknown";
+    switch (track.kind) {
+        case "video":
+            return "visual";
+        case "audio":
+            // Track.name is the only signal left to distinguish vo from music when
+            // the trackId doesn't match the planToProject canonical set (e.g. a
+            // user-added audio track in the editor).
+            return /voice|vo|narration/i.test(track.name ?? "") ? "voiceover" : "music";
+        case "text":
+            return "text";
+        case "caption":
+            return "caption";
+        case "fx":
+            return "unknown";
+        default:
+            return "unknown";
+    }
+}
+/**
+ * Best-effort label for the modal: prefer the clip's user-set `name`, else
+ * "<kind> clip @<seconds>s". Used purely for display — never relied on for
+ * identity (clip.id is the only stable handle).
+ */
+function clipLabel(clip, kind) {
+    if (clip.name && clip.name.trim().length > 0)
+        return clip.name.trim();
+    const seconds = Math.round((clip.display.from ?? 0) / 100) / 10;
+    return `${kind} clip @${seconds}s`;
+}
+function isProtected(clip) {
+    if (clip.locked)
+        return "locked";
+    const source = clip.provenance?.source;
+    if (source && exports.USER_PLACED_PROVENANCE_SOURCES.has(source))
+        return "user-placed";
+    return null;
+}
+/**
+ * Returns the list of clips in `currentProject` that the agent must obtain
+ * user permission for before touching. Returns `[]` if there's no current
+ * project (first run on an empty canvas) or no protected clips.
+ */
+function findClipsNeedingPermission(currentProject) {
+    if (!currentProject)
+        return [];
+    const out = [];
+    for (const clip of currentProject.clips) {
+        const reason = isProtected(clip);
+        if (!reason)
+            continue;
+        const kind = clipKindFor(clip, currentProject);
+        out.push({
+            clipId: clip.id,
+            clipKind: kind,
+            currentLabel: clipLabel(clip, kind),
+            reason,
+            provenanceSource: clip.provenance?.source,
+        });
+    }
+    return out;
+}
+/**
+ * Convenience predicate used by the controller before enqueueing a run.
+ * Returns true if the user must be prompted; false if the run can proceed
+ * straight through.
+ */
+function requiresUserConfirmation(currentProject) {
+    return findClipsNeedingPermission(currentProject).length > 0;
+}