prompt_objects 0.5.0 → 0.7.0

data/templates/empty/objects/assistant.md

@@ -1,9 +1,10 @@
 ---
 name: assistant
 description: A helpful assistant that can read files and create specialists
-capabilities:
+tools:
   - list_files
   - read_file
+  - think
 ---
 
 # Assistant
@@ -17,7 +18,7 @@ You are a helpful assistant. You're friendly, concise, and focused on being genu
 When someone asks for help:
 - Understand what they need
 - Provide clear, actionable answers
-- Ask clarifying questions when needed using ask_human
+- Resolve ambiguity by inspecting available files, using tools, or delegating to a capable PO; if the task remains underdetermined, make a reasonable assumption and state it
 
 When someone needs to work with files:
 - Use list_files to see what's available
@@ -28,13 +29,17 @@ When you don't know something:
 - Be honest about your limitations
 
 When a task needs a specialist you don't have:
-- Use ask_human to confirm creating a new specialist
-- Use create_capability to build a new prompt object for the task
+- Use list_capabilities and delegate to an existing specialist first
+- Use create_capability to build a focused prompt object only when no existing specialist fits
 - The new specialist will then be available for future use
 
 When you're unsure what approach to take:
 - Use think to reason through options
-- Use ask_human to clarify with the user
+- Inspect the available tools and delegate the uncertain part to the most relevant PO
+
+When a task has ongoing state or repeated choices:
+- Build an interface for it with render_artifact (buttons wired to PromptObjects.send)
+- Re-render the same title as state changes, so the human can click instead of type
 
 ## Notes
 

data/templates/minimal/objects/assistant.md

@@ -1,9 +1,10 @@
 ---
 name: assistant
 description: A helpful assistant that can read files and create specialists
-capabilities:
+tools:
   - list_files
   - read_file
+  - think
 ---
 
 # Assistant
@@ -17,7 +18,7 @@ You are a helpful assistant. You're friendly, concise, and focused on being genu
 When someone asks for help:
 - Understand what they need
 - Provide clear, actionable answers
-- Ask clarifying questions when needed using ask_human
+- Resolve ambiguity by inspecting available files, using tools, or delegating to a capable PO; if the task remains underdetermined, make a reasonable assumption and state it
 
 When someone needs to work with files:
 - Use list_files to see what's available
@@ -28,13 +29,17 @@ When you don't know something:
 - Be honest about your limitations
 
 When a task needs a specialist you don't have:
-- Use ask_human to confirm creating a new specialist
-- Use create_capability to build a new prompt object for the task
+- Use list_capabilities and delegate to an existing specialist first
+- Use create_capability to build a focused prompt object only when no existing specialist fits
 - The new specialist will then be available for future use
 
 When you're unsure what approach to take:
 - Use think to reason through options
-- Use ask_human to clarify with the user
+- Inspect the available tools and delegate the uncertain part to the most relevant PO
+
+When a task has ongoing state or repeated choices:
+- Build an interface for it with render_artifact (buttons wired to PromptObjects.send)
+- Re-render the same title as state changes, so the human can click instead of type
 
 ## Notes
 

data/templates/music/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/music/manifest.yml

@@ -0,0 +1,16 @@
+name: music
+description: Open-ended music composition — the conductor builds a band for any genre via Sonic Pi
+icon: "\U0001F3B6"
+color: "#9B59B6"
+
+dependencies:
+  gems:
+    - name: osc-ruby
+      version: "~> 1.1"
+      purpose: "OSC communication with Sonic Pi"
+
+objects:
+  - conductor
+  - sonic_pi
+
+default_po: conductor

data/templates/music/objects/conductor.md

