@nodetool-ai/agents 0.8.1 → 0.8.2

package/dist/capabilities/timelines.js

@@ -17,8 +17,16 @@
  *
  * Design: docs/tool-class-retirement-design.md § "Migration".
  */
-import { listTimelinesSpec, createTimelineSpec, getTimelineSpec, listTimelineVersionsSpec, getTimelineVersionSpec, createTimelineVersionSpec, restoreTimelineVersionSpec, deleteTimelineVersionSpec, editTimelineSpec, validateTimelineSpec, setTimelineDocumentSpec, previewTimelineFrameSpec, compareTimelineFramesSpec, renderTimelineSpec, bakeAudioAnimationSpec, isolateSubjectSpec, ISOLATE_SUBJECT_MODELS, ISOLATE_SUBJECT_RESOLUTIONS, DEFAULT_ISOLATE_SUBJECT_MODEL, DEFAULT_ISOLATE_SUBJECT_RESOLUTION, DEFAULT_BAKE_ATTACK_MS, DEFAULT_BAKE_RELEASE_MS, DEFAULT_BAKE_TOLERANCE, DEFAULT_BAKE_MAX_POINTS, DEFAULT_BAKE_MAX_SECONDS, MAX_BAKE_POINTS, DEFAULT_RENDER_TIMEOUT_MS, MAX_RENDER_TIMEOUT_MS, DEFAULT_PREVIEW_COUNT, DEFAULT_COMPARE_WIDTH, MAX_PREVIEW_TIMES, MAX_PREVIEW_RANGE_COUNT, DEFAULT_VERSION_LIMIT, MAX_VERSION_LIMIT, trackObjectSpec, TRACK_OBJECT_DIRECTIONS, deleteTimelineSpec } from "./timelines.specs.js";
-import { AUDIO_BAKED_ANIMATION_KIND, normalizeAuthoredDocument } from "@nodetool-ai/timeline";
+import { z } from "zod";
+import { applyTimelineTrackOp } from "@nodetool-ai/timeline/ops";
+import { STAGGER_UNITS, ANIMATED_PROPERTIES, DEFAULT_BEAT_TOLERANCE_MS } from "@nodetool-ai/timeline";
+import { buildTimelineToolContracts } from "@nodetool-ai/protocol/api-schemas/timeline-tool-contracts.js";
+import { resolveMoveTrackArgs, resolveDeleteTrackArgs } from "@nodetool-ai/protocol/api-schemas/timeline-tool-params.js";
+import { parseWithTypeCoercion } from "@nodetool-ai/runtime";
+import { listTimelinesSpec, createTimelineSpec, getTimelineSpec, listTimelineVersionsSpec, getTimelineVersionSpec, createTimelineVersionSpec, restoreTimelineVersionSpec, deleteTimelineVersionSpec, editTimelineSpec, validateTimelineSpec, setTimelineDocumentSpec, previewTimelineFrameSpec, compareTimelineFramesSpec, renderTimelineSpec, bakeAudioAnimationSpec, isolateSubjectSpec, ISOLATE_SUBJECT_MODELS, ISOLATE_SUBJECT_RESOLUTIONS, DEFAULT_ISOLATE_SUBJECT_MODEL, DEFAULT_ISOLATE_SUBJECT_RESOLUTION, DEFAULT_BAKE_ATTACK_MS, DEFAULT_BAKE_RELEASE_MS, DEFAULT_BAKE_TOLERANCE, DEFAULT_BAKE_MAX_POINTS, DEFAULT_BAKE_MAX_SECONDS, MAX_BAKE_POINTS, DEFAULT_RENDER_TIMEOUT_MS, MAX_RENDER_TIMEOUT_MS, DEFAULT_PREVIEW_COUNT, DEFAULT_COMPARE_WIDTH, MAX_PREVIEW_TIMES, MAX_PREVIEW_RANGE_COUNT, DEFAULT_VERSION_LIMIT, MAX_VERSION_LIMIT, trackObjectSpec, TRACK_OBJECT_DIRECTIONS, getTimelineCodeSpec, setTimelineCodeSpec, editTimelineCodeSpec, rebakeTimelineCodeSpec, detachTimelineCodeSpec, deleteTimelineSpec } from "./timelines.specs.js";
+import { AUDIO_BAKED_ANIMATION_KIND, normalizeAuthoredDocument, hashSceneSubtree, mergeTimelineSource } from "@nodetool-ai/timeline";
+import { bakeTimelineCode, bakedDocumentMatchesSaved } from "../timeline-code-bake.js";
+import { applyJsScriptEditOps, parseJsScriptEditOps } from "./js-scripts.js";
 import { clipSourceWindowMs } from "./timeline-audio-bake.js";
 import { TIMELINE_NATIVE_MEDIA_CAPABILITIES } from "./timeline-native-media.js";
 import { isFiniteNumber, isRecord, isString } from "../utils/type-guards.js";
