@hraness/dawg 0.6.1 → 0.8.0

package/src/agent/style-tools.ts

@@ -0,0 +1,217 @@
+/**
+ * Agent tools for the style engine (core/styles): `list_styles` and
+ * `style_info` read the taxonomy and cards; `apply_style` generates a song
+ * from a style (optionally blended with a second one) and replaces the
+ * score with it in one undo step, the same path as the `style` command.
+ */
+
+import { DiffError, diffScores } from "../../core/diff.ts";
+import { STYLE_TREE, searchStyles } from "../../core/styles/index.ts";
+import {
+  STYLE_LIMITS,
+  StyleError,
+  styleScore,
+} from "../../core/styles/generate.ts";
+import { STYLE_FAMILIES } from "../../core/styles/taxonomy.ts";
+import { resolveStyle } from "../../core/styles/index.ts";
+import {
+  describeStyle,
+  findStyle,
+  generateFromCommand,
+  generatedSummary,
+} from "../commands/style.ts";
+import type { AgentTool } from "./tools.ts";
+
+class StyleToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+const MAX_LIST = 60;
+
+function nodeJSON(id: string) {
+  const node = STYLE_TREE.get(id)!;
+  return {
+    id,
+    title: node.title,
+    ...(node.leaf ? {} : { children: node.children.length }),
+  };
+}
+
+function knownStyle(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 120)
+    throw new StyleToolError(`${name} must be a style id or name`);
+  const id = findStyle(value);
+  if (!id) {
+    const near = searchStyles(value, 5).map((match) => match.id);
+    throw new StyleToolError(
+      `no style "${value}"${near.length ? `; did you mean ${near.join(", ")}` : "; call list_styles with a query"}`,
+    );
+  }
+  return id;
+}
+
+function integer(value: unknown, name: string, min: number, max: number) {
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < min ||
+    value > max
+  )
+    throw new StyleToolError(`${name} must be an integer ${min}..${max}`);
+  return value;
+}
+
+export const STYLE_TOOLS = Object.freeze([
+  {
+    name: "list_styles",
+    description:
+      "Browse the style taxonomy (read-only). query: ranked search over ids, names, aliases and regions. parent: the children of one style id. Neither: the families and their root styles. Returns ids to pass to style_info and apply_style.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", maxLength: 120 },
+        parent: { type: "string", maxLength: 120 },
+      },
+      additionalProperties: false,
+    },
+    plan(args) {
+      for (const key of Object.keys(args))
+        if (key !== "query" && key !== "parent")
+          throw new StyleToolError(`unknown argument ${key}`);
+      let result: unknown;
+      let summary: string;
+      if (args.query !== undefined) {
+        if (typeof args.query !== "string" || !args.query.trim())
+          throw new StyleToolError("query must be a non-empty string");
+        const matches = searchStyles(args.query, MAX_LIST).map((match) =>
+          nodeJSON(match.id),
+        );
+        result = { query: args.query, matches };
+        summary = `styles · ${matches.length} for "${args.query.slice(0, 40)}"`;
+      } else if (args.parent !== undefined) {
+        const id = knownStyle(args.parent, "parent");
+        const node = STYLE_TREE.get(id)!;
+        result = {
+          parent: id,
+          children: node.children.slice(0, MAX_LIST * 2).map(nodeJSON),
+        };
+        summary = `styles · ${node.children.length} under ${id}`;
+      } else {
+        result = {
+          families: STYLE_FAMILIES.map((family) => ({
+            family: family.key,
+            title: family.title,
+            roots: family.roots.map(nodeJSON),
+          })),
+        };
+        summary = "styles · families";
+      }
+      const content = JSON.stringify(result);
+      return {
+        kind: "action",
+        summary,
+        async run() {
+          return { content, summary };
+        },
+      };
+    },
+  },
+  {
+    name: "style_info",
+    description:
+      "Describe one style (read-only): taxonomy path, meter, tempo range, groove and swing, tuning and scales, harmony model, texture roles, and children.",
+    parameters: {
+      type: "object",
+      properties: { id: { type: "string", maxLength: 120 } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    plan(args) {
+      const id = knownStyle(args.id, "id");
+      const node = STYLE_TREE.get(id)!;
+      const content = JSON.stringify({
+        id,
+        lines: describeStyle(resolveStyle(id)),
+        children: node.children,
+      });
+      const summary = `style ${id}`;
+      return {
+        kind: "action",
+        summary,
+        async run() {
+          return { content, summary };
+        },
+      };
+    },
+  },
+  {
+    name: "apply_style",
+    description: `Replace the whole song with one generated from a style: drums, bass, harmony, melody and form from the style's patterns (one undo step). bars ${STYLE_LIMITS.minBars}..${STYLE_LIMITS.maxBars} (default ${STYLE_LIMITS.defaultBars}); seed picks a variation (same seed, same song). blend + weight (0 is id, 1 is blend) mixes two styles.`,
+    parameters: {
+      type: "object",
+      properties: {
+        id: { type: "string", maxLength: 120 },
+        bars: {
+          type: "integer",
+          minimum: STYLE_LIMITS.minBars,
+          maximum: STYLE_LIMITS.maxBars,
+        },
+        seed: { type: "integer", minimum: 0, maximum: STYLE_LIMITS.maxSeed },
+        blend: { type: "string", maxLength: 120 },
+        weight: { type: "number", minimum: 0, maximum: 1 },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      for (const key of Object.keys(args))
+        if (!["id", "bars", "seed", "blend", "weight"].includes(key))
+          throw new StyleToolError(`unknown argument ${key}`);
+      const id = knownStyle(args.id, "id");
+      const bars = integer(
+        args.bars,
+        "bars",
+        STYLE_LIMITS.minBars,
+        STYLE_LIMITS.maxBars,
+      );
+      const seed = integer(args.seed, "seed", 0, STYLE_LIMITS.maxSeed);
+      if (args.weight !== undefined && args.blend === undefined)
+        throw new StyleToolError("weight needs blend");
+      let blend: { id: string; weight: number } | undefined;
+      if (args.blend !== undefined) {
+        const weight = args.weight ?? 0.5;
+        if (
+          typeof weight !== "number" ||
+          !Number.isFinite(weight) ||
+          weight < 0 ||
+          weight > 1
+        )
+          throw new StyleToolError("weight must be 0..1");
+        blend = { id: knownStyle(args.blend, "blend"), weight };
+      }
+      try {
+        const generated = generateFromCommand({
+          type: "style-apply",
+          id,
+          ...(bars !== undefined ? { bars } : {}),
+          ...(seed !== undefined ? { seed } : {}),
+          ...(blend ? { blend } : {}),
+        });
+        const next = styleScore(generated);
+        return {
+          kind: "score",
+          operations: diffScores(context.score, next),
+          summary: generatedSummary(generated).slice(0, 160),
+        };
+      } catch (error) {
+        if (error instanceof StyleError || error instanceof DiffError)
+          throw new StyleToolError(error.message);
+        throw error;
+      }
+    },
+  },
+] satisfies AgentTool[]);

package/src/agent/tool-error.ts

@@ -0,0 +1,12 @@
+/**
+ * The tool-argument error, in its own module so tool files that `tools.ts`
+ * spreads (voice-tools.ts) can throw it without an import cycle.
+ */
+
+/** A model-supplied argument that the tool refused; never mutates the score. */
+export class ToolArgumentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}

