@nodetool-ai/agents 0.8.1 → 0.8.3

package/dist/capabilities/timeline-bridge.js

@@ -0,0 +1,1008 @@
+/**
+ * Saved-document timeline adapter. Tool schemas parse calls, the shared ops
+ * engine edits the document, and host hooks resolve assets, persist derived
+ * formats, start jobs, and sample frames. Eval surfaces use this adapter too.
+ */
+import { isShortResourceId } from "@nodetool-ai/protocol";
+import { buildTimelineToolContracts } from "@nodetool-ai/protocol/api-schemas/timeline-tool-contracts.js";
+import { APPLY_TRANSITION_AT_CUT_DESCRIPTION, SET_BAKED_ANIMATION_DESCRIPTION, SET_GENERATED_MATTE_DESCRIPTION, applyTransitionAtCutParams, buildTransition, setBakedAnimationParams, setGeneratedMatteParams, textStylePatchParams } from "@nodetool-ai/protocol/api-schemas/timeline-tool-params.js";
+import { uiToolParams } from "@nodetool-ai/protocol/api-schemas/ui-tool-contract.js";
+import { parseWithTypeCoercion } from "@nodetool-ai/runtime";
+import { ANIMATED_PROPERTIES, DEFAULT_BEAT_TOLERANCE_MS, DEFAULT_MIDI_INSTRUMENT, DEFAULT_TEMPO, STAGGER_UNITS, activeTakeIdOf, applyTakeToClip, captureMediaEditSourceContext, composeGenerativeTakePatch, createTimeOrderedUuid, createMediaEditRequest, ensureBaselineTake, formatBarsBeats, makeClip, makeTrack, planTransitionAtCut, resolveTempo, visibleNotes } from "@nodetool-ai/timeline";
+import { applyTimelineOp, timelineOpFromToolArgs } from "@nodetool-ai/timeline/ops";
+import { computeActiveLayers, parseSvgPath } from "@nodetool-ai/timeline/scene";
+import { z } from "zod";
+export { unwrapClipParams } from "@nodetool-ai/timeline/ops";
+/**
+ * The `ui_timeline_*` contracts, shared with the browser registry
+ * (`web/src/lib/tools/builtin/timeline.ts`). The vocabulary comes from
+ * `@nodetool-ai/timeline`, which the protocol package sits below.
+ */
+const CONTRACTS = buildTimelineToolContracts({
+    staggerUnits: STAGGER_UNITS,
+    animatedProperties: ANIMATED_PROPERTIES,
+    beatToleranceMs: DEFAULT_BEAT_TOLERANCE_MS
+});
+const generatedTransitionCandidateParams = applyTransitionAtCutParams;
+const transitionCandidateParams = z.object({
+    candidate_id: z.string().trim().min(1)
+});
+const transitionCandidateLifecycleParams = applyTransitionAtCutParams
+    .partial()
+    .extend({ candidate_id: z.string().trim().min(1).optional() })
+    .superRefine((value, context) => {
+    if (value.candidate_id === undefined &&
+        (value.outgoingClipId === undefined || value.incomingClipId === undefined)) {
+        context.addIssue({
+            code: "custom",
+            message: "Provide outgoingClipId and incomingClipId to create a candidate, or candidate_id to apply one."
+        });
+    }
+});
+/** Units a failed lookup names before it stops and points at get_state. */
+const MAX_LISTED_UNITS = 12;
+function tool(name, description, parameters, impl) {
+    return {
+        name,
+        description,
+        parameters,
+        execute: (args) => {
+            const parsed = parseWithTypeCoercion(parameters, args ?? {});
+            return impl(parsed);
+        }
+    };
+}
+/**
+ * `set_clip_params` takes the style as a patch merged over the clip's own, so
+ * every field is optional. The shared contract still declares the whole-bag
+ * `textStyleParams`, which refuses `{textStyle: {fontFamily}}` on a finished
+ * title. Both hosts override that one field; when protocol carries
+ * `textStylePatchParams` the two overrides go together.
+ */
+const CONTRACT_SHAPE_OVERRIDES = {
+    ui_timeline_set_clip_params: { textStyle: textStylePatchParams.optional() }
+};
+/** A tool whose name, description and argument shape both hosts share. */
+function sharedTool(name, impl) {
+    const contract = CONTRACTS[name];
+    const shape = { ...contract.shape, ...CONTRACT_SHAPE_OVERRIDES[name] };
+    // No host fields: this bridge drives one implicit sequence, so there is no
+    // `timeline_id` to disambiguate.
+    return tool(name, contract.description, uiToolParams({ ...contract, shape }), impl);
+}
+/**
+ * Keys a caller wraps the whole patch in.
+ *
+ * `set_clip_params` reads its fields off the op itself — `{op, target,
+ * textStyle}` — but a REST-shaped guess sends `{op, target, params: {…}}`, and
+ * that used to be refused as an unknown key with the real fields hidden one
+ * level down inside it. The wrapper says nothing the op does not already know,
+ * so it is unwrapped rather than argued with.
+ */
+const isRecordValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function capitalize(s) {
+    return s.length > 0 ? s[0].toUpperCase() + s.slice(1) : s;
+}
+/**
+ * Build an in-memory timeline bridge whose tools share the `ui_timeline_*`
+ * contract but run headlessly against a plain sequence of tracks/clips (no
+ * Zustand stores, no rendering).
+ */
+export function createTimelineToolBridge(initial = {}) {
+    const seed = initial.sequence;
+    const resolveAsset = initial.resolveAsset;
+    const bakeAnimation = initial.bakeAnimation;
+    const bakeModel3DClip = initial.bakeModel3DClip;
+    const loadComposition = initial.loadComposition;
+    const retargetFormat = initial.retargetFormat;
+    const generateTransition = initial.generateTransition;
+    const sequenceId = initial.sequenceId ?? "seq_eval";
+    const sequenceName = initial.sequenceName ?? "Sequence";
+    const projectId = initial.projectId ?? "";
+    const fps = seed?.fps ?? initial.fps ?? 30;
+    const width = seed?.width ?? initial.width ?? 1920;
+    const height = seed?.height ?? initial.height ?? 1080;
+    let playheadMs = 0;
+    let selectedClipIds = [];
+    // Absent until a midi track or `set_tempo` puts one there — a document with
+    // no midi in it should not grow a tempo field it never asked for.
+    let tempo = seed?.tempo;
+    const tracks = [];
+    let clips = [];
+    let markers = [];
+    // Document-level, like markers: a track is named by `clipId`, and a clip
+    // follows one through its own `trackBinding` (P0 AI Video, Phase 2).
+    let mediaTracks = [];
+    let transitionCandidates = [];
+    let auditionedTransitionCandidateId;
+    let appliedTransitionCandidates = [];
+    const derivedSequences = [];
+    let setup = seed?.setup
+        ? structuredClone(seed.setup)
+        : null;
+    const toolLog = [];
+    const previewTimesMs = [];
+    const previewedLayerKinds = new Set();
+    // Generated ids are 32 hex characters, like every other resource id. A
+    // per-call counter restarted at `link_1` on each call and joined a new split
+    // to a link group the seeded document already held.
+    const newId = initial.newId ?? (() => createTimeOrderedUuid());
+    const nextTrackId = () => newId("track");
+    const nextClipId = () => newId("clip");
+    const nextVersionId = () => newId("version");
+    const nextTransitionId = () => newId("transition");
+    const clipEnd = (clip) => clip.startMs + clip.durationMs;
+    function isAmbiguousCut(outgoing, incoming) {
+        const cutTimeMs = incoming.startMs;
+        return clips.some((candidate) => {
+            if (candidate.id === outgoing.id ||
+                candidate.id === incoming.id ||
+                candidate.trackId !== outgoing.trackId) {
+                return false;
+            }
+            return ((candidate.startMs <= cutTimeMs && clipEnd(candidate) > cutTimeMs) ||
+                candidate.startMs === cutTimeMs);
+        });
+    }
+    function transitionSource(outgoing, incoming, durationMs) {
+        return {
+            sequenceId,
+            outgoingClipId: outgoing.id,
+            incomingClipId: incoming.id,
+            outgoingTakeId: activeTakeIdOf(outgoing),
+            incomingTakeId: activeTakeIdOf(incoming),
+            outgoingAssetId: outgoing.currentAssetId,
+            incomingAssetId: incoming.currentAssetId,
+            outgoingTransition: outgoing.transitionIn
+                ? structuredClone(outgoing.transitionIn)
+                : undefined,
+            incomingTransition: incoming.transitionIn
+                ? structuredClone(incoming.transitionIn)
+                : undefined,
+            outgoingStartMs: outgoing.startMs,
+            outgoingDurationMs: outgoing.durationMs,
+            incomingStartMs: incoming.startMs,
+            incomingDurationMs: incoming.durationMs,
+            cutTimeMs: incoming.startMs,
+            durationMs
+        };
+    }
+    function assertFreshTransitionCandidate(candidate) {
+        const outgoing = clips.find((clip) => clip.id === candidate.source.outgoingClipId);
+        const incoming = clips.find((clip) => clip.id === candidate.source.incomingClipId);
+        if (!outgoing || !incoming) {
+            throw new Error("The generated transition candidate is stale because its selected clip no longer exists.");
+        }
+        if (isAmbiguousCut(outgoing, incoming)) {
+            throw new Error("The generated transition candidate is stale because the selected cut is ambiguous.");
+        }
+        const source = transitionSource(outgoing, incoming, candidate.source.durationMs);
+        if (JSON.stringify(source) !== JSON.stringify(candidate.source)) {
+            throw new Error("The generated transition candidate is stale because the selected clips or cut changed.");
+        }
+    }
+    async function createTransitionCandidate(input) {
+        const outgoingClipId = input.outgoingClipId;
+        const incomingClipId = input.incomingClipId;
+        const outgoing = resolveClip(outgoingClipId);
+        const incoming = resolveClip(incomingClipId);
+        if (isAmbiguousCut(outgoing, incoming)) {
+            throw new Error("The selected cut is ambiguous. Choose two adjacent clips with no other clip crossing the cut.");
+        }
+        const planned = planTransitionAtCut(clips, {
+            outgoingClipId: outgoing.id,
+            incomingClipId: incoming.id,
+            durationMs: input.durationMs,
+            overlapMs: input.overlapMs,
+            type: input.type,
+            easing: input.easing,
+            color: input.color,
+            direction: input.direction,
+            softness: input.softness
+        });
+        if (!planned.ok) {
+            throw new Error(planned.error);
+        }
+        if (!generateTransition) {
+            throw new Error("Selected-cut transition generation is unavailable because this surface has no provider generator.");
+        }
+        const source = transitionSource(outgoing, incoming, planned.candidate.durationMs);
+        const request = {
+            durationMs: planned.candidate.durationMs,
+            overlapMs: planned.candidate.overlapMs,
+            type: planned.candidate.type,
+            easing: input.easing,
+            color: input.color,
+            direction: input.direction,
+            softness: input.softness
+        };
+        const generated = await generateTransition({
+            sequenceId,
+            source,
+            request
+        });
+        if (generated.generationId.trim().length === 0 ||
+            generated.assetId.trim().length === 0) {
+            throw new Error("Selected-cut transition generation returned no generation id or asset.");
+        }
+        const id = nextTransitionId();
+        const candidate = {
+            id,
+            generationId: generated.generationId,
+            kind: "generated_transition_at_cut",
+            status: "success",
+            asset: {
+                id: generated.assetId,
+                contentType: generated.contentType ?? "video/mp4"
+            },
+            source,
+            request,
+            operation: {
+                op: "apply_generated_transition_at_cut",
+                candidateId: id,
+                outgoingClipId: outgoing.id,
+                incomingClipId: incoming.id,
+                cutTimeMs: incoming.startMs,
+                durationMs: planned.candidate.durationMs,
+                undoable: true
+            }
+        };
+        transitionCandidates = [...transitionCandidates, candidate];
+        return candidate;
+    }
+    async function applyTransitionCandidate(candidateId) {
+        const candidate = transitionCandidates.find((entry) => entry.id === candidateId);
+        if (!candidate) {
+            throw new Error(`No generated transition candidate named "${candidateId}" exists.`);
+        }
+        assertFreshTransitionCandidate(candidate);
+        if (appliedTransitionCandidates.some((entry) => entry.id === candidate.id)) {
+            throw new Error(`Generated transition candidate "${candidate.id}" was already applied.`);
+        }
+        // Through the shared op, so a locked outgoing clip, its linked partners
+        // and its source length decide the growth the way they do in the editor.
+        const outcome = await applyTimelineOp(readState(), {
+            op: "apply_transition_at_cut",
+            outgoingClipId: candidate.source.outgoingClipId,
+            incomingClipId: candidate.source.incomingClipId,
+            ...candidate.request
+        }, opContext);
+        if (outcome.error) {
+            throw new Error(outcome.error);
+        }
+        commitOutcome(outcome.state);
+        appliedTransitionCandidates = [
+            ...appliedTransitionCandidates,
+            structuredClone(candidate)
+        ];
+        if (auditionedTransitionCandidateId === candidate.id) {
+            auditionedTransitionCandidateId = undefined;
+        }
+        return {
+            candidate,
+            operation: candidate.operation,
+            description: `Apply generated transition candidate "${candidate.id}" to the selected cut as one undoable operation.`
+        };
+    }
+    function addTrackInternal(type, name) {
+        const index = tracks.length;
+        const track = makeTrack({
+            id: nextTrackId(),
+            type,
+            name: name ?? `${capitalize(type)} ${index + 1}`,
+            index
+        });
+        if (type === "midi") {
+            // The track owns the voice, so a midi track without one plays nothing.
+            track.instrument = DEFAULT_MIDI_INSTRUMENT;
+            // Ticks are read against the tempo, so the first midi track is where a
+            // document that never had one gets it — written down rather than left
+            // implicit, so the next reader does not have to know the default.
+            tempo ??= DEFAULT_TEMPO;
+        }
+        tracks.push(track);
+        return track;
+    }
+    function findOrCreateTrack(type) {
+        const existing = tracks.find((t) => t.type === type);
+        if (existing) {
+            return existing;
+        }
+        return addTrackInternal(type);
+    }
+    /**
+     * The ids and names a caller could have used, for the message a failed
+     * lookup throws. Capped, because a long cut has hundreds of clips and an
+     * error listing all of them is one an agent stops reading.
+     */
+    function validUnits(units, kind) {
+        if (units.length === 0) {
+            return `The timeline has no ${kind}s yet.`;
+        }
+        const shown = units
+            .slice(0, MAX_LISTED_UNITS)
+            .map((u) => `${u.id} ("${u.name}")`)
+            .join(", ");
+        const rest = units.length - MAX_LISTED_UNITS;
+        return rest > 0
+            ? `Valid ${kind}s: ${shown}, and ${rest} more — call get_state for the full list.`
+            : `Valid ${kind}s: ${shown}.`;
+    }
+    function resolveClip(target) {
+        if (target.toLowerCase() === "selected") {
+            if (selectedClipIds.length !== 1) {
+                throw new Error(`"selected" requires exactly one selected clip (currently ${selectedClipIds.length}).`);
+            }
+            const clip = clips.find((c) => c.id === selectedClipIds[0]);
+            if (!clip) {
+                throw new Error("Selected clip no longer exists.");
+            }
+            return clip;
+        }
+        const byId = clips.find((c) => c.id === target);
+        if (byId) {
+            return byId;
+        }
+        if (isShortResourceId(target)) {
+            const matches = clips.filter((clip) => clip.id.startsWith(target));
+            if (matches.length === 1) {
+                return matches[0];
+            }
+            if (matches.length > 1) {
+                throw new Error(`Short clip id "${target}" matches more than one clip. Use the full id or name.`);
+            }
+        }
+        const lower = target.toLowerCase();
+        const byName = clips.find((c) => c.name.toLowerCase() === lower);
+        if (byName) {
+            return byName;
+        }
+        throw new Error(`No clip found matching "${target}". ${validUnits(clips, "clip")}`);
+    }
+    /**
+     * A unit by exact id or by an exact unique 12-character prefix — never by
+     * name. The AI edit tools take a durable destination, so a name match that
+     * could later point elsewhere is refused.
+     */
+    function findByIdOrShortId(units, target, kind) {
+        const exact = units.find((unit) => unit.id === target);
+        if (exact || !isShortResourceId(target)) {
+            return exact;
+        }
+        const matches = units.filter((unit) => unit.id.startsWith(target));
+        if (matches.length > 1) {
+            throw new Error(`Short ${kind} id "${target}" matches more than one ${kind}. Use the full id.`);
+        }
+        return matches[0];
+    }
+    function serializeClip(c) {
+        const track = tracks.find((t) => t.id === c.trackId);
+        return {
+            id: c.id,
+            name: c.name,
+            trackId: c.trackId,
+            trackName: track?.name ?? null,
+            mediaType: c.mediaType,
+            sourceType: c.sourceType,
+            startMs: c.startMs,
+            durationMs: c.durationMs,
+            endMs: c.startMs + c.durationMs,
+            inPointMs: c.inPointMs,
+            outPointMs: c.outPointMs,
+            status: c.status,
+            currentAssetId: c.currentAssetId,
+            activeTakeId: activeTakeIdOf(c),
+            takeCount: c.versions?.length ?? 0,
+            prompt: c.prompt,
+            provider: c.provider,
+            model: c.model,
+            voice: c.voice,
+            animations: (c.animations ?? []).map((a) => ({
+                role: a.role,
+                preset: a.preset
+            })),
+            hidden: c.hidden ?? false,
+            muted: c.muted ?? false,
+            locked: c.locked,
+            opacity: c.opacity,
+            transform: c.transform,
+            textStyle: c.textStyle,
+            shapeStyle: c.shapeStyle,
+            captionStyle: c.caption?.style,
+            transitionIn: c.transitionIn,
+            mask: c.mask,
+            matte: c.matte,
+            timeRemap: c.timeRemap,
+            effects: c.effects,
+            parentId: c.parentId,
+            reframe: c.reframe
+                ? {
+                    mode: c.reframe.mode,
+                    trackId: c.reframe.trackId,
+                    safeMargin: c.reframe.safeMargin,
+                    smoothing: c.reframe.smoothing,
+                    sampleCount: c.reframe.samples?.length ?? 0,
+                    keyframeCount: c.reframe.keyframes?.length ?? 0
+                }
+                : undefined,
+            // The notes themselves are the clip's bulk — a phrase is hundreds of
+            // them — so state reports how many there are and how many the window
+            // actually plays. `set_notes` sends the list; nothing reads it back.
+            noteCount: c.notes?.length,
+            audibleNoteCount: c.mediaType === "midi"
+                ? visibleNotes(c, resolveTempo({ tempo }).bpm).length
+                : undefined,
+            // Where the phrase starts in musical time, so placing the next one is
+            // reading a bar number rather than dividing milliseconds by the tempo.
+            startBarsBeats: c.mediaType === "midi"
+                ? formatBarsBeats(c.startMs, resolveTempo({ tempo }))
+                : undefined
+        };
+    }
+    // Seed from a real sequence when one was handed over, otherwise from the
+    // shorthand. Cloned, so the bridge never writes through to the caller's state.
+    if (seed) {
+        tracks.push(...structuredClone(seed.tracks));
+        clips.push(...structuredClone(seed.clips));
+        markers.push(...structuredClone(seed.markers ?? []));
+        mediaTracks.push(...structuredClone(seed.mediaTracks ?? []));
+    }
+    // Seed initial tracks and clips.
+    for (const t of seed ? [] : (initial.tracks ?? [])) {
+        addTrackInternal(t.type, t.name);
+    }
+    for (const c of seed ? [] : (initial.clips ?? [])) {
+        const track = tracks[c.trackIndex];
+        if (!track) {
+            throw new Error(`Initial clip "${c.name}" references trackIndex ${c.trackIndex}, but only ${tracks.length} track(s) exist.`);
+        }
+        clips.push(makeClip({
+            id: nextClipId(),
+            trackId: track.id,
+            name: c.name,
+            startMs: c.startMs,
+            durationMs: c.durationMs,
+            mediaType: c.mediaType ?? "video",
+            sourceType: "imported",
+            status: "generated"
+        }));
+    }
+    function readState() {
+        return {
+            fps,
+            width,
+            height,
+            tracks,
+            clips,
+            markers,
+            mediaTracks,
+            playheadMs,
+            selectedClipIds,
+            tempo,
+            setup,
+            transcript: seed?.transcript,
+            scriptEnabled: seed?.scriptEnabled,
+            templateId: seed?.templateId,
+            trackFolders: structuredClone(seed?.trackFolders),
+            storyboardMaterializations: structuredClone(seed?.storyboardMaterializations),
+            camera2d: structuredClone(seed?.camera2d ?? null)
+        };
+    }
+    const generateFromBeats = async ({ model, provider, voice, music }) => {
+        const plan = setup?.beats ?? [];
+        if (plan.length === 0) {
+            throw new Error("There is no beat plan to generate from; call ui_timeline_plan_beats first.");
+        }
+        const videoTrack = findOrCreateTrack("video");
+        const wantsMusic = music ??
+            plan.some((beat) => beat.music === true);
+        const voiceTrack = voice !== undefined && plan.some((beat) => (beat.voiceover ?? "") !== "")
+            ? findOrCreateTrack("audio")
+            : null;
+        const videoClipIds = [];
+        const voiceoverClipIds = [];
+        const planned = [];
+        let startMs = 0;
+        for (const [index, beat] of plan.entries()) {
+            const durationMs = Math.max(1, Math.round(beat.duration_ms));
+            const clip = makeClip({
+                id: nextClipId(),
+                trackId: videoTrack.id,
+                name: `Beat ${index + 1}`,
+                startMs,
+                durationMs,
+                mediaType: "video",
+                sourceType: "generated",
+                bindingKind: "text-to-video",
+                prompt: beat.prompt,
+                provider: provider,
+                model: model,
+                beatId: beat.id,
+                status: "draft"
+            });
+            if (beat.transition) {
+                clip.transitionIn = buildTransition({
+                    type: beat.transition,
+                    durationMs: 500
+                });
+            }
+            clips.push(clip);
+            videoClipIds.push(clip.id);
+            const line = (beat.voiceover ?? "").trim();
+            if (voiceTrack && line.length > 0) {
+                const voiceClip = makeClip({
+                    id: nextClipId(),
+                    trackId: voiceTrack.id,
+                    name: `Beat ${index + 1} voiceover`,
+                    startMs,
+                    durationMs,
+                    mediaType: "audio",
+                    sourceType: "generated",
+                    bindingKind: "text-to-audio",
+                    prompt: line,
+                    voice: voice,
+                    beatId: beat.id,
+                    status: "draft"
+                });
+                clips.push(voiceClip);
+                voiceoverClipIds.push(voiceClip.id);
+            }
+            planned.push({ ...beat, clip_id: clip.id });
+            startMs += durationMs;
+        }
+        let musicClipId = null;
+        if (wantsMusic) {
+            // One bed under the whole cut, never one per beat: overlapping music
+            // clips would play at once.
+            const musicTrack = findOrCreateTrack("audio");
+            const musicClip = makeClip({
+                id: nextClipId(),
+                trackId: musicTrack.id,
+                name: "Music",
+                startMs: 0,
+                durationMs: startMs,
+                mediaType: "audio",
+                sourceType: "generated",
+                bindingKind: "text-to-audio",
+                prompt: `Instrumental score under: ${setup?.brief ?? ""}`,
+                status: "draft"
+            });
+            clips.push(musicClip);
+            musicClipId = musicClip.id;
+        }
+        setup = {
+            stage: "done",
+            brief: setup?.brief ?? "",
+            format: setup?.format,
+            voiceover: setup?.voiceover,
+            beats: planned
+        };
+        return {
+            ok: true,
+            videoClipIds,
+            voiceoverClipIds,
+            musicClipId,
+            // Nothing renders headlessly: this authors the cut, and the clips are
+            // drafts until a renderer runs them.
+            startedClipIds: [],
+            note: "Clips created as drafts — this surface renders nothing."
+        };
+    };
+    const opContext = {
+        newId,
+        resolveAsset,
+        bakeAnimation,
+        bakeModel3DClip,
+        loadComposition,
+        parseSvgPath,
+        sequence: { id: sequenceId, name: sequenceName, projectId },
+        retargetFormat: async (sequence) => {
+            const stored = retargetFormat
+                ? await retargetFormat(structuredClone(sequence))
+                : { sequenceId: sequence.id, name: sequence.name };
+            derivedSequences.push(structuredClone(sequence));
+            return { sequenceId: stored.sequenceId, name: stored.name };
+        },
+        generateFromBeats: async (_state, op) => {
+            const result = await generateFromBeats(op);
+            return { state: readState(), result, changedClipIds: [] };
+        }
+    };
+    function commitOutcome(next) {
+        tracks.splice(0, tracks.length, ...next.tracks);
+        clips = next.clips;
+        markers = next.markers;
+        mediaTracks = next.mediaTracks ?? [];
+        tempo = next.tempo;
+        setup = next.setup ?? null;
+        playheadMs = next.playheadMs;
+        selectedClipIds = next.selectedClipIds;
+    }
+    async function editOp(name, args) {
+        const outcome = await applyTimelineOp(readState(), timelineOpFromToolArgs(name, args), opContext);
+        if (outcome.error) {
+            throw new Error(outcome.error);
+        }
+        commitOutcome(outcome.state);
+        return name === "get_state"
+            ? { sequenceId, ...outcome.result }
+            : outcome.result;
+    }
+    const tools = [
+        sharedTool("ui_timeline_get_state", async (args) => editOp("get_state", args)),
+        sharedTool("ui_timeline_add_track", async (args) => editOp("add_track", args)),
+        sharedTool("ui_timeline_move_track", async (args) => editOp("move_track", args)),
+        sharedTool("ui_timeline_add_text_clip", async (args) => editOp("add_text_clip", args)),
+        sharedTool("ui_timeline_delete_track", async (args) => editOp("delete_track", args)),
+        sharedTool("ui_timeline_add_media_clip", async (args) => editOp("add_media_clip", args)),
+        sharedTool("ui_timeline_add_shape_clip", async (args) => editOp("add_shape_clip", args)),
+        sharedTool("ui_timeline_add_model3d_clip", async (args) => editOp("add_model3d_clip", args)),
+        sharedTool("ui_timeline_set_model3d_style", async (args) => editOp("set_model3d_style", args)),
+        sharedTool("ui_timeline_bake_model3d_clip", async (args) => editOp("bake_model3d_clip", args)),
+        sharedTool("ui_timeline_generate_clip", async (args) => editOp("generate_clip", args)),
+        sharedTool("ui_timeline_get_clip_frames", async ({ target, timesMs, count, width }) => {
+            if (!initial.getClipFrames) {
+                throw new Error("This timeline host has no clip-frame renderer. Use a media-backed host.");
+            }
+            const clip = resolveClip(target);
+            const frames = await initial.getClipFrames(clip, {
+                timesMs: timesMs,
+                count: count,
+                width: width
+            });
+            return { ok: true, clip: serializeClip(clip), frames };
+        }),
+        sharedTool("ui_timeline_generatively_edit_clip", async ({ clip_id, instruction, provider, model }) => {
+            // The P0 request captures a durable destination. Unlike general
+            // timeline actions, this intentionally refuses names and selection.
+            const clip = findByIdOrShortId(clips, clip_id, "clip");
+            if (!clip) {
+                throw new Error(`No clip with id "${clip_id}" exists on this timeline. Call ui_timeline_get_state and pass the clip id.`);
+            }
+            const baseline = ensureBaselineTake(clip);
+            if (baseline !== clip) {
+                clips = clips.map((candidate) => candidate.id === clip.id ? baseline : candidate);
+            }
+            const source = captureMediaEditSourceContext(sequenceId, baseline);
+            if (!source.ok) {
+                throw new Error(source.error);
+            }
+            // Eval hosts have no selected model catalog. These deterministic
+            // placeholders only stand in for a real provider's returned asset;
+            // browser and server execution keep their normal model validation.
+            const resolvedProvider = provider ?? "headless";
+            const resolvedModel = model ?? "headless-video-to-video";
+            const request = createMediaEditRequest({
+                sourceContext: source.context,
+                instruction: instruction,
+                provider: resolvedProvider,
+                model: resolvedModel
+            });
+            const generated = initial.generateMediaEdit
+                ? await initial.generateMediaEdit(request)
+                : { generationId: nextVersionId(), assetId: "" };
+            const generationId = generated.generationId;
+            const now = new Date().toISOString();
+            const next = composeGenerativeTakePatch(baseline, "restyle", {
+                assetId: generated.assetId || `generative://${baseline.id}/${generationId}`,
+                jobId: generationId,
+                createdAt: now,
+                workflowUpdatedAt: now,
+                provider: request.provider,
+                model: request.model,
+                prompt: request.instruction,
+                durationMs: request.sourceContext.timelineDurationMs,
+                mediaEdit: request
+            });
+            clips = clips.map((candidate) => candidate.id === baseline.id ? next : candidate);
+            const take = next.versions?.find((candidate) => candidate.id === generationId);
+            if (!take) {
+                throw new Error("The AI edit candidate could not be recorded.");
+            }
+            return {
+                ok: true,
+                requestId: generationId,
+                generationId,
+                activeTakeId: activeTakeIdOf(next) ?? null,
+                candidate: {
+                    id: take.id,
+                    status: take.status,
+                    source: take.source
+                },
+                clip: serializeClip(next)
+            };
+        }),
+        sharedTool("ui_timeline_apply_take", async ({ clip_id, take_id }) => {
+            const clip = findByIdOrShortId(clips, clip_id, "clip");
+            if (!clip) {
+                throw new Error(`No clip with id "${clip_id}" exists on this timeline. Call ui_timeline_get_state and pass the clip id.`);
+            }
+            if (clip.locked || tracks.find((t) => t.id === clip.trackId)?.locked) {
+                throw new Error(`Clip "${clip.name}" or its track is locked. Unlock it before editing.`);
+            }
+            const take = findByIdOrShortId(clip.versions ?? [], take_id, "take");
+            if (!take?.mediaEdit) {
+                throw new Error(`Take "${take_id}" is not an AI edit candidate for "${clip.name}". Apply only the candidate returned by ui_timeline_generatively_edit_clip.`);
+            }
+            const result = applyTakeToClip(clip, take.id);
+            if (result.error) {
+                throw new Error(result.error);
+            }
+            clips = clips.map((candidate) => candidate.id === clip.id ? result.clip : candidate);
+            return { ok: true, clip: serializeClip(result.clip) };
+        }),
+        sharedTool("ui_timeline_split_clip", async (args) => editOp("split_clip", args)),
+        sharedTool("ui_timeline_trim_clip", async (args) => editOp("trim_clip", args)),
+        sharedTool("ui_timeline_move_clip", async (args) => editOp("move_clip", args)),
+        sharedTool("ui_timeline_delete_clip", async (args) => editOp("delete_clip", args)),
+        sharedTool("ui_timeline_duplicate_clip", async (args) => editOp("duplicate_clip", args)),
+        sharedTool("ui_timeline_set_clip_params", async (args) => editOp("set_clip_params", args)),
+        sharedTool("ui_timeline_add_group", async (args) => editOp("add_group", args)),
+        sharedTool("ui_timeline_set_parent", async (args) => editOp("set_parent", args)),
+        sharedTool("ui_timeline_set_transition", async (args) => editOp("set_transition", args)),
+        tool("ui_timeline_generate_transition_at_cut", "Generate an inactive cut-level transition candidate for two explicitly adjacent clips. This does not change either clip or create a clip take. Preview the returned candidate before applying it.", generatedTransitionCandidateParams, async (args) => {
+            const candidate = await createTransitionCandidate(args);
+            return {
+                ok: true,
+                requestId: candidate.generationId,
+                generationId: candidate.generationId,
+                candidate,
+                source: candidate.source
+            };
+        }),
+        tool("ui_timeline_preview_transition_candidate", "Audition one generated cut-level transition candidate without changing the timeline document. Refuses candidates whose selected clips, source takes, or cut are stale.", transitionCandidateParams, async ({ candidate_id }) => {
+            const candidate = transitionCandidates.find((entry) => entry.id === candidate_id);
+            if (!candidate) {
+                throw new Error(`No generated transition candidate named "${candidate_id}" exists.`);
+            }
+            assertFreshTransitionCandidate(candidate);
+            auditionedTransitionCandidateId = candidate.id;
+            return { ok: true, previewOnly: true, candidate };
+        }),
+        tool("ui_timeline_apply_transition_at_cut", `${APPLY_TRANSITION_AT_CUT_DESCRIPTION} With clip ids and timing, this creates an inactive cut-level candidate. Apply a returned candidate_id explicitly to commit it as one undoable operation.`, transitionCandidateLifecycleParams, async (args) => {
+            if (args.candidate_id !== undefined) {
+                const applied = await applyTransitionCandidate(args.candidate_id);
+                return { ok: true, applied: true, ...applied };
+            }
+            const candidate = await createTransitionCandidate(args);
+            return {
+                ok: true,
+                applied: false,
+                requestId: candidate.generationId,
+                generationId: candidate.generationId,
+                candidate,
+                source: candidate.source,
+                next: "Preview with ui_timeline_preview_transition_candidate, then call this tool with candidate_id to apply."
+            };
+        }),
+        sharedTool("ui_timeline_set_mask", async (args) => editOp("set_mask", args)),
+        sharedTool("ui_timeline_set_matte", async (args) => editOp("set_matte", args)),
+        // Headless-only: the inspector's own controls write these knobs into the
+        // store. Both this and the ops module's `set_generated_matte` reach
+        // `selectGeneratedMatteVersion`, so the version list cannot fork.
+        tool("ui_timeline_set_generated_matte", SET_GENERATED_MATTE_DESCRIPTION, setGeneratedMatteParams, async (args) => editOp("set_generated_matte", args)),
+        sharedTool("ui_timeline_set_time_remap", async (args) => editOp("set_time_remap", args)),
+        sharedTool("ui_timeline_set_effects", async (args) => editOp("set_effects", args)),
+        sharedTool("ui_timeline_set_clip_binding", async (args) => editOp("set_clip_binding", args)),
+        sharedTool("ui_timeline_animate_clip", async (args) => editOp("animate_clip", args)),
+        // Headless-only: the browser writes curves through the inspector, not
+        // through an agent call. Both this and the ops module's `set_baked_animation`
+        // go through `buildBakedAnimation`, so the replace rule cannot fork.
+        tool("ui_timeline_set_baked_animation", SET_BAKED_ANIMATION_DESCRIPTION, setBakedAnimationParams, async (args) => editOp("set_baked_animation", args)),
+        sharedTool("ui_timeline_stagger_animations", async (args) => editOp("stagger_animations", args)),
+        sharedTool("ui_timeline_clear_animations", async (args) => editOp("clear_animations", args)),
+        sharedTool("ui_timeline_list_animation_presets", async (args) => editOp("list_animation_presets", args)),
+        sharedTool("ui_timeline_select_clip", async (args) => editOp("select_clip", args)),
+        sharedTool("ui_timeline_seek", async (args) => editOp("seek", args)),
+        sharedTool("ui_timeline_add_marker", async (args) => editOp("add_marker", args)),
+        // ── Guided video flow (PRD § 8.6) ───────────────────────────────────
+        sharedTool("ui_timeline_set_setup", async (args) => editOp("set_setup", args)),
+        sharedTool("ui_timeline_plan_beats", async (args) => editOp("plan_beats", args)),
+        sharedTool("ui_timeline_update_beat", async (args) => editOp("update_beat", args)),
+        sharedTool("ui_timeline_remove_beat", async (args) => editOp("remove_beat", args)),
+        sharedTool("ui_timeline_generate_from_beats", async (args) => editOp("generate_from_beats", args)),
+        sharedTool("ui_timeline_delete_marker", async (args) => editOp("delete_marker", args)),
+        sharedTool("ui_timeline_set_markers_from_beats", async (args) => editOp("set_markers_from_beats", args)),
+        sharedTool("ui_timeline_snap_to_beats", async (args) => editOp("snap_to_beats", args)),
+        // ── MIDI ────────────────────────────────────────────────────────────
+        // Notes live on the clip, the instrument on the track, and the tempo on
+        // the document, so each gets its own op.
+        sharedTool("ui_timeline_add_midi_clip", async (args) => editOp("add_midi_clip", args)),
+        sharedTool("ui_timeline_set_notes", async (args) => editOp("set_notes", args)),
+        sharedTool("ui_timeline_set_tempo", async (args) => editOp("set_tempo", args)),
+        sharedTool("ui_timeline_set_track_instrument", async (args) => editOp("set_track_instrument", args)),
+        // The note edits. Each runs the whole list through one pure function from
+        // `@nodetool-ai/timeline` and replaces it — the ids survive, so a
+        // selection and an undo in the editor still point at the same notes.
+        sharedTool("ui_timeline_transpose_clip", async (args) => editOp("transpose_clip", args)),
+        sharedTool("ui_timeline_quantize_notes", async (args) => editOp("quantize_notes", args)),
+        sharedTool("ui_timeline_scale_velocity", async (args) => editOp("scale_velocity", args)),
+        tool("ui_timeline_insert_composition", "Insert a stored composition — a group of clips with named parameters (a lower third, a title card, a callout) — at a timecode. Its children keep the layering the template declares: each template track becomes an overlay track of its own, front-most on top, reused across insertions. `params` overrides the template's defaults by name; anything omitted keeps its default. Call list_compositions for the ids and their parameters.", z.object({
+            composition_id: z
+                .string()
+                .describe("Composition id, from list_compositions."),
+            startMs: z
+                .number()
+                .describe("Where the group starts on the timeline, in ms."),
+            trackId: z
+                .string()
+                .optional()
+                .describe("Track for the group clip itself. Its children still get their own overlay tracks. Defaults to an overlay track."),
+            params: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+                .optional()
+                .describe('Parameter overrides by name, e.g. {name: "Ada Lovelace"}. A name the template does not declare, or a value of the wrong type, is refused.')
+        }), async (args) => editOp("insert_composition", args)),
+        // Headless-only: the editor's ClipVersionHistory panel writes take
+        // switches, renames and deletes straight into TimelineStore via
+        // restoreVersion/renameTake/deleteTake. This op reaches the same
+        // `selectTake`/`renameTake`/`deleteTake` helpers, so the take list cannot
+        // fork between the two hosts (P0 AI Video, PRD § 8.10).
+        tool("ui_timeline_list_takes", "List a clip's take history (clip.versions): id, label, source, " +
+            "provider, model, createdAt, costCredits, durationMs, status, " +
+            "favorite, and which one is active.", z.object({ target: z.string().describe("Clip id or name.") }), async (args) => editOp("list_takes", args)),
+        tool("ui_timeline_select_take", "Make a stored take current on a clip — the same switch " +
+            "restoreVersion does in the editor. Refuses a take that is not " +
+            '`status: "success"`.', z.object({
+            target: z.string().describe("Clip id or name."),
+            takeId: z.string().describe("A take id, from list_takes.")
+        }), async (args) => editOp("select_take", args)),
+        tool("ui_timeline_rename_take", "Set a take's display label.", z.object({
+            target: z.string().describe("Clip id or name."),
+            takeId: z.string().describe("A take id, from list_takes."),
+            label: z.string().describe("The new display label.")
+        }), async (args) => editOp("rename_take", args)),
+        tool("ui_timeline_delete_take", "Remove a take from a clip's history. Refuses when `takeId` is the " +
+            "active take — select_take a different take first, then delete the " +
+            "one you no longer want; a clip must always keep at least one take.", z.object({
+            target: z.string().describe("Clip id or name."),
+            takeId: z.string().describe("A take id, from list_takes.")
+        }), async (args) => editOp("delete_take", args)),
+        // Subject/object tracks (P0 AI Video, Phase 2). The async provider call
+        // that fills a track's samples is the `track_object` capability, not an
+        // op — these four are the structural half over it, and they carry the
+        // same semantics as `applyTimelineOp`'s own cases so the two hosts cannot
+        // fork (`packages/timeline/src/ops/apply.ts`).
+        tool("ui_timeline_list_tracks", "List the document's subject/object tracks — id, clipId, name, kind, " +
+            "status, source window and sample count. The samples themselves are " +
+            "not returned: a track carries one per frame it covers, which is a " +
+            "wall of numbers no caller reads through a listing.", z.object({
+            target: z
+                .string()
+                .optional()
+                .describe("A clip id or name to filter by. Omit for every track.")
+        }), async (args) => editOp("list_tracks", args)),
+        tool("ui_timeline_delete_track_object", "Delete a subject/object track and unbind every clip that was " +
+            "following it — a clip left pointing at a track that is gone reads " +
+            "as bound while following nothing.", z.object({
+            trackId: z.string().describe("A track id, from list_tracks.")
+        }), async (args) => editOp("delete_track_object", args)),
+        tool("ui_timeline_bind_to_track", "Make a clip follow a subject/object track, so its position moves " +
+            'with the tracked subject. Only "position" and "position_scale" are ' +
+            "implemented; the other modes are named by the document format for a " +
+            "later phase and are refused here rather than silently doing nothing.", z.object({
+            target: z.string().describe("Clip id or name."),
+            trackId: z.string().describe("A track id, from list_tracks."),
+            mode: z.string().describe('"position" or "position_scale".'),
+            offset: z
+                .object({ x: z.number(), y: z.number() })
+                .optional()
+                .describe("Canvas-pixel offset added on top of the tracked point."),
+            scale: z
+                .number()
+                .optional()
+                .describe('Scale multiplier, "position_scale" only.'),
+            rotationOffset: z
+                .number()
+                .optional()
+                .describe("Radians added to the clip's rotation."),
+            smoothing: z
+                .number()
+                .optional()
+                .describe("0..1; higher follows the track more loosely.")
+        }), async (args) => editOp("bind_to_track", args)),
+        tool("ui_timeline_unbind_track", "Stop a clip following a track. A clip that follows none is a no-op.", z.object({ target: z.string().describe("Clip id or name.") }), async (args) => editOp("unbind_track", args)),
+        sharedTool("ui_timeline_retarget_format", async (args) => editOp("retarget_format", args)),
+        sharedTool("ui_timeline_set_reframe_subject", async (args) => editOp("set_reframe_subject", args)),
+        sharedTool("ui_timeline_add_reframe_keyframe", async (args) => editOp("add_reframe_keyframe", args)),
+        sharedTool("ui_timeline_clear_reframe", async (args) => editOp("clear_reframe", args))
+    ];
+    // Opt-in, and outside the `ui_timeline_` prefix on purpose: `edit_timeline`
+    // builds this same bridge and matches its ops by that prefix, so a preview
+    // tool it can never call has no business in its op catalogue. A case that
+    // grades "did it look at the frame" asks for it.
+    if (initial.preview) {
+        tools.push(tool("preview_timeline_frame", "Look at the sequence at one or more timecodes: what is on screen, layered top of the stack first, with each layer's opacity and track index. This surface has no rasterizer, so it reports the layer stack rather than pixels — enough to see a layer that is covered, missing, or drawing nothing. Call it after an edit, before you say you are done.", z.object({
+            times_ms: z
+                .array(z.number().nonnegative())
+                .min(1)
+                .max(8)
+                .describe("Absolute timeline positions to look at, in ms.")
+        }), async ({ times_ms }) => {
+            const frames = times_ms.map((timeMs) => ({
+                time_ms: timeMs,
+                layers: computeActiveLayers(tracks, clips, timeMs)
+                    .map((layer) => ({
+                    clip_id: layer.clipId,
+                    clip_name: clips.find((c) => c.id === layer.clipId)?.name ??
+                        layer.clipId,
+                    kind: layer.kind,
+                    track_index: layer.trackIndex,
+                    z_index: 1000 - layer.trackIndex,
+                    opacity: layer.opacity,
+                    text: layer.textStyle?.text
+                }))
+                    // Top of the stack first, the order the skill's report describes.
+                    .sort((a, b) => b.z_index - a.z_index)
+            }));
+            previewTimesMs.push(...times_ms);
+            for (const frame of frames) {
+                for (const layer of frame.layers) {
+                    previewedLayerKinds.add(layer.kind);
+                }
+            }
+            return { ok: true, width, height, frames };
+        }));
+    }
+    // Recorded rather than counted: a predicate asks where the last edit sits
+    // relative to a preview, which a tally cannot answer. The push happens
+    // before the call, so a tool that throws is still in the transcript.
+    let pending = Promise.resolve();
+    const recorded = tools.map((entry) => ({
+        ...entry,
+        execute: (args) => {
+            toolLog.push(entry.name);
+            const parsed = parseWithTypeCoercion(entry.parameters, args);
+            if (!isRecordValue(parsed)) {
+                throw new Error("Timeline tool arguments must be an object.");
+            }
+            const result = pending.then(() => entry.execute(parsed));
+            pending = result.catch(() => undefined);
+            return result;
+        }
+    }));
+    return {
+        tools: recorded,
+        finalState: () => ({
+            fps,
+            width,
+            height,
+            durationMs: clips.reduce((m, c) => Math.max(m, c.startMs + c.durationMs), 0),
+            playheadMs,
+            tracks: tracks.map((t) => ({
+                id: t.id,
+                name: t.name,
+                type: t.type,
+                index: t.index
+            })),
+            clips: clips.map((c) => ({
+                id: c.id,
+                name: c.name,
+                trackId: c.trackId,
+                mediaType: c.mediaType,
+                startMs: c.startMs,
+                durationMs: c.durationMs,
+                prompt: c.prompt,
+                animations: (c.animations ?? []).map((a) => ({
+                    role: a.role,
+                    preset: a.preset
+                }))
+            })),
+            documentTracks: tracks.map((t) => structuredClone(t)),
+            documentClips: clips.map((c) => structuredClone(c)),
+            markers: markers.map((m) => structuredClone(m)),
+            mediaTracks: mediaTracks.map((t) => structuredClone(t)),
+            derivedSequences: derivedSequences.map((sequence) => structuredClone(sequence)),
+            tempo: tempo ? structuredClone(tempo) : undefined,
+            camera2d: structuredClone(seed?.camera2d ?? null),
+            setup: setup ? structuredClone(setup) : null,
+            transitionCandidates: structuredClone(transitionCandidates),
+            auditionedTransitionCandidateId,
+            appliedTransitionCandidates: structuredClone(appliedTransitionCandidates),
+            toolLog: [...toolLog],
+            previewTimesMs: [...previewTimesMs],
+            previewedLayerKinds: [...previewedLayerKinds]
+        })
+    };
+}
+//# sourceMappingURL=timeline-bridge.js.map