@hraness/dawg 0.5.0 → 0.6.1

package/guides/performance.md

@@ -12,13 +12,16 @@ Targets are `all` (default), `bar 3`, `bars 2-4` or note ids.
 
 - "make the bass slide like a 303" · "ghost the off-beat hats"
 - "pedal the piano every bar" · "humanize the drums a little"
+- "play the piano una corda" · "hold the bass note with sostenuto"
 
 ## Type it yourself
 
 - `art staccato|legato|accent|tenuto|marcato|ghost [target]`
 - `glide 60ms legato` per track · `glide 60ms bar 2` per note
+- bowed strings slur overlapping or `art legato` notes in one bow stroke
 - `bend scoop|fall|doit|-200 [target]` · `vibrato 5.5 30 0.2`
 - `pedal 0-3.5 4-7.5` (beats) · `pedal bars` · `pedal off`
+- `pedal soft 0-8` una corda · `pedal sost 0-4` holds keys down at 0
 - `velcurve soft|hard|fixed 0.7` · `humanize 8 5 10 seed 3`
 
 ## Menu

package/guides/resample.md

@@ -0,0 +1,26 @@
+---
+id: resample
+title: Resample, grains and shift
+parent: sound
+order: 8
+---
+
+Turn a part into a sample, grain it, and play the grains like an instrument.
+
+## Ask
+
+- "resample the lead and make a grain cloud of bars 1-2"
+- "shift the vocal sample up a fifth but keep its character"
+
+## Type it yourself
+
+- `resample lead` · `resample drums bars 1-2 grain` · `resample master section chorus`
+- `shift 7` same length · `shift 7 formant keep` · `fade out 0.5` · `fade in 0.05`
+- `grain sync 1/16` · `grain quant scale` · `grain mono on` · `grain pedal on`
+- `automate grain-pos points 0:0.1 8:0.9` sweeps the head
+
+## Menu
+
+- Ctrl-K › Project › Resample: a track, an orbit or the mix
+- Ctrl-K › Sound › granular: Sync, Quant, Mono, Pedal
+- Ctrl-K › Sound › Sample: Shift, Formant, Fade in, Fade out

package/guides/sounds.md

@@ -14,12 +14,17 @@ order: 1
 
 - `instrument sawtooth` · sine square triangle supersaw pulse
 - `synth preset pluck` · pad lead bass acid keys bell organ strings
-- `synth lpf 800 lpenv 3` any parameter · `synth adsr 0.01 0.2 0.5 0.3`
-- `synth lpf off` · `synth reset` · `synth` lists what is set
+- `synth lpf 800 lpenv 3` · `synth adsr 0.01 0.2 0.5 0.3` · `synth reset`
+- `piano felt` · `epiano suitcase` · `wurli` · `clav` · `keys hardness 0.3`
+- `tonewheel` gospel · `combo` vox · `pipe` flutes · `rotary fast` · `keys`
 - `wt list` tables · `wt pwm` load one · `wt 0.5` position
+- `string sitar` · `bowed violin` · cellos erhu koto … · `string presets`
+- `wind sax` · flute trumpet … · `wind breath 0.8` · `modal gamelan` bronzes
 - `/pack list` · `/pack use <pack>/<sound> as kick` · `/pack info vcsl`
 - `/sample samples/kick.wav as kick` add a sampler voice
