@nodetool-ai/agents 0.8.1 → 0.8.3

package/dist/capabilities/storyboards.js

@@ -1,3 +1,4 @@
+import { finishStoryboard, layoutStoryboard, previewStoryboardDesign } from "./finish-storyboard.js";
 /**
  * The `storyboards` capability module.
  *
@@ -15,10 +16,15 @@
  *
  * Design: docs/tool-class-retirement-design.md § "Migration".
  */
-import { mp4DurationSeconds } from "@nodetool-ai/runtime";
+import { z } from "zod";
+import { SpanStatusCode } from "@opentelemetry/api";
+import { mp4DurationSeconds, withSpan } from "@nodetool-ai/runtime";
+import { storyboardMotionDesign, storyboardShotGraphics } from "@nodetool-ai/protocol/api-schemas/storyboards.js";
+import { assertProductionGenerationAllowed, compileOneTake, isFullResourceId, isShortResourceId, productionRequirement } from "@nodetool-ai/protocol";
 import { stampScriptStoryboardId } from "./script-link.js";
-import { listStoryboardsSpec, createStoryboardSpec, getStoryboardSpec, renderStoryboardStillsSpec, renderStoryboardClipsSpec, reviseStoryboardClipSpec, assembleStoryboardTimelineSpec, editStoryboardSpec, directStoryboardSpec, extractScriptFromStoryboardSpec, deleteStoryboardSpec } from "./storyboards.specs.js";
-import { clampConcurrency, mapWithConcurrency } from "./concurrency.js";
+import { listStoryboardsSpec, createStoryboardSpec, getStoryboardSpec, renderStoryboardStillsSpec, renderStoryboardClipsSpec, reviseStoryboardClipSpec, assembleStoryboardTimelineSpec, deriveShotFromClipSpec, editStoryboardSpec, directStoryboardSpec, extractScriptFromStoryboardSpec, deleteStoryboardSpec, getStoryboardOneTakeSpec, updateStoryboardOneTakeSpec } from "./storyboards.specs.js";
+import { measureStoryboardSources } from "./storyboard-measured-sources.js";
+import { clampConcurrency } from "./concurrency.js";
 import { isNonBlankString, isNumber, isRecord, isString } from "../utils/type-guards.js";
 import { resolveProjectId } from "./project-scope.js";
 /** Shots one call may render, so a stray `targets: "all"` cannot bankrupt a run. */
@@ -323,7 +329,8 @@ const listStoryboards = {
                     with_keyframe: doc.shots.filter((s) => !!s.keyframe).length,
                     with_clip: doc.shots.filter((s) => !!s.clip).length,
                     timeline_id: row.timeline_id ?? undefined,
-                    updated_at: row.updated_at
+                    updated_at: row.updated_at,
+                    revision: row.revision
                 };
             })
         };