package/src/agent/tools.ts

@@ -1,4 +1,8 @@
+import { portableSchema } from "./portable-schema.ts";
+import { midiToPitch } from "../../core/pitch.ts";
+import { isGuideInstrument, vocalChainPatch } from "../../core/clips.ts";
 import { INSTRUMENT_WORDS } from "../../core/instruments.ts";
+import type { TrackVocoder } from "../../core/vocoder.ts";
 import {
   DEFAULT_STRING_PRESET,
   STRING_INSTRUMENT,
@@ -83,6 +87,8 @@ import {
   applyFxCommand,
   effectPatch,
   effectValues,
+  FORMANT_VOWEL_HINT,
+  formantGotVowel,
   parseEffectName,
   parseParamName,
   parseFxCommand,
@@ -102,12 +108,16 @@ import { RHYTHM_TOOLS } from "./rhythm-tools.ts";
 import { CHORD_TOOLS } from "./chord-tools.ts";
 import { EXPRESSION_TOOLS } from "./expression-tools.ts";
 import { TUNING_TOOLS } from "./tuning-tools.ts";
+import { CALIBRATION_TOOLS } from "./calibration-tools.ts";
 import { MASTER_TOOLS } from "./master-tools.ts";
+import { STYLE_TOOLS } from "./style-tools.ts";
 import { DRUM_TOOLS } from "./drum-tools.ts";
 import { TIME_TOOLS } from "./time-tools.ts";
 import { SECTION_TOOLS } from "./section-tools.ts";
+import { RANGE_TOOLS } from "./range-tools.ts";
 import { GRANULAR_TOOLS } from "./granular-tools.ts";
 import { RESAMPLE_TOOLS } from "./resample-tool.ts";
+import { VOICE_TOOLS } from "./voice-tools.ts";
 import type { MediaResult, MediaRunContext } from "../media/types.ts";
 import { instrumentPatch, pitchToMidi } from "./ops.ts";
 import { TUNING_LIMITS } from "../../core/tuning.ts";
@@ -255,17 +265,17 @@ export type ToolContext = Readonly<{
 export type AgentTool = Readonly<{
   name: string;
   description: string;
+  /**
+   * Callable but not advertised: a duplicate kept so older transcripts and
+   * models still work. `chatTools` and the xcb catalog leave it out.
+   */
+  hidden?: boolean;
   parameters: Record<string, unknown>;
   plan: (args: Record<string, unknown>, context: ToolContext) => ToolPlan;
 }>;
 
-/** A model-supplied argument that the tool refused; never mutates the score. */
-export class ToolArgumentError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ToolArgumentError";
-  }
-}
+import { ToolArgumentError } from "./tool-error.ts";
+export { ToolArgumentError };
 
 const MAX_NOTES_PER_CALL = 128;
 const MAX_EXPLAIN_CHARS = 2_000;
@@ -404,7 +414,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "update_notes",
     description:
-      "Move, resize, transpose, re-velocity or detune existing notes by id. Times are in beats.",
+      "Move, resize, transpose, re-velocity or detune existing notes by id. Times are in beats. To transpose, prefer transpose (semitones relative to the note's current pitch, e.g. 2 up a whole step, -12 down an octave) over an absolute pitch.",
     parameters: {
       type: "object",
       properties: {
@@ -424,6 +434,13 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
                   { type: "string", maxLength: 4 },
                 ],
               },
+              transpose: {
+                type: "integer",
+                minimum: -127,
+                maximum: 127,
+                description:
+                  "Semitones relative to the current pitch (not with pitch)",
+              },
               velocity: { type: "number", minimum: 0, maximum: 1 },
               cents: {
                 type: "number",
@@ -442,6 +459,9 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
     },
     plan(args, context) {
       const tpb = context.score.ticksPerBeat;
+      // Pitch changes as before→after, so the model sees what it did and
+      // does not transpose again from the refreshed brief.
+      const moves: string[] = [];
       const operations = list(args, "updates", 1, MAX_NOTES_PER_CALL).map(
         (value, index): ScoreOperation => {
           const update = record(value, `updates[${index}]`);
@@ -459,8 +479,41 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
           });
           if (duration !== undefined)
             patch.durationTicks = Math.max(1, Math.round(duration * tpb));
+          const before = context.score.notes.find((n) => n.id === noteId);
           if (update.pitch !== undefined)
             patch.pitch = pitch(update.pitch, `updates[${index}].pitch`);
+          // Small models fill every field: transpose 0 beside a pitch means
+          // no shift, and a pitch that equals the transposed note agrees.
+          if (
+            patch.pitch !== undefined &&
+            update.transpose !== undefined &&
+            update.transpose !== 0 &&
+            patch.pitch !== (before?.pitch ?? 0) + Number(update.transpose)
+          )
+            throw new ToolArgumentError(
+              `updates[${index}] sets both pitch and transpose; use one`,
+            );
+          if (update.transpose !== undefined && patch.pitch === undefined) {
+            const shift = update.transpose;
+            if (typeof shift !== "number" || !Number.isInteger(shift))
+              throw new ToolArgumentError(
+                `updates[${index}].transpose must be whole semitones`,
+              );
+            const moved = (before?.pitch ?? 0) + shift;
+            if (moved < 0 || moved > 127)
+              throw new ToolArgumentError(
+                `updates[${index}].transpose moves ${noteId} to MIDI ${moved}, outside 0..127`,
+              );
+            patch.pitch = moved;
+          }
+          if (
+            patch.pitch !== undefined &&
+            before &&
+            patch.pitch !== before.pitch
+          )
+            moves.push(
+              `${noteId} ${midiToPitch(before.pitch)}→${midiToPitch(patch.pitch)}`,
+            );
           const velocity = optionalNumber(update, "velocity", {
             min: 0,
             max: 1,
@@ -479,7 +532,11 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       return {
         kind: "score",
         operations,
-        summary: `~${operations.length} note${operations.length === 1 ? "" : "s"}`,
+        summary: `~${operations.length} note${operations.length === 1 ? "" : "s"}${
+          moves.length === 0
+            ? ""
+            : ` · pitch ${moves.slice(0, 8).join(", ")}${moves.length > 8 ? ` +${moves.length - 8} more` : ""}`
+        }`,
       };
     },
   },
@@ -520,7 +577,18 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       return {
         kind: "score",
         operations: [
-          { type: "updateTrack", trackId, patch: { ...patch, ...rig } },
+          {
+            type: "updateTrack",
+            trackId,
+            patch: {
+              // `vocal` (0.7): the vocal chain fills unset effects.
+              ...(isGuideInstrument(patch.instrument)
+                ? vocalChainPatch(track)
+                : {}),
+              ...patch,
+              ...rig,
+            },
+          },
         ],
         trackId,
         summary:
@@ -899,7 +967,7 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "set_keys",
-    description: `Shape a modelled piano, electric keys (epiano wurli clav) or organ: preset (instrument, keys and its effects), params ${KEYS_SIMPLE.join(" ")}… (pianos: sym 0.5 adds sympathetic bloom under the sustain pedal, good for Chopin and Debussy; epiano: bark bell tone vibe; wurli: trem; clav: pickup mute; null unsets; DAWG.md lists all), or reset. Stored "piano" stays legacy; set_instrument piano writes grand. Organs (not "organ", a legacy synth): presets tonewheel combo pipe… (aliases hammond b3 farfisa church); drawbars "888800008", registers "08880", stops (plenum, flute8…), rotary; params perc percdecay percvol click scanner drive (tonewheel), voice vib vibmod drive (combo), chiff wind trem (pipe). A row the family does not read is refused.`,
+    description: `Shape a modeled piano, electric keys (epiano wurli clav) or organ: preset (instrument, keys and its effects), params ${KEYS_SIMPLE.join(" ")}… (pianos: sym 0.5 adds sympathetic bloom under the sustain pedal, good for Chopin and Debussy; epiano: bark bell tone vibe; wurli: trem; clav: pickup mute; null unsets; DAWG.md lists all), or reset. Stored "piano" stays legacy; set_instrument piano writes grand. Organs (not "organ", a legacy synth): presets tonewheel combo pipe… (aliases hammond b3 farfisa church); drawbars "888800008", registers "08880", stops (plenum, flute8…), rotary; params perc percdecay percvol click scanner drive (tonewheel), voice vib vibmod drive (combo), chiff wind trem (pipe). A row the family does not read is refused.`,
     parameters: {
       type: "object",
       properties: {
@@ -1278,7 +1346,8 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     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.`,
+    hidden: true,
+    description: `Shorthand for set_fx (use set_fx): low-pass filter, delay (beats) and reverb (mix 0.15..0.35 is a room); null removes one.`,
     parameters: {
       type: "object",
       properties: {
@@ -1438,7 +1507,8 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   },
   {
     name: "add_drums",
-    description: `Add one-off drum hits to a kit track (create one with create_track instrument "kit"); prefer set_rhythm for repeating beats. Voices: ${DRUM_VOICES.map((info) => info.voice).join(", ")}. Give explicit hits, and/or patterns that repeat a voice every N beats across the loop.`,
+    hidden: true,
+    description: `Use set_rhythm. Add one-off drum hits to a kit track (create one with create_track instrument "kit"); prefer set_rhythm for repeating beats. Voices: ${DRUM_VOICES.map((info) => info.voice).join(", ")}. Give explicit hits, and/or patterns that repeat a voice every N beats across the loop.`,
     parameters: {
       type: "object",
       properties: {
@@ -1490,14 +1560,14 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
       const track = context.score.tracks.find((t) => t.id === trackId)!;
       if (!isDrumInstrument(track.instrument))
         throw new ToolArgumentError(
-          `track ${trackId} is ${track.instrument}, not a drum kit; set_instrument kit or create a kit track`,
+          `track ${trackId} is ${track.instrument}, not a kit; set_instrument kit or create a kit track`,
         );
       const tpb = context.score.ticksPerBeat;
       const loopBeats = loopTicksOf(context.score) / tpb;
       const voiceOf = (value: unknown, label: string) => {
         const voice =
           typeof value === "string" ? parseDrumVoice(value) : undefined;
-        if (!voice) throw new ToolArgumentError(`${label}: unknown drum voice`);
+        if (!voice) throw new ToolArgumentError(`${label}: unknown drum`);
         return voice;
       };
       const hits: { voice: DrumVoice; beat: number; velocity: number }[] = [];
@@ -1962,14 +2032,19 @@ export const AGENT_TOOLS: readonly AgentTool[] = Object.freeze([
   ...CHORD_TOOLS,
   ...EXPRESSION_TOOLS,
   ...TUNING_TOOLS,
+  ...CALIBRATION_TOOLS,
   ...DRUM_TOOLS,
   ...TIME_TOOLS,
   ...SECTION_TOOLS,
+  ...RANGE_TOOLS,
   ...MEDIA_TOOLS,
   ...PACK_TOOLS,
   ...MASTER_TOOLS,
+  ...STYLE_TOOLS,
   ...GRANULAR_TOOLS,
   ...RESAMPLE_TOOLS,
+  // 0.7 Voice: one array per lane in voice-tools.ts.
+  ...VOICE_TOOLS,
   // Looks tools up at call time, so it can plan any of the above.
   previewSoundTool((name) => findAgentTool(name)),
 ] satisfies AgentTool[]);
@@ -2066,14 +2141,16 @@ export function findAgentTool(
 export function chatTools(
   tools: readonly AgentTool[] = AGENT_TOOLS,
 ): ChatTool[] {
-  return tools.map((tool) => ({
-    type: "function",
-    function: {
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.parameters,
-    },
-  }));
+  return tools
+    .filter((tool) => !tool.hidden)
+    .map((tool) => ({
+      type: "function",
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: portableSchema(tool.parameters),
+      },
+    }));
 }
 
 function fxToolCommand(
@@ -2099,6 +2176,14 @@ function fxToolCommand(
     throw new ToolArgumentError("set_fx needs on, preset, or params");
   }
   const params = record(args.params, "params");
+  if (
+    effect === "formant" &&
+    formantGotVowel([
+      ...Object.keys(params),
+      ...Object.values(params),
+    ] as string[])
+  )
+    throw new ToolArgumentError(FORMANT_VOWEL_HINT);
   const values: Record<string, number | string | boolean> = {};
   for (const [name, value] of Object.entries(params)) {
     const param = parseParamName(effect, name);
@@ -2296,6 +2381,7 @@ function instrumentName(value: unknown): {
   string?: { preset: string };
   modal?: TrackModal;
   wind?: TrackWind;
+  vocoder?: TrackVocoder;
 } {
   const word = typeof value === "string" ? value.trim() : undefined;
   if (word === STRING_INSTRUMENT)
@@ -2309,6 +2395,7 @@ function instrumentName(value: unknown): {
     (!patch.string &&
       !patch.modal &&
       !patch.wind &&
+      !patch.vocoder &&
       !(AVAILABLE_INSTRUMENTS as readonly string[]).includes(patch.instrument))
   )
     throw new ToolArgumentError(

package/src/agent/usage.ts

@@ -232,7 +232,7 @@ export class SpendMeter {
 
 /**
  * The spend line: `$0.12 session · $0.48 today · opus-5.5 · gateway`;
- * `subscription · sonnet · claude`; `no model · dawg login`. Narrow widths
+ * `subscription · sonnet · claude`; `commands only`. Narrow widths
  * drop the today total, then the session total, then the provider.
  */
 export function spendLine(
@@ -245,7 +245,7 @@ export function spendLine(
   },
   width = 120,
 ): string {
-  if (options.kind === "offline") return "no model · dawg login";
+  if (options.kind === "offline") return "commands only";
   const tail = [options.model, options.provider].filter(Boolean) as string[];
   const money =
     options.kind === "subscription"