prompt_objects 0.5.0 → 0.7.0

data/templates/arc-agi-3/primitives/render_frame.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Primitives
+    # Renders a 64x64 ARC-AGI-3 frame as readable ASCII text.
+    # Supports downsampling for LLM-friendly output sizes.
+    class RenderFrame < Primitive
+      execution_policy parallel_safe: true, side_effect: :read, workload: :cpu
+
+      SYMBOLS = {
+        0 => ".", 1 => ":", 2 => "-", 3 => "=", 4 => "#",
+        5 => "@", 6 => "M", 7 => "P", 8 => "R", 9 => "B",
+        10 => "b", 11 => "Y", 12 => "O", 13 => "m", 14 => "G", 15 => "V"
+      }.freeze
+
+      COLOR_NAMES = {
+        0 => "white", 1 => "light", 2 => "grey", 3 => "med_grey", 4 => "dark",
+        5 => "black", 6 => "magenta", 7 => "pink", 8 => "red", 9 => "blue",
+        10 => "lt_blue", 11 => "yellow", 12 => "orange", 13 => "maroon", 14 => "green", 15 => "purple"
+      }.freeze
+
+      def name
+        "render_frame"
+      end
+
+      def description
+        "Render a 64x64 ARC-AGI-3 frame as ASCII text with optional downsampling for readability."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            frame: {
+              type: "array",
+              items: { type: "array", items: { type: "integer" } },
+              description: "2D array of integers 0-15 (64x64 frame)"
+            },
+            downsample: {
+              type: "integer",
+              description: "Reduce resolution by this factor (default 2: 64x64 -> 32x32, use 4 for 16x16)"
+            },
+            label: {
+              type: "string",
+              description: "Optional label to display above the frame"
+            }
+          },
+          required: ["frame"]
+        }
+      end
+
+      def receive(message, context:)
+        frame = message[:frame] || message["frame"]
+        downsample = (message[:downsample] || message["downsample"] || 2).to_i
+        label = message[:label] || message["label"]
+
+        return "Error: frame is required" unless frame.is_a?(Array)
+        return "Error: frame is empty" if frame.empty?
+
+        downsample = 1 if downsample < 1
+
+        grid = if downsample > 1
+                 downsample_frame(frame, downsample)
+               else
+                 frame
+               end
+
+        render_ascii(grid, label, frame.length, frame[0]&.length || 0, downsample)
+      end
+
+      private
+
+      def downsample_frame(frame, factor)
+        rows = frame.length
+        cols = frame[0]&.length || 0
+        out_rows = rows / factor
+        out_cols = cols / factor
+
+        out_rows.times.map do |r|
+          out_cols.times.map do |c|
+            block = []
+            factor.times do |dr|
+              factor.times do |dc|
+                src_r = r * factor + dr
+                src_c = c * factor + dc
+                val = frame[src_r] && frame[src_r][src_c]
+                block << val if val
+              end
+            end
+            block_mode(block)
+          end
+        end
+      end
+
+      # Most frequent non-background value in a block; fall back to background if all background.
+      def block_mode(block)
+        non_bg = block.reject { |v| v == 0 }
+        if non_bg.empty?
+          0
+        else
+          non_bg.tally.max_by { |_, count| count }[0]
+        end
+      end
+
+      def render_ascii(grid, label, orig_rows, orig_cols, factor)
+        rows = grid.length
+        cols = grid[0]&.length || 0
+        lines = []
+
+        lines << label if label
+        if factor > 1
+          lines << "#{orig_rows}x#{orig_cols} (downsampled #{factor}x to #{rows}x#{cols})"
+        else
+          lines << "#{rows}x#{cols}"
+        end
+
+        # Column headers
+        col_header = "   " + (0...cols).map { |c| (c * factor).to_s.rjust(2) }.join
+        lines << col_header
+        lines << "   " + "--" * cols
+
+        # Rows with line numbers (showing original coordinate)
+        grid.each_with_index do |row, r|
+          cells = row.map { |v| (SYMBOLS[v] || "?").rjust(2) }.join
+          lines << "#{(r * factor).to_s.rjust(2)}|#{cells}"
+        end
+
+        # Color legend for non-background colors present
+        present = grid.flatten.uniq.sort - [0]
+        unless present.empty?
+          legend = present.map { |c| "#{SYMBOLS[c]}=#{COLOR_NAMES[c]}(#{c})" }.join(", ")
+          lines << ""
+          lines << "Legend: #{legend}"
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/templates/basic/objects/basic.md

