agentvibes 5.12.0-alpha.0 → 5.12.0

package/.claude/github-star-reminder.txt

@@ -1 +1 @@
-20260704
+20260703

package/.claude/hooks/play-tts-ssh-remote.sh

@@ -34,8 +34,32 @@ fi
 # Default to "default" so remote always has an LLM key to look up
 LLM_NAME="${LLM_NAME:-default}"
 
-# Validate required input
-if [[ -z "$TEXT" ]]; then
+# Music-only preview mode: AGENTVIBES_MUSIC_ONLY=<track.mp3> tells the receiver to
+# play a standalone background-music track (no speech). Used by the Music tab's
+# remote preview so a track can be auditioned on the receiver. In this mode empty
+# TEXT is allowed and the track name is forwarded as the "music" field with
+# kind=music; the receiver resolves the file from its own ~/.claude/audio/tracks/.
+PAYLOAD_KIND="speak"
+MUSIC_ONLY_TRACK=""
+if [[ -n "${AGENTVIBES_MUSIC_STOP:-}" ]]; then
+  # Stop whatever music preview is currently playing on the receiver.
+  PAYLOAD_KIND="music-stop"
+elif [[ -n "${AGENTVIBES_MUSIC_ONLY:-}" ]]; then
+  # Only a bare .mp3 filename is allowed (no path separators, no leading dash) —
+  # the receiver resolves it against its own tracks dir, so reject path-like input.
+  if [[ "$AGENTVIBES_MUSIC_ONLY" =~ ^[A-Za-z0-9._][A-Za-z0-9._-]*\.mp3$ ]]; then
+    PAYLOAD_KIND="music"
+    MUSIC_ONLY_TRACK="$AGENTVIBES_MUSIC_ONLY"
+  else
+    echo "Invalid music track name: $AGENTVIBES_MUSIC_ONLY" >&2
+    exit 1
+  fi
+fi
+
+# Validate required input (music / music-stop modes carry no speech text)
+if [[ "$PAYLOAD_KIND" == "music" || "$PAYLOAD_KIND" == "music-stop" ]]; then
+  TEXT=""   # no speech in a music preview / stop
+elif [[ -z "$TEXT" ]]; then
   echo "Usage: $0 <text> [voice] [agent_name]" >&2
   exit 1
 fi
@@ -46,6 +70,9 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
 # Derive project name from directory
 PROJECT_NAME=$(basename "$PROJECT_ROOT")
+# Absolute path, forwarded so the receiver-side avatar can show/learn the real
+# remote folder (mirrors the local forward-to-avatar.sh's projectPath field).
+PROJECT_PATH="$PROJECT_ROOT"
 
 # ---------------------------------------------------------------------------
 # Get SSH connection details from config
@@ -365,24 +392,34 @@ build_json_payload() {
       --arg music "$BG_FILE" \
       --arg volume "$BG_VOLUME" \
       --arg project "$PROJECT_NAME" \
+      --arg projectPath "$PROJECT_PATH" \
       --arg pretext "$PRETEXT" \
       --arg speed "$SPEED" \
       --arg provider "$PROVIDER" \
       --arg llm "$LLM_NAME" \
       --arg mute "$MUTE" \
       --arg language "$LANGUAGE" \
-      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, pretext: $pretext, speed: $speed, provider: $provider, llm: $llm, mute: $mute, language: $language}'
+      --arg kind "$PAYLOAD_KIND" \
+      '{text: $text, voice: $voice, effects: $effects, music: $music, volume: $volume, project: $project, projectPath: $projectPath, pretext: $pretext, speed: $speed, provider: $provider, llm: $llm, mute: $mute, language: $language, kind: $kind}'
   else
     # Manual JSON — escape backslashes, quotes, control chars
     local escaped_text
     escaped_text=$(printf '%s' "$TEXT" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ' | sed 's/\r//g')
     local escaped_pretext
     escaped_pretext=$(printf '%s' "$PRETEXT" | sed 's/\\/\\\\/g; s/"/\\"/g')
-    printf '{"text":"%s","voice":"%s","effects":"%s","music":"%s","volume":"%s","project":"%s","pretext":"%s","speed":"%s","provider":"%s","llm":"%s","mute":"%s","language":"%s"}' \
-      "$escaped_text" "$VOICE" "$SOX_EFFECTS" "$BG_FILE" "$BG_VOLUME" "$PROJECT_NAME" "$escaped_pretext" "$SPEED" "$PROVIDER" "$LLM_NAME" "$MUTE" "$LANGUAGE"
+    local escaped_project_path
+    escaped_project_path=$(printf '%s' "$PROJECT_PATH" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    printf '{"text":"%s","voice":"%s","effects":"%s","music":"%s","volume":"%s","project":"%s","projectPath":"%s","pretext":"%s","speed":"%s","provider":"%s","llm":"%s","mute":"%s","language":"%s","kind":"%s"}' \
+      "$escaped_text" "$VOICE" "$SOX_EFFECTS" "$BG_FILE" "$BG_VOLUME" "$PROJECT_NAME" "$escaped_project_path" "$escaped_pretext" "$SPEED" "$PROVIDER" "$LLM_NAME" "$MUTE" "$LANGUAGE" "$PAYLOAD_KIND"
   fi
 }
 
+# Music-only preview: force the track as the "music" field (overriding any
+# per-LLM/agent background-music config) so the receiver plays exactly this track.
+if [[ "$PAYLOAD_KIND" == "music" ]]; then
+  BG_FILE="$MUSIC_ONLY_TRACK"
+fi
+
 JSON_PAYLOAD=$(build_json_payload)
 
 # SECURITY: Base64-encode entire payload — safe for SSH transport

package/.claude/hooks/play-tts.sh

@@ -329,7 +329,12 @@ case "$ACTIVE_PROVIDER" in
     # Transport — keep it.  The receiver's audio-effects.cfg picks the engine.
     ;;
   *)
