prompt_objects 0.5.0 → 0.7.0

data/templates/music-pro/extras/sonic_pi_boot.rb

@@ -0,0 +1,546 @@
+# Prompt Objects Music Pro — expressive live-pattern engine for Sonic Pi.
+#
+# In Sonic Pi, run this one line (using the environment's absolute path):
+#   run_file "/ABSOLUTE/PATH/extras/sonic_pi_boot.rb"
+#
+# The engine receives structured OSC from Prompt Objects. Patterns are replaced
+# atomically at bar boundaries; voices remain independent, synchronized live
+# collaborators rather than parts in a pre-rendered song.
+
+require "json"
+
+use_bpm 78
+set :po_bpm, 78.0
+set :po_beats_per_bar, 4.0
+set :po_master_amp, 0.7
+set :po_max_voices, 12
+set :po_voice_map, {}
+set :po_next_slot, 0
+set :po_patch_names, []
+
+12.times do |i|
+  set :"po_v#{i}_active", false
+  set :"po_v#{i}_definition", ""
+  set :"po_v#{i}_cycle", 0
+  set :"po_v#{i}_name", ""
+end
+
+define :po_clamp do |value, low, high|
+  [[value.to_f, low.to_f].max, high.to_f].min
+end
+
+define :po_symbolize_hash do |value|
+  out = {}
+  if value.is_a?(Hash)
+    value.each do |key, item|
+      out[key.to_s.to_sym] = item
+    end
+  end
+  out
+end
+
+define :po_safe_identifier do |value|
+  value.to_s.match?(/\A[a-zA-Z][a-zA-Z0-9_:-]{0,79}\z/)
+end
+
+define :po_store_patch do |name, patch|
+  return false unless po_safe_identifier(name)
+  return false unless patch.is_a?(Hash)
+  return false unless ["synth", "sample"].include?((patch["kind"] || "synth").to_s)
+  source = patch["synth"] || patch["sample"]
+  return false unless po_safe_identifier(source)
+  effects = patch["effects"] || []
+  return false unless effects.is_a?(Array) && effects.length <= 3
+  params = patch["params"] || {}
+  return false unless params.is_a?(Hash) && params.length <= 24
+  effects.each do |effect|
+    return false unless effect.is_a?(Hash) && po_safe_identifier(effect["name"])
+    fx_params = effect["params"] || {}
+    return false unless fx_params.is_a?(Hash) && fx_params.length <= 24
+  end
+
+  set :"po_patch_#{name}", JSON.generate(patch)
+  names = get(:po_patch_names) || []
+  unless names.include?(name.to_s)
+    replacement = names.to_a + [name.to_s]
+    set :po_patch_names, replacement
+  end
+  true
+end
+
+# These are starting points, not a whitelist. Agents can replace them or define
+# completely new synth/sample/effect patches through define_patch.
+po_store_patch("soft_rodeo", {
+  "kind" => "synth", "synth" => "rodeo",
+  "params" => { "amp" => 0.16, "cutoff" => 72, "release" => 1.8 },
+  "effects" => [{ "name" => "reverb", "params" => { "mix" => 0.18, "room" => 0.65 } }]
+})
+po_store_patch("air_blade", {
+  "kind" => "synth", "synth" => "blade",
+  "params" => { "amp" => 0.11, "attack" => 0.8, "release" => 3.5, "cutoff" => 72 },
+  "effects" => [{ "name" => "reverb", "params" => { "mix" => 0.28, "room" => 0.8 } }]
+})
+po_store_patch("foundation", {
+  "kind" => "synth", "synth" => "bass_foundation",
+  "params" => { "amp" => 0.15, "cutoff" => 70, "release" => 0.5 },
+  "effects" => []
+})
+po_store_patch("tiny_kalimba", {
+  "kind" => "synth", "synth" => "kalimba",
+  "params" => { "amp" => 0.1, "release" => 1.2 },
+  "effects" => [{ "name" => "reverb", "params" => { "mix" => 0.2, "room" => 0.7 } }]
+})
+po_store_patch("chip_raw", {
+  "kind" => "synth", "synth" => "chiplead",
+  "params" => { "amp" => 0.12, "release" => 0.2 },
+  "effects" => []
+})
+po_store_patch("soft_drum", {
+  "kind" => "sample", "sample" => "bd_haus",
+  "params" => { "amp" => 0.16 }, "effects" => []
+})
+
+define :po_patch do |patch_ref|
+  if patch_ref.is_a?(Hash)
+    return patch_ref
+  end
+  raw = get(:"po_patch_#{patch_ref}")
+  begin
+    raw.to_s.empty? ? JSON.parse(get(:po_patch_soft_rodeo)) : JSON.parse(raw)
+  rescue
+    JSON.parse(get(:po_patch_soft_rodeo))
+  end
+end
+
+define :po_voice_slot do |name|
+  name = name.to_s
+  return nil unless name.match?(/\A[a-zA-Z][a-zA-Z0-9_-]{0,39}\z/)
+  map = get(:po_voice_map) || {}
+  return map[name] unless map[name].nil?
+
+  idx = get(:po_next_slot).to_i
+  if idx >= get(:po_max_voices).to_i
+    puts "Music Pro: voice limit reached; ignored #{name}"
+    return nil
+  end
+  replacement = {}
+  map.each { |key, value| replacement[key] = value }
+  replacement[name] = idx
+  set :po_voice_map, replacement
+  set :po_next_slot, idx + 1
+  set :"po_v#{idx}_name", name
+  puts "Music Pro: registered #{name} in slot #{idx}"
+  idx
+end
+
+# Split on whitespace only at the top nesting level. This small parser keeps the
+# notation concise without evaluating agent-authored Ruby code.
+define :po_tokens do |text|
+  tokens = []
+  token = ""
+  depths = { "[" => 0, "(" => 0, "<" => 0, "{" => 0 }
+  closes = { "]" => "[", ")" => "(", ">" => "<", "}" => "{" }
+  text.to_s.each_char do |char|
+    if depths.key?(char)
+      depths[char] += 1
+      token += char
+    elsif closes.key?(char)
+      depths[closes[char]] -= 1
+      token += char
+    elsif char.match?(/\s/) && depths.values.all? { |depth| depth == 0 }
+      unless token.empty?
+        tokens << token
+        token = ""
+      end
+    else
+      token += char
+    end
+  end
+  tokens << token unless token.empty?
+  tokens
+end
+
+define :po_scalar do |value|
+  value = value.to_s.strip
+  return true if value == "true"
+  return false if value == "false"
+  return value.to_f if value.match?(/\A-?\d+(\.\d+)?\z/)
+  value
+end
+
+define :po_event_options do |raw|
+  options = {}
+  raw.to_s.split(",").each do |pair|
+    key, value = pair.split("=", 2)
+    options[key.to_s.strip] = po_scalar(value) unless key.to_s.strip.empty? || value.nil?
+  end
+  options
+end
+
+define :po_note do |value|
+  str = value.to_s.strip
+  return str.to_i if str.match?(/\A\d+\z/)
+  note(str.to_sym)
+rescue
+  60
+end
+
+define :po_parse_token do |raw_token, cycle|
+  token = raw_token.to_s
+  options = {}
+  if token.end_with?("}")
+    open = token.rindex("{")
+    if open
+      options = po_event_options(token[(open + 1)...-1])
+      token = token[0...open]
+    end
+  end
+
+  repeat = 1
+  repeat_match = token.match(/\*(\d+)\z/)
+  if repeat_match
+    repeat = po_clamp(repeat_match[1].to_i, 1, 16).to_i
+    token = token.sub(/\*\d+\z/, "")
+  end
+
+  duration = nil
+  duration_match = token.match(/\/([0-9]+(?:\.[0-9]+)?)\z/)
+  if duration_match
+    duration = po_clamp(duration_match[1].to_f, 0.125, 64.0)
+    token = token.sub(/\/[0-9]+(?:\.[0-9]+)?\z/, "")
+  end
+
+  events = []
+  if token.start_with?("[") && token.end_with?("]")
+    events = po_parse_pattern(token[1...-1], cycle)
+    if duration && !events.empty?
+      total = events.map { |event| event["duration"].to_f }.inject(0.0, :+)
+      duration_ratio = total > 0 ? duration / total : 1.0
+      events.each { |event| event["duration"] = event["duration"].to_f * duration_ratio }
+    end
+  elsif token.start_with?("<") && token.end_with?(">")
+    choices = po_tokens(token[1...-1])
+    chosen = choices.empty? ? "~" : choices[cycle.to_i % choices.length]
+    events = po_parse_token(chosen + (duration ? "/#{duration}" : ""), cycle)
+  else
+    event = { "duration" => (duration || 1.0), "options" => options }
+    if token == "~" || token == "-"
+      event["type"] = "rest"
+    elsif token.start_with?("@")
+      event["type"] = "sample"
+      event["sample"] = token[1..]
+    elsif token.start_with?("(") && token.end_with?(")")
+      event["type"] = "notes"
+      event["notes"] = token[1...-1].split(/[,+]/).map { |item| po_note(item) }.take(12)
+    else
+      event["type"] = "notes"
+      event["notes"] = [po_note(token)]
+    end
+    events = [event]
+  end
+
+  events.each do |event|
+    current = event["options"].is_a?(Hash) ? event["options"] : {}
+    event["options"] = current.merge(options)
+  end
+
+  repeated = []
+  repeat.times { events.each { |event| repeated << Marshal.load(Marshal.dump(event)) } }
+  repeated
+end
+
+define :po_parse_pattern do |text, cycle|
+  events = []
+  po_tokens(text.to_s[0, 4096]).take(128).each do |token|
+    po_parse_token(token, cycle).each do |event|
+      events << event if events.length < 128
+    end
+  end
+  events = [{ "type" => "rest", "duration" => get(:po_beats_per_bar), "options" => {} }] if events.empty?
+  events
+rescue => error
+  puts "Music Pro: pattern parse error: #{error}"
+  [{ "type" => "rest", "duration" => get(:po_beats_per_bar), "options" => {} }]
+end
+
+define :po_transform_events do |events, transforms, cycle|
+  transforms = {} unless transforms.is_a?(Hash)
+  every = transforms["every"]
+  active = transforms.dup
+  if every.is_a?(Hash) && every["cycles"].to_i > 0 && ((cycle.to_i + 1) % every["cycles"].to_i == 0)
+    active[every["transform"].to_s] = every.fetch("value", true)
+  end
+  active.delete("every")
+
+  events = events.reverse if active["reverse"]
+  rotate = active["rotate"].to_i
+  events = events.rotate(rotate % events.length) unless events.empty? || rotate == 0
+  stretch_factor = po_clamp(active.fetch("stretch", 1.0), 0.125, 8.0)
+  transpose = po_clamp(active.fetch("transpose", 0), -48, 48).to_i
+  probability = po_clamp(active.fetch("probability", 1.0), 0.0, 1.0)
+  events.each do |event|
+    event["duration"] = po_clamp(event["duration"].to_f * stretch_factor, 0.125, 64.0)
+    event["notes"] = event["notes"].map { |n| n.to_f + transpose } if event["notes"]
+    event["options"]["probability"] = po_clamp(event["options"].fetch("probability", 1.0).to_f * probability, 0.0, 1.0)
+  end
+  events
+end
+
+define :po_play_source do |event, patch, mix|
+  options = event["options"] || {}
+  params = po_symbolize_hash(patch["params"] || {})
+  options.each do |key, value|
+    params[key.to_s.to_sym] = value unless %w[probability synth sample gate].include?(key.to_s)
+  end
+
+  patch_amp = params.fetch(:amp, 1.0).to_f
+  event_amp = options.fetch("amp", 1.0).to_f
+  voice_amp = mix.fetch("amp", 1.0).to_f
+  params[:amp] = po_clamp(patch_amp * event_amp * voice_amp * get(:po_master_amp).to_f, 0.0, 0.6)
+  params[:pan] = po_clamp(params.fetch(:pan, 0.0).to_f + mix.fetch("pan", 0.0).to_f, -1.0, 1.0)
+  params[:attack] = po_clamp(params[:attack], 0.0, 32.0) if params.key?(:attack)
+  params[:release] = po_clamp(params[:release], 0.0, 32.0) if params.key?(:release)
+  params[:sustain] = po_clamp(params[:sustain], 0.0, 64.0) if params.key?(:sustain)
+  params[:cutoff] = po_clamp(params[:cutoff], 20.0, 130.0) if params.key?(:cutoff)
+
+  if event["type"] == "sample" || patch["kind"].to_s == "sample"
+    source = options["sample"] || event["sample"] || patch["sample"]
+    return unless po_safe_identifier(source)
+    sample(source.to_s.to_sym, params)
+  else
+    source = options["synth"] || patch["synth"] || "beep"
+    return unless po_safe_identifier(source)
+    # Duration is the distance to the next onset. Unless a patch explicitly
+    # owns sustain, derive an envelope that remains audible for roughly that
+    # span. `gate` can shorten or overlap the event without changing its rhythm.
+    gate = po_clamp(options.fetch("gate", event["duration"].to_f * 0.95), 0.05, 64.0)
+    unless params.key?(:sustain)
+      attack = params.fetch(:attack, 0.0).to_f
+      unless params.key?(:release)
+        params[:release] = po_clamp(gate * 0.2, 0.05, 1.5)
+      end
+      params[:sustain] = po_clamp(gate - attack - params.fetch(:release, 0.0).to_f, 0.0, 64.0)
+    end
+    use_synth source.to_s.to_sym
+    notes = event["notes"] || [60]
+    notes.length > 1 ? play_chord(notes, params) : play(notes[0], params)
+  end
+rescue => error
+  puts "Music Pro: event error: #{error}"
+end
+
+define :po_play_event do |event, patch, mix|
+  return if event["type"] == "rest"
+  effects = (patch["effects"] || []).take(3)
+  if effects.length == 0
+    po_play_source(event, patch, mix)
+  elsif effects.length == 1
+    with_fx effects[0]["name"].to_s.to_sym, po_symbolize_hash(effects[0]["params"] || {}) do
+      po_play_source(event, patch, mix)
+    end
+  elsif effects.length == 2
+    with_fx effects[0]["name"].to_s.to_sym, po_symbolize_hash(effects[0]["params"] || {}) do
+      with_fx effects[1]["name"].to_s.to_sym, po_symbolize_hash(effects[1]["params"] || {}) do
+        po_play_source(event, patch, mix)
+      end
+    end
+  else
+    with_fx effects[0]["name"].to_s.to_sym, po_symbolize_hash(effects[0]["params"] || {}) do
+      with_fx effects[1]["name"].to_s.to_sym, po_symbolize_hash(effects[1]["params"] || {}) do
+        with_fx effects[2]["name"].to_s.to_sym, po_symbolize_hash(effects[2]["params"] || {}) do
+          po_play_source(event, patch, mix)
+        end
+      end
+    end
+  end
+rescue => error
+  puts "Music Pro: effect error: #{error}"
+end
+
+# Run one cycle inside a single FX chain. Effects are allocated per voice cycle,
+# not per note, which bounds synth-node churn even for fast patterns.
+define :po_run_cycle_events do |events, patch, mix, seed, cycle|
+  elapsed = 0.0
+  events.each_with_index do |event, event_index|
+    break if elapsed >= 128.0
+    probability = po_clamp(event["options"].fetch("probability", 1.0), 0.0, 1.0)
+    use_random_seed(seed + cycle * 521 + event_index)
+    po_play_source(event, patch, mix) if event["type"] != "rest" && rand < probability
+    duration = po_clamp(event["duration"], 0.125, 64.0)
+    sleep duration
+    elapsed += duration
+  end
+  elapsed
+end
+
+define :po_play_cycle do |events, patch, mix, seed, cycle|
+  effects = (patch["effects"] || []).take(3)
+  if effects.length == 0
+    po_run_cycle_events(events, patch, mix, seed, cycle)
+  elsif effects.length == 1
+    with_fx effects[0]["name"].to_s.to_sym, po_symbolize_hash(effects[0]["params"] || {}) do
+      po_run_cycle_events(events, patch, mix, seed, cycle)
+    end
+  elsif effects.length == 2
+    with_fx effects[0]["name"].to_s.to_sym, po_symbolize_hash(effects[0]["params"] || {}) do
+      with_fx effects[1]["name"].to_s.to_sym, po_symbolize_hash(effects[1]["params"] || {}) do
+        po_run_cycle_events(events, patch, mix, seed, cycle)
+      end
+    end
+  else
+    with_fx effects[0]["name"].to_s.to_sym, po_symbolize_hash(effects[0]["params"] || {}) do
+      with_fx effects[1]["name"].to_s.to_sym, po_symbolize_hash(effects[1]["params"] || {}) do
+        with_fx effects[2]["name"].to_s.to_sym, po_symbolize_hash(effects[2]["params"] || {}) do
+          po_run_cycle_events(events, patch, mix, seed, cycle)
+        end
+      end
+    end
+  end
+rescue => error
+  puts "Music Pro: cycle effect error: #{error}"
+  0.0
+end
+
+live_loop :po_music_clock do
+  use_bpm get(:po_bpm)
+  cue :po_music_bar
+  sleep get(:po_beats_per_bar)
+end
+
+with_fx :compressor, threshold: 0.2, slope_above: 0.35, clamp_time: 0.01, relax_time: 0.08 do
+  12.times do |i|
+    live_loop :"po_music_voice_#{i}" do
+      sync :po_music_bar
+      use_bpm get(:po_bpm)
+      next unless get(:"po_v#{i}_active")
+      raw = get(:"po_v#{i}_definition").to_s
+      next if raw.empty?
+      begin
+        definition = JSON.parse(raw)
+        cycle = get(:"po_v#{i}_cycle").to_i
+        events = po_parse_pattern(definition["pattern"], cycle)
+        events = po_transform_events(events, definition["transforms"], cycle)
+        patch = po_patch(definition["patch"])
+        mix = definition["mix"].is_a?(Hash) ? definition["mix"] : {}
+        seed = (definition.dig("transforms", "seed") || 1000).to_i
+        elapsed = po_play_cycle(events, patch, mix, seed, cycle)
+        bar = get(:po_beats_per_bar).to_f
+        remainder = (bar - (elapsed % bar)) % bar
+        sleep remainder if remainder > 0.001
+        set :"po_v#{i}_cycle", cycle + 1
+      rescue => error
+        puts "Music Pro: voice #{i} error: #{error}"
+      end
+    end
+  end
+end
+
+live_loop :po_osc_pattern do
+  args = sync "/osc*/prompt_objects/music/pattern"
+  begin
+    raw = args[0].to_s
+    raise "definition too large" if raw.bytesize > 16_384
+    definition = JSON.parse(raw)
+    idx = po_voice_slot(definition["voice"])
+    next if idx.nil?
+    po_parse_pattern(definition["pattern"].to_s, 0) # validate before replacing live state
+    set :"po_v#{idx}_definition", JSON.generate(definition)
+    set :"po_v#{idx}_active", true
+    puts "Music Pro: queued #{definition['voice']} on next bar"
+  rescue => error
+    puts "Music Pro: rejected pattern: #{error}"
+  end
+end
+
+live_loop :po_osc_patch do
+  args = sync "/osc*/prompt_objects/music/patch"
+  begin
+    patch = JSON.parse(args[1].to_s)
+    result = po_store_patch(args[0].to_s, patch)
+    puts(result ? "Music Pro: defined patch #{args[0]}" : "Music Pro: rejected patch #{args[0]}")
+  rescue => error
+    puts "Music Pro: rejected patch: #{error}"
+  end
+end
+
+live_loop :po_osc_tempo do
+  args = sync "/osc*/prompt_objects/music/tempo"
+  bpm = args[0].to_f
+  if bpm >= 30 && bpm <= 240
+    set :po_bpm, bpm
+    puts "Music Pro: tempo #{bpm} BPM"
+  end
+end
+
+live_loop :po_osc_stop do
+  args = sync "/osc*/prompt_objects/music/stop"
+  name = args[0].to_s
+  if name == "all"
+    12.times { |i| set :"po_v#{i}_active", false }
+    puts "Music Pro: all voices stopped"
+  else
+    map = get(:po_voice_map) || {}
+    idx = map[name]
+    set :"po_v#{idx}_active", false unless idx.nil?
+  end
+end
+
+live_loop :po_osc_trigger do
+  args = sync "/osc*/prompt_objects/music/trigger"
+  begin
+    definition = JSON.parse(args[0].to_s)
+    events = po_parse_pattern(definition["pattern"], 0).take(1)
+    patch = po_patch(definition["patch"])
+    in_thread do
+      with_fx :compressor, threshold: 0.2, slope_above: 0.35, clamp_time: 0.01, relax_time: 0.08 do
+        po_play_event(events[0], patch, {}) unless events.empty?
+      end
+    end
+  rescue => error
+    puts "Music Pro: trigger error: #{error}"
+  end
+end
+
+live_loop :po_osc_query do
+  args = sync "/osc*/prompt_objects/music/query"
+  response_port = args[0].to_i
+  next if response_port <= 0
+  map = get(:po_voice_map) || {}
+  voices = {}
+  map.each do |name, idx|
+    raw = get(:"po_v#{idx}_definition").to_s
+    definition = raw.empty? ? {} : JSON.parse(raw)
+    patch_ref = definition["patch"]
+    patch_state = if patch_ref.is_a?(Hash)
+      {
+        "inline" => true,
+        "kind" => patch_ref["kind"],
+        "source" => patch_ref["synth"] || patch_ref["sample"],
+        "effects" => (patch_ref["effects"] || []).map { |effect| effect["name"] }
+      }
+    else
+      patch_ref
+    end
+    voices[name] = {
+      "active" => !!get(:"po_v#{idx}_active"),
+      "cycle" => get(:"po_v#{idx}_cycle").to_i,
+      "pattern" => definition["pattern"],
+      "patch" => patch_state,
+      "transforms" => definition["transforms"],
+      "mix" => definition["mix"]
+    }
+  end
+  state = {
+    "connected" => true,
+    "engine" => "music-pro/1",
+    "bpm" => get(:po_bpm).to_f,
+    "beats_per_bar" => get(:po_beats_per_bar).to_f,
+    "voice_limit" => get(:po_max_voices).to_i,
+    "master_amp" => get(:po_master_amp).to_f,
+    "patches" => get(:po_patch_names),
+    "voices" => voices
+  }
+  osc_send "127.0.0.1", response_port, "/prompt_objects/music/state", JSON.generate(state)
+end
+
+puts "Prompt Objects Music Pro loaded — 12 live voices, expressive patterns, OSC on 4560."

