@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/capabilities/timelines.specs.js

@@ -0,0 +1,1527 @@
+/**
+ * The `timelines` module's specs — data only, no implementation.
+ *
+ * Split out so a belt can be assembled synchronously: the registry's eager
+ * spec table imports this file, never `timelines.ts`, so nothing the
+ * implementations pull in reaches the entry graph. `timelines.ts` imports these
+ * back and attaches each to its implementation, so there is one spec object
+ * behind both halves.
+ */
+import { isString } from "../utils/type-guards.js";
+export const DEFAULT_VERSION_LIMIT = 20;
+export const MAX_VERSION_LIMIT = 100;
+export const SAVE_TYPE_PROPERTY = {
+    type: "string",
+    enum: ["manual", "autosave", "restore"],
+    description: "Only versions of this kind: 'manual' (a save someone asked for), " +
+        "'autosave' (taken on a document write), 'restore' (the pre-restore " +
+        "snapshot). Omit for all of them."
+};
+export const LIST_TIMELINES_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Only timelines whose name contains this text (case-insensitive)."
+        },
+        limit: {
+            type: "number",
+            description: "Max timelines to return (default 20)."
+        }
+    }
+};
+export const GET_TIMELINE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id (from list_timelines)."
+        }
+    },
+    required: ["timeline_id"]
+};
+export const LIST_TIMELINE_VERSIONS_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id."
+        },
+        save_type: SAVE_TYPE_PROPERTY,
+        limit: {
+            type: "number",
+            description: `Max versions to return (default ${DEFAULT_VERSION_LIMIT}, max ${MAX_VERSION_LIMIT}).`
+        }
+    },
+    required: ["timeline_id"]
+};
+export const GET_TIMELINE_VERSION_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id."
+        },
+        version: {
+            type: "number",
+            description: "Version number to read, from list_timeline_versions."
+        }
+    },
+    required: ["timeline_id", "version"]
+};
+export const CREATE_TIMELINE_VERSION_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id."
+        },
+        name: {
+            type: "string",
+            description: "Label for the snapshot, e.g. 'before the recut'."
+        }
+    },
+    required: ["timeline_id"]
+};
+export const RESTORE_TIMELINE_VERSION_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id."
+        },
+        version: {
+            type: "number",
+            description: "Version number to restore, from list_timeline_versions."
+        }
+    },
+    required: ["timeline_id", "version"]
+};
+export const EDIT_TIMELINE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: { type: "string", description: "Timeline sequence id." },
+        ops: {
+            type: "array",
+            description: 'At most 60 operations per call; split larger builds into batches and inspect each result. ' +
+                'Operations run in order. Each is {"op": <name>, ...arguments}, e.g. ' +
+                '{"op": "add_track", "type": "audio", "name": "Music"} or ' +
+                '{"op": "animate_clip", "target": "Title", "animations": [{"role": "in", "preset": "fade"}]}. ' +
+                "Ops: get_state, add_track, move_track, add_media_clip, add_text_clip, add_shape_clip, " +
+                "add_group, split_clip, trim_clip, move_clip, duplicate_clip, delete_clip, " +
+                "set_clip_params, set_parent, set_clip_binding, set_transition, set_mask, " +
+                "set_matte, set_time_remap, set_effects, animate_clip, stagger_animations, " +
+                "set_baked_animation, " +
+                "clear_animations, list_animation_presets, select_clip, seek, " +
+                "add_marker, delete_marker, set_markers_from_beats, snap_to_beats, " +
+                "insert_composition, list_takes, select_take, rename_take, " +
+                "delete_take, add_midi_clip, set_notes, set_tempo, " +
+                "set_track_instrument, transpose_clip, quantize_notes, " +
+                "scale_velocity, retarget_format, set_reframe_subject, " +
+                "add_reframe_keyframe, clear_reframe. retarget_format creates a new " +
+                "sequence and must be the only op in its call; call it once per " +
+                "target format. " +
+                "Clip transforms accept rotationX and rotationY in degrees and perspective " +
+                "in pixels through add_*_clip and set_clip_params. For every clip, " +
+                "transform.position.x/y are sequence pixels relative to the frame " +
+                "center (0/0 means no offset, positive x moves right, positive y " +
+                "moves down), including add_text_clip and add_shape_clip. " +
+                "Custom animation curves " +
+                "can animate rotationX and rotationY. Start with get_state to " +
+                "read track and clip ids. To lay existing videos end to end, call " +
+                'add_media_clip once per asset ({"op": "add_media_clip", "asset": ' +
+                '"asset://<id>.mp4"}) — each appends after the last. animate_clip ' +
+                'takes catalog presets and, for motion none of them covers, ' +
+                '{"preset": "custom"} with exactly one of `curves` ' +
+                '([{property, keyframes: [{t, value, easing?}]}], `t` running 0..1 ' +
+                "over the animation's window) or `code` (a JS body baked into curves " +
+                "once, host-side); add `mask` when a curve drives wipeProgress. " +
+                "Either may sit under a nested `custom: {curves|code|mask}` instead. " +
+                "list_animation_presets reports the animatable properties. " +
+                'set_baked_animation writes ONE curve something measured — {"target", ' +
+                '"animation": {property, keyframes: [{sourceMs, value, easing?}], ' +
+                "bakedFrom: {kind, clipId?, assetId?, settings?}, replace?}}. Its " +
+                "keyframes name absolute milliseconds in the target clip's own media, " +
+                "so a trim or split re-slices the motion, and a second write with the " +
+                "same `bakedFrom.kind` on the same property replaces that curve in " +
+                "place. bake_audio_animation is the tool that produces one; reach for " +
+                "animate_clip for a preset or a hand-written curve. " +
+                'set_transition takes {"target", "transition": {type, durationMs, ' +
+                "easing?, color?, direction?, softness?} | null} — the cut plays over " +
+                "the target's head against the clip beneath it, so overlap the two. " +
+                'set_mask takes {"target", "mask": {kind: "rect"|"ellipse"|"path", ' +
+                "x?, y?, width?, height?, d?, featherPx?, invert?} | null} in the " +
+                "clip's own 0..1 space. " +
+                'set_matte takes {"target", "matte": {source, mode: "alpha"|"luma", ' +
+                "invert?} | null}; the source clip stops drawing itself and its alpha " +
+                "or brightness becomes the target's transparency. " +
+                'set_time_remap takes {"target", "timeRemap": {keyframes: [{t, ' +
+                "sourceMs, easing?}]} | null}; `t` runs 0..1 over the clip's window " +
+                "and must start at 0, end at 1 and ascend, while `sourceMs` says " +
+                "which millisecond of the source plays there — descending is reverse, " +
+                "a flat pair is a freeze. It replaces the clip's rate, and split and " +
+                "trim refuse a remapped clip. " +
+                'add_group takes {"name", "startMs", "durationMs", trackId?, ' +
+                'children?: [clip, ...]} and creates a clip with no media whose ' +
+                "transform, opacity and window every clip naming it inherits — move " +
+                "the group and its children move with it. Children keep their own " +
+                "tracks, so what covers what is unchanged. " +
+                'set_parent takes {"target", "parentId": <group> | null}; the parent ' +
+                "must be a clip made with add_group, and a cycle is refused. " +
+                "Track order is z-order — index 0 draws on top — and add_track " +
+                "appends to the bottom, so a picture track added after the overlays " +
+                "covers them. Add the overlays last, or fix it with move_track " +
+                '{"target", and one of "toIndex" (0 is the top), "before" or ' +
+                '"after"}. ' +
+                'add_shape_clip takes the geometry in "shape" (or "shapeStyle"): ' +
+                '{kind: "rect"|"ellipse"|"line"|"polygon"|"star"|"path", x, y, ' +
+                "width, height, fill?, stroke?, strokeWidthPx?}, where x/y/width/" +
+                "height are 0..1 fractions of the frame; those keys are also read " +
+                "from the op itself, and with no geometry at all the shape is a " +
+                "full-frame rect. Shape geometry uses the top-left frame origin, " +
+                "so shape.x/y are not transform.position.x/y. " +
+                'set_clip_params takes {"target", ...fields}; a caption clip\'s look ' +
+                'is "captionStyle": {fontFamily?, fontSizeFrac?, color?, activeColor?, ' +
+                "outline?, bottomMarginFrac?, background?}, each field optional and " +
+                "each absent one keeping the built-in value. It also takes " +
+                '"fontSizePx" (merged into textStyle) and the timing move_clip and ' +
+                'trim_clip apply — "startMs", "trackId", "durationMs", "inPointMs", ' +
+                '"outPointMs" — and refuses a key it does not know by name rather ' +
+                "than ignoring it. " +
+                'set_effects takes {"target", "effects": [{type, ...}]} and replaces ' +
+                "the whole chain — types color, blur, pixelate, posterize, " +
+                "directionalBlur, lensDistortion, stylize, generator, lut, glow, " +
+                "dropShadow, vignette, sharpen, chromaKey, grain, curves, levels, " +
+                "liftGammaGain, applied in the " +
+                "order given. blur takes radius in pixels, e.g. {type: \"blur\", " +
+                "radius: 80}; unknown parameters such as amount are rejected. " +
+                "An empty list clears it. " +
+                'add_marker takes {"timeMs", "label"?, "color"?, "note"?} and ' +
+                'delete_marker {"target"} (marker id or label). ' +
+                "set_markers_from_beats and snap_to_beats both take a grid — " +
+                '"onsets_ms" (detect_audio_events reports `onsets.times` in SECONDS, ' +
+                'so multiply by 1000) or "bpm" with "offset_ms"?; ' +
+                'set_markers_from_beats also needs "count". snap_to_beats takes ' +
+                '"targets" (clip ids or names, or "all"), "tolerance_ms"? (default ' +
+                '60), "mode"? ("start" | "end" | "both") and "action"? ("move" slides ' +
+                'the clip, "trim" changes its length), and reports every target — ' +
+                "including the ones no beat was in reach of, with the reason. " +
+                'insert_composition takes {"composition_id", "startMs", trackId?, ' +
+                'params?} and drops a stored template — a lower third, a title card, a ' +
+                "callout — in as a group with its children, each template track " +
+                "becoming an overlay track of its own so the layering survives. " +
+                "`params` overrides the template's defaults by name; list_compositions " +
+                "reports the ids and what each one takes. " +
+                "Every generated or imported result a clip has ever carried is a take " +
+                '— clip.versions. list_takes {"target"} reports each one (id, label, ' +
+                "source, provider, model, createdAt, costCredits, durationMs, status, " +
+                'favorite) plus which is active. select_take {"target", "takeId"} ' +
+                "makes a stored take current — the same switch restoreVersion does in " +
+                "the editor — refusing a take that is not `status: \"success\"`. " +
+                'rename_take {"target", "takeId", "label"} sets a take\'s display ' +
+                'label. delete_take {"target", "takeId"} removes a take from the ' +
+                "history and 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. " +
+                'A played part is midi: add_track {"type": "midi"} makes a track that ' +
+                "owns the synth (and gives the document a 120 BPM tempo if it had " +
+                'none), add_midi_clip takes {"track", "start_ms", "duration_ms", ' +
+                'name?, notes?} and set_notes {"clip", "notes"} replaces the whole ' +
+                "list. A note is {pitch (0..127, 60 is middle C), start_tick, " +
+                "duration_tick, velocity? (1..127, default 100), id?} in ticks from " +
+                "the clip's content start, 960 ticks to a quarter note — so trimming " +
+                "the clip hides notes instead of deleting them. " +
+                'set_track_instrument takes {"track", "instrument"}, either a named ' +
+                'voice — {"preset": "bass"}, including saw-lead, square-lead, soft-pad, ' +
+                "pluck, bass, bell, the FableSynth WT-1 wavetable patches " +
+                "wt1-prime-lead, wt1-bloom-pad, wt1-vox-morph, wt1-chime-bell, the " +
+                "BL-1 acid basslines bl1-acid, bl1-deep, bl1-rubber, and the DR-1 " +
+                "drum kit dr1-tr-void — or the synth spelled out: {type: " +
+                '"subtractive", waveform, attackMs, decayMs, sustain, releaseMs, ' +
+                "cutoffHz, resonance, gainDb}. dr1-tr-void plays one drum per note " +
+                "from 36 (kick, kick 2, snare, clap, rim, closed hat, open hat, ride, " +
+                "three toms, crash, two percs, vox, glitch) and is silent above 51. " +
+                "get_state reports the preset a track's instrument matches as " +
+                "presetId. Soundtrack voices include sampler (load audio assets into key ranges), wt1-cinematic-strings, " +
+                "wt1-chamber-strings, wt1-short-strings, wt1-low-strings, " +
+                "wt1-warm-brass, wt1-air-choir, wt1-dark-swell, wt1-soft-keys, " +
+                "wt1-glass-mallet, wt1-muted-pluck, bl1-cinematic-sub, " +
+                "bl1-score-pulse, bl1-rounded-bass, and dr1-cinematic. " +
+                "These are synthesized instruments. Use low strings around MIDI " +
+                "36–55, ensembles around 48–79, and basses around 28–48. " +
+                "dr1-cinematic uses MIDI 36–51: low boom, gran cassa, field snare, " +
+                "ensemble strike, wood tick, shaker, brush, metal wash, low/mid/high " +
+                "taiko, cymbal swell, low metal, small bell, deep gong, tension hit. " +
+                'set_tempo takes {"bpm", offset_ms?, beats_per_bar?, beat_unit?} and ' +
+                "rescales every midi clip around offset_ms — halving the BPM doubles " +
+                "each midi clip's start and length — while picture and audio stay " +
+                "where they are. " +
+                "Three ops edit a phrase already placed, each rewriting the clip's " +
+                "whole note list and keeping every id: transpose_clip " +
+                '{"clip", "semitones"} moves every note by whole semitones (12 is an ' +
+                "octave; a note pushed past 0..127 is held at the end, so up and back " +
+                'down is not always the same phrase), quantize_notes {"clip", ' +
+                '"division", strength?, target?} snaps onsets to a note grid — ' +
+                "division is 1/4, 1/8, 1/16, 1/32 or the triplets 1/8T and 1/16T, " +
+                "read in ticks at PPQ 960 (1/4 is 960 ticks, 1/16 is 240, 1/8T is " +
+                "320), strength 0..1 moves each note part of the way and keeps the " +
+                'feel, target "start_and_length" also rounds the held lengths — and ' +
+                'reports movedNoteCount, and scale_velocity {"clip", "factor"} ' +
+                "multiplies every velocity, clamped to 1..127. Each is refused on a " +
+                "clip that is not midi. get_state reports every midi clip's start as " +
+                "startBarsBeats (bar.beat.tick) against the document tempo.",
+            items: { type: "object" }
+        }
+    },
+    required: ["timeline_id", "ops"]
+};
+export const VALIDATE_TIMELINE_SCHEMA = {
+    type: "object",
+    properties: {
+        normalize: {
+            type: "boolean",
+            description: "For inline authoring preflight, fill omitted bookkeeping, effect ids and referenced tracks exactly as set_timeline_document does. Default false inspects the document as sent."
+        },
+        tier: {
+            type: "string",
+            enum: ["standard", "showcase"],
+            description: "Default standard checks correctness. Showcase compares scene-group count, custom-animation density, effect variety and clip density with shipped examples, and checks fast-motion blur, finish, camera depth and concurrent layers. These structural checks do not judge aesthetic quality."
+        },
+        timeline_id: {
+            type: "string",
+            description: "The ID of a saved timeline sequence to validate"
+        },
+        document: {
+            type: "object",
+            description: "Inline TimelineDocument to validate ({ tracks, clips, markers }). " +
+                "Takes precedence over timeline_id."
+        },
+        fps: {
+            type: "number",
+            description: "Frame rate the inline document renders at (default 30). Timing " +
+                "checks are frame-based, so a document authored at another fps " +
+                "validates against the wrong grid without this. Ignored for timeline_id."
+        },
+        width: {
+            type: "number",
+            description: "Render width of the inline document. Ignored for timeline_id."
+        },
+        height: {
+            type: "number",
+            description: "Render height of the inline document. Ignored for timeline_id."
+        }
+    }
+};
+export const listTimelinesSpec = {
+    name: "list_timelines",
+    description: "List the caller's timeline sequences, most recently updated first: id, " +
+        "name, frame rate, resolution, duration, and when it last changed. Start " +
+        "here when the user names a timeline but not its id.",
+    inputSchema: LIST_TIMELINES_SCHEMA,
+    category: "read",
+    userMessage: () => "Listing timelines"
+};
+export const CREATE_TIMELINE_SCHEMA = {
+    type: "object",
+    properties: {
+        name: {
+            type: "string",
+            description: "Name for the new sequence."
+        },
+        fps: { type: "number", description: "Frame rate. Default 30." },
+        width: { type: "number", description: "Render width. Default 1920." },
+        height: { type: "number", description: "Render height. Default 1080." },
+        project_id: {
+            type: "string",
+            description: "Project to file it under. Default 'default'."
+        }
+    },
+    required: ["name"]
+};
+export const createTimelineSpec = {
+    name: "create_timeline",
+    description: "Create an empty timeline sequence and return its id. This is the first " +
+        "step of cutting one headlessly: create it, then add tracks and clips " +
+        "with edit_timeline. Reach for it rather than editing a sequence the " +
+        "user already has open — and rather than a storyboard or script " +
+        "assemble, which build a timeline only out of media they rendered " +
+        "themselves. Vertical is width 1080, height 1920.",
+    inputSchema: CREATE_TIMELINE_SCHEMA,
+    category: "write",
+    userMessage: (params) => {
+        const name = params["name"];
+        return isString(name) && name.trim()
+            ? `Creating timeline ${name}`
+            : "Creating timeline";
+    }
+};
+export const getTimelineSpec = {
+    name: "get_timeline",
+    description: "Read a saved timeline sequence: its fps, size, duration, tracks, clips " +
+        "and markers. This is the stored document edit_timeline writes and " +
+        "validate_timeline checks — read it before editing so clip and track ids " +
+        "come from the sequence rather than a guess.",
+    inputSchema: GET_TIMELINE_SCHEMA,
+    category: "read",
+    userMessage: (params) => `Reading timeline ${String(params["timeline_id"])}`
+};
+export const listTimelineVersionsSpec = {
+    name: "list_timeline_versions",
+    description: "List a timeline sequence's snapshots, newest first: version number, " +
+        "name, save type ('manual', 'autosave', 'restore'), render settings, and " +
+        "when it was taken. Call this before restoring — restore_timeline_version " +
+        "addresses a snapshot by its version number.",
+    inputSchema: LIST_TIMELINE_VERSIONS_SCHEMA,
+    category: "read",
+    userMessage: (params) => `Listing versions of timeline ${String(params["timeline_id"])}`
+};
+export const getTimelineVersionSpec = {
+    name: "get_timeline_version",
+    description: "Read one snapshot of a timeline sequence without restoring it: the " +
+        "version's metadata plus the full document it stored. Use this to inspect " +
+        "or compare versions before deciding which one to restore.",
+    inputSchema: GET_TIMELINE_VERSION_SCHEMA,
+    category: "read",
+    userMessage: (params) => `Reading v${String(params["version"])} of timeline ${String(params["timeline_id"])}`
+};
+export const createTimelineVersionSpec = {
+    name: "create_timeline_version",
+    description: "Snapshot a timeline sequence's current document as a manual version, so " +
+        "it can be restored later. Manual snapshots are never pruned (autosaves " +
+        "are), so take one before an edit the user may want undone. Returns the " +
+        "new version's number.",
+    inputSchema: CREATE_TIMELINE_VERSION_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Snapshotting timeline ${String(params["timeline_id"])}`
+};
+export const restoreTimelineVersionSpec = {
+    name: "restore_timeline_version",
+    description: "Roll a timeline sequence's document and render settings back to one of " +
+        "its snapshots, addressed by version number (from " +
+        "list_timeline_versions). The state being overwritten is snapshotted " +
+        "first, so the restore is itself undoable — restore that snapshot to come " +
+        "back. An old document is restored against today's schema, so the result " +
+        "is validated afterwards and the findings are returned with it.",
+    inputSchema: RESTORE_TIMELINE_VERSION_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Restoring timeline ${String(params["timeline_id"])} to v${String(params["version"])}`
+};
+export const DELETE_TIMELINE_VERSION_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id."
+        },
+        version: {
+            type: "number",
+            description: "Version number to delete, from list_timeline_versions."
+        }
+    },
+    required: ["timeline_id", "version"]
+};
+export const deleteTimelineVersionSpec = {
+    name: "delete_timeline_version",
+    description: "Delete one snapshot of a timeline sequence you own, addressed by " +
+        "version number (from list_timeline_versions). This cannot be undone. " +
+        "The live sequence is not changed.",
+    inputSchema: DELETE_TIMELINE_VERSION_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Deleting v${String(params["version"])} of timeline ${String(params["timeline_id"])}`
+};
+export const editTimelineSpec = {
+    name: "edit_timeline",
+    description: "Edit a saved timeline sequence headlessly: add tracks, add text, " +
+        "shape and 3D-model clips, split, trim, move, duplicate and delete " +
+        "clips, set a 3D clip's camera, animation and lighting with " +
+        "set_model3d_style, set clip " +
+        "params and workflow bindings, group clips under a shared transform, " +
+        "set transitions, masks, mattes and effect chains, and animate clips " +
+        "with presets or keyframed custom curves. It also drives the guided video " +
+        "flow: set_setup writes the brief and stage, plan_beats writes the beat " +
+        "plan (text only — no clip, no job), update_beat edits one row, and " +
+        "generate_from_beats turns the plan into clips. Pass a " +
+        "list of at most 60 operations per call; they run in order against the stored document and " +
+        "the result is saved. An open editor picks the change up live. Call " +
+        "list_timelines to find a sequence and validate_timeline afterwards. " +
+        "Inspect failed and each operation's ok field before dependent edits. " +
+        "A partial batch may already have saved successful operations. Before rendering, " +
+        "read get_timeline and verify clip count, source ranges, start times and total duration " +
+        "against the intended cut. Validation alone does not prove the edits landed. " +
+        "Use render_storyboard_clips or a workflow run to generate media — this " +
+        "tool authors the cut, it does not render.",
+    inputSchema: EDIT_TIMELINE_SCHEMA,
+    category: "write",
+    userMessage: (params) => {
+        const count = Array.isArray(params["ops"]) ? params["ops"].length : 0;
+        const id = params["timeline_id"];
+        const target = typeof id === "string" && id ? ` ${id}` : "";
+        return `Editing timeline${target} (${count} ${count === 1 ? "op" : "ops"})`;
+    }
+};
+export const SET_TIMELINE_DOCUMENT_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence id (from list_timelines)."
+        },
+        document: {
+            type: "object",
+            description: "The whole document to store: {tracks, clips, markers, transcript?, " +
+                "scriptEnabled?, camera2d?}. Set camera2d to null to clear the camera. It replaces the stored one field for field, so " +
+                "anything you leave out is dropped — read the current document with " +
+                "get_timeline and send it back changed, rather than sending only the " +
+                "part you edited. `markers` may be omitted and defaults to an empty " +
+                "list. A midi track's `instrument: {preset: \"<id>\"}` and a " +
+                "typewriter animation's plain `durationMs` resolve as the " +
+                "edit_timeline ops resolve them."
+        },
+        fps: {
+            type: "number",
+            description: "Frame rate to store with the sequence. Omit to keep the current one."
+        },
+        width: {
+            type: "number",
+            description: "Render width. Omit to keep the current one."
+        },
+        height: {
+            type: "number",
+            description: "Render height. Omit to keep the current one."
+        },
+        expected_updated_at: {
+            type: "string",
+            description: "The `updated_at` the document was read at. When it no longer " +
+                "matches the stored row the write is refused as a conflict instead " +
+                "of overwriting whoever changed it in between."
+        },
+        snapshot_name: {
+            type: "string",
+            description: "Label for the snapshot taken before the write, e.g. 'before the " +
+                "title pass'."
+        }
+    },
+    required: ["timeline_id", "document"]
+};
+export const setTimelineDocumentSpec = {
+    name: "set_timeline_document",
+    description: "Write a whole timeline document at once — every track, clip, marker and " +
+        "animation in one call, instead of a script of edit_timeline ops. Reach " +
+        "for it when you are authoring a cut from scratch or restructuring one " +
+        "wholesale; edit_timeline stays the better tool for a few targeted " +
+        "changes to a cut that already exists. The document is validated before " +
+        "anything is written: errors refuse the write and come back as issues, " +
+        "so a document that would not render never reaches the sequence. The " +
+        "state it replaces is snapshotted as a manual version first, so the " +
+        "write is undoable with restore_timeline_version, and the validation of " +
+        "what actually landed is returned with the result.",
+    inputSchema: SET_TIMELINE_DOCUMENT_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Writing the document of timeline ${String(params["timeline_id"])}`
+};
+export const validateTimelineSpec = {
+    name: "validate_timeline",
+    description: "Statically validate a timeline sequence WITHOUT rendering or playing it: " +
+        "clips on tracks the document lacks, duplicate ids, overlapping clips, " +
+        "fades and transitions longer than the clip, in/out points that cannot " +
+        "render, unknown animation presets, incomplete bindings, and fields a " +
+        "schema round trip would strip. Pass an inline `document` to check one you " +
+        "are building, or `timeline_id` to validate a saved sequence. Run it after " +
+        "timeline edits and before rendering. Pass tier: \"showcase\" for structural warnings about scene-group count, custom animations per visible second, effect variety, clip density, fast motion without blur, finish and camera depth. Each gap names a shipped example. Warnings do not change ok and cannot certify aesthetic quality.",
+    inputSchema: VALIDATE_TIMELINE_SCHEMA,
+    category: "read",
+    userMessage: (params) => params["timeline_id"]
+        ? `Validating timeline ${params["timeline_id"]}`
+        : "Validating timeline document"
+};
+/** Largest previewed frame edge. Bigger costs bytes and shows nothing more. */
+export const MAX_PREVIEW_WIDTH = 1280;
+/** Default previewed frame width — legible without being expensive. */
+export const DEFAULT_PREVIEW_WIDTH = 640;
+/** Most timecodes one call renders. */
+export const MAX_PREVIEW_TIMES = 8;
+/** Frames rendered when the caller names no timecodes. */
+export const DEFAULT_PREVIEW_COUNT = 3;
+/**
+ * Most frames a `range` samples. Higher than `MAX_PREVIEW_TIMES` because a
+ * dense sweep is read as one contact sheet: the cost is one image handle and
+ * one read, not one per timecode.
+ */
+export const MAX_PREVIEW_RANGE_COUNT = 24;
+/** Widest contact sheet. Past this the cells are too small to read anyway. */
+export const MAX_SHEET_WIDTH = 1280;
+/** Frame width a compare renders at, so a pair fits a cell of the sheet. */
+export const DEFAULT_COMPARE_WIDTH = 320;
+/**
+ * Documented ceiling on previewed motion-blur samples. The render clamps to
+ * `MAX_MOTION_BLUR_SAMPLES` in `@nodetool-ai/timeline/scene`; this states the
+ * same number without importing it, because this file is the eager spec table
+ * and pulls in no implementation.
+ */
+export const MAX_PREVIEW_BLUR_SAMPLES = 32;
+/** The film convention: the shutter is open for half of each frame. */
+export const DEFAULT_PREVIEW_SHUTTER_ANGLE = 180;
+export const PREVIEW_TIMELINE_FRAME_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence to render. Omit when passing an inline `document`."
+        },
+        document: {
+            type: "object",
+            description: "An inline timeline document ({tracks, clips, markers}) to render " +
+                "instead of a saved sequence. Needs `width`, `height` and `fps` " +
+                "unless they are on the document."
+        },
+        times_ms: {
+            type: "array",
+            items: { type: "number" },
+            description: `Absolute timeline positions to render, in milliseconds. Up to ` +
+                `${MAX_PREVIEW_TIMES}. Omit to sample evenly across the sequence.`
+        },
+        count: {
+            type: "number",
+            description: `How many evenly spaced frames to render when times_ms is omitted. ` +
+                `Default 3, max ${MAX_PREVIEW_TIMES}.`
+        },
+        range: {
+            type: "object",
+            properties: {
+                from_ms: { type: "number" },
+                to_ms: { type: "number" },
+                count: { type: "number" }
+            },
+            description: `Sweep a window instead of naming timecodes: count frames evenly ` +
+                `spaced from from_ms to to_ms, both ends included. Up to ` +
+                `${MAX_PREVIEW_RANGE_COUNT} — more than times_ms allows, because a ` +
+                `sweep is meant to be read as one sheet. Refused together with ` +
+                `times_ms.`
+        },
+        sheet: {
+            type: "boolean",
+            description: `Tile every frame into one image, each cell labelled with its ` +
+                `timecode, instead of one image per frame. One handle to view, and ` +
+                `the layer report of each frame comes back unchanged. Up to ` +
+                `${MAX_SHEET_WIDTH}px wide.`
+        },
+        width: {
+            type: "number",
+            description: `Frame width in pixels; the height follows the sequence aspect. ` +
+                `Default ${DEFAULT_PREVIEW_WIDTH}, max ${MAX_PREVIEW_WIDTH}.`
+        },
+        motion_blur_samples: {
+            type: "number",
+            description: `Average this many sub-frame instants into each frame, so fast ` +
+                `motion smears the way a render with motion blur on will. 1 (the ` +
+                `default) is off; max ${MAX_PREVIEW_BLUR_SAMPLES}. Each sample ` +
+                `composites the whole frame again.`
+        },
+        shutter_angle: {
+            type: "number",
+            description: `How far the shutter opens, in degrees of one frame. ` +
+                `${DEFAULT_PREVIEW_SHUTTER_ANGLE} is the film convention (open for ` +
+                `half the frame); 360 smears across the whole frame. Ignored unless ` +
+                `motion_blur_samples is above 1.`
+        }
+    },
+    required: []
+};
+export const previewTimelineFrameSpec = {
+    name: "preview_timeline_frame",
+    description: "Render what a timeline actually LOOKS LIKE at up to 8 chosen timecodes " +
+        "per call — the composited frame, with every track layered in order, clip transforms " +
+        "and opacity applied, animations sampled mid-flight, transitions part " +
+        "way through, and text and shape clips drawn. This is the tool that " +
+        "answers 'is the title readable', 'does the lower-third cover the " +
+        "face', 'is the fade halfway at 2s'. Returns one image handle per " +
+        "timecode (call view_image on one to see the pixels) plus, for each " +
+        "frame, the layers in composite order with their opacity, blend mode " +
+        "and wipe progress. A frame's `degraded` list names where this " +
+        "compositor drew something the export will draw differently — a " +
+        "feathered mask or wipe drawn as a hard edge, a track matte skipped, a " +
+        "group's blend mode lost, a second drop shadow not cast, brightness " +
+        "applied as a multiply instead of the export's addition — each with the " +
+        "clip it happened to; " +
+        "`effects_not_applied` names the effect types it cannot draw at all. " +
+        "`complete` is false when a layer is skipped, the preview is degraded, " +
+        "an effect is omitted or a font falls back. A missing 3D renderer is " +
+        "reported as model3d_unavailable. Never verify the complete composition " +
+        "from an incomplete frame. Unlike get_clip_frames, which samples one clip's " +
+        "source media, this composites the sequence. The 2D path needs no browser, " +
+        "GPU or open editor; 3D layers need headless Chromium. Sample the middle of an animation, not its endpoints — " +
+        "the endpoints are the states you already know. `range` sweeps a window " +
+        "densely and `sheet` returns the sweep as one labelled contact sheet, " +
+        "which is how you watch a move play out rather than checking one instant.",
+    inputSchema: PREVIEW_TIMELINE_FRAME_SCHEMA,
+    category: "read",
+    userMessage: (params) => params["timeline_id"]
+        ? `Rendering frames of timeline ${String(params["timeline_id"])}`
+        : "Rendering timeline frames"
+};
+/** The three ways either side of a comparison names a timeline. */
+const COMPARE_SIDE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "A saved sequence."
+        },
+        version: {
+            type: "number",
+            description: "With timeline_id, the snapshot of that number rather than the " +
+                "sequence as it stands now (from list_timeline_versions)."
+        },
+        document: {
+            type: "object",
+            description: "An inline document ({tracks, clips, markers})."
+        }
+    }
+};
+export const COMPARE_TIMELINE_FRAMES_SCHEMA = {
+    type: "object",
+    properties: {
+        a: {
+            ...COMPARE_SIDE_SCHEMA,
+            description: "The baseline side. A bare timeline id string works too. " +
+                "{timeline_id}, {timeline_id, version} or {document}."
+        },
+        b: {
+            ...COMPARE_SIDE_SCHEMA,
+            description: "The side to compare against the baseline. Same three forms as `a`."
+        },
+        times_ms: {
+            type: "array",
+            items: { type: "number" },
+            description: `Absolute timeline positions to compare, in milliseconds. Up to ` +
+                `${MAX_PREVIEW_RANGE_COUNT}. Omit for an even sweep of the cut.`
+        },
+        range: {
+            type: "object",
+            properties: {
+                from_ms: { type: "number" },
+                to_ms: { type: "number" },
+                count: { type: "number" }
+            },
+            description: `count frames evenly spaced from from_ms to to_ms, both ends ` +
+                `included. Up to ${MAX_PREVIEW_RANGE_COUNT}. Refused together with ` +
+                `times_ms.`
+        },
+        width: {
+            type: "number",
+            description: `Width of each rendered frame; a pair sits side by side in one cell ` +
+                `of the sheet. Default ${DEFAULT_COMPARE_WIDTH}.`
+        }
+    },
+    required: ["a", "b"]
+};
+export const compareTimelineFramesSpec = {
+    name: "compare_timeline_frames",
+    description: "Measure what actually changed between two timelines — two documents, " +
+        "two sequences, or a sequence and one of its snapshots — by " +
+        "compositing both at the same timecodes and differencing the pixels. " +
+        "Each frame comes back with a mean absolute difference from 0 (nothing " +
+        "moved) to 1, and one side-by-side contact sheet shows the pairs. Run " +
+        "it after a change nobody asked for — a restructure, a composition " +
+        "insert, a snap pass — so you can say which frames it touched instead " +
+        "of hoping it touched none. A difference of 0 everywhere is the proof " +
+        "an edit was cosmetic when complete is true; a difference at times you " +
+        "did not expect is the regression. Incomplete previews return null " +
+        "difference scores and aggregate metrics, with skipped layers and " +
+        "degradations for each side. They cannot establish visual equivalence.",
+    inputSchema: COMPARE_TIMELINE_FRAMES_SCHEMA,
+    category: "read",
+    userMessage: () => "Comparing timeline frames"
+};
+/**
+ * Longest a `wait: true` render blocks before handing back the job id.
+ *
+ * Half of the CodeAct action budget (`DEFAULT_CODEACT_ACTION_TIMEOUT_MS`,
+ * 600_000 in `codeact/codeact-executor.ts`), which is the clock a
+ * `render_timeline` call inside `execute_code` actually runs against. A wait
+ * at or near that budget loses the race: the sandbox aborts the action first
+ * and the caller gets the sandbox's `Execution cancelled` instead of the
+ * render's own message. Staying well below it means this capability always
+ * reports its own timeout, with the job id to come back to.
+ */
+export const MAX_RENDER_TIMEOUT_MS = 5 * 60_000;
+/** How long `wait: true` waits when the caller names no timeout. */
+export const DEFAULT_RENDER_TIMEOUT_MS = 3 * 60_000;
+export const RENDER_TIMELINE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "Timeline sequence to render (from list_timelines)."
+        },
+        format: {
+            type: "string",
+            description: "Container to write: 'mp4' (default), 'webm', 'mov', or " +
+                "'png_sequence' (frames zipped with a manifest). Only webm, mov and " +
+                "png_sequence carry alpha."
+        },
+        alpha: {
+            type: "boolean",
+            description: "Keep transparency instead of compositing onto black. Refused with " +
+                "an mp4."
+        },
+        video_codec: {
+            type: "string",
+            description: "Video codec, when the container allows more than one. Omit for the " +
+                "format's default."
+        },
+        bitrate: {
+            type: ["string", "number"],
+            description: "Target video bitrate: bits per second as a number, or a string with " +
+                "a k/M suffix ('8M', '800k'). Omit for the encoder's default."
+        },
+        motion_blur_samples: {
+            type: "number",
+            description: "Sub-frame samples averaged per frame. 1 (default) is no blur; 8 is " +
+                "a smooth smear and costs 8x the render time."
+        },
+        shutter_angle: {
+            type: "number",
+            description: "Fraction of the frame the shutter is open, in degrees (180 = half " +
+                "the frame). Only read when motion_blur_samples is above 1."
+        },
+        preview_scale: {
+            type: "number",
+            description: "Render at this fraction of the sequence size. 0.5 is roughly a " +
+                "quarter of the time — use it for the drafts you look at, then " +
+                "render at 1 once the cut is right."
+        },
+        include_audio: {
+            type: "boolean",
+            description: "Mix audio-track clips into the render. Default true."
+        },
+        wait: {
+            type: "boolean",
+            description: "Block until the render settles and return the finished asset. " +
+                "Default false: the call returns a job_id immediately and get_job " +
+                "reports it."
+        },
+        timeout_ms: {
+            type: "number",
+            description: `How long to wait when wait is true. Default ` +
+                `${DEFAULT_RENDER_TIMEOUT_MS}, and anything higher is clamped to ` +
+                `${MAX_RENDER_TIMEOUT_MS} — a longer block is killed by the ` +
+                `surrounding action budget before this call can report anything. ` +
+                `On a timeout the render keeps going and the job_id comes back ` +
+                `anyway: poll get_job, or render a draft with preview_scale below 1.`
+        }
+    },
+    required: ["timeline_id"]
+};
+export const renderTimelineSpec = {
+    name: "render_timeline",
+    description: "Render a timeline sequence to a video file — the finished cut, " +
+        "composited exactly as the editor previews it, with audio mixed in. " +
+        "Runs as a job, so `get_job` and `get_job_logs` report on it and " +
+        "`cancel_job` stops it. With `wait` it blocks and hands back the " +
+        "rendered asset. Render before you say a cut is done, then look at what " +
+        "came out: `preview_timeline_frame` answers what one timecode looks " +
+        "like, `analyze_video` measures the file, and `understand_video` " +
+        "describes it. `preview_scale` renders a draft at a fraction of the " +
+        "size while you are still iterating.",
+    inputSchema: RENDER_TIMELINE_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Rendering timeline ${String(params["timeline_id"])}`
+};
+// ---------------------------------------------------------------------------
+// bake_audio_animation
+// ---------------------------------------------------------------------------
+export const DEFAULT_BAKE_ATTACK_MS = 20;
+export const DEFAULT_BAKE_RELEASE_MS = 150;
+export const DEFAULT_BAKE_TOLERANCE = 0.01;
+/** Keyframes one bake writes. Well under the curve cap, and readable in the UI. */
+export const DEFAULT_BAKE_MAX_POINTS = 240;
+/** Hard ceiling on `max_points`, matching the engine's per-curve limit. */
+export const MAX_BAKE_POINTS = 4096;
+/** Seconds of audio one bake decodes before it reports truncation. */
+export const DEFAULT_BAKE_MAX_SECONDS = 120;
+export const BAKE_AUDIO_ANIMATION_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: { type: "string", description: "Timeline sequence id." },
+        audio_clip_id: {
+            type: "string",
+            description: "The clip whose audio is measured — id, name, or \"selected\". Only " +
+                "the stretch it actually plays (its in-point to its out-point) is " +
+                "analyzed."
+        },
+        target_clip_id: {
+            type: "string",
+            description: "The clip the curve is written onto — id, name, or \"selected\". It " +
+                "may be the audio clip itself."
+        },
+        property: {
+            type: "string",
+            enum: ["scale", "opacity", "offsetX", "offsetY"],
+            description: "Channel the curve drives."
+        },
+        mode: {
+            type: "string",
+            enum: ["envelope", "beats"],
+            description: "'envelope' follows the loudness continuously; 'beats' puts one " +
+                "pulse on each detected onset and rests between them. Default " +
+                "'envelope'."
+        },
+        output_range: {
+            type: "array",
+            items: { type: "number" },
+            description: "[quiet, loud] — the property's value at the bottom and top of the " +
+                "measured range, e.g. [1, 1.12] for scale or [0.6, 1] for opacity."
+        },
+        sensitivity: {
+            type: "number",
+            description: "Envelope mode. The measured range is the quietest to the loudest " +
+                "frame; sensitivity divides its top, so 2 reaches the loud end of " +
+                "output_range at half the loudest level and 0.5 needs twice it. " +
+                "Default 1 (the full measured range)."
+        },
+        attack_ms: {
+            type: "number",
+            description: `Rise time. Default ${DEFAULT_BAKE_ATTACK_MS}.`
+        },
+        release_ms: {
+            type: "number",
+            description: `Fall time. Default ${DEFAULT_BAKE_RELEASE_MS}.`
+        },
+        offset_ms: {
+            type: "number",
+            description: "Shift the whole curve along the timeline, in ms. Negative moves the " +
+                "motion earlier. Default 0."
+        },
+        tolerance: {
+            type: "number",
+            description: "How far a point may sit off the line through its neighbours before " +
+                "it is kept, in the property's own units. Peaks survive whatever it " +
+                `is set to. Default ${DEFAULT_BAKE_TOLERANCE}.`
+        },
+        max_points: {
+            type: "number",
+            description: `Keyframes to write at most. Default ${DEFAULT_BAKE_MAX_POINTS}, ceiling ${MAX_BAKE_POINTS}.`
+        },
+        frame_ms: {
+            type: "number",
+            description: "Analysis frame hop in ms. Default 20."
+        },
+        max_seconds: {
+            type: "number",
+            description: "Seconds of audio to decode. A window longer than this is analyzed " +
+                `as far as the cap allows and reported as truncated. Default ${DEFAULT_BAKE_MAX_SECONDS}.`
+        },
+        replace: {
+            type: "boolean",
+            description: "Default true: overwrite the curve an earlier audio bake left on " +
+                "this property. False appends beside it."
+        }
+    },
+    required: ["timeline_id", "audio_clip_id", "target_clip_id", "property", "output_range"]
+};
+export const bakeAudioAnimationSpec = {
+    name: "bake_audio_animation",
+    description: "Drive a clip's motion from a piece of audio: measure the audio clip, " +
+        "turn what it measured into keyframes, and write them onto the target " +
+        "clip as one custom animation. 'envelope' follows the loudness so a " +
+        "layer breathes with the music; 'beats' puts a pulse on each onset so it " +
+        "hits with the track. The keyframes are placed in the target clip's own " +
+        "media, so trimming or splitting it re-slices the motion instead of " +
+        "stretching it, and the animation carries `bakedFrom` — re-running with " +
+        "different settings replaces that curve rather than stacking another " +
+        "one. A curve someone keyframed by hand is never touched. Use " +
+        "set_markers_from_beats instead when you want to cut to the beat rather " +
+        "than animate to it.",
+    inputSchema: BAKE_AUDIO_ANIMATION_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Baking ${String(params["property"])} from audio onto ${String(params["target_clip_id"])}`
+};
+// ---------------------------------------------------------------------------
+// isolate_subject
+// ---------------------------------------------------------------------------
+/**
+ * The provider identity and the two enums live here, with the schema that
+ * advertises them, rather than beside the runner in
+ * `timeline-isolate-subject.ts`: this file is the eager half of the module and
+ * imports nothing heavy, and a second copy of an enum is a second thing to get
+ * wrong.
+ */
+export const ISOLATE_SUBJECT_ENDPOINT = "fal-ai/birefnet/v2/video";
+/** The node that calls it, resolved from the run's registry. */
+export const ISOLATE_SUBJECT_NODE_TYPE = "fal.video_to_video.BiRefNetV2Video";
+export const ISOLATE_SUBJECT_PROVIDER = "fal";
+/** The endpoint's `model` enum, as it spells the values. */
+export const ISOLATE_SUBJECT_MODELS = [
+    "General Use (Light)",
+    "General Use (Light 2K)",
+    "General Use (Heavy)",
+    "Matting",
+    "Portrait",
+    "General Use (Dynamic)"
+];
+export const DEFAULT_ISOLATE_SUBJECT_MODEL = "General Use (Light)";
+/** `2304x2304` is only accepted by the dynamic model, which the endpoint enforces. */
+export const ISOLATE_SUBJECT_RESOLUTIONS = [
+    "1024x1024",
+    "2048x2048",
+    "2304x2304"
+];
+export const DEFAULT_ISOLATE_SUBJECT_RESOLUTION = "1024x1024";
+export const ISOLATE_SUBJECT_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: { type: "string", description: "Timeline sequence id." },
+        clip_id: {
+            type: "string",
+            description: 'The video clip to cut the subject out of — id, name, or "selected". ' +
+                "The matte is carried on that clip, so trimming, splitting or moving " +
+                "it keeps the cutout aligned with no second clip to keep in sync."
+        },
+        model: {
+            type: "string",
+            enum: [...ISOLATE_SUBJECT_MODELS],
+            description: `Segmentation model. Default "${DEFAULT_ISOLATE_SUBJECT_MODEL}" — ` +
+                '"Matting" for hair and soft edges, "Portrait" for people.'
+        },
+        operating_resolution: {
+            type: "string",
+            enum: [...ISOLATE_SUBJECT_RESOLUTIONS],
+            description: `Resolution the segmentation runs at. Default "${DEFAULT_ISOLATE_SUBJECT_RESOLUTION}". ` +
+                'Higher is more accurate on high-res footage; "2304x2304" needs the ' +
+                'dynamic model.'
+        },
+        refine_foreground: {
+            type: "boolean",
+            description: "Refine the foreground against the estimated mask. Default true."
+        },
+        regenerate: {
+            type: "boolean",
+            description: "Default false: a clip that already has a ready, current matte gets " +
+                "it back without spending anything. True always runs the provider, " +
+                "keeping the previous result in the version list."
+        },
+        background: {
+            type: "boolean",
+            description: "Start the generation and return a generation_id instead of waiting. " +
+                "Collect it with await_generation, or read the clip back once it settles."
+        }
+    },
+    required: ["timeline_id", "clip_id"]
+};
+export const isolateSubjectSpec = {
+    name: "isolate_subject",
+    description: "Cut the subject out of a video clip and carry the cutout as that clip's " +
+        "own matte, so everything behind it can be replaced. The mask is " +
+        "generated from the clip's whole source and read back at the clip's own " +
+        "source time, which is what lets a later trim, split or speed change " +
+        "keep it aligned. A clip that already has a current cutout is handed it " +
+        "back for free unless `regenerate` is set, and a regenerate that fails " +
+        "leaves the working matte in place. Adjust the result — invert, " +
+        "strength, feather, or an earlier version — with set_generated_matte; " +
+        "use set_matte instead for a keyhole authored from another clip.",
+    inputSchema: ISOLATE_SUBJECT_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Isolating the subject in ${String(params["clip_id"])}`
+};
+// ---------------------------------------------------------------------------
+// track_object
+// ---------------------------------------------------------------------------
+export const TRACK_OBJECT_DIRECTIONS = ["forward", "backward", "both"];
+export const TRACK_OBJECT_SCHEMA = {
+    type: "object",
+    properties: {
+        provider: { type: "string", description: "Provider with executable track_object support. Required for a new run." },
+        model: { type: "string", description: "Tracking model id. Required for a new run." },
+        timeline_id: { type: "string", description: "Timeline sequence id." },
+        clip_id: {
+            type: "string",
+            description: 'The video clip to track a subject through — id, name, or "selected". ' +
+                "The result is carried as a document-level track, not on the clip."
+        },
+        name: {
+            type: "string",
+            description: 'Label for the resulting track, e.g. "Product".'
+        },
+        initial_region: {
+            type: "object",
+            description: "The subject's starting box, normalized 0..1 over the source frame.",
+            properties: {
+                x: { type: "number" },
+                y: { type: "number" },
+                width: { type: "number" },
+                height: { type: "number" }
+            },
+            required: ["x", "y", "width", "height"]
+        },
+        start_ms: {
+            type: "number",
+            description: "Source ms the tracking window starts at."
+        },
+        end_ms: {
+            type: "number",
+            description: "Source ms the tracking window ends at."
+        },
+        direction: {
+            type: "string",
+            enum: [...TRACK_OBJECT_DIRECTIONS],
+            description: 'Which way to track from the initial region. Default "forward".'
+        },
+        track_id: {
+            type: "string",
+            description: "An existing track's id, to regenerate it in place. Absent mints a " +
+                "new track."
+        },
+        regenerate: {
+            type: "boolean",
+            description: "Default false: an existing track named by track_id that is ready " +
+                "and current is handed back without spending anything. True always " +
+                "runs the provider."
+        }
+    },
+    required: ["timeline_id", "clip_id", "initial_region", "start_ms", "end_ms"]
+};
+export const trackObjectSpec = {
+    name: "track_object",
+    description: "Follow a subject through a clip's source, starting from a box you " +
+        "name, and carry the result as a document-level MediaTrack samples list " +
+        "other clips can bind to (bind_to_track). Box-kind tracks only in this " +
+        "build. New runs require provider and model, and are refused before " +
+        "saving or spending unless the provider implements track_object. " +
+        "Samples use absolute source milliseconds. The initial box is at start_ms " +
+        "for forward/both tracking and end_ms for backward tracking.",
+    inputSchema: TRACK_OBJECT_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Tracking a subject through ${String(params["clip_id"])}`
+};
+const NATIVE_MEDIA_TIMELINE_FIELDS = {
+    timeline_id: {
+        type: "string",
+        description: "Saved timeline sequence id."
+    },
+    clip_id: {
+        type: "string",
+        description: "Video or recorded-speech clip id in the saved timeline."
+    },
+    provider: {
+        type: "string",
+        description: "Provider id from find_model."
+    },
+    model: {
+        type: "string",
+        description: "Model id from find_model for the requested task."
+    },
+    request_id: {
+        type: "string",
+        description: "Optional id for the candidate request. One is generated when absent."
+    }
+};
+export const EXPAND_FRAME_SCHEMA = {
+    type: "object",
+    properties: {
+        ...NATIVE_MEDIA_TIMELINE_FIELDS,
+        source_asset_id: {
+            type: "string",
+            description: "Optional source asset pin captured before the call. A mismatch is stale and is refused."
+        },
+        target_aspect_ratio: {
+            type: "string",
+            description: "Target aspect ratio such as 9:16."
+        },
+        padding: {
+            type: "object",
+            properties: {
+                left: { type: "number" },
+                right: { type: "number" },
+                top: { type: "number" },
+                bottom: { type: "number" }
+            },
+            description: "Non-negative generated-side padding. At least one side is required."
+        },
+        prompt: { type: "string" },
+        negative_prompt: { type: "string" },
+        expand_ratio: { type: "number" },
+        resolution: { type: "string" }
+    },
+    required: [
+        "timeline_id",
+        "clip_id",
+        "provider",
+        "model",
+        "target_aspect_ratio",
+        "padding"
+    ]
+};
+export const expandFrameSpec = {
+    name: "expand_frame",
+    description: "Expand a saved video clip with a provider's outpaint_video task. " +
+        "Returns an inactive candidate with the captured source context and " +
+        "provenance. It never changes the accepted take or sequence dimensions.",
+    inputSchema: EXPAND_FRAME_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Expanding frame for ${String(params["clip_id"])} `
+};
+export const UPSCALE_VIDEO_SCHEMA = {
+    type: "object",
+    properties: {
+        ...NATIVE_MEDIA_TIMELINE_FIELDS,
+        source_asset_id: {
+            type: "string",
+            description: "Optional source asset pin captured before the call. A mismatch is stale and is refused."
+        },
+        target_resolution: {
+            type: "string",
+            description: "Target resolution accepted by the selected model."
+        },
+        scale: { type: "number", description: "Optional scale greater than 1." },
+        prompt: { type: "string" },
+        creativity: {
+            type: "number",
+            description: "Optional model creativity from 0 through 1."
+        },
+        seed: { type: "integer" }
+    },
+    required: [
+        "timeline_id",
+        "clip_id",
+        "provider",
+        "model",
+        "target_resolution"
+    ]
+};
+export const upscaleVideoSpec = {
+    name: "upscale_video",
+    description: "Upscale a saved video clip with a provider's upscale_video task. " +
+        "Returns an inactive candidate with explicit provenance. It never changes " +
+        "the accepted take, sequence dimensions, or existing framing.",
+    inputSchema: UPSCALE_VIDEO_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Upscaling ${String(params["clip_id"])} `
+};
+export const VIDEO_TO_AUDIO_SCHEMA = {
+    type: "object",
+    properties: {
+        ...NATIVE_MEDIA_TIMELINE_FIELDS,
+        source_asset_id: {
+            type: "string",
+            description: "Optional source asset pin captured before the call. A mismatch is stale and is refused."
+        },
+        source_duration_ms: {
+            type: "number",
+            description: "Optional source asset duration in milliseconds when the asset catalog is unavailable."
+        },
+        scene_context: {
+            type: "string",
+            description: "Scene, action, and sound context for the selected clip window."
+        }
+    },
+    required: [
+        "timeline_id",
+        "clip_id",
+        "provider",
+        "model",
+        "scene_context"
+    ]
+};
+export const videoToAudioSpec = {
+    name: "video_to_audio",
+    description: "Generate sound from a saved video clip's captured source window and " +
+        "scene context with a video_to_audio task. Returns an aligned inactive " +
+        "audio candidate and never replaces the video's soundtrack or timeline state.",
+    inputSchema: VIDEO_TO_AUDIO_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Generating sound for ${String(params["clip_id"])} `
+};
+export const RECORDED_VOICE_REPLACEMENT_SCHEMA = {
+    type: "object",
+    properties: {
+        ...NATIVE_MEDIA_TIMELINE_FIELDS,
+        source: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: ["clean_speech", "isolated_speech"]
+                },
+                asset_id: { type: "string" },
+                isolation_request_id: { type: "string" }
+            },
+            required: ["kind", "asset_id"]
+        },
+        target: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: ["voice", "reference_audio"]
+                },
+                voice_id: { type: "string" },
+                asset_id: { type: "string" }
+            },
+            required: ["kind"],
+            description: "Target voice object. reference_audio is explicit but refused until supported."
+        },
+        target_current_asset_id: {
+            type: "string",
+            description: "Optional current target asset pin. A mismatch is stale and is refused."
+        },
+        supported_operations: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional adapter declarations used to reject unsupported operations."
+        }
+    },
+    required: [
+        "timeline_id",
+        "clip_id",
+        "provider",
+        "model",
+        "source",
+        "target"
+    ]
+};
+export const recordedVoiceReplacementSpec = {
+    name: "recorded_voice_replacement",
+    description: "Replace recorded speech from an explicit clean_speech or isolated_speech " +
+        "source with a selected voice through audio_to_audio. Returns an inactive " +
+        "audio candidate and immutable provenance without changing the timeline.",
+    inputSchema: RECORDED_VOICE_REPLACEMENT_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Replacing recorded voice for ${String(params["clip_id"])} `
+};
+export const LIP_SYNC_SCHEMA = {
+    type: "object",
+    properties: {
+        ...NATIVE_MEDIA_TIMELINE_FIELDS,
+        source_asset_id: {
+            type: "string",
+            description: "Optional source video asset pin captured before the call. A mismatch is stale and is refused."
+        },
+        replacement_audio: {
+            type: "object",
+            properties: {
+                asset_id: { type: "string" },
+                status: { type: "string", enum: ["candidate", "accepted"] },
+                provenance: {
+                    type: "object",
+                    properties: {
+                        request_id: { type: "string" },
+                        operation: { type: "string" }
+                    }
+                }
+            },
+            required: ["asset_id", "status", "provenance"]
+        },
+        seed: { type: "integer" }
+    },
+    required: [
+        "timeline_id",
+        "clip_id",
+        "provider",
+        "model",
+        "replacement_audio"
+    ]
+};
+export const lipSyncSpec = {
+    name: "lip_sync",
+    description: "Lip-sync a saved video clip to an accepted recorded_voice_replacement " +
+        "audio candidate with a lip_sync task. Returns an inactive video candidate " +
+        "with both source and replacement provenance and never changes accepted state.",
+    inputSchema: LIP_SYNC_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Lip-syncing ${String(params["clip_id"])} `
+};
+export const deleteTimelineSpec = {
+    name: "delete_timeline",
+    description: "Delete a timeline sequence you own, together with its saved version history. " +
+        "This cannot be undone. A timeline sequence belonging to another user is reported " +
+        "as missing.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            timeline_id: {
+                type: "string",
+                description: "The timeline sequence to delete. You must own it."
+            }
+        },
+        required: ["timeline_id"]
+    },
+    category: "write",
+    userMessage: (params) => `Deleting timeline sequence ${params["timeline_id"]}`
+};
+export const getTimelineCodeSpec = {
+    name: "get_timeline_code",
+    description: "The authoring code a timeline was baked from, and per-scene bake status. " +
+        "Returns {code, baked_at, scenes: [{name, group_id, edited}]} — `code` is " +
+        "null when the timeline carries none. `edited` is true when a scene's " +
+        "subtree has changed since the last bake (a hand edit, or an " +
+        "`edit_timeline` op) and a rebake would keep it and report a conflict.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            timeline_id: {
+                type: "string",
+                description: "The timeline to read. You must own it."
+            }
+        },
+        required: ["timeline_id"]
+    },
+    category: "read",
+    userMessage: (params) => `Reading the authoring code for timeline ${String(params["timeline_id"])}`
+};
+export const SET_TIMELINE_CODE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "The timeline to write code onto. You must own it."
+        },
+        code: {
+            type: "string",
+            description: "An @nodetool-ai/sandbox-timeline script: import the pack, build " +
+                "scenes with video()/scene()/series(), call v.save()."
+        },
+        force: {
+            description: "true to overwrite every scene regardless of hand edits, or an " +
+                "array of scene names to force just those.",
+            oneOf: [{ type: "boolean" }, { type: "array", items: { type: "string" } }]
+        },
+        require_match: {
+            type: "boolean",
+            description: "Attach the code only if it bakes to exactly the document saved " +
+                "now; otherwise write nothing and return a warning. v.save() uses " +
+                "this to attach the program it printed."
+        }
+    },
+    required: ["timeline_id", "code"]
+};
+export const setTimelineCodeSpec = {
+    name: "set_timeline_code",
+    description: "Attach or replace a timeline's authoring code, bake it, and merge the " +
+        "result into the document scene by scene: an untouched scene is replaced " +
+        "by the new build, a hand-edited one is kept and reported in `conflicts` " +
+        "(pass `force` to overwrite it anyway). Returns " +
+        "{timeline_id, errors, warnings, conflicts, scenes}.",
+    inputSchema: SET_TIMELINE_CODE_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Setting authoring code on timeline ${String(params["timeline_id"])}`
+};
+export const EDIT_TIMELINE_CODE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "The timeline whose code to edit. You must own it."
+        },
+        edits: {
+            type: "array",
+            description: "Exact-match string replacements applied to the stored code, in " +
+                "order. Each `old` must match exactly once.",
+            items: {
+                type: "object",
+                properties: {
+                    old: { type: "string" },
+                    new: { type: "string" }
+                },
+                required: ["old", "new"]
+            },
+            minItems: 1
+        },
+        force: {
+            oneOf: [{ type: "boolean" }, { type: "array", items: { type: "string" } }]
+        }
+    },
+    required: ["timeline_id", "edits"]
+};
+export const editTimelineCodeSpec = {
+    name: "edit_timeline_code",
+    description: "Edit a timeline's stored authoring code by exact-match string " +
+        "replacement, then bake and merge the result the way set_timeline_code " +
+        "does. Each edit's `old` must match exactly once in the current code — " +
+        "zero or more than one match is refused, naming the count.",
+    inputSchema: EDIT_TIMELINE_CODE_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Editing authoring code on timeline ${String(params["timeline_id"])}`
+};
+export const rebakeTimelineCodeSpec = {
+    name: "rebake_timeline_code",
+    description: "Re-run a timeline's stored authoring code and merge the result into the " +
+        "document, without changing the code itself. Same merge rule as " +
+        "set_timeline_code: an untouched scene is replaced, a hand-edited one is " +
+        "kept and reported in `conflicts` unless `force` names it.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            timeline_id: {
+                type: "string",
+                description: "The timeline to rebake. You must own it."
+            },
+            force: {
+                oneOf: [{ type: "boolean" }, { type: "array", items: { type: "string" } }]
+            }
+        },
+        required: ["timeline_id"]
+    },
+    category: "write",
+    userMessage: (params) => `Rebaking timeline ${String(params["timeline_id"])}`
+};
+export const DETACH_TIMELINE_CODE_SCHEMA = {
+    type: "object",
+    properties: {
+        timeline_id: {
+            type: "string",
+            description: "The timeline to detach scenes on. You must own it."
+        },
+        scenes: {
+            description: "Scene names to stop tracking, or \"all\" to detach every scene and " +
+                "drop the code entirely.",
+            oneOf: [
+                { const: "all" },
+                { type: "array", items: { type: "string" }, minItems: 1 }
+            ]
+        }
+    },
+    required: ["timeline_id", "scenes"]
+};
+export const detachTimelineCodeSpec = {
+    name: "detach_timeline_code",
+    description: "Stop tracking the named scenes (or every scene, with \"all\") against the " +
+        "timeline's authoring code. A detached scene becomes plain hand-edited " +
+        "content: a later rebake never touches it again. \"all\" also drops the " +
+        "stored code itself.",
+    inputSchema: DETACH_TIMELINE_CODE_SCHEMA,
+    category: "write",
+    userMessage: (params) => `Detaching code tracking on timeline ${String(params["timeline_id"])}`
+};
+/** Every spec this module declares, in declaration order. */
+export const timelinesSpecs = [
+    listTimelinesSpec,
+    createTimelineSpec,
+    getTimelineSpec,
+    listTimelineVersionsSpec,
+    getTimelineVersionSpec,
+    createTimelineVersionSpec,
+    restoreTimelineVersionSpec,
+    deleteTimelineVersionSpec,
+    editTimelineSpec,
+    validateTimelineSpec,
+    setTimelineDocumentSpec,
+    previewTimelineFrameSpec,
+    compareTimelineFramesSpec,
+    renderTimelineSpec,
+    bakeAudioAnimationSpec,
+    isolateSubjectSpec,
+    trackObjectSpec,
+    expandFrameSpec,
+    upscaleVideoSpec,
+    videoToAudioSpec,
+    recordedVoiceReplacementSpec,
+    lipSyncSpec,
+    getTimelineCodeSpec,
+    setTimelineCodeSpec,
+    editTimelineCodeSpec,
+    rebakeTimelineCodeSpec,
+    detachTimelineCodeSpec,
+    deleteTimelineSpec
+];
+//# sourceMappingURL=timelines.specs.js.map