@hraness/dawg 0.0.0-stage → 0.2.0

package/src/agent/brief.ts

@@ -0,0 +1,140 @@
+import type { TrackScore } from "../../core/score.ts";
+import { AVAILABLE_EFFECTS, AVAILABLE_INSTRUMENTS } from "../audio/wav.ts";
+
+export const MAX_BRIEF_BYTES = 12 * 1024;
+const MAX_FOCUSED_NOTES = 96;
+const MAX_RECENT = 8;
+const MAX_RECENT_CHARS = 120;
+const NOTE_NAMES = [
+  "C",
+  "C#",
+  "D",
+  "D#",
+  "E",
+  "F",
+  "F#",
+  "G",
+  "G#",
+  "A",
+  "A#",
+  "B",
+];
+
+/**
+ * A compact, deterministic snapshot of the composition for the model. It is
+ * derived only from score state and caller-supplied operation summaries, so
+ * the same score, revision, and history always yield the same bytes, and no
+ * environment value (including credentials) can reach it.
+ */
+export function compositionBrief(options: {
+  score: TrackScore;
+  revision: number;
+  focusedTrackId: string;
+  recentOperations?: readonly string[];
+  maxBytes?: number;
+}): string {
+  const { score } = options;
+  const maxBytes = options.maxBytes ?? MAX_BRIEF_BYTES;
+  const tpb = score.ticksPerBeat;
+  const beats = (ticks: number) => Math.round((ticks / tpb) * 1000) / 1000;
+  const tracks = score.tracks.map((track) => {
+    const notes = score.notes.filter((note) => note.trackId === track.id);
+    const pitches = notes.map((note) => note.pitch);
+    return {
+      id: track.id,
+      name: track.name,
+      instrument: track.instrument,
+      ...(track.muted ? { muted: true } : {}),
+      volume: track.volume,
+      pan: track.pan,
+      notes: notes.length,
+      ...(notes.length > 0
+        ? {
+            range: `${noteName(Math.min(...pitches))}..${noteName(Math.max(...pitches))}`,
+          }
+        : {}),
+      ...(track.volumeAutomation.length > 0
+        ? { volumeAutomation: track.volumeAutomation.length }
+        : {}),
+      ...(track.panAutomation.length > 0
+        ? { panAutomation: track.panAutomation.length }
+        : {}),
+      ...(track.solo ? { solo: true } : {}),
+      ...(track.filter ? { filter: track.filter } : {}),
+      ...(track.delay ? { delay: track.delay } : {}),
+      ...((track.filterAutomation?.length ?? 0) > 0
+        ? { filterAutomation: track.filterAutomation!.length }
+        : {}),
+      ...(track.reverb ? { reverb: track.reverb } : {}),
+      ...((track.resonanceAutomation?.length ?? 0) > 0
+        ? { resonanceAutomation: track.resonanceAutomation!.length }
+        : {}),
+      ...((track.delayFeedbackAutomation?.length ?? 0) > 0
+        ? { delayFeedbackAutomation: track.delayFeedbackAutomation!.length }
+        : {}),
+      ...((track.delayMixAutomation?.length ?? 0) > 0
+        ? { delayMixAutomation: track.delayMixAutomation!.length }
+        : {}),
+    };
+  });
+  const focusedNotes = score.notes
+    .filter((note) => note.trackId === options.focusedTrackId)
+    .slice()
+    .sort(
+      (left, right) =>
+        left.startTick - right.startTick ||
+        left.pitch - right.pitch ||
+        left.id.localeCompare(right.id),
+    )
+    .map((note) => [
+      note.id,
+      noteName(note.pitch),
+      beats(note.startTick),
+      beats(note.durationTicks),
+      Math.round(note.velocity * 100) / 100,
+    ]);
+  const recent = (options.recentOperations ?? [])
+    .slice(-MAX_RECENT)
+    .map((line) => line.replace(/\s+/g, " ").slice(0, MAX_RECENT_CHARS));
+  const build = (noteLimit: number, trackLimit: number) => {
+    const visible = focusedNotes.slice(0, noteLimit);
+    return JSON.stringify({
+      revision: options.revision,
+      tempoBpm: score.tempoBpm,
+      meter: `${score.beatsPerBar}/4`,
+      bars: score.bars,
+      loopBeats: score.bars * score.beatsPerBar,
+      ...(score.key ? { key: score.key } : {}),
+      focusedTrack: options.focusedTrackId,
+      tracks: tracks.slice(0, trackLimit),
+      ...(tracks.length > trackLimit
+        ? { omittedTracks: tracks.length - trackLimit }
+        : {}),
+      focusedNotes: {
+        columns: ["id", "pitch", "startBeat", "durationBeats", "velocity"],
+        rows: visible,
+        ...(focusedNotes.length > visible.length
+          ? { omitted: focusedNotes.length - visible.length }
+          : {}),
+      },
+      recentOperations: recent,
+      instruments: AVAILABLE_INSTRUMENTS,
+      effects: AVAILABLE_EFFECTS,
+    });
+  };
+  const encoder = new TextEncoder();
+  let noteLimit = Math.min(MAX_FOCUSED_NOTES, focusedNotes.length);
+  let trackLimit = tracks.length;
+  let brief = build(noteLimit, trackLimit);
+  while (encoder.encode(brief).byteLength > maxBytes) {
+    if (noteLimit > 0) noteLimit = Math.floor(noteLimit / 2);
+    else if (trackLimit > 1) trackLimit = Math.floor(trackLimit / 2);
+    else break;
+    brief = build(noteLimit, trackLimit);
+  }
+  return brief;
+}
+
+export function noteName(midi: number): string {
+  return `${NOTE_NAMES[midi % 12]}${Math.floor(midi / 12) - 1}`;
+}