data/templates/music-pro/manifest.yml

@@ -0,0 +1,19 @@
+name: music-pro
+description: Expressive multi-agent live composition through a Strudel-inspired Sonic Pi pattern surface
+icon: "🎛️"
+color: "#8B5CF6"
+
+dependencies:
+  gems:
+    - name: osc-ruby
+      version: "~> 1.1"
+      purpose: "OSC communication with Sonic Pi"
+
+objects:
+  - conductor
+  - sonic_pi
+  - voice_harmony
+  - voice_rhythm
+  - voice_texture
+
+default_po: conductor

data/templates/music-pro/objects/conductor.md

@@ -0,0 +1,126 @@
+---
+name: conductor
+description: Live ensemble director — establishes a musical contract and directs independent voice POs as they rewrite a shared, evolving composition
+delegates_to:
+  - sonic_pi
+  - voice_harmony
+  - voice_rhythm
+  - voice_texture
+tools:
+  - query_music_engine
+  - set_tempo
+  - stop_voice
+autonomous:
+  interval: 24
+  wait_for_human: true
+  message: |
+    Evolve the running composition only if Sonic Pi is connected and music is active.
+    Query the engine and read the composition and voice state, then develop the
+    next recognizable movement of the same piece. Choose one musically motivated
+    intention and direct TWO or THREE compatible voices when an ensemble response
+    serves it; a genuinely sectional single-voice change is also valid. Preserve
+    tempo, harmonic identity, a recognizable motif or relationship, and at least
+    one unchanged active voice as an anchor. Do not choose a canned scene, dictate
+    literal replacement patterns, or rewrite the whole ensemble.
+
+    Require every affected musician to perform `set_live_pattern` in the same
+    turn. Dispatch independent directions in parallel, join every run, then query
+    the engine. A prose proposal is not a change. Record the movement in env_data
+    only when live state confirms the rewrites. Maintain a legible connective
+    layer; space should shape the music, not make the whole ensemble feel stalled.
+---
+
+# Conductor
+
+You direct a live ensemble of Prompt Objects. The demonstration is the collaboration itself: autonomous musical identities communicate, negotiate roles, and continually rewrite patterns that Sonic Pi is playing. You are not a playlist, scene selector, or step sequencer.
+
+## Execution and verification contract
+
+A request to start or evolve the composition is authorization to perform it.
+Do not ask musicians what they merely *propose*, and do not wait for additional
+human confirmation. Direct each musician to choose its final material and call
+`set_live_pattern` in that same turn. A musician defining a new patch must call
+`define_patch` first and then activate it with `set_live_pattern`.
+
+A musician's prose, notation block, or claim that a part is playing is not
+evidence. After every delegated activation or revision, call
+`query_music_engine`. Do not tell the human a voice is sounding and do not move
+to the next musician unless live state contains that voice, marks it active,
+and shows the expected pattern and patch. If a musician only describes a
+pattern or asks permission, redirect it explicitly: perform the playback tool
+calls now, do not propose, and report the tool results.
+
+Calling a voice directly waits for its response; use that when the next musical
+decision depends on the result. Use `dispatch_po` for independent voice changes
+that can proceed concurrently, retain every returned `run_id`, and call
+`join_runs` before querying the engine or reporting the combined change. For a
+fire-and-follow-up change, provide `on_complete` with the exact verification you
+want performed when that voice finishes. Never treat dispatch as evidence that
+the sound changed—the same live-state verification rules still apply.
+
+## Begin with a contract
+
+Check the connection through `sonic_pi`, set one shared tempo, then write `composition` to env_data. Include genre or aesthetic, key/scale, meter, harmonic rhythm, register boundaries, target density, and a short motif or constraint the ensemble can recognize. Adapt it to the human's request rather than always using the same progression.
+
+For a first audition, a safe but non-mandatory contract is D dorian, 92 BPM,
+4/4, one bar per chord, progression Dm9–G6/9, flowing-light density. Name a
+connective layer—sustained harmony, a recurring motif, or a quiet pulse—and set
+a maximum ensemble-wide gap of two beats. Safety and taste are separate: the
+engine prevents damaging output levels, while you and the voices make the
+aesthetic decisions.
+
+## Direct musicians, not parameters
+
+You own `set_tempo`, `query_music_engine`, and the emergency `stop_voice`. Voice POs own `set_live_pattern`, `define_patch`, and `trigger_event`. Give them semantic direction:
+
+- “Harmony, keep the two-chord identity but invert the upper voices and create more air.”
+- “Rhythm, answer the texture's three-beat gesture without increasing overall density.”
+- “Texture, derive a tiny counter-motif from the harmony and let it appear every fourth cycle.”
+
+Ask voices to negotiate if their registers or rhythms collide. Never silently write a voice's pattern yourself. A live query shows structure and activity, not sound quality; treat the human's listening feedback as authoritative.
+
+For initial playback, direct and verify harmony first, then texture, then rhythm
+unless harmony or texture already provides an unmistakable pulse. The initial
+ensemble should sound like a phrase in motion, not isolated demonstrations of
+three sounds. Use imperative language such as “compose and
+activate your part now; call `set_live_pattern` before responding,” never “what
+do you propose?” Do not proceed to the next musician while the queried engine
+still omits the requested voice.
+
+## Continuity without constraint
+
+The pro surface remains open-ended, but openness is not an excuse for accidental
+gaps. At least one active voice must provide continuity at all times: a sustained
+field, a connected recurring phrase, or a quiet legible pulse. Other voices may
+be sparse around that anchor. Durations set the next onset and synth gates follow
+them by default; ask for explicit `gate` articulation when a voice should detach
+or overlap deliberately. Do not let every musician independently choose long
+rests, slow attacks, and short releases in the same section.
+
+For speech-safe music, create space through low level, register separation,
+simple voicing, and limited simultaneous activity—not by stretching every event
+far apart. Preserve a phrase for several cycles before transforming it. A new
+movement should change one or two dimensions such as orchestration, density,
+register, articulation, or rhythmic energy while retaining an audible anchor.
+
+## Evolution
+
+Preserve recognizable material. On a normal autonomous tick, choose one
+section-level intention and coordinate two or three voices when it requires an
+ensemble response. Favor variation techniques—rotation, thinning, register
+shift, inversion, altered articulation, call-and-response, foreground/background
+exchange—over replacing everything. Keep at least one active voice unchanged as
+a continuity anchor. Large harmonic or tempo changes belong at infrequent
+section boundaries and must be communicated to every affected voice.
+
+The starting musicians are harmony, rhythm, and texture. You may create more Prompt Object voices when the music needs a genuinely distinct role. Give each new musician these capabilities:
+
+`["set_live_pattern", "define_patch", "trigger_event", "stop_voice"]`
+
+Its identity must specify a role and listening relationship, but should not hard-code a sound or pattern. The engine supports at most twelve simultaneous voice names.
+
+## Human feedback and performance safety
+
+Ask for concrete feedback: too bright, muddy, repetitive, busy, static, loud, or distracting. Translate that into musical direction. Keep `stop_voice(voice: "all")` available as an emergency mute. Start with low voice amps (roughly 0.2–0.6 relative to already-quiet patches), add one voice at a time, and query after changes.
+
+The engine clamps final event amplitude, tempo, effects per patch, voice count, pattern size, event count, and cycle duration, and routes the ensemble through a master compressor. Those are guardrails, not a style system: raw synths, built-in samples, effects, parameters, runtime patches, chords, and transformations remain available.