fix(agents): clip the audio curve at the target's edges and keep peaks at zero attack

A simplified envelope can have no vertex inside the target window while
still crossing it, so the mapping now inserts interpolated values at the
window's start and end before dropping outside vertices, instead of
reporting no overlap. A zero attack placed the rise at the onset itself
and the guard skipped every beat; the rise now sits one epsilon before
the onset so the peak survives as a step.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013in93XM9r3h7RaFz62YGwN

Author: claude

packages/agents/src/capabilities/timeline-audio-bake.ts

@@ -79,11 +79,36 @@ export interface MapCurveOptions {
   offsetMs: number;
 }
 
+/** One point of the measured curve, carried onto the timeline. */
+interface TimedCurvePoint {
+  timelineMs: number;
+  value: number;
+}
+
+/** The value the segment `a → b` holds at `timelineMs`. */
+function interpolateAt(
+  a: TimedCurvePoint,
+  b: TimedCurvePoint,
+  timelineMs: number
+): number {
+  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,
- * dropping what falls outside the target's own window.
+ * clipped to the stretch of timeline the target occupies.
  *
- * A point the target never shows is dropped rather than clamped: a source
+ * 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.
@@ -95,18 +120,52 @@ export function mapAudioCurveToTarget(
   const { targetClip } = options;
   const windowStartMs = targetClip.startMs;
   const windowEndMs = targetClip.startMs + targetClip.durationMs;
-  const mapped: BakedCurvePoint[] = [];
-  for (const point of points) {
-    const timelineMs =
+  const timed: TimedCurvePoint[] = points.map((point) => ({
+    timelineMs:
       audioSourceMsToTimelineMs(options.audioClip, point.timeMs) +
-      options.offsetMs;
-    if (timelineMs < windowStartMs || timelineMs > windowEndMs) continue;
-    mapped.push({
-      sourceMs: Math.max(0, timelineMsToTargetSourceMs(targetClip, timelineMs)),
-      value: point.value
-    });
+      options.offsetMs,
+    value: point.value
+  }));
+
+  const kept: TimedCurvePoint[] = [];
+  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 mapped;
+
+  return kept.map((point) => ({
+    sourceMs: Math.max(
+      0,
+      timelineMsToTargetSourceMs(targetClip, point.timelineMs)
+    ),
+    value: point.value
+  }));
 }
 
 export interface EnvelopeCurveOptions {
@@ -174,6 +233,13 @@ const EPSILON_MS = 1e-3;
  * 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: readonly number[],
@@ -186,11 +252,11 @@ export function beatCurve(
 
   for (const onsetMs of [...onsetsMs].sort((a, b) => a - b)) {
     if (onsetMs <= lastTimeMs || onsetMs > windowEndMs) continue;
-    const riseMs = Math.max(
-      onsetMs - Math.max(0, options.attackMs),
-      lastTimeMs + EPSILON_MS
+    const riseMs = Math.min(
+      Math.max(onsetMs - Math.max(0, options.attackMs), lastTimeMs + EPSILON_MS),
+      onsetMs - EPSILON_MS
     );
-    if (riseMs >= onsetMs) continue;
+    if (riseMs <= lastTimeMs) continue;
     points.push({ timeMs: riseMs, value: lo });
     points.push({ timeMs: onsetMs, value: hi });
     const fallMs = Math.min(

packages/agents/tests/capabilities-bake-audio-animation.test.ts

@@ -22,6 +22,8 @@ import { createCapabilityRun, UNGATED } from "../src/capabilities/invoke.js";
 import { analyzeAudioFrames } from "../src/capabilities/analysis.js";
 import {
   audioSourceMsToTimelineMs,
+  beatCurve,
+  mapAudioCurveToTarget,
   timelineMsToTargetSourceMs
 } from "../src/capabilities/timeline-audio-bake.js";
 
@@ -190,6 +192,135 @@ describe("the two time hops", () => {
   });
 });
 
+/**
+ * The curve reaching the mapper is already simplified, so "no keyframe inside
+ * the target" is not "no motion over the target". These cases pin the
+ * geometric clip that replaced the membership test.
+ */
+describe("clipping a simplified curve to the target's window", () => {
+  /** 1:1 on the timeline — audio-source ms and timeline ms are one number. */
+  const AUDIO = { startMs: 0, durationMs: 4000 };
+  /** A linear envelope over 0–4000ms, simplified to its two ends. */
+  const RAMP = [
+    { timeMs: 0, value: 1 },
+    { timeMs: 4000, value: 2 }
+  ];
+
+  it("interpolates both boundaries when the target sits between two keyframes", () => {
+    // The reviewer's reproduction: this returned [] before, and the capability
+    // reported "does not overlap" over a ramp that covers the whole target.
+    expect(
+      mapAudioCurveToTarget(RAMP, {
+        audioClip: AUDIO,
+        targetClip: { startMs: 1000, durationMs: 2000 },
+        offsetMs: 0
+      })
+    ).toEqual([
+      { sourceMs: 0, value: 1.25 },
+      { sourceMs: 2000, value: 1.75 }
+    ]);
+  });
+
+  it("clips to one segment of a curve that has interior vertices elsewhere", () => {
+    const curve = [
+      { timeMs: 0, value: 1 },
+      { timeMs: 1000, value: 2 },
+      { timeMs: 3000, value: 3 },
+      { timeMs: 4000, value: 1 }
+    ];
+    // 1500–2500ms falls inside the 1000→3000ms segment, so both ends are
+    // interpolated and no vertex of the curve is retained.
+    expect(
+      mapAudioCurveToTarget(curve, {
+        audioClip: AUDIO,
+        targetClip: { startMs: 1500, durationMs: 1000 },
+        offsetMs: 0
+      })
+    ).toEqual([
+      { sourceMs: 0, value: 2.25 },
+      { sourceMs: 1000, value: 2.75 }
+    ]);
+  });
+
+  it("interpolates the crossed boundary and keeps the rest on a partial overlap", () => {
+    const curve = [
+      { timeMs: 0, value: 1 },
+      { timeMs: 2000, value: 3 },
+      { timeMs: 4000, value: 1 }
+    ];
+    // The target starts mid-curve and outlasts it, so only the start boundary
+    // is crossed and the peak and tail come through as measured.
+    expect(
+      mapAudioCurveToTarget(curve, {
+        audioClip: AUDIO,
+        targetClip: { startMs: 1000, durationMs: 5000 },
+        offsetMs: 0
+      })
+    ).toEqual([
+      { sourceMs: 0, value: 2 },
+      { sourceMs: 1000, value: 3 },
+      { sourceMs: 3000, value: 1 }
+    ]);
+  });
+
+  it("still returns nothing when the curve never reaches the target", () => {
+    expect(
+      mapAudioCurveToTarget(RAMP, {
+        audioClip: AUDIO,
+        targetClip: { startMs: 10000, durationMs: 2000 },
+        offsetMs: 0
+      })
+    ).toEqual([]);
+  });
+});
+
+describe("beatCurve", () => {
+  const ONSETS = [1000, 2000, 3000];
+  const OPTIONS = {
+    releaseMs: 150,
+    outputRange: [1, 1.2] as [number, number],
+    windowMs: [0, 4000] as [number, number],
+    tolerance: 0.01,
+    maxPoints: 4096
+  };
+
+  const peakTimes = (points: readonly { timeMs: number; value: number }[]) =>
+    points.filter((point) => point.value === 1.2).map((point) => point.timeMs);
+
+  it("keeps every peak with a zero attack, as a step into the onset", () => {
+    // Zero attack is what the route and the inspector accept as "no rise";
+    // it used to drop every onset and leave a flat curve.
+    const points = beatCurve(ONSETS, { ...OPTIONS, attackMs: 0 });
+    expect(peakTimes(points)).toEqual(ONSETS);
+
+    for (const onsetMs of ONSETS) {
+      const peak = points.findIndex((point) => point.timeMs === onsetMs);
+      const rest = points[peak - 1]!;
+      expect(rest.value).toBe(1);
+      // Inside a millisecond of the onset: the step is a jump, not a ramp.
+      expect(rest.timeMs).toBeGreaterThan(onsetMs - 1);
+      expect(rest.timeMs).toBeLessThan(onsetMs);
+    }
+    expect(
+      points.every(
+        (point, index) => index === 0 || point.timeMs > points[index - 1]!.timeMs
+      )
+    ).toBe(true);
+    expect(points[0]).toEqual({ timeMs: 0, value: 1 });
+    expect(points[points.length - 1]).toEqual({ timeMs: 4000, value: 1 });
+  });
+
+  it("leaves a non-zero attack untouched: the rise starts attack_ms early", () => {
+    const points = beatCurve(ONSETS, { ...OPTIONS, attackMs: 30 });
+    expect(peakTimes(points)).toEqual(ONSETS);
+    for (const onsetMs of ONSETS) {
+      const peak = points.findIndex((point) => point.timeMs === onsetMs);
+      expect(points[peak - 1]).toEqual({ timeMs: onsetMs - 30, value: 1 });
+      expect(points[peak + 1]).toEqual({ timeMs: onsetMs + 150, value: 1 });
+    }
+  });
+});
+
 describe("bake_audio_animation", () => {
   let bench: Harness | null = null;