@hraness/dawg 0.5.0 → 0.6.0

package/src/agent/tools.ts

@@ -1,3 +1,19 @@
+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 {
   AUTOMATION_PARAMETERS,
   automationPoints,
@@ -16,6 +32,24 @@ 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,
+  KEYS_SIMPLE,
+  isKeysPreset,
+  keysParamName,
+} from "../../core/keys.ts";
 import {
   setSampleControls,
   type SampleControlValue,
@@ -23,16 +57,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 +95,9 @@ 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 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 +131,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 +473,47 @@ 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; set_modal 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();
+        const preset = word === "piano" ? "grand" : 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.instrument}`,
       };
     },
   },
@@ -635,6 +710,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) 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,6 +841,198 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "set_string",
+    description:
+      "Make a track a plucked string (physical model): 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); null unsets one. 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: preset (instrument, keys and its effects), params ${KEYS_SIMPLE.join(" ")}… (null unsets; DAWG.md lists all), or reset. Stored "piano" stays legacy; set_instrument piano writes grand.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: trackIdSchema,
+        preset: { type: "string", enum: Object.keys(KEYS_PRESETS) },
+        reset: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: { type: ["number", "string", "null"] },
+        },
+      },
+      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; 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; 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] },
+        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.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)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: { instrument: next.instrument, modal: next.modal ?? null },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${messages.at(-1)}`,
+      };
+    },
+  },
   {
     name: "set_sample",
     description:
@@ -727,6 +1080,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 +1484,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 +1497,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 = word === "piano" ? "grand" : 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 +1821,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   ...MEDIA_TOOLS,
   ...PACK_TOOLS,
   ...MASTER_TOOLS,
+  ...GRANULAR_TOOLS,
   // Looks tools up at call time, so it can plan any of the above.
   previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);
@@ -1534,6 +1969,37 @@ function fxToolCommand(
   return { type: "fx-set", effect, values };
 }
 
+function keysToolCommand(args: Record<string, unknown>): KeysCommand {
+  if (args.reset === true) return { type: "keys-reset" };
+  if (args.preset !== undefined) {
+    if (typeof args.preset !== "string" || !isKeysPreset(args.preset))
+      throw new ToolArgumentError(
+        `keys presets: ${Object.keys(KEYS_PRESETS).join(", ")}`,
+      );
+    return { type: "keys-preset", preset: args.preset };
+  }
+  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> = {};
+  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 +2044,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 +2103,33 @@ 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;
+} {
+  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 &&
+      !(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 {