@hraness/dawg 0.4.1 → 0.6.0

package/src/agent/tuning-tools.ts

@@ -0,0 +1,301 @@
+/**
+ * Agent tools for tunings and scales: `set_tuning` and `set_scale`. Both
+ * build the same `/tuning` and `/scale` commands the prompt and the menu
+ * run (src/commands/tuning.ts), so every surface validates alike.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { ScoreOperation, TrackScore } from "../../core/score.ts";
+import { TUNING_LIMITS, TUNING_MAPS, type Tuning } from "../../core/tuning.ts";
+import {
+  applyTuningCommand,
+  parseTuningCommand,
+  type ProjectRead,
+  type TuningResult,
+} from "../commands/tuning.ts";
+import { resolveReadPath, WorkspaceError } from "./workspace.ts";
+import type { AgentTool, ScorePlan, ToolContext } from "./tools.ts";
+
+class TuningToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+const MAX_TABLE = 128;
+
+/** The `/tuning …` arguments one set_tuning call stands for. */
+export function tuningCommandsFor(args: Record<string, unknown>): string[] {
+  const target = args.target === undefined ? "song" : args.target;
+  if (target !== "song" && target !== "track")
+    throw new TuningToolError("target must be song or track");
+  const prefix = target === "track" ? "tuning track" : "tuning";
+  if (args.off === true) return [`${prefix} off`];
+  const commands: string[] = [];
+  const tables = ["name", "edo", "ratios", "cents", "scl"].filter(
+    (field) => args[field] !== undefined,
+  );
+  if (tables.length > 1)
+    throw new TuningToolError(
+      `give one of name, edo, ratios, cents or scl (got ${tables.join(", ")})`,
+    );
+  const word = (value: unknown, field: string): string => {
+    if (typeof value !== "string" || !/^[^\s]{1,256}$/.test(value))
+      throw new TuningToolError(`${field} must be one word`);
+    return value;
+  };
+  const table = tables[0];
+  if (table === "name") commands.push(`${prefix} ${word(args.name, "name")}`);
+  else if (table === "edo") {
+    const edo = args.edo;
+    if (
+      typeof edo !== "number" ||
+      !Number.isInteger(edo) ||
+      edo < 1 ||
+      edo > TUNING_LIMITS.maxEdo
+    )
+      throw new TuningToolError(`edo must be 1..${TUNING_LIMITS.maxEdo}`);
+    commands.push(`${prefix} edo ${edo}`);
+  } else if (table === "ratios" || table === "cents") {
+    const list = args[table];
+    if (!Array.isArray(list) || list.length < 1 || list.length > MAX_TABLE)
+      throw new TuningToolError(`${table} must list 1..${MAX_TABLE} steps`);
+    const items = list.map((item, index) => {
+      if (table === "cents" && typeof item === "number" && isFinite(item))
+        return String(item);
+      return word(
+        typeof item === "number" ? String(item) : item,
+        `${table}[${index}]`,
+      );
+    });
+    commands.push(`${prefix} ${table} ${items.join(" ")}`);
+  } else if (table === "scl") {
+    const scl = word(args.scl, "scl");
+    commands.push(
+      args.kbm !== undefined
+        ? `${prefix} scl ${scl} kbm ${word(args.kbm, "kbm")}`
+        : `${prefix} scl ${scl}`,
+    );
+  }
+  if (table !== "scl" && args.kbm !== undefined)
+    commands.push(
+      args.kbm === null
+        ? `${prefix} kbm off`
+        : `${prefix} kbm ${word(args.kbm, "kbm")}`,
+    );
+  if (args.ref !== undefined) {
+    if (args.ref === null) commands.push(`${prefix} ref off`);
+    else if (typeof args.ref === "number" && isFinite(args.ref))
+      commands.push(`${prefix} ref ${args.ref}`);
+    else throw new TuningToolError("ref must be a number of Hz or null");
+  }
+  if (args.root !== undefined)
+    commands.push(
+      `${prefix} root ${args.root === null ? "auto" : word(String(args.root), "root")}`,
+    );
+  if (args.map !== undefined) {
+    if (!TUNING_MAPS.includes(args.map as never))
+      throw new TuningToolError(`map must be ${TUNING_MAPS.join(" or ")}`);
+    commands.push(`${prefix} map ${String(args.map)}`);
+  }
+  if (commands.length === 0)
+    throw new TuningToolError(
+      "give a tuning (name, edo, ratios, cents or scl), ref, root, map or off",
+    );
+  return commands;
+}
+
+/** Runs `commands` in order and returns the operations they produced. */
+function planCommands(
+  score: TrackScore,
+  trackId: string,
+  commands: readonly string[],
+  read: ProjectRead,
+): ScorePlan {
+  let next = score;
+  const operations: ScoreOperation[] = [];
+  const messages: string[] = [];
+  for (const text of commands) {
+    const command = parseTuningCommand(text);
+    if (!command) throw new TuningToolError(`cannot read ${text}`);
+    const result: TuningResult = applyTuningCommand(
+      next,
+      trackId,
+      command,
+      read,
+    );
+    if (!result.ok || !result.next) throw new TuningToolError(result.message);
+    operations.push(operationOf(result, trackId));
+    messages.push(result.message);
+    next = result.next;
+  }
+  return {
+    kind: "score",
+    operations,
+    summary: messages.at(-1) ?? "tuning",
+    trackId,
+  };
+}
+
+function operationOf(result: TuningResult, trackId: string): ScoreOperation {
+  const payload = result.payload ?? {};
+  if (result.kind === "score.tuning")
+    return {
+      type: "setTuning",
+      tuning: (payload.tuning as Tuning | null | undefined) ?? null,
+    };
+  if (result.kind === "score.track")
+    return {
+      type: "updateTrack",
+      trackId,
+      patch: (payload.patch as { tuning: Tuning | null }) ?? {},
+    };
+  if (result.kind === "score.key")
+    return { type: "setKey", key: (payload.key as string | null) ?? null };
+  throw new TuningToolError(`unexpected result ${result.kind ?? ""}`);
+}
+
+function trackFor(args: Record<string, unknown>, context: ToolContext): string {
+  const id = args.trackId ?? context.focusedTrackId;
+  if (typeof id !== "string" || !context.score.tracks.some((t) => t.id === id))
+    throw new TuningToolError(`no track ${String(id)}`);
+  return id;
+}
+
+const SET_TUNING: AgentTool = {
+  name: "set_tuning",
+  description:
+    "Set the song tuning (every track follows it) or one track's own tuning: a library tuning by name, n-EDO, just ratios, cents, or a Scala .scl/.kbm file in the project; plus A4 reference, root key and key mapping. off returns to 12-TET (track: follows the song). Note-level detune is add_notes cents.",
+  parameters: {
+    type: "object",
+    properties: {
+      target: { type: "string", enum: ["song", "track"] },
+      trackId: { type: "string", description: "track target; default focused" },
+      name: {
+        type: "string",
+        description:
+          "19-edo, 24-edo, 31-edo, pythagorean, just, 7-limit, well-tuned-piano, pelog, slendro, rast, bayati, yaman…",
+      },
+      edo: { type: "integer", minimum: 1, maximum: TUNING_LIMITS.maxEdo },
+      ratios: {
+        type: "array",
+        items: { type: "string" },
+        maxItems: MAX_TABLE,
+        description:
+          'degrees 1..n, last is the period: ["9/8","5/4","3/2","2/1"]',
+      },
+      cents: {
+        type: "array",
+        items: { type: "number" },
+        maxItems: MAX_TABLE,
+        description: "degrees 1..n in cents, last is the period (1200)",
+      },
+      scl: { type: "string", description: "project path to a .scl file" },
+      kbm: {
+        type: ["string", "null"],
+        description: "project path to a .kbm keyboard map; null removes it",
+      },
+      ref: {
+        type: ["number", "null"],
+        minimum: TUNING_LIMITS.minRefHz,
+        maximum: TUNING_LIMITS.maxRefHz,
+        description: "A4 in Hz (440); null resets",
+      },
+      root: {
+        type: ["string", "null"],
+        description: 'key of degree 0 ("D4"); null follows the song key',
+      },
+      map: {
+        type: "string",
+        enum: TUNING_MAPS,
+        description:
+          "linear: one key per step · nearest: 12 keys to nearest step",
+      },
+      off: { type: "boolean" },
+    },
+    additionalProperties: false,
+  },
+  plan(args, context) {
+    const trackId = trackFor(args, context);
+    const commands = tuningCommandsFor(args);
+    const needsFiles = args.scl !== undefined || typeof args.kbm === "string";
+    const current =
+      args.target === "track"
+        ? context.score.tracks.find((t) => t.id === trackId)?.tuning
+        : context.score.tuning;
+    if (!needsFiles && !current?.scl && !current?.kbm)
+      return planCommands(context.score, trackId, commands, () => undefined);
+    return {
+      kind: "prepare",
+      summary: commands.join(" · "),
+      async run(host) {
+        const files = new Map<string, string>();
+        if (host.workspace) {
+          const paths = [args.scl, args.kbm, current?.scl, current?.kbm].filter(
+            (path): path is string => typeof path === "string",
+          );
+          for (const path of paths) {
+            try {
+              const resolved = await resolveReadPath(
+                { root: host.workspace.root, trackSlug: "" },
+                path,
+              );
+              files.set(path, await readFile(resolved.real, "utf8"));
+            } catch (error) {
+              if (!(error instanceof WorkspaceError)) throw error;
+            }
+          }
+        }
+        return planCommands(context.score, trackId, commands, (path) =>
+          files.get(path),
+        );
+      },
+    };
+  },
+};
+
+const SET_SCALE: AgentTool = {
+  name: "set_scale",
+  description:
+    "Set the song key and scale: a church mode, harmonic or melodic minor, pentatonic, blues, maqam (hijaz, bayati), raga (yaman, bhairav, kafi…) or a Messiaen mode. Chords, play-mode keys and scale snapping follow it. Scales with microtones or just intonation pair with set_tuning name=<scale>.",
+  parameters: {
+    type: "object",
+    properties: {
+      tonic: {
+        type: "string",
+        description: '"C", "F#", "Eb"; default song tonic',
+      },
+      scale: {
+        type: "string",
+        description:
+          "dorian, harmonic-minor, minor-pentatonic, blues, hijaz, bayati, yaman, bhairav, kafi, messiaen-3…",
+      },
+    },
+    required: ["scale"],
+    additionalProperties: false,
+  },
+  plan(args, context) {
+    const scale = args.scale;
+    if (typeof scale !== "string" || !/^[a-z0-9-]{1,32}$/i.test(scale))
+      throw new TuningToolError("scale must be a scale name");
+    const tonic = args.tonic;
+    if (
+      tonic !== undefined &&
+      (typeof tonic !== "string" || !/^[a-g][#b]?$/i.test(tonic))
+    )
+      throw new TuningToolError('tonic must be a note name like "D" or "Eb"');
+    const command = tonic ? `scale ${tonic} ${scale}` : `scale ${scale}`;
+    return planCommands(
+      context.score,
+      context.focusedTrackId,
+      [command],
+      () => undefined,
+    );
+  },
+};
+
+export const TUNING_TOOLS: readonly AgentTool[] = Object.freeze([
+  SET_TUNING,
+  SET_SCALE,
+]);

package/src/agent/xcb-agent.ts

@@ -1,3 +1,4 @@
+import { GRANULAR_PARAMS } from "../../core/granular.ts";
 import { compositionBrief } from "./brief.ts";
 import { CHORD_PROCESS } from "../../core/chords.ts";
 import {
@@ -46,12 +47,20 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   "Times are in beats from the loop start (0-based). Keep notes inside loopBeats unless you extend the loop first.",
   "Prefer a few well-formed ops (one add_notes op per track part) over many tiny ones.",
   'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a genre groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit; use add_drums only for one-off fills. Drum pitches select voices, so do not use add_notes for beats.',
+  "Song structure: list_sections shows named sections (bars count from 1); edit_section marks, adds, duplicates, moves, renames, deletes, mutes, varies (transpose/gain) and loops them; set_form sets the play order with repeats (intro verse chorus*2 outro); add_transition generates builds (riser, snare roll, filter sweep, uplifter), drops (cut plus impact) and drum fills at section boundaries.",
   CHORD_PROCESS,
   "Synth voices: set_synth shapes a synth track with Strudel params (ADSR, lpf/lpenv filter envelopes, fm/fmh, supersaw unison/detune, vib, penv, noise; z_* ZzFX sounds take slide/pitchJump/lfo/zcrush…) or a preset (pad lead pluck bass keys bell…).",
+  "Plucked strings: set_string makes a track a physical-model string (nylon steel electric jangle ebass slap upright motown sitar tanpura harpsichord lute oud setar tar santur dulcimer koto harp banjo tres requinto) and overrides params (ring bright damp pos mute buzz body sym). The bare words sitar, ebass, pluck keep their older voices; use set_string for the modelled ones.",
+  "Pianos: set_instrument piano (or grand upright felt honkytonk prepared, ballad, lofi) loads a modelled piano with real hammers, stretched inharmonic strings, dampers and the sustain pedal; set_keys tweaks it (hardness touch decay release felt stretch body…, automate as keys-<param> lanes). A track already stored as instrument piano keeps the legacy tone until you set it again.",
+  "Mallets and bells: set_instrument vibes (or marimba via modal, xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani) plays the modal engine; set_modal changes mallet (yarn…brass), hardness, position, ring, damp, motor/motordepth (vibes tremolo), buzz, click. Plain instrument marimba stays the legacy tone.",
   "Sampler voices: set_sample sets Strudel sample controls per voice (begin end speed unit loop loopBegin loopEnd clip/legato fit loopAt accelerate squiz cut); splice = slices with fit.",
+  "Fitting samples (0.6): fit_sample sets a voice's own bpm (or len in beats) so it follows the song's tempo map; fitmode beats for drums and speech (hits stay sharp), tones for pads and vocals (pitch kept), repitch (default) like tape.",
   "Effects (set_fx; set_effects and set_automation): the brief's effects list is the fixed chain order with each effect's simple params. set_fx turns an effect on with good defaults, loads a preset or sets params by dawg or Strudel name. Lanes: volume, pan, filter, resonance, delay-feedback, delay-mix, wt and <effect>-<param> (e.g. autofilter-cutoff).",
+  "Guitar rig (set_rig): rig loads a whole rig (clean crunch punk ragged lead metal fuzz octave funk wah bachata spring bassdrive reese jangle alt) on a guitar or bass track; stomp, head and cab tweak the pedal, amp (level-matched, gate in dB) and cabinet. Tracks named jangle punk funk ragged gtr-lead gtr-metal bachata start with a guitar voice and that rig. `amp` is Strudel gain; the guitar amp is head.",
   "Previewing: preview_sound renders a track, or candidate sound tool calls (changes: [{tool, args}]), without committing, returns loudness, brightness and a comparison, and plays it once in the user's window. Use it when choosing between sounds (tables, presets, effect amounts), say how it sounds, then commit with the normal tools.",
   "Wavetable synth: set_wavetable picks a table (built-ins offline, Strudel wt_ sets fetched once) and scans it by position wt.",
+  `Granular: set_granular makes a track a grain cloud (presets cloud hold sparkle swarm stutter microloop backwards dust) of a synth source (src synth:pad, the default; synth:<name>@<note>) or one of its own sampler voices, and overrides params (${Object.keys(GRANULAR_PARAMS).join(" ")}; repeat and hold latch the head for beat repeats, begin and end pick a region, root takes a MIDI number or note name); off returns to the previous voice; the same seed gives the same grains.`,
+  "Mastering: set_master sets the song master and loudness target; measure_mix reports LUFS, true peak, balance and correlation. Master only when asked for loudness or a finished sound, and measure before and after.",
   'Reply with exactly one JSON object and nothing else, shaped {"ops":[{"tool":"<tool name>","args":{...}}],"say":"<one short sentence describing the musical change>","done":true}.',
   'Set "done":false only if you need to see the results of these ops before continuing; you will then get each op\'s result and can send more ops.',
   "If an op was rejected, read its diagnostic and either send a corrected op or stop with done:true.",