@hraness/dawg 0.4.0 → 0.5.0

package/src/agent/section-tools.ts

@@ -0,0 +1,411 @@
+/**
+ * Agent tools for song structure (0.5): `list_sections`, `edit_section`,
+ * `set_form` and `add_transition`. They build the same commands the prompt
+ * runs (src/commands/arrange.ts), so a tool call and `section …` / `form …`
+ * / `build …` agree, and their operations are the score diff.
+ *
+ * Bars here count from 1 like the prompt and the bar ruler; the score and
+ * the SDK store 0-based `startBar`.
+ */
+import { diffScores } from "../../core/diff.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import {
+  arrangedBars,
+  DROP_CUT_MIN,
+  FILL_BEATS_MIN,
+  FILL_STYLES,
+  formatForm,
+  type FillStyle,
+} from "../../core/sections.ts";
+import {
+  applySectionCommand,
+  describeArrangement,
+  type SectionCommand,
+} from "../commands/arrange.ts";
+import type { AgentTool, ToolContext, ToolPlan } from "./tools.ts";
+import { ToolArgumentError } from "./tools.ts";
+
+const SECTION_ACTIONS = [
+  "mark",
+  "add",
+  "duplicate",
+  "move",
+  "rename",
+  "delete",
+  "unmark",
+  "mute",
+  "unmute",
+  "vary",
+  "reset",
+  "loop",
+  "unloop",
+] as const;
+
+type SectionAction = (typeof SECTION_ACTIONS)[number];
+
+const name = {
+  type: "string",
+  minLength: 1,
+  maxLength: 32,
+  description: "Section name: intro, verse, pre, chorus, build, drop, …",
+} as const;
+
+const bar = (description: string) =>
+  ({
+    type: "integer",
+    minimum: 1,
+    maximum: SCORE_LIMITS.maxBars,
+    description,
+  }) as const;
+
+function text(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "")
+    throw new ToolArgumentError(`${field} must be a non-empty string`);
+  return value.trim();
+}
+
+function count(value: unknown, field: string, max: number): number {
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > max
+  )
+    throw new ToolArgumentError(`${field} must be an integer 1..${max}`);
+  return value;
+}
+
+function optionalBar(value: unknown, field: string): number | undefined {
+  return value === undefined
+    ? undefined
+    : count(value, field, SCORE_LIMITS.maxBars) - 1;
+}
+
+function flag(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean")
+    throw new ToolArgumentError(`${field} must be true or false`);
+  return value;
+}
+
+/** Apply a prompt command and turn its result into a score plan. */
+function plan(
+  context: ToolContext,
+  command: SectionCommand,
+): ToolPlan & { kind: "score" } {
+  const result = applySectionCommand(
+    context.score,
+    context.focusedTrackId,
+    command,
+  );
+  if (!result.ok) throw new ToolArgumentError(result.message);
+  return {
+    kind: "score",
+    operations: result.next ? diffScores(context.score, result.next) : [],
+    trackId: context.focusedTrackId,
+    summary: result.message,
+  };
+}
+
+function sectionCommand(args: Record<string, unknown>): SectionCommand {
+  const action = args.action as SectionAction;
+  if (!SECTION_ACTIONS.includes(action))
+    throw new ToolArgumentError(`action must be ${SECTION_ACTIONS.join(", ")}`);
+  if (action === "unloop") return { type: "section-loop" };
+  if (action === "add") {
+    const command: { type: "section-add"; name?: string; bars?: number } = {
+      type: "section-add",
+    };
+    if (args.name !== undefined) command.name = text(args.name, "name");
+    if (args.bars !== undefined)
+      command.bars = count(args.bars, "bars", SCORE_LIMITS.maxBars);
+    return command;
+  }
+  const section = text(args.name, "name");
+  switch (action) {
+    case "mark": {
+      const startBar = optionalBar(args.fromBar, "fromBar");
+      if (startBar === undefined || args.bars === undefined)
+        throw new ToolArgumentError("mark needs fromBar and bars");
+      return {
+        type: "section-mark",
+        name: section,
+        startBar,
+        bars: count(args.bars, "bars", SCORE_LIMITS.maxBars),
+      };
+    }
+    case "duplicate":
+      return args.to === undefined
+        ? { type: "section-dup", name: section }
+        : { type: "section-dup", name: section, as: text(args.to, "to") };
+    case "move": {
+      if (args.toBar !== undefined)
+        return {
+          type: "section-move",
+          name: section,
+          to: { bar: optionalBar(args.toBar, "toBar")! },
+        };
+      if (args.before !== undefined)
+        return {
+          type: "section-move",
+          name: section,
+          to: { before: text(args.before, "before") },
+        };
+      if (args.after !== undefined)
+        return {
+          type: "section-move",
+          name: section,
+          to: { after: text(args.after, "after") },
+        };
+      throw new ToolArgumentError("move needs toBar, before or after");
+    }
+    case "rename":
+      return { type: "section-rename", name: section, to: text(args.to, "to") };
+    case "delete":
+      return { type: "section-delete", name: section };
+    case "unmark":
+      return { type: "section-unmark", name: section };
+    case "mute":
+    case "unmute": {
+      const tracks = Array.isArray(args.tracks) ? args.tracks : undefined;
+      if (
+        !tracks ||
+        tracks.length === 0 ||
+        tracks.some((id) => typeof id !== "string")
+      )
+        throw new ToolArgumentError(`${action} needs tracks: [track ids]`);
+      return {
+        type: "section-mute",
+        name: section,
+        tracks: tracks as string[],
+        muted: action === "mute",
+      };
+    }
+    case "vary": {
+      const command: {
+        type: "section-vary";
+        name: string;
+        track?: string;
+        transpose?: number;
+        gain?: number;
+        off?: boolean;
+      } = { type: "section-vary", name: section };
+      if (args.trackId !== undefined)
+        command.track = text(args.trackId, "trackId");
+      if (args.transpose !== undefined) {
+        if (
+          typeof args.transpose !== "number" ||
+          !Number.isInteger(args.transpose)
+        )
+          throw new ToolArgumentError("transpose must be whole semitones");
+        command.transpose = args.transpose;
+      }
+      if (args.gain !== undefined) {
+        if (typeof args.gain !== "number")
+          throw new ToolArgumentError("gain must be a number 0..2");
+        command.gain = args.gain;
+      }
+      if (args.transpose === undefined && args.gain === undefined)
+        command.off = true;
+      return command;
+    }
+    case "reset":
+      return { type: "section-reset", name: section };
+    case "loop":
+      return { type: "section-loop", name: section };
+  }
+  throw new ToolArgumentError(`unknown action ${String(action)}`);
+}
+
+function transitionCommand(args: Record<string, unknown>): SectionCommand {
+  const section =
+    args.section === undefined ? undefined : text(args.section, "section");
+  const at = optionalBar(args.atBar, "atBar");
+  if (args.type === "build") {
+    const options: Record<string, unknown> = {};
+    if (section !== undefined) options.section = section;
+    if (args.into !== undefined) options.into = text(args.into, "into");
+    if (at !== undefined) options.startBar = at;
+    if (args.bars !== undefined)
+      options.bars = count(args.bars, "bars", SCORE_LIMITS.maxBars);
+    for (const layer of ["riser", "roll", "sweep", "uplifter"] as const) {
+      const value = flag(args[layer], layer);
+      if (value !== undefined) options[layer] = value;
+    }
+    return { type: "build", options };
+  }
+  if (args.type === "drop") {
+    const options: Record<string, unknown> = {};
+    if (section !== undefined) options.section = section;
+    if (at !== undefined) options.bar = at;
+    if (args.cutBeats !== undefined) {
+      if (
+        typeof args.cutBeats !== "number" ||
+        !Number.isFinite(args.cutBeats) ||
+        args.cutBeats < DROP_CUT_MIN
+      )
+        throw new ToolArgumentError(
+          "cutBeats must be a number of beats, 0 up to two bars",
+        );
+      options.cut = args.cutBeats;
+    }
+    const impact = flag(args.impact, "impact");
+    if (impact !== undefined) options.impact = impact;
+    return { type: "drop", options };
+  }
+  if (args.type === "fill") {
+    const options: Record<string, unknown> = {};
+    if (section !== undefined) options.section = section;
+    if (at !== undefined) options.bar = at;
+    if (args.beats !== undefined) {
+      if (
+        typeof args.beats !== "number" ||
+        !Number.isFinite(args.beats) ||
+        args.beats < FILL_BEATS_MIN
+      )
+        throw new ToolArgumentError(
+          `beats must be a number of beats, ${FILL_BEATS_MIN} up to two bars`,
+        );
+      options.beats = args.beats;
+    }
+    if (args.style !== undefined) {
+      if (!FILL_STYLES.includes(args.style as FillStyle))
+        throw new ToolArgumentError(`style must be ${FILL_STYLES.join(", ")}`);
+      options.style = args.style;
+    }
+    const crash = flag(args.crash, "crash");
+    if (crash !== undefined) options.crash = crash;
+    return { type: "fill", options };
+  }
+  throw new ToolArgumentError("type must be build, drop or fill");
+}
+
+export const SECTION_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "list_sections",
+    description:
+      "Show the song's sections (bars count from 1), the form, the looped section and the arranged length.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+    plan(_args, context) {
+      const score = context.score;
+      const sections = score.sections.map((section) => ({
+        name: section.name,
+        fromBar: section.startBar + 1,
+        bars: section.bars,
+        ...(section.mute ? { mute: section.mute } : {}),
+        ...(section.vary ? { vary: section.vary } : {}),
+      }));
+      return {
+        kind: "action",
+        summary: "list sections",
+        run: async () => ({
+          content: JSON.stringify({
+            ok: true,
+            sections,
+            form: formatForm(score.form) || null,
+            loopSection: score.loopSection ?? null,
+            arrangedBars: arrangedBars(score),
+            text: describeArrangement(score),
+          }),
+          summary: `${sections.length} sections`,
+        }),
+      };
+    },
+  },
+  {
+    name: "edit_section",
+    description:
+      "Arrange song sections (named bar ranges; bars count from 1). mark names bars fromBar..fromBar+bars-1 without moving music; add appends empty bars as a new section; duplicate copies a section's music after it; move moves its music (toBar, before or after a section); rename; delete removes its bars and music; unmark drops only the name; mute/unmute silences tracks in it; vary sets a track's transpose (semitones) and gain (0..2) in it (neither: clears); reset clears mutes and variations; loop makes playback cycle it; unloop plays the song.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: [...SECTION_ACTIONS] },
+        name,
+        fromBar: bar("mark: first bar, 1-based"),
+        bars: {
+          type: "integer",
+          minimum: 1,
+          maximum: SCORE_LIMITS.maxBars,
+          description: "mark/add: length in bars (add defaults to 8)",
+        },
+        to: {
+          type: "string",
+          maxLength: 32,
+          description: "rename: new name; duplicate: the copy's name",
+        },
+        toBar: bar("move: the bar the section starts at afterwards"),
+        before: { type: "string", maxLength: 32 },
+        after: { type: "string", maxLength: 32 },
+        tracks: {
+          type: "array",
+          items: { type: "string", maxLength: SCORE_LIMITS.maxIdLength },
+          maxItems: 64,
+        },
+        trackId: {
+          type: "string",
+          maxLength: SCORE_LIMITS.maxIdLength,
+          description: "vary: the track (default: the focused track)",
+        },
+        transpose: { type: "integer", minimum: -24, maximum: 24 },
+        gain: { type: "number", minimum: 0, maximum: 2 },
+      },
+      required: ["action"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      return plan(context, sectionCommand(args));
+    },
+  },
+  {
+    name: "set_form",
+    description:
+      'Set the song form: the order sections play in, with repeats, e.g. "intro verse chorus*2 verse chorus outro" (commas when a name has spaces). Playback and export follow it. An empty string clears it; bake writes the form out as plain bars (sections laid end to end) and clears it.',
+    parameters: {
+      type: "object",
+      properties: {
+        form: { type: "string", maxLength: 1000 },
+        bake: { type: "boolean" },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      if (args.bake === true) return plan(context, { type: "form-bake" });
+      if (typeof args.form !== "string")
+        throw new ToolArgumentError("set_form needs form or bake");
+      return plan(context, {
+        type: "form-set",
+        text: args.form,
+      });
+    },
+  },
+  {
+    name: "add_transition",
+    description: `Generate a transition with the built-in voices (bars count from 1). build: noise riser, accelerating snare roll, filter sweep and uplifter (all on by default), landing on the bar after its range. The range is \`bars\` bars (default 4) just before section \`into\` (the usual build into a drop or chorus); or a section's own bars (its last \`bars\` bars when bars is given); or \`bars\` bars starting at atBar; default the song's last 4 bars. The sweep is a high-pass up to 1.2 kHz on unfiltered or high-pass pitched tracks and a low-pass opening from cutoff/10 on low-pass tracks, on an octave curve, snapping back on the downbeat. drop: a pre-drop cut (cutBeats of silence, default 1, up to two bars) and an impact hit on the section's first bar or atBar (default: the section named drop, else chorus). fill: a drum fill (${FILL_STYLES.join(", ")}) in the last beats (default 1, ${FILL_BEATS_MIN} up to two bars) leading into the section or into atBar, plus a crash on its downbeat. Without section or atBar, fills go at every section boundary. Out-of-range values are clamped and the result says so.`,
+    parameters: {
+      type: "object",
+      properties: {
+        type: { type: "string", enum: ["build", "drop", "fill"] },
+        section: name,
+        into: name,
+        atBar: bar(
+          "build: first bar; drop: the bar it lands on; fill: the bar it leads into",
+        ),
+        bars: { type: "integer", minimum: 1, maximum: 64 },
+        riser: { type: "boolean" },
+        roll: { type: "boolean" },
+        sweep: { type: "boolean" },
+        uplifter: { type: "boolean" },
+        cutBeats: { type: "number", minimum: 0 },
+        impact: { type: "boolean" },
+        beats: { type: "number", minimum: FILL_BEATS_MIN },
+        style: { type: "string", enum: [...FILL_STYLES] },
+        crash: { type: "boolean" },
+      },
+      required: ["type"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      return plan(context, transitionCommand(args));
+    },
+  },
+]);

