@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/capabilities/timeline-audio-bake.js

@@ -0,0 +1,188 @@
+/**
+ * `bake_audio_animation`'s arithmetic: audio measurements in, keyframes on the
+ * animated clip's own clock out.
+ *
+ * Three clocks are involved and conflating any two of them silently offsets
+ * the motion, so each hop is one named function here rather than inline
+ * arithmetic in the capability:
+ *
+ * 1. **Audio source time** — what `analyzeAudioFrames` reports, milliseconds
+ *    into the audio file. The audio clip plays `inPointMs …
+ *    inPointMs + durationMs * rate` of it.
+ * 2. **Timeline time** — where that instant lands in the cut:
+ *    `startMs + (sourceMs - inPointMs) / rate`, the inverse of the rate the
+ *    compositor plays the clip at (`sourceRate`).
+ * 3. **Target source time** — the millisecond of the animated clip's own media
+ *    showing at that timeline instant: `(timelineMs - startMs) * rate +
+ *    inPointMs`, which is `clipSourceMsAt` for a clip with no time remap.
+ *
+ * Both hops are affine and increasing (`sourceRate` floors the rate above
+ * zero), so an ascending series stays ascending and the curve gate never sees
+ * keyframes that go backwards. A time remap on either clip breaks that — the
+ * relation becomes a curve normalized over the clip's window — which is why
+ * the capability refuses one rather than mapping through an inverse that does
+ * not exist.
+ *
+ * Pure: no I/O, no models, no decode.
+ */
+import { sourceRate } from "@nodetool-ai/timeline";
+import { envelopeToKeyframes, simplifyKeyframes } from "@nodetool-ai/timeline";
+/** The source stretch a clip actually plays, in its own media's ms. */
+export function clipSourceWindowMs(clip) {
+    const fromMs = Math.max(0, clip.inPointMs ?? 0);
+    return [fromMs, fromMs + clip.durationMs * sourceRate(clip)];
+}
+/** Where an instant of the audio file lands on the timeline. */
+export function audioSourceMsToTimelineMs(audioClip, sourceMs) {
+    return (audioClip.startMs + (sourceMs - (audioClip.inPointMs ?? 0)) / sourceRate(audioClip));
+}
+/** The target clip's own source ms showing at a timeline instant. */
+export function timelineMsToTargetSourceMs(targetClip, timelineMs) {
+    return ((timelineMs - targetClip.startMs) * sourceRate(targetClip) +
+        (targetClip.inPointMs ?? 0));
+}
+/** The value the segment `a → b` holds at `timelineMs`. */
+function interpolateAt(a, b, timelineMs) {
+    const span = b.timelineMs - a.timelineMs;
+    if (span <= 0)
+        return b.value;
+    return a.value + (b.value - a.value) * ((timelineMs - a.timelineMs) / span);
+}
+/**
+ * Carry a series measured in audio-source time onto the target clip's clock,
+ * clipped to the stretch of timeline the target occupies.
+ *
+ * The clip is geometric, not a filter: the incoming series is already
+ * simplified, so a target can sit between two retained keyframes and still be
+ * fully covered by the motion between them. Each boundary the curve crosses
+ * contributes an interpolated point, and only then are the vertices outside
+ * dropped. Testing membership first instead returned nothing for such a target
+ * — the capability reported "does not overlap" over a curve that spans it —
+ * and turned the ends of a partially-covered target flat.
+ *
+ * A vertex the target never shows is dropped rather than clamped: a source
+ * curve holds its first and last value flat outside its ends, so the retained
+ * motion is the motion the target actually plays, and the validator's
+ * `source_curve_outside_window` stays quiet.
+ */
+export function mapAudioCurveToTarget(points, options) {
+    const { targetClip } = options;
+    const windowStartMs = targetClip.startMs;
+    const windowEndMs = targetClip.startMs + targetClip.durationMs;
+    const timed = points.map((point) => ({
+        timelineMs: audioSourceMsToTimelineMs(options.audioClip, point.timeMs) +
+            options.offsetMs,
+        value: point.value
+    }));
+    const kept = [];
+    for (let index = 0; index < timed.length; index += 1) {
+        const current = timed[index];
+        const previous = index > 0 ? timed[index - 1] : undefined;
+        if (previous) {
+            if (previous.timelineMs < windowStartMs &&
+                current.timelineMs > windowStartMs) {
+                kept.push({
+                    timelineMs: windowStartMs,
+                    value: interpolateAt(previous, current, windowStartMs)
+                });
+            }
+            if (previous.timelineMs < windowEndMs &&
+                current.timelineMs > windowEndMs) {
+                kept.push({
+                    timelineMs: windowEndMs,
+                    value: interpolateAt(previous, current, windowEndMs)
+                });
+            }
+        }
+        if (current.timelineMs >= windowStartMs &&
+            current.timelineMs <= windowEndMs) {
+            kept.push(current);
+        }
+    }
+    return kept.map((point) => ({
+        sourceMs: Math.max(0, timelineMsToTargetSourceMs(targetClip, point.timelineMs)),
+        value: point.value
+    }));
+}
+/**
+ * The loudness curve: the quietest and loudest frames in the analyzed window
+ * become the ends of `outputRange`, so a bake is scaled to the material rather
+ * than to an absolute level a quiet mix would never reach.
+ */
+export function envelopeCurve(frames, options) {
+    if (frames.length === 0)
+        return [];
+    let quietest = Infinity;
+    let loudest = -Infinity;
+    for (const frame of frames) {
+        if (frame.rms < quietest)
+            quietest = frame.rms;
+        if (frame.rms > loudest)
+            loudest = frame.rms;
+    }
+    const sensitivity = options.sensitivity > 0 ? options.sensitivity : 1;
+    const inputRange = [
+        quietest,
+        quietest + (loudest - quietest) / sensitivity
+    ];
+    return envelopeToKeyframes(frames, {
+        attackMs: options.attackMs,
+        releaseMs: options.releaseMs,
+        inputRange,
+        outputRange: options.outputRange,
+        tolerance: options.tolerance,
+        maxPoints: options.maxPoints
+    });
+}
+/** Times this close together are one instant; a curve needs them apart. */
+const EPSILON_MS = 1e-3;
+/**
+ * One pulse per onset: rest, rise over `attackMs` into the onset, fall back
+ * over `releaseMs`.
+ *
+ * Pulses that would overlap are shortened rather than interleaved — a series
+ * whose times went backwards is refused by the curve gate, and an onset inside
+ * the previous pulse's release is one the ear hears as part of it anyway.
+ *
+ * `attackMs: 0` is a step, not a skipped onset. The route and the inspector
+ * both accept zero, and it used to put the rest point *at* the onset, which
+ * the ascending guard then dropped — every onset in the series, leaving a flat
+ * curve between the two resting endpoints. The rest point sits `EPSILON_MS`
+ * before the onset instead, so the times still ascend and the value jumps at
+ * the onset itself.
+ */
+export function beatCurve(onsetsMs, options) {
+    const [lo, hi] = options.outputRange;
+    const [windowStartMs, windowEndMs] = options.windowMs;
+    const points = [{ timeMs: windowStartMs, value: lo }];
+    let lastTimeMs = windowStartMs;
+    for (const onsetMs of [...onsetsMs].sort((a, b) => a - b)) {
+        if (onsetMs <= lastTimeMs || onsetMs > windowEndMs)
+            continue;
+        const riseMs = Math.min(Math.max(onsetMs - Math.max(0, options.attackMs), lastTimeMs + EPSILON_MS), onsetMs - EPSILON_MS);
+        if (riseMs <= lastTimeMs)
+            continue;
+        points.push({ timeMs: riseMs, value: lo });
+        points.push({ timeMs: onsetMs, value: hi });
+        const fallMs = Math.min(onsetMs + Math.max(EPSILON_MS, options.releaseMs), windowEndMs);
+        if (fallMs > onsetMs) {
+            points.push({ timeMs: fallMs, value: lo });
+            lastTimeMs = fallMs;
+        }
+        else {
+            lastTimeMs = onsetMs;
+        }
+    }
+    if (points[points.length - 1].timeMs < windowEndMs) {
+        points.push({ timeMs: windowEndMs, value: lo });
+    }
+    // Only over budget: simplifying a pulse train that already fits would round
+    // off the attacks the mode exists to produce.
+    return points.length > options.maxPoints
+        ? simplifyKeyframes(points, {
+            tolerance: options.tolerance,
+            maxPoints: options.maxPoints
+        })
+        : points;
+}
+//# sourceMappingURL=timeline-audio-bake.js.map

