agentvibes 5.3.0 → 5.5.0

package/templates/agentvibes-receiver.sh

@@ -1,483 +1,158 @@
-#!/usr/bin/env bash
-#
-# File: agentvibes-receiver.sh
-# Location: User installs to ~/.agentvibes/play-remote.sh
-#
-# AgentVibes SSH-TTS Receiver (v2 — self-contained pipeline)
-# Receives TTS requests via SSH, generates and plays audio locally.
-#
-# Supports two payload formats:
-#   1. JSON payload (v2): single base64-encoded JSON with all config
-#   2. Legacy positional args: base64_text voice_name (backward compat)
-#
-# Pipeline: TTS (piper|soprano|macos|windows-sapi) → sox effects → ffmpeg music mix → audio player
-# All steps run in foreground (required for SSH ForceCommand).
-#
-# Installation:
-#   curl -sSL https://raw.githubusercontent.com/paulpreibisch/AgentVibes/main/scripts/install-ssh-receiver.sh | bash
-#
-# Copyright (c) 2025 Paul Preibisch
-# Licensed under Apache-2.0
-#
-
-set -euo pipefail
-
-# ---------------------------------------------------------------------------
-# Environment setup for SSH ForceCommand context
-# ---------------------------------------------------------------------------
-
-# ForceCommand passes args via SSH_ORIGINAL_COMMAND env var
-# SECURITY: Use read -ra instead of eval to prevent command injection
-if [[ -n "${SSH_ORIGINAL_COMMAND:-}" ]]; then
-  read -ra _ssh_args <<< "$SSH_ORIGINAL_COMMAND"
-  set -- "${_ssh_args[@]}"
-fi
-
-# Handle -- argument separator (skip it if present)
-if [[ "${1:-}" == "--" ]]; then
-  shift
-fi
-
-# ---------------------------------------------------------------------------
-# Configuration — customize these for your installation
-# ---------------------------------------------------------------------------
-
-# Ensure common tool paths are available in restricted SSH context
-export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
-
-# All paths use $HOME — the receiver user's own home directory.
-# During install, voices and tracks are symlinked here from the desktop user.
-# This avoids needing access to another user's home directory.
-
-# Where piper voice models are stored
-VOICES_DIR="${AGENTVIBES_VOICES_DIR:-$HOME/.claude/piper-voices}"
-
-# Where background music tracks are stored
-TRACKS_DIR="${AGENTVIBES_TRACKS_DIR:-$HOME/.claude/audio/tracks}"
-
-# Log file — the TUI reads from this location
-LOG_FILE="${AGENTVIBES_RECEIVER_LOG:-$HOME/.agentvibes/receiver.log}"
-
-# PipeWire/PulseAudio — connect to the desktop user's audio session.
-# Cross-user audio is tricky: Unix sockets reject different-uid callers
-# even with ACLs. The reliable approach is localhost TCP on a fixed port.
-# The setup script configures PipeWire-Pulse to listen on 127.0.0.1:34567.
-AGENTVIBES_PULSE_PORT="${AGENTVIBES_PULSE_PORT:-34567}"
-
-if [[ -z "${PULSE_SERVER:-}" ]]; then
-  _own_runtime="/run/user/$(id -u)"
-  # Detect if we're the dedicated receiver user — always use TCP to reach
-  # the desktop user's audio session, even if we have our own pulse socket.
-  _is_receiver_user=false
-  [[ "$(whoami)" == "agentvibes-receiver" ]] && _is_receiver_user=true
-
-  if [[ "$_is_receiver_user" == true ]]; then
-    # Dedicated receiver user — must use TCP to desktop user's PipeWire-Pulse
-    export PULSE_SERVER="tcp:127.0.0.1:$AGENTVIBES_PULSE_PORT"
-  elif [[ -e "$_own_runtime/pulse/native" ]]; then
-    # Same user — use own Unix socket (fastest)
-    export PULSE_SERVER="unix:$_own_runtime/pulse/native"
-  else
-    # Different user — use localhost TCP (setup by agentvibes installer)
-    export PULSE_SERVER="tcp:127.0.0.1:$AGENTVIBES_PULSE_PORT"
-  fi
-fi
-
-# XDG_RUNTIME_DIR still needed for pipewire tools (pw-play fallback)
-if [[ -z "${XDG_RUNTIME_DIR:-}" ]] || [[ ! -e "$XDG_RUNTIME_DIR/pipewire-0" ]]; then
-  for _rd in /run/user/*/; do
-    [[ -e "${_rd}pipewire-0" ]] && { export XDG_RUNTIME_DIR="${_rd%/}"; break; }
-  done
-fi
-export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
-
-# Audio playback — detect available player
-# Prefer paplay over pw-play: pw-play from a different user causes
-# PipeWire flat-volume side effects that drop the master volume.
-AUDIO_PLAYER=""
-AUDIO_PLAYER_ARGS=()
-
-# Check for user-configured sink (set via TUI receiver tab [S] key)
-SINK_CONFIG="${AGENTVIBES_RECEIVER_SINK:-$HOME/.agentvibes/receiver-sink.txt}"
-_default_sink=""
-if [[ -f "$SINK_CONFIG" ]]; then
-  _configured_sink=$(head -1 "$SINK_CONFIG" 2>/dev/null | tr -d '[:space:]')
-  # Validate sink name format (alphanumeric, hyphens, underscores, dots)
-  if [[ -n "$_configured_sink" ]] && [[ "$_configured_sink" =~ ^[a-zA-Z0-9._-]+$ ]]; then
-    _default_sink="$_configured_sink"
-  fi
-fi
-# Fall back to system default if no valid config
-if [[ -z "$_default_sink" ]]; then
-  _default_sink=$(pactl get-default-sink 2>/dev/null || true)
-fi
-
-if command -v paplay &>/dev/null; then
-  AUDIO_PLAYER="paplay"
-  [[ -n "$_default_sink" ]] && AUDIO_PLAYER_ARGS=(--device="$_default_sink")
-elif command -v pw-play &>/dev/null; then
-  AUDIO_PLAYER="pw-play"
-  [[ -n "$_default_sink" ]] && AUDIO_PLAYER_ARGS=(--target="$_default_sink")
-elif command -v aplay &>/dev/null; then
-  AUDIO_PLAYER="aplay"
-fi
-
-# ---------------------------------------------------------------------------
-# Input parsing
-# ---------------------------------------------------------------------------
-
-ENCODED_PAYLOAD="${1:-}"
-
-if [[ -z "$ENCODED_PAYLOAD" ]]; then
-  echo "Error: No payload provided" >&2
-  echo "Usage: $0 <base64-encoded-json-or-text> [voice]" >&2
-  exit 1
-fi
-
-# SECURITY: Validate base64 format (reject shell metacharacters)
-if [[ ! "$ENCODED_PAYLOAD" =~ ^[A-Za-z0-9+/=]+$ ]]; then
-  echo "Error: Payload must be base64-encoded" >&2
-  exit 1
-fi
-
-# Decode base64
-DECODED=$(printf '%s' "$ENCODED_PAYLOAD" | base64 -d 2>/dev/null) || {
-  echo "Error: Failed to decode base64 payload" >&2
-  exit 1
-}
-
-# ---------------------------------------------------------------------------
-# Parse payload — JSON (v2) or plain text (legacy)
-# ---------------------------------------------------------------------------
-
-TEXT=""
-VOICE="en_US-lessac-medium"
-SOX_EFFECTS=""
-BG_FILE=""
-BG_VOLUME="0.10"
-PROJECT=""
-PRETEXT=""
-SPEED=""
-PROVIDER="piper"
-
-# Detect JSON payload (starts with '{')
-if [[ "$DECODED" == "{"* ]]; then
-  # JSON v2 payload — extract fields with lightweight parsing
-  # SECURITY: Use parameter extraction, not eval
-  if command -v jq &>/dev/null; then
-    TEXT=$(printf '%s' "$DECODED" | jq -r '.text // empty' 2>/dev/null) || TEXT=""
-    VOICE=$(printf '%s' "$DECODED" | jq -r '.voice // "en_US-lessac-medium"' 2>/dev/null) || VOICE="en_US-lessac-medium"
-    SOX_EFFECTS=$(printf '%s' "$DECODED" | jq -r '.effects // empty' 2>/dev/null) || SOX_EFFECTS=""
-    BG_FILE=$(printf '%s' "$DECODED" | jq -r '.music // empty' 2>/dev/null) || BG_FILE=""
-    BG_VOLUME=$(printf '%s' "$DECODED" | jq -r '.volume // "0.10"' 2>/dev/null) || BG_VOLUME="0.10"
-    PROJECT=$(printf '%s' "$DECODED" | jq -r '.project // empty' 2>/dev/null) || PROJECT=""
-    PRETEXT=$(printf '%s' "$DECODED" | jq -r '.pretext // empty' 2>/dev/null) || PRETEXT=""
-    SPEED=$(printf '%s' "$DECODED" | jq -r '.speed // empty' 2>/dev/null) || SPEED=""
-    PROVIDER=$(printf '%s' "$DECODED" | jq -r '.provider // "piper"' 2>/dev/null) || PROVIDER="piper"
-  else
-    # Fallback: extract with grep/sed (no jq available)
-    TEXT=$(printf '%s' "$DECODED" | grep -o '"text"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    VOICE=$(printf '%s' "$DECODED" | grep -o '"voice"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    SOX_EFFECTS=$(printf '%s' "$DECODED" | grep -o '"effects"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    BG_FILE=$(printf '%s' "$DECODED" | grep -o '"music"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    BG_VOLUME=$(printf '%s' "$DECODED" | grep -o '"volume"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    PROJECT=$(printf '%s' "$DECODED" | grep -o '"project"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    PRETEXT=$(printf '%s' "$DECODED" | grep -o '"pretext"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    SPEED=$(printf '%s' "$DECODED" | grep -o '"speed"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    PROVIDER=$(printf '%s' "$DECODED" | grep -o '"provider"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//' || true)
-    [[ -z "$VOICE" ]] && VOICE="en_US-lessac-medium"
-    [[ -z "$BG_VOLUME" ]] && BG_VOLUME="0.10"
-    [[ -z "$PROVIDER" ]] && PROVIDER="piper"
-  fi
-else
-  # Legacy format: plain text, voice from positional arg
-  TEXT="$DECODED"
-  VOICE="${2:-en_US-lessac-medium}"
-fi
-
-# Validate required text
-if [[ -z "$TEXT" ]]; then
-  echo "Error: No text in payload" >&2
-  exit 1
-fi
-
-# SECURITY: Validate voice format (allow :: for multi-speaker, . for locale, space for names)
-_voice_re='^[a-zA-Z0-9_.:  -]+$'
-if [[ ! "$VOICE" =~ $_voice_re ]]; then
-  echo "Error: Invalid voice format" >&2
-  exit 1
-fi
-
-# SECURITY: Validate volume is a number
-if [[ -n "$BG_VOLUME" ]] && [[ ! "$BG_VOLUME" =~ ^[0-9]+\.?[0-9]*$ ]]; then
-  BG_VOLUME="0.10"
-fi
-
-# SECURITY: Validate speed is a number (prevents awk injection)
-if [[ -n "$SPEED" ]] && [[ ! "$SPEED" =~ ^[0-9]+\.?[0-9]*$ ]]; then
-  SPEED=""
-fi
-
-# SECURITY: Validate provider format (known providers only)
-case "$PROVIDER" in
-  piper|soprano|macos|windows-sapi) ;;
-  *) PROVIDER="piper" ;;
-esac
-
-# Prepend pretext if provided
-if [[ -n "$PRETEXT" ]]; then
-  TEXT="${PRETEXT}. ${TEXT}"
-fi
-
-# ---------------------------------------------------------------------------
-# Structured logging (for receiver tab to display)
-# ---------------------------------------------------------------------------
-
-LOG_ID=$(printf '%04x' $((RANDOM % 65536)))
-
-log_message() {
-  local status="$1"
-  local detail="${2:-}"
-  local timestamp
-  timestamp=$(date '+%Y-%m-%dT%H:%M:%S')
-  local log_dir
-  log_dir=$(dirname "$LOG_FILE")
-  mkdir -p "$log_dir" 2>/dev/null || true
-  # Extract sender IP from SSH_CLIENT (set by sshd: "IP PORT PORT")
-  local sender_ip="${SSH_CLIENT%% *}"
-  [[ -z "$sender_ip" ]] && sender_ip="local"
-  # Format: TIMESTAMP|STATUS|PROJECT|VOICE|TEXT_PREVIEW|DETAIL|IP|LOG_ID
-  local preview="${TEXT:0:200}"
-  printf '%s|%s|%s|%s|%s|%s|%s|%s\n' \
-    "$timestamp" "$status" "${PROJECT:-unknown}" "$VOICE" "$preview" "$detail" "$sender_ip" "$LOG_ID" \
-    >> "$LOG_FILE" 2>/dev/null || true
-}
-
-log_message "RECEIVED" "provider=${PROVIDER} effects=${SOX_EFFECTS:-none} music=${BG_FILE:-none}"
-
-# ---------------------------------------------------------------------------
-# Temp files with cleanup
-# ---------------------------------------------------------------------------
-
-# Use own runtime dir for temp files (not the desktop user's)
-_TEMP_BASE="/run/user/$(id -u)"
-[[ -d "$_TEMP_BASE" ]] && [[ -w "$_TEMP_BASE" ]] || _TEMP_BASE="/tmp"
-RAW_WAV=$(mktemp "$_TEMP_BASE/agentvibes-recv-XXXXXX.wav")
-EFFECTS_WAV=$(mktemp "$_TEMP_BASE/agentvibes-recv-fx-XXXXXX.wav")
-FINAL_WAV=$(mktemp "$_TEMP_BASE/agentvibes-recv-final-XXXXXX.wav")
-trap 'rm -f "$RAW_WAV" "$EFFECTS_WAV" "$FINAL_WAV"' EXIT
-
-# ---------------------------------------------------------------------------
-# Step 1: Generate TTS audio (multi-provider dispatch)
-# ---------------------------------------------------------------------------
-
-_generate_tts_piper() {
-  local model="$VOICES_DIR/${VOICE}.onnx"
-  if [[ ! -f "$model" ]]; then
-    # Fallback: try any available voice rather than failing
-    local fallback
-    fallback=$(find "$VOICES_DIR" -maxdepth 1 -name '*.onnx' -type f 2>/dev/null | head -1)
-    if [[ -n "$fallback" ]]; then
-      local fallback_name
-      fallback_name=$(basename "$fallback" .onnx)
-      log_message "WARN" "Voice $VOICE not found, falling back to $fallback_name"
-      echo "Warning: Voice $VOICE not found, using $fallback_name" >&2
-      VOICE="$fallback_name"
-      model="$fallback"
-    else
-      log_message "ERROR" "No voice models found in $VOICES_DIR"
-      echo "Error: No voice models found in $VOICES_DIR" >&2
-      return 1
-    fi
-  fi
-
-  local args=(--model "$model" --output_file "$RAW_WAV")
-  if [[ -n "$SPEED" ]] && [[ "$SPEED" =~ ^[0-9]+\.?[0-9]*$ ]]; then
-    args+=(--length_scale "$SPEED")
-  fi
-
-  echo "$TEXT" | piper "${args[@]}" 2>/dev/null || {
-    log_message "ERROR" "Piper TTS failed"
-    echo "Error: Piper TTS generation failed" >&2
-    return 1
-  }
-}
-
-_generate_tts_soprano() {
-  local soprano_port="${SOPRANO_PORT:-7860}"
-
-  # Try API mode first (OpenAI-compatible endpoint)
-  if curl -sf -X POST "http://127.0.0.1:${soprano_port}/v1/audio/speech" \
-    -H "Content-Type: application/json" \
-    -d "{\"input\":$(printf '%s' "$TEXT" | jq -Rs .)}" \
-    --output "$RAW_WAV" 2>/dev/null; then
-    return 0
-  fi
-
-  # Try CLI mode — options before --, text as final positional arg
-  if command -v soprano &>/dev/null; then
-    soprano -o "$RAW_WAV" -- "$TEXT" 2>/dev/null && return 0
-  fi
-
-  log_message "ERROR" "Soprano TTS failed — is soprano running on port ${soprano_port}?"
-  echo "Error: Soprano TTS unavailable (tried API and CLI)" >&2
-  return 1
-}
-
-_generate_tts_macos() {
-  if ! command -v say &>/dev/null; then
-    log_message "ERROR" "macOS say command not found"
-    echo "Error: macOS say command not available" >&2
-    return 1
-  fi
-
-  local say_args=(-v "$VOICE")
-  # Convert speed multiplier to WPM (say uses WPM, default ~200)
-  if [[ -n "$SPEED" ]] && [[ "$SPEED" =~ ^[0-9]+\.?[0-9]*$ ]]; then
-    local wpm
-    wpm=$(awk "BEGIN {printf \"%d\", 200 * $SPEED}")
-    say_args+=(-r "$wpm")
-  fi
-
-  # say outputs AIFF — convert to WAV for consistent pipeline
-  local aiff_tmp="${RAW_WAV%.wav}.aiff"
-  echo "$TEXT" | say "${say_args[@]}" -o "$aiff_tmp" 2>/dev/null || {
-    log_message "ERROR" "macOS say failed"
-    rm -f "$aiff_tmp"
-    return 1
-  }
-
-  if command -v ffmpeg &>/dev/null; then
-    ffmpeg -y -i "$aiff_tmp" "$RAW_WAV" </dev/null 2>/dev/null
-    rm -f "$aiff_tmp"
-  else
-    # No ffmpeg — rename and hope player handles AIFF
-    mv "$aiff_tmp" "$RAW_WAV"
-  fi
-}
-
-_generate_tts_windows_sapi() {
-  # Windows SAPI via PowerShell (works in WSL2 via powershell.exe)
-  local ps_cmd=""
-  if command -v powershell.exe &>/dev/null; then
-    ps_cmd="powershell.exe"
-  elif command -v pwsh &>/dev/null; then
-    ps_cmd="pwsh"
-  else
-    log_message "ERROR" "PowerShell not found for Windows SAPI"
-    echo "Error: PowerShell required for Windows SAPI" >&2
-    return 1
-  fi
-
-  # SECURITY: Escape text for PowerShell single-quoted string
-  local escaped_text
-  escaped_text=$(printf '%s' "$TEXT" | sed "s/'/''/g")
-
-  local rate=0
-  if [[ -n "$SPEED" ]] && [[ "$SPEED" =~ ^[0-9]+\.?[0-9]*$ ]]; then
-    # SAPI rate: -10 to 10, 0 is normal. Speed 1.0=0, 2.0=5, 0.5=-5
-    rate=$(awk "BEGIN {r = ($SPEED - 1.0) * 10; if (r > 10) r = 10; if (r < -10) r = -10; printf \"%d\", r}")
-  fi
-
-  $ps_cmd -NoProfile -Command "
-    Add-Type -AssemblyName System.Speech
-    \$synth = New-Object System.Speech.Synthesis.SpeechSynthesizer
-    \$synth.Rate = $rate
-    \$synth.SetOutputToWaveFile('$(wslpath -w "$RAW_WAV" 2>/dev/null || echo "$RAW_WAV")')
-    \$synth.Speak('$escaped_text')
-    \$synth.Dispose()
-  " 2>/dev/null || {
-    log_message "ERROR" "Windows SAPI TTS failed"
-    echo "Error: Windows SAPI generation failed" >&2
-    return 1
-  }
-}
-
-# Dispatch to the appropriate TTS provider
-case "$PROVIDER" in
-  piper)
-    _generate_tts_piper || exit 1
-    ;;
-  soprano)
-    _generate_tts_soprano || exit 1
-    ;;
-  macos)
-    _generate_tts_macos || exit 1
-    ;;
-  windows-sapi)
-    _generate_tts_windows_sapi || exit 1
-    ;;
-  *)
-    log_message "ERROR" "Unknown provider: $PROVIDER"
-    echo "Error: Unknown TTS provider: $PROVIDER" >&2
-    exit 1
-    ;;
-esac
-
-PLAY_FILE="$RAW_WAV"
-
-# ---------------------------------------------------------------------------
-# Step 2: Apply sox effects (reverb, EQ, etc.)
-# ---------------------------------------------------------------------------
-
-if [[ -n "$SOX_EFFECTS" ]] && command -v sox &>/dev/null; then
-  # SECURITY: Validate effects contain only safe characters (alphanumeric, spaces, dots, hyphens, underscores)
-  if [[ "$SOX_EFFECTS" =~ ^[a-zA-Z0-9\ ._-]+$ ]]; then
-    sox "$RAW_WAV" "$EFFECTS_WAV" $SOX_EFFECTS 2>/dev/null && PLAY_FILE="$EFFECTS_WAV"
-  else
-    log_message "WARN" "Rejected unsafe sox effects: ${SOX_EFFECTS:0:50}"
-  fi
-fi
-
-# ---------------------------------------------------------------------------
-# Step 3: Mix background music (if configured)
-# ---------------------------------------------------------------------------
-
-if [[ -n "$BG_FILE" ]] && command -v ffmpeg &>/dev/null; then
-  BG_PATH="$TRACKS_DIR/$BG_FILE"
-  if [[ -f "$BG_PATH" ]]; then
-    DURATION=$(ffprobe -v error -show_entries format=duration \
-      -of default=noprint_wrappers=1:nokey=1 "$PLAY_FILE" 2>/dev/null || echo "")
-    if [[ -n "$DURATION" ]]; then
-      TOTAL_DUR=$(awk "BEGIN {printf \"%.2f\", $DURATION + 2}")
-      FADE_OUT=$(awk "BEGIN {printf \"%.2f\", $DURATION}")
-      timeout 20 ffmpeg -y -i "$PLAY_FILE" -stream_loop -1 -i "$BG_PATH" \
-        -filter_complex "[1:a]volume=${BG_VOLUME},afade=t=in:st=0:d=0.3,afade=t=out:st=${FADE_OUT}:d=2[bg];[0:a]adelay=1000|1000,volume=1.5[v];[v][bg]amix=inputs=2:duration=longest:normalize=0[out]" \
-        -map "[out]" -t "$TOTAL_DUR" "$FINAL_WAV" </dev/null 2>/dev/null && PLAY_FILE="$FINAL_WAV"
-    fi
-  fi
-fi
-
-# ---------------------------------------------------------------------------
-# Step 4: Play audio in foreground (required for SSH — no backgrounding)
-# ---------------------------------------------------------------------------
-
-if [[ -z "$AUDIO_PLAYER" ]]; then
-  log_message "ERROR" "No audio player found (pw-play, paplay, aplay)"
-  echo "Error: No audio player available" >&2
-  exit 1
-fi
-
-# Save master volume before playback — flat-volumes in PipeWire/PulseAudio
-# can change master volume when a new stream connects from another user.
-_saved_vol=""
-if command -v pactl &>/dev/null; then
-  _saved_vol=$(pactl get-sink-volume @DEFAULT_SINK@ 2>/dev/null | grep -o '[0-9]*%' | head -1)
-fi
-
-log_message "PLAYING" "player=$AUDIO_PLAYER sink=${_default_sink:-unknown} vol=${_saved_vol:-?} pulse=${PULSE_SERVER:-unset}"
-
-_play_err=$($AUDIO_PLAYER "${AUDIO_PLAYER_ARGS[@]}" "$PLAY_FILE" 2>&1) || {
-  log_message "ERROR" "Playback failed with $AUDIO_PLAYER: $_play_err"
-  echo "Error: Audio playback failed" >&2
-  echo "Detail: $_play_err" >&2
-  exit 1
-}
-
-# Restore master volume to what it was before playback
-if [[ -n "$_saved_vol" ]] && command -v pactl &>/dev/null; then
-  pactl set-sink-volume @DEFAULT_SINK@ "$_saved_vol" 2>/dev/null || true
-fi
-
-log_message "DONE" ""
-exit 0
+#!/usr/bin/env bash
+#
+# File: agentvibes-receiver.sh
+# Location: User installs to ~/.termux/agentvibes-play.sh or ~/.agentvibes/play-remote.sh
+#
+# AgentVibes SSH-TTS Receiver
+# Receives text from remote server via SSH, plays with local AgentVibes
+#
+# Installation:
+#   curl -sSL https://raw.githubusercontent.com/paulpreibisch/AgentVibes/main/scripts/install-ssh-receiver.sh | bash
+#   OR
+#   agentvibes install --ssh-receiver
+#
+# Copyright (c) 2025 Paul Preibisch
+# Licensed under Apache-2.0
+#
+
+set -euo pipefail
+
+# Handle -- argument separator (skip it if present)
+if [[ "${1:-}" == "--" ]]; then
+    shift
+fi
+
+TEXT="${1:-}"
+VOICE="${2:-en_US-ryan-high}"
+MUSIC="${3:-}"
+REVERB="${4:-}"
+
+if [[ -z "$TEXT" ]]; then
+    echo "❌ No text provided" >&2
+    echo "Usage: $0 [--] <text> [voice] [music] [reverb]" >&2
+    exit 1
+fi
+
+# SECURITY: If text is base64-encoded (from secure sender), decode it
+# Base64 text won't contain spaces or special chars, so we detect it heuristically
+if [[ "$TEXT" =~ ^[A-Za-z0-9+/]+=*$ ]] && [[ ${#TEXT} -gt 20 ]]; then
+    DECODED=$(printf '%s' "$TEXT" | base64 -d 2>/dev/null) || DECODED=""
+    if [[ -n "$DECODED" ]]; then
+        TEXT="$DECODED"
+    fi
+fi
+
+# SECURITY: Validate voice format (alphanumeric, hyphens, underscores only)
+if [[ ! "$VOICE" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    echo "❌ Invalid voice format: $VOICE" >&2
+    exit 1
+fi
+
+# Suppress GitHub star reminders (receiver mode)
+export AGENTVIBES_NO_REMINDERS=1
+
+# Find AgentVibes installation
+# SECURITY: Uses controlled paths only, validates existence
+find_agentvibes() {
+    # Try command lookup first
+    if command -v agentvibes >/dev/null 2>&1; then
+        local bin_path
+        bin_path=$(which agentvibes)
+        # Resolve if it's a symlink
+        if [[ -L "$bin_path" ]]; then
+            bin_path=$(readlink -f "$bin_path" 2>/dev/null || realpath "$bin_path" 2>/dev/null || echo "$bin_path")
+        fi
+        # SECURITY: Properly quote nested command substitutions
+        local lib_path
+        lib_path="$(dirname "$(dirname "$bin_path")")/lib/node_modules/agentvibes"
+        if [[ -d "$lib_path" ]]; then
+            echo "$lib_path"
+            return 0
+        fi
+    fi
+
+    # Check common npm global locations (controlled paths only)
+    local search_paths=(
+        "$HOME/.npm-global/lib/node_modules/agentvibes"
+        "/usr/local/lib/node_modules/agentvibes"
+        "/data/data/com.termux/files/usr/lib/node_modules/agentvibes"  # Android Termux
+    )
+
+    # Handle nvm paths separately to avoid glob issues
+    if [[ -d "$HOME/.nvm/versions/node" ]]; then
+        local nvm_path
+        # SECURITY: Use find instead of unsafe glob expansion
+        nvm_path=$(find "$HOME/.nvm/versions/node" -maxdepth 3 -type d -name "agentvibes" -path "*/lib/node_modules/*" 2>/dev/null | head -1)
+        if [[ -n "$nvm_path" ]] && [[ -d "$nvm_path" ]]; then
+            echo "$nvm_path"
+            return 0
+        fi
+    fi
+
+    for path in "${search_paths[@]}"; do
+        if [[ -d "$path" ]]; then
+            echo "$path"
+            return 0
+        fi
+    done
+
+    return 1
+}
+
+AGENTVIBES_ROOT=$(find_agentvibes)
+
+if [[ -z "$AGENTVIBES_ROOT" ]]; then
+    echo "❌ AgentVibes not found" >&2
+    echo "💡 Install: npm install -g agentvibes" >&2
+    exit 1
+fi
+
+PLAY_TTS="$AGENTVIBES_ROOT/.claude/hooks/play-tts.sh"
+
+if [[ ! -f "$PLAY_TTS" ]]; then
+    echo "❌ play-tts.sh not found at $PLAY_TTS" >&2
+    exit 1
+fi
+
+# Configure audio effects and background music if provided
+# CRITICAL: Write to AGENTVIBES package config, not HOME config
+# The audio-processor reads from package config, not ~/.claude/config
+if [[ -n "$MUSIC" ]] || [[ -n "$REVERB" ]]; then
+    CONFIG_DIR="$AGENTVIBES_ROOT/.claude/config"
+    mkdir -p "$CONFIG_DIR"
+    
+    # Enable background music
+    echo "true" > "$CONFIG_DIR/background-music-enabled.txt"
+    
+    # Clear position cache for fresh start
+    rm -f "$CONFIG_DIR/background-music-position.txt"
+    
+    # Set background music track if provided
+    if [[ -n "$MUSIC" ]]; then
+        echo "$MUSIC" > "$CONFIG_DIR/background-music.txt"
+    fi
+    
+    # Set audio effects config (default agent name is always "default")
+    if [[ -n "$MUSIC" ]] && [[ -n "$REVERB" ]]; then
+        echo "default|${REVERB}|${MUSIC}|0.10" > "$CONFIG_DIR/audio-effects.cfg"
+    elif [[ -n "$REVERB" ]]; then
+        echo "default|${REVERB}||0.0" > "$CONFIG_DIR/audio-effects.cfg"
+    elif [[ -n "$MUSIC" ]]; then
+        echo "default||${MUSIC}|0.10" > "$CONFIG_DIR/audio-effects.cfg"
+    fi
+fi
+
+# Log for debugging (optional, comment out in production)
+if [[ "${AGENTVIBES_DEBUG:-0}" == "1" ]]; then
+    echo "[DEBUG] AgentVibes root: $AGENTVIBES_ROOT" >&2
+    echo "[DEBUG] Voice: $VOICE" >&2
+    echo "[DEBUG] Music: ${MUSIC:-none}" >&2
+    echo "[DEBUG] Reverb: ${REVERB:-none}" >&2
+    echo "[DEBUG] Text length: ${#TEXT}" >&2
+fi
+
+# Generate and play with full AgentVibes features
+echo "🎵 Playing via AgentVibes: ${TEXT:0:50}..." >&2
+bash "$PLAY_TTS" "$TEXT" "$VOICE"
+
+exit 0