@hraness/dawg 0.2.0 → 0.4.0

package/src/agent/xcb-agent.ts

@@ -1,10 +1,14 @@
 import { compositionBrief } from "./brief.ts";
+import { CHORD_PROCESS } from "../../core/chords.ts";
 import {
   AGENT_LIMITS,
-  AgentTimeoutError,
+  MEDIA_PROMPT,
   classifyAgentError,
   executeCall,
+  hostProjectOutline,
   tighten,
+  turnDeadline,
+  WORKSPACE_PROMPT,
   type AgentBudget,
   type AgentEvent,
   type AgentHost,
@@ -41,11 +45,19 @@ export const TEXT_AGENT_SYSTEM_PROMPT = [
   "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.",
+  'For drums, create a track with instrument "kit" and prefer set_rhythm (Euclidean rows: pulses over steps, rotate, repeats for rolls, accent, probability, swing) so the beat stays editable as parameters; for a genre groove start from apply_drum_pattern (list_drum_patterns) and pick a sound with set_drum_kit; use add_drums only for one-off fills. Drum pitches select voices, so do not use add_notes for beats.',
+  CHORD_PROCESS,
+  "Synth voices: set_synth shapes a synth track with Strudel params (ADSR, lpf/lpenv filter envelopes, fm/fmh, supersaw unison/detune, vib, penv, noise; z_* ZzFX sounds take slide/pitchJump/lfo/zcrush…) or a preset (pad lead pluck bass keys bell…).",
+  "Sampler voices: set_sample sets Strudel sample controls per voice (begin end speed unit loop loopBegin loopEnd clip/legato fit loopAt accelerate squiz cut); splice = slices with fit.",
+  "Effects (set_fx; set_effects and set_automation): the brief's effects list is the fixed chain order with each effect's simple params. set_fx turns an effect on with good defaults, loads a preset or sets params by dawg or Strudel name. Lanes: volume, pan, filter, resonance, delay-feedback, delay-mix, wt and <effect>-<param> (e.g. autofilter-cutoff).",
+  "Previewing: preview_sound renders a track, or candidate sound tool calls (changes: [{tool, args}]), without committing, returns loudness, brightness and a comparison, and plays it once in the user's window. Use it when choosing between sounds (tables, presets, effect amounts), say how it sounds, then commit with the normal tools.",
+  "Wavetable synth: set_wavetable picks a table (built-ins offline, Strudel wt_ sets fetched once) and scans it by position wt.",
   '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 +112,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 +126,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 +149,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 +220,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 +263,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/audition.ts

@@ -0,0 +1,93 @@
+/**
+ * Audition: a short phrase of one track (or some of its pitches) rendered
+ * through the offline renderer, as a live voice the engine can mix over
+ * silence. The Euclidean editor plays the edited voice's lane once after
+ * every change, and the pattern picker previews a pattern before it lands.
+ *
+ * Like `live.ts` this only builds a smaller score; the renderer is shared,
+ * so an audition sounds exactly like the loop.
+ */
+import {
+  SCORE_LIMITS,
+  TrackScore,
+  type Note,
+  type Track,
+} from "../../core/score.ts";
+import type { LiveNotePcm } from "./live.ts";
+import type { SampleBank } from "./samples.ts";
+import { RENDER_CHANNELS, renderScorePcm } from "./wav.ts";
+
+export type AuditionRequest = Readonly<{
+  score: TrackScore;
+  trackId: string;
+  /** Only these pitches (one drum voice); all of the track's notes when absent. */
+  pitches?: ReadonlySet<number>;
+  /** Bars rendered from the loop start (default 1, at most the loop). */
+  bars?: number;
+  sampleRate: number;
+  samples?: SampleBank;
+}>;
+
+/** Longest audition, so a slow tempo cannot hold a voice for long. */
+export const MAX_AUDITION_SECONDS = 6;
+
+export function renderAudition(
+  request: AuditionRequest,
+): LiveNotePcm | undefined {
+  const { score } = request;
+  const track = score.tracks.find(
+    (candidate) => candidate.id === request.trackId,
+  );
+  if (!track) return undefined;
+  const secondsPerBar = (score.beatsPerBar * 60) / score.tempoBpm;
+  const bars = Math.max(
+    1,
+    Math.min(
+      score.bars,
+      request.bars ?? 1,
+      Math.floor(MAX_AUDITION_SECONDS / secondsPerBar) || 1,
+    ),
+  );
+  const endTick = bars * score.beatsPerBar * score.ticksPerBeat;
+  const notes: Note[] = score.notes.filter(
+    (note) =>
+      note.trackId === track.id &&
+      note.startTick < endTick &&
+      (!request.pitches || request.pitches.has(note.pitch)),
+  );
+  if (notes.length === 0) return undefined;
+  const single = new TrackScore({
+    tempoBpm: score.tempoBpm,
+    beatsPerBar: score.beatsPerBar,
+    bars,
+    ticksPerBeat: score.ticksPerBeat,
+    tracks: [auditionTrack(track)],
+    notes: notes.map((note) => ({
+      ...note,
+      durationTicks: Math.max(
+        1,
+        Math.min(
+          note.durationTicks,
+          endTick - note.startTick,
+          SCORE_LIMITS.maxTick,
+        ),
+      ),
+    })),
+  });
+  const audio = renderScorePcm(single, {
+    sampleRate: request.sampleRate,
+    maxSeconds: MAX_AUDITION_SECONDS + 4,
+    ...(request.samples ? { samples: request.samples } : {}),
+  });
+  let last = audio.pcm.length - 1;
+  while (last >= 0 && audio.pcm[last] === 0) last -= 1;
+  const frames = Math.ceil((last + 1) / RENDER_CHANNELS);
+  if (frames === 0) return undefined;
+  return { pcm: audio.pcm.subarray(0, frames * RENDER_CHANNELS), frames };
+}
+
+/** Audible regardless of mute and solo; the generator rows are not needed. */
+function auditionTrack(track: Track): Track {
+  const { solo: _solo, rhythm: _rhythm, ...rest } = track;
+  return { ...rest, muted: false };
+}

package/src/audio/cache.ts

@@ -0,0 +1,160 @@
+/**
+ * Disk cache budgets and LRU pruning for pack downloads and decoded assets.
+ *
+ * Two caches hold audio on disk:
+ *
+ * - raw pack files, `~/.cache/dawg/packs/files/<sha256(url)>.bin`, shared by
+ *   every project (default cap `DEFAULT_PACKS_CACHE_BYTES`, env
+ *   `DAWG_PACKS_CACHE_MAX`);
+ * - decoded PCM, `<project>/.dawg/assets/<sha256>.pcm`, per project (default
+ *   cap `DEFAULT_ASSETS_CACHE_BYTES`, env `DAWG_ASSETS_CACHE_MAX`).
+ *
+ * Both evict least recently used files first (hits refresh the mtime) and
+ * never evict a protected file: the ones the open project pins. An evicted
+ * pack file is fetched again by its pinned URL and checked against its
+ * pinned sha256, so eviction only ever costs a download.
+ */
+import { readdir, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { SCORE_LIMITS } from "../../core/score.ts";
+
+const MiB = 1024 * 1024;
+const GiB = 1024 * MiB;
+
+/**
+ * Raw pack downloads. 2 GiB holds every file a typical user touches across
+ * the built-in packs (a whole drum-machine bank is a few MiB, a GM
+ * instrument 1–4 MiB of MP3, a uzu wavetable 1–2 MiB) with room to spare,
+ * and stays small next to a browser cache on a laptop disk.
+ */
+export const DEFAULT_PACKS_CACHE_BYTES = 2 * GiB;
+/**
+ * Decoded float32 PCM per project. Decoding grows audio 2× (16-bit WAV) to
+ * ~10× (MP3), so 1 GiB is about 100 minutes of mono 44.1 kHz audio: far
+ * more than a project plays, while a few projects cannot fill a disk.
+ */
+export const DEFAULT_ASSETS_CACHE_BYTES = 1 * GiB;
+/** Decoded samples kept in memory by one `SampleLibrary`. */
+export const DEFAULT_MEMORY_CACHE_BYTES = SCORE_LIMITS.maxSampleCacheBytes;
+
+const SIZE =
+  /^\s*([0-9]+(?:\.[0-9]+)?)\s*(b|k|kb|kib|m|mb|mib|g|gb|gib|t|tb|tib)?\s*$/i;
+
+/**
+ * Bytes from `"2GiB"`, `"512M"`, `"1.5g"`, `"1048576"` (units are binary);
+ * undefined when malformed or negative.
+ */
+export function parseByteSize(value: string): number | undefined {
+  const match = SIZE.exec(value);
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  const unit = (match[2] ?? "b").toLowerCase()[0]!;
+  const scale =
+    unit === "k"
+      ? 1024
+      : unit === "m"
+        ? MiB
+        : unit === "g"
+          ? GiB
+          : unit === "t"
+            ? 1024 * GiB
+            : 1;
+  const bytes = Math.floor(amount * scale);
+  return Number.isFinite(bytes) && bytes >= 0 ? bytes : undefined;
+}
+
+function fromEnv(
+  name: string,
+  fallback: number,
+  env: NodeJS.ProcessEnv,
+): number {
+  const raw = env[name];
+  if (raw === undefined || raw.trim() === "") return fallback;
+  return parseByteSize(raw) ?? fallback;
+}
+
+/** Raw pack file cap: `DAWG_PACKS_CACHE_MAX` or 2 GiB. */
+export function packsCacheMax(env: NodeJS.ProcessEnv = process.env): number {
+  return fromEnv("DAWG_PACKS_CACHE_MAX", DEFAULT_PACKS_CACHE_BYTES, env);
+}
+
+/** Decoded asset cap: `DAWG_ASSETS_CACHE_MAX` or 1 GiB. */
+export function assetsCacheMax(env: NodeJS.ProcessEnv = process.env): number {
+  return fromEnv("DAWG_ASSETS_CACHE_MAX", DEFAULT_ASSETS_CACHE_BYTES, env);
+}
+
+export type CacheUsage = Readonly<{ files: number; bytes: number }>;
+
+type Entry = { name: string; path: string; bytes: number; used: number };
+
+async function entries(dir: string, pattern: RegExp): Promise<Entry[]> {
+  const names = await readdir(dir).catch(() => [] as string[]);
+  const out: Entry[] = [];
+  for (const name of names) {
+    if (!pattern.test(name)) continue;
+    const path = join(dir, name);
+    const info = await stat(path).catch(() => undefined);
+    if (info?.isFile())
+      out.push({ name, path, bytes: info.size, used: info.mtimeMs });
+  }
+  return out;
+}
+
+/** Files and bytes of the cache entries in `dir` matching `pattern`. */
+export async function cacheUsage(
+  dir: string,
+  pattern: RegExp,
+): Promise<CacheUsage> {
+  const list = await entries(dir, pattern);
+  return {
+    files: list.length,
+    bytes: list.reduce((sum, entry) => sum + entry.bytes, 0),
+  };
+}
+
+export type PruneResult = Readonly<{
+  removed: number;
+  freed: number;
+  /** Bytes left, protected files included. */
+  bytes: number;
+}>;
+
+/**
+ * Deletes least recently used entries until `dir` holds at most `maxBytes`.
+ * `keep(name)` protects an entry (the open project's pins, the file being
+ * written); protected entries count toward the total but are never removed,
+ * so a project larger than the cap keeps everything it uses.
+ */
+export async function pruneLru(
+  dir: string,
+  pattern: RegExp,
+  maxBytes: number,
+  keep: (name: string) => boolean = () => false,
+): Promise<PruneResult> {
+  const list = await entries(dir, pattern);
+  let total = list.reduce((sum, entry) => sum + entry.bytes, 0);
+  list.sort((a, b) => a.used - b.used || a.name.localeCompare(b.name));
+  let removed = 0;
+  let freed = 0;
+  for (const entry of list) {
+    if (total <= maxBytes) break;
+    if (keep(entry.name)) continue;
+    try {
+      await unlink(entry.path);
+    } catch {
+      continue;
+    }
+    total -= entry.bytes;
+    freed += entry.bytes;
+    removed += 1;
+  }
+  return { removed, freed, bytes: total };
+}
+
+/** `1.5 GiB`, `320 MiB`, `12 KiB`. */
+export function formatBytes(bytes: number): string {
+  if (bytes >= GiB) return `${Math.round((bytes / GiB) * 10) / 10} GiB`;
+  if (bytes >= MiB) return `${Math.round((bytes / MiB) * 10) / 10} MiB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KiB`;
+  return `${bytes} B`;
+}