@hraness/dawg 0.2.0 → 0.3.0

package/src/agent/xcb-agent.ts

@@ -1,10 +1,13 @@
 import { compositionBrief } from "./brief.ts";
 import {
   AGENT_LIMITS,
-  AgentTimeoutError,
+  MEDIA_PROMPT,
   classifyAgentError,
   executeCall,
+  hostProjectOutline,
   tighten,
+  turnDeadline,
+  WORKSPACE_PROMPT,
   type AgentBudget,
   type AgentEvent,
   type AgentHost,
@@ -46,6 +49,9 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   '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.",
+  WORKSPACE_PROMPT,
+  MEDIA_PROMPT,
+  'Media tools return their outputs in the op result; send them alone with "done":false and chain on the result.',
 ].join(" ");
 
 /** Render the tool registry as a compact op catalog for a text-only model. */
@@ -100,14 +106,10 @@ export async function runTextAgentTurn(
     ((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 deadline = turnDeadline(limits.timeoutMs);
   const signal = options.signal
-    ? AbortSignal.any([options.signal, timeout.signal])
-    : timeout.signal;
+    ? AbortSignal.any([options.signal, deadline.signal])
+    : deadline.signal;
 
   let applied = 0;
   let rejected = 0;
@@ -118,7 +120,7 @@ export async function runTextAgentTurn(
   let feedback = "";
   const currentRevision = () => options.host.snapshot().revision;
   const finish = (result: AgentTurnResult): AgentTurnResult => {
-    clearTimeout(timer);
+    deadline.clear();
     emit(result);
     return result;
   };
@@ -141,10 +143,15 @@ export async function runTextAgentTurn(
       const remainingBytes = limits.maxResponseBytes - bytesUsed;
       if (remainingBytes <= 0)
         throw new SseBudgetError(limits.maxResponseBytes);
+      const snapshot = options.host.snapshot();
+      const brief = compositionBrief({
+        ...snapshot,
+        project: await hostProjectOutline(options.host, snapshot),
+      });
       const prompt = [
         TEXT_AGENT_SYSTEM_PROMPT,
         `Tools:\n${catalog}`,
-        `Composition brief (JSON): ${compositionBrief(options.host.snapshot())}`,
+        `Composition brief (JSON): ${brief}`,
         `User request: ${options.prompt.slice(0, MAX_PROMPT_CHARS)}`,
         ...steering.map((text) => `Steering from the user mid-turn: ${text}`),
         feedback
@@ -207,7 +214,15 @@ export async function runTextAgentTurn(
         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 },
+          {
+            tools,
+            host: options.host,
+            newNoteId,
+            signal,
+            suspendTimeout: deadline.suspend,
+            onProgress: (line) =>
+              emit({ type: "tool-progress", callId, name: op.tool, line }),
+          },
         );
         if (outcome.ok) {
           applied += outcome.mutated ? 1 : 0;
@@ -242,6 +257,6 @@ export async function runTextAgentTurn(
       revision: currentRevision(),
     });
   } finally {
-    clearTimeout(timer);
+    deadline.clear();
   }
 }

package/src/agent/xcb.ts

@@ -40,7 +40,11 @@ export class XcbError extends Error {
   }
 }
 
-export type XcbModel = Readonly<{ key: string; label: string }>;
+export type XcbModel = Readonly<{
+  key: string;
+  label: string;
+  admission?: XcbAdmission;
+}>;
 export type XcbAccount = Readonly<{
   id: string;
   label: string;
@@ -50,11 +54,11 @@ export type XcbAccount = Readonly<{
   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.
+   * xcb 0.20+: the best admission among the account's models. `pending`
+   * means the first call checks it (up to ~60 s slower). Absent when the
+   * account is unavailable or on older xcb builds.
    */
-  admission?: "pending" | "admitted" | "denied" | undefined;
+  admission?: XcbAdmission | undefined;
 }>;
 export type XcbCapabilities = Readonly<{
   supported: boolean;
@@ -77,17 +81,59 @@ function shortString(value: unknown, max: number, fallback = ""): string {
     : fallback;
 }
 
-/** Parse `xcb --json generate --capabilities` output from `unknown`. */
-const ADMISSION_STATES = new Set(["pending", "admitted", "denied"]);
+/**
+ * xcb 0.20+ admission (docs/application-api.md): `pending` means the next
+ * `generate` checks the model first and is slower but usable; `admitted` and
+ * `qualified` are checked. It is `null` whenever the account has a `reason`,
+ * so admission alone never makes an account usable: `available` does.
+ */
+export type XcbAdmission = "pending" | "admitted" | "qualified";
+const ADMISSION_STATES = new Set<string>(["pending", "admitted", "qualified"]);
 
-/** `"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"])
+function admissionState(value: unknown): XcbAdmission | null | undefined {
+  if (value === null) return null;
+  return typeof value === "string" && ADMISSION_STATES.has(value)
+    ? (value as XcbAdmission)
     : undefined;
 }
 
+/** The first xcb release with automatic application admission. */
+export const XCB_MIN_VERSION = "0.20.0";
+
+/**
+ * What a capability `reason` means for the user, with the next step. Unknown
+ * reasons stay unavailable with the raw code.
+ */
+export function describeReason(reason: string | null): string {
+  switch (reason) {
+    case null:
+      return "ready";
+    case "application_disabled":
+      return "app access turned off; run `xcb application enable`";
+    case "authentication_required":
+      return "signed out; run `xcb accounts login <account>`";
+    case "not_connected":
+      return "not signed in";
+    case "account_disabled":
+      return "disabled in xcb";
+    case "account_busy":
+      return "busy (run limit reached); try again shortly";
+    case "runtime_unavailable":
+      return "provider runtime unavailable; run `xcb doctor`";
+    case "sandbox_unproven":
+      return "xcb could not confirm the provider sandbox; run `xcb doctor`";
+    case "admission_failed":
+      return "automatic check failed; retry after 15 minutes";
+    case "models_unavailable":
+      return "no models listed; run `xcb accounts refresh <account>`";
+    case "application_not_qualified":
+      return "needs xcb 0.20.0+ (upgrade xcb)";
+    default:
+      return `unavailable (${reason})`;
+  }
+}
+
+/** Parse `xcb --json generate --capabilities` output from `unknown`. */
 export function parseCapabilities(value: unknown): XcbCapabilities {
   if (!isRecord(value) || value.version !== 1)
     throw new XcbError("xcb capabilities were not a version-1 object");
@@ -113,9 +159,14 @@ export function parseCapabilities(value: unknown): XcbCapabilities {
         !MODEL_PATTERN.test(model.key)
       )
         continue;
+      // xcb 0.20+ lists every model with an admission; `null` means this
+      // account cannot use it. Older builds omit the field (all listed usable).
+      const admission = admissionState(model.admission);
+      if (admission === null) continue;
       models.push({
         key: model.key,
         label: shortString(model.label, 64, model.key) || model.key,
+        ...(admission ? { admission } : {}),
       });
     }
     const label =
@@ -123,20 +174,18 @@ export function parseCapabilities(value: unknown): XcbCapabilities {
       shortString(row.name, 64) ||
       shortString(row.email, 64) ||
       row.id;
+    const reason =
+      typeof row.reason === "string" ? shortString(row.reason, 64) : null;
     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"),
+      // Usable iff xcb says so and it lists a model to call.
+      available: row.available === true && reason === null && models.length > 0,
       ...(admission ? { admission } : {}),
       connected: row.connected === true,
-      reason:
-        typeof row.reason === "string" ? shortString(row.reason, 64) : null,
+      reason,
       models,
     });
   }
@@ -171,6 +220,58 @@ export async function readCapabilities(
   return parseCapabilities(parsed);
 }
 
+/** One row of `xcb --json accounts`: sign-in state, no secrets. */
+export type XcbAccountRow = Readonly<{
+  id: string;
+  label: string;
+  provider: string;
+  enabled: boolean;
+  authenticationRequired: boolean;
+}>;
+
+/** Parse `xcb --json accounts` from `unknown`; unknown rows are skipped. */
+export function parseAccountRows(value: unknown): XcbAccountRow[] {
+  if (!isRecord(value) || !Array.isArray(value.accounts)) return [];
+  const rows: XcbAccountRow[] = [];
+  for (const row of value.accounts.slice(0, XCB_LIMITS.maxAccounts)) {
+    if (
+      !isRecord(row) ||
+      typeof row.id !== "string" ||
+      !ID_PATTERN.test(row.id)
+    )
+      continue;
+    rows.push({
+      id: row.id,
+      label: shortString(row.name, 64) || shortString(row.email, 64) || row.id,
+      provider: shortString(row.provider, 32, "unknown") || "unknown",
+      enabled: row.enabled !== false,
+      authenticationRequired: row.authenticationRequired === true,
+    });
+  }
+  return rows;
+}
+
+/** `xcb --json accounts`, read-only. Empty on any failure. */
+export async function readAccountRows(
+  bin: string,
+  runner: CommandRunner,
+  signal?: AbortSignal,
+): Promise<XcbAccountRow[]> {
+  const result = await runner
+    .run(bin, ["--json", "accounts"], {
+      timeoutMs: 15_000,
+      maxOutputBytes: XCB_LIMITS.maxCapabilityBytes,
+      ...(signal ? { signal } : {}),
+    })
+    .catch(() => undefined);
+  if (!result || result.code !== 0) return [];
+  try {
+    return parseAccountRows(JSON.parse(result.stdout));
+  } catch {
+    return [];
+  }
+}
+
 export type XcbGenerateRequest = Readonly<{
   bin: string;
   runner: CommandRunner;
@@ -182,6 +283,116 @@ export type XcbGenerateRequest = Readonly<{
   signal?: AbortSignal;
 }>;
 
+/** Extra child-process time for xcb's first-call admission check. */
+export const XCB_ADMISSION_GRACE_MS = 75_000;
+/** Backoff before retrying a `busy` result (two first calls on one account). */
+export const XCB_BUSY_BACKOFF_MS = Object.freeze([2_000, 6_000]);
+
+/**
+ * `xcbGenerate`, retried with backoff while xcb answers `busy` (e.g. the
+ * account is mid-admission for another caller). Other failures pass through.
+ */
+export async function xcbGenerateWithRetry(
+  request: XcbGenerateRequest & {
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  },
+): Promise<string> {
+  const sleep = request.sleep ?? abortableSleep;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await xcbGenerate(request);
+    } catch (error) {
+      const delay = XCB_BUSY_BACKOFF_MS[attempt];
+      if (
+        !(error instanceof XcbError) ||
+        error.code !== "busy" ||
+        delay === undefined ||
+        request.signal?.aborted
+      )
+        throw error;
+      await sleep(delay, request.signal);
+      if (request.signal?.aborted) throw new XcbError("cancelled", "cancelled");
+    }
+  }
+}
+
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+/**
+ * `xcb accounts refresh <id>` for accounts whose catalog is empty
+ * (`models_unavailable`): about 5 s, no provider turn. Each account is
+ * refreshed at most once per process. Returns the ids that succeeded.
+ */
+const refreshedAccounts = new Set<string>();
+export async function refreshAccounts(
+  bin: string,
+  runner: CommandRunner,
+  ids: readonly string[],
+  options: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<string[]> {
+  const todo = ids.filter(
+    (id) => ID_PATTERN.test(id) && !refreshedAccounts.has(id),
+  );
+  for (const id of todo) refreshedAccounts.add(id);
+  const results = await Promise.all(
+    todo.map((id) =>
+      runner
+        .run(bin, ["accounts", "refresh", id], {
+          timeoutMs: options.timeoutMs ?? 10_000,
+          maxOutputBytes: 64 * 1024,
+          ...(options.signal ? { signal: options.signal } : {}),
+        })
+        .then((result) => (result.code === 0 ? id : undefined))
+        .catch(() => undefined),
+    ),
+  );
+  return results.filter((id): id is string => id !== undefined);
+}
+
+/** Test hook: forget which accounts this process refreshed. */
+export function resetRefreshedAccounts(): void {
+  refreshedAccounts.clear();
+}
+
+/** `xcb --version` → `0.20.0`, or undefined. */
+export async function readXcbVersion(
+  bin: string,
+  runner: CommandRunner,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  const result = await runner
+    .run(bin, ["--version"], {
+      timeoutMs: 5_000,
+      maxOutputBytes: 4096,
+      ...(signal ? { signal } : {}),
+    })
+    .catch(() => undefined);
+  if (!result || result.code !== 0) return undefined;
+  return /(\d+\.\d+\.\d+)/.exec(result.stdout)?.[1];
+}
+
+/** True when `version` is at least `min` (plain x.y.z). */
+export function versionAtLeast(version: string, min: string): boolean {
+  const a = version.split(".").map(Number);
+  const b = min.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const left = a[index] ?? 0;
+    const right = b[index] ?? 0;
+    if (left !== right) return left > right;
+  }
+  return true;
+}
+
 /**
  * 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).
@@ -222,8 +433,9 @@ export async function xcbGenerate(
   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,
+    // xcb enforces its own deadline; this backstop also covers the automatic
+    // admission check on a binding's first call (up to ~60 s on top).
+    timeoutMs: timeoutMs + XCB_ADMISSION_GRACE_MS,
     maxOutputBytes: maxOutputBytes * 2 + 16 * 1024,
     ...(request.signal ? { signal: request.signal } : {}),
   });

package/src/audio/click.ts

@@ -0,0 +1,125 @@
+/**
+ * The click track (metronome): an accented downbeat, a beat click and a
+ * lighter subdivision click at the transport tempo and time signature.
+ *
+ * The click is a monitoring bus only. The engine mixes it into the live
+ * stream; it is never part of a loop render, `dawg render` or an export, and
+ * nothing here touches the score.
+ */
+
+export type ClickLevel = "accent" | "beat" | "sub";
+
+export type ClickSettings = Readonly<{
+  /** 0..1 output level. */
+  volume: number;
+  beatsPerBar: number;
+  /** Clicks per beat: 1 = quarters, 2 = eighths, 4 = sixteenths. */
+  subdivision: number;
+}>;
+
+export const DEFAULT_CLICK_VOLUME = 0.6;
+export const MAX_SUBDIVISION = 4;
+
+/** One click due inside a block of stream frames. */
+export type ClickEvent = Readonly<{
+  /** Frame offset inside the block. */
+  offset: number;
+  level: ClickLevel;
+  /** Absolute step (beat × subdivision); negative during a count-in. */
+  step: number;
+}>;
+
+/** Level of absolute step `step` (beat × subdivision). */
+export function clickLevel(
+  step: number,
+  beatsPerBar: number,
+  subdivision: number,
+): ClickLevel {
+  const perBar = Math.max(1, beatsPerBar) * Math.max(1, subdivision);
+  const inBar = ((step % perBar) + perBar) % perBar;
+  if (inBar === 0) return "accent";
+  return inBar % Math.max(1, subdivision) === 0 ? "beat" : "sub";
+}
+
+/**
+ * Clicks whose time falls in the half-open beat span [fromBeat, toBeat)
+ * covered by `frames` stream frames. Contiguous blocks never repeat or skip
+ * a click, and a jump (seek, loop wrap) never fires a stray mid-beat click.
+ */
+export function clicksIn(
+  fromBeat: number,
+  toBeat: number,
+  frames: number,
+  settings: Pick<ClickSettings, "beatsPerBar" | "subdivision">,
+): ClickEvent[] {
+  if (!(toBeat > fromBeat) || frames <= 0) return [];
+  const subdivision = Math.max(
+    1,
+    Math.min(MAX_SUBDIVISION, Math.round(settings.subdivision)),
+  );
+  const events: ClickEvent[] = [];
+  const span = toBeat - fromBeat;
+  // Half-open: a click exactly at `toBeat` belongs to the next block, whose
+  // `fromBeat` is computed identically, so it fires once.
+  const first = Math.ceil(fromBeat * subdivision) + 0;
+  for (let step = first; step / subdivision < toBeat; step += 1) {
+    const offset = Math.floor(
+      ((step / subdivision - fromBeat) / span) * frames,
+    );
+    if (offset < 0 || offset >= frames) continue;
+    events.push({
+      offset,
+      step,
+      level: clickLevel(step, settings.beatsPerBar, subdivision),
+    });
+    if (events.length > 64) break;
+  }
+  return events;
+}
+
+const CLICK_TONES: Readonly<
+  Record<ClickLevel, { hz: number; gain: number; ms: number }>
+> = Object.freeze({
+  accent: { hz: 1760, gain: 1, ms: 45 },
+  beat: { hz: 1320, gain: 0.7, ms: 35 },
+  sub: { hz: 990, gain: 0.35, ms: 25 },
+});
+
+/** Mono click waveforms (−1..1) for each level at `sampleRate`. */
+export function clickSounds(
+  sampleRate: number,
+): Readonly<Record<ClickLevel, Float32Array>> {
+  const make = (level: ClickLevel): Float32Array => {
+    const tone = CLICK_TONES[level];
+    const frames = Math.max(1, Math.round((tone.ms * sampleRate) / 1000));
+    const out = new Float32Array(frames);
+    const attack = Math.max(1, Math.round(0.001 * sampleRate));
+    for (let index = 0; index < frames; index += 1) {
+      const t = index / sampleRate;
+      const decay = Math.exp((-index / frames) * 6);
+      const env = Math.min(1, index / attack) * decay;
+      out[index] = Math.sin(2 * Math.PI * tone.hz * t) * env * tone.gain;
+    }
+    return out;
+  };
+  return { accent: make("accent"), beat: make("beat"), sub: make("sub") };
+}
+
+/** `/click on|off|<volume>` → settings change, or an error message. */
+export function parseClickArgument(
+  argument: string,
+  current: Readonly<{ on: boolean; volume: number }>,
+): { on: boolean; volume: number } | { error: string } {
+  const value = argument.trim().toLowerCase();
+  if (value === "" || value === "toggle")
+    return { on: !current.on, volume: current.volume };
+  if (value === "on") return { on: true, volume: current.volume };
+  if (value === "off") return { on: false, volume: current.volume };
+  const percent = value.endsWith("%");
+  const number = Number(percent ? value.slice(0, -1) : value);
+  if (!Number.isFinite(number) || number < 0)
+    return { error: "usage: /click on|off|<volume 0..1 or 0..100%>" };
+  const volume = percent || number > 1 ? number / 100 : number;
+  if (volume > 1) return { error: "click volume is 0..1 (or 0..100%)" };
+  return { on: volume > 0, volume };
+}