package/dist/capabilities/timeline-audio-bake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-audio-bake.js","sourceRoot":"","sources":["../../src/capabilities/timeline-audio-bake.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/timeline-bake.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `bake_model3d_clip` on the server: the clip's samples, Blender, and the
+ * video asset the clip then plays (design §D6).
+ *
+ * The op in `@nodetool-ai/timeline` decides *whether* a bake may run and what
+ * hash it is stored under; this is the half that needs bytes and a renderer.
+ * It reads the clip's glTF, asks the timeline for one model time and one
+ * camera per output frame, hands both to Blender, and persists the muxed video
+ * as a generation, so a bake shows up in the run's cost and asset trail
+ * exactly like `render_model3d` does. A transparent style is muxed to WebM VP9
+ * `yuva420p` and an opaque one to MP4/H.264, which is the whole difference
+ * between the two bakes on this side.
+ */
+import type { TimelineOpBakeModel3DRequest, TimelineOpBakeModel3DResult } from "@nodetool-ai/timeline/ops";
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+/**
+ * Render one clip and store the result. Throws with the cause named — the op
+ * surfaces it to the caller unchanged.
+ */
+export declare function bakeModel3DClipOnServer(context: ProcessingContext, request: TimelineOpBakeModel3DRequest): Promise<TimelineOpBakeModel3DResult>;
+//# sourceMappingURL=timeline-bake.d.ts.map