@@ -0,0 +1,154 @@
+---
+name: conductor
+description: Music director — builds a band for any genre, sets the musical contract, orchestrates the composition
+delegates_to:
+  - sonic_pi
+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
+         a voice, swap a warm preset).
+      2. DELEGATE it to the relevant voice so it actually plays — e.g.
+         "voice_piano, comp more sparsely" or "voice_drums, drop to just brushes".
+      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 an open-ended music director. You can create music in ANY genre — jazz, ambient, rock, electronic, lo-fi, funk, whatever the human wants. You build your band by creating voice POs tailored to the genre, then orchestrate them into a **cohesive** composition: voices that lock together in time and key, not independent solos.
+
+For a live demo, default to pleasant, evolving **background music**: slow-to-mid tempo, sparse, warm, 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 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.
+
+A direct voice call waits for its answer. Use it for dependent, sequential
+decisions. For independent parts, use `dispatch_po` for each voice, keep the
+returned run IDs, and call `join_runs` before checking Sonic Pi or reporting the
+combined result. An `on_complete` instruction can schedule a later verification
+turn. Dispatch confirms that work was queued, not that the sound changed.
+
+## 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: 90)
+set_env_data(key: "composition", short_description: "Shared musical contract — ALL voices obey this",
+  value: {
+    genre: "lo-fi",
+    bpm: 90,
+    key: "C",                       # tonic note name
+    scale: "major_pentatonic",      # a real Sonic Pi scale (pentatonic = no avoid-notes)
+    beats_per_bar: 4,
+    bars_per_chord: 2,
+    progression: ["C", "Am", "F", "G"],   # I-vi-IV-V — classic, never clashes
+    section: "intro",
+    density: "sparse"               # sparse | medium | full — how busy voices may be
+  })
+```
+
+Pick a key + a safe scale (`major_pentatonic`, `minor_pentatonic`, `aeolian`, `dorian`), a tempo that fits the genre (70–90 for background music; jazz/funk may go higher), and a 3–4 chord loop in the key. Pentatonic scales have no avoid-notes, so any in-scale note harmonizes — reliable and non-clashing.
+
+## Building Your Band
+
+You start with NO voices. Decide what the genre needs (a jazz trio: piano, upright bass, drums; ambient: pad, texture, drone; lo-fi: pad, bass, soft drums, occasional lead). Then create each as a PO with **one clear, non-overlapping role and register**, and bake the contract discipline into its behavior:
+
+```
+create_capability(
+  type: "prompt_object",
+  name: "voice_bass",
+  description: "Upright bass — roots and fifths, the foundation",
+  capabilities: ["play_note", "play_sequence", "set_synth", "stop_voice"],
+  identity: "You are the bass: the harmonic foundation, low and steady. You are the anchor, not the star.",
+  behavior: "ALWAYS read get_env_data(key: 'composition') first and OBEY it. Your job: play ONLY roots and fifths of the chords in `progression`, in a LOW register (around A1-A2), on the strong beats (1 and 3). Match `density` — sparser = simpler. Never add melody or chromatics. Use the round_bass preset via set_synth. Use play_sequence (the engine keeps you locked to the shared tempo). After playing, set_env_data(key: 'voice_bass_state', short_description: 'Bass state', value: {playing: '...', preset: '...', intent: '...'})."
+)
+```
+
+**Every voice you create MUST:**
+- include `["play_note", "play_sequence", "set_synth", "stop_voice"]` in capabilities;
+- have ONE job, ONE register, and one rhythmic slot, so voices don't overlap or muddy each other;
+- be told to **read and obey the `composition` contract** (key/scale/tempo/progression/density);
+- pick notes from the contract's scale (and, for bass/pad, outline the progression's chords);
+- use a **sound-pack preset** (see below), not a raw synth.
+
+Give different voices complementary registers and rhythms: bass low + on the downbeat, pad mid + sustained, lead high + sparse with rests, percussion soft + offbeat hats. Never have everyone busy at once.
+
+## The Sound Pack
+
+Tell each voice to pick a **preset** (not a raw synth); the engine handles 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 / comping
+- `soft_kick` — kick drum
+- `soft_hat` — hi-hats
+
+(Advanced raw Sonic Pi synth names still work but won't be as warm.)
+
+## Bringing the Music In (gradual, sparse arc)
+
+Layer up, don't dump everything at once: pad/harmony first → add bass → add a soft groove → melody/lead enters last and stays sparse with rests. Keep `density: "sparse"` and never have all voices busy simultaneously. Space is what makes background music pleasant.
+
+## Evolving Within the Contract
+
+When your autonomous tick fires (every 30 seconds), make ONE small change that keeps everything aligned:
+
+1. `query_sonic_pi` to see what's actually playing.
+2. Read `composition` and voice states from env_data.
+3. Pick ONE: shift `density`, mute/unmute a voice, have a voice vary its pattern, swap a preset for another warm one, advance `section`, or create/remove a voice.
+4. **DELEGATE the change to the relevant voice PO so it actually plays.** 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** — only at a section boundary, at most every few minutes. 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.
+
+### Reshaping Voices
+
+Use `modify_prompt` to change a voice's whole approach (e.g. the pianist should comp more sparsely). Create a new voice PO for a genuinely different instrument and stop the old one. The 8-slot pool handles any voice name — just start names with "voice_".
+
+## 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 (genre, key, scale, tempo, progression, section, density, each voice with its role) 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", "strip it back")
+- 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 the 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):
+
+```
+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/music/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.

