@hraness/dawg 0.0.0-stage → 0.3.0

package/src/agent/ops.ts

@@ -0,0 +1,157 @@
+import { pitchToMidi } from "../../core/pitch.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+
+export { pitchToMidi };
+
+export type AgentOperation =
+  | { type: "add-track"; trackId: string }
+  | {
+      type: "add-note";
+      pitch: number;
+      start: number;
+      duration: number;
+      velocity: number;
+    }
+  | { type: "remove-note"; noteId: string }
+  | {
+      type: "update-note";
+      noteId: string;
+      patch: {
+        start?: number;
+        duration?: number;
+        pitch?: number;
+        velocity?: number;
+      };
+    }
+  | { type: "set-tempo"; tempoBpm: number }
+  | { type: "set-bars"; bars: number }
+  | { type: "extend-bars"; bars: number }
+  | {
+      type: "track";
+      patch: {
+        instrument?: string;
+        muted?: boolean;
+        volume?: number;
+        pan?: number;
+        name?: string;
+      };
+    }
+  | {
+      type: "automation";
+      parameter: "volume" | "pan";
+      points: readonly { beat: number; value: number }[];
+    }
+  | { type: "clear-track" }
+  | { type: "transport"; action: "play" | "pause" | "toggle" };
+
+export function parsePrompt(prompt: string): AgentOperation | undefined {
+  const text = prompt.trim().toLowerCase();
+  if (/^(play|start)\b/.test(text))
+    return { type: "transport", action: "play" };
+  if (/^(pause|stop)\b/.test(text))
+    return { type: "transport", action: "pause" };
+  if (/^toggle\b/.test(text)) return { type: "transport", action: "toggle" };
+  const track = text.match(/^(?:add\s+)?track\s+([a-z0-9._-]{1,64})$/);
+  if (track) return { type: "add-track", trackId: track[1]! };
+  const bars = text.match(/^bars\s+(\d+)$/);
+  const extension = text.match(/^extend\s+(\d+)\s+bars?$/);
+  if (bars || extension) {
+    const count = Number((bars ?? extension)![1]);
+    if (Number.isInteger(count) && count >= 1 && count <= SCORE_LIMITS.maxBars)
+      return { type: bars ? "set-bars" : "extend-bars", bars: count };
+  }
+  const tempo = text.match(/^(?:tempo|bpm)\s+(\d+(?:\.\d+)?)\s*$/);
+  if (tempo) {
+    const tempoBpm = Number(tempo[1]);
+    if (Number.isFinite(tempoBpm)) return { type: "set-tempo", tempoBpm };
+  }
+  if (/^(?:clear|clear\s+track|remove\s+all)$/.test(text))
+    return { type: "clear-track" };
+  const instrument = text.match(
+    /^(?:instrument|sound|voice)\s+([a-z0-9._ -]{1,64})$/,
+  );
+  if (instrument)
+    return { type: "track", patch: { instrument: instrument[1]!.trim() } };
+  if (/^(?:mute|silence)\b/.test(text))
+    return { type: "track", patch: { muted: true } };
+  if (/^(?:unmute|unsilence)\b/.test(text))
+    return { type: "track", patch: { muted: false } };
+  const volume = text.match(/^(?:volume|vol)\s+(0(?:\.\d+)?|1(?:\.0+)?)$/);
+  if (volume) return { type: "track", patch: { volume: Number(volume[1]) } };
+  const clearAutomation = text.match(
+    /^(?:clear|reset)\s+(?:(volume|pan)\s+)?automation$/,
+  );
+  if (clearAutomation)
+    return {
+      type: "automation",
+      parameter:
+        (clearAutomation[1] as "volume" | "pan" | undefined) ?? "volume",
+      points: [],
+    };
+  const automation = text.match(
+    /^(?:automate|automation)\s+(volume|pan)\s+at\s+(\d+(?:\.\d+)?)\s+(-?(?:0(?:\.\d+)?|1(?:\.0+)?))$/,
+  );
+  if (automation) {
+    const parameter = automation[1] as "volume" | "pan";
+    const beat = Number(automation[2]);
+    const value = Number(automation[3]);
+    if (
+      Number.isFinite(beat) &&
+      Number.isFinite(value) &&
+      (parameter === "pan" ? value >= -1 : value >= 0)
+    )
+      return {
+        type: "automation",
+        parameter,
+        points: [{ beat, value }],
+      };
+  }
+  const pan = text.match(/^(?:pan)\s+(-?1(?:\.0+)?|-?0(?:\.\d+)?)$/);
+  if (pan) return { type: "track", patch: { pan: Number(pan[1]) } };
+  const remove = text.match(
+    /^(?:remove|delete)(?:\s+note)?\s+([a-z0-9._-]{1,64})$/,
+  );
+  if (remove) return { type: "remove-note", noteId: remove[1]! };
+  const move = text.match(
+    /^(?:move|shift)\s+(?:note\s+)?([a-z0-9._-]{1,64})\s+(?:to|at)\s+(\d+(?:\.\d+)?)$/,
+  );
+  if (move)
+    return {
+      type: "update-note",
+      noteId: move[1]!,
+      patch: { start: Number(move[2]) },
+    };
+  const length = text.match(
+    /^(?:length|duration)\s+(?:note\s+)?([a-z0-9._-]{1,64})\s+(\d+(?:\.\d+)?)$/,
+  );
+  if (length)
+    return {
+      type: "update-note",
+      noteId: length[1]!,
+      patch: { duration: Number(length[2]) },
+    };
+  const velocity = text.match(
+    /^(?:velocity|vel)\s+(?:note\s+)?([a-z0-9._-]{1,64})\s+(0(?:\.\d+)?|1(?:\.0+)?)$/,
+  );
+  if (velocity)
+    return {
+      type: "update-note",
+      noteId: velocity[1]!,
+      patch: { velocity: Number(velocity[2]) },
+    };
+  const match = text.match(
+    /^(?:add|put)\s+(?:note\s+)?([a-g](?:#|b)?-?\d+)\s+(?:at\s+)?(\d+(?:\.\d+)?)\s*(?:for|dur|duration)?\s*(\d+(?:\.\d+)?)?$/,
+  );
+  if (!match) return undefined;
+  const pitch = pitchToMidi(match[1] ?? "c4");
+  const start = Number(match[2] ?? 0);
+  const duration = Number(match[3] ?? 1);
+  if (
+    !Number.isFinite(pitch) ||
+    !Number.isFinite(start) ||
+    !Number.isFinite(duration) ||
+    duration <= 0
+  )
+    return undefined;
+  return { type: "add-note", pitch, start, duration, velocity: 0.8 };
+}

package/src/agent/planner.ts

@@ -0,0 +1,259 @@
+import {
+  SCORE_LIMITS,
+  AUTOMATION_LANES,
+  isAutomationParameter,
+  normalizeDelay,
+  normalizeFilter,
+  normalizeReverb,
+  normalizeSampler,
+  scoreFromJSON,
+  type ScoreOperation,
+} from "../../core/score.ts";
+import { DRUM_VOICES } from "../../core/drums.ts";
+
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const MAX_OPERATIONS = 32;
+
+export type CompositionPlan = Readonly<{
+  operations: readonly ScoreOperation[];
+  explanation?: string;
+}>;
+
+/** Parse the only model output shape that the local reducer is allowed to apply. */
+export function parseCompositionPlan(text: string): CompositionPlan {
+  if (new TextEncoder().encode(text).byteLength > MAX_RESPONSE_BYTES)
+    throw new Error("agent response is too large");
+  const candidate = text.match(/```(?:json)?\s*([\s\S]*?)```/)?.[1] ?? text;
+  let value: unknown;
+  try {
+    value = JSON.parse(candidate.trim());
+  } catch {
+    throw new Error("agent response was not valid JSON");
+  }
+  if (
+    !isRecord(value) ||
+    !Array.isArray(value.operations) ||
+    value.operations.length > MAX_OPERATIONS
+  ) {
+    throw new Error("agent response must contain a bounded operations array");
+  }
+  const operations = value.operations.map(parseOperation);
+  const explanation =
+    typeof value.explanation === "string"
+      ? value.explanation.slice(0, 2_000)
+      : undefined;
+  return explanation === undefined
+    ? { operations }
+    : { operations, explanation };
+}
+
+/**
+ * Validate one foreign operation against the bounded planner contract. Every
+ * tool call and legacy JSON plan passes through here before the reducer sees it.
+ */
+export function validateAgentOperation(value: unknown): ScoreOperation {
+  return parseOperation(value);
+}
+
+function parseOperation(value: unknown): ScoreOperation {
+  if (!isRecord(value) || typeof value.type !== "string")
+    throw new Error("agent operation is malformed");
+  if (value.type === "addTrack") {
+    const track = scoreFromJSON({ tracks: [value.track] }).tracks[0]!;
+    return { type: "addTrack", track };
+  }
+  if (
+    value.type === "setBars" &&
+    typeof value.bars === "number" &&
+    Number.isInteger(value.bars) &&
+    value.bars >= 1 &&
+    value.bars <= SCORE_LIMITS.maxBars
+  ) {
+    return { type: "setBars", bars: value.bars };
+  }
+  if (
+    value.type === "removeNote" &&
+    typeof value.noteId === "string" &&
+    value.noteId.length <= 64
+  ) {
+    return { type: "removeNote", noteId: value.noteId };
+  }
+  if (
+    value.type === "setTempo" &&
+    typeof value.tempoBpm === "number" &&
+    Number.isFinite(value.tempoBpm)
+  ) {
+    return { type: "setTempo", tempoBpm: value.tempoBpm };
+  }
+  if (
+    value.type === "clearTrack" &&
+    typeof value.trackId === "string" &&
+    value.trackId.length <= 64
+  ) {
+    return { type: "clearTrack", trackId: value.trackId };
+  }
+  if (
+    value.type === "removeTrack" &&
+    typeof value.trackId === "string" &&
+    value.trackId.length <= 64
+  ) {
+    return { type: "removeTrack", trackId: value.trackId };
+  }
+  if (
+    value.type === "moveTrack" &&
+    typeof value.trackId === "string" &&
+    value.trackId.length <= 64 &&
+    typeof value.index === "number" &&
+    Number.isInteger(value.index) &&
+    value.index >= 0 &&
+    value.index < SCORE_LIMITS.maxTracks
+  ) {
+    return { type: "moveTrack", trackId: value.trackId, index: value.index };
+  }
+  if (
+    value.type === "setKey" &&
+    (value.key === null ||
+      (typeof value.key === "string" &&
+        value.key.length <= SCORE_LIMITS.maxNameLength))
+  ) {
+    return { type: "setKey", key: value.key };
+  }
+  if (
+    value.type === "setMeter" &&
+    typeof value.beatsPerBar === "number" &&
+    Number.isInteger(value.beatsPerBar) &&
+    value.beatsPerBar >= 1 &&
+    value.beatsPerBar <= SCORE_LIMITS.maxBeatsPerBar
+  ) {
+    return { type: "setMeter", beatsPerBar: value.beatsPerBar };
+  }
+  if (
+    value.type === "updateTrack" &&
+    typeof value.trackId === "string" &&
+    value.trackId.length <= 64 &&
+    isRecord(value.patch)
+  ) {
+    const patch = value.patch;
+    const safe: Record<string, unknown> = {};
+    if (typeof patch.name === "string") safe.name = patch.name.slice(0, 96);
+    if (typeof patch.instrument === "string")
+      safe.instrument = patch.instrument.slice(0, 64);
+    if (typeof patch.muted === "boolean") safe.muted = patch.muted;
+    if (typeof patch.volume === "number" && Number.isFinite(patch.volume))
+      safe.volume = patch.volume;
+    if (typeof patch.pan === "number" && Number.isFinite(patch.pan))
+      safe.pan = patch.pan;
+    if (typeof patch.solo === "boolean") safe.solo = patch.solo;
+    // Effects reuse the score's bounded validators; null removes an effect.
+    if (patch.filter !== undefined)
+      safe.filter = normalizeFilter(patch.filter) ?? null;
+    if (patch.delay !== undefined)
+      safe.delay = normalizeDelay(patch.delay) ?? null;
+    if (patch.reverb !== undefined)
+      safe.reverb = normalizeReverb(patch.reverb) ?? null;
+    if (patch.sampler !== undefined)
+      safe.sampler = normalizeSampler(patch.sampler) ?? null;
+    return { type: "updateTrack", trackId: value.trackId, patch: safe };
+  }
+  if (
+    value.type === "setAutomation" &&
+    typeof value.trackId === "string" &&
+    value.trackId.length <= SCORE_LIMITS.maxIdLength &&
+    isAutomationParameter(value.parameter) &&
+    Array.isArray(value.points) &&
+    value.points.length <= SCORE_LIMITS.maxAutomationPoints
+  ) {
+    const { min: minValue, max: maxValue } = AUTOMATION_LANES[value.parameter];
+    const points = value.points.map((candidate) => {
+      if (!isRecord(candidate))
+        throw new Error("agent automation point is malformed");
+      if (
+        typeof candidate.tick !== "number" ||
+        !Number.isInteger(candidate.tick) ||
+        candidate.tick < 0 ||
+        candidate.tick > SCORE_LIMITS.maxTick ||
+        typeof candidate.value !== "number" ||
+        !Number.isFinite(candidate.value) ||
+        candidate.value < minValue ||
+        candidate.value > maxValue
+      ) {
+        throw new Error("agent automation point is invalid");
+      }
+      return { tick: candidate.tick, value: candidate.value };
+    });
+    return {
+      type: "setAutomation",
+      trackId: value.trackId,
+      parameter: value.parameter,
+      points,
+    };
+  }
+  if (
+    value.type === "updateNote" &&
+    typeof value.noteId === "string" &&
+    value.noteId.length <= 64 &&
+    isRecord(value.patch)
+  ) {
+    const patch = value.patch;
+    const safe: Record<string, number> = {};
+    for (const key of [
+      "startTick",
+      "durationTicks",
+      "pitch",
+      "velocity",
+    ] as const) {
+      if (typeof patch[key] === "number" && Number.isFinite(patch[key]))
+        safe[key] = patch[key];
+    }
+    return { type: "updateNote", noteId: value.noteId, patch: safe };
+  }
+  if (value.type === "addNote" && isRecord(value.note)) {
+    const note = value.note;
+    if (
+      typeof note.id !== "string" ||
+      typeof note.trackId !== "string" ||
+      typeof note.pitch !== "number" ||
+      typeof note.velocity !== "number"
+    ) {
+      throw new Error("agent note is malformed");
+    }
+    const ticks =
+      typeof note.startTick === "number" &&
+      typeof note.durationTicks === "number";
+    const start = ticks ? note.startTick : note.start;
+    const duration = ticks ? note.durationTicks : note.duration;
+    if (typeof start !== "number" || typeof duration !== "number")
+      throw new Error("agent note timing is malformed");
+    if (
+      !Number.isFinite(start) ||
+      !Number.isFinite(duration) ||
+      duration <= 0 ||
+      !Number.isFinite(note.pitch) ||
+      !Number.isFinite(note.velocity)
+    ) {
+      throw new Error("agent note timing is invalid");
+    }
+    return {
+      type: "addNote",
+      note: {
+        id: note.id.slice(0, 64),
+        trackId: note.trackId.slice(0, 64),
+        ...(ticks
+          ? { startTick: start, durationTicks: duration }
+          : { start, duration }),
+        pitch: note.pitch,
+        velocity: note.velocity,
+      },
+    };
+  }
+  throw new Error("unsupported agent operation");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** "kick=36, snare=38, ..." for the model's drum vocabulary. */
+export function drumVoiceGuide(): string {
+  return DRUM_VOICES.map((info) => `${info.voice}=${info.pitch}`).join(", ");
+}