agentvibes 5.3.0 → 5.5.0

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

@@ -1,138 +1,138 @@
-#
-# File: .claude/hooks-windows/play-tts-termux-ssh.ps1
-#
-# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
-# 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
-#
-# ---
-#
-# @fileoverview Termux SSH TTS Provider (Windows) - Android TTS via SSH tunnel
-# @context Enables TTS output on Android devices when connected via SSH from Windows
-# @architecture SSH-based remote TTS invocation using termux-tts-speak on Android
-# @dependencies ssh.exe (OpenSSH for Windows), termux-tts-speak (on Android), termux-api (on Android)
-# @entrypoints Called by play-tts.ps1 router when provider=termux-ssh
-# @patterns Remote TTS invocation, SSH host alias configuration, graceful fallback
-# @related play-tts.ps1, provider-manager.ps1
-#
-# SETUP INSTRUCTIONS:
-# ===================
-# 1. On Android device (Termux):
-#    - Install: pkg install termux-api openssh
-#    - Install Termux:API app from F-Droid or Google Play
-#    - Start SSH server: sshd
-#
-# 2. On Windows:
-#    - Add to %USERPROFILE%\.ssh\config:
-#      Host android
-#          HostName <your-android-ip>
-#          User <your-termux-username>
-#          Port 8022
-#          IdentityFile ~/.ssh/id_rsa
-#
-# 3. Configure AgentVibes:
-#    - echo android > %USERPROFILE%\.claude\termux-ssh-host.txt
-#    OR
-#    - echo android > .claude\termux-ssh-host.txt  (project-local)
-#
-# 4. Set provider:
-#    - echo termux-ssh > %USERPROFILE%\.claude\tts-provider.txt
-#
-
-param(
-    [Parameter(Mandatory = $true, Position = 0)]
-    [string]$Text,
-
-    [Parameter(Mandatory = $false, Position = 1)]
-    [string]$VoiceOverride  # Not used for termux-ssh, kept for interface compatibility
-)
-
-# Resolve ClaudeDir (project-local preferred, fallback to global)
-$ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
-$ProjectClaudeDir = Split-Path -Parent $ScriptPath
-if (Test-Path (Join-Path $ProjectClaudeDir "config")) {
-    $ClaudeDir = $ProjectClaudeDir
-} else {
-    $ClaudeDir = "$env:USERPROFILE\.claude"
-}
-
-# @function Get-SshHost
-# @intent Determine SSH host alias for Android device
-# @why Allows users to configure their own SSH connection without hardcoded values
-# Priority: env var > project config > script-dir config > global config
-function Get-SshHost {
-    if ($env:TERMUX_SSH_HOST) { return $env:TERMUX_SSH_HOST }
-
-    $projectFile = Join-Path $ClaudeDir "termux-ssh-host.txt"
-    if (Test-Path $projectFile) {
-        $val = (Get-Content $projectFile -Raw).Trim()
-        if ($val) { return $val }
-    }
-
-    $globalFile = "$env:USERPROFILE\.claude\termux-ssh-host.txt"
-    if (Test-Path $globalFile) {
-        $val = (Get-Content $globalFile -Raw).Trim()
-        if ($val) { return $val }
-    }
-
-    return ""
-}
-
-# @function Test-SshConnection
-# @intent Quick reachability check before sending TTS
-# @why Prevents long hangs if Android is offline
-function Test-SshConnection {
-    param([string]$SshTarget)
-    try {
-        $null = ssh -o ConnectTimeout=2 -o BatchMode=yes $SshTarget "echo ok" 2>&1
-        return $LASTEXITCODE -eq 0
-    } catch {
-        return $false
-    }
-}
-
-# --- Main ---
-
-if (-not $Text) {
-    Write-Host "[ERROR] No text provided for TTS" -ForegroundColor Red
-    exit 1
-}
-
-$SshAlias = Get-SshHost
-
-if (-not $SshAlias) {
-    Write-Host "[ERROR] Termux SSH provider not configured" -ForegroundColor Red
-    Write-Host "  Set SSH host alias in one of:" -ForegroundColor Yellow
-    Write-Host "    Environment:  `$env:TERMUX_SSH_HOST = 'android'" -ForegroundColor Yellow
-    Write-Host "    Global:       echo android > `"$env:USERPROFILE\.claude\termux-ssh-host.txt`"" -ForegroundColor Yellow
-    Write-Host "    Project:      echo android > .claude\termux-ssh-host.txt" -ForegroundColor Yellow
-    exit 1
-}
-
-if (-not (Test-SshConnection -SshTarget $SshAlias)) {
-    Write-Host "[WARNING] Cannot connect to SSH host '$SshAlias' - Android offline?" -ForegroundColor Yellow
-    exit 1
-}
-
-# Escape single quotes for safe shell transmission
-$SafeText = $Text -replace "'", "'\'''"
-
-# Send TTS to Android asynchronously (audio plays on device)
-$job = Start-Job -ScriptBlock {
-    param($alias, $text)
-    ssh -o ConnectTimeout=5 $alias "termux-tts-speak '$text'" 2>&1
-} -ArgumentList $SshAlias, $SafeText
-
-Write-Host "[OK] TTS sent to Android ($SshAlias) via SSH" -ForegroundColor Green
-
-# Output empty string — audio plays on Android, not locally
-Write-Output ""
+#
+# File: .claude/hooks-windows/play-tts-termux-ssh.ps1
+#
+# AgentVibes - Finally, your AI Agents can Talk Back! Text-to-Speech WITH personality for AI Assistants!
+# 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
+#
+# ---
+#
+# @fileoverview Termux SSH TTS Provider (Windows) - Android TTS via SSH tunnel
+# @context Enables TTS output on Android devices when connected via SSH from Windows
+# @architecture SSH-based remote TTS invocation using termux-tts-speak on Android
+# @dependencies ssh.exe (OpenSSH for Windows), termux-tts-speak (on Android), termux-api (on Android)
+# @entrypoints Called by play-tts.ps1 router when provider=termux-ssh
+# @patterns Remote TTS invocation, SSH host alias configuration, graceful fallback
+# @related play-tts.ps1, provider-manager.ps1
+#
+# SETUP INSTRUCTIONS:
+# ===================
+# 1. On Android device (Termux):
+#    - Install: pkg install termux-api openssh
+#    - Install Termux:API app from F-Droid or Google Play
+#    - Start SSH server: sshd
+#
+# 2. On Windows:
+#    - Add to %USERPROFILE%\.ssh\config:
+#      Host android
+#          HostName <your-android-ip>
+#          User <your-termux-username>
+#          Port 8022
+#          IdentityFile ~/.ssh/id_rsa
+#
+# 3. Configure AgentVibes:
+#    - echo android > %USERPROFILE%\.claude\termux-ssh-host.txt
+#    OR
+#    - echo android > .claude\termux-ssh-host.txt  (project-local)
+#
+# 4. Set provider:
+#    - echo termux-ssh > %USERPROFILE%\.claude\tts-provider.txt
+#
+
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false, Position = 1)]
+    [string]$VoiceOverride  # Not used for termux-ssh, kept for interface compatibility
+)
+
+# Resolve ClaudeDir (project-local preferred, fallback to global)
+$ScriptPath = Split-Path -Parent $MyInvocation.MyCommand.Path
+$ProjectClaudeDir = Split-Path -Parent $ScriptPath
+if (Test-Path (Join-Path $ProjectClaudeDir "config")) {
+    $ClaudeDir = $ProjectClaudeDir
+} else {
+    $ClaudeDir = "$env:USERPROFILE\.claude"
+}
+
+# @function Get-SshHost
+# @intent Determine SSH host alias for Android device
+# @why Allows users to configure their own SSH connection without hardcoded values
+# Priority: env var > project config > script-dir config > global config
+function Get-SshHost {
+    if ($env:TERMUX_SSH_HOST) { return $env:TERMUX_SSH_HOST }
+
+    $projectFile = Join-Path $ClaudeDir "termux-ssh-host.txt"
+    if (Test-Path $projectFile) {
+        $val = (Get-Content $projectFile -Raw).Trim()
+        if ($val) { return $val }
+    }
+
+    $globalFile = "$env:USERPROFILE\.claude\termux-ssh-host.txt"
+    if (Test-Path $globalFile) {
+        $val = (Get-Content $globalFile -Raw).Trim()
+        if ($val) { return $val }
+    }
+
+    return ""
+}
+
+# @function Test-SshConnection
+# @intent Quick reachability check before sending TTS
+# @why Prevents long hangs if Android is offline
+function Test-SshConnection {
+    param([string]$SshTarget)
+    try {
+        $null = ssh -o ConnectTimeout=2 -o BatchMode=yes $SshTarget "echo ok" 2>&1
+        return $LASTEXITCODE -eq 0
+    } catch {
+        return $false
+    }
+}
+
+# --- Main ---
+
+if (-not $Text) {
+    Write-Host "[ERROR] No text provided for TTS" -ForegroundColor Red
+    exit 1
+}
+
+$SshAlias = Get-SshHost
+
+if (-not $SshAlias) {
+    Write-Host "[ERROR] Termux SSH provider not configured" -ForegroundColor Red
+    Write-Host "  Set SSH host alias in one of:" -ForegroundColor Yellow
+    Write-Host "    Environment:  `$env:TERMUX_SSH_HOST = 'android'" -ForegroundColor Yellow
+    Write-Host "    Global:       echo android > `"$env:USERPROFILE\.claude\termux-ssh-host.txt`"" -ForegroundColor Yellow
+    Write-Host "    Project:      echo android > .claude\termux-ssh-host.txt" -ForegroundColor Yellow
+    exit 1
+}
+
+if (-not (Test-SshConnection -SshTarget $SshAlias)) {
+    Write-Host "[WARNING] Cannot connect to SSH host '$SshAlias' - Android offline?" -ForegroundColor Yellow
+    exit 1
+}
+
+# Escape single quotes for safe shell transmission
+$SafeText = $Text -replace "'", "'\'''"
+
+# Send TTS to Android asynchronously (audio plays on device)
+$job = Start-Job -ScriptBlock {
+    param($alias, $text)
+    ssh -o ConnectTimeout=5 $alias "termux-tts-speak '$text'" 2>&1
+} -ArgumentList $SshAlias, $SafeText
+
+Write-Host "[OK] TTS sent to Android ($SshAlias) via SSH" -ForegroundColor Green
+
+# Output empty string — audio plays on Android, not locally
+Write-Output ""

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

@@ -0,0 +1,178 @@
+#
+# File: .claude/hooks-windows/play-tts-windows-piper.ps1
+#
+# AgentVibes - Windows Piper TTS Provider
+# High-quality neural TTS using Piper.exe
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# Configuration paths
+$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"
+}
+
+# Audio cache and voice config use project-local .claude
+$AudioDir = "$ClaudeDir\audio"
+$VoiceFile = "$ClaudeDir\tts-voice-piper.txt"
+
+# Voices and Piper binary are global (shared across projects, ~100MB+)
+$UserClaudeDir = "$env:USERPROFILE\.claude"
+$VoicesDir = "$UserClaudeDir\piper-voices"
+$PiperExe = "$env:LOCALAPPDATA\Programs\Piper\piper.exe"
+
+# Ensure directories exist
+foreach ($dir in @($AudioDir, $VoicesDir)) {
+    if (-not (Test-Path $dir)) {
+        New-Item -ItemType Directory -Path $dir -Force | Out-Null
+    }
+}
+
+# Check if Piper is installed
+if (-not (Test-Path $PiperExe)) {
+    Write-Host "[ERROR] Piper not found at: $PiperExe" -ForegroundColor Red
+    Write-Host "Run: .\setup-windows.ps1 to install Piper" -ForegroundColor Yellow
+    exit 1
+}
+
+# Determine voice to use
+$VoiceName = ""
+
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride
+}
+elseif (Test-Path $VoiceFile) {
+    $VoiceName = (Get-Content $VoiceFile -Raw).Trim()
+}
+
+# Default voice if not specified
+if (-not $VoiceName) {
+    $VoiceName = "en_US-ryan-high"
+}
+
+# Security: Validate voice name to prevent path traversal
+# Only allow alphanumeric, underscore, hyphen, and period
+if ($VoiceName -notmatch '^[a-zA-Z0-9_\-\.]+$') {
+    Write-Host "[ERROR] Invalid voice name: $VoiceName" -ForegroundColor Red
+    exit 1
+}
+
+# Resolve voice model path and validate it stays within VoicesDir
+$VoiceModelFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx")
+$VoiceJsonFile = [System.IO.Path]::GetFullPath("$VoicesDir\$VoiceName.onnx.json")
+$ResolvedVoicesDir = [System.IO.Path]::GetFullPath($VoicesDir)
+if (-not $VoiceModelFile.StartsWith($ResolvedVoicesDir)) {
+    Write-Host "[ERROR] Voice path outside voices directory" -ForegroundColor Red
+    exit 1
+}
+
+# Check if voice model exists, download if missing
+if (-not (Test-Path $VoiceModelFile)) {
+    Write-Host "[DOWNLOAD] Voice model: $VoiceName" -ForegroundColor Yellow
+
+    # Try to download from Hugging Face
+    # Voice name format: {lang}_{region}-{speaker}-{quality}
+    # HF path format:    {lang}/{lang}_{region}/{speaker}/{quality}/{voicename}.onnx
+    try {
+        # Parse voice name to build correct HF path
+        # e.g. en_US-ryan-high -> en/en_US/ryan/high/en_US-ryan-high.onnx
+        if ($VoiceName -match '^([a-z]{2})_([A-Z]{2})-([a-zA-Z0-9_]+)-([a-z]+)$') {
+            $Lang = $Matches[1]
+            $LangRegion = "$($Matches[1])_$($Matches[2])"
+            $Speaker = $Matches[3]
+            $Quality = $Matches[4]
+            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/$Lang/$LangRegion/$Speaker/$Quality"
+        } else {
+            # Fallback for non-standard voice names
+            $HFBase = "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high"
+        }
+        $ModelUrl = "$HFBase/$VoiceName.onnx"
+        $JsonUrl = "$HFBase/$VoiceName.onnx.json"
+
+        Write-Host "   Downloading model..." -ForegroundColor Cyan
+        Invoke-WebRequest -Uri $ModelUrl -OutFile $VoiceModelFile -ErrorAction Stop
+        Write-Host "   Downloading config..." -ForegroundColor Cyan
+        Invoke-WebRequest -Uri $JsonUrl -OutFile $VoiceJsonFile -ErrorAction Stop
+        Write-Host "[OK] Voice model downloaded" -ForegroundColor Green
+    }
+    catch {
+        Write-Host "[ERROR] Failed to download voice model: $_" -ForegroundColor Red
+        Write-Host "Make sure you have internet connection" -ForegroundColor Yellow
+        exit 1
+    }
+}
+
+# Sanitize text for speech - strip shell metacharacters and PS special chars
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^$;"''()]', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+
+# Create audio file path
+$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss-ffff'
+$AudioFile = "$AudioDir\tts-$Timestamp.wav"
+
+# Synthesize with Piper
+try {
+    Write-Host "[SYNTH] Synthesizing with Piper..." -ForegroundColor Cyan
+
+    # Run Piper with text input
+    $Text | & $PiperExe `
+        --model $VoiceModelFile `
+        --output-file $AudioFile `
+        2>$null
+
+    if (-not (Test-Path $AudioFile)) {
+        Write-Host "[ERROR] Piper synthesis failed" -ForegroundColor Red
+        exit 1
+    }
+
+    # Display results
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $VoiceName (Piper)" -ForegroundColor Green
+
+    # Play the audio (skip if AGENTVIBES_NO_PLAY is set)
+    if (-not $env:AGENTVIBES_NO_PLAY) {
+        # Prefer ffplay: handles 22050 Hz → 48000 Hz resampling cleanly (SoundPlayer uses
+        # WinMM's low-quality resampler which produces choppy audio at non-native rates).
+        $ffplayPath = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+        if (-not $ffplayPath) {
+            # SSH/watcher sessions may have a minimal PATH — refresh from registry
+            $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" +
+                        [System.Environment]::GetEnvironmentVariable("Path","User")
+            $ffplayPath = (Get-Command ffplay -ErrorAction SilentlyContinue)?.Source
+        }
+        if ($ffplayPath) {
+            & $ffplayPath -autoexit -nodisp -loglevel quiet $AudioFile 2>$null
+        }
+        else {
+            $player = $null
+            try {
+                $player = New-Object System.Media.SoundPlayer $AudioFile
+                $player.PlaySync()
+            }
+            catch {
+                Write-Host "[WARNING] Could not play audio (SoundPlayer unavailable)" -ForegroundColor Yellow
+                Write-Host "Audio saved to: $AudioFile" -ForegroundColor Gray
+            }
+            finally {
+                if ($player) { $player.Dispose() }
+            }
+        }
+    }
+}
+catch {
+    Write-Host "[ERROR] Error running Piper: $_" -ForegroundColor Red
+    exit 1
+}

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