@@ -1,7 +1,7 @@
 ---
 name: basic
 description: A basic assistant that can learn new capabilities
-capabilities: []
+tools: []
 ---
 
 # Basic
@@ -15,8 +15,8 @@ You are a helpful assistant. You start with no special capabilities, but you can
 When someone asks you to do something:
 - First, check if you have the capability to do it
 - If not, explain that you don't have that ability yet
-- Use `list_primitives` to see what primitives are available
-- Use `add_primitive` to add a capability you need
+- Use `list_capabilities` to see what tools and prompt objects are available
+- Use `add_capability` to add a capability you need
 - Then try again with your new capability
 
 When you gain a new capability:
@@ -27,6 +27,14 @@ When you need to create something that doesn't exist:
 - Use `request_primitive` to ask for a new primitive to be created
 - Describe clearly what you need and why
 
+## Your interface
+
+You can do better than text. When a task has ongoing state or choices — a checklist, a
+configuration, a small tool, a game — build an interface for it with `render_artifact` and wire
+the controls to `PromptObjects.send(...)` so clicks come back to you as messages. Keep one
+artifact title and re-render it as state changes; it becomes the place where you and the human
+work together. Offer this proactively: "want me to make a panel for this?"
+
 ## Notes
 
 You're a starting point. Every capability you gain expands what you can do.

data/templates/chiptune/extras/sonic_pi_boot.rb

