agentvibes 5.12.0-alpha.0 → 5.13.0

package/.claude/hooks-windows/audio-cache-utils.ps1.user.bak

@@ -0,0 +1,119 @@
+#
+# File: .claude/hooks-windows/audio-cache-utils.ps1
+#
+# AgentVibes Audio Cache Utilities for Windows
+#
+
+param(
+    [Parameter(Position = 0)]
+    [ValidateSet('cleanup', 'stats', 'clear')]
+    [string]$Command
+)
+
+# Detect project-local audio dir (same logic as TTS scripts)
+$ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
+if (Test-Path $ProjectClaudeDir) {
+    $AudioDir = "$ProjectClaudeDir\audio"
+} else {
+    $AudioDir = "$env:USERPROFILE\.claude\audio"
+}
+
+function Ensure-AudioDir {
+    if (-not (Test-Path $AudioDir)) {
+        New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null
+    }
+}
+
+function Get-AudioCacheSize {
+    Ensure-AudioDir
+
+    if (-not (Test-Path $AudioDir)) {
+        return 0
+    }
+
+    $files = Get-ChildItem -Path $AudioDir -Filter "*.wav" -ErrorAction SilentlyContinue
+    $totalSize = 0
+
+    foreach ($file in $files) {
+        $totalSize += $file.Length
+    }
+
+    return $totalSize
+}
+
+function Format-FileSize {
+    param([long]$Size)
+
+    if ($Size -lt 1KB) { return "$Size B" }
+    if ($Size -lt 1MB) { return "{0:N2} KB" -f ($Size / 1KB) }
+    if ($Size -lt 1GB) { return "{0:N2} MB" -f ($Size / 1MB) }
+    return "{0:N2} GB" -f ($Size / 1GB)
+}
+
+function Get-CacheStats {
+    Ensure-AudioDir
+
+    $files = Get-ChildItem -Path $AudioDir -Filter "*.wav" -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum
+
+    $count = if ($files.Count -eq $null) { 0 } else { $files.Count }
+    $totalSize = if ($files.Sum -eq $null) { 0 } else { $files.Sum }
+
+    return @{
+        FileCount = $count
+        TotalSize = $totalSize
+        FormattedSize = Format-FileSize $totalSize
+    }
+}
+
+function Clear-Cache {
+    Ensure-AudioDir
+
+    $files = Get-ChildItem -Path $AudioDir -Filter "*.wav" -ErrorAction SilentlyContinue
+
+    if ($files.Count -eq 0) {
+        Write-Host "[OK] Cache already empty" -ForegroundColor Green
+        return
+    }
+
+    $stats = Get-CacheStats
+    Write-Host "[CLEANUP] Clearing $($stats.FileCount) audio files ($($stats.FormattedSize))" -ForegroundColor Yellow
+
+    foreach ($file in $files) {
+        Remove-Item $file.FullName -Force -ErrorAction SilentlyContinue
+    }
+
+    Write-Host "[OK] Cache cleared" -ForegroundColor Green
+}
+
+function Show-CacheStats {
+    Ensure-AudioDir
+
+    $stats = Get-CacheStats
+
+    Write-Host ""
+    Write-Host "[STATS] Audio Cache Statistics" -ForegroundColor Cyan
+    Write-Host "   Location: $AudioDir"
+    Write-Host "   Files: $($stats.FileCount)"
+    Write-Host "   Total Size: $($stats.FormattedSize)"
+    Write-Host ""
+}
+
+# Main command routing
+switch ($Command) {
+    'stats' {
+        Show-CacheStats
+    }
+
+    'cleanup' {
+        Clear-Cache
+    }
+
+    'clear' {
+        Clear-Cache
+    }
+
+    default {
+        Show-CacheStats
+    }
+}

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

@@ -146,7 +146,13 @@ switch ($Command) {
             Write-Output "Usage: language-manager.ps1 check-voice <voice-name>"
             exit 1
         }
