@hraness/dawg 0.6.1 → 0.8.0

package/src/agent/gateway.ts

@@ -1,4 +1,5 @@
-import { readSseData } from "./sse.ts";
+import { isProviderModelId } from "../auth/credentials.ts";
+import { readSseData, SseBudgetError } from "./sse.ts";
 
 /**
  * The two original model aliases. A model is either one of these or an exact
@@ -18,8 +19,6 @@ export const DEFAULT_MODEL_IDS: Readonly<Record<GatewayModel, string>> =
     "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 {
@@ -36,21 +35,22 @@ export function isGatewayModel(value: unknown): value is GatewayModel {
 export function resolveModelId(
   alias: string,
   overrides: Partial<Record<GatewayModel, string | undefined>> = {},
+  provider: ApiProvider = "gateway",
 ): string {
   if (!isGatewayModel(alias)) {
-    if (MODEL_ID_PATTERN.test(alias)) return alias;
+    if (isProviderModelId(alias, provider)) return alias;
     throw new Error(
       `unknown model "${alias.slice(0, 32)}"; use ${GATEWAY_MODELS.join(" or ")} or a vendor/model ID`,
     );
   }
   const id = overrides[alias] ?? DEFAULT_MODEL_IDS[alias];
-  if (!MODEL_ID_PATTERN.test(id))
+  if (!isProviderModelId(id, provider))
     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))
+function checkedModelId(id: string, provider: ApiProvider): string {
+  if (!isProviderModelId(id, provider))
     throw new Error("model ID must look like provider/model");
   return id;
 }
@@ -85,6 +85,11 @@ export type ChatStreamRequest = {
   modelId?: string;
   maxTokens?: number;
   maxResponseBytes: number;
+  /**
+   * A model ID to try once when every attempt on the main model failed
+   * before producing a byte (a 5xx, a header timeout, a stalled stream).
+   */
+  fallbackModelId?: string;
 };
 
 /** Normalized stream events; provider chunk shapes never leave this module. */
@@ -145,6 +150,12 @@ export const GATEWAY_RETRIES = 2;
 const RETRY_BASE_MS = 500;
 /** Response headers must arrive within this long, per attempt. */
 export const GATEWAY_HEADER_TIMEOUT_MS = 15_000;