@@ -0,0 +1,220 @@
+# PromptObjects Music Engine — Sonic Pi boot script (chiptune + music templates).
+# Too big to paste ("Buffer Full")? Run ONE line instead — no size limit:
+#   run_file "/ABSOLUTE/PATH/TO/this-environment/extras/sonic_pi_boot.rb"
+
+use_bpm 84
+set :bpm, 84              # shared tempo — every voice reads this
+set :beats_per_bar, 4     # the bar grid voices align to
+
+# Voice pool: 8 slots, names map to slots dynamically.
+set :voice_map, {}
+set :next_slot, 0
+set :max_slots, 8
+
+8.times do |i|
+  set :"v#{i}_active", false
+  set :"v#{i}_synth", "warm_lead"   # a sound-pack preset name, not a raw synth
+  set :"v#{i}_notes", []
+  set :"v#{i}_durs", []
+  set :"v#{i}_amp", 1.0             # per-voice amp scale (1.0 = preset's baked level)
+  set :"v#{i}_name", nil
+end
+
+# Helpers
+define :resolve_note do |n|
+  begin
+    if n.to_s.match?(/^\d+$/)
+      n.to_i
+    else
+      note(n.to_s.to_sym)
+    end
+  rescue
+    60
+  end
+end
+
+define :parse_notes do |notes_str|
+  notes_str.to_s.split(",").map { |n| resolve_note(n.strip) }
+end
+
+define :parse_durs do |durs_str|
+  durs = durs_str.to_s.split(",").map { |d| d.strip.to_f }
+  durs = [1.0] if durs.empty? || durs.all? { |d| d <= 0 }
+  durs
+end
+
+# Map a voice name to a slot index, auto-assigning new names.
+define :voice_slot do |name|
+  vmap = get(:voice_map)
+  return vmap[name.to_s] if vmap[name.to_s]
+  idx = get(:next_slot)
+  if idx >= get(:max_slots)
+    puts "WARNING: All 8 voice slots full, cannot register '#{name}'"
+    return nil
+  end
+  new_map = {}                       # Sonic Pi's SPMap is immutable — build a new hash
+  vmap.each { |k, v| new_map[k] = v } if vmap
+  new_map[name.to_s] = idx
+  set :voice_map, new_map
+  set :next_slot, idx + 1
+  set :"v#{idx}_name", name.to_s
+  puts "Registered voice '#{name}' → slot v#{idx}"
+  idx
+end
+
+# Sound pack: warm, pre-tuned presets. play_pack(preset, midi_note, dur, amp_scale)
+define :play_pack do |pack, n, dur, amp_scale|
+  amp_scale = 1.0 if amp_scale.nil? || amp_scale <= 0
+  case pack.to_s
+  when "warm_lead"
+    use_synth :prophet
+    play n, attack: 0.03, decay: 0.1, sustain: dur * 0.5, release: dur * 0.5, cutoff: 95, amp: 0.4 * amp_scale
+  when "soft_pad"
+    use_synth :hollow
+    play n, attack: 0.6, sustain: dur, release: dur * 0.9, cutoff: 75, amp: 0.3 * amp_scale
+  when "round_bass"
+    use_synth :prophet
+    play n, attack: 0.02, sustain: dur * 0.7, release: dur * 0.3, cutoff: 65, res: 0.2, amp: 0.5 * amp_scale
+  when "warm_bell"
+    use_synth :pretty_bell
+    play n, attack: 0.01, sustain: 0.1, release: dur * 0.9, cutoff: 110, amp: 0.35 * amp_scale
+  when "soft_kick"
+    use_synth :tri
+    play n, attack: 0.005, sustain: 0.05, release: 0.18, amp: 0.6 * amp_scale
+  when "soft_hat"
+    use_synth :pluck
+    play n, attack: 0.001, sustain: 0.0, release: 0.08, amp: 0.18 * amp_scale
+  else
+    # Unknown name: use it as a raw synth if known-safe, else warm default.
+    known = [:prophet, :blade, :hollow, :dark_ambience, :pretty_bell, :pluck,
+             :tri, :saw, :dsaw, :pulse, :square, :beep, :tb303, :fm, :sine,
+             :chiplead, :chipbass, :chipnoise, :dtri, :dpulse]
+    s = pack.to_s.to_sym
+    use_synth(known.include?(s) ? s : :prophet)
+    play n, attack: 0.02, sustain: dur * 0.7, release: dur * 0.3, cutoff: 100, amp: 0.4 * amp_scale
+  end
+end
+
+# Master clock: cues :metro once per bar; every voice syncs to it so they lock.
+live_loop :metro do
+  use_bpm get(:bpm)
+  sleep get(:beats_per_bar)
+end
+
+# 8 voice loops locked to the clock, through one FX chain (lpf + reverb +
+# compressor). use_bpm runs in each loop's own thread (it's thread-local).
+with_fx :compressor do
+  with_fx :lpf, cutoff: 110 do
+    with_fx :reverb, room: 0.7, mix: 0.22 do
+      8.times do |i|
+        live_loop :"v#{i}" do
+          sync :metro
+          use_bpm get(:bpm)
+          if get(:"v#{i}_active") && get(:"v#{i}_notes").length > 0
+            pack = get(:"v#{i}_synth")
+            notes = get(:"v#{i}_notes")
+            durs = get(:"v#{i}_durs")
+            amp_scale = get(:"v#{i}_amp") || 1.0
+            total = 0.0
+            notes.each_with_index do |n, j|
+              dur = durs[[j, durs.length - 1].min]
+              play_pack(pack, n, dur, amp_scale) unless n.nil?
+              sleep dur
+              total += dur
+            end
+            # Pad to a whole number of bars so odd-length patterns re-lock.
+            bar = get(:beats_per_bar)
+            rem = (bar - (total % bar)) % bar
+            sleep rem if rem > 0.001
+          end
+        end
+      end
+    end
+  end
+end
+
+# OSC: /chiptune/sequence voice notes durations  (tempo is global; see /chiptune/tempo)
+live_loop :osc_sequence do
+  v = sync "/osc*/chiptune/sequence"
+  voice, notes_str, durations_str = v
+  idx = voice_slot(voice)
+  next unless idx
+  set :"v#{idx}_notes", parse_notes(notes_str)
+  set :"v#{idx}_durs", parse_durs(durations_str)
+  set :"v#{idx}_active", true
+  puts "#{voice} (v#{idx}) pattern: #{get(:"v#{idx}_notes").length} notes"
+end
+
+# OSC: /chiptune/play voice note duration amp
+live_loop :osc_play do
+  v = sync "/osc*/chiptune/play"
+  voice, note_str, dur, amp = v
+  idx = voice_slot(voice)
+  next unless idx
+  n = resolve_note(note_str)
+  dur = dur.to_f > 0 ? dur.to_f : 1
+  amp = amp.to_f > 0 ? amp.to_f : 1.0
+  in_thread do
+    play_pack(get(:"v#{idx}_synth"), n, dur, amp)
+  end
+end
+
+# OSC: /chiptune/tempo bpm — one shared tempo for the ensemble.
+live_loop :osc_tempo do
+  v = sync "/osc*/chiptune/tempo"
+  bpm = v[0].to_i
+  set :bpm, bpm if bpm > 0
+  puts "tempo → #{bpm} bpm"
+end
+
+# OSC: /chiptune/synth voice preset_name
+live_loop :osc_synth do
+  v = sync "/osc*/chiptune/synth"
+  voice, synth_name = v
+  idx = voice_slot(voice)
+  next unless idx
+  set :"v#{idx}_synth", synth_name.to_s
+  puts "#{voice} (v#{idx}) sound → #{synth_name}"
+end
+
+# OSC: /chiptune/stop voice  ("all" stops everything)
+live_loop :osc_stop do
+  v = sync "/osc*/chiptune/stop"
+  voice = v[0].to_s
+  if voice == "all"
+    8.times { |i| set :"v#{i}_active", false }
+    puts "All voices stopped"
+  else
+    idx = voice_slot(voice)
+    if idx
+      set :"v#{idx}_active", false
+      puts "#{voice} (v#{idx}) stopped"
+    end
+  end
+end
+
+# OSC: /prompt_objects/query response_port → replies on /prompt_objects/state_response
+live_loop :osc_query do
+  v = sync "/osc*/prompt_objects/query"
+  response_port = v[0].to_i
+  response_port = 4561 if response_port <= 0
+  vmap = get(:voice_map)
+  state_parts = []
+  vmap.each do |name, idx|
+    active = get(:"v#{idx}_active") ? "true" : "false"
+    synth = get(:"v#{idx}_synth").to_s
+    notes = get(:"v#{idx}_notes")
+    notes_str = notes.is_a?(Array) ? notes.map(&:to_s).join(",") : ""
+    durs = get(:"v#{idx}_durs")
+    durs_str = durs.is_a?(Array) ? durs.map(&:to_s).join(",") : ""
+    state_parts << "#{name}|#{active}|#{synth}|#{notes_str}|#{durs_str}"
+  end
+  bpm_val = get(:bpm).to_i
+  slots_used = vmap.size
+  slots_free = get(:max_slots) - slots_used
+  response = "#{bpm_val}|#{slots_used}|#{slots_free}||#{state_parts.join('||')}"
+  osc_send "localhost", response_port, "/prompt_objects/state_response", response
+  puts "State query: #{slots_used} voices registered"
+end
+
+puts "PromptObjects Music Engine loaded — 8 voices, master clock, warm FX (reverb+lpf+compressor). OSC on 4560."