package/dist/capabilities/timeline-bake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-bake.d.ts","sourceRoot":"","sources":["../../src/capabilities/timeline-bake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAgBH,OAAO,KAAK,EACV,4BAA4B,EAC5B,2BAA2B,EAC5B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAiB9D;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CA8FtC"}

package/dist/capabilities/timeline-bake.js

@@ -0,0 +1,118 @@
+/**
+ * `bake_model3d_clip` on the server: the clip's samples, Blender, and the
+ * video asset the clip then plays (design §D6).
+ *
+ * The op in `@nodetool-ai/timeline` decides *whether* a bake may run and what
+ * hash it is stored under; this is the half that needs bytes and a renderer.
+ * It reads the clip's glTF, asks the timeline for one model time and one
+ * camera per output frame, hands both to Blender, and persists the muxed video
+ * as a generation, so a bake shows up in the run's cost and asset trail
+ * exactly like `render_model3d` does. A transparent style is muxed to WebM VP9
+ * `yuva420p` and an opaque one to MP4/H.264, which is the whole difference
+ * between the two bakes on this side.
+ */
+import { randomUUID } from "node:crypto";
+import { bakeModel3DClipToVideo, bakeVideoFormat } from "@nodetool-ai/blender-nodes";
+import { animationDurations, parseModel3D } from "@nodetool-ai/model3d";
+import { model3dBakeCameraParams } from "@nodetool-ai/timeline";
+import { computeModel3DBakeSamples } from "@nodetool-ai/timeline/scene";
+import { HostBinaryMissingError, loadMediaRefBytes } from "@nodetool-ai/runtime";
+/**
+ * What a bake renders at. EEVEE at 32 samples is the same trade the render
+ * nodes default to — a bake is the intended look, not a final-frame Cycles
+ * render, and a clip is hundreds of frames rather than one.
+ */
+const BAKE_RENDER = {
+    engine: "eevee",
+    samples: 32,
+    denoise: true,
+    resolutionPercentage: 100
+};
+/** Wall clock for one whole bake: the render loop plus the mux. */
+const BAKE_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * Render one clip and store the result. Throws with the cause named — the op
+ * surfaces it to the caller unchanged.
+ */
+export async function bakeModel3DClipOnServer(context, request) {
+    const { clip, sequence } = request;
+    const assetId = clip.currentAssetId;
+    if (!assetId) {
+        throw new Error(`Clip "${clip.name}" has no glTF asset to bake.`);
+    }
+    const bytes = await loadMediaRefBytes({ uri: `asset://${assetId}`, asset_id: assetId }, context);
+    if (!bytes || bytes.length === 0) {
+        throw new Error(`3D model ${assetId} has no stored bytes to bake.`);
+    }
+    const style = clip.model3dStyle;
+    if (!style) {
+        throw new Error(`Clip "${clip.name}" has no model3dStyle to bake.`);
+    }
+    // The animation lengths are what decides where a looped clip wraps and a
+    // held one clamps, and they come off the glTF's own sampler accessors.
+    const durations = animationDurations(parseModel3D(bytes).json);
+    const samples = computeModel3DBakeSamples(clip, sequence, durations);
+    const cameras = samples.cameras.map((camera) => model3dBakeCameraParams(camera, style, BAKE_RENDER));
+    const bakeRequest = {
+        frameTimes: samples.frameTimes,
+        cameras,
+        width: sequence.width,
+        height: sequence.height,
+        fps: sequence.fps
+    };
+    // Absent leaves every animation playing, which is what a clip that names
+    // none asks for.
+    if (style.animation.clipName !== undefined) {
+        bakeRequest.animationName = style.animation.clipName;
+    }
+    // The asset is named and typed before the render runs, and a transparent
+    // style is a WebM rather than an MP4 — the same choice the mux makes from
+    // the same flag (§D6).
+    const format = bakeVideoFormat(style.background.transparent);
+    const generationId = randomUUID();
+    const generation = await context.runGenerationWith({
+        id: generationId,
+        provider: "blender",
+        capability: "bake_model3d_clip",
+        model: "render_animation",
+        params: {
+            model_id: assetId,
+            clip_id: clip.id,
+            frames: samples.frameTimes.length,
+            fps: sequence.fps,
+            width: sequence.width,
+            height: sequence.height,
+            alpha: style.background.transparent
+        },
+        origin: { surface: "capability", tool_call_id: null },
+        persist: {
+            name: `${clip.name || "clip"}-bake.${format.extension}`,
+            mime: format.mimeType
+        }
+    }, async (_provider, signal) => {
+        try {
+            const baked = await bakeModel3DClipToVideo(context, bytes, bakeRequest, {
+                timeoutMs: BAKE_TIMEOUT_MS,
+                signal
+            });
+            return baked.video;
+        }
+        catch (error) {
+            // A server with neither Blender nor ffmpeg still serves the op and
+            // only fails here; naming the binary is the difference between a fix
+            // and a shrug.
+            if (error instanceof HostBinaryMissingError) {
+                throw new Error(`Could not bake clip "${clip.name}": this server has no ` +
+                    `${error.binary} installed. A bake renders in Blender and muxes ` +
+                    `with ffmpeg, so it needs both on the machine.`);
+            }
+            throw error;
+        }
+    }, { withoutProvider: true });
+    const videoAssetId = generation.assets[0]?.asset_id;
+    if (!videoAssetId) {
+        throw new Error(`The bake of clip "${clip.name}" could not be stored.`);
+    }
+    return { assetId: videoAssetId, jobId: generationId };
+}
+//# sourceMappingURL=timeline-bake.js.map