@@ -342,7 +349,8 @@ function createdBoardSummary(row) {
         name: row.name,
         project_id: row.project_id,
         shots: doc.shots.length,
-        updated_at: row.updated_at
+        updated_at: row.updated_at,
+        revision: row.revision
     };
 }
 const createStoryboard = {
@@ -408,6 +416,7 @@ const getStoryboard = {
         const drifted = new Set(link.drifted_shot_ids);
         return {
             id: row.id,
+            revision: row.revision,
             name: row.name,
             brief: doc.brief,
             style: doc.style,
@@ -418,6 +427,7 @@ const getStoryboard = {
             timeline_id: row.timeline_id ?? undefined,
             narration: doc.screenplay?.narration ?? undefined,
             music_prompt: doc.screenplay?.music_prompt ?? undefined,
+            motion_design: doc.screenplay?.motion_design ?? null,
             script_id: link.script_id,
             script_link: link,
             shots: [...doc.shots]
@@ -429,6 +439,10 @@ const getStoryboard = {
                 action: shot.action,
                 camera: shot.camera,
                 motion: shot.motion,
+                end_state: shot.end_state,
+                sound: shot.sound,
+                graphics: shot.graphics,
+                production: shot.production,
                 duration_seconds: shot.duration_seconds,
                 status: shot.status,
                 has_keyframe: !!shot.keyframe,
@@ -531,6 +545,71 @@ async function filterStale(selected, params, doc, entities, kind) {
             .map((shot) => shot.id)
     };
 }
+function modelOverrides(params) {
+    const options = {};
+    if (isNonBlankString(params["provider"])) {
+        options.provider = params["provider"];
+    }
+    if (isNonBlankString(params["model"])) {
+        options.model = params["model"];
+    }
+    return options;
+}
+function missingPlanModel(plan) {
+    if (plan.model.provider && plan.model.model) {
+        return undefined;
+    }
+    return {
+        error: `No ${plan.kind === "keyframe" ? "still" : "clip"} model is set for shot ${plan.shotId}. Pass provider + model (use find_model), or set one on the shot or board.`
+    };
+}
+async function clipModelError(context, plans) {
+    const groups = new Map();
+    for (const plan of plans) {
+        const error = missingPlanModel(plan);
+        if (error) {
+            return error;
+        }
+        if (plan.preflightError) {
+            continue;
+        }
+        const key = JSON.stringify([plan.model.provider, plan.model.model]);
+        const group = groups.get(key) ?? [];
+        group.push(plan);
+        groups.set(key, group);
+    }
+    for (const group of groups.values()) {
+        const model = group[0].model;
+        let supportedTasks = model.supportedTasks;
+        try {
+            const provider = await context.getProvider(model.provider);
+            const models = await provider.getAvailableVideoModels();
+            supportedTasks =
+                models.find((entry) => entry.id === model.model)?.supportedTasks ??
+                    supportedTasks;
+        }
+        catch {
+            // Legacy providers can lack discovery, so their persisted task declarations apply.
+        }
+        const unsupported = group.find((plan) => {
+            const task = plan.mode === "direct" ? "text_to_video" : plan.mode === "reference" ? "reference_to_video" : "image_to_video";
+            return supportedTasks?.length && !supportedTasks.includes(task);
+        });
+        if (unsupported) {
+            const task = unsupported.mode === "direct" ? "text_to_video" : unsupported.mode === "reference" ? "reference_to_video" : "image_to_video";
+            return {
+                error: `The selected clip model ${model.provider}/${model.model} does not support ${task}; choose a model that supports the selected shot mode.`
+            };
+        }
+    }
+    return undefined;
+}
+function uniformModel(plans) {
+    const model = plans[0]?.model;
+    return model && plans.every((plan) => plan.model.provider === model.provider && plan.model.model === model.model)
+        ? { provider: model.provider, model: model.model }
+        : {};
+}
 const renderStoryboardStills = {
     spec: renderStoryboardStillsSpec,
     impl: async (run, params) => {
@@ -539,14 +618,11 @@ const renderStoryboardStills = {
         if (isError(board))
             return board;
         const { row, doc } = board;
-        const model = resolveModel(params, doc.imageModel, "still", "text_to_image");
-        if (isError(model))
-            return model;
         const { shotRenderMode } = await import("@nodetool-ai/protocol");
         // A direct shot renders its clip from the prompt, so it needs no still.
         // Naming it in `targets` still renders one — a board frame to look at is
         // worth having even when the clip does not come from it.
-        const selected = selectShots(doc.shots, params["targets"], (s) => !s.keyframe &&
+        const selected = selectShots(doc.shots, params["targets"], (s) => (params["stale_only"] === true ? !!s.keyframe : !s.keyframe) &&
             shotRenderMode(s) !== "direct" &&
             !shotHasPicture(s, doc.shots));
         if (isError(selected))
@@ -565,6 +641,10 @@ const renderStoryboardStills = {
                     : "No shot needs a still: each already has one, or renders its clip directly."
             };
         }
+        const protectedStill = chosen.find((shot) => shot.production?.protected_inputs?.some((input) => input.asset_id));
+        if (protectedStill) {
+            return { error: `Shot ${protectedStill.id} protects source assets; the current still renderer cannot prove source fidelity. Use those assets directly in Timeline materialization or a policy-aware finishing path.` };
+        }
         if (chosen.length > MAX_SHOTS_PER_CALL) {
             return {
                 error: `${chosen.length} shots selected, over the ${MAX_SHOTS_PER_CALL}-shot per-call limit. Pass targets in batches.`
@@ -575,22 +655,34 @@ const renderStoryboardStills = {
         // says: `style` and `model` can be overridden per call. Recording the
         // override is the point — a version rendered against something other than
         // the board's settings reads stale against the board, correctly.
-        const planOptions = {
-            provider: model.provider,
-            model: model.model
-        };
+        const planOptions = modelOverrides(params);
         if (isString(params["style"])) {
             planOptions.style = params["style"];
         }
         const plans = planShotRenders(doc, entities, "keyframe", chosen.map((shot) => shot.id), planOptions);
-        const outcomes = await renderShots(renderHost(context), { id: row.id }, plans, {
-            concurrency: clampConcurrency(params["concurrency"])
+        const { imageModelSupportsTask } = await import("@nodetool-ai/runtime");
+        for (const plan of plans) {
+            const modelError = missingPlanModel(plan);
+            if (modelError) {
+                return modelError;
+            }
+            plan.stillModelTakesImages = await imageModelSupportsTask(context, plan.model, "image_to_image", plan.model.supportedTasks);
+        }
+        const outcomes = await withSpan("render", {
+            "document.id": row.id,
+            "render.kind": "keyframe",
+            "render.shot_count": plans.length
+        }, async (span) => {
+            const rendered = await renderShots(renderHost(context), { id: row.id }, plans, { concurrency: clampConcurrency(params["concurrency"]) });
+            if (rendered.some((outcome) => !outcome.ok)) {
+                span?.setStatus({ code: SpanStatusCode.ERROR });
+            }
+            return rendered;
         });
         const results = outcomes.map((outcome) => outcomeRow(outcome, false));
         return {
             storyboard_id: row.id,
-            provider: model.provider,
-            model: model.model,
+            ...uniformModel(plans),
             rendered: results.filter((r) => r.ok).length,
             failed: results.filter((r) => !r.ok).length,
             skipped,
@@ -613,43 +705,23 @@ const renderStoryboardClips = {
             override !== "reference") {
             return { error: 'mode must be "keyframe", "direct", or "reference".' };
         }
-        // The call's override wins over the shot's own setting, for this call only.
-        const { shotRenderMode } = await import("@nodetool-ai/protocol");
-        const modeOf = (shot) => override === "keyframe" ||
-            override === "direct" ||
-            override === "reference"
-            ? override
-            : shotRenderMode(shot);
-        const selected = selectShots(doc.shots, params["targets"], (s) => !shotHasPicture(s, doc.shots) &&
-            (modeOf(s) === "direct" || modeOf(s) === "reference" || !!s.keyframe));
-        if (isError(selected))
-            return selected;
-        const requiredCapabilities = new Set(selected.map((shot) => modeOf(shot) === "direct"
-            ? "text_to_video"
-            : modeOf(shot) === "reference"
-                ? "reference_to_video"
-                : "image_to_video"));
-        const capability = requiredCapabilities.has("reference_to_video")
-            ? "reference_to_video"
-            : requiredCapabilities.has("image_to_video")
-                ? "image_to_video"
-                : "text_to_video";
-        const model = resolveModel(params, doc.videoModel, "clip", capability);
-        if (isError(model))
-            return model;
-        const declaredTasks = doc.videoModel?.supported_tasks;
-        if (Array.isArray(declaredTasks) &&
-            declaredTasks.length > 0 &&
-            model.model === doc.videoModel?.id &&
-            model.provider === doc.videoModel?.provider) {
-            const unsupported = [...requiredCapabilities].find((task) => !declaredTasks.includes(task));
-            if (unsupported) {
-                return {
-                    error: `The selected clip model does not support ${unsupported}; choose a model that supports every selected shot mode.`
-                };
-            }
+        const candidates = selectShots(doc.shots, params["targets"], (shot) => (params["stale_only"] === true ? !!shot.clip : !shotHasPicture(shot, doc.shots)) &&
+            !shot.covered_by?.shot_id);
+        if (isError(candidates)) {
+            return candidates;
         }
         const entities = await loadBoardEntities(context, doc);
+        const { planShotRenders, renderShots } = await import("@nodetool-ai/storyboard");
+        const readinessOptions = modelOverrides(params);
+        if (override !== undefined) {
+            readinessOptions.mode = override;
+        }
+        const ready = new Set(planShotRenders(doc, entities, "clip", candidates.map((shot) => shot.id), readinessOptions)
+            .filter((plan) => plan.mode !== "keyframe" || !!plan.sourceKeyframe)
+            .map((plan) => plan.shotId));
+        const selected = params["targets"] === undefined || params["targets"] === null
+            ? candidates.filter((shot) => ready.has(shot.id))
+            : candidates;
         const fresh = await filterStale(selected, params, doc, entities, "clip");
         const skipped = fresh.skipped;
         const chosen = fresh.shots;
@@ -663,13 +735,16 @@ const renderStoryboardClips = {
                     : 'No shot is ready for a clip. A keyframe-mode shot needs a still first (render_storyboard_stills), or set its render_mode to "direct" — or pass mode: "direct" here — to render straight from the prompt. Name shots explicitly with `targets` to override the selection.'
             };
         }
+        const forbiddenClip = chosen.find((shot) => shot.production?.media_strategy === "still_motion_graphics");
+        if (forbiddenClip) {
+            return { error: `Shot ${forbiddenClip.id} is still_motion_graphics; video generation is forbidden. Materialize its still/assets as Timeline layers instead.` };
+        }
         if (chosen.length > MAX_SHOTS_PER_CALL) {
             return {
                 error: `${chosen.length} shots selected, over the ${MAX_SHOTS_PER_CALL}-shot per-call limit. Pass targets in batches.`
             };
         }
         const { scriptLinesById } = await import("@nodetool-ai/timeline");
-        const { planShotRenders, renderShots } = await import("@nodetool-ai/storyboard");
         // A linked board times its shots from the words they cover, so a clip is
         // rendered long enough to hold its voiceover (design §2.3). A shot pinned
         // to `manual`, an unvoiced line, or an unlinked board keeps
@@ -678,8 +753,7 @@ const renderStoryboardClips = {
         // As in the stills path: the record says what this call rendered with, so
         // a per-call model or style override reads stale against the board.
         const planOptions = {
-            provider: model.provider,
-            model: model.model,
+            ...modelOverrides(params),
             style: isString(params["style"]) ? params["style"] : doc.style || "",
             scriptLines: scriptLinesById(scriptDoc?.sections ?? [])
         };
@@ -687,18 +761,31 @@ const renderStoryboardClips = {
             planOptions.mode = override;
         }
         const plans = planShotRenders(doc, entities, "clip", chosen.map((shot) => shot.id), planOptions);
+        const modelError = await clipModelError(context, plans);
+        if (modelError) {
+            return modelError;
+        }
         const renderOptions = {
             concurrency: clampConcurrency(params["concurrency"])
         };
         if (isString(params["resolution"])) {
             renderOptions.resolution = params["resolution"];
         }
-        const outcomes = await renderShots(renderHost(context), { id: row.id }, plans, renderOptions);
+        const outcomes = await withSpan("render", {
+            "document.id": row.id,
+            "render.kind": "clip",
+            "render.shot_count": plans.length
+        }, async (span) => {
+            const rendered = await renderShots(renderHost(context), { id: row.id }, plans, renderOptions);
+            if (rendered.some((outcome) => !outcome.ok)) {
+                span?.setStatus({ code: SpanStatusCode.ERROR });
+            }
+            return rendered;
+        });
         const results = outcomes.map((outcome) => outcomeRow(outcome, true));
         return {
             storyboard_id: row.id,
-            provider: model.provider,
-            model: model.model,
+            ...uniformModel(plans),
             rendered: results.filter((r) => r.ok).length,
             failed: results.filter((r) => !r.ok).length,
             skipped,
@@ -723,6 +810,15 @@ const reviseStoryboardClip = {
                 error: `No shot matches "${String(params["target"])}". Call get_storyboard to list shot ids.`
             };
         }
+        if (shot.production?.media_strategy === "still_motion_graphics") {
+            return { error: `Shot ${shot.id} is still_motion_graphics; video revision is forbidden.` };
+        }
+        try {
+            assertProductionGenerationAllowed(shot.production, "video_to_video");
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
         if (!shot.clip) {
             return {
                 error: "Shot has no clip to revise. Run render_storyboard_clips first."
@@ -739,6 +835,13 @@ const reviseStoryboardClip = {
                     error: "The shot's clip could not be read back from storage."
                 };
             }
+            const current = await loadBoard(run, row.id);
+            if (isError(current))
+                return current;
+            const currentShot = current.doc.shots.find((value) => value.id === shot.id);
+            if (!currentShot)
+                return { error: `Shot ${shot.id} no longer exists.` };
+            assertProductionGenerationAllowed(currentShot.production, "video_to_video");
             const saved = await renderMedia(context, {
                 provider: model.provider,
                 capability: "video_to_video",
@@ -786,7 +889,7 @@ const assembleStoryboardTimeline = {
             return board;
         const { row, doc } = board;
         const { Storyboard, TimelineSequence } = await import("@nodetool-ai/models");
-        const { buildLinkedTimeline, buildStoryboardTimeline, foreignTimelineParts, frameSizeForAspect } = await import("@nodetool-ai/timeline");
+        const { buildLinkedTimeline, buildStoryboardTimeline, foreignTimelineParts, assertStoryboardReassemblyAllowed, frameSizeForAspect } = await import("@nodetool-ai/timeline");
         // A board that links a script is cut against the words: shot lengths come
         // from the takes and every voiced line gets its own clip. A link pointing
         // at a script that is gone is a warning, not a failure — the board still
@@ -799,33 +902,7 @@ const assembleStoryboardTimeline = {
         if (scriptId && !script) {
             warnings.push(`Script ${scriptId} is linked but could not be loaded, so the board was assembled on its own.`);
         }
-        const { loadMediaRefBytes, probeVideoDurationSeconds } = await import("@nodetool-ai/runtime");
-        const { applyMeasuredShotClipDurations } = await import("@nodetool-ai/timeline");
-        const signal = context.signal ?? new AbortController().signal;
-        const measurements = await mapWithConcurrency(doc.shots, clampConcurrency(undefined), async (shot) => {
-            const clip = shot.clip;
-            const assetId = clip?.asset_id;
-            if (shot.status !== "rendered" || !assetId)
-                return null;
-            try {
-                const bytes = await loadMediaRefBytes(clip, context);
-                const seconds = bytes?.length
-                    ? await probeVideoDurationSeconds(bytes, signal)
-                    : null;
-                return seconds === null ? null : [assetId, seconds];
-            }
-            catch (error) {
-                if (signal.aborted)
-                    throw error;
-                return null;
-            }
-        });
-        const durations = new Map();
-        for (const measurement of measurements) {
-            if (measurement)
-                durations.set(...measurement);
-        }
-        const measuredShots = applyMeasuredShotClipDurations(doc.shots, durations);
+        const measuredShots = await measureStoryboardSources(doc.shots, context);
         const assembled = script
             ? buildLinkedTimeline({
                 boardId: row.id,
@@ -865,9 +942,9 @@ const assembleStoryboardTimeline = {
                 `(${worst.usedMs}ms in the cut, ${worst.sourceMs}ms rendered). ` +
                 `Re-render those shots at the length their lines need.`);
         }
-        if (assembled.clips.length === 0) {
+        if (assembled.durationMs === 0) {
             return {
-                error: "No shot has a rendered clip, so there is nothing to assemble. Run render_storyboard_stills, then render_storyboard_clips.",
+                error: "No shot has an allowed still, video, or graphics source. Add graphics intent or use render_storyboard_stills / render_storyboard_clips where allowed by the shot production policy.",
                 skipped_shot_ids: assembled.skippedShotIds,
                 skipped_line_ids: skippedLineIds
             };
@@ -934,11 +1011,12 @@ const assembleStoryboardTimeline = {
                 };
             }
             const previous = current.toDocument();
+            assertStoryboardReassemblyAllowed(previous, row.id);
             const foreign = foreignTimelineParts(previous, (clip) => clip.storyboardBoardId === row.id ||
                 (!!scriptId && clip.scriptId === scriptId));
             const tracks = [...assembled.tracks, ...foreign.tracks];
             const clips = [...assembled.clips, ...foreign.clips];
-            const durationMs = clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0);
+            const durationMs = clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), assembled.durationMs);
             const nextDocument = {
                 ...previous,
                 tracks,
@@ -1215,6 +1293,10 @@ const SHOT_EDIT_FIELDS = new Set([
     "slug",
     "camera",
     "motion",
+    "end_state",
+    "sound",
+    "graphics",
+    "production",
     "dialogue",
     "narration",
     "notes",
@@ -1267,8 +1349,16 @@ const BOARD_EDIT_FIELDS = new Set([
     "aspect_ratio",
     "entity_ids",
     "image_model",
-    "video_model"
+    "video_model",
+    "narration",
+    "music_prompt",
+    "motion_design"
 ]);
+const screenplayDirection = z.object({
+    narration: z.string().optional(),
+    music_prompt: z.string().optional(),
+    motion_design: storyboardMotionDesign.nullable().optional()
+});
 /**
  * The board-level twin of {@link assertKnownShotFields}.
  *
@@ -1350,6 +1440,45 @@ function applyShotFields(shot, args, shots = []) {
         next.camera = args["camera"];
     if (args["motion"] !== undefined)
         next.motion = String(args["motion"]);
+    for (const field of ["end_state", "sound"]) {
+        const value = args[field];
+        if (value === undefined)
+            continue;
+        if (value === null || String(value).trim() === "") {
+            delete next[field];
+        }
+        else {
+            next[field] = String(value);
+        }
+    }
+    if (args["graphics"] !== undefined) {
+        if (args["graphics"] === null) {
+            delete next.graphics;
+        }
+        else {
+            const parsed = storyboardShotGraphics.safeParse(args["graphics"]);
+            if (!parsed.success) {
+                throw new Error(`graphics must be a valid Storyboard graphics object: ${parsed.error.issues
+                    .map((issue) => issue.path.join(".") || issue.message)
+                    .join(", ")}.`);
+            }
+            next.graphics = parsed.data;
+        }
+    }
+    if (args["production"] !== undefined) {
+        if (args["production"] === null) {
+            delete next.production;
+        }
+        else {
+            const parsed = productionRequirement.safeParse(args["production"]);
+            if (!parsed.success) {
+                throw new Error(`production must be a valid production requirement: ${parsed.error.issues
+                    .map((issue) => issue.path.join(".") || issue.message)
+                    .join(", ")}.`);
+            }
+            next.production = parsed.data;
+        }
+    }
     if (args["dialogue"] !== undefined)
         next.dialogue = String(args["dialogue"]);
     if (args["narration"] !== undefined)
@@ -1763,6 +1892,13 @@ function applyBoardOp(doc, { op, args }, entities = []) {
         }
         case "set_board": {
             assertKnownBoardFields(args);
+            const direction = screenplayDirection.safeParse(args);
+            if (!direction.success) {
+                throw new Error("set_board has invalid screenplay direction: " +
+                    direction.error.issues
+                        .map((issue) => `${issue.path.join(".") || "direction"}: ${issue.message}`)
+                        .join("; "));
+            }
             if (args["brief"] !== undefined)
                 doc.brief = String(args["brief"]);
             if (args["style"] !== undefined)
@@ -1797,13 +1933,45 @@ function applyBoardOp(doc, { op, args }, entities = []) {
                 }
                 doc.videoModel = videoModel;
             }
+            if (args["narration"] !== undefined ||
+                args["music_prompt"] !== undefined ||
+                args["motion_design"] !== undefined) {
+                const needsScreenplay = args["narration"] !== undefined ||
+                    args["music_prompt"] !== undefined ||
+                    direction.data.motion_design !== null;
+                if (needsScreenplay) {
+                    doc.screenplay = doc.screenplay ?? {
+                        type: "screenplay",
+                        id: newDocId("sp"),
+                        title: "",
+                        shots: []
+                    };
+                }
+                if (doc.screenplay && direction.data.narration !== undefined) {
+                    doc.screenplay.narration = direction.data.narration;
+                }
+                if (doc.screenplay && direction.data.music_prompt !== undefined) {
+                    doc.screenplay.music_prompt = direction.data.music_prompt;
+                }
+                if (doc.screenplay && direction.data.motion_design !== undefined) {
+                    if (direction.data.motion_design === null) {
+                        delete doc.screenplay.motion_design;
+                    }
+                    else {
+                        doc.screenplay.motion_design = direction.data.motion_design;
+                    }
+                }
+            }
             return {
                 brief: doc.brief,
                 style: doc.style,
                 aspect_ratio: doc.aspectRatio,
                 entity_ids: doc.entityIds,
                 image_model: doc.imageModel,
-                video_model: doc.videoModel
+                video_model: doc.videoModel,
+                narration: doc.screenplay?.narration,
+                music_prompt: doc.screenplay?.music_prompt,
+                motion_design: doc.screenplay?.motion_design
             };
         }
     }
@@ -1830,6 +1998,50 @@ async function loadStyleEntities(run, doc, ops) {
     });
     return [...cast, ...extra];
 }
+/** Resolve source refs before any edit writes. Guest IDs stay short, stored refs stay canonical. */
+async function resolveStoryboardEditSources(run, ops) {
+    const { Asset } = await import("@nodetool-ai/models");
+    const canonical = new Map();
+    const resolve = async (id) => {
+        if (!isFullResourceId(id) && !isShortResourceId(id)) {
+            return id;
+        }
+        const cached = canonical.get(id);
+        if (cached) {
+            return cached;
+        }
+        const asset = run.context.userId ? await Asset.find(run.context.userId, id) : null;
+        if (!asset) {
+            throw new Error(`Source asset or entity ${id} is unavailable.`);
+        }
+        canonical.set(id, asset.id);
+        return asset.id;
+    };
+    const resolved = structuredClone(ops);
+    for (const { args } of resolved) {
+        const references = [args];
+        const graphics = args["graphics"];
+        if (isRecord(graphics) && Array.isArray(graphics["elements"])) {
+            references.push(...graphics["elements"].filter(isRecord));
+        }
+        const production = args["production"];
+        if (isRecord(production) && Array.isArray(production["protected_inputs"])) {
+            references.push(...production["protected_inputs"].filter(isRecord));
+        }
+        for (const reference of references) {
+            for (const field of ["asset_id", "entity_id", "location_id"]) {
+                const id = reference[field];
+                if (isString(id)) {
+                    reference[field] = await resolve(id);
+                }
+            }
+        }
+        if (Array.isArray(args["entity_ids"])) {
+            args["entity_ids"] = await Promise.all(args["entity_ids"].map(async (id) => isString(id) ? resolve(id) : id));
+        }
+    }
+    return resolved;
+}
 const editStoryboard = {
     spec: editStoryboardSpec,
     impl: async (run, params) => {
@@ -1842,12 +2054,22 @@ const editStoryboard = {
             if (isError(board))
                 return board;
             const { row, doc } = board;
+            if (params["expected_revision"] !== undefined && params["expected_revision"] !== row.revision) {
+                return { error: "Storyboard revision conflict. Refresh the board before editing." };
+            }
             // A failing op is recorded and the script continues: stopping at the
             // first error hides every problem behind it.
             const records = [];
-            const entities = await loadStyleEntities(run, doc, ops);
+            let sourceOps;
+            try {
+                sourceOps = await resolveStoryboardEditSources(run, ops);
+            }
+            catch (error) {
+                return { error: error instanceof Error ? error.message : String(error) };
+            }
+            const entities = await loadStyleEntities(run, doc, sourceOps);
             const resolvedOps = [];
-            for (const parsed of ops) {
+            for (const parsed of sourceOps) {
                 try {
                     const result = applyBoardOp(doc, parsed, entities);
                     records.push({
@@ -1888,6 +2110,9 @@ const editStoryboard = {
                     resolvedOps.push({ tool: parsed.op, input: parsed.args });
                 }
             }
+            if (doc.screenplay) {
+                doc.screenplay.shots = doc.shots;
+            }
             const saved = await Storyboard.updateFieldsIfUnchanged(row.id, row.updated_at, {
                 document: JSON.stringify(doc)
             }, 
@@ -1900,6 +2125,7 @@ const editStoryboard = {
             return {
                 storyboard_id: row.id,
                 updated_at: saved.updated_at,
+                revision: saved.revision,
                 applied: records.length - failed.length,
                 failed: failed.length,
                 ops: records,
@@ -1920,6 +2146,212 @@ const editStoryboard = {
     }
 };
 // ---------------------------------------------------------------------------
+// derive_shot_from_clip
+// ---------------------------------------------------------------------------
+const DEFAULT_DERIVED_FRAMES = 3;
+const formatSeconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+/**
+ * The headless twin of the editor's Derived shot section
+ * (`useDeriveShotFromClip`): frames → assets → a shot after the source shot
+ * → a clip following it on a new track above the source clip. The board is
+ * written before the timeline, so a timeline conflict leaves the shot on the
+ * board and says so.
+ */
+const deriveShotFromClip = {
+    spec: deriveShotFromClipSpec,
+    impl: async (run, params) => {
+        const timelineId = params["timeline_id"];
+        if (!isNonBlankString(timelineId)) {
+            return {
+                error: "timeline_id is required (use list_timelines to find one)."
+            };
+        }
+        if (!isNonBlankString(params["clip_id"])) {
+            return { error: "clip_id is required (a clip id or name)." };
+        }
+        const { MAX_DERIVED_FRAMES } = await import("@nodetool-ai/timeline");
+        const frameCount = params["frame_count"] === undefined
+            ? DEFAULT_DERIVED_FRAMES
+            : params["frame_count"];
+        if (!isNumber(frameCount) ||
+            !Number.isInteger(frameCount) ||
+            frameCount < 1 ||
+            frameCount > MAX_DERIVED_FRAMES) {
+            return {
+                error: `frame_count must be a whole number from 1 to ${MAX_DERIVED_FRAMES}.`
+            };
+        }
+        const actionParam = params["action"];
+        if (actionParam !== undefined && !isString(actionParam)) {
+            return { error: "action must be a string." };
+        }
+        const { TimelineSequence, Storyboard } = await import("@nodetool-ai/models");
+        const sequence = await TimelineSequence.findById(timelineId);
+        if (!sequence || sequence.user_id !== run.context.userId) {
+            return { error: `Timeline ${timelineId} was not found.` };
+        }
+        const { findDocumentClip, captureDerivedFrames, placeDerivedShotClip } = await import("./derive-shot.js");
+        const source = findDocumentClip(sequence.toDocument().clips, params["clip_id"]);
+        if (!source) {
+            return {
+                error: `No clip matching "${params["clip_id"]}" in timeline ${timelineId}.`
+            };
+        }
+        const boardId = source.storyboardBoardId;
+        const sourceShotId = source.storyboardShotId;
+        if (!boardId || !sourceShotId) {
+            return {
+                error: `Clip "${source.name}" is not linked to a storyboard shot.`
+            };
+        }
+        if (source.mediaType !== "video" || !source.currentAssetId) {
+            return {
+                error: "Reference frames come from a video clip with footage."
+            };
+        }
+        const board = await loadBoard(run, boardId);
+        if (isError(board))
+            return board;
+        const sourceShot = board.doc.shots.find((shot) => shot.id === sourceShotId);
+        if (!sourceShot) {
+            return {
+                error: `The shot clip "${source.name}" follows is no longer on its board.`
+            };
+        }
+        const label = sourceShot.slug ?? `Shot ${sourceShot.index + 1}`;
+        let frames;
+        try {
+            frames = await captureDerivedFrames(run.context, source, frameCount);
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+        const bindings = [];
+        for (const [index, frame] of frames.entries()) {
+            const created = await run.context.createAsset({
+                name: `${label}-frame-${index + 1}.png`,
+                contentType: "image/png",
+                content: frame.png
+            });
+            const assetId = isRecord(created) && isString(created["id"]) ? created["id"] : null;
+            if (!assetId) {
+                return { error: "A reference frame was saved without an asset id." };
+            }
+            bindings.push({
+                kind: "style",
+                asset_id: assetId,
+                label: `${label} at ${formatSeconds(frame.sourceTimeMs)}`
+            });
+        }
+        const action = actionParam?.trim() || sourceShot.action;
+        const shotArgs = {
+            after_shot_id: sourceShot.id,
+            action,
+            slug: `${label} (derived)`,
+            duration_seconds: source.durationMs / 1000,
+            duration_source: "manual",
+            render_mode: "reference",
+            production: {
+                schema_version: 1,
+                speech_mode: "none",
+                requested_take_count: 1,
+                reference_bindings: bindings
+            }
+        };
+        if (sourceShot.camera !== undefined)
+            shotArgs["camera"] = sourceShot.camera;
+        if (sourceShot.motion !== undefined)
+            shotArgs["motion"] = sourceShot.motion;
+        if (sourceShot.entity_ids !== undefined) {
+            shotArgs["entity_ids"] = sourceShot.entity_ids;
+        }
+        if (sourceShot.location_id !== undefined) {
+            shotArgs["location_id"] = sourceShot.location_id;
+        }
+        let shot;
+        for (let attempt = 0; attempt < CAS_ATTEMPTS && !shot; attempt++) {
+            const current = await loadBoard(run, boardId);
+            if (isError(current))
+                return current;
+            const { row, doc } = current;
+            let shotId;
+            try {
+                const added = applyBoardOp(doc, { op: "add_shot", args: shotArgs });
+                shotId = added.id;
+            }
+            catch (error) {
+                return {
+                    error: error instanceof Error ? error.message : String(error)
+                };
+            }
+            const index = doc.shots.findIndex((candidate) => candidate.id === shotId);
+            if (sourceShot.clip_model !== undefined) {
+                doc.shots[index] = {
+                    ...doc.shots[index],
+                    clip_model: sourceShot.clip_model
+                };
+            }
+            if (doc.screenplay) {
+                doc.screenplay.shots = doc.shots;
+            }
+            const saved = await Storyboard.updateFieldsIfUnchanged(row.id, row.updated_at, { document: JSON.stringify(doc) }, { ops: [{ tool: "add_shot", input: { ...shotArgs, id: shotId } }] });
+            if (saved)
+                shot = doc.shots[index];
+        }
+        if (!shot) {
+            return {
+                error: `Storyboard ${boardId} is being modified concurrently; nothing was saved. Retry the call.`
+            };
+        }
+        for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
+            const current = await TimelineSequence.findById(timelineId);
+            if (!current)
+                break;
+            const document = current.toDocument();
+            const latest = document.clips.find((clip) => clip.id === source.id);
+            if (!latest)
+                break;
+            const placed = placeDerivedShotClip(document, latest, {
+                boardId,
+                shotId: shot.id,
+                name: shot.slug ?? "Derived shot"
+            });
+            const saved = await TimelineSequence.updateDocumentIfUnchanged(current.id, current.updated_at, { ...document, tracks: placed.tracks, clips: placed.clips }, {
+                ops: [
+                    {
+                        tool: "ui_timeline_add_track",
+                        input: { id: placed.trackId, type: "video" }
+                    },
+                    {
+                        tool: "ui_timeline_add_media_clip",
+                        input: { id: placed.clipId, track_id: placed.trackId }
+                    }
+                ]
+            });
+            if (saved) {
+                return {
+                    storyboard_id: boardId,
+                    shot_id: shot.id,
+                    shot_index: shot.index,
+                    slug: shot.slug,
+                    reference_asset_ids: bindings.map((binding) => binding.asset_id),
+                    timeline_id: timelineId,
+                    track_id: placed.trackId,
+                    clip_id: placed.clipId,
+                    next: "Render the shot with render_storyboard_clips, targets " +
+                        `["${shot.id}"]. The clip plays the take once it lands.`
+                };
+            }
+        }
+        return {
+            error: `Shot ${shot.id} was added to storyboard ${boardId}, but timeline ` +
+                `${timelineId} changed or its source clip was removed, so no clip ` +
+                "was placed. Add a clip for the shot with edit_timeline, or remove " +
+                "the shot with edit_storyboard."
+        };
+    }
+};
+// ---------------------------------------------------------------------------
 // direct_storyboard
 // ---------------------------------------------------------------------------
 const DEFAULT_DIRECTED_SHOTS = 6;
@@ -2021,6 +2453,8 @@ const directStoryboard = {
                     ...held,
                     ...shot,
                     index,
+                    graphics: held.graphics,
+                    production: held.production,
                     keyframe: held.keyframe,
                     keyframe_versions: held.keyframe_versions,
                     clip: held.clip,
@@ -2029,7 +2463,11 @@ const directStoryboard = {
                     status: held.status
                 };
             });
-            next.screenplay = screenplay;
+            const previousMotionDesign = next.screenplay?.motion_design;
+            next.screenplay = { ...screenplay, shots: next.shots };
+            if (previousMotionDesign !== undefined) {
+                next.screenplay.motion_design = previousMotionDesign;
+            }
             next.style = screenplay.style_bible ?? next.style;
             next.aspectRatio = screenplay.aspect_ratio ?? next.aspectRatio;
             if (screenplay.genre)
@@ -2040,6 +2478,7 @@ const directStoryboard = {
             return {
                 storyboard_id: current.row.id,
                 updated_at: saved.updated_at,
+                revision: saved.revision,
                 title: screenplay.title,
                 genre: next.genre,
                 redirected: params["redirect"] === true,
@@ -2225,7 +2664,248 @@ const deleteStoryboard = {
             : { error: `Storyboard ${id} was not found, or it is not yours.` };
     }
 };
+// ---------------------------------------------------------------------------
+// get_storyboard_one_take / update_storyboard_one_take
+// ---------------------------------------------------------------------------
+/** Above this the providers that take one continuous clip refuse or truncate. */
+const ONE_TAKE_MAX_SECONDS = 30;
+/** The most reference images a one-take provider accepts. */
+const ONE_TAKE_MAX_IMAGES = 9;
+const oneTakeUpdateInput = z.object({
+    prompt: z.string().optional(),
+    duration_seconds: z.number().positive().nullable().optional(),
+    aspect_ratio: z.string().trim().min(1).nullable().optional(),
+    resolution: z.string().trim().min(1).nullable().optional(),
+    model: z
+        .object({
+        provider: z.string().trim().min(1),
+        id: z.string().trim().min(1),
+        name: z.string().optional()
+    })
+        .nullable()
+        .optional(),
+    shots: z
+        .array(z.object({
+        shot_id: z.string().trim().min(1),
+        end_state: z.string().nullable().optional(),
+        sound: z.string().nullable().optional()
+    }))
+        .optional()
+});
+/** The one-take render settings a call may set; null clears one. */
+const ONE_TAKE_SETTINGS = [
+    "duration_seconds",
+    "aspect_ratio",
+    "resolution",
+    "model"
+];
+/** The board's `videoModel` as a model ref, or null when it names none. */
+function boardVideoModel(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    const id = record["id"];
+    const provider = record["provider"];
+    if (typeof id !== "string" || id === "" || typeof provider !== "string" || provider === "") {
+        return null;
+    }
+    const model = {
+        id,
+        provider: provider
+    };
+    const name = record["name"];
+    if (typeof name === "string") {
+        model.name = name;
+    }
+    return model;
+}
+/** The shape both one-take capabilities return. */
+function oneTakeSummary(row, doc) {
+    const compiled = compileOneTake({
+        shots: doc.shots,
+        oneTake: doc.one_take
+    });
+    const direction = doc.one_take;
+    const settings = {
+        duration_seconds: direction?.duration_seconds ?? null,
+        aspect_ratio: direction?.aspect_ratio ?? null,
+        resolution: direction?.resolution ?? null,
+        model: direction?.model ?? null
+    };
+    const effective = {
+        duration_seconds: compiled.duration_seconds,
+        shot_total_seconds: compiled.shot_total_seconds,
+        aspect_ratio: settings.aspect_ratio ?? doc.aspectRatio ?? null,
+        resolution: settings.resolution,
+        model: settings.model ?? boardVideoModel(doc.videoModel)
+    };
+    const warnings = [];
+    if (!effective.model) {
+        warnings.push("No video model is chosen: set `model` here or the board's video model.");
+    }
+    if (compiled.duration_seconds > ONE_TAKE_MAX_SECONDS) {
+        warnings.push(`The take runs ${compiled.duration_seconds}s, over the ${ONE_TAKE_MAX_SECONDS}s one-take limit.`);
+    }
+    if (compiled.references.length > ONE_TAKE_MAX_IMAGES) {
+        warnings.push(`${compiled.references.length} reference images; one-take models accept at most ${ONE_TAKE_MAX_IMAGES}.`);
+    }
+    const byId = new Map(doc.shots.map((shot) => [shot.id, shot]));
+    const withoutStill = compiled.steps
+        .map((step) => byId.get(step.shot_id))
+        .filter((shot) => !!shot && !shot.keyframe?.asset_id);
+    if (withoutStill.length > 0) {
+        warnings.push(`Shots without a still send no image: ${withoutStill
+            .map((shot) => shot.slug?.trim() || shot.id)
+            .join(", ")}.`);
+    }
+    return {
+        storyboard_id: row.id,
+        revision: row.revision,
+        updated_at: row.updated_at,
+        stored: doc.one_take !== undefined,
+        prompt: doc.one_take?.prompt ?? "",
+        compiled: compiled.compiled,
+        full_prompt: compiled.prompt,
+        references: compiled.references.map((reference, index) => ({
+            image_number: index + 1,
+            marker: `[Image ${index + 1}]`,
+            ...reference
+        })),
+        steps: compiled.steps.map((step) => {
+            const shot = byId.get(step.shot_id);
+            return {
+                shot_id: step.shot_id,
+                index: shot?.index,
+                slug: shot?.slug,
+                start_seconds: step.start_seconds,
+                end_seconds: step.end_seconds,
+                end_state: shot?.end_state ?? null,
+                sound: shot?.sound ?? null
+            };
+        }),
+        duration_seconds: compiled.duration_seconds,
+        settings,
+        effective,
+        warnings
+    };
+}
+const getStoryboardOneTake = {
+    spec: getStoryboardOneTakeSpec,
+    impl: async (run, params) => {
+        const board = await loadBoard(run, params["storyboard_id"]);
+        if (isError(board))
+            return board;
+        return oneTakeSummary(board.row, board.doc);
+    }
+};
+const updateStoryboardOneTake = {
+    spec: updateStoryboardOneTakeSpec,
+    impl: async (run, params) => {
+        const parsed = oneTakeUpdateInput.safeParse({
+            prompt: params["prompt"],
+            duration_seconds: params["duration_seconds"],
+            aspect_ratio: params["aspect_ratio"],
+            resolution: params["resolution"],
+            model: params["model"],
+            shots: params["shots"]
+        });
+        if (!parsed.success) {
+            return {
+                error: parsed.error.issues
+                    .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+                    .join("; ")
+            };
+        }
+        const { prompt, shots: shotPatches } = parsed.data;
+        const settingsGiven = ONE_TAKE_SETTINGS.filter((key) => parsed.data[key] !== undefined);
+        if (prompt === undefined && settingsGiven.length === 0 && !shotPatches) {
+            return {
+                error: "Pass prompt, duration_seconds, aspect_ratio, resolution, model or shots to update."
+            };
+        }
+        const { Storyboard } = await import("@nodetool-ai/models");
+        for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
+            const board = await loadBoard(run, params["storyboard_id"]);
+            if (isError(board))
+                return board;
+            const { row } = board;
+            const doc = board.doc;
+            if (params["expected_revision"] !== undefined &&
+                params["expected_revision"] !== row.revision) {
+                return {
+                    error: "Storyboard revision conflict. Refresh the board before editing."
+                };
+            }
+            const ops = [];
+            if (prompt !== undefined || settingsGiven.length > 0) {
+                const next = {
+                    ...doc.one_take,
+                    prompt: prompt ?? doc.one_take?.prompt ?? ""
+                };
+                const { duration_seconds, aspect_ratio, resolution, model } = parsed.data;
+                if (duration_seconds !== undefined)
+                    next.duration_seconds = duration_seconds;
+                if (aspect_ratio !== undefined)
+                    next.aspect_ratio = aspect_ratio;
+                if (resolution !== undefined)
+                    next.resolution = resolution;
+                if (model !== undefined) {
+                    next.model = model && {
+                        ...model,
+                        provider: model.provider
+                    };
+                }
+                // A null clears the setting: store it absent, not null.
+                for (const key of ONE_TAKE_SETTINGS) {
+                    if (next[key] === null)
+                        delete next[key];
+                }
+                doc.one_take = next;
+                // Field-level, the way set_board is: an open editor takes the
+                // direction whole.
+                ops.push({ tool: "set_board", input: { one_take: doc.one_take } });
+            }
+            for (const patch of shotPatches ?? []) {
+                const shot = findShot(doc.shots, patch.shot_id);
+                if (!shot) {
+                    return {
+                        error: `No shot matches "${patch.shot_id}". Call get_storyboard for shot ids.`
+                    };
+                }
+                const next = { ...shot };
+                for (const field of ["end_state", "sound"]) {
+                    const value = patch[field];
+                    if (value === undefined)
+                        continue;
+                    if (value === null || value.trim() === "") {
+                        delete next[field];
+                    }
+                    else {
+                        next[field] = value;
+                    }
+                }
+                doc.shots = doc.shots.map((s) => (s.id === shot.id ? next : s));
+                ops.push({
+                    tool: "update_shot",
+                    input: { id: shot.id, target: shot.id }
+                });
+            }
+            if (doc.screenplay)
+                doc.screenplay.shots = doc.shots;
+            const saved = await Storyboard.updateFieldsIfUnchanged(row.id, row.updated_at, { document: JSON.stringify(doc) }, { ops });
+            if (!saved)
+                continue;
+            return oneTakeSummary(saved, doc);
+        }
+        return {
+            error: `Storyboard ${String(params["storyboard_id"])} is being modified concurrently; nothing was saved. Retry the call.`
+        };
+    }
+};
 export const STORYBOARD_CAPABILITIES = [
+    finishStoryboard,
+    layoutStoryboard,
+    previewStoryboardDesign,
     listStoryboards,
     createStoryboard,
     getStoryboard,
@@ -2233,14 +2913,17 @@ export const STORYBOARD_CAPABILITIES = [
     renderStoryboardClips,
     reviseStoryboardClip,
     assembleStoryboardTimeline,
+    deriveShotFromClip,
     editStoryboard,
     directStoryboard,
     extractScriptFromStoryboard,
-    deleteStoryboard
+    deleteStoryboard,
+    getStoryboardOneTake,
+    updateStoryboardOneTake
 ];
 export const module = {
     module: "storyboards",
     exports: STORYBOARD_CAPABILITIES
 };
-export { listStoryboards, createStoryboard, getStoryboard, renderStoryboardStills, renderStoryboardClips, reviseStoryboardClip, assembleStoryboardTimeline, editStoryboard, directStoryboard, extractScriptFromStoryboard, deleteStoryboard };
+export { finishStoryboard, layoutStoryboard, previewStoryboardDesign, listStoryboards, createStoryboard, getStoryboard, renderStoryboardStills, renderStoryboardClips, reviseStoryboardClip, assembleStoryboardTimeline, deriveShotFromClip, editStoryboard, directStoryboard, extractScriptFromStoryboard, deleteStoryboard, getStoryboardOneTake, updateStoryboardOneTake };
 //# sourceMappingURL=storyboards.js.map