package/src/agent/time-tools.ts

@@ -0,0 +1,290 @@
+/**
+ * Agent tool for the tempo map, meter changes, fermatas and track time
+ * (`core/tempo.ts`): `set_time`. Each call is one revision built by the same
+ * code as the typed `tempo`, `rit`, `accel`, `fermata`, `meter` and
+ * `track rate|phase|cycle|phasing` commands (`src/commands/time.ts`).
+ */
+import { diffScores } from "../../core/diff.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import { TIME_LIMITS, type TempoRamp } from "../../core/tempo.ts";
+import {
+  applyTimeCommand,
+  FERMATA_DEFAULT_BEATS,
+  type TimeCommand,
+  type TimePosition,
+} from "../commands/time.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+import { ToolArgumentError } from "./tools.ts";
+
+const ACTIONS = [
+  "tempo",
+  "rit",
+  "accel",
+  "a_tempo",
+  "tempo_primo",
+  "fermata",
+  "meter",
+  "track",
+  "phasing",
+  "remove_tempo",
+  "remove_fermata",
+  "remove_meter",
+  "clear",
+] as const;
+type Action = (typeof ACTIONS)[number];
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function num(
+  args: Record<string, unknown>,
+  key: string,
+  min: number,
+  max: number,
+): number | undefined {
+  const value = args[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value))
+    throw new ToolArgumentError(`${key} must be a number`);
+  if (value < min || value > max)
+    throw new ToolArgumentError(`${key} must be between ${min} and ${max}`);
+  return value;
+}
+
+function positionOf(
+  args: Record<string, unknown>,
+  required: boolean,
+): TimePosition | undefined {
+  const beat = num(args, "beat", 0, 1_000_000);
+  const bar = num(args, "bar", 1, SCORE_LIMITS.maxBars);
+  if (beat !== undefined && bar !== undefined)
+    throw new ToolArgumentError("give beat or bar, not both");
+  if (bar !== undefined) {
+    if (!Number.isInteger(bar))
+      throw new ToolArgumentError("bar must be an integer");
+    return { bar };
+  }
+  if (beat !== undefined) return { beat };
+  if (required) throw new ToolArgumentError("needs beat or bar");
+  return undefined;
+}
+
+function rampOf(args: Record<string, unknown>): TempoRamp | undefined {
+  const ramp = args.ramp;
+  if (ramp === undefined || ramp === null || ramp === "step") return undefined;
+  if (ramp === "linear" || ramp === "exp") return ramp;
+  throw new ToolArgumentError("ramp must be step, linear or exp");
+}
+
+function trackIdOf(args: Record<string, unknown>, context: ToolContext) {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || !ID_PATTERN.test(trackId))
+    throw new ToolArgumentError("trackId must be an existing track id");
+  if (!context.score.tracks.some((track) => track.id === trackId))
+    throw new ToolArgumentError(`no track ${trackId}`);
+  return trackId;
+}
+
+/** Builds the typed command for `set_time` arguments. */
+export function timeToolCommand(args: Record<string, unknown>): TimeCommand {
+  const action = args.action as Action;
+  if (!ACTIONS.includes(action))
+    throw new ToolArgumentError(`action must be one of ${ACTIONS.join(", ")}`);
+  const bpm = () => num(args, "bpm", TIME_LIMITS.minBpm, TIME_LIMITS.maxBpm);
+  switch (action) {
+    case "tempo": {
+      const value = bpm();
+      if (value === undefined) throw new ToolArgumentError("tempo needs bpm");
+      const ramp = rampOf(args);
+      return {
+        type: "tempo-at",
+        bpm: value,
+        at: positionOf(args, true)!,
+        ...(ramp ? { ramp } : {}),
+      };
+    }
+    case "rit":
+    case "accel": {
+      const bars = num(args, "bars", 0.25, SCORE_LIMITS.maxBars);
+      const beats = num(args, "beats", 0.25, 100_000);
+      if (bars !== undefined && beats !== undefined)
+        throw new ToolArgumentError("give bars or beats, not both");
+      const value = bpm();
+      const at = positionOf(args, false);
+      return {
+        type: "gradual",
+        direction: action,
+        length: beats ?? bars ?? 2,
+        unit: beats !== undefined ? "beats" : "bars",
+        ...(value !== undefined ? { bpm: value } : {}),
+        ...(at ? { at } : {}),
+        curve: rampOf(args) ?? "linear",
+      };
+    }
+    case "a_tempo":
+    case "tempo_primo": {
+      const at = positionOf(args, false);
+      return {
+        type: "tempo-return",
+        primo: action === "tempo_primo",
+        ...(at ? { at } : {}),
+      };
+    }
+    case "fermata": {
+      const at = positionOf(args, false);
+      return {
+        type: "fermata",
+        ...(at ? { at } : {}),
+        beats:
+          num(args, "beats", 0.25, TIME_LIMITS.maxFermataBeats) ??
+          FERMATA_DEFAULT_BEATS,
+      };
+    }
+    case "meter": {
+      const meter = args.meter;
+      const match =
+        typeof meter === "string" ? /^(\d+)\/(\d+)$/.exec(meter) : null;
+      if (!match) throw new ToolArgumentError("meter must look like 7/8");
+      const bar = num(args, "bar", 1, SCORE_LIMITS.maxBars);
+      return {
+        type: "meter-at",
+        beatsPerBar: Number(match[1]),
+        beatUnit: Number(match[2]),
+        ...(bar !== undefined ? { bar: Math.round(bar) } : {}),
+      };
+    }
+    case "remove_tempo":
+      return { type: "tempo-remove", at: positionOf(args, true)! };
+    case "remove_fermata":
+      return { type: "fermata-remove", at: positionOf(args, true)! };
+    case "remove_meter": {
+      const bar = num(args, "bar", 1, SCORE_LIMITS.maxBars);
+      if (bar === undefined)
+        throw new ToolArgumentError("remove_meter needs bar");
+      return { type: "meter-remove", bar: Math.round(bar) };
+    }
+    case "phasing": {
+      const cycle = num(args, "cycle", 0.25, 100_000);
+      if (cycle === undefined)
+        throw new ToolArgumentError("phasing needs cycle (beats)");
+      const over = num(args, "over", 0.25, 1_000_000);
+      return {
+        type: "track-phasing",
+        cycle,
+        ...(over !== undefined ? { over } : {}),
+        cycles: num(args, "cycles", -64, 64) ?? 1,
+        ...stepArgs(args),
+      };
+    }
+    case "track":
+    case "clear":
+      throw new ToolArgumentError("handled separately");
+  }
+}
+
+const TRACK_FIELDS = ["rate", "phase", "cycle"] as const;
+
+export const TIME_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "set_time",
+    description:
+      "Tempo map and meter: action tempo (bpm at beat|bar; ramp linear|exp glides into it), rit/accel (bars or beats long, optional target bpm and start; default 75%/133% over the last 2 bars), a_tempo/tempo_primo (step back to the tempo before the last rit/accel, or to the start tempo; at the bar after it unless beat|bar), fermata (hold beat|bar for beats extra beats), meter ('7/8' from bar, or the whole song without bar), remove_tempo/remove_fermata/remove_meter, clear (what: tempo|meter|fermatas|track|all). Per-track polytempo/polymeter: action track with rate (tempo ratio, 1.5 = three against two), phase (beats later) and cycle (beats per repeat), null resets one; action phasing (cycle beats, over beats, cycles n) sets a continuous drift that realigns at the loop end (over must divide the loop); with hold/drift (whole cycles) and shift (beats, default 0.25) it is stepped, as in Piano Phase: hold in step, then move shift ahead over drift cycles. Beats count from 0, bars from 1.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: [...ACTIONS] },
+        bpm: {
+          type: "number",
+          minimum: TIME_LIMITS.minBpm,
+          maximum: TIME_LIMITS.maxBpm,
+        },
+        beat: { type: "number", minimum: 0 },
+        bar: { type: "integer", minimum: 1, maximum: SCORE_LIMITS.maxBars },
+        ramp: { type: "string", enum: ["step", "linear", "exp"] },
+        bars: { type: "number", minimum: 0.25 },
+        beats: { type: "number", minimum: 0.25 },
+        meter: { type: "string", pattern: "^\\d+/\\d+$" },
+        what: {
+          type: "string",
+          enum: ["tempo", "meter", "fermatas", "track", "all"],
+        },
+        trackId: { type: "string", maxLength: SCORE_LIMITS.maxIdLength },
+        rate: { type: ["number", "null"] },
+        phase: { type: ["number", "null"] },
+        cycle: { type: ["number", "null"] },
+        over: { type: "number" },
+        cycles: { type: "number" },
+        hold: { type: "number" },
+        drift: { type: "number" },
+        shift: { type: "number" },
+      },
+      required: ["action"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      let score = context.score;
+      const messages: string[] = [];
+      const run = (trackId: string, command: TimeCommand) => {
+        const result = applyTimeCommand(score, trackId, command);
+        if (!result.ok) throw new ToolArgumentError(result.message);
+        if (result.next) score = result.next;
+        messages.push(result.message);
+      };
+      const action = args.action;
+      let trackId: string | undefined;
+      if (action === "track") {
+        trackId = trackIdOf(args, context);
+        const given = TRACK_FIELDS.filter((field) => field in args);
+        if (given.length === 0)
+          throw new ToolArgumentError("track needs rate, phase or cycle");
+        for (const field of given) {
+          const value =
+            args[field] === null
+              ? null
+              : field === "rate"
+                ? num(args, field, TIME_LIMITS.minRate, TIME_LIMITS.maxRate)!
+                : num(args, field, -100_000, 100_000)!;
+          run(trackId, { type: "track-time", field, value });
+        }
+      } else if (action === "clear") {
+        const what = args.what ?? "all";
+        if (what === "tempo" || what === "all")
+          run("", { type: "tempo-clear" });
+        if (what === "meter" || what === "all")
+          run("", { type: "meter-clear" });
+        if (what === "fermatas" || what === "all")
+          run("", { type: "fermata-clear" });
+        if (what === "track") {
+          trackId = trackIdOf(args, context);
+          run(trackId, { type: "track-time-off" });
+        }
+      } else {
+        const command = timeToolCommand(args);
+        if (command.type === "track-phasing")
+          trackId = trackIdOf(args, context);
+        run(trackId ?? "", command);
+      }
+      return {
+        kind: "score",
+        operations: diffScores(context.score, score),
+        ...(trackId ? { trackId } : {}),
+        summary: messages.join(" · "),
+      };
+    },
+  },
+]);
+
+/** Stepped-phasing arguments; present ones switch phasing to steps. */
+function stepArgs(args: Record<string, unknown>): {
+  hold?: number;
+  drift?: number;
+  shift?: number;
+} {
+  const out: { hold?: number; drift?: number; shift?: number } = {};
+  const hold = num(args, "hold", 0, 64);
+  const drift = num(args, "drift", 1, 64);
+  const shift = num(args, "shift", 0.0625, 100_000);
+  if (hold !== undefined) out.hold = Math.round(hold);
+  if (drift !== undefined) out.drift = Math.round(drift);
+  if (shift !== undefined) out.shift = shift;
+  return out;
+}