@hraness/dawg 0.0.0-stage → 0.2.0

package/src/agent/planner.ts

@@ -0,0 +1,221 @@
+import {
+  SCORE_LIMITS,
+  AUTOMATION_LANES,
+  isAutomationParameter,
+  normalizeDelay,
+  normalizeFilter,
+  normalizeReverb,
+  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 === "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;
+    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(", ");
+}

package/src/agent/provider.ts

@@ -0,0 +1,326 @@
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import {
+  configDir,
+  defaultAuthEnv,
+  PROVIDER_CHOICES,
+  readConfig,
+  resolveGatewayKey,
+  type AuthEnv,
+  type CredentialSource,
+  type ProviderChoice,
+} from "../auth/credentials.ts";
+import { systemRunner } from "../auth/runner.ts";
+import {
+  runAgentTurn,
+  type AgentBudget,
+  type AgentEvent,
+  type AgentHost,
+  type AgentTurnResult,
+} from "./agent.ts";
+import {
+  createGatewayClient,
+  type GatewayClient,
+  type GatewayModel,
+} from "./gateway.ts";
+import { runTextAgentTurn } from "./xcb-agent.ts";
+import {
+  readCapabilities,
+  resolveXcbBin,
+  shortModelLabel,
+  xcbGenerate,
+  type XcbCapabilities,
+} from "./xcb.ts";
+
+/**
+ * Which model backend a turn uses. `gateway` is the streaming tool-calling
+ * loop on the Vercel AI Gateway; `xcb` emulates tools over `xcb --json
+ * generate` with an AI subscription; `offline` means only direct commands.
+ */
+export type ProviderSelection =
+  | Readonly<{
+      kind: "gateway";
+      choice: ProviderChoice;
+      apiKey: string;
+      source: CredentialSource;
+    }>
+  | Readonly<{
+      kind: "xcb";
+      choice: ProviderChoice;
+      bin: string;
+      account: string;
+      accountLabel: string;
+      model: string;
+      /** xcb admits this account on its first call, which takes longer. */
+      admissionPending?: boolean;
+    }>
+  | Readonly<{ kind: "offline"; choice: ProviderChoice; reason: string }>;
+
+export const LOGIN_HINT = "run `dawg login` to enable the agent";
+/** The small, cheap model used for one-line helpers such as session names. */
+export const GATEWAY_SMALL_MODEL = "anthropic/claude-haiku-4.5";
+
+export function providerChoice(
+  env: Readonly<Record<string, string | undefined>>,
+  saved: ProviderChoice | undefined,
+): ProviderChoice {
+  const fromEnv = env.DAWG_PROVIDER?.trim().toLowerCase();
+  if (fromEnv && (PROVIDER_CHOICES as readonly string[]).includes(fromEnv))
+    return fromEnv as ProviderChoice;
+  return saved ?? "auto";
+}
+
+/**
+ * Resolve the provider: `DAWG_PROVIDER`, then the choice saved by `dawg
+ * login`, then `auto` (gateway when a key exists, else an available xcb
+ * account, else offline).
+ */
+export async function selectProvider(
+  auth: AuthEnv = defaultAuthEnv(systemRunner),
+  options: { capabilities?: XcbCapabilities } = {},
+): Promise<ProviderSelection> {
+  const config = await readConfig(auth);
+  const choice = providerChoice(auth.env, config.provider);
+  if (choice === "gateway" || choice === "auto") {
+    const key = await resolveGatewayKey(auth);
+    if (key)
+      return { kind: "gateway", choice, apiKey: key.key, source: key.source };
+    if (choice === "gateway")
+      return {
+        kind: "offline",
+        choice,
+        reason: `no AI Gateway key; ${LOGIN_HINT}`,
+      };
+  }
+  const bin = resolveXcbBin(auth.env, auth.runner);
+  if (!bin)
+    return {
+      kind: "offline",
+      choice,
+      reason:
+        choice === "xcb"
+          ? "xcb is not installed; see `dawg login --xcb`"
+          : `no model configured; ${LOGIN_HINT}`,
+    };
+  let capabilities: XcbCapabilities;
+  try {
+    capabilities =
+      options.capabilities ?? (await readCapabilities(bin, auth.runner));
+  } catch {
+    return {
+      kind: "offline",
+      choice,
+      reason: `xcb capabilities unavailable; ${LOGIN_HINT}`,
+    };
+  }
+  const saved = config.xcb;
+  if (saved) {
+    const account = capabilities.accounts.find(
+      (row) => row.id === saved.account,
+    );
+    if (
+      account?.available &&
+      account.models.some((model) => model.key === saved.model)
+    )
+      return {
+        kind: "xcb",
+        choice,
+        bin,
+        account: account.id,
+        accountLabel: account.label,
+        model: saved.model,
+        ...(account.admission === "pending" ? { admissionPending: true } : {}),
+      };
+    if (choice === "xcb")
+      return {
+        kind: "offline",
+        choice,
+        reason: `xcb account ${saved.account.slice(0, 12)} is ${account?.reason ?? "missing"}; run \`dawg login --xcb\``,
+      };
+  }
+  const account = capabilities.accounts.find((row) => row.available);
+  if (account)
+    return {
+      kind: "xcb",
+      choice,
+      bin,
+      account: account.id,
+      accountLabel: account.label,
+      model: account.models[0]!.key,
+      ...(account.admission === "pending" ? { admissionPending: true } : {}),
+    };
+  return {
+    kind: "offline",
+    choice,
+    reason:
+      choice === "xcb"
+        ? "no xcb account is qualified for applications; run `dawg login --xcb`"
+        : `no model configured; ${LOGIN_HINT}`,
+  };
+}
+
+/**
+ * A cheap fingerprint of everything on disk and in the environment that
+ * `selectProvider` reads (config.json, credentials.json, provider env vars).
+ * Two stats per call; the host re-resolves the provider when it changes.
+ */
+export function providerFingerprint(
+  dir: string = configDir(),
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+  const parts = ["config.json", "credentials.json"].map((name) => {
+    try {
+      const info = statSync(join(dir, name));
+      return `${name}:${info.size}:${info.mtimeMs}:${info.ino}`;
+    } catch {
+      return `${name}:-`;
+    }
+  });
+  // Presence only: a process's environment cannot change under it, and the
+  // fingerprint must never carry secret material.
+  parts.push(
+    `env:${env.DAWG_PROVIDER ?? "-"}:${env.AI_GATEWAY_API_KEY ? 1 : 0}`,
+  );
+  return parts.join("|");
+}
+
+/** `opus-5.5 · gateway`, `claude/sonnet · xcb`, or `offline`. */
+export function providerLabel(
+  selection: ProviderSelection,
+  gatewayModel: GatewayModel,
+): string {
+  if (selection.kind === "gateway") return `${gatewayModel} · gateway`;
+  if (selection.kind === "xcb")
+    return `${shortModelLabel(selection.model)} · xcb`;
+  return "offline";
+}
+
+export type ProviderTurnOptions = Readonly<{
+  selection: ProviderSelection;
+  prompt: string;
+  model: GatewayModel;
+  host: AgentHost;
+  onEvent?: (event: AgentEvent) => void;
+  signal?: AbortSignal;
+  budget?: AgentBudget;
+  /** Injected for tests; defaults to a client built from the selection's key. */
+  gatewayClient?: GatewayClient;
+  runner?: AuthEnv["runner"];
+}>;
+
+/** Run one agent turn on whichever provider was selected. */
+export async function runProviderTurn(
+  options: ProviderTurnOptions,
+): Promise<AgentTurnResult> {
+  const { selection } = options;
+  const common = {
+    prompt: options.prompt,
+    host: options.host,
+    ...(options.onEvent ? { onEvent: options.onEvent } : {}),
+    ...(options.signal ? { signal: options.signal } : {}),
+    ...(options.budget ? { budget: options.budget } : {}),
+  };
+  if (selection.kind === "gateway")
+    return runAgentTurn({
+      ...common,
+      model: options.model,
+      client:
+        options.gatewayClient ??
+        createGatewayClient({ apiKey: selection.apiKey }),
+    });
+  if (selection.kind === "xcb") {
+    const runner = options.runner ?? systemRunner;
+    return runTextAgentTurn({
+      ...common,
+      generate: (prompt, call) =>
+        xcbGenerate({
+          bin: selection.bin,
+          runner,
+          account: selection.account,
+          model: selection.model,
+          prompt,
+          timeoutMs: call.timeoutMs,
+          maxOutputBytes: call.maxOutputBytes,
+          signal: call.signal,
+        }),
+    });
+  }
+  const result: AgentTurnResult = {
+    type: "error",
+    code: "provider",
+    message: selection.reason,
+    applied: 0,
+    revision: options.host.snapshot().revision,
+  };
+  options.onEvent?.(result);
+  return result;
+}
+
+export type GenerateTextOptions = Readonly<{
+  /** Upper bound on reply tokens (gateway `max_tokens`; xcb gets ~8 bytes per token). */
+  maxTokens: number;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  /** Reuse an already-resolved provider; otherwise one is selected now. */
+  selection?: ProviderSelection;
+  gatewayClient?: GatewayClient;
+  runner?: AuthEnv["runner"];
+}>;
+
+/**
+ * One short, tool-free completion on whichever provider is configured, for
+ * helpers such as the session auto-namer. Gateway uses `GATEWAY_SMALL_MODEL`;
+ * xcb uses the selected account and model with a small output cap. Throws when
+ * no provider is available (callers should fall back to a local default).
+ * The returned text is untrusted, trimmed, and at most 512 characters.
+ */
+export async function generateText(
+  prompt: string,
+  options: GenerateTextOptions,
+): Promise<string> {
+  const selection = options.selection ?? (await selectProvider());
+  const maxTokens = Math.min(1024, Math.max(1, Math.floor(options.maxTokens)));
+  const timeoutMs = Math.min(
+    60_000,
+    Math.max(1_000, options.timeoutMs ?? 20_000),
+  );
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, timeout])
+    : timeout;
+  const input = prompt.slice(0, 16_000);
+  if (selection.kind === "gateway") {
+    const client =
+      options.gatewayClient ??
+      createGatewayClient({ apiKey: selection.apiKey });
+    let text = "";
+    for await (const event of client.stream(
+      {
+        model: "opus-5.5",
+        modelId: GATEWAY_SMALL_MODEL,
+        maxTokens,
+        messages: [{ role: "user", content: input }],
+        maxResponseBytes: 16 * 1024,
+      },
+      signal,
+    )) {
+      if (event.type === "text") text += event.delta;
+      if (text.length > 2048) break;
+    }
+    return text.trim().slice(0, 512);
+  }
+  if (selection.kind === "xcb") {
+    const text = await xcbGenerate({
+      bin: selection.bin,
+      runner: options.runner ?? systemRunner,
+      account: selection.account,
+      model: selection.model,
+      prompt: input,
+      timeoutMs,
+      maxOutputBytes: Math.min(4096, Math.max(64, maxTokens * 8)),
+      signal,
+    });
+    return text.trim().slice(0, 512);
+  }
+  throw new Error(selection.reason);
+}