package/dist/capabilities/timeline-bake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-bake.js","sourceRoot":"","sources":["../../src/capabilities/timeline-bake.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/timeline-isolate-subject.d.ts

@@ -0,0 +1,157 @@
+/**
+ * `isolate_subject`: cut the subject out of a video clip and carry the result
+ * as that clip's generated matte (D2).
+ *
+ * Three things are separated here on purpose, because only one of them costs
+ * money and only one of them can be tested without a provider key:
+ *
+ * 1. {@link isolateSubjectOnClip} — the state machine over one clip. It marks
+ *    the matte in flight, asks the runner for a mask, stores it, applies the
+ *    result, and persists at every step. No models, no HTTP, no node registry:
+ *    everything it cannot do itself arrives on {@link IsolateSubjectDeps}.
+ * 2. {@link falIsolateSubjectRunner} — the provider call, wrapped in the
+ *    generation seam so the run gets a row, a cost receipt and cancellation.
+ * 3. {@link contextMaskStore} — the download, under the media-egress policy,
+ *    and the asset it becomes.
+ *
+ * **The whole source asset is sent, never the clip's window.** The mask video
+ * is read back at the clip's own source time, so its first frame has to be the
+ * source's first frame; a submission trimmed to `clipSourceWindowMs` would
+ * need an offset the document does not carry. That is also why a later trim or
+ * extend of the clip stays inside `sourceRange` and never reads as stale.
+ *
+ * **A failure never loses a working matte.** A clip that already had a ready
+ * result keeps it, selected, with its status back at `ready`; only a clip that
+ * had none is left with a `failed` marker. The user's own knobs — invert,
+ * strength, feather — survive a regenerate too, which is
+ * `applyGeneratedMatteResult`'s rule rather than this module's.
+ */
+import type { NodeRegistry } from "@nodetool-ai/node-sdk";
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import { type ClipGeneratedMatte, type TimelineClip } from "@nodetool-ai/timeline";
+/** The knobs one generation runs with. Recorded on the matte as provenance. */
+export interface IsolateSubjectSettings {
+    model: string;
+    operating_resolution: string;
+    refine_foreground: boolean;
+}
+/** What the runner is asked for: a mask of one whole source asset. */
+export interface IsolateSubjectRunRequest {
+    /** The clip's own `currentAssetId`, sent whole. */
+    sourceAssetId: string;
+    settings: IsolateSubjectSettings;
+}
+/** What the runner answers with. The bytes are somebody else's problem. */
+export interface IsolateSubjectRunResult {
+    /** Where the grayscale mask video can be read from. */
+    maskVideoUrl: string;
+    /** The generation row, so the caller can poll or reconcile it. */
+    generationId?: string;
+    /** What the provider charged, when it or the catalog stated a price. */
+    costUsd?: number;
+}
+/**
+ * The paid half, injected so a test can stand in for it. A fake runner is the
+ * only way to exercise this capability without a provider key.
+ */
+export type IsolateSubjectRunner = (request: IsolateSubjectRunRequest) => Promise<IsolateSubjectRunResult>;
+/** The mask, once it is somewhere the document can name. */
+export interface StoredMask {
+    assetId: string;
+}
+/** Downloads a provider URL and stores it as an asset. */
+export type MaskStore = (maskVideoUrl: string) => Promise<StoredMask>;
+/**
+ * Writes the clip back to wherever the document lives. `false` means the
+ * document moved under the call — a concurrent edit — and nothing was saved.
+ */
+export type PersistClip = (clip: TimelineClip) => Promise<boolean>;
+export interface IsolateSubjectDeps {
+    runner: IsolateSubjectRunner;
+    storeMask: MaskStore;
+    persist: PersistClip;
+}
+export interface IsolateSubjectInput {
+    clip: TimelineClip;
+    settings: IsolateSubjectSettings;
+    /** True runs the provider even when a ready matte is already there. */
+    regenerate: boolean;
+    /**
+     * The source asset's full duration in ms, when the asset row states one.
+     * Absent falls back to the clip's own source window — the generation did
+     * cover that much, so the staleness check stays honest either way.
+     */
+    sourceDurationMs?: number;
+}
+export interface IsolateSubjectOutcome {
+    clip: TimelineClip;
+    status: "ready" | "failed";
+    assetId?: string;
+    generationId?: string;
+    sourceRange: {
+        fromMs: number;
+        toMs: number;
+    };
+    costUsd?: number;
+    /** True when a ready matte was handed back without spending anything. */
+    reused: boolean;
+    /** The generation's own failure. A refusal is `{error}` instead. */
+    error?: string;
+}
+/** A refusal: the call was never worth making. */
+export interface IsolateSubjectRefusal {
+    error: string;
+}
+/**
+ * The clip with its matte marked in flight, keeping the current asset and the
+ * version list intact — the shot goes on showing the cutout it has while the
+ * next one is being cut.
+ *
+ * A clip with no matte yet gets a placeholder whose `assetId` is empty. The
+ * scene model draws a matte only at `status: "ready"`, so an empty id is never
+ * read; what it buys is a field the UI can show a spinner against.
+ */
+export declare function markGeneratedMatteGenerating(clip: TimelineClip, sourceAssetId: string, sourceRange: {
+    fromMs: number;
+    toMs: number;
+}, settings: IsolateSubjectSettings): TimelineClip;
+/**
+ * The clip after a generation failed or was cancelled.
+ *
+ * A previous ready result is put back exactly as it was — the same asset, the
+ * same versions, the same knobs — because a failed regenerate must not cost
+ * the user the matte they were already working with. Only a first attempt
+ * leaves a `failed` marker behind.
+ */
+export declare function generatedMatteAfterFailure(clip: TimelineClip, previous: ClipGeneratedMatte | undefined): TimelineClip;
+/**
+ * Cut the subject out of one clip, or hand back the cutout it already has.
+ *
+ * Refuses — without spending — a clip that is not video and a clip with no
+ * asset. Reuses a ready, non-stale matte unless `regenerate` is set: a matte
+ * whose source asset was replaced under it describes a picture the clip no
+ * longer shows, so reusing that one would be worse than paying again.
+ */
+export declare function isolateSubjectOnClip(deps: IsolateSubjectDeps, input: IsolateSubjectInput): Promise<IsolateSubjectOutcome | IsolateSubjectRefusal>;
+/**
+ * Run the endpoint through its node, inside the generation seam.
+ *
+ * The seam is what makes this a *generation* rather than a call: the row is
+ * open before the provider is reached, `cancel_generation` can abort it, the
+ * FAL node's own `reportFalCost` lands on the receipt, and a request id the
+ * reconciler can settle against the invoice is recorded either way. The node
+ * holds the API key, so the seam runs `withoutProvider`.
+ *
+ * The mask is the point of the call, so a result without one is an error
+ * rather than a silent no-matte success.
+ */
+export declare function falIsolateSubjectRunner(context: ProcessingContext, registry: NodeRegistry, generationId: string): IsolateSubjectRunner;
+/**
+ * Download the provider's mask and store it as an asset.
+ *
+ * `fetchExternalMedia` is the one door a provider-chosen URL leaves through —
+ * https to a public host, every redirect hop re-checked — because the URL in a
+ * provider's response body is not this host's to trust.
+ */
+export declare function contextMaskStore(context: ProcessingContext): MaskStore;
+//# sourceMappingURL=timeline-isolate-subject.d.ts.map

package/dist/capabilities/timeline-isolate-subject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline-isolate-subject.d.ts","sourceRoot":"","sources":["../../src/capabilities/timeline-isolate-subject.ts"],"names":[],"mappings":"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"}