+- `/bpm 174` sample tempo (`bpm` is the song's) · `fitmode beats` · `len 8`
 
 ## Menu
 
 - Ctrl-K › Sound: instrument, preset, envelope, filter, browse sounds
+- Ctrl-K › Sound › browse sounds › Strings: plucked presets, Bowed

package/guides/tempo.md

@@ -20,6 +20,7 @@ Positions are beats from 0 or `bar <n>`.
 - `fermata at 31 2` hold beat 31 for 2 extra beats
 - `meter 7/8 at bar 5` · `tempo map` show it · `tempo clear`
 - `track rate 3/2` · `track cycle 3` · `track phasing 3` · `track time off`
+- `/bpm 174` on a sampler voice follows the map · `fitmode beats|tones` keeps pitch
 
 ## Menu
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/dawg",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/agent/agent.ts

@@ -1,3 +1,4 @@
+import { GRANULAR_PARAMS } from "../../core/granular.ts";
 import {
   applyScoreOperation,
   type ScoreOperation,
@@ -201,10 +202,22 @@ export const AGENT_SYSTEM_PROMPT = [
   "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.",
+  "Bowed strings: set_string preset violin|viola|cello|contrabass|fiddle|erhu|kamancheh|violins|violas|cellos|contrabasses|pizz|trem plays a bowed physical model (bow params pressure speed attack vib vibmod vibdelay tremhz sord dyn). Overlapping or legato notes slur in one bow. The bare words cello, contrabass and strings keep their older voices; use set_string (or the words violin, viola, fiddle, erhu, violins, cellos) for the bowed ones. Sampler voices take vel [lo, hi] velocity layers and rr round-robin groups via set_sample.",
+  "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; sym 0.5 adds sympathetic bloom under the sustain pedal for pedalled Romantic and Impressionist playing). A track already stored as instrument piano keeps the legacy tone until you set it again.",
+  "Electric keys: set_instrument epiano (rhodes; suitcase stereo vibe, dyno bright 80s), wurli, clav (funkclav); set_keys tweaks bark bell tone vibe (epiano), trem (wurli), pickup neck|bridge|both|out and mute (clav). Soft and sostenuto pedals: set_piano_pedals on any modelled piano.",
+  'Organs: set_instrument tonewheel (hammond b3 gospel jazzorgan), combo (farfisa vox) or pipe (church flutes cornet reeds celeste) loads a modelled organ; instrument organ stays the legacy sine. set_keys drawbars "888800008" (16\' to 1\'), registers "08880" (combo), stops ["principal8","octave4"] or plenum|flutes|cornet|reeds|strings|full (pipe), rotary slow|fast|stop, params perc 3rd percdecay percvol click scanner c3 drive chiff wind trem (each family takes only its own rows); automate keys-rotary and keys-drive lanes.',
+  "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.",
+  "Gamelan: set_modal preset saron demung slenthem gangsa gender bonang kenong kethuk kempul (gong too) with tuning slendro or pelog; for ombak (the shimmer) put the same part on two gangsa tracks and set_modal pair <other track> on one: it sounds ombak Hz (default 6) above its partner. Frame drums: daf bodhran tabla.",
+  "Winds and brass: set_instrument flute recorder whistle ney shakuhachi panpipe suling bansuri clarinet bassclarinet oboe bassoon sax altosax barisax trumpet harmon plunger trombone tuba horn plays the wind engine; set_wind changes breath, bright, mute (open straight cup harmon plunger), players (2..8 spreads a section over chord tones), growl, vib. Lines slur unless re-tongued (gaps or articulations). Plain instrument wind 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). Sidechain: put pads/bass on `orbit` 2 and give the kick `duck` (orbit 2, preset pump); a ducker never ducks itself.",
+  "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.",
+  "Shoegaze: rig shoegaze|glide|dreampop|swell|ebow (or a track named shoegaze); set_fx wobble (tremolo-arm bend: depth cents, rate, drift), bloom (feedback swell on the top note), swell (volume swell: time), double (second take: time, drift, width); reverb ir builtin:reverse|gate|spring. Strumming: set_guitar (tune dadgad, capo, hand, ring), strum_chords (chords or the track's own, strokes folk|pop|punk… or D-DU-UDU, speed ms), write_chords perform guitar.",
   "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. Grain play: sync "1/16" puts grain onsets on the tempo grid, quant scale|chord snaps grain pitches, mono true glides legato notes through one cloud, pedal true freezes the head while the sustain pedal is down; set_automation grain-<param> lanes (grain-pos, grain-scan, grain-pitch …) move a parameter over beats. Resample: the resample tool renders a track, orbit or the mix (a section or bars) to a pinned WAV and adds a sampler track, or with grain a granular track, that plays it; set_sample shift (semitones, length kept, formant 0 keeps a voice's character) and fadeInTime/fadeTime shape a sampler voice.`,
   "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.",
   "If a call is rejected, read the diagnostic and either fix the arguments or stop.",
   WORKSPACE_PROMPT,

package/src/agent/chord-tools.ts

@@ -12,8 +12,12 @@ import {
   generateProgression,
   keyName,
   parseKey,
+  DEFAULT_STROKE_SPEED,
+  GUITAR_TUNING_NAMES,
   PERFORM_MODES,
   PROGRESSION_PRESETS,
+  STROKE_PATTERN_NAMES,
+  strokeGrid,
   PROGRESSION_STYLES,
   renderProgression,
   resolveChord,
@@ -27,6 +31,12 @@ import { midiToPitch } from "../../core/pitch.ts";
 import { resolveTuning, snapToTuning } from "../../core/tuning.ts";
 import { SCORE_LIMITS, type ScoreOperation } from "../../core/score.ts";
 import type { AgentTool, ToolContext } from "./tools.ts";
+import {
+  applyGuitarCommand,
+  parseGuitarCommand,
+  planStrum,
+  StrumError,
+} from "../commands/strum.ts";
 
 /** Most notes one write_chords call may add (arpeggios multiply fast). */
 export const MAX_CHORD_NOTES = 512;
@@ -193,7 +203,9 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
         perform: { type: "string", enum: [...PERFORM_MODES] },
         rate: { ...num, description: "arp step, beats" },
         octaves: int,
-        strum: num,
+        strum: { ...num, description: "strum/strum-up gap, beats" },
+        strokes: { ...str, description: "perform guitar: see strum_chords" },
+        speed: { ...num, description: "perform guitar: ms per stroke" },
         velocity: num,
         pattern: { type: "string", enum: CHORD_PATTERNS.map((p) => p.name) },
         bass: bool,
@@ -225,6 +237,15 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
       const velocity = finite(args, "velocity", 0, 1);
       const rate = finite(args, "rate", 0.0625, 4);
       const strum = finite(args, "strum", 0, 1);
+      const speedMs = finite(args, "speed", 0, 200);
+      const strokes = args.strokes;
+      if (
+        strokes !== undefined &&
+        (typeof strokes !== "string" || !strokeGrid(strokes))
+      )
+        throw new ChordToolError(
+          `strokes must be ${STROKE_PATTERN_NAMES.join(", ")} or a grid of D U d u x - .`,
+        );
       const octaves = integer(args, "octaves", 1, 4);
       const pattern = args.pattern;
       if (
@@ -259,6 +280,16 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
           ...(velocity !== undefined ? { velocity } : {}),
           seed: integer(args, "seed", 0, 2 ** 31) ?? 0,
           ...(typeof pattern === "string" ? { pattern } : {}),
+          ...(mode === "guitar"
+            ? {
+                ...(typeof strokes === "string" ? { strokes } : {}),
+                speed: (speedMs ?? DEFAULT_STROKE_SPEED * 1000) / 1000,
+                tempo: context.score.tempoBpm,
+                ...(guitarOf(context, trackId)
+                  ? { guitar: guitarOf(context, trackId) }
+                  : {}),
+              }
+            : {}),
         },
       });
       const total = rendered.notes.length + rendered.bass.length;
@@ -308,8 +339,129 @@ export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    name: "strum_chords",
+    description: `Strum chords as fretted guitar notes (set_guitar). chords omitted strums the track's block chords. strokes ${STROKE_PATTERN_NAMES.join("|")} or a DUdux-. grid; speed ms/stroke (22); step grid beats; each beats/chord (a bar).`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: str,
+        chords: chordsSchema,
+        strokes: str,
+        speed: num,
+        step: num,
+        each: num,
+        at: num,
+        velocity: num,
+        seed: int,
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = trackOf(args.trackId, context, "trackId");
+      const chords = args.chords;
+      if (
+        chords !== undefined &&
+        (!Array.isArray(chords) ||
+          chords.length > MAX_CHORDS ||
+          !chords.every((c) => typeof c === "string"))
+      )
+        throw new ChordToolError(`chords must be up to ${MAX_CHORDS} strings`);
+      if (args.strokes !== undefined && typeof args.strokes !== "string")
+        throw new ChordToolError("strokes must be a string");
+      const speedMs = finite(args, "speed", 0, 200);
+      const step = finite(args, "step", 1 / 32, 4);
+      const each = finite(args, "each", 1e-3, 64);
+      const at = finite(args, "at", 0, Infinity);
+      const velocity = finite(args, "velocity", 0, 1);
+      const seed = integer(args, "seed", 0, 2 ** 31);
+      try {
+        const plan = planStrum(
+          context.score,
+          trackId,
+          {
+            chords: (chords as string[] | undefined) ?? [],
+            ...(typeof args.strokes === "string"
+              ? { strokes: args.strokes }
+              : {}),
+            ...(speedMs !== undefined ? { speedMs } : {}),
+            ...(step !== undefined ? { step } : {}),
+            ...(each !== undefined ? { each } : {}),
+            ...(at !== undefined ? { at } : {}),
+            ...(velocity !== undefined ? { velocity } : {}),
+            ...(seed !== undefined ? { seed } : {}),
+          },
+          (index) => context.newNoteId(trackId, index),
+          MAX_CHORD_NOTES,
+        );
+        return {
+          kind: "score",
+          operations: plan.operations,
+          trackId,
+          summary: `${trackId} strum ${plan.names.join(" ")}`.slice(0, 160),
+        };
+      } catch (error) {
+        if (error instanceof StrumError)
+          throw new ChordToolError(error.message);
+        throw error;
+      }
+    },
+  },
+  {
+    name: "set_guitar",
+    description: `Guitar fretting for strum: tune ${GUITAR_TUNING_NAMES.join("|")} or notes low-high ("D A D G A D"), capo 0..12, hand 3..6 frets, ring 0..1, position 0..12, reset.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: str,
+        tune: str,
+        capo: int,
+        hand: int,
+        ring: num,
+        position: int,
+        reset: bool,
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = trackOf(args.trackId, context, "trackId");
+      let score = context.score;
+      const messages: string[] = [];
+      const run = (command: string) => {
+        const parsed = parseGuitarCommand(command);
+        const result = parsed
+          ? applyGuitarCommand(score, trackId, parsed)
+          : { ok: false, message: `cannot parse ${command}` };
+        if (!result.ok) throw new ChordToolError(result.message);
+        if ("next" in result && result.next) score = result.next;
+        messages.push(result.message);
+      };
+      if (args.reset === true) run("guitar reset");
+      if (args.tune !== undefined) run(`guitar tune ${String(args.tune)}`);
+      for (const field of ["capo", "hand", "ring", "position"] as const)
+        if (args[field] !== undefined)
+          run(`guitar ${field} ${String(args[field])}`);
+      if (messages.length === 0)
+        throw new ChordToolError(
+          "give tune, capo, hand, ring, position or reset",
+        );
+      const guitar = score.tracks.find((t) => t.id === trackId)?.guitar;
+      return {
+        kind: "score",
+        operations: [
+          { type: "updateTrack", trackId, patch: { guitar: guitar ?? null } },
+        ],
+        trackId,
+        summary: messages.at(-1)!,
+      };
+    },
+  },
 ]);
 
+function guitarOf(context: ToolContext, trackId: string) {
+  return context.score.tracks.find((track) => track.id === trackId)?.guitar;
+}
+
 function trackOf(value: unknown, context: ToolContext, label: string): string {
   const trackId = value ?? context.focusedTrackId;
   if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)

package/src/agent/expression-tools.ts

@@ -9,6 +9,7 @@ import {
   ExpressionValidationError,
   GLIDE_MODES,
   PEDAL_STATES,
+  SOSTENUTO_STATES,
   VELOCITY_CURVES,
   normalizeArticulation,
   normalizeBend,
@@ -20,12 +21,14 @@ import {
   normalizeVibrato,
   normalizeNoteHumanize,
   type NoteExpressionPatch,
+  type PedalState,
 } from "../../core/expression.ts";
 import {
   SCORE_LIMITS,
   type ScoreOperation,
   type TrackPatch,
 } from "../../core/score.ts";
+import { softPedalNote } from "../../core/keys.ts";
 import { loopTicksOf } from "../../core/tempo.ts";
 import { BEND_SHAPES, barPedal } from "../commands/expression.ts";
 import type { AgentTool, ToolContext } from "./tools.ts";
@@ -333,4 +336,92 @@ export const EXPRESSION_TOOLS: readonly AgentTool[] = Object.freeze([
       };
     },
   },
+  {
+    // keys-electric (0.6.1): the modelled piano's soft and middle pedals.
+    name: "set_piano_pedals",
+    description:
+      'Modelled piano soft (una corda: fewer strings, softer, darker) and sostenuto (holds only keys down when it presses) pedals. Each: [{beat, state}], "bars" (whole loop) or null. Sostenuto has no half.',
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: { type: "string" },
+        soft: pedalSchema(PEDAL_STATES),
+        sostenuto: pedalSchema(SOSTENUTO_STATES),
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = trackOf(args, context);
+      const score = context.score;
+      const patch: Record<string, unknown> = {};
+      if (args.soft !== undefined)
+        patch.softPedal = pedalLane(args.soft, "soft", score, PEDAL_STATES);
+      if (args.sostenuto !== undefined)
+        patch.sostenuto = pedalLane(
+          args.sostenuto,
+          "sostenuto",
+          score,
+          SOSTENUTO_STATES,
+        );
+      if (Object.keys(patch).length === 0)
+        throw new ExpressionToolError("set soft, sostenuto or both");
+      const track = score.tracks.find((candidate) => candidate.id === trackId);
+      const silent =
+        patch.softPedal && track ? softPedalNote(track) : undefined;
+      if (silent) throw new ExpressionToolError(`soft pedal · ${silent}`);
+      return {
+        kind: "score",
+        operations: [
+          { type: "updateTrack", trackId, patch: patch as TrackPatch },
+        ],
+        trackId,
+        summary: `${trackId} ${Object.entries(patch)
+          .map(([key, value]) => (value === null ? `${key} off` : key))
+          .join(", ")}`,
+      };
+    },
+  },
 ] satisfies AgentTool[]);
+
+function pedalSchema(states: readonly string[]) {
+  return {
+    type: ["array", "string", "null"],
+    items: {
+      type: "object",
+      properties: {
+        beat: { type: "number" },
+        state: { type: "string", enum: states },
+      },
+    },
+  };
+}
+
+/** A soft or sostenuto lane from tool arguments: events, "bars" or null. */
+function pedalLane(
+  value: unknown,
+  label: string,
+  score: ToolContext["score"],
+  states: readonly PedalState[],
+): unknown {
+  if (value === null) return null;
+  // Soft and sostenuto hold through the loop (no re-pedal at each bar).
+  if (value === "bars")
+    return [
+      { tick: 0, state: "down" },
+      { tick: loopTicksOf(score), state: "up" },
+    ];
+  if (!Array.isArray(value))
+    throw new ExpressionToolError(`${label} must be an array, "bars" or null`);
+  const events = value.map((item: unknown, index) => {
+    const event = (item ?? {}) as Record<string, unknown>;
+    const at = beat(event, "beat");
+    if (at === undefined)
+      throw new ExpressionToolError(`${label}[${index}].beat is required`);
+    return { tick: Math.round(at * score.ticksPerBeat), state: event.state };
+  });
+  return (
+    validated(() =>
+      normalizePedal(events, loopTicksOf(score), label, states),
+    ) ?? null
+  );
+}

package/src/agent/granular-tools.ts

@@ -0,0 +1,138 @@
+/**
+ * Agent tool for the granular instrument: `set_granular` edits a track's
+ * `Track.granular` through the same path as the `grain` prompt command, so
+ * the command, the ctrl-k menu, the tool and the SDK store the same object.
+ */
+import {
+  GRANULAR_PARAMS,
+  GRANULAR_PRESET_NAMES,
+  isGranularPreset,
+  synthSourceNames,
+} from "../../core/granular.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import {
+  applyGranularCommand,
+  type GranularCommand,
+} from "../commands/granular.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+
+class GranularToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+function targetTrack(args: Record<string, unknown>, context: ToolContext) {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
+    throw new GranularToolError("trackId must be a short string");
+  if (!context.score.tracks.some((track) => track.id === trackId))
+    throw new GranularToolError(
+      `unknown track ${trackId}; create it with create_track first`,
+    );
+  return trackId;
+}
+
+/** One tool call becomes the `grain` commands it stands for, in order. */
+export function granularToolCommands(
+  args: Record<string, unknown>,
+): GranularCommand[] {
+  const commands: GranularCommand[] = [];
+  if (args.off === true) return [{ type: "grain-off" }];
+  const voice =
+    typeof args.voice === "string" && args.voice.length > 0
+      ? args.voice.toLowerCase()
+      : undefined;
+  if (args.preset !== undefined) {
+    if (typeof args.preset !== "string" || !isGranularPreset(args.preset))
+      throw new GranularToolError(
+        `granular presets: ${GRANULAR_PRESET_NAMES.join(", ")}`,
+      );
+    commands.push({ type: "grain-preset", preset: args.preset, voice });
+  } else if (args.reset === true) commands.push({ type: "grain-reset" });
+  else commands.push({ type: "grain-on", voice });
+  if (args.src !== undefined) {
+    if (typeof args.src !== "string")
+      throw new GranularToolError("src must be synth:<name>[@note]");
+    const text = args.src.startsWith("synth:") ? args.src : `synth:${args.src}`;
+    commands.push({ type: "grain-src", synth: text.toLowerCase() });
+  }
+  if (args.params !== undefined) {
+    if (
+      typeof args.params !== "object" ||
+      args.params === null ||
+      Array.isArray(args.params)
+    )
+      throw new GranularToolError("params must be an object");
+    const values: Record<string, number | string | boolean | null> = {};
+    for (const [name, value] of Object.entries(args.params)) {
+      if (!Object.prototype.hasOwnProperty.call(GRANULAR_PARAMS, name))
+        throw new GranularToolError(
+          `granular has no parameter ${name}; it takes ${Object.keys(GRANULAR_PARAMS).join(", ")}`,
+        );
+      if (
+        value !== null &&
+        typeof value !== "number" &&
+        typeof value !== "string" &&
+        typeof value !== "boolean"
+      )
+        throw new GranularToolError(`granular ${name} must be a value`);
+      values[name] = value;
+    }
+    commands.push({ type: "grain-set", values });
+  }
+  return commands;
+}
+
+export const GRANULAR_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "set_granular",
+    description: `Make a track a granular instrument (offline, nothing to download) or shape it. preset: ${GRANULAR_PRESET_NAMES.join(" ")}. src: a built-in synth source synth:<${synthSourceNames().slice(0, 8).join("|")}|…>[@note]; on a sampler track the first (or named voice) sample is the source. params (null unsets): grain s, overlap, scan (head speed, 0 held), pos, begin, end, spray, jitter, pitch st, detune, shimmer, shimint, spread, window (hann tukey gauss tri perc rperc), reverse 0..1, freeze, repeat, hold, drift, drate, attack, release, veltone, gain, seed, root. reset keeps preset and source; off returns to the previous voice.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: { type: "string" },
+        preset: { type: "string", enum: [...GRANULAR_PRESET_NAMES] },
+        src: { type: "string" },
+        voice: { type: "string" },
+        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);
+      let score = context.score;
+      let message = "";
+      for (const command of granularToolCommands(args)) {
+        const result = applyGranularCommand(score, trackId, command);
+        if (!result.ok) throw new GranularToolError(result.message);
+        if (result.next) score = result.next;
+        message = result.message;
+      }
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: {
+              instrument: next.instrument,
+              granular: next.granular ?? null,
+            },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${message}`,
+      };
+    },
+  },
+]);

package/src/agent/models.ts

@@ -486,17 +486,17 @@ export async function loadLiveCatalog(
  * and `chatTools()` serialized, plus `compositionBrief` of a 3-track, 48-note
  * loop; see models.test.ts, which keeps these in step with the code):
  *
- * - system prompt ≈ 4.3 KB, tool schemas ≈ 38 KB, brief ≈ 1.6 KB typical
- *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 44 KB ≈ 11,000 tokens
+ * - system prompt ≈ 7 KB, tool schemas ≈ 51 KB, brief ≈ 1.6 KB typical
+ *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 59 KB ≈ 14,800 tokens
  *   per request at ~4 bytes per token;
  * - about 2 requests per prompt (tool calls, then a short reply), the second
  *   also carrying the first step's tool calls and results (≈ 0.6 KB);
  * - output ≈ 450 tokens of tool-call arguments and ≈ 150 of reply.
  *
- * So ≈ 22,100 input and ≈ 600 output tokens per prompt.
+ * So ≈ 29,800 input and ≈ 600 output tokens per prompt.
  */
 export const TYPICAL_PROMPT = Object.freeze({
-  inputTokens: 22_100,
+  inputTokens: 29_800,
   outputTokens: 600,
 });
 

package/src/agent/ops.ts

@@ -1,4 +1,10 @@
+import { resolveInstrumentWord } from "../../core/instruments.ts";
 import { pitchToMidi } from "../../core/pitch.ts";
+import {
+  instrumentPatchForWord,
+  type TrackModal,
+  type TrackWind,
+} from "../../core/resonators.ts";
 import { SCORE_LIMITS } from "../../core/score.ts";
 
 export { pitchToMidi };
@@ -34,11 +40,16 @@ export type AgentOperation =
       type: "track";
       patch: {
         instrument?: string;
+        string?: { preset: string };
+        /** 0.6: a modal preset word (`instrument vibes`) sets this too. */
+        modal?: TrackModal;
         muted?: boolean;
         volume?: number;
         pan?: number;
         name?: string;
       };
+      /** The instrument word as typed (a guitar alias also loads its rig). */
+      word?: string;
     }
   | {
       type: "automation";
@@ -74,8 +85,14 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
   const instrument = text.match(
     /^(?:instrument|sound|voice)\s+([a-z0-9._ -]{1,64})$/,
   );
-  if (instrument)
-    return { type: "track", patch: { instrument: instrument[1]!.trim() } };
+  if (instrument) {
+    const word = instrument[1]!.trim();
+    return {
+      type: "track",
+      patch: instrumentPatch(word),
+      ...(resolveInstrumentWord(word)?.fx ? { word } : {}),
+    };
+  }
   if (/^(?:mute|silence)\b/.test(text))
     return { type: "track", patch: { muted: true } };
   if (/^(?:unmute|unsilence)\b/.test(text))
@@ -180,3 +197,26 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
     ...(offset !== 0 ? { cents: offset } : {}),
   };
 }
+
+/**
+ * The track patch an instrument word means: a 0.6 resolver word for the
+ * string engine also writes its preset (`instrument nylon` plays the nylon
+ * string); every other word stores the instrument as before.
+ */
+export function instrumentPatch(word: string): {
+  instrument: string;
+  string?: { preset: string };
+  modal?: TrackModal;
+  wind?: TrackWind;
+} {
+  const meaning = resolveInstrumentWord(word);
+  if (!meaning) return { instrument: word };
+  if (meaning.field === "modal" || meaning.field === "wind")
+    return instrumentPatchForWord(word);
+  if (meaning.field === "string" && meaning.preset)
+    return {
+      instrument: meaning.instrument,
+      string: { preset: meaning.preset },
+    };
+  return { instrument: meaning.instrument };
+}