@hraness/dawg 0.6.0 → 0.7.0

package/src/agent/agent.ts

@@ -1,3 +1,4 @@
+import type { CommandHost } from "./command-agent.ts";
 import { GRANULAR_PARAMS } from "../../core/granular.ts";
 import {
   applyScoreOperation,
@@ -38,7 +39,9 @@ import { projectOutline, type ProjectOutline } from "./workspace.ts";
 export const AGENT_LIMITS = Object.freeze({
   maxSteps: 8,
   maxToolCalls: 32,
-  maxResponseBytes: 256 * 1024,
+  // Raw SSE bytes, framing included: each streamed token costs ~150-200
+  // bytes, so reasoning models need room beyond the visible reply.
+  maxResponseBytes: 1024 * 1024,
   maxToolArgumentBytes: 32 * 1024,
   timeoutMs: 90_000,
   maxTextChars: 4_000,
@@ -71,6 +74,20 @@ export type AgentEvent =
       costUsd?: number;
     }
   | { type: "text-delta"; delta: string }
+  /**
+   * Command mode: the command line the model is writing, as it streams
+   * (empty once the line is done), for the prompt bar's ghost text.
+   */
+  | { type: "command-typing"; text: string }
+  /** Command mode: one complete line ran through the typed-command path. */
+  | {
+      type: "command";
+      line: string;
+      ok: boolean;
+      message: string;
+      baseRevision: number;
+      resultRevision: number;
+    }
   /** Provider progress worth a status line (a retry), not model output. */
   | { type: "activity"; message: string }
   | { type: "tool-start"; callId: string; name: string; step: number }
@@ -165,6 +182,11 @@ export type AgentHost = Readonly<{
   packs?: PackStore;
   /** How preview_sound renders and plays (the TUI plays it once). */
   preview?: PreviewHost;
+  /**
+   * Show-me command mode: the agent writes prompt commands that run through
+   * the user's own command path. Absent keeps the JSON tool loop.
+   */
+  commands?: CommandHost;
 }>;
 
 export type AgentTurnOptions = Readonly<{
@@ -172,6 +194,8 @@ export type AgentTurnOptions = Readonly<{
   /** An alias (`opus-5.5`) or an exact `vendor/model` ID. */
   model: GatewayModel | string;
   client: GatewayClient;
+  /** A model ID to try once when `model` fails before its first byte. */
+  fallbackModel?: string;
   host: AgentHost;
   onEvent?: (event: AgentEvent) => void;
   signal?: AbortSignal;
@@ -193,30 +217,79 @@ export const WORKSPACE_PROMPT = [
 export const MEDIA_PROMPT =
   "Media tools (download_audio, split_stems, analyze_audio, transcribe_notes, import_sample, make_wavetable, transcribe_lyrics) work on files under tracks/<slug>/downloads/ and report project-relative paths; the brief's project tree lists what is already there (read_file reports a wav's type and size), so never download the same video twice. They can run for minutes, so call them one at a time and chain on their outputs (download → stems → analyze → notes). make_wavetable turns a download, stem or sample into tracks/<slug>/wavetables/<name>.wav and describes its sweep; play it with set_wavetable table <that path>.";
 
+/**
+ * Lets a model end the turn in the same response as its last tool calls,
+ * which saves the summary-only round trip (about a third of a typical turn).
+ */
+export const DONE_PROMPT =
+  'When you are done, reply with one short sentence describing the musical change. For a tempo, mix, effect or sound change, you may instead put that sentence first, beginning "Done:", before the calls.';
+
+/**
+ * Tools that write musical content (notes, rhythms, chords, structure).
+ * The eval shows models skipping their self-check when they end the turn
+ * early on these, so a step containing one always gets a reply step, even
+ * after "Done:". Parameter edits (tempo, mix, fx, instruments) and project
+ * file edits, which passed every eval run either way, end early.
+ */
+export const CONTENT_TOOLS: ReadonlySet<string> = new Set([
+  "add_notes",
+  "update_notes",
+  "remove_notes",
+  "add_drums",
+  "set_rhythm",
+  "apply_drum_pattern",
+  "write_chords",
+  "strum_chords",
+  "set_automation",
+  "add_transition",
+  "edit_section",
+  "set_form",
+  "extend_loop",
+  "edit_clip",
+  "place_clip",
+]);
+
+/** `Done: added a kick` → `added a kick`; anything else → undefined. */
+export function doneSummary(text: string): string | undefined {
+  const match = /^\s*\**done\**\s*[:\u2014\u2013-]\s*([\s\S]*)$/i.exec(text);
+  if (!match) return undefined;
+  const rest = match[1]!.trim();
+  return rest ? rest.charAt(0).toUpperCase() + rest.slice(1) : "Done.";
+}
+
 export const AGENT_SYSTEM_PROMPT = [
   "You are dawg, a loop composer inside a terminal music workstation.",
   "Edit the score only by calling the provided tools; every call is validated and applied immediately, and its result tells you the new revision.",
-  "Times are in beats from the loop start (0-based). Keep notes inside loopBeats unless you extend the loop first.",
+  'Times are in beats from the loop start (0-based), while musicians count from 1: in 4/4 "beats 2 and 4" are beats 1 and 3 of each bar here, "the and of 1" is 0.5, and bar n starts at (n-1)×beats per bar. Keep notes inside loopBeats unless you extend the loop first.',
   "Prefer a few well-formed calls (one add_notes call per track part) over many tiny ones.",
-  'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a genre groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit; use add_drums only for one-off fills. Drum pitches select voices, so do not use add_notes for beats.',
+  'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a style groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit. Drum pitches select voices, so do not use add_notes for beats.',
   "Song structure: list_sections shows named sections (bars count from 1); edit_section marks, adds, duplicates, moves, renames, deletes, mutes, varies (transpose/gain) and loops them; set_form sets the play order with repeats (intro verse chorus*2 outro); add_transition generates builds (riser, snare roll, filter sweep, uplifter), drops (cut plus impact) and drum fills at section boundaries.",
   CHORD_PROCESS,
   "Synth voices: set_synth shapes a synth track with Strudel params (ADSR, lpf/lpenv filter envelopes, fm/fmh, supersaw unison/detune, vib, penv, noise; z_* ZzFX sounds take slide/pitchJump/lfo/zcrush…) or a preset (pad lead pluck bass keys bell…).",
-  "Plucked strings: set_string makes a track a physical-model string (nylon steel electric jangle ebass slap upright motown sitar tanpura harpsichord lute oud setar tar santur dulcimer koto harp banjo tres requinto) and overrides params (ring bright damp pos mute buzz body sym). The bare words sitar, ebass, pluck keep their older voices; use set_string for the modelled ones.",
-  "Pianos: set_instrument piano (or grand upright felt honkytonk prepared, ballad, lofi) loads a modelled piano with real hammers, stretched inharmonic strings, dampers and the sustain pedal; set_keys tweaks it (hardness touch decay release felt stretch body…, automate as keys-<param> lanes). A track already stored as instrument piano keeps the legacy tone until you set it again.",
+  "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 modeled 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 modeled 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 modeled piano.",
+  'Organs: set_instrument tonewheel (hammond b3 gospel jazzorgan), combo (farfisa vox) or pipe (church flutes cornet reeds celeste) loads a modeled 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.",
+  "Autotune (0.7): autotune_vocal corrects pitch on a track's clips and sampler voices; presets hard robot warble trap pop natural gentle guided locked (pop by default). Scale targets use the song or track key and tuning, so maqam, raga and n-EDO work; to chord follows the chords; to notes with from <track> follows a guide melody. Preview it, and use analyze_pitch to find the key first when unsure.",
+  "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.",
+  "Voices (0.7): set_instrument aah ooh choir chorale (or set_sing preset oohchoir airy glass lament soprano basso drone) plays the built-in singing voice, a synthetic glottal source through formants (never a cloned voice); set_sing params voice (auto soprano alto tenor bass), vowel (a e i o u or a>o), voices 2..8 (an ensemble), breath, vib, jitter, bright; set_vowels puts vowels on notes. Throat singing: khoomei, sygyt (whistle) and kargyraa (sub growl) hold a drone (set_sing params drone D2) and each note picks a harmonic of it.",
+  "Vocoder: a vocoder is a carrier track whose vocoder.src is the modulator (usually the user's vocal). make one with create_track (instrument vocoder), then set_vocoder with src set to the vocal, and mute the vocal; talkbox suits funk and soul, choir and glass suit hyperpop, robot and smear suit electronic or ambient. Vocode only the user's own or licensed audio, never an identifiable third party's speech unless the user confirms they hold the rights.",
   "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.",
+  "Effects (set_fx 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.`,
+  `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,
   MEDIA_PROMPT,
-  "When you are done, reply with one short sentence describing the musical change.",
+  DONE_PROMPT,
 ].join(" ");
 
 /**
@@ -277,6 +350,7 @@ export async function runAgentTurn(
     return result;
   };
   const currentRevision = () => options.host.snapshot().revision;
+  const turnStartRevision = currentRevision();
 
   try {
     for (let step = 1; step <= limits.maxSteps; step += 1) {
@@ -294,9 +368,17 @@ export async function runAgentTurn(
       });
       // The brief already describes the current score, so tool results from
       // older steps only need to say what happened, not repeat it in full.
+      // It sits before the user request, so once this turn has edited the
+      // score it says so: otherwise a model reads the edited notes as the
+      // starting point and applies the same edit again (a transpose that
+      // repeats until the step limit).
+      const briefMessage = (json: string, revision: number) =>
+        revision === turnStartRevision
+          ? `Composition brief (JSON): ${json}`
+          : `Composition brief (JSON, the current score at revision ${revision}: it already includes every edit your tool calls made this turn, starting from revision ${turnStartRevision}; do not repeat them): ${json}`;
       const request: ChatMessage[] = [
         messages[0]!,
-        { role: "system", content: `Composition brief (JSON): ${brief}` },
+        { role: "system", content: briefMessage(brief, snapshot.revision) },
         ...messages.slice(1).map((message, offset) => {
           const producedAt = toolResultStep.get(offset + 1);
           return message.role === "tool" &&
@@ -324,6 +406,9 @@ export async function runAgentTurn(
           messages: request,
           tools: chatToolList,
           maxResponseBytes: remaining,
+          ...(options.fallbackModel
+            ? { fallbackModelId: options.fallbackModel }
+            : {}),
         },
         signal,
       )) {
@@ -376,7 +461,7 @@ export async function runAgentTurn(
         }
       }
       bytesUsed += streamBytes;
-      if (text.trim()) finalText = text.trim();
+      if (text.trim()) finalText = doneSummary(text) ?? text.trim();
 
       const calls = [...pending.entries()]
         .sort(([left], [right]) => left - right)
@@ -405,6 +490,11 @@ export async function runAgentTurn(
         tool_calls: assistantCalls,
       });
       let overBudget = false;
+      let stepMutated = 0;
+      let stepRejected = 0;
+      const stepWritesContent = calls.some((call) =>
+        CONTENT_TOOLS.has(call.name),
+      );
       for (const call of calls) {
         if (signal.aborted) throw signal.reason;
         let content: string;
@@ -439,10 +529,12 @@ export async function runAgentTurn(
           });
           if (outcome.ok) {
             applied += outcome.mutated ? 1 : 0;
+            stepMutated += outcome.mutated ? 1 : 0;
             if (outcome.explanation) finalText = outcome.explanation;
             emit(outcome.event);
           } else {
             rejected += 1;
+            stepRejected += 1;
             emit({
               type: "tool-rejected",
               callId: call.id,
@@ -455,6 +547,25 @@ export async function runAgentTurn(
         toolResultStep.set(messages.length, step);
         messages.push({ role: "tool", tool_call_id: call.id, content });
       }
+      // "Done:" in the same response as the calls ends the turn here, but
+      // only when something changed and nothing was rejected: a rejection
+      // still goes back to the model so it can fix the arguments.
+      const done = doneSummary(text);
+      if (
+        done !== undefined &&
+        stepMutated > 0 &&
+        stepRejected === 0 &&
+        !stepWritesContent
+      ) {
+        return finish({
+          type: "done",
+          reason: "stop",
+          text: done.slice(0, AGENT_LIMITS.maxTextChars),
+          applied,
+          rejected,
+          revision: currentRevision(),
+        });
+      }
       if (overBudget || toolCalls >= limits.maxToolCalls) {
         return finish({
           type: "done",
@@ -831,7 +942,7 @@ export function classifyAgentError(
   signal: AbortSignal,
   userSignal: AbortSignal | undefined,
 ): { code: AgentErrorCode; message: string } {
-  if (userSignal?.aborted) return { code: "aborted", message: "cancelled" };
+  if (userSignal?.aborted) return { code: "aborted", message: "canceled" };
   if (
     error instanceof AgentTimeoutError ||
     signal.reason instanceof AgentTimeoutError
@@ -851,7 +962,14 @@ export function classifyAgentError(
   if (error instanceof Error && error.name === "XcbError")
     return { code: "provider", message: errorMessage(error) };
   if (error instanceof Error && error.name === "AbortError")
-    return { code: "aborted", message: "cancelled" };
+    return { code: "aborted", message: "canceled" };
+  // A transport timeout (AbortSignal.timeout's DOMException) that escaped the
+  // client is still the provider's failure, not an internal one.
+  if (error instanceof Error && error.name === "TimeoutError")
+    return {
+      code: "provider",
+      message: `model request timed out: ${errorMessage(error)}`,
+    };
   return { code: "internal", message: errorMessage(error) };
 }
 
@@ -891,7 +1009,7 @@ export function describeAgentEvent(event: AgentEvent): string | undefined {
       );
     case "error":
       return event.code === "aborted"
-        ? `cancelled · kept rev ${event.revision}`
+        ? `canceled · kept rev ${event.revision}`
         : `agent ${event.code}: ${event.message}`;
   }
 }

package/src/agent/calibration-tools.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent tool `set_calibration`: runs the same `/calibration` command the
+ * prompt and the menu do (src/commands/calibration.ts).
+ */
+
+import { CALIBRATION_LATEST } from "../../core/score.ts";
+import {
+  applyCalibrationCommand,
+  parseCalibrationCommand,
+} from "../commands/calibration.ts";
+import { ToolArgumentError } from "./tool-error.ts";
+import type { AgentTool } from "./tools.ts";
+
+const SET_CALIBRATION: AgentTool = {
+  name: "set_calibration",
+  description: `Set the song's sound calibration: ${CALIBRATION_LATEST} (latest) chokes the open hat, tunes GM toms, adds crash, ride and cowbell, levels keys presets and steadies lip brass; 0 keeps the legacy 0.4 to 0.6.1 sound byte-identical. New songs start at the latest.`,
+  parameters: {
+    type: "object",
+    properties: {
+      calibration: { type: "integer", minimum: 0, maximum: CALIBRATION_LATEST },
+    },
+    required: ["calibration"],
+    additionalProperties: false,
+  },
+  plan(args, context) {
+    const value = args.calibration;
+    if (
+      typeof value !== "number" ||
+      !Number.isInteger(value) ||
+      value < 0 ||
+      value > CALIBRATION_LATEST
+    )
+      throw new ToolArgumentError(
+        `calibration must be an integer 0..${CALIBRATION_LATEST}`,
+      );
+    const result = applyCalibrationCommand(
+      context.score,
+      parseCalibrationCommand(`calibration ${value}`)!,
+    );
+    if (!result.ok) throw new ToolArgumentError(result.message);
+    return {
+      kind: "score",
+      operations: [
+        { type: "setCalibration", calibration: value === 0 ? null : value },
+      ],
+      summary: result.message,
+    };
+  },
+};
+
+export const CALIBRATION_TOOLS: readonly AgentTool[] = Object.freeze([
+  SET_CALIBRATION,
+]);

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)