@hraness/dawg 0.3.0 → 0.4.1

package/package.json

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

package/src/agent/agent.ts

@@ -3,7 +3,10 @@ import {
   type ScoreOperation,
   type TrackScore,
 } from "../../core/score.ts";
+import { CHORD_PROCESS } from "../../core/chords.ts";
 import type { MediaServices } from "../media/types.ts";
+import type { PackStore } from "../audio/packs.ts";
+import type { PreviewHost } from "./preview-tool.ts";
 import { compositionBrief } from "./brief.ts";
 import {
   GatewayError,
@@ -12,6 +15,8 @@ import {
   type GatewayClient,
   type GatewayModel,
 } from "./gateway.ts";
+import { diffScores } from "../../core/diff.ts";
+import { reconcileRhythm } from "../../core/rhythm.ts";
 import { validateAgentOperation } from "./planner.ts";
 import { SseBudgetError } from "./sse.ts";
 import {
@@ -155,6 +160,10 @@ export type AgentHost = Readonly<{
   web?: WebHost;
   /** Runner and env for the media tools (root and slug come from `workspace`); absent → rejected. */
   media?: MediaServices;
+  /** Sample packs for the pack tools; default the user cache. */
+  packs?: PackStore;
+  /** How preview_sound renders and plays (the TUI plays it once). */
+  preview?: PreviewHost;
 }>;
 
 export type AgentTurnOptions = Readonly<{
@@ -181,15 +190,20 @@ export const WORKSPACE_PROMPT = [
 ].join(" ");
 /** Shared by both agent loops: how the media tools fit the composition flow. */
 export const MEDIA_PROMPT =
-  "Media tools (download_audio, split_stems, analyze_audio, transcribe_notes, import_sample, 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).";
+  "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>.";
 
 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.",
   "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 use add_drums; drum pitches select voices, so do not use add_notes for beats.',
-  "Effects (set_effects, set_automation): low-pass filter cutoff 20..20000 Hz and resonance 0..1; stereo delay beats 0.0625..4, feedback 0..0.9, mix 0..1; stereo reverb mix 0..1 (0.15..0.35 is a natural room) and size 0..1; pan -1..1 is equal-power stereo. Automatable lanes: volume, pan, filter, resonance, delay-feedback, delay-mix.",
+  '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.',
+  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…).",
+  "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.",
+  "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.",
+  "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.",
   "If a call is rejected, read the diagnostic and either fix the arguments or stop.",
   WORKSPACE_PROMPT,
   MEDIA_PROMPT,
@@ -551,6 +565,18 @@ export async function executeCall(
       event: appliedEvent(plan.summary, snapshot.revision),
     };
   }
+  if (plan.kind === "prepare") {
+    try {
+      plan = await plan.run({
+        ...(context.host.packs ? { packs: context.host.packs } : {}),
+        ...(context.signal ? { signal: context.signal } : {}),
+      });
+    } catch (error) {
+      if (context.signal?.aborted) throw context.signal.reason;
+      if (isActionDiagnostic(error)) return reject(errorMessage(error));
+      return reject(`${call.name} failed: ${errorMessage(error)}`);
+    }
+  }
   if (plan.kind === "action") {
     const action: ActionContext = {
       ...(context.host.workspace ? { workspace: context.host.workspace } : {}),
@@ -561,6 +587,8 @@ export async function executeCall(
           }
         : {}),
       ...(context.host.web ? { web: context.host.web } : {}),
+      ...(context.host.packs ? { packs: context.host.packs } : {}),
+      ...(context.host.preview ? { preview: context.host.preview } : {}),
       ...(context.signal ? { signal: context.signal } : {}),
     };
     try {
@@ -642,6 +670,13 @@ export async function executeCall(
       next = applyScoreOperation(next, operation);
       operations.push(operation);
     }
+    // Keep rhythm rows and their lanes consistent (regenerate after a loop
+    // resize, freeze a row whose lane the tool edited by hand).
+    const reconciled = reconcileRhythm(snapshot.score, next);
+    if (reconciled !== next) {
+      operations.push(...diffScores(next, reconciled));
+      next = reconciled;
+    }
   } catch (error) {
     return reject(`rejected by score validation: ${errorMessage(error)}`);
   }

package/src/agent/brief.ts

@@ -1,5 +1,9 @@
 import type { TrackScore } from "../../core/score.ts";
-import { AVAILABLE_EFFECTS, AVAILABLE_INSTRUMENTS } from "../audio/wav.ts";
+import {
+  AVAILABLE_EFFECTS,
+  AVAILABLE_FX_PRESETS,
+  AVAILABLE_INSTRUMENTS,
+} from "../audio/wav.ts";
 import type { ProjectOutline } from "./workspace.ts";
 
 export const MAX_BRIEF_BYTES = 12 * 1024;
@@ -69,6 +73,17 @@ export function compositionBrief(options: {
         ? { filterAutomation: track.filterAutomation!.length }
         : {}),
       ...(track.reverb ? { reverb: track.reverb } : {}),
+      ...(track.fx ? { fx: track.fx } : {}),
+      ...(track.fxAutomation
+        ? {
+            fxAutomation: Object.fromEntries(
+              Object.entries(track.fxAutomation).map(([lane, points]) => [
+                lane,
+                points?.length ?? 0,
+              ]),
+            ),
+          }
+        : {}),
       ...((track.resonanceAutomation?.length ?? 0) > 0
         ? { resonanceAutomation: track.resonanceAutomation!.length }
         : {}),
@@ -78,6 +93,10 @@ export function compositionBrief(options: {
       ...((track.delayMixAutomation?.length ?? 0) > 0
         ? { delayMixAutomation: track.delayMixAutomation!.length }
         : {}),
+      ...(track.wavetable ? { wavetable: track.wavetable } : {}),
+      ...((track.wtAutomation?.length ?? 0) > 0
+        ? { wtAutomation: track.wtAutomation!.length }
+        : {}),
     };
   });
   const focusedNotes = score.notes
@@ -104,6 +123,7 @@ export function compositionBrief(options: {
     noteLimit: number,
     trackLimit: number,
     projectLevel: number,
+    presets: boolean,
   ) => {
     const visible = focusedNotes.slice(0, noteLimit);
     return JSON.stringify({
@@ -128,6 +148,7 @@ export function compositionBrief(options: {
       recentOperations: recent,
       instruments: AVAILABLE_INSTRUMENTS,
       effects: AVAILABLE_EFFECTS,
+      ...(presets ? { fxPresets: AVAILABLE_FX_PRESETS } : {}),
       ...(project && projectLevel > 0 && project.tree.length > 0
         ? {
             project: {
@@ -144,13 +165,17 @@ export function compositionBrief(options: {
   let noteLimit = Math.min(MAX_FOCUSED_NOTES, focusedNotes.length);
   let trackLimit = tracks.length;
   let projectLevel = 2;
-  let brief = build(noteLimit, trackLimit, projectLevel);
+  // Preset names are a convenience (`set_fx` lists them on a miss), so
+  // the brief carries them only when the score already uses effects.
+  let presets = score.tracks.some((track) => track.fx !== undefined);
+  let brief = build(noteLimit, trackLimit, projectLevel, presets);
   while (encoder.encode(brief).byteLength > maxBytes) {
-    if (noteLimit > 0) noteLimit = Math.floor(noteLimit / 2);
+    if (presets) presets = false;
+    else if (noteLimit > 0) noteLimit = Math.floor(noteLimit / 2);
     else if (projectLevel > 0) projectLevel -= 1;
     else if (trackLimit > 1) trackLimit = Math.floor(trackLimit / 2);
     else break;
-    brief = build(noteLimit, trackLimit, projectLevel);
+    brief = build(noteLimit, trackLimit, projectLevel, presets);
   }
   return brief;
 }

package/src/agent/chord-tools.ts

@@ -0,0 +1,357 @@
+/**
+ * Agent tools for chords: `suggest_progression` (read-only) and
+ * `write_chords` (score). Both run core/chords.ts, so the agent gets the
+ * same key-mode harmony, voice leading and performance play mode uses.
+ */
+
+import {
+  BASS_MODES,
+  CHORD_PATTERNS,
+  findChordPattern,
+  type BassMode,
+  generateProgression,
+  keyName,
+  parseKey,
+  PERFORM_MODES,
+  PROGRESSION_PRESETS,
+  PROGRESSION_STYLES,
+  renderProgression,
+  resolveChord,
+  SPREADS,
+  type Chord,
+  type Key,
+  type PerformMode,
+  type Spread,
+} from "../../core/chords.ts";
+import { midiToPitch } from "../../core/pitch.ts";
+import { SCORE_LIMITS, type ScoreOperation } from "../../core/score.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+
+/** Most notes one write_chords call may add (arpeggios multiply fast). */
+export const MAX_CHORD_NOTES = 512;
+const MAX_CHORDS = 32;
+
+class ChordToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+const STYLE_NAMES = [
+  ...PROGRESSION_STYLES,
+  ...PROGRESSION_PRESETS.map((preset) => preset.name),
+];
+
+const str = { type: "string" } as const;
+const int = { type: "integer" } as const;
+const num = { type: "number" } as const;
+const bool = { type: "boolean" } as const;
+const keySchema = {
+  type: "string",
+  description: '"C major", "a dorian"; default song key',
+} as const;
+const chordsSchema = {
+  type: "array",
+  items: str,
+  description: '"ii7", "bVII", "V/V" or "Cm7", "F/A"',
+} as const;
+const voicingSchema = {
+  inversion: { ...int, description: "-12..12" },
+  spread: { type: "string", enum: [...SPREADS] },
+} as const;
+const progressionSchema = {
+  key: keySchema,
+  chords: {
+    ...chordsSchema,
+    description: `${chordsSchema.description}; omit to generate`,
+  },
+  length: int,
+  style: str,
+  seed: int,
+  sevenths: bool,
+  ...voicingSchema,
+} as const;
+
+type Progression = Readonly<{ key: Key; chords: Chord[] }>;
+
+function progressionOf(
+  args: Record<string, unknown>,
+  context: ToolContext,
+): Progression {
+  const keyText =
+    args.key === undefined ? (context.score.key ?? "C major") : args.key;
+  const key = parseKey(typeof keyText === "string" ? keyText : undefined);
+  if (!key)
+    throw new ChordToolError(
+      `key must look like "C major", "a minor" or "F# dorian"`,
+    );
+  if (args.chords !== undefined) {
+    if (
+      !Array.isArray(args.chords) ||
+      args.chords.length === 0 ||
+      args.chords.length > MAX_CHORDS
+    )
+      throw new ChordToolError(`chords must list 1..${MAX_CHORDS} chords`);
+    const chords = args.chords.map((value, index) => {
+      const chord =
+        typeof value === "string" ? resolveChord(key, value) : undefined;
+      if (!chord)
+        throw new ChordToolError(
+          `chords[${index}]: not a roman numeral or chord symbol`,
+        );
+      return chord;
+    });
+    return { key, chords };
+  }
+  const length = integer(args, "length", 1, MAX_CHORDS) ?? 4;
+  const style = args.style;
+  if (
+    style !== undefined &&
+    (typeof style !== "string" || !STYLE_NAMES.includes(style))
+  )
+    throw new ChordToolError(`style must be one of ${STYLE_NAMES.join(", ")}`);
+  const sevenths = optionalBoolean(args, "sevenths");
+  return {
+    key,
+    chords: generateProgression({
+      key,
+      length,
+      ...(style !== undefined ? { style } : {}),
+      seed: integer(args, "seed", 0, 2 ** 31) ?? 1,
+      ...(sevenths !== undefined ? { sevenths } : {}),
+    }),
+  };
+}
+
+function voicingOf(args: Record<string, unknown>): {
+  inversion?: number;
+  spread?: Spread;
+} {
+  const inversion = integer(args, "inversion", -12, 12);
+  const spread = args.spread;
+  if (spread !== undefined && !(SPREADS as readonly unknown[]).includes(spread))
+    throw new ChordToolError(`spread must be one of ${SPREADS.join(", ")}`);
+  return {
+    ...(inversion !== undefined ? { inversion } : {}),
+    ...(spread !== undefined ? { spread: spread as Spread } : {}),
+  };
+}
+
+export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "suggest_progression",
+    description: `Read-only: voice-led diatonic chords (name, numeral, voicing, bass). style ${PROGRESSION_STYLES.join("|")} walks a seeded harmony graph; or a preset ${PROGRESSION_PRESETS.map((p) => p.name).join("|")}. length ≤${MAX_CHORDS}.`,
+    parameters: {
+      type: "object",
+      properties: progressionSchema,
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const { key, chords } = progressionOf(args, context);
+      const rendered = renderProgression({
+        key,
+        chords,
+        ...voicingOf(args),
+        bass: true,
+      });
+      const result = {
+        key: keyName(key),
+        chords: rendered.voiced.map((chord) => ({
+          name: chord.name,
+          roman: chord.roman,
+          voicing: chord.pitches.map((pitch) => midiToPitch(pitch)),
+          ...(chord.bass !== undefined
+            ? { bass: midiToPitch(chord.bass) }
+            : {}),
+        })),
+      };
+      const names = rendered.voiced.map((chord) => chord.name).join(" ");
+      return {
+        kind: "action",
+        summary: `${keyName(key)}: ${names}`.slice(0, 160),
+        run: async () => ({
+          content: JSON.stringify(result),
+          summary: `${keyName(key)}: ${names}`.slice(0, 160),
+        }),
+      };
+    },
+  },
+  {
+    name: "write_chords",
+    description: `Write voice-led chords to a track (one bar each by default), with optional bass here or on bassTrackId. perform pattern uses pattern ${CHORD_PATTERNS.map((p) => p.name).join("|")}. bassMode ${BASS_MODES.join("|")} (solo: bass only). ≤${MAX_CHORD_NOTES} notes.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: str,
+        key: keySchema,
+        chords: chordsSchema,
+        ...voicingSchema,
+        start: num,
+        beatsPerChord: num,
+        perform: { type: "string", enum: [...PERFORM_MODES] },
+        rate: { ...num, description: "arp step, beats" },
+        octaves: int,
+        strum: num,
+        velocity: num,
+        pattern: { type: "string", enum: CHORD_PATTERNS.map((p) => p.name) },
+        bass: bool,
+        bassMode: { type: "string", enum: [...BASS_MODES] },
+        bassTrackId: str,
+      },
+      required: ["chords"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = trackOf(args.trackId, context, "trackId");
+      if (args.chords === undefined)
+        throw new ChordToolError(
+          "write_chords needs chords (try suggest_progression)",
+        );
+      const bassTrackId =
+        args.bassTrackId === undefined
+          ? undefined
+          : trackOf(args.bassTrackId, context, "bassTrackId");
+      const { key, chords } = progressionOf(args, context);
+      const mode = args.perform;
+      if (
+        mode !== undefined &&
+        !(PERFORM_MODES as readonly unknown[]).includes(mode)
+      )
+        throw new ChordToolError(
+          `perform must be one of ${PERFORM_MODES.join(", ")}`,
+        );
+      const velocity = finite(args, "velocity", 0, 1);
+      const rate = finite(args, "rate", 0.0625, 4);
+      const strum = finite(args, "strum", 0, 1);
+      const octaves = integer(args, "octaves", 1, 4);
+      const pattern = args.pattern;
+      if (
+        pattern !== undefined &&
+        (typeof pattern !== "string" || !findChordPattern(pattern))
+      )
+        throw new ChordToolError(
+          `pattern must be one of ${CHORD_PATTERNS.map((p) => p.name).join(", ")}`,
+        );
+      const bassMode = args.bassMode;
+      if (
+        bassMode !== undefined &&
+        !(BASS_MODES as readonly unknown[]).includes(bassMode)
+      )
+        throw new ChordToolError(
+          `bassMode must be one of ${BASS_MODES.join(", ")}`,
+        );
+      const rendered = renderProgression({
+        key,
+        chords,
+        start: finite(args, "start", 0, Infinity) ?? 0,
+        beatsPerChord:
+          finite(args, "beatsPerChord", 1e-3, 64) ?? context.score.beatsPerBar,
+        ...voicingOf(args),
+        bass: args.bass === true || bassTrackId !== undefined,
+        ...(bassMode !== undefined ? { bassMode: bassMode as BassMode } : {}),
+        perform: {
+          mode: (mode as PerformMode | undefined) ?? "block",
+          ...(rate !== undefined ? { rate } : {}),
+          ...(strum !== undefined ? { strum } : {}),
+          ...(octaves !== undefined ? { octaves } : {}),
+          ...(velocity !== undefined ? { velocity } : {}),
+          seed: integer(args, "seed", 0, 2 ** 31) ?? 0,
+          ...(typeof pattern === "string" ? { pattern } : {}),
+        },
+      });
+      const total = rendered.notes.length + rendered.bass.length;
+      if (total > MAX_CHORD_NOTES)
+        throw new ChordToolError(
+          `${total} notes exceed ${MAX_CHORD_NOTES}; use fewer chords, a slower rate or fewer octaves`,
+        );
+      const tpb = context.score.ticksPerBeat;
+      const operations: ScoreOperation[] = [];
+      const add = (
+        notes: readonly {
+          pitch: number;
+          start: number;
+          length: number;
+          velocity: number;
+        }[],
+        target: string,
+      ) => {
+        for (const note of notes)
+          operations.push({
+            type: "addNote",
+            note: {
+              id: context.newNoteId(target, operations.length),
+              trackId: target,
+              startTick: Math.round(note.start * tpb),
+              durationTicks: Math.max(1, Math.round(note.length * tpb)),
+              pitch: note.pitch,
+              velocity: note.velocity,
+            },
+          });
+      };
+      add(rendered.notes, trackId);
+      add(rendered.bass, bassTrackId ?? trackId);
+      const names = rendered.voiced.map((chord) => chord.name).join(" ");
+      return {
+        kind: "score",
+        operations,
+        trackId,
+        summary: `${trackId} chords ${names}`.slice(0, 160),
+      };
+    },
+  },
+]);
+
+function trackOf(value: unknown, context: ToolContext, label: string): string {
+  const trackId = value ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
+    throw new ChordToolError(`${label} must be a short string`);
+  if (!context.score.tracks.some((track) => track.id === trackId))
+    throw new ChordToolError(
+      `unknown track ${trackId}; create it with create_track first`,
+    );
+  return trackId;
+}
+
+function finite(
+  args: Record<string, unknown>,
+  name: string,
+  min: number,
+  max: number,
+): number | undefined {
+  const value = args[name];
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value < min ||
+    value > max
+  )
+    throw new ChordToolError(
+      `${name} must be a number in ${min}..${max === Infinity ? "∞" : max}`,
+    );
+  return value;
+}
+
+function integer(
+  args: Record<string, unknown>,
+  name: string,
+  min: number,
+  max: number,
+): number | undefined {
+  const value = finite(args, name, min, max);
+  if (value !== undefined && !Number.isInteger(value))
+    throw new ChordToolError(`${name} must be an integer`);
+  return value;
+}
+
+function optionalBoolean(
+  args: Record<string, unknown>,
+  name: string,
+): boolean | undefined {
+  const value = args[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean")
+    throw new ChordToolError(`${name} must be true or false`);
+  return value;
+}

package/src/agent/drum-tools.ts

@@ -0,0 +1,135 @@
+/**
+ * Agent tools for the drum pattern library and the synthesized kits:
+ * `list_drum_patterns`, `apply_drum_pattern`, `set_drum_kit`. Patterns land
+ * as rhythm rows (`set_rhythm` edits them afterwards), so a groove stays a
+ * few parameters per voice instead of dozens of notes.
+ */
+import { diffScores } from "../../core/diff.ts";
+import { SYNTH_KITS } from "../../core/kits.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import {
+  applyDrumPattern,
+  applySynthKit,
+  DRUM_PATTERNS,
+  patternLine,
+} from "../commands/drums.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+import { ToolArgumentError } from "./tools.ts";
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function trackIdOf(args: Record<string, unknown>, context: ToolContext) {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || !ID_PATTERN.test(trackId))
+    throw new ToolArgumentError(
+      "trackId must be 1-64 letters, digits, dot, dash, or underscore",
+    );
+  return trackId;
+}
+
+const trackId = {
+  type: "string",
+  maxLength: SCORE_LIMITS.maxIdLength,
+  description:
+    "Drum track id (created when missing). Defaults to the focused track.",
+} as const;
+
+export const DRUM_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "list_drum_patterns",
+    description:
+      "List the built-in drum patterns (name · tempo range · genre tags · voices). Filter by a word such as house, trap or 2-step.",
+    parameters: {
+      type: "object",
+      properties: { filter: { type: "string", maxLength: 40 } },
+      additionalProperties: false,
+    },
+    plan(args) {
+      const needle =
+        typeof args.filter === "string" ? args.filter.trim().toLowerCase() : "";
+      const lines = DRUM_PATTERNS.filter(
+        (entry) =>
+          !needle ||
+          entry.name.includes(needle) ||
+          entry.tags.some((tag) => tag.includes(needle)),
+      ).map(patternLine);
+      return {
+        kind: "action",
+        summary: needle ? `patterns ${needle}` : "list patterns",
+        run: async () => ({
+          content: JSON.stringify({
+            ok: true,
+            patterns: lines,
+            hint: "apply_drum_pattern puts one on a drum track; set_rhythm then edits its rows",
+          }),
+          summary: `${lines.length} patterns`,
+        }),
+      };
+    },
+  },
+  {
+    name: "apply_drum_pattern",
+    description:
+      "Replace a drum track's notes with a library pattern as Euclidean/grid rhythm rows (one per voice). Moves the tempo into the pattern's range unless tempo is keep.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", maxLength: 40 },
+        trackId,
+        tempo: { type: "string", enum: ["auto", "keep", "set"] },
+      },
+      required: ["name"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      if (typeof args.name !== "string" || !args.name.trim())
+        throw new ToolArgumentError("name must be a pattern name");
+      const id = trackIdOf(args, context);
+      const tempo =
+        args.tempo === "keep" || args.tempo === "set" ? args.tempo : "auto";
+      const result = applyDrumPattern(
+        context.score,
+        id,
+        args.name.trim().toLowerCase(),
+        tempo,
+      );
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      return {
+        kind: "score",
+        operations: diffScores(context.score, result.next),
+        trackId: id,
+        summary: result.message,
+      };
+    },
+  },
+  {
+    name: "set_drum_kit",
+    description: `Choose the synthesized drum kit of a drum track: ${SYNTH_KITS.map((kit) => kit.name).join(", ")}, or default. Offline and instant; sample kits (909, 808, linn, …) go through use_sound.`,
+    parameters: {
+      type: "object",
+      properties: {
+        kit: {
+          type: "string",
+          enum: ["default", ...SYNTH_KITS.map((kit) => kit.name)],
+        },
+        trackId,
+      },
+      required: ["kit"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      if (typeof args.kit !== "string")
+        throw new ToolArgumentError("kit must be a synth kit name");
+      const id = trackIdOf(args, context);
+      const result = applySynthKit(context.score, id, args.kit);
+      if (!result.ok) throw new ToolArgumentError(result.message);
+      return {
+        kind: "score",
+        operations: result.next ? diffScores(context.score, result.next) : [],
+        trackId: id,
+        summary: result.message,
+      };
+    },
+  },
+]);