package/src/agent/sse.ts

@@ -0,0 +1,90 @@
+/**
+ * Minimal, bounded Server-Sent Events reader for streamed chat completions.
+ *
+ * It yields the `data:` payload of each event (multi-line data is joined with
+ * `\n`), skips comments and other fields, and stops at `[DONE]`. Every byte
+ * read counts against `maxBytes`, and an abort signal cancels the underlying
+ * reader even when the fetch implementation does not observe the signal.
+ */
+
+export class SseBudgetError extends Error {
+  constructor(readonly maxBytes: number) {
+    super(`agent response exceeded ${maxBytes} bytes`);
+    this.name = "SseBudgetError";
+  }
+}
+
+export async function* readSseData(
+  body: ReadableStream<Uint8Array>,
+  options: { maxBytes: number; signal?: AbortSignal },
+): AsyncGenerator<string> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let data: string[] = [];
+  let total = 0;
+  const signal = options.signal;
+  let onAbort: (() => void) | undefined;
+  const aborted =
+    signal === undefined
+      ? undefined
+      : new Promise<never>((_, reject) => {
+          onAbort = () => reject(abortReason(signal));
+          if (signal.aborted) onAbort();
+          else signal.addEventListener("abort", onAbort, { once: true });
+        });
+  // Avoid an unhandled rejection when the stream finishes before an abort.
+  aborted?.catch(() => undefined);
+  try {
+    while (true) {
+      const chunk = aborted
+        ? await Promise.race([reader.read(), aborted])
+        : await reader.read();
+      if (chunk.done) break;
+      total += chunk.value.byteLength;
+      if (total > options.maxBytes) throw new SseBudgetError(options.maxBytes);
+      buffer += decoder.decode(chunk.value, { stream: true });
+      let newline = buffer.search(/\r\n|\r|\n/);
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline);
+        const width =
+          buffer[newline] === "\r" && buffer[newline + 1] === "\n" ? 2 : 1;
+        buffer = buffer.slice(newline + width);
+        if (line === "") {
+          if (data.length > 0) {
+            const payload = data.join("\n");
+            data = [];
+            if (payload === "[DONE]") return;
+            yield payload;
+          }
+        } else if (line.startsWith("data:")) {
+          data.push(line.slice(line[5] === " " ? 6 : 5));
+        }
+        newline = buffer.search(/\r\n|\r|\n/);
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.startsWith("data:"))
+      data.push(buffer.slice(buffer[5] === " " ? 6 : 5));
+    if (data.length > 0) {
+      const payload = data.join("\n");
+      if (payload !== "[DONE]") yield payload;
+    }
+  } finally {
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+    await reader.cancel().catch(() => undefined);
+    try {
+      reader.releaseLock();
+    } catch {
+      // A pending read is rejected by cancel(); the lock is already moot.
+    }
+  }
+}
+
+function abortReason(signal: AbortSignal): Error {
+  const reason: unknown = signal.reason;
+  if (reason instanceof Error) return reason;
+  const error = new Error("agent request was aborted");
+  error.name = "AbortError";
+  return error;
+}