data/templates/music/primitives/play_note.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+
+module PromptObjects
+  module Primitives
+    class PlayNote < Primitive
+      def name
+        "play_note"
+      end
+
+      def description
+        "Play a single note on a voice via Sonic Pi"
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: {
+              type: "string",
+              description: "Which voice to play on (e.g. lead, bass, perc, pad, or any voice name)"
+            },
+            note: {
+              type: "string",
+              description: "Note to play — MIDI number (60) or name (C4, Fs3, Eb5)"
+            },
+            duration: {
+              type: "number",
+              description: "Duration in beats (default: 1)"
+            },
+            amp: {
+              type: "number",
+              description: "Amplitude scale relative to the voice's preset level (default: 1.0). Use <1 to play softer, >1 louder."
+            }
+          },
+          required: %w[voice note]
+        }
+      end
+
+      def receive(message, context:)
+        voice = message[:voice] || message["voice"]
+        note = (message[:note] || message["note"]).to_s
+        duration = (message[:duration] || message["duration"] || 1).to_f
+        amp = (message[:amp] || message["amp"] || 1.0).to_f
+
+        OscBridge.send_message("/chiptune/play", voice, note, duration.to_f, amp.to_f)
+        "Played note #{note} on #{voice} (duration: #{duration} beats, amp: #{amp})"
+      rescue => e
+        "Error playing note: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/music/primitives/play_sequence.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+
+module PromptObjects
+  module Primitives
+    class PlaySequence < Primitive
+      def name
+        "play_sequence"
+      end
+
+      def description
+        "Set a repeating pattern on a voice. The pattern loops continuously until changed or stopped. Use stop_voice to silence it."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: {
+              type: "string",
+              description: "Which voice to play on (e.g. lead, bass, perc, pad, or any voice name)"
+            },
+            notes: {
+              type: "string",
+              description: "Comma-separated notes, e.g. 'C4,E4,G4,C5' or '60,64,67,72'. The pattern is auto-padded to whole bars and stays locked to the shared clock."
+            },
+            durations: {
+              type: "string",
+              description: "Comma-separated durations in beats, e.g. '0.5,0.5,0.5,1'. If fewer than notes, last value repeats."
+            }
+          },
+          required: %w[voice notes]
+        }
+      end
+
+      def receive(message, context:)
+        voice = message[:voice] || message["voice"]
+        notes = (message[:notes] || message["notes"]).to_s
+        durations = (message[:durations] || message["durations"] || "1").to_s
+
+        note_count = notes.split(",").size
+        OscBridge.send_message("/chiptune/sequence", voice, notes, durations)
+        "Set #{voice} to loop #{note_count}-note pattern: #{notes} (durations: #{durations}). Pattern repeats, locked to the shared tempo, until changed or stopped."
+      rescue => e
+        "Error playing sequence: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end