-        $multilingual = @("Antoni", "Rachel", "Domi", "Bella", "Charlotte", "Matilda")
+        # AVI-S9.6 AC1: trimmed to names that exist in the 21-voice ElevenLabs
+        # catalog (src/services/provider-catalog.js ELEVENLABS_VOICES) — the
+        # list previously included "Antoni"/"Rachel"/"Domi"/"Charlotte", none of
+        # which exist there (the same class of bug design row 21 found in the
+        # now-deleted learn-manager.sh). Parity-asserted against the catalog by
+        # test/unit/provider-catalog-conformance.test.js.
+        $multilingual = @("Bella", "Matilda")
         if ($Arg1 -in $multilingual) { Write-Output "yes" } else { Write-Output "no" }
     }
 

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

@@ -29,6 +29,13 @@ if ($env:CLAUDE_PROJECT_DIR -and (Test-Path "$env:CLAUDE_PROJECT_DIR\.claude"))
 
 $PersonalityFile = Join-Path $ConfigClaudeDir "tts-personality.txt"
 
+# Load the generated Provider Catalog (SSOT) for the Piper default voice.
+# FAIL-SAFE: consumers probe `Get-Command Get-CatalogDefaultVoice` and fall back
+# to the legacy literal when the artifact is missing (installed-tree skew) —
+# mirrors voice-manager-windows.ps1 / play-tts-kokoro.ps1 (AVI-S9.3/9.4).
+$CatalogPs1 = Join-Path $ScriptDir 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) { . $CatalogPs1 }
+
 function Get-PersonalityData {
     param([string]$Personality, [string]$Field)
     $file = Join-Path $PersonalitiesDir "$Personality.md"
@@ -116,7 +123,15 @@ switch ($Command) {
 
         # Get assigned voice
         $assignedVoice = Get-PersonalityData $personality "piper_voice"
-        if (-not $assignedVoice) { $assignedVoice = "en_US-lessac-medium" }
+        if (-not $assignedVoice) {
+            # Fallback to default Piper voice — sourced from the generated Provider
+            # Catalog SSOT (AVI-S9.4). FAIL-SAFE: legacy literal if artifact missing.
+            $assignedVoice = $null
+            if (Get-Command Get-CatalogDefaultVoice -ErrorAction SilentlyContinue) {
+                $assignedVoice = Get-CatalogDefaultVoice -Provider 'piper'
+            }
+            if (-not $assignedVoice) { $assignedVoice = "en_US-lessac-medium" }
+        }
 
         if ($assignedVoice) {
             Write-Output "Switching to assigned voice: $assignedVoice"

package/.claude/hooks-windows/play-tts-kokoro.ps1

@@ -27,6 +27,20 @@ $ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
 $ProjectClaudeDir = Join-Path (Split-Path -Parent (Split-Path -Parent $ScriptPath)) ".claude"
 if (Test-Path $ProjectClaudeDir) { $ClaudeDir = $ProjectClaudeDir } else { $ClaudeDir = "$env:USERPROFILE\.claude" }
 
+# --- Default voice from the generated Provider Catalog (SSOT) -----------------
+# FAIL-SAFE: keep the literal fallback for installed-tree skew (mirrors play-tts.sh
+# PLAN_OK). The synth-time shape check below stays LENIENT (design §3.3) so a voice
+# from a newer kokoro model still degrades audibly instead of bricking.
+$KokoroDefault = "af_heart"
+$CatalogPs1 = Join-Path $ScriptPath 'provider-catalog.ps1'
+if (Test-Path $CatalogPs1) {
+    . $CatalogPs1
+    if (Get-Command Get-CatalogDefaultVoice -ErrorAction SilentlyContinue) {
+        $d = Get-CatalogDefaultVoice -Provider 'kokoro'
+        if ($d) { $KokoroDefault = $d }
+    }
+}
+
 $AudioDir  = "$ClaudeDir\audio"
 $ConfigDir = "$ClaudeDir\config"
 if (-not (Test-Path $AudioDir)) { New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null }
@@ -70,13 +84,15 @@ if ($VoiceOverride) {
 }
 # Kokoro voice ids look like af_heart, am_michael, bf_emma. Strip any ::display suffix.
 if ($VoiceName -match '::') { $VoiceName = ($VoiceName -split '::')[0] }
-if (-not $VoiceName) { $VoiceName = "af_heart" }
+if (-not $VoiceName) { $VoiceName = $KokoroDefault }
 
 # Security: validate voice id (lowercase prefix + underscore + name).
-# Rejects path-traversal / injection before it reaches the command line.
+# LENIENT shape check (design §3.3) — rejects path-traversal / injection but lets
+# an unknown-but-shape-valid voice from a newer kokoro model through; falls back
+# to the catalog default only on a shape violation.
 if ($VoiceName -notmatch '^[a-z]{2}_[a-z0-9_]+$') {
-    Write-Host "[WARNING] Invalid Kokoro voice '$VoiceName' - falling back to af_heart" -ForegroundColor Yellow
-    $VoiceName = "af_heart"
+    Write-Host "[WARNING] Invalid Kokoro voice '$VoiceName' - falling back to $KokoroDefault" -ForegroundColor Yellow
+    $VoiceName = $KokoroDefault
 }
 
 # --- Optional speed ----------------------------------------------------------

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

@@ -116,8 +116,9 @@ switch ($ActiveProvider) {
 # by the SSH-receiver watcher via -ProviderOverride).  This lets the Linux-side
 # audio-effects.cfg row for llm:claude-code specify "piper" and have it honoured
 # on Windows without requiring the Windows tts-provider.txt to be reconfigured.
-# Priority: lower than per-LLM $_LlmEngine (audio-effects.cfg row, set later), higher
-# than the global tts-provider.txt default set above.
+# Priority: an explicit -ProviderOverride is AUTHORITATIVE — it wins over both the
+# per-LLM $_LlmEngine column and the global tts-provider.txt default (see the
+# $ProviderOverride guard in the engine-resolution block below).
 if ($ProviderOverride) {
     switch ($ProviderOverride) {
         { $_ -in "windows-piper", "piper" } {
@@ -308,8 +309,30 @@ $PlanVoiceIsOverride = $false
 if ($ProviderOverride) {
     # A fresh -ProviderOverride for THIS request must win over any stale/inherited
     # AGENTVIBES_FORCE_PROVIDER in the environment (a validated allowlist only).
+    #
+    # The allowlist DERIVES from the Provider Catalog (SSOT): the Windows platform
+    # set PLUS the cross-platform forwarding aliases this script normalizes
+    # (piper→windows-piper, sapi→windows-sapi, and macos forwarded verbatim for
+    # SSH-relayed senders). FAIL-SAFE: the literal below is the legacy fallback
+    # used when the generated provider-catalog.ps1 is missing (installed-tree skew).
+    $ProviderOverrideAllowlist = @('piper','soprano','macos','windows-sapi','sapi','kokoro','windows-piper')
+    $__CatalogPs1 = Join-Path $ScriptPath 'provider-catalog.ps1'
+    if (Test-Path $__CatalogPs1) {
+        try {
+            . $__CatalogPs1
+            if (Get-Command Get-CatalogProvidersForPlatform -ErrorAction SilentlyContinue) {
+                $__WinSet = @(Get-CatalogProvidersForPlatform 'windows')
+                if ($__WinSet.Count -gt 0) {
+                    # Windows synth providers + the forwarding aliases play-tts.ps1 normalizes.
+                    $ProviderOverrideAllowlist = @($__WinSet + @('piper','sapi','macos') | Select-Object -Unique)
+                }
+            }
+        } catch {
+            # Keep the legacy fallback allowlist on any catalog load error.
+        }
+    }
     switch ($ProviderOverride) {
-        { $_ -in @('piper','soprano','macos','windows-sapi','sapi','kokoro','elevenlabs','windows-piper') } {
+        { $_ -in $ProviderOverrideAllowlist } {
             $env:AGENTVIBES_FORCE_PROVIDER = $ProviderOverride
         }
     }
@@ -522,6 +545,12 @@ else {
         # ENGINE column or the global tts-provider.txt default.
         $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
     }
+    elseif ($ProviderOverride) {
+        # An explicit -ProviderOverride (forwarded from the SSH payload's "provider"
+        # field, or a preview) is AUTHORITATIVE and was already applied above. Do NOT
+        # let the per-LLM ENGINE column override it, or a receiver whose llm row
+        # defaults to piper silently swallows a forwarded windows-sapi request.
+    }
     elseif ($_LlmEngine) {
         # Accept both canonical Windows names and the cross-platform aliases the TUI
         # writes (e.g. "piper" saved on a Linux/WSL install that is later read on

package/.claude/hooks-windows/provider-catalog.ps1

@@ -0,0 +1,140 @@
+# provider-catalog.ps1 — GENERATED FILE. DO NOT EDIT.
+# DO NOT EDIT — generated from src/services/provider-catalog.js
+# Regenerate with: node scripts/generate-provider-catalog.mjs
+# content-hash: sha256:5e717024f1250a8f54d07291256e532606dba7b4a15ab9589305d1af6bba7f35
+# Dot-source this file to load the catalog accessors; do not execute it.
+
+$script:AgentVibesCatalogVersion = '5e717024f1250a8f'
+
+$script:CatalogDefaults = @{
+  'soprano' = 'soprano-default'
+  'piper' = 'en_US-lessac-medium'
+  'kokoro' = 'af_heart'
+  'elevenlabs' = 'Sarah'
+  'macos' = 'Samantha'
+  'windows-sapi' = ''
+  'windows-piper' = 'en_US-lessac-medium'
+}
+
+$script:CatalogDisplayNames = @{
+  'soprano' = 'Soprano TTS'
+  'piper' = 'Piper TTS'
+  'kokoro' = 'Kokoro TTS'
+  'elevenlabs' = 'ElevenLabs'
+  'macos' = 'macOS Say'
+  'windows-sapi' = 'Windows SAPI'
+  'windows-piper' = 'Piper TTS'
+}
+
+$script:CatalogAlias = @{
+  'macos-say' = 'macos'
+  'say' = 'macos'
+  'sapi' = 'windows-sapi'
+}
+
+$script:CatalogPlatform = @{
+  'unix' = @('soprano','piper','kokoro','elevenlabs')
+  'darwin' = @('soprano','piper','kokoro','elevenlabs','macos')
+  'windows' = @('soprano','kokoro','windows-sapi','windows-piper')
+}
+
+$script:CatalogVoices = @{
+  'soprano' = @('soprano-default')
+  'piper' = @()
+  'kokoro' = @('af_heart','af_alloy','af_aoede','af_bella','af_jessica','af_kore','af_nicole','af_nova','af_river','af_sarah','af_sky','am_adam','am_echo','am_eric','am_fenrir','am_liam','am_michael','am_onyx','am_puck','bf_alice','bf_emma','bf_isabella','bf_lily','bm_daniel','bm_fable','bm_george','bm_lewis','jf_alpha','jf_gongitsune','jf_nezumi','jf_tebukuro','jm_kumo','zf_xiaobei','zf_xiaoni','zf_xiaoxiao','zf_xiaoyi','zm_yunxi','zm_yunxia','zm_yunyang','ef_dora','em_alex','em_santa','ff_siwis','hf_alpha','hm_omega','if_sara','im_nicola','pf_dora','pm_alex','pm_santa','kf_alpha','km_hyunsu')
+  'elevenlabs' = @('Sarah','Roger','Laura','Charlie','George','Callum','River','Harry','Liam','Alice','Matilda','Will','Jessica','Eric','Bella','Chris','Brian','Daniel','Lily','Adam','Bill')
+  'macos' = @()
+  'windows-sapi' = @()
+  'windows-piper' = @()
+}
+
+$script:CatalogElevenLabs = @{
+  'sarah' = 'EXAVITQu4vr4xnSDxMaL'
+  'roger' = 'CwhRBWXzGAHq8TQ4Fs17'
+  'laura' = 'FGY2WhTYpPnrIDTdsKH5'
+  'charlie' = 'IKne3meq5aSn9XLyUdCD'
+  'george' = 'JBFqnCBsd6RMkjVDRZzb'
+  'callum' = 'N2lVS1w4EtoT3dr4eOWO'
+  'river' = 'SAz9YHcvj6GT2YYXdXww'
+  'harry' = 'SOYHLrjzK2X1ezoPC6cr'
+  'liam' = 'TX3LPaxmHKxFdv7VOQHJ'
+  'alice' = 'Xb7hH8MSUJpSbSDYk0k2'
+  'matilda' = 'XrExE9yKIg1WjnnlVkGX'
+  'will' = 'bIHbv24MWmeRgasZH58o'
+  'jessica' = 'cgSgspJ2msm6clMCkdW9'
+  'eric' = 'cjVigY5qzO86Huf0OWal'
+  'bella' = 'hpp4J3VqNfWAUOO0d1Us'
+  'chris' = 'iP95p4xoKVk53GoZ742B'
+  'brian' = 'nPczCjzI2devNBz1zQrb'
+  'daniel' = 'onwK4e9ZLuTAKqWW03F9'
+  'lily' = 'pFZP5JQG7iQjIQuC4Bku'
+  'adam' = 'pNInz6obpgDQGcFmaJgB'
+  'bill' = 'pqHfZKP75CvOlQylNhV4'
+}
+
+function Get-CatalogCanonicalProvider {
+  param([Parameter(Mandatory)][string]$Provider)
+  $key = $Provider.Trim().ToLowerInvariant()
+  if ($script:CatalogDefaults.ContainsKey($key)) { return $key }
+  if ($script:CatalogAlias.ContainsKey($key)) { return $script:CatalogAlias[$key] }
+  return $null
+}
+
+function Get-CatalogDefaultVoice {
+  param([Parameter(Mandatory)][string]$Provider)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return $null }
+  return $script:CatalogDefaults[$p]
+}
+
+function Get-CatalogDisplayName {
+  param([Parameter(Mandatory)][string]$Provider)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return $Provider }
+  return $script:CatalogDisplayNames[$p]
+}
+
+function Get-CatalogProvidersForPlatform {
+  param([Parameter(Mandatory)][string]$Platform)
+  $key = $Platform.Trim().ToLowerInvariant()
+  if ($script:CatalogPlatform.ContainsKey($key)) { return $script:CatalogPlatform[$key] }
+  return @()
+}
+
+function Get-CatalogVoices {
+  param([Parameter(Mandatory)][string]$Provider)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return @() }
+  return $script:CatalogVoices[$p]
+}
+
+function Test-CatalogVoice {
+  param([Parameter(Mandatory)][string]$Provider, [Parameter(Mandatory)][AllowEmptyString()][string]$Voice)
+  $p = Get-CatalogCanonicalProvider $Provider
+  if ($null -eq $p) { return $null }
+  $lc = $Voice.Trim().ToLowerInvariant()
+  switch ($p) {
+    'kokoro' {
+      if ($script:CatalogVoices['kokoro'] -contains $lc) { return $lc }
+      return $null
+    }
+    'elevenlabs' {
+      if ($script:CatalogElevenLabs.ContainsKey($lc)) { return $script:CatalogElevenLabs[$lc] }
+      if ($Voice -match '^[A-Za-z0-9]{20}$') { return $Voice }
+      return $null
+    }
+    'soprano' {
+      if ($lc -eq '' -or $lc -eq 'soprano' -or $lc -eq 'soprano-default') { return 'soprano-default' }
+      return $null
+    }
+    { $_ -eq 'piper' -or $_ -eq 'windows-piper' } {
+      if ($Voice -match '^[a-z]{2,3}_[A-Z]{2}-' -or $Voice -like '*::*') { return $Voice }
+      return $null
+    }
+    default {
+      if ($Voice -ne '') { return $Voice }
+      if ($p -eq 'windows-sapi') { return '' }
+      return $null
+    }
+  }
+}

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

@@ -15,7 +15,25 @@ param(
 
 $ClaudeDir = "$env:USERPROFILE\.claude"
 $ProviderFile = "$ClaudeDir\tts-provider.txt"
-$ValidProviders = @('windows-piper', 'windows-sapi', 'soprano')
+# $ValidProviders DERIVES from the generated Provider Catalog (SSOT): the Windows
+# platform set (kokoro is cross-platform — play-tts-kokoro.ps1 exists; elevenlabs
+# is NOT playable on Windows and is therefore absent). Dot-source the generated
+# provider-catalog.ps1 and pull `windows`. FAIL-SAFE: the literal below is the
+# legacy fallback used when the catalog artifact is missing (installed-tree skew)
+# — mirrors AVI-S9.3's probe/fallback pattern. See AVI-S8.1 / AVI-S9.5.
+$ValidProviders = @('windows-piper', 'windows-sapi', 'soprano', 'kokoro')
+$__CatalogPs1 = Join-Path $PSScriptRoot 'provider-catalog.ps1'
+if (Test-Path $__CatalogPs1) {
+    try {
+        . $__CatalogPs1
+        if (Get-Command Get-CatalogProvidersForPlatform -ErrorAction SilentlyContinue) {
+            $__WinSet = @(Get-CatalogProvidersForPlatform 'windows')
+            if ($__WinSet.Count -gt 0) { $ValidProviders = $__WinSet }
+        }
+    } catch {
+        # Keep the legacy fallback literal on any catalog load error.
+    }
+}
 
 # Ensure claude directory exists
 if (-not (Test-Path $ClaudeDir)) {
@@ -35,6 +53,14 @@ function Get-ActiveProvider {
 function Get-AvailableProviders {
     $available = @()
 
+    # Fast path: skip the live install probes (soprano HTTP + kokoro python
+    # spawns). Those probes are what make `provider list` occasionally stall for
+    # tens of seconds under load; when the caller only needs the provider NAMES
+    # (e.g. the parallel test harness, or an offline listing) set
+    # AGENTVIBES_PROVIDER_LIST_NO_PROBE=1 to report installed=$false without
+    # touching the network or spawning interpreters. Default behavior unchanged.
+    $noProbe = ($env:AGENTVIBES_PROVIDER_LIST_NO_PROBE -eq '1')
+
     # Always available
     $available += @{
         name = "windows-sapi"
@@ -59,15 +85,18 @@ function Get-AvailableProviders {
         $null = Get-Command soprano -ErrorAction Stop
         $sopranoInstalled = $true
     } catch {
-        # Also check if a Soprano server is running (try both API paths)
-        try {
-            $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/gradio_api/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
-            $sopranoInstalled = $true
-        } catch {
+        # Also check if a Soprano server is running (try both API paths) — unless
+        # the fast path is requested, in which case skip the network probes.
+        if (-not $noProbe) {
             try {
-                $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
+                $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/gradio_api/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
                 $sopranoInstalled = $true
-            } catch {}
+            } catch {
+                try {
+                    $null = Invoke-WebRequest -Uri "http://127.0.0.1:${sopranoPort}/info" -TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
+                    $sopranoInstalled = $true
+                } catch {}
+            }
         }
     }
 
@@ -77,6 +106,32 @@ function Get-AvailableProviders {
         installed = $sopranoInstalled
     }
 
+    # Check if Kokoro is installed. Mirror validateKokoroInstallation() in
+    # src/utils/provider-validator.js, but use importlib.util.find_spec so we do
+    # NOT actually import kokoro — importing the 82M-param neural lib takes
+    # several seconds and would make `provider list` hang (AVI-S8.1). find_spec
+    # only confirms the packages are importable, which is all we need here.
+    $kokoroInstalled = $false
+    $kokoroProbe = "import importlib.util as u,sys; sys.exit(0 if all(u.find_spec(m) for m in ('kokoro','soundfile','numpy')) else 1)"
+    foreach ($py in ($(if ($noProbe) { @() } else { @('py', 'python', 'python3') }))) {
+        if (-not (Get-Command $py -ErrorAction SilentlyContinue)) { continue }
+        try {
+            $null = & $py -c $kokoroProbe 2>$null
+            # Only stop once an interpreter actually HAS the packages — mirrors
+            # validateKokoroInstallation(), which tries every interpreter (the
+            # packages may live under python/python3, not the `py` launcher).
+            if ($LASTEXITCODE -eq 0) { $kokoroInstalled = $true; break }
+        } catch {
+            # interpreter present but failed to run the probe — try next
+        }
+    }
+
+    $available += @{
+        name = "kokoro"
+        description = "Kokoro TTS (Neural, pip install kokoro-onnx soundfile numpy)"
+        installed = $kokoroInstalled
+    }
+
     return $available
 }
 

package/.claude/hooks-windows/soprano-gradio-synth.py.user.bak

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+#
+# File: .claude/hooks-windows/soprano-gradio-synth.py
+#
+# AgentVibes - Finally, your AI Agents can Talk Back!
+# Website: https://agentvibes.org
+# Repository: https://github.com/paulpreibisch/AgentVibes
+#
+# Co-created by Paul Preibisch with Claude AI
+# Copyright (c) 2025 Paul Preibisch
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# ---
+#
+# Soprano Gradio WebUI synthesizer helper.
+# Calls the Soprano WebUI's Gradio API and saves the result as a WAV file.
+# Uses only Python stdlib (json, sys, urllib) — no extra dependencies.
+#
+# Usage: python3 soprano-gradio-synth.py "text to speak" output.wav [port]
+#
+"""
+Soprano Gradio WebUI synthesizer helper for AgentVibes.
+
+Calls the Soprano WebUI's Gradio API via the Server-Sent Events (SSE) protocol
+and downloads the generated audio as a WAV file.
+
+Flow:
+  1. Submit generation request -> get event_id
+  2. Poll SSE stream for audio file URL
+  3. Download WAV file to output path
+
+See: https://github.com/ekwek1/soprano
+"""
+import json
+import sys
+import urllib.request
+import urllib.error
+
+
+def synth(text: str, output_path: str, port: int = 7860) -> None:
+    base = f"http://127.0.0.1:{port}"
+
+    # Step 1: Submit generation request
+    # Args: text, temperature, top_p, repetition_penalty, chunk_size, streaming
+    payload = json.dumps({
+        "data": [text, 0.0, 0.95, 1.2, 1, False]
+    }).encode()
+
+    event_id = submit_request(base, payload)
+
+    # Step 2: Poll SSE stream for audio file URL
+    audio_url = poll_for_result(base, event_id)
+
+    # Step 3: Download the audio file (validate localhost to prevent SSRF)
+    download_file(audio_url, output_path, port)
+
+
+def submit_request(base: str, payload: bytes) -> str:
+    """Submit generation request to Gradio API, return event_id."""
+    for api_base in ["/gradio_api/call", "/call"]:
+        url = f"{base}{api_base}/generate_speech"
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                return json.loads(resp.read())["event_id"]
+        except urllib.error.URLError:
+            continue
+
+    raise RuntimeError("Could not reach Soprano WebUI API")
+
+
+def poll_for_result(base: str, event_id: str) -> str:
+    """Poll SSE endpoint until audio file URL is returned."""
+    for api_base in ["/gradio_api/call", "/call"]:
+        url = f"{base}{api_base}/generate_speech/{event_id}"
+        req = urllib.request.Request(url)
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                for raw_line in resp:
+                    line = raw_line.decode("utf-8", errors="replace").strip()
+                    if not line.startswith("data: "):
+                        continue
+                    try:
+                        parsed = json.loads(line[6:])
+                    except json.JSONDecodeError:
+                        continue
+                    # Response format: [{"path": "...", "url": "...", ...}, "status string"]
+                    if isinstance(parsed, list) and len(parsed) >= 1:
+                        audio = parsed[0]
+                        if isinstance(audio, dict) and "url" in audio:
+                            return audio["url"]
+            break
+        except urllib.error.URLError:
+            continue
+
+    raise RuntimeError("No audio URL in Soprano response")
+
+
+def download_file(url: str, output_path: str, port: int = 7860) -> None:
+    """Download audio file from Gradio file server.
+
+    Security: Validates URL points to localhost to prevent SSRF.
+    """
+    # Validate URL is localhost to prevent SSRF via crafted Gradio responses
+    allowed_prefixes = [
+        f"http://127.0.0.1:{port}/",
+        f"http://localhost:{port}/",
+    ]
+    if not any(url.startswith(prefix) for prefix in allowed_prefixes):
+        raise RuntimeError(f"Refused download from non-localhost URL: {url[:80]}")
+
+    req = urllib.request.Request(url)
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        with open(output_path, "wb") as f:
+            while True:
+                chunk = resp.read(8192)
+                if not chunk:
+                    break
+                f.write(chunk)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print(f"Usage: {sys.argv[0]} \"text\" output.wav [port]", file=sys.stderr)
+        sys.exit(1)
+
+    text = sys.argv[1]
+    output = sys.argv[2]
+    port = int(sys.argv[3]) if len(sys.argv) > 3 else 7860
+    if not (1 <= port <= 65535):
+        print(f"Error: Invalid port number: {port}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        synth(text, output, port)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)