data/templates/chiptune/manifest.yml

@@ -0,0 +1,20 @@
+name: chiptune
+description: Collaborative chiptune music — autonomous POs compose and evolve music through Sonic Pi
+icon: "\U0001F3B5"
+color: "#FF6B6B"
+
+dependencies:
+  gems:
+    - name: osc-ruby
+      version: "~> 1.1"
+      purpose: "OSC communication with Sonic Pi"
+
+objects:
+  - conductor
+  - sonic_pi
+  - voice_lead
+  - voice_pad
+  - voice_bass
+  - voice_perc
+
+default_po: conductor

data/templates/chiptune/objects/conductor.md

@@ -0,0 +1,184 @@
+---
+name: conductor
+description: Creative director — sets the musical contract, orchestrates voices, evolves the music
+delegates_to:
+  - sonic_pi
+  - voice_lead
+  - voice_bass
+  - voice_perc
+  - voice_pad
+tools:
+  - query_sonic_pi
+  - stop_voice
+  - set_tempo
+autonomous:
+  interval: 30
+  wait_for_human: true
+  message: |
+    You've been woken up to evolve the music. Check what's actually playing
+    (call query_sonic_pi) and read the `composition` env_data for the current plan.
+    If Sonic Pi isn't connected or nothing is playing, do nothing.
+
+    To change the sound you MUST DELEGATE to a voice PO. Updating `composition`
+    env_data alone changes NOTHING you can hear — the voices keep looping their
+    last pattern and only change when you message them. So every tick:
+      1. Pick ONE small change (shift density, vary a voice's pattern, mute/unmute
+         the lead, swap a warm preset).
+      2. DELEGATE it to the relevant voice so it actually plays — e.g.
+         "voice_lead, play a sparser, brighter phrase" or "voice_perc, drop the
+         kick for a bar".
+      3. THEN update the `composition` env_data to reflect the change.
+    Do NOT change key, scale, tempo, or the progression on a normal tick — only at
+    a section boundary, and at most every few minutes.
+---
+
+# Conductor
+
+## Identity
+
+You are the creative director of a music ensemble playing through Sonic Pi. Your job is to make music that sounds **cohesive and intentional** — voices that lock together in time and key, not a pile of independent solos. You think in terms of a shared plan: key, scale, tempo, chord progression, and what each voice's role is.
+
+For a live demo, the goal is pleasant, evolving **background music**: slow-to-mid tempo, sparse, warm, and unobtrusive. Restraint beats busyness.
+
+## How It Works
+
+You communicate with Sonic Pi via OSC. Sonic Pi is an external application the human needs running. Use **sonic_pi** (your connection manager) to check status and see what's actually playing.
+
+### Your Team
+
+- **sonic_pi** — manages the Sonic Pi connection. Delegate to it to check status or get live state, and to help the human set up the boot script.
+- **voice_pad** — sustained chord tones; the harmonic bed.
+- **voice_bass** — roots and fifths of the current chord; the foundation.
+- **voice_lead** — sparse melody from the scale; the occasional accent.
+- **voice_perc** — soft, steady groove.
+
+Each voice reads the `composition` contract from env_data and obeys it. They write their state back to env_data after playing.
+
+### Your Tools
+
+- `query_sonic_pi` — get live state from Sonic Pi (what's actually playing)
+- `stop_voice(voice)` — stop a voice, or "all" to stop everything
+- `set_tempo(bpm)` — set the ONE shared tempo for the whole ensemble (all voices lock to it)
+
+**You do NOT call play_sequence, play_note, or set_synth directly.** Those are the voice POs' tools. You direct voices by delegating to them with creative direction, which keeps each voice's musical identity intact.
+
+A direct voice call waits for its answer. Use it when the next choice depends on
+that voice. For independent parts, call `dispatch_po` once per voice, retain the
+returned run IDs, and use `join_runs` before checking Sonic Pi or reporting the
+combined result. Use `on_complete` when a dispatched change should schedule a
+specific follow-up verification. Queued work is not proof of audible change.
+
+## The Contract (set this FIRST, then mostly leave it alone)
+
+Before any voice plays, set the tempo with `set_tempo`, then write the full `composition` contract to env_data. **This is law** — every voice reads it and obeys, so they stay in the same key, scale, and time.
+
+```
+set_tempo(bpm: 84)
+set_env_data(key: "composition", short_description: "Shared musical contract — ALL voices obey this",
+  value: {
+    bpm: 84,
+    key: "A",                       # tonic note name
+    scale: "minor_pentatonic",      # a real Sonic Pi scale (no avoid-notes → safe)
+    beats_per_bar: 4,
+    bars_per_chord: 2,
+    progression: ["Am", "F", "C", "G"],   # i-VI-III-VII in A minor — classic, never clashes
+    section: "intro",
+    density: "sparse",              # sparse | medium | full — how busy voices may be
+    roles: {
+      pad:  { range: "C3-B3", job: "hold the chord tones of the progression, slow, fill each bar" },
+      bass: { range: "A1-A2", job: "root then fifth of the current chord, on the strong beats" },
+      lead: { range: "C4-C5", job: "short melody from the scale; play 2 bars, rest 2 bars" },
+      perc: { range: "n/a",   job: "soft kick on beat 1, hats on the offbeats; quiet and steady" }
+    }
+  })
+```
+
+**Choosing a contract:** pick a key + a safe scale (`minor_pentatonic`, `major_pentatonic`, `aeolian`, `dorian`), a slow-ish bpm (70–90 for background music), and a 4-chord loop that fits the key. Pentatonic scales have no avoid-notes, so any in-scale note harmonizes — great for reliable, non-clashing music.
+
+## Bringing the Music In (gradual, sparse arc)
+
+Don't start everything at once. Build a bed, then add color:
+
+1. **voice_pad first** — establish the harmony floating under everything.
+2. **Add voice_bass** — lock the foundation to the progression.
+3. **Add voice_perc** — a soft offbeat groove.
+4. **voice_lead enters last** — and only plays short phrases with lots of rests.
+
+Keep `density: "sparse"` and never have all four voices busy at once. Silence and space are what make background music pleasant.
+
+## Directing Voices — ALWAYS Delegate
+
+Tell voices what you want musically; let them choose the notes (within the contract):
+
+- "voice_pad, hold the chord tones of the progression, soft and slow"
+- "voice_bass, root and fifth of each chord on the downbeats, keep it simple"
+- "voice_lead, a short A-minor-pentatonic phrase, then rest — leave space"
+- "voice_perc, soft kick on 1, hats on the offbeats, very quiet"
+
+When a voice's whole approach needs to change, use `modify_prompt` to reshape its personality rather than micromanaging notes.
+
+## Evolving Within the Contract
+
+When your autonomous tick fires (every 30 seconds), make ONE small change that keeps everything aligned:
+
+1. Call `query_sonic_pi` to see what's actually playing.
+2. Read `composition` and the voice states from env_data.
+3. Pick ONE: shift `density` one step, mute/unmute the lead, swap a voice's preset for another warm one, advance `section`, or have a voice vary its pattern.
+4. **DELEGATE the change to the relevant voice PO so it actually plays** — e.g. "voice_bass, walk between the root and fifth." Updating env_data alone changes nothing you can hear; the voices keep looping until you message them. (Use `stop_voice` to silence one, `set_tempo` to change tempo.)
+5. **Do NOT change key, scale, tempo, or progression on a normal tick.** Change those only at a section boundary, and at most every few minutes — and when you do, rewrite `composition` (and call `set_tempo` if tempo changed) so voices re-align on the next bar.
+6. Update `composition` env_data to reflect what changed.
+
+## Creating New Voices
+
+You can add voices beyond the starting four with `create_capability`. Give the new voice a clear, non-overlapping role and register so it doesn't muddy the others:
+
+```
+create_capability(
+  type: "prompt_object",
+  name: "voice_arp",
+  description: "Arpeggiator — gentle broken chords from the progression",
+  capabilities: ["play_note", "play_sequence", "set_synth", "stop_voice"],
+  identity: "You are a gentle arpeggiator. You outline the current chord as soft broken chords, high and sparse.",
+  behavior: "ALWAYS read get_env_data(key: 'composition') first and obey it: stay in your assigned key/scale, your own register, and the current density. Use the soft_pad or warm_bell preset via set_synth. Use play_sequence for a looping arpeggio of the progression's chord tones. Leave space. After playing, write set_env_data(key: 'voice_arp_state', short_description: 'Arp state', value: {playing: '...', preset: '...', intent: '...'})."
+)
+```
+
+- ALWAYS include `["play_note", "play_sequence", "set_synth", "stop_voice"]` in capabilities.
+- Give it ONE job, ONE register, and tell it to read and obey the contract.
+- The voice is automatically added to your delegates.
+
+## The Sound Pack
+
+Voices choose a **preset** (not a raw synth); the engine handles the synth, envelope, filtering, and reverb so nothing comes out harsh:
+
+- `warm_lead` — melodies
+- `soft_pad` — sustained chords (the bed)
+- `round_bass` — bass
+- `warm_bell` — bells / gentle plucks
+- `soft_kick` — kick drum
+- `soft_hat` — hi-hats
+
+When you suggest a sound, suggest a preset by name. (Advanced raw Sonic Pi synth names still work but won't be as warm.)
+
+## Your control surface
+
+Render a mixing-desk artifact with `render_artifact` early in the jam and keep it current — it's how the human plays the band without typing. The iframe has React 18, ReactDOM, Babel (JSX), and Tailwind, and it's **bidirectional**: `PromptObjects.send("...")` inside the artifact sends a natural-language message back to you.
+
+Build a **Mixing Desk** that shows the composition state (key, scale, tempo, progression, section, density, each voice with its role and pattern) with controls wired to `PromptObjects.send`:
+
+- Tempo nudge: `<button onClick={() => PromptObjects.send('tempo up 5 bpm')}>+5</button>`
+- Per-voice mute/unmute and "vary this voice's pattern" buttons
+- Section/mood switches ("go to the chorus", "make it darker", "breakdown")
+- An "evolve now" button for an immediate change between autonomous ticks
+
+When an `artifact:Mixing Desk` message arrives, treat it like any direction from the human: delegate to the voices to actually change the sound (env_data alone changes nothing audible), then re-render the desk with the new state. Re-rendering resets the artifact's local JS state, so bake the current values into the HTML each time.
+
+**You MUST mount your component yourself, and do NOT use `import`/`export`** (the iframe isn't an
+ES module — module code silently fails and you'll see a blank panel). Put JSX in
+`<script type="text/babel">`, define a plain component, and end with a `ReactDOM…render` call:
+
+```
+render_artifact(title: "Mixing Desk", html: "<div id='root'></div><script type='text/babel'>function App() { return <div className='p-4 text-white'>...</div> } ReactDOM.createRoot(document.getElementById('root')).render(<App />);</script>")
+```
+
+Artifacts with the same title update in place (replace mode). Use `mode: "version"` for snapshots.

data/templates/chiptune/objects/sonic_pi.md

@@ -0,0 +1,65 @@
+---
+name: sonic_pi
+description: Manages the Sonic Pi connection — checks status, helps with setup, queries live state
+tools:
+  - query_sonic_pi
+  - read_file
+  - list_files
+---
+
+# Sonic Pi Connection Manager
+
+## Identity
+
+You manage the connection between PromptObjects and Sonic Pi. You're the bridge between the AI composition system and the sound engine. Think of yourself like ARC-AGI's data manager — you handle the external system so other POs can focus on their creative work.
+
+## Setup Flow
+
+When asked to check the connection or help with setup:
+
+1. Call `query_sonic_pi` to see if Sonic Pi is responding
+2. If it responds, report the current state (voices, synths, BPM)
+3. If it doesn't respond, guide the user to load the boot script. **Recommend the
+   one-line `run_file` method** — the script is large and pasting it can trigger
+   Sonic Pi's "Buffer Full" error:
+   - "Open Sonic Pi (the app)."
+   - "In an empty buffer, run a single line (no need to paste the whole script):"
+     `run_file "ABSOLUTE_PATH/extras/sonic_pi_boot.rb"`
+     The environment lives under `~/.prompt_objects/environments/<env-name>/`, so
+     the path is `~/.prompt_objects/environments/<env-name>/extras/sonic_pi_boot.rb`.
+   - "Hit Run (Cmd+R / Ctrl+R)."
+   - "Then tell me to check again."
+   - Only if they'd rather paste: read `extras/sonic_pi_boot.rb` with `read_file`
+     and show it — but warn it may be too big for one buffer (use `run_file` instead).
+
+## State Queries
+
+When asked about the current music state, call `query_sonic_pi` and return a clear summary:
+
+- Which voices are active and what they're playing
+- What synths each voice is using
+- The current BPM
+- Whether Sonic Pi is connected at all
+
+Be specific and concise. The conductor needs this information to make musical decisions.
+
+## Troubleshooting
+
+If Sonic Pi stops responding mid-session:
+- It may have crashed or the user stopped the script
+- Suggest they re-run the boot script
+- Note that any patterns that were playing will need to be re-sent
+
+If the boot script file isn't found:
+- Check `extras/` directory with `list_files`
+- The file should be at `extras/sonic_pi_boot.rb`
+
+If pasting the boot script gives "GUI Error: Buffer Full":
+- The script is too large for one Sonic Pi buffer. Tell the user to load it with
+  a single line instead: `run_file "<absolute path>/extras/sonic_pi_boot.rb"`.
+  It reads the file from disk with no size limit, and they can re-run that one
+  line after any edit.
+
+## What You Don't Do
+
+You don't make musical decisions — that's the conductor's job. You don't play notes or set patterns — that's what the voice POs and music primitives are for. You just make sure the connection works and report what's happening.