+/**
+ * After headers, the first stream event must arrive within this long, per
+ * attempt. A provider that accepts the request and then sends nothing is
+ * retried like a header timeout: no byte has reached the caller yet.
+ */
+export const GATEWAY_FIRST_BYTE_TIMEOUT_MS = 20_000;
 
 export type GatewayRetryOptions = Readonly<{
   retries?: number;
@@ -174,6 +185,7 @@ export type ApiClientOptions = {
   fetcher?: GatewayFetcher;
   retry?: GatewayRetryOptions;
   headerTimeoutMs?: number;
+  firstByteTimeoutMs?: number;
 };
 
 /** The streaming tool-calling client for OpenRouter's OpenAI-compatible API. */
@@ -212,6 +224,8 @@ function createApiClient(
   const sleep = options.retry?.sleep ?? ((ms: number) => Bun.sleep(ms));
   const random = options.retry?.random ?? Math.random;
   const headerTimeoutMs = options.headerTimeoutMs ?? GATEWAY_HEADER_TIMEOUT_MS;
+  const firstByteTimeoutMs =
+    options.firstByteTimeoutMs ?? GATEWAY_FIRST_BYTE_TIMEOUT_MS;
   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,
@@ -222,50 +236,82 @@ function createApiClient(
 
   return {
     provider,
-    modelId: (model) => resolveModelId(model, overrides),
+    modelId: (model) => resolveModelId(model, overrides, provider),
     async *stream(request, signal) {
-      const model =
+      const primary =
         request.modelId !== undefined
-          ? checkedModelId(request.modelId)
-          : resolveModelId(request.model, overrides);
+          ? checkedModelId(request.modelId, provider)
+          : resolveModelId(request.model, overrides, provider);
+      const fallback =
+        request.fallbackModelId !== undefined &&
+        request.fallbackModelId !== primary
+          ? checkedModelId(request.fallbackModelId, provider)
+          : undefined;
       if (!apiKey)
         throw new GatewayError(
           provider === "openrouter"
-            ? "no OpenRouter key; run `dawg login openrouter` or set OPENROUTER_API_KEY"
-            : "no AI Gateway key; run `dawg login` or set AI_GATEWAY_API_KEY",
+            ? "no OpenRouter key; run `dawg model key openrouter` or set OPENROUTER_API_KEY"
+            : "no AI Gateway key; run `dawg model key` or set AI_GATEWAY_API_KEY",
         );
-      const body: Record<string, unknown> = {
-        model,
-        messages: request.messages,
-        stream: true,
-        // The final chunk then carries token usage (and OpenRouter's cost).
-        stream_options: { include_usage: true },
+      const encodeFor = (model: string): string => {
+        const body: Record<string, unknown> = {
+          model,
+          messages: withPromptCache(provider, model, request.messages),
+          stream: true,
+          // The final chunk then carries token usage (and OpenRouter's cost).
+          stream_options: { include_usage: true },
+        };
+        if (provider === "openrouter") body.usage = { include: true };
+        // The Gateway adds Anthropic cache breakpoints itself when asked; it
+        // documents the option as a no-op for implicitly caching providers.
+        else body.providerOptions = { gateway: { caching: "auto" } };
+        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);
+        return JSON.stringify(body);
       };
-      if (provider === "openrouter") body.usage = { include: 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 encoded = JSON.stringify(body);
+      let model = primary;
+      let encoded = encodeFor(model);
       // Retry only before any byte of a response has been consumed: a
       // network failure, a header-phase timeout, or 408/429/5xx. Once the
       // stream is flowing, a failure surfaces as-is (replaying could repeat
       // tool calls the model already made).
-      let response: Response | undefined;
+      let events: AsyncIterator<string> | undefined;
+      let first: IteratorResult<string> | undefined;
+      const streamOptions: { maxBytes: number; signal?: AbortSignal } = {
+        maxBytes: request.maxResponseBytes,
+      };
       for (let attempt = 0; ; attempt += 1) {
         if (signal?.aborted) throw abortError(signal);
-        const headerSignal = AbortSignal.any([
-          ...(signal === undefined ? [] : [signal]),
-          AbortSignal.timeout(headerTimeoutMs),
-        ]);
+        // The header budget bounds only the wait for response headers. A
+        // fetch signal also governs the body, so the timer is cleared as soon
+        // as headers arrive; after that only the caller's signal (the user or
+        // the turn budget) can cut the stream short.
+        const headerController = new AbortController();
+        const headerTimer = setTimeout(
+          () =>
+            headerController.abort(
+              new DOMException(
+                `${name} did not respond within ${headerTimeoutMs} ms`,
+                "TimeoutError",
+              ),
+            ),
+          headerTimeoutMs,
+        );
+        const headerSignal = headerController.signal;
+        const requestSignal =
+          signal === undefined
+            ? headerSignal
+            : AbortSignal.any([signal, headerSignal]);
         const init: RequestInit = {
           method: "POST",
           headers: {
@@ -275,57 +321,197 @@ function createApiClient(
             ...(provider === "openrouter" ? OPENROUTER_HEADERS : {}),
           },
           body: encoded,
-          signal: headerSignal,
+          signal: requestSignal,
         };
         let reason: string;
         try {
-          const candidate = await fetcher(`${baseUrl}/chat/completions`, init);
+          let candidate: Response;
+          try {
+            candidate = await fetcher(`${baseUrl}/chat/completions`, init);
+          } finally {
+            clearTimeout(headerTimer);
+          }
           if (candidate.ok) {
-            response = candidate;
-            break;
+            if (!candidate.body)
+              throw new GatewayError(`${name} returned an empty stream`);
+            // Wait for the first event under its own budget; the stall
+            // signal is never fired once it has arrived.
+            const stall = new AbortController();
+            const stallTimer = setTimeout(
+              () =>
+                stall.abort(
+                  new DOMException(
+                    `${name} sent nothing within ${firstByteTimeoutMs} ms`,
+                    "TimeoutError",
+                  ),
+                ),
+              firstByteTimeoutMs,
+            );
+            streamOptions.signal =
+              signal === undefined
+                ? stall.signal
+                : AbortSignal.any([signal, stall.signal]);
+            // Any byte, a keep-alive comment included, proves the provider
+            // is alive and disarms the stall timer.
+            const watched = candidate.body.pipeThrough(
+              new TransformStream<Uint8Array, Uint8Array>({
+                transform(chunk, controller) {
+                  clearTimeout(stallTimer);
+                  controller.enqueue(chunk);
+                },
+              }),
+            );
+            const iterator = readSseData(watched, streamOptions)[
+              Symbol.asyncIterator
+            ]();
+            try {
+              first = await iterator.next();
+              events = iterator;
+              break;
+            } catch (error) {
+              if (!stall.signal.aborted || signal?.aborted) throw error;
+              await iterator.return?.(undefined).catch(() => undefined);
+              if (attempt >= retries) {
+                if (fallback !== undefined && model !== fallback) {
+                  model = fallback;
+                  encoded = encodeFor(model);
+                  attempt = -1;
+                  yield {
+                    type: "activity",
+                    message: `falling back to ${model} (stalled)…`,
+                  };
+                  continue;
+                }
+                throw new GatewayError(
+                  `${name} sent nothing within ${firstByteTimeoutMs} ms`,
+                );
+              }
+              reason = "stalled";
+            } finally {
+              clearTimeout(stallTimer);
+            }
+            yield { type: "activity", message: `retrying (${reason})…` };
+            await sleep(
+              Math.round(retryBaseMs * 2 ** attempt * (0.5 + random())),
+            );
+            continue;
           }
           const detail = redact(await boundedErrorDetail(candidate));
           const error = new GatewayError(
             `${name} request failed (${candidate.status})${detail ? `: ${detail}` : ""}`,
             candidate.status,
           );
-          if (!retryableStatus(candidate.status) || attempt >= retries)
-            throw error;
+          if (!retryableStatus(candidate.status)) throw error;
+          if (attempt >= retries) {
+            if (fallback === undefined || model === fallback) throw error;
+            reason = String(candidate.status);
+            model = fallback;
+            encoded = encodeFor(model);
+            attempt = -1;
+            yield {
+              type: "activity",
+              message: `falling back to ${model} (${reason})…`,
+            };
+            continue;
+          }
           reason = String(candidate.status);
         } catch (error) {
-          if (error instanceof GatewayError) throw error;
+          if (error instanceof GatewayError || error instanceof SseBudgetError)
+            throw error;
           if (signal?.aborted) throw abortError(signal);
-          if (attempt >= retries)
-            throw new GatewayError(
+          if (attempt >= retries) {
+            const failure = new GatewayError(
               headerSignal.aborted
                 ? `${name} did not respond within ${headerTimeoutMs} ms`
                 : `${name} request failed: ${redact(error instanceof Error ? error.message : String(error))}`,
             );
+            if (fallback === undefined || model === fallback) throw failure;
+            model = fallback;
+            encoded = encodeFor(model);
+            attempt = -1;
+            yield {
+              type: "activity",
+              message: `falling back to ${model} (${headerSignal.aborted ? "timeout" : "network"})…`,
+            };
+            continue;
+          }
           reason = headerSignal.aborted ? "timeout" : "network";
         }
         yield { type: "activity", message: `retrying (${reason})…` };
         const backoff = retryBaseMs * 2 ** attempt;
         await sleep(Math.round(backoff * (0.5 + random())));
       }
-      if (!response.body)
-        throw new GatewayError(`${name} 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(`${name} sent a malformed stream chunk`);
+      try {
+        for (let next = first; !next.done; next = await events.next()) {
+          const data = next.value;
+          let chunk: unknown;
+          try {
+            chunk = JSON.parse(data);
+          } catch {
+            throw new GatewayError(`${name} sent a malformed stream chunk`);
+          }
+          yield* normalizeChunk(chunk, redact, name);
         }
-        yield* normalizeChunk(chunk, redact, name);
+      } catch (error) {
+        // A failure while the body streams (a reset connection, a transport
+        // timeout) is a provider failure, not an internal one. Budget errors
+        // and the caller's own abort keep their identity.
+        if (
+          error instanceof GatewayError ||
+          error instanceof SseBudgetError ||
+          signal?.aborted
+        )
+          throw error;
+        const timedOut =
+          error instanceof Error && error.name === "TimeoutError";
+        throw new GatewayError(
+          timedOut
+            ? `${name} stream timed out`
+            : `${name} stream failed: ${redact(error instanceof Error ? error.message : String(error)).slice(0, 300)}`,
+        );
       }
     },
   };
 }
 
+/**
+ * Mark the leading system message as a prompt-cache breakpoint for Anthropic
+ * models on OpenRouter and the AI Gateway. Anthropic caches tools, then
+ * system, then messages, so a breakpoint on the static system prompt caches
+ * the tool schemas and the prompt (about 27K tokens) across every step of a
+ * turn; the per-step brief follows it and stays uncached. The Gateway's
+ * `caching: "auto"` option alone cached nothing on its chat completions
+ * endpoint (bench/agent-eval measured 0 cached tokens over 4M), so the
+ * breakpoint is explicit there too. Other providers cache prefixes
+ * implicitly, so their messages go out unchanged.
+ */
+export function withPromptCache(
+  provider: ApiProvider,
+  model: string,
+  messages: readonly ChatMessage[],
+): readonly unknown[] {
+  const first = messages[0];
+  if (
+    !model.toLowerCase().startsWith("anthropic/") ||
+    first?.role !== "system" ||
+    first.content.length === 0
+  )
+    return messages;
+  return [
+    {
+      role: "system",
+      content: [
+        {
+          type: "text",
+          text: first.content,
+          cache_control: { type: "ephemeral" },
+        },
+      ],
+    },
+    ...messages.slice(1),
+  ];
+}
+
 function* normalizeChunk(
   chunk: unknown,
   redact: (text: string) => string,

package/src/agent/models.ts

@@ -1,6 +1,6 @@
 import { mkdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { writePrivateJson } from "../auth/credentials.ts";
+import { isProviderModelId, writePrivateJson } from "../auth/credentials.ts";
 import {
   DEFAULT_MODEL_IDS,
   GATEWAY_BASE_URL,
@@ -27,6 +27,11 @@ export type CatalogEntry = Readonly<{
   class: ModelClass;
   gateway?: string;
   openrouter?: string;
+  /**
+   * Alias of a model on another vendor to try once when this one fails
+   * before its first byte (repeated 5xx, header timeout, stalled stream).
+   */
+  fallback?: string;
 }>;
 
 /**
@@ -71,6 +76,14 @@ export const MODEL_CATALOG: readonly CatalogEntry[] = Object.freeze([
     gateway: "anthropic/claude-sonnet-5.5",
     openrouter: "anthropic/claude-sonnet-5.5",
   },
+  {
+    alias: "haiku-5.5",
+    label: "Claude Haiku 5.5",
+    class: "fast",
+    gateway: "anthropic/claude-haiku-5.5",
+    openrouter: "anthropic/claude-haiku-5.5",
+    fallback: "glm-5.3-flash",
+  },
   {
     alias: "haiku-4.5",
     label: "Claude Haiku 4.5",
@@ -120,6 +133,13 @@ export const MODEL_CATALOG: readonly CatalogEntry[] = Object.freeze([
     gateway: "zai/glm-5.3",
     openrouter: "z-ai/glm-5.3",
   },
+  {
+    alias: "glm-5.3-flash",
+    label: "GLM-5.3 Flash",
+    class: "fast",
+    gateway: "zai/glm-5.3-flash",
+    openrouter: "z-ai/glm-5.3-flash",
+  },
   {
     alias: "llama-4-maverick",
     label: "Llama 4 Maverick",
@@ -129,28 +149,48 @@ export const MODEL_CATALOG: readonly CatalogEntry[] = Object.freeze([
   },
 ]);
 
-const MODEL_ID_PATTERN =
-  /^[a-z0-9][a-z0-9-]{0,63}\/[a-z0-9][a-z0-9._-]{0,127}$/i;
-
 export function defaultModelId(provider: ApiProvider): string {
   return provider === "openrouter"
     ? MODEL_CATALOG[0]!.openrouter!
     : DEFAULT_MODEL_IDS["opus-5.5"];
 }
 
-/** An alias, a catalog label, or an exact `vendor/model` ID → the provider's ID. */
+/**
+ * `/model fast` picks this alias: the fastest model measured by
+ * bench/agent-eval that passes the non-style tasks about as well as the
+ * default (see docs/model-eval.md).
+ */
+export const FAST_MODEL_ALIAS = "haiku-5.5";
+
+/** The provider ID to fall back to for `id`, if its catalog row names one. */
+export function fallbackModelId(
+  provider: ApiProvider,
+  id: string,
+): string | undefined {
+  const row = MODEL_CATALOG.find((entry) => entry[provider] === id);
+  if (!row?.fallback) return undefined;
+  return MODEL_CATALOG.find((entry) => entry.alias === row.fallback)?.[
+    provider
+  ];
+}
+
+/**
+ * An alias (`fast` included), a catalog label, or an exact `vendor/model` ID
+ * → the provider's ID.
+ */
 export function resolveModelChoice(
   provider: ApiProvider,
   input: string,
 ): string | undefined {
   const value = input.trim();
   const lower = value.toLowerCase();
+  if (lower === "fast") return resolveModelChoice(provider, FAST_MODEL_ALIAS);
   const entry = MODEL_CATALOG.find(
     (row) => row.alias === lower || row.label.toLowerCase() === lower,
   );
   if (entry) return entry[provider];
   if (isGatewayModel(lower)) return DEFAULT_MODEL_IDS[lower];
-  return MODEL_ID_PATTERN.test(value) ? value : undefined;
+  return isProviderModelId(value, provider) ? value : undefined;
 }
 
 /** `anthropic/claude-opus-5.5` → `opus-5.5`; unknown IDs show as themselves. */
@@ -397,7 +437,7 @@ export function parseLiveCatalog(
     if (
       !isRecord(row) ||
       typeof row.id !== "string" ||
-      !MODEL_ID_PATTERN.test(row.id)
+      !isProviderModelId(row.id, provider)
     )
       continue;
     const pricing = isRecord(row.pricing) ? row.pricing : {};
@@ -486,17 +526,18 @@ export async function loadLiveCatalog(
  * and `chatTools()` serialized, plus `compositionBrief` of a 3-track, 48-note
  * loop; see models.test.ts, which keeps these in step with the code):
  *
- * - system prompt ≈ 7 KB, tool schemas ≈ 51 KB, brief ≈ 1.6 KB typical
- *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 59 KB ≈ 14,800 tokens
- *   per request at ~4 bytes per token;
+ * - system prompt ≈ 11 KB, tool schemas ≈ 70 KB, brief ≈ 1.6 KB typical
+ *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 83 KB per request. JSON
+ *   schemas tokenize at about 3 bytes per token: the agent eval
+ *   (bench/agent-eval) measured 26,500 input tokens per request on Claude;
  * - about 2 requests per prompt (tool calls, then a short reply), the second
  *   also carrying the first step's tool calls and results (≈ 0.6 KB);
  * - output ≈ 450 tokens of tool-call arguments and ≈ 150 of reply.
  *
- * So ≈ 29,800 input and ≈ 600 output tokens per prompt.
+ * So ≈ 53,000 input and ≈ 600 output tokens per prompt.
  */
 export const TYPICAL_PROMPT = Object.freeze({
-  inputTokens: 29_800,
+  inputTokens: 53_000,
   outputTokens: 600,
 });
 

package/src/agent/ops.ts

@@ -1,4 +1,5 @@
 import { resolveInstrumentWord } from "../../core/instruments.ts";
+import type { TrackVocoder } from "../../core/vocoder.ts";
 import { pitchToMidi } from "../../core/pitch.ts";
 import {
   instrumentPatchForWord,
@@ -6,6 +7,7 @@ import {
   type TrackWind,
 } from "../../core/resonators.ts";
 import { SCORE_LIMITS } from "../../core/score.ts";
+import type { TrackSing } from "../../core/sing.ts";
 
 export { pitchToMidi };
 
@@ -50,6 +52,8 @@ export type AgentOperation =
       };
       /** The instrument word as typed (a guitar alias also loads its rig). */
       word?: string;
+      /** `volume drums 0.5`: another track than the focused one. */
+      trackId?: string;
     }
   | {
       type: "automation";
@@ -99,6 +103,19 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
     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]) } };
+  // `volume drums 0.5` / `pan bass -0.2`: the mixer page's rows name their
+  // track, so a level is set without moving the focus.
+  const level = text.match(
+    /^(volume|vol|pan)\s+([a-z0-9][a-z0-9._-]{0,63})\s+(-?1(?:\.0+)?|-?0(?:\.\d+)?)$/,
+  );
+  if (level && !(level[1] !== "pan" && level[3]!.startsWith("-"))) {
+    const value = Number(level[3]);
+    return {
+      type: "track",
+      patch: level[1] === "pan" ? { pan: value } : { volume: value },
+      trackId: level[2]!,
+    };
+  }
   const clearAutomation = text.match(
     /^(?:clear|reset)\s+(?:(volume|pan)\s+)?automation$/,
   );
@@ -208,10 +225,19 @@ export function instrumentPatch(word: string): {
   string?: { preset: string };
   modal?: TrackModal;
   wind?: TrackWind;
+  sing?: TrackSing;
+  vocoder?: TrackVocoder;
 } {
   const meaning = resolveInstrumentWord(word);
   if (!meaning) return { instrument: word };
-  if (meaning.field === "modal" || meaning.field === "wind")
+  // f07-vocoder: the built-in carrier needs its (empty) field.
+  if (meaning.field === "vocoder")
+    return { instrument: meaning.instrument, vocoder: Object.freeze({}) };
+  if (
+    meaning.field === "modal" ||
+    meaning.field === "wind" ||
+    meaning.field === "sing"
+  )
     return instrumentPatchForWord(word);
   if (meaning.field === "string" && meaning.preset)
     return {

package/src/agent/pack-tools.ts

@@ -224,7 +224,7 @@ export const PACK_TOOLS: readonly AgentTool[] = Object.freeze([
   {
     name: "use_sound",
     description:
-      'Put a pack sound on a track through the sampler. sound is <pack>/<sound>[:<n>] (n picks a file, like Strudel s("bd:3")), a kit/bank name or Strudel bank nickname (909, 808, linn, TR909, tr808, sp12, dmx, RolandTR909, tidal-drum-machines/RolandTR707) to load a whole drum kit, or a keyed instrument such as gm/gm_acoustic_grand_piano or piano/piano. The file is fetched and pinned by sha256 so renders stay reproducible. Drum hits on the track keep playing the matching kit voice.',
+      'Put a pack sound on a track through the sampler. sound is <pack>/<sound>[:<n>] (n picks a file, like Strudel s("bd:3")), a kit/bank name or Strudel bank nickname (909, 808, linn, TR909, tr808, sp12, dmx, RolandTR909, tidal-drum-machines/RolandTR707) to load a whole kit, or a keyed instrument such as gm/gm_acoustic_grand_piano or piano/piano. The file is fetched and pinned by sha256 so renders stay reproducible. Drum hits on the track keep playing the matching kit voice.',
     parameters: {
       type: "object",
       properties: {

package/src/agent/planner.ts

@@ -1,8 +1,10 @@
+import { normalizeSongStyle } from "../../core/style-provenance.ts";
 import { normalizeSynth } from "../../core/synth.ts";
 import { normalizeSongTime, normalizeTrackTime } from "../../core/tempo.ts";
 import { normalizeFx } from "../../core/fx.ts";
 import { normalizeMaster } from "../../core/master.ts";
 import {
+  CALIBRATION_LATEST,
   SCORE_LIMITS,
   automationRange,
   isAutomationParameter,
@@ -142,9 +144,20 @@ function parseOperation(value: unknown): ScoreOperation {
     const time = value.time === null ? null : normalizeSongTime(value.time);
     return { type: "setTime", time: time ?? null };
   }
+  if (
+    value.type === "setCalibration" &&
+    (value.calibration === null ||
+      (typeof value.calibration === "number" &&
+        Number.isInteger(value.calibration) &&
+        value.calibration >= 0 &&
+        value.calibration <= CALIBRATION_LATEST))
+  )
+    return { type: "setCalibration", calibration: value.calibration };
   // The master reuses its bounded validator; null removes it.
   if (value.type === "setMaster" && value.master !== undefined)
     return { type: "setMaster", master: normalizeMaster(value.master) ?? null };
+  if (value.type === "setStyle" && value.style !== undefined)
+    return { type: "setStyle", style: normalizeSongStyle(value.style) ?? null };
   if (
     value.type === "setSections" &&
     Array.isArray(value.sections) &&
@@ -165,6 +178,18 @@ function parseOperation(value: unknown): ScoreOperation {
       loopSection: (value.loopSection ?? null) as string | null,
     };
   }
+  if (
+    value.type === "setLoop" &&
+    (value.loop === null ||
+      (isRecord(value.loop) &&
+        typeof value.loop.startBar === "number" &&
+        typeof value.loop.bars === "number"))
+  )
+    // The reducer checks the range (TrackScore normalizeLoopRange).
+    return {
+      type: "setLoop",
+      loop: value.loop as { startBar: number; bars: number } | null,
+    };
   if (
     value.type === "updateTrack" &&
     typeof value.trackId === "string" &&