@hraness/dawg 0.0.0-stage → 0.2.0

package/src/agent/xcb-agent.ts

@@ -0,0 +1,247 @@
+import { compositionBrief } from "./brief.ts";
+import {
+  AGENT_LIMITS,
+  AgentTimeoutError,
+  classifyAgentError,
+  executeCall,
+  tighten,
+  type AgentBudget,
+  type AgentEvent,
+  type AgentHost,
+  type AgentTurnResult,
+} from "./agent.ts";
+import { AGENT_TOOLS, type AgentTool } from "./tools.ts";
+import { parseTextReply, XcbError, type TextReply } from "./xcb.ts";
+import { SseBudgetError } from "./sse.ts";
+
+/** Steps per xcb turn. Each step is one full model call, so keep it small. */
+export const XCB_MAX_STEPS = 3;
+const MAX_PROMPT_CHARS = 8_000;
+const MAX_FEEDBACK_CHARS = 6_000;
+
+/** One text-in/text-out model call; `generate` must honour `signal`. */
+export type TextGenerate = (
+  prompt: string,
+  options: { signal: AbortSignal; timeoutMs: number; maxOutputBytes: number },
+) => Promise<string>;
+
+export type TextAgentTurnOptions = Readonly<{
+  prompt: string;
+  generate: TextGenerate;
+  host: AgentHost;
+  onEvent?: (event: AgentEvent) => void;
+  signal?: AbortSignal;
+  budget?: AgentBudget;
+  tools?: readonly AgentTool[];
+  newNoteId?: (trackId: string, revision: number, index: number) => string;
+}>;
+
+export const TEXT_AGENT_SYSTEM_PROMPT = [
+  "You are dawg, a loop composer inside a terminal music workstation.",
+  "You edit the score by returning operations. Each op is validated and applied immediately, in order, as its own 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 ops (one add_notes op 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.",
+  'Reply with exactly one JSON object and nothing else, shaped {"ops":[{"tool":"<tool name>","args":{...}}],"say":"<one short sentence describing the musical change>","done":true}.',
+  'Set "done":false only if you need to see the results of these ops before continuing; you will then get each op\'s result and can send more ops.',
+  "If an op was rejected, read its diagnostic and either send a corrected op or stop with done:true.",
+].join(" ");
+
+/** Render the tool registry as a compact op catalog for a text-only model. */
+export function renderToolCatalog(
+  tools: readonly AgentTool[] = AGENT_TOOLS,
+): string {
+  return tools
+    .map(
+      (tool) =>
+        `- ${tool.name}: ${tool.description}\n  args schema: ${JSON.stringify(tool.parameters)}`,
+    )
+    .join("\n");
+}
+
+/**
+ * A tool loop for providers without tool calling (xcb). The model returns one
+ * JSON object of ops; each op goes through the same tool argument checks,
+ * operation validator, reducer dry run and per-op commit as the gateway path.
+ * Rejected ops or `done:false` trigger another call with diagnostics, up to
+ * `XCB_MAX_STEPS` calls and the usual turn budgets.
+ */
+export async function runTextAgentTurn(
+  options: TextAgentTurnOptions,
+): Promise<AgentTurnResult> {
+  const limits = {
+    maxSteps: Math.min(
+      XCB_MAX_STEPS,
+      tighten(options.budget?.maxSteps, AGENT_LIMITS.maxSteps),
+    ),
+    maxToolCalls: tighten(
+      options.budget?.maxToolCalls,
+      AGENT_LIMITS.maxToolCalls,
+    ),
+    maxResponseBytes: tighten(
+      options.budget?.maxResponseBytes,
+      AGENT_LIMITS.maxResponseBytes,
+    ),
+    timeoutMs: tighten(options.budget?.timeoutMs, AGENT_LIMITS.timeoutMs),
+  };
+  const emit = (event: AgentEvent) => {
+    try {
+      options.onEvent?.(event);
+    } catch {
+      // A rendering failure must never corrupt the turn.
+    }
+  };
+  const tools = options.tools ?? AGENT_TOOLS;
+  const catalog = renderToolCatalog(tools);
+  const nonce = Math.random().toString(36).slice(2, 6);
+  const newNoteId =
+    options.newNoteId ??
+    ((trackId: string, revision: number, index: number) =>
+      `${trackId.slice(0, 40)}-${revision}-${nonce}${index}`);
+  const startedAt = Date.now();
+  const timeout = new AbortController();
+  const timer = setTimeout(
+    () => timeout.abort(new AgentTimeoutError(limits.timeoutMs)),
+    limits.timeoutMs,
+  );
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, timeout.signal])
+    : timeout.signal;
+
+  let applied = 0;
+  let rejected = 0;
+  let toolCalls = 0;
+  let bytesUsed = 0;
+  let finalText = "";
+  const steering: string[] = [];
+  let feedback = "";
+  const currentRevision = () => options.host.snapshot().revision;
+  const finish = (result: AgentTurnResult): AgentTurnResult => {
+    clearTimeout(timer);
+    emit(result);
+    return result;
+  };
+  const done = (reason: "stop" | "max-steps" | "max-tool-calls") =>
+    finish({
+      type: "done",
+      reason,
+      text: finalText,
+      applied,
+      rejected,
+      revision: currentRevision(),
+    });
+
+  try {
+    for (let step = 1; step <= limits.maxSteps; step += 1) {
+      if (signal.aborted) throw signal.reason;
+      for (const steer of options.host.takeSteering?.() ?? [])
+        steering.push(steer.slice(0, 2_000));
+      emit({ type: "step", step });
+      const remainingBytes = limits.maxResponseBytes - bytesUsed;
+      if (remainingBytes <= 0)
+        throw new SseBudgetError(limits.maxResponseBytes);
+      const prompt = [
+        TEXT_AGENT_SYSTEM_PROMPT,
+        `Tools:\n${catalog}`,
+        `Composition brief (JSON): ${compositionBrief(options.host.snapshot())}`,
+        `User request: ${options.prompt.slice(0, MAX_PROMPT_CHARS)}`,
+        ...steering.map((text) => `Steering from the user mid-turn: ${text}`),
+        feedback
+          ? `Results of your previous ops (the brief above already reflects accepted ones):\n${feedback}`
+          : "",
+        "Reply now with the single JSON object.",
+      ]
+        .filter(Boolean)
+        .join("\n\n");
+      const remainingMs = limits.timeoutMs - (Date.now() - startedAt);
+      const reply = await options.generate(prompt, {
+        signal,
+        timeoutMs: Math.max(1_000, remainingMs),
+        maxOutputBytes: Math.min(remainingBytes, 64 * 1024),
+      });
+      if (signal.aborted) throw signal.reason;
+      bytesUsed += reply.length;
+
+      let parsed: TextReply;
+      try {
+        parsed = parseTextReply(reply);
+      } catch (error) {
+        const diagnostic =
+          error instanceof XcbError
+            ? error.message
+            : "reply could not be parsed";
+        rejected += 1;
+        emit({
+          type: "tool-rejected",
+          callId: `xcb-${step}-reply`,
+          name: "reply",
+          diagnostic,
+        });
+        feedback = `Your reply was rejected: ${diagnostic}. Reply with exactly one JSON object.`;
+        continue;
+      }
+      if (parsed.say) {
+        finalText = parsed.say;
+        emit({ type: "text-delta", delta: parsed.say });
+      }
+      const results: string[] = [];
+      let stepRejected = 0;
+      let overBudget = false;
+      for (const [index, op] of parsed.ops.entries()) {
+        if (signal.aborted) throw signal.reason;
+        const callId = `xcb-${step}-${index}`;
+        if (toolCalls >= limits.maxToolCalls) {
+          overBudget = true;
+          rejected += 1;
+          stepRejected += 1;
+          emit({
+            type: "tool-rejected",
+            callId,
+            name: op.tool,
+            diagnostic: "tool call budget exhausted",
+          });
+          continue;
+        }
+        toolCalls += 1;
+        emit({ type: "tool-start", callId, name: op.tool, step });
+        const outcome = await executeCall(
+          { id: callId, name: op.tool, arguments: JSON.stringify(op.args) },
+          { tools, host: options.host, newNoteId },
+        );
+        if (outcome.ok) {
+          applied += outcome.mutated ? 1 : 0;
+          if (outcome.explanation) finalText = outcome.explanation;
+          emit(outcome.event);
+        } else {
+          rejected += 1;
+          stepRejected += 1;
+          emit({
+            type: "tool-rejected",
+            callId,
+            name: op.tool,
+            diagnostic: outcome.diagnostic,
+          });
+        }
+        results.push(`ops[${index}] ${op.tool}: ${outcome.content}`);
+      }
+      if (overBudget || toolCalls >= limits.maxToolCalls)
+        return done("max-tool-calls");
+      if (stepRejected === 0 && parsed.done) return done("stop");
+      feedback =
+        results.join("\n").slice(0, MAX_FEEDBACK_CHARS) || "No ops were sent.";
+    }
+    return done("max-steps");
+  } catch (error) {
+    const { code, message } = classifyAgentError(error, signal, options.signal);
+    return finish({
+      type: "error",
+      code,
+      message,
+      applied,
+      revision: currentRevision(),
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/agent/xcb.ts

@@ -0,0 +1,367 @@
+import type { CommandRunner } from "../auth/runner.ts";
+
+/**
+ * Client for xcb's application API (`xcb --json generate`): one prompt in, one
+ * untrusted text reply out, zero tools, no streaming. See
+ * https://github.com/hraness/xcb/blob/main/docs/application-api.md
+ */
+export const XCB_DOC_URL =
+  "https://github.com/hraness/xcb/blob/main/docs/application-api.md";
+export const XCB_INSTALL = "curl -fsSL https://xcb.sh/install.sh | sh";
+export const XCB_LIMITS = Object.freeze({
+  maxInputBytes: 1024 * 1024,
+  maxOutputBytes: 262_144,
+  minTimeoutMs: 1_000,
+  maxTimeoutMs: 300_000,
+  maxCapabilityBytes: 2 * 1024 * 1024,
+  maxAccounts: 128,
+  maxModelsPerAccount: 64,
+});
+const ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+const MODEL_PATTERN = /^[A-Za-z0-9._:/-]{1,200}$/;
+const FAILURE_CODES = new Set([
+  "invalid_request",
+  "unavailable",
+  "busy",
+  "deadline",
+  "cancelled",
+  "provider_error",
+  "output_limit",
+  "custody_unproven",
+]);
+
+export class XcbError extends Error {
+  constructor(
+    message: string,
+    readonly code: string = "provider_error",
+  ) {
+    super(message);
+    this.name = "XcbError";
+  }
+}
+
+export type XcbModel = Readonly<{ key: string; label: string }>;
+export type XcbAccount = Readonly<{
+  id: string;
+  label: string;
+  provider: string;
+  available: boolean;
+  connected: boolean;
+  reason: string | null;
+  models: readonly XcbModel[];
+  /**
+   * xcb's per-account application admission, when it reports one. `pending`
+   * means xcb admits the account on first use (that call is slower); it
+   * treats it as usable. Absent on xcb builds without automatic admission.
+   */
+  admission?: "pending" | "admitted" | "denied" | undefined;
+}>;
+export type XcbCapabilities = Readonly<{
+  supported: boolean;
+  accounts: readonly XcbAccount[];
+}>;
+
+/** `XCB_BIN` if set, otherwise `xcb` on PATH. Never installs anything. */
+export function resolveXcbBin(
+  env: Readonly<Record<string, string | undefined>>,
+  runner: CommandRunner,
+): string | undefined {
+  const explicit = env.XCB_BIN?.trim();
+  if (explicit) return explicit;
+  return runner.which("xcb");
+}
+
+function shortString(value: unknown, max: number, fallback = ""): string {
+  return typeof value === "string"
+    ? value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, max)
+    : fallback;
+}
+
+/** Parse `xcb --json generate --capabilities` output from `unknown`. */
+const ADMISSION_STATES = new Set(["pending", "admitted", "denied"]);
+
+/** `"pending"` or `{ state | status: "pending" }`; anything else is ignored. */
+function admissionState(value: unknown): XcbAccount["admission"] {
+  const raw = isRecord(value) ? (value.state ?? value.status) : value;
+  return typeof raw === "string" && ADMISSION_STATES.has(raw)
+    ? (raw as XcbAccount["admission"])
+    : undefined;
+}
+
+export function parseCapabilities(value: unknown): XcbCapabilities {
+  if (!isRecord(value) || value.version !== 1)
+    throw new XcbError("xcb capabilities were not a version-1 object");
+  const rows = Array.isArray(value.accounts)
+    ? value.accounts.slice(0, XCB_LIMITS.maxAccounts)
+    : [];
+  const accounts: XcbAccount[] = [];
+  for (const row of rows) {
+    if (
+      !isRecord(row) ||
+      typeof row.id !== "string" ||
+      !ID_PATTERN.test(row.id)
+    )
+      continue;
+    const models: XcbModel[] = [];
+    const modelRows = Array.isArray(row.models)
+      ? row.models.slice(0, XCB_LIMITS.maxModelsPerAccount)
+      : [];
+    for (const model of modelRows) {
+      if (
+        !isRecord(model) ||
+        typeof model.key !== "string" ||
+        !MODEL_PATTERN.test(model.key)
+      )
+        continue;
+      models.push({
+        key: model.key,
+        label: shortString(model.label, 64, model.key) || model.key,
+      });
+    }
+    const label =
+      shortString(row.label, 64) ||
+      shortString(row.name, 64) ||
+      shortString(row.email, 64) ||
+      row.id;
+    const admission = admissionState(row.admission);
+    accounts.push({
+      id: row.id,
+      label,
+      provider: shortString(row.provider, 32, "unknown") || "unknown",
+      // A pending admission is usable: xcb admits the account on first call.
+      available:
+        models.length > 0 &&
+        admission !== "denied" &&
+        (row.available === true || admission === "pending"),
+      ...(admission ? { admission } : {}),
+      connected: row.connected === true,
+      reason:
+        typeof row.reason === "string" ? shortString(row.reason, 64) : null,
+      models,
+    });
+  }
+  return { supported: value.supported === true, accounts };
+}
+
+export async function readCapabilities(
+  bin: string,
+  runner: CommandRunner,
+  signal?: AbortSignal,
+): Promise<XcbCapabilities> {
+  const result = await runner.run(
+    bin,
+    ["--json", "generate", "--capabilities"],
+    {
+      timeoutMs: 15_000,
+      maxOutputBytes: XCB_LIMITS.maxCapabilityBytes,
+      ...(signal ? { signal } : {}),
+    },
+  );
+  if (result.code !== 0)
+    throw new XcbError(
+      `xcb capabilities failed (exit ${result.code})`,
+      "unavailable",
+    );
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    throw new XcbError("xcb capabilities were not valid JSON");
+  }
+  return parseCapabilities(parsed);
+}
+
+export type XcbGenerateRequest = Readonly<{
+  bin: string;
+  runner: CommandRunner;
+  account: string;
+  model: string;
+  prompt: string;
+  timeoutMs: number;
+  maxOutputBytes: number;
+  signal?: AbortSignal;
+}>;
+
+/**
+ * One `xcb --json generate` call. Aborting sends SIGTERM and waits for xcb to
+ * finish its own cleanup (it keeps the account held until the provider exits).
+ */
+export async function xcbGenerate(
+  request: XcbGenerateRequest,
+): Promise<string> {
+  if (!ID_PATTERN.test(request.account))
+    throw new XcbError("invalid xcb account id", "invalid_request");
+  if (!MODEL_PATTERN.test(request.model))
+    throw new XcbError("invalid xcb model key", "invalid_request");
+  const timeoutMs = clamp(
+    Math.round(request.timeoutMs),
+    XCB_LIMITS.minTimeoutMs,
+    XCB_LIMITS.maxTimeoutMs,
+  );
+  const maxOutputBytes = clamp(
+    Math.round(request.maxOutputBytes),
+    1,
+    XCB_LIMITS.maxOutputBytes,
+  );
+  const prompt = request.prompt.replace(/\u0000/g, "");
+  if (prompt.trim().length === 0)
+    throw new XcbError("empty prompt", "invalid_request");
+  const body = JSON.stringify({
+    version: 1,
+    account: request.account,
+    model: request.model,
+    prompt,
+    timeoutMs,
+    maxOutputBytes,
+  });
+  if (new TextEncoder().encode(body).byteLength > XCB_LIMITS.maxInputBytes)
+    throw new XcbError(
+      "prompt exceeds xcb's 1 MiB input limit",
+      "invalid_request",
+    );
+  if (request.signal?.aborted) throw new XcbError("cancelled", "cancelled");
+  const result = await request.runner.run(request.bin, ["--json", "generate"], {
+    stdin: body,
+    // xcb enforces its own deadline; this is a backstop for a wedged process.
+    timeoutMs: timeoutMs + 30_000,
+    maxOutputBytes: maxOutputBytes * 2 + 16 * 1024,
+    ...(request.signal ? { signal: request.signal } : {}),
+  });
+  if (result.killed || request.signal?.aborted)
+    throw new XcbError("cancelled", "cancelled");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    throw new XcbError(`xcb generate returned no JSON (exit ${result.code})`);
+  }
+  if (!isRecord(parsed))
+    throw new XcbError("xcb generate returned a non-object");
+  if (
+    parsed.status === "completed" &&
+    result.code === 0 &&
+    typeof parsed.text === "string"
+  )
+    return parsed.text.slice(0, maxOutputBytes);
+  const code =
+    typeof parsed.code === "string" && FAILURE_CODES.has(parsed.code)
+      ? parsed.code
+      : "provider_error";
+  const requestId =
+    typeof parsed.requestId === "string" &&
+    /^[A-Za-z0-9_-]{1,80}$/.test(parsed.requestId)
+      ? ` (${parsed.requestId})`
+      : "";
+  throw new XcbError(`xcb generate failed: ${code}${requestId}`, code);
+}
+
+/**
+ * Find the first balanced top-level JSON object in `text`, honouring strings
+ * and escapes. Only the first `maxBytes` characters are scanned.
+ */
+export function extractFirstJsonObject(
+  text: string,
+  maxChars = 64 * 1024,
+): string | undefined {
+  const scan = text.slice(0, maxChars);
+  let start = scan.indexOf("{");
+  while (start >= 0) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < scan.length; index += 1) {
+      const char = scan[index]!;
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (char === "\\") escaped = true;
+        else if (char === '"') inString = false;
+        continue;
+      }
+      if (char === '"') inString = true;
+      else if (char === "{") depth += 1;
+      else if (char === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          const candidate = scan.slice(start, index + 1);
+          try {
+            JSON.parse(candidate);
+            return candidate;
+          } catch {
+            break;
+          }
+        }
+      }
+    }
+    start = scan.indexOf("{", start + 1);
+  }
+  return undefined;
+}
+
+export type TextOp = Readonly<{ tool: string; args: Record<string, unknown> }>;
+export type TextReply = Readonly<{
+  ops: readonly TextOp[];
+  say?: string;
+  done: boolean;
+}>;
+export const TEXT_REPLY_LIMITS = Object.freeze({
+  maxChars: 64 * 1024,
+  maxOps: 16,
+  maxSayChars: 400,
+});
+
+/** Parse a model reply into `{ops, say, done}` or throw with a short diagnostic. */
+export function parseTextReply(text: string): TextReply {
+  const json = extractFirstJsonObject(text, TEXT_REPLY_LIMITS.maxChars);
+  if (json === undefined)
+    throw new XcbError(
+      text.length > TEXT_REPLY_LIMITS.maxChars
+        ? "reply exceeded 64 KiB without a complete JSON object"
+        : "reply did not contain a JSON object",
+      "invalid_reply",
+    );
+  const value: unknown = JSON.parse(json);
+  if (!isRecord(value))
+    throw new XcbError("reply was not a JSON object", "invalid_reply");
+  const rawOps = value.ops ?? [];
+  if (!Array.isArray(rawOps))
+    throw new XcbError("ops must be an array", "invalid_reply");
+  if (rawOps.length > TEXT_REPLY_LIMITS.maxOps)
+    throw new XcbError(
+      `at most ${TEXT_REPLY_LIMITS.maxOps} ops per reply`,
+      "invalid_reply",
+    );
+  const ops: TextOp[] = rawOps.map((op, index) => {
+    if (
+      !isRecord(op) ||
+      typeof op.tool !== "string" ||
+      op.tool.length === 0 ||
+      op.tool.length > 64
+    )
+      throw new XcbError(`ops[${index}] needs a tool name`, "invalid_reply");
+    const args = op.args ?? {};
+    if (!isRecord(args))
+      throw new XcbError(
+        `ops[${index}].args must be an object`,
+        "invalid_reply",
+      );
+    return { tool: op.tool, args };
+  });
+  const say =
+    typeof value.say === "string" && value.say.trim()
+      ? value.say.trim().slice(0, TEXT_REPLY_LIMITS.maxSayChars)
+      : undefined;
+  return { ops, done: value.done !== false, ...(say ? { say } : {}) };
+}
+
+/** A friendly short label: `claude/sonnet/low` → `claude/sonnet`. */
+export function shortModelLabel(key: string): string {
+  return key.split("/").slice(0, 2).join("/");
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : min;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/audio/clock.ts

@@ -0,0 +1,68 @@
+export class TransportClock {
+  private startedAtMs: number | undefined;
+  private pausedBeat = 0;
+  private bpm: number;
+
+  constructor(bpm = 120) {
+    this.bpm = bpm;
+  }
+
+  play(nowMs = performance.now()): void {
+    if (this.startedAtMs === undefined)
+      this.startedAtMs = nowMs - this.beatToMs(this.pausedBeat);
+  }
+
+  pause(nowMs = performance.now()): void {
+    this.pausedBeat = this.beatAt(nowMs);
+    this.startedAtMs = undefined;
+  }
+
+  toggle(nowMs = performance.now()): void {
+    if (this.startedAtMs === undefined) this.play(nowMs);
+    else this.pause(nowMs);
+  }
+
+  beatAt(nowMs = performance.now()): number {
+    if (this.startedAtMs === undefined) return this.pausedBeat;
+    return Math.max(0, (nowMs - this.startedAtMs) / this.beatToMs(1));
+  }
+
+  get playing(): boolean {
+    return this.startedAtMs !== undefined;
+  }
+
+  setTempo(bpm: number, nowMs = performance.now()): void {
+    if (!Number.isFinite(bpm) || bpm <= 0) return;
+    const beat = this.beatAt(nowMs);
+    this.bpm = bpm;
+    if (this.startedAtMs !== undefined)
+      this.startedAtMs = nowMs - this.beatToMs(beat);
+    else this.pausedBeat = beat;
+  }
+
+  /** Converge to a timestamped transport event from another TUI process. */
+  sync(
+    beat: number,
+    playing: boolean,
+    eventAtMs = Date.now(),
+    nowWallMs = Date.now(),
+    nowMonotonicMs = performance.now(),
+  ): void {
+    if (!Number.isFinite(beat) || beat < 0) return;
+    if (!Number.isFinite(eventAtMs) || !Number.isFinite(nowWallMs)) return;
+    const elapsed = playing
+      ? Math.max(0, nowWallMs - eventAtMs) / this.beatToMs(1)
+      : 0;
+    const currentBeat = beat + elapsed;
+    if (playing) {
+      this.startedAtMs = nowMonotonicMs - this.beatToMs(currentBeat);
+    } else {
+      this.pausedBeat = currentBeat;
+      this.startedAtMs = undefined;
+    }
+  }
+
+  private beatToMs(beats: number): number {
+    return (beats * 60_000) / this.bpm;
+  }
+}