-    if [[ -n "$_LLM_ENGINE" ]]; then
+    if [[ "$VOICE_OVERRIDE" =~ ^(af|am|bf|bm|jf|jm|kf|km|zf|zm|ff|fm|hf|hm|if|im|pf|pm|ef|em|nf|nm)_[a-zA-Z0-9]+$ ]]; then
+      # Kokoro-shaped voice override (e.g. af_heart) must win over the LLM row's
+      # engine column, else it is synthesized as a Piper voice, 404s downloading
+      # a model that doesn't exist, and stays silent. (Grafted from master WIP.)
+      ACTIVE_PROVIDER="kokoro"
+    elif [[ -n "$_LLM_ENGINE" ]]; then
       ACTIVE_PROVIDER="$_LLM_ENGINE"
     fi
     ;;
@@ -513,12 +518,17 @@ speak_text() {
     termux-ssh)
       bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$text" "$voice"
       ;;
-    ssh-remote)
+    ssh-remote|agentvibes-receiver)
+      # Both route through the base64-JSON sender that the modern receiver
+      # (templates/agentvibes-receiver.ps1 / .sh, installed as play-remote.*)
+      # understands. The old voiceless-connections sender spoke a 3-positional-arg
+      # protocol for a legacy ~/.agentvibes/play-remote.sh receiver that no current
+      # receiver install produces, so it delivered a non-base64 command the modern
+      # receiver rejects ("Payload must be base64-encoded"). play-tts-ssh-remote.sh
+      # resolves the host from any transport-config mode=remote entry (Priority 2b),
+      # so the agentvibes-receiver section is found without an ssh-remote section.
       bash "$SCRIPT_DIR/play-tts-ssh-remote.sh" "$text" "$voice" "" "${profile_file:-}"
       ;;
-    agentvibes-receiver)
-      bash "$SCRIPT_DIR/play-tts-agentvibes-receiver-for-voiceless-connections.sh" "$text" "$voice"
-      ;;
     *)
       echo "❌ Unknown provider: $provider" >&2
       return 1
@@ -653,12 +663,14 @@ case "$ACTIVE_PROVIDER" in
   termux-ssh)
     exec bash "$SCRIPT_DIR/play-tts-termux-ssh.sh" "$TEXT" "$VOICE_OVERRIDE"
     ;;
-  ssh-remote)
+  ssh-remote|agentvibes-receiver)
+    # Both route through the base64-JSON sender the modern receiver understands.
+    # The legacy voiceless-connections sender spoke a 3-arg protocol for an old
+    # ~/.agentvibes/play-remote.sh receiver that no current install produces, so it
+    # delivered a non-base64 command the modern receiver rejects with
+    # "Payload must be base64-encoded".
     exec bash "$SCRIPT_DIR/play-tts-ssh-remote.sh" "$TEXT" "$VOICE_OVERRIDE" "" "${AGENT_PROFILE_FILE:-}"
     ;;
-  agentvibes-receiver)
-    exec bash "$SCRIPT_DIR/play-tts-agentvibes-receiver-for-voiceless-connections.sh" "$TEXT" "$VOICE_OVERRIDE"
-    ;;
   *)
     echo "❌ Unknown provider: $ACTIVE_PROVIDER" >&2
     echo "   Run: /agent-vibes:provider list" >&2

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/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)

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

@@ -31,10 +31,65 @@ 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"
+                                    $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 to the
+                # TalkingHead forward so the avatar badge/tab shows the real remote
+                # origin instead of this machine's own profile dir. (Grafted from master WIP.)
+                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") }

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

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