@hraness/dawg 0.5.0 → 0.6.1

package/src/agent/tools.ts

@@ -1,3 +1,28 @@
+import { INSTRUMENT_WORDS } from "../../core/instruments.ts";
+import {
+  DEFAULT_STRING_PRESET,
+  STRING_INSTRUMENT,
+} from "../../core/strings.ts";
+import {
+  instrumentPatchForWord,
+  MODAL_ALIASES,
+  MODAL_MALLET_NAMES,
+  MODAL_PARAMS,
+  MODAL_PRESET_NAMES,
+  modalParamName,
+  modalPresetFor,
+  type TrackModal,
+} from "../../core/resonators.ts";
+import { applyModalCommand, type ModalCommand } from "../commands/modal.ts";
+import { applyWindCommand, type WindCommand } from "../commands/wind.ts";
+import {
+  type TrackWind,
+  WIND_ALIASES,
+  WIND_PARAMS,
+  WIND_PRESET_NAMES,
+  windParamName,
+  windPresetFor,
+} from "../../core/winds.ts";
 import {
   AUTOMATION_PARAMETERS,
   automationPoints,
@@ -16,6 +41,26 @@ import {
   synthParamName,
 } from "../../core/synth.ts";
 import { applySynthCommand, type SynthCommand } from "../commands/synth.ts";
+import { applyStringCommand, type StringCommand } from "../commands/string.ts";
+import {
+  STRING_PARAMS,
+  STRING_PRESET_NAMES,
+  stringParamName,
+  stringPresetName,
+} from "../../core/strings.ts";
+import {
+  applyKeysCommand,
+  keysPresetPatch,
+  type KeysCommand,
+} from "../commands/keys.ts";
+import {
+  KEYS_PRESETS,
+  ORGAN_ALIASES,
+  KEYS_SIMPLE,
+  isKeysPreset,
+  keysParamName,
+  pianoWrite,
+} from "../../core/keys.ts";
 import {
   setSampleControls,
   type SampleControlValue,
@@ -23,16 +68,26 @@ import {
 import {
   EFFECT_NAMES,
   FX_PRESETS,
+  RIG_STAGES,
   effectSpec,
   type EffectName,
 } from "../../core/fx.ts";
+import {
+  RIG_PRESET_NAMES,
+  applyRigCommand,
+  parseRigCommand,
+  rigTrackFields,
+  rigWordPatch,
+} from "../commands/rig.ts";
 import {
   applyFxCommand,
   effectPatch,
   effectValues,
   parseEffectName,
   parseParamName,
+  parseFxCommand,
   type FxCommand,
+  type FxResult,
 } from "../commands/fx.ts";
 import type { ChatTool } from "./gateway.ts";
 import { MEDIA_TOOLS } from "../media/tools.ts";
@@ -51,8 +106,10 @@ import { MASTER_TOOLS } from "./master-tools.ts";
 import { DRUM_TOOLS } from "./drum-tools.ts";
 import { TIME_TOOLS } from "./time-tools.ts";
 import { SECTION_TOOLS } from "./section-tools.ts";
+import { GRANULAR_TOOLS } from "./granular-tools.ts";
+import { RESAMPLE_TOOLS } from "./resample-tool.ts";
 import type { MediaResult, MediaRunContext } from "../media/types.ts";
-import { pitchToMidi } from "./ops.ts";
+import { instrumentPatch, pitchToMidi } from "./ops.ts";
 import { TUNING_LIMITS } from "../../core/tuning.ts";
 import {
   DRUM_VOICES,
@@ -86,6 +143,13 @@ import {
   type SearchSpend,
 } from "../web/search.ts";
 
+/** Instrument words the tools accept: legacy voices, `string`, 0.6 words. */
+const INSTRUMENT_ENUM: string[] = [
+  ...AVAILABLE_INSTRUMENTS,
+  STRING_INSTRUMENT,
+  ...INSTRUMENT_WORDS.map((row) => row.word),
+].filter((word, index, all) => all.indexOf(word) === index);
+
 /** What a validated tool call asks the host to do. */
 export type ScorePlan = Readonly<{
   kind: "score";
@@ -421,24 +485,48 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "set_instrument",
-    description: "Change a track's instrument voice.",
+    description:
+      "Change a track's instrument voice. Mallets and bells (modal): modal (marimba) vibes xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani, gamelan saron gangsa bonang …; set_modal shapes them. Electric keys: epiano suitcase dyno wurli clav funkclav (set_keys). Winds and brass (wind engine): flute recorder clarinet oboe bassoon sax trumpet trombone tuba horn …; set_wind shapes them.",
     parameters: {
       type: "object",
       properties: {
         trackId: trackIdSchema,
-        instrument: { type: "string", enum: [...AVAILABLE_INSTRUMENTS] },
+        instrument: { type: "string", enum: INSTRUMENT_ENUM },
       },
       required: ["instrument"],
       additionalProperties: false,
     },
     plan(args, context) {
       const trackId = targetTrack(args, context);
-      const instrument = instrumentName(args.instrument);
+      // piano/grand/upright/felt…: a new write is the modelled piano.
+      const track = context.score.tracks.find((t) => t.id === trackId);
+      if (track && typeof args.instrument === "string") {
+        const word = args.instrument.toLowerCase();
+        // `rhodes`, `wurlitzer`, `clavinet` name their electric presets.
+        const preset = pianoWrite(word)?.preset ?? word;
+        if (isKeysPreset(preset)) {
+          const patch = keysPresetPatch(track, preset);
+          return {
+            kind: "score",
+            operations: [{ type: "updateTrack", trackId, patch }],
+            trackId,
+            summary: `${trackId} → ${patch.instrument} (${preset})`,
+          };
+        }
+      }
+      const patch = instrumentName(args.instrument);
+      // A guitar alias (`jangle`, `gtr-metal`…) also loads its rig.
+      const rig = rigWordPatch(String(args.instrument), track?.fx);
       return {
         kind: "score",
-        operations: [{ type: "updateTrack", trackId, patch: { instrument } }],
+        operations: [
+          { type: "updateTrack", trackId, patch: { ...patch, ...rig } },
+        ],
         trackId,
-        summary: `${trackId} → ${instrument}`,
+        summary:
+          patch.instrument === "marimba" && !patch.modal
+            ? `${trackId} → marimba (legacy tone) · set_modal preset marimba for the mallet engine`
+            : `${trackId} → ${patch.string?.preset ?? patch.modal?.preset ?? patch.wind?.preset ?? patch.instrument}`,
       };
     },
   },
@@ -512,7 +600,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         parameter: {
           type: "string",
           description:
-            "volume, pan, filter, resonance, delay-feedback, delay-mix, or <effect>-<param>",
+            "volume, pan, filter, resonance, delay-feedback, delay-mix, <effect>-<param>, or grain-<param> on a granular track",
         },
         mode: { type: "string", enum: ["replace", "merge"] },
         points: {
@@ -635,6 +723,92 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "set_rig",
+    description:
+      "Guitar rig on a track (stomp → amp head with noise gate → speaker cab, before tremolo). rig loads a whole rig (clean crunch punk ragged lead metal fuzz octave funk wah bachata spring bassdrive reese jangle alt, and the shoegaze rigs shoegaze glide dreampop swell ebow that add wobble/bloom/swell/double and a long reverb) or reset removes it; stomp/head/cab set stage params (stomp type fuzz|face|od|rat|octave gain tone level; head type clean|chime|crunch|lead|high|solid|bass gain bass mid treble presence master sag gate(dB); cab type 1x12|2x12|4x12|1x10|open|8x10|1x15|di mic), or null removes a stage. Heads are level-matched. `amp` is Strudel gain, not this.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        rig: { type: "string", enum: [...RIG_PRESET_NAMES, "reset"] },
+        ...Object.fromEntries(
+          RIG_STAGES.map((stage) => [
+            stage,
+            {
+              type: ["object", "null"],
+              additionalProperties: { type: ["number", "string"] },
+            },
+          ]),
+        ),
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      let score = context.score;
+      const messages: string[] = [];
+      const run = (result: FxResult) => {
+        if (!result.ok) throw new ToolArgumentError(result.message);
+        if (result.next) score = result.next;
+        messages.push(result.message);
+      };
+      if (args.rig !== undefined) {
+        if (typeof args.rig !== "string")
+          throw new ToolArgumentError("rig must be a rig name or reset");
+        const command = parseRigCommand(`rig ${args.rig}`);
+        if (!command || command.type === "rig-show")
+          throw new ToolArgumentError(
+            `rig must be one of ${RIG_PRESET_NAMES.join(", ")} or reset`,
+          );
+        run(applyRigCommand(score, trackId, command));
+      }
+      for (const stage of RIG_STAGES) {
+        const params = args[stage];
+        if (params === undefined) continue;
+        if (params === null) {
+          run(
+            applyFxCommand(score, trackId, { type: "fx-off", effect: stage }),
+          );
+          continue;
+        }
+        if (typeof params !== "object" || Array.isArray(params))
+          throw new ToolArgumentError(`${stage} must be an object or null`);
+        const words = Object.entries(params as Record<string, unknown>)
+          .map(([key, value]) => `${key} ${String(value)}`)
+          .join(" ");
+        const command = words.length
+          ? parseFxCommand(`fx ${stage} ${words}`)
+          : ({ type: "fx-on", effect: stage } as const);
+        if (!command)
+          throw new ToolArgumentError(
+            `${stage}: unknown parameter or value in ${words}`,
+          );
+        run(applyFxCommand(score, trackId, command));
+      }
+      if (messages.length === 0)
+        throw new ToolArgumentError("give rig, stomp, head or cab");
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      const before = context.score.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: {
+              fx: next.fx ?? null,
+              ...(next.reverb !== before.reverb
+                ? { reverb: next.reverb ?? null }
+                : {}),
+            },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${messages.join(" · ")}`,
+      };
+    },
+  },
   {
     name: "set_synth",
     description:
@@ -680,10 +854,328 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "set_string",
+    description:
+      "Make a track a plucked, struck or bowed string (physical model). Bowed presets (exciter bow): violin viola cello contrabass fiddle erhu kamancheh, sections violins violas cellos contrabasses, pizz trem. preset picks the instrument; params override it (ring s, bright, damp, pos, mute, buzz = jawari, body, sym = sympathetic strings, stiff, exciter pick|finger|hammer|noise|bow); null unsets one. Bowed presets take pressure speed attack vib vibmod vibdelay tremhz sord dyn. reset keeps the preset and drops overrides; off returns the track to a plain pluck voice.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: { type: "string", enum: [...STRING_PRESET_NAMES] },
+        reset: { type: "boolean" },
+        off: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: { type: ["number", "string", "null"] },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      let score = context.score;
+      const messages: string[] = [];
+      for (const command of stringToolCommands(args)) {
+        const result = applyStringCommand(score, trackId, command);
+        if (!result.ok) throw new ToolArgumentError(result.message);
+        if (result.next) score = result.next;
+        messages.push(result.message);
+      }
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, string: next.string ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${messages.at(-1)}`,
+      };
+    },
+  },
+  {
+    name: "set_keys",
+    description: `Shape a modelled piano, electric keys (epiano wurli clav) or organ: preset (instrument, keys and its effects), params ${KEYS_SIMPLE.join(" ")}… (pianos: sym 0.5 adds sympathetic bloom under the sustain pedal, good for Chopin and Debussy; epiano: bark bell tone vibe; wurli: trem; clav: pickup mute; null unsets; DAWG.md lists all), or reset. Stored "piano" stays legacy; set_instrument piano writes grand. Organs (not "organ", a legacy synth): presets tonewheel combo pipe… (aliases hammond b3 farfisa church); drawbars "888800008", registers "08880", stops (plenum, flute8…), rotary; params perc percdecay percvol click scanner drive (tonewheel), voice vib vibmod drive (combo), chiff wind trem (pipe). A row the family does not read is refused.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: {
+          type: "string",
+          enum: [...Object.keys(KEYS_PRESETS), ...Object.keys(ORGAN_ALIASES)],
+        },
+        reset: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: { type: ["number", "string", "null"] },
+        },
+        // f061-organ
+        drawbars: { type: "string", pattern: "^[0-8]{9}$" },
+        registers: { type: "string", pattern: "^[0-8]{5}$" },
+        stops: { type: ["array", "string"], items: { type: "string" } },
+        rotary: { type: "string", enum: ["slow", "fast", "stop"] },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const command = keysToolCommand(args);
+      const result = applyKeysCommand(context.score, trackId, command);
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      const before = context.score.tracks.find((t) => t.id === trackId)!;
+      const next = result.next.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: {
+              instrument: next.instrument,
+              keys: next.keys ?? null,
+              ...(next.filter !== before.filter
+                ? { filter: next.filter ?? null }
+                : {}),
+              ...(next.fx !== before.fx ? { fx: next.fx ?? null } : {}),
+              ...(next.reverb !== before.reverb
+                ? { reverb: next.reverb ?? null }
+                : {}),
+            },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message}`,
+      };
+    },
+  },
+  {
+    name: "set_modal",
+    description:
+      "Mallets and bells on the modal engine: preset (marimba vibes xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani) switches the voice and keeps overrides (gamelan: crotales musicbox toypiano saron demung slenthem gangsa gender bonang kenong kethuk kempul; frame drums daf bodhran tabla); mallet yarn|cord|rubber|plastic|brass; params sets MODAL_PARAMS (hardness position ring tilt release damp motor motordepth ombak buzz click strikebend strikedecay gain), null returns one to the preset; pair names a partner modal track: this track (pengisep) sounds ombak Hz above it and the partner (pengumbang) gets ombak 0, null unpairs; reset clears overrides. Turns the track into instrument modal.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: {
+          type: "string",
+          enum: [...MODAL_PRESET_NAMES, ...Object.keys(MODAL_ALIASES)],
+        },
+        mallet: { type: "string", enum: [...MODAL_MALLET_NAMES] },
+        pair: { type: ["string", "null"] },
+        reset: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: { type: ["number", "string", "null"] },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const commands: ModalCommand[] = [];
+      if (args.reset === true) commands.push({ type: "modal-reset" });
+      if (args.preset !== undefined) {
+        const preset =
+          typeof args.preset === "string"
+            ? modalPresetFor(args.preset)
+            : undefined;
+        if (!preset)
+          throw new ToolArgumentError(
+            `preset must be one of ${MODAL_PRESET_NAMES.join(", ")}`,
+          );
+        commands.push({ type: "modal-preset", preset });
+      }
+      const values: Record<string, number | string | null> = {};
+      if (args.mallet !== undefined) {
+        if (typeof args.mallet !== "string")
+          throw new ToolArgumentError("mallet must be a string");
+        values.mallet = args.mallet;
+      }
+      if (args.pair !== undefined) {
+        if (args.pair !== null && typeof args.pair !== "string")
+          throw new ToolArgumentError("pair must be a track id or null");
+        values.pair = args.pair;
+      }
+      if (args.params !== undefined) {
+        if (
+          typeof args.params !== "object" ||
+          args.params === null ||
+          Array.isArray(args.params)
+        )
+          throw new ToolArgumentError("params must be an object");
+        for (const [key, value] of Object.entries(args.params)) {
+          const name = modalParamName(key);
+          if (!name)
+            throw new ToolArgumentError(
+              `modal has no parameter ${key} (${Object.keys(MODAL_PARAMS).join(" ")})`,
+            );
+          if (
+            value !== null &&
+            typeof value !== "number" &&
+            typeof value !== "string"
+          )
+            throw new ToolArgumentError(`${key} must be a number or string`);
+          values[name] = value;
+        }
+      }
+      if (Object.keys(values).length > 0)
+        commands.push({ type: "modal-set", values });
+      if (commands.length === 0) {
+        // An empty call turns the track modal and keeps a modal track's preset.
+        const current = context.score.tracks.find((t) => t.id === trackId);
+        commands.push({
+          type: "modal-preset",
+          preset:
+            current?.instrument === "modal" && current.modal?.preset
+              ? current.modal.preset
+              : "marimba",
+        });
+      }
+      let score = context.score;
+      const messages: string[] = [];
+      for (const command of commands) {
+        const result = applyModalCommand(score, trackId, command);
+        if (!result.ok || !result.next)
+          throw new ToolArgumentError(result.message);
+        score = result.next;
+        messages.push(result.message);
+      }
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      // A pair also sets the partner (pengumbang) to ombak 0.
+      const partners = score.tracks.filter(
+        (t) =>
+          t.id !== trackId &&
+          t.modal !== context.score.tracks.find((o) => o.id === t.id)?.modal,
+      );
+      return {
+        kind: "score",
+        operations: [
+          ...partners.map((t) => ({
+            type: "updateTrack" as const,
+            trackId: t.id,
+            patch: { modal: t.modal ?? null },
+          })),
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, modal: next.modal ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${messages.at(-1)}`,
+      };
+    },
+  },
+  {
+    name: "set_wind",
+    description:
+      "Winds and brass on the wind engine (breath-driven waveguides): preset (flute recorder whistle ney shakuhachi panpipe suling bansuri clarinet bassclarinet oboe bassoon sax altosax barisax trumpet harmon plunger trombone tuba horn) switches the voice and keeps overrides; params sets WIND_PARAMS (breath bright mute players growl noise attack release vib vibmod reed stopped wah wahenv flutter gain model), null returns one to the preset; players 2..8 is a section that spreads over chord tones; reset clears overrides; off returns to the legacy wind tone. Lines slur by default (a note that starts while one note is held is not re-tongued). Turns the track into the wind engine.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: {
+          type: "string",
+          enum: [...WIND_PRESET_NAMES, ...Object.keys(WIND_ALIASES)],
+        },
+        reset: { type: "boolean" },
+        off: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "null"],
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      const commands: WindCommand[] = [];
+      if (args.off === true) commands.push({ type: "wind-off" });
+      if (args.reset === true) commands.push({ type: "wind-reset" });
+      if (args.preset !== undefined) {
+        const preset =
+          typeof args.preset === "string"
+            ? windPresetFor(args.preset)
+            : undefined;
+        if (!preset)
+          throw new ToolArgumentError(
+            `preset must be one of ${WIND_PRESET_NAMES.join(", ")}`,
+          );
+        commands.push({ type: "wind-preset", preset });
+      }
+      const values: Record<string, number | string | boolean | null> = {};
+      if (args.params !== undefined) {
+        if (
+          typeof args.params !== "object" ||
+          args.params === null ||
+          Array.isArray(args.params)
+        )
+          throw new ToolArgumentError("params must be an object");
+        for (const [key, value] of Object.entries(args.params)) {
+          const name = windParamName(key);
+          if (!name)
+            throw new ToolArgumentError(
+              `wind has no parameter ${key} (${Object.keys(WIND_PARAMS).join(" ")})`,
+            );
+          if (
+            value !== null &&
+            typeof value !== "number" &&
+            typeof value !== "string" &&
+            typeof value !== "boolean"
+          )
+            throw new ToolArgumentError(
+              `${key} must be a number, string or boolean`,
+            );
+          values[name] = value;
+        }
+      }
+      if (Object.keys(values).length > 0)
+        commands.push({ type: "wind-set", values });
+      if (commands.length === 0) {
+        // An empty call turns the track into the wind engine.
+        const current = context.score.tracks.find((t) => t.id === trackId);
+        commands.push({
+          type: "wind-preset",
+          preset:
+            current?.instrument === "wind" && current.wind?.preset
+              ? current.wind.preset
+              : "flute",
+        });
+      }
+      let score = context.score;
+      const messages: string[] = [];
+      for (const command of commands) {
+        const result = applyWindCommand(score, trackId, command);
+        if (!result.ok) throw new ToolArgumentError(result.message);
+        if (result.next) score = result.next;
+        messages.push(result.message);
+      }
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, wind: next.wind ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${messages.at(-1)}`,
+      };
+    },
+  },
   {
     name: "set_sample",
     description:
-      "Set a sampler voice's Strudel sample controls: begin end gain speed unit(r|c|s) loop loopBegin loopEnd clip(legato) fit loopAt accelerate squiz cut; null unsets one.",
+      "Set a sampler voice's Strudel sample controls: begin end gain speed unit(r|c|s) loop loopBegin loopEnd clip(legato) fit loopAt accelerate squiz cut, and (0.6.1) shift (semitones, length kept) formant (0 keeps the voice's formants) fadeInTime fadeTime (seconds), vel [lo,hi] (velocity layer) rr (round-robin group). null unsets one.",
     parameters: {
       type: "object",
       properties: {
@@ -692,7 +1184,15 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
         params: {
           type: "object",
           additionalProperties: {
-            type: ["number", "string", "boolean", "null"],
+            anyOf: [
+              { type: ["number", "string", "boolean", "null"] },
+              {
+                type: "array",
+                items: { type: "integer", minimum: 0, maximum: 127 },
+                minItems: 2,
+                maxItems: 2,
+              },
+            ],
           },
         },
       },
@@ -727,6 +1227,55 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "fit_sample",
+    description:
+      "Fit a sampler voice to the song's tempo map (ramps included): bpm is the sample's own tempo (20..400), len its length in beats; fitmode repitch (tape: pitch moves with speed, default) | beats (drums, speech: onset slices placed on time, unstretched) | tones (pads, vocals: phase-vocoder stretch, pitch kept). fit on > bpm > len. null unsets one. Song tempo is set_tempo, not this.",
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        voice: { type: "string" },
+        bpm: { type: ["number", "null"], minimum: 20, maximum: 400 },
+        fitmode: {
+          anyOf: [
+            { type: "string", enum: ["repitch", "beats", "tones"] },
+            { type: "null" },
+          ],
+        },
+        len: { type: ["number", "null"], exclusiveMinimum: 0, maximum: 1024 },
+      },
+      required: ["voice"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      if (typeof args.voice !== "string")
+        throw new ToolArgumentError("fit_sample needs voice");
+      const values: Record<string, SampleControlValue> = {};
+      for (const key of ["bpm", "len", "fitmode"] as const)
+        if (args[key] !== undefined)
+          values[key] = args[key] as SampleControlValue;
+      if (Object.keys(values).length === 0)
+        throw new ToolArgumentError("fit_sample needs bpm, len or fitmode");
+      const result = setSampleControls(
+        context.score,
+        trackId,
+        args.voice,
+        values,
+      );
+      if (!result.ok) throw new ToolArgumentError(result.message);
+      const next = result.next.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          { type: "updateTrack", trackId, patch: { sampler: next.sampler } },
+        ],
+        trackId,
+        summary: `${trackId} ${result.message.replace(/^sample/, "fit")}`,
+      };
+    },
+  },
   {
     name: "set_effects",
     description: `Shorthand: low-pass filter, delay (beats) and reverb (mix 0.15..0.35 is a room); null removes one. Prefer set_fx.`,
@@ -1082,7 +1631,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       properties: {
         id: { type: "string", pattern: ID_PATTERN.source, maxLength: 64 },
         name: { type: "string", maxLength: SCORE_LIMITS.maxNameLength },
-        instrument: { type: "string", enum: [...AVAILABLE_INSTRUMENTS] },
+        instrument: { type: "string", enum: INSTRUMENT_ENUM },
       },
       required: ["id", "instrument"],
       additionalProperties: false,
@@ -1095,14 +1644,46 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       const id = args.id;
       if (context.score.tracks.some((track) => track.id === id))
         throw new ToolArgumentError(`track ${id} already exists`);
-      const instrument = instrumentName(args.instrument);
       const name =
         typeof args.name === "string" && args.name.trim().length > 0
           ? args.name.trim().slice(0, SCORE_LIMITS.maxNameLength)
           : id;
+      const word =
+        typeof args.instrument === "string"
+          ? args.instrument.toLowerCase()
+          : "";
+      const preset = pianoWrite(word)?.preset ?? word;
+      if (isKeysPreset(preset)) {
+        const patch = keysPresetPatch({}, preset);
+        return {
+          kind: "score",
+          operations: [
+            {
+              type: "addTrack",
+              track: { id, name, ...patch, instrument: patch.instrument! },
+            },
+          ],
+          trackId: id,
+          summary: `+track ${id} (${patch.instrument} ${preset})`,
+        };
+      }
+      const patch = instrumentName(args.instrument);
+      const instrument =
+        patch.string?.preset ?? patch.modal?.preset ?? patch.instrument;
       return {
         kind: "score",
-        operations: [{ type: "addTrack", track: { id, name, instrument } }],
+        operations: [
+          {
+            type: "addTrack",
+            track: {
+              id,
+              name,
+              ...patch,
+              // A guitar alias also starts with its rig.
+              ...rigTrackFields(String(args.instrument)),
+            },
+          },
+        ],
         trackId: id,
         summary: `+track ${id} (${instrument})`,
       };
@@ -1387,6 +1968,8 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   ...MEDIA_TOOLS,
   ...PACK_TOOLS,
   ...MASTER_TOOLS,
+  ...GRANULAR_TOOLS,
+  ...RESAMPLE_TOOLS,
   // Looks tools up at call time, so it can plan any of the above.
   previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);
