agentvibes 5.10.1 → 5.11.0

package/.claude/hooks-windows/kokoro-server.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+#
+# File: .claude/hooks/kokoro-server.py
+#
+# AgentVibes - Kokoro TTS persistent daemon
+# Loads the Kokoro model ONCE (on GPU when available) and serves synthesis over
+# a localhost HTTP socket, so each request skips the ~10s model-load + CUDA-init
+# cost that a fresh `python kokoro-tts.py` invocation pays every time.
+#
+# This is the difference between ~31s/message (cold process per call) and
+# ~2-3s/message (warm resident model).
+#
+# Endpoints (bound to 127.0.0.1 only — never exposed off-host):
+#   GET  /health  -> 200 {"ok":true} once the model is loaded and warmed
+#   POST /synth   -> body {text, voice, speed, output}; writes a WAV to `output`
+#                    and returns {"ok":true,"path":output} or {"ok":false,"error":...}
+#
+# Usage: python kokoro-server.py [port]   (default port 7855)
+#
+# Licensed under the Apache License, Version 2.0
+#
+import json
+import os
+import sys
+import tempfile
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+# A bad argv[1] (non-numeric) must not crash the daemon before it can bind;
+# fall back to the standard kokoro-server port.
+try:
+    PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 7855
+except (ValueError, IndexError):
+    PORT = 7855
+
+# Language code from the voice prefix (af/am=American, bf/bm=British, etc.)
+LANG_MAP = {
+    'af': 'a', 'am': 'a', 'bf': 'b', 'bm': 'b', 'jf': 'j', 'jm': 'j',
+    'kf': 'k', 'km': 'k', 'zf': 'z', 'zm': 'z', 'ff': 'f', 'fm': 'f',
+    'hf': 'h', 'hm': 'h', 'if': 'i', 'im': 'i', 'pf': 'p', 'pm': 'p',
+    'ef': 'e', 'em': 'e', 'nf': 'n', 'nm': 'n',
+}
+
+# Heavy imports up front so the model is resident before we accept connections.
+import numpy as np
+import soundfile as sf
+from kokoro import KPipeline
+
+_pipelines = {}
+_lock = threading.Lock()        # guards pipeline creation only
+_infer_lock = threading.Lock()  # serializes inference (torch is not thread-safe)
+
+
+def get_pipeline(lang_code):
+    """Return a cached KPipeline for the language, creating it once on demand."""
+    with _lock:
+        pipe = _pipelines.get(lang_code)
+        if pipe is None:
+            pipe = KPipeline(lang_code=lang_code)
+            _pipelines[lang_code] = pipe
+        return pipe
+
+
+def synth(text, voice, speed, output):
+    """Synthesize `text` with `voice` to the `output` WAV path. Returns the path."""
+    prefix = voice[:2].lower() if len(voice) >= 2 else 'af'
+    lang_code = LANG_MAP.get(prefix, 'a')
+    pipeline = get_pipeline(lang_code)
+
+    chunks = []
+    # The daemon shares one KPipeline across ThreadingHTTPServer worker threads
+    # and torch inference is not thread-safe — run one inference at a time. This
+    # lock is acquired after get_pipeline() has released _lock, so no deadlock.
+    with _infer_lock:
+        for result in pipeline(text, voice=voice, speed=speed):
+            audio = getattr(result, "audio", None)
+            if audio is None:
+                try:
+                    audio = result[-1]
+                except (TypeError, IndexError, KeyError):
+                    audio = None
+            if audio is None:
+                continue
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            audio = np.asarray(audio).reshape(-1)
+            if audio.size > 0:
+                chunks.append(audio)
+
+    if not chunks:
+        raise RuntimeError("Kokoro returned no audio samples")
+
+    sf.write(output, np.concatenate(chunks), 24000)  # kokoro is always 24 kHz
+    return output
+
+
+def _allowed_output_dirs():
+    """Directories a /synth request is permitted to write a WAV into.
+
+    Mirrors the shell hooks' audio-cache resolution (project-local first, then
+    the global ~/.claude/audio) plus TEMP, which is where the daemon writes its
+    own transient/warmup files.
+    """
+    dirs = []
+    proj = os.environ.get("CLAUDE_PROJECT_DIR")
+    if proj:
+        dirs.append(os.path.join(proj, ".claude", "audio"))
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    dirs.append(os.path.join(home, ".claude", "audio"))
+    dirs.append(os.environ.get("TEMP", "/tmp"))
+    return dirs
+
+
+def is_output_within_cache(output):
+    """True if `output` resolves inside an allowed audio dir (blocks traversal).
+
+    The daemon is shared across projects on a fixed port, so it cannot rely on
+    its own CLAUDE_PROJECT_DIR to know every project's audio dir. Accept the
+    home/TEMP locations plus any file that sits directly inside a ".claude/audio"
+    directory (the only place the providers ever write). realpath has already
+    collapsed any "..", so true traversal (e.g. /etc/x.wav) is still rejected.
+    """
+    tgt = os.path.realpath(output)
+    for base in _allowed_output_dirs():
+        base = os.path.realpath(base)
+        if tgt == base or tgt.startswith(base + os.sep):
+            return True
+    # Project-local audio dir for ANY project — the file must live directly in
+    # a ".claude/audio" directory.
+    parent = os.path.dirname(tgt).replace("\\", "/").lower()
+    if parent.endswith("/.claude/audio"):
+        return True
+    return False
+
+
+class Handler(BaseHTTPRequestHandler):
+    # Silence default per-request stderr logging
+    def log_message(self, *args):
+        pass
+
+    def _send(self, code, obj):
+        data = json.dumps(obj).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        try:
+            self.wfile.write(data)
+        except OSError:
+            # Client closed the socket early (health probes do this) — WinError
+            # 10053/10054 etc. Nothing to send to; ignore.
+            pass
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._send(200, {"ok": True})
+        else:
+            self._send(404, {"ok": False, "error": "not found"})
+
+    def do_POST(self):
+        if self.path != "/synth":
+            self._send(404, {"ok": False, "error": "not found"})
+            return
+        try:
+            length = int(self.headers.get("Content-Length", 0))
+            body = json.loads(self.rfile.read(length) or b"{}")
+            text = body["text"]
+            voice = body.get("voice", "af_heart")
+            speed = float(body.get("speed", 1.0))
+            output = body["output"]
+            # Output must be an absolute .wav path (the provider always supplies one)
+            if not isinstance(output, str) or not output.lower().endswith(".wav"):
+                raise ValueError("output must be a .wav path")
+            # Path-traversal guard: the resolved target must stay inside an
+            # allowed audio directory — reject before any file is written.
+            if not is_output_within_cache(output):
+                self._send(400, {"ok": False, "error": "output path outside allowed audio directory"})
+                return
+            synth(text, voice, speed, output)
+            self._send(200, {"ok": True, "path": output})
+        except Exception as e:  # noqa: BLE001 - report any failure to the client
+            self._send(500, {"ok": False, "error": str(e)})
+
+
+def main():
+    try:
+        import torch
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+    except Exception:
+        device = "cpu"
+
+    # Bind first so a second accidental launch fails fast (address in use) and
+    # exits instead of loading a second copy of the model.
+    try:
+        server = ThreadingHTTPServer(("127.0.0.1", PORT), Handler)
+    except OSError as e:
+        print(f"kokoro-server: port {PORT} unavailable ({e}); another instance is likely running", file=sys.stderr)
+        sys.exit(0)
+
+    # Warm the default English pipeline + trigger CUDA kernel compilation so the
+    # very first real /synth request is already fast.
+    warm_fd, warm_out = tempfile.mkstemp(suffix=".wav")
+    os.close(warm_fd)  # synth/soundfile reopens by path; we only need the name
+    try:
+        synth("ready", "af_heart", 1.0, warm_out)
+    except Exception as e:  # noqa: BLE001
+        print(f"kokoro-server: warmup failed (continuing): {e}", file=sys.stderr)
+    finally:
+        try:
+            os.remove(warm_out)
+        except OSError:
+            pass
+
+    print(f"kokoro-server ready on 127.0.0.1:{PORT} device={device}", flush=True)
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks-windows/kokoro-tts.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+AgentVibes — Kokoro TTS synthesizer
+Synthesizes text to a WAV file using the kokoro-onnx package.
+Prints the output WAV path to stdout.
+
+Usage: kokoro-tts.py <text> <voice> <output_path> [speed]
+
+Voices (examples):
+  af_heart  af_nova  af_sky  af_bella  af_sarah  af_nicole
+  am_adam   am_michael
+  bf_emma   bf_isabella
+  bm_george bm_lewis
+
+Install: pip install kokoro-onnx soundfile numpy
+"""
+
+import sys
+import os
+
+def main():
+    if len(sys.argv) < 4:
+        print("Usage: kokoro-tts.py <text> <voice> <output_path> [speed]", file=sys.stderr)
+        sys.exit(1)
+
+    text = sys.argv[1]
+    voice = sys.argv[2]
+    output_path = sys.argv[3]
+    try:
+        speed = float(sys.argv[4]) if len(sys.argv) > 4 else 1.0
+    except ValueError:
+        speed = 1.0
+
+    # Determine language code from voice prefix
+    # af/am = American English ('a'), bf/bm = British English ('b')
+    # jf/jm = Japanese ('j'), kf/km = Korean ('k'), etc.
+    prefix = voice[:2].lower() if len(voice) >= 2 else 'af'
+    lang_map = {
+        'af': 'a', 'am': 'a',  # American English
+        'bf': 'b', 'bm': 'b',  # British English
+        'jf': 'j', 'jm': 'j',  # Japanese
+        'kf': 'k', 'km': 'k',  # Korean
+        'zf': 'z', 'zm': 'z',  # Mandarin
+        'ff': 'f', 'fm': 'f',  # French
+        'hf': 'h', 'hm': 'h',  # Hindi
+        'if': 'i', 'im': 'i',  # Italian
+        'pf': 'p', 'pm': 'p',  # Brazilian Portuguese
+        'ef': 'e', 'em': 'e',  # Spanish (Spain)
+        'nf': 'n', 'nm': 'n',  # Spanish (Latin America)
+    }
+    lang_code = lang_map.get(prefix, 'a')
+
+    try:
+        from kokoro import KPipeline
+    except ImportError:
+        print("❌ kokoro-onnx not installed. Run: pip install kokoro-onnx soundfile numpy", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        import numpy as np
+        import soundfile as sf
+    except ImportError:
+        print("❌ soundfile/numpy not installed. Run: pip install soundfile numpy", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        pipeline = KPipeline(lang_code=lang_code)
+        generator = pipeline(text, voice=voice, speed=speed)
+
+        all_samples = []
+        sample_rate = 24000  # kokoro always outputs 24 kHz
+
+        for result in generator:
+            # kokoro >=0.9 yields a KPipeline.Result whose waveform is the
+            # `.audio` attribute (a torch.Tensor); older builds yield a
+            # (graphemes, phonemes, audio) tuple. Prefer `.audio`, then fall
+            # back to the last tuple element.
+            audio = getattr(result, "audio", None)
+            if audio is None:
+                try:
+                    audio = result[-1]
+                except (TypeError, IndexError, KeyError):
+                    audio = None
+            if audio is None:
+                continue
+            # Tensor -> numpy, force 1-D so np.concatenate never sees a 0-d array
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            audio = np.asarray(audio).reshape(-1)
+            if audio.size > 0:
+                all_samples.append(audio)
+
+        if not all_samples:
+            print("❌ Kokoro returned no audio samples", file=sys.stderr)
+            sys.exit(3)
+
+        combined = np.concatenate(all_samples)
+        sf.write(output_path, combined, sample_rate)
+        print(output_path)
+
+    except Exception as e:
+        print(f"❌ Kokoro synthesis failed: {e}", file=sys.stderr)
+        sys.exit(3)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,191 @@
+#
+# File: .claude/hooks-windows/play-tts-kokoro.ps1
+#
+# AgentVibes - Windows Kokoro TTS Provider
+# High-quality local neural TTS via the `kokoro` Python package (KPipeline).
+# Synthesizes text to a WAV file with kokoro-tts.py and emits the path so the
+# parent play-tts.ps1 router coordinates playback / effects / background music.
+#
+# Contract (mirrors play-tts-piper.ps1):
+#   - Receives $Text and optional $VoiceOverride (a Kokoro voice id, e.g. af_heart)
+#   - Synthesizes a WAV, optionally applies per-agent effects via audio-processor.ps1
+#   - Does NOT play audio; emits the final WAV path via Write-Output for the parent
+#
+# Install deps:  pip install kokoro soundfile numpy
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# --- Configuration paths (mirror play-tts-piper.ps1) -------------------------
+$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" }
+
+$AudioDir  = "$ClaudeDir\audio"
+$ConfigDir = "$ClaudeDir\config"
+if (-not (Test-Path $AudioDir)) { New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null }
+
+# --- Locate the kokoro synth helper (lives next to this script) --------------
+$KokoroPy = Join-Path $ScriptPath "kokoro-tts.py"
+if (-not (Test-Path $KokoroPy)) {
+    Write-Host "[ERROR] kokoro-tts.py not found at: $KokoroPy" -ForegroundColor Red
+    exit 1
+}
+
+# --- Resolve the Python executable -------------------------------------------
+# SSH-receiver watcher sessions can inherit a minimal PATH; refresh from the
+# registry if the first lookup fails (same pattern as play-tts-piper.ps1).
+function Find-Python {
+    foreach ($cand in @("python", "python3", "py")) {
+        $c = Get-Command $cand -ErrorAction SilentlyContinue
+        if ($c) { return $c.Source }
+    }
+    return $null
+}
+$PythonExe = Find-Python
+if (-not $PythonExe) {
+    $env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
+                [System.Environment]::GetEnvironmentVariable("Path", "User")
+    $PythonExe = Find-Python
+}
+if (-not $PythonExe) {
+    Write-Host "[ERROR] Python not found. Install Python 3, then: pip install kokoro soundfile numpy" -ForegroundColor Red
+    exit 1
+}
+
+# --- Determine the Kokoro voice ----------------------------------------------
+$VoiceName = ""
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride.Trim()
+} else {
+    $VoiceFile = "$ClaudeDir\tts-voice-kokoro.txt"
+    if (-not (Test-Path $VoiceFile)) { $VoiceFile = "$ClaudeDir\tts-voice.txt" }
+    if (Test-Path $VoiceFile) { $VoiceName = (Get-Content $VoiceFile -Raw).Trim() }
+}
+# 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" }
+
+# Security: validate voice id (lowercase prefix + underscore + name).
+# Rejects path-traversal / injection before it reaches the command line.
+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"
+}
+
+# --- Optional speed ----------------------------------------------------------
+$Speed = "1.0"
+$SpeedFile = "$ConfigDir\tts-speed.txt"
+if (Test-Path $SpeedFile) {
+    $s = (Get-Content $SpeedFile -Raw).Trim()
+    if ($s -match '^\d+(\.\d+)?$') { $Speed = $s }
+}
+
+# --- Sanitize text -----------------------------------------------------------
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^;]', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+if (-not $Text) { Write-Host "[ERROR] No text to synthesize" -ForegroundColor Red; exit 1 }
+
+# --- Output path (random name, no predictable timestamp; issue #130) ----------
+$AudioFile = "$AudioDir\tts-$([System.IO.Path]::GetRandomFileName() -replace '\..*').wav"
+
+# --- Persistent daemon configuration -----------------------------------------
+# A resident kokoro-server keeps the model loaded on the GPU so each request is
+# ~2-3s (just synthesis) instead of ~31s (fresh model load + CUDA init per call).
+# Fast path: POST to the daemon. Fallback: auto-start the daemon for next time,
+# and synthesize this one message directly so nothing is dropped while it warms.
+$KokoroPort = 7855
+$KokoroServerPy = Join-Path $ScriptPath "kokoro-server.py"
+
+function Test-KokoroServer {
+    try {
+        $r = Invoke-WebRequest -Uri "http://127.0.0.1:$KokoroPort/health" -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
+        return $r.StatusCode -eq 200
+    } catch { return $false }
+}
+
+function Start-KokoroServer {
+    if (-not (Test-Path $KokoroServerPy)) { return }
+    # Prefer pythonw.exe (no console window); fall back to python.exe hidden.
+    $pythonw = $PythonExe -replace 'python\.exe$', 'pythonw.exe'
+    $exe = if (Test-Path $pythonw) { $pythonw } else { $PythonExe }
+    try {
+        Start-Process -FilePath $exe -ArgumentList @($KokoroServerPy, "$KokoroPort") `
+            -WindowStyle Hidden -ErrorAction Stop | Out-Null
+    } catch {
+        Write-Host "[WARNING] Could not auto-start kokoro-server: $_" -ForegroundColor Yellow
+    }
+}
+
+# --- Synthesize --------------------------------------------------------------
+try {
+    $usedServer = $false
+    if (Test-KokoroServer) {
+        Write-Host "[SYNTH] Synthesizing with Kokoro daemon (voice=$VoiceName speed=$Speed)..." -ForegroundColor Cyan
+        try {
+            $payload = @{ text = $Text; voice = $VoiceName; speed = [double]$Speed; output = $AudioFile } | ConvertTo-Json -Compress
+            $resp = Invoke-WebRequest -Uri "http://127.0.0.1:$KokoroPort/synth" -Method POST `
+                -Body $payload -ContentType 'application/json' -TimeoutSec 120 -UseBasicParsing -ErrorAction Stop
+            if ($resp.StatusCode -eq 200 -and (Test-Path $AudioFile) -and (Get-Item $AudioFile).Length -gt 0) {
+                $usedServer = $true
+            } else {
+                Write-Host "[WARNING] Kokoro daemon returned no audio; falling back to direct synth" -ForegroundColor Yellow
+            }
+        } catch {
+            Write-Host "[WARNING] Kokoro daemon request failed ($_); falling back to direct synth" -ForegroundColor Yellow
+        }
+    }
+
+    if (-not $usedServer) {
+        # Daemon not up (or failed): start it for subsequent messages, then
+        # synthesize this one directly so the current message is never dropped.
+        Start-KokoroServer
+        Write-Host "[SYNTH] Synthesizing with Kokoro direct (voice=$VoiceName speed=$Speed)..." -ForegroundColor Cyan
+        $synthOut = & $PythonExe $KokoroPy $Text $VoiceName $AudioFile $Speed 2>&1
+        if (-not (Test-Path $AudioFile) -or (Get-Item $AudioFile).Length -eq 0) {
+            Write-Host "[ERROR] Kokoro synthesis failed" -ForegroundColor Red
+            if ($synthOut) { $synthOut | ForEach-Object { Write-Host "        $_" -ForegroundColor DarkGray } }
+            exit 1
+        }
+    }
+
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $VoiceName (Kokoro TTS)" -ForegroundColor Green
+
+    # Apply per-agent audio effects via audio-processor.ps1, but SKIP when
+    # AGENTVIBES_NO_PLAY is set - that means the parent play-tts.ps1 will do its
+    # own reverb / background-music post-processing and running effects here too
+    # would double-process the audio.
+    $ProcessorScript = Join-Path $ScriptPath "audio-processor.ps1"
+    $ProcessedFile = $AudioFile
+    if (-not $env:AGENTVIBES_NO_PLAY -and (Test-Path $ProcessorScript)) {
+        $AgentName = if ($env:AGENTVIBES_AGENT_NAME) { $env:AGENTVIBES_AGENT_NAME } elseif ($env:AGENTVIBES_LLM_KEY) { $env:AGENTVIBES_LLM_KEY } else { "default" }
+        $EffectedFile = "$AudioFile.effected.wav"
+        try {
+            & $ProcessorScript $AudioFile $AgentName $EffectedFile
+            if ((Test-Path $EffectedFile) -and (Get-Item $EffectedFile).Length -gt 0) {
+                $ProcessedFile = $EffectedFile
+                Write-Host "[EFFECTS] Audio effects applied" -ForegroundColor Cyan
+            }
+        } catch {
+            Write-Host "[WARNING] Audio effects processing skipped: $_" -ForegroundColor Yellow
+        }
+    }
+
+    # Emit the final path for the parent router to coordinate playback.
+    # DO NOT play here - play-tts.ps1 owns all audio playback.
+    Write-Host "[OUTPUT] Processed audio: $ProcessedFile" -ForegroundColor Gray
+    Write-Output $ProcessedFile
+}
+catch {
+    Write-Host "[ERROR] Error running Kokoro: $_" -ForegroundColor Red
+    exit 1
+}

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

@@ -102,6 +102,9 @@ switch ($ActiveProvider) {
     "soprano" {
         $ProviderScript = "$HooksDir\play-tts-soprano.ps1"
     }
+    "kokoro" {
+        $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
+    }
     default {
         Write-Host "[ERROR] Unknown provider: $ActiveProvider" -ForegroundColor Red
         Write-Host "Use: .\provider-manager.ps1 list" -ForegroundColor Yellow
@@ -126,6 +129,7 @@ if ($ProviderOverride) {
             if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-sapi.ps1" }
         }
         "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
+        "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
         default {
             Write-Host "[WARNING] play-tts.ps1: Unknown ProviderOverride '$ProviderOverride' ignored" -ForegroundColor Yellow
         }
@@ -382,7 +386,25 @@ if ($OverrideEffects -ne "" -and $OverrideEffects -in @("off", "light", "medium"
 # Transport providers (ssh-remote etc.) are not listed because they forward
 # TTS to a remote host — overriding with a local engine would synthesize on
 # the wrong machine.
-if ($_LlmEngine) {
+#
+# Voice/engine coupling guard: Kokoro voice ids follow a strict
+# "<2-letter prefix>_<name>" pattern where the 2nd char is the gender (f/m)
+# — e.g. af_river, am_eric, bf_emma, jf_alpha.  They are all-lowercase with no
+# locale, hyphen, digit, or "::" multi-speaker separator that Piper/LibriTTS
+# voices always carry, so the pattern can never match a Piper voice.  Such a
+# voice can ONLY be synthesised by the Kokoro engine.  When the active voice is
+# a Kokoro voice (e.g. the Kokoro voice picker preview, which sends
+# provider=kokoro + a Kokoro voice), the per-LLM ENGINE column — which may name
+# piper/sapi for that LLM's normal text responses that use Piper voices — must
+# NOT redirect it to an incompatible engine, or synthesis fails silently
+# (Piper can't find the Kokoro voice model → no audio, exit 0).
+$_VoiceIsKokoro = $VoiceOverride -match '^[a-z]{2}_[a-z0-9_]+$'
+if ($_VoiceIsKokoro) {
+    # A Kokoro-format voice forces the Kokoro engine regardless of the per-LLM
+    # ENGINE column or the global tts-provider.txt default.
+    $ProviderScript = "$HooksDir\play-tts-kokoro.ps1"
+}
+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
     # Windows, or "sapi" as a short form).  Unknown values keep the global default.
@@ -398,6 +420,7 @@ if ($_LlmEngine) {
             if (-not (Test-Path $ProviderScript)) { $ProviderScript = "$HooksDir\play-tts-windows-piper.ps1" }
         }
         "soprano" { $ProviderScript = "$HooksDir\play-tts-soprano.ps1" }
+        "kokoro" { $ProviderScript = "$HooksDir\play-tts-kokoro.ps1" }
         default {
             Write-Host "[INFO] play-tts.ps1: Unrecognised engine '$_LlmEngine' — keeping default provider" -ForegroundColor DarkGray
         }
@@ -428,6 +451,11 @@ if ($env:AGENTVIBES_VERBOSE -eq "1") {
 # ffplay uses libswresample with sinc resampling — no artefacts.
 function Invoke-AudioPlay {
     param([string]$FilePath)
+    # Stay silent while the automated test suite is running. The windows-tts/effects
+    # tests invoke this script and assert on its [VOICE]/routing output (printed
+    # earlier) — they never check playback — so skipping only the audio output keeps
+    # them green while preventing real speech on the developer's machine.
+    if (Test-Path (Join-Path $env:USERPROFILE ".agentvibes-tests-running")) { return }
     $ffplayCmd = Get-Command ffplay -ErrorAction SilentlyContinue
     $fp = if ($ffplayCmd) { $ffplayCmd.Source } else { $null }
     if (-not $fp) {