agentvibes 5.12.0-alpha.0 → 5.13.0

package/.claude/hooks-windows/tts-watcher.ps1

@@ -31,10 +31,76 @@ try {
             try { Rename-Item $f.FullName $procFile -ErrorAction Stop } catch { continue }
             try {
                 $req = Get-Content $procFile -Raw | ConvertFrom-Json
+
+                # Music preview: play/stop a standalone background-music track
+                # ASYNCHRONOUSLY (Start-Process) so it never blocks the TTS queue,
+                # tracking the ffplay PID so a new request (or an explicit stop)
+                # replaces the previous track instead of stacking playback.
+                #   kind=music       → stop any current preview, then play the track
+                #   kind=music-stop  → stop any current preview (no new playback)
+                if ($req.kind -eq 'music' -or $req.kind -eq 'music-stop') {
+                    $pidFile = Join-Path $env:USERPROFILE '.agentvibes\music-preview.pid'
+                    # Stop the currently-playing preview, if any. Verify the PID is
+                    # actually ffplay so a recycled PID can't kill an unrelated proc.
+                    if (Test-Path $pidFile) {
+                        $oldPid = (Get-Content $pidFile -Raw -ErrorAction SilentlyContinue).Trim()
+                        if ($oldPid -match '^\d+$') {
+                            $op = Get-Process -Id ([int]$oldPid) -ErrorAction SilentlyContinue
+                            if ($op -and $op.ProcessName -eq 'ffplay') { Stop-Process -Id ([int]$oldPid) -Force -ErrorAction SilentlyContinue }
+                        }
+                        Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+                    }
+                    if ($req.kind -eq 'music') {
+                        $trackName = [string]$req.music
+                        if ($trackName -match '^[A-Za-z0-9._][A-Za-z0-9._ \-]*\.mp3$') {
+                            $tracksDir = Join-Path $env:USERPROFILE '.claude\audio\tracks'
+                            $full     = [System.IO.Path]::GetFullPath((Join-Path $tracksDir $trackName))
+                            $baseFull = [System.IO.Path]::GetFullPath($tracksDir)
+                            if (-not $baseFull.EndsWith([IO.Path]::DirectorySeparatorChar)) { $baseFull += [IO.Path]::DirectorySeparatorChar }
+                            if ($full.StartsWith($baseFull, [StringComparison]::OrdinalIgnoreCase) -and (Test-Path $full)) {
+                                $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
+                                if ($ffplay) {
+                                    Write-WatcherLog "INFO" "music-preview id=$($req.id) track=$trackName"
+                                    # Readiness bling — a short cue played in THIS (audio-capable) watcher
+                                    # session BEFORE the track so a listener knows music is incoming. Launched
+                                    # async (NOT -Wait — the wav's shimmer tail is long); a fixed 0.3s gap then
+                                    # lets the music follow tightly. Best-effort: a missing wav / player error
+                                    # never blocks the track.
+                                    $blingWav = Join-Path $env:USERPROFILE '.claude\audio\ui\bling-success.wav'
+                                    if (-not (Test-Path $blingWav)) { $blingWav = Join-Path $env:USERPROFILE '.agentvibes\bling-success.wav' }
+                                    if (Test-Path $blingWav) {
+                                        try { Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet',$blingWav) -WindowStyle Hidden | Out-Null } catch { }
+                                        Start-Sleep -Milliseconds 300
+                                    }
+                                    $mp = Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet','-volume','80',$full) -WindowStyle Hidden -PassThru
+                                    if ($mp) { Set-Content -Path $pidFile -Value $mp.Id -NoNewline -ErrorAction SilentlyContinue }
+                                } else {
+                                    Write-WatcherLog "WARN" "ffplay not found - cannot preview music id=$($req.id)"
+                                }
+                            } else {
+                                Write-WatcherLog "WARN" "music track not found id=$($req.id) track=$trackName"
+                            }
+                        } else {
+                            Write-WatcherLog "WARN" "invalid music track name id=$($req.id)"
+                        }
+                    } else {
+                        Write-WatcherLog "INFO" "music-stop id=$($req.id)"
+                    }
+                    Remove-Item $procFile -Force -ErrorAction SilentlyContinue
+                    continue
+                }
+
                 # Validate voice before passing to command line
                 $safeVoice = if ($req.voice -and $req.voice -match '^[a-zA-Z0-9_\-\. :]+$') { $req.voice } else { "" }
                 $env:CLAUDE_PROJECT_DIR = $env:USERPROFILE
                 $env:AGENTVIBES_NO_PRETEXT = "1"
+                # Carry the sender's project (folder name/path) through so a
+                # downstream receiver shows the real remote origin instead of
+                # this machine's own profile dir.
+                if ($req.project) { $env:AGENTVIBES_PROJECT = $req.project }
+                else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_PROJECT", $null, "Process") }
+                if ($req.projectPath) { $env:AGENTVIBES_PROJECT_PATH = $req.projectPath }
+                else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_PROJECT_PATH", $null, "Process") }
                 # Use SetEnvironmentVariable to truly unset (assignment to $null leaves empty string)
                 if ($req.music)   { $env:AGENTVIBES_OVERRIDE_MUSIC   = $req.music }
                 else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_OVERRIDE_MUSIC",   $null, "Process") }
@@ -44,16 +110,26 @@ try {
                 else { [System.Environment]::SetEnvironmentVariable("AGENTVIBES_OVERRIDE_EFFECTS", $null, "Process") }
 
                 if (Test-Path $PlayTts) {
-                    # Play remote arrival prefix sound if configured
-                    $prefixSoundFile = "$env:USERPROFILE\.agentvibes\remote-prefix-sound.txt"
-                    if (Test-Path $prefixSoundFile) {
-                        $prefixSound = (Get-Content $prefixSoundFile -Raw).Trim()
-                        if ($prefixSound -and (Test-Path $prefixSound)) {
-                            $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
-                            if ($ffplay) {
-                                & $ffplay.Source -autoexit -nodisp -loglevel quiet $prefixSound 2>$null
+                    # Always play a crisp local "incoming" bling so the user KNOWS audio is
+                    # on the way — even when audio is routed to a downstream receiver
+                    # instead of the local speakers. Standard bling-success.wav, async
+                    # with a 0.3s gap (same as the music-preview path); fall back to the
+                    # user-configured remote-prefix-sound.txt if the bling wav is missing.
+                    $ffplay = Get-Command ffplay -ErrorAction SilentlyContinue
+                    if ($ffplay) {
+                        $blingWav = Join-Path $env:USERPROFILE '.claude\audio\ui\bling-success.wav'
+                        if (-not (Test-Path $blingWav)) { $blingWav = Join-Path $env:USERPROFILE '.agentvibes\bling-success.wav' }
+                        if (-not (Test-Path $blingWav)) {
+                            $prefixSoundFile = "$env:USERPROFILE\.agentvibes\remote-prefix-sound.txt"
+                            if (Test-Path $prefixSoundFile) {
+                                $ps = (Get-Content $prefixSoundFile -Raw).Trim()
+                                if ($ps -and (Test-Path $ps)) { $blingWav = $ps }
                             }
                         }
+                        if (Test-Path $blingWav) {
+                            try { Start-Process -FilePath $ffplay.Source -ArgumentList @('-autoexit','-nodisp','-loglevel','quiet',$blingWav) -WindowStyle Hidden | Out-Null } catch { }
+                            Start-Sleep -Milliseconds 300
+                        }
                     }
 
                     $tempText = Join-Path $env:TEMP "agentvibes-tts-$($req.id).txt"

package/.claude/hooks-windows/voice-manager-windows.ps1

@@ -17,6 +17,14 @@ $ClaudeDir = "$env:USERPROFILE\.claude"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
 $VoiceSapiFile = "$ClaudeDir\tts-voice-sapi.txt"
 $VoicePiperFile = "$ClaudeDir\tts-voice-piper.txt"
+$VoiceKokoroFile = "$ClaudeDir\tts-voice-kokoro.txt"
+
+# Load the generated Provider Catalog (SSOT) for kokoro switch-time validation.
+# FAIL-SAFE: consumers probe `Get-Command Test-CatalogVoice` and fall back to the
+# legacy shape regex when the artifact is missing (installed-tree skew) — mirrors
+# play-tts.sh's PLAN_OK legacy fallback. Switch never breaks on a missing catalog.
+$CatalogPs1 = Join-Path $PSScriptRoot 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) { . $CatalogPs1 }
 
 # Get active provider
 $ActiveProvider = "windows-sapi"
@@ -129,6 +137,47 @@ function Switch-Voice {
         Write-Host "[INFO] Soprano uses a single fixed voice (Soprano-1.1-80M)" -ForegroundColor Cyan
         return $true
     }
+    elseif ($ActiveProvider -eq "kokoro") {
+        # Kokoro switch-time validation via the generated Provider Catalog (SSOT):
+        # MEMBERSHIP + canonical case-fold, so a typo like af_hart is rejected HERE
+        # and never reaches tts-voice-kokoro.txt to die silently at the model.
+        # Escape hatch AGENTVIBES_ALLOW_UNLISTED_VOICE=1 bypasses MEMBERSHIP (not
+        # shape) so a voice from a newer kokoro model still switches. FAIL-SAFE:
+        # fall back to the legacy shape regex when the catalog artifact is missing.
+        $kokoroVoice = $NewVoice.ToLower()
+        $allowUnlisted = ($env:AGENTVIBES_ALLOW_UNLISTED_VOICE -eq '1')
+        if (Get-Command Test-CatalogVoice -ErrorAction SilentlyContinue) {
+            $canon = Test-CatalogVoice -Provider 'kokoro' -Voice $NewVoice
+            if ($canon) {
+                Set-Content -Path $VoiceKokoroFile -Value $canon
+                Write-Host "[OK] Voice set to: $canon" -ForegroundColor Green
+                return $true
+            }
+            elseif ($allowUnlisted -and $kokoroVoice -match '^[a-z]{2}_[a-z0-9_]+$') {
+                Write-Host "[WARN] '$NewVoice' is not in the shipped Kokoro catalog; allowing it (AGENTVIBES_ALLOW_UNLISTED_VOICE=1)." -ForegroundColor Yellow
+                Set-Content -Path $VoiceKokoroFile -Value $kokoroVoice
+                Write-Host "[OK] Voice set to: $kokoroVoice" -ForegroundColor Green
+                return $true
+            }
+            else {
+                Write-Host "[ERROR] Kokoro voice not found: $NewVoice" -ForegroundColor Red
+                Write-Host "That is not a known Kokoro voice. Examples: af_heart, am_michael, bf_emma, bm_george, jf_alpha, zf_xiaoxiao, ef_dora." -ForegroundColor Yellow
+                Write-Host "Set AGENTVIBES_ALLOW_UNLISTED_VOICE=1 to allow a newer-model voice." -ForegroundColor Yellow
+                return $false
+            }
+        }
+        else {
+            # FAIL-SAFE legacy path (catalog artifact missing): shape-only regex.
+            if ($kokoroVoice -notmatch '^[a-z]{2}_[a-z0-9_]+$') {
+                Write-Host "[ERROR] Kokoro voice not found: $NewVoice" -ForegroundColor Red
+                Write-Host "Kokoro ids look like <lang><sex>_name, e.g. af_heart, am_michael, bf_emma." -ForegroundColor Yellow
+                return $false
+            }
+            Set-Content -Path $VoiceKokoroFile -Value $kokoroVoice
+            Write-Host "[OK] Voice set to: $kokoroVoice" -ForegroundColor Green
+            return $true
+        }
+    }
 
     if ($ValidVoices -notcontains $NewVoice) {
         Write-Host "[ERROR] Voice not found: $NewVoice" -ForegroundColor Red

package/.claude/piper-voices-dir.txt

@@ -0,0 +1 @@
+C:\Users\Paul\.claude\piper-voices

package/.clawdbot/README.md

@@ -1,105 +1,105 @@
-# Clawdbot Integration
-
-AgentVibes TTS integration for Clawdbot - the AI assistant framework.
-
-## What is Clawdbot?
-
-Clawdbot is a powerful AI assistant framework that connects Claude AI to messaging platforms (WhatsApp, Telegram, Discord, etc.) and provides extensible skills.
-
-**Website**: https://clawd.bot
-**GitHub**: https://github.com/clawdbot/clawdbot
-
-## AgentVibes + Clawdbot
-
-This integration provides Clawdbot with professional TTS capabilities using AgentVibes:
-
-- **Free & Offline**: No API costs, works without internet
-- **50+ Voices**: Professional AI voices in 30+ languages
-- **Remote SSH Support**: Audio tunnels from server to local machine
-- **Zero Setup**: Automatic when AgentVibes is installed
-
-## Installation
-
-```bash
-npx agentvibes install
-```
-
-That's it! AgentVibes is ready to use.
-
-## Usage from Clawdbot
-
-Once installed, use AgentVibes for TTS:
-
-```bash
-npx agentvibes speak "Hello from Clawdbot"
-```
-
-## Features
-
-- **Automatic Detection**: Clawdbot automatically uses AgentVibes when available
-- **Voice Selection**: 50+ voices across 30+ languages
-- **SSH Tunneling**: Audio plays on local machine from remote servers
-- **Zero Config**: Works out of the box once AgentVibes is installed
-
-## Remote SSH Audio
-
-When running Clawdbot on a remote server, set up PulseAudio tunneling so audio plays on your local machine:
-
-**Quick Setup:**
-
-1. **Remote server** (`~/.bashrc`):
-```bash
-export PULSE_SERVER=tcp:localhost:14713
-```
-
-2. **Local machine** (`~/.ssh/config`):
-```
-Host your-server
-    RemoteForward 14713 localhost:14713
-```
-
-3. **Connect and test**:
-```bash
-ssh your-server
-agentvibes speak "Testing remote audio"
-```
-
-**Full guide**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/remote-audio-setup.md
-
-## Documentation
-
-- **Skill Documentation**: [skill/SKILL.md](skill/SKILL.md)
-- **AgentVibes Docs**: https://agentvibes.org
-- **Clawdbot Docs**: https://docs.clawd.bot
-
-## Architecture
-
-```
-Clawdbot Request
-    ↓
-AgentVibes Skill (this)
-    ↓
-AgentVibes CLI (agentvibes speak)
-    ↓
-Piper TTS Engine
-    ↓
-PulseAudio → SSH Tunnel → Local Speakers
-```
-
-## Development
-
-The skill is automatically packaged with AgentVibes npm releases. To update:
-
-1. Edit `skill/SKILL.md`
-2. Test with Clawdbot
-3. Commit to AgentVibes repo
-4. Publish new AgentVibes version
-
-## Support
-
-- **AgentVibes Issues**: https://github.com/paulpreibisch/AgentVibes/issues
-- **Clawdbot Issues**: https://github.com/clawdbot/clawdbot/issues
-
-## License
-
-Apache 2.0 - Same as AgentVibes
+# Clawdbot Integration
+
+AgentVibes TTS integration for Clawdbot - the AI assistant framework.
+
+## What is Clawdbot?
+
+Clawdbot is a powerful AI assistant framework that connects Claude AI to messaging platforms (WhatsApp, Telegram, Discord, etc.) and provides extensible skills.
+
+**Website**: https://clawd.bot
+**GitHub**: https://github.com/clawdbot/clawdbot
+
+## AgentVibes + Clawdbot
+
+This integration provides Clawdbot with professional TTS capabilities using AgentVibes:
+
+- **Free & Offline**: No API costs, works without internet
+- **50+ Voices**: Professional AI voices in 30+ languages
+- **Remote SSH Support**: Audio tunnels from server to local machine
+- **Zero Setup**: Automatic when AgentVibes is installed
+
+## Installation
+
+```bash
+npx agentvibes install
+```
+
+That's it! AgentVibes is ready to use.
+
+## Usage from Clawdbot
+
+Once installed, use AgentVibes for TTS:
+
+```bash
+npx agentvibes speak "Hello from Clawdbot"
+```
+
+## Features
+
+- **Automatic Detection**: Clawdbot automatically uses AgentVibes when available
+- **Voice Selection**: 50+ voices across 30+ languages
+- **SSH Tunneling**: Audio plays on local machine from remote servers
+- **Zero Config**: Works out of the box once AgentVibes is installed
+
+## Remote SSH Audio
+
+When running Clawdbot on a remote server, set up PulseAudio tunneling so audio plays on your local machine:
+
+**Quick Setup:**
+
+1. **Remote server** (`~/.bashrc`):
+```bash
+export PULSE_SERVER=tcp:localhost:14713
+```
+
+2. **Local machine** (`~/.ssh/config`):
+```
+Host your-server
+    RemoteForward 14713 localhost:14713
+```
+
+3. **Connect and test**:
+```bash
+ssh your-server
+agentvibes speak "Testing remote audio"
+```
+
+**Full guide**: https://github.com/paulpreibisch/AgentVibes/blob/master/docs/remote-audio-setup.md
+
+## Documentation
+
+- **Skill Documentation**: [skill/SKILL.md](skill/SKILL.md)
+- **AgentVibes Docs**: https://agentvibes.org
+- **Clawdbot Docs**: https://docs.clawd.bot
+
+## Architecture
+
+```
+Clawdbot Request
+    ↓
+AgentVibes Skill (this)
+    ↓
+AgentVibes CLI (agentvibes speak)
+    ↓
+Piper TTS Engine
+    ↓
+PulseAudio → SSH Tunnel → Local Speakers
+```
+
+## Development
+
+The skill is automatically packaged with AgentVibes npm releases. To update:
+
+1. Edit `skill/SKILL.md`
+2. Test with Clawdbot
+3. Commit to AgentVibes repo
+4. Publish new AgentVibes version
+
+## Support
+
+- **AgentVibes Issues**: https://github.com/paulpreibisch/AgentVibes/issues
+- **Clawdbot Issues**: https://github.com/clawdbot/clawdbot/issues
+
+## License
+
+Apache 2.0 - Same as AgentVibes

package/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "agentvibes": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--package=agentvibes",
+        "agentvibes-mcp-server"
+      ],
+      "env": {
+        "AGENTVIBES_MCP_FALLBACK": "copilot"
+      }
+    }
+  }
+}