@@ -0,0 +1,108 @@
+#
+# File: .claude/hooks-windows/play-tts-windows-sapi.ps1
+#
+# AgentVibes - Windows SAPI TTS Provider (Zero Dependencies)
+# Uses built-in Windows System.Speech API
+#
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Text,
+
+    [Parameter(Mandatory = $false)]
+    [string]$VoiceOverride
+)
+
+# Configuration paths
+$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"
+$VoiceFile = "$ClaudeDir\tts-voice-sapi.txt"
+
+# Ensure directories exist
+if (-not (Test-Path $AudioDir)) {
+    New-Item -ItemType Directory -Path $AudioDir -Force | Out-Null
+}
+
+# Load System.Speech assembly
+try {
+    Add-Type -AssemblyName System.Speech
+}
+catch {
+    Write-Host "[ERROR] System.Speech assembly not available" -ForegroundColor Red
+    exit 1
+}
+
+# Determine voice to use
+$VoiceName = ""
+
+if ($VoiceOverride) {
+    $VoiceName = $VoiceOverride
+}
+elseif (Test-Path $VoiceFile) {
+    $VoiceName = (Get-Content $VoiceFile -Raw).Trim()
+}
+
+# Initialize speech synthesizer
+$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
+
+# Set voice if specified
+if ($VoiceName) {
+    try {
+        $synth.SelectVoice($VoiceName)
+    }
+    catch {
+        Write-Host "[WARNING] Voice '$VoiceName' not found, using default" -ForegroundColor Yellow
+    }
+}
+
+# Sanitize text for speech - strip shell metacharacters, PS special chars, and SSML tags
+$Text = $Text -replace '\\', ' '
+$Text = $Text -replace '[{}<>|`~^$;"''()]', ''
+$Text = $Text -replace '&[a-zA-Z]+;', ''
+$Text = $Text -replace '\s+', ' '
+$Text = $Text.Trim()
+
+# Get actual voice name (after selection or default)
+$ActualVoice = $synth.Voice.Name
+
+# Create audio file path
+$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss-ffff'
+$AudioFile = "$AudioDir\tts-$Timestamp.wav"
+
+# Save to WAV file with proper resource cleanup
+$player = $null
+try {
+    $synth.SetOutputToWaveFile($AudioFile)
+    $synth.Speak($Text)
+
+    # Display results
+    Write-Host "[OK] Saved to: $AudioFile" -ForegroundColor Green
+    Write-Host "[VOICE] Voice used: $ActualVoice (Windows SAPI)" -ForegroundColor Green
+
+    # Play the audio using built-in Windows audio player (skip if AGENTVIBES_NO_PLAY is set)
+    if (-not $env:AGENTVIBES_NO_PLAY) {
+        try {
+            $player = New-Object System.Media.SoundPlayer $AudioFile
+            $player.PlaySync()
+        }
+        catch {
+            Write-Host "[WARNING] Could not play audio (SoundPlayer unavailable)" -ForegroundColor Yellow
+        }
+    }
+}
+catch {
+    Write-Host "[ERROR] Error synthesizing speech: $_" -ForegroundColor Red
+    exit 1
+}
+finally {
+    if ($synth) { $synth.Dispose() }
+    if ($player) { $player.Dispose() }
+}