@@ -1534,6 +2117,72 @@ function fxToolCommand(
   return { type: "fx-set", effect, values };
 }
 
+/** f061-organ: set_keys drawbars/registers/stops/rotary as keys values. */
+function organToolValues(
+  args: Record<string, unknown>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const name of ["drawbars", "registers", "rotary"] as const) {
+    const value = args[name];
+    if (value === undefined) continue;
+    if (typeof value !== "string")
+      throw new ToolArgumentError(`keys ${name} must be a string`);
+    out[name] = value;
+  }
+  if (args.stops !== undefined) {
+    const words = Array.isArray(args.stops)
+      ? args.stops
+      : typeof args.stops === "string"
+        ? args.stops.split(/[\s,+]+/)
+        : undefined;
+    if (!words || !words.every((word) => typeof word === "string"))
+      throw new ToolArgumentError("keys stops must be stop names");
+    out.stops = words.join(" ");
+  }
+  return out;
+}
+
+function keysToolCommand(args: Record<string, unknown>): KeysCommand {
+  if (args.reset === true) return { type: "keys-reset" };
+  const organ = organToolValues(args);
+  const organSet = Object.keys(organ).length > 0;
+  if (args.preset !== undefined) {
+    const preset =
+      typeof args.preset === "string"
+        ? (pianoWrite(args.preset)?.preset ?? args.preset)
+        : undefined;
+    if (preset === undefined || !isKeysPreset(preset))
+      throw new ToolArgumentError(
+        `keys presets: ${Object.keys(KEYS_PRESETS).join(", ")}`,
+      );
+    return organSet
+      ? { type: "keys-preset", preset, values: organ }
+      : { type: "keys-preset", preset };
+  }
+  if (args.params === undefined && organSet)
+    return { type: "keys-set", values: organ };
+  if (args.params === undefined)
+    throw new ToolArgumentError("set_keys needs preset, reset, or params");
+  const params = record(args.params, "params");
+  const values: Record<string, number | string | null> = { ...organ };
+  for (const [name, value] of Object.entries(params)) {
+    const param = keysParamName(name);
+    if (!param)
+      throw new ToolArgumentError(
+        `keys has no parameter ${name} (DAWG.md lists them under Keys)`,
+      );
+    if (
+      value !== null &&
+      typeof value !== "number" &&
+      typeof value !== "string"
+    )
+      throw new ToolArgumentError(`keys ${param} takes a number or a word`);
+    values[param] = value;
+  }
+  return { type: "keys-set", values };
+}
+
+/** Instrument words the agent may pick: the voice bank plus the pianos. */
 function synthToolCommand(args: Record<string, unknown>): SynthCommand {
   if (args.reset === true) return { type: "synth-reset" };
   if (args.zzfx !== undefined) {
@@ -1578,6 +2227,46 @@ function synthToolCommand(args: Record<string, unknown>): SynthCommand {
   return { type: "synth-set", values };
 }
 
+function stringToolCommands(args: Record<string, unknown>): StringCommand[] {
+  if (args.off === true) return [{ type: "string-off" }];
+  const commands: StringCommand[] = [];
+  if (args.preset !== undefined) {
+    const preset =
+      typeof args.preset === "string"
+        ? stringPresetName(args.preset)
+        : undefined;
+    if (!preset)
+      throw new ToolArgumentError(
+        `string presets: ${STRING_PRESET_NAMES.join(", ")}`,
+      );
+    commands.push({ type: "string-preset", preset });
+  }
+  if (args.reset === true) commands.push({ type: "string-reset" });
+  if (args.params !== undefined) {
+    const values: Record<string, number | string | null> = {};
+    for (const [name, value] of Object.entries(record(args.params, "params"))) {
+      const param = stringParamName(name);
+      if (!param)
+        throw new ToolArgumentError(
+          `string has no parameter ${name}; params: ${Object.keys(STRING_PARAMS).join(", ")}`,
+        );
+      if (
+        value !== null &&
+        typeof value !== "number" &&
+        typeof value !== "string"
+      )
+        throw new ToolArgumentError(`string ${name} must be a value`);
+      values[param] = value;
+    }
+    commands.push({ type: "string-set", values });
+  }
+  if (commands.length === 0)
+    throw new ToolArgumentError(
+      "set_string needs preset, params, reset or off",
+    );
+  return commands;
+}
+
 function targetTrack(args: Record<string, unknown>, context: ToolContext) {
   const trackId = args.trackId ?? context.focusedTrackId;
   if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
@@ -1597,15 +2286,35 @@ function knownNoteId(value: unknown, context: ToolContext, label: string) {
   return value;
 }
 
-function instrumentName(value: unknown): string {
+/**
+ * The track patch an instrument word means: legacy words store themselves,
+ * `string` and the string resolver words (nylon, koto, harp…) also write
+ * the `Track.string` preset the engine needs.
+ */
+function instrumentName(value: unknown): {
+  instrument: string;
+  string?: { preset: string };
+  modal?: TrackModal;
+  wind?: TrackWind;
+} {
+  const word = typeof value === "string" ? value.trim() : undefined;
+  if (word === STRING_INSTRUMENT)
+    return {
+      instrument: STRING_INSTRUMENT,
+      string: { preset: DEFAULT_STRING_PRESET },
+    };
+  const patch = word === undefined ? undefined : instrumentPatch(word);
   if (
-    typeof value !== "string" ||
-    !(AVAILABLE_INSTRUMENTS as readonly string[]).includes(value)
+    patch === undefined ||
+    (!patch.string &&
+      !patch.modal &&
+      !patch.wind &&
+      !(AVAILABLE_INSTRUMENTS as readonly string[]).includes(patch.instrument))
   )
     throw new ToolArgumentError(
-      `instrument must be one of ${AVAILABLE_INSTRUMENTS.join(", ")}`,
+      `instrument must be one of ${INSTRUMENT_ENUM.join(", ")}`,
     );
-  return value;
+  return patch;
 }
 
 function pitch(value: unknown, label: string): number {