@@ -193,7 +201,7 @@ const getTimeline = {
         const seq = await loadTimeline(run, params["timeline_id"]);
         if (isError(seq))
             return seq;
-        return { timeline: seq.toTimelineSequence() };
+        return { timeline: seq.toTimelineSequence(), revision: seq.revision };
     }
 };
 const listTimelineVersions = {
@@ -367,20 +375,9 @@ const CAS_ATTEMPTS = 2;
 /** Operations one call may apply, so a runaway script cannot rewrite a cut. */
 const MAX_OPS = 60;
 const TOOL_PREFIX = "ui_timeline_";
-/**
- * Tools the browser bridge exposes that this capability cannot run safely.
- *
- * `edit_timeline` persists document mutations but has no durable media-edit
- * generation adapter or callback path. Exposing generative editing here would
- * require it to invent an asset id, so it remains browser-only until a server
- * generation runner can create and attach the candidate take. `apply_take`
- * stays available because it only promotes an existing candidate.
- */
-const EXCLUDED_OPS = new Set([
-    `${TOOL_PREFIX}get_clip_frames`,
-    `${TOOL_PREFIX}generate_clip`,
-    `${TOOL_PREFIX}generatively_edit_clip`
-]);
+/** Browser generation without a real provider adapter remains excluded. */
+const EXCLUDED_OPS = new Set([`${TOOL_PREFIX}generate_clip`]);
+const READ_ONLY_OPS = new Set([`${TOOL_PREFIX}get_clip_frames`]);
 /** `add_track`, `ui_add_track`, and `ui_timeline_add_track` all name one tool. */
 function normalizeOpName(name) {
     const trimmed = name.trim();
@@ -392,7 +389,7 @@ function normalizeOpName(name) {
     return `${TOOL_PREFIX}${bare}`;
 }
 /** An op is `{op, ...args}` — the arguments sit alongside the verb. */
-function parseOps(raw) {
+export function parseOps(raw) {
     if (!Array.isArray(raw) || raw.length === 0) {
         return {
             error: 'ops must be a non-empty array, e.g. [{"op": "add_track", "type": "audio"}].'
@@ -506,34 +503,11 @@ async function bakeTimelineAnimation(run, request) {
     return result;
 }
 /**
- * Run `ops` against a bridge seeded from `document`.
- *
- * A failing op is recorded and the script continues: stopping at the first
- * error hides every problem behind it, and the caller wants the whole picture.
+ * The bridge hooks that write outside the document: a Blender render of a 3D
+ * clip, and the new sequence `retarget_format` creates.
  */
-async function applyOps(run, sequence, document, ops) {
-    const { createTimelineToolBridge } = await import("../evals/surfaces/timeline.js");
-    const bridge = createTimelineToolBridge({
-        sequenceId: sequence.id,
-        sequenceName: sequence.name,
-        projectId: sequence.project_id,
-        sequence: {
-            fps: sequence.fps,
-            width: sequence.width,
-            height: sequence.height,
-            tracks: document.tracks,
-            clips: document.clips,
-            markers: document.markers,
-            transcript: document.transcript,
-            scriptEnabled: document.scriptEnabled,
-            templateId: document.templateId,
-            tempo: document.tempo,
-            camera2d: document.camera2d,
-            setup: document.setup,
-            mediaTracks: document.mediaTracks
-        },
-        resolveAsset: (ref) => resolveTimelineAsset(run, ref),
-        bakeAnimation: (request) => bakeTimelineAnimation(run, request),
+function writingHooks(run, sequence) {
+    return {
         bakeModel3DClip: async (request) => {
             const { bakeModel3DClipOnServer } = await import("./timeline-bake.js");
             return bakeModel3DClipOnServer(run.context, request);
@@ -576,7 +550,156 @@ async function applyOps(run, sequence, document, ops) {
                 document: JSON.stringify(derivedDocument)
             });
             return { sequenceId: created.id, name };
+        }
+    };
+}
+/** Track-only batches need no simulated editor or external hooks. */
+function applyTrackOps(sequence, document, ops) {
+    const contracts = buildTimelineToolContracts({
+        staggerUnits: STAGGER_UNITS,
+        animatedProperties: ANIMATED_PROPERTIES,
+        beatToleranceMs: DEFAULT_BEAT_TOLERANCE_MS
+    });
+    let state = {
+        fps: sequence.fps,
+        width: sequence.width,
+        height: sequence.height,
+        tracks: document.tracks,
+        clips: document.clips,
+        markers: document.markers,
+        mediaTracks: document.mediaTracks,
+        tempo: document.tempo,
+        playheadMs: 0,
+        selectedClipIds: []
+    };
+    const usedIds = new Set([
+        ...[
+            ...document.tracks,
+            ...document.clips,
+            ...document.markers,
+            ...(document.mediaTracks ?? [])
+        ].map((unit) => unit.id),
+        ...document.clips.flatMap((clip) => (clip.animations ?? []).map((animation) => animation.id))
+    ]);
+    let nextId = 0;
+    const newId = () => {
+        let id;
+        do {
+            id = `track_${++nextId}`;
+        } while (usedIds.has(id));
+        usedIds.add(id);
+        return id;
+    };
+    const records = [];
+    for (const entry of ops) {
+        try {
+            let op;
+            if (entry.op === "ui_timeline_add_track") {
+                const args = parseWithTypeCoercion(z.object(contracts.ui_timeline_add_track.shape), entry.input);
+                op = { op: "add_track", ...args };
+            }
+            else if (entry.op === "ui_timeline_move_track") {
+                const args = parseWithTypeCoercion(z.object(contracts.ui_timeline_move_track.shape), entry.input);
+                op = { op: "move_track", ...resolveMoveTrackArgs(args) };
+            }
+            else {
+                const args = parseWithTypeCoercion(z.object(contracts.ui_timeline_delete_track.shape), entry.input);
+                op = { op: "delete_track", ...resolveDeleteTrackArgs(args) };
+            }
+            const outcome = applyTimelineTrackOp(state, op, { newId });
+            if (outcome.error)
+                throw new Error(outcome.error);
+            state = outcome.state;
+            records.push({ op: entry.op, ok: true, result: outcome.result });
+        }
+        catch (error) {
+            records.push({
+                op: entry.op,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return {
+        records,
+        state: {
+            fps: state.fps,
+            width: state.width,
+            height: state.height,
+            durationMs: state.clips.reduce((end, clip) => Math.max(end, clip.startMs + clip.durationMs), 0),
+            playheadMs: state.playheadMs,
+            tracks: state.tracks.map(({ id, name, type, index }) => ({
+                id,
+                name,
+                type,
+                index
+            })),
+            clips: state.clips.map((clip) => ({
+                id: clip.id,
+                name: clip.name,
+                trackId: clip.trackId,
+                mediaType: clip.mediaType,
+                startMs: clip.startMs,
+                durationMs: clip.durationMs,
+                prompt: clip.prompt,
+                animations: (clip.animations ?? []).map(({ role, preset }) => ({
+                    role,
+                    preset
+                }))
+            })),
+            documentTracks: state.tracks,
+            documentClips: state.clips,
+            markers: state.markers,
+            mediaTracks: state.mediaTracks ?? [],
+            derivedSequences: [],
+            tempo: state.tempo,
+            camera2d: document.camera2d ?? null,
+            setup: document.setup ?? null,
+            transitionCandidates: [],
+            appliedTransitionCandidates: [],
+            toolLog: ops.map((entry) => entry.op),
+            previewTimesMs: [],
+            previewedLayerKinds: []
+        }
+    };
+}
+/**
+ * Run `ops` against a bridge seeded from `document`.
+ *
+ * A failing op is recorded and the script continues: stopping at the first
+ * error hides every problem behind it, and the caller wants the whole picture.
+ *
+ * `hermetic` leaves out the hooks that write outside the document: the 3D
+ * render and the new sequence a retarget creates. A code bake sets it. The
+ * bridge then uses its in-memory fallbacks for those ops.
+ */
+export async function applyOps(run, sequence, document, ops, options = {}) {
+    if (ops.every(({ op }) => op === "ui_timeline_add_track" || op === "ui_timeline_move_track" || op === "ui_timeline_delete_track")) {
+        return applyTrackOps(sequence, document, ops);
+    }
+    const { createTimelineToolBridge } = await import("./timeline-bridge.js");
+    let operationIndex = 0;
+    const init = {
+        sequenceId: sequence.id,
+        sequenceName: sequence.name,
+        projectId: sequence.project_id,
+        sequence: {
+            fps: sequence.fps,
+            width: sequence.width,
+            height: sequence.height,
+            tracks: document.tracks,
+            clips: document.clips,
+            markers: document.markers,
+            transcript: document.transcript,
+            scriptEnabled: document.scriptEnabled,
+            templateId: document.templateId,
+            tempo: document.tempo,
+            camera2d: document.camera2d,
+            setup: document.setup,
+            mediaTracks: document.mediaTracks
         },
+        resolveAsset: (ref) => resolveTimelineAsset(run, ref),
+        bakeAnimation: (request) => bakeTimelineAnimation(run, request),
         loadComposition: {
             get: async (id) => {
                 const { loadComposition } = await import("./compositions.js");
@@ -592,12 +715,31 @@ async function applyOps(run, sequence, document, ops) {
                 ];
             }
         }
-    });
+    };
+    if (!options.hermetic) {
+        Object.assign(init, writingHooks(run, sequence));
+        const { timelineMediaEditGenerator } = await import("./timeline-media-edit.js");
+        const generate = options.generateMediaEdit ?? timelineMediaEditGenerator(run);
+        init.generateMediaEdit = (request) => generate(request, operationIndex);
+        init.getClipFrames = async (clip, frameOptions) => {
+            const current = bridge.finalState();
+            const { inspectTimelineClipFrames } = await import("./timeline-clip-frames.js");
+            return inspectTimelineClipFrames(run.context, { ...sequence.toDocument(),
+                tracks: current.documentTracks, clips: current.documentClips, markers: current.markers,
+                mediaTracks: current.mediaTracks, tempo: current.tempo, camera2d: current.camera2d,
+                id: sequence.id, projectId: sequence.project_id ?? "default", name: sequence.name,
+                fps: sequence.fps, width: sequence.width, height: sequence.height,
+                durationMs: sequence.duration_ms, createdAt: sequence.created_at, updatedAt: sequence.updated_at
+            }, clip, frameOptions);
+        };
+    }
+    const bridge = createTimelineToolBridge(init);
     const byName = new Map(bridge.tools
-        .filter((tool) => !EXCLUDED_OPS.has(tool.name))
+        .filter((tool) => !EXCLUDED_OPS.has(tool.name) && !(options.hermetic && (tool.name === `${TOOL_PREFIX}generatively_edit_clip` || READ_ONLY_OPS.has(tool.name))))
         .map((tool) => [tool.name, tool]));
     const records = [];
-    for (const { op, input } of ops) {
+    for (const [index, { op, input }] of ops.entries()) {
+        operationIndex = index;
         const tool = byName.get(op);
         if (!tool) {
             const known = [...byName.keys()]
@@ -741,7 +883,9 @@ const editTimeline = {
                     "the returned timeline id."
             };
         }
-        const { TimelineSequence } = await import("@nodetool-ai/models");
+        const { TimelineSequence, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        const { timelineMediaEditGenerator } = await import("./timeline-media-edit.js");
+        const generateMediaEdit = timelineMediaEditGenerator(run);
         for (let attempt = 0; attempt < CAS_ATTEMPTS; attempt++) {
             const sequence = await TimelineSequence.findById(timelineId);
             // A sequence owned by someone else reads as missing — the rule the tRPC
@@ -750,7 +894,7 @@ const editTimeline = {
                 return { error: `Timeline ${timelineId} was not found.` };
             }
             const document = sequence.toDocument();
-            const { records, state } = await applyOps(run, sequence, document, ops);
+            const { records, state } = await applyOps(run, sequence, document, ops, { generateMediaEdit });
             // The transcript rides along untouched — no timeline operation edits it,
             // so the stored copy stays authoritative. Markers come back from the
             // bridge, which seeded them and which the marker ops write to.
@@ -784,12 +928,12 @@ const editTimeline = {
             // hand an open editor a merge with nothing in it.
             const appliedOps = ops
                 .map((parsed, index) => ({ parsed, index }))
-                .filter(({ index }) => records[index]?.ok);
+                .filter(({ parsed, index }) => records[index]?.ok && !READ_ONLY_OPS.has(parsed.op));
             if (appliedOps.length === 0) {
                 return {
                     timeline_id: timelineId,
                     updated_at: sequence.updated_at,
-                    applied: 0,
+                    applied: records.filter((record) => record.ok).length,
                     failed: failed.length,
                     ops: records,
                     tracks: state.tracks,
@@ -826,15 +970,23 @@ const editTimeline = {
                     }))
                 };
             }
+            const undo = appliedOps.some(({ parsed }) => parsed.op === `${TOOL_PREFIX}apply_take`)
+                ? await TimelineSequenceVersion.snapshot(sequence, { saveType: "manual", name: "Before applying AI edit take" })
+                : undefined;
             const saved = await TimelineSequence.updateDocumentIfUnchanged(sequence.id, sequence.updated_at, next, {
                 ops: appliedOps.map(({ parsed, index }) => ({
                     tool: parsed.op,
                     input: resolveTimelineOpInput(parsed.input, document, state, records[index]?.result)
                 }))
+            }).catch(async (error) => {
+                await undo?.delete();
+                throw error;
             });
-            if (!saved)
+            if (!saved) {
+                await undo?.delete();
                 continue;
-            return {
+            }
+            const response = {
                 timeline_id: timelineId,
                 updated_at: saved.updated_at,
                 applied: records.length - failed.length,
@@ -851,6 +1003,10 @@ const editTimeline = {
                     animations: clip.animations
                 }))
             };
+            if (undo) {
+                Object.assign(response, { undo_version: undo.version });
+            }
+            return response;
         }
         return {
             error: `Timeline ${timelineId} is being modified concurrently; nothing was saved. Retry the call.`
@@ -1333,6 +1489,7 @@ const previewTimelineFrame = {
                 mime: "image/png"
             });
             sheet = {
+                complete: result.complete,
                 columns: tiled.columns,
                 rows: tiled.rows,
                 cells: tiled.cells,
@@ -1346,12 +1503,15 @@ const previewTimelineFrame = {
         const frames = [];
         for (const frame of result.frames) {
             const entry = {
+                complete: frame.complete,
                 time_ms: frame.time_ms,
                 width: frame.width,
                 height: frame.height,
                 layers: frame.layers,
+                failures: frame.failures,
                 dropped: frame.dropped,
-                degraded: frame.degraded
+                degraded: frame.degraded,
+                degradations: frame.degraded
             };
             if (!wantSheet) {
                 const saved = await persistOutput(run.context, frame.png, {
@@ -1363,6 +1523,8 @@ const previewTimelineFrame = {
             frames.push(entry);
         }
         return {
+            complete: result.complete,
+            visual_output_verified: false,
             timeline_id: isString(timelineId) ? timelineId : undefined,
             name,
             fps: meta.fps,
@@ -1372,12 +1534,15 @@ const previewTimelineFrame = {
             frames,
             sheet,
             effects_not_applied: result.effectsNotApplied,
-            hint: wantSheet
+            fonts_unavailable: result.fontsUnavailable,
+            hint: (!result.complete
+                ? "Incomplete preview: requested content was skipped or approximated. Inspect failures, dropped, degradations, skipped layers, effects_not_applied and fonts_unavailable. This image cannot verify the complete composition. "
+                : "") + (wantSheet
                 ? "Call view_image with the sheet's asset_id to see every frame at " +
                     "once; the cells run left to right, labelled with their timecode. " +
                     "Each frame's layers are listed top of the stack first."
                 : "Call view_image with a frame's asset_id to see it. The layers are " +
-                    "listed top of the stack first — the first one covers the rest."
+                    "listed top of the stack first — the first one covers the rest.")
         };
     }
 };
@@ -1510,10 +1675,15 @@ const compareTimelineFrames = {
         const frames = [];
         const cells = [];
         for (let i = 0; i < times.length; i++) {
-            const difference = Number((await frameDifference(left.frames[i].png, right.frames[i].png)).toFixed(4));
-            frames.push({ time_ms: times[i], difference });
+            const complete = left.frames[i].complete && right.frames[i].complete;
+            const difference = complete ? Number((await frameDifference(left.frames[i].png, right.frames[i].png)).toFixed(4)) : null;
+            frames.push({
+                time_ms: times[i], complete, difference,
+                a: { failures: left.frames[i].failures, dropped: left.frames[i].dropped, degradations: left.frames[i].degraded, skipped: left.frames[i].layers.filter((layer) => layer.skipped) },
+                b: { failures: right.frames[i].failures, dropped: right.frames[i].dropped, degradations: right.frames[i].degraded, skipped: right.frames[i].layers.filter((layer) => layer.skipped) }
+            });
             cells.push({
-                label: `${times[i]}ms  ${difference.toFixed(3)}`,
+                label: `${times[i]}ms  ${difference === null ? "incomplete" : difference.toFixed(3)}`,
                 png: await sideBySide(left.frames[i].png, right.frames[i].png)
             });
         }
@@ -1522,16 +1692,20 @@ const compareTimelineFrames = {
             namePrefix: "timeline-compare",
             mime: "image/png"
         });
-        const differences = frames.map((frame) => frame.difference);
-        const changed = frames.filter((frame) => frame.difference > 0);
+        const complete = left.complete && right.complete;
+        const differences = frames.flatMap((frame) => frame.difference === null ? [] : [frame.difference]);
+        const changed = frames.filter((frame) => frame.difference !== null && frame.difference > 0);
         return {
+            complete,
+            visual_output_verified: false,
             a: a.source,
             b: b.source,
             frames,
-            changed_times_ms: changed.map((frame) => frame.time_ms),
-            max_difference: Math.max(...differences),
-            mean_difference: Number((differences.reduce((sum, d) => sum + d, 0) / differences.length).toFixed(4)),
+            changed_times_ms: complete ? changed.map((frame) => frame.time_ms) : null,
+            max_difference: complete ? Math.max(...differences) : null,
+            mean_difference: complete ? Number((differences.reduce((sum, d) => sum + d, 0) / differences.length).toFixed(4)) : null,
             sheet: {
+                complete,
                 columns: tiled.columns,
                 rows: tiled.rows,
                 cells: tiled.cells,
@@ -1542,7 +1716,11 @@ const compareTimelineFrames = {
             effects_not_applied: [
                 ...new Set([...left.effectsNotApplied, ...right.effectsNotApplied])
             ].sort(),
-            hint: "difference is the mean absolute RGB difference, 0 (identical) to 1. " +
+            fonts_unavailable: [
+                ...new Set([...left.fontsUnavailable, ...right.fontsUnavailable])
+            ].sort(),
+            hint: (!complete ? "Incomplete previews cannot establish visual equivalence. Difference scores are null for incomplete pairs and aggregate metrics are unavailable. " : "") +
+                "difference is the mean absolute RGB difference, 0 (identical) to 1. " +
                 "Each cell of the sheet is a pair: `a` on the left, `b` on the right, " +
                 "labelled with its timecode and score."
         };
@@ -2283,6 +2461,322 @@ const trackObject = {
         return result;
     }
 };
+/**
+ * The report shape `get_timeline_code`, `set_timeline_code`, `edit_timeline_code`
+ * and `rebake_timeline_code` all answer for `scenes`: `edited` means "kept
+ * as-is rather than reflecting the code" — either the code has never been
+ * baked into a current merge (`get`), or this call's own merge kept it as a
+ * conflict (`set`/`edit`/`rebake`).
+ */
+function sceneReport(scenes, editedNames) {
+    return Object.entries(scenes).map(([name, recorded]) => ({
+        name,
+        group_id: recorded.groupId,
+        edited: editedNames.has(name)
+    }));
+}
+/** `force` is a boolean or an array of scene names; anything else is refused. */
+function normalizeForceOption(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === true)
+        return true;
+    if (value === false)
+        return undefined;
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value;
+    }
+    return { error: "force must be a boolean or an array of scene names." };
+}
+/**
+ * Validate, snapshot, and CAS-write a document the way `set_timeline_document`
+ * does (see its own docstring for why each step is there): validate first so
+ * a document that would not render never reaches the database, snapshot the
+ * state being replaced so the write is undoable, then a CAS write so a
+ * concurrent edit is reported rather than clobbered.
+ */
+export async function writeTimelineCodeDocument(sequence, document, snapshotName) {
+    const { validateTimelineSequence } = await import("@nodetool-ai/execution/timeline-debug");
+    const before = validateTimelineSequence(document, { fps: sequence.fps, width: sequence.width, height: sequence.height });
+    const errors = before.errors.map((issue) => issue.message);
+    const warnings = before.warnings.map((issue) => issue.message);
+    if (!before.ok) {
+        return {
+            written: false,
+            error: `The baked document has ${before.errors.length} error${before.errors.length === 1 ? "" : "s"} and was not written to timeline ${sequence.id}.`,
+            errors,
+            warnings
+        };
+    }
+    const { TimelineSequence: TimelineSequenceModel, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+    await TimelineSequenceVersion.snapshot(sequence, {
+        saveType: "manual",
+        name: snapshotName
+    });
+    const saved = await TimelineSequenceModel.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, {
+        document: JSON.stringify(document),
+        duration_ms: documentDurationMs(document)
+    });
+    if (!saved) {
+        return {
+            written: false,
+            error: `Timeline ${sequence.id} was modified concurrently; nothing was written. Read it again and try again.`,
+            errors,
+            warnings
+        };
+    }
+    return { written: true, timeline_id: saved.id, errors, warnings };
+}
+/**
+ * Bake `code`, merge the result into `sequence`'s current document (see
+ * `mergeTimelineSource` in `@nodetool-ai/timeline` for the merge rule), and
+ * write it through the same path `set_timeline_document` uses. Shared by
+ * `set_timeline_code`, `edit_timeline_code` and `rebake_timeline_code` — they
+ * differ only in where `code` comes from.
+ */
+async function bakeAndMergeTimelineCode(run, sequence, code, force) {
+    const current = sequence.toDocument();
+    const baked = await bakeTimelineCode(run.context, code);
+    if (!baked.ok || !baked.document) {
+        return {
+            timeline_id: sequence.id,
+            errors: [baked.error ?? "The code failed to build a document."],
+            warnings: [],
+            conflicts: [],
+            scenes: []
+        };
+    }
+    const previousScenes = current.source?.scenes ?? {};
+    const merged = mergeTimelineSource(current, baked.document, previousScenes, force !== undefined ? { force } : {});
+    const mergedWithSource = {
+        ...merged.document,
+        source: {
+            lang: "js",
+            code,
+            bakedAt: new Date().toISOString(),
+            scenes: merged.scenes
+        }
+    };
+    const editedNames = new Set(merged.conflicts.map((c) => c.scene));
+    const scenes = sceneReport(merged.scenes, editedNames);
+    const write = await writeTimelineCodeDocument(sequence, mergedWithSource, "Before writing timeline code");
+    if (!write.written) {
+        return {
+            timeline_id: sequence.id,
+            errors: [write.error, ...write.errors],
+            warnings: write.warnings,
+            conflicts: merged.conflicts,
+            scenes
+        };
+    }
+    return {
+        timeline_id: write.timeline_id,
+        errors: write.errors,
+        warnings: write.warnings,
+        conflicts: merged.conflicts,
+        scenes
+    };
+}
+/**
+ * Attach `code` as `sequence`'s authoring source only when a hermetic bake
+ * of it gives exactly the document that is saved now. This is
+ * `set_timeline_code` with `require_match: true`, which `v.save()` calls
+ * with the retained program it printed (docs/timeline-code-capture.md).
+ *
+ * A mismatch writes nothing and returns a warning. The document stays as it
+ * was saved, only without code, because code that does not rebuild it would
+ * make a later rebake diverge from what the timeline shows.
+ */
+async function attachMatchingTimelineCode(run, sequence, code) {
+    const current = sequence.toDocument();
+    const notEmbedded = (warning) => ({
+        timeline_id: sequence.id,
+        embedded: false,
+        errors: [],
+        warnings: [warning],
+        conflicts: [],
+        scenes: []
+    });
+    const baked = await bakeTimelineCode(run.context, code);
+    if (!baked.ok || !baked.document) {
+        return notEmbedded(`Code not embedded: the retained program failed to rebake (${baked.error ?? "unknown error"}).`);
+    }
+    if (!bakedDocumentMatchesSaved(current, baked.document)) {
+        return notEmbedded("Code not embedded: the retained program rebakes to a different " +
+            "timeline than the one saved. A scene clip probably changed after " +
+            "v.series(), or a value came from Math.random() or Date.now().");
+    }
+    // Every scene is new here: the saved document was just written from this
+    // same run, so there are no hand edits to keep.
+    const merged = mergeTimelineSource(current, baked.document, {}, { force: true });
+    const write = await writeTimelineCodeDocument(sequence, {
+        ...merged.document,
+        source: {
+            lang: "js",
+            code,
+            bakedAt: new Date().toISOString(),
+            scenes: merged.scenes
+        }
+    }, "Attach authoring code");
+    if (!write.written) {
+        return notEmbedded(`Code not embedded: ${write.error}`);
+    }
+    return {
+        timeline_id: write.timeline_id,
+        embedded: true,
+        errors: write.errors,
+        warnings: write.warnings,
+        conflicts: [],
+        scenes: sceneReport(merged.scenes, new Set())
+    };
+}
+const getTimelineCode = {
+    spec: getTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const doc = sequence.toDocument();
+        const source = doc.source;
+        if (!source)
+            return { code: null, baked_at: null, scenes: [] };
+        const groupIdByScene = new Map();
+        for (const clip of doc.clips) {
+            if (typeof clip.sourceScene === "string" && clip.sourceScene) {
+                groupIdByScene.set(clip.sourceScene, clip.id);
+            }
+        }
+        const editedNames = new Set();
+        for (const [name, recorded] of Object.entries(source.scenes)) {
+            const groupId = groupIdByScene.get(name);
+            const edited = groupId === undefined ||
+                hashSceneSubtree(doc.clips, groupId) !== recorded.hash;
+            if (edited)
+                editedNames.add(name);
+        }
+        return {
+            code: source.code,
+            baked_at: source.bakedAt,
+            scenes: sceneReport(source.scenes, editedNames)
+        };
+    }
+};
+const setTimelineCode = {
+    spec: setTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const code = params["code"];
+        if (!isString(code) || !code.trim()) {
+            return { error: "code is required and must be a non-empty script." };
+        }
+        if (params["require_match"] === true) {
+            return attachMatchingTimelineCode(run, sequence, code);
+        }
+        const force = normalizeForceOption(params["force"]);
+        if (isError(force))
+            return force;
+        return bakeAndMergeTimelineCode(run, sequence, code, force);
+    }
+};
+const editTimelineCode = {
+    spec: editTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const source = sequence.toDocument().source;
+        if (!source) {
+            return {
+                error: `Timeline ${sequence.id} has no authoring code to edit. Call set_timeline_code first.`
+            };
+        }
+        const ops = parseJsScriptEditOps(params["edits"]);
+        if (isError(ops))
+            return ops;
+        const applied = applyJsScriptEditOps(source.code, ops);
+        if (isError(applied))
+            return applied;
+        const force = normalizeForceOption(params["force"]);
+        if (isError(force))
+            return force;
+        return bakeAndMergeTimelineCode(run, sequence, applied.code, force);
+    }
+};
+const rebakeTimelineCode = {
+    spec: rebakeTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const source = sequence.toDocument().source;
+        if (!source) {
+            return { error: `Timeline ${sequence.id} has no authoring code to rebake.` };
+        }
+        const force = normalizeForceOption(params["force"]);
+        if (isError(force))
+            return force;
+        return bakeAndMergeTimelineCode(run, sequence, source.code, force);
+    }
+};
+const detachTimelineCode = {
+    spec: detachTimelineCodeSpec,
+    impl: async (run, params) => {
+        const sequence = await loadTimeline(run, params["timeline_id"]);
+        if (isError(sequence))
+            return sequence;
+        const current = sequence.toDocument();
+        const source = current.source;
+        if (!source)
+            return { scenes: [] };
+        const scenesParam = params["scenes"];
+        // "all" drops the code entirely — there is nothing left to track, and
+        // nothing left worth rebaking. Naming every currently-tracked scene one
+        // by one is a different request: those scenes stop being tracked, but
+        // the code stays, so a later edit that reintroduces a scene (or adds a
+        // new one) still has somewhere to bake into.
+        const dropCode = scenesParam === "all";
+        let detachedNames;
+        if (dropCode) {
+            detachedNames = Object.keys(source.scenes);
+        }
+        else if (Array.isArray(scenesParam) &&
+            scenesParam.length > 0 &&
+            scenesParam.every((s) => typeof s === "string")) {
+            detachedNames = scenesParam.filter((name) => name in source.scenes);
+        }
+        else {
+            return {
+                error: 'scenes must be "all" or a non-empty array of scene names.'
+            };
+        }
+        if (detachedNames.length === 0)
+            return { scenes: [] };
+        const remaining = { ...source.scenes };
+        for (const name of detachedNames)
+            delete remaining[name];
+        const nextDocument = { ...current };
+        if (dropCode) {
+            delete nextDocument["source"];
+        }
+        else {
+            nextDocument["source"] = { ...source, scenes: remaining };
+        }
+        const { TimelineSequence: TimelineSequenceModel, TimelineSequenceVersion } = await import("@nodetool-ai/models");
+        await TimelineSequenceVersion.snapshot(sequence, {
+            saveType: "manual",
+            name: "Before detaching timeline code"
+        });
+        const saved = await TimelineSequenceModel.updateFieldsIfUnchanged(sequence.id, sequence.updated_at, { document: JSON.stringify(nextDocument) });
+        if (!saved) {
+            return {
+                error: `Timeline ${sequence.id} was modified concurrently; nothing was written. Try again.`
+            };
+        }
+        return { timeline_id: saved.id, scenes: detachedNames };
+    }
+};
 const deleteTimeline = {
     spec: deleteTimelineSpec,
     impl: async (run, params) => {
@@ -2316,11 +2810,16 @@ export const TIMELINE_CAPABILITIES = [
     isolateSubject,
     trackObject,
     ...TIMELINE_NATIVE_MEDIA_CAPABILITIES,
+    getTimelineCode,
+    setTimelineCode,
+    editTimelineCode,
+    rebakeTimelineCode,
+    detachTimelineCode,
     deleteTimeline
 ];
 export const module = {
     module: "timelines",
     exports: TIMELINE_CAPABILITIES
 };
-export { listTimelines, createTimeline, getTimeline, listTimelineVersions, getTimelineVersion, createTimelineVersion, restoreTimelineVersion, deleteTimelineVersion, editTimeline, validateTimeline, setTimelineDocument, previewTimelineFrame, compareTimelineFrames, renderTimeline, bakeAudioAnimation, isolateSubject, trackObject, deleteTimeline };
+export { listTimelines, createTimeline, getTimeline, listTimelineVersions, getTimelineVersion, createTimelineVersion, restoreTimelineVersion, deleteTimelineVersion, editTimeline, validateTimeline, setTimelineDocument, previewTimelineFrame, compareTimelineFrames, renderTimeline, bakeAudioAnimation, isolateSubject, trackObject, getTimelineCode, setTimelineCode, editTimelineCode, rebakeTimelineCode, detachTimelineCode, deleteTimeline };
 //# sourceMappingURL=timelines.js.map