package/src/agent/gateway.ts

@@ -0,0 +1,267 @@
+import { readSseData } from "./sse.ts";
+
+/** The only model labels dawg accepts. Provider IDs are local configuration. */
+export const GATEWAY_MODELS = Object.freeze(["opus-5.5", "sol-6.1"] as const);
+export type GatewayModel = (typeof GATEWAY_MODELS)[number];
+
+/**
+ * Default provider IDs, confirmed against the AI Gateway catalog
+ * (`GET https://ai-gateway.vercel.sh/v1/models`, 2026-10-06): both are
+ * language models tagged `tool-use`.
+ */
+export const DEFAULT_MODEL_IDS: Readonly<Record<GatewayModel, string>> =
+  Object.freeze({
+    "opus-5.5": "anthropic/claude-opus-5.5",
+    "sol-6.1": "openai/gpt-6.1-sol",
+  });
+
+const MODEL_ID_PATTERN =
+  /^[a-z0-9][a-z0-9-]{0,63}\/[a-z0-9][a-z0-9._-]{0,127}$/i;
+const MAX_ERROR_BODY_BYTES = 4 * 1024;
+
+export function isGatewayModel(value: unknown): value is GatewayModel {
+  return (
+    typeof value === "string" &&
+    (GATEWAY_MODELS as readonly string[]).includes(value)
+  );
+}
+
+/** Resolve an allowlisted alias to its provider ID, rejecting anything else. */
+export function resolveModelId(
+  alias: string,
+  overrides: Partial<Record<GatewayModel, string | undefined>> = {},
+): string {
+  if (!isGatewayModel(alias))
+    throw new Error(
+      `unknown model "${alias.slice(0, 32)}"; use ${GATEWAY_MODELS.join(" or ")}`,
+    );
+  const id = overrides[alias] ?? DEFAULT_MODEL_IDS[alias];
+  if (!MODEL_ID_PATTERN.test(id))
+    throw new Error(`model ID for ${alias} must look like provider/model`);
+  return id;
+}
+
+function checkedModelId(id: string): string {
+  if (!MODEL_ID_PATTERN.test(id))
+    throw new Error("model ID must look like provider/model");
+  return id;
+}
+
+export type ChatToolCall = {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };
+};
+
+export type ChatMessage =
+  | { role: "system" | "user"; content: string }
+  | { role: "assistant"; content: string | null; tool_calls?: ChatToolCall[] }
+  | { role: "tool"; tool_call_id: string; content: string };
+
+export type ChatTool = {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+};
+
+export type ChatStreamRequest = {
+  model: GatewayModel;
+  messages: readonly ChatMessage[];
+  tools?: readonly ChatTool[];
+  temperature?: number;
+  /** Exact provider model ID, bypassing the alias (e.g. a small model for naming). */
+  modelId?: string;
+  maxTokens?: number;
+  maxResponseBytes: number;
+};
+
+/** Normalized stream events; provider chunk shapes never leave this module. */
+export type ChatStreamEvent =
+  | { type: "text"; delta: string }
+  | {
+      type: "tool-delta";
+      index: number;
+      id?: string;
+      name?: string;
+      arguments?: string;
+    }
+  | { type: "finish"; reason: string };
+
+export type GatewayClient = {
+  /** The provider model ID that a turn will use (for diagnostics only). */
+  modelId(model: GatewayModel): string;
+  stream(
+    request: ChatStreamRequest,
+    signal?: AbortSignal,
+  ): AsyncIterable<ChatStreamEvent>;
+};
+
+export class GatewayError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+  ) {
+    super(message);
+    this.name = "GatewayError";
+  }
+}
+
+type GatewayFetcher = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export function createGatewayClient(
+  options: {
+    apiKey?: string;
+    baseUrl?: string;
+    modelIds?: Partial<Record<GatewayModel, string>>;
+    fetcher?: GatewayFetcher;
+  } = {},
+): GatewayClient {
+  const fetcher = options.fetcher ?? fetch;
+  const baseUrl = (
+    options.baseUrl ??
+    process.env.AI_GATEWAY_BASE_URL ??
+    "https://ai-gateway.vercel.sh/v1"
+  ).replace(/\/$/, "");
+  const apiKey = options.apiKey ?? process.env.AI_GATEWAY_API_KEY;
+  const overrides: Partial<Record<GatewayModel, string | undefined>> = {
+    "opus-5.5": process.env.DAWG_OPUS_MODEL || undefined,
+    "sol-6.1": process.env.DAWG_SOL_MODEL || undefined,
+    ...options.modelIds,
+  };
+  const redact = (text: string): string =>
+    apiKey && apiKey.length > 0 ? text.split(apiKey).join("[redacted]") : text;
+
+  return {
+    modelId: (model) => resolveModelId(model, overrides),
+    async *stream(request, signal) {
+      const model =
+        request.modelId !== undefined
+          ? checkedModelId(request.modelId)
+          : resolveModelId(request.model, overrides);
+      if (!apiKey)
+        throw new GatewayError(
+          "no AI Gateway key; run `dawg login` or set AI_GATEWAY_API_KEY",
+        );
+      const body: Record<string, unknown> = {
+        model,
+        messages: request.messages,
+        stream: true,
+      };
+      if (request.tools && request.tools.length > 0) {
+        body.tools = request.tools;
+        body.tool_choice = "auto";
+      }
+      if (request.temperature !== undefined)
+        body.temperature = request.temperature;
+      if (
+        request.maxTokens !== undefined &&
+        Number.isInteger(request.maxTokens) &&
+        request.maxTokens > 0
+      )
+        body.max_tokens = Math.min(request.maxTokens, 4096);
+      const init: RequestInit = {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          "content-type": "application/json",
+          accept: "text/event-stream",
+        },
+        body: JSON.stringify(body),
+      };
+      if (signal !== undefined) init.signal = signal;
+      const response = await fetcher(`${baseUrl}/chat/completions`, init);
+      if (!response.ok) {
+        const detail = redact(await boundedErrorDetail(response));
+        throw new GatewayError(
+          `AI Gateway request failed (${response.status})${detail ? `: ${detail}` : ""}`,
+          response.status,
+        );
+      }
+      if (!response.body)
+        throw new GatewayError("AI Gateway returned an empty stream");
+      const streamOptions: { maxBytes: number; signal?: AbortSignal } = {
+        maxBytes: request.maxResponseBytes,
+      };
+      if (signal !== undefined) streamOptions.signal = signal;
+      for await (const data of readSseData(response.body, streamOptions)) {
+        let chunk: unknown;
+        try {
+          chunk = JSON.parse(data);
+        } catch {
+          throw new GatewayError("AI Gateway sent a malformed stream chunk");
+        }
+        yield* normalizeChunk(chunk, redact);
+      }
+    },
+  };
+}
+
+function* normalizeChunk(
+  chunk: unknown,
+  redact: (text: string) => string,
+): Generator<ChatStreamEvent> {
+  if (!isRecord(chunk)) return;
+  if (isRecord(chunk.error)) {
+    const message =
+      typeof chunk.error.message === "string"
+        ? chunk.error.message.slice(0, 300)
+        : "unknown provider error";
+    throw new GatewayError(`AI Gateway stream error: ${redact(message)}`);
+  }
+  const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : undefined;
+  if (!isRecord(choice)) return;
+  const delta = isRecord(choice.delta) ? choice.delta : undefined;
+  if (delta && typeof delta.content === "string" && delta.content.length > 0)
+    yield { type: "text", delta: delta.content };
+  if (delta && Array.isArray(delta.tool_calls)) {
+    for (const [position, call] of delta.tool_calls.entries()) {
+      if (!isRecord(call)) continue;
+      const event: ChatStreamEvent = {
+        type: "tool-delta",
+        index:
+          typeof call.index === "number" && Number.isInteger(call.index)
+            ? call.index
+            : position,
+      };
+      if (typeof call.id === "string") event.id = call.id;
+      const fn = isRecord(call.function) ? call.function : undefined;
+      if (fn && typeof fn.name === "string" && fn.name.length > 0)
+        event.name = fn.name;
+      if (fn && typeof fn.arguments === "string")
+        event.arguments = fn.arguments;
+      yield event;
+    }
+  }
+  if (typeof choice.finish_reason === "string")
+    yield { type: "finish", reason: choice.finish_reason };
+}
+
+async function boundedErrorDetail(response: Response): Promise<string> {
+  try {
+    const text = (await response.text()).slice(0, MAX_ERROR_BODY_BYTES);
+    try {
+      const parsed: unknown = JSON.parse(text);
+      if (
+        isRecord(parsed) &&
+        isRecord(parsed.error) &&
+        typeof parsed.error.message === "string"
+      )
+        return parsed.error.message.slice(0, 300);
+    } catch {
+      // Plain-text error bodies are summarized below.
+    }
+    return text.replace(/\s+/g, " ").trim().slice(0, 300);
+  } catch {
+    return "";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/agent/ops.ts

@@ -0,0 +1,172 @@
+import { SCORE_LIMITS } from "../../core/score.ts";
+
+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 };
+}
+
+export function pitchToMidi(value: string): number {
+  const match = value.match(/^([a-g])([#b]?)(-?\d+)$/);
+  if (!match) return Number.NaN;
+  const semitones: Record<string, number> = {
+    c: 0,
+    d: 2,
+    e: 4,
+    f: 5,
+    g: 7,
+    a: 9,
+    b: 11,
+  };
+  const accidental = match[2] === "#" ? 1 : match[2] === "b" ? -1 : 0;
+  return (
+    (Number(match[3]) + 1) * 12 + (semitones[match[1] ?? "c"] ?? 0) + accidental
+  );
+}